From c9f77c589f19d921bf7a9112c20f165f0f874aba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 00:53:41 -0700 Subject: [PATCH 1/4] chore(quest): claim ts-mp2-join-hole Co-Authored-By: Claude Opus 5.5 From 7fa439a0cbe50f70af7d7332966bf02a13a9978d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 01:41:08 -0700 Subject: [PATCH 2/4] fix(mux): start a live export at the publisher's largest group A live export latched onto the newest group announced when its first frame arrived. Behind a backlog, the budget serves groups oldest first, so the backlog's oldest group can land alone: the export read it, then skipped the groups after it once the next PES moved the live edge a budget past them. That is TS validation's MP2 hole: one frame, then 96 ms missing. The latch now takes the publisher's largest (SUBSCRIBE_START on lite-07) when it names a group past what has arrived. A relay answered with only the newest group it held, which right after its upstream subscribed can be that same oldest group, so a lite-07 relay's SUBSCRIBE_START now forwards its source's largest. Co-Authored-By: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 2 +- quest/m1/test-flakes-2/README.md | 1 - quest/m1/test-flakes-2/ts-mp2-join-hole.md | 52 ------- quest/m2/audio-join-budget.md | 9 +- rs/moq-mux/src/container/consumer.rs | 30 ++-- rs/moq-mux/src/container/source.rs | 126 ++++++++++----- rs/moq-mux/src/container/test_util.rs | 173 +++++++++++++++++++++ rs/moq-net/src/lite/publisher.rs | 36 ++++- rs/moq-net/src/model/track.rs | 15 ++ 9 files changed, 337 insertions(+), 107 deletions(-) delete mode 100644 quest/m1/test-flakes-2/ts-mp2-join-hole.md diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 4320d28fdd8..08cbea9d463 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1308,7 +1308,7 @@ The second case is easy to get wrong, so to be explicit: a subscriber that reque The frame offset belonged to group 5 and is gone along with the rest of it; it does not carry forward to whichever group the publisher resolved to. **Largest Group** and **Largest Frame**: -The largest position the publisher has for the track when it answers: the last frame that exists, like moq-transport's Largest Location. +The largest position the publisher knows of for the track when it answers: the last frame that exists, like moq-transport's Largest Location, including one a relay's source reported that has yet to arrive. `Largest Group` is the group sequence plus one, and 0 means the track has nothing yet, in which case `Largest Frame` is absent. A subscriber takes it as where the live feed is: a relay holding groups from an earlier subscription serves them from cache only once this says they are current, which a publisher answering promptly lets it do without waiting for a frame. diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md index a6ae9e970c3..e5cf41e23ca 100644 --- a/quest/m1/test-flakes-2/README.md +++ b/quest/m1/test-flakes-2/README.md @@ -35,7 +35,6 @@ Public API: none. Wire: none. ## Required -- [TS MP2 join hole](/quest/m1/test-flakes-2/ts-mp2-join-hole.md) - the TS export skips no MPEG-1 audio group right after its live join, fixed at the cause - [Auth refresh mocks time](/quest/m1/test-flakes-2/auth-refresh-mock-time.md) - moq-relay's auth refresh and fixed-lease tests measure a grant's life on one mocked clock - [Relay burst drill](/quest/m1/test-flakes-2/relay-burst-impaired.md) - the impaired transport-peer burst drill never aborts its subscription while the link is up - [BBR marking seed](/quest/m1/test-flakes-2/bbr-marking-seed.md) - the BBR marking test seeds its probe schedule, replays a failing seed, and its rare drop is fixed at the cause diff --git a/quest/m1/test-flakes-2/ts-mp2-join-hole.md b/quest/m1/test-flakes-2/ts-mp2-join-hole.md deleted file mode 100644 index f12983dea00..00000000000 --- a/quest/m1/test-flakes-2/ts-mp2-join-hole.md +++ /dev/null @@ -1,52 +0,0 @@ -# [M] TS export loses no MP2 group after its live join - -## Goal - -TS validation's "TS full multiplex at its own rate" step (`just test ts --full`) passes -reliably because the exporter never skips an MPEG-1 audio group right after it joins. -The fix lands at the cause, with a deterministic regression test that fails without it. - -## Plan - -Seen 2026-10-17 on #5857's TS validation run 39042472016 (head 754a5af, `main` with -#5854 plus a test-only change). PID 0x101 lost 96 ms in one 120 ms step at 2.390 s, -right after the capture's first MP2 frame. The exporter logged it itself, so this is -real loss, not one of the ffprobe ghost holes #5854 fixed in `holes.py`: -`media skipped upstream ... track="2.mp2" at=2.389977s skipped=120ms`. - -Evidence kept from that run's `ts-failure` artifact, which expires about 2026-10-24 -and holds only INFO logs, not the consumer's decisions: - -- Publisher instance up at 15:04:31.10. The subscriber subscribed to `2.mp2` at - 15:04:33.082 with `max_delay: 450ms`, `start_group: None`, `order: Descending`. The - relay forwarded the same upstream at 15:04:33.083. -- The skip was logged at 15:04:33.143, about 60 ms after subscribing. The capture's - first MP2 frame is at 2.366 s against a source starting at 1.070 s. Video starts at - 2.080 s, AC-3 at 2.515 s, both without holes. -- MP2 is published as one group per 24 ms frame, about five per PES, so the 120 ms - step is about one PES. - -What #5854 already rules out: the zero-budget race it fixed (reproduced by -`a_live_start_loses_no_group_the_publisher_bursts`), since this SUBSCRIBE carried the -real budget. What it doesn't rule out: the consumer measures `max_delay` in media time -(`max_timestamp - next_start`), not wall time, so 60 ms after subscribing is no bound. -The publisher had run about two seconds before the join, so its cache could hand the -budget a backlog spanning that much media time even though the relay held none. - -Suspicion, unverified: #5854's live latch (`container::Consumer::live`) starts at the -newest group *announced* when any frame first arrives, and drops what lies below it. -A group's announcement and its frames race on separate streams, and the backlog -arrives beside the live groups. So the latch, or the budget's skip rules right after -it, may misjudge a burst that is still in flight. - -First step: reproduce it deterministically over `moq_net::transport::memory`, the way -#5857's test does. Use a publisher holding a backlog when the live export joins, then -bursting a PES of one-frame groups. Trace which skip or latch rule declares the gap -before choosing a fix. - -Public API: none expected. Wire: none expected. - -## Related - -- [Audio join budget](/quest/m2/audio-join-budget.md) - moq-audio's live join may share the same race; whichever lands first should check the other -- [TS fidelity and recovery](/quest/m1/ts-reliability/README.md) - loss after a late join is part of the TS contract diff --git a/quest/m2/audio-join-budget.md b/quest/m2/audio-join-budget.md index 907d5d394a0..138ea1f84f7 100644 --- a/quest/m2/audio-join-budget.md +++ b/quest/m2/audio-join-budget.md @@ -18,8 +18,7 @@ session. Reproduce it the same way first: a publisher bursting one-frame groups over `moq_net::transport::memory` before the update lands. If it holds, subscribe with the full budget from the start and keep the warmup reach local, as the export now picks its live -edge in the consumer instead of on the wire. - -## Related - -- [TS MP2 join hole](/quest/m1/test-flakes-2/ts-mp2-join-hole.md) - the TS export still loses MP2 groups after its live join; it may share this race +edge in the consumer instead of on the wire. The export anchors that edge on the +publisher's largest (`track::Subscriber::poll_largest`), which a relay now forwards from +its source; `moq_mux::container::test_util::Link::held` delivers one group stream ahead of +the rest, the way the export's join test does. diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index fe26ab0ec30..d06db19fe1f 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -87,7 +87,7 @@ pub struct Consumer { // subscription names no start. Cleared once a first group is chosen. startup: bool, - // Latch onto the newest group to arrive instead, discarding what arrived below it. + // Latch onto the newest group instead, discarding what arrived below it. newest: bool, // How far we may drift from the live edge before skipping a group. @@ -193,9 +193,10 @@ impl Consumer { } } - /// Start at the newest group to arrive, the live edge, rather than the floor or the oldest - /// group the publisher serves. The subscription keeps its budget, so every group after the - /// start arrives as it would for any reader; what arrived below the start is discarded. + /// Start at the newest group, the live edge, rather than the floor or the oldest group the + /// publisher serves: the publisher's largest when it reports one past what has arrived. The + /// subscription keeps its budget, so every group after the start arrives as it would for any + /// reader; what arrived below the start is discarded. pub(crate) fn live(mut self) -> Self { self.startup = true; self.newest = true; @@ -299,14 +300,21 @@ impl Consumer { !group.empty }); if any_frame { - // A live reader takes the newest group announced so far, though its frames may - // still be on their way, and discards the older ones the budget also delivers. + // A live reader takes the newest group, though its frames may still be on their + // way, and discards the older ones the budget also delivers. The publisher's + // largest names it before its stream lands: the backlog's oldest group can arrive + // first, and starting there loses the groups after it once the live edge moves a + // budget past them. let start = match self.newest { - true => self.pending.back(), - false => self.pending.front(), - } - .expect("a group has a frame") - .sequence; + true => { + let mut start = self.pending.back().expect("a group has a frame").sequence; + while let Poll::Ready(Some(largest)) = self.track.poll_largest(waiter) { + start = start.max(largest.group); + } + start + } + false => self.pending.front().expect("a group has a frame").sequence, + }; // Nothing has been read, so discarding what lies below the start is no gap. self.pending.retain(|group| group.sequence >= start); self.current = start; diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 9bef78df461..0f57a1dd450 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -251,10 +251,10 @@ impl ExportSource { }) } - /// Start at the newest group to arrive, the live edge, rather than the oldest one the max - /// delay still reaches. The subscription carries the max delay from the start: under a zero - /// budget every hop drops each group a newer one supersedes, and raising it later cannot - /// recover the groups that follow the edge. + /// Start at the newest group, the live edge, rather than the oldest one the max delay still + /// reaches. The subscription carries the max delay from the start: under a zero budget every + /// hop drops each group a newer one supersedes, and raising it later cannot recover the + /// groups that follow the edge. pub fn live(mut self) -> Self { self.live = true; self @@ -716,39 +716,10 @@ mod tests { use std::time::Duration; use crate::container::Container as _; - use crate::container::test_util::raw_frame; - use moq_net::transport::memory; + use crate::container::test_util::{Link, origin, raw_frame}; - let origin = |hop| { - let config = moq_net::origin::Config::new(moq_net::Hop::new(hop).unwrap()); - let (producer, driver) = moq_net::origin::Producer::new(config); - tokio::spawn(moq_net::time::run(driver)); - producer - }; let (publisher, subscriber) = (origin(1), origin(2)); - let version: moq_net::Version = "moq-lite-07-wip".parse().unwrap(); - let mut config = memory::Config::default(); - config.protocol = Some(version.alpn().to_string()); - let (client_transport, server_transport) = memory::pair(config); - let client = moq_net::Client::new() - .with_versions(version.into()) - .with_publisher(publisher.consume()); - let server = moq_net::Server::new() - .with_versions(version.into()) - .with_subscriber(subscriber.clone()); - // Each driver runs as soon as its handshake resolves: the accept waits on the client's SETUP. - let _sessions = tokio::join!( - async { - let (session, driver) = client.connect(moq_net::time::now(), client_transport).await.unwrap(); - tokio::spawn(moq_net::time::run(driver)); - session - }, - async { - let (session, driver) = server.accept(moq_net::time::now(), server_transport).await.unwrap(); - tokio::spawn(moq_net::time::run(driver)); - session - } - ); + let _link = Link::new(&publisher, &subscriber).await; let broadcast = publisher.create_broadcast("room").unwrap(); let track = broadcast @@ -804,6 +775,91 @@ mod tests { assert_eq!(export.skips(), 0); } + /// A live start begins at the publisher's newest group, even when an older group of the + /// backlog the budget serves arrives first. Starting at that older group reads it, then + /// skips the groups after it once the next PES moves the live edge a budget past them: a + /// gap right after the first frame. Behind a relay holding only that first group, the + /// relay passes on the newest group its source named. + #[tokio::test(start_paused = true)] + async fn a_live_start_behind_a_backlog_starts_at_the_newest_group() { + use std::time::Duration; + + use crate::container::Container as _; + use crate::container::test_util::{Link, origin, raw_frame}; + + for relay in [false, true] { + let (publisher, subscriber) = (origin(1), origin(3)); + // SETUP takes the first uni stream; the second is the backlog's oldest group. + let (held, _downstream) = match relay { + true => { + let middle = origin(2); + let held = Link::held(&publisher, &middle, 2).await; + (held, Some(Link::new(&middle, &subscriber).await)) + } + false => (Link::held(&publisher, &subscriber, 2).await, None), + }; + + let broadcast = publisher.create_broadcast("room").unwrap(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + let consumer = subscriber.consume(); + consumer.routed("room").await.unwrap(); + let remote = consumer.request_broadcast("room", None).await.unwrap(); + let source = crate::Source::new(consumer, remote); + + // MPEG-1 audio from TS: one 24 ms frame per group, a PES of five written at once. + let wire = HangContainer::Legacy(crate::container::Kind::Audio); + let pes = |pes: u64| { + for sequence in pes * 5..pes * 5 + 5 { + let mut group = track.create_group(moq_net::group::Info { sequence }).unwrap(); + wire.write(&mut group, &[raw_frame(sequence * 24_000, b"audio", true)]) + .unwrap(); + group.finish().unwrap(); + } + }; + // About two seconds of it, so the budget's backlog reaches back about 450 ms. + for n in 0..17 { + pes(n); + tokio::time::sleep(Duration::from_millis(120)).await; + } + + let mut export = ExportSource::for_audio(&source, "audio", &audio(None), Duration::from_millis(450)) + .unwrap() + .unwrap() + .live(); + let mut read = async || { + tokio::time::timeout(Duration::from_millis(100), kio::wait(|waiter| export.poll_read(waiter))) + .await + .ok() + .map(|frame| frame.unwrap().map(|frame| frame.timestamp.as_micros())) + }; + let mut timestamps = Vec::new(); + // Only the backlog's oldest group has landed. + if let Some(Some(timestamp)) = read().await { + timestamps.push(timestamp); + } + // The next PES moves the live edge on before the rest of the backlog lands. + pes(17); + tokio::time::sleep(Duration::from_millis(120)).await; + pes(18); + held.open(); + while let Some(Some(timestamp)) = read().await { + timestamps.push(timestamp); + } + track.finish().unwrap(); + while let Some(Some(timestamp)) = read().await { + timestamps.push(timestamp); + } + + // Group 84 was the newest when the export joined. + let expected: Vec = (84..95).map(|sequence| sequence * 24_000).collect(); + assert_eq!(timestamps, expected, "relay: {relay}"); + assert_eq!(export.skips(), 0, "relay: {relay}"); + } + } + async fn audio_export() -> (moq_net::track::Producer, ExportSource) { use std::time::Duration; let live = Live::audio(audio(None)); diff --git a/rs/moq-mux/src/container/test_util.rs b/rs/moq-mux/src/container/test_util.rs index 9c65a3995eb..b69610165dc 100644 --- a/rs/moq-mux/src/container/test_util.rs +++ b/rs/moq-mux/src/container/test_util.rs @@ -213,3 +213,176 @@ pub(crate) fn common_offset( } offset.expect("frames were published") } + +/// An origin at `hop`, its driver spawned. +pub(crate) fn origin(hop: u64) -> moq_net::origin::Producer { + let config = moq_net::origin::Config::new(moq_net::Hop::new(hop).unwrap()); + let (producer, driver) = moq_net::origin::Producer::new(config); + tokio::spawn(moq_net::time::run(driver)); + producer +} + +/// A lite-07 session over memory carrying `from`'s broadcasts into `to`, open while held. +pub(crate) struct Link { + _sessions: (moq_net::Session, moq_net::Session), + gate: Gate, +} + +impl Link { + /// Link `from` into `to`, which accepts every stream. + pub(crate) async fn new(from: &moq_net::origin::Producer, to: &moq_net::origin::Producer) -> Self { + Self::held(from, to, usize::MAX).await + } + + /// Link `from` into `to`, which accepts only its first `uni` uni streams until + /// [`open`](Self::open), as a network can deliver one group stream well ahead of the + /// rest. SETUP takes the first. + pub(crate) async fn held(from: &moq_net::origin::Producer, to: &moq_net::origin::Producer, uni: usize) -> Self { + use moq_net::transport::memory; + + let version: moq_net::Version = "moq-lite-07-wip".parse().unwrap(); + let mut config = memory::Config::default(); + config.protocol = Some(version.alpn().to_string()); + let (client_transport, server_transport) = memory::pair(config); + let gate = Gate(std::sync::Arc::new(std::sync::Mutex::new((uni, None)))); + let server_transport = Gated { + inner: server_transport, + gate: gate.clone(), + }; + let client = moq_net::Client::new() + .with_versions(version.into()) + .with_publisher(from.consume()); + let server = moq_net::Server::new() + .with_versions(version.into()) + .with_subscriber(to.clone()); + // Each driver runs as soon as its handshake resolves: the accept waits on the client's SETUP. + let sessions = tokio::join!( + async { + let (session, driver) = client + .connect_lite(moq_net::time::now(), client_transport) + .await + .unwrap(); + tokio::spawn(moq_net::time::run(driver)); + session + }, + async { + let (session, driver) = server + .accept_lite(moq_net::time::now(), server_transport) + .await + .unwrap(); + tokio::spawn(moq_net::time::run(driver)); + session + } + ); + Self { + _sessions: sessions, + gate, + } + } + + /// Accept every stream from now on, the held ones first. + pub(crate) fn open(&self) { + let mut gate = self.gate.0.lock().unwrap(); + gate.0 = usize::MAX; + if let Some(waker) = gate.1.take() { + waker.wake(); + } + } +} + +/// The uni streams a [`Gated`] session may still accept, and its accept's waker. +#[derive(Clone)] +struct Gate(std::sync::Arc)>>); + +/// A memory session that accepts uni streams only while its [`Gate`] allows. +#[derive(Clone)] +struct Gated { + inner: moq_net::transport::memory::Session, + gate: Gate, +} + +impl moq_net::transport::poll::Session for Gated { + type SendStream = ::SendStream; + type RecvStream = ::RecvStream; + type Error = ::Error; + + fn poll_accept_uni( + &mut self, + cx: &mut std::task::Context<'_>, + ) -> std::task::Poll> { + { + let mut gate = self.gate.0.lock().unwrap(); + if gate.0 == 0 { + gate.1 = Some(cx.waker().clone()); + return std::task::Poll::Pending; + } + } + let accepted = std::task::ready!(self.inner.poll_accept_uni(cx)); + let mut gate = self.gate.0.lock().unwrap(); + gate.0 = gate.0.saturating_sub(1); + std::task::Poll::Ready(accepted) + } + + fn poll_accept_bi( + &mut self, + cx: &mut std::task::Context<'_>, + ) -> std::task::Poll, Self::Error>> { + self.inner.poll_accept_bi(cx) + } + + fn poll_open_uni( + &mut self, + cx: &mut std::task::Context<'_>, + options: moq_net::transport::poll::SendOptions<'_, moq_net::transport::poll::Ungrouped>, + ) -> std::task::Poll> { + self.inner.poll_open_uni(cx, options) + } + + fn poll_open_bi( + &mut self, + cx: &mut std::task::Context<'_>, + options: moq_net::transport::poll::SendOptions<'_, moq_net::transport::poll::Ungrouped>, + ) -> std::task::Poll, Self::Error>> { + self.inner.poll_open_bi(cx, options) + } + + fn send_group(&mut self, priority: i64) -> Option { + self.inner.send_group(priority) + } + + fn send_datagram( + &mut self, + payload: Bytes, + options: moq_net::transport::poll::SendOptions<'_, moq_net::transport::poll::Ungrouped>, + ) -> Result<(), Self::Error> { + self.inner.send_datagram(payload, options) + } + + fn poll_recv_datagram(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll> { + self.inner.poll_recv_datagram(cx) + } + + fn max_datagram_size(&self) -> usize { + self.inner.max_datagram_size() + } + + fn protocol(&self) -> Option<&str> { + self.inner.protocol() + } + + fn binding(&self) -> moq_net::transport::Binding { + self.inner.binding() + } + + fn close(&mut self, code: u32, reason: &str) { + self.inner.close(code, reason) + } + + fn poll_closed(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll { + self.inner.poll_closed(cx) + } + + fn stats(&self) -> impl moq_net::transport::Stats { + self.inner.stats() + } +} diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 3695ea33c8b..9b5c0408fda 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -3703,11 +3703,13 @@ impl TrackRun { self.start = Some(start); // Only the group: the subscriber derives the start frame from its own request // (see `lite::SubscribeStart`). The track is live by now, since its first group - // was readable. - let largest = match self.track.poll_live(&kio::Waiter::noop()) { + // was readable. A relay can hold just the first group of a backlog its source + // already answered past, so the source's largest says where the live feed is. + let live = match self.track.poll_live(&kio::Waiter::noop()) { Poll::Ready(largest) => largest, Poll::Pending => None, }; + let largest = live.max(self.track.peek_largest()); writer.buffer(&lite::SubscribeResponse::Start(lite::SubscribeStart { group: start, largest, @@ -4856,6 +4858,36 @@ mod serve_group_test { assert_eq!(*log.writes.lock().unwrap(), [0, 3, 0, 1, 0, 1, 2, 3, 2]); } + /// A relay that holds only the first group of a backlog answers with the largest its + /// source reported, so a live joiner downstream starts at the newest group rather than + /// the oldest one the budget serves. + #[moq_clock::test] + async fn lite07_start_reports_the_sources_largest() { + let mut track = track::Producer::new( + Arc::new(broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + // The source answered with group 4 as its largest; only group 0 has landed. + track.report_largest(track::Position::group(4)); + let subscriber = track.subscribe(None); + let (mut run, mut writer, log) = lite07_run(SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 0, 0); + while run.start.is_none() { + assert!(run.poll_step(&mut writer, &kio::Waiter::noop()).is_ready()); + } + kio::wait(|waiter| writer.poll_flush(&mut waiter.context())) + .await + .unwrap(); + + let writes = log.writes.lock().unwrap().clone(); + let (msg, _) = lite::SubscribeResponse::decode_slice(&writes, Version::Lite07).unwrap(); + let lite::SubscribeResponse::Start(start) = msg else { + panic!("expected SUBSCRIBE_START, got {msg:?}"); + }; + assert_eq!((start.group, start.largest), (0, Some(track::Position::group(4)))); + } + /// The SUBSCRIBE_DROP ranges a run loop's subscribe stream carried, once flushed. async fn drops(writer: &mut Writer, log: &Log, version: Version) -> Vec<(u64, u64)> { // The serve flushes what the run loop buffered before its FIN. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 478270f7552..52cd849bbdc 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -5537,6 +5537,21 @@ impl Subscriber { kio::wait(|waiter| self.poll_largest(waiter)).await } + /// The largest location known now, without waiting or moving [`Self::poll_largest`] on: + /// past what the cache holds once the source reported a newer one. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: capability gap + pub(crate) fn peek_largest(&mut self) -> Option { + let mut seen = None; + match &mut self.inner { + Inner::Plain(cursor) => cursor.state.read().cache.take_largest(&mut seen), + Inner::Resume(resume, _) => match resume.poll_largest(&mut seen, &kio::Waiter::noop()) { + Poll::Ready(largest) => largest, + Poll::Pending => None, + }, + } + } + #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/serve.md pub(crate) fn latest_sequence(&self) -> Option { From 800565dd9e777d57f3ac0cceae37d7d1ed63dcb1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 08:27:24 -0700 Subject: [PATCH 3/4] docs(net): a relay behaves the same with a warm or cold cache Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-net/AGENTS.md b/rs/moq-net/AGENTS.md index b0b22b6b611..a353bc28683 100644 --- a/rs/moq-net/AGENTS.md +++ b/rs/moq-net/AGENTS.md @@ -5,6 +5,7 @@ The wire layer. Generic over the transport and media-agnostic: the relay never i - Any wire change updates the matching draft in `drafts/` and `js/net` in the same PR: `draft-lcurley-moq-lite.md` for session/SETUP/framing, the per-feature draft otherwise. New capabilities are additive SETUP extensions; receivers ignore unknown parameters. - Closes never cascade. Aborting a group must not tear down its track, broadcast, or siblings. - A route change is never fatal on its own. A subscription stays on the instance it started on while that instance still has a route, even after a newer route wins the path. Once none is left (e.g. the publisher's session closed), it ends with an error, never a clean end, and the app requests the path again. Never stitch it onto another instance. A clean end means only a deliberate publisher finish or the local session closing. See "Publisher epochs" in `doc/concept/moq-lite.md`. +- The cache is a performance optimization. A relay behaves the same warm or cold: report upstream state (e.g. the largest group), not what the cache happens to hold. - Sessions are caller-driven: `connect`/`accept` return `(Session, Driver)`. The `Driver` holds no `Session` clone, so spawning it never keeps the session alive. - Version matching: outside the crate branch on `is_lite()` / `is_ietf()` and `alpn()`; inside it match the draft enums. List old drafts explicitly and let the newest behavior be the fallthrough so future drafts fall forward. - Interop rule of thumb: respond to every feature a peer may use, but don't request new ones. Never emit or accept partial groups; a group starts at frame 0. Exception: moq-transport passthrough forwards a mid-group start as the publisher sent it. From 83dfe1f4de30d106ada45a25aea403e01d80879b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 19 Oct 2026 08:41:21 -0700 Subject: [PATCH 4/4] fix(net): a JS relay's SUBSCRIBE_START reports its source's largest Mirror the Rust relay: a lite-07 SUBSCRIBE_START names the larger of the newest buffered frame and the largest the source reported, so a relay holding only the oldest group of a backlog still points a live joiner at the newest group. Co-Authored-By: Claude Opus 5.5 --- js/net/src/internal.ts | 6 +++++ js/net/src/lite/publisher.test.ts | 38 +++++++++++++++++++++++++++++++ js/net/src/lite/publisher.ts | 13 ++++++++++- js/net/src/track.ts | 1 + 4 files changed, 57 insertions(+), 1 deletion(-) diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 79bb5283a93..e8e5e6fe9bc 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -278,6 +278,9 @@ export const hooks: { // pending: /quest/m1/public-model/serve.md /** The newest frame buffered for a subscriber, which wire answers name; assigned by `track.ts`. */ bufferedLargest: (subscriber: Subscriber) => Location | undefined; + // private: capability gap + /** The track's largest known now, past what is buffered once the source reported newer; assigned by `track.ts`. */ + peekLargest: (subscriber: Subscriber) => Location | undefined; /** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */ groupProgress: (group: GroupProducer, fn: (total: number) => void) => Dispose; // pending: /quest/m1/public-model/ingest.md @@ -387,6 +390,9 @@ export const hooks: { bufferedLargest: () => { throw new Error("track.ts not loaded"); }, + peekLargest: () => { + throw new Error("track.ts not loaded"); + }, groupProgress: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index c6455a316a1..9894c2cc1a5 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -2245,6 +2245,44 @@ test.each([0, 1])("lite draft-07 reports the cached largest position when starti } }); +// A relay that holds only the first group of a backlog answers with the largest its source +// reported, so a live joiner downstream starts at the newest group rather than the oldest one +// the budget serves. +test("lite draft-07 reports the source's largest position past what a relay holds", async () => { + const version = Version.DRAFT_07; + const pair = createMockTransportPair(ALPN_07_WIP); + const origin = new OriginProducer(); + const publisher = new Publisher(pair.server, version, randomHop(), origin.consume()); + const broadcast = publish(origin, Path.from("relayed")); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + // The source answered with group 4 as its largest; only group 0 has landed. + hooks.reportedLargest(track, { group: 4, frame: 0 }); + const group = new GroupProducer(0); + group.writeFrame(textFrame("oldest")); + group.close(); + track.writeGroup(group); + const client = await Stream.open(pair.client, { version }); + const server = await Stream.accept(pair.server, version); + if (!server) throw new Error("missing subscribe stream"); + const running = publisher.runSubscribe( + replaySubscribe({ id: 0n, broadcast: Path.from("relayed"), track: "video", priority: 0 }), + server, + ); + try { + const response = await decodeSubscribeResponse(client.reader, version); + if (!("start" in response)) throw new Error("expected SUBSCRIBE_START"); + expect([response.start.group, response.start.largest]).toEqual([0, { group: 4, frame: 0 }]); + } finally { + client.close(); + publisher.close(); + broadcast.close(); + origin.close(); + pair.client.close(); + pair.server.close(); + await running; + } +}); + async function settleControls(): Promise { await new Promise((resolve) => { const channel = new MessageChannel(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 773134c6c4e..d72163e1d45 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -304,6 +304,12 @@ class SubscriptionControls { } } +// The later of two locations, either of which may be unknown. +function newer(a: track.Location | undefined, b: track.Location | undefined): track.Location | undefined { + if (!a || !b) return a ?? b; + return b.group > a.group || (b.group === a.group && b.frame > a.frame) ? b : a; +} + // Register both readiness sources in the same turn after the caller observed neither ready. // The winner disposes both registrations, so an idle subscription accumulates nothing no // matter how many times it wakes. @@ -1120,7 +1126,12 @@ export class Publisher { // Exactly-once arrival-order serving. This synchronous package-internal pop // and frameRange call are the operation's linearization point. // Popping or filtering a group removes the subscriber's view of its edge. - const largest = !startSent && hasLargest(this.version) ? hooks.bufferedLargest(track) : undefined; + // A relay can hold just the first group of a backlog its source already + // answered past, so the source's largest says where the live feed is. + const largest = + !startSent && hasLargest(this.version) + ? newer(hooks.bufferedLargest(track), hooks.peekLargest(track)) + : undefined; const recv = hooks.tryRecvGroup(track, startSent); switch (recv.kind) { case "error": diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 07b16ba3925..98f7d7eb506 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1670,6 +1670,7 @@ export class Subscriber { hooks.tryRecvGroup = (subscriber, started) => subscriber.#tryRecvGroup(started); hooks.latestSequence = (subscriber) => subscriber.#state.latest; hooks.bufferedLargest = (subscriber) => subscriber.#bufferedLargest(); + hooks.peekLargest = (subscriber) => subscriber.#state.largest.peek(); hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); hooks.fetchBudget = (subscriber, maxDelay) => { subscriber.#fetchBudget = maxDelay ?? Number.POSITIVE_INFINITY;