From 6356481b969b097eec09aae64ee0271fe134fbaa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 05:55:27 -0700 Subject: [PATCH 1/8] chore(quest): claim quest/m2/p2p/udp-demux.md Quest-Claim: 1555076f208bbd7d From c453d7a4fd55791935c8151ead7f77a5574d697d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 06:04:50 -0700 Subject: [PATCH 2/8] feat(sock): classify datagrams for a shared QUIC and WebRTC port Co-Authored-By: Claude Opus 5.5 --- rs/moq-sock/README.md | 4 + rs/moq-sock/src/demux.rs | 433 +++++++++++++++++++++++++++++++++++++++ rs/moq-sock/src/lib.rs | 4 +- 3 files changed, 440 insertions(+), 1 deletion(-) create mode 100644 rs/moq-sock/src/demux.rs diff --git a/rs/moq-sock/README.md b/rs/moq-sock/README.md index 7cab2a2101a..e3ca72f87c8 100644 --- a/rs/moq-sock/README.md +++ b/rs/moq-sock/README.md @@ -16,6 +16,10 @@ runtimes (`moq-tokio` and `moq-uring`). carries (`moq_quic::RandomConnectionIdGenerator::set_shard`). Anything else on the port, including other protocols, keeps the kernel's 4-tuple hash. - **`cpu`**: pinning worker threads to cores. +- **`demux`**: classifying each datagram on a shared port by its first byte + (RFC 7983), so QUIC and the WebRTC media path (ICE checks, DTLS, RTP) share + one socket, plus the pin table and per-source queue the listeners divert + through. Every QUIC endpoint behind it turns QUIC-bit greasing off. - **`udp`**: sending and receiving with GSO, GRO, and ECN, a hard fork of [quinn-udp](https://github.com/quinn-rs/quinn). All credit for it goes to the quinn developers; it stays under quinn's MIT or Apache-2.0 license. See diff --git a/rs/moq-sock/src/demux.rs b/rs/moq-sock/src/demux.rs new file mode 100644 index 00000000000..8b05c695c64 --- /dev/null +++ b/rs/moq-sock/src/demux.rs @@ -0,0 +1,433 @@ +//! Splitting one UDP socket between QUIC and the WebRTC media path. +//! +//! [`classify`] reads a datagram's first byte by RFC 7983's partition, which QUIC +//! fills as long as its fixed bit is set: every endpoint served through this must +//! turn QUIC-bit greasing (RFC 9287) off. [`Flows`] pins a remote address to a +//! stack regardless of what it sends, and [`Queue`] buffers one stack's datagrams +//! with a per-source share. None of it touches a runtime, so the tokio and +//! io_uring listeners run the same rules. + +use std::{ + collections::{HashMap, VecDeque}, + net::SocketAddr, + sync::{ + Arc, Mutex, + atomic::{AtomicU64, AtomicUsize, Ordering}, + }, +}; + +/// What a datagram carries, judged by its first byte and, for STUN, its attributes. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Class { + /// A QUIC packet: the fixed bit is set, in a long (192 to 255) or short (64 to 127) header. + Quic, + /// A STUN Binding request carrying USERNAME: an ICE connectivity check. + Check, + /// Any other STUN message, such as a public Binding query or a response. + Stun, + /// A DTLS record (20 to 63). + Dtls, + /// An RTP or RTCP packet (128 to 191). + Rtp, + /// Nothing this socket serves, including an empty datagram. + Unknown, +} + +const STUN_HEADER: usize = 20; +const STUN_COOKIE: [u8; 4] = [0x21, 0x12, 0xA4, 0x42]; +const STUN_BINDING_REQUEST: [u8; 2] = [0x00, 0x01]; +const STUN_USERNAME: u16 = 0x0006; + +/// Classify a datagram by RFC 7983's first-byte ranges. +pub fn classify(datagram: &[u8]) -> Class { + match datagram.first() { + Some(0..=3) if is_check(datagram) => Class::Check, + Some(0..=3) => Class::Stun, + Some(20..=63) => Class::Dtls, + Some(64..=127 | 192..=255) => Class::Quic, + Some(128..=191) => Class::Rtp, + _ => Class::Unknown, + } +} + +/// Whether `datagram` is a well-formed STUN Binding request with a USERNAME attribute. +fn is_check(datagram: &[u8]) -> bool { + let Some((header, mut attributes)) = datagram.split_at_checked(STUN_HEADER) else { + return false; + }; + if header[0..2] != STUN_BINDING_REQUEST || header[4..8] != STUN_COOKIE { + return false; + } + if usize::from(u16::from_be_bytes([header[2], header[3]])) != attributes.len() { + return false; + } + + while let Some((attribute, rest)) = attributes.split_at_checked(4) { + let kind = u16::from_be_bytes([attribute[0], attribute[1]]); + let len = usize::from(u16::from_be_bytes([attribute[2], attribute[3]])); + if kind == STUN_USERNAME { + return len <= rest.len(); + } + // Values are padded to a multiple of four. + let Some(rest) = rest.get(len.next_multiple_of(4)..) else { + return false; + }; + attributes = rest; + } + false +} + +/// Where a datagram goes. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Route { + /// The QUIC endpoint. + Quic, + /// The WebRTC media path: ICE checks, DTLS, and RTP. + WebRtc, + /// Nowhere; counted under this reason. + Discard(Discard), +} + +/// Why a datagram was dropped instead of delivered. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Discard { + /// STUN that is not an ICE check, such as a public Binding query; the public + /// responder binds its own port. + Stun, + /// Nothing this socket serves. + Unknown, + /// WebRTC traffic while nothing consumes it. + Unclaimed, + /// WebRTC traffic that found its queue full, or its source over its share. + Overflow, +} + +impl Discard { + /// Every reason, in [`Counters`] order. + pub const ALL: [Self; 4] = [Self::Stun, Self::Unknown, Self::Unclaimed, Self::Overflow]; + + /// A stable lowercase label, for metrics. + pub fn as_str(self) -> &'static str { + match self { + Self::Stun => "stun", + Self::Unknown => "unknown", + Self::Unclaimed => "unclaimed", + Self::Overflow => "overflow", + } + } +} + +/// Datagrams dropped per [`Discard`] reason. Clones share the counts. +#[derive(Clone, Debug, Default)] +pub struct Counters(Arc<[AtomicU64; Discard::ALL.len()]>); + +impl Counters { + /// Count one datagram dropped for `reason`. + pub fn discard(&self, reason: Discard) { + self.0[reason as usize].fetch_add(1, Ordering::Relaxed); + } + + /// How many datagrams were dropped for `reason`. + pub fn get(&self, reason: Discard) -> u64 { + self.0[reason as usize].load(Ordering::Relaxed) + } +} + +/// Remote addresses pinned to WebRTC, whatever they send. Clones share the table. +/// +/// Keyed by the remote address alone: the local port is the socket's, and a +/// remote address reaching two of a wildcard socket's local addresses is +/// treated as one flow. IPv4-mapped addresses are folded to IPv4, as +/// `moq_ice::canonical` does, so a dual-stack socket's pins match. +#[derive(Clone, Debug, Default)] +pub struct Flows(Arc); + +#[derive(Debug, Default)] +struct FlowsState { + /// Skips the lock on every datagram while nothing is pinned. + pinned: AtomicUsize, + /// How many [`Pin`]s hold each address. + pins: Mutex>, +} + +impl Flows { + /// Route `datagram` from `remote`: a pin wins, otherwise its [`Class`] decides. + pub fn route(&self, remote: SocketAddr, datagram: &[u8]) -> Route { + if self.is_pinned(remote) { + return Route::WebRtc; + } + match classify(datagram) { + Class::Quic => Route::Quic, + Class::Check | Class::Dtls | Class::Rtp => Route::WebRtc, + Class::Stun => Route::Discard(Discard::Stun), + Class::Unknown => Route::Discard(Discard::Unknown), + } + } + + /// Pin `remote` to WebRTC until the returned [`Pin`] drops. + pub fn pin(&self, remote: SocketAddr) -> Pin { + let remote = canonical(remote); + let mut pins = self.0.pins.lock().unwrap(); + *pins.entry(remote).or_default() += 1; + self.0.pinned.store(pins.len(), Ordering::Release); + Pin { + flows: self.clone(), + remote, + } + } + + fn is_pinned(&self, remote: SocketAddr) -> bool { + if self.0.pinned.load(Ordering::Acquire) == 0 { + return false; + } + self.0.pins.lock().unwrap().contains_key(&canonical(remote)) + } +} + +fn canonical(addr: SocketAddr) -> SocketAddr { + SocketAddr::new(addr.ip().to_canonical(), addr.port()) +} + +/// Keeps a remote address pinned to WebRTC in its [`Flows`]; dropping it releases the pin. +#[derive(Debug)] +pub struct Pin { + flows: Flows, + remote: SocketAddr, +} + +impl Drop for Pin { + fn drop(&mut self) { + let mut pins = self.flows.0.pins.lock().unwrap(); + if let Some(count) = pins.get_mut(&self.remote) { + *count -= 1; + if *count == 0 { + pins.remove(&self.remote); + } + } + self.flows.0.pinned.store(pins.len(), Ordering::Release); + } +} + +/// A FIFO of one stack's datagrams, bounded by cost with a per-source share. +/// +/// A source may hold at most [`Queue::SHARE`] of the capacity, so one flooding +/// sender is refused while the rest still get in; filling the queue takes that +/// many sources at once. +#[derive(Debug)] +pub struct Queue { + items: VecDeque<(SocketAddr, usize, T)>, + /// The cost each source holds in `items`; a source holding nothing has no entry. + sources: HashMap, + cost: usize, + capacity: usize, +} + +impl Queue { + /// The fraction of the capacity, as a divisor, one source may hold. + pub const SHARE: usize = 8; + + /// An empty queue holding up to `capacity` in total cost. + pub fn new(capacity: usize) -> Self { + Self { + items: VecDeque::new(), + sources: HashMap::new(), + cost: 0, + capacity, + } + } + + /// Append `item` from `source`, charged `cost`, or hand it back when the queue + /// is full or `source` already holds its share. + pub fn push(&mut self, source: SocketAddr, cost: usize, item: T) -> Result<(), T> { + let held = self.sources.get(&source).copied().unwrap_or(0); + if self.cost + cost > self.capacity || held + cost > self.capacity / Self::SHARE { + return Err(item); + } + self.cost += cost; + *self.sources.entry(source).or_default() += cost; + self.items.push_back((source, cost, item)); + Ok(()) + } + + /// Remove the oldest item. + pub fn pop(&mut self) -> Option { + let (source, cost, item) = self.items.pop_front()?; + self.cost -= cost; + if let Some(held) = self.sources.get_mut(&source) { + *held -= cost; + if *held == 0 { + self.sources.remove(&source); + } + } + Some(item) + } + + /// Drop every item. + pub fn clear(&mut self) { + self.items.clear(); + self.sources.clear(); + self.cost = 0; + } + + /// Whether nothing is queued. + pub fn is_empty(&self) -> bool { + self.items.is_empty() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A Binding request: header, then the given attributes. + fn binding(attributes: &[(u16, &[u8])]) -> Vec { + let mut body = Vec::new(); + for (kind, value) in attributes { + body.extend_from_slice(&kind.to_be_bytes()); + body.extend_from_slice(&(value.len() as u16).to_be_bytes()); + body.extend_from_slice(value); + body.resize(body.len().next_multiple_of(4), 0); + } + let mut out = Vec::new(); + out.extend_from_slice(&STUN_BINDING_REQUEST); + out.extend_from_slice(&(body.len() as u16).to_be_bytes()); + out.extend_from_slice(&STUN_COOKIE); + out.extend_from_slice(&[7; 12]); + out.extend_from_slice(&body); + out + } + + const PRIORITY: u16 = 0x0024; + + fn addr(port: u16) -> SocketAddr { + SocketAddr::from(([192, 0, 2, 1], port)) + } + + #[test] + fn first_byte_classes() { + let check = binding(&[(PRIORITY, &[0, 0, 0, 1]), (STUN_USERNAME, b"abc:def")]); + let cases: &[(&[u8], Class)] = &[ + (&check, Class::Check), + (&binding(&[(PRIORITY, &[0, 0, 0, 1])]), Class::Stun), + (&[0x01, 0x01, 0, 0], Class::Stun), + (&[3], Class::Stun), + (&[4], Class::Unknown), + (&[19], Class::Unknown), + (&[20], Class::Dtls), + (&[0x16, 0xfe, 0xfd], Class::Dtls), + (&[63], Class::Dtls), + (&[64], Class::Quic), + (&[127], Class::Quic), + (&[128], Class::Rtp), + (&[0x80, 0x00], Class::Rtp), + (&[191], Class::Rtp), + (&[192], Class::Quic), + (&[255], Class::Quic), + (&[], Class::Unknown), + ]; + for (datagram, class) in cases { + assert_eq!(classify(datagram), *class, "{datagram:02x?}"); + } + } + + #[test] + fn malformed_checks_are_plain_stun() { + let check = binding(&[(STUN_USERNAME, b"abc:def")]); + + let mut cookie = check.clone(); + cookie[4] ^= 1; + assert_eq!(classify(&cookie), Class::Stun); + + // A Binding success response carrying USERNAME is still not a check. + let mut response = check.clone(); + response[0..2].copy_from_slice(&[0x01, 0x01]); + assert_eq!(classify(&response), Class::Stun); + + // The header's length must cover the attributes exactly. + let mut long = check.clone(); + long.push(0); + assert_eq!(classify(&long), Class::Stun); + assert_eq!(classify(&check[..check.len() - 4]), Class::Stun); + + // An attribute running past the message hides any USERNAME after it. + let mut truncated = binding(&[(PRIORITY, &[0, 0, 0, 1]), (STUN_USERNAME, b"abc:def")]); + truncated[STUN_HEADER + 3] = 200; + assert_eq!(classify(&truncated), Class::Stun); + } + + #[test] + fn routes_follow_the_class() { + let flows = Flows::default(); + let check = binding(&[(STUN_USERNAME, b"abc:def")]); + assert_eq!(flows.route(addr(1), &check), Route::WebRtc); + assert_eq!(flows.route(addr(1), &[0x16]), Route::WebRtc); + assert_eq!(flows.route(addr(1), &[0x80]), Route::WebRtc); + assert_eq!(flows.route(addr(1), &[0x40]), Route::Quic); + assert_eq!(flows.route(addr(1), &[0xc0]), Route::Quic); + assert_eq!( + flows.route(addr(1), &binding(&[])), + Route::Discard(Discard::Stun) + ); + assert_eq!(flows.route(addr(1), &[5]), Route::Discard(Discard::Unknown)); + } + + #[test] + fn a_pin_wins_until_every_holder_releases_it() { + let flows = Flows::default(); + let mapped = SocketAddr::from((std::net::Ipv4Addr::new(192, 0, 2, 1).to_ipv6_mapped(), 1)); + + let first = flows.pin(addr(1)); + let second = flows.pin(mapped); + assert_eq!(flows.route(addr(1), &[0x40]), Route::WebRtc); + assert_eq!(flows.route(mapped, &[5]), Route::WebRtc); + assert_eq!(flows.route(addr(2), &[0x40]), Route::Quic); + + drop(first); + assert_eq!(flows.route(addr(1), &[0x40]), Route::WebRtc); + drop(second); + assert_eq!(flows.route(addr(1), &[0x40]), Route::Quic); + } + + #[test] + fn counters_count_each_reason() { + let counters = Counters::default(); + counters.clone().discard(Discard::Overflow); + counters.discard(Discard::Overflow); + counters.discard(Discard::Stun); + assert_eq!(counters.get(Discard::Overflow), 2); + assert_eq!(counters.get(Discard::Stun), 1); + assert_eq!(counters.get(Discard::Unknown), 0); + } + + #[test] + fn a_flooding_source_is_held_to_its_share() { + let mut queue = Queue::new(16); + queue.push(addr(1), 1, 0).unwrap(); + queue.push(addr(1), 1, 1).unwrap(); + assert_eq!(queue.push(addr(1), 1, 2), Err(2)); + + // Its share is spent, not the queue: everyone else still gets in. + for port in 2..9 { + queue.push(addr(port), 2, 10 + port).unwrap(); + } + // Now the queue is full, whatever the source. + assert_eq!(queue.push(addr(9), 1, 19), Err(19)); + + // Popping refunds the oldest item's source. + assert_eq!(queue.pop(), Some(0)); + queue.push(addr(1), 1, 2).unwrap(); + let drained: Vec<_> = std::iter::from_fn(|| queue.pop()).collect(); + assert_eq!(drained, [1, 12, 13, 14, 15, 16, 17, 18, 2]); + assert!(queue.is_empty()); + assert!(queue.sources.is_empty()); + } + + #[test] + fn clear_forgets_every_source() { + let mut queue = Queue::new(16); + queue.push(addr(1), 2, ()).unwrap(); + queue.clear(); + assert!(queue.is_empty()); + queue.push(addr(1), 2, ()).unwrap(); + } +} diff --git a/rs/moq-sock/src/lib.rs b/rs/moq-sock/src/lib.rs index e5ff6593a56..6074e1c7fda 100644 --- a/rs/moq-sock/src/lib.rs +++ b/rs/moq-sock/src/lib.rs @@ -5,11 +5,13 @@ //! [`shard::bind`] forms and steers an `SO_REUSEPORT` group by QUIC connection //! id, so a worker-per-core listener keeps each connection on the socket that //! owns it; [`cpu`] pins those workers; [`udp`] (forked from quinn-udp) sends -//! and receives with GSO, GRO, and ECN. Both `moq-tokio` and `moq-uring` build +//! and receives with GSO, GRO, and ECN; [`demux`] splits one socket's datagrams +//! between QUIC and the WebRTC media path. Both `moq-tokio` and `moq-uring` build //! their worker groups on this crate, so the group-formation invariants live //! here once, in the group itself rather than in each caller. pub mod bind; pub mod cpu; +pub mod demux; pub mod shard; pub mod udp; From fb4ebe446d9bba8c381ec8dabf430c0e7e291d06 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 06:12:24 -0700 Subject: [PATCH 3/8] feat(tokio,relay): divert the WebRTC media path from the QUIC port Co-Authored-By: Claude Opus 5.5 --- rs/moq-relay/src/internal.rs | 85 +++++ rs/moq-relay/src/relay.rs | 40 +++ rs/moq-relay/tests/integration/embed.rs | 68 ++++ rs/moq-tokio/src/quic.rs | 2 + rs/moq-tokio/src/quic/backend.rs | 180 ++++++++-- rs/moq-tokio/src/quic/demux.rs | 412 +++++++++++++++++++++++ rs/moq-tokio/src/quic/driver/endpoint.rs | 4 +- rs/moq-tokio/src/server.rs | 9 + 8 files changed, 770 insertions(+), 30 deletions(-) create mode 100644 rs/moq-tokio/src/quic/demux.rs diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index 7c88c8420a8..db08fb722c4 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -93,6 +93,8 @@ pub struct Internal { uring: Vec, #[cfg(any(feature = "stun", test))] stun: Option, + #[cfg(feature = "_quic")] + demux: Option, shutdown: Option, listener: Option, addr: Option, @@ -108,6 +110,8 @@ struct InternalState { uring: Vec, #[cfg(any(feature = "stun", test))] stun: Option, + #[cfg(feature = "_quic")] + demux: Option, shutdown: Option, } @@ -137,6 +141,8 @@ impl Internal { uring: Vec::new(), #[cfg(any(feature = "stun", test))] stun: None, + #[cfg(feature = "_quic")] + demux: None, shutdown: None, listener: None, addr: None, @@ -149,6 +155,12 @@ impl Internal { self } + #[cfg(feature = "_quic")] + pub(crate) fn with_demux(mut self, counters: Option) -> Self { + self.demux = counters; + self + } + pub(crate) fn with_timeout(mut self, timeout: Option) -> Self { self.timeout = timeout; self @@ -265,6 +277,8 @@ impl Internal { uring: self.uring.clone(), #[cfg(any(feature = "stun", test))] stun: self.stun.clone(), + #[cfg(feature = "_quic")] + demux: self.demux.clone(), shutdown: self.shutdown.clone(), }) } @@ -343,6 +357,10 @@ async fn serve_metrics(State(state): State) -> Response { if let Some(stun) = &state.stun { stun.render(&mut body); } + #[cfg(feature = "_quic")] + if let Some(demux) = &state.demux { + render_demux(&mut body, demux); + } if let Some(shutdown) = &state.shutdown { render_drain(&mut body, shutdown.tally()); } @@ -647,6 +665,28 @@ fn render_drain(out: &mut String, tally: crate::shutdown::Tally) { let _ = writeln!(out, "moq_relay_draining_sessions {}", tally.draining); } +/// Datagrams the QUIC port dropped instead of handing to QUIC or the WebRTC feed, +/// one row per reason from zero. `unclaimed` is WebRTC traffic while no embedder +/// takes the feed, which is every WebRTC datagram on a bare relay. +#[cfg(feature = "_quic")] +fn render_demux(out: &mut String, counters: &moq_tokio::quic::demux::Counters) { + use std::fmt::Write as _; + + let _ = writeln!( + out, + "# HELP moq_relay_demux_dropped_total Datagrams the QUIC port dropped, by reason." + ); + let _ = writeln!(out, "# TYPE moq_relay_demux_dropped_total counter"); + for reason in moq_tokio::quic::demux::Discard::ALL { + let _ = writeln!( + out, + "moq_relay_demux_dropped_total{{reason=\"{}\"}} {}", + Label(reason.as_str()), + counters.get(reason) + ); + } +} + /// Sessions admission turned away, one row per reason, every reason present from /// zero so a rate over it is defined from the first scrape. A refused session /// never reaches the traffic counters above. @@ -905,6 +945,8 @@ mod tests { listeners: Vec::new(), uring: Vec::new(), stun, + #[cfg(feature = "_quic")] + demux: None, shutdown: None, }; let response = serve_metrics(State(state)).await; @@ -915,6 +957,45 @@ mod tests { } } + /// Every drop reason renders from zero, and only for a relay whose QUIC port + /// runs the demux. + #[cfg(feature = "_quic")] + #[tokio::test] + async fn demux_metrics_list_every_reason_from_zero() { + use moq_tokio::quic::demux::{Counters, Discard}; + + for demux in [None, Some(Counters::default())] { + let configured = demux.clone(); + if let Some(counters) = &demux { + counters.discard(Discard::Stun); + } + let state = InternalState { + stats: moq_net::stats::Registry::disabled(), + nodes: None, + refusals: None, + sessions: crate::session::Registry::new(), + listeners: Vec::new(), + uring: Vec::new(), + stun: None, + demux, + shutdown: None, + }; + let response = serve_metrics(State(state)).await; + let body = axum::body::to_bytes(response.into_body(), usize::MAX).await.unwrap(); + let body = std::str::from_utf8(&body).unwrap(); + match configured { + None => assert!(!body.contains("moq_relay_demux_dropped_total")), + Some(_) => { + assert!(body.contains("moq_relay_demux_dropped_total{reason=\"stun\"} 1")); + for reason in Discard::ALL { + let row = format!("moq_relay_demux_dropped_total{{reason=\"{}\"}}", reason.as_str()); + assert!(body.contains(&row), "{row} missing"); + } + } + } + } + } + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -1174,6 +1255,8 @@ mod tests { uring: Vec::new(), #[cfg(any(feature = "stun", test))] stun: None, + #[cfg(feature = "_quic")] + demux: None, shutdown: None, }; @@ -1194,6 +1277,8 @@ mod tests { uring: Vec::new(), #[cfg(any(feature = "stun", test))] stun: None, + #[cfg(feature = "_quic")] + demux: None, shutdown: None, }; diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index 08e5b3a1b43..9290123a2b6 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -108,6 +108,10 @@ pub struct Relay { /// they own the QUIC listen address instead of `workers`. #[cfg(all(target_os = "linux", feature = "_uring"))] uring: Option, + /// The tokio QUIC listener's demux, which every worker shares. `None` when + /// nothing on tokio serves QUIC: a stream-only relay, or the io_uring workers. + #[cfg(feature = "_quic")] + demux: Option, } impl Relay { @@ -215,6 +219,11 @@ impl Relay { listen.tls = Default::default(); } + // Shared by whichever tokio listener serves QUIC, so one feed and one set of + // counters covers every worker. + #[cfg(feature = "_quic")] + let demux = moq_tokio::quic::demux::Demux::default(); + #[cfg(feature = "_quic")] let workers = match config.runtime.workers() { Some(worker) if !io_uring => { @@ -223,6 +232,7 @@ impl Relay { server.tls = served.clone(); server.quic = config.quic.clone(); server.activity = shutdown.activity.clone(); + server.demux = demux.clone(); Some(moq_tokio::worker::Workers::bind(server, worker).context("failed to start the QUIC workers")?) } _ => None, @@ -264,6 +274,10 @@ impl Relay { server_config.tls = served; server_config.quic = config.quic.clone(); server_config.activity = shutdown.activity.clone(); + #[cfg(feature = "_quic")] + { + server_config.demux = demux.clone(); + } #[cfg(feature = "iroh")] { server_config.iroh = iroh.clone(); @@ -288,6 +302,13 @@ impl Relay { }, }; + // The io_uring workers serve QUIC without the demux, and a stream-only relay + // has no UDP port at all. + #[cfg(all(feature = "_quic", target_os = "linux", feature = "_uring"))] + let demux = (addr.is_some() && uring.is_none()).then_some(demux); + #[cfg(all(feature = "_quic", not(all(target_os = "linux", feature = "_uring"))))] + let demux = addr.is_some().then_some(demux); + let cache = config.cache.init()?; // Whichever worker group owns QUIC holds the certificates; the shared // server then has none of its own. @@ -356,6 +377,8 @@ impl Relay { .bind()?; #[cfg(feature = "stun")] let internal = internal.with_stun(stun.as_ref().map(|stun| stun.counters.clone())); + #[cfg(feature = "_quic")] + let internal = internal.with_demux(demux.as_ref().map(|demux| demux.counters().clone())); // Bound but not yet serving: registering here (rather than after the // threads start) is what gives every worker a series from the first // scrape, including one that is about to fail setup. @@ -397,6 +420,8 @@ impl Relay { workers, #[cfg(all(target_os = "linux", feature = "_uring"))] uring, + #[cfg(feature = "_quic")] + demux, }) } @@ -446,6 +471,21 @@ impl Relay { self.admissions.take() } + /// The WebRTC media path (ICE checks, DTLS, and RTP) arriving on the QUIC port, + /// for an embedder's WebRTC stack to serve and answer through the same port. + /// + /// Until a feed is taken, and once every feed is dropped, that traffic is + /// dropped and counted. Fails when no tokio listener serves QUIC: a stream-only + /// relay, or one on the io_uring workers, which do not split the port yet. + #[cfg(feature = "_quic")] + pub fn webrtc(&self) -> anyhow::Result { + let demux = self + .demux + .as_ref() + .context("the WebRTC media path needs QUIC served by the tokio runtime")?; + Ok(demux.webrtc()) + } + /// The shared cluster: the origin every session and peer publishes into. pub fn cluster(&self) -> &cluster::Cluster { &self.cluster diff --git a/rs/moq-relay/tests/integration/embed.rs b/rs/moq-relay/tests/integration/embed.rs index c40d96800dc..3c2803fcdd4 100644 --- a/rs/moq-relay/tests/integration/embed.rs +++ b/rs/moq-relay/tests/integration/embed.rs @@ -424,6 +424,74 @@ async fn uring_custom_route_and_quic() { embed_and_stop(config).await; } +/// The WebRTC media path on the QUIC port reaches the embedder's feed, whichever +/// worker read it, and the feed's reply leaves from the QUIC port. +async fn webrtc_feed(mut config: Config) { + let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); + config.drain_timeout = Some((Duration::ZERO).into()); + let relay = Relay::load(config).await.expect("load relay").with_signals(false); + let quic = relay.quic_addr().expect("quic listener bound"); + let feed = relay.webrtc().expect("tokio serves QUIC"); + let trigger = relay.shutdown_trigger().clone(); + let running = tokio::spawn(relay.run()); + + // Enough sources that a reuseport group's 4-tuple hash spreads them over every member. + let mut peers = Vec::new(); + for i in 0..16u8 { + let peer = tokio::net::UdpSocket::bind("127.0.0.1:0").await.expect("bind peer"); + peer.send_to(&[0x16, 0xfe, 0xfd, i], quic).await.expect("send DTLS"); + peers.push(peer); + } + let mut seen = std::collections::HashSet::new(); + tokio::time::timeout(TIMEOUT, async { + while seen.len() < peers.len() { + let datagram = feed.recv().await.expect("feed open"); + assert_eq!(datagram.data[..3], [0x16, 0xfe, 0xfd]); + seen.insert(datagram.remote); + } + }) + .await + .expect("every peer's datagram reached the feed"); + + let peer = &peers[0]; + feed.send(&moq_tokio::quic::demux::Transmit { + destination: peer.local_addr().expect("peer addr"), + ecn: None, + contents: b"reply", + segment_size: None, + src_ip: None, + }) + .await + .expect("send reply"); + let mut buf = [0; 16]; + let (len, from) = tokio::time::timeout(TIMEOUT, peer.recv_from(&mut buf)) + .await + .expect("reply arrived") + .expect("recv reply"); + assert_eq!(&buf[..len], b"reply"); + assert_eq!(from.port(), quic.port()); + + stop(trigger, running).await; +} + +#[tokio::test] +async fn shared_tokio_webrtc_feed() { + let dir = tempfile::tempdir().expect("tempdir"); + let (cert, key) = certificate(dir.path()); + webrtc_feed(http_and_quic(&cert, &key, "127.0.0.1:0".into())).await; +} + +#[cfg(target_os = "linux")] +#[tokio::test] +async fn worker_tokio_webrtc_feed() { + let dir = tempfile::tempdir().expect("tempdir"); + let (cert, key) = certificate(dir.path()); + let mut config = http_and_quic(&cert, &key, "127.0.0.1:0".into()); + config.runtime.workers = Some(2); + config.runtime.pin = false; + webrtc_feed(config).await; +} + /// An embedder-owned accept loop joins the relay's own /metrics exposition. #[tokio::test] async fn embedded_listener_health_reaches_metrics() { diff --git a/rs/moq-tokio/src/quic.rs b/rs/moq-tokio/src/quic.rs index ae8167d0bf4..d057b6eadb3 100644 --- a/rs/moq-tokio/src/quic.rs +++ b/rs/moq-tokio/src/quic.rs @@ -20,6 +20,8 @@ mod backend; pub use backend::Error; #[cfg(feature = "quic")] pub(crate) use backend::{Client, Closer, Options, Server, accept}; +#[cfg(feature = "quic")] +pub mod demux; /// The flow-control limits a live QUIC connection can change; see [`driver::Connection::set_limits`]. #[cfg(feature = "driver")] pub use moq_quic::{Limits, LimitsError}; diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index 28f8951374d..7c29c65a510 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -595,8 +595,11 @@ pub(crate) struct Server { /// as long as anything holds its handle, so dropping the endpoint leaves the port /// bound until every accepted session is gone too. Taking the socket out of this /// slot closes it regardless. +/// +/// Every datagram it reads goes through the listener's [`Divert`](super::demux::Divert), +/// which leaves only QUIC for the endpoint. #[derive(Clone, Debug)] -struct Socket { +pub(crate) struct Socket { io: Arc>>>, state: Arc, local: net::SocketAddr, @@ -605,10 +608,11 @@ struct Socket { blocked: Arc, /// When a send error was last logged, shared so a busy server logs one per interval. last_send_error: Arc>>, + divert: super::demux::Divert, } impl Socket { - fn new(socket: std::net::UdpSocket) -> std::io::Result { + fn new(socket: std::net::UdpSocket, divert: super::demux::Divert) -> std::io::Result { let state = moq_sock::udp::UdpSocketState::new((&socket).into())?; let local = socket.local_addr()?; let io = tokio::net::UdpSocket::from_std(socket)?; @@ -618,6 +622,7 @@ impl Socket { local, blocked: Default::default(), last_send_error: Default::default(), + divert, }) } @@ -626,6 +631,46 @@ impl Socket { fn release(&self) { self.io.write().unwrap().take(); } + + /// Whether [`Self::release`] closed the socket. + pub(crate) fn is_released(&self) -> bool { + self.io.read().unwrap().is_none() + } + + /// Whether the socket is AF_INET6, so an IPv4 destination needs its mapped form. + pub(crate) fn is_ipv6(&self) -> bool { + self.local.is_ipv6() + } + + /// Send `transmit`, or register `cx` to retry once the socket is writable. + pub(crate) fn poll_transmit( + &self, + transmit: &moq_sock::udp::Transmit<'_>, + cx: &mut Context<'_>, + ) -> Poll> { + let io = self.io.read().unwrap(); + // Released: the datagram is lost, which UDP always allows. + let Some(io) = io.as_deref() else { + return Poll::Ready(Ok(())); + }; + loop { + match io.try_io(tokio::io::Interest::WRITABLE, || { + self.state.try_send(io.into(), transmit) + }) { + Ok(()) => return Poll::Ready(Ok(())), + Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {} + Err(err) => { + let mut last = self.last_send_error.lock().unwrap(); + return Poll::Ready(driver::send_failed(&mut last, err, transmit)); + } + } + // Every connection sends from its own task, but tokio keeps one waker per + // direction, so register a fan-out to all of them instead of this task's. + self.blocked.push(cx.waker()); + let waker = Waker::from(self.blocked.clone()); + ready!(io.poll_send_ready(&mut Context::from_waker(&waker)))?; + } + } } impl driver::AsyncUdpSocket for Socket { @@ -648,7 +693,7 @@ impl driver::AsyncUdpSocket for Socket { loop { ready!(io.poll_recv_ready(cx))?; match io.try_io(tokio::io::Interest::READABLE, || self.state.recv(io.into(), bufs, meta)) { - Ok(res) => return Poll::Ready(Ok(res)), + Ok(received) => return Poll::Ready(Ok(self.divert.split(bufs, meta, received))), // `try_io` clears readiness only for `WouldBlock`; retrying any other error // would spin, since `poll_recv_ready` completes at once and the recv fails again. Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {} @@ -676,28 +721,7 @@ impl driver::UdpSender for Socket { transmit: &moq_sock::udp::Transmit<'_>, cx: &mut Context<'_>, ) -> Poll> { - let io = self.io.read().unwrap(); - // Released: the datagram is lost, which UDP always allows. - let Some(io) = io.as_deref() else { - return Poll::Ready(Ok(())); - }; - loop { - match io.try_io(tokio::io::Interest::WRITABLE, || { - self.state.try_send(io.into(), transmit) - }) { - Ok(()) => return Poll::Ready(Ok(())), - Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {} - Err(err) => { - let mut last = self.last_send_error.lock().unwrap(); - return Poll::Ready(driver::send_failed(&mut last, err, transmit)); - } - } - // Every connection sends from its own task, but tokio keeps one waker per - // direction, so register a fan-out to all of them instead of this task's. - self.blocked.push(cx.waker()); - let waker = Waker::from(self.blocked.clone()); - ready!(io.poll_send_ready(&mut Context::from_waker(&waker)))?; - } + self.poll_transmit(transmit, cx) } fn max_transmit_segments(&self) -> usize { @@ -735,6 +759,7 @@ pub(crate) struct Options { pub quic: crate::quic::Config, pub member: Option, pub tls: crate::tls::Serve, + pub demux: super::demux::Demux, } impl Server { @@ -744,6 +769,7 @@ impl Server { quic, member, tls: served, + demux, } = options; let mut transport = driver::TransportConfig::default(); let quic = quic.resolve(); @@ -798,6 +824,9 @@ impl Server { let load_balancer = config.load_balancer(); let mut endpoint_config = driver::EndpointConfig::default(); + // The demux, and the shard steering filter, tell QUIC from the WebRTC media + // path by the fixed bit, so peers must never be invited to clear it. + endpoint_config.grease_quic_bit(false); // First, since it also keys the default connection ID generator. The ones // below validate a predecessor's IDs without it. if let Some(secret) = &config.reset.secret { @@ -810,8 +839,6 @@ impl Server { if load_balancer.is_some() { return Err(Error::ShardWithQuicLb); } - // The steering filter recognizes short headers by their fixed bit. - endpoint_config.grease_quic_bit(false); tracing::debug!( index = shard.index(), count = shard.count(), @@ -852,7 +879,8 @@ impl Server { }; // Create the generic QUIC endpoint. - let socket = Socket::new(socket).map_err(Error::CreateEndpoint)?; + let socket = Socket::new(socket, demux.divert()).map_err(Error::CreateEndpoint)?; + demux.attach(socket.clone()); let quic = driver::Endpoint::new_with_abstract_socket(endpoint_config, Some(tls), Box::new(socket.clone())) .map_err(Error::CreateEndpoint)?; @@ -1078,7 +1106,7 @@ mod tests { socket .bind(&net::SocketAddr::from((net::Ipv6Addr::LOCALHOST, 0)).into()) .unwrap(); - let socket = Socket::new(socket.into()).unwrap(); + let socket = Socket::new(socket.into(), crate::quic::demux::Demux::default().divert()).unwrap(); let transmit = moq_sock::udp::Transmit { destination: net::SocketAddr::new(net::Ipv4Addr::LOCALHOST.to_ipv6_mapped().into(), 1), @@ -1128,6 +1156,98 @@ mod tests { ); } + /// QUIC and the WebRTC media path share the listening port: a QUIC session + /// connects while a WebRTC peer's ICE check, DTLS, and RTP reach the feed and + /// its reply leaves from the same port, and a public STUN query is dropped. + #[tokio::test] + async fn one_port_serves_quic_and_webrtc() { + let demux = crate::quic::demux::Demux::default(); + let feed = demux.webrtc(); + let quic = crate::quic::Config::default(); + let config = listen::Config { + bind: Some("[::]:0".parse().unwrap()), + tls: crate::tls::Listen { + generate: vec!["localhost".into()], + ..Default::default() + }, + ..Default::default() + }; + let tls = config.tls.load().unwrap(); + let server = Server::new(Options { + config, + quic: quic.clone(), + member: None, + tls, + demux: demux.clone(), + }) + .expect("server init"); + let port = server.local_addr().expect("local addr").port(); + let addr = net::SocketAddr::from((net::Ipv4Addr::LOCALHOST, port)); + + let peer = tokio::net::UdpSocket::bind("127.0.0.1:0").await.unwrap(); + let check: &[u8] = &[ + 0x00, 0x01, 0x00, 0x08, 0x21, 0x12, 0xa4, 0x42, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 0x00, 0x06, 0x00, + 0x03, b'a', b':', b'b', 0, + ]; + let query = &check[..20]; + let query = [&[0x00, 0x01, 0x00, 0x00][..], &query[4..]].concat(); + let sent: [&[u8]; 3] = [check, &[0x16, 0xfe, 0xfd, 1], &[0x80, 0x00, 0, 1]]; + peer.send_to(&query, addr).await.unwrap(); + for datagram in sent { + peer.send_to(datagram, addr).await.unwrap(); + } + + let mut tls_config = crate::tls::Connect::default(); + tls_config.fingerprint = server.certificates().fingerprints(); + let config = connect::Config { + bind: Some("127.0.0.1:0".parse().unwrap()), + tls: tls_config, + ..Default::default() + }; + let tls = config.tls.build().expect("tls config"); + let client = Client::new(&config, &quic).expect("client init"); + let url: Url = format!("moqt://localhost:{port}/test").parse().unwrap(); + let versions = moq_net::Versions::default(); + let dial = client.connect(&tls, url.into(), &versions); + let accept = async { + let incoming = server.accept().await.expect("incoming connection"); + super::accept(incoming, versions.alpns()).await + }; + let webrtc = async { + let mut received = Vec::new(); + for _ in sent { + let datagram = feed.recv().await.expect("feed open"); + assert_eq!(datagram.remote, peer.local_addr().unwrap()); + received.push(datagram.data.to_vec()); + } + feed.send(&moq_sock::udp::Transmit { + destination: peer.local_addr().unwrap(), + ecn: None, + contents: b"reply", + segment_size: None, + src_ip: None, + }) + .await + .unwrap(); + let mut buf = [0; 16]; + let (len, from) = peer.recv_from(&mut buf).await.unwrap(); + (received, buf[..len].to_vec(), from.port()) + }; + let (session, received) = tokio::time::timeout(Duration::from_secs(5), async { + let (session, received) = tokio::join!(async { tokio::try_join!(dial, accept) }, webrtc); + (session, received) + }) + .await + .expect("timed out"); + session.expect("QUIC beside WebRTC"); + + let (received, reply, from) = received; + assert_eq!(received, sent.map(<[u8]>::to_vec)); + assert_eq!(reply, b"reply"); + assert_eq!(from, port); + assert_eq!(demux.counters().get(crate::quic::demux::Discard::Stun), 1); + } + async fn pinned_connection(bind: &str, host_name: Option<&str>) { let quic = crate::quic::Config::default(); let config = listen::Config { @@ -1144,6 +1264,7 @@ mod tests { quic: quic.clone(), member: None, tls, + demux: Default::default(), }) .expect("server init"); let addr = server.local_addr().expect("local addr"); @@ -1250,6 +1371,7 @@ mod tests { quic: quic.clone(), member: None, tls, + demux: Default::default(), }) .expect("server init"); let addr = server.local_addr().expect("local addr"); diff --git a/rs/moq-tokio/src/quic/demux.rs b/rs/moq-tokio/src/quic/demux.rs new file mode 100644 index 00000000000..42a3c99c181 --- /dev/null +++ b/rs/moq-tokio/src/quic/demux.rs @@ -0,0 +1,412 @@ +//! One UDP port shared by QUIC and the WebRTC media path. +//! +//! A QUIC listener's socket classifies every datagram it reads with +//! [`moq_sock::demux`]: QUIC stays on the endpoint, and ICE checks, DTLS, and RTP +//! are diverted to a [`WebRtc`] feed that an embedder hands to its WebRTC stack. +//! Anything else is dropped and counted. The split runs inline in the endpoint's +//! receive, so a QUIC datagram is never copied or handed across tasks. + +use std::{ + io::{self, IoSliceMut}, + net::{IpAddr, SocketAddr}, + sync::{Arc, Mutex}, + task::Poll, +}; + +use bytes::Bytes; +use moq_sock::{ + demux::{Flows, Queue, Route}, + udp::RecvMeta, +}; + +pub use moq_sock::{ + demux::{Counters, Discard, Pin}, + udp::Transmit, +}; + +use super::backend::Socket; + +/// The bytes a [`WebRtc`] feed may hold before it drops, shared by every source. +const CAPACITY: usize = 4 << 20; + +/// A QUIC listener's demux: what its socket diverts, pins, and drops. +/// +/// Clones share one state, so every shard of a worker group feeds one [`WebRtc`] +/// and counts into one [`Counters`]. Set it as +/// [`server::Config::demux`](crate::server::Config::demux) and keep a clone. +#[derive(Clone, Debug, Default)] +pub struct Demux { + /// Liveness: a [`WebRtc`] consumes it, and closes when every clone is gone. + live: kio::Producer<()>, + shared: Arc, + /// The listening sockets a [`WebRtc`] answers through. + sockets: Arc>>, +} + +#[derive(Debug)] +struct Shared { + flows: Flows, + counters: Counters, + queue: kio::Shared>, +} + +impl Default for Shared { + fn default() -> Self { + Self { + flows: Flows::default(), + counters: Counters::default(), + queue: kio::Shared::new(Queue::new(CAPACITY)), + } + } +} + +impl Demux { + /// The datagrams this listener dropped, per reason. + pub fn counters(&self) -> &Counters { + &self.shared.counters + } + + /// Start diverting the WebRTC media path to a feed. + /// + /// Until a feed exists, and again once every feed is dropped, that traffic is + /// dropped as [`Discard::Unclaimed`]. Feeds share one queue. + pub fn webrtc(&self) -> WebRtc { + // The first feed starts clean rather than reading what a previous one left. + if !self.live.is_used() { + self.shared.queue.lock().clear(); + } + WebRtc { + live: self.live.consume(), + shared: self.shared.clone(), + sockets: self.sockets.clone(), + } + } + + /// The receive half a listening socket runs, which never keeps the feed open. + pub(crate) fn divert(&self) -> Divert { + Divert { + live: self.live.weak(), + shared: self.shared.clone(), + } + } + + /// Answer through `socket`, one of the sockets this demux reads. + pub(crate) fn attach(&self, socket: Socket) { + self.sockets.lock().unwrap().push(socket); + } +} + +/// A datagram diverted to the WebRTC media path. +#[derive(Clone, Debug)] +#[non_exhaustive] +pub struct Datagram { + /// The sender, with an IPv4-mapped address folded to IPv4. + pub remote: SocketAddr, + /// The local address it arrived on, where the platform reports it. + pub local: Option, + /// The whole datagram. + pub data: Bytes, +} + +/// The WebRTC media path of a [`Demux`]: ICE checks, DTLS, and RTP from its +/// socket, and a way to answer through it. +/// +/// Diverting runs while any feed is alive; drop it to stop. +#[derive(Debug)] +pub struct WebRtc { + live: kio::Consumer<()>, + shared: Arc, + sockets: Arc>>, +} + +impl WebRtc { + /// Poll for the next datagram; `None` once every [`Demux`] clone is gone. + pub fn poll_recv(&self, waiter: &kio::Waiter) -> Poll> { + if let Poll::Ready(mut queue) = self.shared.queue.poll(waiter, |queue| match queue.is_empty() { + true => Poll::Pending, + false => Poll::Ready(()), + }) { + return Poll::Ready(queue.pop()); + } + // Nothing queued; nothing more arrives once the listener is gone. + match self.live.poll_closed(waiter) { + Poll::Ready(()) => Poll::Ready(self.shared.queue.lock().pop()), + Poll::Pending => Poll::Pending, + } + } + + /// Receive the next datagram; `None` once every [`Demux`] clone is gone. + pub async fn recv(&self) -> Option { + kio::wait(|waiter| self.poll_recv(waiter)).await + } + + /// Poll to send `transmit` from the shared port, with GSO and ECN as it asks. + /// + /// A datagram sent once the listener has released its socket is lost, as UDP + /// allows. Errors are those of [`AsyncUdpSocket`](crate::quic::driver::AsyncUdpSocket)'s + /// sender: an unreachable destination comes back, anything else is logged. + pub fn poll_send(&self, waiter: &kio::Waiter, transmit: &Transmit<'_>) -> Poll> { + // Any member of a reuseport group answers from the same port. + let sockets = self.sockets.lock().unwrap(); + let Some(socket) = sockets.iter().find(|socket| !socket.is_released()) else { + return Poll::Ready(Ok(())); + }; + let destination = match (transmit.destination, socket.is_ipv6()) { + (SocketAddr::V4(v4), true) => SocketAddr::new(v4.ip().to_ipv6_mapped().into(), v4.port()), + (destination, _) => destination, + }; + let transmit = Transmit { + destination, + ..*transmit + }; + socket.poll_transmit(&transmit, &mut waiter.context()) + } + + /// Send `transmit` from the shared port; see [`Self::poll_send`]. + pub async fn send(&self, transmit: &Transmit<'_>) -> io::Result<()> { + kio::wait(|waiter| self.poll_send(waiter, transmit)).await + } + + /// Route every datagram from `remote` to this feed, whatever its first byte, + /// until the returned [`Pin`] drops. + pub fn pin(&self, remote: SocketAddr) -> Pin { + self.shared.flows.pin(remote) + } +} + +/// The receive half of a [`Demux`], run by each listening socket. +#[derive(Clone, Debug)] +pub(crate) struct Divert { + live: kio::ProducerWeak<()>, + shared: Arc, +} + +impl Divert { + /// Route the `received` batches in `bufs` and `metas`, keeping only QUIC. + /// + /// QUIC segments are compacted to the front of each batch and the batches + /// emptied by the split are removed, so the endpoint reads the first + /// returned-count entries as usual. That count may be zero. + pub(crate) fn split(&self, bufs: &mut [IoSliceMut<'_>], metas: &mut [RecvMeta], received: usize) -> usize { + let mut kept = 0; + for i in 0..received { + let mut meta = metas[i]; + meta.len = self.split_batch(&mut bufs[i][..meta.len], &meta); + if meta.len == 0 { + continue; + } + if kept != i { + let (head, tail) = bufs.split_at_mut(i); + head[kept][..meta.len].copy_from_slice(&tail[0][..meta.len]); + } + metas[kept] = meta; + kept += 1; + } + kept + } + + /// Route each `meta.stride` segment of one batch, returning the length of the + /// QUIC segments left at its front. + /// + /// Only the last segment of a batch may be short, and the QUIC ones keep their + /// order, so the compacted batch keeps the same stride. + fn split_batch(&self, buf: &mut [u8], meta: &RecvMeta) -> usize { + let mut kept = 0; + let mut start = 0; + while start < buf.len() { + let end = buf.len().min(start + meta.stride.max(1)); + match self.shared.flows.route(meta.addr, &buf[start..end]) { + Route::Quic => { + buf.copy_within(start..end, kept); + kept += end - start; + } + Route::WebRtc => self.push(meta, &buf[start..end]), + Route::Discard(reason) => self.shared.counters.discard(reason), + } + start = end; + } + kept + } + + fn push(&self, meta: &RecvMeta, data: &[u8]) { + if !self.live.is_used() { + self.shared.counters.discard(Discard::Unclaimed); + return; + } + let remote = SocketAddr::new(meta.addr.ip().to_canonical(), meta.addr.port()); + let datagram = Datagram { + remote, + local: meta.dst_ip.map(|ip| ip.to_canonical()), + data: Bytes::copy_from_slice(data), + }; + let cost = data.len() + size_of::(); + if self.shared.queue.lock().push(remote, cost, datagram).is_err() { + self.shared.counters.discard(Discard::Overflow); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const CHECK: &[u8] = &[ + 0x00, 0x01, 0x00, 0x08, 0x21, 0x12, 0xa4, 0x42, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, // header + 0x00, 0x06, 0x00, 0x03, b'a', b':', b'b', 0, // USERNAME + ]; + const QUERY: &[u8] = &[ + 0x00, 0x01, 0x00, 0x00, 0x21, 0x12, 0xa4, 0x42, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, + ]; + + fn remote(port: u16) -> SocketAddr { + SocketAddr::from(([192, 0, 2, 1], port)) + } + + /// Split `batches`, each one GRO batch of equal-stride segments from one source, + /// and return what the endpoint would read. + fn split(divert: &Divert, batches: &[(SocketAddr, &[&[u8]])]) -> Vec<(SocketAddr, usize, Vec)> { + let mut storage = vec![[0u8; 1024]; batches.len()]; + let mut metas = vec![RecvMeta::default(); batches.len()]; + for ((buf, meta), (addr, segments)) in storage.iter_mut().zip(&mut metas).zip(batches) { + let stride = segments[0].len(); + let mut len = 0; + for segment in *segments { + buf[len..len + segment.len()].copy_from_slice(segment); + len += stride; + } + len -= stride - segments.last().unwrap().len(); + meta.addr = *addr; + meta.len = len; + meta.stride = stride; + } + let mut bufs: Vec<_> = storage.iter_mut().map(|buf| IoSliceMut::new(buf)).collect(); + let kept = divert.split(&mut bufs, &mut metas, batches.len()); + metas[..kept] + .iter() + .zip(&bufs) + .map(|(meta, buf)| (meta.addr, meta.stride, buf[..meta.len].to_vec())) + .collect() + } + + fn drain(feed: &WebRtc) -> Vec<(SocketAddr, Vec)> { + std::iter::from_fn(|| match feed.poll_recv(&kio::Waiter::noop()) { + Poll::Ready(Some(datagram)) => Some((datagram.remote, datagram.data.to_vec())), + _ => None, + }) + .collect() + } + + #[test] + fn each_class_reaches_its_stack() { + let demux = Demux::default(); + let feed = demux.webrtc(); + let kept = split( + &demux.divert(), + &[ + (remote(1), &[&[0x40, 1]]), + (remote(2), &[CHECK]), + (remote(3), &[&[0x16, 0xfe, 0xfd]]), + (remote(4), &[&[0x80, 0x00]]), + (remote(5), &[&[0xc0, 5]]), + (remote(6), &[QUERY]), + (remote(7), &[&[5]]), + ], + ); + + // QUIC compacts to the front; the diverted batches leave no gap. + assert_eq!(kept, [(remote(1), 2, vec![0x40, 1]), (remote(5), 2, vec![0xc0, 5])]); + assert_eq!( + drain(&feed), + [ + (remote(2), CHECK.to_vec()), + (remote(3), vec![0x16, 0xfe, 0xfd]), + (remote(4), vec![0x80, 0x00]), + ] + ); + assert_eq!(demux.counters().get(Discard::Stun), 1); + assert_eq!(demux.counters().get(Discard::Unknown), 1); + } + + #[test] + fn a_mixed_batch_keeps_its_stride() { + let demux = Demux::default(); + let feed = demux.webrtc(); + let kept = split( + &demux.divert(), + &[(remote(1), &[&[0x40, 1, 1], &[0x80, 2, 2], &[0x41, 3, 3], &[0x42, 4]])], + ); + + assert_eq!(kept, [(remote(1), 3, vec![0x40, 1, 1, 0x41, 3, 3, 0x42, 4])]); + assert_eq!(drain(&feed), [(remote(1), vec![0x80, 2, 2])]); + } + + #[test] + fn a_pinned_remote_reaches_webrtc_whatever_it_sends() { + let demux = Demux::default(); + let feed = demux.webrtc(); + let pin = feed.pin(remote(1)); + let kept = split( + &demux.divert(), + &[(remote(1), &[&[0x40, 1]]), (remote(2), &[&[0x40, 2]])], + ); + assert_eq!(kept, [(remote(2), 2, vec![0x40, 2])]); + assert_eq!(drain(&feed), [(remote(1), vec![0x40, 1])]); + + drop(pin); + let kept = split(&demux.divert(), &[(remote(1), &[&[0x40, 1]])]); + assert_eq!(kept.len(), 1); + } + + #[test] + fn webrtc_traffic_waits_for_a_feed() { + let demux = Demux::default(); + let divert = demux.divert(); + let rtp: &[(SocketAddr, &[&[u8]])] = &[(remote(1), &[&[0x80, 0]])]; + + // Nobody reads it yet, so nothing is held for later. + assert!(split(&divert, rtp).is_empty()); + assert_eq!(demux.counters().get(Discard::Unclaimed), 1); + + let feed = demux.webrtc(); + split(&divert, rtp); + drop(feed); + split(&divert, rtp); + assert_eq!(demux.counters().get(Discard::Unclaimed), 2); + + // A new feed starts clean, without the datagram the dropped one left. + let feed = demux.webrtc(); + assert!(drain(&feed).is_empty()); + } + + #[test] + fn a_flooding_source_overflows_alone() { + let demux = Demux::default(); + let feed = demux.webrtc(); + let divert = demux.divert(); + let big = [0x80; 1024]; + let share = CAPACITY / Queue::::SHARE / big.len(); + for _ in 0..=share { + split(&divert, &[(remote(1), &[&big])]); + } + let overflow = demux.counters().get(Discard::Overflow); + assert!(overflow > 0); + + split(&divert, &[(remote(2), &[&big])]); + assert_eq!(demux.counters().get(Discard::Overflow), overflow); + assert_eq!(drain(&feed).last().map(|(remote, _)| *remote), Some(remote(2))); + } + + #[test] + fn the_feed_ends_with_the_listener() { + let demux = Demux::default(); + let feed = demux.webrtc(); + let divert = demux.divert(); + split(&divert, &[(remote(1), &[&[0x80, 0]])]); + drop(demux); + + // What was queued still arrives, then the end. + let waiter = kio::Waiter::noop(); + assert!(matches!(feed.poll_recv(&waiter), Poll::Ready(Some(_)))); + assert!(matches!(feed.poll_recv(&waiter), Poll::Ready(None))); + } +} diff --git a/rs/moq-tokio/src/quic/driver/endpoint.rs b/rs/moq-tokio/src/quic/driver/endpoint.rs index 1b2bec10304..050e5306a02 100644 --- a/rs/moq-tokio/src/quic/driver/endpoint.rs +++ b/rs/moq-tokio/src/quic/driver/endpoint.rs @@ -868,7 +868,9 @@ impl RecvState { loop { match socket.poll_recv(cx, &mut iovs, &mut metas) { Poll::Ready(Ok(msgs)) => { - self.recv_limiter.record_work(msgs); + // A demuxing socket can hand back an empty batch after diverting every + // datagram it read; that read is still work, or a flood of it never yields. + self.recv_limiter.record_work(msgs.max(1)); // Copy the received batch into `datagrams` and split each datagram off as // an owned slice. We can't read directly into `datagrams` and drop // `recv_buf`: once a slice has been handed to a connection the allocation diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index 176d1fcd092..20ee22e304d 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -193,6 +193,11 @@ pub struct Config { /// Per-connection statistics context. pub stats: moq_net::stats::Session, + + /// What the QUIC socket diverts from the shared port and drops; keep a clone to + /// take its [`webrtc`](crate::quic::demux::Demux::webrtc) feed or read its counters. + #[cfg(feature = "quic")] + pub demux: crate::quic::demux::Demux, } impl Config { @@ -222,6 +227,7 @@ impl Config { subscriber: self.subscriber.clone(), stats: self.stats.clone(), activity: self.activity.clone(), + demux: self.demux.clone(), } } } @@ -279,6 +285,8 @@ impl Server { publisher, subscriber, stats, + #[cfg(feature = "quic")] + demux, } = config; // Refuse here rather than in `init`, so a caller that skipped its own check @@ -376,6 +384,7 @@ impl Server { quic: quic.clone(), member, tls: tls.clone().expect("QUIC needs TLS"), + demux: demux.clone(), }) }) .transpose()?; From 5ec772fafaee74b60a9d029b913aee5ac35f8e38 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 06:13:42 -0700 Subject: [PATCH 4/8] docs(relay): one UDP port for QUIC and WebRTC; finish the UDP demux quest Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/config.md | 7 ++++ doc/bin/relay/index.md | 3 ++ quest/m2/one-port/README.md | 23 ++++++------- quest/m2/one-port/rtc-feed.md | 14 +++++--- quest/m2/one-port/srt-demux.md | 11 +++--- quest/m2/one-port/tcp-demux.md | 1 - quest/m2/p2p/README.md | 1 - quest/m2/p2p/native-quic.md | 6 ++-- quest/m2/p2p/udp-demux.md | 63 ---------------------------------- quest/m2/perf/shard-default.md | 1 - quest/m2/uring-demux.md | 10 +++--- 11 files changed, 45 insertions(+), 95 deletions(-) delete mode 100644 quest/m2/p2p/udp-demux.md diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index da3e71ef842..647eadb72cc 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -55,6 +55,13 @@ alike. A client that advertises its own name (moq-lite-05+ or any moq-transport reaches the [auth server](/bin/relay/auth#the-contract) with it as `implementation`, which is where to count client versions; older clients arrive without one. +`bind` is the relay's one UDP port. Beside QUIC it carries WebRTC media for an +[embedder](/bin/relay/#embed) that takes it; otherwise that traffic is dropped, +as are STUN Binding queries ([`[stun]`](#stun) has its own port) and anything +else. `/metrics` counts the drops in `moq_relay_demux_dropped_total` by `reason`: +`unclaimed` (WebRTC with no embedder), `overflow`, `stun`, and `unknown`. Not +with `runtime.io_uring`, which serves QUIC alone. + `reset.secret` lets a relay restarted on the same address reset its predecessor's QUIC connections, so clients reconnect at once instead of waiting out the idle timeout. Keep it secret, and give it to one relay diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 79af9ecd559..40d5bcde2c4 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -99,6 +99,9 @@ relay.with_web(web).run().await?; send its path in the SETUP. - To decide admissions yourself, leave `[auth]` empty and answer `relay.admissions()`; see [Authentication](/bin/relay/auth#in-process). +- To serve WebRTC media (WHIP, WHEP) on the QUIC port, take `relay.webrtc()`: + ICE checks, DTLS, and RTP arrive on it, and its `send` answers from the same + port. It fails with `runtime.io_uring`, whose workers do not split the port yet. See [docs.rs/moq-relay](https://docs.rs/moq-relay) and [`rs/moq-relay/examples/embed.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/examples/embed.rs). diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index 862fb1b9c6a..45e4c56a70a 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -31,12 +31,12 @@ Decided 2026-10-05, from moq.pro's audit: `moq-rtc` taking a fed socket m2 rather than m3, since moq.pro's edge cutover and its uring rollout wait on them. -Decided 2026-10-15: [UDP demux](/quest/m2/p2p/udp-demux.md) remains -under P2P, now deferred to m2, -because [native pairs](/quest/m2/p2p/native-quic.md) run QUIC and ICE's -STUN on one socket through the same demux. The rest of this line builds on -that shared prerequisite in m2. QUIC shard steering landed in #5638; -reuse its filter rather than recreating that completed work. +The UDP demux has landed: `moq_sock::demux` classifies, and the tokio QUIC +listener's socket diverts the WebRTC media path inline in its receive to a +`moq_tokio::quic::demux::WebRtc` feed, which `moq_relay::Relay::webrtc` +hands an embedder. [Native pairs](/quest/m2/p2p/native-quic.md) reuse the +classifier. QUIC shard steering landed in #5638; reuse its filter rather than +recreating that completed work. ### Classifying a datagram @@ -62,11 +62,11 @@ unknown tuple is not SRT; it is dropped or given to the WebRTC mux. ### Virtual sockets -One OS socket, or one shard of a reuseport group, is read by the demux and -fanned into virtual sockets, one per stack, each with the `AsyncUdpSocket` -shape. Sends go straight to the shared socket, so every stack answers from -the same address and port. moq-tokio's `quic::driver` accepts the virtual socket through -`new_with_abstract_socket`. `moq-rtc`'s `Mux` already demuxes STUN by ufrag +One OS socket, or one shard of a reuseport group, is read by the QUIC +endpoint's own socket, which keeps QUIC in place and copies every other +class into that stack's bounded feed, shared by every shard. Sends go +straight to the shared socket, so every stack answers from the same address +and port. `moq-rtc`'s `Mux` already demuxes STUN by ufrag internally and takes a fed socket in [WebRTC on the shared socket](/quest/m2/one-port/rtc-feed.md). SRT skips `srt-tokio`, which accepts a `tokio::net::UdpSocket` but no abstraction, and feeds @@ -101,6 +101,5 @@ pre-accepted streams can stand behind. ## Related -- [UDP demux](/quest/m2/p2p/udp-demux.md) - one socket carries QUIC, with a WebRTC hook for embedders; owned by deferred native P2P in m2 - [One port on the io_uring workers](/quest/m2/uring-demux.md) - the io_uring workers host the UDP demux - [Stream transports](/quest/m2/perf/stream/README.md) - the io_uring workers that would host the TCP acceptor later diff --git a/quest/m2/one-port/rtc-feed.md b/quest/m2/one-port/rtc-feed.md index 2f846076181..e5aa62e487d 100644 --- a/quest/m2/one-port/rtc-feed.md +++ b/quest/m2/one-port/rtc-feed.md @@ -60,6 +60,16 @@ demux routes that tuple to WebRTC before any SRT test (see the released when its session ends or ICE moves to another pair: either an unpin message or idle expiry in the flow table, as SRT's pins have. +The demux side has landed: `moq_tokio::quic::demux::WebRtc` (from +`Demux::webrtc`, or `moq_relay::Relay::webrtc` for an embedded relay) yields +ICE checks, DTLS, and RTP as `Datagram`s whose `remote` is already in +`moq_ice::canonical` form, sends a `Transmit` from the shared port (mapping an +IPv4 destination for an AF_INET6 socket), and pins a remote with `pin`, which +returns a guard that releases the pin on drop. So the fed `Socket` takes a +`WebRtc` rather than the channels in the sketch, and the mux holds a `Pin` per +selected pair, dropped when its session ends or ICE moves. A feed's `recv` +returns `None` once the listener is gone. + Things to watch: the server config is `Clone` today and a receiver is not, so the fed socket may belong in the server's constructor rather than the config. The fed mux has nothing to bind lazily, and a dropped feed should @@ -69,7 +79,3 @@ Tests: a fed mux completes ICE and DTLS with a client through an in-memory `Transmit`, reports the selected tuple on `pinned`, and releases it when the session closes. A fed dual-stack socket serves an IPv4 peer. The existing bound tests keep passing. - -## Required - -- [UDP demux](/quest/m2/p2p/udp-demux.md) - the WebRTC hook and flow table this feeds from and pins into diff --git a/quest/m2/one-port/srt-demux.md b/quest/m2/one-port/srt-demux.md index 645641f02eb..06086824fd8 100644 --- a/quest/m2/one-port/srt-demux.md +++ b/quest/m2/one-port/srt-demux.md @@ -17,8 +17,11 @@ demuxed packets. That is more code, but it removes the dependency on upstream (now rosalyntg/srt-rs) has not been pushed since 2024-05, and its maintainer said they do not actively support it. -The demux side is the flow table from [UDP demux](/quest/m2/p2p/udp-demux.md): -a 4-tuple already pinned to WebRTC (ICE succeeded) is never tested for SRT. +The demux side extends `moq_sock::demux`, whose `Flows` table today pins a +remote to WebRTC only, and the tokio listener's `quic::demux::Demux`, which +diverts inline in the QUIC socket's receive: add an SRT class with its own +feed and bounded `Queue`, and an owner per pin. A 4-tuple already pinned to +WebRTC (ICE succeeded) is never tested for SRT. An unknown 4-tuple whose full SRT handshake header matches (control bit, type 0, and the SRT magic, not merely `80 00`) pins to SRT provisionally: the provisional table is small and bounded, per-source rate limited, and an @@ -43,7 +46,3 @@ clock, so `tokio::time::pause` cannot drive its idle timeout. Tests: `moq-srt`'s existing integration test runs against the shared socket with a QUIC client active on the same port; a QUIC short header from a new 4-tuple during an SRT session still reaches QUIC. - -## Required - -- [UDP demux](/quest/m2/p2p/udp-demux.md) diff --git a/quest/m2/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md index c3f8da62751..edd8cb00be7 100644 --- a/quest/m2/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -54,6 +54,5 @@ right arm. ## Related -- [UDP demux](/quest/m2/p2p/udp-demux.md) - the UDP half - [mTLS on tls://](/quest/m2/tls-listener-mtls.md) - client-certificate verification on the `tls://` arm this acceptor carries - [WebSocket bitrate caps](/quest/m2/rate-websocket.md) - sizes the kernel buffers of the socket this acceptor boxes diff --git a/quest/m2/p2p/README.md b/quest/m2/p2p/README.md index 3def72861d0..2b54a6f9575 100644 --- a/quest/m2/p2p/README.md +++ b/quest/m2/p2p/README.md @@ -157,7 +157,6 @@ Extractor declaration checks, which analyze only published packages since - [Peer grants](/quest/m2/p2p/peer-grant.md) - the relay issues a key-bound, asymmetrically signed grant a browser can verify; HS256 keys issue none - [Signaling and policy](/quest/m2/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used -- [UDP demux](/quest/m2/p2p/udp-demux.md) - one classifier splits QUIC from STUN and WebRTC on the relay's socket and on a native pair's - [Native pairs over ICE and QUIC](/quest/m2/p2p/native-quic.md) - two native peers connect through ICE, then `moq-quic` over the nominated path with fingerprints pinned from the offer - [moq-cli joins](/quest/m2/p2p/cli.md) - `--p2p` publishes a roster entry, dials native peers over ICE and QUIC, and serves browsers as a transit hop - [Peer route policy](/quest/m2/p2p/cost-scopes.md) - application priorities and total cost choose eligible routes, with epoch-aware handover diff --git a/quest/m2/p2p/native-quic.md b/quest/m2/p2p/native-quic.md index 4d05a99735e..6e05876346a 100644 --- a/quest/m2/p2p/native-quic.md +++ b/quest/m2/p2p/native-quic.md @@ -28,7 +28,10 @@ Decided with the maintainer on 2026-10-13: in SDP. Both sides pin it with the existing `tls.fingerprint` check. MoQ AUTH with a [peer grant](/quest/m2/p2p/peer-grant.md) still runs on top. - After nomination the session's socket carries ICE consent checks and - QUIC, split by the [UDP demux](/quest/m2/p2p/udp-demux.md) classifier. + QUIC, split by `moq_sock::demux::classify`: `Check` and `Stun` go to the + ICE agent and `Quic` to the endpoint. The tokio listener's `quic::demux` + routes for a relay (STUN queries dropped, no ICE agent), so the session + socket needs its own small policy over the same classifier. Roles are deterministic: the ICE controlling side is the QUIC client, so a simultaneous dial resolves the same way [signaling](/quest/m2/p2p/signal.md) @@ -60,5 +63,4 @@ covers LAN and NAT pairs between two `moq-cli --p2p` nodes. ## Required -- [UDP demux](/quest/m2/p2p/udp-demux.md) - the classifier that splits STUN from QUIC - [Signaling and policy](/quest/m2/p2p/signal.md) - the offer schema and roster this extends diff --git a/quest/m2/p2p/udp-demux.md b/quest/m2/p2p/udp-demux.md deleted file mode 100644 index b12cb04a508..00000000000 --- a/quest/m2/p2p/udp-demux.md +++ /dev/null @@ -1,63 +0,0 @@ -# [M] UDP demux - -## Goal - -`moq-relay` reads one UDP socket and serves QUIC from it. The WebRTC media -path (DTLS, RTP, and ICE's STUN checks) is an embedder hook: the demux hands -its class to an embedder such as moq.pro's edge, which feeds it to -`moq-rtc`, since `moq-relay` serves no WHIP or WHEP. The same classifier -splits a native P2P session's socket into ICE's STUN and QUIC. - -## Plan - -Decided 2026-10-15: deferred to m2 with P2P as a whole, so [native P2P pairs](/quest/m2/p2p/native-quic.md) share one demux with the -relay rather than a P2P-only classifier (maintainer's choice over splitting -the classifier out). A native P2P session's socket uses the same classifier: -STUN goes to its ICE agent and QUIC to its endpoint; it has no flow table -and no WebRTC hook. - -`moq-sock` gains the demux: a task owning the OS socket (or shard) that -classifies each datagram by the rules in the -[one-port README](/quest/m2/one-port/README.md) and hands it to the matching -virtual socket, plus the flow table keyed by 4-tuple that WebRTC and SRT pin -into. Keep the classifier and flow table runtime-agnostic, apart from the -tokio task that drives them, because -[the io_uring demux](/quest/m2/uring-demux.md) runs the same piece inside -`moq-uring`'s endpoint. Each virtual socket implements -`AsyncUdpSocket`: `poll_recv` drains its queue, `poll_send` writes through -the shared socket with GSO and ECN passed along, `local_addr` is the shared -one. Bound queues per stack with a per-source drop rather than unbounded -growth; report drops as a counter. - -QUIC: the server takes the virtual socket through whatever the QUIC stack -accepts: the driver's `new_with_abstract_socket` on `moq-quic`. QUIC-bit -greasing is already off for sharded endpoints. - -STUN: an ICE connectivity check is a Binding request carrying USERNAME, so -it goes to the WebRTC hook, whose mux reads the local ufrag from it. A -Binding request without USERNAME is a public query; drop and count it. -Decided 2026-10-08: the public STUN responder is left to the P2P line, -so `moq-sock` takes no STUN codec dependency (str0m included). Decided -2026-10-13: it binds its own port ([relay STUN](/doc/bin/relay/config.md#stun)). -That listener and its settings are behind the relay's non-default `stun` -feature; consuming it must enable that feature explicitly. - -WebRTC: DTLS, RTP, and USERNAME-carrying STUN go to a `webrtc` hook that -`moq-relay` leaves unconsumed and an embedder takes: the datagrams, a send -path through the shared socket, and a way to pin a 4-tuple to WebRTC in the -flow table and release it. [WebRTC on the shared socket](/quest/m2/one-port/rtc-feed.md) -makes `moq-rtc` consume it. - -Decided in the 2026-09-30 audit: the relay itself serves only QUIC here, -because `moq-relay` has no `moq-rtc` dependency and serves no WHIP or WHEP. -Decided 2026-10-05: feeding `moq-rtc` moved from the embedder to -rtc-feed, because `moq-rtc` is an upstream, generic crate. - -Tests: a unit test per first-byte class routes to the right virtual socket, -including the WebRTC hook; an integration test runs a QUIC client against -the demuxed port. `moq-relay` docs list the port once. - -## Related - -- [One port](/quest/m2/one-port/README.md) - the line this came from, which builds the rest of one-port on it -- [One port on the io_uring workers](/quest/m2/uring-demux.md) - runs this classifier and flow table on the io_uring workers diff --git a/quest/m2/perf/shard-default.md b/quest/m2/perf/shard-default.md index 4adea1eafdd..579a142a859 100644 --- a/quest/m2/perf/shard-default.md +++ b/quest/m2/perf/shard-default.md @@ -62,6 +62,5 @@ Update `doc/bin/relay/` for the default change. ## Related - [kio channel contention](/quest/m2/perf/kio-channel-contention/README.md) - its per-thread spikes run on the workers -- [UDP demux](/quest/m2/p2p/udp-demux.md) - demuxes each shard's socket - [Performance survey](/quest/m2/performance-survey/README.md) - paired benchmark evidence and memory/settings controls - [Socket queues](/quest/m2/performance-survey/socket-queues.md) - queue sizing and local drop attribution diff --git a/quest/m2/uring-demux.md b/quest/m2/uring-demux.md index 1b4b45a65fc..f58d10f8b32 100644 --- a/quest/m2/uring-demux.md +++ b/quest/m2/uring-demux.md @@ -23,10 +23,11 @@ STUN responder class either. An ICE Binding request is WebRTC traffic and follows that class. Each worker's endpoint receives a batch and feeds every segment straight to -the QUIC endpoint. The classifier and flow table from the -[UDP demux](/quest/m2/p2p/udp-demux.md), split there into a -runtime-agnostic piece, run first on each segment; only QUIC continues into -the endpoint. The worker is thread-per-core and `!Send`, while the consumers +the QUIC endpoint. The classifier, pin table, per-source `Queue`, and +`Counters` in `moq_sock::demux` run first on each segment, as the tokio +listener's socket does inline in its receive; only QUIC continues into the +endpoint. Until this lands, `moq_relay::Relay::webrtc` refuses an io_uring +relay. The worker is thread-per-core and `!Send`, while the consumers of the other classes (`moq-rtc`, `moq-srt`) run on tokio, so non-QUIC datagrams cross to them on a `Send` channel, and their replies come back through a remote-send path into the owning worker's ring, @@ -49,7 +50,6 @@ off on the ring, from shard steering. ## Required -- [UDP demux](/quest/m2/p2p/udp-demux.md) - the classifier and flow table this runs on the ring - [WebRTC on the shared socket](/quest/m2/one-port/rtc-feed.md) - the fed RTC socket and transmit contract the ring integrates - [SRT on the shared socket](/quest/m2/one-port/srt-demux.md) - the SRT state machines fed through the shared demux From 0614b339a3002f97b536543fe5f7b000e87abe0c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 06:21:45 -0700 Subject: [PATCH 5/8] perf(sock): read the pin table without a lock, with a benchmark Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 2 ++ rs/moq-sock/Cargo.toml | 6 ++++ rs/moq-sock/benches/demux.rs | 69 ++++++++++++++++++++++++++++++++++++ rs/moq-sock/src/demux.rs | 41 ++++++++++++--------- sh/gh/nightly.sh | 4 +-- 5 files changed, 104 insertions(+), 18 deletions(-) create mode 100644 rs/moq-sock/benches/demux.rs diff --git a/Cargo.lock b/Cargo.lock index d43faae9d44..34aac31694a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5792,8 +5792,10 @@ dependencies = [ name = "moq-sock" version = "0.2.0" dependencies = [ + "arc-swap", "cfg_aliases", "core_affinity", + "criterion", "libc", "rand 0.10.3", "socket2 0.6.5", diff --git a/rs/moq-sock/Cargo.toml b/rs/moq-sock/Cargo.toml index 839c1fb9022..91dd215d631 100644 --- a/rs/moq-sock/Cargo.toml +++ b/rs/moq-sock/Cargo.toml @@ -17,6 +17,7 @@ categories = ["network-programming"] fast-apple-datapath = [] [dependencies] +arc-swap = "1.9" core_affinity = "0.8" libc = { workspace = true } socket2 = { version = "0.6", features = ["all"] } @@ -30,8 +31,13 @@ windows-sys = { version = "0.61", features = ["Win32_Foundation", "Win32_System_ cfg_aliases = "0.2" [dev-dependencies] +criterion = { workspace = true } rand = "0.10" tracing-test = "0.2" +[[bench]] +name = "demux" +harness = false + [lints] workspace = true diff --git a/rs/moq-sock/benches/demux.rs b/rs/moq-sock/benches/demux.rs new file mode 100644 index 00000000000..85d23de0a38 --- /dev/null +++ b/rs/moq-sock/benches/demux.rs @@ -0,0 +1,69 @@ +//! Routing on a shared port: what every QUIC datagram pays to be told it is QUIC. +//! +//! Swept over the pins held (WebRTC sessions) and the shards routing at once, +//! since every shard of a worker group reads the same pin table. + +#![allow( + clippy::disallowed_methods, + clippy::disallowed_types, + reason = "a benchmark times itself on the host clock" +)] + +use std::{ + hint::black_box, + net::SocketAddr, + time::{Duration, Instant}, +}; + +use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main}; +use moq_sock::demux::{Flows, Route}; + +/// Datagrams one shard routes per iteration, as one receive batch would hold. +const BATCH: usize = 64; + +fn remote(i: usize) -> SocketAddr { + SocketAddr::from(([10, (i >> 16) as u8, (i >> 8) as u8, i as u8], 4433)) +} + +fn bench_route(c: &mut Criterion) { + let mut group = c.benchmark_group("demux_route"); + let quic = [0x40u8; 1200]; + for pins in [0, 1, 1024] { + let flows = Flows::default(); + // Pinned addresses never match the senders, so every datagram stays QUIC. + let _pins: Vec<_> = (0..pins).map(|i| flows.pin(remote(1 << 20 | i))).collect(); + for shards in [1, 4] { + group.throughput(Throughput::Elements((BATCH * shards) as u64)); + group.bench_function( + BenchmarkId::new(format!("pins_{pins}"), format!("shards_{shards}")), + |b| { + b.iter_custom(|iters| { + let start = Instant::now(); + std::thread::scope(|scope| { + for shard in 0..shards { + let flows = &flows; + scope.spawn(move || { + for _ in 0..iters { + for i in 0..BATCH { + let route = flows.route(remote(shard * BATCH + i), &quic); + assert_eq!(black_box(route), Route::Quic); + } + } + }); + } + }); + start.elapsed() + }) + }, + ); + } + } + group.finish(); +} + +criterion_group! { + name = benches; + config = Criterion::default().measurement_time(Duration::from_secs(2)); + targets = bench_route +} +criterion_main!(benches); diff --git a/rs/moq-sock/src/demux.rs b/rs/moq-sock/src/demux.rs index 8b05c695c64..7c83a791b98 100644 --- a/rs/moq-sock/src/demux.rs +++ b/rs/moq-sock/src/demux.rs @@ -8,14 +8,16 @@ //! io_uring listeners run the same rules. use std::{ - collections::{HashMap, VecDeque}, + collections::{HashMap, HashSet, VecDeque}, net::SocketAddr, sync::{ Arc, Mutex, - atomic::{AtomicU64, AtomicUsize, Ordering}, + atomic::{AtomicBool, AtomicU64, Ordering}, }, }; +use arc_swap::ArcSwap; + /// What a datagram carries, judged by its first byte and, for STUN, its attributes. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Class { @@ -144,12 +146,22 @@ pub struct Flows(Arc); #[derive(Debug, Default)] struct FlowsState { - /// Skips the lock on every datagram while nothing is pinned. - pinned: AtomicUsize, - /// How many [`Pin`]s hold each address. + /// Whether anything is pinned, so an unpinned listener skips the set entirely. + any: AtomicBool, + /// The pinned addresses, read without a lock on every datagram by every shard + /// and replaced whole on the rare pin or release. + pinned: ArcSwap>, + /// How many [`Pin`]s hold each address, which only pinning and releasing touch. pins: Mutex>, } +impl FlowsState { + fn publish(&self, pins: &HashMap) { + self.pinned.store(Arc::new(pins.keys().copied().collect())); + self.any.store(!pins.is_empty(), Ordering::Release); + } +} + impl Flows { /// Route `datagram` from `remote`: a pin wins, otherwise its [`Class`] decides. pub fn route(&self, remote: SocketAddr, datagram: &[u8]) -> Route { @@ -168,8 +180,11 @@ impl Flows { pub fn pin(&self, remote: SocketAddr) -> Pin { let remote = canonical(remote); let mut pins = self.0.pins.lock().unwrap(); - *pins.entry(remote).or_default() += 1; - self.0.pinned.store(pins.len(), Ordering::Release); + let count = pins.entry(remote).or_default(); + *count += 1; + if *count == 1 { + self.0.publish(&pins); + } Pin { flows: self.clone(), remote, @@ -177,10 +192,7 @@ impl Flows { } fn is_pinned(&self, remote: SocketAddr) -> bool { - if self.0.pinned.load(Ordering::Acquire) == 0 { - return false; - } - self.0.pins.lock().unwrap().contains_key(&canonical(remote)) + self.0.any.load(Ordering::Acquire) && self.0.pinned.load().contains(&canonical(remote)) } } @@ -202,9 +214,9 @@ impl Drop for Pin { *count -= 1; if *count == 0 { pins.remove(&self.remote); + self.flows.0.publish(&pins); } } - self.flows.0.pinned.store(pins.len(), Ordering::Release); } } @@ -364,10 +376,7 @@ mod tests { assert_eq!(flows.route(addr(1), &[0x80]), Route::WebRtc); assert_eq!(flows.route(addr(1), &[0x40]), Route::Quic); assert_eq!(flows.route(addr(1), &[0xc0]), Route::Quic); - assert_eq!( - flows.route(addr(1), &binding(&[])), - Route::Discard(Discard::Stun) - ); + assert_eq!(flows.route(addr(1), &binding(&[])), Route::Discard(Discard::Stun)); assert_eq!(flows.route(addr(1), &[5]), Route::Discard(Discard::Unknown)); } diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index 876f702d46d..fc653587ca4 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -122,10 +122,10 @@ case "$1" in # The allocation/window/play-buffer tables keep their stdout in the run; # only Criterion estimates enter the trend report. criterion extra --no-fail-fast -p moq-e2ee -p moq-json -p moq-archive -p moq-cli -p moq-mux -p moq-audio \ - -p moq-quic --features moq-quic/fuzz \ + -p moq-quic -p moq-sock --features moq-quic/fuzz \ --bench protect --bench codec --bench table --bench allocations --bench window \ --bench producer --bench play_buffer --bench jitter --bench decode_clock --bench ts_programs --bench ts_video \ - --bench bus --bench parameter_sets --bench sent_packets + --bench bus --bench parameter_sets --bench sent_packets --bench demux ;; rust-uring) # One run per target makes an unsupported/skipped ring fail report From 13334904bbbebed96e1fe940f82cadecceb1f415 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 30 Oct 2026 22:37:18 -0700 Subject: [PATCH 6/8] fix(demux): deliver ICE responses, end the feed with the listener moq-ice runs str0m's full ICE, whose own connectivity checks are answered by Binding responses without USERNAME. Those were dropped as plain STUN, so ICE could never validate a pair on the shared port. Class::Check becomes Class::Ice, which also takes Binding success and error responses; only the WebRTC agent sends requests from this port. A listening socket's Divert now holds the feed's liveness producer, so a feed taken before Server::new moves its config in stays open while the listener runs, and ends once the endpoint releases its socket. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/index.md | 2 +- quest/m2/one-port/README.md | 4 ++- quest/m2/one-port/rtc-feed.md | 2 +- quest/m2/p2p/native-quic.md | 2 +- rs/moq-relay/src/relay.rs | 2 +- rs/moq-sock/README.md | 2 +- rs/moq-sock/src/demux.rs | 55 ++++++++++++++++++++++---------- rs/moq-tokio/src/quic/backend.rs | 10 ++++-- rs/moq-tokio/src/quic/demux.rs | 29 +++++++++++------ 9 files changed, 74 insertions(+), 34 deletions(-) diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 40d5bcde2c4..0987f1aba57 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -100,7 +100,7 @@ relay.with_web(web).run().await?; - To decide admissions yourself, leave `[auth]` empty and answer `relay.admissions()`; see [Authentication](/bin/relay/auth#in-process). - To serve WebRTC media (WHIP, WHEP) on the QUIC port, take `relay.webrtc()`: - ICE checks, DTLS, and RTP arrive on it, and its `send` answers from the same + ICE, DTLS, and RTP arrive on it, and its `send` answers from the same port. It fails with `runtime.io_uring`, whose workers do not split the port yet. See [docs.rs/moq-relay](https://docs.rs/moq-relay) and diff --git a/quest/m2/one-port/README.md b/quest/m2/one-port/README.md index 8b68b86613c..bd3bb0e59aa 100644 --- a/quest/m2/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -86,7 +86,9 @@ decided. Decided 2026-10-08: the public STUN responder is left to P2P (m2), its only consumer. Here, a Binding request carrying USERNAME is an ICE check -and goes to WebRTC; any other is dropped and counted. Decided 2026-10-13: +and goes to WebRTC, as does every Binding response, since the WebRTC agent +runs full ICE and only it sends requests from this port. Any other STUN is +dropped and counted. Decided 2026-10-13: the responder binds its own port ([relay STUN](/doc/bin/relay/config.md#stun)), so the shared port never answers public Binding requests. diff --git a/quest/m2/one-port/rtc-feed.md b/quest/m2/one-port/rtc-feed.md index e5aa62e487d..667799c2c00 100644 --- a/quest/m2/one-port/rtc-feed.md +++ b/quest/m2/one-port/rtc-feed.md @@ -62,7 +62,7 @@ unpin message or idle expiry in the flow table, as SRT's pins have. The demux side has landed: `moq_tokio::quic::demux::WebRtc` (from `Demux::webrtc`, or `moq_relay::Relay::webrtc` for an embedded relay) yields -ICE checks, DTLS, and RTP as `Datagram`s whose `remote` is already in +ICE checks and responses, DTLS, and RTP as `Datagram`s whose `remote` is already in `moq_ice::canonical` form, sends a `Transmit` from the shared port (mapping an IPv4 destination for an AF_INET6 socket), and pins a remote with `pin`, which returns a guard that releases the pin on drop. So the fed `Socket` takes a diff --git a/quest/m2/p2p/native-quic.md b/quest/m2/p2p/native-quic.md index 9cab1fbe6d6..7ad753f0edd 100644 --- a/quest/m2/p2p/native-quic.md +++ b/quest/m2/p2p/native-quic.md @@ -30,7 +30,7 @@ Decided with the maintainer on 2026-10-13: in SDP. Both sides pin it with the existing `tls.fingerprint` check. MoQ AUTH with a [peer grant](/quest/m2/p2p/peer-grant.md) still runs on top. - After nomination the session's socket carries ICE consent checks and - QUIC, split by `moq_sock::demux::classify`: `Check` and `Stun` go to the + QUIC, split by `moq_sock::demux::classify`: `Ice` and `Stun` go to the ICE agent and `Quic` to the endpoint. The tokio listener's `quic::demux` routes for a relay (STUN queries dropped, no ICE agent), so the session socket needs its own small policy over the same classifier. diff --git a/rs/moq-relay/src/relay.rs b/rs/moq-relay/src/relay.rs index 9290123a2b6..04d1c5d7ade 100644 --- a/rs/moq-relay/src/relay.rs +++ b/rs/moq-relay/src/relay.rs @@ -471,7 +471,7 @@ impl Relay { self.admissions.take() } - /// The WebRTC media path (ICE checks, DTLS, and RTP) arriving on the QUIC port, + /// The WebRTC media path (ICE, DTLS, and RTP) arriving on the QUIC port, /// for an embedder's WebRTC stack to serve and answer through the same port. /// /// Until a feed is taken, and once every feed is dropped, that traffic is diff --git a/rs/moq-sock/README.md b/rs/moq-sock/README.md index e3ca72f87c8..68a6b81d279 100644 --- a/rs/moq-sock/README.md +++ b/rs/moq-sock/README.md @@ -17,7 +17,7 @@ runtimes (`moq-tokio` and `moq-uring`). on the port, including other protocols, keeps the kernel's 4-tuple hash. - **`cpu`**: pinning worker threads to cores. - **`demux`**: classifying each datagram on a shared port by its first byte - (RFC 7983), so QUIC and the WebRTC media path (ICE checks, DTLS, RTP) share + (RFC 7983), so QUIC and the WebRTC media path (ICE, DTLS, RTP) share one socket, plus the pin table and per-source queue the listeners divert through. Every QUIC endpoint behind it turns QUIC-bit greasing off. - **`udp`**: sending and receiving with GSO, GRO, and ECN, a hard fork of diff --git a/rs/moq-sock/src/demux.rs b/rs/moq-sock/src/demux.rs index 7c83a791b98..0bb82b81180 100644 --- a/rs/moq-sock/src/demux.rs +++ b/rs/moq-sock/src/demux.rs @@ -23,9 +23,11 @@ use arc_swap::ArcSwap; pub enum Class { /// A QUIC packet: the fixed bit is set, in a long (192 to 255) or short (64 to 127) header. Quic, - /// A STUN Binding request carrying USERNAME: an ICE connectivity check. - Check, - /// Any other STUN message, such as a public Binding query or a response. + /// ICE: a STUN Binding request carrying USERNAME (a connectivity check), or a + /// Binding response, which answers a request only the WebRTC agent sends from + /// this port, since a full ICE agent needs its own checks answered. + Ice, + /// Any other STUN message, such as a public Binding query or an indication. Stun, /// A DTLS record (20 to 63). Dtls, @@ -38,12 +40,14 @@ pub enum Class { const STUN_HEADER: usize = 20; const STUN_COOKIE: [u8; 4] = [0x21, 0x12, 0xA4, 0x42]; const STUN_BINDING_REQUEST: [u8; 2] = [0x00, 0x01]; +const STUN_BINDING_SUCCESS: [u8; 2] = [0x01, 0x01]; +const STUN_BINDING_ERROR: [u8; 2] = [0x01, 0x11]; const STUN_USERNAME: u16 = 0x0006; /// Classify a datagram by RFC 7983's first-byte ranges. pub fn classify(datagram: &[u8]) -> Class { match datagram.first() { - Some(0..=3) if is_check(datagram) => Class::Check, + Some(0..=3) if is_ice(datagram) => Class::Ice, Some(0..=3) => Class::Stun, Some(20..=63) => Class::Dtls, Some(64..=127 | 192..=255) => Class::Quic, @@ -52,16 +56,19 @@ pub fn classify(datagram: &[u8]) -> Class { } } -/// Whether `datagram` is a well-formed STUN Binding request with a USERNAME attribute. -fn is_check(datagram: &[u8]) -> bool { +/// Whether `datagram` is a well-formed STUN Binding response, or Binding request +/// with a USERNAME attribute. +fn is_ice(datagram: &[u8]) -> bool { let Some((header, mut attributes)) = datagram.split_at_checked(STUN_HEADER) else { return false; }; - if header[0..2] != STUN_BINDING_REQUEST || header[4..8] != STUN_COOKIE { + if header[4..8] != STUN_COOKIE || usize::from(u16::from_be_bytes([header[2], header[3]])) != attributes.len() { return false; } - if usize::from(u16::from_be_bytes([header[2], header[3]])) != attributes.len() { - return false; + match [header[0], header[1]] { + STUN_BINDING_SUCCESS | STUN_BINDING_ERROR => return true, + STUN_BINDING_REQUEST => {} + _ => return false, } while let Some((attribute, rest)) = attributes.split_at_checked(4) { @@ -84,7 +91,7 @@ fn is_check(datagram: &[u8]) -> bool { pub enum Route { /// The QUIC endpoint. Quic, - /// The WebRTC media path: ICE checks, DTLS, and RTP. + /// The WebRTC media path: ICE, DTLS, and RTP. WebRtc, /// Nowhere; counted under this reason. Discard(Discard), @@ -93,7 +100,7 @@ pub enum Route { /// Why a datagram was dropped instead of delivered. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Discard { - /// STUN that is not an ICE check, such as a public Binding query; the public + /// STUN that is not ICE, such as a public Binding query; the public /// responder binds its own port. Stun, /// Nothing this socket serves. @@ -170,7 +177,7 @@ impl Flows { } match classify(datagram) { Class::Quic => Route::Quic, - Class::Check | Class::Dtls | Class::Rtp => Route::WebRtc, + Class::Ice | Class::Dtls | Class::Rtp => Route::WebRtc, Class::Stun => Route::Discard(Discard::Stun), Class::Unknown => Route::Discard(Discard::Unknown), } @@ -293,6 +300,11 @@ mod tests { /// A Binding request: header, then the given attributes. fn binding(attributes: &[(u16, &[u8])]) -> Vec { + stun(STUN_BINDING_REQUEST, attributes) + } + + /// A STUN message of `kind`: header, then the given attributes. + fn stun(kind: [u8; 2], attributes: &[(u16, &[u8])]) -> Vec { let mut body = Vec::new(); for (kind, value) in attributes { body.extend_from_slice(&kind.to_be_bytes()); @@ -301,7 +313,7 @@ mod tests { body.resize(body.len().next_multiple_of(4), 0); } let mut out = Vec::new(); - out.extend_from_slice(&STUN_BINDING_REQUEST); + out.extend_from_slice(&kind); out.extend_from_slice(&(body.len() as u16).to_be_bytes()); out.extend_from_slice(&STUN_COOKIE); out.extend_from_slice(&[7; 12]); @@ -310,6 +322,7 @@ mod tests { } const PRIORITY: u16 = 0x0024; + const XOR_MAPPED_ADDRESS: u16 = 0x0020; fn addr(port: u16) -> SocketAddr { SocketAddr::from(([192, 0, 2, 1], port)) @@ -319,8 +332,15 @@ mod tests { fn first_byte_classes() { let check = binding(&[(PRIORITY, &[0, 0, 0, 1]), (STUN_USERNAME, b"abc:def")]); let cases: &[(&[u8], Class)] = &[ - (&check, Class::Check), + (&check, Class::Ice), + ( + &stun(STUN_BINDING_SUCCESS, &[(XOR_MAPPED_ADDRESS, &[0; 8])]), + Class::Ice, + ), + (&stun(STUN_BINDING_ERROR, &[]), Class::Ice), (&binding(&[(PRIORITY, &[0, 0, 0, 1])]), Class::Stun), + // A Binding indication, which no ICE agent here waits on. + (&stun([0x00, 0x11], &[]), Class::Stun), (&[0x01, 0x01, 0, 0], Class::Stun), (&[3], Class::Stun), (&[4], Class::Unknown), @@ -350,9 +370,9 @@ mod tests { cookie[4] ^= 1; assert_eq!(classify(&cookie), Class::Stun); - // A Binding success response carrying USERNAME is still not a check. - let mut response = check.clone(); - response[0..2].copy_from_slice(&[0x01, 0x01]); + // A response is held to the same framing as a check. + let mut response = stun(STUN_BINDING_SUCCESS, &[(XOR_MAPPED_ADDRESS, &[0; 8])]); + response.push(0); assert_eq!(classify(&response), Class::Stun); // The header's length must cover the attributes exactly. @@ -372,6 +392,7 @@ mod tests { let flows = Flows::default(); let check = binding(&[(STUN_USERNAME, b"abc:def")]); assert_eq!(flows.route(addr(1), &check), Route::WebRtc); + assert_eq!(flows.route(addr(1), &stun(STUN_BINDING_SUCCESS, &[])), Route::WebRtc); assert_eq!(flows.route(addr(1), &[0x16]), Route::WebRtc); assert_eq!(flows.route(addr(1), &[0x80]), Route::WebRtc); assert_eq!(flows.route(addr(1), &[0x40]), Route::Quic); diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index b6949ebb7b2..15a358f12e1 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -909,10 +909,12 @@ mod tests { /// QUIC and the WebRTC media path share the listening port: a QUIC session /// connects while a WebRTC peer's ICE check, DTLS, and RTP reach the feed and /// its reply leaves from the same port, and a public STUN query is dropped. + /// The feed lives as long as the listener, without a clone of its demux kept. #[tokio::test] async fn one_port_serves_quic_and_webrtc() { let demux = crate::quic::demux::Demux::default(); let feed = demux.webrtc(); + let counters = demux.counters().clone(); let quic = crate::quic::Config::default(); let config = listen::Config { bind: Some("[::]:0".parse().unwrap()), @@ -928,7 +930,7 @@ mod tests { quic: quic.clone(), member: None, tls, - demux: demux.clone(), + demux, }) .expect("server init"); let port = server.local_addr().port(); @@ -995,7 +997,11 @@ mod tests { assert_eq!(received, sent.map(<[u8]>::to_vec)); assert_eq!(reply, b"reply"); assert_eq!(from, port); - assert_eq!(demux.counters().get(crate::quic::demux::Discard::Stun), 1); + assert_eq!(counters.get(crate::quic::demux::Discard::Stun), 1); + + server.shutdown().await; + let end = tokio::time::timeout(Duration::from_secs(5), feed.recv()).await; + assert!(end.expect("the feed outlived the listener").is_none()); } async fn pinned_connection(bind: &str, host_name: Option<&str>) { diff --git a/rs/moq-tokio/src/quic/demux.rs b/rs/moq-tokio/src/quic/demux.rs index fab9f53b1dd..7b4c4939c35 100644 --- a/rs/moq-tokio/src/quic/demux.rs +++ b/rs/moq-tokio/src/quic/demux.rs @@ -1,7 +1,7 @@ //! One UDP port shared by QUIC and the WebRTC media path. //! //! A QUIC listener's socket classifies every datagram it reads with -//! [`moq_sock::demux`]: QUIC stays on the endpoint, and ICE checks, DTLS, and RTP +//! [`moq_sock::demux`]: QUIC stays on the endpoint, and ICE, DTLS, and RTP //! are diverted to a [`WebRtc`] feed that an embedder hands to its WebRTC stack. //! Anything else is dropped and counted. The split runs inline in the endpoint's //! receive, so a QUIC datagram is never copied or handed across tasks. @@ -39,7 +39,8 @@ const CAPACITY: usize = 4 << 20; /// [`server::Config::demux`](crate::server::Config::demux) and keep a clone. #[derive(Clone, Debug, Default)] pub struct Demux { - /// Liveness: a [`WebRtc`] consumes it, and closes when every clone is gone. + /// Liveness: a [`WebRtc`] consumes it, and closes once every clone and every + /// listening socket's [`Divert`] is gone. live: kio::Producer<()>, shared: Arc, /// The listening sockets a [`WebRtc`] answers through. @@ -85,10 +86,12 @@ impl Demux { } } - /// The receive half a listening socket runs, which never keeps the feed open. + /// The receive half a listening socket runs, which keeps the feed open until the + /// endpoint releases the socket, so the feed ends with the listener even when no + /// clone of this is kept. pub(crate) fn divert(&self) -> Divert { Divert { - live: self.live.weak(), + live: self.live.clone(), shared: self.shared.clone(), } } @@ -132,7 +135,7 @@ pub struct Datagram { pub data: Bytes, } -/// The WebRTC media path of a [`Demux`]: ICE checks, DTLS, and RTP from its +/// The WebRTC media path of a [`Demux`]: ICE, DTLS, and RTP from its /// socket, and a way to answer through it. /// /// Diverting runs while any feed is alive; drop it to stop. @@ -144,7 +147,8 @@ pub struct WebRtc { } impl WebRtc { - /// Poll for the next datagram; `None` once every [`Demux`] clone is gone. + /// Poll for the next datagram; `None` once every [`Demux`] clone is gone and + /// every listening socket it split is released. pub fn poll_recv(&self, waiter: &kio::Waiter) -> Poll> { if let Poll::Ready(mut queue) = self.shared.queue.poll(waiter, |queue| match queue.is_empty() { true => Poll::Pending, @@ -159,7 +163,8 @@ impl WebRtc { } } - /// Receive the next datagram; `None` once every [`Demux`] clone is gone. + /// Receive the next datagram; `None` once the listener and every [`Demux`] + /// clone are gone; see [`Self::poll_recv`]. pub async fn recv(&self) -> Option { kio::wait(|waiter| self.poll_recv(waiter)).await } @@ -245,7 +250,7 @@ impl AsyncUdpSocket for Split { /// The receive half of a [`Demux`], run by each listening socket. #[derive(Clone, Debug)] pub(crate) struct Divert { - live: kio::ProducerWeak<()>, + live: kio::Producer<()>, shared: Arc, } @@ -472,9 +477,15 @@ mod tests { split(&divert, &[(remote(1), &[&[0x80, 0]])]); drop(demux); - // What was queued still arrives, then the end. + // The listening socket still diverts, so the feed stays open. let waiter = kio::Waiter::noop(); assert!(matches!(feed.poll_recv(&waiter), Poll::Ready(Some(_)))); + assert!(feed.poll_recv(&waiter).is_pending()); + + // What was queued still arrives, then the end. + split(&divert, &[(remote(1), &[&[0x80, 0]])]); + drop(divert); + assert!(matches!(feed.poll_recv(&waiter), Poll::Ready(Some(_)))); assert!(matches!(feed.poll_recv(&waiter), Poll::Ready(None))); } } From 05f83654dc8b7ca70deacdce362d3211775cb5f8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:41:27 -0800 Subject: [PATCH 7/8] fix(demux): mark the classifier enums non_exhaustive, and document reply sources `Class`, `Route`, and `Discard` gain variants with the SRT demux, so they are `#[non_exhaustive]`; the tokio split counts a route it does not serve as `unknown`. `WebRtc::poll_send` and the relay guide say to set `src_ip` from `Datagram::local` on a multihomed wildcard bind, and the guide names the stream-only relay as a case `relay.webrtc()` refuses. The tests use the ambient-clock `kio::clock::timeout`, which main's clippy config now requires. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/index.md | 6 +++++- rs/moq-relay/tests/integration/embed.rs | 4 ++-- rs/moq-sock/src/demux.rs | 3 +++ rs/moq-tokio/src/quic/backend.rs | 4 ++-- rs/moq-tokio/src/quic/demux.rs | 6 ++++++ 5 files changed, 18 insertions(+), 5 deletions(-) diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 730fe6f7d86..624ea816578 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -101,7 +101,11 @@ relay.with_web(web).run().await?; `relay.admissions()`; see [Authentication](/bin/relay/auth#in-process). - To serve WebRTC media (WHIP, WHEP) on the QUIC port, take `relay.webrtc()`: ICE, DTLS, and RTP arrive on it, and its `send` answers from the same - port. It fails with `runtime.io_uring`, whose workers do not split the port yet. + port. On a wildcard bind with several local addresses, set the reply's + `Transmit.src_ip` to the `Datagram.local` it answers; left `None`, the kernel + picks the source address, which the peer may not accept. It fails unless the + tokio runtime serves QUIC: on a stream-only relay, and with `runtime.io_uring`, + whose workers do not split the port yet. - To serve RTMP on the web ports, take `relay.rtmp()` and pass each accepted stream to `moq_rtmp::accept_stream`. The HTTP and HTTPS listeners hand it plaintext RTMP, and RTMPS (TLS with no ALPN) already decrypted; untaken, the diff --git a/rs/moq-relay/tests/integration/embed.rs b/rs/moq-relay/tests/integration/embed.rs index dedcc3b15b2..6d0b7d74db5 100644 --- a/rs/moq-relay/tests/integration/embed.rs +++ b/rs/moq-relay/tests/integration/embed.rs @@ -444,7 +444,7 @@ async fn webrtc_feed(mut config: Config) { peers.push(peer); } let mut seen = std::collections::HashSet::new(); - tokio::time::timeout(TIMEOUT, async { + kio::clock::timeout(TIMEOUT, async { while seen.len() < peers.len() { let datagram = feed.recv().await.expect("feed open"); assert_eq!(datagram.data[..3], [0x16, 0xfe, 0xfd]); @@ -465,7 +465,7 @@ async fn webrtc_feed(mut config: Config) { .await .expect("send reply"); let mut buf = [0; 16]; - let (len, from) = tokio::time::timeout(TIMEOUT, peer.recv_from(&mut buf)) + let (len, from) = kio::clock::timeout(TIMEOUT, peer.recv_from(&mut buf)) .await .expect("reply arrived") .expect("recv reply"); diff --git a/rs/moq-sock/src/demux.rs b/rs/moq-sock/src/demux.rs index 0bb82b81180..37617b4c9cb 100644 --- a/rs/moq-sock/src/demux.rs +++ b/rs/moq-sock/src/demux.rs @@ -20,6 +20,7 @@ use arc_swap::ArcSwap; /// What a datagram carries, judged by its first byte and, for STUN, its attributes. #[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] pub enum Class { /// A QUIC packet: the fixed bit is set, in a long (192 to 255) or short (64 to 127) header. Quic, @@ -88,6 +89,7 @@ fn is_ice(datagram: &[u8]) -> bool { /// Where a datagram goes. #[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] pub enum Route { /// The QUIC endpoint. Quic, @@ -99,6 +101,7 @@ pub enum Route { /// Why a datagram was dropped instead of delivered. #[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] pub enum Discard { /// STUN that is not ICE, such as a public Binding query; the public /// responder binds its own port. diff --git a/rs/moq-tokio/src/quic/backend.rs b/rs/moq-tokio/src/quic/backend.rs index 1fa19933469..7a338e03c85 100644 --- a/rs/moq-tokio/src/quic/backend.rs +++ b/rs/moq-tokio/src/quic/backend.rs @@ -984,7 +984,7 @@ mod tests { let (len, from) = peer.recv_from(&mut buf).await.unwrap(); (received, buf[..len].to_vec(), from.port()) }; - let (session, received) = tokio::time::timeout(Duration::from_secs(5), async { + let (session, received) = kio::clock::timeout(Duration::from_secs(5), async { let (session, received) = tokio::join!(async { tokio::try_join!(dial, accept) }, webrtc); (session, received) }) @@ -999,7 +999,7 @@ mod tests { assert_eq!(counters.get(crate::quic::demux::Discard::Stun), 1); server.shutdown().await; - let end = tokio::time::timeout(Duration::from_secs(5), feed.recv()).await; + let end = kio::clock::timeout(Duration::from_secs(5), feed.recv()).await; assert!(end.expect("the feed outlived the listener").is_none()); } diff --git a/rs/moq-tokio/src/quic/demux.rs b/rs/moq-tokio/src/quic/demux.rs index 17ed837dd3b..fc2af50649a 100644 --- a/rs/moq-tokio/src/quic/demux.rs +++ b/rs/moq-tokio/src/quic/demux.rs @@ -171,6 +171,10 @@ impl WebRtc { /// Poll to send `transmit` from the shared port, with GSO and ECN as it asks. /// + /// Its `src_ip` is kept as given. On a wildcard bind with several local + /// addresses, set it to the [`Datagram::local`] being answered; `None` lets the + /// kernel pick the source address, which the peer may not accept. + /// /// A datagram sent once the listener has released its socket is lost, as UDP /// allows. Errors are those of the endpoint's own sends: an unreachable destination /// comes back, as [`AsyncUdpSocket::try_send`] describes, and anything else is logged. @@ -295,6 +299,8 @@ impl Divert { } Route::WebRtc => self.push(meta, &buf[start..end]), Route::Discard(reason) => self.shared.counters.discard(reason), + // A stack this listener does not serve yet. + _ => self.shared.counters.discard(Discard::Unknown), } start = end; } From ec4fc0ec905a1b2cbc02d14fc32bda881539490d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:45:42 -0800 Subject: [PATCH 8/8] chore(moq-sock): sort Cargo.toml sections An earlier merge left the Apple dev-dependencies after the bench table. Co-Authored-By: Claude Opus 5.5 --- rs/moq-sock/Cargo.toml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rs/moq-sock/Cargo.toml b/rs/moq-sock/Cargo.toml index 15736a556ea..7c01e824ef4 100644 --- a/rs/moq-sock/Cargo.toml +++ b/rs/moq-sock/Cargo.toml @@ -35,12 +35,12 @@ criterion = { package = "bench-harness", path = "../bench-harness" } rand = "0.10" tracing-test = "0.2" +[target.'cfg(target_vendor = "apple")'.dev-dependencies] +nix = { workspace = true } + [[bench]] name = "demux" harness = false -[target.'cfg(target_vendor = "apple")'.dev-dependencies] -nix = { workspace = true } - [lints] workspace = true