From 4447e04b066b26fa51c4335e712cb9f5992849f7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 03:47:55 -0800 Subject: [PATCH 01/20] chore(quest): claim quest/m1/subscribe-ranges/fetch-range.md Quest-Claim: 36c0f8901bd684e8 From 5deb4063cf6116d7e6d1682d58f25f97463154b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 03:50:27 -0800 Subject: [PATCH 02/20] chore(quest): checkpoint blocked fetch-range validation Co-Authored-By: GPT-6.1 Sol --- quest/m1/subscribe-ranges/fetch-range.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/quest/m1/subscribe-ranges/fetch-range.md b/quest/m1/subscribe-ranges/fetch-range.md index 36fb438a660..64763b9c374 100644 --- a/quest/m1/subscribe-ranges/fetch-range.md +++ b/quest/m1/subscribe-ranges/fetch-range.md @@ -9,6 +9,15 @@ page, and `moq fetch` through `moq_relay::fetch_group`. ## Plan +Checkpoint 2026-11-02 +([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): no remaining +model, API, or consumer changes implemented. On main `f8c608a24b`, +`quest gate nix develop --command just rs test -p moq-net -E 'test(bounded)'` +exited 1 before compilation: mbx could not launch Cargo (`Argument list too +long (os error 7)`). Resume with working validation; the remaining scope and +decisions below still apply. No validation bypass or upstream mbx work is part +of this claim. + Split out of dynamic range requests, which replaced `requested_group` with `requested_fill`, by the maintainer on 2026-10-20 ([moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so each PR From 50dbca75f3a38f3d698f0cc2c0aa21e0dc9763ee Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:29:10 -0800 Subject: [PATCH 03/20] feat(net): a front's bounded read ends once its range is accounted The serving copy's cursor judges the window from its resume point against the logical reader's record and its own, and a replaced or backfill copy that may still deliver keeps the read open. Wire publishers keep parking. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/resume.rs | 42 ++++++++++++++++++- rs/moq-net/src/model/resume_model.rs | 31 +++++++++++--- rs/moq-net/src/model/track.rs | 36 +++++++++++----- rs/moq-net/tests/integration/fetch_only.rs | 3 +- .../tests/integration/subscribe_ranges.rs | 19 ++++++--- 5 files changed, 107 insertions(+), 24 deletions(-) diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 8adf4905ec3..872258b8d33 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -723,20 +723,30 @@ impl Mirror { impl Subscriber { /// Reserve the lowest next group not in `delivered` across copies, without handing it /// out: in arrival order, or in sequence order for `ordered`. + /// Unless it `parks`, a bounded reader ends once its window has nothing left on any copy; + /// see [`Reader::exhausted`]. pub(super) fn poll_peek_group( &mut self, ordered: bool, + parks: bool, delivered: &Delivered, waiter: &kio::Waiter, ) -> Poll>> { let mut reader = self.reader(); loop { - if let Some(result) = reader.poll_lowest(ordered, delivered, waiter) { + if let Some(result) = reader.poll_lowest(ordered, parks, delivered, waiter) { return result; } } } + /// Whether this reader's bounded window has nothing left for the readers that handed out + /// `taken`, the first of which is its own; see [`Reader::exhausted`]. + pub(super) fn exhausted(&mut self, taken: &[&Delivered], waiter: &kio::Waiter) -> bool { + let mut reader = self.reader(); + !reader.let_go(taken[0], waiter) && reader.exhausted(taken, waiter) + } + /// Hand out the group a [`Self::poll_peek_group`] reserved. pub(super) fn take(&mut self, candidate: Candidate) -> Result { self.reader().take(candidate) @@ -1433,6 +1443,7 @@ impl Reader { fn poll_lowest( &mut self, ordered: bool, + parks: bool, delivered: &Delivered, waiter: &kio::Waiter, ) -> Option>>> { @@ -1530,6 +1541,9 @@ impl Reader { } let drained = self.bound_at_end(); let waits = self.let_go(delivered, waiter); + if !parks && !waits && self.exhausted(&[delivered], waiter) { + return Some(Poll::Ready(Ok(None))); + } match self.poll_end(waiter, |copy| copy.done.clone()) { // The serving copy drained, but a copy it replaced may still deliver a group below // its end: the track ends once that copy has. @@ -1538,6 +1552,32 @@ impl Reader { } } + /// Whether a bounded window has nothing left to deliver, once no replaced copy may still + /// deliver a group under its bound. The serving copy reads every group of the window from + /// its resume point, so its cursor judges those: each was handed out (in any of `taken`, or + /// by that copy), dropped, skipped as stale, or given up as unfillable. What lies under its + /// resume point was the copies' it replaced, each let go once it had nothing more, and a + /// backfill still out is not judged yet. A route between copies has nothing to judge. + fn exhausted(&mut self, taken: &[&Delivered], waiter: &kio::Waiter) -> bool { + if self.resumed.is_some() { + return false; + } + let window = self.window(); + if window.is_pending() || window.end().is_none() { + return false; + } + match self.copies.last_mut() { + Some(Copy { + generation, + replaced: false, + done: None, + sub: Sub::Ready(sub), + .. + }) if Some(*generation) == self.generation => sub.exhausted_for(taken, waiter), + _ => false, + } + } + /// Whether the track ended, once the serving copy's channel (as `done` reads it) ran /// out. `None` when the route moved since it was read: the caller looks again. fn poll_end( diff --git a/rs/moq-net/src/model/resume_model.rs b/rs/moq-net/src/model/resume_model.rs index dab72582ce5..4fd30742d16 100644 --- a/rs/moq-net/src/model/resume_model.rs +++ b/rs/moq-net/src/model/resume_model.rs @@ -419,6 +419,11 @@ impl Model { }; reader.ranges = range; let _ = reader.control.update(subscription(reader.spec.budget, range)); + // A read that ended at its range's end reads on once the range widens. + if matches!(reader.end, Some(Ok(()))) && !self.instances[reader.instance].ended { + reader.end = None; + reader.carried.clear(); + } self.poll(index)?; } Op::Bounds { reader: index, range } => { @@ -684,12 +689,18 @@ impl Model { ); } Poll::Ready(Ok(None)) => { - if !instance.ended { + // A bounded read ends once its range is read, a local cap holding nothing + // back: what lands in it afterwards is not owed. + if !instance.ended && reader.ranges.is_none() { return Err(fail(index, "the track ended cleanly though no route declared an end")); } + let covers = |group: u64| match instance.ended { + true => reader.covers(group), + false => reader.ranges.is_some_and(|(start, end)| (start..end).contains(&group)), + }; // A group landing below the end afterwards is not owed: a reader stops at it. reader.carried = (0..GROUPS) - .filter(|group| reader.covers(*group) && instance.live().all(|copy| copy.complete(*group))) + .filter(|group| covers(*group) && instance.live().all(|copy| copy.complete(*group))) .collect(); reader.end = Some(Ok(())); } @@ -845,15 +856,25 @@ impl Model { if reader.doomed { return match &reader.end { Some(Err(_)) => Ok(()), - Some(Ok(())) if instance.ended => Ok(()), + Some(Ok(())) if instance.ended || reader.ranges.is_some() => Ok(()), end => Err(fail(index, format!("outlived its instance's routes: {end:?}"))), }; } // What every live route carries in full. let carried = |group: u64| instance.live().all(|copy| copy.complete(group)); + // A read that ended its range owed every group in it, whatever its cap, but an + // ordered one passes what its floor keeps out once it reads past it. + let read_range = matches!(reader.end, Some(Ok(()))) && !instance.ended; + let covers = |group: u64| match read_range { + true => { + reader.ranges.is_some_and(|(start, end)| (start..end).contains(&group)) + && (!reader.spec.ordered || reader.bounds.is_none_or(|(start, _)| group >= start)) + } + false => reader.covers(group), + }; let mut owed: Vec = (0..GROUPS) .filter(|group| reader.floor.is_none_or(|floor| *group > floor)) - .filter(|group| reader.covers(*group) && carried(*group)) + .filter(|group| covers(*group) && carried(*group)) .collect(); if reader.spec.ordered { owed.retain(|group| before.is_none_or(|before| *group > before)); @@ -886,7 +907,7 @@ impl Model { } match (&reader.end, finish && instance.live().next().is_some()) { (None, false) | (Some(Ok(())), true) => {} - (Some(Ok(())), false) if instance.ended => {} + (Some(Ok(())), false) if instance.ended || reader.ranges.is_some() => {} (end, _) => { let _ = write!(problems, "track end {end:?}; "); } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 214e500bdfb..19eecf50f90 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -6700,10 +6700,10 @@ impl Cursor { } /// Whether a bounded window has nothing left to deliver: every group in its ranges was - /// handed out (`taken`), dropped, skipped as stale, or given up as unfillable. An open - /// window, or one with a fill still out, always has more, and so does one its cap - /// keeps a group out of, since a reader may raise a cap again. - fn is_exhausted(&self, taken: &Delivered) -> bool { + /// handed out (in any of `taken`), dropped, skipped as stale, or given up as unfillable. + /// An open window, or one with a fill still out, always has more, and so does one its + /// cap keeps a group out of, since a reader may raise a cap again. + fn is_exhausted(&self, taken: &[&Delivered]) -> bool { let Some(end) = self.filter.window.end() else { return false; }; @@ -6737,7 +6737,11 @@ impl Cursor { .take_while(|run| *run.start() < end) .all(|run| { let run = *run.start()..run.end().checked_add(1).map_or(end, |next| next.min(end)); - taken.gaps(run).into_iter().all(&accounted) + let mut gaps = vec![run]; + for taken in taken { + gaps = gaps.into_iter().flat_map(|gap| taken.gaps(gap)).collect(); + } + gaps.into_iter().all(&accounted) }) } @@ -7755,8 +7759,8 @@ impl Subscriber { /// was handed out, dropped, skipped as stale, or given up as unfillable, rather than /// waiting for an update to widen them: a reader that wants more keeps a range open. A /// [`Self::with_range`] cap never ends a read, since it may rise again, and a group it - /// keeps out stays owed. - /// A track an origin serves from whichever of its routes is up still parks there for now. + /// keeps out stays owed. A track an origin serves from whichever of its routes is up ends + /// the same way, once no route it left may still deliver a group in range. /// /// A group one of [`Subscription::ranges`] starts or ends inside reads only the frames /// they cover there. One missing the frames asked for reads [`Error::Lagged`] rather @@ -7804,7 +7808,7 @@ impl Subscriber { Poll::Pending => { // A read that only skipped since its last hand-out settles its write-offs too. cursor.retire_written_off(&mut self.delivered); - if !self.parks && cursor.is_exhausted(&self.delivered) { + if !self.parks && cursor.is_exhausted(&[&self.delivered]) { return Poll::Ready(Ok(None)); } return Poll::Pending; @@ -7820,13 +7824,25 @@ impl Subscriber { // A replay advances only this copy's cursor, as an ordinary read would. cursor.take(peeked); }, - // A front's bounded read parks past its end for now, as each copy's reader does. Inner::Resume(resume, _) => resume - .poll_peek_group(ordered, &self.delivered, waiter) + .poll_peek_group(ordered, self.parks, &self.delivered, waiter) .map(|res| res.map(|candidate| candidate.map(|candidate| Reserved::Resume(Box::new(candidate))))), } } + /// Whether this route copy's bounded window has nothing left for the logical readers that + /// handed out `logical`: what this copy took itself, wrote off, or gave up counts too. + pub(super) fn exhausted_for(&mut self, logical: &[&Delivered], waiter: &kio::Waiter) -> bool { + let mut taken = Vec::with_capacity(logical.len() + 1); + taken.push(&self.delivered); + taken.extend_from_slice(logical); + match &mut self.inner { + Inner::Plain(cursor) => cursor.is_exhausted(&taken), + // A copy that is another front's logical track judges across its own copies. + Inner::Resume(resume, _) => resume.exhausted(&taken, waiter), + } + } + /// Hand out the group a [`Self::poll_peek_group`] on this subscriber reserved. pub(super) fn take(&mut self, reserved: Reserved) -> Result { let meter = self.stats.meter(); diff --git a/rs/moq-net/tests/integration/fetch_only.rs b/rs/moq-net/tests/integration/fetch_only.rs index 89a735d04e3..00abf4d885c 100644 --- a/rs/moq-net/tests/integration/fetch_only.rs +++ b/rs/moq-net/tests/integration/fetch_only.rs @@ -248,10 +248,9 @@ async fn bounded_direct(version: &str) { let remote = resolve(&client).await; let copy = remote.track("video").unwrap(); copy.info().await.expect("TRACK_STATUS resolves the track"); - // A front's bounded read still parks past its end, as each copy's reader does, so this - // reads the group and stops there. let mut sub = subscribe_history(©).await; assert_eq!(next_frames(&mut sub).await, Some(frames(1)), "{version}"); + assert_eq!(next_frames(&mut sub).await, None, "{version}: the read ends"); assert!( !subscribed.load(Ordering::SeqCst), "{version}: the bounded read subscribed" diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index c33e815427b..c64ae7c4e66 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -311,8 +311,8 @@ async fn draft22_updates_both_bounds_across_cached_groups() { TIMEOUT, kio::wait(|waiter| { assert!( - reader.poll_recv_group(waiter).is_pending(), - "the narrowed reader has no unread group" + matches!(reader.poll_recv_group(waiter), std::task::Poll::Ready(Ok(None))), + "the narrowed reader read its range" ); loop { if fixture @@ -519,8 +519,9 @@ async fn draft18_updates_narrow_then_widen() { } } -/// Empty ranges retire only demand no other reader holds. A later widening reuses -/// the copy and joins the new live group, without disturbing a sibling reader. +/// Empty ranges end the read and retire only demand no other reader holds. A later +/// widening reuses the copy and joins the new live group, without disturbing a sibling +/// reader. #[kio::test] async fn empty_ranges_retire_the_wire_and_can_widen_again() { for version in ["moq-transport-18", "moq-transport-22"] { @@ -532,7 +533,10 @@ async fn empty_ranges_retire_the_wire_and_can_widen_again() { assert_eq!(next(&mut reader).await, Some(5)); assert_eq!(next(&mut sibling).await, Some(5)); reader.update(live.clone().with_ranges([])).unwrap(); - assert!(reader.poll_recv_group(&kio::Waiter::noop()).is_pending()); + assert!(matches!( + reader.poll_recv_group(&kio::Waiter::noop()), + std::task::Poll::Ready(Ok(None)) + )); let mut group = fixture .track .create_group(moq_net::group::Info { sequence: 6 }) @@ -549,7 +553,10 @@ async fn empty_ranges_retire_the_wire_and_can_widen_again() { kio::clock::timeout( TIMEOUT, kio::wait(|waiter| { - assert!(reader.poll_recv_group(waiter).is_pending()); + assert!(matches!( + reader.poll_recv_group(waiter), + std::task::Poll::Ready(Ok(None)) + )); loop { if fixture.track.subscription().is_none() { return std::task::Poll::Ready(()); From dbf749f9ff75d2e5a123d476cf2060fb50b5461a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:39:46 -0800 Subject: [PATCH 04/20] feat(net): a bounded read fills the head of a group it lacks A bounded window reads whole groups as a fetch does, so a cached live group missing its first frames is handed out from a fill asked from frame 0, and given up when no fill serves it, rather than read as Lagged. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 288 ++++++++++++++++++++++++----- rs/moq-net/src/model/track/miss.rs | 2 +- 2 files changed, 243 insertions(+), 47 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 19eecf50f90..d5a34ac78a7 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -5219,10 +5219,6 @@ impl Consumer { options, end: frame_end, } = request; - let frames = group::Bounds { - start: options.frame_start, - end: frame_end, - }; // One fetch per calling context, counted here (coalesced upstream work is // still one request served). Independent of `subscriptions` and the viewer @@ -5250,7 +5246,6 @@ impl Consumer { let state = self.resolve(None).0; let resume = state.read().routes.clone(); - let mut result = None; // A front's logical track caches nothing: the serving route answers. if let Some(resume) = resume { @@ -5276,45 +5271,15 @@ impl Consumer { }); } - // Queue a request only when the group isn't already resolvable from the track - // (cached, aborted, or past-final all resolve through `Fetching::poll` without - // a queue entry). - let (fills, cached) = { - let state = state.read(); - (state.fills.clone(), state.poll_fetch_cached(sequence, frames)) - }; - let unresolved = cached.is_pending(); - // Hold a hit until the caller polls: the held consumer keeps the group wanted, - // so an abandoned fetch filling it can't abort it in between. - let hit = match cached { - Poll::Ready(Ok(group)) => Some(Box::new(group)), - _ => None, - }; - - if unresolved { - result = queue( - &fills, - sequence, - &FetchOptions { - options: options.clone(), - end: frame_end, - }, - ); - } - - kio::Pending::new(Fetching { + kio::Pending::new(Fetching::cached_or_queued( state, - fills, sequence, - frame_start: options.frame_start, - frame_end, - priority: options.priority, - max_delay: options.max_delay, - result, - hit, - stats: self.stats.clone(), - resume: None, - }) + FetchOptions { + options, + end: frame_end, + }, + self.stats.clone(), + )) } /// The sequences of `span` the cache holds, lowest first. @@ -5630,6 +5595,50 @@ pub struct Fetching { resume: Option>, } +impl Fetching { + /// A fetch of `sequence` from the track's own cache, queueing a fill for it only when + /// the cache can't resolve it (cached, aborted, or past-final all resolve through + /// [`Self::poll`] without one). + fn cached_or_queued( + state: kio::Consumer, + sequence: u64, + request: FetchOptions, + stats: stats::Scope, + ) -> Self { + let frames = group::Bounds { + start: request.options.frame_start, + end: request.end, + }; + let (fills, cached) = { + let state = state.read(); + (state.fills.clone(), state.poll_fetch_cached(sequence, frames)) + }; + let result = match cached.is_pending() { + true => queue(&fills, sequence, &request), + false => None, + }; + // Hold a hit until the caller polls: the held consumer keeps the group wanted, + // so an abandoned fetch filling it can't abort it in between. + let hit = match cached { + Poll::Ready(Ok(group)) => Some(Box::new(group)), + _ => None, + }; + Self { + state, + fills, + sequence, + frame_start: request.options.frame_start, + frame_end: request.end, + priority: request.options.priority, + max_delay: request.options.max_delay, + result, + hit, + stats, + resume: None, + } + } +} + impl kio::Task for Fetching { type Output = Result; @@ -6309,6 +6318,8 @@ struct Cursor { drops: Option>, /// What this cursor misses and asks fills for, once it first reads. misses: Option>, + /// The heads a bounded window asked for, once it first finds a group missing one. + heads: Option>, /// The group read that last parked, answered again without the walk until something /// it parked on fires, once it first parks. idle: Option>, @@ -6341,6 +6352,18 @@ enum Taken { Owed, /// What a fill answered. Filled, + /// A head a bounded window asked for. + Head, +} + +/// The groups a bounded window read missing their head, which it hands out only once a +/// fill answered from their first frame: a whole-group read never starts short. +#[derive(Default)] +struct Heads { + /// Asked, by sequence. + fetching: BTreeMap, + /// Answered and not handed out yet. + filled: BTreeMap, } /// The sequences a [`DropCursor`] reports from: a cursor's span, narrowed to its window. @@ -6544,6 +6567,7 @@ impl Cursor { skipped: Skipped::default(), drops: None, misses: None, + heads: None, idle: None, finished: None, } @@ -7225,7 +7249,9 @@ impl Cursor { /// Whether a fill still owes this cursor a group, so the end of the feed is not its end. fn awaits_fill(&self) -> bool { - self.misses.as_ref().is_some_and(|misses| misses.is_waiting()) || self.filter.window.lookups().next().is_some() + self.misses.as_ref().is_some_and(|misses| misses.is_waiting()) + || self.filter.window.lookups().next().is_some() + || self.heads.as_ref().is_some_and(|heads| !heads.fetching.is_empty()) } /// Find the next group in arrival order, or in sequence order for `ordered`, without @@ -7274,18 +7300,22 @@ impl Cursor { /// [`Self::poll_peek_recv`] once synced, judging against `drift`. fn poll_recv_with(&mut self, mut drift: Drift, waiter: &kio::Waiter) -> Poll>> { + self.poll_heads(waiter); loop { // Re-offer what a widening newly covers ahead of the arrival walk, in the // subscription's order: it is the oldest thing still owed. A group the walk has // yet to reach comes again from it, and the subscriber's delivered set drops the // repeat. let owed = match self.next_owed() { - Some(producer) => Some((producer, Taken::Owed)), + Some(producer) => Some((producer.consume(), Taken::Owed)), // A fill answered what the walk never reaches: backfill is not in it. - None => self.next_filled().map(|producer| (producer, Taken::Filled)), + None => match self.next_filled() { + Some(producer) => Some((producer.consume(), Taken::Filled)), + None => self.next_head().map(|group| (group, Taken::Head)), + }, }; let (consumer, taken) = match owed { - Some((producer, taken)) => (producer.consume(), taken), + Some((consumer, taken)) => (consumer, taken), None => { let floor = self.floor(); let polled = self.poll(waiter, |state| { @@ -7354,6 +7384,12 @@ impl Cursor { } continue; } + if self.lacks_head(&consumer) { + self.advance_arrival(consumer.sequence, taken); + self.ask_head(consumer.sequence); + self.poll_heads(waiter); + continue; + } return Poll::Ready(Ok(Some(Peeked { group: consumer, arrival: Some(taken), @@ -7372,9 +7408,72 @@ impl Cursor { misses.take_filled(sequence); } } + Taken::Head => { + if let Some(heads) = &mut self.heads { + heads.filled.remove(&sequence); + } + } + } + } + + /// Whether `group` is one this cursor hands out only from its first frame, which it + /// lacks: the window is bounded, so it reads whole groups as a fetch would. + fn lacks_head(&self, group: &group::Consumer) -> bool { + self.filter.window.end().is_some() && group.first_frame() > 0 + } + + /// Ask a fill for the head of `sequence`, as a fetch from frame 0 would. + fn ask_head(&mut self, sequence: u64) { + let asking = self.subscription.read().clone(); + let request = FetchOptions { + options: group::Fetch { + priority: asking.priority, + max_delay: asking.max_delay, + frame_start: 0, + }, + end: None, + }; + let fetching = Fetching::cached_or_queued(self.state.clone(), sequence, request, stats::Scope::default()); + self.heads.get_or_insert_default().fetching.insert(sequence, fetching); + } + + /// Take in the heads answered, parking `waiter` on those still out. A head no fill can + /// serve gives its group up, as a refused miss is. + fn poll_heads(&mut self, waiter: &kio::Waiter) { + let Some(heads) = &mut self.heads else { return }; + let mut given_up = Vec::new(); + heads.fetching.retain(|sequence, fetching| match kio::Task::poll(fetching, waiter) { + Poll::Pending => true, + Poll::Ready(Ok(group)) => { + heads.filled.insert(*sequence, group); + false + } + Poll::Ready(Err(_)) => { + given_up.push(*sequence..sequence.saturating_add(1)); + false + } + }); + if given_up.is_empty() { + return; + } + let misses = self.misses.get_or_insert_with(Box::default); + let mut runs = Vec::new(); + for run in given_up { + misses.give_up(run, &mut runs); + } + if let Some(drops) = &mut self.drops { + for run in runs { + drops.give_up(run); + } } } + /// The lowest head answered and not handed out yet. + fn next_head(&self) -> Option { + let heads = self.heads.as_ref()?; + heads.filled.values().next().cloned() + } + /// The next datagram inside this subscriber's range, dropping the ones outside it. /// /// The floor, cap and time/group ranges select whole datagram groups here; frame @@ -7509,6 +7608,30 @@ impl Cursor { // until the budget gives up on it. Its landing, its drop, or that verdict wakes us. ready!(self.poll_owed(from..group.sequence, &drift, waiter))?; + // A group missing its head comes from the fill asked for it, in its turn. + let group = match self.lacks_head(&group) { + false => group, + true => { + let sequence = group.sequence; + if self.heads.as_ref().is_none_or(|heads| { + !heads.fetching.contains_key(&sequence) && !heads.filled.contains_key(&sequence) + }) && self.misses.as_ref().is_none_or(|misses| misses.gone(sequence).is_none()) + { + self.ask_head(sequence); + } + self.poll_heads(waiter); + match self.heads.as_ref().and_then(|heads| heads.filled.get(&sequence)) { + Some(head) => head.clone(), + // Given up: past it, as past any group no fill can serve. + None if self.misses.as_ref().is_some_and(|misses| misses.gone(sequence).is_some()) => { + floor = sequence.saturating_add(1); + continue; + } + None => return Poll::Pending, + } + } + }; + // A conviction the budget walked back: the group is handed over after all, // so it must never reach the stale count. self.seek_pending.remove(&group.sequence); @@ -7524,6 +7647,9 @@ impl Cursor { if let Some(misses) = &mut self.misses { misses.take_filled(group.sequence); } + if let Some(heads) = &mut self.heads { + heads.filled.remove(&group.sequence); + } // The delivery commits everything the seek stepped over to reach this group. self.commit_seek_stale(self.next_sequence.unwrap_or(u64::MAX)); group.cache_refresh(); @@ -17146,6 +17272,76 @@ mod test { ); } + /// A bounded read of a live group the feed started partway into asks its head as a fill, + /// and reads the filled copy from its first frame rather than lagging. + #[kio::test] + #[cfg(feature = "async")] + async fn a_bounded_read_fills_the_head_of_a_live_group() { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.requests(); + + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + live.finish().unwrap(); + + let mut sub = producer.subscribe(replay().with_range(0..1)); + let reading = kio::clock::sim::spawn(async move { + let mut group = sub.recv_group().await.unwrap().expect("the group"); + let mut frames = Vec::new(); + while let Some(frame) = group.read_frame().await.unwrap() { + frames.push(frame.payload); + } + (frames, sub.recv_group().await.unwrap().is_none()) + }); + let request = kio::clock::timeout(std::time::Duration::from_secs(1), dynamic.requested_fill_group()) + .await + .expect("the head is asked") + .unwrap(); + assert_eq!(request.frame_start(), 0); + let mut head = request.accept(Info::timed()).unwrap(); + for payload in [&b"snapshot"[..], b"delta"] { + head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(payload)) + .unwrap(); + } + head.finish().unwrap(); + let (frames, ended) = reading.await.unwrap(); + assert_eq!(frames, [&b"snapshot"[..], b"delta"]); + assert!(ended, "the read ends with its range"); + } + + /// An ordered bounded read whose head no fill serves gives that group up and reads on, + /// rather than handing it out to lag. + #[kio::test] + #[cfg(feature = "async")] + async fn a_bounded_read_gives_up_a_group_whose_head_is_refused() { + let producer = track_producer("test", Info::default()); + let dynamic = producer.requests(); + + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(None, bytes::Bytes::from_static(b"delta")) + .unwrap(); + live.finish().unwrap(); + framed(&producer, 1, 1).finish().unwrap(); + + let mut sub = producer.subscribe(replay().with_range(0..2)).ordered(); + let reading = kio::clock::sim::spawn(async move { + let mut read = Vec::new(); + while let Some(group) = sub.next_group().await.unwrap() { + read.push(group.sequence); + } + read + }); + let request = kio::clock::timeout(std::time::Duration::from_secs(1), dynamic.requested_fill_group()) + .await + .expect("the head is asked") + .unwrap(); + request.reject(Error::NotFound); + assert_eq!(reading.await.unwrap(), [1]); + } + /// A refused mid-group end caps none of its group's copies, even one that fit under it. #[kio::test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/model/track/miss.rs b/rs/moq-net/src/model/track/miss.rs index 20b4e340f2f..87a65362325 100644 --- a/rs/moq-net/src/model/track/miss.rs +++ b/rs/moq-net/src/model/track/miss.rs @@ -881,7 +881,7 @@ impl Misses { } } - fn give_up(&mut self, groups: ops::Range, given_up: &mut GivenUp) { + pub(super) fn give_up(&mut self, groups: ops::Range, given_up: &mut GivenUp) { if groups.is_empty() { return; } From ee6eca9dc3f3f90f22e734cc7a3c14a45444f42f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:52:56 -0800 Subject: [PATCH 05/20] fix(net): keep a routed bounded read open for groups its local bounds hold back A group in range under the serving copy's resume point that the local floor or cap keeps out stays owed, as on one cursor. An ordered copy lets go of heads it passed, so a fill it no longer polls never holds the read open. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/delivered.rs | 9 +++++ rs/moq-net/src/model/resume.rs | 22 +++++++++++- rs/moq-net/src/model/resume_model.rs | 53 ++++++++++++++++++++++++++++ rs/moq-net/src/model/track.rs | 21 ++++++----- 4 files changed, 96 insertions(+), 9 deletions(-) diff --git a/rs/moq-net/src/model/delivered.rs b/rs/moq-net/src/model/delivered.rs index ec631e54c53..dd1f1ce79a3 100644 --- a/rs/moq-net/src/model/delivered.rs +++ b/rs/moq-net/src/model/delivered.rs @@ -109,6 +109,15 @@ impl Delivered { gaps } + /// The parts of `groups` none of `taken` handed out, in order. + pub fn gaps_in_all(taken: &[&Self], groups: std::ops::Range) -> Vec> { + let mut gaps = Vec::from([groups]); + for taken in taken { + gaps = gaps.into_iter().flat_map(|gap| taken.gaps(gap)).collect(); + } + gaps + } + /// Count every sequence below `floor` as handed out. pub fn forget_below(&mut self, floor: u64) { let Some(below) = floor.checked_sub(1) else { diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 872258b8d33..e9718ddc5fe 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1558,13 +1558,33 @@ impl Reader { /// by that copy), dropped, skipped as stale, or given up as unfillable. What lies under its /// resume point was the copies' it replaced, each let go once it had nothing more, and a /// backfill still out is not judged yet. A route between copies has nothing to judge. + /// `taken` holds the logical readers' records, the reader's own first. fn exhausted(&mut self, taken: &[&Delivered], waiter: &kio::Waiter) -> bool { if self.resumed.is_some() { return false; } + let (lowest, cap) = self.groups; + let resumed = self.copies.last().and_then(|copy| copy.floor); let window = self.window(); - if window.is_pending() || window.end().is_none() { + let Some(end) = window.end().filter(|_| !window.is_pending()) else { return false; + }; + // A group under the serving copy's resume point that the local floor or cap keeps + // out stays owed, as on one cursor, though no copy reads it. + if let Some(resumed) = resumed { + let until = resumed.min(end); + for run in window + .runs(window.floor().unwrap_or(0)) + .take_while(|run| *run.start() < until) + { + let run = *run.start()..run.end().saturating_add(1).min(until); + if Delivered::gaps_in_all(taken, run) + .iter() + .any(|gap| gap.start < lowest || cap.is_some_and(|cap| gap.end > cap)) + { + return false; + } + } } match self.copies.last_mut() { Some(Copy { diff --git a/rs/moq-net/src/model/resume_model.rs b/rs/moq-net/src/model/resume_model.rs index 4fd30742d16..637514d54b5 100644 --- a/rs/moq-net/src/model/resume_model.rs +++ b/rs/moq-net/src/model/resume_model.rs @@ -1106,6 +1106,59 @@ fn regressions() { ], finish: false, }, + // An ordered reader whose ranges narrowed to groups only a standby route's head + // fill can complete reads them and ends with the track. + Case { + ops: vec![ + Op::Up { epoch: 0, slot: 1 }, + Op::Join { + reader: 1, + spec: spec(false, Budget::Hour, None, false), + }, + Op::Up { epoch: 0, slot: 2 }, + Op::Join { + reader: 0, + spec: spec(true, Budget::Hour, None, false), + }, + Op::Ranges { + reader: 0, + range: Some((8, 11)), + }, + Op::Write { + epoch: 0, + slot: 1, + group: Some(8), + frames: 1, + }, + ], + finish: true, + }, + // Groups in range under the resume point that the local floor keeps out stay owed, + // so the read does not end once the copies read everything above them. + Case { + ops: vec![ + Op::Join { + reader: 1, + spec: spec(false, Budget::Hour, None, false), + }, + Op::Write { + epoch: 0, + slot: 0, + group: Some(6), + frames: 1, + }, + Op::Up { epoch: 0, slot: 1 }, + Op::Ranges { + reader: 1, + range: Some((0, 8)), + }, + Op::Bounds { + reader: 1, + range: Some((3, 8)), + }, + ], + finish: false, + }, ]; for case in cases { if let Err(err) = run(&case) { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index d5a34ac78a7..c2a953e606c 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -6761,11 +6761,7 @@ impl Cursor { .take_while(|run| *run.start() < end) .all(|run| { let run = *run.start()..run.end().checked_add(1).map_or(end, |next| next.min(end)); - let mut gaps = vec![run]; - for taken in taken { - gaps = gaps.into_iter().flat_map(|gap| taken.gaps(gap)).collect(); - } - gaps.into_iter().all(&accounted) + Delivered::gaps_in_all(taken, run).into_iter().all(&accounted) }) } @@ -7517,6 +7513,17 @@ impl Cursor { if !self.seek_pending.is_empty() { self.seek_pending = next.map_or_else(BTreeMap::new, |next| self.seek_pending.split_off(&next)); } + self.forget_heads_below(next); + } + + /// Let go of the heads asked below `next`, which an ordered read never goes back for: + /// one still out would keep the read waiting on a fill it no longer polls. + fn forget_heads_below(&mut self, next: Option) { + if let Some(heads) = &mut self.heads { + let next = next.unwrap_or(u64::MAX); + heads.fetching = heads.fetching.split_off(&next); + heads.filled = heads.filled.split_off(&next); + } } /// The lowest servable group past the last one returned, walking off everything the @@ -7647,9 +7654,7 @@ impl Cursor { if let Some(misses) = &mut self.misses { misses.take_filled(group.sequence); } - if let Some(heads) = &mut self.heads { - heads.filled.remove(&group.sequence); - } + self.forget_heads_below(self.next_sequence); // The delivery commits everything the seek stepped over to reach this group. self.commit_seek_stale(self.next_sequence.unwrap_or(u64::MAX)); group.cache_refresh(); From 1f0121c484006bfa1448f6bc79c97558e2a61303 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 10:59:20 -0800 Subject: [PATCH 06/20] fix(net): a bounded moq-transport request learns the edge before subscribing A first request whose ranges all end asks TRACK_STATUS, as a fetch does, so a read of history below the reported Largest Object is filled by FETCH and never SUBSCRIBEs, which a finished track would refuse. One reaching past the edge subscribes once the status says so. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 10 +- rs/moq-net/tests/integration/fetch_only.rs | 6 +- rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/range_read.rs | 165 ++++++++++++++++++ .../tests/integration/subscribe_ranges.rs | 24 ++- 5 files changed, 191 insertions(+), 15 deletions(-) create mode 100644 rs/moq-net/tests/integration/range_read.rs diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 826897ba137..b070a5061ac 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2880,12 +2880,14 @@ impl Subscriber { // Demand with nobody subscribing (fetches, or a TRACK_STATUS downstream) learns the // track from TRACK_STATUS rather than a SUBSCRIBE: a finished track refuses one, and - // one made only to learn the track races the fetches it was for. + // one made only to learn the track races the fetches it was for. So does a bounded + // subscription, which may read only history below the Largest Object the status + // reports, as a fetch would: `linger` subscribes once it reaches past that. let mut target = match request.subscription() { subscription - if subscription - .as_ref() - .is_none_or(|subscription| subscription.ranges.is_empty()) => + if subscription.as_ref().is_none_or(|subscription| { + subscription.ranges.is_empty() || subscription.start().is_some() && subscription.end().is_some() + }) => { let Some(idle) = self .track_status(&broadcast_path, &track_name, request, &mut group_fetches, &mut gate) diff --git a/rs/moq-net/tests/integration/fetch_only.rs b/rs/moq-net/tests/integration/fetch_only.rs index 00abf4d885c..3fc0cf4a702 100644 --- a/rs/moq-net/tests/integration/fetch_only.rs +++ b/rs/moq-net/tests/integration/fetch_only.rs @@ -247,7 +247,6 @@ async fn bounded_direct(version: &str) { let remote = resolve(&client).await; let copy = remote.track("video").unwrap(); - copy.info().await.expect("TRACK_STATUS resolves the track"); let mut sub = subscribe_history(©).await; assert_eq!(next_frames(&mut sub).await, Some(frames(1)), "{version}"); assert_eq!(next_frames(&mut sub).await, None, "{version}: the read ends"); @@ -259,8 +258,9 @@ async fn bounded_direct(version: &str) { drop((sub, copy, remote, pair, broadcast, client, publisher)); } -/// A copy the session holds no subscription for is unfed: a bounded read of the history -/// below the publisher's Largest Object fetches its holes at once, never subscribing. +/// A bounded read learns the track from TRACK_STATUS, and of the history below the +/// publisher's Largest Object, which a finished track's SUBSCRIBE would refuse, fetches its +/// holes at once, never subscribing. #[kio::test] async fn a_bounded_read_of_history_fetches_without_subscribing() { let mut failures = Vec::new(); diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index c92b429c3ac..5076f686ed9 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -44,6 +44,7 @@ mod model; mod multi_cdn; mod partial_group; mod quiet_catalog; +mod range_read; mod range_anchors; mod received_rewind; mod rejoin; diff --git a/rs/moq-net/tests/integration/range_read.rs b/rs/moq-net/tests/integration/range_read.rs new file mode 100644 index 00000000000..cee8209e9a5 --- /dev/null +++ b/rs/moq-net/tests/integration/range_read.rs @@ -0,0 +1,165 @@ +#![cfg(feature = "async")] + +//! A one-range read is how a past group is fetched: it gets each group of its range, then +//! ends, on every wire, from the publisher directly or through a relay. A range reaching +//! past the live edge ends once the groups up to its end arrive. + +use crate::support; + +use std::time::Duration; + +use moq_net::track::{Order, Subscription}; +use moq_net::{Hop, Timestamp, Version}; +use support::harness::{MockConnectOptions, connect_mock}; + +const TIMEOUT: Duration = Duration::from_secs(5); + +fn produce_origin(hop: u64) -> moq_net::origin::Producer { + let (producer, driver) = moq_net::origin::Producer::new(moq_net::origin::Config::new(Hop::new(hop).unwrap())); + support::harness::spawn(driver); + producer +} + +fn write_group(track: &mut moq_net::track::Producer, sequence: u64) { + let mut group = track.append_group().unwrap(); + assert_eq!(group.sequence, sequence); + for frame in 0..2u64 { + let at = Timestamp::from_millis(sequence * 100 + frame).unwrap(); + group.write_frame(at, payload(sequence, frame)).unwrap(); + } + group.finish().unwrap(); +} + +fn payload(sequence: u64, frame: u64) -> Vec { + format!("{sequence}-{frame}").into_bytes() +} + +/// Each group a one-range read of `range` gets, read whole, until it ends. +async fn read(sub: &mut moq_net::track::Subscriber) -> Vec { + let mut read = Vec::new(); + while let Some(mut group) = kio::clock::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("the read neither ended nor got a group") + .expect("recv group") + { + let mut frames = Vec::new(); + while let Some(frame) = kio::clock::timeout(TIMEOUT, group.read_frame()) + .await + .expect("read timed out") + .expect("read frame") + { + frames.push(frame.payload.to_vec()); + } + assert_eq!(frames, [payload(group.sequence, 0), payload(group.sequence, 1)]); + read.push(group.sequence); + } + read +} + +/// A live track with groups 0 to 2 written, read on `version` through a relay hop when +/// `relay` is set, as the reader's broadcast and the publisher's track. +async fn fixture( + version: Version, + relay: bool, +) -> ( + moq_net::broadcast::Consumer, + moq_net::track::Producer, + impl Sized, +) { + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let mut track = broadcast + .create_track("video", moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + for sequence in 0..3 { + write_group(&mut track, sequence); + } + + let middle = produce_origin(2); + let client = produce_origin(3); + let mut sessions = Vec::new(); + if relay { + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(middle.clone()); + sessions.push(connect_mock(options).await); + } + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(match relay { + true => middle.consume(), + false => publisher.consume(), + }); + options.client_subscribe = Some(client.clone()); + sessions.push(connect_mock(options).await); + + let remote = kio::clock::timeout(TIMEOUT, client.consume().follow("bcast", None).unwrap().available()) + .await + .expect("resolve timeout") + .expect("broadcast resolves"); + (remote, track, (sessions, broadcast, publisher, middle, client)) +} + +fn one_range(groups: std::ops::Range) -> Subscription { + Subscription::default() + .with_range(groups) + .with_max_delay(None) + .with_order(Order::Ascending) +} + +async fn history(version: Version, relay: bool, finished: bool) { + let (remote, track, _held) = fixture(version, relay).await; + if finished { + track.finish().unwrap(); + } + let mut sub = remote.track("video").unwrap().subscribe(one_range(1..2)).await.unwrap(); + assert_eq!(read(&mut sub).await, [1], "{version} relay={relay} finished={finished}"); +} + +/// A range wholly below the live edge reads its group and ends, live or finished. +#[kio::test] +async fn a_range_of_history_reads_its_groups_and_ends() { + let mut failures = Vec::new(); + for version in support::every_version() { + for relay in [false, true] { + for finished in [false, true] { + if kio::clock::sim::spawn(history(version, relay, finished)).await.is_err() { + failures.push((version, relay, finished)); + } + } + } + } + assert!(failures.is_empty(), "failed: {failures:?}"); +} + +async fn straddling(version: Version, relay: bool) { + let (remote, mut track, _held) = fixture(version, relay).await; + let mut sub = remote.track("video").unwrap().subscribe(one_range(1..5)).await.unwrap(); + let reading = kio::clock::sim::spawn(async move { read(&mut sub).await }); + kio::clock::sleep(Duration::from_millis(50)).await; + for sequence in 3..6 { + write_group(&mut track, sequence); + } + // Arrival order: an older wire sends a backlog in no particular order. + let mut read = reading.await.unwrap(); + read.sort_unstable(); + assert_eq!(read, [1, 2, 3, 4], "{version} relay={relay}"); +} + +/// A range from below the live edge to past it reads the history and the live groups up +/// to its end, then ends. Draft-18 has no bounded SUBSCRIBE, so it refuses one. +#[kio::test] +async fn a_range_across_the_live_edge_reads_up_to_its_end() { + let mut failures = Vec::new(); + for version in support::every_version() + .into_iter() + .filter(|version| version.to_string() != "moq-transport-18") + { + for relay in [false, true] { + if kio::clock::sim::spawn(straddling(version, relay)).await.is_err() { + failures.push((version, relay)); + } + } + } + assert!(failures.is_empty(), "failed: {failures:?}"); +} diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index c64ae7c4e66..ec42758b363 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -290,22 +290,26 @@ async fn initial_mixed_ranges_keep_the_absolute_history() { async fn draft22_updates_both_bounds_across_cached_groups() { for relay in [false, true] { let mut fixture = range_fixture(relay).await; + // Reaching the live group 5, so the copy subscribes: history alone is fetched. let initial = Subscription::default() - .with_range(2..4) + .with_ranges([Range::groups(2..4), Range::groups(5..6)]) .with_max_delay(None) .with_order(moq_net::track::Order::Ascending); let mut reader = subscribe(&fixture.remote, initial.clone()).await; - let mut seen = [next(&mut reader).await.unwrap(), next(&mut reader).await.unwrap()]; + let mut seen = Vec::new(); + for _ in 0..3 { + seen.push(next(&mut reader).await.unwrap()); + } seen.sort_unstable(); - assert_eq!(seen, [2, 3]); + assert_eq!(seen, [2, 3, 5]); reader.update(initial.clone().with_range(0..6)).unwrap(); let mut got = Vec::new(); - for _ in 0..4 { + for _ in 0..3 { let seen = next(&mut reader).await; got.push(seen.expect("a widened group never arrived")); } got.sort_unstable(); - assert_eq!(got, [0, 1, 4, 5], "relay={relay}"); + assert_eq!(got, [0, 1, 4], "relay={relay}"); reader.update(initial.clone().with_range(4..5)).unwrap(); kio::clock::timeout( TIMEOUT, @@ -348,14 +352,18 @@ async fn draft22_updates_both_bounds_across_cached_groups() { async fn draft22_resolves_cached_time_ends() { for relay in [false, true] { let mut fixture = range_fixture(relay).await; + // Reaching the live group 5, so the copy subscribes: history alone is fetched. let initial = Subscription::default() - .with_range(2..4) + .with_ranges([Range::groups(2..4), Range::groups(5..6)]) .with_max_delay(None) .with_order(moq_net::track::Order::Ascending); let mut reader = subscribe(&fixture.remote, initial.clone()).await; - let mut seen = [next(&mut reader).await.unwrap(), next(&mut reader).await.unwrap()]; + let mut seen = Vec::new(); + for _ in 0..3 { + seen.push(next(&mut reader).await.unwrap()); + } seen.sort_unstable(); - assert_eq!(seen, [2, 3]); + assert_eq!(seen, [2, 3, 5]); let unknown = initial.clone().with_ranges([Range { start: moq_net::track::Anchor::Absolute(0), end: Some(moq_net::track::Anchor::Time(Timestamp::from_millis(10_000).unwrap())), From 3f5dd1693e85821b62b1cee018f4d7686dfbf884 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 11:07:30 -0800 Subject: [PATCH 07/20] docs(quest): rewrite fetch-range to what remains after this attempt Co-Authored-By: Claude Opus 5.5 --- quest/m1/subscribe-ranges/fetch-range.md | 89 +++++++++++++----------- rs/moq-net/MIGRATE.md | 4 +- 2 files changed, 51 insertions(+), 42 deletions(-) diff --git a/quest/m1/subscribe-ranges/fetch-range.md b/quest/m1/subscribe-ranges/fetch-range.md index 64763b9c374..3336c580c87 100644 --- a/quest/m1/subscribe-ranges/fetch-range.md +++ b/quest/m1/subscribe-ranges/fetch-range.md @@ -9,15 +9,6 @@ page, and `moq fetch` through `moq_relay::fetch_group`. ## Plan -Checkpoint 2026-11-02 -([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): no remaining -model, API, or consumer changes implemented. On main `f8c608a24b`, -`quest gate nix develop --command just rs test -p moq-net -E 'test(bounded)'` -exited 1 before compilation: mbx could not launch Cargo (`Argument list too -long (os error 7)`). Resume with working validation; the remaining scope and -decisions below still apply. No validation bypass or upstream mbx work is part -of this claim. - Split out of dynamic range requests, which replaced `requested_group` with `requested_fill`, by the maintainer on 2026-10-20 ([moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so each PR @@ -27,34 +18,29 @@ the questions decided below and landed only the `track_range_filling` benchmark. The second attempt ([moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)) landed the bounded-read end on a plain cursor, the parking wire publishers, the cached-backfill rule, the bounded miss grace, and the unfed moq-transport -copy; what remains is below. +copy. The third ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)) +landed the end of a front's bounded read, the head fill, and the first bounded +moq-transport request; what remains is the API removal, its consumers, and the +legacy demand questions below. -- **Ending a bounded read** (decided 2026-10-20). `recv_group` returns `None` - once every sequence in a bounded window is delivered, dropped, stale, or - unfillable. Landed for a track's own cache: a `with_range` cap never ends a - read, since it may rise again. A front's logical track (a routed track, - `model/resume.rs`) still parks, because each copy's reader parks and the - routes judge the end. Its `Delivered` counts what is no longer owed as - handed out (`track::Subscriber::skip_ordered`), so it cannot account for the - window alone, and `resume_model` asserts a reader never ends before a route - declares an end, which ending there has to change. `Ok(None)` before any group arrives is a miss, which the - moq-ffi fetch wrapper reports as `NotFound`; after one, it is the range's - end. A one-range read surfaces no `NotFetchable` or `Old` result, and a +- **Ending a bounded read** (decided 2026-10-20; landed). `recv_group` returns + `None` once every sequence in a bounded window is delivered, dropped, stale, or + unfillable, on a track's own cache and on a front's logical track alike: the + serving copy's cursor judges the window from its resume point, a replaced or + backfill copy that may still deliver keeps the read open, and so does a group + in range the local floor or cap keeps out. A `with_range` cap never ends a + read. Still to do with the API: `Ok(None)` before any group arrives is a miss, + which the moq-ffi fetch wrapper reports as `NotFound`; after one, it is the + range's end. A one-range read surfaces no `NotFetchable` or `Old` result, and a peer's reset with either names the group dropped. Every fetch boundary already treats `NotFetchable` as not found (relay HTTP 404, hls `is_cache_miss`, moq-ffi `map_fetch_error`, moq-c `NOT_FOUND`); a fetched - `Old` becomes a miss too, where relay HTTP answers 500 and moq-c reports - `OLD` today. Both stay as wire stream errors, and `Old` still aborts a cut - group mid-read. The Impact bullet says how to migrate each affected package. -- A one-range subscription for a cached live group missing the frames its - range starts at needs a head fill. Frame bounds - ([moq-dev/moq#6129](https://github.com/moq-dev/moq/pull/6129)) hand such a - group out positioned at the asked frame, so reading the missing head returns - `Error::Lagged` rather than the group being skipped (maintainer, - 2026-10-20). Only `fetch_group` requests a head fill today, so the one-range - read has to request it instead of letting `Lagged` reach the caller. - `fill::Ask` already carries a start frame, so the miss judge can count a - headless slot as a hole for a bounded window. + `Old` becomes a miss too, where moq-c reports `OLD` today. Both stay as wire + stream errors, and `Old` still aborts a cut group mid-read. The Impact bullet + says how to migrate each affected package. +- **A bounded read fills a missing head** (landed). A bounded window hands out a + cached live group missing its first frames only once a fill answered it from + frame 0, as `fetch_group` asks, and gives the group up when none can. - **Wire publishers keep parking** (landed). Every wire publisher reads its subscription through `track::Subscriber::parked`: the IETF publisher and lite publishers before lite-07 keep parking on a bounded downstream @@ -177,14 +163,35 @@ copy; what remains is below. is one range FETCH on moq-transport, and per-group FETCH is lite-only, until [lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) land. A bounded upstream SUBSCRIBE accounted by SUBSCRIBE_START and SUBSCRIBE_DROP was - rejected: it works on lite-05 and later only. Landed for a lingering - moq-transport copy whose subscription lies wholly below the reported Largest - Object (the unfed copy above). Still to do: a first request with a bounded - subscription, which SUBSCRIBEs before any TRACK_STATUS names an edge; a - subscription only partly below the edge; and lite before lite-07. A - subscription to a copy no SUBSCRIBE accepts waits for the track's info - today, so this also needs a one-range read to resolve from the info its fill - installs. + rejected: it works on lite-05 and later only. Landed for moq-transport: a + copy no SUBSCRIBE feeds (the unfed copy above), and a first request whose + ranges all have an absolute start and end, which asks TRACK_STATUS first and + subscribes only once a range reaches the reported Largest Object. + `range_read.rs` reads history and a range across the live edge on every + wire, direct and relayed; draft-18 refuses the latter, having no bounded + SUBSCRIBE (`subscribe_join`). Open, found migrating the moq-net integration + tests onto one-range reads ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): + - Lite before lite-07 tells no live edge without a SUBSCRIBE, so a one-range + read of history there SUBSCRIBEs where `fetch_group` FETCHes: + `fetch_pipeline` (the FETCH sent with TRACK), `fetch_fanout`, + `fetch_cancel`, and `catalog_handover`'s fetch cases assert the FETCH. + - A moq-transport read of the group at the reported Largest Object reaches + "the group the publisher may still be writing" (`wants_feed`), so it + subscribes: draft-18 refuses that, and a finished track's SUBSCRIBE is + refused (`fetch_only`, `compress::ietf_fetch_keeps_the_stored_form`). The + relay's `fetch_group(None)` reads exactly that group. + - Our moq-transport publishers answer only a one-group FETCH, so a run of + missing history groups read from one of them is refused and named dropped + (`subscribe_ranges`'s draft-22 cases now open with a range reaching the + Largest Object), until [hole markers](/quest/m2/ietf-hole-marker.md). + - Fetch-only behavior to carry over or drop: a fetch keeps both sessions busy + (`session_idle`), a session close cancels a pending fetch from either side + (`subscription_end_integrity`), a pre-lite-05 fetch is served from a feed + opened with it and an unfed fetch is a miss (`fetch_from_feed`), an + abandoned fetch reaches the publisher and a refetch within the linger stays + on the relay (`fetch_cancel`), an untimed fetched frame arrives untimed + (`untimed`), and a fetched datagram is `NotFetchable` (`datagram`, now a + miss by the rule above). - **The fill path goes linear first** (maintainer, 2026-10-25). One-range reads put every past read on the fill path, which `track_range_filling` measured as superlinear in range count and span. It is flat since diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 7bc82a99c30..1c756aff244 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -7,11 +7,13 @@ How to update your code for each breaking change, newest first. ### A bounded subscription ends once its ranges are read When every one of a subscription's `ranges` has an end, `track::Subscriber::recv_group` and `track::Ordered::next_group` return `None` once each group in them was handed out, dropped, skipped as stale, or given up as unfillable, instead of waiting for an update to widen the ranges. -This holds for a track read from its own producer's cache. A track read through an origin's routes, such as a remote broadcast's, still waits past its ranges for now, so a reader there stops once it has the groups it asked for rather than waiting for `None`. +This holds for a track read through an origin's routes, such as a remote broadcast's, too: it ends once no route it left may still deliver a group in range. A reader that wants to widen its ranges later keeps one open, such as `Range::groups(n..)`, and narrows its reads with `with_range`, whose cap never ends a read. A group another reader's fetch or fill cached is now handed to every subscriber whose ranges hold it, not only fetches. A missing group the live feed may still deliver is waited for at most one second before it is asked of a fill or named dropped, when neither the readers' `max_delay` nor the track's max age bounds the wait. Before, a reader with `max_delay: None` on a track with no max age waited for it until the track ended. Over moq-transport, a subscription to a copy the session holds no upstream subscription for, such as one only fetched so far, whose ranges all end below the publisher's reported Largest Object, is served by FETCH without subscribing upstream. Each missing group is asked at once and a refusal is final, since nothing else would deliver it. +A first request whose ranges all have an absolute start and end asks TRACK_STATUS before it subscribes, so one wholly below the Largest Object is served the same way. Since moq-transport publishers here answer only a one-group FETCH, such a read of a run of missing groups from one of them is refused and names the run dropped; keep a range that reaches the Largest Object to have it subscribed instead. +A cached group missing its first frames, such as one a relay joined midway, is handed to a bounded subscription only once a fill answered it from its first frame, and is given up when none can, rather than read as `Error::Lagged`. ### `broadcast::Demand` reads like `track::Demand` From 83fdffd3fad14ff7fcd64bf3b0a9611834ddef5e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 11:10:15 -0800 Subject: [PATCH 08/20] style: format Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/MIGRATE.md | 2 +- rs/moq-net/src/model/track.rs | 38 +++++++++++++--------- rs/moq-net/tests/integration/main.rs | 2 +- rs/moq-net/tests/integration/range_read.rs | 11 +++---- 4 files changed, 30 insertions(+), 23 deletions(-) diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 1c756aff244..33ccedcf418 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -12,7 +12,7 @@ A reader that wants to widen its ranges later keeps one open, such as `Range::gr A group another reader's fetch or fill cached is now handed to every subscriber whose ranges hold it, not only fetches. A missing group the live feed may still deliver is waited for at most one second before it is asked of a fill or named dropped, when neither the readers' `max_delay` nor the track's max age bounds the wait. Before, a reader with `max_delay: None` on a track with no max age waited for it until the track ended. Over moq-transport, a subscription to a copy the session holds no upstream subscription for, such as one only fetched so far, whose ranges all end below the publisher's reported Largest Object, is served by FETCH without subscribing upstream. Each missing group is asked at once and a refusal is final, since nothing else would deliver it. -A first request whose ranges all have an absolute start and end asks TRACK_STATUS before it subscribes, so one wholly below the Largest Object is served the same way. Since moq-transport publishers here answer only a one-group FETCH, such a read of a run of missing groups from one of them is refused and names the run dropped; keep a range that reaches the Largest Object to have it subscribed instead. +A first request whose ranges all have an absolute start and end asks TRACK\_STATUS before it subscribes, so one wholly below the Largest Object is served the same way. Since moq-transport publishers here answer only a one-group FETCH, such a read of a run of missing groups from one of them is refused and names the run dropped; keep a range that reaches the Largest Object to have it subscribed instead. A cached group missing its first frames, such as one a relay joined midway, is handed to a bounded subscription only once a fill answered it from its first frame, and is given up when none can, rather than read as `Error::Lagged`. ### `broadcast::Demand` reads like `track::Demand` diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c2a953e606c..a9396ccf589 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7438,17 +7438,19 @@ impl Cursor { fn poll_heads(&mut self, waiter: &kio::Waiter) { let Some(heads) = &mut self.heads else { return }; let mut given_up = Vec::new(); - heads.fetching.retain(|sequence, fetching| match kio::Task::poll(fetching, waiter) { - Poll::Pending => true, - Poll::Ready(Ok(group)) => { - heads.filled.insert(*sequence, group); - false - } - Poll::Ready(Err(_)) => { - given_up.push(*sequence..sequence.saturating_add(1)); - false - } - }); + heads + .fetching + .retain(|sequence, fetching| match kio::Task::poll(fetching, waiter) { + Poll::Pending => true, + Poll::Ready(Ok(group)) => { + heads.filled.insert(*sequence, group); + false + } + Poll::Ready(Err(_)) => { + given_up.push(*sequence..sequence.saturating_add(1)); + false + } + }); if given_up.is_empty() { return; } @@ -7622,7 +7624,10 @@ impl Cursor { let sequence = group.sequence; if self.heads.as_ref().is_none_or(|heads| { !heads.fetching.contains_key(&sequence) && !heads.filled.contains_key(&sequence) - }) && self.misses.as_ref().is_none_or(|misses| misses.gone(sequence).is_none()) + }) && self + .misses + .as_ref() + .is_none_or(|misses| misses.gone(sequence).is_none()) { self.ask_head(sequence); } @@ -7630,7 +7635,11 @@ impl Cursor { match self.heads.as_ref().and_then(|heads| heads.filled.get(&sequence)) { Some(head) => head.clone(), // Given up: past it, as past any group no fill can serve. - None if self.misses.as_ref().is_some_and(|misses| misses.gone(sequence).is_some()) => { + None if self + .misses + .as_ref() + .is_some_and(|misses| misses.gone(sequence).is_some()) => + { floor = sequence.saturating_add(1); continue; } @@ -17326,8 +17335,7 @@ mod test { let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); live.start_at(1).unwrap(); - live.write_frame(None, bytes::Bytes::from_static(b"delta")) - .unwrap(); + live.write_frame(None, bytes::Bytes::from_static(b"delta")).unwrap(); live.finish().unwrap(); framed(&producer, 1, 1).finish().unwrap(); diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index 5076f686ed9..1f02fc09f42 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -44,8 +44,8 @@ mod model; mod multi_cdn; mod partial_group; mod quiet_catalog; -mod range_read; mod range_anchors; +mod range_read; mod received_rewind; mod rejoin; mod relay_upstream_close; diff --git a/rs/moq-net/tests/integration/range_read.rs b/rs/moq-net/tests/integration/range_read.rs index cee8209e9a5..eef2f01ffec 100644 --- a/rs/moq-net/tests/integration/range_read.rs +++ b/rs/moq-net/tests/integration/range_read.rs @@ -61,15 +61,14 @@ async fn read(sub: &mut moq_net::track::Subscriber) -> Vec { async fn fixture( version: Version, relay: bool, -) -> ( - moq_net::broadcast::Consumer, - moq_net::track::Producer, - impl Sized, -) { +) -> (moq_net::broadcast::Consumer, moq_net::track::Producer, impl Sized) { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); let mut track = broadcast - .create_track("video", moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI)) + .create_track( + "video", + moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI), + ) .unwrap(); broadcast.announce(Default::default()).unwrap(); for sequence in 0..3 { From 4070d495f4a14f3f048042ec965887e6051c6ec7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 11:14:48 -0800 Subject: [PATCH 09/20] test(moq-c): keep a read that widens its range later open A read whose ranges all end now ends once it read them on a routed track too, so the update tests hold an open range far ahead. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 59 +++++++++++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index e1cdba200a6..eb2c2df728d 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2196,19 +2196,36 @@ fn raw_track_subscription_options_and_update() { let consume = request_broadcast(origin, path); let frame_cb = Callback::new(); - let ranges = [moq_range { - start: moq_anchor { - kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, - group: 1, - timestamp: moq_timestamp::default(), + // A read whose ranges all end ends once it read them, so an open range far ahead keeps + // this one open for the update. + let ranges = [ + moq_range { + start: moq_anchor { + kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, + group: 1, + timestamp: moq_timestamp::default(), + }, + end: moq_anchor { + kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, + group: 2, + timestamp: moq_timestamp::default(), + }, + end_present: true, }, - end: moq_anchor { - kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, - group: 2, - timestamp: moq_timestamp::default(), + moq_range { + start: moq_anchor { + kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, + group: 100, + timestamp: moq_timestamp::default(), + }, + end: moq_anchor { + kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, + group: 0, + timestamp: moq_timestamp::default(), + }, + end_present: false, }, - end_present: true, - }]; + ]; let subscription = moq_subscription { priority: 5, max_delay_us: 25_000, @@ -2500,12 +2517,20 @@ fn raw_track_relative_update_counts_from_the_track_edge() { publish(b"zero"); let consume = request_broadcast(origin, path); - // Group 0 only: the reader's cap sits below where the track will be. - let first = [moq_range { - start: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 0), - end: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 1), - end_present: true, - }]; + // Group 0 only: the reader's cap sits below where the track will be. A read whose + // ranges all end ends once it read them, so an open range far ahead keeps it open. + let first = [ + moq_range { + start: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 0), + end: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 1), + end_present: true, + }, + moq_range { + start: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 100), + end: anchor(moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE, 0), + end_present: false, + }, + ]; let frame_cb = Callback::new(); let consumer = id(unsafe { moq_consume_track( From 559da3dfe51dc9c810659fe1a92ba6cf956a638e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 11:32:25 -0800 Subject: [PATCH 10/20] fix(net): hand out a filled head only while the reader's bounds admit it Poll the heads still out once per read, and each new one as it is asked, rather than every pending head after each ask. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 73 +++++++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index a9396ccf589..18d900496e0 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7382,8 +7382,7 @@ impl Cursor { } if self.lacks_head(&consumer) { self.advance_arrival(consumer.sequence, taken); - self.ask_head(consumer.sequence); - self.poll_heads(waiter); + self.ask_head(consumer.sequence, waiter); continue; } return Poll::Ready(Ok(Some(Peeked { @@ -7418,8 +7417,9 @@ impl Cursor { self.filter.window.end().is_some() && group.first_frame() > 0 } - /// Ask a fill for the head of `sequence`, as a fetch from frame 0 would. - fn ask_head(&mut self, sequence: u64) { + /// Ask a fill for the head of `sequence`, as a fetch from frame 0 would, taking in an + /// answer already at hand. + fn ask_head(&mut self, sequence: u64, waiter: &kio::Waiter) { let asking = self.subscription.read().clone(); let request = FetchOptions { options: group::Fetch { @@ -7429,14 +7429,27 @@ impl Cursor { }, end: None, }; - let fetching = Fetching::cached_or_queued(self.state.clone(), sequence, request, stats::Scope::default()); - self.heads.get_or_insert_default().fetching.insert(sequence, fetching); + let mut fetching = Fetching::cached_or_queued(self.state.clone(), sequence, request, stats::Scope::default()); + let heads = self.heads.get_or_insert_default(); + match kio::Task::poll(&mut fetching, waiter) { + Poll::Pending => { + heads.fetching.insert(sequence, fetching); + } + Poll::Ready(Ok(group)) => { + heads.filled.insert(sequence, group); + } + Poll::Ready(Err(_)) => self.give_up_heads(std::iter::once(sequence..sequence.saturating_add(1))), + } } - /// Take in the heads answered, parking `waiter` on those still out. A head no fill can - /// serve gives its group up, as a refused miss is. + /// Take in the heads answered, parking `waiter` on those still out, once per read. A + /// head the reader's bounds no longer admit is let go: a widening offers its group again. fn poll_heads(&mut self, waiter: &kio::Waiter) { - let Some(heads) = &mut self.heads else { return }; + let Some(mut heads) = self.heads.take() else { return }; + let floor = self.floor(); + let admitted = |sequence: &u64| *sequence >= floor && self.admits(*sequence); + heads.fetching.retain(|sequence, _| admitted(sequence)); + heads.filled.retain(|sequence, _| admitted(sequence)); let mut given_up = Vec::new(); heads .fetching @@ -7451,7 +7464,14 @@ impl Cursor { false } }); - if given_up.is_empty() { + self.heads = Some(heads); + self.give_up_heads(given_up); + } + + /// Give up the groups whose head no fill can serve, as a refused miss is. + fn give_up_heads(&mut self, given_up: impl IntoIterator>) { + let mut given_up = given_up.into_iter().peekable(); + if given_up.peek().is_none() { return; } let misses = self.misses.get_or_insert_with(Box::default); @@ -7553,6 +7573,7 @@ impl Cursor { waiter: &kio::Waiter, ) -> Poll>> { let end = self.end_sequence; + self.poll_heads(waiter); // Where the gap below the candidate starts: groups stepped over as stale are cached. let mut from = floor; let group = loop { @@ -7629,9 +7650,8 @@ impl Cursor { .as_ref() .is_none_or(|misses| misses.gone(sequence).is_none()) { - self.ask_head(sequence); + self.ask_head(sequence, waiter); } - self.poll_heads(waiter); match self.heads.as_ref().and_then(|heads| heads.filled.get(&sequence)) { Some(head) => head.clone(), // Given up: past it, as past any group no fill can serve. @@ -17325,6 +17345,35 @@ mod test { assert!(ended, "the read ends with its range"); } + /// A head answered after the reader's ranges moved off its group is not handed out. + #[kio::test] + #[cfg(feature = "async")] + async fn a_head_answered_outside_the_ranges_is_not_handed_out() { + let producer = track_producer("test", Info::default()); + let dynamic = producer.requests(); + + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(None, bytes::Bytes::from_static(b"delta")).unwrap(); + live.finish().unwrap(); + framed(&producer, 1, 1).finish().unwrap(); + + let mut sub = producer.subscribe(replay().with_range(0..2)); + let group = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(group.sequence, 1); + let request = dynamic.requested_fill_group().now_or_never().unwrap().unwrap(); + assert_eq!(request.sequence(), 0); + + sub.update(replay().with_range(1..2)).unwrap(); + let mut head = request.accept(Info::default()).unwrap(); + head.write_frame(None, bytes::Bytes::from_static(b"snapshot")).unwrap(); + head.finish().unwrap(); + assert!( + matches!(sub.recv_group().now_or_never(), Some(Ok(None))), + "the narrowed read ends without group 0" + ); + } + /// An ordered bounded read whose head no fill serves gives that group up and reads on, /// rather than handing it out to lag. #[kio::test] From f10403d25bc27fab9782bb4bed22f536ce70e249 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 12:12:51 -0800 Subject: [PATCH 11/20] test(net): name the route instance in the new resume cases after merging main Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/resume_model.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/src/model/resume_model.rs b/rs/moq-net/src/model/resume_model.rs index 9638a25e9c8..73e421e5803 100644 --- a/rs/moq-net/src/model/resume_model.rs +++ b/rs/moq-net/src/model/resume_model.rs @@ -1105,12 +1105,12 @@ fn regressions() { // fill can complete reads them and ends with the track. Case { ops: vec![ - Op::Up { epoch: 0, slot: 1 }, + Op::Up { instance: 0, slot: 1 }, Op::Join { reader: 1, spec: spec(false, Budget::Hour, None, false), }, - Op::Up { epoch: 0, slot: 2 }, + Op::Up { instance: 0, slot: 2 }, Op::Join { reader: 0, spec: spec(true, Budget::Hour, None, false), @@ -1120,7 +1120,7 @@ fn regressions() { range: Some((8, 11)), }, Op::Write { - epoch: 0, + instance: 0, slot: 1, group: Some(8), frames: 1, @@ -1137,12 +1137,12 @@ fn regressions() { spec: spec(false, Budget::Hour, None, false), }, Op::Write { - epoch: 0, + instance: 0, slot: 0, group: Some(6), frames: 1, }, - Op::Up { epoch: 0, slot: 1 }, + Op::Up { instance: 0, slot: 1 }, Op::Ranges { reader: 1, range: Some((0, 8)), From 0dde22bb3517779825b08cb765d672aee2bfae0e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 12:52:16 -0800 Subject: [PATCH 12/20] docs(quest): record the 2026-11-02 fetch-range answers and the blockers found removing fetch_group Co-Authored-By: Claude Opus 5.5 --- quest/m1/subscribe-ranges/fetch-range.md | 80 +++++++++++++++++++----- 1 file changed, 66 insertions(+), 14 deletions(-) diff --git a/quest/m1/subscribe-ranges/fetch-range.md b/quest/m1/subscribe-ranges/fetch-range.md index 3336c580c87..56bc6f40a75 100644 --- a/quest/m1/subscribe-ranges/fetch-range.md +++ b/quest/m1/subscribe-ranges/fetch-range.md @@ -169,21 +169,42 @@ legacy demand questions below. subscribes only once a range reaches the reported Largest Object. `range_read.rs` reads history and a range across the live edge on every wire, direct and relayed; draft-18 refuses the latter, having no bounded - SUBSCRIBE (`subscribe_join`). Open, found migrating the moq-net integration - tests onto one-range reads ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): - - Lite before lite-07 tells no live edge without a SUBSCRIBE, so a one-range - read of history there SUBSCRIBEs where `fetch_group` FETCHes: - `fetch_pipeline` (the FETCH sent with TRACK), `fetch_fanout`, - `fetch_cancel`, and `catalog_handover`'s fetch cases assert the FETCH. - - A moq-transport read of the group at the reported Largest Object reaches - "the group the publisher may still be writing" (`wants_feed`), so it - subscribes: draft-18 refuses that, and a finished track's SUBSCRIBE is - refused (`fetch_only`, `compress::ietf_fetch_keeps_the_stored_form`). The - relay's `fetch_group(None)` reads exactly that group. - - Our moq-transport publishers answer only a one-group FETCH, so a run of + SUBSCRIBE (`subscribe_join`). Found migrating the moq-net integration tests + onto one-range reads, and settled by the maintainer on 2026-11-02 + ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): + - **Scope.** ✅ Keep going in one PR: remove the public `fetch_group` and + migrate its callers, finishing this quest. Alternative: land the bounded + read changes first and remove the API in a later PR. + - **Past-group reads on lite-05/06.** Lite before lite-07 tells no live edge + without a SUBSCRIBE, so a one-range read of history there SUBSCRIBEs where + `fetch_group` FETCHes: `fetch_pipeline` (the FETCH sent with TRACK), + `fetch_fanout`, `fetch_cancel`, and `catalog_handover`'s fetch cases + assert the FETCH. + - ✅ (a) Accept the bounded SUBSCRIBE before lite-07 and rewrite those four + tests. + - (b) Serve a fully bounded absolute subscription fetch-only before + lite-07, keeping today's wire behavior, though a range past the live + edge ends short. + - **Newest group on moq-transport.** A read of the group at the reported + Largest Object reaches "the group the publisher may still be writing" + (`wants_feed`), so it subscribes. Draft-18 refuses that, and so does a + finished track (`fetch_only`, `compress::ietf_fetch_keeps_the_stored_form`). + The relay's newest-group read (`moq_relay::fetch_group(None)`) reads + exactly that group. + - ✅ Read it as live with a SUBSCRIBE, with no special-case fallback, and + accept the draft-18 and finished-track refusals. "Whatever the simplest + option is, prob subscribe. I hate the IETF fetch/subscribe logic and we + should not agonize over making it correct." + - FETCH it. + - SUBSCRIBE while the track is live, FETCH once it ended. + - **Multi-group history between our moq-transport nodes.** Our + moq-transport publishers answer only a one-group FETCH, so a run of missing history groups read from one of them is refused and named dropped - (`subscribe_ranges`'s draft-22 cases now open with a range reaching the - Largest Object), until [hole markers](/quest/m2/ietf-hole-marker.md). + (`subscribe_ranges`'s draft-22 cases open with a range reaching the + Largest Object). + - ✅ Accept the refusal until [hole markers](/quest/m2/ietf-hole-marker.md) + let our publishers answer a range. + - Answer a multi-group FETCH now. - Fetch-only behavior to carry over or drop: a fetch keeps both sessions busy (`session_idle`), a session close cancels a pending fetch from either side (`subscription_end_integrity`), a pre-lite-05 fetch is served from a feed @@ -192,6 +213,37 @@ legacy demand questions below. on the relay (`fetch_cancel`), an untimed fetched frame arrives untimed (`untimed`), and a fetched datagram is `NotFetchable` (`datagram`, now a miss by the rule above). +- **Blockers found removing the API** (2026-11-02, on + [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)). Making + `track::Consumer::fetch_group` crate-private, which the wire publishers + still serve a FETCH through, and moving the relay, hls, and transcode onto + one-range reads surfaced three gaps: + - **Sequential one-range reads stall on lite-07.** On one session, a + one-range read after an earlier one on the same track can time out, + direct or relayed. Reading groups 1 then 2 stalls on 2, and 2, 1, 0 stalls + on 0, even after the copy's linger expires. Lite-06 and moq-transport pass. + It hangs hls's `a_live_fmp4_import_serves_segments_over_lite07`, which reads + a segment's groups one by one. To reproduce: in `range_read.rs`'s fixture + on lite-07, read `one_range(1..2)`, drop it, then read `one_range(2..3)`. + - **A local track asks no fill without a told edge.** A one-range read on a + local track asks its `Requests` handler for a missing group only below a + start the publisher declared (`track::Producer::start_at`). Writing a + newer group is not enough (`late_lower_group`). `fetch_group` asked at once. + So in-process reads of on-demand groups hang: moq-c group requests and + moq-ffi fills (`track_dynamic_serves_a_fetch_miss`, + `track_request_dynamic_survives_accept`, `fill_goes_unwanted_*`), and + transcode's rung, which reads its source and serves its output that way + (`a_group_nobody_reads_releases_its_fill`, + `retirement_waits_for_an_unclaimed_fetch`). moq-archive already declares + its edge, but moq-c and moq-ffi expose no `start_at`. + - **A group past the live edge waits.** A one-range read of a group the + live track has not reached yet waits for it, where `fetch_group`'s FETCH + was refused at once. `moq fetch --group 99` and the relay's + `/fetch?group=99` time out (HTTP 504 after 30 s) instead of answering 404. + - Keep the subscription open while its group is read. Dropping the + `track::Subscriber` after `recv_group` stalls a group still being written + on every wire, so each boundary that hands a group out (relay HTTP, + moq-ffi, hls, transcode) keeps the subscriber with it. - **The fill path goes linear first** (maintainer, 2026-10-25). One-range reads put every past read on the fill path, which `track_range_filling` measured as superlinear in range count and span. It is flat since From 4d5ec8789148a29fd0ce4ae706dfb85f072824b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 13:21:44 -0800 Subject: [PATCH 13/20] docs(quest): keep fetch_group public, record the lite-07 FETCH replacement, and trace the back-to-back hang Co-Authored-By: Claude Opus 5.5 --- quest/m1/subscribe-ranges/fetch-range.md | 107 ++++++++++++----------- 1 file changed, 58 insertions(+), 49 deletions(-) diff --git a/quest/m1/subscribe-ranges/fetch-range.md b/quest/m1/subscribe-ranges/fetch-range.md index 56bc6f40a75..e0b62d730b8 100644 --- a/quest/m1/subscribe-ranges/fetch-range.md +++ b/quest/m1/subscribe-ranges/fetch-range.md @@ -2,10 +2,10 @@ ## Goal -`fetch_group` is gone: every caller reads a past group through a one-range -subscription, which ends once its range is accounted for. That covers the -relay, moq-archive, hls, moq-ffi and every binding wrapper with its `doc/lib` -page, and `moq fetch` through `moq_relay::fetch_group`. +A one-range read works on every path, including back to back on one lite-07 +session. `track::Consumer::fetch_group` stays public as the single-group fetch +(maintainer, 2026-11-02), so its callers keep it: moq-c group requests, +moq-ffi fills, transcode, the relay's `/fetch`, `moq fetch`, and hls. ## Plan @@ -20,8 +20,8 @@ landed the bounded-read end on a plain cursor, the parking wire publishers, the cached-backfill rule, the bounded miss grace, and the unfed moq-transport copy. The third ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)) landed the end of a front's bounded read, the head fill, and the first bounded -moq-transport request; what remains is the API removal, its consumers, and the -legacy demand questions below. +moq-transport request. `fetch_group` now stays public (below), so what +remains is the lite-07 back-to-back hang. - **Ending a bounded read** (decided 2026-10-20; landed). `recv_group` returns `None` once every sequence in a bounded window is delivered, dropped, stale, or @@ -29,15 +29,7 @@ legacy demand questions below. serving copy's cursor judges the window from its resume point, a replaced or backfill copy that may still deliver keeps the read open, and so does a group in range the local floor or cap keeps out. A `with_range` cap never ends a - read. Still to do with the API: `Ok(None)` before any group arrives is a miss, - which the moq-ffi fetch wrapper reports as `NotFound`; after one, it is the - range's end. A one-range read surfaces no `NotFetchable` or `Old` result, and a - peer's reset with either names the group dropped. Every fetch boundary - already treats `NotFetchable` as not found (relay HTTP 404, hls - `is_cache_miss`, moq-ffi `map_fetch_error`, moq-c `NOT_FOUND`); a fetched - `Old` becomes a miss too, where moq-c reports `OLD` today. Both stay as wire - stream errors, and `Old` still aborts a cut group mid-read. The Impact bullet - says how to migrate each affected package. + read. - **A bounded read fills a missing head** (landed). A bounded window hands out a cached live group missing its first frames only once a fill answered it from frame 0, as `fetch_group` asks, and gives the group up when none can. @@ -50,7 +42,7 @@ legacy demand questions below. explicit end below removes that FIN. - **Route recovery keeps a frame start.** `resume::Recover` fetches the rest of a group from frame N on the new route (`group::Fetch::frame_start`), which a - whole-group range cannot say, so a crate-private fetch stays for it. + whole-group range cannot say, so it keeps the fetch. - **Ends are signaled, not inferred** (maintainer, 2026-11-01, on [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "we should have a SUBSCRIBE_END message or something to signal the last group of a @@ -172,9 +164,10 @@ legacy demand questions below. SUBSCRIBE (`subscribe_join`). Found migrating the moq-net integration tests onto one-range reads, and settled by the maintainer on 2026-11-02 ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): - - **Scope.** ✅ Keep going in one PR: remove the public `fetch_group` and + - **Scope.** Keep going in one PR: remove the public `fetch_group` and migrate its callers, finishing this quest. Alternative: land the bounded - read changes first and remove the API in a later PR. + read changes first and remove the API in a later PR. Superseded below: + `fetch_group` stays. - **Past-group reads on lite-05/06.** Lite before lite-07 tells no live edge without a SUBSCRIBE, so a one-range read of history there SUBSCRIBEs where `fetch_group` FETCHes: `fetch_pipeline` (the FETCH sent with TRACK), @@ -213,37 +206,53 @@ legacy demand questions below. on the relay (`fetch_cancel`), an untimed fetched frame arrives untimed (`untimed`), and a fetched datagram is `NotFetchable` (`datagram`, now a miss by the rule above). -- **Blockers found removing the API** (2026-11-02, on - [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)). Making - `track::Consumer::fetch_group` crate-private, which the wire publishers - still serve a FETCH through, and moving the relay, hls, and transcode onto - one-range reads surfaced three gaps: - - **Sequential one-range reads stall on lite-07.** On one session, a - one-range read after an earlier one on the same track can time out, - direct or relayed. Reading groups 1 then 2 stalls on 2, and 2, 1, 0 stalls - on 0, even after the copy's linger expires. Lite-06 and moq-transport pass. - It hangs hls's `a_live_fmp4_import_serves_segments_over_lite07`, which reads - a segment's groups one by one. To reproduce: in `range_read.rs`'s fixture - on lite-07, read `one_range(1..2)`, drop it, then read `one_range(2..3)`. - - **A local track asks no fill without a told edge.** A one-range read on a - local track asks its `Requests` handler for a missing group only below a - start the publisher declared (`track::Producer::start_at`). Writing a - newer group is not enough (`late_lower_group`). `fetch_group` asked at once. - So in-process reads of on-demand groups hang: moq-c group requests and - moq-ffi fills (`track_dynamic_serves_a_fetch_miss`, - `track_request_dynamic_survives_accept`, `fill_goes_unwanted_*`), and - transcode's rung, which reads its source and serves its output that way - (`a_group_nobody_reads_releases_its_fill`, - `retirement_waits_for_an_unclaimed_fetch`). moq-archive already declares - its edge, but moq-c and moq-ffi expose no `start_at`. - - **A group past the live edge waits.** A one-range read of a group the - live track has not reached yet waits for it, where `fetch_group`'s FETCH - was refused at once. `moq fetch --group 99` and the relay's - `/fetch?group=99` time out (HTTP 504 after 30 s) instead of answering 404. - - Keep the subscription open while its group is read. Dropping the - `track::Subscriber` after `recv_group` stalls a group still being written - on every wire, so each boundary that hands a group out (relay HTTP, - moq-ffi, hls, transcode) keeps the subscriber with it. +- **`fetch_group` stays public** (maintainer, 2026-11-02, on + [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): "We can have + a public fetch_group for a single group." This reverses the removal above. + Removing it surfaced two problems a single-group fetch already avoids: a + one-range read on a local track asks its `Requests` handler for a missing + group only below a start the publisher declared (`start_at`), so moq-c, + moq-ffi, and transcode on-demand reads hang, and a one-range read of a group + past the live edge waits where a fetch is refused, so `moq fetch --group 99` + and `/fetch?group=99` answer 504 instead of 404. Keeping one-range subscribers + alive while their group is read, and the `NotFetchable`/`Old` mapping above, + went with the removal. +- **A lite-07 FETCH replacement** (maintainer, 2026-11-02, on + [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): "lite-07 can + issue a one group SUBSCRIBE as a FETCH replacement (no max-delay) if an + existing SUBSCRIBE had it dropped", "and only when the group is officially + marked DROP so we don't receive two copies of it". So on lite-07 a group an + existing subscription named in SUBSCRIBE_DROP is recovered by a new + SUBSCRIBE bounded to that group with no max delay, never on a guess, a + timeout, or while the group may still arrive. Tests: a group still in flight + on the existing subscription sends no second SUBSCRIBE, and a dropped group + is recovered once. This replaces lite-07 FETCH for that case, which + [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) + lands in Rust and JS together because a JS publisher serves a range only from + its cache. +- **Back-to-back one-range reads hang on lite-07.** On one session, a + one-range read after an earlier one on the same track times out, direct or + relayed: groups 1 then 2 hangs on 2, and 2, 1, 0 hangs on 0. Lite-05/06 and + moq-transport pass, and draft-18 refuses the newest group, as decided above. + It hangs hls's `a_live_fmp4_import_serves_segments_over_lite07` once hls + reads a segment's groups that way. No SUBSCRIBE_DROP is involved, so the + FETCH replacement above does not reach it. Both causes are the covered FIN + (see "Ends are signaled" above), traced on `range_read.rs`'s fixture: + - On this branch, the copy sends SUBSCRIBE_UPDATE widening `1..2` to `1..3` + while the publisher FINs the covered `1..2` without reading it. The copy's + tail then owes `1..3` (`SubStream::covered`, `updated` set) and waits its + grace, which is `Duration::MAX` with no max delay + (`Subscription::budget`), so group 2 never comes and nothing re-subscribes. + - On main, the FIN lands first. The tail settles, `TrackServe::begin` finds + the lingering demand equal to the covered ranges and keeps `Sub::None`, and + the second read's demand never wakes the serve loop again, so no SUBSCRIBE + is sent. + + The subscriber cannot tell whether the publisher read the update, and a fresh + SUBSCRIBE while group 2 may still be in flight would deliver it twice, which + the maintainer ruled out above. Keeping the Subscribe Stream open (the + settled lite-07 design under "Ends are signaled") lets the publisher read + the update and serve or drop the group, which removes both paths. - **The fill path goes linear first** (maintainer, 2026-10-25). One-range reads put every past read on the fill path, which `track_range_filling` measured as superlinear in range count and span. It is flat since From 92a8f49838d68c23b32e67ffdd87751a61603ebb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 13:35:09 -0800 Subject: [PATCH 14/20] docs(quest): finish fetch-range, moving its lite-07 work to lite-07 ranges The maintainer kept `fetch_group` public and settled both open decisions on 2026-11-02: the lite-07 back-to-back hang and the one-group SUBSCRIBE recovery of a dropped group belong to lite-07 ranges. Move them there with the settled explicit-end design (SUBSCRIBE_FINISH, the stream stays open, no covered FIN), point JS ranges at that design, and delete the quest. Co-Authored-By: Claude Opus 5.5 --- quest/m1/subscribe-ranges/README.md | 1 - quest/m1/subscribe-ranges/fetch-range.md | 259 ---------------------- quest/m1/subscribe-ranges/js.md | 7 +- quest/m1/subscribe-ranges/lite.md | 135 +++++++++-- quest/m1/time-addressing/model.md | 7 +- quest/m2/intra-refresh/consumer-warmup.md | 4 - 6 files changed, 121 insertions(+), 292 deletions(-) delete mode 100644 quest/m1/subscribe-ranges/fetch-range.md diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 0ef6ae40a02..d3051609410 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -102,7 +102,6 @@ every sequence delivered or dropped. ## Required -- [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) - `fetch_group` becomes a one-range subscription that ends once its range is accounted for - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft - [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity, and the on-demand request surface - [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) - FETCH removed from lite-07 in Rust, JS, and the draft diff --git a/quest/m1/subscribe-ranges/fetch-range.md b/quest/m1/subscribe-ranges/fetch-range.md deleted file mode 100644 index e0b62d730b8..00000000000 --- a/quest/m1/subscribe-ranges/fetch-range.md +++ /dev/null @@ -1,259 +0,0 @@ -# [L] Fetch as a range - -## Goal - -A one-range read works on every path, including back to back on one lite-07 -session. `track::Consumer::fetch_group` stays public as the single-group fetch -(maintainer, 2026-11-02), so its callers keep it: moq-c group requests, -moq-ffi fills, transcode, the relay's `/fetch`, `moq fetch`, and hls. - -## Plan - -Split out of dynamic range requests, which replaced `requested_group` with -`requested_fill`, by the maintainer on 2026-10-20 -([moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so each PR -breaks one API once. Resized from [M] to [L] on 2026-10-24, when the first -attempt ([moq-dev/moq#6722](https://github.com/moq-dev/moq/pull/6722)) found -the questions decided below and landed only the `track_range_filling` benchmark. -The second attempt ([moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)) -landed the bounded-read end on a plain cursor, the parking wire publishers, -the cached-backfill rule, the bounded miss grace, and the unfed moq-transport -copy. The third ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)) -landed the end of a front's bounded read, the head fill, and the first bounded -moq-transport request. `fetch_group` now stays public (below), so what -remains is the lite-07 back-to-back hang. - -- **Ending a bounded read** (decided 2026-10-20; landed). `recv_group` returns - `None` once every sequence in a bounded window is delivered, dropped, stale, or - unfillable, on a track's own cache and on a front's logical track alike: the - serving copy's cursor judges the window from its resume point, a replaced or - backfill copy that may still deliver keeps the read open, and so does a group - in range the local floor or cap keeps out. A `with_range` cap never ends a - read. -- **A bounded read fills a missing head** (landed). A bounded window hands out a - cached live group missing its first frames only once a fill answered it from - frame 0, as `fetch_group` asks, and gives the group up when none can. -- **Wire publishers keep parking** (landed). Every wire publisher reads its - subscription through `track::Subscriber::parked`: the IETF publisher and - lite publishers before lite-07 keep parking on a bounded downstream - SUBSCRIBE rather than FIN it, and a lite-07 publisher FINs a covered bounded - subscription without SUBSCRIBE_END - ([moq-dev/moq#6807](https://github.com/moq-dev/moq/pull/6807)) until the - explicit end below removes that FIN. -- **Route recovery keeps a frame start.** `resume::Recover` fetches the rest of - a group from frame N on the new route (`group::Fetch::frame_start`), which a - whole-group range cannot say, so it keeps the fetch. -- **Ends are signaled, not inferred** (maintainer, 2026-11-01, on - [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "we should - have a SUBSCRIBE_END message or something to signal the last group of a - track? we were using QUIC FIN to signal that but that prevents updates in the - future, so we should have a signal instead". The follow-up answers, the same - day: - - "do we need a SUBSCRIBE_COVERED? We have SUBSCRIBE_DROP so the peer can - determine that the bounded range has been received? SUBSCRIBE_END (rename - to FINISH?) would signal the final group of the track maybe, but would be - independent of the bounded range?" No new message: a subscriber judges a - bounded range complete from the groups it received, SUBSCRIBE_DROP, the - Range Starts in SUBSCRIBE_OK, and SUBSCRIBE_END. Drops and groups name - absolute sequences, so the subscriber judges against its latest ranges and - an update in flight changes nothing it has counted; the FIN's race with an - unread update goes away. One gap: before SUBSCRIBE_OK a lite-07 publisher - holds back what it gave up (`TrackRun::skipped`) and answers only once a - group stream resolves the start, so a bounded subscription none of whose - groups it can serve gets neither, and only the covered FIN ends it today. - Fix: once such a subscription is covered, the publisher sends SUBSCRIBE_OK - and then the drops it held. Datagrams are left out: they become their own - track kind, which takes no ranges (maintainer, 2026-11-01). - - "Keep stream open": SUBSCRIBE_END (or FINISH) names the track's final group - and no longer FINs the Subscribe Stream, so an update can still reach an - ended track's history. The subscriber FINs once it wants nothing more, and - the publisher FINs in reply. The covered FIN goes too. - - ✅ Rename SUBSCRIBE_END to SUBSCRIBE_FINISH in lite-07 (maintainer, - 2026-11-01). It matches TRACKS_FINISH and `track::Producer::finish`, and - "END" would read as closing the stream, which it no longer does. - - The settled lite-07 wire design, together: - - SUBSCRIBE_FINISH (formerly SUBSCRIBE_END) names the track's final group and - no longer FINs the Subscribe Stream. - - A covered bounded subscription is not FINed either: the subscriber judges - it complete from the groups it received, SUBSCRIBE_DROP, the Range Starts in - SUBSCRIBE_OK, and SUBSCRIBE_FINISH. - - A publisher that held back SUBSCRIBE_OK (`TrackRun::skipped`) sends it, then - the drops it held, once such a subscription is covered. - - The subscriber FINs the stream once it wants nothing more, and the - publisher FINs in reply. - - Datagrams take no ranges, since they become their own track kind. The - datagram-tracks plan - ([moq-dev/moq#7575](https://github.com/moq-dev/moq/pull/7575)) touches - `lite.md` too, and should take this design and the rename as given. - - This wire half belongs to [lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - (Rust and the draft) and [JS ranges](/quest/m1/subscribe-ranges/js.md), not - to this quest. It is recorded here while - [moq-dev/moq#7487](https://github.com/moq-dev/moq/pull/7487) rewrites that - quest, and moves there once it lands. -- **The live edge is told, never inferred** (maintainer, 2026-11-01, on - [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "If the relay - doesn't know the live edge, it shouldn't say anything. It should be a - separate message if it's async or the OK should block. NEVER use the cache - as the live edge." The OK blocks, since the wire already works that way: - lite-07 SUBSCRIBE_OK carries Largest Group and waits until each Range's - start resolves, a relay's `TrackRun` waits on its source's start - (`track::Subscriber::poll_start`) before answering, and an idle copy reads - nothing until its route answers. The draft's exception for a start past the - publisher's largest position should say that a relay knows that position - only from its upstream's answer (lite-07 ranges' draft change). A reader - asks fills only below the newest group the live feed produced (decision 2 - on [moq-dev/moq#6123](https://github.com/moq-dev/moq/pull/6123)), so with - nothing produced it waits for the answer that its own demand's upstream - subscription brings. Earlier (maintainer, 2026-10-25): while a track has no - live feed, holes in a bounded range are misses up to its end, and treating - "no group produced" as "no feed" asks too early - (`subscribe_ranges::sparse_ranges_reach_the_publisher_on_lite07` reads - `[0]` on lite-06). moq-archive needs nothing new: its consumer declares the - newest stored sequence with `start_at`. -- **The session marks a copy unfed** (maintainer, 2026-11-01, on - [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545); landed). ✅ - The session marks a copy it holds no upstream subscription for unfed - (`track::Producer::set_unfed`), from its own state, never from the cache. - A bounded read's holes there are misses up to its end at once, per the - 2026-10-25 rule, a refusal is final, and the read takes what the cache holds - in its window even while the copy is idle; an open read still waits for a - feed. The moq-transport subscriber marks a lingering copy unfed, such as one - learned from TRACK_STATUS for a fetch, and keeps a subscription whose ranges - all end below the publisher's reported Largest Object out of the upstream - SUBSCRIBE (`fetch_only.rs`). The rejected alternative, a one-range read always - subscribing so its OK names the edge, broke the fetch-only rule below. -- **Every hole ends** (maintainer, 2026-11-01, on - [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)): "uhh the - publisher is supposed to emit the start/end bounds if the subscriber didn't - ask for one? I don't understand, but parking forever is terrible?" A hole is - asked as a miss, refused, or covered by the publisher's bounds, and a - bounded read never parks for good. A hole under the start the publisher - resolved is asked at once, and a refusal there is held while the feed may - still deliver the group late (maintainer, 2026-10-21, on - [moq-dev/moq#6171](https://github.com/moq-dev/moq/pull/6171)). Nothing is - inferred from the first arrival, since a local producer may still write a - lower group (`late_lower_group`). Landed: that hold, and the wait before a - hole with no start under it is asked, last the arrival grace, or - `ledger::GRACE` when neither a budget nor a max age bounds it - (`TrackState::miss_grace`), and a held refusal wakes its reader at its - deadline. -- **Cached backfill is owed** (maintainer, 2026-10-25; landed). A cached - backfill group inside a reader's window is taken as filled, whether or not - the live feed may still deliver it, so a relay behaves the same warm or - cold. Re-filling a cached group was rejected: it costs an upstream FETCH for - a group already in the cache. -- **Relay demand before lite-07** (maintainer, 2026-10-25). A one-range read's - ranges join the track's aggregate, so a relay would put a bounded SUBSCRIBE - upstream where `fetch_group` puts a FETCH. `fetch_only.rs` asserts that a - moq-transport fetch never subscribes, and a lite SUBSCRIBE before lite-05 - cannot name a missing group. A range wholly below the live edge stays out of - the upstream SUBSCRIBE on any wire without range SUBSCRIBE and is filled by - FETCH, keeping today's wire behavior: since - [moq-dev/moq#6724](https://github.com/moq-dev/moq/pull/6724) a run of misses - is one range FETCH on moq-transport, and per-group FETCH is lite-only, until - [lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) land. A bounded - upstream SUBSCRIBE accounted by SUBSCRIBE_START and SUBSCRIBE_DROP was - rejected: it works on lite-05 and later only. Landed for moq-transport: a - copy no SUBSCRIBE feeds (the unfed copy above), and a first request whose - ranges all have an absolute start and end, which asks TRACK_STATUS first and - subscribes only once a range reaches the reported Largest Object. - `range_read.rs` reads history and a range across the live edge on every - wire, direct and relayed; draft-18 refuses the latter, having no bounded - SUBSCRIBE (`subscribe_join`). Found migrating the moq-net integration tests - onto one-range reads, and settled by the maintainer on 2026-11-02 - ([moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): - - **Scope.** Keep going in one PR: remove the public `fetch_group` and - migrate its callers, finishing this quest. Alternative: land the bounded - read changes first and remove the API in a later PR. Superseded below: - `fetch_group` stays. - - **Past-group reads on lite-05/06.** Lite before lite-07 tells no live edge - without a SUBSCRIBE, so a one-range read of history there SUBSCRIBEs where - `fetch_group` FETCHes: `fetch_pipeline` (the FETCH sent with TRACK), - `fetch_fanout`, `fetch_cancel`, and `catalog_handover`'s fetch cases - assert the FETCH. - - ✅ (a) Accept the bounded SUBSCRIBE before lite-07 and rewrite those four - tests. - - (b) Serve a fully bounded absolute subscription fetch-only before - lite-07, keeping today's wire behavior, though a range past the live - edge ends short. - - **Newest group on moq-transport.** A read of the group at the reported - Largest Object reaches "the group the publisher may still be writing" - (`wants_feed`), so it subscribes. Draft-18 refuses that, and so does a - finished track (`fetch_only`, `compress::ietf_fetch_keeps_the_stored_form`). - The relay's newest-group read (`moq_relay::fetch_group(None)`) reads - exactly that group. - - ✅ Read it as live with a SUBSCRIBE, with no special-case fallback, and - accept the draft-18 and finished-track refusals. "Whatever the simplest - option is, prob subscribe. I hate the IETF fetch/subscribe logic and we - should not agonize over making it correct." - - FETCH it. - - SUBSCRIBE while the track is live, FETCH once it ended. - - **Multi-group history between our moq-transport nodes.** Our - moq-transport publishers answer only a one-group FETCH, so a run of - missing history groups read from one of them is refused and named dropped - (`subscribe_ranges`'s draft-22 cases open with a range reaching the - Largest Object). - - ✅ Accept the refusal until [hole markers](/quest/m2/ietf-hole-marker.md) - let our publishers answer a range. - - Answer a multi-group FETCH now. - - Fetch-only behavior to carry over or drop: a fetch keeps both sessions busy - (`session_idle`), a session close cancels a pending fetch from either side - (`subscription_end_integrity`), a pre-lite-05 fetch is served from a feed - opened with it and an unfed fetch is a miss (`fetch_from_feed`), an - abandoned fetch reaches the publisher and a refetch within the linger stays - on the relay (`fetch_cancel`), an untimed fetched frame arrives untimed - (`untimed`), and a fetched datagram is `NotFetchable` (`datagram`, now a - miss by the rule above). -- **`fetch_group` stays public** (maintainer, 2026-11-02, on - [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): "We can have - a public fetch_group for a single group." This reverses the removal above. - Removing it surfaced two problems a single-group fetch already avoids: a - one-range read on a local track asks its `Requests` handler for a missing - group only below a start the publisher declared (`start_at`), so moq-c, - moq-ffi, and transcode on-demand reads hang, and a one-range read of a group - past the live edge waits where a fetch is refused, so `moq fetch --group 99` - and `/fetch?group=99` answer 504 instead of 404. Keeping one-range subscribers - alive while their group is read, and the `NotFetchable`/`Old` mapping above, - went with the removal. -- **A lite-07 FETCH replacement** (maintainer, 2026-11-02, on - [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): "lite-07 can - issue a one group SUBSCRIBE as a FETCH replacement (no max-delay) if an - existing SUBSCRIBE had it dropped", "and only when the group is officially - marked DROP so we don't receive two copies of it". So on lite-07 a group an - existing subscription named in SUBSCRIBE_DROP is recovered by a new - SUBSCRIBE bounded to that group with no max delay, never on a guess, a - timeout, or while the group may still arrive. Tests: a group still in flight - on the existing subscription sends no second SUBSCRIBE, and a dropped group - is recovered once. This replaces lite-07 FETCH for that case, which - [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) - lands in Rust and JS together because a JS publisher serves a range only from - its cache. -- **Back-to-back one-range reads hang on lite-07.** On one session, a - one-range read after an earlier one on the same track times out, direct or - relayed: groups 1 then 2 hangs on 2, and 2, 1, 0 hangs on 0. Lite-05/06 and - moq-transport pass, and draft-18 refuses the newest group, as decided above. - It hangs hls's `a_live_fmp4_import_serves_segments_over_lite07` once hls - reads a segment's groups that way. No SUBSCRIBE_DROP is involved, so the - FETCH replacement above does not reach it. Both causes are the covered FIN - (see "Ends are signaled" above), traced on `range_read.rs`'s fixture: - - On this branch, the copy sends SUBSCRIBE_UPDATE widening `1..2` to `1..3` - while the publisher FINs the covered `1..2` without reading it. The copy's - tail then owes `1..3` (`SubStream::covered`, `updated` set) and waits its - grace, which is `Duration::MAX` with no max delay - (`Subscription::budget`), so group 2 never comes and nothing re-subscribes. - - On main, the FIN lands first. The tail settles, `TrackServe::begin` finds - the lingering demand equal to the covered ranges and keeps `Sub::None`, and - the second read's demand never wakes the serve loop again, so no SUBSCRIBE - is sent. - - The subscriber cannot tell whether the publisher read the update, and a fresh - SUBSCRIBE while group 2 may still be in flight would deliver it twice, which - the maintainer ruled out above. Keeping the Subscribe Stream open (the - settled lite-07 design under "Ends are signaled") lets the publisher read - the update and serve or drop the group, which removes both paths. -- **The fill path goes linear first** (maintainer, 2026-10-25). One-range - reads put every past read on the fill path, which `track_range_filling` - measured as superlinear in range count and span. It is flat since - [moq-dev/moq#6995](https://github.com/moq-dev/moq/pull/6995). diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 1d0b7c687c4..0caa660ce69 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -17,11 +17,14 @@ the ranges model, anchors, `maxDelay: null`, and the on-demand request surface. Rust's lite-07 SUBSCRIBE already carries ranges ([moq-dev/moq#6715](https://github.com/moq-dev/moq/pull/6715)). -Mirror lite-07 bounded completion in the publisher: a covered bounded +Mirror lite-07 bounded completion in the publisher. Today a covered bounded subscription FINs without SUBSCRIBE_END. The JS subscriber already accepts that FIN, closing the request's track once its tail settles, and failing it when an update moved the range and the groups that arrived leave it uncovered. Reopen -that demand on the same track instead, as the Rust copy does. +that demand on the same track instead, as the Rust copy does. The settled +replacement, SUBSCRIBE_FINISH with the Subscribe Stream kept open and no +covered FIN, is in [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md)' +"Ends are signaled" plan; mirror whichever the wire has when this lands. Mirror the Rust names, including `Time(pts)` ends and their refusal on an untimed track. The publisher resolves no relative or time start, serving it from the oldest diff --git a/quest/m1/subscribe-ranges/lite.md b/quest/m1/subscribe-ranges/lite.md index 3a7e229f7d0..c07dfe0af5a 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -1,8 +1,11 @@ -# [L] Lite-07 ranges +# [XL] Lite-07 ranges ## Goal -A relay fills a lite-07 upstream by subscribing to the missing ranges. FETCH stays on lite-07 until +A relay fills a lite-07 upstream by subscribing to the missing ranges, and +recovers a dropped group with a one-group SUBSCRIBE. SUBSCRIBE_FINISH signals +a track's end and the Subscribe Stream stays open, so one-range reads back to +back on one lite-07 session complete. FETCH stays on lite-07 until [Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) removes it from both implementations. @@ -17,27 +20,27 @@ range fill work without it. Decided 2026-11-01 (maintainer, on [moq-dev/moq#7487](https://github.com/moq-dev/moq/pull/7487)): this quest -waits for [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md)'s miss -judging (a miss with no feed frontier, and holes below where a live feed -started) and its cached backfill rule. Without them a range fill is a -functional regression from FETCH, which answers a miss at once. Both landed -in [moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545) on -2026-11-02, so this quest is unblocked. Fetch as a range's remaining work, -such as the explicit end signal, doesn't block it. +waited for Fetch as a range's miss judging (a miss with no feed frontier, and +holes below where a live feed started) and its cached backfill rule. Without +them a range fill is a functional regression from FETCH, which answers a miss +at once. Both landed in +[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545) on 2026-11-02. +Fetch as a range finished in +[moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625), which kept +`track::Consumer::fetch_group` public as the single-group fetch and moved its +remaining lite-07 work here (maintainer, 2026-11-02): the explicit end, the +back-to-back hang, and the one-group recovery below. ### Range fill through the subscription Lite-07 SUBSCRIBE and SUBSCRIBE_UPDATE carry the range list (`lite::Range`, typed anchors), and the publisher serves it from the model. Older wires map at the codec, and a merged request goes upstream as one span, from group 0 when -its starts mix (`wire_span`). A lite-07 publisher FINs a covered bounded -subscription without SUBSCRIBE_END; the Rust copy settles its tail, keeps the -cached copy, and subscribes again only for demand the covered ranges leave -out. The maintainer has since directed an explicit end signal (SUBSCRIBE_END -or similar) in place of that FIN, since a FIN prevents later updates (on -[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545)). -[Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) owns that -design; build the fill on whatever it settles, not on the FIN. +its starts mix (`wire_span`). Today a lite-07 publisher FINs a covered bounded +subscription without SUBSCRIBE_END, and the Rust copy settles its tail, keeps +the cached copy, and subscribes again only for demand the covered ranges leave +out. The explicit end below replaces that FIN; build the fill on it, not on +the FIN. The first attempt ([moq-dev/moq#7487](https://github.com/moq-dev/moq/pull/7487), WIP commit @@ -74,14 +77,14 @@ whole) passed. These failed, and must pass on #7545's miss judging: ask a fill and park (`untimed::a_fetched_untimed_frame_arrives_untimed`, `fetch_cancel::a_refetch_within_the_linger_stays_on_the_relay_lite07`, `subscription_end_integrity::a_session_close_cancels_a_pending_fetch_from_either_side`). - Fetch as a range's miss with no feed frontier covers them. + #7545's miss with no feed frontier covers them. - A missing or expired group fetched with no budget parks where FETCH answered NotFound at once (`rejoin::{rejoined,taken_over}_quiet_catalog_survives_cache_expiry`). - Fetch as a range's holes below where a live feed started cover them. + #7545's holes below where a live feed started cover them. - A relay re-asks upstream for groups it cached, since its covered memory leaves with the downstream demand (`fetch_fanout::sequential_viewers_share_the_relays_fetched_groups`, two - upstream SUBSCRIBEs where FETCH needed one). Fetch as a range's cached + upstream SUBSCRIBEs where FETCH needed one). #7545's cached backfill rule covers it: a relay leaves cached groups out of a bounded upstream range. On lite-07 the test counts SUBSCRIBE streams, not FETCH. @@ -96,10 +99,12 @@ Open questions the attempt raised, each with the attempt's recommendation: datagram; the subscriber already maps that drop onto the fill. This is a wire change. The alternative keeps FETCH for a fill the first answer shows is a datagram, at a round trip and a second path. + Since settled in part: datagrams become their own track kind, which takes + no ranges (maintainer, 2026-11-01; see "Ends are signaled" below). - **Fills from partway through a group.** Route recovery (`resume::Recover`) fills from frame N, which a whole-group range cannot say. Recommended: keep - FETCH on lite-07 for a fill whose first group starts past frame 0, matching - Fetch as a range's crate-private fetch for that case. The alternative asks + FETCH on lite-07 for a fill whose first group starts past frame 0, as + `resume::Recover` does today (`group::Fetch::frame_start`). The alternative asks for the whole group and drops the frames the reader already has. - **One budget caps every range.** Merging the fills into the upstream Subscriber Max Age takes the most tolerant budget, which loosens the live @@ -129,6 +134,92 @@ bounded ranges complete upstream. A hole on a live track counts as dropped once the feed gives up on it, past the arrival grace (#7545's bounded wait, `TrackState::miss_grace`). +### Ends are signaled, not inferred + +The maintainer, 2026-11-01, on +[moq-dev/moq#7545](https://github.com/moq-dev/moq/pull/7545): "we should have +a SUBSCRIBE_END message or something to signal the last group of a track? we +were using QUIC FIN to signal that but that prevents updates in the future, so +we should have a signal instead". Settled the same day: + +- No SUBSCRIBE_COVERED message: a subscriber judges a bounded range complete + from the groups it received, SUBSCRIBE_DROP, the Range Starts in + SUBSCRIBE_OK, and SUBSCRIBE_FINISH. Drops and groups name absolute + sequences, so the subscriber judges against its latest ranges and an update + in flight changes nothing it has counted; the FIN's race with an unread + update goes away. +- "Keep stream open": SUBSCRIBE_FINISH names the track's final group and no + longer FINs the Subscribe Stream, so an update can still reach an ended + track's history. A covered bounded subscription is not FINed either. +- ✅ Rename SUBSCRIBE_END to SUBSCRIBE_FINISH. It matches TRACKS_FINISH and + `track::Producer::finish`, and "END" would read as closing the stream, which + it no longer does. +- Before SUBSCRIBE_OK a lite-07 publisher holds back what it gave up + (`TrackRun::skipped`) and answers only once a group stream resolves the + start, so a bounded subscription none of whose groups it can serve gets + neither, and only the covered FIN ends it today. Once such a subscription is + covered, the publisher sends SUBSCRIBE_OK and then the drops it held. +- The subscriber FINs the stream once it wants nothing more, and the publisher + FINs in reply. +- Datagrams take no ranges, since they become their own track kind + (maintainer, 2026-11-01). The datagram-tracks plan + ([moq-dev/moq#7575](https://github.com/moq-dev/moq/pull/7575)) touches this + quest too, and should take this design and the rename as given. + +The draft's exception for a start past the publisher's largest position should +also say that a relay knows that position only from its upstream's answer, +never from its cache (maintainer, 2026-11-01: "NEVER use the cache as the live +edge"). + +### Back-to-back one-range reads + +Acceptance test (maintainer, 2026-11-02, on +[moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): on lite-07, +one-range reads of the same track through one session, groups 1 then 2, and +2, 1, 0, each complete, direct and through a relay. Today each hangs on the +later read (on 2, and on 0). Lite-05/06 and moq-transport pass. It also hangs +hls's `a_live_fmp4_import_serves_segments_over_lite07` once hls reads a +segment's groups that way. Reproduce with sequential `one_range` reads in +`range_read.rs`'s fixture. + +The cause is the publisher's end-of-subscription FIN on a covered bounded +subscription, traced with tracing on: + +- When the copy widens `1..2` to `1..3` with SUBSCRIBE_UPDATE while the + publisher FINs the covered `1..2` without reading it, the copy's tail owes + `1..3` (`SubStream::covered`, `updated` set) and waits its grace, which is + `Duration::MAX` with no max delay (`Subscription::budget`). Group 2 never + comes and nothing re-subscribes. +- When the FIN lands first (as on main before + [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)), the tail + settles, `TrackServe::begin` finds the lingering demand equal to the covered + ranges and keeps `Sub::None`, and the second read's demand never wakes the + serve loop again, so the copy is left with no upstream subscription. + +No SUBSCRIBE_DROP is involved, so the one-group recovery below does not reach +it, and a fresh SUBSCRIBE while group 2 may still be in flight could deliver +it twice. Fix it with the explicit end above: the Subscribe Stream stays open +and the covered FIN goes, so the publisher reads the update and serves or +drops the group. + +### Recovering a dropped group + +Decided 2026-11-02 (maintainer, on +[moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): "lite-07 can +issue a one group SUBSCRIBE as a FETCH replacement (no max-delay) if an +existing SUBSCRIBE had it dropped", "and only when the group is officially +marked DROP so we don't receive two copies of it". A group a reader still +wants, once an existing subscription names it in SUBSCRIBE_DROP, is recovered +by a new SUBSCRIBE covering only that group with no max delay, never on a +guess, a timeout, or while the group may still arrive. This is lite-07's +FETCH replacement for a dropped group, so that +[Remove FETCH from lite-07](/quest/m1/subscribe-ranges/lite07-fetch.md) can +remove FETCH from Rust and JS together, as decided on 2026-10-25. Tests: a +group still in flight on the existing subscription sends no second SUBSCRIBE, +and a dropped group is recovered exactly once. + +### Draft and checks + Update `drafts/draft-lcurley-moq-lite.md` with each wire change here, including that a subscriber fills missing groups through its ranges. Run `just drafts check` and `just test interop --all`, and the `moq-net-tests` diff --git a/quest/m1/time-addressing/model.md b/quest/m1/time-addressing/model.md index 04f3e4b9fdb..184a1ae9d9b 100644 --- a/quest/m1/time-addressing/model.md +++ b/quest/m1/time-addressing/model.md @@ -51,10 +51,10 @@ a producer would need per-track memory of its last number. [moq-dev/moq#6780](https://github.com/moq-dev/moq/pull/6780); the cut removes its sequence half, leaving a re-created track to keep its PTS moving forward. -- **What it waits on** (decided 2026-10-27, maintainer): only the +- **What it waits on** (decided 2026-10-27, maintainer; Fetch as a range + finished in [moq-dev/moq#7625](https://github.com/moq-dev/moq/pull/7625)): only the subscribe-ranges children that put sequence ranges into the model and the - wire, [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md), - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md), and + wire, [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) and [Delete the old start bookkeeping](/quest/m1/subscribe-ranges/start-bookkeeping.md), not the whole epic. [Drop set](/quest/m1/drop-set.md) lands first too: its runs keyed by group sequence convert mechanically to starts. @@ -117,7 +117,6 @@ Wire: no format change; legacy and lite-07-wip group IDs become start ticks. ## Required -- [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) - the one-range reads this rework moves onto times - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the range ends and drops this rework moves onto times - [Delete the old start bookkeeping](/quest/m1/subscribe-ranges/start-bookkeeping.md) - the lite cursor state lives in the model before the cut rekeys it - [Drop set](/quest/m1/drop-set.md) - its dropped and expired runs convert mechanically from sequences to starts diff --git a/quest/m2/intra-refresh/consumer-warmup.md b/quest/m2/intra-refresh/consumer-warmup.md index ea90f7bc11b..06643233e09 100644 --- a/quest/m2/intra-refresh/consumer-warmup.md +++ b/quest/m2/intra-refresh/consumer-warmup.md @@ -55,7 +55,3 @@ The fix is history rather than a withhold rule: ## Required - [Plan: recovery boundaries](/quest/m2/intra-refresh/plan-boundary.md) - K derives from `warmup`, which must be a safe upper bound - -## Related - -- [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) - the range read the history fetch uses From ce75cc7b91af49e0279b011c49271a2f14bed412 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 13:41:31 -0800 Subject: [PATCH 15/20] test(net): read before checking the relay's upstream SUBSCRIBE on a fetched copy Main's new history-SUBSCRIBE test asserted the relay subscribed upstream as soon as `subscribe` returned. A first bounded read now asks TRACK_STATUS first and SUBSCRIBEs once the answer arrives, so check after reading the group, and pin that the bounded read then ends. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/tests/integration/fetch_only.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/tests/integration/fetch_only.rs b/rs/moq-net/tests/integration/fetch_only.rs index 119b27d91fa..9e9f2792216 100644 --- a/rs/moq-net/tests/integration/fetch_only.rs +++ b/rs/moq-net/tests/integration/fetch_only.rs @@ -404,13 +404,19 @@ async fn fetched_copy(upstream_version: Version, version: Version) -> FetchedCop async fn history_through_fetched_copy(upstream: Version, version: Version) { let copy = fetched_copy(upstream, version).await; - // A front's bounded read parks past its end, so this reads the group and stops there. + // The fresh session asks TRACK_STATUS first, which the relay answers without an edge, + // so the read SUBSCRIBEs once that answer arrives, after `subscribe` returns. let mut sub = subscribe_history(©.fresh).await; + assert_eq!(next_frames(&mut sub).await, Some(frames(1)), "{upstream} to {version}"); + assert_eq!( + next_frames(&mut sub).await, + None, + "{upstream} to {version}: the read ends" + ); assert!( copy.track.subscription().is_some(), "{upstream} to {version}: answered without subscribing upstream" ); - assert_eq!(next_frames(&mut sub).await, Some(frames(1)), "{upstream} to {version}"); // The copy still serves its other reader. assert_eq!( fetch(©.fetched, 0).await.expect("fetch after the SUBSCRIBE"), From 789ac6e7c448a3381750d9712679fc5a7d5ca1ab Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 14:10:44 -0800 Subject: [PATCH 16/20] test(net): read a range across the live edge on draft-18 too Main no longer refuses a draft-18 bounded SUBSCRIBE: the join stays open and the reader stops at its own end, so the range test covers every version. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/tests/integration/range_read.rs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/tests/integration/range_read.rs b/rs/moq-net/tests/integration/range_read.rs index eef2f01ffec..25ae9a1999a 100644 --- a/rs/moq-net/tests/integration/range_read.rs +++ b/rs/moq-net/tests/integration/range_read.rs @@ -146,14 +146,12 @@ async fn straddling(version: Version, relay: bool) { } /// A range from below the live edge to past it reads the history and the live groups up -/// to its end, then ends. Draft-18 has no bounded SUBSCRIBE, so it refuses one. +/// to its end, then ends. Draft-18 has no bounded SUBSCRIBE, so it joins live and the +/// reader stops at its own end. #[kio::test] async fn a_range_across_the_live_edge_reads_up_to_its_end() { let mut failures = Vec::new(); - for version in support::every_version() - .into_iter() - .filter(|version| version.to_string() != "moq-transport-18") - { + for version in support::every_version() { for relay in [false, true] { if kio::clock::sim::spawn(straddling(version, relay)).await.is_err() { failures.push((version, relay)); From cc34b0bd256b234969767aec63a156fad3dbf746 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 14:18:25 -0800 Subject: [PATCH 17/20] fix(net): judge a head fill against the reader's window A bounded read's head fill went through `Fetching`, which refuses a group a newer cached one superseded, judged across the whole cache. A reader whose window leaves the newer group out, such as `0..1` with no max delay, then gave up a group it would read from a full copy. The cursor already judges the answer against its window when it hands it out, so a head fill leaves staleness to it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 57 +++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index f138c77529d..2025c44c7c3 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -5331,6 +5331,7 @@ impl Consumer { frame_end, priority: options.priority, max_delay: options.max_delay, + judges_drift: true, result: None, hit: Some(Box::new(group)), stats: self.stats.clone(), @@ -5351,6 +5352,7 @@ impl Consumer { frame_end, priority: options.priority, max_delay: options.max_delay, + judges_drift: true, result: None, hit: None, stats: self.stats.clone(), @@ -5676,6 +5678,9 @@ pub struct Fetching { priority: i8, // This caller's own age cap. None means only the publisher's max age. max_delay: Option, + // Whether this fetch refuses a group a newer cached one superseded, judged across the + // whole cache. A cursor's head fill leaves it to the cursor, which judges its window. + judges_drift: bool, // The fill this fetch joined; `None` on a cache hit, or when no handler existed to // queue on. Boxed: a miss already allocates, and the handle stays small. result: Option>, @@ -5725,12 +5730,21 @@ impl Fetching { frame_end: request.end, priority: request.options.priority, max_delay: request.options.max_delay, + judges_drift: true, result, hit, stats, resume: None, } } + + /// Leave staleness to the caller, a cursor filling a head: it judges the group against + /// its own window when it hands it out, where a newer group outside that window + /// supersedes nothing. + fn unjudged(mut self) -> Self { + self.judges_drift = false; + self + } } impl kio::Task for Fetching { @@ -5771,7 +5785,7 @@ impl kio::Task for Fetching { let state = state.read(); let budget = clamp_max_delay(self.max_delay.unwrap_or(Duration::MAX), state.max_age_bound()); let _ = state.cache.wakes().watch_landing(sequence, waiter); - if state.poll_drifted(sequence, &Servable::ALL, budget, None, waiter) { + if self.judges_drift && state.poll_drifted(sequence, &Servable::ALL, budget, None, waiter) { return Poll::Ready(Err(Error::Old)); } state.cache.clone() @@ -7818,7 +7832,9 @@ impl Cursor { }, end: None, }; - let mut fetching = Fetching::cached_or_queued(self.state.clone(), sequence, request, stats::Scope::default()); + // The cursor judges the answer against its window when it hands it out. + let mut fetching = + Fetching::cached_or_queued(self.state.clone(), sequence, request, stats::Scope::default()).unjudged(); let heads = self.heads.get_or_insert_default(); match kio::Task::poll(&mut fetching, waiter) { Poll::Pending => { @@ -17908,6 +17924,43 @@ mod test { assert!(ended, "the read ends with its range"); } + /// A head fill is judged against the reader's window, as the cursor judges a cached + /// group: a newer group outside the window leaves it fresh, even with no max delay. + #[kio::test] + #[cfg(feature = "async")] + async fn a_head_fill_is_judged_against_the_reader_window() { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.requests(); + + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + live.finish().unwrap(); + let mut newer = producer.create_group(group::Info { sequence: 1 }).unwrap(); + newer + .write_frame(Timestamp::from_secs(1).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + newer.finish().unwrap(); + + let mut sub = producer.subscribe(Subscription::default().with_range(0..1)); + let reading = kio::clock::sim::spawn(async move { + let group = sub.recv_group().await.unwrap().map(|group| group.sequence); + (group, sub.recv_group().await.unwrap().is_none()) + }); + let request = kio::clock::timeout(std::time::Duration::from_secs(1), dynamic.requested_fill_group()) + .await + .expect("the head is asked") + .unwrap(); + let mut head = request.accept(Info::timed()).unwrap(); + for payload in [&b"snapshot"[..], b"delta"] { + head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(payload)) + .unwrap(); + } + head.finish().unwrap(); + assert_eq!(reading.await.unwrap(), (Some(0), true)); + } + /// A head answered after the reader's ranges moved off its group is not handed out. #[kio::test] #[cfg(feature = "async")] From f2eeb3359c4b122ca77190b37f7576df9f186b00 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 14:24:12 -0800 Subject: [PATCH 18/20] fix(net): write off a head fill whose group went stale in the reader's window With head fills no longer judging staleness themselves, a head still asked when a newer group in the reader's window superseded it was never written off, so a bounded read waited on the fill. The cursor now judges each outstanding head against its own window and budget, parking on what can change the verdict, and writes a stale one off as `Old`, as it does a stale group in its walk. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 112 +++++++++++++++++++++++++++++----- 1 file changed, 96 insertions(+), 16 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 2025c44c7c3..9f8a85bd9e1 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7700,6 +7700,7 @@ impl Cursor { /// [`Self::poll_peek_recv`] once synced, judging against `drift`. fn poll_recv_with(&mut self, mut drift: Drift, waiter: &kio::Waiter) -> Poll>> { self.poll_heads(waiter); + self.expire_heads(&drift, waiter); loop { // Re-offer what a widening newly covers ahead of the arrival walk, in the // subscription's order: it is the oldest thing still owed. A group the walk has @@ -7724,6 +7725,7 @@ impl Cursor { if polled.is_pending() && self.watch_time(waiter) { self.admit(); drift = ready!(self.poll_drift(&self.servable, waiter))?; + self.expire_heads(&drift, waiter); continue; } let Some((producer, found_index)) = ready!(polled)? else { @@ -7765,22 +7767,7 @@ impl Cursor { // poll walks a whole backlog off rather than handing it out group by group. if ready!(self.poll_stale(&consumer, &drift, waiter))? { self.advance_arrival(consumer.sequence, taken); - self.stale.add(consumer.content()); - if let Some(drops) = &mut self.drops - && let Some(end) = consumer.sequence.checked_add(1) - { - drops.pending.insert(consumer.sequence..end, StreamError::Old); - } - match drift.bounded { - // A re-offered group stale at the bound is final. - true => self.skipped.remove(consumer.sequence), - false => self.skip(consumer.sequence, drift.budget), - } - // Whatever the window is now: narrowed to a bounded one later, it accounts for - // this group by it, even once the group left the cache. - if let Some(end) = consumer.sequence.checked_add(1) { - self.filter.written_off.insert(consumer.sequence..end); - } + self.write_off_stale(consumer.sequence, consumer.content(), &drift); continue; } if self.lacks_head(&consumer) { @@ -7795,6 +7782,27 @@ impl Cursor { } } + /// Write off group `sequence`, which the drift budget gave up on, as dropped `Old`: + /// skipped for a wider budget to offer again, unless the budget is at its bound. + fn write_off_stale(&mut self, sequence: u64, content: stats::Content, drift: &Drift) { + self.stale.add(content); + if let Some(drops) = &mut self.drops + && let Some(end) = sequence.checked_add(1) + { + drops.pending.insert(sequence..end, StreamError::Old); + } + match drift.bounded { + // A re-offered group stale at the bound is final. + true => self.skipped.remove(sequence), + false => self.skip(sequence, drift.budget), + } + // Whatever the window is now: narrowed to a bounded one later, it accounts for this + // group by it, even once the group left the cache. + if let Some(end) = sequence.checked_add(1) { + self.filter.written_off.insert(sequence..end); + } + } + /// Move the arrival cursor past a group it read: from the walk, to `index`; from what /// a widening owes, out of the owed spans. fn advance_arrival(&mut self, sequence: u64, taken: Taken) { @@ -7873,6 +7881,40 @@ impl Cursor { self.give_up_heads(given_up); } + /// Write off the heads still asked whose group went stale within this cursor's window, + /// so a bounded read never waits on a fill for a group it would not hand out. The cursor + /// judges what it hands out, so a head fill does not ([`Fetching::unjudged`]). + fn expire_heads(&mut self, drift: &Drift, waiter: &kio::Waiter) { + let Some(heads) = &self.heads else { return }; + if heads.fetching.is_empty() { + return; + } + let asked: Vec = heads.fetching.keys().copied().collect(); + let servable = self.servable.clone(); + let Poll::Ready(Ok(stale)) = self.poll(waiter, |state| { + let stale: Vec<(u64, stats::Content)> = asked + .iter() + .filter_map(|&sequence| { + let slot = state.lookup.get(&sequence)?; + // Parked first, so a group landing above while this judges wakes it. + let _ = state.cache.wakes().watch_landing(sequence, waiter); + state + .poll_drifted(sequence, &servable, drift.budget, None, waiter) + .then(|| (sequence, slot.group.consume().content())) + }) + .collect(); + Poll::Ready(Ok(stale)) + }) else { + return; + }; + for (sequence, content) in stale { + if let Some(heads) = &mut self.heads { + heads.fetching.remove(&sequence); + } + self.write_off_stale(sequence, content, drift); + } + } + /// Give up the groups whose head no fill can serve, as a refused miss is. fn give_up_heads(&mut self, given_up: impl IntoIterator>) { let mut given_up = given_up.into_iter().peekable(); @@ -17961,6 +18003,44 @@ mod test { assert_eq!(reading.await.unwrap(), (Some(0), true)); } + /// A head still asked when a newer group in the reader's window supersedes it is + /// written off, so the bounded read ends without waiting on the fill. + #[kio::test] + #[cfg(feature = "async")] + async fn a_head_still_asked_goes_stale_within_the_window() { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.requests(); + + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + live.finish().unwrap(); + + let mut sub = producer.subscribe(Subscription::default().with_range(0..2)); + assert!(sub.recv_group().now_or_never().is_none(), "the head is still asked"); + let request = dynamic.requested_fill_group().now_or_never().unwrap().unwrap(); + assert_eq!(request.sequence(), 0); + + let mut newer = producer.create_group(group::Info { sequence: 1 }).unwrap(); + newer + .write_frame(Timestamp::from_millis(1).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + newer.finish().unwrap(); + let group = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) + .await + .expect("group 1 timed out") + .unwrap() + .expect("group 1"); + assert_eq!(group.sequence, 1); + let end = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) + .await + .expect("the read never ended") + .unwrap(); + assert!(end.is_none(), "the read ends with group 0 written off"); + drop(request); + } + /// A head answered after the reader's ranges moved off its group is not handed out. #[kio::test] #[cfg(feature = "async")] From b1c22fcd6eb3a3ffb1abbb8db08b6d751fcacf6a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 14:28:36 -0800 Subject: [PATCH 19/20] fix(net): expire a head fill whose headless copy the cache evicted `expire_heads` judged only heads whose headless copy was still cached, so an eviction left a stale head asked and the bounded read waiting on it. The drift check judges a group whether or not the track holds it, so judge every head still asked and take its content from the cache only when it is there. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 78 +++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 31 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 9f8a85bd9e1..0cef9ed13f0 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7895,12 +7895,22 @@ impl Cursor { let stale: Vec<(u64, stats::Content)> = asked .iter() .filter_map(|&sequence| { - let slot = state.lookup.get(&sequence)?; // Parked first, so a group landing above while this judges wakes it. let _ = state.cache.wakes().watch_landing(sequence, waiter); + // Judged whether or not the cache still holds the headless copy: an evicted + // one goes stale all the same, and counts as a group of unknown size. state .poll_drifted(sequence, &servable, drift.budget, None, waiter) - .then(|| (sequence, slot.group.consume().content())) + .then(|| { + let content = match state.lookup.get(&sequence) { + Some(slot) => slot.group.consume().content(), + None => stats::Content { + groups: 1, + ..Default::default() + }, + }; + (sequence, content) + }) }) .collect(); Poll::Ready(Ok(stale)) @@ -18004,41 +18014,47 @@ mod test { } /// A head still asked when a newer group in the reader's window supersedes it is - /// written off, so the bounded read ends without waiting on the fill. + /// written off, so the bounded read ends without waiting on the fill, whether or not the + /// cache still holds the headless copy. #[kio::test] #[cfg(feature = "async")] async fn a_head_still_asked_goes_stale_within_the_window() { - let producer = track_producer("test", Info::timed()); - let dynamic = producer.requests(); + for evict in [false, true] { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.requests(); - let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); - live.start_at(1).unwrap(); - live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) - .unwrap(); - live.finish().unwrap(); + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + live.finish().unwrap(); - let mut sub = producer.subscribe(Subscription::default().with_range(0..2)); - assert!(sub.recv_group().now_or_never().is_none(), "the head is still asked"); - let request = dynamic.requested_fill_group().now_or_never().unwrap().unwrap(); - assert_eq!(request.sequence(), 0); + let mut sub = producer.subscribe(Subscription::default().with_range(0..2)); + assert!(sub.recv_group().now_or_never().is_none(), "the head is still asked"); + let request = dynamic.requested_fill_group().now_or_never().unwrap().unwrap(); + assert_eq!(request.sequence(), 0); - let mut newer = producer.create_group(group::Info { sequence: 1 }).unwrap(); - newer - .write_frame(Timestamp::from_millis(1).unwrap(), bytes::Bytes::from_static(b"x")) - .unwrap(); - newer.finish().unwrap(); - let group = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) - .await - .expect("group 1 timed out") - .unwrap() - .expect("group 1"); - assert_eq!(group.sequence, 1); - let end = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) - .await - .expect("the read never ended") - .unwrap(); - assert!(end.is_none(), "the read ends with group 0 written off"); - drop(request); + let mut newer = producer.create_group(group::Info { sequence: 1 }).unwrap(); + newer + .write_frame(Timestamp::from_millis(1).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + newer.finish().unwrap(); + if evict { + producer.modify().unwrap().evict_group(0, Error::Evicted); + } + let group = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) + .await + .expect("group 1 timed out") + .unwrap() + .expect("group 1"); + assert_eq!(group.sequence, 1, "evict={evict}"); + let end = kio::clock::timeout(std::time::Duration::from_secs(1), sub.recv_group()) + .await + .unwrap_or_else(|_| panic!("evict={evict}: the read never ended")) + .unwrap(); + assert!(end.is_none(), "evict={evict}: the read ends with group 0 written off"); + drop(request); + } } /// A head answered after the reader's ranges moved off its group is not handed out. From 092d075c8dcca40c2c8de3ed72216ca03e54c344 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 15:29:14 -0800 Subject: [PATCH 20/20] fix(net): end a read range after a route switch and hand out heads in order A bounded read whose whole window was handed out parked after a route switch: the replaced copy, still live and never bounded, counted as one that may still deliver. A replaced copy is now kept rather than waited on once the reader holds every group of its bounded window, so the read ends and a widening judges the copy again. Answered head fills went out lowest first whatever the subscription's order; they now follow it, as owed and filled groups do. Also state one bounded-completion rule in the JS ranges quest. Co-Authored-By: Claude Opus 5.5 --- quest/m1/subscribe-ranges/js.md | 18 +++++---- rs/moq-net/src/model/resume.rs | 68 ++++++++++++++++++++++++++++++++- rs/moq-net/src/model/track.rs | 52 ++++++++++++++++++++++++- 3 files changed, 126 insertions(+), 12 deletions(-) diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 0caa660ce69..807e1308773 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -17,14 +17,16 @@ the ranges model, anchors, `maxDelay: null`, and the on-demand request surface. Rust's lite-07 SUBSCRIBE already carries ranges ([moq-dev/moq#6715](https://github.com/moq-dev/moq/pull/6715)). -Mirror lite-07 bounded completion in the publisher. Today a covered bounded -subscription FINs without SUBSCRIBE_END. The JS subscriber already accepts that -FIN, closing the request's track once its tail settles, and failing it when an -update moved the range and the groups that arrived leave it uncovered. Reopen -that demand on the same track instead, as the Rust copy does. The settled -replacement, SUBSCRIBE_FINISH with the Subscribe Stream kept open and no -covered FIN, is in [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md)' -"Ends are signaled" plan; mirror whichever the wire has when this lands. +Mirror lite-07 bounded completion as the Rust copy implements it when this +lands. The target is [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md)' +"Ends are signaled" design: a covered bounded subscription sends +SUBSCRIBE_FINISH, keeps the Subscribe Stream open, and never FINs it. This +quest does not wait on that one, so if it lands first, the wire still FINs a +covered bounded subscription without SUBSCRIBE_END. The JS subscriber already +accepts that FIN, closing the request's track once its tail settles, and +failing it when an update moved the range and the groups that arrived leave it +uncovered; until SUBSCRIBE_FINISH ships it reopens that demand on the same +track instead, as the Rust copy does. Mirror the Rust names, including `Time(pts)` ends and their refusal on an untimed track. The publisher resolves no relative or time start, serving it from the oldest diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index df1c50b5a46..d243b23d069 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -588,9 +588,14 @@ impl Copy { if !reader.groups_read { return Retains::No; } - // Not yet bounded, it may still feed a group the new copy never has. + // Not yet bounded, it may still feed a group the new copy never has, unless the reader + // already holds every group of a bounded window. Then it is kept rather than waited + // on, so the read ends, and a widening judges it again. if self.until.is_none() && self.done.is_none() { - return Retains::Wait; + return match reader.holds_window() { + true => Retains::Keep, + false => Retains::Wait, + }; } // Superseded once the serving copy has a group past the bound. if self.since.is_none() @@ -669,6 +674,22 @@ struct Retain<'a> { waiter: &'a kio::Waiter, } +impl Retain<'_> { + /// Whether the reader handed out every group its bounded, resolved window names. + fn holds_window(&self) -> bool { + let Some(end) = self.window.end().filter(|_| !self.window.is_pending()) else { + return false; + }; + self.window + .runs(self.window.floor().unwrap_or(0)) + .take_while(|run| *run.start() < end) + .all(|run| { + let run = *run.start()..run.end().saturating_add(1).min(end); + self.delivered.gaps(run).is_empty() + }) + } +} + /// How a reader still needs a replaced copy; see [`Copy::retains`]. enum Retains { /// It may still deliver a group the reader lacks. @@ -4127,6 +4148,49 @@ mod test { } } + /// A bounded read whose whole window was handed out ends after a route switch, to a copy + /// with nothing or only a group already read, though the replaced copy is still live. + #[test] + fn a_read_range_ends_after_a_switch_to_a_repeating_route() { + for ordered in [false, true] { + for repeats in [false, true] { + let case = format!("ordered={ordered}, repeats={repeats}"); + let routes = Producer::new(); + let logical = logical(&routes); + let a = copy(); + routes.serve(a.consume()); + let subscription = Subscription::default().with_max_delay(HOUR).with_range(0..1); + let mut sub = logical + .consume() + .subscribe(subscription) + .now_or_never() + .unwrap() + .unwrap(); + write(&a, 0); + assert_eq!(drain(&mut sub, ordered), [0], "{case}"); + let b = copy(); + if repeats { + write(&b, 0); + } + routes.serve(b.consume()); + let res = match ordered { + true => sub.poll_next_group(&kio::Waiter::noop()), + false => sub.poll_recv_group(&kio::Waiter::noop()), + }; + let res = res.map(|res| res.map(|group| group.map(|group| group.sequence))); + assert!( + matches!(res, Poll::Ready(Ok(None))), + "{case}: the read ends, got {res:?}" + ); + // The replaced copy was kept, so a widening still reads what only it has. + write(&a, 1); + sub.update(Subscription::default().with_max_delay(HOUR).with_range(0..2)) + .unwrap(); + assert_eq!(drain(&mut sub, ordered), [1], "{case}"); + } + } + } + /// A replaced copy is bounded only once the new copy delivers its first group: a group /// buffered on it must be read before a later group on the serving copy. #[test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 0cef9ed13f0..88f496f598c 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7943,10 +7943,15 @@ impl Cursor { } } - /// The lowest head answered and not handed out yet. + /// The next head answered and not handed out yet, in the subscription's order. fn next_head(&self) -> Option { let heads = self.heads.as_ref()?; - heads.filled.values().next().cloned() + let mut filled = heads.filled.values(); + match self.subscription.read().order { + Order::Ascending => filled.next(), + Order::Descending => filled.next_back(), + } + .cloned() } /// The next datagram inside this subscriber's range, dropping the ones outside it. @@ -18057,6 +18062,49 @@ mod test { } } + /// Answered heads go out in the subscription's order, as owed and filled groups do. + #[kio::test] + #[cfg(feature = "async")] + async fn answered_heads_go_out_in_the_subscription_order() { + for (order, expected) in [(Order::Ascending, [0, 1]), (Order::Descending, [1, 0])] { + let producer = track_producer("test", Info::default()); + let dynamic = producer.requests(); + for sequence in 0..2 { + let mut live = producer.create_group(group::Info { sequence }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(None, bytes::Bytes::from_static(b"delta")).unwrap(); + live.finish().unwrap(); + } + + let mut sub = producer.subscribe(replay().with_order(order).with_range(0..2)); + assert!( + sub.recv_group().now_or_never().is_none(), + "{order:?}: the heads are asked" + ); + let mut requests = Vec::new(); + while let Some(request) = dynamic.requested_fill_group().now_or_never() { + requests.push(request.unwrap()); + } + assert_eq!(requests.len(), 2, "{order:?}: both heads are asked"); + for request in requests { + let mut head = request.accept(Info::default()).unwrap(); + head.write_frame(None, bytes::Bytes::from_static(b"snapshot")).unwrap(); + head.finish().unwrap(); + } + + let mut got = Vec::new(); + for _ in 0..2 { + let group = sub.recv_group().now_or_never().unwrap().unwrap().expect("a head"); + got.push(group.sequence); + } + assert_eq!(got, expected, "{order:?}"); + assert!( + matches!(sub.recv_group().now_or_never(), Some(Ok(None))), + "{order:?}: the read ends" + ); + } + } + /// A head answered after the reader's ranges moved off its group is not handed out. #[kio::test] #[cfg(feature = "async")]