From 949406e0721c50993a9d68666b055dfb9eedfcf6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 08:32:28 -0800 Subject: [PATCH 1/9] chore(quest): claim quest/m2/min-age-join.md Quest-Claim: 3a62c67a5d8fa9e5 From 7eb963788accebdaddce607a7aaf38665b20bacf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:07:07 -0800 Subject: [PATCH 2/9] feat(net): a live join reaches back by its Subscriber Min Age A subscription following the live edge from the latest or the oldest group, stating a nonzero Min Age, starts at the newest group that began that far behind the newest frame the serving hop holds (by arrival on a scale-less track). Relays forward the largest stated Min Age. A SUBSCRIBE_UPDATE changing no term still re-drops a stale group. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/lite/publisher.rs | 6 +- rs/moq-net/src/model/resume.rs | 10 +- rs/moq-net/src/model/subscription.rs | 23 +- rs/moq-net/src/model/subscription/window.rs | 135 ++++++--- rs/moq-net/src/model/track.rs | 262 ++++++++++++++++-- rs/moq-net/src/model/track/demand.rs | 5 +- rs/moq-net/tests/integration/main.rs | 1 + rs/moq-net/tests/integration/min_age_join.rs | 76 +++++ .../tests/integration/subscriber_max_age.rs | 15 +- 9 files changed, 448 insertions(+), 85 deletions(-) create mode 100644 rs/moq-net/tests/integration/min_age_join.rs diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index f60f510f90d..a5e2f461dab 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -8805,8 +8805,8 @@ mod serve_group_test { /// A stale group already named in SUBSCRIBE_DROP stays dropped before lite-07 after any /// SUBSCRIBE_UPDATE, since those subscribers settle a drop for good. Lite-07 reopens it on /// every update: one that widens the max age past it serves it, and one that keeps the - /// budget drops it again under the new update's number. The groups served around it are - /// never resent. + /// budget, changing no term at all, drops it again under the new update's number. The + /// groups served around it are never resent. #[kio::test] async fn any_update_reoffers_a_reported_stale_drop_on_lite07_alone() { for version in [Version::Lite05, Version::Lite06, Version::Lite07] { @@ -8835,7 +8835,7 @@ mod serve_group_test { wanted_group: None, priority: 0, max_delay: if widen { Duration::from_secs(10) } else { budget }, - min_delay: None, + min_delay: Some(Duration::ZERO), ranges: vec![(0, lite::Range::span(None, 0, None, None))], order: Order::Descending, update: 1, diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 666c7a21c09..63545d0c28d 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -161,7 +161,7 @@ impl Producer { }) if *from == preferences.ranges => sub.resolved_ranges(), Some(Copy { sub: Sub::Ready(sub), .. - }) => sub.resolve_ranges(&preferences.ranges), + }) => sub.resolve_ranges(&preferences), Some(copy) if copy.from == preferences.ranges => copy.resolved.clone(), _ => Vec::new(), }; @@ -382,7 +382,7 @@ impl Consumer { /// Subscribe to the logical track with the reader's own preferences. pub(super) fn subscribe(&self, subscription: track::Preferences) -> Subscriber { let mirrored = subscription.read().clone(); - let window = Window::new(&mirrored.ranges, None, &Unheld).expect("an unheld hop refuses nothing"); + let window = Window::new(&mirrored.ranges, None, None, &Unheld).expect("an unheld hop refuses nothing"); let reader = Arc::new_cyclic(|this| { Mutex::new(Reader { this: this.clone(), @@ -552,7 +552,7 @@ impl Copy { Sub::Ready(sub) if reader.ranges == self.from => self.resolved = sub.resolved_ranges(), // Replaced ranges resolve against this copy's cache now, as any subscriber's do. Sub::Ready(sub) => { - self.resolved = sub.resolve_ranges(&reader.ranges); + self.resolved = sub.resolve_ranges(reader); self.from = reader.ranges.clone(); } Sub::Pending(_) if reader.ranges == self.from => {} @@ -1218,7 +1218,7 @@ impl Reader { if unplaced { return; } - let window = Window::new(&ranges, None, &Placed).expect("a placed hop refuses nothing"); + let window = Window::new(&ranges, None, None, &Placed).expect("a placed hop refuses nothing"); if !window.is_pending() { self.window = window; } @@ -1241,7 +1241,7 @@ impl Reader { if let Some(sub) = changed { let replaced = sub.ranges != self.mirrored.ranges; if replaced { - self.window = Window::new(&sub.ranges, None, &Unheld).expect("an unheld hop refuses nothing"); + self.window = Window::new(&sub.ranges, None, None, &Unheld).expect("an unheld hop refuses nothing"); // The serving copy's resume point may cut off groups the new ranges cover, judged // by the reader's window. self.resumed = Some((None, Vec::new())); diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 984a08420bf..6f998450488 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -58,11 +58,20 @@ pub struct Delay { /// The target latency, the playout or jitter-buffer delay held behind the live edge, or /// `None` when the subscriber did not state one. /// - /// Only a peer whose wire cannot carry it leaves it unstated: moq-lite before 07 and - /// moq-transport. A media consumer reads an unstated minimum as zero. The aggregate - /// across subscribers is the smallest stated one, so an unstated minimum never pulls it - /// to zero, and a relay forwards it upstream as is. A publisher may use it, such as to - /// start a cold join that far back; nothing reads it there yet. + /// A join that follows the live edge from [`Range::live`] or [`Range::oldest`] starts this + /// far behind it: at the newest group that began at or before the live edge minus this, + /// so a player's buffer arrives full instead of filling in real time, and no fuller. The + /// hop serving it measures from what it holds: in media time from the newest frame on a + /// timed track, and by arrival on its own clock on a scale-less one. With no such group + /// held it starts at the oldest one, and never fetches upstream for more. [`Self::max`] + /// still skips what has gone stale. A start naming a group or a count back, a range with + /// an end, and a resumed subscription ignore it, and changing it later moves nothing + /// already started. Zero or unstated asks for no reach back, so the range alone decides. + /// + /// A media consumer reads an unstated minimum as zero. The aggregate across subscribers is + /// the largest stated one, which a relay forwards upstream, so the copy it fills reaches + /// back for the reader that buffers most; each reader's own minimum then bounds what it + /// reads of that copy. moq-lite before 07 and moq-transport cannot carry it. /// /// This is the `Subscriber Min Age` on the moq-lite-07 wire, in milliseconds. pub min: Option, @@ -551,7 +560,7 @@ impl Combined { _ => None, }; combined.delay.min = match (combined.delay.min, sub.delay.min) { - (Some(a), Some(b)) => Some(a.min(b)), + (Some(a), Some(b)) => Some(a.max(b)), (a, b) => a.or(b), }; combined.ranges.extend_from_slice(&sub.ranges); @@ -769,7 +778,7 @@ mod tests { /// group exists only the farthest offset resolves, since it is group 0 regardless. #[test] fn relative_starts_resolve_against_the_latest_group() { - let floor = |sub: &Subscription, latest| Window::new(&sub.ranges, latest, &Contiguous).unwrap().floor(); + let floor = |sub: &Subscription, latest| Window::new(&sub.ranges, None, latest, &Contiguous).unwrap().floor(); let live = Subscription::default().with_ranges([Range::live()]); assert_eq!(floor(&live, Some(7)), Some(7)); diff --git a/rs/moq-net/src/model/subscription/window.rs b/rs/moq-net/src/model/subscription/window.rs index 88a10efc891..4665714be16 100644 --- a/rs/moq-net/src/model/subscription/window.rs +++ b/rs/moq-net/src/model/subscription/window.rs @@ -4,7 +4,7 @@ //! what arrives, not what one subscriber asked for. A [`Window`] is the per-subscriber //! side: resolved at the hop serving the subscriber, it filters that subscriber's reads. -use std::{ops, sync::Arc}; +use std::{ops, sync::Arc, time::Duration}; use super::{Anchor, Layered, Range, Runs}; use crate::{Error, Result}; @@ -75,6 +75,15 @@ pub(in crate::model) trait Holdings { /// to the oldest group rather than wait. fn complete(&self) -> bool; + /// Where a live join holding `min` behind the live edge starts, `latest` being the latest + /// group: the time that far behind the newest frame held, a group that starts at or + /// before it, or [`Anchor::Oldest`] when none held does. `None` while nothing held can + /// measure it, so the join waits for a group as a relative start does. + fn reach_back(&self, latest: u64, min: Duration) -> Option { + let _ = (latest, min); + None + } + /// Whether the producer declared every key in `keys` skipped, so no group starts there /// even in the history a handler serves. fn never_produced(&self, keys: ops::Range) -> bool { @@ -124,6 +133,8 @@ impl Holdings for Unheld { pub(in crate::model) struct Window { /// What these were resolved from, so only replacing the ranges resolves again. ranges: Vec, + /// The subscriber's Min Age, which reaches a live join back from the live edge. + min: Option, spans: Vec, /// The spans still looking up their time start (see [`Self::found`]), which read nothing /// meanwhile: kept apart so a probe finds them without visiting every span. @@ -154,6 +165,8 @@ pub(in crate::model) struct Window { struct Span { /// Which of the ranges it came from. index: usize, + /// Where it starts: its range's start, or where a live join's Min Age reached it back to. + anchor: Anchor, start: u64, /// The exclusive end, `None` past every group. end: Option, @@ -176,14 +189,16 @@ struct Looking { } impl Window { - /// Resolve `ranges`, counting relative anchors back from `latest`. + /// Resolve `ranges`, counting relative anchors back from `latest`, and reaching a live + /// join back by `min` (see [`joins`]). /// /// Refuses an [`Anchor::Oldest`] end with [`Error::InvalidRange`] where the hop /// [resolves](Holdings::resolves) ranges itself, and an anchor a received copy's wire /// drops with [`Error::Unsupported`]. - pub fn new(ranges: &[Range], latest: Option, holdings: &impl Holdings) -> Result { + pub fn new(ranges: &[Range], min: Option, latest: Option, holdings: &impl Holdings) -> Result { let mut window = Self { ranges: ranges.to_vec(), + min, spans: Vec::new(), looking: Vec::new(), waiting: Vec::new(), @@ -237,7 +252,7 @@ impl Window { fn start_waiting(&mut self, holdings: &impl Holdings) -> bool { let mut started = false; for position in std::mem::take(&mut self.waiting) { - let Anchor::Time(time) = self.ranges[self.spans[position].index].start else { + let Anchor::Time(time) = self.spans[position].anchor else { unreachable!("only a time start waits on a group"); }; let (start, floored) = match holdings.containing(time) { @@ -263,9 +278,10 @@ impl Window { /// where the groups held can't place it, as when first resolved, and otherwise reading /// its groups. fn start_span(&mut self, position: usize, time: u64, start: u64, floored: bool, holdings: &impl Holdings) { + let asked = matches!(self.ranges[self.spans[position].index].start, Anchor::Time(_)); let span = &mut self.spans[position]; (span.start, span.floored, span.waiting) = (start, floored, false); - if let Some(below) = unresolved(time, start, floored, holdings) { + if let Some(below) = unresolved(time, start, floored, holdings).filter(|_| asked) { span.looking = Some(Looking { time, below }); self.looking.push(position); } @@ -485,7 +501,18 @@ impl Window { self.pending = true; continue; }; - let (start, floored) = match start(range.start, latest, holdings) { + let anchor = match joins(range, self.min, holdings) { + None => range.start, + Some(min) => match latest.map(|latest| holdings.reach_back(latest, min)) { + Some(Some(anchor)) => anchor, + // Nothing to measure the live edge by yet. + _ => { + self.pending = true; + continue; + } + }, + }; + let (start, floored) = match start(anchor, latest, holdings) { Start::At(start, floored) => (start, floored), Start::Pending => { self.pending = true; @@ -497,6 +524,7 @@ impl Window { self.waiting.push(self.spans.len()); self.spans.push(Span { index, + anchor, start: 0, end, floored: false, @@ -506,9 +534,12 @@ impl Window { continue; } }; - // A time start the groups held can't place reads nothing until its lookup answers. - let looking = match range.start { - Anchor::Time(time) => unresolved(time, start, floored, holdings).map(|below| Looking { time, below }), + // A time start the groups held can't place reads nothing until its lookup answers. A + // join's reach back never looks one up: it starts from what this hop holds. + let looking = match (range.start, anchor) { + (Anchor::Time(_), Anchor::Time(time)) => { + unresolved(time, start, floored, holdings).map(|below| Looking { time, below }) + } _ => None, }; if looking.is_some() { @@ -516,6 +547,7 @@ impl Window { } self.spans.push(Span { index, + anchor, start, end, floored, @@ -554,7 +586,7 @@ impl Window { // there, as one reaching back past every group held does: whichever group contains // it starts at or before it, so every group from there on is in range. if span.waiting { - if let Anchor::Time(time) = self.ranges[span.index].start + if let Anchor::Time(time) = span.anchor && time <= last { groups.push(time..=last); @@ -571,7 +603,7 @@ impl Window { // on is in range, the key at the time itself being the containing group if it // exists. A relative one counting back past every group held asks none below the // oldest, since which of them it reaches is unknown. - let reach = match (self.ranges[span.index].start, span.floored) { + let reach = match (span.anchor, span.floored) { (Anchor::Time(time), false) => time, (Anchor::Relative(_), false) => holdings.next_start(0).unwrap_or(span.start), _ => span.start, @@ -585,6 +617,15 @@ impl Window { } } +/// The Min Age a live join reaches back by: a nonzero `min`, for a range that follows the live +/// edge from the latest or the oldest group, where this hop resolves its own ranges. A start +/// naming a group or a count back wins, as does a range with an end. A zero or unstated +/// minimum asks for no reach back, so the range alone decides. +fn joins(range: &Range, min: Option, holdings: &impl Holdings) -> Option { + let live = matches!(range.start, Anchor::Oldest | Anchor::Relative(0)) && range.end.is_none(); + min.filter(|min| !min.is_zero() && live && holdings.resolves()) +} + /// Where a range starts. enum Start { /// At this group, and whether it names that group rather than reaching back to the @@ -742,7 +783,7 @@ mod tests { fn ranges_cover_only_their_groups() { let keys = Keys::new(0..10); let ranges = [range(time(2), time(3)), range(time(7), None)]; - let window = Window::new(&ranges, Some(9), &keys).unwrap(); + let window = Window::new(&ranges, None, Some(9), &keys).unwrap(); assert_eq!(covered(&window, 0..10), vec![2, 3, 7, 8, 9]); assert_eq!(window.floor(), Some(2)); assert_eq!(window.end(), None); @@ -770,7 +811,7 @@ mod tests { assert_eq!(window.starts(5), [None, Some(7)]); // Nothing asked for is nothing in range, floored nowhere. - let window = Window::new(&[], None, &keys).unwrap(); + let window = Window::new(&[], None, None, &keys).unwrap(); assert_eq!(covered(&window, 0..4), Vec::::new()); assert_eq!((window.floor(), window.end()), (Some(0), Some(0))); } @@ -780,7 +821,7 @@ mod tests { #[test] fn time_anchors_name_groups_by_their_starts() { let keys = Keys::new([0, 33, 66, 99]); - let window = Window::new(&[range(time(50), time(70))], Some(99), &keys).unwrap(); + let window = Window::new(&[range(time(50), time(70))], None, Some(99), &keys).unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), vec![33, 66]); assert!(window.is_settled()); assert_eq!( @@ -793,16 +834,16 @@ mod tests { ); // A start exactly on a group names that group, and an end on one includes it. - let window = Window::new(&[range(time(33), time(66))], Some(99), &keys).unwrap(); + let window = Window::new(&[range(time(33), time(66))], None, Some(99), &keys).unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), vec![33, 66]); // An end before its start is empty, and so is one ending before every group. - let window = Window::new(&[range(time(66), time(33))], Some(99), &keys).unwrap(); + let window = Window::new(&[range(time(66), time(33))], None, Some(99), &keys).unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), Vec::::new()); // Before every start held: reach back to the group containing it, naming no floor. let keys = Keys::new([10, 20]); - let window = Window::new(&[range(time(5), None)], Some(20), &keys).unwrap(); + let window = Window::new(&[range(time(5), None)], None, Some(20), &keys).unwrap(); assert_eq!(covered(&window, [10, 20]), vec![10, 20]); assert_eq!((window.floor(), window.start(), window.named()), (Some(0), None, None)); assert_eq!(window.missable(0).next(), Some(5..=u64::MAX), "nothing below its time"); @@ -813,19 +854,25 @@ mod tests { #[test] fn relative_anchors_count_groups_back_from_the_latest() { let keys = Keys::new([0, 33, 66, 99]); - let window = Window::new(&[range(Anchor::Relative(2), Anchor::Relative(1))], Some(99), &keys).unwrap(); + let window = Window::new( + &[range(Anchor::Relative(2), Anchor::Relative(1))], + None, + Some(99), + &keys, + ) + .unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), vec![33, 66]); assert_eq!(window.start(), Some(33)); // Counting back past every group held reaches back to the oldest as a start, and ends // before them all as an end. - let window = Window::new(&[range(Anchor::Relative(10), None)], Some(99), &keys).unwrap(); + let window = Window::new(&[range(Anchor::Relative(10), None)], None, Some(99), &keys).unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), vec![0, 33, 66, 99]); assert_eq!(window.start(), None); - let window = Window::new(&[range(Anchor::Oldest, Anchor::Relative(10))], Some(99), &keys).unwrap(); + let window = Window::new(&[range(Anchor::Oldest, Anchor::Relative(10))], None, Some(99), &keys).unwrap(); assert_eq!(covered(&window, [0, 33, 66, 99]), Vec::::new()); - let mut window = Window::new(&[Range::live()], None, &Keys::default()).unwrap(); + let mut window = Window::new(&[Range::live()], None, None, &Keys::default()).unwrap(); assert!(window.is_pending() && window.contains(3) && window.floor().is_none()); assert!(!window.settle(None, &Keys::default())); let keys = Keys::new([5]); @@ -834,15 +881,15 @@ mod tests { assert!(window.is_settled()); // The oldest start needs no latest group, and names no floor. - let window = Window::new(&[Range::oldest()], None, &keys).unwrap(); + let window = Window::new(&[Range::oldest()], None, None, &keys).unwrap(); assert_eq!((window.floor(), window.start()), (Some(0), None)); // Any count back, however far, waits on a latest group. for back in [u64::MAX, u64::MAX - 1] { let open = range(Anchor::Relative(back), None); assert!(!open.is_wire()); - assert!(Window::new(&[open], None, &keys).unwrap().is_pending()); - assert_eq!(Window::new(&[open], Some(5), &keys).unwrap().start(), None); + assert!(Window::new(&[open], None, None, &keys).unwrap().is_pending()); + assert_eq!(Window::new(&[open], None, Some(5), &keys).unwrap().start(), None); } } @@ -851,11 +898,11 @@ mod tests { fn an_oldest_end_is_refused() { let ranges = [range(time(0), Anchor::Oldest)]; assert!(matches!( - Window::new(&ranges, Some(3), &Keys::new(0..4)), + Window::new(&ranges, None, Some(3), &Keys::new(0..4)), Err(Error::InvalidRange) )); // A hop holding no groups leaves the refusal to the copies that do. - assert!(Window::new(&ranges, Some(3), &Unheld).is_ok()); + assert!(Window::new(&ranges, None, Some(3), &Unheld).is_ok()); } /// The named floor is the lowest start, unless a range reaches back to the oldest @@ -863,7 +910,7 @@ mod tests { #[test] fn the_named_start_is_the_lowest_unless_one_reaches_back() { let keys = Keys::new(0..10); - let start = |ranges: &[Range], latest| Window::new(ranges, latest, &keys).unwrap().start(); + let start = |ranges: &[Range], latest| Window::new(ranges, None, latest, &keys).unwrap().start(); assert_eq!(start(&[range(time(4), None), Range::live()], Some(9)), Some(4)); assert_eq!(start(&[range(time(4), None), Range::live()], Some(2)), Some(2)); assert_eq!(start(&[range(time(0), None)], None), Some(0)); @@ -878,7 +925,7 @@ mod tests { fn a_time_start_waits_for_a_group() { let mut keys = Keys::default(); let ranges = [range(time(2500), None), range(Anchor::Relative(0), Anchor::Relative(0))]; - let mut window = Window::new(&ranges, Some(9), &keys).unwrap(); + let mut window = Window::new(&ranges, None, Some(9), &keys).unwrap(); assert!(!window.is_pending() && !window.is_settled()); assert_eq!(covered(&window, 0..22), vec![9], "only the other range reads below it"); assert_eq!( @@ -912,7 +959,7 @@ mod tests { "3000 starts past it" ); keys.held.insert(2000); - let window = Window::new(&ranges, Some(3000), &keys).unwrap(); + let window = Window::new(&ranges, None, Some(3000), &keys).unwrap(); assert_eq!( window.resolved()[0], Some(Resolved { @@ -927,7 +974,7 @@ mod tests { complete: true, ..Keys::default() }; - let window = Window::new(&ranges, Some(9), &keys).unwrap(); + let window = Window::new(&ranges, None, Some(9), &keys).unwrap(); assert_eq!( window.resolved()[0], Some(Resolved { @@ -945,7 +992,7 @@ mod tests { for latest in [None, Some(9)] { let mut keys = Keys::default(); let ranges = [range(time(2500), Anchor::Relative(0))]; - let mut window = Window::new(&ranges, latest, &keys).unwrap(); + let mut window = Window::new(&ranges, None, latest, &keys).unwrap(); assert_eq!(window.is_pending(), latest.is_none()); keys.held.extend([2000, 3000]); assert!(window.settle(Some(3000), &keys)); @@ -965,7 +1012,7 @@ mod tests { fn coverage_resumes_within_what_was_checked() { let keys = Keys::new(0..6); let ranges = [range(time(0), time(1)), range(time(4), time(5))]; - let mut window = Window::new(&ranges, None, &keys).unwrap(); + let mut window = Window::new(&ranges, None, None, &keys).unwrap(); let accounted = rangemap::RangeSet::from_iter([0..1, 4..6]); assert!(window.covered_by(4, None, &accounted)); assert!( @@ -986,7 +1033,7 @@ mod tests { /// behind where it stopped. #[test] fn coverage_resumes_within_a_range() { - let mut window = Window::new(&[range(time(0), time(7))], None, &Keys::new(0..8)).unwrap(); + let mut window = Window::new(&[range(time(0), time(7))], None, None, &Keys::new(0..8)).unwrap(); let mut accounted = rangemap::RangeSet::from_iter(std::iter::once(0..3)); assert!(!window.covered_by(0, None, &accounted)); assert_eq!(window.covered, Some((0, 3)), "stops at the first missing group"); @@ -1002,7 +1049,7 @@ mod tests { #[test] fn coverage_reads_a_map_of_the_groups_accounted_for() { let ranges = [range(time(0), time(1)), range(time(4), time(5))]; - let mut window = Window::new(&ranges, None, &Keys::new(0..6)).unwrap(); + let mut window = Window::new(&ranges, None, None, &Keys::new(0..6)).unwrap(); let mut accounted = rangemap::RangeMap::new(); accounted.insert(0..2, 'a'); accounted.insert(4..5, 'b'); @@ -1019,7 +1066,7 @@ mod tests { fn a_time_start_the_groups_cant_place_is_looked_up() { let mut keys = Keys::new([4000, 9000]); keys.looks_up = true; - let mut window = Window::new(&[range(time(8500), None)], Some(9000), &keys).unwrap(); + let mut window = Window::new(&[range(time(8500), None)], None, Some(9000), &keys).unwrap(); assert_eq!(window.lookups().collect::>(), [(8500, 9000)]); assert!(!window.is_settled() && !window.contains(9000) && window.resolved() == [None]); keys.held.insert(8000); @@ -1034,12 +1081,12 @@ mod tests { ); assert!(window.is_settled()); - let window = Window::new(&[range(time(8500), None)], Some(9000), &keys).unwrap(); + let window = Window::new(&[range(time(8500), None)], None, Some(9000), &keys).unwrap(); assert_eq!(window.lookups().count(), 1, "something may start between 8000 and 8500"); - let window = Window::new(&[range(time(8000), None)], Some(9000), &keys).unwrap(); + let window = Window::new(&[range(time(8000), None)], None, Some(9000), &keys).unwrap(); assert_eq!(window.lookups().count(), 0, "8000 starts exactly there"); - let mut window = Window::new(&[range(time(500), None)], Some(9000), &keys).unwrap(); + let mut window = Window::new(&[range(time(500), None)], None, Some(9000), &keys).unwrap(); assert_eq!(window.lookups().collect::>(), [(500, 4000)]); assert!(window.found(500, None, &keys)); assert_eq!( @@ -1060,7 +1107,7 @@ mod tests { let mut keys = Keys::new([0, 33, 66]); keys.looks_up = true; keys.skipped = vec![1..33, 34..66]; - let window = Window::new(&[range(time(50), None)], Some(66), &keys).unwrap(); + let window = Window::new(&[range(time(50), None)], None, Some(66), &keys).unwrap(); assert_eq!(window.lookups().count(), 0); assert_eq!(window.resolved()[0].map(|resolved| resolved.start), Some(33)); } @@ -1071,7 +1118,7 @@ mod tests { fn an_unanswered_lookup_settles_with_its_time_end() { let mut keys = Keys::new([4000, 9000]); keys.looks_up = true; - let mut window = Window::new(&[range(time(500), time(3000))], Some(9000), &keys).unwrap(); + let mut window = Window::new(&[range(time(500), time(3000))], None, Some(9000), &keys).unwrap(); assert_eq!(window.lookups().collect::>(), [(500, 4000)]); assert!(window.found(500, None, &keys)); assert!(window.is_settled()); @@ -1089,7 +1136,13 @@ mod tests { #[test] fn a_time_start_is_not_looked_up_without_a_history() { let keys = Keys::new([4000, 9000]); - let window = Window::new(&[range(time(8500), None), range(time(500), None)], Some(9000), &keys).unwrap(); + let window = Window::new( + &[range(time(8500), None), range(time(500), None)], + None, + Some(9000), + &keys, + ) + .unwrap(); assert_eq!(window.lookups().count(), 0); assert_eq!( window.resolved(), diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index eeda631ad97..23bd22afb3b 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1061,6 +1061,45 @@ impl Holdings for TrackState { self.outcome.is_final() } + /// In media time, from the newest frame held, or the latest group's start when it is + /// newer; on a scale-less track, by arrival on this hop's clock, as expiry measures it. + /// + /// Where groups are keyed by their start, the time itself, so a received copy resolves it + /// as any time start. On a copy whose wire keys groups otherwise, the newest group held + /// whose first frame presented at or before it. + fn reach_back(&self, latest: u64, min: Duration) -> Option { + let Some(scale) = self.info.as_ref()?.timescale else { + let key = self.live(..).rev().find(|(_, slot)| self.aged(slot.arrived, min)); + return match key { + Some((&key, _)) => Some(Anchor::Time(key)), + None if self.lookup.is_empty() => None, + None => Some(Anchor::Oldest), + }; + }; + let newest = self + .live_edge(&Servable::ALL) + .and_then(|edge| edge.timestamp.convert(scale).ok()) + .map(Timestamp::value); + // A Min Age past every timestamp reaches back to the oldest group. + let back = Timestamp::try_from(min) + .and_then(|min| min.convert(scale)) + .map_or(u64::MAX, Timestamp::value); + if self.anchors != Anchors::Refused && !self.starts_at_keys { + let edge = newest.map_or(latest, |newest| newest.max(latest)); + return Some(Anchor::Time(edge.saturating_sub(back))); + } + let target = newest?.saturating_sub(back); + let started = |slot: &Slot| { + self.started_at(slot) + .and_then(|start| start.convert(scale).ok()) + .is_some_and(|start| start.value() <= target) + }; + Some(match self.live(..).rev().find(|(_, slot)| started(slot)) { + Some((&key, _)) => Anchor::Time(key), + None => Anchor::Oldest, + }) + } + fn never_produced(&self, keys: ops::Range) -> bool { // Skip runs coalesce, so a gap between two held groups is one run unless the cache // evicted a group inside it. @@ -4853,7 +4892,7 @@ impl Producer { } let ranges: Vec = relative.iter().map(|index| subscription.ranges[*index]).collect(); let state = self.state.read(); - let window = Window::new(&ranges, state.latest_live(), &*state)?; + let window = Window::new(&ranges, None, state.latest_live(), &*state)?; if !window.is_settled() { return Err(Error::Unsupported); } @@ -8257,9 +8296,9 @@ struct Filter { impl Cursor { fn new(state: kio::Consumer, subscription: Preferences) -> Self { - // The ranges floor the cursor, and the budget picks where above it to start, timed - // or not: delivery skips the cached groups it already judges stale, on whichever - // clock convicts them. + // The ranges floor the cursor, raised for a live join by its Min Age, and the budget + // picks where above it to start, timed or not: delivery skips the cached groups it + // already judges stale, on whichever clock convicts them. if subscription.read().joins_live() { TrackState::join(state.read()); } @@ -8267,10 +8306,14 @@ impl Cursor { let preferences = subscription.read(); let ranges_revision = subscription.ranges_revision(); let state = state.read(); - let (window, refused) = match Window::new(&preferences.ranges, state.latest_live(), &*state) { - Ok(window) => (window, None), - Err(err) => (Window::new(&[], None, &*state).expect("nothing to refuse"), Some(err)), - }; + let (window, refused) = + match Window::new(&preferences.ranges, preferences.delay.min, state.latest_live(), &*state) { + Ok(window) => (window, None), + Err(err) => ( + Window::new(&[], None, None, &*state).expect("nothing to refuse"), + Some(err), + ), + }; let filter = Filter { window, resolved: ranges_revision, @@ -8394,7 +8437,7 @@ impl Cursor { let replaced = { let preferences = self.subscription.read(); let revision = self.subscription.ranges_revision(); - (revision != self.filter.resolved).then(|| (revision, preferences.ranges.clone())) + (revision != self.filter.resolved).then(|| (revision, preferences.ranges.clone(), preferences.delay.min)) }; // A settled window has nothing to read from the track, whose lock every subscriber // of it takes. @@ -8404,9 +8447,9 @@ impl Cursor { let state = self.state.read(); let holdings = &*state; let moved = match replaced { - Some((revision, ranges)) => { + Some((revision, ranges, min)) => { self.filter.resolved = revision; - match Window::new(&ranges, state.latest_live(), holdings) { + match Window::new(&ranges, min, state.latest_live(), holdings) { Ok(window) => { self.filter.window = window; self.filter.refused = None; @@ -8690,6 +8733,11 @@ impl Cursor { return Vec::new(); }; let (runs, received) = drops.take_stale(&mut self.record); + // What it owes again notifies nothing a parked read waits on, as when an update that + // changes no term leaves the window and budget alone. + if !runs.is_empty() { + idle::Idle::disarm(&mut self.idle); + } // What neither a skip nor a miss offers again: a group written off at the track's max // age bound, which no budget reverses. It is still stale under the new terms. What an // upstream's stale run decided is the upstream's to judge again: the next scan folds @@ -9607,16 +9655,16 @@ impl Republish { let Some(published) = self.published.produce() else { return; }; - let (ranges, revision) = { + let (ranges, min, revision) = { let current = preferences.read(); - (current.ranges.clone(), preferences.ranges_revision()) + (current.ranges.clone(), current.delay.min, preferences.ranges_revision()) }; if published.read().revision >= revision { return; } let state = self.state.read(); // The update was refused before it got here if the track can't resolve it. - let Ok(window) = Window::new(&ranges, state.latest_live(), &*state) else { + let Ok(window) = Window::new(&ranges, min, state.latest_live(), &*state) else { return; }; drop(state); @@ -10325,14 +10373,19 @@ impl Subscriber { } } - /// `ranges` resolved against this track's cache now, by index. - pub(super) fn resolve_ranges(&self, ranges: &[Range]) -> Vec> { + /// The ranges of `subscription` resolved against this track's cache now, by index. + pub(super) fn resolve_ranges(&self, subscription: &Subscription) -> Vec> { match &self.inner { Inner::Plain(cursor) => { let state = cursor.state.read(); - Window::new(ranges, state.latest_live(), &*state) - .map(|window| window.resolved()) - .unwrap_or_default() + Window::new( + &subscription.ranges, + subscription.delay.min, + state.latest_live(), + &*state, + ) + .map(|window| window.resolved()) + .unwrap_or_default() } Inner::Resume(..) => Vec::new(), } @@ -12078,6 +12131,175 @@ mod test { keys } + /// A timed track of 500 ms groups starting at 0 through 5 s, each presenting at its start. + fn half_second_groups() -> Producer { + let mut producer = track_producer("test", Info::timed()); + for _ in (0..=5000).step_by(500) { + append_half_second(&mut producer); + } + producer + } + + /// Append the next 500 ms group, presenting at its start. + fn append_half_second(producer: &mut Producer) -> u64 { + let start = producer.state.read().latest_group.map_or(0, |latest| latest + 500); + let mut group = producer.create_group(group::Info { start }).unwrap(); + group + .write_frame(Timestamp::from_millis(start).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); + start + } + + /// A join over `range` holding `min` behind the live edge, with a budget that keeps the cache. + fn joining(range: Range, min: impl Into>) -> Subscription { + Subscription::default() + .with_ranges([range]) + .with_delay(Delay::default().with_min(min).with_max(Duration::from_secs(30))) + } + + /// A live join stating a Min Age starts at the newest group that began that far behind the + /// newest frame, from the latest or the oldest group alike, and plays through to live. + #[test] + fn a_live_join_reaches_back_by_its_min_age() { + for range in [Range::live(), Range::oldest()] { + let mut producer = half_second_groups(); + let mut reader = producer.subscribe(joining(range, Duration::from_secs(2))); + assert_eq!( + ready_groups(&mut reader), + vec![3000, 3500, 4000, 4500, 5000], + "{range:?}: four groups back" + ); + assert_eq!(append_half_second(&mut producer), 5500); + assert_eq!(ready_groups(&mut reader), vec![5500], "{range:?}: no gap to live"); + } + + // Measured from the newest frame, not the latest group's start. + let producer = half_second_groups(); + let mut group = producer.create_group(group::Info { start: 5500 }).unwrap(); + group + .write_frame(Timestamp::from_millis(5900).unwrap(), &b"x"[..]) + .unwrap(); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!(ready_groups(&mut reader), vec![3500, 4000, 4500, 5000, 5500]); + } + + /// A join stating no Min Age, or zero, starts where its range says: the latest group, or as + /// far back as its budget keeps. + #[test] + fn a_join_without_a_min_age_starts_where_its_range_says() { + let producer = half_second_groups(); + let all: Vec = (0..=5000).step_by(500).collect(); + for min in [None, Some(Duration::ZERO)] { + let mut live = producer.subscribe(joining(Range::live(), min)); + assert_eq!(ready_groups(&mut live), vec![5000], "{min:?}"); + let mut oldest = producer.subscribe(joining(Range::oldest(), min)); + assert_eq!(ready_groups(&mut oldest), all, "{min:?}"); + } + } + + /// A Min Age past everything held starts at the oldest group held, and never past what the + /// budget keeps: a shorter budget starts at the oldest group still fresh. + #[test] + fn a_min_age_reaches_back_no_further_than_the_cache_or_the_budget() { + let producer = half_second_groups(); + let all: Vec = (0..=5000).step_by(500).collect(); + let mut far = producer.subscribe(joining(Range::live(), Duration::from_secs(60))); + assert_eq!(ready_groups(&mut far), all); + + let budget = Subscription::default().with_ranges([Range::live()]).with_delay( + Delay::default() + .with_min(Duration::from_secs(2)) + .with_max(Duration::from_secs(1)), + ); + let mut budget = producer.subscribe(budget); + assert_eq!(ready_groups(&mut budget), vec![4000, 4500, 5000]); + } + + /// A start naming a time or a count back, or a range with an end, ignores the Min Age. + #[test] + fn a_named_start_or_an_end_ignores_the_min_age() { + let producer = half_second_groups(); + let min = Duration::from_secs(2); + let cases = [ + ( + Range { + start: Anchor::Time(1000), + end: Some(Anchor::Time(2000)), + }, + vec![1000, 1500, 2000], + ), + ( + Range { + start: Anchor::Relative(1), + end: None, + }, + vec![4500, 5000], + ), + ( + Range { + start: Anchor::Oldest, + end: Some(Anchor::Time(1000)), + }, + vec![0, 500, 1000], + ), + ]; + for (range, expected) in cases { + let mut reader = producer.subscribe(joining(range, min)); + assert_eq!(ready_groups(&mut reader), expected, "{range:?}"); + } + } + + /// Changing the Min Age later moves nothing already started. + #[test] + fn an_update_to_the_min_age_moves_no_started_join() { + let mut producer = half_second_groups(); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(1))); + assert_eq!(ready_groups(&mut reader), vec![4000, 4500, 5000]); + reader.update(joining(Range::live(), Duration::from_secs(3))).unwrap(); + assert_eq!(ready_groups(&mut reader), Vec::::new()); + append_half_second(&mut producer); + assert_eq!(ready_groups(&mut reader), vec![5500]); + } + + /// A scale-less track has no media time, so a join reaches back by arrival on this hop's + /// clock, as expiry measures it. + #[test] + fn a_scale_less_join_reaches_back_by_arrival() { + let producer = track_producer("test", None); + // Group N arrives N seconds in, and the join comes at 5 s. + for key in 0..5 { + framed(&producer, key, 1).close().unwrap(); + elapse(&producer, Duration::from_secs(1)); + } + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_millis(2500))); + assert_eq!(ready_groups(&mut reader), vec![2, 3, 4]); + let mut far = producer.subscribe(joining(Range::live(), Duration::from_secs(10))); + assert_eq!(ready_groups(&mut far), vec![0, 1, 2, 3, 4]); + framed(&producer, 5, 1).close().unwrap(); + assert_eq!(ready_groups(&mut reader), vec![5]); + } + + /// A copy whose wire keys groups by sequence measures the reach back by where each group's + /// first frame presented, not by its key. + #[test] + fn a_sequence_keyed_copy_reaches_back_by_first_frames() { + let producer = track_producer("test", Info::timed()); + producer.received(); + producer.starts_at_keys(); + for key in 0..10 { + let mut group = producer.create_group(group::Info { start: key }).unwrap(); + group + .write_frame(Timestamp::from_millis(key * 500).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); + } + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!(ready_groups(&mut reader), vec![5, 6, 7, 8, 9]); + let mut far = producer.subscribe(joining(Range::live(), Duration::from_secs(60))); + assert_eq!(ready_groups(&mut far), (0..10).collect::>()); + } + /// A relative start taken while the copy is idle counts back from the live feed's /// latest group once the route answers, not from the newest one an ended feed left. #[test] @@ -21656,7 +21878,7 @@ mod test { let mut index = 0; let window = { let state = producer.state.read(); - Window::new(&replay().ranges, None, &*state).unwrap() + Window::new(&replay().ranges, None, None, &*state).unwrap() }; while let Poll::Ready(Ok(Some((group, next)))) = producer.state.read().poll_recv_group(index, 0, &window) { walked.push(group.start); diff --git a/rs/moq-net/src/model/track/demand.rs b/rs/moq-net/src/model/track/demand.rs index 8a7adf99c3e..93c9160aed0 100644 --- a/rs/moq-net/src/model/track/demand.rs +++ b/rs/moq-net/src/model/track/demand.rs @@ -20,7 +20,7 @@ pub(super) struct Subscriptions { priority: BTreeMap, // Keyed by budget, so `None` counts as the widest of all. max_delay: BTreeMap, - // Only stated minimums count, so an unstated one never pulls the smallest to zero. + // Only stated minimums count, so an unstated one never reads as zero. min_delay: BTreeMap, ranges: Ranges, descending: usize, @@ -65,7 +65,8 @@ impl Subscriptions { ( *self.priority.last_key_value().unwrap().0, Delay { - min: self.min_delay.first_key_value().map(|(min, _)| *min), + // The largest, so an upstream starts far enough back for the reader that buffers most. + min: self.min_delay.last_key_value().map(|(min, _)| *min), max: Some(*self.max_delay.last_key_value().unwrap().0).filter(|budget| *budget != Duration::MAX), }, if self.descending == 0 { diff --git a/rs/moq-net/tests/integration/main.rs b/rs/moq-net/tests/integration/main.rs index bc102f00049..07e276306bb 100644 --- a/rs/moq-net/tests/integration/main.rs +++ b/rs/moq-net/tests/integration/main.rs @@ -50,6 +50,7 @@ mod late_tail_reader; mod lazy_discovery; mod mesh_sweep; mod mesh_withdraw; +mod min_age_join; mod model; mod mount; mod multi_cdn; diff --git a/rs/moq-net/tests/integration/min_age_join.rs b/rs/moq-net/tests/integration/min_age_join.rs new file mode 100644 index 00000000000..10eec30f4f0 --- /dev/null +++ b/rs/moq-net/tests/integration/min_age_join.rs @@ -0,0 +1,76 @@ +#![cfg(feature = "async")] + +//! A live join stating a Min Age starts that far behind the live edge, through relays that +//! hold nothing yet. + +use std::time::Duration; + +use moq_net::{Timestamp, Version, cache, origin, track}; + +use crate::support::harness::{peer, spawn}; + +const TIMEOUT: Duration = Duration::from_secs(10); + +fn origin(hop: u64) -> origin::Producer { + let mut config = origin::Config::new(std::num::NonZeroU64::new(hop).unwrap()); + config.pool = cache::Pool::unbounded(); + let (origin, driver) = origin::Producer::new(config); + spawn(driver); + origin.with_proxy(true) +} + +/// Append the 500 ms group starting at `start`, presenting there. +fn append(source: &track::Producer, start: u64) { + let mut group = source.append_group(start).unwrap(); + group + .write_frame(Timestamp::from_millis(start).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); +} + +/// A viewer joining through two relays that hold nothing gets the four groups behind the +/// live group its 2 s Min Age asks for, oldest first, then plays on to live with no gap. +#[kio::test] +async fn a_cold_relay_chain_reaches_back_by_min_age() { + let version: Version = "moq-lite-07-wip".parse().unwrap(); + let publisher = origin(1); + let edge = origin(2); + let inner = origin(3); + let viewer = origin(4); + let _a = peer(version, &publisher, &inner).await; + let _b = peer(version, &inner, &edge).await; + let _c = peer(version, &edge, &viewer).await; + + let broadcast = publisher.route("live", origin::RouteOptions::hidden()).unwrap(); + let info = track::Info::default() + .with_timescale(moq_net::Timescale::MILLI) + .with_max_age(None); + let source = broadcast.broadcast().create_track("video", info).unwrap(); + for start in (0..=5000).step_by(500) { + append(&source, start); + } + broadcast.announce().unwrap(); + + let joining = track::Subscription::default() + .with_ranges([track::Range::live()]) + .with_order(track::Order::Ascending) + .with_delay( + track::Delay::default() + .with_min(Duration::from_secs(2)) + .with_max(Duration::from_secs(30)), + ); + kio::clock::timeout(TIMEOUT, async { + let remote = viewer.consume().follow("live", None).unwrap().available().await; + let remote = remote.unwrap().expect("the broadcast resolves"); + let mut subscriber = remote.track("video").unwrap().subscribe(joining).await.unwrap(); + let mut starts = Vec::new(); + while starts.len() < 5 { + starts.push(subscriber.recv_group().await.unwrap().expect("a group").start); + } + assert_eq!(starts, [3000, 3500, 4000, 4500, 5000]); + append(&source, 5500); + assert_eq!(subscriber.recv_group().await.unwrap().expect("a group").start, 5500); + }) + .await + .expect("the viewer read its reach back"); +} diff --git a/rs/moq-net/tests/integration/subscriber_max_age.rs b/rs/moq-net/tests/integration/subscriber_max_age.rs index cd829ed8c0d..9ae0a535d4b 100644 --- a/rs/moq-net/tests/integration/subscriber_max_age.rs +++ b/rs/moq-net/tests/integration/subscriber_max_age.rs @@ -1,6 +1,6 @@ #![cfg(feature = "async")] -//! Relays forward their subscribers' delay: the most tolerant negotiated max, and the smallest stated min. +//! Relays forward their subscribers' delay: the most tolerant negotiated max, and the largest stated min. use std::time::Duration; @@ -103,10 +103,11 @@ async fn min_delay(track: &mut track::Producer, min: Option) { .unwrap_or_else(|_| panic!("wanted min {min:?}, publisher has {:?}", track.subscription())); } -/// A lite-07 relay forwards the smallest stated min delay upstream, and a lite-06 subscriber, -/// whose wire cannot state one, never pulls it to zero. +/// A lite-07 relay forwards the largest stated min delay upstream, so its copy reaches back for +/// the reader that buffers most, and a lite-06 subscriber, whose wire cannot state one, counts +/// for nothing. #[kio::test] -async fn relay_forwards_the_smallest_stated_min_delay() { +async fn relay_forwards_the_largest_stated_min_delay() { let lite07: Version = "moq-lite-07-wip".parse().unwrap(); let lite06: Version = "moq-lite-06".parse().unwrap(); let publisher = origin(1); @@ -152,13 +153,13 @@ async fn relay_forwards_the_smallest_stated_min_delay() { let unstated = cache(&legacy).await.subscribe(prefs(Some(0))).await.unwrap(); min_delay(&mut source, None).await; let modern = cache(&modern).await; - let slow = modern.subscribe(prefs(Some(500))).await.unwrap(); - min_delay(&mut source, Some(Duration::from_millis(500))).await; let fast = modern.subscribe(prefs(Some(100))).await.unwrap(); min_delay(&mut source, Some(Duration::from_millis(100))).await; - drop(fast); + let slow = modern.subscribe(prefs(Some(500))).await.unwrap(); min_delay(&mut source, Some(Duration::from_millis(500))).await; drop(slow); + min_delay(&mut source, Some(Duration::from_millis(100))).await; + drop(fast); min_delay(&mut source, None).await; drop(unstated); } From d32fbfe96ed16b2567f5ea87ffa2d82d1b54733f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:12:39 -0800 Subject: [PATCH 3/9] feat(net): the lite-07 draft and @moq/net reach a live join back by Min Age Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 3 +- drafts/draft-lcurley-moq-lite.md | 12 +++-- js/net/src/track.test.ts | 81 ++++++++++++++++++++++++++++++-- js/net/src/track.ts | 64 +++++++++++++++++++++---- js/net/src/window.ts | 63 ++++++++++++++++++++----- 5 files changed, 193 insertions(+), 30 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index f270c250a90..982881d7858 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -283,7 +283,8 @@ Each subscription carries the knobs that decide behavior under congestion: | **Priority** (-128..127, default 0) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. The publisher's track priority breaks ties between subscriptions at one priority. From a native Rust publisher over QUIC or WebTransport, subscriptions at the same priority and publisher priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. | | **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. | | **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. Unset leaves the publisher's max age alone to bound it. | -| **Ranges** | Which groups to ask for: from the oldest group, a number of groups back from the latest, or the group containing a time, through an end that includes its group. Each group arrives whole, from its first frame. The default asks for everything max delay allows. Max delay still caps every range. | +| **Min delay** | The playout buffer the subscriber holds behind the live edge. A join from the latest or the oldest group that follows the live edge starts at the newest group beginning this far behind it, so the buffer arrives full instead of filling in real time, and no fuller. The hop answering measures from what it holds: media time on a timed track, arrival time on an untimed one, and it never fetches upstream to reach further. Zero (the default) reaches back nothing. Carried by moq-lite 07, where a relay asks upstream for the largest its subscribers state. | +| **Ranges** | Which groups to ask for: from the oldest group, a number of groups back from the latest, or the group containing a time, through an end that includes its group. Each group arrives whole, from its first frame. The default asks for everything max delay allows, or only what min delay reaches back to when set. Max delay still caps every range. | On moq-lite 05 and later, a publisher explicitly reports groups that will not arrive. This lets a finished subscription settle without waiting for missing groups. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 48a1e21e76f..649f0e03339 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1641,8 +1641,8 @@ See the [Expiration](#expiration) section for more information. **Subscriber Min Age**: The subscriber's target latency behind the live edge, in milliseconds plus one: the playout or jitter-buffer delay it holds. A value of `0` means the subscriber did not state one, which is distinct from a stated zero (`1`). -It is a hint that asks for nothing: a publisher MAY use it, for example to start a cold join that far back, and MAY ignore it. -A relay forwarding an aggregate of several subscriptions SHOULD carry the smallest stated value, and not stated when none is, so a subscription that did not state one never pulls the aggregate to zero. +It decides where a Range following the live edge starts (see below). +A relay forwarding an aggregate of several subscriptions SHOULD carry the largest stated value, and not stated when none is, so its own copy starts far enough back for the subscription that buffers most. **Range Count**: The number of Ranges that follow. @@ -1669,13 +1669,17 @@ A Range resolves once: an update that leaves it live does not resolve it again. The number of the subscription's terms this message sets: 0 on SUBSCRIBE, and on each SUBSCRIBE_UPDATE a larger value than the one before it. A [SUBSCRIBE_DROP](#subscribe-drop) echoes the number in effect when its groups were given up, so the subscriber can tell a stale verdict on its current terms from one an update has since replaced. -A `Start` is a floor, not a request; `Subscriber Max Age` is the only thing that asks for data. +A `Start` is a floor, not a request; `Subscriber Max Age` and `Subscriber Min Age` are the only things that ask for data. The publisher SHOULD start at the oldest group at or above the floor that [Expiration](#expiration) has not expired, and MUST NOT deliver an older one. A `Subscriber Max Age` of 0 therefore starts at the latest group, since every older group is already stale. A subscriber that buffers is then handed the head of what it can still play instead of only the live edge, and is never sent history it would discard on arrival: the same bound decides what to start at and what to expire, so the two cannot disagree. A floor above the latest group simply waits there: that is a resumed subscription naming where it left off. Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). +A Range following the live edge, with a `Start` of None or Relative 0 and an `End` of None, starts by a nonzero `Subscriber Min Age` instead: the publisher SHOULD start it at the newest group it holds that starts at or before the live edge minus the Min Age, at the oldest group it holds when none does, and never at a group Expiration has expired. +The live edge is the newest frame timestamp the publisher holds; on a Track without a timescale, the Min Age is measured by when each group arrived at the publisher instead. +The publisher starts from what it holds and never fetches to reach further back, so a subscriber is handed the buffer it will play, and no more, without waiting for it to fill. + A Range covers whole Groups; a subscriber reads a slice of a Group with FETCH (see [Positions](#positions)). ## SUBSCRIBE_UPDATE {#subscribe-update} @@ -2439,7 +2443,7 @@ An application-specific payload. - Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, an absolute Group (exclusive as an end), a count of Groups back from the latest, or a presentation time. - Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1). -- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A relay forwards the smallest stated value. +- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A Range following the live edge starts that far behind it, from the groups the publisher holds. A relay forwards the largest stated value. - FETCH reads one Group or a slice of one, and SUBSCRIBE reads whole Groups: a read starting partway through a Group FETCHes it. A publisher holding only part of a Group a subscription covers drops it. - A SUBSCRIBE_UPDATE that lowers a `Start` covers the groups below the old start that the publisher still holds, not only those that arrive later. A group already sent is not sent again. - Replaced SUBSCRIBE_OK `Group` with a `Range Start` per Range: the Group where that Range's delivery starts, including at a Relative or Time Anchor, from which its Groups are owed. diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index e6be84d4f0f..a55936c03e7 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -610,17 +610,18 @@ test("multiple subscriber options aggregate like Rust", async () => { delay: { min: Duration.millis(50), max: Duration.millis(250) }, ranges: [{ start: { absolute: 5n } }], }); - // A minimum that went unstated, as a legacy peer's does, never pulls the smallest to zero. + // A minimum that went unstated, as a legacy peer's does, counts for nothing. const legacy = producer.subscribe({ delay: { min: null, max: Duration.millis(0) }, ranges: [{ start: { absolute: 5n } }], }); // One descending subscriber makes the aggregate descending, so a live reader is never held - // behind another's backlog. + // behind another's backlog. The largest minimum wins, so an upstream reaches back far enough + // for the reader that buffers most. expect(producer.subscription.peek()).toEqual({ priority: 7, - delay: { min: Duration.millis(50), max: Duration.millis(250) }, + delay: { min: Duration.millis(400), max: Duration.millis(250) }, order: "descending", ranges: [{ start: { absolute: 5n } }], }); @@ -860,6 +861,80 @@ test("a time range reads the groups containing its times, settling its end as gr expect(hooks.servingEnd(reader)).toBe(4n); }); +// Every group `reader` can take now, in delivery order. +function readable(reader: ReturnType): bigint[] { + const got: bigint[] = []; + for (let group = reader.tryRecvGroup(); group; group = reader.tryRecvGroup()) got.push(group.sequence); + return got; +} + +// A timed track of 500 ms groups 0 through 10, each presenting at its start. +function halfSecondGroups(): TrackProducer { + const producer = new TrackProducer("test"); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + for (let sequence = 0n; sequence <= 10n; sequence++) appendHalfSecond(producer, sequence); + return producer; +} + +function appendHalfSecond(producer: TrackProducer, sequence: bigint): void { + const group = producer.createGroup(sequence); + group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(Number(sequence) * 500))); + group.finish(); +} + +test("a live join reaches back by its min age, from the latest or the oldest group", () => { + for (const ranges of [[LIVE], [{}]]) { + const producer = halfSecondGroups(); + const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges }); + // The newest frame presents at 5 s, so the join starts at the group containing 3 s. + expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]); + appendHalfSecond(producer, 11n); + expect(readable(reader)).toEqual([11n]); + } +}); + +test("a join without a min age, or with zero, starts where its range says", () => { + const producer = halfSecondGroups(); + const all = Array.from({ length: 11 }, (_, sequence) => BigInt(sequence)); + for (const min of [null, Duration.ZERO]) { + const live = producer.subscribe({ delay: { min, max: Duration.secs(30) }, ranges: [LIVE] }); + expect(readable(live)).toEqual([10n]); + const oldest = producer.subscribe({ delay: { min, max: Duration.secs(30) } }); + expect(readable(oldest)).toEqual(all); + } + // Past everything held, it starts at the oldest group; a named start ignores it. + const far = producer.subscribe({ delay: { min: Duration.secs(60), max: Duration.secs(30) }, ranges: [LIVE] }); + expect(readable(far)).toEqual(all); + const named = producer.subscribe({ + delay: { min: Duration.secs(2), max: Duration.secs(30) }, + ranges: [{ start: { relative: 1n } }], + }); + expect(readable(named)).toEqual([9n, 10n]); +}); + +test("a scale-less join reaches back by arrival", () => { + const clock = manualTime(0); + try { + const producer = new TrackProducer("test"); + producer.accept({ maxAge: null }); + // Group N arrives N seconds in, and the join comes at 5 s. + for (let sequence = 0n; sequence < 5n; sequence++) { + const group = producer.createGroup(sequence); + group.writeFrame(textFrame(`${sequence}`, Timestamp.unscaled(sequence))); + group.finish(); + clock.set(Number(sequence + 1n) * 1000); + } + const reader = producer.subscribe({ + delay: { min: Duration.millis(2500), max: Duration.secs(30) }, + ranges: [LIVE], + }); + expect(readable(reader)).toEqual([2n, 3n, 4n]); + producer.close(); + } finally { + clock.installed.close(); + } +}); + // A reached end leaves a held group that may still start, so a time start still waits on it. test("a time start waits on groups below a reached end that have yet to start", () => { for (const order of ["ascending", "descending"] as const) { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 0ce09c6b669..14f5b7375ce 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -52,7 +52,7 @@ import { } from "./internal.ts"; import { grace, Ledger } from "./ledger.ts"; import { rescale } from "./rescale.ts"; -import { keyOf, Timescale, type Timestamp } from "./time.ts"; +import { keyOf, Timescale, Timestamp } from "./time.ts"; import { checkEnd, checkSequence, max, min, UNBOUNDED } from "./util/sequence.ts"; import { bounded, @@ -313,9 +313,19 @@ export interface Delay { * means `0`; `null` means not stated, which only a peer whose wire cannot carry it (moq-lite * before 07, moq-transport) sends. A media consumer reads an unstated minimum as `0`. * - * The aggregate across subscribers is the smallest stated one, so an unstated minimum never - * pulls it to zero, and it is forwarded upstream as is. A publisher may use it, such as to - * start a cold join that far back; nothing reads it there yet. + * A join that follows the live edge from the latest or the oldest group starts this far behind + * it: at the newest group that began at or before the live edge minus this, so a player's + * buffer arrives full instead of filling in real time, and no fuller. The hop serving it + * measures from what it holds: in media time from the newest frame on a timed track, and by + * arrival on its own clock on a scale-less one. With no such group held it starts at the + * oldest one, and never fetches upstream for more. {@link Delay.max} still skips what has gone + * stale. A start naming a group or a count back, a range with an end, and a resumed + * subscription ignore it, and changing it later moves nothing already started. Zero or + * unstated asks for no reach back, so the range alone decides where to start. + * + * The aggregate across subscribers is the largest stated one, which a relay forwards upstream, + * so the copy it fills reaches back for the reader that buffers most; each reader's own + * minimum then bounds what it reads of that copy. */ min?: Duration | null; /** @@ -424,11 +434,11 @@ function orderOf(order: Order | undefined): Order { return order; } -// The smaller of two minimums, ignoring one that went unstated (`null`). -function smallest(a: Duration | null | undefined, b: Duration | null | undefined): Duration | null { +// The larger of two minimums, ignoring one that went unstated (`null`). +function largest(a: Duration | null | undefined, b: Duration | null | undefined): Duration | null { if (a === null || a === undefined) return b ?? null; if (b === null || b === undefined) return a; - return a.min(b); + return a.max(b); } // Aggregate the preferences of `states`, matching Rust's Subscription::poll_combined. @@ -445,8 +455,8 @@ function combineSubscriptions(states: Iterable): Subscription | unde combined.priority = Math.max(combined.priority ?? 0, subscription.priority ?? 0); combined.delay = { max: Duration.millis(Math.max(maxDelayOf(combined), maxDelayOf(subscription))), - // Only stated minimums count, so one that went unstated never pulls the smallest to zero. - min: smallest(combined.delay?.min, subscription.delay?.min), + // The largest stated, so an upstream starts far enough back for the reader that buffers most. + min: largest(combined.delay?.min, subscription.delay?.min), }; // One live subscriber held behind another's backlog is worse than a backlog sent late. combined.order = @@ -3288,7 +3298,13 @@ export class Subscriber { // Resolve this reader's ranges again, as when they are replaced. #resolve(): void { - this.#window = new Window(this.#state.update.peek()?.ranges ?? [{}], this.#latestGroup(), this.#holdings()); + const update = this.#state.update.peek(); + this.#window = new Window( + update?.ranges ?? [{}], + this.#latestGroup(), + this.#holdings(), + update?.delay?.min ?? undefined, + ); // Leaves the lookups the old ranges asked, which a settled window never reads again. if (this.#lookups.length > 0) this.#lookUp(); this.#moved(); @@ -3343,9 +3359,37 @@ export class Subscriber { complete: () => state.closed.peek() !== undefined, // A received copy's handler is its session, which fetches by group alone. looksUp: () => !receivedCopy(producer) && fillsOf(producer).serving, + reachBack: (_latest, min) => this.#reachBack(min), }; } + // Where a live join holding `min` behind the live edge starts, as {@link Holdings.reachBack} + // says: in media time from the newest frame held, or on a scale-less track, by arrival on this + // hop's clock, as expiry measures it. Mirrors the Rust `TrackState::reach_back`. + #reachBack(min: Duration): { anchor?: Anchor } | undefined { + const timeline = this.#state.timeline; + // The newest group held for which `f` holds, failed ones aside. + const newest = (f: (group: GroupConsumer) => boolean) => timeline.findLast((g) => !hooks.groupFailed(g) && f(g)); + const info = this.#state.info.peek(); + if (info?.timescale == null) { + if (!newest(() => true)) return undefined; + const at = now(); + const aged = newest((group) => at.since(hooks.groupArrived(group)).ge(min)); + return aged ? { anchor: { absolute: aged.sequence } } : {}; + } + const stamped = newest((group) => hooks.groupTimestamp(group) !== undefined); + const started = stamped && hooks.groupTimestamp(stamped); + if (!stamped || !started) return undefined; + const target = Math.max(0, (hooks.groupLatest(stamped) ?? started).asMicros() - min.asMicros()); + // moq-transport promises no timestamps that never rewind, so its starts go unindexed and a + // time anchor can't name a group: take the newest whose first frame presented by then. + if (info.ietf !== undefined) { + const first = newest((group) => (hooks.groupTimestamp(group)?.asMicros() ?? Infinity) <= target); + return first ? { anchor: { absolute: first.sequence } } : {}; + } + return { anchor: { time: Timestamp.fromMicros(target) } }; + } + // Resolve what the groups now held settle: a relative anchor waiting on a first group once // one exists, and a time end as groups start. Returns the refusal of ranges this copy cannot // resolve, which every read reports. diff --git a/js/net/src/window.ts b/js/net/src/window.ts index 7d8ef6be169..f2a74e04873 100644 --- a/js/net/src/window.ts +++ b/js/net/src/window.ts @@ -9,6 +9,7 @@ * @module */ +import type { Duration } from "@moq/clock"; import { Timescale, Timestamp } from "./time.ts"; import type { Anchor, Range } from "./track.ts"; import { max, min, saturatingSub, UNBOUNDED } from "./util/sequence.ts"; @@ -364,6 +365,14 @@ export interface Holdings { * history, as the Rust `Holdings::looks_up` says. Absent for none. */ looksUp?(): boolean; + /** + * Where a live join holding `min` behind the live edge starts, `latest` being the latest group: + * a time that far behind the newest frame held, a group that starts at or before it, or with no + * anchor, the oldest group, when none held does. Undefined while nothing held can measure it, + * so the join waits for a group as a relative start does. Absent where the hop leaves its ranges + * to the copies it follows. Mirrors the Rust `Holdings::reach_back`. + */ + reachBack?(latest: bigint, min: Duration): { anchor?: Anchor } | undefined; } /** @@ -568,13 +577,19 @@ export class Window { * The ranges, by index, whose time start waits on a group starting, so they read nothing yet, * with the latest group their relative end counts back from. */ - #waiting: { index: number; latest: bigint | undefined }[] = []; + #waiting: { index: number; latest: bigint | undefined; start: Anchor | undefined }[] = []; /** Nothing is left to resolve as groups arrive and start. */ #settled = false; + /** The subscriber's Min Age, which reaches a live join back from the live edge. */ + readonly #min: Duration | undefined; - /** Resolve `ranges`, counting relative anchors back from `latest` and time anchors from `holdings`. */ - constructor(ranges: readonly Range[], latest: bigint | undefined, holdings: Holdings = UNHELD) { + /** + * Resolve `ranges`, counting relative anchors back from `latest` and time anchors from + * `holdings`, and reaching a live join back by `min` (see {@link joins}). + */ + constructor(ranges: readonly Range[], latest: bigint | undefined, holdings: Holdings = UNHELD, min?: Duration) { this.ranges = ranges; + this.#min = min; this.#place(latest, holdings); } @@ -603,8 +618,8 @@ export class Window { this.#waiting = []; // A relative end counts back from the latest group when asked, or the first observed // group on an empty track, even while the time start waits. - for (const { index, latest } of waiting) { - if (this.#span(index, latest, holdings)) moved = true; + for (const { index, latest, start } of waiting) { + if (this.#span(index, latest, holdings, { anchor: start })) moved = true; } for (const span of this.#spans) { if (span.end === "open" || !("time" in span.end)) continue; @@ -775,8 +790,9 @@ export class Window { this.#rebuild(); } - // Resolve range `index` into a span, or note what it waits on. Returns whether it resolved. - #span(index: number, latest: bigint | undefined, holdings: Holdings): boolean { + // Resolve range `index` into a span, or note what it waits on, starting at `reached` when a + // join's reach back already chose it. Returns whether it resolved. + #span(index: number, latest: bigint | undefined, holdings: Holdings, reached?: { anchor?: Anchor }): boolean { const range = this.ranges[index]; if (isEmpty(range)) return false; const until = endOf(range.end, latest); @@ -784,9 +800,19 @@ export class Window { this.#pending = true; return false; } - const start = startOf(range.start, latest, holdings); + const min = joins(range, this.#min, holdings); + if (!reached && min !== undefined) { + reached = latest === undefined ? undefined : holdings.reachBack?.(latest, min); + // Nothing to measure the live edge by yet. + if (!reached) { + this.#pending = true; + return false; + } + } + const anchor = reached ? reached.anchor : range.start; + const start = startOf(anchor, latest, holdings); if (start === "waiting") { - this.#waiting.push({ index, latest }); + this.#waiting.push({ index, latest, start: anchor }); return false; } if (start === undefined) { @@ -795,9 +821,11 @@ export class Window { } let end: End = until === "open" || "before" in until ? until : { time: new TimeEnd(until.pts, start.group) }; // A time start the groups held can't place reads nothing until its lookup answers, and its - // time end walks from where that puts it. - const pts = time(range.start); - const below = pts === undefined ? undefined : unresolved(start.group, start.floored, holdings); + // time end walks from where that puts it. A join's reach back never looks one up: it starts + // from what this hop holds. + const pts = time(anchor); + const asked = time(range.start) !== undefined; + const below = pts === undefined || !asked ? undefined : unresolved(start.group, start.floored, holdings); if (pts !== undefined && below !== undefined) { this.#spans.push({ index, start: start.group, end, floored: start.floored, looking: { pts, below } }); return true; @@ -845,6 +873,17 @@ function intersect(runs: readonly Run[], from: bigint, end: bigint): Run[] { return out; } +/** + * The Min Age a live join reaches back by: a nonzero `min`, for a range that follows the live edge + * from the latest or the oldest group, where the hop resolves its own ranges. A start naming a + * group or a count back wins, as does a range with an end. A zero or unstated minimum asks for no + * reach back, so the range alone decides. Mirrors the Rust `joins`. + */ +function joins(range: Range, min: Duration | undefined, holdings: Holdings): Duration | undefined { + const live = (range.start === undefined || relative(range.start) === 0n) && range.end === undefined; + return live && min !== undefined && !min.isZero() && holdings.reachBack ? min : undefined; +} + /** * The first group a range starts at, and whether it names that group rather than reaching back * to the oldest one. Undefined while it waits on a latest group, and `"waiting"` for a time From 181550bc6ef832b8c954d1342504803027015f3b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:13:20 -0800 Subject: [PATCH 4/9] chore(quest): finish quest/m2/min-age-join.md Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 2 +- quest/m2/delay-hole-wait.md | 3 +- quest/m2/lite07-finalize.md | 3 +- quest/m2/min-age-join.md | 89 ------------------------------ quest/m2/time-addressing/lite07.md | 1 - 5 files changed, 3 insertions(+), 95 deletions(-) delete mode 100644 quest/m2/min-age-join.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 42df4d4cfa6..83da84e4220 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -23,7 +23,7 @@ removal, a rename, or a wire, catalog, or format change that is free until - **lite-07 wire.** [YIELDED continuations](/quest/m2/yield-defer.md) leave for lite-08; [the ietf extension](/quest/m2/ietf-records-per-track.md) costs nothing on a moq-lite track; [the path escape](/quest/m2/path-escape.md) - is finished; [Subscriber Min Age](/quest/m2/min-age-join.md) stays and + is finished; Subscriber Min Age stays and gains its reader, reversing 2026-11-14; and [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries the smaller wire fixes. [Refresh](/quest/m2/refresh-interval.md) and diff --git a/quest/m2/delay-hole-wait.md b/quest/m2/delay-hole-wait.md index d577b32691c..377618c7daf 100644 --- a/quest/m2/delay-hole-wait.md +++ b/quest/m2/delay-hole-wait.md @@ -50,7 +50,7 @@ For the PR, settle the home of native audio's live estimate first. Two ways: moq-audio's reorder tests) with the playhead in place. 2. moq-audio writes its estimate into the subscription's `Delay::min` as it moves. `min` is Subscriber Min Age on the lite-07 wire, so each change is - a SUBSCRIBE_UPDATE, and since [a cold join reaches back by it](/quest/m2/min-age-join.md) + a SUBSCRIBE_UPDATE, and since a cold join reaches back by it it would also move where a join starts. Take this only with a coarse step and a measured update rate, and say why the playhead did not do. @@ -69,5 +69,4 @@ loses `ConsumerProps.wait`. Wire: none. ## Related -- [A cold join reaches back by Min Age](/quest/m2/min-age-join.md) - gives `Delay::min` a reader on the wire, which rules out using it as a fast-moving estimate - [Native audio playout is a library](/quest/m3/audio-playout-library.md) - moves the placement this wait feeds into moq-audio diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index 3646a454881..b12c3f516f2 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -176,7 +176,7 @@ audited the lite-07 draft for what it could lose): removed: moq-transport names a track by a tuple, and the escape is how a moq-lite path carries one. - ✅ Subscriber Min Age stays, reversing the 2026-11-14 pick, and - [gains its reader](/quest/m2/min-age-join.md); + gains its reader; [moq-dev/moq#8839](https://github.com/moq-dev/moq/pull/8839), which removed it, was closed. - ✅ Kept as they are: datagram tracks, including the lite-05/06 bridge (a @@ -200,7 +200,6 @@ the version that ships them. - [YIELDED deferred](/quest/m2/yield-defer.md) - removes reset code 0x3C and continuations from the lite-07 wire - [ietf records per track](/quest/m2/ietf-records-per-track.md) - changes the extension's framing on relay links - [Path escape](/quest/m2/path-escape.md) - defines a path segment when a path carries an escape -- [Min Age join](/quest/m2/min-age-join.md) - makes Subscriber Min Age normative - [Cache-aware multicast](/quest/m2/multicast/README.md) - lite-07 carries the redesigned route layer: routes to forwarding nodes, no holds or doubt, claims crossing trust boundaries by a chain, and no Route Key - [Routes and announces](/quest/m2/cluster-routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the native hop list gone (only the temporary lite-06 compatibility chain remains) - [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers diff --git a/quest/m2/min-age-join.md b/quest/m2/min-age-join.md deleted file mode 100644 index 69e76eed1ea..00000000000 --- a/quest/m2/min-age-join.md +++ /dev/null @@ -1,89 +0,0 @@ -# [M] A cold join reaches back by Subscriber Min Age - -## Goal - -`Subscriber Min Age` stays on lite-07's SUBSCRIBE and SUBSCRIBE_UPDATE and -has a reader. A subscription that joins live and states one starts that far -behind the live edge: the publisher or relay answering it begins with the -cached group that covers the live edge minus Min Age, so a player's buffer -arrives full instead of filling in real time. A subscription that states -none starts where it does today. `Delay { min, max }` keeps its shape in -moq-net and `@moq/net`. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ Keep the wire field (rejected: drop it and keep `Delay::min` local). - This reverses the 2026-11-14 pick on - [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764), whose PR, - [moq-dev/moq#8839](https://github.com/moq-dev/moq/pull/8839), was closed - unmerged on 2026-11-16. The 2026-11-14 reason was that a field frozen with - no reader costs every relay an aggregate and a forward; the answer is to - give it the reader, not to remove it. -- ✅ The reader: a cold join reaches back by Min Age, from the answering - node's cache (rejected: leave it a hint with no defined behaviour). - -Facts found by the audit: - -- `Delay::min` documents itself as "the `Subscriber Min Age` on the - moq-lite-07 wire" and says "A publisher may use it, such as to start a - cold join that far back; nothing reads it there yet" - (`rs/moq-net/src/model/subscription.rs:57-68`). The draft calls it "a - hint that asks for nothing". -- It is already stated by players: `rs/moq-audio/src/decode/consumer.rs`, - `rs/moq-cli/src/play/video.rs`, and `js/watch/src/audio/decoder.ts` set - `delay.min` to the latency they hold, and both codecs encode it. The - publisher decodes it into the subscription - (`rs/moq-net/src/lite/publisher.rs:3084`, `:5285`) and nothing looks. -- Where a subscription starts is decided by one rule today: "A `Start` is a - floor ... The publisher SHOULD start at the oldest group at or above the - floor that Expiration has not expired" (draft, SUBSCRIBE). So a reader - gets everything its Max Age allows or, with the default start, only the - latest group. Neither is "as much as I am going to buffer": a lossless - reader (no Max Age) asking from the oldest gets the whole cache. -- The aggregate across readers is the smallest stated value - (`subscription.rs:553-556`), which a relay forwards upstream. - -Recommendations for the PR (the maintainer decided the behaviour, not these -details): - -- The rule, in the draft's SUBSCRIBE text beside the floor rule: a - subscription that follows the live edge and states Min Age starts at the - newest group that began at or before the live edge minus Min Age, never - below its `Start` floor and never at an expired group; with no such group - cached it starts at the oldest one it may. It stays best effort ("from - its cache"): the node never fetches upstream to satisfy it. The field's - text loses "a hint that asks for nothing". -- The live edge is the newest frame the node holds. On a timed track the - distance is in media time, from group starts; on a scale-less track it is - arrival age on the node's own clock, as expiry already measures it. -- An explicit `Time` start or a resumed position wins: Min Age applies only - to a join that would otherwise start at the latest group or the oldest - unexpired one. -- The aggregate a relay forwards: recommend the largest stated value in - place of the smallest. A relay that subscribes upstream cold fills its - cache from where the upstream starts, and each reader's own Min Age then - bounds what the relay hands it, so the smallest starves the reader that - buffers most. Nothing else reads the aggregate. Unstated still never - counts. This changes one SHOULD in the draft; settle it in the PR. -- Implement where a subscription's first group is picked in the model, so - the Rust publisher, the relay, and a moq-transport or pre-07 reader - (which state none) share it, and mirror it in `js/net`'s lite publisher. - SUBSCRIBE_UPDATE changing Min Age later moves nothing already started. -- Tests, with time mocked: a track of 500 ms groups and a join stating 2 s - starts four groups back and plays through to live with no gap; a join - stating none starts at the latest group as before; a join stating more - than the cache holds gets what there is; a two-relay chain with a cold - edge gives the reader its reach-back; a scale-less track reaches back by - arrival age. Update `doc/concept/moq-lite.md` and the lite-07 changelog - line for the field. Run `just test interop --all`. - -Public API: none; `Delay::min`'s doc changes from "nothing reads it" to the -rule. Wire: lite-07-wip keeps the field; its meaning becomes normative, and -the aggregate rule changes if the recommendation is taken. - -## Related - -- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - rewrites the same SUBSCRIBE fields, and gives the group starts this measures by -- [Refresh a track by interval](/quest/m2/refresh-interval.md) - the other thing a live join does: it may ask for a new group diff --git a/quest/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md index 0f03820d24d..639f29e9acb 100644 --- a/quest/m2/time-addressing/lite07.md +++ b/quest/m2/time-addressing/lite07.md @@ -190,4 +190,3 @@ TRACKS_ADD change, and the Padding stream and datagram types go. - [YIELDED deferred](/quest/m2/yield-defer.md) - removes continuations, the last use of GROUP's `Frame Start` - [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - reads the spans SUBSCRIBE_DROP names - [Refresh a track](/quest/m2/refresh-interval.md) - raises the `Wanted Group` this turns into a start time -- [A cold join reaches back](/quest/m2/min-age-join.md) - gives SUBSCRIBE's `Subscriber Min Age` its reader From 36467f41e74fe1a474a51284342f78c2ea965ae2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 09:46:19 -0800 Subject: [PATCH 5/9] fix(net): only a live join reaches back, and a playout warms it by its warmup Starting from the oldest group asks for everything the budget keeps, so Min Age now moves only a Range::live join; narrowing the oldest start broke "decode every cached group" in moq-audio. A playout widens the min delay by the catalog warmup, as it already did the max, so the reach-back covers the decoder's warmup too (moq-mux, moq-c, moq-ffi, js/watch). Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 4 +-- drafts/draft-lcurley-moq-lite.md | 6 ++-- js/hang/src/container/consumer.ts | 4 +-- js/net/src/track.test.ts | 20 ++++++------ js/net/src/track.ts | 20 ++++++------ js/net/src/window.ts | 9 +++--- js/watch/src/audio/decoder.ts | 6 +++- js/watch/src/video/decoder.ts | 6 ++-- rs/moq-audio/src/decode/consumer.rs | 8 +++-- rs/moq-c/src/consume.rs | 11 ++++--- rs/moq-ffi/src/media.rs | 4 +-- rs/moq-mux/src/container/consumer.rs | 30 ++++++++++++------ rs/moq-net/src/model/subscription.rs | 17 +++++----- rs/moq-net/src/model/subscription/window.rs | 10 +++--- rs/moq-net/src/model/track.rs | 35 ++++++++++++--------- 15 files changed, 107 insertions(+), 83 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 982881d7858..54d8dd23714 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -283,8 +283,8 @@ Each subscription carries the knobs that decide behavior under congestion: | **Priority** (-128..127, default 0) | Higher-priority tracks get bandwidth first. Audio above video, base layer above enhancement. The publisher's track priority breaks ties between subscriptions at one priority. From a native Rust publisher over QUIC or WebTransport, subscriptions at the same priority and publisher priority split bandwidth evenly by bytes, streams and datagrams alike, however many groups each has queued. A browser publisher and other transports without send groups are not covered. | | **Order** | Which group to send first when several are pending. Newest first for live (the default), oldest first for catch-up. Needs moq-lite 07 or moq-transport; older moq-lite always sends newest first. | | **Max delay** | How long a non-latest group stays worth delivering before it is skipped. Zero means "live edge only", and raising it is also what asks for history. Unset leaves the publisher's max age alone to bound it. | -| **Min delay** | The playout buffer the subscriber holds behind the live edge. A join from the latest or the oldest group that follows the live edge starts at the newest group beginning this far behind it, so the buffer arrives full instead of filling in real time, and no fuller. The hop answering measures from what it holds: media time on a timed track, arrival time on an untimed one, and it never fetches upstream to reach further. Zero (the default) reaches back nothing. Carried by moq-lite 07, where a relay asks upstream for the largest its subscribers state. | -| **Ranges** | Which groups to ask for: from the oldest group, a number of groups back from the latest, or the group containing a time, through an end that includes its group. Each group arrives whole, from its first frame. The default asks for everything max delay allows, or only what min delay reaches back to when set. Max delay still caps every range. | +| **Min delay** | The playout buffer the subscriber holds behind the live edge. A join from the latest group starts at the newest group beginning this far behind it, so the buffer arrives full instead of filling in real time, and no fuller. The hop answering measures from what it holds: media time on a timed track, arrival time on an untimed one, and it never fetches upstream to reach further. Zero (the default) reaches back nothing, and a range from the oldest group or a named start ignores it. Carried by moq-lite 07, where a relay asks upstream for the largest its subscribers state. | +| **Ranges** | Which groups to ask for: from the oldest group, a number of groups back from the latest, or the group containing a time, through an end that includes its group. Each group arrives whole, from its first frame. The default asks for everything max delay allows. Max delay still caps every range. | On moq-lite 05 and later, a publisher explicitly reports groups that will not arrive. This lets a finished subscription settle without waiting for missing groups. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 649f0e03339..1da7615393c 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -1641,7 +1641,7 @@ See the [Expiration](#expiration) section for more information. **Subscriber Min Age**: The subscriber's target latency behind the live edge, in milliseconds plus one: the playout or jitter-buffer delay it holds. A value of `0` means the subscriber did not state one, which is distinct from a stated zero (`1`). -It decides where a Range following the live edge starts (see below). +It decides where a Range joining at the live edge starts (see below). A relay forwarding an aggregate of several subscriptions SHOULD carry the largest stated value, and not stated when none is, so its own copy starts far enough back for the subscription that buffers most. **Range Count**: @@ -1676,7 +1676,7 @@ A subscriber that buffers is then handed the head of what it can still play inst A floor above the latest group simply waits there: that is a resumed subscription naming where it left off. Reaching back is best-effort, not a guarantee that the groups still exist; see `Publisher Max Age` in [TRACK_INFO](#track-info). -A Range following the live edge, with a `Start` of None or Relative 0 and an `End` of None, starts by a nonzero `Subscriber Min Age` instead: the publisher SHOULD start it at the newest group it holds that starts at or before the live edge minus the Min Age, at the oldest group it holds when none does, and never at a group Expiration has expired. +A Range joining at the live edge, with a `Start` of Relative 0 and an `End` of None, starts by a nonzero `Subscriber Min Age` instead: the publisher SHOULD start it at the newest group it holds that starts at or before the live edge minus the Min Age, at the oldest group it holds when none does, and never at a group Expiration has expired. The live edge is the newest frame timestamp the publisher holds; on a Track without a timescale, the Min Age is measured by when each group arrived at the publisher instead. The publisher starts from what it holds and never fetches to reach further back, so a subscriber is handed the buffer it will play, and no more, without waiting for it to fill. @@ -2443,7 +2443,7 @@ An application-specific payload. - Replaced `Group Start`, `Group End`, `Frame Start`, and `Frame End` in SUBSCRIBE and SUBSCRIBE_UPDATE with a non-empty list of Ranges of whole Groups. Each end is an Anchor: none, an absolute Group (exclusive as an end), a count of Groups back from the latest, or a presentation time. - Added `Group Order` to SUBSCRIBE and SUBSCRIBE_UPDATE: descending (0x0, the previous fixed order) or ascending (0x1). -- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A Range following the live edge starts that far behind it, from the groups the publisher holds. A relay forwards the largest stated value. +- Added an optional `Subscriber Min Age` to SUBSCRIBE and SUBSCRIBE_UPDATE, the subscriber's target latency, encoded as milliseconds plus one with zero meaning not stated. A Range joining at the latest group starts that far behind the live edge, from the groups the publisher holds. A relay forwards the largest stated value. - FETCH reads one Group or a slice of one, and SUBSCRIBE reads whole Groups: a read starting partway through a Group FETCHes it. A publisher holding only part of a Group a subscription covers drops it. - A SUBSCRIBE_UPDATE that lowers a `Start` covers the groups below the old start that the publisher still holds, not only those that arrive later. A group already sent is not sent again. - Replaced SUBSCRIBE_OK `Group` with a `Range Start` per Range: the Group where that Range's delivery starts, including at a Relative or Time Anchor, from which its Groups are owed. diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index f063129a06f..f6218608b5c 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -61,8 +61,8 @@ export interface ConsumerProps { * Opus decoder or an intra-refresh video decoder. Pass the catalog * rendition's `warmup`. Mirrors Rust's `container::Playout`. * - * Put the max delay plus the warmup on the subscription, since the publisher skips what falls - * outside that budget. The start is no later than the group covering the live edge less + * Put the min and max delay plus the warmup on the subscription, since the publisher starts a + * live join at the min and skips what falls outside the max. The start is no later than the group covering the live edge less * `delay.min` and the warmup: one that starts at or before that point. Both default to zero, * which the newest group covers, so the start waits for nothing. Otherwise groups can arrive * newest first, so when none that arrived covers that point the start waits for an earlier one, diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index a55936c03e7..b6ad0702e24 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -882,23 +882,23 @@ function appendHalfSecond(producer: TrackProducer, sequence: bigint): void { group.finish(); } -test("a live join reaches back by its min age, from the latest or the oldest group", () => { - for (const ranges of [[LIVE], [{}]]) { - const producer = halfSecondGroups(); - const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges }); - // The newest frame presents at 5 s, so the join starts at the group containing 3 s. - expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]); - appendHalfSecond(producer, 11n); - expect(readable(reader)).toEqual([11n]); - } +test("a live join reaches back by its min age", () => { + const producer = halfSecondGroups(); + const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] }); + // The newest frame presents at 5 s, so the join starts at the group containing 3 s. + expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]); + appendHalfSecond(producer, 11n); + expect(readable(reader)).toEqual([11n]); }); -test("a join without a min age, or with zero, starts where its range says", () => { +test("a live join without a min age starts at the latest group, and the oldest start ignores it", () => { const producer = halfSecondGroups(); const all = Array.from({ length: 11 }, (_, sequence) => BigInt(sequence)); for (const min of [null, Duration.ZERO]) { const live = producer.subscribe({ delay: { min, max: Duration.secs(30) }, ranges: [LIVE] }); expect(readable(live)).toEqual([10n]); + } + for (const min of [null, Duration.ZERO, Duration.secs(2)]) { const oldest = producer.subscribe({ delay: { min, max: Duration.secs(30) } }); expect(readable(oldest)).toEqual(all); } diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 14f5b7375ce..f220cd62f8e 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -313,15 +313,14 @@ export interface Delay { * means `0`; `null` means not stated, which only a peer whose wire cannot carry it (moq-lite * before 07, moq-transport) sends. A media consumer reads an unstated minimum as `0`. * - * A join that follows the live edge from the latest or the oldest group starts this far behind - * it: at the newest group that began at or before the live edge minus this, so a player's - * buffer arrives full instead of filling in real time, and no fuller. The hop serving it - * measures from what it holds: in media time from the newest frame on a timed track, and by - * arrival on its own clock on a scale-less one. With no such group held it starts at the - * oldest one, and never fetches upstream for more. {@link Delay.max} still skips what has gone - * stale. A start naming a group or a count back, a range with an end, and a resumed - * subscription ignore it, and changing it later moves nothing already started. Zero or - * unstated asks for no reach back, so the range alone decides where to start. + * A live join, `{ start: { relative: 0n } }` with no end, starts this far behind the live edge: + * at the newest group that began at or before the live edge minus this, so a player's buffer + * arrives full instead of filling in real time. The hop serving it measures from what it holds: + * in media time from the newest frame on a timed track, and by arrival on its own clock on a + * scale-less one. With no such group held it starts at the oldest one, and never fetches + * upstream for more. {@link Delay.max} still skips what has gone stale. Any other range, the + * default oldest start included, and a resumed subscription ignore it, and changing it later + * moves nothing already started. * * The aggregate across subscribers is the largest stated one, which a relay forwards upstream, * so the copy it fills reaches back for the reader that buffers most; each reader's own @@ -3369,7 +3368,8 @@ export class Subscriber { #reachBack(min: Duration): { anchor?: Anchor } | undefined { const timeline = this.#state.timeline; // The newest group held for which `f` holds, failed ones aside. - const newest = (f: (group: GroupConsumer) => boolean) => timeline.findLast((g) => !hooks.groupFailed(g) && f(g)); + const newest = (f: (group: GroupConsumer) => boolean) => + timeline.findLast((g) => !hooks.groupFailed(g) && f(g)); const info = this.#state.info.peek(); if (info?.timescale == null) { if (!newest(() => true)) return undefined; diff --git a/js/net/src/window.ts b/js/net/src/window.ts index f2a74e04873..1d407484a68 100644 --- a/js/net/src/window.ts +++ b/js/net/src/window.ts @@ -874,13 +874,12 @@ function intersect(runs: readonly Run[], from: bigint, end: bigint): Run[] { } /** - * The Min Age a live join reaches back by: a nonzero `min`, for a range that follows the live edge - * from the latest or the oldest group, where the hop resolves its own ranges. A start naming a - * group or a count back wins, as does a range with an end. A zero or unstated minimum asks for no - * reach back, so the range alone decides. Mirrors the Rust `joins`. + * The Min Age a live join reaches back by: `min`, for {@link LIVE}, where the hop resolves its own + * ranges. Any other start names where it starts, the oldest one included, which asks for everything + * the budget keeps. A zero minimum starts at the latest group anyway. Mirrors the Rust `joins`. */ function joins(range: Range, min: Duration | undefined, holdings: Holdings): Duration | undefined { - const live = (range.start === undefined || relative(range.start) === 0n) && range.end === undefined; + const live = relative(range.start) === 0n && range.end === undefined; return live && min !== undefined && !min.isZero() && holdings.reachBack ? min : undefined; } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index cff00137535..00bc3ce885f 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -207,6 +207,9 @@ export class Decoder { // The subscription's max delay: the shared budget, raised to the delay plus the estimator's ceiling. #subscribeMaxDelay = new Signal(Duration.ZERO); + // The subscription's min delay: the playout delay plus the warmup, where the publisher starts a + // live join. + #subscribeMinDelay = new Signal(Duration.ZERO); // The container consumer's delay: the playout delay to start at and the shared budget. Its warmup // reaches the start further back, to the media the decoder primes on. #delay = new Signal({}); @@ -370,6 +373,7 @@ export class Decoder { const max = maxDelay(budget); const warmup = Duration.millis(effect.get(this.source.out.config)?.warmup ?? 0).min(DELAY_MAX); this.#delay.set({ min: delay, max }); + this.#subscribeMinDelay.set(delay.add(warmup)); this.#subscribeMaxDelay.set(max.add(warmup)); } @@ -642,7 +646,7 @@ export class Decoder { broadcast: active, track: Catalog.track(track, identity), priority: Catalog.PRIORITY.audio, - delay: new Derived([this.sync.out.delay, this.#subscribeMaxDelay], (min, max) => ({ min, max })), + delay: new Derived([this.#subscribeMinDelay, this.#subscribeMaxDelay], (min, max) => ({ min, max })), }); if (!sub) { this.#retire(); diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index fdadbb35d57..aac3cffcc54 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -602,8 +602,8 @@ class Rendition { // The catalog `warmup`, capped like the delay so a publisher cannot hold the viewer without bound. #warmup: Duration; // The playout delay is where a cold join starts, and the shared max delay how late it may fall. The - // consumer's warmup reaches the start further back; the subscription widens its max by the same - // warmup, since the publisher skips what falls outside it. + // consumer's warmup reaches the start further back; the subscription widens both by the same + // warmup, since the publisher starts a live join at the min and skips what falls outside the max. #delay: Getter; #subscription: Getter; // The running codec's join and gap state: which leading pictures to refuse, and which still warm up. @@ -669,7 +669,7 @@ class Rendition { this.#warmup = Duration.millis(this.config.warmup ?? 0).min(DELAY_MAX); this.#delay = new Derived([this.sync.out.delay, this.sync.out.maxDelay], (min, max) => ({ min, max })); this.#subscription = new Derived([this.sync.out.delay, this.sync.out.maxDelay], (min, max) => ({ - min, + min: min.add(this.#warmup), max: max.add(this.#warmup), })); this.#predecessor = props.predecessor; diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index f3d0da8fe1f..d29328b761d 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -975,7 +975,7 @@ mod tests { use crate::encode::{Config as EncodeConfig, Encoder, Input, Options as EncodeOptions, Producer}; use crate::{Format, Layout}; - /// The first request already states the min delay, and the max plus the warmup: a latest + /// The first request already states the min and max delay, each plus the warmup: a latest /// start waits for the live edge with its subscription open, before the container could /// update it. #[tokio::test] @@ -1009,7 +1009,11 @@ mod tests { }; assert_eq!( first.map(|sub| sub.delay), - Some(delay.with_max(Duration::from_millis(600))) + Some( + delay + .with_min(Duration::from_millis(400)) + .with_max(Duration::from_millis(600)) + ) ); } diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 0ba8738f4ef..057e8ca643b 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -1670,13 +1670,16 @@ mod tests { max, }; let consumer = MediaConsumer::new(video, warmup, delay).await; + let warmup = warmup.unwrap_or_default(); assert_eq!( consumer.initial_delay, // The request aggregate represents Duration::MAX as unlimited. - delay.with_max( - max.map(|max| max.saturating_add(warmup.unwrap_or_default())) - .filter(|max| *max != Duration::MAX) - ) + Delay { + min: Some(Duration::from_millis(200) + warmup), + max: max + .map(|max| max.saturating_add(warmup)) + .filter(|max| *max != Duration::MAX), + } ); consumer.cancel().await; } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 7eaacedcf2c..b621f2a4e24 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -1624,13 +1624,13 @@ mod read_tests { } /// A catalog rendition's warmup survives conversion and widens the raw subscription past the - /// caller's max delay, keeping the min delay as asked. + /// caller's min and max delay, so a live join reaches back far enough to warm the decoder. #[tokio::test] async fn raw_media_catalog_warmup_widens_the_subscription() { for video in [false, true] { let (_broadcast, track, _reader, _) = subscribe_warmup(video).await; let subscription = track.subscription().unwrap(); - assert_eq!(subscription.delay.min, Some(DELAY), "video={video}"); + assert_eq!(subscription.delay.min, Some(DELAY + WARMUP), "video={video}"); assert_eq!(subscription.delay.max, Some(DELAY + WARMUP), "video={video}"); } } diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 805ae842346..775382274b6 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -322,8 +322,9 @@ fn gap(edge: std::time::Duration, resume: Timestamp) -> Result Delay { + Delay { + min: delay.min.map(|min| min.saturating_add(warmup)), + max: delay.max.map(|max| max.saturating_add(warmup)), + } +} + impl Playout { /// Play at `delay`, starting `warmup` further back. pub fn new(delay: Delay, warmup: std::time::Duration) -> Self { Self { delay, warmup } } - /// `subscription` with this playout's delay, its max widened by the warmup. + /// `subscription` with this playout's delay, both bounds widened by the warmup. pub fn subscription(&self, subscription: moq_net::track::Subscription) -> moq_net::track::Subscription { subscription.with_delay(self.subscribed()) } @@ -375,8 +385,7 @@ impl Playout { /// The delay the subscription carries. fn subscribed(&self) -> Delay { - self.delay - .with_max(self.delay.max.map(|max| max.saturating_add(self.reach()))) + warmed(self.delay, self.reach()) } /// The warmup, capped at [`DELAY_MAX`]. @@ -1377,7 +1386,7 @@ impl Consumer { // tolerance set here has to reach it: otherwise moq-net skips the very groups // this consumer was told to wait for, before they ever get here. It keeps the // warmup too, as [`Playout::subscription`] does. - let delay = delay.with_max(delay.max.map(|max| max.saturating_add(self.warmup))); + let delay = warmed(delay, self.warmup); if track.subscription().delay != delay { let subscription = track.subscription().with_delay(delay); let _ = track.update(subscription); @@ -4321,9 +4330,10 @@ mod tests { assert_eq!(frame.timestamp, ts(5_000_000)); } - /// The subscription carries the min delay as is and the max delay plus the warmup. + /// The subscription carries the min and max delay, each plus the warmup, so a live join + /// reaches back far enough to warm the decoder before its first played frame. #[tokio::test] - async fn the_subscription_carries_the_min_delay_and_the_warmed_max_delay() { + async fn the_subscription_carries_the_warmed_min_and_max_delay() { let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer = reach_consumer( &mut track, @@ -4332,7 +4342,7 @@ mod tests { Duration::from_millis(300), ); let subscription = subscribed(&consumer).subscription(); - assert_eq!(subscription.delay.min, Some(Duration::from_secs(2))); + assert_eq!(subscription.delay.min, Some(Duration::from_millis(2_300))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); } @@ -4350,7 +4360,7 @@ mod tests { let consumer = Playout::new(delay, Duration::from_millis(300)) .consumer(consumer_track, Container::Legacy(crate::container::Kind::Data)); let subscription = subscribed(&consumer).subscription(); - assert_eq!(subscription.delay.min, Some(Duration::from_millis(100))); + assert_eq!(subscription.delay.min, Some(Duration::from_millis(400))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); assert_eq!(consumer.warmup, Duration::from_millis(300)); diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 6f998450488..0910a33c75d 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -58,15 +58,14 @@ pub struct Delay { /// The target latency, the playout or jitter-buffer delay held behind the live edge, or /// `None` when the subscriber did not state one. /// - /// A join that follows the live edge from [`Range::live`] or [`Range::oldest`] starts this - /// far behind it: at the newest group that began at or before the live edge minus this, - /// so a player's buffer arrives full instead of filling in real time, and no fuller. The - /// hop serving it measures from what it holds: in media time from the newest frame on a - /// timed track, and by arrival on its own clock on a scale-less one. With no such group - /// held it starts at the oldest one, and never fetches upstream for more. [`Self::max`] - /// still skips what has gone stale. A start naming a group or a count back, a range with - /// an end, and a resumed subscription ignore it, and changing it later moves nothing - /// already started. Zero or unstated asks for no reach back, so the range alone decides. + /// A [`Range::live`] join starts this far behind the live edge: at the newest group that + /// began at or before the live edge minus this, so a player's buffer arrives full instead + /// of filling in real time. The hop serving it measures from what it holds: in media time + /// from the newest frame on a timed track, and by arrival on its own clock on a scale-less + /// one. With no such group held it starts at the oldest one, and never fetches upstream for + /// more. [`Self::max`] still skips what has gone stale. Any other range, [`Range::oldest`] + /// included, and a resumed subscription ignore it, and changing it later moves nothing + /// already started. /// /// A media consumer reads an unstated minimum as zero. The aggregate across subscribers is /// the largest stated one, which a relay forwards upstream, so the copy it fills reaches diff --git a/rs/moq-net/src/model/subscription/window.rs b/rs/moq-net/src/model/subscription/window.rs index 4665714be16..5640f1cf93c 100644 --- a/rs/moq-net/src/model/subscription/window.rs +++ b/rs/moq-net/src/model/subscription/window.rs @@ -617,13 +617,11 @@ impl Window { } } -/// The Min Age a live join reaches back by: a nonzero `min`, for a range that follows the live -/// edge from the latest or the oldest group, where this hop resolves its own ranges. A start -/// naming a group or a count back wins, as does a range with an end. A zero or unstated -/// minimum asks for no reach back, so the range alone decides. +/// The Min Age a live join reaches back by: `min`, for [`Range::live`], where this hop resolves +/// its own ranges. Any other start names where it starts, the oldest one included, which asks for +/// everything the budget keeps. A zero minimum starts at the latest group anyway. fn joins(range: &Range, min: Option, holdings: &impl Holdings) -> Option { - let live = matches!(range.start, Anchor::Oldest | Anchor::Relative(0)) && range.end.is_none(); - min.filter(|min| !min.is_zero() && live && holdings.resolves()) + min.filter(|min| *range == Range::live() && !min.is_zero() && holdings.resolves()) } /// Where a range starts. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 23bd22afb3b..aca24463335 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -12159,20 +12159,18 @@ mod test { } /// A live join stating a Min Age starts at the newest group that began that far behind the - /// newest frame, from the latest or the oldest group alike, and plays through to live. + /// newest frame, and plays through to live. #[test] fn a_live_join_reaches_back_by_its_min_age() { - for range in [Range::live(), Range::oldest()] { - let mut producer = half_second_groups(); - let mut reader = producer.subscribe(joining(range, Duration::from_secs(2))); - assert_eq!( - ready_groups(&mut reader), - vec![3000, 3500, 4000, 4500, 5000], - "{range:?}: four groups back" - ); - assert_eq!(append_half_second(&mut producer), 5500); - assert_eq!(ready_groups(&mut reader), vec![5500], "{range:?}: no gap to live"); - } + let mut producer = half_second_groups(); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!( + ready_groups(&mut reader), + vec![3000, 3500, 4000, 4500, 5000], + "four groups back" + ); + assert_eq!(append_half_second(&mut producer), 5500); + assert_eq!(ready_groups(&mut reader), vec![5500], "no gap to live"); // Measured from the newest frame, not the latest group's start. let producer = half_second_groups(); @@ -12184,8 +12182,8 @@ mod test { assert_eq!(ready_groups(&mut reader), vec![3500, 4000, 4500, 5000, 5500]); } - /// A join stating no Min Age, or zero, starts where its range says: the latest group, or as - /// far back as its budget keeps. + /// A live join stating no Min Age, or zero, starts at the latest group, and a join from the + /// oldest group reaches as far back as its budget keeps, whatever its Min Age. #[test] fn a_join_without_a_min_age_starts_where_its_range_says() { let producer = half_second_groups(); @@ -12193,6 +12191,8 @@ mod test { for min in [None, Some(Duration::ZERO)] { let mut live = producer.subscribe(joining(Range::live(), min)); assert_eq!(ready_groups(&mut live), vec![5000], "{min:?}"); + } + for min in [None, Some(Duration::ZERO), Some(Duration::from_secs(2))] { let mut oldest = producer.subscribe(joining(Range::oldest(), min)); assert_eq!(ready_groups(&mut oldest), all, "{min:?}"); } @@ -12243,6 +12243,13 @@ mod test { }, vec![0, 500, 1000], ), + ( + Range { + start: Anchor::Relative(0), + end: Some(Anchor::Relative(0)), + }, + vec![5000], + ), ]; for (range, expected) in cases { let mut reader = producer.subscribe(joining(range, min)); From ae64cd41df3c1743d59cc8fde096000515d19b1d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 10:54:49 -0800 Subject: [PATCH 6/9] fix(net): a join reaches back only to groups held, by the Min Age stated when it starts A lite-07 copy resolved the reach-back to a raw time, so a target below everything it held waited on that prefix and asked its upstream for it. Every track now starts at the newest group held starting by the target, or the oldest held, in Rust and @moq/net. A Min Age update that left the ranges as they were never reached a join still pending, so it started by the old value. A pending window now takes the current Min Age when it places its ranges. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 10 +++ js/net/src/track.ts | 26 +++---- js/net/src/window.ts | 17 +++-- rs/moq-net/src/model/subscription/window.rs | 6 ++ rs/moq-net/src/model/track.rs | 84 ++++++++++++++++----- 5 files changed, 105 insertions(+), 38 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index b6ad0702e24..0761f40390c 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -891,6 +891,16 @@ test("a live join reaches back by its min age", () => { expect(readable(reader)).toEqual([11n]); }); +test("a min age update reaches a live join not yet started", () => { + const producer = new TrackProducer("test"); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + const reader = producer.subscribe({ delay: { min: Duration.secs(1), max: Duration.secs(30) }, ranges: [LIVE] }); + expect(readable(reader)).toEqual([]); + reader.update({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] }); + for (let sequence = 0n; sequence <= 10n; sequence++) appendHalfSecond(producer, sequence); + expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]); +}); + test("a live join without a min age starts at the latest group, and the oldest start ignores it", () => { const producer = halfSecondGroups(); const all = Array.from({ length: 11 }, (_, sequence) => BigInt(sequence)); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index f220cd62f8e..10af48906d5 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -52,7 +52,7 @@ import { } from "./internal.ts"; import { grace, Ledger } from "./ledger.ts"; import { rescale } from "./rescale.ts"; -import { keyOf, Timescale, Timestamp } from "./time.ts"; +import { keyOf, Timescale, type Timestamp } from "./time.ts"; import { checkEnd, checkSequence, max, min, UNBOUNDED } from "./util/sequence.ts"; import { bounded, @@ -3364,30 +3364,28 @@ export class Subscriber { // Where a live join holding `min` behind the live edge starts, as {@link Holdings.reachBack} // says: in media time from the newest frame held, or on a scale-less track, by arrival on this - // hop's clock, as expiry measures it. Mirrors the Rust `TrackState::reach_back`. + // hop's clock, as expiry measures it. Always a group held: the newest one starting by the + // target, or the oldest one when none does, so nothing below what this hop holds is asked for. + // Mirrors the Rust `TrackState::reach_back`. #reachBack(min: Duration): { anchor?: Anchor } | undefined { const timeline = this.#state.timeline; // The newest group held for which `f` holds, failed ones aside. const newest = (f: (group: GroupConsumer) => boolean) => timeline.findLast((g) => !hooks.groupFailed(g) && f(g)); + const held = (group: GroupConsumer | undefined) => { + const at = group ?? timeline.find((g) => !hooks.groupFailed(g)); + return at && { anchor: { absolute: at.sequence } }; + }; const info = this.#state.info.peek(); if (info?.timescale == null) { - if (!newest(() => true)) return undefined; const at = now(); - const aged = newest((group) => at.since(hooks.groupArrived(group)).ge(min)); - return aged ? { anchor: { absolute: aged.sequence } } : {}; + return held(newest((group) => at.since(hooks.groupArrived(group)).ge(min))); } const stamped = newest((group) => hooks.groupTimestamp(group) !== undefined); const started = stamped && hooks.groupTimestamp(stamped); if (!stamped || !started) return undefined; const target = Math.max(0, (hooks.groupLatest(stamped) ?? started).asMicros() - min.asMicros()); - // moq-transport promises no timestamps that never rewind, so its starts go unindexed and a - // time anchor can't name a group: take the newest whose first frame presented by then. - if (info.ietf !== undefined) { - const first = newest((group) => (hooks.groupTimestamp(group)?.asMicros() ?? Infinity) <= target); - return first ? { anchor: { absolute: first.sequence } } : {}; - } - return { anchor: { time: Timestamp.fromMicros(target) } }; + return held(newest((group) => (hooks.groupTimestamp(group)?.asMicros() ?? Infinity) <= target)); } // Resolve what the groups now held settle: a relative anchor waiting on a first group once @@ -4993,8 +4991,10 @@ export class Subscriber { const reordered = subscription.order !== this.#state.update.peek()?.order; this.#state.update.set(subscription); if (replaced) this.#resolve(); + // A live join not yet started reaches back by the Min Age stated when it starts. + else this.#window.min = subscription.delay?.min ?? undefined; // A fill's order follows its readers, so its handler wakes to serve the new first group. - else if (reordered) this.#fillsMoved(); + if (!replaced && reordered) this.#fillsMoved(); } } diff --git a/js/net/src/window.ts b/js/net/src/window.ts index 1d407484a68..ba0a0fd8af4 100644 --- a/js/net/src/window.ts +++ b/js/net/src/window.ts @@ -367,9 +367,9 @@ export interface Holdings { looksUp?(): boolean; /** * Where a live join holding `min` behind the live edge starts, `latest` being the latest group: - * a time that far behind the newest frame held, a group that starts at or before it, or with no - * anchor, the oldest group, when none held does. Undefined while nothing held can measure it, - * so the join waits for a group as a relative start does. Absent where the hop leaves its ranges + * the newest group held that starts at or before the newest frame held less `min`, or the oldest + * group held when none does. Undefined while nothing held can measure it, so the join waits for + * a group as a relative start does. Absent where the hop leaves its ranges * to the copies it follows. Mirrors the Rust `Holdings::reach_back`. */ reachBack?(latest: bigint, min: Duration): { anchor?: Anchor } | undefined; @@ -580,8 +580,11 @@ export class Window { #waiting: { index: number; latest: bigint | undefined; start: Anchor | undefined }[] = []; /** Nothing is left to resolve as groups arrive and start. */ #settled = false; - /** The subscriber's Min Age, which reaches a live join back from the live edge. */ - readonly #min: Duration | undefined; + /** + * The subscriber's Min Age, which reaches a live join back from the live edge. Only a pending + * window reads it, when it places its ranges, so a join already started stays where it started. + */ + min: Duration | undefined; /** * Resolve `ranges`, counting relative anchors back from `latest` and time anchors from @@ -589,7 +592,7 @@ export class Window { */ constructor(ranges: readonly Range[], latest: bigint | undefined, holdings: Holdings = UNHELD, min?: Duration) { this.ranges = ranges; - this.#min = min; + this.min = min; this.#place(latest, holdings); } @@ -800,7 +803,7 @@ export class Window { this.#pending = true; return false; } - const min = joins(range, this.#min, holdings); + const min = joins(range, this.min, holdings); if (!reached && min !== undefined) { reached = latest === undefined ? undefined : holdings.reachBack?.(latest, min); // Nothing to measure the live edge by yet. diff --git a/rs/moq-net/src/model/subscription/window.rs b/rs/moq-net/src/model/subscription/window.rs index 5640f1cf93c..6ce3b433da6 100644 --- a/rs/moq-net/src/model/subscription/window.rs +++ b/rs/moq-net/src/model/subscription/window.rs @@ -224,6 +224,12 @@ impl Window { self.pending } + /// Take the subscriber's current Min Age. Only a pending window reads it, when it places + /// its ranges, so a join already started stays where it started. + pub fn set_min(&mut self, min: Option) { + self.min = min; + } + /// Whether a time start still waits on the groups held to place it. pub fn is_waiting(&self) -> bool { !self.waiting.is_empty() diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index aca24463335..1b143d4100a 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1064,17 +1064,15 @@ impl Holdings for TrackState { /// In media time, from the newest frame held, or the latest group's start when it is /// newer; on a scale-less track, by arrival on this hop's clock, as expiry measures it. /// - /// Where groups are keyed by their start, the time itself, so a received copy resolves it - /// as any time start. On a copy whose wire keys groups otherwise, the newest group held - /// whose first frame presented at or before it. + /// Always a group this hop holds: the newest one starting at or before the target, or the + /// oldest one when none does, so a copy never asks its upstream for the prefix it lacks. + /// Groups keyed by their start are found by key; on a copy whose wire keys groups + /// otherwise, by when each one's first frame presented. Pending until a group is held. fn reach_back(&self, latest: u64, min: Duration) -> Option { + let oldest = || self.live(..).next().map(|(&key, _)| Anchor::Time(key)); let Some(scale) = self.info.as_ref()?.timescale else { let key = self.live(..).rev().find(|(_, slot)| self.aged(slot.arrived, min)); - return match key { - Some((&key, _)) => Some(Anchor::Time(key)), - None if self.lookup.is_empty() => None, - None => Some(Anchor::Oldest), - }; + return key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest); }; let newest = self .live_edge(&Servable::ALL) @@ -1086,7 +1084,9 @@ impl Holdings for TrackState { .map_or(u64::MAX, Timestamp::value); if self.anchors != Anchors::Refused && !self.starts_at_keys { let edge = newest.map_or(latest, |newest| newest.max(latest)); - return Some(Anchor::Time(edge.saturating_sub(back))); + let target = edge.saturating_sub(back); + let key = self.live(..=target).next_back(); + return key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest); } let target = newest?.saturating_sub(back); let started = |slot: &Slot| { @@ -1094,10 +1094,8 @@ impl Holdings for TrackState { .and_then(|start| start.convert(scale).ok()) .is_some_and(|start| start.value() <= target) }; - Some(match self.live(..).rev().find(|(_, slot)| started(slot)) { - Some((&key, _)) => Anchor::Time(key), - None => Anchor::Oldest, - }) + let key = self.live(..).rev().find(|(_, slot)| started(slot)); + key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest) } fn never_produced(&self, keys: ops::Range) -> bool { @@ -8434,10 +8432,14 @@ impl Cursor { /// ranges, counting relative anchors back from the latest group then, and settled as /// the groups it waits on arrive. Returns whether the window moved. fn sync(&mut self) -> bool { - let replaced = { + let (replaced, min) = { let preferences = self.subscription.read(); let revision = self.subscription.ranges_revision(); - (revision != self.filter.resolved).then(|| (revision, preferences.ranges.clone(), preferences.delay.min)) + let min = preferences.delay.min; + ( + (revision != self.filter.resolved).then(|| (revision, preferences.ranges.clone())), + min, + ) }; // A settled window has nothing to read from the track, whose lock every subscriber // of it takes. @@ -8447,7 +8449,7 @@ impl Cursor { let state = self.state.read(); let holdings = &*state; let moved = match replaced { - Some((revision, ranges, min)) => { + Some((revision, ranges)) => { self.filter.resolved = revision; match Window::new(&ranges, min, state.latest_live(), holdings) { Ok(window) => { @@ -8462,8 +8464,11 @@ impl Cursor { None if self.filter.window.is_settled() => false, // The live feed had no group when the ranges resolved, so the newest one then was // the first to arrive, or the newest once it went live, however many have arrived - // or left since. - None if self.filter.window.is_pending() => self.filter.window.settle(state.first_live(), holdings), + // or left since. A live join not yet started reaches back by the Min Age stated now. + None if self.filter.window.is_pending() => { + self.filter.window.set_min(min); + self.filter.window.settle(state.first_live(), holdings) + } None => self.filter.window.settle(state.latest_live(), holdings), }; drop(state); @@ -12307,6 +12312,49 @@ mod test { assert_eq!(ready_groups(&mut far), (0..10).collect::>()); } + /// A lite-07 copy reaches back only to groups it holds, so the join starts at once and + /// leaves no unheld prefix for its upstream to be asked: the newest group held starting at + /// or before the target, or the oldest one held when none does. + #[test] + #[cfg(feature = "async")] + fn a_received_copy_reaches_back_only_to_groups_it_holds() { + let placed = + |subscriber: &mut Subscriber| subscriber.resolved()[0].map(|resolved| (resolved.start, resolved.floored)); + let producer = track_producer("test", Info::timed()); + producer.received(); + producer.anchored(); + write_group(&producer, 5000); + let mut short = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!( + placed(&mut short), + Some((5000, true)), + "nothing held reaches back further" + ); + assert_eq!(drain(&mut short), vec![5000]); + + write_group(&producer, 3000); + let mut held = producer.subscribe(joining(Range::live(), Duration::from_secs(1))); + assert_eq!( + placed(&mut held), + Some((3000, true)), + "the newest held at or before 4000" + ); + } + + /// A live join that has not started yet reaches back by the Min Age stated when it starts, + /// though the update left its ranges as they were. + #[test] + fn a_min_age_update_reaches_a_join_not_yet_started() { + let mut producer = track_producer("test", Info::timed()); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(1))); + assert_eq!(ready_groups(&mut reader), Vec::::new()); + reader.update(joining(Range::live(), Duration::from_secs(2))).unwrap(); + for _ in (0..=5000).step_by(500) { + append_half_second(&mut producer); + } + assert_eq!(ready_groups(&mut reader), vec![3000, 3500, 4000, 4500, 5000]); + } + /// A relative start taken while the copy is idle counts back from the live feed's /// latest group once the route answers, not from the newest one an ended feed left. #[test] From c6aedacc2d7201c453f06e88e3f439958eb39f8c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 11:07:16 -0800 Subject: [PATCH 7/9] quest: moq-c's raw track options test flakes under load Found by just check on this branch; it fails at the base commit too. Co-Authored-By: Claude Opus 5.5 --- quest/m0/test-flakes-3/c-raw-track-options.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 quest/m0/test-flakes-3/c-raw-track-options.md diff --git a/quest/m0/test-flakes-3/c-raw-track-options.md b/quest/m0/test-flakes-3/c-raw-track-options.md new file mode 100644 index 00000000000..01e34c233a4 --- /dev/null +++ b/quest/m0/test-flakes-3/c-raw-track-options.md @@ -0,0 +1,25 @@ +# [S] moq-c's raw track options test reads its first group under load + +## Goal + +`rs/moq-c/src/test.rs::raw_track_subscription_options_and_update` passes +every run of the full moq-c suite. + +## Plan + +Found 2026-11-16 by `just check` on +[moq-dev/moq#8958](https://github.com/moq-dev/moq/pull/8958), whose change +does not reach this test's Absolute ranges. Run alone it passes. Running the +whole `moq-c` unit binary (`test::` filter) 20 times in a row fails it 6 +times at the base commit 949406e072: at `rs/moq-c/src/test.rs:2794`, it +receives `two` where it expects `one`, the group starting at 20 ms. + +The test publishes three groups 20 ms apart, then subscribes with a 25 ms +`max_us` and a range starting at 20 ms. Under load, the read likely comes +after group `one` went stale by its successor's arrival on the host clock, so +the read skips it. That is correct behaviour for a 25 ms budget, so the fix is +in the test, as the epic's rules ask: drive it on a paused or manual clock, +or give it a budget that does not depend on how fast the suite runs. Confirm +the cause before fixing. + +Public API: none. Wire: none. From 9ce361a9fb58507febc93eb4b4e83d31f1615e44 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 13:53:04 -0800 Subject: [PATCH 8/9] fix(net): a live join reads nothing until it can measure its reach back Review round 2: a join with groups held but nothing to measure the live edge by (an unaccepted track, or no first frame yet) read every group as a pending window does; it now reads none and wakes when a group starts. The reach back skips aborted groups, rounds its Min Age up to whole ticks, and in JS compares in the track's own scale. A playout widens an unstated min by its warmup. The raw track options follow-up traces the out-of-range delivery before blaming the test. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 34 ++++ js/net/src/track.ts | 18 +- js/net/src/window.ts | 30 ++- quest/m0/test-flakes-3/c-raw-track-options.md | 17 +- rs/moq-mux/src/container/consumer.rs | 18 +- rs/moq-net/src/model/subscription/window.rs | 172 +++++++++++------- rs/moq-net/src/model/track.rs | 105 ++++++++++- 7 files changed, 304 insertions(+), 90 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 0761f40390c..7e55351956a 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -922,6 +922,40 @@ test("a live join without a min age starts at the latest group, and the oldest s expect(readable(named)).toEqual([9n, 10n]); }); +test("a live join reads nothing until the groups held measure the live edge", () => { + const producer = new TrackProducer("test"); + // Groups written before accept say nothing yet of whether the track is timed. + const groups = Array.from({ length: 11 }, (_, sequence) => producer.createGroup(BigInt(sequence))); + const reader = producer.subscribe({ delay: { min: Duration.secs(2), max: Duration.secs(30) }, ranges: [LIVE] }); + expect(readable(reader)).toEqual([]); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + // Accepted, but still only headers: nothing to measure by. + expect(readable(reader)).toEqual([]); + for (const [sequence, group] of groups.entries()) { + group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(sequence * 500))); + group.finish(); + } + expect(readable(reader)).toEqual([6n, 7n, 8n, 9n, 10n]); +}); + +test("a live join reaches back by ticks rounded up, at any timestamp the track accepts", () => { + const producer = new TrackProducer("test"); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + // Past what microseconds can hold as a safe number. + const base = 10_000_000_000_000; + for (let sequence = 0; sequence <= 2; sequence++) { + const group = producer.createGroup(BigInt(sequence)); + group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(base + sequence))); + group.finish(); + } + // 1.5 ms back from 2 ms past the base is 0.5 ms past it, which only group 0 starts by. + const reader = producer.subscribe({ + delay: { min: Duration.micros(1500), max: Duration.secs(30) }, + ranges: [LIVE], + }); + expect(readable(reader)).toEqual([0n, 1n, 2n]); +}); + test("a scale-less join reaches back by arrival", () => { const clock = manualTime(0); try { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 10af48906d5..492ec05c73d 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -3377,15 +3377,27 @@ export class Subscriber { return at && { anchor: { absolute: at.sequence } }; }; const info = this.#state.info.peek(); - if (info?.timescale == null) { + // Until the track is accepted, whether it is timed at all is unknown. + if (info === undefined) return undefined; + const scale = info.timescale; + if (scale == null) { const at = now(); return held(newest((group) => at.since(hooks.groupArrived(group)).ge(min))); } const stamped = newest((group) => hooks.groupTimestamp(group) !== undefined); const started = stamped && hooks.groupTimestamp(stamped); if (!stamped || !started) return undefined; - const target = Math.max(0, (hooks.groupLatest(stamped) ?? started).asMicros() - min.asMicros()); - return held(newest((group) => (hooks.groupTimestamp(group)?.asMicros() ?? Infinity) <= target)); + // In the track's own scale, which holds every timestamp it accepted. The Min Age rounds up + // to whole ticks, so the start is never newer than it allows. + const back = (BigInt(Math.ceil(min.asNanos())) * BigInt(scale) + 999_999_999n) / 1_000_000_000n; + const edge = BigInt((hooks.groupLatest(stamped) ?? started).as(scale)); + const target = edge > back ? edge - back : 0n; + return held( + newest((group) => { + const start = hooks.groupTimestamp(group); + return start !== undefined && BigInt(start.as(scale)) <= target; + }), + ); } // Resolve what the groups now held settle: a relative anchor waiting on a first group once diff --git a/js/net/src/window.ts b/js/net/src/window.ts index ba0a0fd8af4..adacfd3ad36 100644 --- a/js/net/src/window.ts +++ b/js/net/src/window.ts @@ -578,6 +578,11 @@ export class Window { * with the latest group their relative end counts back from. */ #waiting: { index: number; latest: bigint | undefined; start: Anchor | undefined }[] = []; + /** + * The ranges, by index, of a live join whose reach back waits on the groups held to measure the + * live edge, so they read nothing yet: a group held is no reason to start at it. + */ + #reaching: number[] = []; /** Nothing is left to resolve as groups arrive and start. */ #settled = false; /** @@ -617,6 +622,11 @@ export class Window { return !this.#pending; } let moved = false; + const reaching = this.#reaching; + this.#reaching = []; + for (const index of reaching) { + if (this.#span(index, latest, holdings)) moved = true; + } const waiting = this.#waiting; this.#waiting = []; // A relative end counts back from the latest group when asked, or the first observed @@ -654,7 +664,7 @@ export class Window { /** The lowest group in range, undefined while an anchor waits. Nothing in range floors at group 0. */ floor(): bigint | undefined { - if (this.#pending || this.#waiting.length > 0 || this.#looking()) return undefined; + if (this.#pending || this.#unplaced() || this.#looking()) return undefined; return this.#runs[0]?.start ?? 0n; } @@ -663,7 +673,7 @@ export class Window { * a relative anchor waits on a first group. */ start(): bigint | undefined { - if (this.#pending || this.#waiting.length > 0 || this.#looking() || this.#spans.some((span) => !span.floored)) + if (this.#pending || this.#unplaced() || this.#looking() || this.#spans.some((span) => !span.floored)) return undefined; let start: bigint | undefined; for (const span of this.#spans) start = min(start ?? span.start, span.start); @@ -675,7 +685,7 @@ export class Window { * time end counts as open: its cap only holds reads back meanwhile. Nothing in range ends at 0. */ end(): bigint | undefined { - if (this.#pending || this.#waiting.length > 0 || this.#looking()) return undefined; + if (this.#pending || this.#unplaced() || this.#looking()) return undefined; if (this.#spans.some((span) => span.end !== "open" && "time" in span.end)) return undefined; const end = this.#runs.at(-1)?.end ?? 0n; return end === UNBOUNDED ? undefined : end; @@ -758,6 +768,11 @@ export class Window { return true; } + // Whether a time start or a join's reach back waits on the groups held to place it. + #unplaced(): boolean { + return this.#waiting.length > 0 || this.#reaching.length > 0; + } + // Whether a time start is still looked up. #looking(): boolean { return this.#spans.some((span) => span.looking); @@ -789,6 +804,7 @@ export class Window { this.#spans = []; this.#pending = false; this.#waiting = []; + this.#reaching = []; for (let index = 0; index < this.ranges.length; index++) this.#span(index, latest, holdings); this.#rebuild(); } @@ -806,9 +822,11 @@ export class Window { const min = joins(range, this.min, holdings); if (!reached && min !== undefined) { reached = latest === undefined ? undefined : holdings.reachBack?.(latest, min); - // Nothing to measure the live edge by yet. + // Nothing to measure the live edge by yet: with no group, as a relative start waits; + // with groups held, reading none of them until one measures it. if (!reached) { - this.#pending = true; + if (latest === undefined) this.#pending = true; + else this.#reaching.push(index); return false; } } @@ -846,7 +864,7 @@ export class Window { #rebuild(): void { this.#settled = !this.#pending && - this.#waiting.length === 0 && + !this.#unplaced() && this.#spans.every((span) => !span.looking && (span.end === "open" || !("time" in span.end))); const read = this.#spans.filter((span) => !span.looking); this.#runs = merge(read.map((span) => ({ start: span.start, end: limitOf(span) }))); diff --git a/quest/m0/test-flakes-3/c-raw-track-options.md b/quest/m0/test-flakes-3/c-raw-track-options.md index 01e34c233a4..385b789883d 100644 --- a/quest/m0/test-flakes-3/c-raw-track-options.md +++ b/quest/m0/test-flakes-3/c-raw-track-options.md @@ -15,11 +15,16 @@ times at the base commit 949406e072: at `rs/moq-c/src/test.rs:2794`, it receives `two` where it expects `one`, the group starting at 20 ms. The test publishes three groups 20 ms apart, then subscribes with a 25 ms -`max_us` and a range starting at 20 ms. Under load, the read likely comes -after group `one` went stale by its successor's arrival on the host clock, so -the read skips it. That is correct behaviour for a 25 ms budget, so the fix is -in the test, as the epic's rules ask: drive it on a paused or manual clock, -or give it a budget that does not depend on how fast the suite runs. Confirm -the cause before fixing. +`max_us` and two ranges: `[20000, 20001)`, holding only group `one`, and an +open one from 100,000,000 µs. Group `two` (40,000 µs) is in neither, so a +stale skip of `one` under load would explain the read missing `one` but not +receiving `two`: that read should then wait on the open range. Trace how the +consumer hands out `two` first. If a path admits a group outside the +requested ranges (such as a read before the ranges resolve, a drop or skip +that widens the range, or moq-c's own frame pump), that is a range-delivery +bug in the library, and the fix belongs there with a regression test. Only +if the trace shows `two` arrives by a path the ranges allow is the fix in +the test, as the epic's rules ask: drive it on a paused or manual clock, or +give it a budget that does not depend on how fast the suite runs. Public API: none. Wire: none. diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 775382274b6..34cd6055b32 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -355,7 +355,12 @@ pub const DELAY_MAX: std::time::Duration = std::time::Duration::from_secs(10); /// both bounds widened, so a live join reaches back far enough and the budget keeps what it reaches. fn warmed(delay: Delay, warmup: std::time::Duration) -> Delay { Delay { - min: delay.min.map(|min| min.saturating_add(warmup)), + // An unstated minimum reads as zero, so a warmup still reaches back for it. + min: match delay.min { + Some(min) => Some(min.saturating_add(warmup)), + None if warmup.is_zero() => None, + None => Some(warmup), + }, max: delay.max.map(|max| max.saturating_add(warmup)), } } @@ -4035,6 +4040,17 @@ mod tests { ); } + /// An unstated min delay reads as zero, so the warmup still reaches a live join back for it; + /// without a warmup it stays unstated. + #[test] + fn the_warmup_widens_an_unstated_min() { + let warmup = Duration::from_millis(300); + let unstated = Delay::default().with_min(None); + assert_eq!(warmed(unstated, warmup).min, Some(warmup)); + assert_eq!(warmed(unstated, Duration::ZERO).min, None); + assert_eq!(warmed(unstated.with_min(Duration::ZERO), warmup).min, Some(warmup)); + } + /// The warmup reaches past the min delay for the start, waiting for the group covering the live /// edge less both. #[tokio::test] diff --git a/rs/moq-net/src/model/subscription/window.rs b/rs/moq-net/src/model/subscription/window.rs index 6ce3b433da6..d168c9815ea 100644 --- a/rs/moq-net/src/model/subscription/window.rs +++ b/rs/moq-net/src/model/subscription/window.rs @@ -76,9 +76,10 @@ pub(in crate::model) trait Holdings { fn complete(&self) -> bool; /// Where a live join holding `min` behind the live edge starts, `latest` being the latest - /// group: the time that far behind the newest frame held, a group that starts at or - /// before it, or [`Anchor::Oldest`] when none held does. `None` while nothing held can - /// measure it, so the join waits for a group as a relative start does. + /// group: a group held, the newest one starting at or before the newest frame held less + /// `min`, or the oldest one held when none does, never a raw time a copy would ask its + /// upstream to fill. `None` while nothing held can measure it, so the join waits for a + /// group as a relative start does. fn reach_back(&self, latest: u64, min: Duration) -> Option { let _ = (latest, min); None @@ -142,6 +143,10 @@ pub(in crate::model) struct Window { /// The spans whose time start waits on a group arriving, which read only the groups from /// that time meanwhile. waiting: Vec, + /// The ranges, by index, of a live join whose reach back waits on the groups held to + /// measure the live edge, which read nothing meanwhile: a group held is no reason to + /// start at it. + reaching: Vec, /// The groups the spans cover, shared with what reads them. groups: Layered, /// The part of `groups` a miss may ask for: see [`Self::missable`]. @@ -202,6 +207,7 @@ impl Window { spans: Vec::new(), looking: Vec::new(), waiting: Vec::new(), + reaching: Vec::new(), groups: Layered::default(), missable: Layered::default(), pending: false, @@ -230,6 +236,12 @@ impl Window { self.min = min; } + /// Whether a live join's reach back waits on a group held starting, to measure the live + /// edge by. + pub fn is_reaching(&self) -> bool { + !self.reaching.is_empty() + } + /// Whether a time start still waits on the groups held to place it. pub fn is_waiting(&self) -> bool { !self.waiting.is_empty() @@ -246,7 +258,18 @@ impl Window { let _ = self.place(latest, holdings); return !self.pending; } - let moved = !self.waiting.is_empty() && self.start_waiting(holdings); + let mut moved = false; + if !self.reaching.is_empty() { + let placed = self.spans.len(); + for index in std::mem::take(&mut self.reaching) { + self.place_range(index, latest, holdings); + } + if self.spans.len() > placed { + self.name(); + moved = true; + } + } + moved |= !self.waiting.is_empty() && self.start_waiting(holdings); if moved { self.rebuild(holdings); } @@ -301,7 +324,7 @@ impl Window { /// The lowest group in range, `None` while an anchor waits. Nothing in range floors /// nowhere: group 0. pub fn floor(&self) -> Option { - match self.pending || !self.waiting.is_empty() { + match self.pending || self.unplaced() { true => None, false => Some(self.groups.lowest().unwrap_or(0)), } @@ -310,7 +333,7 @@ impl Window { /// The lowest group the ranges name, `None` while one reaches back to the oldest group /// or an anchor waits. pub fn start(&self) -> Option { - match self.pending || !self.all_named { + match self.pending || !self.reaching.is_empty() || !self.all_named { true => None, false => self.named, } @@ -319,7 +342,7 @@ impl Window { /// The lowest group a range names, `None` when none does or an anchor waits. /// Unlike [`Self::start`], a range reaching back to the oldest group names nothing. pub fn named(&self) -> Option { - match self.pending || !self.waiting.is_empty() { + match self.pending || self.unplaced() { true => None, false => self.named, } @@ -501,71 +524,90 @@ impl Window { self.spans.clear(); self.looking.clear(); self.waiting.clear(); + self.reaching.clear(); self.pending = false; - for (index, range) in self.ranges.iter().enumerate().filter(|(_, range)| !range.is_empty()) { - let Some(end) = end(range.end, latest, holdings) else { - self.pending = true; - continue; - }; - let anchor = match joins(range, self.min, holdings) { - None => range.start, - Some(min) => match latest.map(|latest| holdings.reach_back(latest, min)) { - Some(Some(anchor)) => anchor, - // Nothing to measure the live edge by yet. - _ => { - self.pending = true; - continue; - } - }, - }; - let (start, floored) = match start(anchor, latest, holdings) { - Start::At(start, floored) => (start, floored), - Start::Pending => { - self.pending = true; - continue; - } - // Reads only the groups from its time until the groups held place it; see - // [`Self::start_waiting`]. - Start::Waiting => { - self.waiting.push(self.spans.len()); - self.spans.push(Span { - index, - anchor, - start: 0, - end, - floored: false, - looking: None, - waiting: true, - }); - continue; - } - }; - // A time start the groups held can't place reads nothing until its lookup answers. A - // join's reach back never looks one up: it starts from what this hop holds. - let looking = match (range.start, anchor) { - (Anchor::Time(_), Anchor::Time(time)) => { - unresolved(time, start, floored, holdings).map(|below| Looking { time, below }) - } - _ => None, - }; - if looking.is_some() { - self.looking.push(self.spans.len()); + for index in 0..self.ranges.len() { + if !self.ranges[index].is_empty() { + self.place_range(index, latest, holdings); } - self.spans.push(Span { - index, - anchor, - start, - end, - floored, - looking, - waiting: false, - }); } self.name(); self.rebuild(holdings); Ok(()) } + /// Resolve the non-empty range at `index` into a span, or note what it waits on. + fn place_range(&mut self, index: usize, latest: Option, holdings: &impl Holdings) { + let range = self.ranges[index]; + let Some(end) = end(range.end, latest, holdings) else { + self.pending = true; + return; + }; + let anchor = match joins(&range, self.min, holdings) { + None => range.start, + Some(min) => match latest.map(|latest| holdings.reach_back(latest, min)) { + Some(Some(anchor)) => anchor, + // Nothing to measure the live edge by yet: with groups held, read none of them + // until one measures it; with none, wait as a relative start does. + Some(None) => { + self.reaching.push(index); + return; + } + None => { + self.pending = true; + return; + } + }, + }; + let (start, floored) = match start(anchor, latest, holdings) { + Start::At(start, floored) => (start, floored), + Start::Pending => { + self.pending = true; + return; + } + // Reads only the groups from its time until the groups held place it; see + // [`Self::start_waiting`]. + Start::Waiting => { + self.waiting.push(self.spans.len()); + self.spans.push(Span { + index, + anchor, + start: 0, + end, + floored: false, + looking: None, + waiting: true, + }); + return; + } + }; + // A time start the groups held can't place reads nothing until its lookup answers. A + // join's reach back never looks one up: it starts from what this hop holds. + let looking = match (range.start, anchor) { + (Anchor::Time(_), Anchor::Time(time)) => { + unresolved(time, start, floored, holdings).map(|below| Looking { time, below }) + } + _ => None, + }; + if looking.is_some() { + self.looking.push(self.spans.len()); + } + self.spans.push(Span { + index, + anchor, + start, + end, + floored, + looking, + waiting: false, + }); + } + + /// Whether a time start or a join's reach back waits on the groups held to place it. + fn unplaced(&self) -> bool { + !self.waiting.is_empty() || !self.reaching.is_empty() + } + /// Keep [`Self::named`] and [`Self::start`] current with where the spans start. fn name(&mut self) { self.named = self @@ -582,7 +624,7 @@ impl Window { fn rebuild(&mut self, holdings: &impl Holdings) { self.covered = None; // A span still looking up its start reads nothing until it knows which group that is. - self.settled = !self.pending && self.looking.is_empty() && self.waiting.is_empty(); + self.settled = !self.pending && self.looking.is_empty() && !self.unplaced(); let (mut groups, mut missable) = (Vec::new(), Vec::new()); for span in self.spans.iter().filter(|span| span.looking.is_none()) { let Some(last) = span.end.map_or(Some(u64::MAX), |end| end.checked_sub(1)) else { diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 1b143d4100a..e56c5dcb5d3 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1069,23 +1069,27 @@ impl Holdings for TrackState { /// Groups keyed by their start are found by key; on a copy whose wire keys groups /// otherwise, by when each one's first frame presented. Pending until a group is held. fn reach_back(&self, latest: u64, min: Duration) -> Option { - let oldest = || self.live(..).next().map(|(&key, _)| Anchor::Time(key)); + let oldest = || self.walked(..).next().map(|(&key, _)| Anchor::Time(key)); let Some(scale) = self.info.as_ref()?.timescale else { - let key = self.live(..).rev().find(|(_, slot)| self.aged(slot.arrived, min)); + let key = self.walked(..).rev().find(|(_, slot)| self.aged(slot.arrived, min)); return key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest); }; let newest = self .live_edge(&Servable::ALL) .and_then(|edge| edge.timestamp.convert(scale).ok()) .map(Timestamp::value); - // A Min Age past every timestamp reaches back to the oldest group. - let back = Timestamp::try_from(min) - .and_then(|min| min.convert(scale)) - .map_or(u64::MAX, Timestamp::value); + // Rounded up to whole ticks, so the start is never newer than the Min Age allows; one + // past every timestamp reaches back to the oldest group. + let back = u64::try_from( + min.as_nanos() + .saturating_mul(u128::from(scale.as_u64())) + .div_ceil(1_000_000_000), + ) + .unwrap_or(u64::MAX); if self.anchors != Anchors::Refused && !self.starts_at_keys { let edge = newest.map_or(latest, |newest| newest.max(latest)); let target = edge.saturating_sub(back); - let key = self.live(..=target).next_back(); + let key = self.walked(..=target).next_back(); return key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest); } let target = newest?.saturating_sub(back); @@ -1094,7 +1098,7 @@ impl Holdings for TrackState { .and_then(|start| start.convert(scale).ok()) .is_some_and(|start| start.value() <= target) }; - let key = self.live(..).rev().find(|(_, slot)| started(slot)); + let key = self.walked(..).rev().find(|(_, slot)| started(slot)); key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest) } @@ -1888,6 +1892,20 @@ impl TrackState { } } + /// Wake `waiter` once a live group held starts: a group starting wakes no reader parked on + /// the track, and a live join's reach back waits on one to measure the live edge by. + fn watch_starts(&self, waiter: &kio::Waiter) { + for (_, slot) in self.walked(..) { + let _ = slot.group.poll_started(waiter); + } + } + + /// The live-feed groups in `range` still served: an aborted one cannot start a join, whose + /// floor would then pass the usable group before it. + fn walked(&self, range: impl ops::RangeBounds) -> impl DoubleEndedIterator { + self.live(range).filter(|(_, slot)| slot.is_walked()) + } + /// The live feed's cached groups within `range`, by key: never fetched backfill. fn live(&self, range: impl ops::RangeBounds) -> impl DoubleEndedIterator { // Without backfill every cached group is the feed's, so the cache is walked as is. @@ -8469,7 +8487,11 @@ impl Cursor { self.filter.window.set_min(min); self.filter.window.settle(state.first_live(), holdings) } - None => self.filter.window.settle(state.latest_live(), holdings), + None => { + // A live join waiting on a group to measure the live edge by has not started either. + self.filter.window.set_min(min); + self.filter.window.settle(state.latest_live(), holdings) + } }; drop(state); if moved { @@ -8810,6 +8832,9 @@ impl Cursor { if res.is_pending() { // The end can settle with no write: when the grace for a missing group passes. state.watch_tail(waiter); + if self.filter.window.is_reaching() { + state.watch_starts(waiter); + } } res }); @@ -12312,6 +12337,68 @@ mod test { assert_eq!(ready_groups(&mut far), (0..10).collect::>()); } + /// A live join reads none of the groups held until one measures the live edge: a copy + /// holding only group headers gives nothing to reach back by, so no group is handed out + /// before a first frame says where the join starts. + #[test] + fn a_live_join_reads_nothing_until_a_frame_measures_the_live_edge() { + let producer = track_producer("test", Info::timed()); + producer.received(); + producer.starts_at_keys(); + let groups: Vec<_> = (0..10) + .map(|key| producer.create_group(group::Info { start: key }).unwrap()) + .collect(); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!(ready_groups(&mut reader), Vec::::new(), "nothing to measure by"); + for (key, mut group) in (0..).zip(groups) { + group + .write_frame(Timestamp::from_millis(key * 500).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); + } + let mut got = ready_groups(&mut reader); + got.sort_unstable(); + assert_eq!(got, vec![5, 6, 7, 8, 9]); + } + + /// A join skips a group the publisher gave up: it starts at the newest group still served + /// that began by the target, never at an aborted one that would floor it past that group. + #[test] + fn a_live_join_reaches_back_past_an_aborted_group() { + let mut producer = track_producer("test", Info::timed()); + for _ in (0..=2500).step_by(500) { + append_half_second(&mut producer); + } + let aborted = producer.create_group(group::Info { start: 3000 }).unwrap(); + aborted.abort(Error::Cancel).unwrap(); + let mut group = producer.create_group(group::Info { start: 3500 }).unwrap(); + group + .write_frame(Timestamp::from_millis(3500).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); + for _ in (4000..=5000).step_by(500) { + append_half_second(&mut producer); + } + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!(ready_groups(&mut reader)[0], 2500); + } + + /// A Min Age that is not a whole number of ticks rounds up, so the join never starts newer + /// than it allows. + #[test] + fn a_live_join_rounds_its_min_age_up_to_whole_ticks() { + let producer = track_producer("test", Info::timed()); + for start in 0..=2 { + let mut group = producer.create_group(group::Info { start }).unwrap(); + group + .write_frame(Timestamp::from_millis(start).unwrap(), &b"x"[..]) + .unwrap(); + group.close().unwrap(); + } + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_micros(1500))); + assert_eq!(ready_groups(&mut reader), vec![0, 1, 2]); + } + /// A lite-07 copy reaches back only to groups it holds, so the join starts at once and /// leaves no unheld prefix for its upstream to be asked: the newest group held starting at /// or before the target, or the oldest one held when none does. From bc2788e3756be4ff60863a421f4837412f0ff0cd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 14:03:43 -0800 Subject: [PATCH 9/9] fix(net): a live join measures from groups still held, flooring between-tick timestamps Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 13 +++++++++++++ js/net/src/track.ts | 7 ++++--- rs/moq-net/src/model/track.rs | 20 ++++++++++++++++---- 3 files changed, 33 insertions(+), 7 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 7e55351956a..8711c7d6ecf 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -956,6 +956,19 @@ test("a live join reaches back by ticks rounded up, at any timestamp the track a expect(readable(reader)).toEqual([0n, 1n, 2n]); }); +test("a live join measures timestamps between ticks, floored", () => { + const producer = new TrackProducer("test"); + producer.accept({ timescale: Timescale.MILLI, maxAge: null }); + for (const [sequence, ms] of [0.5, 1.5, 2.5].entries()) { + const group = producer.createGroup(BigInt(sequence)); + group.writeFrame(textFrame(`${sequence}`, Timestamp.fromMillis(ms))); + group.finish(); + } + // The edge floors to 2 ms, so 1 ms back is the group starting by 1 ms. + const reader = producer.subscribe({ delay: { min: Duration.millis(1), max: Duration.secs(30) }, ranges: [LIVE] }); + expect(readable(reader)).toEqual([1n, 2n]); +}); + test("a scale-less join reaches back by arrival", () => { const clock = manualTime(0); try { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 492ec05c73d..23e42f16d75 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -52,7 +52,7 @@ import { } from "./internal.ts"; import { grace, Ledger } from "./ledger.ts"; import { rescale } from "./rescale.ts"; -import { keyOf, Timescale, type Timestamp } from "./time.ts"; +import { floorAt, keyOf, Timescale, type Timestamp } from "./time.ts"; import { checkEnd, checkSequence, max, min, UNBOUNDED } from "./util/sequence.ts"; import { bounded, @@ -3390,12 +3390,13 @@ export class Subscriber { // In the track's own scale, which holds every timestamp it accepted. The Min Age rounds up // to whole ticks, so the start is never newer than it allows. const back = (BigInt(Math.ceil(min.asNanos())) * BigInt(scale) + 999_999_999n) / 1_000_000_000n; - const edge = BigInt((hooks.groupLatest(stamped) ?? started).as(scale)); + // Floored exactly, as Rust's `Timestamp::convert`: an accepted timestamp may sit between ticks. + const edge = BigInt(floorAt(hooks.groupLatest(stamped) ?? started, scale)); const target = edge > back ? edge - back : 0n; return held( newest((group) => { const start = hooks.groupTimestamp(group); - return start !== undefined && BigInt(start.as(scale)) <= target; + return start !== undefined && BigInt(floorAt(start, scale)) <= target; }), ); } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index e56c5dcb5d3..809d11dfce6 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1061,14 +1061,14 @@ impl Holdings for TrackState { self.outcome.is_final() } - /// In media time, from the newest frame held, or the latest group's start when it is - /// newer; on a scale-less track, by arrival on this hop's clock, as expiry measures it. + /// In media time, from the newest frame held, or the newest group still served when it + /// starts later, never a group given up; on a scale-less track, by arrival on this hop's clock, as expiry measures it. /// /// Always a group this hop holds: the newest one starting at or before the target, or the /// oldest one when none does, so a copy never asks its upstream for the prefix it lacks. /// Groups keyed by their start are found by key; on a copy whose wire keys groups /// otherwise, by when each one's first frame presented. Pending until a group is held. - fn reach_back(&self, latest: u64, min: Duration) -> Option { + fn reach_back(&self, _latest: u64, min: Duration) -> Option { let oldest = || self.walked(..).next().map(|(&key, _)| Anchor::Time(key)); let Some(scale) = self.info.as_ref()?.timescale else { let key = self.walked(..).rev().find(|(_, slot)| self.aged(slot.arrived, min)); @@ -1087,7 +1087,8 @@ impl Holdings for TrackState { ) .unwrap_or(u64::MAX); if self.anchors != Anchors::Refused && !self.starts_at_keys { - let edge = newest.map_or(latest, |newest| newest.max(latest)); + let held = self.walked(..).next_back().map(|(&key, _)| key); + let edge = newest.max(held)?; let target = edge.saturating_sub(back); let key = self.walked(..=target).next_back(); return key.map(|(&key, _)| Anchor::Time(key)).or_else(oldest); @@ -12399,6 +12400,17 @@ mod test { assert_eq!(ready_groups(&mut reader), vec![0, 1, 2]); } + /// A newest group given up does not move the live edge: the join measures from the content + /// still held, so it keeps the buffering prefix. + #[test] + fn a_live_join_measures_from_groups_still_held() { + let producer = half_second_groups(); + let aborted = producer.create_group(group::Info { start: 10_000 }).unwrap(); + aborted.abort(Error::Cancel).unwrap(); + let mut reader = producer.subscribe(joining(Range::live(), Duration::from_secs(2))); + assert_eq!(ready_groups(&mut reader)[0], 3000); + } + /// A lite-07 copy reaches back only to groups it holds, so the join starts at once and /// leaves no unheld prefix for its upstream to be asked: the newest group held starting at /// or before the target, or the oldest one held when none does.