diff --git a/quest/m1/subscribe-drop.md b/quest/m1/subscribe-drop.md index 59eb1636971..39384ba36d5 100644 --- a/quest/m1/subscribe-drop.md +++ b/quest/m1/subscribe-drop.md @@ -11,10 +11,18 @@ brings it back in place of `Stream Count`. ## Plan -Today SUBSCRIBE_DROP is on the wire for lite-03 through lite-06 and the Rust -subscriber accounts for it, but no publisher sends it. lite-07 (still -`moq-lite-07-wip`, unpublished) removed it for a `Stream Count` on -SUBSCRIBE_END (#4224). +Today SUBSCRIBE_DROP is on the wire for lite-03 through lite-06, and the Rust +and `@moq/net` subscribers account for it. Once a track ends, the Rust +publisher on lite-05 and lite-06 names every sequence from its +SUBSCRIBE_START to the end that the subscription never got (skipped, +stale, or missing its head), just before its FIN. Still missing: JS +publishers, drops sent as soon as a group is given up rather than at the end, +and groups reset before their header. The end-of-track drops also miss a gap +the publisher aged out of its grace while the subscriber still waits on it: +the publisher ages a gap from when it queued the group above it, which can be +well before stream credit lets that group's header out. lite-07 (still `moq-lite-07-wip`, +unpublished) removed SUBSCRIBE_DROP for a `Stream Count` on SUBSCRIBE_END +(#4224). Decided: @@ -24,11 +32,14 @@ Decided: - A reliable reset ([Reliable stream reset](/quest/m1/quic/reliable-reset.md)) that keeps the stream header acts as a one-group drop, an optimization over sending the DROP. -- Publishers send SUBSCRIBE_DROP on lite-03 through lite-06 too: for every group +- Publishers send SUBSCRIBE_DROP on lite-05 and lite-06 too: for every group in range they won't deliver (expired, deprioritized, or reset without its header delivered) and for every explicit gap. Publishers that skip sequences (`cut` and group discontinuities in the media layers) must mark the gap so the net layer can drop it. +- Not on lite-03 or lite-04 (maintainer, 2026-10-09): they declare no + SUBSCRIBE_END, so no subscriber has an owed range to settle against, and a + drop would only add traffic to legacy peers. - Datagram groups stay best effort. A publisher counts a datagram as delivered, so a lost one leaves an uncovered hole that waits out the tail grace, as today. @@ -65,9 +76,10 @@ lite-07 changelog), `doc/concept/moq-lite.md`, and the Rust and JS lite publishers, subscribers, and tail accounting. Run `just drafts check` and `just test interop --all`. -Regression tests: a publisher that expires a group, skips a sequence, and -resets a stream before its header; on each version the subscriber settles -without waiting out the grace. +Regression tests: a publisher that expires a group or resets a stream before +its header; on each version the subscriber settles without waiting out the +grace. A skipped sequence at the end is covered on lite-05 through lite-07 +(`track_tail::skipped_groups_end_without_the_grace`). Add the lite-07 drop case to the tail interop harness from [track tail interop](/quest/m1/track-tail-interop.md): Rust and JS diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index a7679fa9263..75e3338ef63 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1,4 +1,8 @@ -use crate::{SessionError, announce, frame, group, origin, track}; +use crate::{ + SessionError, announce, frame, group, origin, + tail::{self, Tail}, + track, +}; use std::{ collections::{BTreeSet, HashMap}, ops::{Bound, ControlFlow}, @@ -2604,11 +2608,12 @@ impl Subscription { /// /// The datagram is dropped (there is no group fallback) if the encoded body doesn't fit the /// transport's datagram limit or the send fails (congestion / no capacity right now). - fn serve_datagram(&mut self, datagram: crate::Datagram) { + /// Returns whether it was handed to the transport. + fn serve_datagram(&mut self, datagram: crate::Datagram) -> bool { // Datagrams are lite-05+, which always declares a timescale in TRACK_INFO. let Ok(timestamp) = wire_timestamp(datagram.timestamp, self.timescale.unwrap_or_default(), &self.runtime) else { - return; + return false; }; let body = lite::Datagram { subscribe: self.id, @@ -2618,7 +2623,7 @@ impl Subscription { }; // has_datagrams is checked before this runs, so encoding never hits the version guard. let Ok(body) = body.encode_bytes(self.version) else { - return; + return false; }; let max = self.session.max_datagram_size(); @@ -2629,10 +2634,11 @@ impl Subscription { max, "dropping datagram larger than the transport limit" ); - return; + return false; } let _ = self.session.send_datagram(&body); + true } /// Read the latest SUBSCRIBE_UPDATE track priority, marking it seen. @@ -2686,7 +2692,8 @@ struct TrackRun { // once the first group is known, SUBSCRIBE_END as soon as the track declares its // exclusive final sequence (which may be ahead of the live edge). emit_range: bool, - start_sent: bool, + // Where SUBSCRIBE_START resolved the feed, once sent. + start: Option, // The first servable group, held until the source resolves where its feed starts. first: Option, // Groups skipped for a missing head before the start resolved, which it must not name. @@ -2695,6 +2702,13 @@ struct TrackRun { // Lite07+ sends SUBSCRIBE_END with the stream count instead of as soon as the // boundary is known, once every group below it has opened its stream. count_streams: bool, + // Lite05 and Lite06 name every sequence below the end that this subscription never + // got with SUBSCRIBE_DROP, so the subscriber settles without waiting out its grace + // for a group that will not come. The sequences served or sent as a datagram, with + // the subscriber's grace: a gap older than that it no longer waits for, so it is + // folded away here too, which bounds this by the gaps opened within the grace. + // `None` on other versions. + served: Option, // Serve datagrams off this same subscriber, but only on lite-05+ over a // datagram-capable transport (qmux/WebSocket/TCP/UDS report size 0). No group // fallback: otherwise off. @@ -2716,6 +2730,8 @@ impl TrackRun { let emit_range = ctx.version.has_track_stream(); let count_streams = ctx.version.has_stream_count(); let datagrams = ctx.version.has_datagrams() && ctx.session.max_datagram_size() > 0; + // Lite03 and Lite04 declare no end, so neither side could settle on a drop. + let served = (emit_range && !count_streams).then(|| Tail::new(tail::grace(track.subscription().max_delay))); Self { start_frame: bounds.start_frame(), @@ -2724,11 +2740,12 @@ impl TrackRun { track, track_priority_tx, emit_range, - start_sent: false, + start: None, first: None, skipped: BTreeSet::new(), end_sent: false, count_streams, + served, datagrams, children: kio::Tasks::new(), } @@ -2748,7 +2765,8 @@ impl TrackRun { // Feed the full update into the model subscriber so the producer's // aggregate reflects it (and a relay re-forwards it upstream). // Read first: `update` replaces these preferences. - let floored = self.track.subscription().start.is_some_and(|start| start.group > 0); + let requested = self.track.subscription().start.map(|start| start.group); + let floored = requested.is_some_and(|group| group > 0); let bounds = Bounds::from(&upd); let _ = self.track.update(crate::track::Subscription { priority: upd.priority, @@ -2764,10 +2782,26 @@ impl TrackRun { // floor on the same update, so both sides have to change together. // Pre-06 an absent start means the latest group, which `position_cursor` // already applied. - match upd.start_group { - Some(start_group) => self.track.start_at(start_group), - None if floored && self.ctx.version.resolves_start() => self.track.start_at(0), - None => {} + let lowered = match upd.start_group { + Some(start_group) => Some(start_group), + None if floored && self.ctx.version.resolves_start() => Some(0), + None => None, + }; + if let Some(served) = &mut self.served { + served.set_grace(tail::grace(upd.max_delay)); + } + if let Some(start) = lowered { + self.track.start_at(start); + // The subscriber owes itself the groups it newly asks for, below the floor it + // asked for last, and restarts their gap ages, so the drops at the end count + // from there too, on the same clock. + if let Some(resolved) = self.start { + if let Some(served) = &mut self.served { + let floor = requested.unwrap_or(resolved); + served.demand(start..floor, self.ctx.runtime.now()); + } + self.start = Some(resolved.min(start)); + } } self.track .end_at(upd.end_group.map_or(Bound::Unbounded, Bound::Included)); @@ -2816,7 +2850,7 @@ impl TrackRun { if self.datagrams && let Poll::Ready(Some(datagram)) = self.track.poll_recv_datagram(waiter)? { - self.ctx.serve_datagram(datagram); + self.serve_datagram(datagram); return Poll::Ready(Ok(ControlFlow::Continue(()))); } return Poll::Pending; @@ -2829,13 +2863,13 @@ impl TrackRun { // a quiet track may not reach that start for a while, and the subscriber judges // what it holds against the answer. if self.emit_range - && !self.start_sent + && self.start.is_none() && self.ctx.version.has_largest() && let Some(start) = self.track.subscription().start && let Poll::Ready(Some(largest)) = self.track.poll_live(waiter) && start > largest { - self.start_sent = true; + self.start = Some(start.group); writer.buffer(&lite::SubscribeResponse::Start(lite::SubscribeStart { group: start.group, largest: Some(largest), @@ -2857,17 +2891,17 @@ impl TrackRun { // partial group. Skip it rather than open a stream that can // only be reset; the next servable group resolves the start. tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence = group.sequence, "skipping group with a missing head"); - if self.emit_range && !self.start_sent { + if self.emit_range && self.start.is_none() { self.skipped.insert(group.sequence); } return Poll::Ready(Ok(ControlFlow::Continue(()))); } - match self.emit_range && !self.start_sent { + match self.emit_range && self.start.is_none() { true => self.first = Some(group), false => self.serve(group), } } - Recv::Datagram(datagram) => self.ctx.serve_datagram(datagram), + Recv::Datagram(datagram) => self.serve_datagram(datagram), Recv::Boundary(group) => { // The track declared its exclusive final sequence. Forward it now, // even if trailing groups (below `group`) are still in flight, then @@ -2888,13 +2922,65 @@ impl TrackRun { self.end_sent = true; writer.buffer(&lite::SubscribeResponse::End(lite::SubscribeEnd { group, streams }))?; } - Recv::Finished => return Poll::Ready(Ok(ControlFlow::Break(()))), + Recv::Finished => { + self.drop_unserved(writer)?; + return Poll::Ready(Ok(ControlFlow::Break(()))); + } } return Poll::Ready(Ok(ControlFlow::Continue(()))); } Poll::Pending } + + /// Send a datagram, recording its sequence once it went out. + fn serve_datagram(&mut self, datagram: crate::Datagram) { + let sequence = datagram.sequence; + if self.ctx.serve_datagram(datagram) { + self.mark_served(sequence); + } + } + + /// Record `sequence` as served, for [`Self::drop_unserved`]. + fn mark_served(&mut self, sequence: u64) { + let Some(served) = &mut self.served else { + return; + }; + if let Some(next) = sequence.checked_add(1) { + served.account(sequence..next, self.ctx.runtime.now()); + } + } + + /// Name every sequence from the start to the end that this subscription never got. The + /// track has ended, so none of them will be served now: groups it never produced (a + /// skipped sequence), and groups the cursor passed over (stale, or missing their head). + fn drop_unserved(&mut self, writer: &mut Writer) -> Result<(), Error> { + let (Some(served), Some(start)) = (&mut self.served, self.start) else { + // Without a SUBSCRIBE_START the subscriber owes itself no group (see + // `SubStream::owed`) and settles on the FIN alone, so there is nothing to drop. + return Ok(()); + }; + let Poll::Ready(Ok(fin)) = self.track.poll_finished(&kio::Waiter::noop()) else { + // A track closed without a final sequence sent no SUBSCRIBE_END, so the subscriber + // owes itself no range either. + return Ok(()); + }; + // A cap below the end bounds what the subscriber is owed, as on its side. + let end = match self.track.subscription().end { + Some(end) if end.frame == 0 => end.group.min(fin), + Some(end) => end.group.saturating_add(1).min(fin), + None => fin, + }; + served.expire(self.ctx.runtime.now()); + for gap in served.gaps(start..end) { + writer.buffer(&lite::SubscribeResponse::Drop(lite::SubscribeDrop { + start: gap.start, + end: gap.end - 1, + error: 0, + }))?; + } + Ok(()) + } } impl TrackRun { @@ -2918,7 +3004,7 @@ impl TrackRun { start += 1; } self.skipped.clear(); - self.start_sent = true; + self.start = Some(start); // Only the group: the subscriber derives the start frame from its own request // (see `lite::SubscribeStart`). The track is live by now, since its first group // was readable. @@ -2944,6 +3030,7 @@ impl TrackRun { fn serve(&mut self, group: group::Consumer) { let sequence = group.sequence; let frame_start = group.index(); + self.mark_served(sequence); tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "serving group"); // Use the latest priority for new groups so SUBSCRIBE_UPDATE applies to them too. @@ -3738,9 +3825,18 @@ mod serve_group_test { fn lite07_run( session: SinkSession, track: track::Subscriber, + ) -> (TrackRun, Writer, Log) { + lite_run(Version::Lite07, session, track) + } + + /// A subscription's run loop on `version`, from group 0, and the log of its subscribe stream. + fn lite_run( + version: Version, + session: SinkSession, + track: track::Subscriber, ) -> (TrackRun, Writer, Log) { let log = Log::default(); - let writer = Writer::new(SinkSend::new(log.clone()), Version::Lite07); + let writer = Writer::new(SinkSend::new(log.clone()), version); let track_priority = kio::Producer::new(0u8); let ctx = Subscription { session, @@ -3749,7 +3845,7 @@ mod serve_group_test { priority: PriorityQueue::default(), track_priority: track_priority.consume(), track_priority_seen: 0, - version: Version::Lite07, + version, timescale: Some(crate::Timescale::default()), runtime: crate::time::Clock::sim(), opens: Default::default(), @@ -3842,6 +3938,190 @@ mod serve_group_test { assert_eq!(*log.writes.lock().unwrap(), [0, 3, 0, 1, 0, 1, 2, 3, 2]); } + /// The SUBSCRIBE_DROP ranges a run loop's subscribe stream carried, once flushed. + async fn drops(mut writer: Writer, log: &Log, version: Version) -> Vec<(u64, u64)> { + // The serve flushes what the run loop buffered before its FIN. + kio::wait(|waiter| writer.poll_flush(&mut waiter.context())) + .await + .unwrap(); + let writes = log.writes.lock().unwrap().clone(); + let mut buf = writes.as_slice(); + let mut drops = Vec::new(); + while !buf.is_empty() { + let (msg, size) = lite::SubscribeResponse::decode_slice(buf, version).unwrap(); + buf = &buf[size..]; + if let lite::SubscribeResponse::Drop(drop) = msg { + drops.push((drop.start, drop.end)); + } + } + drops + } + + /// Lite-05 and lite-06 name every sequence below the end that the subscription never + /// got once the track ends: one skipped between groups, and one past the last. + #[moq_net_sim::test] + async fn the_end_drops_the_sequences_never_served() { + for version in [Version::Lite05, Version::Lite06] { + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let subscriber = track.subscribe(None); + let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); + { + let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); + track.finish_at(4).unwrap(); + write_group(&mut track, 0, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + write_group(&mut track, 2, 2); + // The last producer going ends the track with group 3 never produced. + drop(track); + run.await.unwrap(); + } + assert_eq!(drops(writer, &log, version).await, [(1, 1), (3, 3)], "{version:?}"); + } + } + + /// A SUBSCRIBE_UPDATE that lowers the start below SUBSCRIBE_START asks for those groups + /// too, so the drops at the end count from there. + #[moq_net_sim::test] + async fn the_end_drops_below_a_lowered_start() { + let version = Version::Lite06; + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let subscription = track::Subscription::default() + .with_start(track::Position::group(5)) + .with_max_delay(Duration::from_secs(60)); + let subscriber = track.subscribe(subscription); + let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 2, 2); + write_group(&mut track, 5, 5); + track.finish_at(7).unwrap(); + // Serve group 5, which resolves SUBSCRIBE_START. + while run.start.is_none() { + let step = run.poll_step(&mut writer, &kio::Waiter::noop()); + assert!(step.is_ready(), "the start never resolved"); + } + assert_eq!(run.start, Some(5)); + + run.update(lite::SubscribeUpdate { + priority: 0, + max_delay: Duration::from_secs(60), + start_group: Some(0), + end_group: None, + start_frame: 0, + end_frame: None, + }); + { + let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); + assert!(futures::poll!(run.as_mut()).is_pending()); + drop(track); + run.await.unwrap(); + } + // Group 2 arrived before the subscription and the cursor has passed it, so it was + // never served either. + assert_eq!(drops(writer, &log, version).await, [(0, 4), (6, 6)]); + } + + /// A lowered start restarts the age of the gaps it newly asks for, as the subscriber does, + /// so a gap below the old start isn't folded away on the time before the update. + #[moq_net_sim::test] + async fn the_end_drops_below_a_lowered_start_after_the_grace() { + let version = Version::Lite06; + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let subscription = track::Subscription::default() + .with_start(track::Position::group(5)) + .with_max_delay(Duration::from_secs(1)); + let subscriber = track.subscribe(subscription); + let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 5, 0); + while run.start.is_none() { + let step = run.poll_step(&mut writer, &kio::Waiter::noop()); + assert!(step.is_ready(), "the start never resolved"); + } + + moq_net_sim::advance(Duration::from_secs(2)).await; + run.update(lite::SubscribeUpdate { + priority: 0, + max_delay: Duration::from_secs(1), + start_group: Some(0), + end_group: None, + start_frame: 0, + end_frame: None, + }); + { + let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); + write_group(&mut track, 2, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + track.finish_at(6).unwrap(); + drop(track); + run.await.unwrap(); + } + assert_eq!(drops(writer, &log, version).await, [(0, 1), (3, 4)]); + } + + /// After a raised start, lowering it again restarts the gaps below the raised floor, not + /// only those below the lowest start ever asked for. + #[moq_net_sim::test] + async fn the_end_drops_below_a_start_raised_then_lowered() { + let version = Version::Lite06; + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let subscription = track::Subscription::default() + .with_start(track::Position::group(0)) + .with_max_delay(Duration::from_secs(1)); + let subscriber = track.subscribe(subscription); + let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); + write_group(&mut track, 0, 0); + while run.start.is_none() { + let step = run.poll_step(&mut writer, &kio::Waiter::noop()); + assert!(step.is_ready(), "the start never resolved"); + } + + let update = |start_group| lite::SubscribeUpdate { + priority: 0, + max_delay: Duration::from_secs(1), + start_group: Some(start_group), + end_group: None, + start_frame: 0, + end_frame: None, + }; + run.update(update(5)); + { + let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); + write_group(&mut track, 5, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + } + + moq_net_sim::advance(Duration::from_millis(900)).await; + run.update(update(2)); + moq_net_sim::advance(Duration::from_millis(200)).await; + track.finish_at(6).unwrap(); + drop(track); + kio::wait(|waiter| run.poll(&mut writer, waiter)).await.unwrap(); + assert_eq!(drops(writer, &log, version).await, [(1, 4)]); + } + + /// A gap older than the subscriber's grace is one it no longer waits for, so the run loop + /// forgets it rather than holding every gap of a long track until the end. + #[moq_net_sim::test] + async fn the_end_drops_only_gaps_within_the_grace() { + let version = Version::Lite06; + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let subscriber = track.subscribe(track::Subscription::default().with_max_delay(Duration::from_secs(1))); + let (mut run, mut writer, log) = lite_run(version, SinkSession::new(Log::default()), subscriber); + { + let mut run = std::pin::pin!(kio::wait(|waiter| run.poll(&mut writer, waiter))); + write_group(&mut track, 0, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + write_group(&mut track, 2, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + + moq_net_sim::advance(Duration::from_secs(2)).await; + write_group(&mut track, 4, 0); + assert!(futures::poll!(run.as_mut()).is_pending()); + track.finish_at(5).unwrap(); + drop(track); + run.await.unwrap(); + } + assert_eq!(drops(writer, &log, version).await, [(3, 3)]); + } + /// A lite-07 run over a relay's track, whose upstream subscription still waits on the /// source's SUBSCRIBE_START, on a subscribe stream the test can push updates onto. struct RelayRun { diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index 63e9e16598e..2c957ec8c35 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -142,6 +142,25 @@ impl Tail { .any(|run| run.groups.start <= groups.start && groups.end <= run.groups.end) } + /// The runs of `groups` not accounted for, in order. + pub fn gaps(&self, groups: Range) -> Vec> { + let mut gaps = Vec::new(); + let mut next = groups.start; + for run in &self.runs { + if next >= groups.end { + break; + } + if run.groups.start > next { + gaps.push(next..run.groups.start.min(groups.end)); + } + next = next.max(run.groups.end); + } + if next < groups.end { + gaps.push(next..groups.end); + } + gaps + } + /// Data streams received, whether they finished or were reset. pub fn streams(&self) -> u64 { self.streams diff --git a/rs/moq-net/tests/track_tail.rs b/rs/moq-net/tests/track_tail.rs index b938b0430d9..0de744ab2b6 100644 --- a/rs/moq-net/tests/track_tail.rs +++ b/rs/moq-net/tests/track_tail.rs @@ -220,13 +220,20 @@ async fn a_lost_group_ends_the_track_after_the_grace() { } } -/// Skipped sequences have no stream and must not hold lite-07's counted tail open. +/// Skipped sequences have no stream, so they must not hold the tail open: lite-07 does not +/// count them, and lite-05 and lite-06 publishers name them with SUBSCRIBE_DROP. #[moq_net_sim::test] -async fn lite07_skipped_groups_end_without_the_grace() { - let outcome = round("moq-lite-07-wip", Late::Delivered, 3).await; - assert!(outcome.err.is_none()); - assert_eq!(outcome.frames, [PAYLOAD]); - assert!(outcome.elapsed < GRACE / 10, "ended after {:?}", outcome.elapsed); +async fn skipped_groups_end_without_the_grace() { + for version in ["moq-lite-05", "moq-lite-06", "moq-lite-07-wip"] { + let outcome = round(version, Late::Delivered, 3).await; + assert!(outcome.err.is_none(), "{version}: {:?}", outcome.err); + assert_eq!(outcome.frames, [PAYLOAD], "{version}"); + assert!( + outcome.elapsed < GRACE / 10, + "{version}: ended after {:?}", + outcome.elapsed + ); + } } /// A zero stream count leaves no tail to wait for.