From 4b669ae97fd30fecb2058a3a2cb683a29b2d1038 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 20 Oct 2026 15:27:06 -0700 Subject: [PATCH 01/22] quest: claim public ingest From 00d700ac93ac767d93ada965d38fef4f54fff98b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:13:41 -0700 Subject: [PATCH 02/22] refactor(net)!: derive a group's content from its own state, publish session end calls Drop received-group withholding: every group joins arrival order when created, and the model's judgments (live edge, successor, rejoin wait, newest, idle) count a group only once its first frame opens or it finishes. receive_group, reveal_group, and is_started go; the lite subscriber uses create_group. Publish group::Producer::info, track::Producer::received and close, and fold abort_session into abort, which now aborts open groups too. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 4 +- rs/moq-net/src/lite/subscriber.rs | 43 +--- rs/moq-net/src/model/group.rs | 47 +++- rs/moq-net/src/model/resume.rs | 9 +- rs/moq-net/src/model/track.rs | 363 ++++++++++++------------------ 5 files changed, 207 insertions(+), 259 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index d590a411019..7adf1b43435 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -179,14 +179,14 @@ impl State { request.reject(err.clone()); } if let Some(producer) = track.producer { - let _ = producer.abort_session(err.clone()); + let _ = producer.abort(err.clone()); } if let Fill::Ready { producer, .. } = &*track.fill.read() { let _ = producer.handle().abort(err.clone()); } } for (_, producer) in self.lingering.drain() { - let _ = producer.abort_session(err.clone()); + let _ = producer.abort(err.clone()); } } fn close(&mut self) { diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 825dcbe86ec..6b797309267 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -566,7 +566,7 @@ impl SubscriptionCleanup { /// their cleanup independently; this records the track's terminal state. fn abort(&self, err: &Error) { for (_, entry) in self.0.lock().drain() { - let _ = entry.producer.abort_session(err.clone()); + let _ = entry.producer.abort(err.clone()); } } fn close(&self) { @@ -857,8 +857,6 @@ enum GroupRecvState { group: crate::recv::Group, track: track::Producer, ingest: FrameIngest, - /// Whether readers see the group yet; see [`track::Producer::receive_group`]. - shown: bool, _reading: Reading, }, Done, @@ -888,9 +886,9 @@ impl GroupRecv { let group_info = group::Info { sequence: hdr.sequence }; // Stats (groups/frames/bytes) are counted in the model as the group - // is written, through the tagged `track::Producer`. Withheld from - // readers until its first frame lands. - let received = entry.producer.receive_group(group_info); + // is written, through the tagged `track::Producer`. The track counts + // it as content once its first frame lands. + let received = entry.producer.create_group(group_info); // The subscription's end waits until this stream is read. Counted // whatever the cache said, since the publisher counts every stream it // opens (a resubscribe resends a cached group), and only after the @@ -940,16 +938,11 @@ impl GroupRecv { group: crate::recv::Group::new(group), track, ingest: FrameIngest::new(&self.subscriber, timescale, ietf, hdr.frame_start), - shown: false, _reading: reading, }; } GroupRecvState::Serve { - group, - track, - ingest, - shown, - .. + group, track, ingest, .. } => { // The track or group dying cancels the stream; the peer's own close // arrives through the ingest's reads. @@ -960,13 +953,7 @@ impl GroupRecv { if let Poll::Ready(err) = group.handle().poll_closed(waiter) { break 'serve Err(err); } - let res = ingest.poll(&mut self.reader, group, waiter); - // Shown once its first frame opens, even mid-payload. - if !*shown && group.handle().is_started() { - track.reveal_group(group.handle()); - *shown = true; - } - match res { + match ingest.poll(&mut self.reader, group, waiter) { Poll::Ready(res) => break 'serve res, Poll::Pending => return Poll::Pending, } @@ -976,16 +963,13 @@ impl GroupRecv { // short drops into an already-aborted group instead of reporting a loss. let GroupRecvState::Serve { group, - track, ingest: _ingest, - shown, _reading, + .. } = std::mem::replace(&mut self.state, GroupRecvState::Done) else { unreachable!() }; - // A group that ended without a frame shows once it settles. - let handle = (!shown).then(|| group.handle().clone()); let res = match res { Ok(()) => { let _ = group.finish(); @@ -1001,9 +985,6 @@ impl GroupRecv { Err(err) } }; - if let Some(handle) = handle { - track.reveal_group(&handle); - } return Poll::Ready(res); } GroupRecvState::Done => return Poll::Ready(Ok(())), @@ -1850,7 +1831,7 @@ mod tests { /// A group arriving at the relay as its header lands: cached, then accounted for. fn arrive(track: &track::Producer, tail: &kio::Producer, sequence: u64, now: crate::time::Instant) { - let mut group = track.receive_group(group::Info { sequence }).unwrap(); + let mut group = track.create_group(group::Info { sequence }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); let Ok(mut ledger) = tail.write() else { @@ -1935,7 +1916,7 @@ mod tests { let h = Harness::new(Version::Lite04); let (mut track, fetching, req) = feed_fetch(3); for sequence in [5, 6] { - let mut group = track.receive_group(group::Info { sequence }).unwrap(); + let mut group = track.create_group(group::Info { sequence }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); } @@ -1980,7 +1961,7 @@ mod tests { "group 3 was asked for just now (update: {update})" ); - let mut group = track.receive_group(group::Info { sequence: 3 }).unwrap(); + let mut group = track.create_group(group::Info { sequence: 3 }).unwrap(); group.write_frame(None, &b"x"[..]).unwrap(); group.finish().unwrap(); fetches.poll(&sub, now, &kio::Waiter::noop()); @@ -2800,7 +2781,7 @@ mod tests { "video", crate::track::Info::timed(), ); - let mut cached = track.receive_group(group::Info { sequence: 3 }).unwrap(); + let mut cached = track.create_group(group::Info { sequence: 3 }).unwrap(); cached.write_frame(Timestamp::ZERO, &b"x"[..]).unwrap(); cached.finish().unwrap(); let tail = kio::Producer::new(Tail::default()); @@ -3919,7 +3900,7 @@ mod tests { let established = h.wire().len(); let arrive = |serving: &ServeLoop, sequence| { - let mut group = serving.serving.receive_group(group::Info { sequence }).unwrap(); + let mut group = serving.serving.create_group(group::Info { sequence }).unwrap(); for frame in [&b"key"[..], b"abc", b"d"] { group.write_frame(None, frame).unwrap(); } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 6498967b55d..15b03de3f11 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -700,6 +700,10 @@ struct Alive { // Whether the abort was the publisher giving the group up rather than cache policy // (`Old`, `Timeout`, `Evicted`). Stored before `aborted`, under the same rules. cut: AtomicBool, + // Monotone mirror of `GroupState::started` for the first frame or the finish, set after + // the group lock is released and before the track is told: a track scan reading a stale + // false judges the group frameless until that wake re-judges it. + started: AtomicBool, // The cache stamp `GroupState::charge` maintains, held here as well so the // eviction and expiry walks can weigh a candidate without taking the group lock // they already hold the track lock over. @@ -823,6 +827,7 @@ impl Producer { aborted: AtomicBool::new(false), checked: AtomicBool::new(false), cut: AtomicBool::new(false), + started: AtomicBool::new(false), access, }); Self { @@ -845,9 +850,8 @@ impl Producer { self } - /// The group header. - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn info(&self) -> Info { + /// The group's header, as it was created. + pub fn info(&self) -> Info { self.handle.info } @@ -950,6 +954,7 @@ impl Producer { track.share_bound(self.handle.info.sequence, start); } drop(track); + self.handle.start(); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. @@ -1037,6 +1042,9 @@ impl Producer { track.share_bound(self.handle.info.sequence, start); } drop(track); + if count > 0 { + self.handle.start(); + } self.handle.cache.settle(now); if let Some(latest) = latest { @@ -1159,6 +1167,7 @@ impl Producer { track.share_bound(self.handle.info.sequence, start); } drop(track); + self.handle.start(); // With the group lock released (lock order is track then group), settle // eviction debt if enough has been written since the track last paid. @@ -1246,6 +1255,9 @@ impl Producer { let mut state = modify(&self.handle.state)?; debug_assert!(state.partial.is_none(), "a frame is already open"); state.fin = Some(state.next_index); + drop(state); + // An empty group counts as content once it ends. + self.handle.start(); // A finished group can no longer raise the track's largest, which may end its stream. self.handle.cache.finish_largest(self.sequence); Ok(()) @@ -1408,6 +1420,7 @@ impl Handle { } let now = state.charge.add(payload + metadata + growth); drop(state); + self.start(); self.cache.settle(now); } @@ -1535,11 +1548,29 @@ impl Handle { self.state.same_channel(&other.state) } - /// Whether the group opened its first frame, or ended without one. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn is_started(&self) -> bool { - self.state.read().started() + /// Whether the group opened its first frame or finished, so the track counts it as + /// content. An aborted group is not content either way. + /// + /// Reads the mirror rather than the group's state, so a track scan holding the track + /// lock never takes the group's. + pub(super) fn is_started(&self) -> bool { + self.alive.started.load(Ordering::Relaxed) + } + + /// The first frame opened or the group finished: tell the track once, so it re-judges + /// the reads that skipped this group while it was frameless. Called with the group + /// lock released, since the track's is taken first. + fn start(&self) { + if self.alive.started.swap(true, Ordering::Relaxed) { + return; + } + let Some(track) = self.cache.track() else { + return; + }; + let answers = track.read().reveal(self); + if answers && let Ok(mut state) = track.write() { + state.shown(self.sequence); + } } /// Where the group starts in presentation time: its first frame's timestamp, or diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index f23b4d8f831..1a25d51259a 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1604,7 +1604,7 @@ mod test { let b = copy(); let dynamic = b.dynamic(); - let mut newer = b.receive_group(group::Info { sequence: 1 }).unwrap(); + let mut newer = b.create_group(group::Info { sequence: 1 }).unwrap(); newer.write_frame(ts(1), b"newer".as_ref()).unwrap(); newer.finish().unwrap(); routes.serve(b.consume()); @@ -1621,7 +1621,7 @@ mod test { ); if arrives { - let mut late = b.receive_group(group::Info { sequence: 0 }).unwrap(); + let mut late = b.create_group(group::Info { sequence: 0 }).unwrap(); late.write_frame(ts(0), b"first".as_ref()).unwrap(); late.write_frame(ts(1), b"continued".as_ref()).unwrap(); late.finish().unwrap(); @@ -2953,6 +2953,8 @@ mod test { assert_eq!(read(&mut group), Some(b"held".to_vec())); let b = copy(); + // A route's copy, whose received timestamps are never checked for a rewind. + b.received(); routes.serve(b.consume()); let groups = groups .iter() @@ -3023,7 +3025,8 @@ mod test { #[test] #[cfg(feature = "async")] fn a_group_no_route_continues_wakes_when_its_successor_aborts() { - let mut held = Held::new(&[(3, None), (4, Some(4000)), (5, Some(5000))]); + // A frameless successor bounds nothing, so it takes one that started near the edge. + let mut held = Held::new(&[(3, Some(4950)), (4, Some(4000)), (5, Some(5000))]); // Group 4 succeeds it instead, a full second behind the edge. held.groups.remove(&3).unwrap().abort(Error::Dropped).unwrap(); assert!(held.woken(), "the successor's abort wakes the held group"); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 5a7d2f66c1b..84e765a2c6d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -386,10 +386,6 @@ pub(crate) struct TrackState { // does, so this holds only the gaps still worth waiting for. arrivals: Ledger, - // Cached groups a route is still withholding (see `Slot::pending`), so an end check - // need not scan the cache for one. - withheld: usize, - // No producer remains (aborted, sealed, or dropped), so nothing protects the live // edge any longer: the pool's idle expiry reclaims it like every other group, and a // stale consumer cannot pin the cache. @@ -500,12 +496,8 @@ struct Slot { // subscription content. Fetch-only backfill stays cached but never anchors drift. visible: bool, - // A live group received from a route, withheld from readers until its first frame - // lands or its stream ends; see [`Producer::receive_group`]. - pending: bool, - - // When the group arrived here, withheld or not: the start of the wall clock for the - // group before it (see [`TrackState::arrival`]). Read on the pool's clock. + // When the group arrived here, before its first frame: the start of the wall clock for + // the group before it (see [`TrackState::arrival`]). Read on the pool's clock. arrived: crate::time::Instant, // A fetched copy of a live `group` that the feed started past the frames a fetch @@ -521,15 +513,17 @@ impl Slot { self.visible && !self.group.is_aborted() } - /// Whether readers see this slot as live content: [`Self::is_live`], and not withheld. + /// Whether this slot counts as live content: [`Self::is_live`], and its first frame + /// opened or it finished. A frameless group is handed to readers, but no judgment + /// counts it until then: not the live edge, a successor, nor the rejoin wait. fn is_shown(&self) -> bool { - self.is_live() && !self.pending + self.is_live() && self.group.is_started() } - /// Whether the arrival walk hands this slot out: the live feed's, not withheld, and - /// still serving, a fetched head counting for an aborted live group. + /// Whether the arrival walk hands this slot out: the live feed's, and still serving, a + /// fetched head counting for an aborted live group. fn is_walked(&self) -> bool { - self.visible && !self.pending && !self.is_aborted() + self.visible && !self.is_aborted() } /// The copy to hand readers: the fetched head while it lasts, else the live group. @@ -1065,8 +1059,8 @@ impl TrackState { self.successor(sequence, servable)?.group.timestamp() } - /// The group after `sequence` that bounds it: the first servable one in `servable`, - /// stamped or not, empty or not. + /// The group after `sequence` that bounds it: the first servable one in `servable` whose + /// first frame opened or that finished, stamped or not, empty or not. fn successor(&self, sequence: u64, servable: &Servable) -> Option<&Slot> { self.find_servable(servable, sequence.checked_add(1)?, false, |slot| { slot.is_shown().then_some(slot) @@ -1074,8 +1068,8 @@ impl TrackState { } /// The group after `sequence` that starts its wall clock: like [`Self::successor`], but - /// counting a group a route is still withholding. Its header arrived, so a relay ages the - /// group before it as the origin does, even if its first frame never comes. + /// counting a group before its first frame. Its header arrived, so a relay ages the group + /// before it as the origin does, even if its first frame never comes. fn arrival(&self, sequence: u64, servable: &Servable) -> Option<&Slot> { self.find_servable(servable, sequence.checked_add(1)?, false, |slot| { slot.is_live().then_some(slot) @@ -1456,7 +1450,6 @@ impl TrackState { } self.lookup .retain(|_, slot| slot.copies().any(group::Handle::is_finished)); - self.withheld = self.lookup.values().filter(|slot| slot.pending).count(); let lookup = &self.lookup; self.bounds .get_mut() @@ -1464,10 +1457,9 @@ impl TrackState { .retain(|sequence, _| lookup.contains_key(sequence)); } - /// Take `sequence` out of the cache, keeping the withheld count in step. + /// Take `sequence` out of the cache, along with its checked start. fn remove_slot(&mut self, sequence: u64) -> Option { let slot = self.lookup.remove(&sequence)?; - self.withheld -= usize::from(slot.pending); self.bounds .get_mut() .unwrap_or_else(PoisonError::into_inner) @@ -1570,9 +1562,9 @@ impl TrackState { /// Updates the live edge, demoting the previous latest into the eviction order; /// the current latest is never enqueued, which is what protects it from /// eviction. `visible` controls arrival-order delivery: publisher-produced - /// groups reach subscribers, fetched backfill is served by sequence only. A - /// `pending` group joins arrival order only once [`Self::reveal`] shows it. - fn insert_group(&mut self, group: &group::Handle, visible: bool, pending: bool) { + /// groups reach subscribers, fetched backfill is served by sequence only. A group + /// counts as content only once [`Self::reveal`] reports its first frame or finish. + fn insert_group(&mut self, group: &group::Handle, visible: bool) { let sequence = group.sequence; self.next_stamp = self.next_stamp.wrapping_add(1); let stamp = self.next_stamp; @@ -1614,66 +1606,45 @@ impl TrackState { if visible { self.record_arrival(sequence, now); } - self.withheld += usize::from(pending); let replaced = self.lookup.insert( sequence, Slot { group: group.clone(), stamp, visible, - pending, arrived: now, head: None, }, ); - if let Some(replaced) = replaced { - self.withheld -= usize::from(replaced.pending); + if replaced.is_some() { self.bounds .get_mut() .unwrap_or_else(PoisonError::into_inner) .remove(&sequence); } self.cache.wakes().arrived(sequence..=sequence); - if visible && !pending { + if visible { + // Readers and group demand reach it at once. Its arrival starts the wall clock of + // the reads it succeeds, but it counts as content only once it starts. self.arrival.push_back((sequence, stamp)); - self.landed(sequence); - } else if visible { - // Withheld, but its arrival starts the wall clock of the reads it succeeds. self.wake_landed(sequence); } } - /// Show a [`Producer::receive_group`] group to readers, if `group` still holds its slot. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - fn reveal(&mut self, group: &group::Handle) { + /// Count `group` as content now that its first frame opened or it finished, if it + /// still holds its slot: wake the reads it succeeds. Returns whether an answer waits on + /// it, which the caller shows with [`Self::shown`] under the write lock. + /// + /// Takes the read lock so a group starting wakes only the reads it can move, not every + /// reader parked on the track. + pub(super) fn reveal(&self, group: &group::Handle) -> bool { let sequence = group.sequence; - let Some(slot) = self.lookup.get_mut(&sequence) else { - return; - }; - if !slot.pending || !slot.group.is_clone(group) { - return; - } - slot.pending = false; - self.withheld -= 1; - self.arrival.push_back((sequence, slot.stamp)); - // A group reset before its first frame shows nothing of the route's feed. - if slot.group.is_aborted() { - return; - } - let latest = slot.group.latest(); - self.landed(sequence); - // Its frames presented while hidden, so a read woken by them may have judged the - // older edge and parked again: present them once more now that they count. - if let Some(latest) = latest { - self.cache.wakes().presented(latest); + match self.lookup.get(&sequence) { + Some(slot) if slot.visible && slot.group.is_clone(group) && !slot.group.is_aborted() => {} + _ => return false, } - } - - /// Content at `sequence` became servable: wake the reads it succeeds, and show an answer - /// waiting on it. - fn landed(&mut self, sequence: u64) { self.wake_landed(sequence); - self.shown(sequence); + matches!(self.feed, Feed::Answered { from } if sequence >= from) } /// Wake the reads a group landing at `sequence` succeeds. @@ -1689,7 +1660,7 @@ impl TrackState { } /// Content at `sequence` became readable: an answer waiting on it now shows. - fn shown(&mut self, sequence: u64) { + pub(super) fn shown(&mut self, sequence: u64) { if let Feed::Answered { from } = self.feed && sequence >= from { @@ -1700,9 +1671,9 @@ impl TrackState { /// Admit a freshly-created group: settle eviction debt first (so the newcomer /// can never be a victim of the very write that created it), insert it, then /// expire idle groups. - fn commit_group(&mut self, group: &group::Handle, pending: bool) { + fn commit_group(&mut self, group: &group::Handle) { self.charge_debt(); - self.insert_group(group, true, pending); + self.insert_group(group, true); self.evict_expired(); } @@ -1931,7 +1902,7 @@ impl TrackState { let reached = self.sealed || self .final_sequence() - .is_some_and(|fin| self.edge() >= fin && !self.withholds() && !self.awaits_tail(fin)); + .is_some_and(|fin| self.edge() >= fin && !self.awaits_tail(fin)); reached && (self.abort.is_none() || self.settled) } @@ -1948,14 +1919,6 @@ impl TrackState { self.max_sequence.map_or(0, |max| max.saturating_add(1)) } - /// Whether a cached group is still withheld from readers until its first frame lands - /// (see [`Producer::receive_group`]): the end is not reached before it shows, or - /// readers would end without it. Every cached group sits below a declared end. - fn withholds(&self) -> bool { - debug_assert_eq!(self.withheld, self.lookup.values().filter(|slot| slot.pending).count()); - self.withheld > 0 - } - /// Whether a group below `fin` the wire subscription still owes has yet to arrive. /// Only such a hole holds readers, so a tail with nothing missing ends them at once. fn awaits_tail(&self, fin: u64) -> bool { @@ -2092,7 +2055,7 @@ impl TrackState { .lookup .iter() .rev() - .find(|(_, slot)| slot.visible && !slot.pending)?; + .find(|(_, slot)| slot.visible && slot.group.is_started())?; Some((*sequence, slot.group.frame_count() as u64)) } @@ -2192,7 +2155,7 @@ impl TrackState { } // Invisible to arrival-order subscribers: fetched on demand, not produced // live by the publisher. - None => self.insert_group(&group.handle(), false, false), + None => self.insert_group(&group.handle(), false), } self.evict_expired(); Ok(group) @@ -2367,34 +2330,11 @@ impl Producer { } /// Create a new group with the given sequence number. - pub fn create_group(&self, group: group::Info) -> Result { - self.insert(group, false) - } - - /// Create a group a session is receiving from a route, withheld from readers until - /// [`Self::reveal_group`]. /// - /// A publisher writes a group's first frame as it creates it, but a route's group - /// header lands before its first frame. Shown in between, it would leave the group - /// before it with no stamped successor, so a joiner at the live edge would be handed - /// that older group first. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn receive_group(&self, group: group::Info) -> Result { - self.insert(group, true) - } - - /// Show a [`Self::receive_group`] group to readers: its first frame landed, or its - /// stream ended. A no-op once another incarnation took its sequence. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn reveal_group(&self, group: &group::Handle) { - if let Ok(mut state) = self.modify() { - state.reveal(group); - } - } - - fn insert(&self, group: group::Info, pending: bool) -> Result { + /// Readers and group demand reach it at once, but the track counts it as content (its + /// live edge, or the successor that ages the group before it) only once its first frame + /// opens or it finishes. + pub fn create_group(&self, group: group::Info) -> Result { let mut state = self.modify()?; // A sealed track takes no group, not even one below its end. if state.sealed || state.final_sequence().is_some_and(|fin| group.sequence >= fin) { @@ -2407,7 +2347,7 @@ impl Producer { let group = group::Producer::new(group, track, state.cache.clone()).with_meter(self.stats.meter()); state.cap(&group.handle())?; - state.commit_group(&group.handle(), pending); + state.commit_group(&group.handle()); Ok(group) } @@ -2430,7 +2370,7 @@ impl Producer { let group = group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter()); state.cap(&group.handle())?; - state.commit_group(&group.handle(), false); + state.commit_group(&group.handle()); Ok(group) } @@ -2563,10 +2503,12 @@ impl Producer { Ok(()) } - /// End a locally closed session's receive track without declaring a wire boundary. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn close(self) -> Result<()> { + /// End the track without declaring where it ends, as a closed session does. + /// + /// Consumers drain the groups that finished and then end cleanly; the open groups are + /// dropped. A reader following the track's routes resumes from another one where this + /// copy stopped. Use [`Self::finish`] or [`Self::finish_at`] when the end is known. + pub fn close(self) -> Result<()> { let mut state = self.modify()?; state.sealed = true; // See `commit_abort`: a takeover resumes mid-group once the open group goes away. @@ -2577,25 +2519,6 @@ impl Producer { Ok(()) } - /// Abort the groups still receiving from a failed session before ending its track. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn abort_session(self, err: Error) -> Result<()> { - let state = self.modify()?; - let open: Vec<_> = state - .lookup - .values() - .filter(|slot| !slot.group.is_finished()) - .map(|slot| slot.group.clone()) - .collect(); - // Snapshot the resume boundary before aborting groups releases their frames. - commit_abort(state, err.clone()); - for group in open { - let _ = group.abort(err.clone()); - } - Ok(()) - } - /// Mark the track as finished after the last appended group. /// /// Ends the track at the head of the group after the current max_sequence. @@ -2686,11 +2609,10 @@ impl Producer { Ok(()) } - /// Mark this track as a session's copy of a remote one: its groups are never checked - /// for a rewind, which only a local publisher's writes refuse. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn received(&self) { + /// Mark this track as a copy received from a remote publisher: its groups are never + /// checked for a timestamp rewind, which only a local publisher's writes refuse, since a + /// received timestamp may not be media time. + pub fn received(&self) { if let Ok(mut state) = self.modify() { state.received = true; } @@ -2795,10 +2717,11 @@ impl Producer { /// Abort the track with the given error. /// /// Consumes the handle, since nothing can be written to an aborted track. Consumers - /// still draining get the finished groups, then the abort error. Open groups leave the - /// cache; a consumer that already pulled one keeps its own handle and ends with it. - /// The pool's idle expiry (see [`cache::Config::with_expiry`]) reclaims the rest, the - /// latest group included, so a stale [`Consumer`] can't pin them in memory forever. + /// still draining get the finished groups, then the abort error. Open groups are + /// aborted with the same error and leave the cache, so a consumer that already pulled + /// one ends with it too, and their writers fail. The pool's idle expiry (see + /// [`cache::Config::with_expiry`]) reclaims the rest, the latest group included, so a + /// stale [`Consumer`] can't pin them in memory forever. /// /// If the declared end had settled (the final sequence from /// [`finish_at`](Self::finish_at) was reached and every group below it finished), @@ -2807,7 +2730,19 @@ impl Producer { /// [`finish`](Self::finish) is deliberately not terminal: it declares the final /// sequence, and lower-numbered groups may still be written afterwards. pub fn abort(self, err: Error) -> Result<()> { - TrackState::abort(&self.state, err) + let state = self.modify()?; + let open: Vec<_> = state + .lookup + .values() + .filter(|slot| !slot.group.is_finished()) + .map(|slot| slot.group.clone()) + .collect(); + // Snapshot the resume boundary before aborting groups releases their frames. + commit_abort(state, err.clone()); + for group in open { + let _ = group.abort(err.clone()); + } + Ok(()) } /// Abort an unused track, returning the producer unchanged if consumers remain. @@ -2880,13 +2815,30 @@ impl Producer { kio::wait(|waiter| self.poll_largest(waiter)).await } - /// Ready once the track holds a group past `sequence`, or is closed. + /// Ready once the track holds content past `sequence`, or is closed: a later group whose + /// first frame opened or that finished, or a later datagram. A frameless group header + /// does not count, since nothing says the copy reached it yet. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: capability gap pub(crate) fn poll_past(&self, sequence: u64, waiter: &kio::Waiter) -> Poll<()> { - let past = self.state.poll_ref(waiter, |state| match state.max_sequence { - Some(latest) if latest > sequence => Poll::Ready(()), - _ => Poll::Pending, + let Some(next) = sequence.checked_add(1) else { + return Poll::Pending; + }; + let past = self.state.poll_ref(waiter, |state| { + if state.shows(next) { + return Poll::Ready(()); + } + // A group starting wakes no reader parked on the track, so wait on each one past + // it that has yet to start. + let started = state + .lookup + .range(next..) + .filter(|(_, slot)| slot.is_live()) + .any(|(_, slot)| slot.group.poll_started(waiter).is_ready() && !slot.group.is_aborted()); + match started { + true => Poll::Ready(()), + false => Poll::Pending, + } }); past.map(|_| ()) } @@ -8527,11 +8479,11 @@ mod test { } } - /// A route's successor whose header landed but whose first frame never does still - /// starts the wall clock, so a relay ages the group before it as the origin does. + /// A successor whose header landed but whose first frame never does still starts the + /// wall clock, so a relay ages the group before it as the origin does. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_withheld_successor_ages_its_predecessor() { + async fn a_frameless_successor_ages_its_predecessor() { for info in [Info::default(), Info::timed()] { let producer = track_producer("test", info.clone()); let at = info.timescale.map(|_| Timestamp::ZERO); @@ -8545,7 +8497,7 @@ mod test { let woken = Arc::new(std::sync::atomic::AtomicBool::new(false)); let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); assert!(reading.poll_read_frame(&waiter).is_pending()); - let _successor = producer.receive_group(group::Info { sequence: 1 }).unwrap(); + let _successor = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert!( woken.swap(false, Ordering::SeqCst), "{info:?}: the header never woke the read" @@ -8795,12 +8747,11 @@ mod test { producer.set_idle(); open.abort(Error::Cancel).unwrap(); - let mut answer = producer.receive_group(group::Info { sequence: 2 }).unwrap(); + let mut answer = producer.create_group(group::Info { sequence: 2 }).unwrap(); producer.set_live(Some(Position::group(2))); answer .write_frame(Timestamp::from_millis(533).unwrap(), bytes::Bytes::from_static(b"")) .unwrap(); - producer.reveal_group(&answer.handle()); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(400))); assert_eq!(drain(&mut subscriber), vec![2]); @@ -9401,9 +9352,9 @@ mod test { ); } - /// A received group's frames present while it is hidden, so a parked read they wake - /// still sees the older edge and parks again. Revealing the group has to wake it once - /// more, though the read sits below the group's nearest shown predecessor. + /// A group's header lands before its first frame, which moves no edge. The first frame + /// has to wake a parked read it expires, though the read sits below the group's nearest + /// started predecessor. #[test] #[cfg(feature = "async")] fn revealing_a_presented_group_wakes_a_read_it_expires() { @@ -9429,18 +9380,17 @@ mod test { let mut next = std::pin::pin!(held.read_frame()); assert!(next.as_mut().poll(&mut cx).is_pending()); - let mut received = producer.receive_group(group::Info { sequence: 2 }).unwrap(); - received - .write_frame(Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"x")) - .unwrap(); + let mut received = producer.create_group(group::Info { sequence: 2 }).unwrap(); woken.store(false, Ordering::SeqCst); assert!( next.as_mut().poll(&mut cx).is_pending(), - "the hidden group moves no edge" + "the frameless group moves no edge" ); - producer.reveal_group(&received.handle()); - assert!(woken.load(Ordering::SeqCst), "the reveal wakes the expired read"); + received + .write_frame(Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + assert!(woken.load(Ordering::SeqCst), "the first frame wakes the expired read"); let result = next.as_mut().poll(&mut cx); assert!( matches!(result, Poll::Ready(Err(Error::Old))), @@ -9449,70 +9399,63 @@ mod test { } /// A route can declare the end, then land every group's header before its first frame. - /// Those groups are withheld until their frames land, so the end is not reached before - /// they show: a reader ending at the boundary would never see them. + /// Readers reach those groups at once, and the end with them, but nothing counts a + /// frameless group as content: the track shows nothing past the first until it starts. #[test] #[cfg(feature = "async")] - fn a_withheld_group_holds_the_end() { + fn a_frameless_group_does_not_count_as_content() { let mut producer = track_producer("test", crate::track::Info::timed()); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_secs(60))); producer.finish_at(Position::group(2)).unwrap(); let mut received: Vec<_> = (0..2) - .map(|sequence| producer.receive_group(group::Info { sequence }).unwrap()) + .map(|sequence| producer.create_group(group::Info { sequence }).unwrap()) .collect(); - assert!( - subscriber.recv_group().now_or_never().is_none(), - "the end waits for the withheld groups" - ); + let mut first = subscriber.assert_group(); + let mut second = subscriber.assert_group(); + assert_eq!((first.sequence, second.sequence), (0, 1)); + assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); + let waiter = kio::Waiter::noop(); + assert!(producer.poll_past(0, &waiter).is_pending(), "a frameless group is not content"); for group in &mut received { group .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) .unwrap(); - producer.reveal_group(&group.handle()); } - assert_eq!(subscriber.assert_group().sequence, 0); - assert_eq!(subscriber.assert_group().sequence, 1); - assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); + assert!(producer.poll_past(0, &waiter).is_ready(), "its first frame makes it content"); + assert!(first.read_frame().now_or_never().unwrap().unwrap().is_some()); + assert!(second.read_frame().now_or_never().unwrap().unwrap().is_some()); } - /// A withheld group whose stream ends with no frame, cleanly or reset, shows when it - /// ends, which wakes a reader parked on the end. + /// A frameless group whose stream ends with no frame, cleanly or reset, ends its readers + /// with it, and the track's end follows. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_withheld_group_that_ends_empty_releases_the_end() { + async fn a_frameless_group_that_ends_empty_ends_its_readers() { for abort in [false, true] { let mut producer = track_producer("test", None); let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_secs(60))); producer.finish_at(Position::group(1)).unwrap(); - let mut group = producer.receive_group(group::Info { sequence: 0 }).unwrap(); - let handle = group.handle(); + let mut group = producer.create_group(group::Info { sequence: 0 }).unwrap(); + let mut reading = subscriber.assert_group(); + assert_eq!(reading.sequence, 0); - let first = { - let mut next = std::pin::pin!(subscriber.recv_group()); - assert!( - futures::poll!(next.as_mut()).is_pending(), - "the end waits for the group" - ); + let ended = { + let mut next = std::pin::pin!(reading.read_frame()); + assert!(futures::poll!(next.as_mut()).is_pending(), "the group is still open"); match abort { true => group.abort(Error::Cancel).unwrap(), false => group.finish().unwrap(), } - producer.reveal_group(&handle); moq_clock::timeout(Duration::from_secs(1), next) .await - .expect("the reveal wakes the reader") - .unwrap() + .expect("the end wakes the reader") }; - match abort { - // A reset group shows nothing, so the reader ends. - true => assert!(first.is_none()), - false => { - assert_eq!(first.expect("the empty group").sequence, 0); - assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); - } + true => assert!(matches!(ended, Err(Error::Cancel)), "{ended:?}"), + false => assert!(matches!(ended, Ok(None)), "{ended:?}"), } + assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); } } @@ -9811,12 +9754,12 @@ mod test { assert_eq!(drain(&mut sub), vec![1, 2]); } - /// An unstamped immediate successor leaves a group's reach unbounded: a later - /// stamped group proves nothing about where the successor will begin, and - /// shrinking the bound is the unsafe direction. + /// A frameless successor is not content, so the next started group bounds the group + /// before it. That bound is sound: the frameless group's first frame is checked to start + /// at or below the next group's, so the true reach can only be earlier. #[test] #[cfg(feature = "async")] - fn an_unstamped_immediate_successor_leaves_reach_unbounded() { + fn a_frameless_successor_leaves_the_next_started_group_as_the_bound() { let mut producer = track_producer("test", Info::timed()); // Any budget, so only media time judges: the wall clock stands still here. let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(Duration::from_millis(500))); @@ -9826,10 +9769,8 @@ mod test { append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 - // Group 1's reach is group 2's start, a second behind the edge: stale. - // Group 0's reach is unknown until group 1 presents its first frame, so it is - // kept rather than convicted on a bound that could shrink the wrong way. - assert_eq!(drain(&mut subscriber), vec![0, 2, 3]); + // Groups 0 and 1 both reach at most group 2's start, a second behind the edge: stale. + assert_eq!(drain(&mut subscriber), vec![2, 3]); } fn untimed_producer() -> Producer { @@ -10041,23 +9982,21 @@ mod test { assert_eq!(drain_ordered(&mut replay), vec![0, 1, 2, 3]); } - /// A group whose immediate successor has not presented a frame has no proven reach, - /// so nothing says its frames are too old and the ordered cursor keeps it. + /// The ordered cursor judges a group past a frameless successor by the next started one. #[test] #[cfg(feature = "async")] - fn next_group_keeps_a_group_with_no_proven_reach() { + fn next_group_judges_past_a_frameless_successor() { let mut producer = track_producer("test", Info::timed()); append_at(&mut producer, 0); // seq 0 let _writer_1 = producer.append_group().unwrap(); // seq 1 stalls before its first frame append_at(&mut producer, 10_000); // seq 2 append_at(&mut producer, 11_000); // seq 3 - // Group 1 reaches 10s, a second behind the edge: convicted. Group 0 is bounded - // only by group 1, which has yet to say where it begins, and arrived just now. + // Groups 0 and 1 reach at most 10s, a second behind the edge: convicted. let mut subscriber = producer .subscribe(Subscription::default().with_max_delay(Duration::from_millis(500))) .ordered(); - assert_eq!(drain_ordered(&mut subscriber), vec![0, 2, 3]); + assert_eq!(drain_ordered(&mut subscriber), vec![2, 3]); } #[test] @@ -14039,10 +13978,10 @@ mod test { } /// Lowering the floor re-offers only what the arrival walk could have read: a fetched - /// group stays out of arrival order, and a withheld one waits until it is revealed. + /// group stays out of arrival order, while a live one is offered before its first frame. #[moq_clock::test] #[cfg(feature = "async")] - async fn a_lowered_floor_reoffers_neither_fetched_nor_withheld_groups() { + async fn a_lowered_floor_reoffers_live_groups_but_not_fetched_ones() { let (producer, _pool) = pooled_producer(1 << 40); let dynamic = producer.dynamic(); let consumer = producer.consume(); @@ -14062,19 +14001,13 @@ mod test { .unwrap(); fetched.finish().unwrap(); pending.await.unwrap(); - let mut withheld = producer.receive_group(group::Info { sequence: 3 }).unwrap(); + let _frameless = producer.create_group(group::Info { sequence: 3 }).unwrap(); subscriber.update(replay().with_groups(0..)).unwrap(); + assert_eq!(subscriber.assert_group().sequence, 3, "offered before its first frame"); subscriber.assert_no_group(); - withheld - .write_frame(Timestamp::from_millis(3).unwrap(), bytes::Bytes::from_static(b"x")) - .unwrap(); - producer.reveal_group(&withheld.handle()); - assert_eq!(subscriber.assert_group().sequence, 3, "shown once revealed"); - subscriber.assert_no_group(); - - // A cursor floor lowered before the next read counts only shown groups as unread. + // A cursor floor lowered before the next read counts only walked groups as unread. let mut lowered = producer.subscribe(replay()); lowered.start_at(5); assert_eq!(lowered.assert_group().sequence, 5); From ad4caa1b072877c9f3aab20f4e95fd67edf00f00 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:32:32 -0700 Subject: [PATCH 03/22] wip(net)!: own the chunked frame writer and move the frame budget onto the origin handle group::Producer::create_frame now consumes the writer and returns an owned frame::Producer whose finish hands it back; a refused frame aborts the group. The borrowing writer and ProducerOwned go. The allocation budget leaves the call signature: it rides the origin handle into each broadcast's tracks, and built-in sessions give their handle their own. hang and moq-mux write whole frames through write_frame. Co-Authored-By: Claude Opus 5.5 --- quest/m2/perf/ingest-batch.md | 6 +- rs/hang/src/container/frame.rs | 29 +- rs/moq-ffi/src/test.rs | 9 +- rs/moq-mux/src/container/fmp4/export_test.rs | 9 +- rs/moq-mux/src/container/fmp4/import.rs | 7 +- rs/moq-mux/src/container/fmp4/mod.rs | 7 +- rs/moq-mux/src/container/loc/mod.rs | 7 +- rs/moq-net/src/coding/reader.rs | 19 +- rs/moq-net/src/fuzz.rs | 8 +- rs/moq-net/src/ietf/publisher.rs | 8 +- rs/moq-net/src/ietf/subscriber.rs | 22 +- rs/moq-net/src/lite/ietf.rs | 15 +- rs/moq-net/src/lite/publisher.rs | 5 +- rs/moq-net/src/lite/subscriber.rs | 29 +- rs/moq-net/src/model/broadcast.rs | 6 + rs/moq-net/src/model/cache.rs | 31 +- rs/moq-net/src/model/frame.rs | 364 ++++++++----------- rs/moq-net/src/model/group.rs | 139 ++++--- rs/moq-net/src/model/origin.rs | 20 + rs/moq-net/src/model/resume.rs | 63 ++-- rs/moq-net/src/model/track.rs | 35 +- rs/moq-net/src/recv.rs | 24 +- rs/moq-tokio/tests/integration/broadcast.rs | 39 +- 23 files changed, 385 insertions(+), 516 deletions(-) diff --git a/quest/m2/perf/ingest-batch.md b/quest/m2/perf/ingest-batch.md index 3714694ee29..2d7dfd1db53 100644 --- a/quest/m2/perf/ingest-batch.md +++ b/quest/m2/perf/ingest-batch.md @@ -2,7 +2,7 @@ ## Goal -Relay ingest pays two group lock acquisitions (`create_frame_owned`, then +Relay ingest pays two group lock acquisitions (`create_object`, then `frame_commit`), a waiter-list wake, and a clock read for every received frame. A frame's payload chunks are already amortized per poll, but a burst of small whole frames is not. Egress is already amortized (the `Prefetch` @@ -24,7 +24,7 @@ Where the path stands: - The batched machinery exists but is unused here: `group::Producer::write_frames` takes a `frame::Buffer` and pays one lock per batch, while the ingest path (lite's `FrameIngest`, the IETF - subscriber's object loop) creates each frame through `create_frame_owned` + subscriber's object loop) creates each frame through `create_object` instead. The `group_write_frames` bench in `rs/moq-net/benches/group.rs` compares the two as `single` against `batch32`, a `frame::Buffer::<32>` flushed through `write_frames`; take the before number from there. @@ -35,7 +35,7 @@ are already amortized): - Where whole frames are available in one poll turn, feed them through `write_frames`/`frame::Buffer` instead of frame-at-a-time creation. This is the larger half: a small frame that arrives whole still pays a - `create_frame_owned` plus a `frame_commit`, two lock acquisitions where the + `create_object` plus a `frame_commit`, two lock acquisitions where the batch API pays one for the whole burst. - The per-chunk `stats` bumps on the same loop, which `write` still pays individually. diff --git a/rs/hang/src/container/frame.rs b/rs/hang/src/container/frame.rs index e03900bf001..dc5db53fb44 100644 --- a/rs/hang/src/container/frame.rs +++ b/rs/hang/src/container/frame.rs @@ -92,28 +92,19 @@ impl Frame { /// Write the frame to `group` as a single moq-lite frame, in the [`Self::encode`] format. /// - /// Prefer this over [`Self::encode`] when writing to a group: it streams the header and - /// payload as separate chunks rather than copying the payload into one buffer, and stamps - /// the moq-net frame timestamp so moq-lite-05 and later can delta-encode it on the wire - /// independently of the container-level prefix. + /// Prefer this over [`Self::encode`] when writing to a group: it stamps the moq-net frame + /// timestamp so moq-lite-05 and later can delta-encode it on the wire independently of the + /// container-level prefix. pub fn write_to(&self, group: &mut moq_net::group::Producer) -> Result<(), Error> { - let mut header = BytesMut::new(); - self.encode_header(&mut header)?; - let header = header.freeze(); + // The header and payload share one buffer: a frame written in chunks is copied into + // one anyway, so building it here costs the same copy. + let mut buf = BytesMut::with_capacity(8 + self.payload.len()); + self.encode_header(&mut buf)?; + buf.extend_from_slice(&self.payload); - let size = (header.len() + self.payload.len()) as u64; - - // `create_frame` converts the timestamp into the track's timescale; older drafts + // `write_frame` converts the timestamp into the track's timescale; older drafts // simply don't put it on the wire. - let info = moq_net::frame::Info { - size, - timestamp: Some(self.timestamp), - }; - let mut chunked = group.create_frame(info)?; - chunked.write(header)?; - chunked.write(self.payload.clone())?; - chunked.finish()?; - + group.write_frame(self.timestamp, buf.freeze())?; Ok(()) } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 404a497b708..ccd5f21829d 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1833,14 +1833,9 @@ fn write_legacy(group: &mut moq_net::group::Producer, transport_us: u64, media_u } fn write_raw(group: &mut moq_net::group::Producer, transport_us: u64, payload: bytes::Bytes) { - let mut frame = group - .create_frame(moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(moq_net::Timestamp::from_micros(transport_us).unwrap()), - }) + group + .write_frame(moq_net::Timestamp::from_micros(transport_us).unwrap(), payload) .unwrap(); - frame.write(payload).unwrap(); - frame.finish().unwrap(); } /// A broadcast with one legacy-container track, and a raw consumer subscribed to it. diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index e88d2732f66..277f72226a5 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -2190,14 +2190,9 @@ async fn cmaf_source_exports_at_the_frame_timestamp() { let fragment = super::encode_fragment(info, &samples).unwrap(); let mut group = track.append_group().unwrap(); - let mut frame = group - .create_frame(moq_net::frame::Info { - size: fragment.len() as u64, - timestamp: Some(moq_net::Timestamp::from_secs(10).unwrap()), - }) + group + .write_frame(moq_net::Timestamp::from_secs(10).unwrap(), fragment) .unwrap(); - frame.write(fragment).unwrap(); - frame.finish().unwrap(); group.finish().unwrap(); track.finish().unwrap(); diff --git a/rs/moq-mux/src/container/fmp4/import.rs b/rs/moq-mux/src/container/fmp4/import.rs index 8d1d17092d4..4c092ca09b1 100644 --- a/rs/moq-mux/src/container/fmp4/import.rs +++ b/rs/moq-mux/src/container/fmp4/import.rs @@ -1044,12 +1044,7 @@ impl Import { track.estimator.cut(Some(timestamp)); } let fragment_len = fragment_bytes.len(); - let mut frame = g.create_frame(moq_net::frame::Info { - size: fragment_bytes.len() as u64, - timestamp: Some(timestamp), - })?; - frame.write(fragment_bytes)?; - frame.finish()?; + g.write_frame(timestamp, fragment_bytes)?; // Only once published, so a rejected fragment is never indexed. Audio is always // independently decodable; video says whether this fragment really begins on an IDR, diff --git a/rs/moq-mux/src/container/fmp4/mod.rs b/rs/moq-mux/src/container/fmp4/mod.rs index 74d8d5d74ac..c884ec07212 100644 --- a/rs/moq-mux/src/container/fmp4/mod.rs +++ b/rs/moq-mux/src/container/fmp4/mod.rs @@ -572,12 +572,7 @@ fn encode(group: &mut moq_net::group::Producer, frames: &[Frame], info: Fragment let timestamp = Timestamp::new(timestamp_ticks(earliest, info.timescale)?, info.timescale)?; let bytes = encode_fragment(info, frames)?; - let mut writer = group.create_frame(moq_net::frame::Info { - size: bytes.len() as u64, - timestamp: Some(timestamp), - })?; - writer.write(bytes)?; - writer.finish()?; + group.write_frame(timestamp, bytes)?; Ok(()) } diff --git a/rs/moq-mux/src/container/loc/mod.rs b/rs/moq-mux/src/container/loc/mod.rs index b7caabd6786..9b18171c52b 100644 --- a/rs/moq-mux/src/container/loc/mod.rs +++ b/rs/moq-mux/src/container/loc/mod.rs @@ -33,12 +33,7 @@ impl Container for Wire { // Carry the timestamp on the net frame too (converted to the track's // timescale), so a relay sees it without parsing the LOC payload. - let mut chunked = group.create_frame(moq_net::frame::Info { - size: data.len() as u64, - timestamp: Some(frame.timestamp), - })?; - chunked.write(data)?; - chunked.finish()?; + group.write_frame(frame.timestamp, data)?; } Ok(()) } diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index d61f6f411e8..4c8da6624c3 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -211,14 +211,14 @@ impl Reader { /// hands over everything it has already buffered in one turn, and each wake pays a /// group lock and a clock read, so the intermediate ones mostly publish bytes the /// consumer is about to be handed anyway. Pairing the deferred - /// [`frame::ProducerOwned::write`] with its wake is this function's job precisely + /// [`frame::Producer::write_deferred`] with its wake is this function's job precisely /// because it owns the only `Pending` it can return; the other two exits are woken /// by the caller's `finish` (which stamps and publishes the frame) or `abort` (which /// fails the group). [`WAKE_BUDGET`] bounds the wait in between. pub(crate) fn poll_read_frame( &mut self, cx: &mut Context<'_>, - frame: &mut crate::frame::ProducerOwned, + frame: &mut crate::frame::Producer, ) -> Poll> { let mut owed = 0; @@ -236,7 +236,7 @@ impl Reader { } Poll::Ready(Ok(Some(chunk))) if !chunk.is_empty() => { owed += chunk.len(); - if let Err(err) = frame.write(chunk) { + if let Err(err) = frame.write_deferred(chunk) { break Err(err); } if owed >= WAKE_BUDGET { @@ -423,7 +423,7 @@ mod tests { fn parked_frame( size: usize, ) -> ( - crate::frame::ProducerOwned, + crate::frame::Producer, crate::frame::Consumer, kio::Waiter, Arc, @@ -431,13 +431,10 @@ mod tests { let group = crate::group::Info { sequence: 0 }.produce(); let mut consumer = group.consume(); let frame = group - .create_frame_owned( - crate::frame::Info { - size: size as u64, - timestamp: Some(crate::Timestamp::ZERO), - }, - &Default::default(), - ) + .create_frame(crate::frame::Info { + size: size as u64, + timestamp: Some(crate::Timestamp::ZERO), + }) .unwrap(); let payload = consumer.next_frame().now_or_never().unwrap().unwrap().unwrap(); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 29abae75ae5..ed2c9e19ed2 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -54,7 +54,7 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr }, fields, }; - let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + let mut frame = group.create_object(header).unwrap(); frame.write(payload.clone()).unwrap(); group = frame.finish().unwrap(); } @@ -1139,7 +1139,7 @@ pub fn seeds() -> Vec { /// every declared size when the first byte lands and `Some(0)` grows every buffer with /// the bytes received. pub struct FrameRecv { - streams: Vec, frame::ProducerOwned)>>, + streams: Vec, frame::Producer)>>, // Keeps the groups' track alive. _track: track::Producer, _broadcast: broadcast::Producer, @@ -1152,6 +1152,7 @@ impl FrameRecv { // Unbounded, so eviction never aborts a group mid-frame. let mut info = broadcast::Info::new(); info.pool = cache::Pool::unbounded(); + info.frames = budget.map(frame::Budget::new).unwrap_or_default(); let broadcast = info.produce(); let track = broadcast .create_track( @@ -1159,7 +1160,6 @@ impl FrameRecv { crate::track::Info::default().with_timescale(crate::Timescale::MILLI), ) .unwrap(); - let budget = budget.map(frame::Budget::new).unwrap_or_default(); let payload = bytes::Bytes::from(vec![0u8; size]); let streams = (0..streams) @@ -1169,7 +1169,7 @@ impl FrameRecv { size: size as u64, timestamp: Some(crate::Timestamp::ZERO), }; - let frame = group.create_frame_owned(info, &budget).unwrap(); + let frame = group.create_frame(info).unwrap(); let stream = Chunks { payload: payload.clone(), chunk, diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 4e7d6e9ef59..e86bca5c4d3 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -6033,7 +6033,7 @@ mod group_priority_test { crate::track::Info::timed(), ); let mut subscriber = track.subscribe(None); - let mut old = track.append_group().unwrap(); + let old = track.append_group().unwrap(); let mut frame = old .create_frame(frame::Info { timestamp: Some(crate::Timestamp::ZERO), @@ -6067,8 +6067,7 @@ mod group_priority_test { *open = false; drop(open); frame.write(b"b".as_slice()).unwrap(); - frame.finish().unwrap(); - old.finish().unwrap(); + frame.finish().unwrap().finish().unwrap(); assert!( futures::poll!(serving.as_mut()).is_pending(), "the final byte is transport-blocked" @@ -6871,7 +6870,7 @@ mod serve_tests { /// inside it and the group stream waits for object 1. async fn fail_update_mid_flight(version: Version) -> Wire { let h = serve(version); - let mut group = h.track.create_group(group::Info { sequence: 0 }).unwrap(); + let group = h.track.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = group .create_frame(frame::Info { timestamp: Some(timestamp()), @@ -6902,7 +6901,6 @@ mod serve_tests { .expect("the failed update ends the subscription") .ok(); drop(frame); - drop(group); let wire = Wire::read(&h.log, version); let error = wire diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 7adf1b43435..0c20e73ac96 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -754,8 +754,6 @@ pub(super) struct Subscriber { going_away: crate::goaway::GoingAway, // Our grant (MoQ Auth): a subscription it stops covering is cancelled. auth: crate::auth::Handle, - // What this session may allocate up front for objects still arriving. - frames: frame::Budget, // Namespaces the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, } @@ -836,7 +834,8 @@ where Self { runtime, session, - origin, + // Its own frame budget, so a peer's declared sizes crowd out no other session. + origin: origin.with_own_frames(), control, session_origin: peer_hop.unwrap_or(crate::Hop::UNKNOWN), self_origin, @@ -848,7 +847,6 @@ where version, going_away, auth: crate::auth::Handle::new(false), - frames: Default::default(), announces: Default::default(), validity: Default::default(), epoch: None, @@ -4422,7 +4420,6 @@ struct GroupIngest { /// The object being read is one the group started past, so it is read and dropped. dropping: bool, phase: IngestPhase, - budget: frame::Budget, } enum IngestPhase { @@ -4437,7 +4434,7 @@ enum IngestPhase { /// Reading the status of an empty object. Status { timestamp: Option }, /// Streaming the object payload. - Payload { frame: frame::ProducerOwned }, + Payload { frame: frame::Producer }, /// Discarding a dropped object's payload: the bytes of it still to read. Skip { size: usize }, /// An explicit end-of-group or end-of-track status arrived. @@ -4462,7 +4459,6 @@ impl GroupIngest { gap: None, dropping: false, phase: IngestPhase::Delta, - budget: subscriber.frames.clone(), } } } @@ -4843,7 +4839,7 @@ where info: frame::Info { size, timestamp }, fields, }; - let mut frame = producer.create_frame_owned(header, &self.frames)?; + let mut frame = producer.create_object(header)?; if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { let _ = frame.abort(err.clone()); return Err(err); @@ -5629,12 +5625,12 @@ impl GroupIngest { self.phase = IngestPhase::Skip { size }; continue; } - // `create_frame_owned` is the allocation chokepoint: it rejects an - // oversized `size` and allocates up front only within the budget, so - // no pre-check is needed. + // `create_object` is the allocation chokepoint: it rejects an oversized + // `size` and allocates up front only within the origin's budget, so no + // pre-check is needed. let timestamp = object_time(self.timescale, *timestamp)?; let header = self.header(group, frame::Info { size, timestamp })?; - let frame = group.create_frame_owned(header, &self.budget)?; + let frame = group.create_object(header)?; self.phase = IngestPhase::Payload { frame }; } IngestPhase::Status { timestamp } => { @@ -5643,7 +5639,7 @@ impl GroupIngest { if !self.dropping { let timestamp = object_time(self.timescale, *timestamp)?; let header = self.header(group, frame::Info { size: 0, timestamp })?; - let frame = group.create_frame_owned(header, &self.budget)?; + let frame = group.create_object(header)?; group.restore(frame.finish()?); } self.phase = IngestPhase::Delta; diff --git a/rs/moq-net/src/lite/ietf.rs b/rs/moq-net/src/lite/ietf.rs index e52389bb764..869d59458d5 100644 --- a/rs/moq-net/src/lite/ietf.rs +++ b/rs/moq-net/src/lite/ietf.rs @@ -1036,16 +1036,13 @@ mod hop_tests { payload: &[u8], ) -> group::Producer { let mut frame = group - .create_frame_owned( - frame::Header { - info: frame::Info { - size: payload.len() as u64, - timestamp: Some(ts(millis)), - }, - fields: fields.map(Arc::new), + .create_object(frame::Header { + info: frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(millis)), }, - &frame::Budget::default(), - ) + fields: fields.map(Arc::new), + }) .unwrap(); frame.write(Bytes::copy_from_slice(payload)).unwrap(); frame.finish().unwrap() diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 2850cf0f487..93af9f0731d 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4797,7 +4797,7 @@ mod serve_group_test { crate::track::Info::timed(), ); let mut subscriber = track.subscribe(None); - let mut old = track.append_group().unwrap(); + let old = track.append_group().unwrap(); let mut frame = old .create_frame(frame::Info { timestamp: Some(Timestamp::ZERO), @@ -4820,8 +4820,7 @@ mod serve_group_test { *open = false; drop(open); frame.write(b"b".as_slice()).unwrap(); - frame.finish().unwrap(); - old.finish().unwrap(); + frame.finish().unwrap().finish().unwrap(); assert!( futures::poll!(serve.as_mut()).is_pending(), "the final byte is transport-blocked" diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 6b797309267..231ce18ca59 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -84,8 +84,6 @@ pub(super) struct Subscriber { sources: kio::Queue, going_away: crate::goaway::GoingAway, auth: crate::auth::Handle, - /// What this session may allocate up front for frames still arriving. - frames: frame::Budget, /// Broadcasts the peer may have announced at once (`session::Limits::announces`). pub(super) announces: crate::session::Slots, } @@ -110,7 +108,8 @@ impl Subscriber { Self { session: config.session, runtime: config.runtime, - origin: config.origin, + // Its own frame budget, so a peer's declared sizes crowd out no other session. + origin: config.origin.with_own_frames(), recv_bandwidth: config.recv_bandwidth, self_origin, session_origin: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), @@ -123,7 +122,6 @@ impl Subscriber { sources: kio::Queue::new(), going_away: config.going_away, auth: config.auth, - frames: Default::default(), announces: Default::default(), } } @@ -1003,7 +1001,6 @@ struct FrameIngest { /// zigzag-delta decode. The first frame's delta is absolute (prev = 0). prev_ts: u64, phase: IngestPhase, - budget: frame::Budget, version: Version, /// Where the stream's frames start, the first Object ID until a record names it. frame_start: u64, @@ -1044,7 +1041,7 @@ enum IngestPhase { /// where there is no timing prefix to act as the sentinel). Size { timestamp: Option }, /// Streaming the frame payload. - Payload { frame: frame::ProducerOwned }, + Payload { frame: frame::Producer }, } impl FrameIngest { @@ -1062,7 +1059,6 @@ impl FrameIngest { true => IngestPhase::State, false => IngestPhase::Timing, }, - budget: subscriber.frames.clone(), version: subscriber.version, frame_start, records: None, @@ -1207,17 +1203,14 @@ impl FrameIngest { } None => None, }; - // `create_frame_owned` is the allocation chokepoint: it rejects an - // oversized `size` and allocates up front only within the budget, so - // no pre-check is needed. No wire timestamp (pre-lite-05) means an - // untimed frame. - let frame = group.create_frame_owned( - frame::Header { - info: frame::Info { size, timestamp }, - fields, - }, - &self.budget, - )?; + // `create_object` is the allocation chokepoint: it rejects an oversized + // `size` and allocates up front only within the origin's budget, so no + // pre-check is needed. No wire timestamp (pre-lite-05) means an untimed + // frame. + let frame = group.create_object(frame::Header { + info: frame::Info { size, timestamp }, + fields, + })?; self.phase = IngestPhase::Payload { frame }; } IngestPhase::Payload { frame } => { diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index f21764656c2..89050369597 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -56,6 +56,11 @@ pub struct Info { /// Stamped on every [`Consumer`] an origin resolves, like [`Self::path`]. `None` for a /// route without an epoch and for a handle not resolved through an origin. pub epoch: Option, + + // What the frames this broadcast's groups are still receiving may allocate up front, + // inherited from the origin handle that created it. + // private: tuning + pub(crate) frames: super::frame::Budget, } impl Default for Info { @@ -65,6 +70,7 @@ impl Default for Info { cache_duration: std::time::Duration::MAX, path: crate::PathOwned::default(), epoch: None, + frames: Default::default(), } } } diff --git a/rs/moq-net/src/model/cache.rs b/rs/moq-net/src/model/cache.rs index 13d42ee35c8..f4448b890d6 100644 --- a/rs/moq-net/src/model/cache.rs +++ b/rs/moq-net/src/model/cache.rs @@ -699,6 +699,10 @@ pub(super) struct Track { // Here rather than on the track state so a frame write advances it without the track // lock, and wakes only the readers following it. largest: kio::Shared, + + // What the frames this track's groups are still receiving may allocate up front, + // shared with every track minted from the same origin handle. + frames: super::frame::Budget, } /// The greatest location a track has written or its source reported, followed by the track @@ -785,10 +789,12 @@ impl Track { next } - /// Open an account against `pool` for the track behind `state`. - pub(super) fn new(pool: Pool, state: kio::Weak) -> Arc { + /// Open an account against `pool` for the track behind `state`, its frames + /// allocating up front within `frames`. + pub(super) fn new(pool: Pool, frames: super::frame::Budget, state: kio::Weak) -> Arc { let track = Arc::new(Self { pool, + frames, written: AtomicU64::new(0), next_expiry: AtomicU64::new(0), expiry_cursor: AtomicUsize::new(0), @@ -809,6 +815,11 @@ impl Track { &self.pool } + /// What this track's frames may allocate up front. + pub(super) fn frames(&self) -> &super::frame::Budget { + &self.frames + } + /// The track holding this account's groups, while it is still open. pub(super) fn track(&self) -> Option> { self.state.upgrade() @@ -1205,7 +1216,7 @@ mod test { fn charge(pool: &Pool) -> Charge { // No track behind the account: nothing here settles debt, it just accounts. - Track::new(pool.clone(), kio::Weak::new()).charge() + Track::new(pool.clone(), Default::default(), kio::Weak::new()).charge() } fn bounded(capacity: u64) -> Pool { @@ -1233,7 +1244,7 @@ mod test { #[test] fn wall_deadlines_wake_the_driver_and_then_the_read() { let pool = Pool::unbounded(); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); let now = super::super::clock::wall(); let at = now + Duration::from_secs(1); let (read, reading) = flag(); @@ -1265,7 +1276,7 @@ mod test { let pool = Pool::unbounded(); let now = super::super::clock::wall(); pool.gc(now, &kio::Waiter::noop()); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); let (_read, reading) = flag(); track.watch_wall(now + Duration::from_secs(2), &reading); track.watch_wall(now + Duration::from_secs(1), &reading); @@ -1382,7 +1393,7 @@ mod test { #[test] fn charge_counts_gross_writes() { - let track = Track::new(bounded(1000), kio::Weak::new()); + let track = Track::new(bounded(1000), Default::default(), kio::Weak::new()); let mut c = track.charge(); c.add(100); assert_eq!(track.take_written(), ENTRY_OVERHEAD + 100); @@ -1464,7 +1475,7 @@ mod test { #[test] fn expiry_gate_reuses_a_supplied_tick() { let pool = Pool::new(Config::default().with_expiry(Duration::from_secs(1))); - let track = Track::new(pool, kio::Weak::new()); + let track = Track::new(pool, Default::default(), kio::Weak::new()); // A supplied tick drives the gate on its own: claimed immediately, closed // until the interval elapses, claimable again on the tick it reopens. assert!(track.expiry_due(Some(0))); @@ -1487,7 +1498,7 @@ mod test { let pool = bounded(1000); assert!(pool.inner.tracks.lock().is_empty()); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); assert_eq!(pool.inner.tracks.lock().len(), 1); // A registered account whose track is already gone is swept harmlessly. @@ -1501,7 +1512,7 @@ mod test { fn an_inert_pool_registers_nothing() { // No window means no sweep, so a bare pool pays no registry cost. let pool = Pool::unbounded(); - let track = Track::new(pool.clone(), kio::Weak::new()); + let track = Track::new(pool.clone(), Default::default(), kio::Weak::new()); assert!(pool.inner.tracks.lock().is_empty()); pool.sweep(); drop(track); @@ -1510,7 +1521,7 @@ mod test { #[test] fn expiry_gate_stays_closed_without_a_window() { // No window means no time gate, and no clock read to reach it. - let track = Track::new(Pool::unbounded(), kio::Weak::new()); + let track = Track::new(Pool::unbounded(), Default::default(), kio::Weak::new()); assert!(!track.expiry_due(None)); assert!(!track.expiry_due(Some(u64::MAX))); } diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 0846c7ff098..bf0301534b9 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -160,34 +160,49 @@ impl Buffer { } } -/// Bytes one session may allocate up front for the frames it is still receiving. +/// Bytes the frames still being written through one origin handle may allocate up front. /// -/// A peer declares each frame's size before sending it, and allocating that size up -/// front saves a reallocation and copy per doubling as the payload arrives. The -/// declaration costs the peer nothing, though, so without a bound it could commit up to +/// A writer declares each frame's size before sending it, and allocating that size up +/// front saves a reallocation and copy per doubling as the payload arrives. A peer's +/// declaration costs it nothing, though, so without a bound it could commit up to /// [`group::MAX_CACHE_BYTES`] per stream without sending a byte. A frame whose declared /// size fits what remains is allocated up front; past that, its buffer grows with the /// bytes received. Each frame returns its share once it completes or aborts. -#[derive(Clone)] -#[cfg_attr(not(feature = "async"), allow(dead_code))] -// pending: /quest/m1/public-model/ingest.md -pub(crate) struct Budget(Arc); +/// +/// Every broadcast, track, and group minted from an [`crate::origin::Producer`] handle shares +/// its budget. The built-in sessions each ingest through a handle with its own. +#[derive(Clone, Default)] +// private: tuning +pub(crate) struct Budget(Arc); + +struct Remaining(AtomicUsize); + +impl Default for Remaining { + fn default() -> Self { + Self(AtomicUsize::new(Budget::DEFAULT)) + } +} + +impl std::fmt::Debug for Budget { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_tuple("Budget").field(&self.0.0.load(Ordering::Relaxed)).finish() + } +} impl Budget { /// Enough for a handful of large keyframes in flight at once. - #[cfg_attr(not(feature = "async"), allow(dead_code))] const DEFAULT: usize = 16 * 1024 * 1024; - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + /// A budget of `bytes`, for a benchmark sweeping it. + #[cfg(any(test, feature = "fuzz"))] pub(crate) fn new(bytes: usize) -> Self { - Self(Arc::new(AtomicUsize::new(bytes))) + Self(Arc::new(Remaining(AtomicUsize::new(bytes)))) } /// Take `size` bytes of the budget, or `None` if that is more than remains. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) fn reserve(&self, size: usize) -> Option { self.0 + .0 .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |left| left.checked_sub(size)) .ok()?; Some(Reservation { @@ -197,14 +212,7 @@ impl Budget { } } -impl Default for Budget { - fn default() -> Self { - Self::new(Self::DEFAULT) - } -} - /// A frame's share of a [`Budget`], returned on drop. -#[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) struct Reservation { budget: Budget, size: usize, @@ -212,7 +220,7 @@ pub(super) struct Reservation { impl Drop for Reservation { fn drop(&mut self) { - self.budget.0.fetch_add(self.size, Ordering::Relaxed); + self.budget.0.0.fetch_add(self.size, Ordering::Relaxed); } } @@ -222,7 +230,7 @@ impl Drop for Reservation { /// A whole-frame [`Bytes`] write is stored directly. Chunked writes are copied into a /// heap [`Segment`], either sized to the declared frame up front or grown as bytes /// arrive (see [`Budget`]). The producer writes through the raw pointer (sole writer, -/// guaranteed by the exclusive borrow of the parent group); `written` provides +/// guaranteed by the frame owning the group's only writer); `written` provides /// happens-before for cross-thread reads. #[derive(Clone)] pub(super) struct FrameBuf(Arc); @@ -308,7 +316,6 @@ impl FrameBuf { } /// A buffer for a frame of `size` bytes that allocates only as bytes arrive. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub(super) fn growing(size: usize) -> Self { Self::with_growth(size, true) } @@ -353,8 +360,8 @@ impl FrameBuf { /// Append `src` at the current write offset and publish it. /// /// Safety relies on the single-producer invariant: only one [`Producer`] exists for - /// a frame (it holds the exclusive borrow of the parent group), so this is the sole - /// writer even though it takes `&self`. + /// a frame (it owns the group's only writer), so this is the sole writer even though + /// it takes `&self`. fn append(&self, src: &[u8]) { if src.is_empty() { return; @@ -428,232 +435,88 @@ impl FrameBuf { } } -/// The writer behind [`Producer`] and [`ProducerOwned`], generic over how it -/// reaches the parent group (an exclusive borrow, or an owned clone). -struct Raw> { - group: Option, +/// Writes the payload of a group's single in-flight frame in one or more chunks. +/// +/// Created by [`group::Producer::create_frame`], which hands it the group's writer: no +/// other frame can be opened, and the group cannot finish, until [`Self::finish`] returns +/// the writer. Owned rather than borrowed, so a driver can hold it across polls while +/// the payload streams in. [`Self::group`] still reads the group meanwhile. +/// +/// The total bytes written must exactly match [`Info::size`]; call [`Self::finish`] to +/// commit the frame (or [`Self::abort`] to fail it). Dropping it without either aborts +/// the group, since an unfinished frame leaves the group's stream broken. +/// +/// A single whole-frame [`write`](Self::write) keeps the caller's allocation +/// (zero-copy); chunked writes copy into one buffer sized to the declared frame, or +/// grown as bytes arrive once the declared sizes in flight pass the origin's budget. +pub struct Producer { + group: Option, buf: FrameBuf, info: Info, // Set once the frame is committed (finished) or aborted, so Drop is a no-op. done: bool, - // An owned receive frame carries its handler's cancellation cleanup across polls. + // A receive handler's cancellation cleanup, carried across polls. cancel_on_drop: bool, // Ingress payload meter, inherited from the parent group. Counts each written // chunk's bytes. Empty (no-op) for an untagged group. stats: stats::Meter, + // The frame's share of the origin's [`Budget`], if it got one, held until it ends. + _reserved: Option, } -impl> Raw { - fn remaining(&self) -> usize { - self.buf.size() - self.buf.written(Ordering::Acquire) - } - - fn write(&mut self, chunk: B) -> Result<()> { - let len = chunk.as_ref().len(); - if len > self.remaining() { - return Err(Error::WrongSize); - } - // Ingress payload: count the chunk's bytes as they're written. - self.stats.bytes(len as u64); - // Fast path: a single whole-frame write keeps the caller's allocation. - if len == self.buf.size() && self.buf.written(Ordering::Acquire) == 0 { - match self.buf.try_set_bytes(chunk.into_bytes()) { - Ok(()) => { - let size = self.buf.size(); - // Safety: `try_set_bytes` checked the buffer exactly matches the declared - // size, so publishing all bytes is in bounds. - unsafe { self.buf.store_written(size) }; - } - Err(chunk) => self.buf.append(&chunk), - } - } else { - self.buf.append(chunk.as_ref()); - } - Ok(()) - } - - fn finish(&mut self) -> Result<()> { - if self.buf.written(Ordering::Acquire) != self.buf.size() { - return Err(Error::WrongSize); - } - let payload = self.buf.freeze(); - self.group - .as_mut() - .expect("frame owns its group") - .borrow_mut() - .frame_commit(Frame { - timestamp: self.info.timestamp, - payload, - })?; - self.done = true; - Ok(()) - } - - fn abort(&mut self, err: Error) -> Result<()> { - self.group - .as_mut() - .expect("frame owns its group") - .borrow_mut() - .frame_abort(err); - self.done = true; - Ok(()) - } -} - -impl> Drop for Raw { - fn drop(&mut self) { - if !self.done { - // An unfinished frame leaves the group stream broken; fail the group so - // consumers surface an error instead of hanging on the partial forever. - // A group already aborted (superseded, evicted, cancelled) carries its own - // reason, so cutting its in-flight frame short is expected. - let Some(group) = self.group.as_mut() else { - return; - }; - let group = group.borrow_mut(); - if !group.is_aborted() && !self.cancel_on_drop { - tracing::warn!( - group = group.info().sequence, - "frame::Producer dropped before writing all bytes" - ); - } - group.frame_abort(if self.cancel_on_drop { - Error::Cancel - } else { - Error::Dropped - }); - } - } -} - -/// Writes the payload of the single in-flight frame in one or more chunks. -/// -/// Borrows the parent [`group::Producer`] exclusively, so no other frame can be -/// opened while this one is live. The total bytes written must exactly match -/// [`Info::size`]; call [`Self::finish`] to commit the frame (or [`Self::abort`] to -/// fail it). Dropping without either aborts the group, since an unfinished frame -/// leaves the group's stream broken. -/// -/// A single whole-frame [`write`](Self::write) keeps the caller's allocation -/// (zero-copy); chunked writes copy into one buffer sized to the declared frame. -pub struct Producer<'a>(Raw<&'a mut group::Producer>); - -impl std::ops::Deref for Producer<'_> { +impl std::ops::Deref for Producer { type Target = Info; fn deref(&self) -> &Self::Target { - &self.0.info + &self.info } } -impl<'a> Producer<'a> { - pub(super) fn new(group: &'a mut group::Producer, buf: FrameBuf, info: Info) -> Self { - Self(Raw { +impl Producer { + pub(super) fn new(group: group::Producer, buf: FrameBuf, info: Info, reserved: Option) -> Self { + Self { group: Some(group), buf, info, done: false, cancel_on_drop: false, stats: stats::Meter::default(), - }) + _reserved: reserved, + } } /// Attach the parent group's ingress meter, so written chunks bump `bytes`. pub(super) fn with_meter(mut self, meter: stats::Meter) -> Self { - self.0.stats = meter; + self.stats = meter; self } - /// The parent group this frame belongs to. - pub fn group(&self) -> group::Info { - self.0.group.as_ref().expect("frame owns its group").info() - } - - /// Bytes still needed to complete the frame. - pub fn remaining(&self) -> usize { - self.0.remaining() - } - - /// Write a chunk of data to the frame. - /// - /// Returns [`Error::WrongSize`] if the chunk would exceed the remaining bytes. - pub fn write(&mut self, chunk: B) -> Result<()> { - self.0.write(chunk)?; - self.0.group.as_mut().expect("frame owns its group").frame_notify(); - Ok(()) - } - - /// Commit the frame, verifying that all bytes were written. - /// - /// Returns [`Error::WrongSize`] if the bytes written don't match [`Info::size`]. - pub fn finish(mut self) -> Result<()> { - self.0.finish() - } - - /// Abort the frame (and its group) with the given error. - pub fn abort(mut self, err: Error) -> Result<()> { - self.0.abort(err) - } -} - -/// The owned counterpart of [`Producer`], for the wire drivers that stream a -/// frame across polls and cannot hold the group borrowed inside their state. -/// -/// Owns the only group writer until the frame finishes and returns it, so another -/// frame or a group finish cannot race this frame. -/// -/// Holds the frame's share of the session's [`Budget`], if it got one, until then. -#[cfg_attr(not(feature = "async"), allow(dead_code))] -// pending: /quest/m1/public-model/ingest.md -pub(crate) struct ProducerOwned { - raw: Raw, - _reserved: Option, -} - -impl std::ops::Deref for ProducerOwned { - type Target = Info; - - fn deref(&self) -> &Self::Target { - &self.raw.info - } -} - -impl ProducerOwned { /// Transfer a receive handler's cancellation cleanup into its in-flight frame. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: capability gap - // Public drivers still borrow frames; the owned public writer belongs to ingest. + // A dropped receive handler cannot name its error; a public driver aborts explicitly. pub(crate) fn cancel_on_drop(mut self) -> Self { - self.raw.cancel_on_drop = true; + self.cancel_on_drop = true; self } - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub(super) fn new(group: group::Producer, buf: FrameBuf, info: Info, reserved: Option) -> Self { - Self { - raw: Raw { - group: Some(group), - buf, - info, - done: false, - cancel_on_drop: false, - stats: stats::Meter::default(), - }, - _reserved: reserved, - } - } - - /// Attach the parent group's ingress meter, so written chunks bump `bytes`. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub(super) fn with_meter(mut self, meter: stats::Meter) -> Self { - self.raw.stats = meter; - self + /// The group this frame belongs to, readable while the frame holds its writer. + pub fn group(&self) -> &group::Producer { + self.group.as_ref().expect("frame owns its group") } /// Bytes still needed to complete the frame. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub fn remaining(&self) -> usize { - self.raw.remaining() + self.buf.size() - self.buf.written(Ordering::Acquire) + } + + /// Write a chunk of data to the frame, waking its readers. + /// + /// Returns [`Error::WrongSize`] if the chunk would exceed the remaining bytes. + pub fn write(&mut self, chunk: B) -> Result<()> { + self.write_deferred(chunk)?; + self.notify(); + Ok(()) } /// Write a chunk of payload *without* waking consumers; pair it with [`Self::notify`]. @@ -666,34 +529,93 @@ impl ProducerOwned { /// `coding::Reader::poll_read_frame` owns the pairing and is the only caller. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: tuning - pub(crate) fn write(&mut self, chunk: B) -> Result<()> { - self.raw.write(chunk) + pub(crate) fn write_deferred(&mut self, chunk: B) -> Result<()> { + let len = chunk.as_ref().len(); + if len > self.remaining() { + return Err(Error::WrongSize); + } + // Ingress payload: count the chunk's bytes as they're written. + self.stats.bytes(len as u64); + // Fast path: a single whole-frame write keeps the caller's allocation. + if len == self.buf.size() && self.buf.written(Ordering::Acquire) == 0 { + match self.buf.try_set_bytes(chunk.into_bytes()) { + Ok(()) => { + let size = self.buf.size(); + // Safety: `try_set_bytes` checked the buffer exactly matches the declared + // size, so publishing all bytes is in bounds. + unsafe { self.buf.store_written(size) }; + } + Err(chunk) => self.buf.append(&chunk), + } + } else { + self.buf.append(chunk.as_ref()); + } + Ok(()) } /// Publish what has been written so far, waking consumers parked on the group. #[cfg_attr(not(feature = "async"), allow(dead_code))] // private: tuning pub(crate) fn notify(&self) { - self.raw.group.as_ref().expect("frame owns its group").frame_notify(); + self.group().frame_notify(); } - /// Commit the frame, verifying that all bytes were written. - #[cfg_attr(not(feature = "async"), allow(dead_code))] + /// Commit the frame, verifying that all bytes were written, and return the group's + /// writer for its next frame or its finish. + /// + /// Returns [`Error::WrongSize`] if the bytes written don't match [`Info::size`]. pub fn finish(mut self) -> Result { - self.raw.finish()?; - Ok(self.raw.group.take().expect("frame owns its group")) + if self.buf.written(Ordering::Acquire) != self.buf.size() { + return Err(Error::WrongSize); + } + let payload = self.buf.freeze(); + let mut group = self.group.take().expect("frame owns its group"); + let committed = group.frame_commit(Frame { + timestamp: self.info.timestamp, + payload, + }); + self.done = true; + committed?; + Ok(group) } /// Abort the frame (and its group) with the given error. - #[cfg_attr(not(feature = "async"), allow(dead_code))] pub fn abort(mut self, err: Error) -> Result<()> { - self.raw.abort(err) + self.group.as_mut().expect("frame owns its group").frame_abort(err); + self.done = true; + Ok(()) } /// Heap bytes the frame's buffer currently holds for the payload. #[cfg(test)] pub(super) fn allocated(&self) -> usize { - self.raw.buf.allocated() + self.buf.allocated() + } +} + +impl Drop for Producer { + fn drop(&mut self) { + if self.done { + return; + } + // An unfinished frame leaves the group stream broken; fail the group so + // consumers surface an error instead of hanging on the partial forever. + // A group already aborted (superseded, evicted, cancelled) carries its own + // reason, so cutting its in-flight frame short is expected. + let Some(group) = self.group.as_mut() else { + return; + }; + if !group.is_aborted() && !self.cancel_on_drop { + tracing::warn!( + group = group.info().sequence, + "frame::Producer dropped before writing all bytes" + ); + } + group.frame_abort(if self.cancel_on_drop { + Error::Cancel + } else { + Error::Dropped + }); } } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 15b03de3f11..001703b5e2b 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1056,37 +1056,30 @@ impl Producer { } /// Create a frame with an upfront size and presentation timestamp, streamed in - /// chunks. Borrows the group exclusively until the returned [`frame::Producer`] - /// is finished or dropped, so only one frame is open at a time. + /// chunks. The returned [`frame::Producer`] takes this writer, so only one frame is + /// open at a time; its [`finish`](frame::Producer::finish) hands the writer back. + /// Use [`Self::write_frame`] for a frame already in one buffer. /// /// The `timestamp` is converted into the parent track's timescale, so the scale you - /// build it with doesn't have to match the track. Returns [`Error::FrameTooLarge`] - /// if the declared size exceeds the group's byte budget (refused before allocating) - /// or [`Error::TimestampMismatch`] if the timestamp can't be converted (overflow). - pub fn create_frame(&mut self, frame: frame::Info) -> Result> { - // The buffer allocates on its first write, so refusing the frame costs nothing. - let buf = FrameBuf::new(frame.size as usize); - let info = self.open_frame(frame.into(), &buf)?; - let meter = self.stats.clone(); - Ok(frame::Producer::new(self, buf, info).with_meter(meter)) + /// build it with doesn't have to match the track. A frame the group cannot take + /// aborts the group with the error: [`Error::FrameTooLarge`] if the declared size + /// exceeds the group's byte budget (refused before allocating), + /// [`Error::TimestampMismatch`] if the timestamp can't be converted, or + /// [`Error::Closed`] once the group finished. + /// + /// The declared size is allocated up front while the frames in flight through the + /// origin handle fit its budget, and grows with the bytes written past that, so a + /// peer's declaration cannot commit memory it never sends. + pub fn create_frame(self, frame: frame::Info) -> Result { + self.create_object(frame.into()) } - /// The owned counterpart of [`Self::create_frame`], for the wire drivers that - /// stream a frame across polls and cannot hold the group borrowed inside their - /// state. The frame owns the only writer until its finish returns it. - /// - /// The declared size is the peer's claim, so the buffer is allocated up front only - /// while it fits the session's `budget`; otherwise it grows with the bytes received. + /// [`Self::create_frame`] with the moq-transport object fields a relay forwards. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn create_frame_owned( - mut self, - frame: impl Into, - budget: &frame::Budget, - ) -> Result { - let frame = frame.into(); + // private: passthrough + pub(crate) fn create_object(mut self, frame: frame::Header) -> Result { let size = frame.info.size as usize; - let reserved = budget.reserve(size); + let reserved = self.handle.cache.frames().reserve(size); let buf = match reserved { Some(_) => FrameBuf::new(size), None => FrameBuf::growing(size), @@ -1099,7 +1092,7 @@ impl Producer { } }; let meter = self.stats.clone(); - Ok(frame::ProducerOwned::new(self, buf, info, reserved).with_meter(meter)) + Ok(frame::Producer::new(self, buf, info, reserved).with_meter(meter)) } /// Open `buf` as the in-flight frame, returning its header in the track's timescale. @@ -2734,7 +2727,7 @@ mod test { #[cfg(feature = "async")] fn object_fields_follow_their_frames_through_every_read() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::default(), cache); group.write_frame(None, Bytes::from_static(b"p")).unwrap(); let plain = pool.used(); @@ -2750,7 +2743,7 @@ mod test { properties: Default::default(), })), }; - let mut frame = group.create_frame_owned(header, &frame::Budget::default()).unwrap(); + let mut frame = group.create_object(header).unwrap(); frame.write(Bytes::from_static(b"f")).unwrap(); group = frame.finish().unwrap(); } @@ -2802,7 +2795,7 @@ mod test { #[cfg(feature = "async")] fn terminal_metadata_stays_charged_after_frames_are_released() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::default(), cache); group.write_frame(None, Bytes::from_static(b"payload")).unwrap(); let fields = super::super::object::Fields { @@ -2866,7 +2859,7 @@ mod test { fn frame_capacity_growth_is_charged_and_released() { for mode in 0..3 { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut group = Producer::new(Info::from(0u64), track::Info::timed(), cache); for _ in 0..FRAME_SLOTS { group.write_frame(Timestamp::ZERO, bytes::Bytes::new()).unwrap(); @@ -2891,7 +2884,7 @@ mod test { timestamp: Some(Timestamp::ZERO), }) .unwrap(); - frame.finish().unwrap(); + group = frame.finish().unwrap(); } } let capacity = group.handle.state.read().frames.capacity(); @@ -3022,18 +3015,16 @@ mod test { #[test] #[cfg(feature = "async")] fn chunked_frame_reads_whole() { - let mut producer = Info { sequence: 0 }.produce(); - { - let mut frame = producer - .create_frame(frame::Info { - size: 10, - timestamp: Some(Timestamp::ZERO), - }) - .unwrap(); - frame.write(Bytes::from_static(b"hello")).unwrap(); - frame.write(Bytes::from_static(b"world")).unwrap(); - frame.finish().unwrap(); - } + let producer = Info { sequence: 0 }.produce(); + let mut frame = producer + .create_frame(frame::Info { + size: 10, + timestamp: Some(Timestamp::ZERO), + }) + .unwrap(); + frame.write(Bytes::from_static(b"hello")).unwrap(); + frame.write(Bytes::from_static(b"world")).unwrap(); + let mut producer = frame.finish().unwrap(); producer.finish().unwrap(); // Frame data is held in a single per-frame buffer; a whole-frame read returns @@ -3046,7 +3037,7 @@ mod test { #[test] #[cfg(feature = "async")] fn chunked_frame_streams_partial() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let mut consumer = producer.consume(); let mut frame = producer @@ -3064,7 +3055,7 @@ mod test { assert!(f.read_chunk().now_or_never().is_none()); frame.write(Bytes::from_static(b"bar")).unwrap(); - frame.finish().unwrap(); + let _producer = frame.finish().unwrap(); let c2 = f.read_chunk().now_or_never().unwrap().unwrap(); assert_eq!(c2, Some(Bytes::from_static(b"bar"))); @@ -3168,7 +3159,7 @@ mod test { (Error::GroupTooLarge, false), ] { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); producer.write_frame(None, Bytes::from_static(b"b")).unwrap(); @@ -3195,7 +3186,7 @@ mod test { #[test] fn a_held_head_expires_with_the_pool_window() { let pool = cache::Pool::new(cache::Config::default().with_expiry(std::time::Duration::from_secs(1))); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); @@ -3215,7 +3206,7 @@ mod test { fn the_held_registry_follows_the_heads_held() { const BURST: usize = 64; let pool = cache::Pool::new(cache::Config::default().with_expiry(std::time::Duration::from_secs(1))); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let fail = |sequence: u64| { let mut producer = Producer::new(Info::from(sequence), track::Info::default(), cache.clone()); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); @@ -3243,7 +3234,7 @@ mod test { #[test] fn a_full_pool_holds_no_head() { let pool = cache::Pool::new(cache::Config::default().with_capacity(1)); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut producer = Producer::new(Info::from(0u64), track::Info::default(), cache); producer.write_frame(None, Bytes::from_static(b"a")).unwrap(); let handoff = producer.consume().handoff(); @@ -3257,7 +3248,7 @@ mod test { #[test] fn an_open_frame_reserves_its_remainder_from_adoption() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool, kio::Weak::new()); + let cache = cache::Track::new(pool, Default::default(), kio::Weak::new()); let mut tail = Producer::new(Info::from(0u64), track::Info::default(), cache); tail.start_at(1).unwrap(); let adopter = tail.handle(); @@ -3321,7 +3312,7 @@ mod test { }; for wired_first in [true, false] { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let mut tail = Producer::new(Info::from(0u64), track::Info::default(), cache); tail.start_at(2).unwrap(); if wired_first { @@ -3536,7 +3527,7 @@ mod test { #[cfg(feature = "async")] fn prefetched_consumer(pool: &cache::Pool, max_age: std::time::Duration) -> (Producer, Consumer) { - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let track = track::Info::timed().with_max_age(max_age); let mut producer = Producer::new(Info { sequence: 0 }, track, cache); producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); @@ -3783,7 +3774,7 @@ mod test { #[moq_clock::test] #[cfg(feature = "async")] async fn chunk_write_wakes_parked_reader() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let mut consumer = producer.consume(); let mut frame = producer .create_frame(frame::Info { @@ -3810,7 +3801,7 @@ mod test { fn create_frame_converts_mismatched_scale() { use crate::{Timescale, Timestamp}; - let mut producer = Producer::new( + let producer = Producer::new( Info { sequence: 0 }, track::Info::default().with_timescale(Timescale::MICRO), Default::default(), @@ -3829,7 +3820,7 @@ mod test { fn create_frame_converts_current_timestamp() { use crate::Timescale; - let mut producer = Producer::new( + let producer = Producer::new( Info { sequence: 0 }, track::Info::default().with_timescale(Timescale::MICRO), Default::default(), @@ -4006,7 +3997,7 @@ mod test { /// The per-frame size cap (the group byte budget) is enforced before allocating. #[test] fn create_frame_rejects_oversized() { - let mut producer = Info { sequence: 0 }.produce(); + let producer = Info { sequence: 0 }.produce(); let result = producer.create_frame(frame::Info { size: MAX_CACHE_BYTES + 1, timestamp: Some(Timestamp::ZERO), @@ -4027,17 +4018,17 @@ mod test { #[test] fn frame_is_charged_as_written() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); let observing = producer.handle(); let mut frame = producer - .create_frame_owned(sized(MAX_CACHE_BYTES), &frame::Budget::default()) + .create_frame(sized(MAX_CACHE_BYTES)) .unwrap(); assert_eq!(pool.used(), before, "the declared size was charged"); - frame.write(Bytes::from(vec![0u8; 100])).unwrap(); + frame.write_deferred(Bytes::from(vec![0u8; 100])).unwrap(); assert_eq!(pool.used(), before, "charged before the write was published"); frame.notify(); assert_eq!(pool.used(), before + 100); @@ -4052,11 +4043,11 @@ mod test { } #[test] - fn refused_owned_frame_aborts_with_its_error() { + fn refused_frame_aborts_with_its_error() { let producer = Info { sequence: 0 }.produce(); let handle = producer.handle(); assert!(matches!( - producer.create_frame_owned(sized(MAX_CACHE_BYTES + 1), &frame::Budget::default()), + producer.create_frame(sized(MAX_CACHE_BYTES + 1)), Err(Error::FrameTooLarge) )); assert!(matches!( @@ -4069,36 +4060,40 @@ mod test { #[test] fn frame_commit_charges_the_tail() { let pool = cache::Pool::unbounded(); - let cache = cache::Track::new(pool.clone(), kio::Weak::new()); + let cache = cache::Track::new(pool.clone(), Default::default(), kio::Weak::new()); let producer = Producer::new(Info { sequence: 0 }, track::Info::timed(), cache); let before = pool.used(); let observing = producer.handle(); let mut frame = producer - .create_frame_owned(sized(300), &frame::Budget::default()) + .create_frame(sized(300)) .unwrap(); frame.write(Bytes::from(vec![0u8; 100])).unwrap(); - frame.notify(); - frame.write(Bytes::from(vec![0u8; 200])).unwrap(); + frame.write_deferred(Bytes::from(vec![0u8; 200])).unwrap(); let _producer = frame.finish().unwrap(); assert_eq!(pool.used(), before + 300); assert_eq!(observing.state.read().cache, 300); } - /// Frames within the session's budget allocate their declared size up front; past + /// Frames within their origin's budget allocate their declared size up front; past /// it, a frame's buffer holds only what has arrived. A frame hands its share back /// once it ends. #[test] fn frame_budget_bounds_upfront_allocation() { let budget = frame::Budget::new(1024); - let a = Info { sequence: 0 }.produce(); - let b = Info { sequence: 1 }.produce(); + let pool = cache::Pool::unbounded(); + let group = |sequence| { + let cache = cache::Track::new(pool.clone(), budget.clone(), kio::Weak::new()); + Producer::new(Info { sequence }, track::Info::timed(), cache) + }; + let a = group(0); + let b = group(1); - let mut first = a.create_frame_owned(sized(1024), &budget).unwrap(); + let mut first = a.create_frame(sized(1024)).unwrap(); first.write(Bytes::from_static(b"x")).unwrap(); assert_eq!(first.allocated(), 1024, "a frame within budget is allocated up front"); - let mut second = b.create_frame_owned(sized(MAX_CACHE_BYTES), &budget).unwrap(); + let mut second = b.create_frame(sized(MAX_CACHE_BYTES)).unwrap(); second.write(Bytes::from(vec![0u8; 100])).unwrap(); assert_eq!( second.allocated(), @@ -4111,8 +4106,8 @@ mod test { let mut a = first.finish().unwrap(); a.finish().unwrap(); - let a = Info { sequence: 2 }.produce(); - let mut third = a.create_frame_owned(sized(1024), &budget).unwrap(); + let a = group(2); + let mut third = a.create_frame(sized(1024)).unwrap(); third.write(Bytes::from_static(b"x")).unwrap(); assert_eq!(third.allocated(), 1024, "the finished frame did not return its share"); } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 607e23345ab..1aa489242ce 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1773,6 +1773,10 @@ pub struct Producer { // The clock advanced by the origin driver. timers: Deadlines, + + // What the frames written through this handle may allocate up front, shared by every + // broadcast it creates. + frames: super::frame::Budget, } impl Producer { @@ -1800,6 +1804,7 @@ impl Producer { preference: Preference::default(), tasks, timers: timers.clone(), + frames: Default::default(), }; let driver = Driver { state: DriverState { @@ -1813,6 +1818,15 @@ impl Producer { (producer, driver) } + /// Give this handle a frame budget of its own, so what one session allocates up front + /// never crowds out another's. + #[cfg_attr(not(feature = "async"), allow(dead_code))] + // private: tuning + pub(crate) fn with_own_frames(mut self) -> Self { + self.frames = Default::default(); + self + } + /// The ingress stats context this handle was tagged with. #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/answer.md @@ -1909,6 +1923,7 @@ impl Producer { preference: Preference::default(), tasks, timers: Deadlines::new(Instant::ZERO), + frames: Default::default(), } } @@ -1982,6 +1997,7 @@ impl Producer { cache_duration: self.cache_duration, path: full, epoch: None, + frames: self.frames.clone(), }; let source = info.produce().with_stats(ingress.clone()); let entry = announcing.announce( @@ -2022,6 +2038,7 @@ impl Producer { cache_duration: self.cache_duration, path: full, epoch: None, + frames: self.frames.clone(), } .produce() .with_stats(ingress) @@ -2143,6 +2160,7 @@ impl Producer { preference: self.preference, tasks: self.tasks.clone(), timers: self.timers.clone(), + frames: self.frames.clone(), }) } @@ -5673,6 +5691,8 @@ impl Consumer { cache_duration: self.cache_duration, path: absolute.clone(), epoch: None, + // A front reads its routes' copies, so it writes no frames of its own. + frames: Default::default(), }); let request = kio::Producer::::default(); let consumer = request.consume(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 1a25d51259a..3044c35ab7d 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -1737,7 +1737,7 @@ mod test { routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3087,7 +3087,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3137,7 +3137,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, Duration::from_secs(2)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3150,7 +3150,7 @@ mod test { assert!(chunks.read_chunk().now_or_never().unwrap().is_ok()); let b = copy(); - let mut replacement = b.create_group(group::Info { sequence: 0 }).unwrap(); + let replacement = b.create_group(group::Info { sequence: 0 }).unwrap(); let mut replacement_frame = replacement .create_frame(crate::frame::Info { size: 4, @@ -3241,8 +3241,7 @@ mod test { }) .unwrap(); let mut frame = group - .create_frame_owned( - crate::frame::Header { + .create_object(crate::frame::Header { info: crate::frame::Info { size: 1, timestamp: Some(ts(0)), @@ -3251,9 +3250,7 @@ mod test { id: 6, properties: Default::default(), })), - }, - &crate::frame::Budget::default(), - ) + }) .unwrap(); frame.write(bytes::Bytes::from_static(b"a")).unwrap(); let group = frame.finish().unwrap(); @@ -3263,8 +3260,7 @@ mod test { assert_eq!(read(&mut reading), Some(b"a".to_vec())); assert_eq!(a.consume().resume_position(), Some(Position::group(1))); let mut partial = group - .create_frame_owned( - crate::frame::Header { + .create_object(crate::frame::Header { info: crate::frame::Info { size: 2, timestamp: Some(ts(1)), @@ -3273,9 +3269,7 @@ mod test { id: 8, properties: Default::default(), })), - }, - &crate::frame::Budget::default(), - ) + }) .unwrap(); partial.write(bytes::Bytes::from_static(b"b")).unwrap(); let mut chunks = reading.next_frame().now_or_never().unwrap().unwrap().unwrap(); @@ -3310,8 +3304,7 @@ mod test { .unwrap(); for &(id, payload) in objects { let mut frame = group - .create_frame_owned( - crate::frame::Header { + .create_object(crate::frame::Header { info: crate::frame::Info { size: payload.len() as u64, timestamp: Some(ts(id)), @@ -3320,9 +3313,7 @@ mod test { id, properties: Default::default(), })), - }, - &crate::frame::Budget::default(), - ) + }) .unwrap(); frame.write(bytes::Bytes::from_static(payload)).unwrap(); group = frame.finish().unwrap(); @@ -3340,7 +3331,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&front, Duration::from_secs(10)); - let mut open = a.create_group(group::Info { sequence: 0 }).unwrap(); + let open = a.create_group(group::Info { sequence: 0 }).unwrap(); let mut frame = open .create_frame(crate::frame::Info { size: 4, @@ -3904,21 +3895,25 @@ mod test { let mut sub = subscribe(&logical, Duration::from_secs(if widen { 2 } else { 10 })); let b = copy(); // Both routes carry the same content, including the unfinished payload. - let mut writers = [&a, &b].map(|source| source.create_group(group::Info { sequence: 0 }).unwrap()); - let _frames: Vec<_> = writers - .iter_mut() - .map(|group| { + let writers = [&a, &b].map(|source| source.create_group(group::Info { sequence: 0 }).unwrap()); + // Each group's writer, held open by its unfinished frame when chunked. + let _writers: Vec<_> = writers + .into_iter() + .map(|mut group| { group.write_frame(ts(0), b"first".as_ref()).unwrap(); - chunked.then(|| { - let mut frame = group - .create_frame(crate::frame::Info { - size: 4, - timestamp: Some(ts(1)), - }) - .unwrap(); - frame.write(b"ab".as_ref()).unwrap(); - frame - }) + match chunked { + false => (Some(group), None), + true => { + let mut frame = group + .create_frame(crate::frame::Info { + size: 4, + timestamp: Some(ts(1)), + }) + .unwrap(); + frame.write(b"ab".as_ref()).unwrap(); + (None, Some(frame)) + } + } }) .collect(); let mut group = recv(&mut sub); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 84e765a2c6d..b4af4ef6583 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1505,7 +1505,7 @@ impl TrackState { broadcast: broadcast.clone(), ..Default::default() }); - let cache = cache::Track::new(broadcast.pool.clone(), state.downgrade()); + let cache = cache::Track::new(broadcast.pool.clone(), broadcast.frames.clone(), state.downgrade()); state.write().ok().expect("a new track is open").cache = cache; state } @@ -7477,13 +7477,10 @@ mod test { .unwrap(); let handle = group.handle(); let _partial = group - .create_frame_owned( - frame::Info { + .create_frame(frame::Info { size: 2, timestamp: Some(Timestamp::ZERO), - }, - &frame::Budget::default(), - ) + }) .unwrap(); assert_eq!(handle.frame_count(), 2); drop(_partial); @@ -8003,7 +8000,7 @@ mod test { #[test] fn streaming_frame_writes_keep_the_group_alive() { let producer = track_producer("test", Info::timed()); - let mut straggler = producer.create_group(0u64.into()).unwrap(); + let straggler = producer.create_group(0u64.into()).unwrap(); // The live edge moves on, so the straggler is demoted and expirable. producer.create_group(1u64.into()).unwrap().finish().unwrap(); @@ -8020,7 +8017,7 @@ mod test { frame.write(bytes::Bytes::from_static(b"x")).unwrap(); producer.create_group(seq.into()).unwrap().finish().unwrap(); } - frame.finish().unwrap(); + let mut straggler = frame.finish().unwrap(); straggler.finish().unwrap(); let state = producer.state.read(); @@ -8042,20 +8039,17 @@ mod test { producer.create_group(1u64.into()).unwrap().finish().unwrap(); let mut frame = straggler - .create_frame_owned( - frame::Info { + .create_frame(frame::Info { size: 3, timestamp: Some(Timestamp::ZERO), - }, - &Default::default(), - ) + }) .unwrap(); // The sender stalls past the retention window, then the whole payload lands in // one poll turn: the loop never returns `Pending`, so `notify` is never reached // and `finish` is the only write the charge sees. elapse(&producer, cache::DEFAULT_EXPIRY + Duration::from_secs(1)); - frame.write(bytes::Bytes::from_static(b"abc")).unwrap(); + frame.write_deferred(bytes::Bytes::from_static(b"abc")).unwrap(); let mut straggler = frame.finish().unwrap(); straggler.finish().unwrap(); @@ -8323,7 +8317,7 @@ mod test { fn streaming_frame_write_expires_idle_siblings() { let producer = track_producer_expiring("test", Duration::from_secs(1)); producer.append_group().unwrap().finish().unwrap(); // seq 0 - let mut live = producer.append_group().unwrap(); // seq 1 + let live = producer.append_group().unwrap(); // seq 1 let mut frame = live .create_frame(frame::Info { size: 1, @@ -9637,7 +9631,7 @@ mod test { async fn a_handed_out_partial_frame_expires_while_its_payload_is_stalled() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - let mut source = producer.append_group().unwrap(); + let source = producer.append_group().unwrap(); let mut writing = source .create_frame(frame::Info { size: 6, @@ -10905,6 +10899,8 @@ mod test { .is_ok() ); assert!(matches!(group.write_frames(&mut frames), Err(Error::Closed))); + assert_eq!(group.frame_count(), 2); + // A refused frame aborts its group, since a write past the end is a bug. assert!(matches!( group.create_frame(frame::Info { size: 1, @@ -10912,7 +10908,6 @@ mod test { }), Err(Error::Closed) )); - assert_eq!(group.frame_count(), 2); assert!(producer.create_group(group::Info { sequence: 6 }).is_err()); } } @@ -14876,7 +14871,8 @@ mod test { assert_eq!(frames.len(), 1, "the batch is left to retry"); assert_eq!(batched.frame_count(), 0); - let mut streamed = producer.append_group().unwrap(); + let streamed = producer.append_group().unwrap(); + let handle = streamed.handle(); let refused = streamed .create_frame(frame::Info { size: 1, @@ -14884,7 +14880,8 @@ mod test { }) .err(); assert!(matches!(refused, Some(Error::TimestampMismatch)), "{refused:?}"); - assert_eq!(streamed.frame_count(), 0); + assert_eq!(handle.frame_count(), 0); + assert!(handle.is_aborted(), "a refused frame aborts its group"); } /// Eviction is not a sequence prefix: a group stamped after its predecessor was evicted diff --git a/rs/moq-net/src/recv.rs b/rs/moq-net/src/recv.rs index 28331f4cb9b..d005fd209c9 100644 --- a/rs/moq-net/src/recv.rs +++ b/rs/moq-net/src/recv.rs @@ -1,6 +1,6 @@ //! Receive-side ownership: a cancelled handler explicitly aborts its unfinished group. //! -//! Frames need no guard here: `frame::Raw`'s own `Drop` already aborts the group when a +//! Frames need no guard here: `frame::Producer`'s own `Drop` already aborts the group when a //! frame dies before its declared size is written, so a partial frame is never silent. use std::ops::{Deref, DerefMut}; @@ -22,16 +22,12 @@ impl Group { } /// Move the writer and cancellation cleanup into its next frame. - pub fn create_frame_owned( - &mut self, - frame: impl Into, - budget: &frame::Budget, - ) -> Result { + pub fn create_object(&mut self, frame: frame::Header) -> Result { self.writer .take() .expect("group writer is available between frames") - .create_frame_owned(frame, budget) - .map(frame::ProducerOwned::cancel_on_drop) + .create_object(frame) + .map(frame::Producer::cancel_on_drop) } /// Restore the writer returned by a completed frame. @@ -103,12 +99,12 @@ mod tests { let mut consumer = producer.consume(); let mut receiving = Group::new(producer); let frame = receiving - .create_frame_owned( + .create_object( crate::frame::Info { size: 2, timestamp: Some(crate::Timestamp::ZERO), - }, - &crate::frame::Budget::default(), + } + .into(), ) .unwrap(); drop(frame); @@ -124,12 +120,12 @@ mod tests { let mut consumer = producer.consume(); let mut receiving = Group::new(producer); let frame = receiving - .create_frame_owned( + .create_object( crate::frame::Info { size: 2, timestamp: Some(crate::Timestamp::ZERO), - }, - &crate::frame::Budget::default(), + } + .into(), ) .unwrap(); receiving.abort(Error::App(42)).unwrap(); diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index a9021e1cdd8..fd5e5a2c523 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -159,15 +159,9 @@ async fn lite05_timestamp_roundtrip(scheme: &str) { let mut group = track.append_group().expect("failed to append group"); for &us in &frames { let payload = format!("frame@{us}").into_bytes(); - let frame = moq_tokio::moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - }; - let mut writer = group.create_frame(frame).expect("failed to create frame"); - writer - .write(bytes::Bytes::from(payload)) + group + .write_frame(Timestamp::new(us, Timescale::MICRO).unwrap(), payload) .expect("failed to write frame"); - writer.finish().expect("failed to finish frame"); } group.finish().expect("failed to finish group"); @@ -282,15 +276,9 @@ async fn lite05_fetch_roundtrip(scheme: &str) { let mut group = track.append_group().expect("failed to append group"); // seq 0 for &us in &frames { let payload = format!("frame@{us}").into_bytes(); - let frame = moq_tokio::moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - }; - let mut writer = group.create_frame(frame).expect("failed to create frame"); - writer - .write(bytes::Bytes::from(payload)) + group + .write_frame(Timestamp::new(us, Timescale::MICRO).unwrap(), payload) .expect("failed to write frame"); - writer.finish().expect("failed to finish frame"); } group.finish().expect("failed to finish group"); @@ -517,13 +505,6 @@ async fn fetch_moq_transport_20() { async fn lite05_fetch_during_subscribe(scheme: &str) { use moq_tokio::moq_net::{Timescale, Timestamp}; - fn timestamped_frame(us: u64, payload: &str) -> moq_net::frame::Info { - moq_net::frame::Info { - size: payload.len() as u64, - timestamp: Some(Timestamp::new(us, Timescale::MICRO).unwrap()), - } - } - let pub_origin = moq_tokio::origin::spawn(); let broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); broadcast @@ -539,15 +520,15 @@ async fn lite05_fetch_during_subscribe(scheme: &str) { // Group 0 is the "past" group only reachable via FETCH; group 1 is the latest, // delivered live over the subscription. let mut group0 = track.append_group().expect("append group 0"); // seq 0 - let mut w = group0.create_frame(timestamped_frame(10_000, "old")).expect("frame 0"); - w.write(bytes::Bytes::from_static(b"old")).expect("write 0"); - w.finish().expect("finish frame 0"); + group0 + .write_frame(Timestamp::new(10_000, Timescale::MICRO).unwrap(), b"old".as_slice()) + .expect("frame 0"); group0.finish().expect("finish group 0"); let mut group1 = track.append_group().expect("append group 1"); // seq 1 - let mut w = group1.create_frame(timestamped_frame(20_000, "new")).expect("frame 1"); - w.write(bytes::Bytes::from_static(b"new")).expect("write 1"); - w.finish().expect("finish frame 1"); + group1 + .write_frame(Timestamp::new(20_000, Timescale::MICRO).unwrap(), b"new".as_slice()) + .expect("frame 1"); group1.finish().expect("finish group 1"); let mut server_config = moq_tokio::listen::Config::default(); From 1c5f6bfc3741cf891a262274b36be5a18593b7b0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 16:58:12 -0700 Subject: [PATCH 04/22] refactor(net)!: the model waits out a received end's tail itself A received copy's `finish_at` now holds readers at a hole below the end for the subscription's grace, timed by the model over its own arrival record, so a custom subscriber declares a peer's end with the public `finish_at`. Drops count as accounted, and a feed still delivering keeps the gap above its last arrival open. `finish_at_pending` and `set_tail_pending` are gone (folded into `finish_at`, which now accepts a repeated or refined end), `demand_arrivals` folds into the start declaration, `drop_groups` is public, and the ledger moves out of the model. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/Cargo.toml | 3 +- rs/moq-net/benches/tail.rs | 5 +- rs/moq-net/src/fuzz.rs | 6 - rs/moq-net/src/ietf/subscriber.rs | 10 +- rs/moq-net/src/{model => }/ledger.rs | 8 +- rs/moq-net/src/lib.rs | 1 + rs/moq-net/src/lite/subscriber.rs | 20 +- rs/moq-net/src/model/frame.rs | 1 + rs/moq-net/src/model/mod.rs | 2 - rs/moq-net/src/model/track.rs | 366 +++++++++++++++++++-------- rs/moq-net/src/tail.rs | 4 +- 11 files changed, 282 insertions(+), 144 deletions(-) rename rs/moq-net/src/{model => }/ledger.rs (98%) diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index fd3f53810a2..5e7a74dab82 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -130,11 +130,10 @@ name = "track" harness = false required-features = ["async"] -# Declares a pending tail through the hidden `fuzz` module. [[bench]] name = "tail" harness = false -required-features = ["fuzz"] +required-features = ["async"] [[bench]] name = "priority" diff --git a/rs/moq-net/benches/tail.rs b/rs/moq-net/benches/tail.rs index 4c76c9325be..3ca1d3ca13a 100644 --- a/rs/moq-net/benches/tail.rs +++ b/rs/moq-net/benches/tail.rs @@ -5,7 +5,7 @@ //! check is judged by the track's record of arrivals, so a cost that grows with the groups //! cached or the tracks held shows up as a slope over either axis. //! -//! Run with `cargo bench -p moq-net --features fuzz --bench tail`. +//! Run with `cargo bench -p moq-net --bench tail`. use std::{hint::black_box, task::Poll, time::Duration}; @@ -38,7 +38,8 @@ impl Held { track.subscribe(track::Subscription::default().with_max_delay(Duration::from_secs(3600))); track.start_at(0).unwrap(); let end = track::Position::group(groups as u64 + 1); - moq_net::fuzz::finish_at_pending(&mut track, end).unwrap(); + track.received(); + track.finish_at(end).unwrap(); // Group 0 never arrives: the hole that holds the reader. for sequence in 1..=groups as u64 { track.create_group(group::Info { sequence }).unwrap().finish().unwrap(); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index ed2c9e19ed2..b2c7b1d901d 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -62,12 +62,6 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr (broadcast, track, group) } -/// Declare a received track's end while the wire may still owe groups below it, as a -/// subscriber does on SUBSCRIBE_END, for the pending-tail benchmark. -pub fn finish_at_pending(track: &mut track::Producer, end: track::Position) -> crate::Result<()> { - track.finish_at_pending(end) -} - /// Every target, keyed by the name of its `fuzz_targets/.rs` shim. pub const TARGETS: &[(&str, Target)] = &[ ("lite", lite_wire), diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 0c20e73ac96..0bd388813f2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3255,9 +3255,8 @@ where fill.end(); } } - // The tail settled, so readers may end at an END_OF_TRACK's boundary. - track.set_tail_pending(false); - // A no-op once an END_OF_TRACK declared the end. + // A no-op once an END_OF_TRACK declared the end, whose readers wait + // for a missing group only as long as the grace. let _ = track.finish(); } Err(err) => { @@ -4155,8 +4154,9 @@ fn end_track(track: &mut track::Producer, end: track::Position, properties: bool let _ = track.clone().abort(Error::Unsupported); return Err(Error::Unsupported); } - // Lower groups may still be on the wire, behind the one that carried the end. - if let Err(err) = track.finish_at_pending(end) { + // Lower groups may still be on the wire, behind the one that carried the end: the + // received copy holds readers at a hole for the grace. + if let Err(err) = track.finish_at(end) { tracing::warn!(%err, ?end, "invalid END_OF_TRACK"); let _ = track.clone().abort(Error::ProtocolViolation); return Err(Error::ProtocolViolation); diff --git a/rs/moq-net/src/model/ledger.rs b/rs/moq-net/src/ledger.rs similarity index 98% rename from rs/moq-net/src/model/ledger.rs rename to rs/moq-net/src/ledger.rs index 055f1d904d8..bb2a68e67b3 100644 --- a/rs/moq-net/src/model/ledger.rs +++ b/rs/moq-net/src/ledger.rs @@ -12,12 +12,10 @@ use crate::time::Instant; /// /// Bounds the wait on IETF, and on moq-lite when the subscription has no max delay to bound /// it with. Matches `@moq/net`, so a reader cannot tell which side it is talking to. -// pending: /quest/m1/public-model/ingest.md pub(crate) const GRACE: Duration = Duration::from_secs(1); /// The grace for a subscription with `max_delay`: how long the subscriber was willing to /// wait for a late group anyway, or [`GRACE`] without one. -// pending: /quest/m1/public-model/ingest.md pub(crate) fn grace(max_delay: Duration) -> Duration { match max_delay.is_zero() { true => GRACE, @@ -35,7 +33,6 @@ struct Run { /// The sequences accounted for, and how late each gap between them is. #[derive(Debug)] -// pending: /quest/m1/public-model/ingest.md pub(crate) struct Ledger { // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace // can no longer be waited for, so it folds into the runs around it, which bounds this by @@ -114,6 +111,11 @@ impl Ledger { self.runs.first().map(|run| run.groups.start) } + /// One past the highest sequence accounted for. + pub fn end(&self) -> Option { + self.runs.last().map(|run| run.groups.end) + } + /// Whether every group in `groups` is accounted for. pub fn covers(&self, groups: Range) -> bool { // Runs merge on insert, so one run covers the span or none does. diff --git a/rs/moq-net/src/lib.rs b/rs/moq-net/src/lib.rs index c7999766c73..1553495e7d1 100644 --- a/rs/moq-net/src/lib.rs +++ b/rs/moq-net/src/lib.rs @@ -96,6 +96,7 @@ pub mod goaway; #[doc(hidden)] pub mod fuzz; mod ietf; +mod ledger; mod lite; mod model; pub mod path; diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 231ce18ca59..6fd2904326b 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -5624,11 +5624,6 @@ impl TrackServe { if subscription.start().is_none() { subscription.set_bounds(producer.idle_newest().map(Position::group), subscription.end()); } - // The track's arrivals outlive a subscription, and this one asks for - // its groups only now. - if let Some(start) = subscription.start() { - producer.demand_arrivals(start.group..u64::MAX); - } // Open an upstream SUBSCRIBE for the first subscriber. Ok(Begin::Establish(self.prepare_establish( producer, @@ -5643,15 +5638,13 @@ impl TrackServe { active.priority = subscription.priority; active.order = subscription.order; active.max_delay = subscription.max_delay; - // A lowered floor owes groups nobody asked for until now, in the track's - // arrivals that held fetches read as well as in the session's tail. + // A lowered floor owes groups nobody asked for until now, in the session's + // tail as well as in the track's arrivals, which its start declaration + // restarts. let lowered = subscription.start().map(|start| { let floor = active.start.map(|start| start.group).or(active.served); start.group..floor.unwrap_or(u64::MAX) }); - if let Some(groups) = &lowered { - producer.demand_arrivals(groups.clone()); - } if let Ok(mut tail) = active.tail.write() { tail.set_grace(tail::grace(subscription.max_delay)); if let Some(groups) = lowered { @@ -6105,7 +6098,6 @@ impl kio::Task for TrackServeRun { } }, ServeEnd::Finished => { - serve_loop.serving.set_tail_pending(false); let _ = serve_loop.serving.finish(); } ServeEnd::GiveBack(err) => { @@ -6705,14 +6697,14 @@ impl ServeLoop { // then finds the track already finished. lite::SubscribeResponse::End(end) => { // Lower groups may still be on the wire, behind a higher - // one, so the end holds readers at a hole until the tail - // settles. finish_at rejects a boundary at or below a group + // one, so the end holds readers at a hole until it fills or + // its grace passes. finish_at rejects a boundary at or below a group // already received. lite-05 specified an inclusive end, // and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it // only costs the early boundary: warn, and let the FIN // finish the track. Later drafts made it exclusive, so // the publisher contradicted its own end. - if let Err(err) = self.serving.finish_at_pending(Position::group(end.group)) { + if let Err(err) = self.serving.finish_at(Position::group(end.group)) { match serve.subscriber.version { Version::Lite05 => { tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end") diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index bf0301534b9..964c3152a55 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -195,6 +195,7 @@ impl Budget { /// A budget of `bytes`, for a benchmark sweeping it. #[cfg(any(test, feature = "fuzz"))] + // private: tuning pub(crate) fn new(bytes: usize) -> Self { Self(Arc::new(Remaining(AtomicUsize::new(bytes)))) } diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 6d8fcd85ef8..08c46d781aa 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -23,8 +23,6 @@ mod clock; pub(crate) mod datagram; mod delivered; mod expiry; -// pending: /quest/m1/public-model/ingest.md -pub(crate) mod ledger; // private: passthrough pub(crate) mod object; mod requests; diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index b4af4ef6583..6982a2721b1 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -17,7 +17,7 @@ use crate::{Error, Result, Timescale, Timestamp, coding}; use crate::{broadcast, cache, group, stats}; use super::delivered::Delivered; -use super::ledger::{self, Ledger}; +use crate::ledger::{self, Ledger}; use super::{Datagram, Requests}; use super::Cap; @@ -375,10 +375,11 @@ pub(crate) struct TrackState { // or the receiving session closed locally without declaring an end. sealed: bool, - // A wire subscription declared the end ahead of the group streams below it, which - // QUIC may deliver in any order: readers wait for its tail to settle, or for the - // last producer to go, rather than end at the boundary with groups still to arrive. - tail_pending: bool, + // Set once a received copy's end is declared, ahead of group streams below it that QUIC + // may deliver in any order: when the end was declared or a group last arrived since. + // Readers wait out the grace for that tail (see [`Self::tail_deadline`]), rather than + // end at the boundary with groups still to arrive. + tail: Option, // The sequences the live feed delivered, as a group or a datagram: what a pending tail // is judged by. Fetched copies never count, and eviction never touches it. A gap folds @@ -1470,6 +1471,10 @@ impl TrackState { /// Record that the live feed delivered `sequence`, then fold the gaps that aged out. fn record_arrival(&mut self, sequence: u64, now: crate::time::Instant) { self.arrivals.account(sequence..sequence.saturating_add(1), now); + // A feed still delivering keeps the gap above its last arrival open. + if self.tail.is_some() { + self.tail = Some(now); + } self.fold_arrivals(now); } @@ -1480,10 +1485,16 @@ impl TrackState { if !self.arrivals.has_gaps() { return; } + self.arrivals.set_grace(self.arrival_grace()); + self.arrivals.expire(now); + } + + /// How long a missing live group is waited for, from the max delay the track's + /// subscribers ask for. + fn arrival_grace(&self) -> Duration { let max_delay = snapshot_subscription(&self.subscriptions, self.max_age_bound()) .map_or(Duration::ZERO, |subscription| subscription.max_delay); - self.arrivals.set_grace(ledger::grace(max_delay)); - self.arrivals.expire(now); + ledger::grace(max_delay) } /// Attach the publisher's immutable metadata without replacing it with local cache policy. @@ -1835,11 +1846,16 @@ impl TrackState { /// declaration: the signal is scoped to the current subscription's demand, /// which may legitimately move in either direction. `None` clears it (the /// demand dropped to the live edge, whose floor is unknown until declared). + /// + /// A declared start asks the feed for every group from it, so a gap in the arrivals at + /// or above it is waited for a fresh grace: the feed may only now be sending it. fn set_start(&mut self, start_sequence: Option, pending: bool) { self.start_sequence = start_sequence; self.start_pending = pending; if let Some(start) = start_sequence { self.cache.wakes().arrived(..start); + let now = self.cache.pool().now_wall(); + self.arrivals.demand(start..u64::MAX, now); } } @@ -1890,8 +1906,8 @@ impl TrackState { /// Whether the track has reached its end: the final boundary is set and the live /// edge has caught up to it, so no further group can arrive. A future boundary /// (declared via [`Producer::finish_at`] ahead of the live edge) stays incomplete - /// until the remaining groups are produced, or until the last producer drops without - /// them. Drives the end-of-stream signal from + /// until the remaining groups are produced, the last producer drops without them, or, + /// on a received copy, the grace for them passes. Drives the end-of-stream signal from /// the read methods (`recv_group` / `next_group` / `read_frame` return `None`). /// /// An abort before the end settled wins over it: a group below the boundary was @@ -1902,10 +1918,16 @@ impl TrackState { let reached = self.sealed || self .final_sequence() - .is_some_and(|fin| self.edge() >= fin && !self.awaits_tail(fin)); + .is_some_and(|fin| self.reaches(fin) && !self.awaits_tail(fin)); reached && (self.abort.is_none() || self.settled) } + /// Whether the live edge reached `fin`, or a received copy's tail decides it instead: + /// what it still misses up to `fin` is waited for only as long as the grace. + fn reaches(&self, fin: u64) -> bool { + self.edge() >= fin || self.tail.is_some() + } + /// Whether the largest can no longer advance while a producer is still held: the track /// reached its declared end, and the largest group's content is final. Every sequence below /// the end raised it already, and a group name fixes its content, so no legal write moves @@ -1926,26 +1948,53 @@ impl TrackState { self.abort.is_none() && self.owes(fin) } - /// Whether the pending tail misses a sequence from where the feed starts up to `fin`: - /// one no live group or datagram delivered, in a gap younger than the grace. - /// - /// Judged by the arrivals, not the cache, so an evicted group or a datagram counts - /// as delivered, and the check costs the same however much is cached. + /// Whether the tail misses a sequence from where the feed starts up to `fin` that is + /// still worth waiting for; see [`Self::tail_deadline`]. fn owes(&self, fin: u64) -> bool { - if !self.tail_pending { - return false; - } + self.tail_deadline(fin) + .is_some_and(|at| self.cache.pool().now_wall() < at) + } + + /// When a received copy's declared end stops waiting for its tail: the latest instant a + /// sequence below `fin` it still misses is given up. `None` when nothing is missing. + /// + /// A missing sequence is one no live group or datagram delivered and the publisher did + /// not drop. A gap below an arrival is given up a grace after that arrival opened it, as + /// the session's tail does. The gap above the last arrival is given up a grace after + /// the end was declared or a group last arrived, so a feed still delivering toward an + /// end declared ahead of it is not cut off. Judged by the arrivals, not the cache, so an evicted group or a + /// datagram counts as delivered, and the check costs the same however much is cached. + fn tail_deadline(&self, fin: u64) -> Option { + let active = self.tail?; + let grace = self.arrival_grace(); // Fetched backfill never reaches a reader in arrival order, so only the live feed's // arrivals count. Without a declared start, the first one stands in for it. let floor = match self.start_sequence { Some(start) => start, - None if self.start_pending => return true, - None => match self.arrivals.first() { - Some(first) => first, - None => return fin > 0, - }, + // Where the feed starts is still unknown, so all of it is owed. + None if self.start_pending => return active.checked_add(grace), + None => self.arrivals.first().unwrap_or(0), }; - !self.arrivals.covers(floor.min(fin)..fin) + let owed = floor.min(fin)..fin; + let top = self.arrivals.end().unwrap_or(0)..fin; + self.arrivals + .folds(grace) + .chain(active.checked_add(grace).map(|at| (top, at))) + .filter(|(gap, _)| { + let gap = gap.start.max(owed.start)..gap.end.min(owed.end); + !gap.is_empty() && self.drops.gaps(&gap).next().is_some() + }) + .map(|(_, at)| at) + .max() + } + + /// Wake `waiter` when a received copy's declared end stops waiting for its tail. + fn watch_tail(&self, waiter: &kio::Waiter) { + if let Some(at) = self.final_sequence().and_then(|fin| self.tail_deadline(fin)) + && self.cache.pool().now_wall() < at + { + self.cache.watch_wall(at, waiter); + } } /// Whether the declared end is reached, the pending tail owes nothing below it, and @@ -1957,7 +2006,7 @@ impl TrackState { let Some(fin) = self.final_sequence() else { return false; }; - let reached = self.sealed || self.edge() >= fin; + let reached = self.sealed || self.reaches(fin); reached && (self.abort.is_none() || self.settled) && !self.owes(fin) @@ -2223,18 +2272,24 @@ fn poll_largest( /// Ready once the track's feed is live, or nothing more can move its largest. A declared /// end that is not reached yet does not count: an idle copy's largest is still only what /// its ended feed left. -fn largest_live(state: &TrackState) -> Poll<()> { +fn largest_live(state: &TrackState, waiter: &kio::Waiter) -> Poll<()> { match state.feed == Feed::Live || state.sealed || state.abort.is_some() || state.largest_settled() { true => Poll::Ready(()), - false => Poll::Pending, + false => { + state.watch_tail(waiter); + Poll::Pending + } } } /// Ready once the track's largest can no longer advance; see [`TrackState::largest_settled`]. -fn largest_ended(state: &TrackState) -> Poll<()> { +fn largest_ended(state: &TrackState, waiter: &kio::Waiter) -> Poll<()> { match state.largest_settled() { true => Poll::Ready(()), - false => Poll::Pending, + false => { + state.watch_tail(waiter); + Poll::Pending + } } } @@ -2547,20 +2602,15 @@ impl Producer { /// already exists is [`Error::ProtocolViolation`]. Consumers only see end-of-stream /// once the live edge reaches the end's group. Use [`Self::finish`] to finish exactly /// at the live edge. - pub fn finish_at(&mut self, end: Position) -> Result<()> { - self.modify()?.set_end(end) - } - - /// [`Self::finish_at`] for a wire subscription that may still owe groups below the end. /// - /// The end and the pending tail land in one write: a reader that saw the end without - /// the tail would end at a hole the wire is still filling. Repeating the declared end - /// is a no-op, and a mid-group end may refine a group boundary it falls just before - /// (a FETCH_OK names only the boundary). Any other second end is - /// [`Error::ProtocolViolation`]. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn finish_at_pending(&mut self, end: Position) -> Result<()> { + /// Repeating the declared end is a no-op, and a mid-group end may refine the group + /// boundary it falls just before (a peer may name only the boundary first). Any other + /// second end is [`Error::ProtocolViolation`]. + /// + /// On a [received](Self::received) copy, groups below the end may still be in flight: + /// readers wait for a missing one until a grace passes, the subscription's max delay + /// or one second without one, before ending at the boundary. + pub fn finish_at(&mut self, end: Position) -> Result<()> { let mut state = self.modify()?; match state.end { Some(declared) if declared == end => return Ok(()), @@ -2574,24 +2624,10 @@ impl Producer { Some(_) => return Err(Error::ProtocolViolation), None => state.set_end(end)?, } - state.tail_pending = true; - Ok(()) - } - - /// Whether a wire subscription still owes group streams below the declared end. - /// - /// While pending, readers do not end at the boundary: a lower group's stream may - /// arrive after a higher one. The session clears it once its tail settles; the last - /// producer going ends readers regardless. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn set_tail_pending(&self, pending: bool) { - if self.state.read().tail_pending == pending { - return; - } - if let Ok(mut state) = self.modify() { - state.tail_pending = pending; + if state.received && state.tail.is_none() { + state.tail = Some(state.cache.pool().now_wall()); } + Ok(()) } /// Declare the first group the live feed serves (the wire's SUBSCRIBE_START, @@ -2609,19 +2645,21 @@ impl Producer { Ok(()) } - /// Mark this track as a copy received from a remote publisher: its groups are never - /// checked for a timestamp rewind, which only a local publisher's writes refuse, since a - /// received timestamp may not be media time. + /// Mark this track as a copy received from a remote publisher, before writing to it. + /// + /// Its groups are never checked for a timestamp rewind, which only a local publisher's + /// writes refuse, since a received timestamp may not be media time. Its declared end + /// waits for groups still in flight below it; see [`Self::finish_at`]. pub fn received(&self) { if let Ok(mut state) = self.modify() { state.received = true; } } - /// Record sequences the upstream publisher explicitly gave up. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn drop_groups(&self, groups: ops::Range) { + /// Record that the publisher gave up `groups`: none will arrive, so a reader waiting + /// on one moves past it, the declared end does not wait for them, and a relay serving + /// this track forwards the drop. + pub fn drop_groups(&self, groups: ops::Range) { if groups.is_empty() { return; } @@ -2630,17 +2668,6 @@ impl Producer { } } - /// Restart the age of every arrival gap reaching into `groups`, which the live feed's - /// subscription newly asks for. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn demand_arrivals(&self, groups: ops::Range) { - if let Ok(mut state) = self.modify() { - let now = state.cache.pool().now_wall(); - state.arrivals.demand(groups, now); - } - } - /// Readers get nothing from the cache until [`Self::set_live`]: the upstream /// subscription ended with this copy still held, so what it cached may go stale. #[cfg_attr(not(feature = "async"), allow(dead_code))] @@ -2804,8 +2831,8 @@ impl Producer { &mut self.largest, Bounds::default(), waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ) } @@ -4099,8 +4126,8 @@ impl Consumer { seen, bounds, waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ), } }) @@ -4160,6 +4187,7 @@ impl Consumer { if state.end.is_some() && state.is_complete() { Poll::Ready(()) } else { + state.watch_tail(waiter); Poll::Pending } })) { @@ -5285,7 +5313,15 @@ impl Cursor { where F: Fn(&kio::Ref<'_, TrackState>) -> Poll>, { - Poll::Ready(match ready!(self.state.poll(waiter, f)) { + let polled = self.state.poll(waiter, |state| { + let res = f(state); + if res.is_pending() { + // The end can settle with no write: when the grace for a missing group passes. + state.watch_tail(waiter); + } + res + }); + Poll::Ready(match ready!(polled) { Ok(res) => res, // We try to clone abort just in case the function forgot to check for terminal state. Err(state) => Err(state.abort.clone().unwrap_or(Error::Dropped)), @@ -6267,8 +6303,8 @@ impl Subscriber { seen, bounds, waiter, - |waiter| state.poll(waiter, |state| largest_live(state)).map(|_| ()), - |waiter| state.poll(waiter, |state| largest_ended(state)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_live(state, waiter)).map(|_| ()), + |waiter| state.poll(waiter, |state| largest_ended(state, waiter)).map(|_| ()), ) } Inner::Resume(resume, _) => resume.poll_largest(seen, bounds, waiter), @@ -10804,8 +10840,10 @@ mod test { assert_eq!(producer.end(), Some(Position::group(6))); - // Re-finishing is rejected, and no group at or above the boundary can be created. - assert!(producer.finish_at(Position::group(6)).is_err()); + // Repeating the end is a no-op, moving it is rejected, and no group at or above the + // boundary can be created. + assert!(producer.finish_at(Position::group(6)).is_ok()); + assert!(producer.finish_at(Position::group(7)).is_err()); assert!(producer.create_group(group::Info { sequence: 4 }).is_ok()); assert!(producer.create_group(group::Info { sequence: 6 }).is_err()); } @@ -10815,14 +10853,13 @@ mod test { let pool = cache::Pool::new(cache::Config::default().with_expiry(Duration::from_secs(1))); let mut producer = track_producer_pooled("test", pool.clone()); let end = Position { group: 5, frame: 5 }; - producer.finish_at_pending(end).unwrap(); + producer.finish_at(end).unwrap(); let mut group = producer.create_group(group::Info { sequence: 5 }).unwrap(); for _ in 0..5 { group.write_frame(Timestamp::ZERO, b"x".as_slice()).unwrap(); } group.finish().unwrap(); let consumer = producer.consume(); - producer.set_tail_pending(false); drop(producer); // Date the last activity before advancing the cache clock past expiry. pool.sweep(); @@ -10841,13 +10878,13 @@ mod test { fn a_wire_end_repeats_or_refines_but_never_moves() { let mut producer = track_producer("test", Info::timed()); // A FETCH_OK names only the boundary; END_OF_TRACK may then name the frame before it. - producer.finish_at_pending(Position::group(6)).unwrap(); - producer.finish_at_pending(Position { group: 5, frame: 5 }).unwrap(); - producer.finish_at_pending(Position { group: 5, frame: 5 }).unwrap(); + producer.finish_at(Position::group(6)).unwrap(); + producer.finish_at(Position { group: 5, frame: 5 }).unwrap(); + producer.finish_at(Position { group: 5, frame: 5 }).unwrap(); assert_eq!(producer.end(), Some(Position { group: 5, frame: 5 })); for moved in [Position { group: 5, frame: 4 }, Position::group(6), Position::group(5)] { assert!(matches!( - producer.finish_at_pending(moved), + producer.finish_at(moved), Err(Error::ProtocolViolation) )); } @@ -11007,17 +11044,18 @@ mod test { )); } - /// A wire subscription's pending tail holds readers at a hole below the end, since a - /// lower group's stream may arrive after a higher one, until the hole fills or the tail - /// settles. The last producer going ends them regardless. + /// A received copy's end holds readers at a hole below it, since a lower group's stream + /// may arrive after a higher one, until the hole fills or its grace passes. The last + /// producer going ends them regardless. #[moq_clock::test] #[cfg(feature = "async")] async fn a_pending_tail_holds_readers_at_a_hole() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); // The wire declares where the feed starts. producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); let _high = producer.create_group(group::Info { sequence: 2 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 2); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); @@ -11030,39 +11068,145 @@ mod test { assert_eq!(arrival.assert_group().sequence, 1); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); - // A settled tail ends readers at the boundary, hole and all. + // The grace passing ends readers at the boundary, hole and all. let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); assert!(arrival.recv_group().now_or_never().is_none()); - producer.set_tail_pending(false); + // The subscription's max delay is the grace. + elapse(&producer, replay().max_delay); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); // So does the last producer going. let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); drop(producer); assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); } + /// The grace alone ends a reader parked at a hole, with no write to wake it: below an + /// arrival it runs from that arrival, and above the last one from the declared end. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_parked_reader_wakes_when_the_tail_grace_passes() { + // The subscription's max delay is the grace. + let grace = replay().max_delay; + // Hole 0 sits below arrival 1; holes 2..4 sit above the last arrival. + for (end, arrived_late) in [(2, false), (4, true)] { + let mut producer = track_producer("test", None); + producer.received(); + elapse(&producer, Duration::ZERO); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + if arrived_late { + // The end comes later than the arrival, so its gap runs from the end. + elapse(&producer, grace / 2); + } + producer.finish_at(Position::group(end)).unwrap(); + + let woken = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); + assert!(arrival.poll_recv_group(&waiter).is_pending(), "end {end}: held at the hole"); + elapse(&producer, grace - Duration::from_millis(1)); + assert!(!woken.load(Ordering::SeqCst), "end {end}: woken before the grace"); + assert!(arrival.poll_recv_group(&waiter).is_pending()); + elapse(&producer, Duration::from_millis(1)); + assert!(woken.load(Ordering::SeqCst), "end {end}: the grace never woke the reader"); + assert!(matches!(arrival.poll_recv_group(&waiter), Poll::Ready(Ok(None)))); + } + } + + /// An end declared ahead of a feed still delivering does not cut it off: each arrival + /// restarts the grace for the groups above it. A feed that stalls past it ends readers. + #[test] + #[cfg(feature = "async")] + fn a_delivering_feed_holds_an_end_declared_ahead() { + let mut producer = track_producer("test", None); + producer.received(); + let grace = replay().max_delay; + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(5)).unwrap(); + for sequence in 0..3 { + elapse(&producer, grace / 2); + producer + .create_group(group::Info { sequence }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, sequence); + } + elapse(&producer, grace - Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().is_none(), "still within the grace"); + elapse(&producer, Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// Only a received copy waits for its tail: a local publisher's end below a hole ends + /// readers once the edge reaches it, as the publisher skipped the group. + #[test] + #[cfg(feature = "async")] + fn a_local_end_does_not_wait_for_a_tail() { + let mut producer = track_producer("test", None); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + + /// A group the publisher dropped is not in flight, so it holds no reader at the end. + #[test] + #[cfg(feature = "async")] + fn a_dropped_group_fills_the_tail() { + let mut producer = track_producer("test", None); + producer.received(); + let mut arrival = producer.subscribe(replay()); + producer.start_at(0).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); + producer + .create_group(group::Info { sequence: 2 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 2); + assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); + producer.drop_groups(0..2); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + /// A fetched copy of a group the live feed still owes never reaches an arrival-order /// reader, so it does not fill the hole: the reader waits for the live group. #[moq_clock::test] #[cfg(feature = "async")] async fn a_fetched_group_does_not_fill_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let dynamic = producer.dynamic(); let consumer = producer.consume(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let _high = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 1); @@ -11081,9 +11225,10 @@ mod test { #[cfg(feature = "async")] async fn an_abort_errors_a_pending_tail_short_of_a_group() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); let mut high = producer.create_group(group::Info { sequence: 1 }).unwrap(); high.finish().unwrap(); assert_eq!(arrival.assert_group().sequence, 1); @@ -11102,9 +11247,10 @@ mod test { #[cfg(feature = "async")] async fn an_abort_after_a_full_tail_ends_cleanly() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); for sequence in [1, 0] { producer .create_group(group::Info { sequence }) @@ -11125,9 +11271,10 @@ mod test { async fn an_abort_past_the_grace_ends_a_pending_tail_cleanly() { for (waited, ended) in [(ledger::GRACE / 2, false), (ledger::GRACE, true)] { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(None); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); for sequence in [0, 2] { producer .create_group(group::Info { sequence }) @@ -11151,9 +11298,10 @@ mod test { #[cfg(feature = "async")] fn an_evicted_group_still_fills_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); for sequence in [0, 1] { producer .create_group(group::Info { sequence }) @@ -11178,9 +11326,10 @@ mod test { #[cfg(feature = "async")] fn a_datagram_fills_a_pending_tail() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); - producer.finish_at_pending(Position::group(2)).unwrap(); + producer.finish_at(Position::group(2)).unwrap(); producer.insert_datagram(0, None, b"x".as_slice()).unwrap(); producer .create_group(group::Info { sequence: 1 }) @@ -11198,17 +11347,18 @@ mod test { #[cfg(feature = "async")] async fn an_end_after_the_highest_group_holds_the_reader() { let mut producer = track_producer("test", None); + producer.received(); let mut arrival = producer.subscribe(replay()); producer.start_at(0).unwrap(); let _high = producer.create_group(group::Info { sequence: 2 }).unwrap(); assert_eq!(arrival.assert_group().sequence, 2); assert!(arrival.recv_group().now_or_never().is_none()); - producer.finish_at_pending(Position::group(3)).unwrap(); + producer.finish_at(Position::group(3)).unwrap(); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); assert!( matches!( - producer.finish_at_pending(Position::group(2)), + producer.finish_at(Position::group(2)), Err(Error::ProtocolViolation) ), "a second end is refused" diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index f7ca6c2f63b..8e8a8b41f26 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -12,9 +12,9 @@ use std::{ops::Range, task::Poll, time::Duration}; -pub(crate) use crate::model::ledger::{GRACE, grace}; +pub(crate) use crate::ledger::{GRACE, grace}; use crate::{ - model::ledger::Ledger, + ledger::Ledger, time::{Deadline, Instant}, }; From 7af204028fd4961aa5919fd421ddf8744880d3d7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:09:16 -0700 Subject: [PATCH 05/22] refactor(net)!: request a pending start before accepting `track::Request::request_start(floor)` replaces the crate-private `resolving_start`: the accepted track's start stays pending at the requested floor until `Producer::start_at` resolves it, set before any reader sees the track. `Producer::request_start` stays private for a held copy's next subscription (capability gap). The IETF subscriber accepts a TRACK_STATUS copy idle in the same step, so no reader takes it as live in between, and reports the answer's Largest before resolving the start. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/subscriber.rs | 27 +++++----- rs/moq-net/src/lite/subscriber.rs | 2 +- rs/moq-net/src/model/origin.rs | 4 +- rs/moq-net/src/model/track.rs | 87 +++++++++++++++++++++++++------ 4 files changed, 86 insertions(+), 34 deletions(-) diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 0bd388813f2..22f4c24a890 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2994,10 +2994,9 @@ where self.remove_subscribe(request_id); return None; }; - let request = match live { - true => request.resolving_start(), - false => request, - }; + // Pending until the answer is written in below, so a relay serving the copy + // never reads the requested floor as where the feed starts. + let request = request.request_start(start.map(|start| start.group)); // Serves cache misses with a group FETCH. Registered before accepting, so a // miss queued meanwhile waits for it rather than failing for want of a handler. let dynamic = request.dynamic(); @@ -3005,13 +3004,6 @@ where } }; track.received(); - // A live join starts at the publisher's edge; an absolute one where it asked. With - // no Largest the join skips nothing, so every group is owed: a lower one's stream - // may still arrive after a higher one's. - let _ = match live { - true => track.start_at(largest.map_or(0, |largest| largest.group)), - false => track.start_at(start.map(|start| start.group)), - }; // Object IDs can start past zero or skip, while readers see frame ordinals, so only // the group carries over: its first frame is the edge a reader can count on. if let Some(largest) = largest { @@ -3020,6 +3012,13 @@ where frame: 0, }); } + // A live join starts at the publisher's edge; an absolute one where it asked. With + // no Largest the join skips nothing, so every group is owed: a lower one's stream + // may still arrive after a higher one's. This resolves the pending start. + let _ = match live { + true => track.start_at(largest.map_or(0, |largest| largest.group)), + false => track.start_at(start.map(|start| start.group)), + }; let mut fetching: Option = None; { let mut state = self.state.lock(); @@ -3864,10 +3863,10 @@ where tracing::debug!(broadcast = %self.origin.absolute(broadcast_path), track = %track_name, "track status known"); let dynamic = request.dynamic(); - let mut track = request.accept(accepted_info(&ok.properties)); + // Nothing feeds this copy live: what it caches is fetched, never the live edge. Idle + // from the accept, so no reader takes it as live in between. + let track = request.idle().accept(accepted_info(&ok.properties)); track.received(); - // Nothing feeds this copy live: what it caches is fetched, never the live edge. - track.set_idle(); Some(Idle { demand: track.demand(), track, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 6fd2904326b..d136ffdaa77 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -6496,7 +6496,7 @@ impl ServeLoop { // Lite-06+ resolves each subscription's start from its budget, so the floor // the SUBSCRIBE asks for is not where delivery begins until SUBSCRIBE_START says. let request = match serve.subscriber.version.resolves_start() { - true => request.resolving_start(), + true => request.request_start(None), false => request, }; let serving = request.accept(info); diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 1aa489242ce..fbaa343a490 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -8034,7 +8034,7 @@ mod tests { .await .expect("the front asked the source") .expect("request"); - let source = request.resolving_start().accept(crate::track::Info::timed()); + let source = request.request_start(None).accept(crate::track::Info::timed()); let mut group = source.create_group(0u64.into()).unwrap(); group.write_frame(crate::Timestamp::ZERO, b"snapshot".as_ref()).unwrap(); group.finish().unwrap(); @@ -8466,7 +8466,7 @@ mod tests { serving.lock().unwrap().push(group); } }); - let mut next = request.resolving_start().accept(crate::track::Info::timed()); + let mut next = request.request_start(None).accept(crate::track::Info::timed()); next.start_at(0).unwrap(); let mut next_group = next.create_group(0u64.into()).unwrap(); next_group.start_at(2).unwrap(); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 6982a2721b1..baeaa189f20 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2640,6 +2640,8 @@ impl Producer { /// earlier, and a narrowed subscription skips groups an earlier declaration /// still promised. Pass `None` to clear it, for demand at the live edge: /// its floor is unknown until the feed declares one. + /// + /// Resolves a start left pending by [`Request::request_start`]. pub fn start_at(&mut self, sequence: impl Into>) -> Result<()> { self.modify()?.set_start(sequence.into(), false); Ok(()) @@ -2713,12 +2715,10 @@ impl Producer { state.idle_newest.filter(|_| state.feed == Feed::Idle) } - /// Declare the floor a subscription asked for while the serving session has yet to - /// resolve its start: nothing below `sequence` arrives, exactly as [`Self::start_at`], - /// but [`Subscriber::poll_start`] keeps waiting until a later [`Self::start_at`] - /// resolves it. + /// [`Request::request_start`] for a copy already accepted, which a held copy's next + /// subscription asks for again. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md + // private: capability gap pub(crate) fn request_start(&mut self, sequence: Option) -> Result<()> { self.modify()?.set_start(sequence, true); Ok(()) @@ -6539,9 +6539,12 @@ pub struct Request { // unless this request was reserved on a tagged broadcast. stats: stats::Scope, - // The serving session resolves the start of each subscription itself, so the - // accepted track's start is unknown until it says (see [`Self::resolving_start`]). - resolving_start: bool, + // The floor the accepted track's start is pending at, until the source resolves it + // (see [`Self::request_start`]). + requested_start: Option>, + + // Whether the accepted track starts idle; see [`Self::idle`]. + idle: bool, // Served from a front's routes; see [`Self::routes`]. routes: Option, @@ -6561,7 +6564,8 @@ impl Request { alive, _dynamic: dynamic, stats: stats::Scope::default(), - resolving_start: false, + requested_start: None, + idle: false, routes: None, } } @@ -6574,14 +6578,25 @@ impl Request { self } - /// Mark the track as served by a session that resolves each subscription's start - /// (lite-06+), so [`Subscriber::poll_start`] waits for its declaration instead of - /// reading the requested floor as the start. Applied atomically with - /// [`Self::accept`], before any reader can see the track. + /// Accept the track with its start pending at `floor`, the first group its source was + /// asked for (`None` for the live edge), until the source says where its feed starts + /// with [`Producer::start_at`]. + /// + /// Nothing below `floor` arrives, as with [`Producer::start_at`], and groups are read + /// as they arrive, but a relay serving the track waits for the resolved start before + /// declaring its own. Applied atomically with [`Self::accept`], before any reader can + /// see the track. + pub fn request_start(mut self, floor: impl Into>) -> Self { + self.requested_start = Some(floor.into()); + self + } + + /// Accept the track idle, as a copy that no live feed fills yet: readers get nothing + /// from it until the feed goes live. Applied atomically with [`Self::accept`]. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/ingest.md - pub(crate) fn resolving_start(mut self) -> Self { - self.resolving_start = true; + // private: capability gap + pub(crate) fn idle(mut self) -> Self { + self.idle = true; self } @@ -6668,7 +6683,12 @@ impl Request { // tolerate it: the Producer we hand back simply can't write. if let Ok(mut state) = self.state.write() { state.accept(info.clone()); - state.start_pending = self.resolving_start; + if let Some(floor) = self.requested_start { + state.set_start(floor, true); + } + if self.idle { + state.set_idle(); + } state.routes = self.routes; } // Accepting the request creates the track producer: count it as one ingress @@ -10128,6 +10148,39 @@ mod test { ); } + /// A start requested before the accept holds a reader of the start from the moment the + /// track is visible, while its groups are read as they arrive, until the source + /// resolves it. + #[test] + #[cfg(feature = "async")] + fn a_requested_start_waits_for_the_source() { + let waiter = kio::Waiter::noop(); + let request = Request::new(Arc::new(broadcast::Info::default()), "test"); + let consumer = request.consume(); + let mut producer = request.request_start(2).accept(None); + let mut subscriber = consumer.subscribe(None).now_or_never().unwrap().unwrap(); + assert!(subscriber.poll_start(&waiter).is_pending(), "the floor is not the start"); + + // Nothing below the floor is waited for, and a group above it reads at once. + producer.create_group(group::Info { sequence: 3 }).unwrap().finish().unwrap(); + assert_eq!(subscriber.assert_group().sequence, 3); + assert!(subscriber.poll_start(&waiter).is_pending()); + + producer.start_at(3).unwrap(); + assert_eq!(subscriber.poll_start(&waiter), Poll::Ready(Some(3))); + } + + /// A copy accepted idle is never readable as live in between. + #[test] + fn an_idle_accept_is_not_live() { + let request = Request::new(Arc::new(broadcast::Info::default()), "test"); + let consumer = request.consume(); + let mut producer = request.idle().accept(None); + assert!(!consumer.is_live(), "idle from the accept"); + producer.set_live(None); + assert!(consumer.is_live()); + } + /// A fetched group installs metadata but never accepts the track's live feed. #[test] fn a_fetch_only_cache_is_not_live() { From 3d75830413f0e22e7192da17eecf17fb893bdb52 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:16:52 -0700 Subject: [PATCH 06/22] refactor(net)!: mirror public ingest in @moq/net and document the migration `Track.Producer.received()` and `dropGroups()` replace the internal hooks, the IETF subscriber accepts at SUBSCRIBE_OK with the answer's Largest reported before the start resolves, and a frameless group no longer counts as a successor. MIGRATE.md covers the Rust and JS breaking changes. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 5 +++ js/net/src/group.ts | 1 + js/net/src/ietf/subscriber.test.ts | 40 +++++++++++--------- js/net/src/ietf/subscriber.ts | 51 +++++++++++++++---------- js/net/src/internal.ts | 26 +++---------- js/net/src/lite/subscriber.ts | 4 +- js/net/src/track.test.ts | 23 ++++++------ js/net/src/track.ts | 60 +++++++++++++++++++++++------- rs/moq-net/MIGRATE.md | 37 ++++++++++++++++++ 9 files changed, 162 insertions(+), 85 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 4d7076305f6..abadbce09bf 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### A frameless group is not a successor (#6111) + +A group followed by a frameless one is judged stale against the next group that has a frame, where the frameless group used to count. +`Track.Producer.received()` marks a track as written from a peer, and `Track.Producer.dropGroups(start, end)` marks groups the peer said it skipped. + ### `largest()` reports within a reader's `setGroups` bounds `Track.Subscriber.largest()` and `Track.Ordered.largest()` report the track's largest only while it is within the bounds set with `setGroups` or `withGroups`, where they used to ignore the bounds. diff --git a/js/net/src/group.ts b/js/net/src/group.ts index b2f6274f3be..da4cf957d87 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -520,6 +520,7 @@ export class Consumer { group.#state.unverified = true; }; hooks.groupArrived = (group) => group.#state.arrived; + hooks.groupStarted = (group) => group.#state.total.peek() > 0 || group.#state.closed.peek() !== undefined; hooks.arriveGroup = (group, at) => { group.#state.arrived = at; }; diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index d18e12dc1cb..458d9feb013 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1236,15 +1236,15 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u const subscriber = new Subscriber({ session }); const opening = spyOn(session, "openBi"); const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; + const make = hooks.makeRequest; let returned: track.Subscriber | undefined; const resumed = Promise.withResolvers(); const waiting = Promise.withResolvers(); const unwanted = demandUtil.unwanted; const unwantedSpy = spyOn(demandUtil, "unwanted"); - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { - const producer = pending(request); - const demand = producer.demand(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const demand = request.demand(); let returnedOnce = false; unwantedSpy.mockImplementation(async (watched) => { if (watched !== demand) return unwanted(watched); @@ -1267,7 +1267,7 @@ test.each(["acceptance", "timeout"])("returning demand preserves pending setup u return used; }); }); - return producer; + return request; }); const first = broadcast.track("video").subscribe(); // Restore real timers even if an injection promise outlives the test. @@ -1314,13 +1314,13 @@ test("setup abandonment closes before a queued viewer can attach", async () => { const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session }); const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; + const make = hooks.makeRequest; const resumed = Promise.withResolvers(); const unwanted = demandUtil.unwanted; const unwantedSpy = spyOn(demandUtil, "unwanted"); - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { - const producer = pending(request); - const demand = producer.demand(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const demand = request.demand(); unwantedSpy.mockImplementationOnce(async (watched) => { await unwanted(watched); const peek = demand.wanted.peek.bind(demand.wanted); @@ -1336,7 +1336,7 @@ test("setup abandonment closes before a queued viewer can attach", async () => { return used; }); }); - return producer; + return request; }); const first = broadcast.track("video").subscribe(); let returned: track.Subscriber | undefined; @@ -1381,13 +1381,19 @@ test("abandonment cancels once and a late acceptance cannot capture a reused ali peer.reader.version = version; peer.writer.version = version; const broadcast = subscriber.consume(Path.from("room")); - const pending = hooks.pendingTrackProducer; - let producer: track.Producer | undefined; + const make = hooks.makeRequest; let oldRequest: track.Request | undefined; - const captured = spyOn(hooks, "pendingTrackProducer").mockImplementationOnce((request) => { + // The error the abandoned request is rejected with. + const rejected = Promise.withResolvers(); + const captured = spyOn(hooks, "makeRequest").mockImplementationOnce((options) => { + const request = make(options); + const reject = request.reject.bind(request); + spyOn(request, "reject").mockImplementation((err) => { + rejected.resolve(err); + reject(err); + }); oldRequest = request; - producer = pending(request); - return producer; + return request; }); const decoded = Promise.withResolvers(); const release = Promise.withResolvers(); @@ -1403,13 +1409,13 @@ test("abandonment cancels once and a late acceptance cannot capture a reused ali try { expect(await peer.reader.u53()).toBe(Subscribe.id); const request = await Subscribe.decode(peer.reader, version); - if (!producer || !oldRequest) throw new Error("missing pending track"); + if (!oldRequest) throw new Error("missing pending track"); const accepted = spyOn(oldRequest, "accept"); await peer.writer.u53(SubscribeOk.id); await new SubscribeOk({ requestId: request.requestId, trackAlias: ALIAS }).encode(peer.writer, version); await decoded.promise; first.close(); - expect(await producer.closed).toBeInstanceOf(Error); + expect(await rejected.promise).toBeInstanceOf(Error); expect(await peer.reader.u53()).toBe(Unsubscribe.id); expect((await Unsubscribe.decode(peer.reader, version)).requestId).toBe(request.requestId); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index bf621937bc1..42249bd8103 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -100,6 +100,8 @@ type Subscription = { // before the setup promise settles. type SubscribeSetupState = { stream?: Stream; + // The accepted subscription, which a registered alias names. + subscription?: Subscription; registeredAlias?: bigint; /** * Whether the caller has given up. Setup checks this once the stream exists so a request @@ -800,27 +802,24 @@ export class Subscriber { // Keep the request pending until SUBSCRIBE_OK supplies immutable track metadata. // Group streams already wait on the alias, so early data stays behind this response. - const producer = hooks.pendingTrackProducer(request); - hooks.receiveTrack(producer); - const subscription: Subscription = { track: producer, tail: new Tail() }; - // Open the stream and wait for SUBSCRIBE_OK under a timeout. State // flows back via `state` so the timeout path can clean up the stream // and any registration if setup eventually finishes. const state: SubscribeSetupState = {}; const deadline = new Deadline(); - const setup = this.#openSubscribe(state, broadcast, request, subscription, requestId, deadline, epoch); + const setup = this.#openSubscribe(state, broadcast, request, requestId, deadline, epoch); // The publisher can be serving before it answers, so waiting only on the response // would miss the local side going away and leave it serving a track nobody reads. // Demand returning before we commit is not abandonment, matching the serving loop. - const demand = producer.demand(); + const demand = request.demand(); const waitAbandoned = async (): Promise => { await demandAbandoned(demand); return null; }; let stream: Stream; + let subscription: Subscription; let trackAlias: bigint; // The SUBSCRIBER_PRIORITY the request went out with. let priority: number; @@ -833,6 +832,7 @@ export class Subscriber { const result = await untilAborted(race([accepted, waitAbandoned()]), valid); if (result !== null) { stream = result.stream; + subscription = result.subscription; trackAlias = result.alias; priority = result.priority; maxAge = result.maxAge; @@ -858,7 +858,11 @@ export class Subscriber { const cleanup = async (afterSetup: boolean) => { state.cancelled = true; - if (state.registeredAlias !== undefined && this.#aliases.retire(state.registeredAlias, subscription)) { + if ( + state.registeredAlias !== undefined && + state.subscription && + this.#aliases.retire(state.registeredAlias, state.subscription) + ) { this.#timescales.delete(state.registeredAlias); } @@ -892,6 +896,7 @@ export class Subscriber { return; } + const producer = subscription.track; let disposeGrant: Dispose | undefined; try { // Which terminal fired decides whether we owe the publisher a cancellation, so @@ -1124,11 +1129,10 @@ export class Subscriber { state: SubscribeSetupState, broadcast: Path.Valid, request: track.Request, - subscription: Subscription, requestId: bigint, deadline: Deadline, epoch: Epoch.Valid | undefined, - ): Promise<{ stream: Stream; alias: bigint; priority: number; maxAge?: number }> { + ): Promise<{ stream: Stream; subscription: Subscription; alias: bigint; priority: number; maxAge?: number }> { const version = this.#session.version; const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16; @@ -1199,29 +1203,32 @@ export class Subscriber { if (maxCacheDuration !== undefined && maxCacheDuration > BigInt(Number.MAX_SAFE_INTEGER)) { throw new RangeError("max cache duration exceeds safe milliseconds"); } - request.accept({ + if (ok.largest && ok.largest.groupId > BigInt(Number.MAX_SAFE_INTEGER)) { + throw new RangeError("largest group exceeds safe integers"); + } + const producer = request.accept({ // No TIMESCALE (always so on drafts 14-16, which can't carry it) means no timeline, // and the track must not claim one when served onward. timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), }); - if (ok.largest && ok.largest.groupId > BigInt(Number.MAX_SAFE_INTEGER)) { - throw new RangeError("largest group exceeds safe integers"); + producer.received(); + const subscription: Subscription = { track: producer, tail: new Tail() }; + state.subscription = subscription; + if (ok.largest) { + // Object IDs can start past zero or skip, while readers see frame ordinals, so only + // the group carries over: its first frame is the edge a reader can count on. + hooks.reportedLargest(producer, { group: Number(ok.largest.groupId), frame: 0 }); } // The live join starts at the publisher's edge, whatever floor the demand asked for. // With no Largest it skips nothing, so every group is owed: a lower one's stream may // still arrive after a higher one's. const groups = request.subscription.groups; - hooks.startTrack(subscription.track, { + hooks.startTrack(producer, { start: ok.largest ? Number(ok.largest.groupId) : 0, requested: groups?.start === undefined ? undefined : groupBounds(groups).start, }); - if (ok.largest) { - // Object IDs can start past zero or skip, while readers see frame ordinals, so only - // the group carries over: its first frame is the edge a reader can count on. - hooks.reportedLargest(subscription.track, { group: Number(ok.largest.groupId), frame: 0 }); - } try { this.#aliases.set(ok.trackAlias, subscription, { broadcast, name: request.name, epoch }); @@ -1237,7 +1244,13 @@ export class Subscriber { throw err; } state.registeredAlias = ok.trackAlias; - return { stream: state.stream, alias: ok.trackAlias, priority: msg.subscriberPriority, maxAge: msg.maxAge }; + return { + stream: state.stream, + subscription, + alias: ok.trackAlias, + priority: msg.subscriberPriority, + maxAge: msg.maxAge, + }; } /** diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index c342ed8218a..14be5993505 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -365,17 +365,8 @@ export const hooks: { * `track.ts`. */ startTrack: (producer: Producer, served: { start: number; requested?: number }) => void; - // pending: /quest/m1/public-model/ingest.md - /** - * Mark a track as a session's copy of a remote one: its groups are never checked for a - * rewind, since a received timestamp may not be media time. - */ - receiveTrack: (producer: Producer) => void; /** Mint a track {@link Request}; assigned by `track.ts`. */ makeRequest: (options: TrackRequestOptions) => Request; - // pending: /quest/m1/public-model/ingest.md - /** Access the existing producer while a request awaits immutable wire metadata. */ - pendingTrackProducer: (request: Request) => Producer; /** Have a producer write through a broadcast's sequence namespace for its name. */ bindSequence: (producer: Producer, sequence: TrackSequence) => void; /** The newest frame a producer's cache holds, read without subscribing; assigned by `track.ts`. */ @@ -391,9 +382,6 @@ export const hooks: { bufferedLargest: (subscriber: Subscriber) => Location | undefined; /** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */ groupProgress: (group: GroupProducer, fn: (total: number) => void) => Dispose; - // pending: /quest/m1/public-model/ingest.md - /** Record sequences `[start, end)` an upstream publisher explicitly gave up. */ - dropTrackGroups: (producer: Producer, start: number, end: number) => void; // pending: /quest/m1/public-model/serve.md /** * Take the next group the subscriber's cursor allows, without waiting; assigned by `track.ts`. @@ -473,6 +461,8 @@ export const hooks: { groupLatest: (group: GroupConsumer) => Timestamp | undefined; /** Return when a group joined its track at this hop, on the installed clock. */ groupArrived: (group: GroupConsumer) => Instant; + /** Whether a group counts as content: its first frame landed, or it ended. */ + groupStarted: (group: GroupConsumer) => boolean; /** Record when a track's mirror of a group joined that track at this hop. */ arriveGroup: (group: GroupConsumer, at: Instant) => void; /** Keep applying a subscription's drift policy after it hands a group out. */ @@ -497,9 +487,6 @@ export const hooks: { /** Name the epoch of the route an origin resolved a broadcast handle through. */ stampEpoch: (target: BroadcastConsumer, epoch: Epoch.Valid | undefined) => void; } = { - receiveTrack: () => { - throw new Error("track.ts not loaded"); - }, endTrack: () => { throw new Error("track.ts not loaded"); }, @@ -518,9 +505,6 @@ export const hooks: { makeRequest: () => { throw new Error("track.ts not loaded"); }, - pendingTrackProducer: () => { - throw new Error("track.ts not loaded"); - }, bindSequence: () => { throw new Error("track.ts not loaded"); }, @@ -539,9 +523,6 @@ export const hooks: { groupProgress: () => { throw new Error("group.ts not loaded"); }, - dropTrackGroups: () => { - throw new Error("track.ts not loaded"); - }, tryRecvGroup: () => { throw new Error("track.ts not loaded"); }, @@ -623,6 +604,9 @@ export const hooks: { groupArrived: () => { throw new Error("group.ts not loaded"); }, + groupStarted: () => { + throw new Error("group.ts not loaded"); + }, expireGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 4a1cacc8009..83f68cdc319 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -863,7 +863,7 @@ export class Subscriber { timescale.set(0); drainOk = true; } - hooks.receiveTrack(producer); + producer.received(); // Register before opening SUBSCRIBE so a racing GROUP stream finds the entry. const entry: SubscribeEntry = { @@ -1253,7 +1253,7 @@ export class Subscriber { } } else if ("drop" in resp) { entry.tail.account(resp.drop.start, resp.drop.end + 1); - hooks.dropTrackGroups(entry.track, resp.drop.start, resp.drop.end + 1); + entry.track.dropGroups(resp.drop.start, resp.drop.end + 1); } } } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index e5929cce134..3be802e8524 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -630,10 +630,10 @@ test("the latency budget skips a buffered timeline on either cursor", async () = expect((await replay.nextGroup())?.sequence).toBe(2); }); -// An unstamped immediate successor leaves a group's reach unbounded: a later stamped -// group proves nothing about where the successor will begin, and shrinking the bound -// is the unsafe direction. -test("an unstamped immediate successor leaves reach unbounded", async () => { +// A frameless successor is not content, so the next started group bounds the group before +// it. That bound is sound: the frameless group's first frame is checked to start at or below +// the next group's, so the true reach can only be earlier. +test("a frameless successor leaves the next started group as the bound", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); // Any budget, so only media time judges: the wall clock barely moves here. const track = producer.subscribe({ maxDelay: Milli(500) }); @@ -643,9 +643,8 @@ test("an unstamped immediate successor leaves reach unbounded", async () => { producer.writeFrame({ payload: enc.encode("2"), timestamp: Timestamp.fromMillis(10_000) }); producer.writeFrame({ payload: enc.encode("3"), timestamp: Timestamp.fromMillis(11_000) }); - // Group 1's reach is group 2's start, a second behind the edge: stale. - // Group 0's reach is unknown until group 1 presents its first frame, so it is kept. - expect(drain(track)).toEqual([0, 2, 3]); + // Groups 0 and 1 both reach at most group 2's start, a second behind the edge: stale. + expect(drain(track)).toEqual([2, 3]); }); // Groups can arrive out of sequence order; the immediate successor bounds reach even when it @@ -2697,7 +2696,7 @@ test("an explicit start floors an untimed track", () => { test("explicit and producer-cut drops survive outside the group cache", async () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); - hooks.dropTrackGroups(producer, 3, 4); + producer.dropGroups(3, 4); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 3, end: 4 }); const group = new GroupProducer(4); @@ -2713,7 +2712,7 @@ test("explicit and producer-cut drops survive outside the group cache", async () test("a drop below the window is reported once the window lowers to it", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000), groups: { start: { included: 5 } } }); - hooks.dropTrackGroups(producer, 2, 3); + producer.dropGroups(2, 3); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); hooks.replaceGroups(reader, { start: { included: 0 } }); @@ -2744,11 +2743,11 @@ test("a re-created cut group is served, not dropped", async () => { test("a wide drop is held and reported as one run", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); - hooks.dropTrackGroups(producer, 2, 2 ** 40); + producer.dropGroups(2, 2 ** 40); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 2 ** 40 }); // A wider drop reports only what this cursor has not reported yet. - hooks.dropTrackGroups(producer, 1, 2 ** 40 + 2); + producer.dropGroups(1, 2 ** 40 + 2); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 1, end: 2 }); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2 ** 40, end: 2 ** 40 + 2 }); expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); @@ -3239,7 +3238,7 @@ for (const abort of [false, true]) { const next = reader.recvGroup(); expect(await settled(next)).toBe(false); - hooks.dropTrackGroups(producer, 0, 2); + producer.dropGroups(0, 2); if (abort) producer.close(new Error("dropped")); expect(await next).toBeUndefined(); if (abort) expect(await reader.closed).toBeNull(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index d6f11592e30..d473f1c2e83 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -290,7 +290,6 @@ export class Request { static { hooks.makeRequest = (options) => new Request(options); - hooks.pendingTrackProducer = (request) => request.#producer; } /** Watch the subscribers waiting for this request. */ @@ -730,9 +729,6 @@ export class Producer { producer.#served = served; producer.#owe(); }; - hooks.receiveTrack = (producer) => { - producer.#remote = true; - }; // Anything written before binding still counts, so the namespace never goes backwards. bindProducerSequence = (producer, sequence) => { const own = producer.#sequence; @@ -766,7 +762,25 @@ export class Producer { hooks.arriveGroup(mirror, entry.arrived); return mirror; }; - hooks.dropTrackGroups = (producer, start, end) => producer.#drop(start, end); + } + + /** + * Mark this track as a copy received from a remote publisher, before writing to it, + * mirroring the Rust `received`. Its groups are never checked for a timestamp rewind, + * which only a local publisher's writes refuse, since a received timestamp may not be + * media time. + */ + received(): void { + this.#remote = true; + } + + /** + * Record that the publisher gave up the groups `[start, end)`, mirroring the Rust + * `drop_groups`: none will arrive, so a reader waiting on one moves past it, the declared + * end does not wait for them, and a relay serving this track forwards the drop. + */ + dropGroups(start: number, end: number): void { + this.#drop(start, end); } #drop(start: number, end: number): void { @@ -1648,21 +1662,37 @@ export class Subscriber { }; } - // The group after `sequence` that bounds it: the first servable one below `end`, - // stamped or not, empty or not. + // The group after `sequence` that bounds it: the first servable one below `end` that + // counts as content (its first frame landed, or it ended), stamped or not. // // Its first timestamp is the furthest presentation time `sequence` could still reach. // An upper bound, deliberately: a frame's duration is not on the wire, so a group's own - // last timestamp says where it starts presenting, not where it ends. The bound is the - // *immediate* successor's start, so an unstamped successor leaves the reach unbounded - // until it presents a frame. + // last timestamp says where it starts presenting, not where it ends. A group whose header + // landed without a frame is not content yet, so the next one is the bound; an unstamped + // successor leaves the reach unbounded. #successor(sequence: number, end?: number): GroupConsumer | undefined { + return this.#after(sequence, end, hooks.groupStarted); + } + + // The group after `sequence` that starts its wall clock: like {@link #successor}, but + // counting a group before its first frame. Its header arrived, so a relay ages the group + // before it as the origin does, even if its first frame never comes. + #arrival(sequence: number, end?: number): GroupConsumer | undefined { + return this.#after(sequence, end, () => true); + } + + // The first servable group after `sequence` below `end` that `counts`. + #after( + sequence: number, + end: number | undefined, + counts: (group: GroupConsumer) => boolean, + ): GroupConsumer | undefined { const timeline = this.#state.timeline; for (let i = timelineIndex(timeline, sequence + 1); i < timeline.length; i++) { const successor = timeline[i]; if (end !== undefined && successor.sequence >= end) break; if (successor.closed.peek() instanceof Error) continue; - return successor; + if (counts(successor)) return successor; } return undefined; } @@ -1695,13 +1725,15 @@ export class Subscriber { // The drift verdict for `sequence` by its successor alone, whether or not this track holds it. #staleAt(sequence: number, drift: Drift, wake = false): boolean { - const successor = this.#successor(sequence, drift.end); - if (!successor) return false; + const arrival = this.#arrival(sequence, drift.end); + if (!arrival) return false; // Plain arithmetic: an unenforced budget is infinite, which no duration brand holds. - const deadline = hooks.groupArrived(successor) + drift.budget * 1_000_000; + const deadline = hooks.groupArrived(arrival) + drift.budget * 1_000_000; if (now() >= deadline) return true; if (wake) this.#wakeAt(deadline); + const successor = this.#successor(sequence, drift.end); + if (!successor) return false; const reach = hooks.groupTimestamp(successor)?.asMillis(); return ( drift.presentation !== undefined && diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index f86f29361e9..91e57d55311 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,43 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Frame writers own their group (#6111) + +`group::Producer::create_frame` now takes the writer by value and returns an owned `frame::Producer` with no lifetime. +`frame::Producer::finish` hands the group writer back, and `frame::Producer::group()` returns `&group::Producer` instead of a `group::Info` copy. +A frame the group refuses (closed, or past its size) now aborts the group. + +```rust +// Before +let mut frame = group.create_frame(info)?; +frame.write(payload)?; +frame.finish()?; +// After +let mut frame = group.create_frame(info)?; +frame.write(payload)?; +group = frame.finish()?; +``` + +A caller that holds the group behind `&mut` can write a whole frame with `write_frame` instead. + +### A received track's end waits for groups in flight (#6111) + +Call `track::Producer::received()` before writing what a peer sends into a track, then declare the peer's end with `finish_at`. +On a received copy, readers wait at a hole below that end for the subscription's max delay (or one second) in case its group is still in flight; `drop_groups(range)` marks groups the peer said it skipped, so readers stop waiting for them. +`finish_at` now accepts a repeat of the same end and a refinement within the last group; any other second end fails with `Error::ProtocolViolation`. + +`track::Request::request_start(floor)` leaves an accepted copy's start pending at `floor` until `track::Producer::start_at` resolves it, for a subscriber whose peer reports the start after accepting. + +### A frameless group is not the live edge (#6111) + +Every group reaches readers as soon as it is created, but the live edge, `largest()`, and the judgment of whether a group was succeeded count a group only once its first frame opens or it finishes. +A group followed by a frameless one is judged against the next group that has a frame. + +### `track::Producer::abort` aborts open groups (#6111) + +Aborting a track now aborts its unfinished groups with the same error, so their readers end with it and their writers fail. +`track::Producer::close`, `track::Producer::received`, and `group::Producer::info` are now public. + ### Each group has one writer (#6020) `group::Producer` no longer implements `Clone`: keep one writer and move it by value between owners, or put it behind a lock when several callers write it. From af1e7a0be62a3d6af4d740b9f0c8cabade223895 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:19:37 -0700 Subject: [PATCH 07/22] quest: record the received end and resolved start in public ingest Co-Authored-By: Claude Opus 5.5 --- quest/m1/public-model/ingest.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md index 3c328a23b16..788fb6fed6e 100644 --- a/quest/m1/public-model/ingest.md +++ b/quest/m1/public-model/ingest.md @@ -127,6 +127,15 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: timer: the model folds a gap only on a write, so the session still settles the tail with `set_tail_pending(false)`. The shape is this quest's to settle. + - Landed in #6111: a plain `finish_at` on a `received()` copy. The model + holds readers at a hole below the end until the grace passes on the + pool's wall clock, counting `drop_groups` as accounted and keeping the + gap above the latest arrival open while groups still land. + `finish_at_pending` and `set_tail_pending` go, `demand_arrivals` folds + into the start declaration, `drop_groups` is public, and the ledger + moves out of `model/`. The session no longer settles early when every + stream is in, so an IETF publisher that skips group IDs without a + drop makes readers wait out the grace at END_OF_TRACK. - **Session end** (`track::Producer::close`, `abort_session`; both subscribers): public. Fold `abort_session` into the public `abort` (abort open groups too) unless the implementer finds a reader-visible difference, @@ -148,6 +157,15 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: TRACK_STATUS `accept` → `set_idle` race with it. Regression test: accept, replay a retained group on the same task, and SUBSCRIBE_OK carries Largest Location on a multi-thread runtime over many runs. + - Landed in #6111: public `track::Request::request_start(floor)`, applied + atomically with `accept`, gates `poll_start` (the lite publisher's + resolved start) until `start_at`. The IETF TRACK_STATUS race is fixed + with a crate-private `Request::idle()` applied in the same accept. + - Still open: the public way to accept idle, replay, then go live. Gating + `poll_live` on a pending start breaks lite-06 relays (no SUBSCRIBE_OK, so + the start resolves only with the first served group). Options: public + `Request::idle()` plus `Producer::set_live`; or `request_start` also + gating `poll_live`, accepting the lite-06 change. - **Idle copy** (`track::Producer::set_idle`, `set_live`, `is_live`, `idle_newest`, `track::IDLE_LINGER`, `poll_past`; lite subscriber, `set_idle`, `set_live`, and `poll_past` also IETF). They keep a lingering copy's cache from serving stale groups @@ -175,6 +193,8 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: check skips it (#5803). It goes public with the other ingest calls, unless [time provenance](/quest/m1/lite-time-provenance.md) makes received timestamps checkable first. + Public in #6111 (JS `Track.Producer.received()`), and it also arms the + received-end grace above. - Passthrough, stay private and marked: `group::Producer::wire`, `set_wire`, `mark_gap`, `set_end_object`, `group::Wire`, the `object` and `datagram` modules, `track::Producer::insert_wire_datagram`, @@ -192,6 +212,9 @@ JS items (`js/net/src/`): mirror each Rust decision under the same name. an unaccepted request so objects landing before SUBSCRIBE_OK are kept. Replace it with the resolved-start shape above: the request is accepted with its start pending, so early data has a public producer to land in. + Done in #6111: the IETF subscriber holds the request's demand before + SUBSCRIBE_OK and accepts at the answer, so the hook goes. JS has no + pending-start gate; its lite publisher does not wait on one. - `Group.Producer.mirror` (`@internal`, lite subscriber fetch coalescing): moved to the deferred quest, which waits on Model ranges and JS track handover. From ad502036127ffc52657e5d2f4c8934b18ef5794f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:32:05 -0700 Subject: [PATCH 08/22] test(net): cover the public ingest calls Unit tests for close dropping an unpulled open group, abort ending a pulled open group and failing its writer, a received copy skipping the rewind check, group::Producer::info, an open frame reading its group, and poll_past waking a real waiter on a later group's first frame. Formats this PR's own test code and moves a misplaced doc comment back onto poll_recv_group. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/frame.rs | 4 +- rs/moq-net/src/model/group.rs | 40 ++++++++-- rs/moq-net/src/model/resume.rs | 54 ++++++------- rs/moq-net/src/model/track.rs | 142 +++++++++++++++++++++++++++------ 4 files changed, 180 insertions(+), 60 deletions(-) diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index 964c3152a55..96332b5f2e4 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -185,7 +185,9 @@ impl Default for Remaining { impl std::fmt::Debug for Budget { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - f.debug_tuple("Budget").field(&self.0.0.load(Ordering::Relaxed)).finish() + f.debug_tuple("Budget") + .field(&self.0.0.load(Ordering::Relaxed)) + .finish() } } diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 001703b5e2b..0df05e748d0 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -4023,9 +4023,7 @@ mod test { let before = pool.used(); let observing = producer.handle(); - let mut frame = producer - .create_frame(sized(MAX_CACHE_BYTES)) - .unwrap(); + let mut frame = producer.create_frame(sized(MAX_CACHE_BYTES)).unwrap(); assert_eq!(pool.used(), before, "the declared size was charged"); frame.write_deferred(Bytes::from(vec![0u8; 100])).unwrap(); @@ -4042,6 +4040,38 @@ mod test { assert!(pool.used() <= before); } + /// A writer names the group it fills. + #[test] + fn info_names_the_group() { + let producer = Info { sequence: 7 }.produce(); + assert_eq!(producer.info(), Info { sequence: 7 }); + } + + /// An open frame still reads its group: which one it is, how many frames it holds, + /// and whether anyone reads it. Finishing the frame hands the same writer back. + #[test] + #[cfg(feature = "async")] + fn an_open_frame_reads_its_group() { + let mut producer = Info { sequence: 3 }.produce(); + producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"a")).unwrap(); + let mut consumer = producer.consume(); + + let mut frame = producer.create_frame(sized(1)).unwrap(); + let group = frame.group(); + assert_eq!(group.info().sequence, 3); + assert_eq!(group.frame_count(), 2, "the open frame counts"); + assert!(group.demand().is_used()); + assert!(group.poll_closed(&kio::Waiter::noop()).is_pending()); + + frame.write(Bytes::from_static(b"b")).unwrap(); + let mut producer = frame.finish().unwrap(); + producer.finish().unwrap(); + let mut read = || consumer.read_frame().now_or_never().unwrap().unwrap(); + assert_eq!(read().unwrap().payload, Bytes::from_static(b"a")); + assert_eq!(read().unwrap().payload, Bytes::from_static(b"b")); + assert!(read().is_none()); + } + #[test] fn refused_frame_aborts_with_its_error() { let producer = Info { sequence: 0 }.produce(); @@ -4065,9 +4095,7 @@ mod test { let before = pool.used(); let observing = producer.handle(); - let mut frame = producer - .create_frame(sized(300)) - .unwrap(); + let mut frame = producer.create_frame(sized(300)).unwrap(); frame.write(Bytes::from(vec![0u8; 100])).unwrap(); frame.write_deferred(Bytes::from(vec![0u8; 200])).unwrap(); let _producer = frame.finish().unwrap(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 3044c35ab7d..b8d41b46a84 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -3242,15 +3242,15 @@ mod test { .unwrap(); let mut frame = group .create_object(crate::frame::Header { - info: crate::frame::Info { - size: 1, - timestamp: Some(ts(0)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id: 6, - properties: Default::default(), - })), - }) + info: crate::frame::Info { + size: 1, + timestamp: Some(ts(0)), + }, + fields: Some(Arc::new(super::super::object::Fields { + id: 6, + properties: Default::default(), + })), + }) .unwrap(); frame.write(bytes::Bytes::from_static(b"a")).unwrap(); let group = frame.finish().unwrap(); @@ -3261,15 +3261,15 @@ mod test { assert_eq!(a.consume().resume_position(), Some(Position::group(1))); let mut partial = group .create_object(crate::frame::Header { - info: crate::frame::Info { - size: 2, - timestamp: Some(ts(1)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id: 8, - properties: Default::default(), - })), - }) + info: crate::frame::Info { + size: 2, + timestamp: Some(ts(1)), + }, + fields: Some(Arc::new(super::super::object::Fields { + id: 8, + properties: Default::default(), + })), + }) .unwrap(); partial.write(bytes::Bytes::from_static(b"b")).unwrap(); let mut chunks = reading.next_frame().now_or_never().unwrap().unwrap().unwrap(); @@ -3305,15 +3305,15 @@ mod test { for &(id, payload) in objects { let mut frame = group .create_object(crate::frame::Header { - info: crate::frame::Info { - size: payload.len() as u64, - timestamp: Some(ts(id)), - }, - fields: Some(Arc::new(super::super::object::Fields { - id, - properties: Default::default(), - })), - }) + info: crate::frame::Info { + size: payload.len() as u64, + timestamp: Some(ts(id)), + }, + fields: Some(Arc::new(super::super::object::Fields { + id, + properties: Default::default(), + })), + }) .unwrap(); frame.write(bytes::Bytes::from_static(payload)).unwrap(); group = frame.finish().unwrap(); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index baeaa189f20..bdff083cd76 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -17,8 +17,8 @@ use crate::{Error, Result, Timescale, Timestamp, coding}; use crate::{broadcast, cache, group, stats}; use super::delivered::Delivered; -use crate::ledger::{self, Ledger}; use super::{Datagram, Requests}; +use crate::ledger::{self, Ledger}; use super::Cap; pub use super::subscription::{Anchor, Order, Position, Range, Subscription}; @@ -785,17 +785,17 @@ impl TrackState { } } - /// Find the next live group at or after `index` in arrival order. - /// - /// Returns the group and its absolute index so the consumer can advance past it. - /// The cached producer rather than a consumer: `consume` reads the clock and can - /// take the group's own lock, which the caller does once the track guard is gone. /// Whether readers may take from the cache: it reflects the live feed, or the track /// ended, which makes the cache the whole of it. fn readable(&self) -> bool { self.feed == Feed::Live || self.sealed || self.end.is_some() || self.abort.is_some() } + /// Find the next live group at or after `index` in arrival order. + /// + /// Returns the group and its absolute index so the consumer can advance past it. + /// The cached producer rather than a consumer: `consume` reads the clock and can + /// take the group's own lock, which the caller does once the track guard is gone. fn poll_recv_group(&self, index: usize, min_sequence: u64) -> Poll>> { let start = index.saturating_sub(self.offset); let readable = self.readable(); @@ -7534,9 +7534,9 @@ mod test { let handle = group.handle(); let _partial = group .create_frame(frame::Info { - size: 2, - timestamp: Some(Timestamp::ZERO), - }) + size: 2, + timestamp: Some(Timestamp::ZERO), + }) .unwrap(); assert_eq!(handle.frame_count(), 2); drop(_partial); @@ -8096,9 +8096,9 @@ mod test { let mut frame = straggler .create_frame(frame::Info { - size: 3, - timestamp: Some(Timestamp::ZERO), - }) + size: 3, + timestamp: Some(Timestamp::ZERO), + }) .unwrap(); // The sender stalls past the retention window, then the whole payload lands in @@ -9466,17 +9466,46 @@ mod test { assert!(subscriber.recv_group().now_or_never().unwrap().unwrap().is_none()); let waiter = kio::Waiter::noop(); - assert!(producer.poll_past(0, &waiter).is_pending(), "a frameless group is not content"); + assert!( + producer.poll_past(0, &waiter).is_pending(), + "a frameless group is not content" + ); for group in &mut received { group .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) .unwrap(); } - assert!(producer.poll_past(0, &waiter).is_ready(), "its first frame makes it content"); + assert!( + producer.poll_past(0, &waiter).is_ready(), + "its first frame makes it content" + ); assert!(first.read_frame().now_or_never().unwrap().unwrap().is_some()); assert!(second.read_frame().now_or_never().unwrap().unwrap().is_some()); } + /// A parked `poll_past` wakes when a later group starts, not when its header lands. + #[test] + fn poll_past_wakes_when_a_later_group_starts() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let producer = track_producer("test", Info::timed()); + let woken = Arc::new(AtomicBool::new(false)); + let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); + assert!(producer.poll_past(0, &waiter).is_pending()); + + let mut group = producer.create_group(group::Info { sequence: 1 }).unwrap(); + woken.store(false, Ordering::SeqCst); + assert!( + producer.poll_past(0, &waiter).is_pending(), + "a frameless header is not content" + ); + group + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + assert!(woken.load(Ordering::SeqCst), "its first frame wakes the parked poll"); + assert!(producer.poll_past(0, &waiter).is_ready()); + } + /// A frameless group whose stream ends with no frame, cleanly or reset, ends its readers /// with it, and the track's end follows. #[moq_clock::test] @@ -10159,10 +10188,17 @@ mod test { let consumer = request.consume(); let mut producer = request.request_start(2).accept(None); let mut subscriber = consumer.subscribe(None).now_or_never().unwrap().unwrap(); - assert!(subscriber.poll_start(&waiter).is_pending(), "the floor is not the start"); + assert!( + subscriber.poll_start(&waiter).is_pending(), + "the floor is not the start" + ); // Nothing below the floor is waited for, and a group above it reads at once. - producer.create_group(group::Info { sequence: 3 }).unwrap().finish().unwrap(); + producer + .create_group(group::Info { sequence: 3 }) + .unwrap() + .finish() + .unwrap(); assert_eq!(subscriber.assert_group().sequence, 3); assert!(subscriber.poll_start(&waiter).is_pending()); @@ -10760,6 +10796,27 @@ mod test { assert!(matches!(result, Err(Error::Dropped))); } + /// Aborting a track aborts its open groups: a reader that already pulled one ends with + /// the error, and the group's writer fails. + #[test] + #[cfg(feature = "async")] + fn abort_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.clone().abort(Error::Cancel).unwrap(); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Cancel)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); + } + #[test] fn drop_after_abort_does_not_warn() { // abort() closes the channel after recording `abort`. Drop must treat the @@ -10936,10 +10993,7 @@ mod test { producer.finish_at(Position { group: 5, frame: 5 }).unwrap(); assert_eq!(producer.end(), Some(Position { group: 5, frame: 5 })); for moved in [Position { group: 5, frame: 4 }, Position::group(6), Position::group(5)] { - assert!(matches!( - producer.finish_at(moved), - Err(Error::ProtocolViolation) - )); + assert!(matches!(producer.finish_at(moved), Err(Error::ProtocolViolation))); } } @@ -11174,12 +11228,18 @@ mod test { let woken = Arc::new(std::sync::atomic::AtomicBool::new(false)); let waiter = kio::Waiter::new(futures::task::waker(Arc::new(FlagWake(woken.clone())))); - assert!(arrival.poll_recv_group(&waiter).is_pending(), "end {end}: held at the hole"); + assert!( + arrival.poll_recv_group(&waiter).is_pending(), + "end {end}: held at the hole" + ); elapse(&producer, grace - Duration::from_millis(1)); assert!(!woken.load(Ordering::SeqCst), "end {end}: woken before the grace"); assert!(arrival.poll_recv_group(&waiter).is_pending()); elapse(&producer, Duration::from_millis(1)); - assert!(woken.load(Ordering::SeqCst), "end {end}: the grace never woke the reader"); + assert!( + woken.load(Ordering::SeqCst), + "end {end}: the grace never woke the reader" + ); assert!(matches!(arrival.poll_recv_group(&waiter), Poll::Ready(Ok(None)))); } } @@ -11410,10 +11470,7 @@ mod test { producer.finish_at(Position::group(3)).unwrap(); assert!(arrival.recv_group().now_or_never().is_none(), "held at the hole"); assert!( - matches!( - producer.finish_at(Position::group(2)), - Err(Error::ProtocolViolation) - ), + matches!(producer.finish_at(Position::group(2)), Err(Error::ProtocolViolation)), "a second end is refused" ); assert_eq!(producer.end(), Some(Position::group(3)), "the first end stands"); @@ -11470,6 +11527,26 @@ mod test { assert!(matches!(consumer.recv_group().await, Err(Error::Timeout))); } + /// A close drops a group still open that no reader pulled: readers drain the finished + /// groups, then end without a declared end. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn local_close_drops_an_unpulled_open_group() { + let producer = track_producer("local", Info::timed()); + let mut consumer = producer.consume().subscribe(None).await.unwrap(); + producer.append_group().unwrap().finish().unwrap(); + let mut open = producer.append_group().unwrap(); + open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + producer.clone().close().unwrap(); + assert_eq!( + consumer.recv_group().await.unwrap().map(|group| group.sequence), + Some(0) + ); + assert!(consumer.recv_group().await.unwrap().is_none()); + assert!(matches!(consumer.finished().await, Err(Error::Closed))); + } + /// A local close is a dead route to the origin, not finished content, so a /// replacement route can take over where it left off. #[test] @@ -15024,6 +15101,19 @@ mod test { .unwrap(); } + /// A received copy writes what its peer sent, so a group starting before the one ahead of + /// it is not refused as a rewind, as a local write is. + #[test] + fn a_received_copy_skips_the_rewind_check() { + let mut producer = track_producer("test", Info::timed()); + producer.received(); + append_at(&mut producer, 1000); + let mut group = producer.append_group().unwrap(); + group + .write_frame(Timestamp::from_millis(500).unwrap(), &b"x"[..]) + .unwrap(); + } + /// The one-shot write ends the group it appended rather than leaving it open. #[test] fn a_rewound_single_frame_group_is_aborted() { From 3d81ac4f8e02225f4f8fcea17a3f9642b92bd9fa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:59:07 -0700 Subject: [PATCH 09/22] fix(net): allow TrackState::abort unused without async Its other caller went with the abort refactor, so the no-default-features clippy run flagged it. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index bdff083cd76..e3c3c07b77d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2135,6 +2135,7 @@ impl TrackState { } /// Abort shared track state without extending its publisher lifetime. + #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/deferred.md pub(crate) fn abort(producer: &kio::Producer, err: Error) -> Result<()> { commit_abort(Self::modify(producer)?, err); From 1785e3e51b1c8f1d43fbc3a39922562e8407f717 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 18:04:52 -0700 Subject: [PATCH 10/22] quest: list the accept-with-content candidates in public ingest Co-Authored-By: Claude Opus 5.5 --- quest/m1/public-model/ingest.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md index 788fb6fed6e..b5a3ee69110 100644 --- a/quest/m1/public-model/ingest.md +++ b/quest/m1/public-model/ingest.md @@ -161,11 +161,13 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: atomically with `accept`, gates `poll_start` (the lite publisher's resolved start) until `start_at`. The IETF TRACK_STATUS race is fixed with a crate-private `Request::idle()` applied in the same accept. - - Still open: the public way to accept idle, replay, then go live. Gating - `poll_live` on a pending start breaks lite-06 relays (no SUBSCRIBE_OK, so - the start resolves only with the first served group). Options: public - `Request::idle()` plus `Producer::set_live`; or `request_start` also - gating `poll_live`, accepting the lite-06 change. + - Still open: the public way to accept with content. Gating `poll_live` + on a pending start makes an IETF SUBSCRIBE_OK for an empty lite-06 track + wait for its first group (lite-06 resolves its start only with the first + served group), and a public runtime `set_live` is unwanted. Candidates: + write through the request before `accept`; a staged accept whose + `commit(self) -> Producer` publishes the track, rejecting if dropped; or + `accept` taking the initial content. - **Idle copy** (`track::Producer::set_idle`, `set_live`, `is_live`, `idle_newest`, `track::IDLE_LINGER`, `poll_past`; lite subscriber, `set_idle`, `set_live`, and `poll_past` also IETF). They keep a lingering copy's cache from serving stale groups From 44ec039c355dfce56155c679960023228ae347da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 18:31:16 -0700 Subject: [PATCH 11/22] feat(net): stage a requested track before subscribers see it `track::Request::stage(info)` mints the producer while waiting subscribers stay pending; `Staged::commit` publishes it with everything written, and dropping it uncommitted rejects the request. `accept(info)` is `stage(info).commit()`. A relay replaying retained groups stages them, so SUBSCRIBE_OK's Largest Location, which the IETF publisher snapshots once the subscribe resolves, always names them (#5862, with a multi-thread regression test that fails on accept-then-replay). The IETF subscriber stages its copy until the answer's Largest and start are in. @moq/net mirrors it (`Request.stage`, `Staged.producer`, `commit`, disposal rejects). Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 5 ++ js/net/src/broadcast.test.ts | 30 ++++++++++ js/net/src/ietf/subscriber.ts | 6 +- js/net/src/track.ts | 65 +++++++++++++++++++--- quest/m1/public-model/ingest.md | 32 ++++++++--- rs/moq-net/MIGRATE.md | 12 ++++ rs/moq-net/src/ietf/publisher.rs | 31 +++++++++++ rs/moq-net/src/ietf/subscriber.rs | 11 +++- rs/moq-net/src/model/broadcast.rs | 37 +++++++++++++ rs/moq-net/src/model/track.rs | 91 +++++++++++++++++++++++++++---- 10 files changed, 292 insertions(+), 28 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index abadbce09bf..455d0ea6889 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Stage a requested track before subscribers see it (#6111) + +`Track.Request.stage(info)` returns a `Track.Staged` whose `producer` writes while subscribers waiting on the request stay pending; `commit()` publishes it with everything written so far and returns the `Producer`. +Disposing a `Staged` uncommitted (`using`, or `[Symbol.dispose]()`) rejects the request. `accept(info)` is unchanged and equals `stage(info).commit()`. + ### A frameless group is not a successor (#6111) A group followed by a frameless one is judged stale against the next group that has a frame, where the frameless group used to count. diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 8f15ca10df6..79f6810e900 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -56,6 +56,36 @@ test("consumer dedupes repeat subscriptions onto one upstream request", async () expect((await pendingRequest(consumer))?.name).toBe("video"); }); +test("a staged track resolves its subscribers at commit, with what was written", async () => { + const consumer = new TestConsumer(); + const track = consumer.track("video"); + const reader = track.subscribe().ordered(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + const staged = request.stage({ timescale: Timescale.MILLI }); + staged.producer.writeFrame(textFrame("hello")); + const pending = Symbol("pending"); + expect(await Promise.race([track.info(), Promise.resolve(pending)])).toBe(pending); + + staged.commit(); + expect((await track.info()).timescale).toBe(Timescale.MILLI); + expect(await reader.readString()).toBe("hello"); +}); + +test("disposing an uncommitted staged track rejects the request", async () => { + const consumer = new TestConsumer(); + const info = consumer.track("video").info(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + { + using staged = request.stage({ timescale: Timescale.MILLI }); + staged.producer.writeFrame(textFrame("hello")); + } + await expect(info).rejects.toThrow(); +}); + // A replacement continues the name's timeline, so its groups can't start before the highest one an // earlier producer checked, while a new broadcast starts over. test("a replacement producer refuses a rewind past its predecessor", () => { diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 42249bd8103..e853703f206 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -1206,13 +1206,16 @@ export class Subscriber { if (ok.largest && ok.largest.groupId > BigInt(Number.MAX_SAFE_INTEGER)) { throw new RangeError("largest group exceeds safe integers"); } - const producer = request.accept({ + // Staged until the answer is written in below, so no reader sees the track before its + // Largest and start. + const staged = request.stage({ // No TIMESCALE (always so on drafts 14-16, which can't carry it) means no timeline, // and the track must not claim one when served onward. timescale: ok.properties.timescale, priority: fromWire(ok.properties.priority ?? 128), maxAge: maxCacheDuration === undefined ? undefined : Milli(Number(maxCacheDuration)), }); + const producer = staged.producer; producer.received(); const subscription: Subscription = { track: producer, tail: new Tail() }; state.subscription = subscription; @@ -1229,6 +1232,7 @@ export class Subscriber { start: ok.largest ? Number(ok.largest.groupId) : 0, requested: groups?.start === undefined ? undefined : groupBounds(groups).start, }); + staged.commit(); try { this.#aliases.set(ok.trackAlias, subscription, { broadcast, name: request.name, epoch }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index d473f1c2e83..38e042b48cf 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -309,24 +309,73 @@ export class Request { /** * Accept the request, committing the track's immutable {@link Info}. Throws, rejecting the - * request, if `info` is invalid. + * request, if `info` is invalid. The same as {@link stage} followed by {@link Staged.commit}. */ accept(info: Partial = {}): Producer { + return this.stage(info).commit(); + } + + /** + * Take the track's {@link Producer} without resolving any subscriber yet, so content written + * through {@link Staged.producer} is there when the first reader looks. For a relay that + * already holds groups of the track: write them, then {@link Staged.commit}. Disposing the + * {@link Staged} uncommitted rejects the request. + */ + stage(info: Partial = {}): Staged { + this.#pending.delete(this); + bindProducerSequence(this.#producer, this.#sequences.get(this.name)); + return new Staged(this.#producer, info); + } + + /** Reject the request, closing the track optionally with an error. */ + reject(err?: Error): void { this.#pending.delete(this); + this.#producer.close(err); + } +} + +/** + * A requested track being written before any subscriber sees it; see {@link Request.stage}. + * + * Write through {@link producer}. Subscribers waiting on the request resolve only at + * {@link commit}, with everything written by then. Disposing it uncommitted rejects the request, + * so hold it with `using` or commit it. + * + * @public + */ +export class Staged { + /** The track's writer. */ + readonly producer: Producer; + + #info: Partial; + #done = false; + + /** @internal */ + constructor(producer: Producer, info: Partial) { + this.producer = producer; + this.#info = info; + } + + /** + * Publish the track: every waiting subscriber resolves now, with what was written. Throws, + * rejecting the request, if the info is invalid or something written does not match it. + */ + commit(): Producer { + this.#done = true; try { - bindProducerSequence(this.#producer, this.#sequences.get(this.name)); - return this.#producer.accept(info); + return this.producer.accept(this.#info); } catch (err) { // Refused, so its subscribers see the error instead of waiting on an open request. - this.#producer.close(err instanceof Error ? err : new Error(String(err))); + this.producer.close(err instanceof Error ? err : new Error(String(err))); throw err; } } - /** Reject the request, closing the track optionally with an error. */ - reject(err?: Error): void { - this.#pending.delete(this); - this.#producer.close(err); + /** Reject the request unless it was committed. */ + [Symbol.dispose](): void { + if (this.#done) return; + this.#done = true; + this.producer.close(new Error("staged track dropped")); } } diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md index b5a3ee69110..799add07821 100644 --- a/quest/m1/public-model/ingest.md +++ b/quest/m1/public-model/ingest.md @@ -161,13 +161,31 @@ Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: atomically with `accept`, gates `poll_start` (the lite publisher's resolved start) until `start_at`. The IETF TRACK_STATUS race is fixed with a crate-private `Request::idle()` applied in the same accept. - - Still open: the public way to accept with content. Gating `poll_live` - on a pending start makes an IETF SUBSCRIBE_OK for an empty lite-06 track - wait for its first group (lite-06 resolves its start only with the first - served group), and a public runtime `set_live` is unwanted. Candidates: - write through the request before `accept`; a staged accept whose - `commit(self) -> Producer` publishes the track, rejecting if dropped; or - `accept` taking the initial content. + - ✅ Decided 2026-10-20 by the maintainer and landed in #6111: a staged + accept. `Request::stage(info) -> Staged` (`#[must_use]`, derefs to the + `Producer`), `Staged::commit(self) -> Producer` resolves the waiting + subscribers with what was written, and dropping it uncommitted rejects + the request with `Error::Dropped`. `accept(info)` is `stage(info).commit()`. + The IETF subscriber stages, reports Largest, resolves its start, then + commits. JS mirrors it (`Request.stage`, `Staged.producer`, `commit`, + disposal rejects). Everything else, lite-fed copies included, keeps + answering SUBSCRIBE_OK and TRACK_STATUS from the cache at once: the relay + never waits on a peer for Largest, and the subscriber filters old content. + Rejected: + - Gating `poll_live` on a pending start: an IETF SUBSCRIBE_OK for an + empty lite-06 track would wait for its first group. + - A public idle accept plus `Producer::set_live`: a runtime flag the + caller must remember to flip. + - A public `report_largest(Option)` that SUBSCRIBE_OK waits on: + it makes the relay wait on a peer for Largest, which for lite-fed copies + means the first group, and a quiet track would time out the JS IETF + subscriber's 10 s request deadline. + - `Request::producer(info)` plus an info-less `accept()`: no less API + than `stage`, breaks every `accept` caller, and loses the drop-rejects + guarantee. A `Request` cannot write before it knows its `Info`, since + every write checks the timescale and groups copy the info. + - `accept` taking the initial content: breaks every caller, adopts groups + from another track, and cannot carry a group still being written. - **Idle copy** (`track::Producer::set_idle`, `set_live`, `is_live`, `idle_newest`, `track::IDLE_LINGER`, `poll_past`; lite subscriber, `set_idle`, `set_live`, and `poll_past` also IETF). They keep a lingering copy's cache from serving stale groups diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 91e57d55311..f100d6cd6b8 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,18 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Stage a requested track before subscribers see it (#6111) + +`track::Request::stage(info)` returns a `track::Staged` that derefs to the track's `Producer` while subscribers waiting on the request stay pending; `commit()` publishes it with everything written so far and returns the `Producer`. +A relay that holds groups of a lazily served track writes them before committing, so the first reader (and an IETF SUBSCRIBE_OK's Largest Location) sees them. +Dropping a `Staged` uncommitted rejects the request with `Error::Dropped`. `accept(info)` is unchanged and equals `stage(info).commit()`. + +```rust +let mut staged = request.stage(info); +for group in retained { /* staged.create_group(..), write, finish */ } +let producer = staged.commit(); +``` + ### Frame writers own their group (#6111) `group::Producer::create_frame` now takes the writer by value and returns an owned `frame::Producer` with no lifetime. diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index e86bca5c4d3..e4b85f59304 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -15784,6 +15784,37 @@ mod range_tests { ); } + /// A relay holding groups of a requested track stages them before committing, so the + /// Largest Location that SUBSCRIBE_OK snapshots as soon as the subscribe resolves always + /// names the replayed group (#5862). Raced on real threads, many times. + #[test] + fn subscribe_ok_reports_a_staged_replay() { + for _ in 0..500 { + let broadcast = crate::broadcast::Info::new().produce(); + let request = broadcast.reserve_track("video").unwrap(); + let cache = broadcast.consume().track("video").unwrap(); + let snapshot = std::thread::spawn(move || { + futures::executor::block_on(async { + let mut track = cache.subscribe(None).await.unwrap(); + kio::wait(|waiter| track.poll_live(waiter)).await; + live_edge(&cache).largest + }) + }); + let staged = request.stage(crate::track::Info::timed()); + for sequence in 0..3 { + let mut group = staged.create_group(group::Info { sequence }).unwrap(); + for _ in 0..2 { + group + .write_frame(crate::Timestamp::from_millis(sequence).unwrap(), b"frame".as_slice()) + .unwrap(); + } + group.finish().unwrap(); + } + let _track = staged.commit(); + assert_eq!(snapshot.join().unwrap(), Some(Location { group: 2, object: 1 })); + } + } + /// Group numbering may legally skip sequences, so the walk follows the cache's own /// order rather than decrementing by one. #[test] diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 22f4c24a890..880e87d5d6e 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2980,6 +2980,9 @@ where frame: largest.object, }) }); + // A fresh copy is staged until the answer is written in below, so no reader sees it + // before its Largest and start. + let mut staged = None; let (mut track, dynamic) = match resumed { Some(idle) => { if !self.state.lock().subscribes.contains_key(&request_id) { @@ -3000,7 +3003,10 @@ where // Serves cache misses with a group FETCH. Registered before accepting, so a // miss queued meanwhile waits for it rather than failing for want of a handler. let dynamic = request.dynamic(); - (request.accept(info), dynamic) + let copy = request.stage(info); + let track = track::Producer::clone(©); + staged = Some(copy); + (track, dynamic) } }; track.received(); @@ -3019,6 +3025,9 @@ where true => track.start_at(largest.map_or(0, |largest| largest.group)), false => track.start_at(start.map(|start| start.group)), }; + if let Some(staged) = staged { + staged.commit(); + } let mut fetching: Option = None; { let mut state = self.state.lock(); diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index 89050369597..14eb1b6dfcd 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -2067,6 +2067,43 @@ mod test { assert!(stale.append_group().is_err()); } + /// A staged track resolves no subscriber until it commits, and then with what was + /// written meanwhile. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn a_staged_track_resolves_subscribers_at_commit() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let track = producer.consume().track("track1").unwrap(); + let mut subscribing = std::pin::pin!(track.subscribe(None)); + assert!(futures::poll!(subscribing.as_mut()).is_pending()); + + let mut staged = request.stage(crate::track::Info::timed()); + staged.write_frame(crate::Timestamp::ZERO, b"x".as_slice()).unwrap(); + moq_clock::sim::yield_now().await; + assert!(futures::poll!(subscribing.as_mut()).is_pending(), "still staged"); + + let _track = staged.commit(); + let mut subscriber = subscribing.await.unwrap(); + assert_eq!(subscriber.recv_group().await.unwrap().unwrap().sequence, 0); + } + + /// Dropping a staged track uncommitted rejects the request, so its subscribers fail + /// rather than wait on a track nobody will publish. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn dropping_a_staged_track_rejects_the_request() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let track = producer.consume().track("track1").unwrap(); + let subscribing = track.subscribe(None); + + let mut staged = request.stage(crate::track::Info::timed()); + staged.write_frame(crate::Timestamp::ZERO, b"x".as_slice()).unwrap(); + drop(staged); + assert!(matches!(subscribing.await, Err(Error::Dropped))); + } + /// Ending the broadcast doesn't cascade into a track someone is publishing: it keeps /// its cache and its publisher decides when it ends. Only a new lookup is refused. #[moq_clock::test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index e3c3c07b77d..d78989022bb 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -278,6 +278,9 @@ pub(crate) struct TrackState { // Whether a live Producer was minted. A reverse fetch may install `info` // before acceptance, so the two states are deliberately separate. published: bool, + // Minted by `Request::stage` and not committed yet: the producer writes, but waiting + // subscribers resolve only at `Staged::commit`, with everything written by then. + staged: bool, // Whether a dynamic handler took the request. Its answer is the handler's call, // so ending the broadcast leaves it pending rather than rejecting it. claimed: bool, @@ -774,7 +777,7 @@ impl TrackState { } fn poll_info(&self) -> Poll> { - if let Some(info) = &self.info { + if let Some(info) = self.info.as_ref().filter(|_| !self.staged) { Poll::Ready(Ok(info.clone())) } else if let Some(err) = &self.abort { // Aborted before anyone served it, so the info can never arrive: fail the @@ -6506,12 +6509,62 @@ impl Ordered { } } +/// A requested track being written before any subscriber sees it; see [`Request::stage`]. +/// +/// Write through it as through the [`Producer`] it derefs to. Subscribers waiting on the +/// request resolve only at [`Self::commit`], with everything written by then. Dropping it +/// uncommitted rejects the request with [`Error::Dropped`]. +#[must_use = "a staged track is rejected unless committed"] +pub struct Staged { + // Taken only by `commit`. + producer: Option, + // The request's fetch claim, held until the track is published like an unanswered + // request's: a cache miss meanwhile waits rather than racing its own handler. + _dynamic: Dynamic, +} + +impl Staged { + /// Publish the track: every waiting subscriber resolves now, with what was written. + pub fn commit(mut self) -> Producer { + let producer = self.producer.take().expect("taken only by commit"); + if let Ok(mut state) = producer.state.write() { + state.staged = false; + } + producer + } +} + +impl ops::Deref for Staged { + type Target = Producer; + + fn deref(&self) -> &Producer { + self.producer.as_ref().expect("taken only by commit") + } +} + +impl ops::DerefMut for Staged { + fn deref_mut(&mut self) -> &mut Producer { + self.producer.as_mut().expect("taken only by commit") + } +} + +impl Drop for Staged { + fn drop(&mut self) { + if let Some(producer) = self.producer.take() + && let Ok(state) = producer.state.write() + { + commit_abort(state, Error::Dropped); + } + } +} + /// A subscriber asked for a track this broadcast doesn't have yet. /// /// Yielded by [`poll_requested_track`](crate::broadcast::Dynamic::poll_requested_track), /// or created up front with [`broadcast::Producer::reserve_track`](crate::broadcast::Producer::reserve_track). /// Subscribers block until the request is -/// resolved: call [`accept`](Self::accept) to serve it with a [`Producer`], or +/// resolved: call [`accept`](Self::accept) to serve it with a [`Producer`] (or +/// [`stage`](Self::stage) to write content before they see it), or /// [`reject`](Self::reject) to fail them. Dropping it without either rejects with /// [`Error::Dropped`]. /// @@ -6678,12 +6731,25 @@ impl Request { /// (`None` for the defaults). If the track was already aborted, the returned /// [`Producer`] is inert: writes fail with the abort error, as if it had been /// aborted immediately after accepting. + /// + /// The same as [`Self::stage`] followed by [`Staged::commit`]. pub fn accept(self, info: impl Into>) -> Producer { + self.stage(info).commit() + } + + /// Mint the track's [`Producer`] without resolving any subscriber yet, so content + /// written through the returned [`Staged`] is there when the first reader looks. + /// + /// For a relay that already holds groups of the track: write them, then + /// [`Staged::commit`]. Dropping the [`Staged`] uncommitted rejects the request with + /// [`Error::Dropped`]. + pub fn stage(self, info: impl Into>) -> Staged { let info = info.into().unwrap_or_default(); // A closed state means the track was aborted under us. Mirror `reject` and // tolerate it: the Producer we hand back simply can't write. if let Ok(mut state) = self.state.write() { state.accept(info.clone()); + state.staged = true; if let Some(floor) = self.requested_start { state.set_start(floor, true); } @@ -6695,15 +6761,18 @@ impl Request { // Accepting the request creates the track producer: count it as one ingress // subscription (closed when the last handle drops). No-op when untagged. self.alive.publish(Some(&self.stats)); - Producer { - name: self.name, - info, - broadcast: self.broadcast, - state: self.state, - prev_subscription: None, - alive: self.alive, - stats: self.stats, - largest: None, + Staged { + producer: Some(Producer { + name: self.name, + info, + broadcast: self.broadcast, + state: self.state, + prev_subscription: None, + alive: self.alive, + stats: self.stats, + largest: None, + }), + _dynamic: self._dynamic, } } From fa59de50abdc8e5cec8aea6a34b12cf11b452520 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 19:01:21 -0700 Subject: [PATCH 12/22] docs(net): format the staged-accept migration note Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/MIGRATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index f100d6cd6b8..4cdfd0143c9 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -7,7 +7,7 @@ How to update your code for each breaking change, newest first. ### Stage a requested track before subscribers see it (#6111) `track::Request::stage(info)` returns a `track::Staged` that derefs to the track's `Producer` while subscribers waiting on the request stay pending; `commit()` publishes it with everything written so far and returns the `Producer`. -A relay that holds groups of a lazily served track writes them before committing, so the first reader (and an IETF SUBSCRIBE_OK's Largest Location) sees them. +A relay that holds groups of a lazily served track writes them before committing, so the first reader (and an IETF `SUBSCRIBE_OK`'s Largest Location) sees them. Dropping a `Staged` uncommitted rejects the request with `Error::Dropped`. `accept(info)` is unchanged and equals `stage(info).commit()`. ```rust From df3e197834dc22211d3b7d48c7d994cab07aedf1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 16:22:01 -0700 Subject: [PATCH 13/22] quest: complete public ingest The decisions it recorded are in the PR description; drop it from the public-model epic and the deferred quest's blockers. Co-Authored-By: Claude Opus 5.5 --- quest/m1/public-model/README.md | 7 +- quest/m1/public-model/deferred.md | 8 +- quest/m1/public-model/ingest.md | 257 ------------------------------ sh/rs/model-markers.py | 2 +- 4 files changed, 9 insertions(+), 265 deletions(-) delete mode 100644 quest/m1/public-model/ingest.md diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index 3f5981bacde..ee3d54b7271 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -35,7 +35,9 @@ Rules every child follows: that change cost, never behavior a third party can observe. - "capability gap": a built-in behavior a third party can observe but not reproduce yet, kept private by a recorded decision that names what - would close it (the idle copy in [ingest](/quest/m1/public-model/ingest.md)). + would close it (the idle copy, `track::Producer::set_idle` and `set_live`: + a custom subscriber ends its track when its upstream subscription ends + instead of keeping a lingering copy). - "plumbing" (JS only): session or wire plumbing hosted beside the model, such as `wire.ts` `Established`, `wireOf`, `tail.ts`, `consume.ts`, and `priority.ts`. @@ -61,7 +63,7 @@ Inventory on `main` at b4eab0db1: - Rust has 347 `pub(crate)` items in `model/` and no `#[doc(hidden)]` model item. 106 are reached by session code, 16 only by session tests, and 225 only inside `model/`. -- The 106 split into [ingest](/quest/m1/public-model/ingest.md), +- The 106 split into ingest (landed in [moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111)), [serving](/quest/m1/public-model/serve.md), [routes and answering](/quest/m1/public-model/answer.md), and the passthrough carve-out (listed in each child where it shares a type). @@ -101,7 +103,6 @@ Work owned by this README, after the children land: ## Required -- [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls - [Public serving](/quest/m1/public-model/serve.md) - a custom publisher reads a track's start, cursor, and group expiry for its wire through public calls - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/deferred.md b/quest/m1/public-model/deferred.md index 87c752e6700..97b9c5a6ae4 100644 --- a/quest/m1/public-model/deferred.md +++ b/quest/m1/public-model/deferred.md @@ -10,7 +10,7 @@ info, and declares a received end in JS, through public calls only. ## Plan -Split from the [ingest](/quest/m1/public-model/ingest.md), +Split from the ingest ([moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111)), [serving](/quest/m1/public-model/serve.md), and [answering](/quest/m1/public-model/answer.md) quests in review of #5717, so those three do not wait on the large quests that replace these items. @@ -37,8 +37,9 @@ the prerequisites will have deleted or renamed most of these. requests that Model ranges defines, completing the answering quest's `Broadcast.requested` decision. - JS `hooks.endTrack` and `hooks.startTrack` (the JS `finish_at_pending` and - `start_at`): public under the received-end shape the ingest quest settles in - Rust. + `start_at`): public under the received-end shape Rust settled in + [moq-dev/moq#6111](https://github.com/moq-dev/moq/pull/6111): `finish_at` + on a `received()` copy, and `start_at` after `track::Request::request_start`. Tests: as in the other children, mock time in each language, with the built-in sessions moved onto the public calls. @@ -46,6 +47,5 @@ built-in sessions moved onto the public calls. ## Required - [Dynamic range requests](/quest/m1/subscribe-ranges/dynamic.md) - replaces per-group fetch requests, the peeks, and `fork` -- [Public ingest](/quest/m1/public-model/ingest.md) - settles the received-end shape JS mirrors - [JS ranges](/quest/m1/subscribe-ranges/js.md) - the JS `Track.Request`/`Track.Dynamic` range requests that answer track info and fetches - [Public routes and answering](/quest/m1/public-model/answer.md) - the public `Broadcast.requested` handout this completes diff --git a/quest/m1/public-model/ingest.md b/quest/m1/public-model/ingest.md deleted file mode 100644 index 799add07821..00000000000 --- a/quest/m1/public-model/ingest.md +++ /dev/null @@ -1,257 +0,0 @@ -# [L] Public ingest - -## Goal - -A custom subscriber writes what it receives into a track through public -moq-net and @moq/net calls only: groups whose header lands before their first -frame, frames streamed across polls with peer-declared sizes, the start its -peer resolves, a received end with groups still in flight, and the session -ending. The built-in lite and IETF subscribers use the same calls. - -## Plan - -Rules, carve-outs, and the inventory method are in the -[epic](/quest/m1/public-model/README.md). Rerun the inventory first; the -recommendations below are the planning quest's, and the ones marked -**decision** were settled by the maintainer on 2026-10-16 (#5717). - -Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: - -- **Withheld groups** (`track::Producer::receive_group`, `reveal_group`, - `group::Producer::is_started`; lite subscriber). **Decision**, reopened - in review and settled 2026-10-16: - - ~~`create_group` withholds every group until its first frame or end.~~ - It deadlocks a publisher that creates a group and waits on - `group::Producer::demand()` before encoding, since no reader can reach - a withheld group to demand it. - - A public `receive_group` that reveals itself on its first frame or end. - - A public `receive_group` and `reveal_group` pair, as today. - - ✅ Drop withholding. Hiding a group from readers was never what fixed - #4914's rejoin bug: the model's judgments must not count a frameless - group as content. Derive that from each group's own state (first frame - opened, or ended) for every group, wherever the model asks it: the live - edge, successor and staleness, the rejoin wait (`shows`), `newest` and - `largest`, and `set_idle`. Every group joins arrival order when created, - so readers and group demand reach it before its first frame. - `create_group` is the only call; `receive_group`, `reveal_group`, and - `is_started` go. The group wakes its track once, on its first frame or - end, as `reveal` does today. Verified on a scratch branch at dd95d5804 - for received groups: with arrival order immediate and the judgments - gated, the whole moq-net suite passes except the two tests that assert - the old design. Consequences: - - The cache's internal largest stops reporting a frameless newest group - as (N, 0) and reports the last frame that exists. The public - `largest()` stream (#5725) deliberately does not: the maintainer - decided on 2026-10-17 that it counts every sequence seen, an empty - group at its head, so a late group below it never moves it. - - Regression guard: `rejoin_waits_for_the_answers_first_frame` - (`rs/moq-net/tests/integration/rejoin.rs`, fails when the judgments count a - frameless group) and - `revealing_a_presented_group_wakes_a_read_it_expires` stay; - `a_withheld_group_holds_the_end` and - `a_withheld_group_that_ends_empty_releases_the_end` are rewritten to - "a frameless group does not count as content" rather than "a reader - cannot see it". - - Unverified: app-created groups on the derived path, and the JS - mirror. Check both here before landing. -- **Owned frame writer** (`group::Producer::create_frame_owned`, - `frame::ProducerOwned`; both subscribers, `coding/reader.rs`). A - poll-driven wire driver cannot hold the borrowing `frame::Producer<'a>` - across polls. **Decision**, reopened in review and settled 2026-10-16: - - One owned `frame::Producer` guarded only by the runtime - `Error::FrameOpen` refusal. - - A second, public owned type (AGENTS.md's no-twins rule argues against - it). - - ✅ Make one open frame per group a compile-time guarantee. Drop public - `Clone` from `group::Producer`; the model and sessions keep a - crate-private non-writing handle. The chunked writer is owned: - `group::Producer::create_frame(self, info) -> Result` - aborts the group with the error on failure (an oversized frame, a - timestamp mismatch, or a closed group are bugs or protocol errors), - `frame::Producer::finish(self) -> Result` hands it - back, and `frame.group()` gives read access (demand, info, closed) - while the frame is open. `write_frame(&mut self)` stays for one-shot - frames. The borrowing `create_frame` and `ProducerOwned` go, with the - stale "caller's promise" doc. `track::Producer` keeps `Clone`: several - writers creating groups is legitimate, and `claim_sequence` already - refuses a duplicate sequence. - - #6020 dropped `Clone`, added the crate-private non-writing - `group::Handle`, and deleted `FrameOpen` (decided 2026-10-18, #5892), - so the backstop above goes. This item keeps the - public owned chunked writer. Its callers that hold a - `&mut group::Producer` (hang's `Frame::write_to`, moq-mux's LOC and - fMP4 encoders) cannot call a consuming `create_frame(self)`; weigh - that before landing it. - - Compile probe at dd95d5804: 26 `group::Producer` clone sites, 16 - model-internal and 7 in the sessions (kept by the crate-private - duplicate), and 3 outside the crate (2 in - `rs/moq-net/benches/track.rs`, 1 moq-ffi test), all trivial. - - The sessions clone to abort a group held elsewhere and to watch - demand or closure. If a third-party session needs to abort without - owning the writer, add a non-writing abort handle rather than - `Clone`. - - Pitfall: `group::Producer` derefs to the `Copy` `group::Info`, so a - downstream `producer.clone()` silently copies the `Info` and fails - later with a confusing "no method on `Info`" error. Say so in the - changelog, or drop the `Deref` for an `info()` getter. -- The frame writer's write without a wake (today - `frame::ProducerOwned::write`) and `notify`: stay private, "tunes the - built-in sessions" (batches wakes per poll turn). -- **Allocation budget** (`frame::Budget`; both subscribers): remove the - caller-supplied argument, but keep the aggregate bound. Today one 16 MiB - budget is shared by every frame a lite or IETF subscriber session - receives, so a peer that opens many streams declaring maximum-size frames - gets lazy growth past it, not memory. A per-producer budget would lose - that, and so would the origin's cache pool, which is unbounded by - default. Recommended: the budget lives on the origin producer handle a - session ingests through (the one that already carries its stats and - identity), with the same default, and is shared by every source, track, - and group minted from that handle. A frame whose declared size does not - fit grows with the bytes received, as today. The alternative is no - up-front allocation at all (always lazy), which needs no budget but pays - a reallocation per doubling on every large frame. Measure it against the - ingest benchmarks before choosing it. -- `group::Producer::info` (IETF subscriber): public, mirroring - `track::Producer::info`. -- **Received end** (`track::Producer::finish_at_pending`, `set_tail_pending`; - both subscribers). Without it, a custom subscriber over unordered streams - ends readers at a hole. **Decision**: - - Public after Tail arrivals, as one call that returns a handle the - session settles when its tail is in. - - Keep it private. - - ✅ Public after Tail arrivals, with the shape left to that quest. Once - the model records arrivals per track bounded by the subscription's - grace, it may own the grace timer itself, so a plain `finish_at` on a - received track could be enough and no settle handle is needed. - - Tail arrivals landed the record (`TrackState::arrivals`) without a - timer: the model folds a gap only on a write, so the session still - settles the tail with `set_tail_pending(false)`. The shape is this - quest's to settle. - - Landed in #6111: a plain `finish_at` on a `received()` copy. The model - holds readers at a hole below the end until the grace passes on the - pool's wall clock, counting `drop_groups` as accounted and keeping the - gap above the latest arrival open while groups still land. - `finish_at_pending` and `set_tail_pending` go, `demand_arrivals` folds - into the start declaration, `drop_groups` is public, and the ledger - moves out of `model/`. The session no longer settles early when every - stream is in, so an IETF publisher that skips group IDs without a - drop makes readers wait out the grace at END_OF_TRACK. -- **Session end** (`track::Producer::close`, `abort_session`; both - subscribers): public. Fold `abort_session` into the public `abort` (abort - open groups too) unless the implementer finds a reader-visible difference, - and expose `close` as "end without declaring an end, so a reader resumes - from another route". -- **Resolved start** (`track::Request::resolving_start`, - `track::Producer::request_start`; both subscribers): replace with one - public way to accept a request whose start the peer resolves later. It - must be set before any reader sees the track, so it lives on - `track::Request` (for example a pre-accept `request_start(floor)`), with - the public `start_at` resolving it. - Decided 2026-10-19 by the maintainer (#5862): the same shape must let a - lazily served relay track be accepted with content it already holds, so - no reader observes it accepted but empty and IETF SUBSCRIBE_OK never omits - Largest Location. Accept it idle (the `Feed::Idle` gate `poll_live` - already waits on), let the caller write its retained groups, then go - live. Not a closure: #5862's `accept_with(info, |producer| …)` is - rejected, as callback parameters are. Fix the IETF subscriber's own - TRACK_STATUS `accept` → `set_idle` race with it. Regression test: accept, - replay a retained group on the same task, and SUBSCRIBE_OK carries - Largest Location on a multi-thread runtime over many runs. - - Landed in #6111: public `track::Request::request_start(floor)`, applied - atomically with `accept`, gates `poll_start` (the lite publisher's - resolved start) until `start_at`. The IETF TRACK_STATUS race is fixed - with a crate-private `Request::idle()` applied in the same accept. - - ✅ Decided 2026-10-20 by the maintainer and landed in #6111: a staged - accept. `Request::stage(info) -> Staged` (`#[must_use]`, derefs to the - `Producer`), `Staged::commit(self) -> Producer` resolves the waiting - subscribers with what was written, and dropping it uncommitted rejects - the request with `Error::Dropped`. `accept(info)` is `stage(info).commit()`. - The IETF subscriber stages, reports Largest, resolves its start, then - commits. JS mirrors it (`Request.stage`, `Staged.producer`, `commit`, - disposal rejects). Everything else, lite-fed copies included, keeps - answering SUBSCRIBE_OK and TRACK_STATUS from the cache at once: the relay - never waits on a peer for Largest, and the subscriber filters old content. - Rejected: - - Gating `poll_live` on a pending start: an IETF SUBSCRIBE_OK for an - empty lite-06 track would wait for its first group. - - A public idle accept plus `Producer::set_live`: a runtime flag the - caller must remember to flip. - - A public `report_largest(Option)` that SUBSCRIBE_OK waits on: - it makes the relay wait on a peer for Largest, which for lite-fed copies - means the first group, and a quiet track would time out the JS IETF - subscriber's 10 s request deadline. - - `Request::producer(info)` plus an info-less `accept()`: no less API - than `stage`, breaks every `accept` caller, and loses the drop-rejects - guarantee. A `Request` cannot write before it knows its `Info`, since - every write checks the timescale and groups copy the info. - - `accept` taking the initial content: breaks every caller, adopts groups - from another track, and cannot carry a group still being written. -- **Idle copy** (`track::Producer::set_idle`, `set_live`, `is_live`, - `idle_newest`, `track::IDLE_LINGER`, `poll_past`; lite subscriber, - `set_idle`, `set_live`, and `poll_past` also IETF). They keep a lingering copy's cache from serving stale groups - between subscriptions. **Decision**: - - ✅ Stay private, marked as a known capability gap rather than tuning: - the staleness they prevent is observable, so "tunes the built-in - sessions" does not fit. A custom subscriber that ends its track when - its upstream subscription ends is correct, but cannot keep a lingering - copy. When designing the resolved start below, check whether idle folds - into it (re-subscribing a lingering copy is a request whose start the - peer resolves later); if it does, the gap closes there. - - Public as an idle handle whose `live(largest)` resumes readers. - - `track::Producer::poll_past` (IETF resume: a group past the answer's - Largest marks the copy live) belongs to this item and shares its fate: - private while the idle copy is, public only with it. Fix it either way: - it reads `max_sequence`, which a frameless group header advances, so it - must wait for a later group that has started (a frame landed or it - ended), the gating rule above. -- Fetch ingest (`group::Request` fields `state` and `result`, - `track::TrackState`, `track::FetchOutcome`, `finish_track_at`, - `poll_landed`): moved to [the deferred quest](/quest/m1/public-model/deferred.md), - which waits on Model ranges. -- `track::Producer::received` (lite and IETF subscribers; JS - `hooks.receiveTrack`) marks a session's copy so the local-write rewind - check skips it (#5803). It goes public with the other ingest calls, unless - [time provenance](/quest/m1/lite-time-provenance.md) makes received - timestamps checkable first. - Public in #6111 (JS `Track.Producer.received()`), and it also arms the - received-end grace above. -- Passthrough, stay private and marked: `group::Producer::wire`, - `set_wire`, `mark_gap`, `set_end_object`, `group::Wire`, the `object` and - `datagram` modules, `track::Producer::insert_wire_datagram`, - `frame::Header`. -- Test-only: `track::Producer::new`, `publisher_priority`, `start_sequence`, - `group::Producer::is_aborted`, `is_finished`, `group::Info::produce`, - `track::Info::timed` (see the epic). - -JS items (`js/net/src/`): mirror each Rust decision under the same name. - -- `hooks.endTrack` (`internal.ts`, IETF subscriber; the JS - `finish_at_pending`): moved to the deferred quest, which waits on JS - pending tail. -- `hooks.pendingTrackProducer` (IETF subscriber) reaches the producer behind - an unaccepted request so objects landing before SUBSCRIBE_OK are kept. - Replace it with the resolved-start shape above: the request is accepted - with its start pending, so early data has a public producer to land in. - Done in #6111: the IETF subscriber holds the request's demand before - SUBSCRIBE_OK and accepts at the answer, so the hook goes. JS has no - pending-start gate; its lite publisher does not wait on one. -- `Group.Producer.mirror` (`@internal`, lite subscriber fetch coalescing): - moved to the deferred quest, which waits on Model ranges and JS track - handover. -- `internal.ts` `finalSequence` (IETF subscriber) is public with the serving - quest's `Position::final_sequence`. -- `tail.ts` `Tail` and `TAIL_GRACE_MS`, `consume.ts` `BroadcastCache`: stay - private. They are session plumbing in both languages (Rust's `tail.rs` and - consume cache sit outside `model/`). - -Tests: each public call gets a mock-time test in its language, and the -built-in subscribers move onto the public calls, so their existing suites -cover the behavior. - -## Closes - -- [#5862](https://github.com/moq-dev/moq/issues/5862) - no way to accept a track::Request with content - -## Related - -- [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - the fetch ingest, `mirror`, and `endTrack` items split out of this quest diff --git a/sh/rs/model-markers.py b/sh/rs/model-markers.py index 9d7cb2c8fa0..b061ad7fa10 100644 --- a/sh/rs/model-markers.py +++ b/sh/rs/model-markers.py @@ -5,7 +5,7 @@ past the public API to a marked set. Each item they reach is either pending, naming the quest that makes it public, or deliberately private with its reason: - // pending: /quest/m1/public-model/ingest.md + // pending: /quest/m1/public-model/serve.md // private: passthrough | tuning | capability gap | test | plumbing (JS only) The marker sits in the comment and attribute lines directly above the item. A marker From ff66774f4f6720e8727948150a518913de0d5bdb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 16:25:08 -0700 Subject: [PATCH 14/22] style(net): format the main merge Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/subscriber.ts | 8 +++++++- js/net/src/track.test.ts | 5 +---- rs/moq-net/src/model/group.rs | 4 +--- rs/moq-net/src/model/resume.rs | 2 +- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 04cd588f06c..015fc06410f 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -1125,7 +1125,13 @@ export class Subscriber { requestId: bigint, deadline: Deadline, epoch: Epoch.Valid | undefined, - ): Promise<{ stream: RequestStream; subscription: Subscription; alias: bigint; priority: number; maxAge?: number }> { + ): Promise<{ + stream: RequestStream; + subscription: Subscription; + alias: bigint; + priority: number; + maxAge?: number; + }> { const version = this.#session.version; const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15 || version === Version.DRAFT_16; diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index a6164b31b11..96c6f7c44e7 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2819,10 +2819,7 @@ test("adjacent drops with the same code merge into one run", () => { const reader = producer.subscribe({ maxDelay: Milli(60_000) }); // Each DROP decodes to its own error, so runs must merge by code, not identity. for (let sequence = 2; sequence < 5; sequence++) { - producer.dropGroups(sequence, - sequence + 1, - new StreamError(StreamCode.NotFound, { message: "dropped" }), - ); + producer.dropGroups(sequence, sequence + 1, new StreamError(StreamCode.NotFound, { message: "dropped" })); } const recv = hooks.tryRecvGroup(reader, true); expect(recv.kind === "drop" ? [recv.start, recv.end, recv.error] : recv).toEqual([2, 5, DROPPED]); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 3bc9371ae84..9e8c94d1180 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -5047,9 +5047,7 @@ mod test { let res = compressed_group(&pool).create_object(header(MAX_CACHE_BYTES + 1)); assert!(matches!(res, Err(Error::FrameTooLarge))); - let res = Info::from(1u64) - .produce_untimed() - .create_object(header(1)); + let res = Info::from(1u64).produce_untimed().create_object(header(1)); assert!(matches!(res, Err(Error::ProtocolViolation))); } diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index b66ede3385b..9dcf35d16d4 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -35,8 +35,8 @@ use crate::time::Instant; use crate::{Error, Result, StreamError, group, stats, track}; use super::delivered::Delivered; -use crate::ledger; use super::subscription::{Anchor, Cap, Position, Resolved, Subscription, Unheld, Window}; +use crate::ledger; /// What the front says about a logical track: the copy to read now, and how it ended. #[derive(Default)] From 0ce49633ecad549edac1b5291d5897f10018f2c2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 16:52:57 -0700 Subject: [PATCH 15/22] test(net): a staged track is listed until dropped uncommitted Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/listing.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/rs/moq-net/src/model/listing.rs b/rs/moq-net/src/model/listing.rs index 50d755a1df9..35ff4c7384a 100644 --- a/rs/moq-net/src/model/listing.rs +++ b/rs/moq-net/src/model/listing.rs @@ -734,6 +734,18 @@ mod tests { assert_eq!(drain(&mut tracks), ["-a"]); } + #[test] + fn a_staged_track_is_listed_until_dropped_uncommitted() { + let broadcast = Info::new().produce(); + let request = broadcast.reserve_track("a").unwrap(); + let mut tracks = broadcast.consume().tracks().unwrap(); + assert_eq!(drain(&mut tracks), ["synced"]); + let staged = request.stage(None); + assert_eq!(drain(&mut tracks), ["+a"]); + drop(staged); + assert_eq!(drain(&mut tracks), ["-a"]); + } + #[test] fn a_track_served_on_request_is_never_listed() { let broadcast = Info::new().produce(); From 8a690a1fb22a1d4165dbb3502d8426184523bc49 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 17:12:49 -0700 Subject: [PATCH 16/22] fix(net): a track abort also aborts an open fetched head Producer::abort snapshotted only each slot's live group, so a fetched head still being written stayed open and its reader waited instead of ending with the track's error. Also show the full dropGroups signature in the @moq/net migration note. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 2 +- rs/moq-net/src/model/track.rs | 39 ++++++++++++++++++++++++++++++----- 2 files changed, 35 insertions(+), 6 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 2aa8a21aacc..e942c40136a 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -12,7 +12,7 @@ Disposing a `Staged` uncommitted (`using`, or `[Symbol.dispose]()`) rejects the ### A frameless group is not a successor (#6111) A group followed by a frameless one is judged stale against the next group that has a frame, where the frameless group used to count. -`Track.Producer.received()` marks a track as written from a peer, and `Track.Producer.dropGroups(start, end)` marks groups the peer said it skipped. +`Track.Producer.received()` marks a track as written from a peer, and `Track.Producer.dropGroups(start, end, error)` marks groups `[start, end)` the peer said it skipped; a reader holding one of them rejects with `error`. ### A dropped or cut group ends its reader with an error (#6143) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 867e1949de3..fc2b0901ea4 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -3043,9 +3043,9 @@ impl Producer { /// Abort the track with the given error. /// /// Consumes the handle, since nothing can be written to an aborted track. Consumers - /// still draining get the finished groups, then the abort error. Open groups are - /// aborted with the same error and leave the cache, so a consumer that already pulled - /// one ends with it too, and their writers fail. The pool's idle expiry (see + /// still draining get the finished groups, then the abort error. Open groups, fetched + /// copies included, are aborted with the same error and leave the cache, so a consumer + /// that already pulled one ends with it too, and their writers fail. The pool's idle expiry (see /// [`cache::Config::with_expiry`]) reclaims the rest, the latest group included, so a /// stale [`Consumer`] can't pin them in memory forever. /// @@ -3062,8 +3062,9 @@ impl Producer { let open: Vec<_> = state .lookup .values() - .filter(|slot| !slot.group.is_finished()) - .map(|slot| slot.group.clone()) + .flat_map(|slot| std::iter::once(&slot.group).chain(slot.head.as_deref())) + .filter(|group| !group.is_finished()) + .cloned() .collect(); // Snapshot the resume boundary before aborting groups releases their frames. commit_abort(state, err.clone()); @@ -11616,6 +11617,34 @@ mod test { assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); } + /// Aborting a track also aborts a fetched head still being written, so its reader ends + /// with the track's error rather than waiting on a fetch that can no longer land. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn abort_ends_an_open_fetched_head() { + let producer = track_producer("test", Info::timed()); + let dynamic = producer.dynamic(); + let consumer = producer.consume(); + let mut live = producer.create_group(group::Info { sequence: 0 }).unwrap(); + live.start_at(1).unwrap(); + live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")) + .unwrap(); + + let _fetch = consumer.fetch_group(0, None); + let request = dynamic.requested_group().await.unwrap(); + let mut head = request.accept(Info::timed()).unwrap(); + head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"snapshot")) + .unwrap(); + let mut reading = consumer.peek_group(0).expect("the head serves group 0"); + assert!(reading.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.abort(Error::App(7)).unwrap(); + let read = reading.read_frame().now_or_never().expect("the abort settles the head"); + assert!(matches!(read, Err(Error::App(7))), "{read:?}"); + let write = head.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta")); + assert!(matches!(write, Err(Error::App(7))), "{write:?}"); + } + #[test] fn drop_after_abort_does_not_warn() { // abort() closes the channel after recording `abort`. Drop must treat the From 2f3d97f851f9b9f3f7e639bc40b37c9802df7bd8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:33:27 -0700 Subject: [PATCH 17/22] fix(net): a declared start restarts a pending tail's grace A start declared after a received copy's end asks the feed for groups it may only now send. The gaps between arrivals already got a fresh grace, but the gap above the last arrival kept the end's timestamp, so a start resolved late in the grace ended readers almost at once. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index fc2b0901ea4..4a48e059e1b 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -407,7 +407,7 @@ pub(crate) struct TrackState { sealed: bool, // Set once a received copy's end is declared, ahead of group streams below it that QUIC - // may deliver in any order: when the end was declared or a group last arrived since. + // may deliver in any order: when the end or a start was declared, or a group last arrived since. // Readers wait out the grace for that tail (see [`Self::tail_deadline`]), rather than // end at the boundary with groups still to arrive. tail: Option, @@ -2071,7 +2071,8 @@ impl TrackState { /// demand dropped to the live edge, whose floor is unknown until declared). /// /// A declared start asks the feed for every group from it, so a gap in the arrivals at - /// or above it is waited for a fresh grace: the feed may only now be sending it. + /// or above it, and a pending tail above the last arrival, is waited for a fresh grace: + /// the feed may only now be sending it. fn set_start(&mut self, start_sequence: Option, pending: bool) { self.start_sequence = start_sequence; self.start_pending = pending; @@ -2079,6 +2080,9 @@ impl TrackState { self.cache.wakes().arrived(..start); let now = self.cache.pool().now_wall(); self.arrivals.demand(start..u64::MAX, now); + if self.tail.is_some() { + self.tail = Some(now); + } } } @@ -2184,7 +2188,7 @@ impl TrackState { /// A missing sequence is one no live group or datagram delivered and the publisher did /// not drop. A gap below an arrival is given up a grace after that arrival opened it, as /// the session's tail does. The gap above the last arrival is given up a grace after - /// the end was declared or a group last arrived, so a feed still delivering toward an + /// the end or a start was declared, or a group last arrived, so a feed still delivering toward an /// end declared ahead of it is not cut off. Judged by the arrivals, not the cache, so an evicted group or a /// datagram counts as delivered, and the check costs the same however much is cached. fn tail_deadline(&self, fin: u64) -> Option { @@ -12098,6 +12102,24 @@ mod test { assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); } + /// A start declared after the end asks the feed for groups it may only now send, so the + /// tail above the last arrival waits a fresh grace from it, not what is left of the end's. + #[test] + #[cfg(feature = "async")] + fn a_late_start_restarts_the_tail_grace() { + let mut producer = track_producer("test", None); + producer.received(); + let grace = replay().max_delay; + let mut arrival = producer.subscribe(replay()); + producer.finish_at(Position::group(2)).unwrap(); + elapse(&producer, grace - Duration::from_millis(1)); + producer.start_at(0).unwrap(); + elapse(&producer, Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().is_none(), "a fresh grace"); + elapse(&producer, grace - Duration::from_millis(1)); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + /// Only a received copy waits for its tail: a local publisher's end below a hole ends /// readers once the edge reaches it, as the publisher skipped the group. #[test] From 6e1d58f00835cce7ba93b264cc31c5028656db4f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 18:52:09 -0700 Subject: [PATCH 18/22] fix(net): dropping a staged track aborts its open groups Staged's drop only committed the abort to the track state, so a group created through it kept accepting frames after the request was rejected. Drop through Producer::abort instead, which also aborts unfinished groups, matching the JS Staged dispose. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/broadcast.rs | 14 ++++++++++++++ rs/moq-net/src/model/track.rs | 7 ++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/src/model/broadcast.rs b/rs/moq-net/src/model/broadcast.rs index d9df5349a33..231957b0477 100644 --- a/rs/moq-net/src/model/broadcast.rs +++ b/rs/moq-net/src/model/broadcast.rs @@ -2161,6 +2161,20 @@ mod test { assert!(matches!(subscribing.await, Err(Error::Dropped))); } + /// Dropping a staged track uncommitted aborts a group still being written through it, so + /// its writer fails rather than fill a track nobody will read. + #[moq_clock::test] + #[cfg(feature = "async")] + async fn dropping_a_staged_track_aborts_its_open_groups() { + let producer = Info::new().produce(); + let request = producer.reserve_track("track1").unwrap(); + let staged = request.stage(crate::track::Info::timed()); + let mut group = staged.append_group().unwrap(); + drop(staged); + let write = group.write_frame(crate::Timestamp::ZERO, b"x".as_slice()); + assert!(matches!(write, Err(Error::Dropped)), "{write:?}"); + } + /// Ending the broadcast doesn't cascade into a track someone is publishing: it keeps /// its cache and its publisher decides when it ends. Only a new lookup is refused. #[moq_clock::test] diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 4a48e059e1b..7e192706a06 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -7073,11 +7073,8 @@ impl Drop for Staged { let Some(producer) = self.producer.take() else { return; }; - // Unlisted first, as in `Producer::abort`. - producer.alive.unlist(); - if let Ok(state) = producer.state.write() { - commit_abort(state, Error::Dropped); - } + // Aborted like the producer it derefs to, so a group written through it ends too. + let _ = producer.abort(Error::Dropped); } } From d109dfdf21284e8cb90ccf9858a92002ce6e0dda Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 20:36:25 -0700 Subject: [PATCH 19/22] fix(net): abort open groups on every track teardown `close`, `abort_unused`, the crate-internal aborts, and the last producer dropping unfinished took open groups out of the cache without aborting the handles, so a writer the caller still held kept accepting frames and a reader that had pulled the group hung. The shared teardown now returns the unfinished copies and every path aborts them once the track lock is released, which `Producer::abort` used to do alone. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/MIGRATE.md | 5 +- rs/moq-net/src/model/track.rs | 168 +++++++++++++++++++++++++--------- 2 files changed, 128 insertions(+), 45 deletions(-) diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 6acb11b2453..e37e10238be 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -48,9 +48,10 @@ On a received copy, readers wait at a hole below that end for the subscription's Every group reaches readers as soon as it is created, but the live edge, `largest()`, and the judgment of whether a group was succeeded count a group only once its first frame opens or it finishes. A group followed by a frameless one is judged against the next group that has a frame. -### `track::Producer::abort` aborts open groups (#6111) +### Ending a track aborts its open groups (#6111) -Aborting a track now aborts its unfinished groups with the same error, so their readers end with it and their writers fail. +Aborting a track (`abort` or `abort_unused`) now aborts its unfinished groups with the same error, so their readers end with it and their writers fail. +Dropping the last `track::Producer` without a finish aborts them with `Error::Dropped`, and `close` with `Error::SessionClosed`. `track::Producer::close`, `track::Producer::received`, and `group::Producer::info` are now public. ### A dropped or cut group ends its reader with an error (#6143) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 5126df46ed0..5c8719476c4 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1617,10 +1617,23 @@ impl TrackState { } } - /// Drop the open groups nobody will finish now that the track ended abruptly, and - /// keep the finished ones for readers still draining. A consumer that already - /// pulled an open group keeps its own handle and ends with it. - fn drop_open_groups(&mut self, err: StreamError) { + /// End the track abruptly with `err`: drop the open groups nobody will finish, keep the + /// finished ones for readers still draining, and stop protecting the live edge. + /// + /// Returns every unfinished copy, to abort once the track lock is released, so a reader + /// that already pulled one ends with `err` too and its writer fails. + fn tear_down(&mut self, err: Error) -> OpenGroups { + // Snapshot the frame boundary before the open group it may sit in goes away: an + // abrupt end is exactly when a replacement route asks where to resume. + self.resume = self.resume_position(); + let groups = self + .lookup + .values() + .flat_map(Slot::copies) + .filter(|group| !group.is_finished()) + .cloned() + .collect(); + let dropped = StreamError::from(&err); let open: Vec<_> = self .lookup .iter() @@ -1628,7 +1641,7 @@ impl TrackState { .filter_map(|(&sequence, _)| Some(sequence..sequence.checked_add(1)?)) .collect(); for groups in open { - self.drop_groups(groups, err.clone()); + self.drop_groups(groups, dropped.clone()); } self.lookup .retain(|_, slot| slot.copies().any(group::Handle::is_finished)); @@ -1641,6 +1654,8 @@ impl TrackState { .get_mut() .unwrap_or_else(PoisonError::into_inner) .retain(|sequence, _| lookup.contains_key(sequence)); + self.close_cache(); + OpenGroups { groups, err } } /// Take `sequence` out of the cache, along with its checked start. @@ -2381,7 +2396,7 @@ impl TrackState { #[cfg_attr(not(feature = "async"), allow(dead_code))] // pending: /quest/m1/public-model/deferred.md pub(crate) fn abort(producer: &kio::Producer, err: Error) -> Result<()> { - commit_abort(Self::modify(producer)?, err); + commit_abort(Self::modify(producer)?, err).abort(); Ok(()) } @@ -2455,25 +2470,38 @@ impl TrackState { } } -/// Record `err` and close the track: the shared tail of [`Producer::abort`] and -/// [`Producer::abort_unused`]. -fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) { - // Snapshot the frame boundary before the open group it may sit in goes away: an - // abort is exactly when a replacement route asks where to resume. - state.resume = state.resume_position(); +/// Record `err` and close the track, the shared tail of every abort, returning the open +/// groups to abort once the guard is gone. +fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) -> OpenGroups { // Decided before the open groups go: the groups below the end are the evidence. A gap // past the grace was lost before the abort rather than cut off by it. let now = state.cache.pool().now_wall(); state.fold_arrivals(now); state.settled = state.is_settled(); - let dropped = StreamError::from(&err); - state.abort = Some(err); + state.abort = Some(err.clone()); // Keep what finished for consumers still draining: they get it, then the abort (or // the clean end, when the end settled). Clearing here would abort finished groups a // slower reader has not pulled yet. The pool's idle expiry bounds how long they stay. - state.drop_open_groups(dropped); - state.close_cache(); + let open = state.tear_down(err); state.close(); + open +} + +/// The unfinished groups a teardown took out of the track, aborted once the track lock +/// is released. +#[must_use = "abort the open groups after releasing the track lock"] +struct OpenGroups { + groups: Vec, + err: Error, +} + +impl OpenGroups { + /// End each group with the teardown's error: its readers end and its writer fails. + fn abort(self) { + for group in self.groups { + let _ = group.abort(self.err.clone()); + } + } } /// A reader's local group bounds: the floor, and the exclusive cap (`None` for none). @@ -2845,17 +2873,17 @@ impl Producer { /// End the track without declaring where it ends, as a closed session does. /// - /// Consumers drain the groups that finished and then end cleanly; the open groups are - /// dropped. A reader following the track's routes resumes from another one where this - /// copy stopped. Use [`Self::finish`] or [`Self::finish_at`] when the end is known. + /// Consumers drain the groups that finished and then end cleanly. The open groups are + /// aborted with [`Error::SessionClosed`], so a consumer that already pulled one ends + /// with it and their writers fail. A reader following the track's routes resumes from + /// another one where this copy stopped. Use [`Self::finish`] or [`Self::finish_at`] + /// when the end is known. pub fn close(self) -> Result<()> { let mut state = self.modify()?; state.sealed = true; - // See `commit_abort`: a takeover resumes mid-group once the open group goes away. - state.resume = state.resume_position(); - state.drop_open_groups(StreamError::from(&Error::SessionClosed)); - state.close_cache(); + let open = state.tear_down(Error::SessionClosed); state.close(); + open.abort(); Ok(()) } @@ -3062,19 +3090,7 @@ impl Producer { pub fn abort(self, err: Error) -> Result<()> { // Unlisted first, so the track leaves the listing before its name is free again. self.alive.unlist(); - let state = self.modify()?; - let open: Vec<_> = state - .lookup - .values() - .flat_map(|slot| std::iter::once(&slot.group).chain(slot.head.as_deref())) - .filter(|group| !group.is_finished()) - .cloned() - .collect(); - // Snapshot the resume boundary before aborting groups releases their frames. - commit_abort(state, err.clone()); - for group in open { - let _ = group.abort(err.clone()); - } + commit_abort(self.modify()?, err).abort(); Ok(()) } @@ -3085,6 +3101,9 @@ impl Producer { /// the track is closed, including when it was already closed; existing handles /// may still observe its final state. `Err(producer)` leaves the track unchanged /// so the caller can continue serving and wait for the next unused wake. + /// + /// The abort is the same as [`Self::abort`]: a group consumer that outlived the track's + /// consumers ends with `err`, and the group's writer fails. #[expect( clippy::result_large_err, reason = "return the owned producer without allocating on an idle check" @@ -3092,7 +3111,7 @@ impl Producer { pub fn abort_unused(self, err: Error) -> std::result::Result<(), Self> { let used = match self.state.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); false } kio::Unused::Closed => false, @@ -3550,10 +3569,9 @@ impl Drop for Alive { track = %self.name, "track::Producer dropped without finish() or abort()" ); - // See `abort`: keep the frame boundary once its open group goes away. - state.resume = state.resume_position(); - state.drop_open_groups(StreamError::from(&Error::Dropped)); - state.close_cache(); + let open = state.tear_down(Error::Dropped); + drop(state); + open.abort(); } Err(state) => { if state.sealed || state.end.is_some() || state.abort.is_some() { @@ -3728,7 +3746,7 @@ impl TrackWeak { }; match producer.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); true } kio::Unused::Closed => true, @@ -7285,7 +7303,7 @@ impl Request { pub(crate) fn reject_unused(&self, err: Error) -> bool { match self.state.write_unused() { kio::Unused::Idle(guard) => { - commit_abort(guard, err); + commit_abort(guard, err).abort(); true } kio::Unused::Closed => true, @@ -11700,6 +11718,70 @@ mod test { assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); } + /// Closing a track aborts its open groups like [`Producer::abort`], with + /// [`Error::SessionClosed`]. + #[test] + #[cfg(feature = "async")] + fn close_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + producer.close().unwrap(); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::SessionClosed)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::SessionClosed)), "{write:?}"); + } + + /// Aborting an unused track aborts an open group whose reader outlived the track's + /// consumers. + #[test] + #[cfg(feature = "async")] + fn abort_unused_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + drop(consumer); + + assert!(producer.abort_unused(Error::Cancel).is_ok()); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Cancel)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Cancel)), "{write:?}"); + } + + /// Dropping the last producer without a finish aborts its open groups with + /// [`Error::Dropped`]. + #[test] + #[cfg(feature = "async")] + fn drop_unfinished_ends_a_pulled_open_group() { + let producer = track_producer("test", Info::timed()); + let mut consumer = producer.subscribe(None); + let mut writer = producer.append_group().unwrap(); + writer + .write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"x")) + .unwrap(); + let mut group = consumer.assert_group(); + assert!(group.read_frame().now_or_never().unwrap().unwrap().is_some()); + + drop(producer); + let read = group.read_frame().now_or_never().expect("should not block"); + assert!(matches!(read, Err(Error::Dropped)), "{read:?}"); + let write = writer.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"y")); + assert!(matches!(write, Err(Error::Dropped)), "{write:?}"); + } + /// Aborting a track also aborts a fetched head still being written, so its reader ends /// with the track's error rather than waiting on a fetch that can no longer land. #[moq_clock::test] From 39b0e0a9fc430abbf9cd8f58c5e399d9abc25da6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 23:17:59 -0700 Subject: [PATCH 20/22] test(net): drop groups through the public Producer.dropGroups main's #6206 test used the hooks.dropTrackGroups hook this PR replaced with the public method. Co-Authored-By: Claude Opus 5.5 --- js/net/src/lite/publisher.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 881f844fc57..5d3b538287f 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -1058,7 +1058,7 @@ for (const skipped of ["failed", "stale"] as const) { group.writeFrame(textFrame("old", Timestamp.fromMillis(5))); sub.track.writeGroup(group); group.close(skipped === "failed" ? new Error("cut") : undefined); - if (skipped === "failed") hooks.dropTrackGroups(sub.track, 7, 8, new Error("cut")); + if (skipped === "failed") sub.track.dropGroups(7, 8, new Error("cut")); sub.serve(6); const response = await decodeSubscribeResponse(sub.client.reader, Version.DRAFT_06); if (!("start" in response)) throw new Error("expected SUBSCRIBE_START"); From 15d92dec3aa06ecb941ca50cf400c29bea76e077 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 02:48:08 -0700 Subject: [PATCH 21/22] fix(net): a pending start owes only the undelivered tail While a received copy's start is pending, its declared end waited the full grace even with nothing missing below it: an end at group 0, or one whose groups all arrived or were dropped. Owe only the sequences below the end that no live arrival delivered and the publisher did not drop. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 56 +++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 90548365aee..28cfb1e8ce2 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2230,8 +2230,15 @@ impl TrackState { // arrivals count. Without a declared start, the first one stands in for it. let floor = match self.start_sequence { Some(start) => start, - // Where the feed starts is still unknown, so all of it is owed. - None if self.start_pending => return active.checked_add(grace), + // Where the feed starts is still unknown, so everything below the end not yet + // delivered or dropped is owed. + None if self.start_pending => { + let missing = self + .arrivals + .gaps(0..fin) + .any(|(gap, _)| self.drops.gaps(&gap).next().is_some()); + return missing.then(|| active.checked_add(grace)).flatten(); + } None => self.arrivals.first().unwrap_or(0), }; let owed = floor.min(fin)..fin; @@ -12335,6 +12342,51 @@ mod test { assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); } + /// While the start is pending, everything below the end is owed, but only what has + /// not arrived or been dropped: an end with nothing missing below it ends readers at once. + #[test] + #[cfg(feature = "async")] + fn a_pending_start_owes_nothing_already_accounted_for() { + // An end before the first group owes nothing. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer.finish_at(Position::group(0)).unwrap(); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + + // Nor does one whose groups below it all arrived or were dropped. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer + .create_group(group::Info { sequence: 0 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 0); + producer.drop_groups(1..2, StreamError::NotFound); + producer.finish_at(Position::group(2)).unwrap(); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + + // A hole is still owed until the grace passes. + let mut producer = track_producer("test", None); + producer.received(); + producer.request_start(None).unwrap(); + let mut arrival = producer.subscribe(replay()); + producer + .create_group(group::Info { sequence: 1 }) + .unwrap() + .finish() + .unwrap(); + assert_eq!(arrival.assert_group().sequence, 1); + producer.finish_at(Position::group(2)).unwrap(); + assert!(arrival.recv_group().now_or_never().is_none(), "group 0 is owed"); + elapse(&producer, replay().max_delay); + assert!(arrival.recv_group().now_or_never().unwrap().unwrap().is_none()); + } + /// A fetched copy of a group the live feed still owes never reaches an arrival-order /// reader, so it does not fill the hole: the reader waits for the live group. #[moq_clock::test] From 8768d8e764b894ba8580fd1d0223322807a74902 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 09:15:00 -0700 Subject: [PATCH 22/22] fix(js/net): refuse committing a disposed staged track A disposed `Staged` has already rejected its subscribers, but `commit()` called `Producer.accept`, which returns silently on a closed producer, so it reported a successful publication. A committed or disposed `Staged` now throws on `commit()`, matching Rust's consuming `commit(self)`. Co-Authored-By: Claude Opus 5.5 --- js/net/src/broadcast.test.ts | 12 ++++++++++++ js/net/src/track.ts | 4 ++++ 2 files changed, 16 insertions(+) diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 2dacd4841a8..efbbe4411ad 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -88,6 +88,18 @@ test("disposing an uncommitted staged track rejects the request", async () => { await expect(info).rejects.toThrow(); }); +test("a disposed staged track refuses a later commit", async () => { + const consumer = new TestConsumer(); + const info = consumer.track("video").info(); + const request = await pendingRequest(consumer); + if (!request) throw new Error("expected request"); + + const staged = request.stage({ timescale: Timescale.MILLI }); + staged[Symbol.dispose](); + expect(() => staged.commit()).toThrow("staged track already committed or dropped"); + await expect(info).rejects.toThrow("staged track dropped"); +}); + // A replacement continues the name's timeline, so its groups can't start before the highest one an // earlier producer checked, while a new broadcast starts over. test("a replacement producer refuses a rewind past its predecessor", () => { diff --git a/js/net/src/track.ts b/js/net/src/track.ts index f02b692a0bc..886e23b70e1 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -405,8 +405,12 @@ export class Staged { /** * Publish the track: every waiting subscriber resolves now, with what was written. Throws, * rejecting the request, if the info is invalid or something written does not match it. + * Throws without publishing once committed or disposed. */ commit(): Producer { + // Rust's `commit(self)` consumes the handle; here a disposed one has already rejected + // its subscribers, and accepting a closed producer would silently do nothing. + if (this.#done) throw new Error("staged track already committed or dropped"); this.#done = true; try { return this.producer.accept(this.#info);