diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da97feaec27..057db04296a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,7 @@ Keep the body short and structured, not narrated: - **Summary**: a few bullets on what changed and why. For a bug fix, state the root cause (see Root Cause First in [CLAUDE.md](CLAUDE.md)). - **Public API changes**: every new/renamed/removed/signature-changed `pub` item in `rs/moq-*` and `js/*`, with breaking ones called out per [Branch Targeting](#branch-targeting). Distinguish genuinely public surface from `pub(crate)`/private. +- **Wire behavior changes**: what a *peer* observes differently, even when no signature moved and the encoding is byte-identical. A change to which content gets delivered, when a stream is reset rather than FIN'd (and with which error code), what a default now implies, or when a message is sent, is something another implementation has to match, and it is invisible in an API diff. Say what the old and new behavior are and which side decides. New/changed encodings additionally need the matching `drafts/` update in the same PR, per [Cross-Package Sync](CLAUDE.md#cross-package-sync). - **Test plan**: what was run and verified. - If you skip a [Cross-Package Sync](CLAUDE.md#cross-package-sync) row, say why. @@ -57,7 +58,7 @@ CodeRabbit reviews PRs automatically, but it has an hourly quota and runs out of Reply to review comments as you address them, saying what changed or why you disagree, so the reviewer doesn't have to diff the branch to find out. Replies are GitHub prose like any other, so they carry the [AI Contributions](#ai-contributions) marker. -When reviewing a PR, always include the same public API changes list described above, and call out anything breaking per [Branch Targeting](#branch-targeting). +When reviewing a PR, always include the same public API and wire behavior lists described above, and call out anything breaking per [Branch Targeting](#branch-targeting). Wire behavior is the easier of the two to miss, since nothing in the diff's signatures flags it: read for what a peer would now see, not just for what the types say. ## Releases diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 24055bf89a3..06c09c57513 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -400,14 +400,16 @@ counterpart no traffic can flow, so the entry is dropped: "broadcasts": 1, "broadcasts_closed": 0, "subscriptions": 5, "subscriptions_closed": 2, "fetches": 3, - "bytes": 12345, "frames": 678, "groups": 9, "datagrams": 2 + "bytes": 12345, "frames": 678, "groups": 9, "datagrams": 2, + "stale": { "bytes": 456, "frames": 23, "groups": 4, "datagrams": 0 } }, "anon/foo": { "announced": 1, "announced_closed": 0, "announced_bytes": 8, "broadcasts": 1, "broadcasts_closed": 0, "subscriptions": 2, "subscriptions_closed": 0, "fetches": 0, - "bytes": 234, "frames": 12, "groups": 1, "datagrams": 0 + "bytes": 234, "frames": 12, "groups": 1, "datagrams": 0, + "stale": { "bytes": 0, "frames": 0, "groups": 0, "datagrams": 0 } } } ``` @@ -417,6 +419,7 @@ Field semantics: - `announced` / `announced_closed`: cumulative count of every broadcast announce/unannounce event on this `(tier, role)` slot, regardless of whether any subscription happened. Use this for "all known broadcasts". + - `announced_bytes`: cumulative broadcast-name length summed over each model-visible announce and unannounce of this broadcast. It counts the name, not the encoded message size, so a broadcast isn't charged for hop chains or @@ -424,6 +427,7 @@ Field semantics: Separate from `bytes`, which is media payload. Announce control traffic that never enters the model (auth-rejected or unmatched-prefix announcements) is not counted. + - `broadcasts` / `broadcasts_closed`: per-(broadcast, session) subscription sentinel. The first active subscription a peer session opens for a broadcast bumps `broadcasts`; the last one it closes bumps @@ -431,13 +435,16 @@ Field semantics: broadcasts_closed` is the number of distinct sessions currently subscribed to the broadcast (i.e. viewers on the egress side), which is typically what billing and UI want. + - `subscriptions` / `subscriptions_closed`: cumulative count of track-level subscriptions opened and dropped. + - `fetches`: cumulative one-shot group fetches requested by a calling session, counted once per coalesced fetch when the request is issued, so a fetch that resolves to "not found" still counts. It is separate from `subscriptions` and the viewer sentinel; the fetched payload still flows into `bytes` / `frames` / `groups`. + - `bytes` / `frames` / `groups`: cumulative payload counters, bumped as groups/frames are read out of the model on the egress side and written into it on the ingress side. Egress bytes are counted when read out of the model @@ -445,12 +452,21 @@ Field semantics: still count. For a fan-out egress reader (e.g. an HLS/DASH muxer) this is bytes read once per segment at the broadcast origin, not per downstream HTTP client. + - `datagrams`: cumulative single-frame groups delivered over an unreliable QUIC datagram (moq-lite-05+ on a datagram-capable transport). A subset of `groups`: each datagram also counts there, and its payload in `frames` / `bytes`. Counted when the datagram enters or leaves the model, so an egress datagram dropped by congestion or an oversized body still counts. +- `stale`: cumulative `{ bytes, frames, groups, datagrams }` skipped because the + content drifted further behind the live edge than the subscriber's latency + budget allows, so the relay never put it on the wire. These are disjoint from + the top-level payload counters, which remain the backwards-compatible shape for + delivered content. A steady rate here means subscribers are consistently behind + the live edge, which is normal for a real-time subscription during congestion + and a problem for one that asked to tolerate more. + The session tracks (`sessions.json` and any `/sessions.json`) instead map each auth root to a `{ sessions, sessions_closed }` snapshot. `sessions` bumps when a session authenticated under that root connects and diff --git a/doc/bin/relay/http.md b/doc/bin/relay/http.md index 566d1493e1e..874d8e74f55 100644 --- a/doc/bin/relay/http.md +++ b/doc/bin/relay/http.md @@ -109,7 +109,10 @@ cluster topology endpoint below. ### GET /metrics Prometheus text exposition of this node's own traffic counters (bytes, frames, -groups, subscriptions, viewers, sessions), split by `tier` and `role`. +groups, subscriptions, viewers, sessions), split by `tier` and `role`. Content +skipped after drifting beyond a subscriber's latency budget is exposed through +`moq_relay_stale_bytes_total`, `moq_relay_stale_frames_total`, +`moq_relay_stale_groups_total`, and `moq_relay_stale_datagrams_total`. Alongside them are the TCP listeners' accept-loop counters, which are how a node that has stopped accepting connections says so: diff --git a/doc/concept/layer/moq-lite.md b/doc/concept/layer/moq-lite.md index 70ed9415871..974a6788e68 100644 --- a/doc/concept/layer/moq-lite.md +++ b/doc/concept/layer/moq-lite.md @@ -116,6 +116,12 @@ Each Subscription consists of a few properties: - **Group Order**: The order in which groups are delivered. Defaults to descending; higher IDs are delivered first. - **Subscriber Max Latency**: The maximum age of a non-latest group before it is skipped. Defaults to zero, so stale groups are skipped immediately. +That age is measured both on the media timeline (a group's first timestamp against the newest stamped one) and by wall-clock arrival time, and either limit can expire the group. +The media timeline keeps a backlog delivered as a burst old, while wall-clock time backstops stalled or empty groups that have no timestamp. +Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads. +The publisher only ever sees the most tolerant budget across its subscribers, which is why the subscriber applies it too. +Asking for old groups with `Group Start` does not exempt them: a start bounds what you are sent, and a subscriber that wants history has to raise its budget to match. + The publisher also keeps old groups around for a best-effort **Publisher Max Latency** cache window so relays and late subscribers can still fetch them. This defaults to 5 seconds. The subscriber's maximum latency is bounded by this window: a group can't be waited for longer than it's actually kept around. diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index c3d57ad1bf8..211e83104de 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -621,7 +621,7 @@ async def test_raw_multiple_frames(): consumer = origin.consume() async for announcement in consumer.announced(): - raw_consumer = await announcement.broadcast.subscribe_track("commands") + raw_consumer = await announcement.broadcast.subscribe_track("commands", moq.Subscription(latency_max_ms=1_000)) messages = [ b'{"cmd": "led", "arm": "left", "led": "THUMB", "state": 1}', @@ -646,7 +646,7 @@ async def test_raw_producer_consume_direct(): """Consume a raw track directly from the producer, no origin/broadcast plumbing.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("direct") - consumer = track.consume() + consumer = track.consume(moq.Subscription(latency_max_ms=1_000)) track.write_frame(b"hello", 0) track.write_frame(b"world", 0) @@ -702,7 +702,7 @@ async def test_raw_group_sequence(): consumer = origin.consume() async for announcement in consumer.announced(): - raw_consumer = await announcement.broadcast.subscribe_track("seq") + raw_consumer = await announcement.broadcast.subscribe_track("seq", moq.Subscription(latency_max_ms=1_000)) sent_sequences = [] for i in range(3): @@ -733,8 +733,9 @@ async def test_default_iteration_is_sequence_order(): broadcast = origin.create_broadcast("track/ordering") raw = broadcast.publish_track("ordering") - seq_consumer = raw.consume() - arr_consumer = raw.consume() + subscription = moq.Subscription(latency_max_ms=1_000) + seq_consumer = raw.consume(subscription) + arr_consumer = raw.consume(subscription) for sequence in (5, 3): group = raw.create_group(sequence) @@ -787,7 +788,7 @@ async def test_read_frame_one_per_group(): """read_frame() returns the first frame of each successive group.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("status") - consumer = track.consume() + consumer = track.consume(moq.Subscription(latency_max_ms=1_000)) track.write_frame(b"ready", 0) track.write_frame(b"running", 0) @@ -831,7 +832,7 @@ async def test_read_frame_skips_remaining_frames_in_group(): """read_frame() only returns the first frame of a multi-frame group.""" broadcast = moq.BroadcastProducer() track = broadcast.publish_track("mixed") - consumer = track.consume() + consumer = track.consume(moq.Subscription(latency_max_ms=1_000)) group = track.append_group() group.write_frame(b"first", 0) diff --git a/rs/hang/examples/subscribe.rs b/rs/hang/examples/subscribe.rs index 2b2365adb33..194efa71626 100644 --- a/rs/hang/examples/subscribe.rs +++ b/rs/hang/examples/subscribe.rs @@ -74,12 +74,16 @@ async fn run_subscribe(consumer: moq_net::origin::Consumer) -> anyhow::Result<() ); // Subscribe to the video track. + let latency = moq_mux::Latency::max(Duration::from_millis(500)); let track_consumer = broadcast .track(name)? - .subscribe(moq_net::track::Subscription::default().with_priority(1)) + .subscribe( + moq_net::track::Subscription::default() + .with_priority(1) + .with_latency(latency), + ) .await?; - let mut ordered = moq_mux::container::Consumer::new(track_consumer, moq_mux::catalog::hang::Container::Legacy) - .with_latency(moq_mux::Latency::max(Duration::from_millis(500))); + let mut ordered = moq_mux::container::Consumer::new(track_consumer, moq_mux::catalog::hang::Container::Legacy); // Read frames in latency-bounded presentation order. while let Some(frame) = ordered.read().await? { diff --git a/rs/kio/src/weak.rs b/rs/kio/src/weak.rs index eb1bf8f8f56..2185871b1c2 100644 --- a/rs/kio/src/weak.rs +++ b/rs/kio/src/weak.rs @@ -275,6 +275,32 @@ impl ConsumerWeak { } } + /// Poll the shared state with a closure, exactly as [`Consumer::poll`] does. + /// + /// Available here so a watcher can register for changes without joining the + /// consumer count, which is what [`Producer::unused`](crate::Producer::unused) + /// keys off. + pub fn poll(&self, waiter: &Waiter, mut f: F) -> Poll>> + where + F: FnMut(&Ref<'_, T>) -> Poll, + { + let state = self.state.lock(); + let consumer_state = Ref { state }; + + if let Poll::Ready(res) = f(&consumer_state) { + return Poll::Ready(Ok(res)); + } + + if consumer_state.state.closed { + return Poll::Ready(Err(consumer_state)); + } + + let mut state = consumer_state.state; + waiter.register(&mut state.waiters_value); + + Poll::Pending + } + /// Returns `true` if the channel has been closed. pub fn is_closed(&self) -> bool { self.state.lock().closed diff --git a/rs/libmoq/src/consume.rs b/rs/libmoq/src/consume.rs index 736b775c606..fa07d806701 100644 --- a/rs/libmoq/src/consume.rs +++ b/rs/libmoq/src/consume.rs @@ -379,9 +379,13 @@ impl Consume { let res = async move { let track = broadcast .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video)) + .subscribe( + moq_net::track::Subscription::default() + .with_priority(hang::catalog::PRIORITY.video) + .with_latency(latency), + ) .await?; - let track = moq_mux::container::Consumer::new(track, container).with_latency(latency); + let track = moq_mux::container::Consumer::new(track, container); Self::run_track(on_frame, track, channel.1).await } .await; @@ -428,9 +432,13 @@ impl Consume { let res = async move { let track = broadcast .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)) + .subscribe( + moq_net::track::Subscription::default() + .with_priority(hang::catalog::PRIORITY.audio) + .with_latency(latency), + ) .await?; - let track = moq_mux::container::Consumer::new(track, container).with_latency(latency); + let track = moq_mux::container::Consumer::new(track, container); Self::run_track(on_frame, track, channel.1).await } .await; diff --git a/rs/libmoq/src/test.rs b/rs/libmoq/src/test.rs index fa0ada4c863..773a6602cc1 100644 --- a/rs/libmoq/src/test.rs +++ b/rs/libmoq/src/test.rs @@ -1144,12 +1144,23 @@ fn raw_track_publish_consume() { let consume = request_broadcast(origin, path); let frame_cb = Callback::new(); + // This round trip verifies every published frame. Allow the first group to + // finish draining if the second becomes visible while the callback runs. + let subscription = moq_subscription { + priority: 0, + ordered: false, + latency_max_ms: 1_000, + group_start: 0, + group_start_valid: false, + group_end: 0, + group_end_valid: false, + }; let consumer = id(unsafe { moq_consume_track( consume, track_name.as_ptr() as *const c_char, track_name.len(), - std::ptr::null(), + &subscription, Some(channel_callback), frame_cb.ptr, ) diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index f1d414688a1..e67af9a6cbd 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -50,13 +50,17 @@ impl Consumer { let name = name.into(); let track = broadcast .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)) + .subscribe( + moq_net::track::Subscription::default() + .with_priority(hang::catalog::PRIORITY.audio) + .with_latency(config.latency), + ) .await?; // The catalog says how the track is framed, and it is not always the legacy // wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a // varint timestamp plus a payload decodes to garbage rather than failing. let container = moq_mux::catalog::hang::Container::try_from(&catalog.container)?; - let track = moq_mux::container::Consumer::new(track, container).with_latency(config.latency); + let track = moq_mux::container::Consumer::new(track, container); Ok(Self { decoder, @@ -170,23 +174,27 @@ mod tests { async fn reads_the_container_the_catalog_declares() { let mut broadcast = moq_net::broadcast::Info::new().produce(); let track = broadcast.create_track("audio", hang::container::track_info()).unwrap(); + let observed = track.clone(); let subscriber = broadcast.consume(); let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 1); catalog.container = hang::catalog::Container::Loc; let mut producer = moq_mux::container::Producer::new(track, moq_mux::catalog::hang::Container::Loc); + let latency = moq_mux::Latency::max(std::time::Duration::from_millis(250)); let mut consumer = Consumer::new( &subscriber, &catalog, "audio", Config { format: Format::F32, + latency, ..Config::new() }, ) .await .unwrap(); + assert_eq!(observed.subscription().unwrap().latency, latency); let samples = [0.25f32, -0.5, 0.75, -1.0]; let payload: Vec = samples.iter().flat_map(|sample| sample.to_le_bytes()).collect(); diff --git a/rs/moq-audio/src/decode/decoder.rs b/rs/moq-audio/src/decode/decoder.rs index d6ace02e296..c2474235aef 100644 --- a/rs/moq-audio/src/decode/decoder.rs +++ b/rs/moq-audio/src/decode/decoder.rs @@ -33,7 +33,8 @@ pub struct Config { pub channels: Option, /// How far playback may drift from the live edge before skipping a stalled group. /// - /// Forwarded to [`moq_mux::container::Consumer::with_latency`]. Defaults to + /// Applied to the initial transport subscription and inherited by + /// [`moq_mux::container::Consumer`]. Defaults to /// [`Latency::REAL_TIME`](moq_mux::Latency::REAL_TIME), which skips aggressively. /// Set [`Latency::max`](moq_mux::Latency::max) to the playout buffer you can /// tolerate (typically tens to a few hundred ms) for the best diff --git a/rs/moq-audio/tests/roundtrip.rs b/rs/moq-audio/tests/roundtrip.rs index 525f4f16990..312ac0ccbb1 100644 --- a/rs/moq-audio/tests/roundtrip.rs +++ b/rs/moq-audio/tests/roundtrip.rs @@ -65,6 +65,10 @@ async fn opus_round_trip_48k_stereo() { let cfg = snapshot.audio.renditions.get("audio").expect("audio rendition"); let mut config = decode::Config::default(); config.format = Format::F32; + // The whole clip is encoded before anything decodes it. The default REAL_TIME + // budget is enforced on the subscription, so without a tolerance the decoder would + // take the live edge and drop the rest of the batch. + config.latency = moq_mux::Latency::max(Duration::from_secs(30)); let mut consumer = decode::Consumer::new(&broadcast_consumer, cfg, "audio", config) .await .unwrap(); diff --git a/rs/moq-bench/src/connection.rs b/rs/moq-bench/src/connection.rs index 91f78ca51e6..dbde4408c8d 100644 --- a/rs/moq-bench/src/connection.rs +++ b/rs/moq-bench/src/connection.rs @@ -412,6 +412,10 @@ mod tests { } } + fn replay() -> track::Subscription { + track::Subscription::default().with_latency(moq_net::Latency::max(Duration::from_secs(30))) + } + /// A produced group must start with the JSON keyframe describing the rolled /// parameters, followed by `group_size` zeroed payload frames. #[tokio::test] @@ -429,7 +433,7 @@ mod tests { // Advance past one full group (keyframe + 2 payload) into the next. tokio::time::advance(Duration::from_millis(350)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap(); + let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap(); let mut group = sub.next_group().await.unwrap().expect("a group"); let keyframe = group.read_frame().await.unwrap().expect("keyframe"); @@ -464,7 +468,7 @@ mod tests { let task = tokio::spawn(produce(0, "bench/test".into(), rolled(10, 4, 0), track, stats.clone())); tokio::time::advance(Duration::from_millis(250)).await; - let mut sub = consumer.track(TRACK).unwrap().subscribe(None).await.unwrap(); + let mut sub = consumer.track(TRACK).unwrap().subscribe(replay()).await.unwrap(); let mut group = sub.next_group().await.unwrap().expect("a group"); // Just the keyframe, then the group ends. diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index a7f12db9048..856da08b088 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -560,11 +560,18 @@ mod tests { Export::with_ts(moq_mux::Source::new(origin.consume(), "cli"), CatalogFormat::Hang) .await .unwrap() - .with_latency(moq_mux::Latency::REAL_TIME), + .with_latency(moq_mux::Latency::max(RECORDING_LATENCY)), ) .await } + /// The media track's full retention window, so an exporter started after publishing + /// can still read every retained group. These tests publish a whole feed before + /// exporting it, which the default + /// [`Latency::REAL_TIME`](moq_mux::Latency::REAL_TIME) collapses to the live edge: + /// completeness has to be asked for, exactly as a real recorder does. + const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + /// Full CLI round-trip: a TS feed with undecoded streams goes through `Publish` /// (which selects the `mpegts` catalog) and the subscribe-side `Export::with_ts`, /// and the SCTE-35 section and the verbatim PES survive with their PIDs, framing, @@ -597,7 +604,7 @@ mod tests { Export::with_ts(moq_mux::Source::new(origin.consume(), "cli"), CatalogFormat::Hang) .await .unwrap() - .with_latency(moq_mux::Latency::REAL_TIME), + .with_latency(moq_mux::Latency::max(RECORDING_LATENCY)), ) .await; @@ -656,7 +663,7 @@ mod tests { /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); - let mut reader = Consumer::new(track, Container::Legacy).with_latency(moq_mux::Latency::REAL_TIME); + let mut reader = Consumer::new(track, Container::Legacy); let frame = tokio::time::timeout(Duration::from_secs(1), reader.read()) .await .expect("verbatim read timed out") diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index cb4113c8e56..e610b0b3360 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -289,9 +289,8 @@ impl MoqBroadcastConsumer { // subscription if init parsing fails. let media = media_container(container)?; let subscription = subscription.map(moq_net::track::Subscription::from).unwrap_or_default(); - let latency = subscription.latency; let track = self.inner.track(&name)?.subscribe(subscription).await?; - let consumer = moq_mux::container::Consumer::new(track, media).with_latency(latency); + let consumer = moq_mux::container::Consumer::new(track, media); Ok(Arc::new(MoqMediaConsumer { task: Task::new(Media { inner: consumer }), })) diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 1a550531a4e..d0e7ab6ac1d 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -442,9 +442,10 @@ async fn reconcile( } .fetch_add(1, Ordering::Relaxed); - let track_subscriber = broadcast.track(&name)?.subscribe(None).await?; - let track = moq_mux::container::Consumer::new(track_subscriber, container) - .with_latency(moq_mux::Latency::max(Duration::from_secs(1))); + let latency = moq_mux::Latency::max(Duration::from_secs(1)); + let subscription = moq_net::track::Subscription::default().with_latency(latency); + let track_subscriber = broadcast.track(&name)?.subscribe(subscription).await?; + let track = moq_mux::container::Consumer::new(track_subscriber, container); let descriptor = TrackDescriptor { kind: d.kind, diff --git a/rs/moq-mux/src/codec/h264/export.rs b/rs/moq-mux/src/codec/h264/export.rs index 880adc34dba..9d77642cd38 100644 --- a/rs/moq-mux/src/codec/h264/export.rs +++ b/rs/moq-mux/src/codec/h264/export.rs @@ -67,8 +67,8 @@ impl Export { /// Set the latency tolerance for the per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; @@ -293,7 +293,10 @@ mod tests { // Consumer side: run the exporter. let consumer = broadcast.consume(); - let mut export = Export::new(crate::source::announced(&consumer), Once(Some(catalog))); + // The whole track is written before the exporter runs, so it needs a budget + // wide enough to read it: the default skips everything but the live edge. + let mut export = Export::new(crate::source::announced(&consumer), Once(Some(catalog))) + .with_latency(crate::Latency::max(std::time::Duration::from_secs(30))); let frame0 = export.next().await.unwrap().expect("first frame"); let frame1 = export.next().await.unwrap().expect("second frame"); diff --git a/rs/moq-mux/src/codec/h265/export.rs b/rs/moq-mux/src/codec/h265/export.rs index d87bd98fcf8..3b0f849bfbe 100644 --- a/rs/moq-mux/src/codec/h265/export.rs +++ b/rs/moq-mux/src/codec/h265/export.rs @@ -59,8 +59,8 @@ impl Export { /// Set the latency tolerance for the per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; @@ -279,7 +279,10 @@ mod tests { track.finish().unwrap(); let consumer = broadcast.consume(); - let mut export = Export::new(crate::source::announced(&consumer), Once(Some(catalog))); + // The whole track is written before the exporter runs, so it needs a budget + // wide enough to read it: the default skips everything but the live edge. + let mut export = Export::new(crate::source::announced(&consumer), Once(Some(catalog))) + .with_latency(crate::Latency::max(std::time::Duration::from_secs(30))); let frame0 = export.next().await.unwrap().expect("first frame"); let frame1 = export.next().await.unwrap().expect("second frame"); diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 6c4898c23ea..66cb8dabdff 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -29,8 +29,9 @@ use super::{Container, Frame}; /// group's first timestamp has nothing left worth waiting for. Containers without a /// duration report zero, which disables this check and falls back to the latency budget. /// -/// Set the latency with [`with_latency`](Self::with_latency) (builder) or -/// [`set_latency`](Self::set_latency) (mid-stream). +/// Put the initial latency on the [`moq_net::track::Subscription`] before +/// subscribing. [`new`](Self::new) inherits that budget, and +/// [`set_latency`](Self::set_latency) changes it mid-stream. /// /// ## Timeline rewinds /// @@ -128,30 +129,22 @@ impl Reset { impl Consumer { /// Create a Consumer wrapping the given moq-lite consumer, decoding `format`. /// - /// Skips aggressively by default; raise the tolerance with - /// [`with_latency`](Self::with_latency). + /// The ordering window inherits the subscriber's current latency budget. Put + /// that budget on the [`moq_net::track::Subscription`] before awaiting the + /// subscription, so the publisher preserves the same replay window. pub fn new(track: moq_net::track::Subscriber, format: F) -> Self { + let latency = track.subscription().latency; Self { track, format, current: 0, pending: VecDeque::new(), startup: true, - latency: crate::Latency::REAL_TIME, + latency, rewind: Rewind::default(), } } - /// Set the latency tolerance. - /// - /// Groups older than the newest timestamp minus [`Latency::max`](crate::Latency::max) are - /// skipped. [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (the default) skips - /// aggressively: any group with a newer alternative is dropped. - pub fn with_latency(mut self, latency: crate::Latency) -> Self { - self.latency = latency; - self - } - /// A counter that increments each time the consumer detects a timeline rewind and drops /// the reneged buffer. /// @@ -480,6 +473,11 @@ impl Consumer { /// Set the latency tolerance mid-stream. pub fn set_latency(&mut self, latency: crate::Latency) { self.latency = latency; + // The transport enforces the same budget on the subscription itself, so a + // tolerance set here has to reach it: otherwise moq-net skips the very groups + // this consumer was told to wait for, before they ever get here. + let subscription = self.track.subscription().with_latency(latency); + let _ = self.track.update(subscription); } } @@ -761,14 +759,43 @@ mod tests { Ok(frames) } + /// Wrap `track` so only the container consumer performs latency skips. The + /// transport gets the media track's full retention window and hands over every + /// retained group; what the container does with them is what the test measures. + /// + /// Both layers enforce the same budget, and normally should: the transport skipping + /// a group the consumer was going to skip anyway just saves the bandwidth. These + /// tests are the exception, since they are about the consumer's half of it. + fn container_latency_only(track: moq_net::track::Subscriber, latency: Latency) -> Consumer { + let control = track.control(); + let mut consumer = Consumer::new(track, Container::Legacy); + consumer.set_latency(latency); + control + .update(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(30)))) + .unwrap(); + consumer + } + // ---- Basic Reading ---- + #[test] + fn new_inherits_the_initial_subscription_latency() { + let track = track_producer("test", hang::container::track_info()); + let latency = Latency::max(Duration::from_millis(250)); + let subscriber = track.subscribe(moq_net::track::Subscription::default().with_latency(latency)); + + let consumer = Consumer::new(subscriber, Container::Legacy); + + assert_eq!(consumer.latency, latency); + assert_eq!(consumer.track.subscription().latency, latency); + } + #[tokio::test] async fn read_single_group() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); track.finish().unwrap(); @@ -785,9 +812,9 @@ mod tests { #[tokio::test] async fn read_multiple_frames_single_group() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0), ts(33_000), ts(66_000)]); track.finish().unwrap(); @@ -804,9 +831,9 @@ mod tests { #[tokio::test] async fn read_multiple_groups_within_latency() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // 5 groups, 20ms spacing. Total span = 80ms, well within 500ms latency. for i in 0..5u64 { @@ -824,9 +851,9 @@ mod tests { async fn latency_skip_delivers_recent_groups() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Group 0: 5 frames, NOT finished (blocks consumer) let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -868,7 +895,7 @@ mod tests { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); let consumer_track = track.subscribe(None); - let mut consumer = Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::REAL_TIME); + let mut consumer = container_latency_only(consumer_track, Latency::REAL_TIME); // Group 0 at ts 0 keeps timestamps monotonic with sequence (groups 1-9 follow at // g*50 ms), so the test exercises latency skipping and not rewind detection. @@ -907,8 +934,7 @@ mod tests { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let mut consumer = container_latency_only(consumer_track, Latency::max(Duration::from_millis(100))); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -976,9 +1002,9 @@ mod tests { async fn reset_keeps_out_of_order_new_group() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Old epoch, played forward until the live edge passes the rewind point. write_group(&mut track, 0, &[ts(0)]); @@ -1016,9 +1042,9 @@ mod tests { async fn reset_detected_behind_forward_newest_group() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Old timeline, played to a live edge of 200 ms. write_group(&mut track, 0, &[ts(0)]); @@ -1052,10 +1078,10 @@ mod tests { async fn backwards_timestamp_resets_buffer() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); // Large latency so the slow-group skip never fires; isolate the rewind path. - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Publisher runs ahead: groups 0-4 at 0, 100, 200, 300, 400 ms. for i in 0..5u64 { @@ -1079,9 +1105,9 @@ mod tests { #[tokio::test] async fn backwards_timestamp_always_resets() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); write_group(&mut track, 1, &[ts(500_000)]); @@ -1115,9 +1141,9 @@ mod tests { #[tokio::test] async fn empty_payload_is_skipped() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); let media = |timestamp| Frame { @@ -1145,9 +1171,9 @@ mod tests { #[tokio::test] async fn consecutive_markers_do_not_stall() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -1179,9 +1205,9 @@ mod tests { async fn groups_delivered_in_sequence_order() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -1216,9 +1242,9 @@ mod tests { #[tokio::test] async fn adjacent_group_flushed_immediately() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); write_group(&mut track, 1, &[ts(30_000)]); @@ -1235,9 +1261,9 @@ mod tests { #[tokio::test] async fn bframes_within_group() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0), ts(66_000), ts(33_000)]); track.finish().unwrap(); @@ -1255,9 +1281,9 @@ mod tests { async fn empty_track_returns_none() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); track.finish().unwrap(); @@ -1274,9 +1300,9 @@ mod tests { async fn track_closed_with_error() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); track.abort(moq_net::Error::Cancel).unwrap(); @@ -1298,9 +1324,9 @@ mod tests { #[tokio::test] async fn gap_in_group_sequence_recovery() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0), ts(20_000)]); write_group(&mut track, 1, &[ts(40_000), ts(60_000)]); @@ -1317,9 +1343,9 @@ mod tests { #[tokio::test] async fn gap_at_start_of_sequence() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(80))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(80)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 5, &[ts(0), ts(20_000)]); write_group(&mut track, 7, &[ts(80_000), ts(100_000)]); @@ -1341,9 +1367,9 @@ mod tests { #[tokio::test] async fn evicted_group_with_gap_skips_to_live() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Group 0: a frame the consumer reads, positioning it there. let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -1385,9 +1411,9 @@ mod tests { #[tokio::test] async fn missing_sequence_skips_on_live_track() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Group 0, then group 2 -- sequence 1 is missing (evicted) and never arrives. // The track is NOT finished (live), the case that used to hang. @@ -1485,9 +1511,9 @@ mod tests { #[tokio::test] async fn frame_timestamp_and_index_decoding() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0), ts(33_333), ts(66_666)]); track.finish().unwrap(); @@ -1506,9 +1532,9 @@ mod tests { #[tokio::test] async fn frame_payload_preserved() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let payload_bytes = vec![0x01, 0x02, 0x03, 0x04, 0x05]; let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -1545,9 +1571,9 @@ mod tests { async fn no_infinite_loop_with_buffered_frames() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -1592,9 +1618,9 @@ mod tests { #[tokio::test] async fn large_timestamps() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(3700))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(3700)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let one_hour = 3_600_000_000u64; write_group(&mut track, 0, &[ts(one_hour)]); @@ -1609,9 +1635,9 @@ mod tests { #[tokio::test] async fn set_latency_changes_behavior() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); track.finish().unwrap(); @@ -1628,11 +1654,11 @@ mod tests { async fn max_timestamp_tracks_through_bframes() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(110)))); // latency must exceed (group1_max - group0_min) = 100ms - 0ms = 100ms // to avoid the latency skip and test B-frame timestamp tracking. - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(110))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); for ×tamp in &[ts(0), ts(66_000), ts(33_000)] { @@ -1681,9 +1707,9 @@ mod tests { async fn startup_selects_earliest_group() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 3, &[ts(0)]); write_group(&mut track, 5, &[ts(150_000)]); @@ -1735,9 +1761,9 @@ mod tests { async fn startup_skips_groups_without_data() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let _group5 = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); write_group(&mut track, 7, &[ts(210_000)]); @@ -1759,9 +1785,9 @@ mod tests { #[tokio::test] async fn startup_single_group_mid_stream() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 100, &[ts(3_000_000)]); track.finish().unwrap(); @@ -1774,9 +1800,9 @@ mod tests { async fn multiple_sequential_latency_skips() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(50))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(50)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -1811,9 +1837,9 @@ mod tests { async fn latency_skip_boundary_exact() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(100)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); Container::Legacy @@ -1851,8 +1877,7 @@ mod tests { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let mut consumer = container_latency_only(consumer_track, Latency::max(Duration::from_millis(100))); // Group 0: stalled at ts=0, NOT finished let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -1890,8 +1915,7 @@ mod tests { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(100))); + let mut consumer = container_latency_only(consumer_track, Latency::max(Duration::from_millis(100))); // Group 0: finished normally write_group(&mut track, 0, &[ts(0), ts(20_000)]); @@ -1906,9 +1930,9 @@ mod tests { #[tokio::test] async fn group_error_skips_to_next() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); group0.abort(moq_net::Error::Cancel).unwrap(); @@ -1924,9 +1948,9 @@ mod tests { async fn track_finishes_while_reading() { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); write_group(&mut track, 0, &[ts(0)]); @@ -1954,9 +1978,9 @@ mod tests { #[tokio::test] async fn empty_group_advances() { let mut track = track_producer("test", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); group0.finish().unwrap(); @@ -1975,9 +1999,9 @@ mod tests { tokio::time::pause(); let mut track = track_producer("video", hang::container::track_info()); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, Container::Legacy).with_latency(Latency::max(Duration::from_millis(500))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); + let mut consumer = Consumer::new(consumer_track, Container::Legacy); // Write frames using Container::Legacy encoding let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -2018,10 +2042,10 @@ mod tests { // DurationWire is a test-only container that doesn't stamp moq_net frame // timestamps; leave the track untimed so model-layer validation matches. let mut track = track_producer("test", None); - let consumer_track = track.subscribe(None); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); // Latency dwarfs the gap, so only duration coverage can trigger the skip. - let mut consumer = - Consumer::new(consumer_track, DurationWire).with_latency(Latency::max(Duration::from_secs(10))); + let mut consumer = Consumer::new(consumer_track, DurationWire); // Group 0: one frame at ts=0 lasting 33ms, never finished. let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); @@ -2060,9 +2084,9 @@ mod tests { tokio::time::pause(); // DurationWire is untimed at the moq_net frame layer. let mut track = track_producer("test", None); - let consumer_track = track.subscribe(None); - let mut consumer = - Consumer::new(consumer_track, DurationWire).with_latency(Latency::max(Duration::from_secs(10))); + let consumer_track = track + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let mut consumer = Consumer::new(consumer_track, DurationWire); // Group 0: frame at ts=0 lasting only 10ms, far short of group 1 at 33ms. let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 6b9ea41d76e..47f483e0f78 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -189,8 +189,8 @@ impl Export { /// Set the latency tolerance for each per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 97a2647d3ff..732ae46af1a 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -10,6 +10,15 @@ use hang::catalog::{AudioCodec, VideoCodec}; use super::{Export, Import}; +/// A drift budget no test timeline comes close to, so the exporter reads every group. +/// +/// The media track's full retention window, so an exporter started after publishing +/// can still read every retained group. These tests write or import a whole broadcast +/// and only then export it, which the +/// exporter's default [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) collapses to the +/// live edge: completeness has to be asked for, exactly as a real recorder does. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + /// A minimal `AVCDecoderConfigurationRecord` (profile 0x42, level 0x1f, one SPS + PPS). fn avcc() -> Vec { let sps = [0x67u8, 0x42, 0xc0, 0x1f]; @@ -169,7 +178,10 @@ async fn export_emits_sequence_headers_and_frames() { importer.decode(&bytes::BytesMut::from(synth_flv().as_slice())).unwrap(); catalog.finish().unwrap(); - let exporter = Export::new(crate::source::announced(&consumer)).await.unwrap(); + let exporter = Export::new(crate::source::announced(&consumer)) + .await + .unwrap() + .with_latency(crate::Latency::max(RECORDING_LATENCY)); let exported = drain_export(exporter, importer).await; let tags = parse_tags(&exported); diff --git a/rs/moq-mux/src/container/flv/import_test.rs b/rs/moq-mux/src/container/flv/import_test.rs index 1086ead95ed..5c9ce8bd9d9 100644 --- a/rs/moq-mux/src/container/flv/import_test.rs +++ b/rs/moq-mux/src/container/flv/import_test.rs @@ -127,9 +127,15 @@ async fn import_emits_frames() { let video_name = snap.video.renditions.keys().next().unwrap().clone(); // Decode the video track back through the Legacy container. - let track = consumer.track(&video_name).unwrap().subscribe(None).await.unwrap(); - let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy) - .with_latency(Latency::max(std::time::Duration::from_secs(1))); + let track = consumer + .track(&video_name) + .unwrap() + .subscribe( + moq_net::track::Subscription::default().with_latency(Latency::max(std::time::Duration::from_secs(1))), + ) + .await + .unwrap(); + let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let frame = decoder.read().await.unwrap().expect("a video frame"); assert!(frame.keyframe); // The payload is the length-prefixed NALU, carried through verbatim. @@ -414,9 +420,15 @@ async fn import_enhanced_av1() { assert!(matches!(v.codec, VideoCodec::AV1(_))); assert_eq!(v.description.as_ref().map(|b| b.as_ref()), Some(&AV1C[..])); - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); - let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy) - .with_latency(Latency::max(std::time::Duration::from_secs(1))); + let track = consumer + .track(name) + .unwrap() + .subscribe( + moq_net::track::Subscription::default().with_latency(Latency::max(std::time::Duration::from_secs(1))), + ) + .await + .unwrap(); + let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let frame = decoder.read().await.unwrap().expect("an AV1 frame"); assert!(frame.keyframe); assert_eq!(frame.payload.as_ref(), payload); @@ -517,9 +529,15 @@ async fn import_reports_negative_pts_and_can_resume() { let snap = catalog.snapshot(); let name = snap.video.renditions.keys().next().unwrap(); - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); - let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy) - .with_latency(Latency::max(std::time::Duration::from_secs(1))); + let track = consumer + .track(name) + .unwrap() + .subscribe( + moq_net::track::Subscription::default().with_latency(Latency::max(std::time::Duration::from_secs(1))), + ) + .await + .unwrap(); + let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let frame = decoder.read().await.unwrap().expect("the good frame"); assert_eq!(frame.timestamp.as_millis(), 10); } @@ -550,9 +568,15 @@ async fn import_enhanced_hvc1_applies_composition_time() { let snap = catalog.snapshot(); let name = snap.video.renditions.keys().next().unwrap(); - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); - let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy) - .with_latency(Latency::max(std::time::Duration::from_secs(1))); + let track = consumer + .track(name) + .unwrap() + .subscribe( + moq_net::track::Subscription::default().with_latency(Latency::max(std::time::Duration::from_secs(1))), + ) + .await + .unwrap(); + let mut decoder = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let frame = decoder.read().await.unwrap().expect("a video frame"); assert_eq!(frame.timestamp.as_millis(), 17); } diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index cb3d27a3bca..9a7eef94113 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -167,8 +167,8 @@ impl Export { /// Set the latency tolerance for each per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; diff --git a/rs/moq-mux/src/container/fmp4/export_test.rs b/rs/moq-mux/src/container/fmp4/export_test.rs index d35dbd0cf94..c5085fafed2 100644 --- a/rs/moq-mux/src/container/fmp4/export_test.rs +++ b/rs/moq-mux/src/container/fmp4/export_test.rs @@ -7,6 +7,13 @@ use mp4_atom::{DecodeMaybe, Encode}; use crate::container::test_util::{Live, PPS, SPS, raw_frame, video_frame}; +/// The media track's full retention window, so an exporter started after publishing +/// can still read every retained group. These tests write or import a whole broadcast +/// and only then export it, which the +/// exporter's default [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) collapses to the +/// live edge: completeness has to be asked for, exactly as a real recorder does. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + /// Avc3-shape source (catalog `Container::Legacy`, `H264 { inline: true }`, /// `description: None`) → fMP4 / CMAF export must synthesize a valid init /// segment from the codec config the Avc1 transform builds on the wire. @@ -530,7 +537,8 @@ async fn next_chunk_reports_segment_metadata() { // Sub-GOP cap so GOP 0 splits into two parts (the trailing part non-independent). let mut exporter = crate::container::fmp4::Export::new(live.source(), live.catalog_stream().await) - .with_fragment_duration(std::time::Duration::from_millis(20)); + .with_fragment_duration(std::time::Duration::from_millis(20)) + .with_latency(crate::Latency::max(RECORDING_LATENCY)); // First emit is the init segment, which carries no segmenting metadata to assert on. chunk_now(&mut exporter) diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 68f2bd6ad10..9d22f7eaa28 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -2,6 +2,19 @@ use futures::FutureExt; use hang::catalog::Container; use mp4_atom::{Decode, Encode}; +/// A drift budget no test timeline comes close to, so every group is read. +/// +/// The media track's full retention window, so a reader started after publishing can +/// still read every retained group. These tests write every group up front, which the +/// default [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) budget collapses to the live +/// edge: completeness has to be asked for. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + +/// A replay window with that budget, for a test asserting every group is delivered. +fn replay() -> moq_net::track::Subscription { + moq_net::track::Subscription::default().with_latency(moq_net::Latency::max(RECORDING_LATENCY)) +} + /// Drain every group currently buffered on the consumer without waiting for new ones. /// Used in tests where the producer is still alive after writing. #[cfg(test)] @@ -631,8 +644,8 @@ async fn segmented_source_groups_per_segment() { let snapshot = catalog.snapshot(); let video_name = snapshot.video.renditions.keys().next().unwrap().clone(); let audio_name = snapshot.audio.renditions.keys().next().unwrap().clone(); - let mut video_track = consumer.track(&video_name).unwrap().subscribe(None).await.unwrap(); - let mut audio_track = consumer.track(&audio_name).unwrap().subscribe(None).await.unwrap(); + let mut video_track = consumer.track(&video_name).unwrap().subscribe(replay()).await.unwrap(); + let mut audio_track = consumer.track(&audio_name).unwrap().subscribe(replay()).await.unwrap(); // Three 1s segments: 2 video fragments each (only the first an IDR) and 4 audio fragments, // so a per-fragment grouping and a per-segment one can't be confused. @@ -867,8 +880,8 @@ async fn a_single_leading_styp_still_segments_on_keyframes() { let snapshot = catalog.snapshot(); let video_name = snapshot.video.renditions.keys().next().unwrap().clone(); let audio_name = snapshot.audio.renditions.keys().next().unwrap().clone(); - let mut video_track = consumer.track(&video_name).unwrap().subscribe(None).await.unwrap(); - let mut audio_track = consumer.track(&audio_name).unwrap().subscribe(None).await.unwrap(); + let mut video_track = consumer.track(&video_name).unwrap().subscribe(replay()).await.unwrap(); + let mut audio_track = consumer.track(&audio_name).unwrap().subscribe(replay()).await.unwrap(); // One styp up front, then four segments' worth of fragments each opening on an IDR. fmp4.decode(&styp()).unwrap(); diff --git a/rs/moq-mux/src/container/mkv/export.rs b/rs/moq-mux/src/container/mkv/export.rs index 5769d12df09..59df461e756 100644 --- a/rs/moq-mux/src/container/mkv/export.rs +++ b/rs/moq-mux/src/container/mkv/export.rs @@ -173,8 +173,8 @@ impl Export { /// Set the latency tolerance for each per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; diff --git a/rs/moq-mux/src/container/mkv/export_test.rs b/rs/moq-mux/src/container/mkv/export_test.rs index a840b268cf6..39935745d24 100644 --- a/rs/moq-mux/src/container/mkv/export_test.rs +++ b/rs/moq-mux/src/container/mkv/export_test.rs @@ -13,6 +13,15 @@ use webm_iterable::matroska_spec::{Master, MatroskaSpec, SimpleBlock}; use crate::container::test_util::{IDR, Live, PPS, SPS, raw_frame, video_frame}; +/// A drift budget no test timeline comes close to, so the exporter reads every group. +/// +/// The media track's full retention window, so an exporter started after publishing +/// can still read every retained group. These tests import a whole file and only then +/// export it, which the exporter's default +/// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) collapses to the live edge: +/// completeness has to be asked for, exactly as a real recorder does. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + #[tokio::test(start_paused = true)] async fn export_header_roundtrip_vp9_opus() { // Build a tiny synthetic WebM with one VP9 video track and one Opus audio track. @@ -367,7 +376,8 @@ async fn export_emits_blocks_for_each_frame() { let mut exporter = crate::container::mkv::Export::new(crate::source::announced(&consumer), catalog_stream) // Use per-frame clustering so each frame is observable as its own // Cluster chunk; batching is exercised in a dedicated test below. - .with_fragment_duration(std::time::Duration::ZERO); + .with_fragment_duration(std::time::Duration::ZERO) + .with_latency(crate::Latency::max(RECORDING_LATENCY)); let mut exported: Vec = Vec::new(); let mut importer = Some(importer); @@ -605,7 +615,8 @@ async fn export_fragment_duration_batches_blocks() { .await .expect("catalog consumer"); let mut exporter = crate::container::mkv::Export::new(crate::source::announced(&consumer), catalog_stream) - .with_fragment_duration(std::time::Duration::from_secs(2)); + .with_fragment_duration(std::time::Duration::from_secs(2)) + .with_latency(crate::Latency::max(RECORDING_LATENCY)); let mut exported: Vec = Vec::new(); let mut importer = Some(importer); diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index fb2ca4569d3..8e7de9a752c 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -398,6 +398,19 @@ mod tests { .unwrap() } + /// A replay window wide enough to read a whole batch back. + /// + /// These tests write every group up front and only then read, which the default + /// [`Latency::REAL_TIME`](moq_net::Latency::REAL_TIME) budget collapses to the live + /// edge: history has to be asked for. + fn replay() -> moq_net::track::Subscription { + moq_net::track::Subscription::default().with_latency(moq_net::Latency::max(RECORDING_LATENCY)) + } + + /// The media track's full retention window, so readers started after publishing + /// can still consume every retained group. + const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + fn frame(timestamp_us: u64, keyframe: bool) -> Frame { Frame { timestamp: Timestamp::from_micros(timestamp_us).unwrap(), @@ -544,8 +557,14 @@ mod tests { /// consumer can see the break instead of inferring continuity from adjacent sequences. #[tokio::test] async fn discontinuity_publishes_an_empty_group() { - let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + // The resumed clock jumps forty minutes, so both the retention window and the + // drift budget have to cover it or the pre-discontinuity group reads as ancient. + let discontinuity_latency = std::time::Duration::from_secs(41 * 60); + let info = hang::container::track_info().with_latency_max(discontinuity_latency); + let track = track_producer("test", info); + let consumer = track.subscribe( + moq_net::track::Subscription::default().with_latency(moq_net::Latency::max(discontinuity_latency)), + ); let mut producer = Producer::new(track, Container::Legacy); producer.write(frame(0, true)).unwrap(); @@ -581,7 +600,7 @@ mod tests { #[tokio::test] async fn keyframe_closes_group_immediately() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); producer.write(frame(0, true)).unwrap(); // first frame must be a keyframe @@ -600,7 +619,7 @@ mod tests { #[tokio::test] async fn needs_keyframe_drives_audio_grouping() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); // Drive grouping off `needs_keyframe`, as the audio importers do: the first frame of each @@ -624,7 +643,7 @@ mod tests { #[tokio::test] async fn cut_closes_immediately() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); producer.write(frame(0, true)).unwrap(); @@ -642,7 +661,7 @@ mod tests { #[allow(deprecated)] async fn deprecated_finish_group_still_closes() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); producer.write(frame(0, true)).unwrap(); @@ -677,7 +696,7 @@ mod tests { #[tokio::test] async fn seek_uses_explicit_sequence() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); producer.write(frame(0, true)).unwrap(); // seq 0 @@ -692,7 +711,7 @@ mod tests { #[tokio::test] async fn seek_clears_pending_after_use() { let track = track_producer("test", hang::container::track_info()); - let consumer = track.subscribe(None); + let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Legacy); producer.seek(5).unwrap(); diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 1d9b01dd57f..6273aded154 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -228,7 +228,8 @@ impl ExportSource { Poll::Pending => return Poll::Pending, } }; - self.state = SourceState::Subscribing(broadcast.track(&name)?.subscribe(None)); + let subscription = moq_net::track::Subscription::default().with_latency(self.latency); + self.state = SourceState::Subscribing(broadcast.track(&name)?.subscribe(subscription)); } // Resolve the subscription before reading any frames. @@ -248,7 +249,7 @@ impl ExportSource { .media .take() .expect("media present until the subscription resolves"); - self.state = SourceState::Active(Box::new(Consumer::new(track, media).with_latency(self.latency))); + self.state = SourceState::Active(Box::new(Consumer::new(track, media))); } loop { @@ -436,4 +437,26 @@ mod tests { .unwrap_or_else(|| panic!("{reference:?} should keep the rendition")); } } + + /// The requested budget must be present on the first SUBSCRIBE. Updating it + /// after SUBSCRIBE_OK cannot recover backlog the publisher already skipped. + #[tokio::test] + async fn latency_is_sent_with_the_initial_subscription() { + let live = Live::avc3(); + let latency = crate::Latency::max(std::time::Duration::from_secs(10)); + let mut export = ExportSource::for_video(&live.source(), live.track.name(), &video(None), latency) + .unwrap() + .expect("fixture should produce a video rendition"); + + let observed = kio::wait(|waiter| { + let _ = export.poll_read(waiter); + match live.track.subscription() { + Some(subscription) => Poll::Ready(subscription.latency), + None => Poll::Pending, + } + }) + .await; + + assert_eq!(observed, latency); + } } diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index e410afd27fe..494c2a972aa 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -185,6 +185,11 @@ struct SiTrack { pending: Option<(moq_net::group::Consumer, super::si::Snapshot)>, /// Media timestamp of the last emission ([`due`]). last_emit: Option, + /// The same budget the media sources use. SI carries table snapshots at a low + /// rate, so the real-time default would take only the newest group and drop + /// the revisions between: an SI track needs the export's replay window as much + /// as the media it describes. + latency: crate::Latency, } /// The SI subscription's lifecycle, mirroring `ExportSource`'s but reading raw @@ -203,7 +208,7 @@ enum SiState { } impl SiTrack { - fn new(source: &crate::Source, track: &str, interval: Option) -> Self { + fn new(source: &crate::Source, track: &str, interval: Option, latency: crate::Latency) -> Self { Self { track: track.to_string(), interval, @@ -211,6 +216,7 @@ impl SiTrack { active: Default::default(), pending: None, last_emit: None, + latency, } } @@ -232,7 +238,9 @@ impl SiTrack { }; self.state = match resolved { Ok((broadcast, name)) => match broadcast.track(&name) { - Ok(track) => SiState::Subscribing(track.subscribe(None)), + Ok(track) => SiState::Subscribing( + track.subscribe(moq_net::track::Subscription::default().with_latency(self.latency)), + ), Err(err) => { tracing::warn!(%err, track = %name, "SI track unavailable; carrying the last snapshot"); SiState::Done @@ -366,8 +374,8 @@ impl Export { /// Set the latency tolerance for each per-track source. /// - /// See [`Consumer::with_latency`](crate::container::Consumer::with_latency) for the - /// per-track skip behavior. Defaults to + /// See [`Consumer`](crate::container::Consumer) for the per-track skip behavior. + /// Defaults to /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) (skip aggressively). pub fn with_latency(mut self, latency: crate::Latency) -> Self { self.latency = latency; @@ -575,7 +583,7 @@ impl Export { // staying attached would repeat its stale sections forever. The last // snapshot carries across so emission never goes dark mid-swap. Some(existing) if existing.track != entry.track => { - let mut replacement = SiTrack::new(&self.source, &entry.track, entry.interval); + let mut replacement = SiTrack::new(&self.source, &entry.track, entry.interval, self.latency); replacement.active = std::mem::take(&mut existing.active); replacement.last_emit = existing.last_emit; *existing = replacement; @@ -584,7 +592,7 @@ impl Export { None => { self.si.insert( (*pid, *table_id), - SiTrack::new(&self.source, &entry.track, entry.interval), + SiTrack::new(&self.source, &entry.track, entry.interval, self.latency), ); } } diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index b3c18908c3f..df6f273637b 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -60,12 +60,22 @@ fn length_prefixed(nals: &[&[u8]]) -> Bytes { /// finished, retained tracks; that means it never reaches a hard end-of-stream, /// so we pull until a `next()` blocks (`Pending`, surfaced as a timeout under /// paused time) or the stream ends. +/// A drift budget no test timeline comes close to, so the exporter reads every group. +/// +/// The media track's full retention window, so an exporter started after publishing +/// can still read every retained group. These tests write a whole broadcast up front +/// and only then export it, which the +/// exporter's default [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) collapses to the +/// live edge: completeness has to be asked for, exactly as a real recorder does. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + async fn drain(consumer: moq_net::broadcast::Consumer) -> BytesMut { drain_with(Export::new(crate::source::announced(&consumer)).await.unwrap()).await } /// `drain` for an exporter built with an explicit catalog extension. -async fn drain_with(mut exporter: Export) -> BytesMut { +async fn drain_with(exporter: Export) -> BytesMut { + let mut exporter = exporter.with_latency(crate::Latency::max(RECORDING_LATENCY)); let mut out = BytesMut::new(); // `while let Ok` stops on the first timeout (`Pending`: no more output). while let Ok(res) = tokio::time::timeout(std::time::Duration::from_secs(1), exporter.next()).await { @@ -638,7 +648,12 @@ async fn export_scte35_roundtrip() { assert_eq!(verbatim, 1, "round-trip lost the SCTE-35 track"); let name = scte_track(&snapshot).expect("a scte35 track"); - let track = consumer2.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer2 + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut scte_reader = crate::container::Consumer::new(track, HangContainer::Legacy); let frame = scte_reader .read() @@ -733,7 +748,12 @@ async fn export_pes_verbatim_roundtrip() { assert_eq!(verbatim.stream_id, Some(STREAM_ID), "PES stream_id preserved"); let name = name.clone(); - let track = consumer2.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer2 + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, HangContainer::Legacy); let frame = reader .read() @@ -801,7 +821,12 @@ async fn scte35_without_video_export_is_rejected() { /// Subscribe to a track and read every retained frame payload it holds. async fn read_frames(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec> { - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, HangContainer::Legacy); let mut frames = Vec::new(); while let Ok(res) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await { @@ -1117,7 +1142,12 @@ fn scte_track(snap: &crate::catalog::hang::Catalog) -> Option Vec<(Vec, Timestamp)> { - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, HangContainer::Legacy); let mut cues = Vec::new(); while let Ok(res) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await { @@ -2430,9 +2460,12 @@ async fn repointed_si_entry_resubscribes() { producer.cut(None).unwrap(); }; + // Writes both GOPs up front and only then reads, so it needs a replay window: + // the real-time default would take the live edge and skip the first. let mut exporter = Export::with_ts(crate::source::announced(&consumer), crate::catalog::CatalogFormat::Hang) .await - .unwrap(); + .unwrap() + .with_latency(crate::Latency::max(RECORDING_LATENCY)); let mut before = BytesMut::new(); write_key(&mut producer, 0); write_key(&mut producer, 1); diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 61e81675509..d8f19e036d3 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -2305,6 +2305,14 @@ impl Read for Feed { #[cfg(test)] mod test { + + /// A drift budget no test timeline comes close to, so the reader sees every group. + /// + /// The media track's full retention window, so a reader started after importing can + /// still read every retained group. These tests import a whole file first, which the default + /// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) budget collapses to the live + /// edge: completeness has to be asked for. + const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); use mpeg2ts::es::StreamType; use super::SectionReassembler; @@ -2638,8 +2646,13 @@ mod test { // track name while it is still registered. let name = catalog.snapshot().mpegts.tracks.keys().next().unwrap().clone(); import.finish().unwrap(); - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); - let mut reader = Consumer::new(track, Container::Legacy).with_latency(Latency::REAL_TIME); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); + let mut reader = Consumer::new(track, Container::Legacy); let frame = tokio::time::timeout(std::time::Duration::from_secs(1), reader.read()) .await .expect("cue read timed out") @@ -2870,7 +2883,12 @@ mod test { .next() .expect("an audio track") .clone(); - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let mut frames = Vec::new(); while let Ok(Ok(Some(frame))) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await @@ -3678,7 +3696,7 @@ mod test { let track = consumer .track(hang::catalog::Catalog::DEFAULT_NAME) .unwrap() - .subscribe(None) + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(RECORDING_LATENCY))) .await .unwrap(); let mut reader = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); @@ -3935,8 +3953,13 @@ mod test { import.finish().unwrap(); let name = catalog.snapshot().mpegts.tracks.keys().next().unwrap().clone(); - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); - let mut reader = Consumer::new(track, Container::Legacy).with_latency(Latency::REAL_TIME); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); + let mut reader = Consumer::new(track, Container::Legacy); let frame = tokio::time::timeout(std::time::Duration::from_secs(1), reader.read()) .await .expect("cue read timed out") @@ -4080,8 +4103,13 @@ mod test { assert_eq!(verbatim.stream_id, Some(0xC0), "recorded the PES stream_id"); assert_eq!(track.pid, DATA_PID, "recorded the original PID"); - let track = consumer.track(name.as_str()).unwrap().subscribe(None).await.unwrap(); - let mut reader = Consumer::new(track, Container::Legacy).with_latency(Latency::REAL_TIME); + let track = consumer + .track(name.as_str()) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); + let mut reader = Consumer::new(track, Container::Legacy); let frame = tokio::time::timeout(std::time::Duration::from_secs(1), reader.read()) .await .expect("verbatim read timed out") diff --git a/rs/moq-mux/src/container/ts/import_test.rs b/rs/moq-mux/src/container/ts/import_test.rs index 8ec7be5dbaa..efe35341274 100644 --- a/rs/moq-mux/src/container/ts/import_test.rs +++ b/rs/moq-mux/src/container/ts/import_test.rs @@ -5,6 +5,14 @@ use bytes::BytesMut; +/// A drift budget no test timeline comes close to, so the reader sees every group. +/// +/// The media track's full retention window, so a reader started after importing can +/// still read every retained group. These tests import a whole file first, which the default +/// [`Latency::REAL_TIME`](crate::Latency::REAL_TIME) budget collapses to the live edge: +/// completeness has to be asked for. +const RECORDING_LATENCY: std::time::Duration = std::time::Duration::from_secs(30); + /// Decode a whole TS buffer into a fresh broadcast and return the catalog. fn import_ts(data: &[u8]) -> crate::catalog::hang::Catalog { let mut broadcast = moq_net::broadcast::Info::new().produce(); @@ -142,7 +150,12 @@ async fn import_opus_frames() { .expect("an Opus track") .clone(); - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let mut frames = Vec::new(); while let Ok(res) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await { @@ -284,7 +297,8 @@ async fn import_export_import_roundtrip() { // subscribe to the finished, retained tracks. let mut exporter = crate::container::ts::Export::new(crate::source::announced(&consumer)) .await - .unwrap(); + .unwrap() + .with_latency(crate::Latency::max(RECORDING_LATENCY)); let mut out = BytesMut::new(); while let Ok(res) = tokio::time::timeout(std::time::Duration::from_secs(1), exporter.next()).await { match res.expect("exporter error") { @@ -336,7 +350,12 @@ async fn survives_midstream_join() { // The track resumes at the keyframe: the leading delta was dropped, the IDR // anchors the one and only group. - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let mut frames = Vec::new(); while let Ok(Ok(Some(frame))) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await { @@ -380,7 +399,12 @@ async fn kyrion_dirtystart_extracts_real_cues() { .find(|(_, t)| t.verbatim.as_ref().is_some_and(|v| v.stream_type == 0x86)) .map(|(name, _)| name.clone()) .expect("scte35 track"); - let track = consumer.track(&name).unwrap().subscribe(None).await.unwrap(); + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_latency(crate::Latency::max(RECORDING_LATENCY))) + .await + .unwrap(); let mut reader = crate::container::Consumer::new(track, crate::catalog::hang::Container::Legacy); let mut cues = Vec::new(); while let Ok(Ok(Some(frame))) = tokio::time::timeout(std::time::Duration::from_millis(50), reader.read()).await { diff --git a/rs/moq-mux/src/import/track.rs b/rs/moq-mux/src/import/track.rs index d642af3c4a6..d3f1bd4b8e7 100644 --- a/rs/moq-mux/src/import/track.rs +++ b/rs/moq-mux/src/import/track.rs @@ -888,7 +888,12 @@ mod tests { catalog: &crate::catalog::Producer, ) -> (crate::codec::opus::Import, moq_net::track::Subscriber) { let track = broadcast.create_track("audio", hang::container::track_info()).unwrap(); - let subscriber = track.subscribe(None); + // Every group is written before anything reads, which the default + // REAL_TIME budget would collapse to the live edge. + let subscriber = track.subscribe( + moq_net::track::Subscription::default() + .with_latency(moq_net::Latency::max(std::time::Duration::from_secs(30))), + ); let config = crate::codec::opus::Config::new(48_000, 2); let import = crate::codec::opus::Import::new(track, catalog.reserve(), config.into()).unwrap(); (import, subscriber) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 5be62aba061..47afe36ad96 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1,7 +1,8 @@ -use crate::{frame, group, origin, track}; +use crate::{Latency, frame, group, origin, track}; use std::{ collections::HashMap, task::{Poll, ready}, + time::Duration, }; use web_transport_trait::poll::SendStream as _; @@ -16,6 +17,21 @@ use crate::{ use super::{Message, Version, cluster, peer}; +/// Largest millisecond duration every implementation can carry losslessly. +const MAX_SAFE_LATENCY_MS: u64 = (1_u64 << 53) - 1; + +/// Build the serving-side subscription for a peer whose wire protocol carries no +/// latency preference. The receiver applies its own budget after the transfer. +fn serving_subscription(subscriber_priority: u8) -> Subscription { + Subscription { + priority: super::priority::from_wire(subscriber_priority), + // Demand can cross a Lite hop before the producer's retention bound is + // known, so use the largest duration that remains wire-encodable. + latency: Latency::max(Duration::from_millis(MAX_SAFE_LATENCY_MS)), + ..Default::default() + } +} + /// A broadcast whose route table is watched for changes in what we advertise: the /// namespace becoming (un)advertisable, or its path or cost moving. struct Watched { @@ -537,10 +553,9 @@ impl Publisher { } }; - let subscription = Subscription { - priority: super::priority::from_wire(msg.subscriber_priority), - ..Default::default() - }; + // moq-transport has no subscriber latency parameter. Keep everything the + // producer retained and let the receiving subscriber enforce its own budget. + let subscription = serving_subscription(msg.subscriber_priority); let track = match async { broadcast.track(&msg.track_name)?.subscribe(subscription).await }.await { Ok(track) => track, @@ -1515,6 +1530,10 @@ impl GroupServe { loop { match &mut self.state { GroupState::Open => { + if self.group.poll_expired(waiter) { + self.state = GroupState::Done; + return Poll::Ready(Err(Error::Old)); + } let stream = match ready!(self.session.poll_open_uni(&mut cx)) { Ok(stream) => stream, Err(err) => { @@ -1547,7 +1566,16 @@ impl GroupServe { match writer.poll_flush(&mut cx) { Poll::Ready(Ok(())) => {} Poll::Ready(Err(err)) => break 'serve Err(err), - Poll::Pending => return Poll::Pending, + // Parking on the transport is the one stall the group cursor cannot + // see, and the only place a served group applies the drift budget: + // flow control must not pin a stream that has gone stale. `true` + // because the transport still owns bytes the cursor has released. + Poll::Pending => { + if self.group.poll_expired_while_pending(waiter, true) { + break 'serve Err(Error::Old); + } + return Poll::Pending; + } } if let Some(pending) = chunk { match writer.poll_write(&mut cx, pending) { @@ -1557,7 +1585,16 @@ impl GroupServe { } } Poll::Ready(Err(err)) => break 'serve Err(err), - Poll::Pending => return Poll::Pending, + // Parking on the transport is the one stall the group cursor cannot + // see, and the only place a served group applies the drift budget: + // flow control must not pin a stream that has gone stale. `true` + // because the transport still owns bytes the cursor has released. + Poll::Pending => { + if self.group.poll_expired_while_pending(waiter, true) { + break 'serve Err(Error::Old); + } + return Poll::Pending; + } } } else if let Some(pending) = frame { match pending.poll_read_chunk(waiter) { @@ -1696,6 +1733,111 @@ mod group_priority_test { "model priority must pass through unchanged" ); } + + /// A subgroup waiting for stream credit keeps its subscription expiry armed. + #[tokio::test] + async fn group_waiting_for_stream_credit_expires() { + tokio::time::pause(); + + let gate = kio::Producer::new(false); + let session = SinkSession::gated_open_uni(gate.consume()); + let mut track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(crate::Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let mut serve = GroupServe { + session, + msg: ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + priority: 0, + group, + timescale: Timescale::default(), + version: Version::Draft19, + state: GroupState::Open, + }; + let mut serving = std::pin::pin!(kio::wait(|waiter| serve.poll_serve(waiter))); + assert!( + futures::poll!(serving.as_mut()).is_pending(), + "stream credit is exhausted" + ); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(crate::Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(serving.await, Err(Error::Old))); + } + + /// The final payload remains guarded after its frame has advanced the group cursor. + #[tokio::test] + async fn blocked_final_transport_chunk_expires_with_the_group() { + tokio::time::pause(); + + let gate = kio::Producer::new(true); + let session = SinkSession::gated_uni(gate.consume()); + let mut track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + let mut frame = old + .create_frame(frame::Info { + timestamp: crate::Timestamp::ZERO, + size: 2, + }) + .unwrap(); + frame.write(b"a".as_slice()).unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + let mut serve = GroupServe { + session, + msg: ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + priority: 0, + group, + timescale: Timescale::default(), + version: Version::Draft19, + state: GroupState::Open, + }; + let mut serving = std::pin::pin!(kio::wait(|waiter| serve.poll_serve(waiter))); + assert!( + futures::poll!(serving.as_mut()).is_pending(), + "waiting for the final byte" + ); + + let Ok(mut open) = gate.write() else { + panic!("transport gate closed"); + }; + *open = false; + drop(open); + frame.write(b"b".as_slice()).unwrap(); + frame.finish().unwrap(); + old.finish().unwrap(); + assert!( + futures::poll!(serving.as_mut()).is_pending(), + "the final byte is transport-blocked" + ); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(crate::Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(serving.await, Err(Error::Old))); + } } #[cfg(test)] @@ -1736,6 +1878,7 @@ mod tests { use super::*; use crate::lite::test_transport::SinkSession; use crate::model::ProduceTest; + use futures::FutureExt; async fn settle() { tokio::time::sleep(std::time::Duration::from_millis(1)).await; @@ -1757,6 +1900,33 @@ mod tests { slot } + /// moq-transport cannot carry the receiver's latency budget, so the serving + /// subscription must preserve everything the producer still retains. + #[test] + fn serving_subscription_keeps_retained_backlog() { + let mut producer = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", None); + for millis in [0, 1000] { + let mut group = producer.append_group().unwrap(); + group + .write_frame(crate::Timestamp::from_millis(millis).unwrap(), b"frame".as_slice()) + .unwrap(); + group.finish().unwrap(); + } + + let subscription = serving_subscription(128); + assert_eq!(subscription.latency.max.as_millis(), MAX_SAFE_LATENCY_MS as u128); + let mut subscriber = producer.subscribe(subscription); + for sequence in [0, 1] { + let group = subscriber + .recv_group() + .now_or_never() + .expect("retained group should be ready") + .unwrap() + .expect("track should remain open"); + assert_eq!(group.sequence, sequence); + } + } + /// A peer that requires solicitation, which is what hands the advertisements to the /// SUBSCRIBE_NAMESPACE stream. fn requires_solicitation() -> peer::PeerSetup { diff --git a/rs/moq-net/src/latency.rs b/rs/moq-net/src/latency.rs index 2155eff5524..636078b6b75 100644 --- a/rs/moq-net/src/latency.rs +++ b/rs/moq-net/src/latency.rs @@ -4,12 +4,6 @@ use std::time::Duration; /// How far a subscriber may drift behind the live edge before a group is skipped. /// -/// One budget, enforced in two places: the publisher's cache drops a group that exceeds it -/// (this is `Subscriber Max Latency` on the wire, see -/// [`Subscription::latency`](crate::track::Subscription::latency)), and a receiver that -/// buffers applies the same bound locally while reordering. A group is skipped once either -/// measure exceeds it. -/// /// Only a ceiling today: a stalled group is skipped once newer data is [`max`](Self::max) /// ahead of it. [`Latency::REAL_TIME`] (the default) skips aggressively, so any group with /// a newer alternative is dropped. @@ -18,9 +12,40 @@ use std::time::Duration; /// ahead, so raising it buys a stalled group more time to arrive rather than padding a /// buffer. /// +/// # Where it is enforced +/// +/// At both ends of a subscription, and neither alone is enough. A publisher skips a group +/// that has drifted past the budget instead of putting it on the wire, which is what bounds +/// a backlog before it costs bandwidth. But what reaches a publisher is the aggregate +/// across every subscriber, which [`merge`](Self::merge) resolves in favor of the most +/// tolerant one, so that gate is only ever as tight as the most patient viewer. The +/// subscriber applies the same budget again as it reads, where its own budget is the only +/// one in play and the semantics are exact. +/// +/// This bounds a *subscription*. [`track::Consumer::fetch_group`](crate::track::Consumer::fetch_group) +/// is exempt: it names one old group explicitly, so there is no live edge to be late +/// against. +/// +/// # How drift is measured +/// +/// By both presentation time and wall-clock arrival time, with either age able to expire +/// the group. Presentation time compares a group's first timestamp against the newest one +/// above it, so a backlog delivered as a burst still reads as its true age. Wall-clock time +/// compares when each group entered this hop, which backstops an empty or stalled group that +/// has not supplied a first-frame timestamp. +/// +/// Protocols whose wire can't carry a timestamp (pre-Lite05 moq-lite, moq-transport without +/// the Timestamp property) have their frames stamped on receipt instead, which makes the +/// measure burst-blind on the receiving side: thirty seconds of backlog delivered in three +/// reads as three. The publisher's copy is stamped as it produces, so the gate there still +/// holds; it is just the coarser of the two. +/// +/// # Not a retention window +/// /// Distinct from [`track::Info::latency_max`](crate::track::Info::latency_max), which is a /// *retention* bound (how long the publisher keeps a group, the inverse of an HTTP -/// `Cache-Control: max-age`) rather than a drift budget. +/// `Cache-Control: max-age`) rather than a drift budget. A budget is clamped to it, since +/// waiting for a group longer than it is kept around cannot produce it. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct Latency { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index e838518cb19..5f621027eab 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -89,6 +89,23 @@ struct Shared { goaway: crate::goaway::Protocol, } +/// Largest millisecond duration every implementation can carry losslessly. +const MAX_SAFE_LATENCY_MS: u64 = (1_u64 << 53) - 1; + +/// The budget to serve a peer with, given what its wire could tell us. +/// +/// A version without the field decodes as [`Duration::ZERO`], which is +/// indistinguishable from a peer genuinely asking for the live edge. Serving that +/// as real time would discard backlog a legacy subscriber never declined, so fall +/// back to a window wide enough not to drop and leave enforcement to the receiver, +/// exactly as the IETF path does for the same reason. +fn serving_latency(version: Version, requested: Duration) -> crate::Latency { + match version.carries_latency() { + true => crate::Latency::max(requested), + false => crate::Latency::max(Duration::from_millis(MAX_SAFE_LATENCY_MS)), + } +} + impl Shared { /// The origin to resolve a peer-requested broadcast from: excludes routes /// through the peer when its SETUP declared an origin id, so a subscription @@ -1202,8 +1219,9 @@ enum SubscribeState { msg: lite::Subscribe<'static>, subscribing: track::Subscribing, }, - /// Streaming groups and datagrams. - Run(TrackRun), + /// Streaming groups and datagrams. Boxed: by far the largest state, and the enum + /// is moved on every transition. + Run(Box>), /// The track finished: draining the in-flight group streams before the FIN. Drain { children: kio::Tasks, @@ -1292,7 +1310,7 @@ impl SubscribeServe { let subscription = crate::track::Subscription { priority: msg.priority, ordered: msg.ordered, - latency: crate::Latency::max(msg.latency_max), + latency: serving_latency(self.shared.version, msg.latency_max), ..Bounds::from(&msg).positions() }; @@ -1358,7 +1376,7 @@ impl SubscribeServe { }; let run = TrackRun::new(sub, track, Bounds::from(&msg), track_priority_tx); - self.state = SubscribeState::Run(run); + self.state = SubscribeState::Run(Box::new(run)); } SubscribeState::Run(run) => { let stream = self.stream.as_mut().expect("stream present"); @@ -1718,7 +1736,8 @@ mod test { use futures::FutureExt; let mut producer = track_producer("test"); - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer + .subscribe(track::Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(5)))); producer.create_group(group::Info { sequence: 2 }).unwrap(); match recv_next(&mut subscriber, false, false).await.unwrap() { @@ -2768,7 +2787,7 @@ impl TrackRun { let _ = self.track.update(crate::track::Subscription { priority: upd.priority, ordered: upd.ordered, - latency: crate::Latency::max(upd.latency_max), + latency: serving_latency(self.ctx.version, upd.latency_max), ..bounds.positions() }); if let Some(start_group) = upd.start_group { @@ -2910,6 +2929,10 @@ impl GroupServe { loop { match &mut self.state { GroupState::Open => { + if self.group.poll_expired(waiter) { + self.state = GroupState::Done; + return Poll::Ready(Err(Error::Old)); + } let mut cx = Context::from_waker(waiter.waker()); let stream = match ready!(self.ctx.session.poll_open_uni(&mut cx)) { Ok(stream) => stream, @@ -2969,7 +2992,16 @@ impl GroupServe { match writer.poll_flush(&mut cx) { Poll::Ready(Ok(())) => {} Poll::Ready(Err(err)) => break 'serve Err(err), - Poll::Pending => return Poll::Pending, + // Parking on the transport is the one stall the group cursor cannot + // see, and the only place a served group applies the drift budget: + // flow control must not pin a stream that has gone stale. `true` + // because the transport still owns bytes the cursor has released. + Poll::Pending => { + if self.group.poll_expired_while_pending(waiter, true) { + break 'serve Err(Error::Old); + } + return Poll::Pending; + } } if let Some(pending) = chunk { match writer.poll_write(&mut cx, pending) { @@ -2979,7 +3011,16 @@ impl GroupServe { } } Poll::Ready(Err(err)) => break 'serve Err(err), - Poll::Pending => return Poll::Pending, + // Parking on the transport is the one stall the group cursor cannot + // see, and the only place a served group applies the drift budget: + // flow control must not pin a stream that has gone stale. `true` + // because the transport still owns bytes the cursor has released. + Poll::Pending => { + if self.group.poll_expired_while_pending(waiter, true) { + break 'serve Err(Error::Old); + } + return Poll::Pending; + } } } else if let Some(pending) = frame { match pending.poll_read_chunk(waiter) { @@ -3209,6 +3250,184 @@ mod serve_group_test { assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); } + /// A subscription group keeps checking latency while a transport write is + /// flow-control blocked, so a stalled send cannot pin the stream indefinitely. + #[tokio::test] + async fn blocked_transport_write_expires_with_the_group() { + tokio::time::pause(); + + let gate = kio::Producer::new(false); + let session = SinkSession::gated_uni(gate.consume()); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + ordered: false, + version: Version::Lite06Wip, + timescale: Some(crate::Timescale::default()), + }; + + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!( + futures::poll!(serve.as_mut()).is_pending(), + "transport write is blocked" + ); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(serve.await, Err(Error::Old))); + assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); + } + + /// The final payload remains guarded after its frame has advanced the group cursor. + #[tokio::test] + async fn blocked_final_transport_chunk_expires_with_the_group() { + tokio::time::pause(); + + let gate = kio::Producer::new(true); + let session = SinkSession::gated_uni(gate.consume()); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + ordered: false, + version: Version::Lite06Wip, + timescale: Some(crate::Timescale::default()), + }; + + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + let mut frame = old + .create_frame(frame::Info { + timestamp: Timestamp::ZERO, + size: 2, + }) + .unwrap(); + frame.write(b"a".as_slice()).unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!( + futures::poll!(serve.as_mut()).is_pending(), + "waiting for the final byte" + ); + + let Ok(mut open) = gate.write() else { + panic!("transport gate closed"); + }; + *open = false; + drop(open); + frame.write(b"b".as_slice()).unwrap(); + frame.finish().unwrap(); + old.finish().unwrap(); + assert!( + futures::poll!(serve.as_mut()).is_pending(), + "the final byte is transport-blocked" + ); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(serve.await, Err(Error::Old))); + assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); + } + + /// A subscription group keeps checking latency while transport stream credit is + /// exhausted, so returning credit is reserved for content that is still live. + #[tokio::test] + async fn blocked_transport_open_expires_with_the_group() { + tokio::time::pause(); + + let gate = kio::Producer::new(false); + let session = SinkSession::gated_open_uni(gate.consume()); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + ordered: false, + version: Version::Lite06Wip, + timescale: Some(crate::Timescale::default()), + }; + + let mut track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!( + futures::poll!(serve.as_mut()).is_pending(), + "stream credit is exhausted" + ); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(serve.await, Err(Error::Old))); + } + + /// Lite01/02 have no latency field, so a SUBSCRIBE from one decodes as + /// `Duration::ZERO`. Serving that as a real-time budget would hold every legacy + /// peer to the live edge and discard backlog it never declined, so those versions + /// get a non-dropping window and leave enforcement to the receiver. + /// + /// These are the two most-preferred negotiated versions, so this is the common + /// wire, not an edge case. + #[test] + fn a_version_without_the_field_serves_a_non_dropping_budget() { + for version in [Version::Lite01, Version::Lite02] { + let latency = serving_latency(version, Duration::ZERO); + assert!( + latency.max >= Duration::from_secs(86_400), + "{version:?} must not be served as real time: {latency:?}" + ); + } + + // A version that does carry it is taken at its word, zero included. + assert_eq!(serving_latency(Version::Lite05, Duration::ZERO).max, Duration::ZERO); + assert_eq!( + serving_latency(Version::Lite05, Duration::from_secs(3)).max, + Duration::from_secs(3) + ); + } + /// A group that completes cleanly must not reset at all. The completion path /// releases the stream via `poll_close`; leaving the writer to drop after /// `finish()` would fire the Drop fallback and tack a spurious Cancel reset diff --git a/rs/moq-net/src/lite/subscribe.rs b/rs/moq-net/src/lite/subscribe.rs index 1b442ec730c..7c5829b3a55 100644 --- a/rs/moq-net/src/lite/subscribe.rs +++ b/rs/moq-net/src/lite/subscribe.rs @@ -28,6 +28,17 @@ pub struct Subscribe<'a> { pub end_frame: Option, } +impl Version { + /// Whether this version's SUBSCRIBE carries the subscriber's latency preference. + /// + /// Lite01/02 have no field for it, so a decoded `Duration::ZERO` there means + /// "not stated", not "real time". Callers that act on the budget must tell the + /// two apart or they will hold every legacy peer to the live edge. + pub(crate) fn carries_latency(self) -> bool { + !matches!(self, Version::Lite01 | Version::Lite02) + } +} + impl Message for Subscribe<'_> { fn decode_msg(r: &mut R, version: Version) -> Result { let id = u64::decode(r, version)?; diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index 6b3dd8c76fc..3b56ade9d4b 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -313,6 +313,11 @@ pub struct SinkSession { /// Set by [`Self::gated_bi`]. `None` parks `open_bi` itself forever, which is all /// a test driving only uni streams needs. bi_gate: Option>, + /// Set by [`Self::gated_uni`] to hold unidirectional stream writes. + uni_gate: Option>, + /// Set by [`Self::gated_open_uni`] to withhold unidirectional stream credit. + uni_open_gate: Option>, + uni_open_park: kio::Park, /// The ALPN to report, for a test that needs a specific negotiated version rather /// than the SETUP-negotiated fallback an absent one selects. protocol: Option<&'static str>, @@ -323,6 +328,9 @@ impl SinkSession { Self { log, bi_gate: None, + uni_gate: None, + uni_open_gate: None, + uni_open_park: kio::Park::default(), protocol: None, } } @@ -342,6 +350,33 @@ impl SinkSession { Self { log: Log::default(), bi_gate: Some(gate), + uni_gate: None, + uni_open_gate: None, + uni_open_park: kio::Park::default(), + protocol: None, + } + } + + /// Open unidirectional streams immediately, holding their writes until `gate` opens. + pub fn gated_uni(gate: kio::Consumer) -> Self { + Self { + log: Log::default(), + bi_gate: None, + uni_gate: Some(gate), + uni_open_gate: None, + uni_open_park: kio::Park::default(), + protocol: None, + } + } + + /// Hold unidirectional stream opens until `gate` grants stream credit. + pub fn gated_open_uni(gate: kio::Consumer) -> Self { + Self { + log: Log::default(), + bi_gate: None, + uni_gate: None, + uni_open_gate: Some(gate), + uni_open_park: kio::Park::default(), protocol: None, } } @@ -375,8 +410,18 @@ impl poll::Session for SinkSession { Poll::Ready(Ok((send, PendingRecv))) } - fn poll_open_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { - Poll::Ready(Ok(SinkSend::new(self.log.clone()))) + fn poll_open_uni(&mut self, cx: &mut Context<'_>) -> Poll> { + if let Some(gate) = &self.uni_open_gate { + let waiter = self.uni_open_park.hold(cx); + match gate.poll(waiter, |open| (**open).then_some(()).map_or(Poll::Pending, Poll::Ready)) { + Poll::Ready(Ok(())) => {} + Poll::Ready(Err(_)) | Poll::Pending => return Poll::Pending, + } + } + Poll::Ready(Ok(match &self.uni_gate { + Some(gate) => SinkSend::gated(self.log.clone(), gate.clone()), + None => SinkSend::new(self.log.clone()), + })) } fn poll_send_datagram(&mut self, _cx: &mut Context<'_>, _payload: &[u8]) -> Poll> { diff --git a/rs/moq-net/src/model/frame.rs b/rs/moq-net/src/model/frame.rs index ea4d8a36c7e..9241ec94bf2 100644 --- a/rs/moq-net/src/model/frame.rs +++ b/rs/moq-net/src/model/frame.rs @@ -5,9 +5,10 @@ //! through [`Producer`], which borrows its parent [`group::Producer`] exclusively so //! the borrow checker enforces that only one frame is open at a time. A [`Consumer`] //! reads one frame, sharing the group's channel rather than a per-frame one. +use std::ops::Range; use std::sync::Arc; use std::sync::OnceLock; -use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::task::{Poll, ready}; use bytes::Bytes; @@ -414,6 +415,38 @@ pub(crate) enum Source { Partial(FrameBuf), } +/// Subscriber expiry state carried across the group-to-frame handoff. +#[derive(Clone)] +pub(crate) struct Expiry { + policy: Arc, + stale_stats: stats::Meter, + stale_counted: Arc, + tail: Range, + count_payload: bool, +} + +impl Expiry { + pub(crate) fn new( + policy: Arc, + stale_stats: stats::Meter, + stale_counted: Arc, + ) -> Self { + Self { + policy, + stale_stats, + stale_counted, + tail: 0..0, + count_payload: false, + } + } + + pub(crate) fn for_frame(mut self, tail: Range, count_payload: bool) -> Self { + self.tail = tail; + self.count_payload = count_payload; + self + } +} + /// Reads one frame's payload, streaming as bytes arrive for the in-flight tail. /// /// Owns a handle to the parent group's channel (not a per-frame one), so a group with @@ -431,6 +464,9 @@ pub struct Consumer { // from the prefetch batch, whose bytes were already counted at fill), so chunks // bump `bytes` exactly once. Empty (no-op) otherwise. stats: stats::Meter, + // The parent subscription can expire after this frame handle is returned. + expiry: Option, + expired: bool, } impl std::ops::Deref for Consumer { @@ -449,6 +485,8 @@ impl Consumer { source, read_idx: 0, stats: stats::Meter::default(), + expiry: None, + expired: false, } } @@ -459,11 +497,59 @@ impl Consumer { self } + pub(crate) fn with_expiry(mut self, expiry: Expiry) -> Self { + self.expiry = Some(expiry); + self + } + + fn size(&self) -> usize { + match &self.source { + Source::Complete(bytes) => bytes.len(), + Source::Partial(_) => self.info.size as usize, + } + } + + /// Evaluate the parent subscription's drift budget. + /// + /// Only called once a read has nothing buffered to return: the budget bounds a + /// *stalled* payload, so bytes already in hand are always drained rather than + /// truncated. `self.expired` is sticky, so the answer is only ever computed once. + fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { + if self.expired || self.read_idx >= self.size() { + return self.expired; + } + let Some(expiry) = &self.expiry else { + return false; + }; + // A half-read payload sits at its own frame's presentation time, not at the + // start of the group that carries it. + let at = group::Position { + presentation: Some(self.info.timestamp), + activity: self.state.read().activity, + }; + if !expiry.policy.is_expired(waiter, at) { + return false; + } + + self.expired = true; + if !expiry.stale_counted.swap(true, Ordering::Relaxed) { + let mut stale = self.state.read().content_range(expiry.tail.start, expiry.tail.end); + if expiry.count_payload { + stale.bytes += self.size().saturating_sub(self.read_idx) as u64; + } + expiry.stale_stats.stale(stale); + } + true + } + /// Poll for the next chunk of bytes since the last read. /// /// Returns `None` once the frame is finished and all bytes have been consumed. pub fn poll_read_chunk(&mut self, waiter: &kio::Waiter) -> Poll>> { - match &self.source { + if self.expired { + return Poll::Ready(Err(Error::Old)); + } + let buf = match &self.source { Source::Complete(bytes) => { if self.read_idx >= bytes.len() { return Poll::Ready(Ok(None)); @@ -471,38 +557,42 @@ impl Consumer { let out = bytes.slice(self.read_idx..); self.read_idx = bytes.len(); self.stats.bytes(out.len() as u64); - Poll::Ready(Ok(Some(out))) + return Poll::Ready(Ok(Some(out))); } - Source::Partial(buf) => { - let buf = buf.clone(); - let size = self.info.size as usize; - loop { - let written = buf.written(Ordering::Acquire); - if written > self.read_idx { - let out = buf.slice(self.read_idx, written); - self.read_idx = written; - self.stats.bytes(out.len() as u64); - return Poll::Ready(Ok(Some(out))); - } - if written >= size { - return Poll::Ready(Ok(None)); - } - let read_idx = self.read_idx; - // Park on the group's channel; the producer notifies it on each write and - // on abort. Re-check the atomic on wake. - ready!(poll_state(&self.state, waiter, |state| { - if let Some(err) = &state.abort { - return Poll::Ready(Err(err.clone())); - } - let w = buf.written(Ordering::Acquire); - if w > read_idx || w >= size { - Poll::Ready(Ok(())) - } else { - Poll::Pending - } - })?); - } + Source::Partial(buf) => buf.clone(), + }; + + let size = self.info.size as usize; + loop { + let written = buf.written(Ordering::Acquire); + if written > self.read_idx { + let out = buf.slice(self.read_idx, written); + self.read_idx = written; + self.stats.bytes(out.len() as u64); + return Poll::Ready(Ok(Some(out))); + } + if written >= size { + return Poll::Ready(Ok(None)); } + // Nothing buffered and the frame isn't finished: this park is the stall the + // drift budget exists to bound, and the only place it can apply. + if self.poll_expired(waiter) { + return Poll::Ready(Err(Error::Old)); + } + let read_idx = self.read_idx; + // Park on the group's channel; the producer notifies it on each write and + // on abort. Re-check the atomic on wake. + ready!(poll_state(&self.state, waiter, |state| { + if let Some(err) = &state.abort { + return Poll::Ready(Err(err.clone())); + } + let w = buf.written(Ordering::Acquire); + if w > read_idx || w >= size { + Poll::Ready(Ok(())) + } else { + Poll::Pending + } + })?); } } @@ -513,33 +603,39 @@ impl Consumer { /// Poll for all remaining bytes, resolving once the frame is finished. pub fn poll_read_all(&mut self, waiter: &kio::Waiter) -> Poll> { - match &self.source { + if self.expired { + return Poll::Ready(Err(Error::Old)); + } + let buf = match &self.source { Source::Complete(bytes) => { let out = bytes.slice(self.read_idx..); self.read_idx = bytes.len(); self.stats.bytes(out.len() as u64); - Poll::Ready(Ok(out)) - } - Source::Partial(buf) => { - let buf = buf.clone(); - let size = self.info.size as usize; - let read_idx = self.read_idx; - ready!(poll_state(&self.state, waiter, |state| { - if let Some(err) = &state.abort { - return Poll::Ready(Err(err.clone())); - } - if buf.written(Ordering::Acquire) >= size { - Poll::Ready(Ok(())) - } else { - Poll::Pending - } - })?); - let out = buf.slice(read_idx, size); - self.read_idx = size; - self.stats.bytes(out.len() as u64); - Poll::Ready(Ok(out)) + return Poll::Ready(Ok(out)); } + Source::Partial(buf) => buf.clone(), + }; + + let size = self.info.size as usize; + let read_idx = self.read_idx; + // Waiting on the rest of the payload is a stall; see `poll_read_chunk`. + if buf.written(Ordering::Acquire) < size && self.poll_expired(waiter) { + return Poll::Ready(Err(Error::Old)); } + ready!(poll_state(&self.state, waiter, |state| { + if let Some(err) = &state.abort { + return Poll::Ready(Err(err.clone())); + } + if buf.written(Ordering::Acquire) >= size { + Poll::Ready(Ok(())) + } else { + Poll::Pending + } + })?); + let out = buf.slice(read_idx, size); + self.read_idx = size; + self.stats.bytes(out.len() as u64); + Poll::Ready(Ok(out)) } /// Return all remaining bytes, blocking until the frame is finished. diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index ce028dd0244..d858895f50d 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -21,6 +21,7 @@ use crate::{Timescale, stats, track}; use std::collections::VecDeque; use std::mem::MaybeUninit; use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; use std::task::{Poll, ready}; use crate::{Error, IntoBytes, Result, Timestamp}; @@ -124,6 +125,23 @@ pub(crate) struct GroupState { // against the byte budget tracks evict toward. charge: cache::Charge, + // The first frame's timestamp, recorded once and never revised: the group's + // presentation start. Kept here rather than read off `frames` so it survives a + // front eviction, and so an abort doesn't erase where the group sat in time. + // `None` until the first frame is written, which is the only honest answer: an + // empty group has not presented anything yet. + timestamp: Option, + + // The newest frame's timestamp: the group's presentation end so far. A reader + // that has taken every frame sits here, which is what a drift budget measures it + // against. Kept alongside `timestamp` for the same reasons. + latest: Option, + + // When the group last accepted a frame. The wall-clock half of the same question: + // a group is silent from here, not from whenever it was created. `None` while it + // has produced nothing, where the track's arrival time is the only thing to go on. + pub(crate) activity: Option, + // Once finalized, the total number of frames the group will ever contain. Recorded // at finish so the count outlives an abort that clears the cache. pub(crate) fin: Option, @@ -133,6 +151,46 @@ pub(crate) struct GroupState { } impl GroupState { + /// Content still available to a reader of this group. + fn content(&self) -> stats::Content { + stats::Content { + bytes: self.cache, + frames: self.next_index.saturating_sub(self.offset) as u64, + groups: 1, + datagrams: 0, + } + } + + /// Content in the half-open frame range that is still cached here. + pub(crate) fn content_range(&self, start: usize, end: usize) -> stats::Content { + let start = start.max(self.offset); + let end = end.min(self.next_index); + if start >= end { + return stats::Content::default(); + } + + let local_start = start.saturating_sub(self.offset).min(self.frames.len()); + let local_end = end.saturating_sub(self.offset).min(self.frames.len()); + let mut bytes = self + .frames + .range(local_start..local_end) + .map(|frame| frame.payload.len() as u64) + .sum(); + if start <= self.committed + && self.committed < end + && let Some(partial) = &self.partial + { + bytes += partial.buf.capacity() as u64; + } + + stats::Content { + bytes, + frames: (end - start) as u64, + groups: 0, + datagrams: 0, + } + } + /// Resolve the source for the frame at `index`: a completed frame (whole) or the /// in-flight tail (streamed). Used by [`Consumer::poll_next_frame`]. fn poll_frame_source(&self, index: usize) -> Poll>> { @@ -187,6 +245,26 @@ impl GroupState { } } + /// Record where the group starts and currently ends in presentation time, plus + /// when it last produced. `timestamp` is the first frame only; the rest track + /// every frame, so a reader that has caught up can be measured where it sits. + fn stamp(&mut self, timestamp: Timestamp) { + self.timestamp.get_or_insert(timestamp); + self.latest = Some(timestamp); + self.activity = Some(web_async::time::Instant::now()); + } + + /// Where a cursor at `index` sits in presentation time: the next frame it would + /// read, or the newest frame in the group once it has taken them all. + /// + /// `None` only while the group has presented nothing at all. + fn position(&self, index: usize) -> Option { + self.frames + .get(index.saturating_sub(self.offset)) + .map(|frame| frame.timestamp) + .or(self.latest) + } + /// Evict completed frames from the front until within the byte budget. fn evict(&mut self) { while self.cache > MAX_GROUP_CACHE { @@ -405,6 +483,7 @@ impl Producer { state.frames.push_back(Frame { timestamp, payload }); state.next_index = next_index; state.committed = state.next_index; + state.stamp(timestamp); state.evict(); drop(state); @@ -452,6 +531,9 @@ impl Producer { buf: buf.clone(), }); state.next_index = next_index; + // Opening the frame is enough: the header carries the timestamp, so the group's + // place in time is known before a single payload byte streams in. + state.stamp(timestamp); state.evict(); drop(state); @@ -501,6 +583,9 @@ impl Producer { buf: buf.clone(), }); state.next_index = next_index; + // Opening the frame is enough: the header carries the timestamp, so the group's + // place in time is known before a single payload byte streams in. + state.stamp(timestamp); state.evict(); drop(state); @@ -603,6 +688,24 @@ impl Producer { self.state.read().committed } + /// Where the group starts in presentation time: its first frame's timestamp, + /// or `None` while no frame has been opened. + /// + /// Stamped once, when the group's first frame arrives, so it measures the group's + /// place in the media timeline rather than when it happened to be delivered. That + /// is what lets the track tell a burst of old content apart from live content (see + /// [`track::Subscriber`]). On protocols whose wire can't carry a timestamp the + /// receiver stamps frames with [`Timestamp::now`], which makes this the local + /// receive time instead: an estimate that a burst compresses. + pub(crate) fn timestamp(&self) -> Option { + self.state.read().timestamp + } + + /// Snapshot the content a subscriber would discard by skipping this group. + pub(crate) fn content(&self) -> stats::Content { + self.state.read().content() + } + /// The group's full cached footprint (payload plus fixed overhead), used by the /// track to size this group as an eviction victim. pub(crate) fn cache_size(&self) -> u64 { @@ -646,6 +749,25 @@ impl Producer { // Untagged: a tagged track attaches the egress meter via `with_meter` // when it hands the consumer to a subscriber/fetch. stats: stats::Meter::default(), + stale_stats: stats::Meter::default(), + expiry: None, + expired: false, + ended: false, + stale_counted: Arc::default(), + } + } + + /// Register for the first-frame timestamp while the group is still unstamped. + pub(crate) fn poll_timestamp(&self, waiter: &kio::Waiter) -> Poll<()> { + match self.state.poll(waiter, |state| { + if state.timestamp.is_some() || state.fin.is_some() || state.abort.is_some() { + Poll::Ready(()) + } else { + Poll::Pending + } + }) { + Poll::Ready(_) => Poll::Ready(()), + Poll::Pending => Poll::Pending, } } @@ -771,6 +893,29 @@ pub struct Consumer { // Egress payload meter, set by a tagged track via [`Self::with_meter`]. Empty // (no-op) for an untagged group. stats: stats::Meter, + // The meter that owns unread content discarded by expiry. Route-specific + // cursors inside a spliced group inherit this without metering delivery twice. + stale_stats: stats::Meter, + + // Subscriber-specific drift policy. A group can become stale after the track + // hands it out, while its reader is waiting for the first or next frame. + expiry: Option>, + expired: bool, + // Sticky: the budget gave up on a cursor that had already taken every frame, so + // the group ends rather than fails. Recorded because `expired` alone would turn a + // clean end into `Error::Old` on the next poll, and a caller is allowed to probe + // again after the end. + ended: bool, + // Cloned cursors are parallel views of one handed-out delivery. Whichever + // observes expiry first records its unread tail; the others must not repeat it. + stale_counted: Arc, +} + +/// Subscriber-specific policy for expiring a group after it was handed out. +pub(crate) trait Expiry: Send + Sync { + /// Return whether a reader sitting at `at` is stale, registering `waiter` for + /// anything that could change the answer while the group remains live. + fn is_expired(&self, waiter: &kio::Waiter, at: Position) -> bool; } // `Plain` is the hot path and carries an inline frame prefetch, so boxing it to even the @@ -823,6 +968,11 @@ impl Clone for Consumer { // Inherit the meter without re-counting the group: the original already // counted it when the track handed it out. stats: self.stats.clone(), + stale_stats: self.stale_stats.clone(), + expiry: self.expiry.clone(), + expired: self.expired, + ended: self.ended, + stale_counted: self.stale_counted.clone(), } } } @@ -836,14 +986,45 @@ impl std::ops::Deref for Consumer { } impl Consumer { + /// Snapshot the content this cursor would discard if its group were skipped. + pub(crate) fn content(&self) -> stats::Content { + match &self.inner { + ConsumerKind::Plain(plain) => plain.state.read().content(), + // Drift is evaluated before a segment copy is wrapped as a spliced group. + // Keep the group count honest if a future caller reaches this fallback. + ConsumerKind::Spliced(_) => stats::Content { + groups: 1, + ..Default::default() + }, + } + } + + /// Content not already attributed as delivered by this handed-out cursor. + fn unread_content(&self) -> stats::Content { + match &self.inner { + ConsumerKind::Plain(plain) => plain.unread_content(), + // Each route-specific plain cursor enforces expiry inside a spliced group. + ConsumerKind::Spliced(_) => stats::Content::default(), + } + } + /// Rebuild this consumer as the head of a group assembled across route changes, /// keeping the group's identity and its track's properties. See [`super::resume`]. - pub(crate) fn into_spliced(self, spliced: super::resume::Group) -> Self { + pub(crate) fn into_spliced(self, mut spliced: super::resume::Group) -> Self { + spliced.set_stale_meter(self.stale_stats.clone()); Self { inner: ConsumerKind::Spliced(Box::new(spliced)), info: self.info, track: self.track, stats: self.stats, + stale_stats: self.stale_stats, + // Each segment keeps its own route-specific expiry policy. Applying the + // head segment's policy to the assembled group would use the wrong edge + // after a takeover. + expiry: None, + expired: false, + ended: false, + stale_counted: self.stale_counted, } } @@ -851,10 +1032,113 @@ impl Consumer { /// Called by a tagged track when it hands the consumer to a subscriber or fetch. pub(crate) fn with_meter(mut self, meter: stats::Meter) -> Self { meter.group(); - self.stats = meter; + self.stats = meter.clone(); + self.set_stale_meter(meter); + self + } + + /// Attach only the meter that owns content discarded by expiry. + pub(crate) fn set_stale_meter(&mut self, meter: stats::Meter) { + if let ConsumerKind::Spliced(spliced) = &mut self.inner { + spliced.set_stale_meter(meter.clone()); + } + self.stale_stats = meter; + } + + /// Keep applying this subscription's drift budget while the group is read. + pub(crate) fn with_expiry(mut self, expiry: Arc) -> Self { + self.expiry = Some(expiry); self } + /// Check the parent subscription while a wire publisher drains detached payload. + pub(crate) fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { + self.poll_expired_while_pending(waiter, false) + } + + /// Apply the drift budget to a read that found nothing and is about to park. + /// + /// A group with frames in hand is always drained to its end: the budget bounds a + /// group that has *stalled* while the live edge moved on, not one whose reader is + /// merely slower than the wire. Judging every read instead would truncate the tail + /// of every group, since the arrival of the next group is exactly what makes the + /// current one no longer newest. + /// + /// Keeping it off the ready path also keeps it off the hot path: evaluating the + /// policy walks the track's group cache under its lock, which is shared by every + /// subscriber of that track. + /// + /// `Some(false)` ends the group cleanly and `Some(true)` fails it with + /// [`Error::Old`]; see [`Self::expired_truncates`]. + fn poll_expired_if_blocked(&mut self, waiter: &kio::Waiter) -> Option { + if self.ended { + return Some(false); + } + if !self.poll_expired(waiter) { + return None; + } + let truncates = self.expired_truncates(); + self.ended = !truncates; + Some(truncates) + } + + /// Whether giving up on this group now loses the reader anything. + /// + /// A frame-level read only parks once the cursor has taken every frame the group + /// holds, so expiring there costs nothing: the reader got everything that exists, + /// and the group ends rather than fails. What it was still waiting for was the + /// producer's FIN, and a group abandoned at its own end is indistinguishable from + /// one that ended. A cursor that still holds unread content (a wire publisher with + /// buffered frames, a half-read payload) is genuinely truncated and reports it. + fn expired_truncates(&self) -> bool { + let unread = self.unread_content(); + unread.frames > 0 || unread.bytes > 0 + } + + /// Keep checking expiry while a wire publisher still owns buffered group data. + pub(crate) fn poll_expired_while_pending(&mut self, waiter: &kio::Waiter, pending: bool) -> bool { + if !self.expired && (pending || self.expiry_pending()) { + // Resolved here rather than up front: the sticky flag above answers most + // calls without touching the group's state at all. + let at = self.position(); + if self.expiry.as_ref().is_some_and(|expiry| expiry.is_expired(waiter, at)) { + self.expired = true; + if !self.stale_counted.swap(true, Ordering::Relaxed) { + self.stale_stats.stale(self.unread_content()); + } + } + } + self.expired + } + + /// Whether expiry can still discard content or unblock a group that may grow. + fn expiry_pending(&self) -> bool { + match &self.inner { + ConsumerKind::Plain(plain) => plain.expiry_pending(), + // The route-specific plain cursors own expiry for a spliced group. + ConsumerKind::Spliced(_) => false, + } + } + + /// Whether this cursor failed because its subscription latency budget expired. + pub(crate) fn latency_expired(&self) -> bool { + self.expired + } + + /// Where this cursor sits, for a drift budget to measure it against the live edge. + /// + /// A group is not late because it *started* long ago. What is late is the content + /// its reader has yet to take, so a reader that has drained a group sits at the + /// group's newest frame, not its first. Measuring from the first would make every + /// group one group-duration behind by construction. + pub(crate) fn position(&self) -> Position { + match &self.inner { + ConsumerKind::Plain(plain) => plain.position(), + // A spliced group's route-specific cursors carry their own policy. + ConsumerKind::Spliced(_) => Position::default(), + } + } + /// Whether the group has been aborted (including pool eviction); the abort /// dropped the cached frames, so a held consumer has nothing left to read. /// @@ -938,9 +1222,19 @@ impl Consumer { /// Returns None if the group is finished and the index is out of range, or the cursor /// passed the [`Self::end_at`] cap. pub fn poll_next_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { + if self.ended { + return Poll::Ready(Ok(None)); + } + if self.expired { + return Poll::Ready(Err(Error::Old)); + } let stats = self.stats.clone(); - match &mut self.inner { - ConsumerKind::Plain(plain) => plain.poll_next_frame(waiter, &stats), + let expiry = self + .expiry + .as_ref() + .map(|policy| frame::Expiry::new(policy.clone(), self.stale_stats.clone(), self.stale_counted.clone())); + let res = match &mut self.inner { + ConsumerKind::Plain(plain) => plain.poll_next_frame(waiter, &stats, expiry), ConsumerKind::Spliced(spliced) => { // The per-route copies underneath are untagged, so meter the spliced // stream here: it is the one the subscriber actually reads. @@ -950,13 +1244,24 @@ impl Consumer { } Poll::Ready(Ok(res.map(|frame| frame.with_meter(stats)))) } + }; + match res.is_pending().then(|| self.poll_expired_if_blocked(waiter)).flatten() { + Some(true) => Poll::Ready(Err(Error::Old)), + Some(false) => Poll::Ready(Ok(None)), + None => res, } } /// Read the next frame (timestamp and payload) all at once, without blocking. pub fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { + if self.ended { + return Poll::Ready(Ok(None)); + } + if self.expired { + return Poll::Ready(Err(Error::Old)); + } let stats = self.stats.clone(); - match &mut self.inner { + let res = match &mut self.inner { ConsumerKind::Plain(plain) => plain.poll_read_frame(waiter, &stats), ConsumerKind::Spliced(spliced) => { let res = ready!(spliced.poll_read_frame(waiter))?; @@ -966,12 +1271,21 @@ impl Consumer { } Poll::Ready(Ok(res)) } + }; + match res.is_pending().then(|| self.poll_expired_if_blocked(waiter)).flatten() { + Some(true) => Poll::Ready(Err(Error::Old)), + Some(false) => Poll::Ready(Ok(None)), + None => res, } } /// Read the next frame (timestamp and payload) all at once. pub async fn read_frame(&mut self) -> Result> { - if let ConsumerKind::Plain(plain) = &mut self.inner { + // A prefetched frame is already buffered, so the drift budget (which only judges + // a read that would park) can never apply to it. + if !self.expired + && let ConsumerKind::Plain(plain) = &mut self.inner + { // Serve from the prefetched batch without building a future or allocating a waker. if !plain.capped() && let Some(frame) = plain.prefetch.pop() @@ -985,9 +1299,21 @@ impl Consumer { /// Poll for the final number of frames in the group. pub fn poll_finished(&mut self, waiter: &kio::Waiter) -> Poll> { - match &mut self.inner { + if self.ended { + return Poll::Ready(Ok(self.index())); + } + if self.expired { + return Poll::Ready(Err(Error::Old)); + } + let res = match &mut self.inner { ConsumerKind::Plain(plain) => plain.poll(waiter, |state| state.poll_finished()), ConsumerKind::Spliced(spliced) => spliced.poll_finished(waiter), + }; + match res.is_pending().then(|| self.poll_expired_if_blocked(waiter)).flatten() { + Some(true) => Poll::Ready(Err(Error::Old)), + // The group ended where the cursor stands, so that is its frame count. + Some(false) => Poll::Ready(Ok(self.index())), + None => res, } } @@ -997,7 +1323,46 @@ impl Consumer { } } +/// Where a group cursor sits in presentation and wall-clock time. +/// +/// `None` fields mean the group has presented nothing (an empty or stalled group), +/// where the track falls back to when the group arrived. +#[derive(Clone, Copy, Default)] +pub(crate) struct Position { + pub(crate) presentation: Option, + pub(crate) activity: Option, +} + impl Plain { + fn position(&self) -> Position { + // The prefetch batch was drained under an earlier lock, so the cursor's real + // position is past it. + let index = self.index.saturating_add(self.prefetch.buffered().0 as usize); + let state = self.state.read(); + Position { + presentation: state.position(index), + activity: state.activity, + } + } + + /// Whether this cursor still has unread content or may receive another frame. + fn expiry_pending(&self) -> bool { + if self.capped() { + return false; + } + + let state = self.state.read(); + state.abort.is_none() && state.fin.is_none_or(|fin| self.index < fin) + } + + /// Content this cursor has neither returned nor already counted in a prefetch batch. + fn unread_content(&self) -> stats::Content { + let prefetched = self.prefetch.buffered().0 as usize; + let start = self.index.saturating_add(prefetched); + let end = self.end.map_or(usize::MAX, |end| end.saturating_add(1)); + self.state.read().content_range(start, end) + } + // A helper to automatically apply Dropped if the state is closed without an error. fn poll(&self, waiter: &kio::Waiter, f: F) -> Poll> where @@ -1026,22 +1391,33 @@ impl Plain { self.prefetch = Prefetch::default(); } - fn poll_next_frame(&mut self, waiter: &kio::Waiter, stats: &stats::Meter) -> Poll>> { + fn poll_next_frame( + &mut self, + waiter: &kio::Waiter, + stats: &stats::Meter, + expiry: Option, + ) -> Poll>> { if self.capped() { return Poll::Ready(Ok(None)); } + let end = self.end.map_or(usize::MAX, |end| end.saturating_add(1)); // Hand out any frames a prior read_frame prefetched before touching the tail. // Their bytes were already counted at the batch fill, so the frame::Consumer // carries no meter. if let Some(frame) = self.prefetch.pop() { self.index += 1; + let tail = self.index.saturating_add(self.prefetch.buffered().0 as usize)..end; let info = frame::Info { size: frame.payload.len() as u64, timestamp: frame.timestamp, }; let source = frame::Source::Complete(frame.payload); - return Poll::Ready(Ok(Some(frame::Consumer::new(self.state.clone(), info, source)))); + let frame = frame::Consumer::new(self.state.clone(), info, source); + return Poll::Ready(Ok(Some(match expiry { + Some(expiry) => frame.with_expiry(expiry.for_frame(tail, false)), + None => frame, + }))); } let index = self.index; @@ -1053,9 +1429,11 @@ impl Plain { // A direct read (not prefetched): count the frame here; the frame::Consumer // counts its bytes per chunk as they're read out. stats.frames(1); - Poll::Ready(Ok(Some( - frame::Consumer::new(self.state.clone(), info, source).with_meter(stats.clone()), - ))) + let frame = frame::Consumer::new(self.state.clone(), info, source).with_meter(stats.clone()); + Poll::Ready(Ok(Some(match expiry { + Some(expiry) => frame.with_expiry(expiry.for_frame(self.index..end, true)), + None => frame, + }))) } fn poll_read_frame(&mut self, waiter: &kio::Waiter, stats: &stats::Meter) -> Poll>> { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index ff51c45cd84..582ad5154bd 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -3844,6 +3844,133 @@ mod tests { assert_eq!(entry.subscriber.fetches, 0, "ingress cannot fetch"); } + /// A group the drift budget skips is counted, not silently dropped: without a + /// counter a skip is indistinguishable from loss, and `groups` alone would just + /// quietly under-report. + #[tokio::test] + async fn test_stats_counts_stale_skips() { + use crate::Timestamp; + use crate::stats::{Config, Registry, Tier}; + use bytes::Bytes; + + tokio::time::pause(); + + let registry = Registry::new(Config::new()); + let ctx = registry.tier(Tier::default()).session("acme"); + + let origin = Origin::random().produce(); + let ingress = origin.clone().with_stats(ctx.clone()); + let egress = origin.consume().with_stats(ctx.clone()); + + let mut announced = egress.announced(); + let source = ingress.create_broadcast("demo", announce()).unwrap(); + let mut dynamic = source.dynamic(); + settle().await; + settle().await; + + let broadcast = announced.next().await.unwrap().broadcast.unwrap(); + let subscribing = broadcast.track("video").unwrap().subscribe(None); + let mut producer = accept_track(&mut dynamic, "video").await; + settle().await; + let mut sub = subscribing.await.unwrap(); + + // Three seconds of media, delivered as a burst before the subscriber reads. + for second in 0..3 { + let mut group = producer.append_group().unwrap(); + group + .write_frame( + Timestamp::from_millis(second * 1000).unwrap(), + Bytes::from_static(b"hi"), + ) + .unwrap(); + group.finish().unwrap(); + } + + // The default REAL_TIME budget takes the live edge and writes the other two off. + let group = sub.recv_group().await.unwrap().unwrap(); + assert_eq!(group.sequence, 2); + settle().await; + + let report = registry.report(); + let entry = report.traffic.iter().find(|e| e.path.as_str() == "demo").unwrap(); + assert_eq!(entry.publisher.stale.groups, 2, "two groups skipped on the way out"); + assert_eq!(entry.publisher.stale.frames, 2); + assert_eq!(entry.publisher.stale.bytes, 4); + assert_eq!(entry.publisher.stale.datagrams, 0); + assert_eq!(entry.publisher.groups, 1, "only the live edge was delivered"); + assert_eq!(entry.subscriber.stale.groups, 0, "ingress wrote all three"); + assert_eq!(entry.subscriber.groups, 3); + } + + /// Expiry after handoff writes off only the unread tail. The group itself and + /// the frame already returned stay solely in the delivered counters, and a + /// cloned cursor cannot report the same tail again. + #[tokio::test] + async fn test_stats_handed_out_expiry_counts_the_unread_tail_once() { + use crate::Timestamp; + use crate::stats::{Config, Registry, Tier}; + use bytes::Bytes; + + tokio::time::pause(); + + let registry = Registry::new(Config::new()); + let ctx = registry.tier(Tier::default()).session("acme"); + + let origin = Origin::random().produce(); + let ingress = origin.clone().with_stats(ctx.clone()); + let egress = origin.consume().with_stats(ctx.clone()); + + let mut announced = egress.announced(); + let source = ingress.create_broadcast("demo", announce()).unwrap(); + let mut dynamic = source.dynamic(); + settle().await; + settle().await; + + let broadcast = announced.next().await.unwrap().broadcast.unwrap(); + let subscribing = broadcast.track("video").unwrap().subscribe(None); + let mut producer = accept_track(&mut dynamic, "video").await; + settle().await; + let mut sub = subscribing.await.unwrap(); + + // A frame whose payload is still in flight: the readers drain what has landed + // and then park on the rest, which is the stall the drift budget bounds. A + // group whose frames are all in hand is drained instead, so it would never + // reach expiry here. + let mut group = producer.append_group().unwrap(); + let mut writing = group + .create_frame(crate::frame::Info { + timestamp: Timestamp::ZERO, + size: 4, + }) + .unwrap(); + writing.write(Bytes::from_static(b"aa")).unwrap(); + + let mut reading = sub.recv_group().await.unwrap().expect("first group"); + let mut clone = reading.clone(); + let mut first = reading.next_frame().await.unwrap().expect("first frame"); + let mut second = clone.next_frame().await.unwrap().expect("cloned frame"); + assert_eq!(first.read_chunk().await.unwrap(), Some(Bytes::from_static(b"aa"))); + assert_eq!(second.read_chunk().await.unwrap(), Some(Bytes::from_static(b"aa"))); + + let mut edge = producer.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), Bytes::from_static(b"edge")) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(first.read_chunk().await, Err(crate::Error::Old))); + assert!(matches!(second.read_chunk().await, Err(crate::Error::Old))); + + let report = registry.report(); + let entry = report.traffic.iter().find(|e| e.path.as_str() == "demo").unwrap(); + assert_eq!(entry.publisher.groups, 1, "the handed-out group was delivered"); + assert_eq!(entry.publisher.stale.groups, 0, "the group is not counted twice"); + assert_eq!(entry.publisher.stale.frames, 0, "no whole frame went unread"); + assert_eq!( + entry.publisher.stale.bytes, 2, + "the undelivered half of the payload is stale, counted by one reader only" + ); + } + /// `Subscriber::read_frame` collapses a group to its first frame. The paths it /// delegates to (plain and spliced) build their own *unmetered* group consumers, /// so the wrapper is the only place that can attribute the read: exactly one @@ -3898,6 +4025,76 @@ mod tests { ); } + /// A spliced `read_frame` holds its group internally while a partial frame fills. + /// If that group expires, its unread content still belongs to the logical + /// subscriber's stale counters even though the helper skips to the live edge. + #[tokio::test] + async fn test_stats_spliced_read_frame_counts_internal_expiry() { + use crate::Timestamp; + use crate::frame; + use crate::stats::{Config, Registry, Tier}; + use bytes::Bytes; + + tokio::time::pause(); + + let registry = Registry::new(Config::new()); + let ctx = registry.tier(Tier::default()).session("acme"); + + let origin = Origin::random().produce(); + let ingress = origin.clone().with_stats(ctx.clone()); + let egress = origin.consume().with_stats(ctx.clone()); + + let mut announced = egress.announced(); + let source = ingress.create_broadcast("demo", announce()).unwrap(); + let mut dynamic = source.dynamic(); + settle().await; + settle().await; + + let broadcast = announced.next().await.unwrap().broadcast.unwrap(); + let subscribing = broadcast.track("video").unwrap().subscribe(None); + let mut producer = accept_track(&mut dynamic, "video").await; + settle().await; + let mut subscriber = subscribing.await.unwrap(); + + let mut old = producer.append_group().unwrap(); + let mut writing = old + .create_frame(frame::Info { + size: 6, + timestamp: Timestamp::ZERO, + }) + .unwrap(); + writing.write(Bytes::from_static(b"old")).unwrap(); + + let pending = tokio::spawn(async move { subscriber.read_frame().await }); + tokio::task::yield_now().await; + assert!(!pending.is_finished(), "the partial frame should still be pending"); + + tokio::time::advance(std::time::Duration::from_secs(1)).await; + let mut edge = producer.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), Bytes::from_static(b"edge")) + .unwrap(); + edge.finish().unwrap(); + + let frame = pending.await.unwrap().unwrap().expect("live edge frame"); + assert_eq!(frame.payload, Bytes::from_static(b"edge")); + writing.abort(crate::Error::Cancel).unwrap(); + settle().await; + + let report = registry.report(); + let traffic = &report + .traffic + .iter() + .find(|entry| entry.path.as_str() == "demo") + .expect("demo tracked") + .publisher; + assert_eq!(traffic.groups, 1, "only the live edge group was delivered"); + assert_eq!(traffic.frames, 1, "only the live edge frame was delivered"); + assert_eq!(traffic.bytes, 4, "only the live edge payload was delivered"); + assert_eq!(traffic.stale.groups, 0, "the internal group was never handed out"); + assert_eq!(traffic.stale.frames, 1, "the expired partial frame was discarded"); + assert_eq!(traffic.stale.bytes, 6, "the declared partial payload was discarded"); + } + /// Datagrams bypass the group/frame handles entirely, so they're metered at the /// producer (ingress write) and the subscriber (egress read). Each one counts as /// the single-frame group it stands in for, plus the `datagrams` breakout. @@ -4286,7 +4483,10 @@ mod tests { announced.assert_next_wait(); // Subscribing dispatches the track to the best source (A). - let subscribing = broadcast.track("video").unwrap().subscribe(None); + let subscribing = broadcast + .track("video") + .unwrap() + .subscribe(track::Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(5)))); let mut producer = accept_track(&mut dynamic_a, "video").await; settle().await; dynamic_b.assert_no_request(); @@ -4669,7 +4869,10 @@ mod tests { let broadcast = consumer.request_broadcast("test").await.unwrap(); announced.assert_next_some("test"); - let subscribing = broadcast.track("video").unwrap().subscribe(None); + let subscribing = broadcast + .track("video") + .unwrap() + .subscribe(track::Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(5)))); let mut producer_a = accept_track(&mut dynamic_a, "video").await; settle().await; let mut sub = subscribing.await.unwrap(); diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 06ce9e6b184..98cf8752e23 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -468,6 +468,8 @@ impl Consumer { next_sequence: 0, min_sequence: 0, end_sequence: None, + drift_cap: kio::Producer::new(None), + stale_stats: Default::default(), reading: None, } } @@ -667,6 +669,11 @@ fn frames(start: Option, end: Option, sequence: u64) -> Opti Some((start, end)) } +/// The last group a half-open segment can serve, or no bound for the newest segment. +fn last_group(end: Option) -> Option { + end?.before().map(|position| position.group) +} + /// A group assembled from several routes' copies, joined at frame boundaries. /// /// Rather than being fed, it pulls: on every frame it asks the segment list which route @@ -679,6 +686,10 @@ fn frames(start: Option, end: Option, sequence: u64) -> Opti /// replacement can arrive. pub(crate) struct Group { state: kio::Consumer, + /// The logical subscription's live latency budget. + subscription: kio::Consumer, + /// The logical reader's group cap, used only to bound each route's drift anchor. + cap: kio::Consumer>, /// The logical group being assembled. sequence: u64, @@ -695,18 +706,22 @@ pub(crate) struct Group { /// The segment whose copy died under us, and why. dead: Option<(u64, Error)>, + + /// The tagged logical subscriber's meter for route-copy expiry only. + stale_stats: crate::stats::Meter, } struct Current { segment: u64, cap: Option, + bound: Option, group: group::Consumer, } /// A route covering one position: the segment id, its track, and the segment's /// exclusive frame bound on the group (outer `None` when the group escapes the /// segment's range entirely, from [`frames`]). -type Covering = (u64, track::Consumer, Option>); +type Covering = (u64, track::Consumer, Option>, Option); impl Clone for Group { fn clone(&self) -> Self { @@ -722,30 +737,51 @@ impl Clone for Group { (group.index() == self.index).then_some(Current { segment: current.segment, cap: current.cap, + bound: current.bound, group, }) }); Self { state: self.state.clone(), + subscription: self.subscription.clone(), + cap: self.cap.clone(), sequence: self.sequence, index: self.index, end: self.end, current, dead: self.dead.clone(), + stale_stats: self.stale_stats.clone(), } } } impl Group { - fn new(state: kio::Consumer, sequence: u64, index: u64) -> Self { + fn new( + state: kio::Consumer, + subscription: kio::Consumer, + cap: kio::Consumer>, + sequence: u64, + index: u64, + ) -> Self { Self { state, + subscription, + cap, sequence, index, end: None, current: None, dead: None, + stale_stats: Default::default(), + } + } + + /// Attribute expiry for route-specific copies behind this logical group. + pub(crate) fn set_stale_meter(&mut self, meter: crate::stats::Meter) { + if let Some(current) = &mut self.current { + current.group.set_stale_meter(meter.clone()); } + self.stale_stats = meter; } /// Pre-latch the delivering route's own copy, so the payload it already @@ -758,12 +794,18 @@ impl Group { /// latched, since the reuse path trusts the latch's alignment and would /// misnumber its frames. The reader re-resolves instead, and the peek path's /// own check buries the copy as lagged. - fn latched(mut self, segment: u64, cap: Option, mut group: group::Consumer) -> Self { + fn latched(mut self, segment: u64, cap: Option, bound: Option, mut group: group::Consumer) -> Self { // The segment bound is exclusive; a group consumer's cap is inclusive. group.end_at(cap.map(|cap| cap.saturating_sub(1))); group.start_at(self.index); + group.set_stale_meter(self.stale_stats.clone()); if group.index() == self.index { - self.current = Some(Current { segment, cap, group }); + self.current = Some(Current { + segment, + cap, + bound, + group, + }); } self } @@ -833,6 +875,7 @@ impl Group { segment.id, segment.track.clone(), frames(segment.start, segment.end, sequence).map(|(_, end)| end), + last_group(segment.end), ))), Poll::Pending => match terminal { true => Poll::Ready(None), @@ -844,6 +887,7 @@ impl Group { segment.id, segment.track.clone(), frames(segment.start, segment.end, sequence).map(|(_, end)| end), + last_group(segment.end), ))), // No route owns them yet; park unless none is coming. None if terminal => Poll::Ready(None), @@ -873,7 +917,7 @@ impl Group { let sequence = self.sequence; let found = ready!(self.poll_covering(position, dead, waiter)); - let Some((segment, track, Some(cap))) = found else { + let Some((segment, track, Some(cap), bound)) = found else { // No segment covers the position, but a latched copy still drains: // a pruned segment's cursor holds exactly the frames it owned (its // cap was its produced edge), so read it dry before giving up. Once @@ -889,13 +933,13 @@ impl Group { if self .current .as_ref() - .is_some_and(|current| current.segment == segment && current.cap == cap) + .is_some_and(|current| current.segment == segment && current.cap == cap && current.bound == bound) { return Poll::Ready(Ok(true)); } // The route may not have delivered this group yet, so wait on its cache. - let Some(mut group) = ready!(track.poll_peek_group(sequence, waiter)) else { + let Some(group) = ready!(track.poll_peek_group(sequence, waiter)) else { // This route will never have it; fall back to whichever segment replaces it. self.dead = Some((segment, Error::NotFound)); continue; @@ -904,6 +948,8 @@ impl Group { // `start_at` clamps up to the first frame the copy still holds, so landing // higher than asked means this route can't cover the seam after all. Treat it // like a dead copy and wait for one that can. + let mut group = track.guard_group(group, self.subscription.clone(), self.cap.clone(), bound); + group.set_stale_meter(self.stale_stats.clone()); group.start_at(self.index); if group.index() != self.index { self.dead = Some((segment, Error::Lagged)); @@ -912,7 +958,12 @@ impl Group { // The segment bound is exclusive; a group consumer's cap is inclusive. group.end_at(cap.map(|cap| cap.saturating_sub(1))); - self.current = Some(Current { segment, cap, group }); + self.current = Some(Current { + segment, + cap, + bound, + group, + }); self.dead = None; return Poll::Ready(Ok(true)); } @@ -970,14 +1021,22 @@ impl Group { if !ready!(self.poll_current(waiter))? { return Poll::Ready(Ok(None)); } - let current = self.current.as_mut().expect("resolved above"); - match ready!(current.group.poll_read_frame(waiter)) { + let result = { + let current = self.current.as_mut().expect("resolved above"); + ready!(current.group.poll_read_frame(waiter)) + }; + let latency_expired = self + .current + .as_ref() + .is_some_and(|current| current.group.latency_expired()); + match result { Ok(Some(frame)) => { self.index += 1; return Poll::Ready(Ok(Some(frame))); } Ok(None) if self.roll() => continue, Ok(None) => return Poll::Ready(Ok(None)), + Err(err) if latency_expired => return Poll::Ready(Err(err)), Err(err) => self.bury(err), } } @@ -991,14 +1050,22 @@ impl Group { if !ready!(self.poll_current(waiter))? { return Poll::Ready(Ok(None)); } - let current = self.current.as_mut().expect("resolved above"); - match ready!(current.group.poll_next_frame(waiter)) { + let result = { + let current = self.current.as_mut().expect("resolved above"); + ready!(current.group.poll_next_frame(waiter)) + }; + let latency_expired = self + .current + .as_ref() + .is_some_and(|current| current.group.latency_expired()); + match result { Ok(Some(frame)) => { self.index += 1; return Poll::Ready(Ok(Some(frame))); } Ok(None) if self.roll() => continue, Ok(None) => return Poll::Ready(Ok(None)), + Err(err) if latency_expired => return Poll::Ready(Err(err)), Err(err) => self.bury(err), } } @@ -1029,13 +1096,18 @@ impl Group { }; loop { let dead = self.dead.as_ref().map(|(segment, _)| *segment); - let Some((segment, track, _)) = ready!(self.poll_covering(seam, dead, waiter)) else { + let Some((segment, track, _, bound)) = ready!(self.poll_covering(seam, dead, waiter)) else { return Poll::Ready(Ok(cap)); }; match ready!(track.poll_peek_group(self.sequence, waiter)) { // The continuation's copy declares the count: its own count // already includes the frames it skipped. - Some(mut continuation) => return continuation.poll_finished(waiter), + Some(continuation) => { + let mut continuation = + track.guard_group(continuation, self.subscription.clone(), self.cap.clone(), bound); + continuation.set_stale_meter(self.stale_stats.clone()); + return continuation.poll_finished(waiter); + } // This route will never have it; wait for whatever replaces it. None => self.dead = Some((segment, Error::NotFound)), } @@ -1049,6 +1121,9 @@ struct SegmentSub { start: Option, end: Option, sub: SubState, + /// A completed segment's cursor, retained while parked groups may need their + /// latency budget re-evaluated after the outer cap rises. + terminal: Option, /// The producer dropped this segment (pruned, or replaced before producing). /// The cursor drains what it already holds, then retires; see /// [`Self::retired`]. @@ -1062,6 +1137,23 @@ struct SegmentSub { } impl SegmentSub { + /// The cursor that can evaluate staleness, whether the segment is live or has + /// already completed. + fn stale_sub_mut(&mut self) -> Option<&mut track::Subscriber> { + match &mut self.sub { + SubState::Active(sub) => Some(sub), + _ => self.terminal.as_mut(), + } + } + + /// Move an active cursor into terminal retention and mark the segment done. + fn complete(&mut self, count: Option) { + let previous = std::mem::replace(&mut self.sub, SubState::Done(count)); + if let SubState::Active(sub) = previous { + self.terminal = Some(sub); + } + } + /// The first group this segment can serve, for the underlying read cursor. fn first_group(&self) -> u64 { self.start.map_or(0, |start| start.group) @@ -1070,17 +1162,16 @@ impl SegmentSub { /// The last group this segment can serve (inclusive), for the underlying read /// cursor. `None` while it is the newest segment. fn last_group(&self) -> Option { - let end = self.end?; // An empty segment would serve nothing, and no switch produces one: every // boundary comes from `resume_position`, which sits at or above the first frame. // `None` here reads as "no cap", which is why it is asserted rather than relied // on; the authoritative filter is `Segment::covers`, which uses the exclusive // bound directly. debug_assert!( - end != Position::default(), + self.end != Some(Position::default()), "a segment cannot end at the start of the track" ); - Some(end.before()?.group) + last_group(self.end) } /// Whether a producer-dropped segment is spent and can be removed. A capped @@ -1141,6 +1232,10 @@ pub struct Subscriber { min_sequence: u64, /// Inclusive cap for [`Self::next_group`], set by [`Self::end_at`]. end_sequence: Option, + /// Shared copy of [`Self::end_sequence`] for groups that outlive this cursor poll. + drift_cap: kio::Producer>, + /// Logical subscriber meter for groups drained internally by [`Self::poll_read_frame`]. + stale_stats: crate::stats::Meter, /// The group currently being drained by [`Self::read_frame`]. reading: Option, @@ -1154,6 +1249,14 @@ impl Subscriber { self.reap(); } + /// Attribute expiry for the group this frame helper drains internally. + pub(crate) fn set_stale_meter(&mut self, meter: crate::stats::Meter) { + if let Some(reading) = &mut self.reading { + reading.set_stale_meter(meter.clone()); + } + self.stale_stats = meter; + } + /// Reap retired cursors, then bound the live stragglers: a pruned segment's /// cursor keeps draining (groups below its cap may still arrive out of /// order, and its demand keeps the upstream serving them), but only the @@ -1178,6 +1281,7 @@ impl Subscriber { } if seg.pruned { seg.sub = SubState::Done(None); + seg.terminal = None; seg.parked.clear(); cut -= 1; } @@ -1203,8 +1307,9 @@ impl Subscriber { }; self.last_prefs = prefs; for seg in &mut self.segments { - if let SubState::Active(sub) = &mut seg.sub { - let _ = sub.update(slice(&self.last_prefs, seg.start, seg.end)); + let prefs = slice(&self.last_prefs, seg.start, seg.end); + if let Some(sub) = seg.stale_sub_mut() { + let _ = sub.update(prefs); } } } @@ -1273,7 +1378,10 @@ impl Subscriber { Some(existing) => { if existing.end != segment.end { existing.end = segment.end; - if let SubState::Active(sub) = &mut existing.sub { + let cap = Self::stale_cap(existing, self.end_sequence); + if let Some(sub) = existing.stale_sub_mut() { + // The boundary bounds the drift anchor as well as the demand. + sub.set_stale_cap(cap); // Shrink the demand so the session can cap upstream. The // read bounds stay on this subscriber (see `poll_recv_group`): // an inner `end_at` would park boundary-crossing groups in the @@ -1295,6 +1403,7 @@ impl Subscriber { start: segment.start, end: segment.end, sub: SubState::Pending(sub), + terminal: None, pruned: false, parked: BTreeMap::new(), }); @@ -1321,14 +1430,39 @@ impl Subscriber { // through the segment list, which forgets this route the moment its // segment is pruned, turning a group the cursor already delivered into an // empty husk. - let spliced = Group::new(self.state.clone(), sequence, 0).latched(seg.id, end, group.clone()); + let spliced = Group::new( + self.state.clone(), + self.prefs.consume(), + self.drift_cap.consume(), + sequence, + 0, + ) + .latched(seg.id, end, seg.last_group(), group.clone()); Some(group.into_spliced(spliced)) } + /// The highest sequence a segment could hand its reader: the reader's own cap and + /// the segment's boundary, whichever is lower. + /// + /// A segment's inner cursor is deliberately left uncapped (an inner `end_at` would + /// park boundary-crossing groups where its completion can't be seen), so this is how + /// both bounds reach the drift anchor. Without them a segment measures staleness + /// against groups it will never surface: the route running past the boundary, or the + /// reader's own cap holding content back. + fn stale_cap(seg: &SegmentSub, end_sequence: Option) -> Option { + min_some(end_sequence, seg.last_group()) + } + /// Resolve a segment's pending subscription, if any. Ready once the segment is /// `Active` or `Done`; a rejected or closed track becomes `Done` (stall, not /// error). Never consumes groups, so terminal-state pollers can share it. - fn poll_activate(seg: &mut SegmentSub, prefs: &Subscription, min_sequence: u64, waiter: &kio::Waiter) -> Poll<()> { + fn poll_activate( + seg: &mut SegmentSub, + prefs: &Subscription, + min_sequence: u64, + end_sequence: Option, + waiter: &kio::Waiter, + ) -> Poll<()> { if let SubState::Pending(pending) = &mut seg.sub { match pending.poll_ok(waiter) { Poll::Ready(Ok(mut sub)) => { @@ -1338,6 +1472,7 @@ impl Subscriber { // this subscriber, never on the inner cursor: an inner cap would // park groups there and hide the segment's completion. sub.start_at(seg.first_group().max(min_sequence)); + sub.set_stale_cap(Self::stale_cap(seg, end_sequence)); let _ = sub.update(slice(prefs, seg.start, seg.end)); seg.sub = SubState::Active(sub); } @@ -1355,12 +1490,13 @@ impl Subscriber { seg: &mut SegmentSub, prefs: &Subscription, min_sequence: u64, + end_sequence: Option, waiter: &kio::Waiter, ) -> Poll> { loop { match &mut seg.sub { SubState::Pending(_) => { - ready!(Self::poll_activate(seg, prefs, min_sequence, waiter)); + ready!(Self::poll_activate(seg, prefs, min_sequence, end_sequence, waiter)); } SubState::Active(sub) => match sub.poll_recv_group(waiter) { Poll::Ready(Ok(Some(group))) => { @@ -1379,13 +1515,13 @@ impl Subscriber { Poll::Ready(count) => count, Poll::Pending => None, }; - seg.sub = SubState::Done(count); + seg.complete(count); return Poll::Ready(None); } // A dead segment stalls the logical track rather than erroring; // the next switch resumes it. Poll::Ready(Err(_)) => { - seg.sub = SubState::Done(None); + seg.complete(None); return Poll::Ready(None); } // An empty cursor on a pruned segment is NOT proof it drained: @@ -1450,6 +1586,14 @@ impl Subscriber { .parked .remove(&sequence) .expect("parked key just observed"); + // The cap rising widens the live edge too, so a group parked while it + // was current can be a backlog by the time it is owed again. Re-check it + // rather than hand back content the budget has since given up on. + if let Some(sub) = self.segments[index].stale_sub_mut() + && matches!(sub.poll_stale(&group, waiter), Poll::Ready(Ok(true))) + { + continue; + } // Folded into a group already handed out: try the next parked one. if let Some(group) = self.hand_out(index, group) { self.next_sequence = self.next_sequence.max(sequence.saturating_add(1)); @@ -1458,7 +1602,13 @@ impl Subscriber { } loop { - let polled = Self::poll_segment(&mut self.segments[index], &self.last_prefs, min_sequence, waiter); + let polled = Self::poll_segment( + &mut self.segments[index], + &self.last_prefs, + min_sequence, + end_sequence, + waiter, + ); match polled { Poll::Ready(Some(group)) => { if beyond_cap(group.sequence) { @@ -1561,7 +1711,10 @@ impl Subscriber { } match ready!(self.poll_next_group(waiter))? { - Some(group) => self.reading = Some(group), + Some(mut group) => { + group.set_stale_meter(self.stale_stats.clone()); + self.reading = Some(group); + } None => return Poll::Ready(Ok(None)), } } @@ -1583,7 +1736,7 @@ impl Subscriber { // be woken when it activates. let mut pending_activation = false; if let Some(seg) = self.segments.last_mut() { - if Self::poll_activate(seg, &self.last_prefs, self.min_sequence, waiter).is_pending() { + if Self::poll_activate(seg, &self.last_prefs, self.min_sequence, self.end_sequence, waiter).is_pending() { pending_activation = true; } else if let SubState::Active(sub) = &mut seg.sub { match sub.poll_recv_datagram(waiter) { @@ -1638,16 +1791,22 @@ impl Subscriber { let Some(seg) = self.segments.last_mut() else { return Poll::Ready(Ok(0)); }; - ready!(Self::poll_activate(seg, &self.last_prefs, self.min_sequence, waiter)); + ready!(Self::poll_activate( + seg, + &self.last_prefs, + self.min_sequence, + self.end_sequence, + waiter + )); match &mut seg.sub { SubState::Done(count) => Poll::Ready(Ok(count.unwrap_or(0))), SubState::Active(sub) => match ready!(sub.poll_finished(waiter)) { Ok(count) => { - seg.sub = SubState::Done(Some(count)); + seg.complete(Some(count)); Poll::Ready(Ok(count)) } Err(_) => { - seg.sub = SubState::Done(None); + seg.complete(None); Poll::Ready(Ok(0)) } }, @@ -1679,6 +1838,18 @@ impl Subscriber { /// re-offers it. pub fn end_at(&mut self, sequence: impl Into>) { self.end_sequence = sequence.into(); + if let Ok(mut cap) = self.drift_cap.write() { + *cap = self.end_sequence; + } + // The cap bounds each segment's drift anchor as well as this reader's own + // delivery: a segment must not measure against groups this cap hides. + let end_sequence = self.end_sequence; + for seg in &mut self.segments { + let cap = Self::stale_cap(seg, end_sequence); + if let Some(sub) = seg.stale_sub_mut() { + sub.set_stale_cap(cap); + } + } } /// The shared preferences channel, so `track::SubscriberControl` can wrap it. @@ -1686,6 +1857,21 @@ impl Subscriber { self.prefs.clone() } + /// Take the groups every segment's drift budget skipped since the last call. + /// + /// The segments are subscribed untagged, so their skips have nowhere to be counted + /// until they reach the [`track::Subscriber`] that owns the stats scope. A retired + /// segment's tail is lost with it, which is the same bound its groups already had. + pub(crate) fn take_stale(&mut self) -> crate::stats::Content { + let mut stale = crate::stats::Content::default(); + for seg in &mut self.segments { + if let Some(sub) = seg.stale_sub_mut() { + stale.add(sub.take_stale()); + } + } + stale + } + /// Replace this subscriber's preferences; each segment's demand is re-derived /// on the next poll. pub fn update(&mut self, subscription: Subscription) { @@ -1708,9 +1894,10 @@ impl Subscriber { #[cfg(test)] mod test { use super::*; - use crate::{Timestamp, broadcast}; + use crate::{Latency, Timestamp, broadcast}; use futures::FutureExt; use std::sync::Arc; + use std::time::Duration; fn track_pair(name: &str) -> (track::Producer, track::Consumer) { let producer = track::Producer::new(Arc::new(broadcast::Info::default()), name, None); @@ -1718,12 +1905,37 @@ mod test { (producer, consumer) } + /// [`track_pair`] with explicit publisher properties, for tests that care about the + /// retention window a subscriber's drift budget is clamped to. + fn track_pair_with(name: &str, info: track::Info) -> (track::Producer, track::Consumer) { + let producer = track::Producer::new(Arc::new(broadcast::Info::default()), name, info); + let consumer = producer.consume(); + (producer, consumer) + } + + /// A bounded replay window for tests whose subject requires every buffered group. + fn replay() -> Subscription { + Subscription::default().with_latency(Latency::max(Duration::from_secs(30))) + } + fn write_group(producer: &mut track::Producer, sequence: u64, payload: &str) { let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.write_frame(Timestamp::ZERO, payload.as_bytes().to_vec()).unwrap(); group.finish().unwrap(); } + /// Like [`write_group`], but placing the group on a real media timeline so the + /// drift budget has something to measure. Most tests here are about splicing + /// mechanics and use [`write_group`], paired with [`replay`] when they need every + /// buffered group rather than the real-time live edge. + fn write_group_at(producer: &mut track::Producer, sequence: u64, payload: &str, at: Duration) { + let mut group = producer.create_group(group::Info { sequence }).unwrap(); + group + .write_frame(at.try_into().unwrap(), payload.as_bytes().to_vec()) + .unwrap(); + group.finish().unwrap(); + } + fn recv(sub: &mut Subscriber) -> u64 { sub.recv_group() .now_or_never() @@ -1777,7 +1989,7 @@ mod test { let mut producer = Producer::new(); producer.switch(&consumer_a, None).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); write_group(&mut track_a, 0, "a0"); write_group(&mut track_a, 1, "a1"); @@ -1865,7 +2077,7 @@ mod test { // No segments yet: the takeover is unbounded. producer.takeover(&consumer_a).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); write_group(&mut track_a, 0, "a0"); write_group(&mut track_a, 1, "a1"); assert_eq!(recv(&mut sub), 0); @@ -1880,6 +2092,125 @@ mod test { assert_eq!(recv(&mut sub), 2); } + /// A route that stalls while a replacement runs on leaves the boundary trailing, + /// so the takeover asks the new route to replay a backlog. That backlog is bounded + /// by the drift budget and nothing else: a REAL_TIME subscriber jumps to the live + /// edge, while one that declared a budget covering the gap reads it whole. + #[tokio::test] + async fn a_takeover_backlog_is_bounded_by_the_budget() { + // Both routes retain a minute, so the budget is the only thing bounding the + // backlog (a budget past the publisher's window is clamped to it). + let retain = track::Info::default().with_latency_max(Duration::from_secs(60)); + let (mut track_a, consumer_a) = track_pair_with("a", retain.clone()); + let (mut track_b, consumer_b) = track_pair_with("b", retain); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut live = producer.consume().subscribe(None); + let mut patient = producer + .consume() + .subscribe(Subscription::default().with_latency(Latency::max(Duration::from_secs(60)))); + + write_group_at(&mut track_a, 0, "a0", Duration::ZERO); + assert_eq!(recv(&mut live), 0); + assert_eq!(recv(&mut patient), 0); + + // The old route stalls; the replacement resumes at the boundary and replays + // half a minute of media as fast as the wire allows. + track_a.abort(Error::Dropped).unwrap(); + producer.takeover(&consumer_b).unwrap(); + recv_pending(&mut live); + for second in 1..=30 { + write_group_at(&mut track_b, second, "b", Duration::from_secs(second)); + } + + // The live subscriber takes the edge and writes the backlog off; the patient + // one asked to tolerate it and gets every group. + assert_eq!(recv(&mut live), 30); + recv_pending(&mut live); + + let mut backfill = Vec::new(); + while let Some(Ok(Some(group))) = patient.recv_group().now_or_never() { + backfill.push(group.sequence); + } + assert_eq!(backfill, (1..=30).collect::>()); + } + + /// A capped spliced subscriber measures drift against its cap, exactly like a plain + /// one. The segment is deliberately left uncapped so its completion stays visible, so + /// the cap has to reach its drift anchor by another route or the groups the reader + /// still wants read as ancient. + #[tokio::test] + async fn a_capped_spliced_subscriber_measures_drift_against_its_cap() { + let retain = track::Info::default().with_latency_max(Duration::from_secs(60)); + let (mut track_a, consumer_a) = track_pair_with("a", retain); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer.consume().subscribe(None); + sub.end_at(0); + + write_group_at(&mut track_a, 0, "a0", Duration::ZERO); + write_group_at(&mut track_a, 1, "a1", Duration::from_secs(30)); + + // Group 1 is past the cap, so it is not a live edge this reader can jump to. + assert_eq!(recv(&mut sub), 0); + } + + /// A group parked above the cap is re-checked when the cap rises: the live edge moved + /// while it waited, so handing it back unconditionally would deliver a backlog the + /// budget has already given up on. + #[tokio::test] + async fn a_raised_cap_rechecks_parked_groups() { + let retain = track::Info::default().with_latency_max(Duration::from_secs(60)); + let (mut track_a, consumer_a) = track_pair_with("a", retain); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer.consume().subscribe(None); + sub.end_at(0); + + write_group_at(&mut track_a, 0, "a0", Duration::ZERO); + assert_eq!(recv(&mut sub), 0); + + // Group 1 parks above the cap; group 2 lands half a minute further on. + write_group_at(&mut track_a, 1, "a1", Duration::from_secs(1)); + recv_pending(&mut sub); + write_group_at(&mut track_a, 2, "a2", Duration::from_secs(30)); + + // Raising the cap owes the reader group 1 again, but by now it is a backlog. + sub.end_at(None); + assert_eq!(recv(&mut sub), 2); + recv_pending(&mut sub); + } + + /// Completing the segment must not discard the cursor that evaluates parked + /// groups. A later cap increase still uses the terminal track's live edge. + #[tokio::test] + async fn a_raised_cap_rechecks_parked_groups_after_segment_finish() { + let retain = track::Info::default().with_latency_max(Duration::from_secs(60)); + let (mut track_a, consumer_a) = track_pair_with("a", retain); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer.consume().subscribe(None); + sub.end_at(0); + + write_group_at(&mut track_a, 0, "a0", Duration::ZERO); + assert_eq!(recv(&mut sub), 0); + + write_group_at(&mut track_a, 1, "a1", Duration::from_secs(1)); + write_group_at(&mut track_a, 2, "a2", Duration::from_secs(30)); + track_a.finish().unwrap(); + // Drive the inner cursor through its clean end while both newer groups are + // parked above the cap. + recv_pending(&mut sub); + + sub.end_at(None); + assert_eq!(recv(&mut sub), 2, "the stale parked group is skipped after finish"); + recv_pending(&mut sub); + } + #[tokio::test] async fn takeover_replaces_empty_segment() { let (track_a, consumer_a) = track_pair("a"); @@ -2100,7 +2431,7 @@ mod test { let mut producer = Producer::new(); producer.switch(&consumer_a, None).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); sub.end_at(1); @@ -2149,7 +2480,7 @@ mod test { let mut producer = Producer::new(); producer.switch(&consumer_a, None).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); let next = |sub: &mut Subscriber| { kio::wait(|waiter| sub.poll_next_group(waiter)) @@ -2250,6 +2581,47 @@ mod test { recv_pending(&mut sub); } + #[tokio::test] + async fn a_replacement_copy_keeps_the_handed_out_group_latency_budget() { + tokio::time::pause(); + + let (mut track_a, consumer_a) = track_pair("a"); + let (mut track_b, consumer_b) = track_pair("b"); + + let mut producer = Producer::new(); + producer.takeover(&consumer_a).unwrap(); + let mut sub = producer.consume().subscribe(None); + + let mut head = track_a.create_group(group::Info { sequence: 0 }).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().expect("head group"); + assert_eq!(read(&mut reading), b"a0"); + + producer.takeover(&consumer_b).unwrap(); + track_a.abort(Error::Dropped).unwrap(); + recv_pending(&mut sub); + + let mut continuation = track_b.create_group(group::Info { sequence: 0 }).unwrap(); + continuation.start_at(1).unwrap(); + continuation.write_frame(Timestamp::ZERO, b"b1".to_vec()).unwrap(); + assert_eq!(read(&mut reading), b"b1"); + + assert!( + reading.read_frame().now_or_never().is_none(), + "the replacement group is still the live edge" + ); + + tokio::time::advance(Duration::from_secs(1)).await; + write_group_at(&mut track_b, 1, "edge", Duration::from_secs(1)); + + let result = reading + .read_frame() + .now_or_never() + .expect("the newer group changes the verdict"); + // Drained, so the budget ends the replacement rather than truncating it. + assert!(matches!(result, Ok(None)), "the replacement ends: {result:?}"); + } + /// A replacement that serves the whole group instead of the requested tail still /// splices cleanly: the reader picks up at the seam and never sees the frames it /// already has. @@ -2500,7 +2872,7 @@ mod test { let mut producer = Producer::new(); producer.takeover(&consumer_a).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); let mut group = track_a.create_group(group::Info { sequence: 0 }).unwrap(); group.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); @@ -2637,7 +3009,7 @@ mod test { let mut producer = Producer::new(); producer.takeover(&consumer_a).unwrap(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); recv_pending(&mut sub); assert_eq!(track_a.subscription().unwrap().start, None); @@ -2673,9 +3045,13 @@ mod test { let mut producer = Producer::new(); producer.takeover(&consumer_a).unwrap(); - let mut sub = producer - .consume() - .subscribe(Subscription::default().with_start(Position::group(0))); + // The budget is what makes the backfill readable: an explicit start says which + // groups the publisher should send, not that the subscriber will wait for them. + let mut sub = producer.consume().subscribe( + Subscription::default() + .with_start(Position::group(0)) + .with_latency(Latency::max(Duration::from_secs(60))), + ); recv_pending(&mut sub); assert_eq!(track_a.subscription().unwrap().start, Some(Position::group(0))); @@ -3071,7 +3447,7 @@ mod test { #[tokio::test] async fn late_group_drains_from_a_pruned_cursor() { let mut producer = Producer::new(); - let mut sub = producer.consume().subscribe(None); + let mut sub = producer.consume().subscribe(replay()); // A delivers group 1 first; group 0 is still in flight when A is outranked // and enough failovers prune its segment. diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index b24cc99ac95..2a1a5993a4d 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -20,9 +20,11 @@ pub struct Subscription { /// skipped); a larger ceiling tolerates that much reordering before giving up on the /// older group. /// - /// This is the `Subscriber Max Latency` on the wire, enforced by the publisher's - /// cache. Receivers that buffer (e.g. a jitter buffer) enforce the same budget - /// locally, and a group is skipped once either measure exceeds it. + /// This is the `Subscriber Max Latency` on the wire. It is enforced at both ends: + /// the publisher skips a group rather than sending it, and this subscriber skips it + /// again as it reads. Clamped to the publisher's + /// [`Info::latency_max`](crate::track::Info::latency_max) retention window; stored + /// here verbatim, so what was asked for stays readable. pub latency: crate::Latency, /// First [`Position`] the publisher should deliver, or `None` to start at the latest /// group. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 0b2b4f21ccb..bc72c4a41b9 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -13,7 +13,7 @@ //! //! The track is closed with [Error] when all writers or readers are dropped. -use crate::{Error, Result, Timescale, Timestamp, coding}; +use crate::{Error, Latency, Result, Timescale, Timestamp, coding}; use crate::{broadcast, cache, frame, group, stats}; use super::{Datagram, Requests}; @@ -225,6 +225,20 @@ pub(crate) struct TrackState { fetch: kio::Shared, } +/// What a frame-level scan found, including content skipped on the way to either a +/// frame or the clean end of the track. +struct FrameScan { + hit: Option, + stale: stats::Content, +} + +/// A frame found by a frame-level scan and the cursor position it came from. +struct FrameHit { + frame: frame::Frame, + index: usize, + sequence: u64, +} + /// A cached group plus its bookkeeping in the track's `lookup` map. /// /// Access times and the evictable-population sample live in the group's own @@ -233,11 +247,19 @@ pub(crate) struct TrackState { struct Slot { group: group::Producer, + // When this group entered the track at this hop. This is the wall-clock + // backstop for groups whose first frame has not supplied a timestamp yet. + arrived: web_async::time::Instant, + // Incarnation stamp, echoed by this slot's arrival entry (if any). A re-served // sequence (an aborted group re-created by the publisher or re-fetched as // backfill) gets a fresh stamp, so a historical arrival entry can't resolve to // the replacement and deliver it twice or at the wrong position. stamp: u32, + + // Whether this incarnation came from the live publisher and can replace older + // subscription content. Fetch-only backfill stays cached but never anchors drift. + visible: bool, } /// The registered subscriptions, aggregated by the producer. @@ -348,10 +370,15 @@ impl TrackState { &self, index: usize, next_sequence: u64, + drift: Drift, waiter: &kio::Waiter, - ) -> Poll>> { + ) -> Poll> { let start = index.saturating_sub(self.offset); let mut pending_seen = false; + // Groups the budget gave up on below the frame this returns. Counted only on the + // winning scan, whose cursor jumps past them, so a scan that ends Pending leaves + // them to be counted exactly once by the one that eventually succeeds. + let mut stale = stats::Content::default(); for (i, (sequence, stamp)) in self.arrival.iter().enumerate().skip(start) { if *sequence < next_sequence { continue; @@ -364,11 +391,25 @@ impl TrackState { // incarnation, delivered (if at all) at its own arrival position. continue; } + // The drift budget bounds this the same as the group-level reads: a frame + // from a group the subscription has given up on is no fresher for being + // read one frame at a time. + if self.is_stale(*sequence, None, drift.edge, drift.budget) { + stale.add(slot.group.content()); + continue; + } let mut consumer = slot.group.consume(); match consumer.poll_read_frame(waiter) { Poll::Ready(Ok(Some(frame))) => { - return Poll::Ready(Ok(Some((frame, self.offset + i, *sequence)))); + return Poll::Ready(Ok(FrameScan { + hit: Some(FrameHit { + frame, + index: self.offset + i, + sequence: *sequence, + }), + stale, + })); } Poll::Ready(Ok(None)) => continue, // A single group failing (aborted upstream, or evicted from the @@ -386,7 +427,7 @@ impl TrackState { if pending_seen { Poll::Pending } else if self.is_complete() { - Poll::Ready(Ok(None)) + Poll::Ready(Ok(FrameScan { hit: None, stale })) } else if let Some(err) = &self.abort { Poll::Ready(Err(err.clone())) } else { @@ -490,6 +531,104 @@ impl TrackState { self.info.as_ref().map(|info| info.latency_max) } + /// The live edges a subscription bounded at `cap` measures drift against: the + /// highest-sequence group for wall-clock age, plus the highest one that has + /// presented a frame for timestamp age. + /// + /// One scan answers a whole poll. Each highest-sequence anchor in range is above + /// every candidate below it and above none at or past it. Recomputing per candidate + /// would make walking a backlog of N groups off in one poll cost O(N^2). + /// + /// Capped because a group can only be late relative to data that would actually be + /// served in its place: a subscription ending at a takeover boundary can't jump past + /// it, so the groups it still wants aren't stale just because the route ran on. + /// Fetched backfill is absent from `arrival`, so it cannot age subscription content + /// as though it were a live replacement. + fn live_edge(&self, cap: Option) -> Option { + let mut wall: Option = None; + let mut presentation: Option = None; + for slot in self.lookup.values() { + if !slot.visible { + continue; + } + let group = &slot.group; + if cap.is_some_and(|cap| group.sequence > cap) || group.is_aborted() { + continue; + } + if wall.is_none_or(|edge| group.sequence > edge.sequence) { + wall = Some(WallEdge { + sequence: group.sequence, + stamp: slot.stamp, + arrived: slot.arrived, + }); + } + if let Some(timestamp) = group.timestamp() + && presentation.is_none_or(|edge| group.sequence > edge.sequence) + { + presentation = Some(PresentationEdge { + sequence: group.sequence, + stamp: slot.stamp, + timestamp, + }); + } + } + wall.map(|wall| Edge { wall, presentation }) + } + + /// Whether the group at `sequence` has drifted further behind `edge` than `budget` + /// tolerates, so a subscriber should skip it rather than hand it over. + /// + /// Presentation time distinguishes a backlog delivered as a burst from live content. + /// Wall-clock arrival time backstops it, including for an empty or stalled group that + /// has no first-frame timestamp. Either age exceeding the budget makes the group stale. + /// + /// The edge must sit strictly above the candidate. The live edge is never late + /// against itself, and backfill or the tail of a rewound timeline can carry a high + /// timestamp on a low sequence without being an edge at all. + fn is_stale(&self, sequence: u64, at: Option, edge: Option, budget: Duration) -> bool { + let Some(edge) = edge else { + return false; + }; + let Some(slot) = self.lookup.get(&sequence) else { + return false; + }; + + // Where the candidate sits. A group nobody has started reading sits at its own + // start; one already handed out sits wherever its reader got to, so a reader + // that has kept up is not convicted by how long ago its group opened. + let at = at.unwrap_or_default(); + let presentation = at.presentation.or_else(|| slot.group.timestamp()); + let arrived = at.activity.unwrap_or(slot.arrived); + + // The anchors were resolved under an earlier lock, so confirm each still names + // the same servable incarnation before it convicts a candidate. Failing safe + // (delivering) is right, since the next poll resolves fresh anchors. + let wall_stale = edge.wall.sequence > sequence + && self + .lookup + .get(&edge.wall.sequence) + .is_some_and(|live| live.stamp == edge.wall.stamp && !live.group.is_aborted()) + && (budget.is_zero() + || edge + .wall + .arrived + .checked_duration_since(arrived) + .is_some_and(|age| age > budget)); + + let presentation_stale = edge.presentation.is_some_and(|edge| { + edge.sequence > sequence + && self + .lookup + .get(&edge.sequence) + .is_some_and(|live| live.stamp == edge.stamp && !live.group.is_aborted()) + && presentation.is_some_and( + |timestamp| matches!(edge.timestamp.checked_sub(timestamp), Ok(age) if Duration::from(age) > budget), + ) + }); + + wall_stale || presentation_stale + } + /// Resolve a one-shot fetch from the track side: the cached group, or an [`Error`] /// once it can never be served. A missing group is a failure ([`Error::NotFound`]), not an /// end-of-stream. The handler side (a rejection, or no [`Dynamic`] at all) lives @@ -673,7 +812,9 @@ impl TrackState { sequence, Slot { group: group.clone(), + arrived: web_async::time::Instant::now(), stamp, + visible, }, ); if visible { @@ -1281,6 +1422,7 @@ impl Producer { let info = self.state.read().info.clone().expect("producer always has info"); let subscription = kio::Producer::new(preferences); register_subscription(self.state.read(), &subscription); + let drift_cap = kio::Producer::new(None); // Hoisted: an inline `read()` guard would live to the end of the struct literal, // deadlocking against the `consume()` below. @@ -1298,6 +1440,9 @@ impl Producer { next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), + stale_cap: None, + drift_cap, + stale: stats::Content::default(), }), // A producer-side (in-process) subscribe is not egress: stay untagged. stats: stats::Scope::default(), @@ -1638,18 +1783,44 @@ fn snapshot_subscription(subs: &kio::Shared, bound: Option, outer: Option) -> Option { + super::subscription::min_some(cursor, outer) +} + +/// Clamp a drift budget to the publisher's retention window: nobody can wait for a late +/// group longer than the publisher keeps it around. /// /// The single clamp point. Subscribers hold their preferences verbatim, so what they asked -/// for stays readable, and clamping the aggregate is equivalent to clamping each subscriber -/// first (`min` distributes over the `max` that combines them). `bound` is `None` on a track -/// whose info isn't known yet (an unaccepted [`Request`]), which imposes no window. -fn clamp_combined(combined: Option, bound: Option) -> Option { - let mut combined = combined?; +/// for stays readable, and it is applied here on both sides of the aggregate: to the +/// combined request the publisher sees ([`clamp_combined`]) and to one subscriber's own +/// budget when it decides a group is stale ([`TrackState::is_stale`]). Those agree because +/// `min` distributes over the `max` that combines them. `bound` is `None` on a track whose +/// info isn't known yet (an unaccepted [`Request`]), which imposes no window. +fn clamp_latency(mut latency: crate::Latency, bound: Option) -> crate::Latency { if let Some(bound) = bound { - combined.latency.max = combined.latency.max.min(bound); + latency.max = latency.max.min(bound); } + latency +} + +/// Clamp the aggregate's latency budget to the publisher's window; see [`clamp_latency`]. +fn clamp_combined(combined: Option, bound: Option) -> Option { + let mut combined = combined?; + combined.latency = clamp_latency(combined.latency, bound); Some(combined) } @@ -1872,6 +2043,27 @@ impl Consumer { } } + /// Attach a subscription's drift policy to a cached group resolved outside its cursor. + pub(crate) fn guard_group( + &self, + group: group::Consumer, + subscription: kio::Consumer, + cap: kio::Consumer>, + bound: Option, + ) -> group::Consumer { + let ConsumerKind::Plain(state) = &self.inner else { + return group; + }; + let sequence = group.sequence; + group.with_expiry(Arc::new(GroupExpiry { + state: state.weak(), + subscription, + cap, + bound, + sequence, + })) + } + /// Poll for a cached group by sequence, parking `waiter` until it lands. /// /// `Ready(None)` once it can never arrive: the track ended below the sequence, or @@ -2117,6 +2309,7 @@ impl Subscribing { let info = ready!(state.poll(waiter, |state| state.poll_info())) .map_err(|e| e.abort.clone().unwrap_or(Error::Dropped))??; + let drift_cap = kio::Producer::new(None); Poll::Ready(Ok(Subscriber { name: self.name.clone(), broadcast: self.broadcast.clone(), @@ -2130,6 +2323,9 @@ impl Subscribing { next_sequence: 0, end_sequence: None, parked: BTreeMap::new(), + stale_cap: None, + drift_cap, + stale: stats::Content::default(), }), stats: self.stats.clone(), _stats_sub: self.stats.subscribe(), @@ -2430,6 +2626,126 @@ enum SubscriberKind { Spliced(Box), } +/// One poll's view of how far this subscription may drift: the clamped budget and the +/// live edge to measure a candidate group against. Resolved once, then applied to every +/// group that poll considers. +#[derive(Clone, Copy)] +struct Drift { + budget: Duration, + edge: Option, +} + +/// Keeps one handed-out group tied to the subscription whose cursor selected it. +struct GroupExpiry { + /// Weak so a handed-out group never joins the track's consumer count, which is what + /// [`crate::broadcast::Demand`] reads to decide the track still has readers. A group + /// outlives the cursor that produced it (a relay serves one for the life of its + /// stream), and pinning demand on that would hold an upstream subscription open past + /// the last real subscriber. + state: kio::ConsumerWeak, + subscription: kio::Consumer, + cap: kio::Consumer>, + bound: Option, + sequence: u64, +} + +impl group::Expiry for GroupExpiry { + fn is_expired(&self, waiter: &kio::Waiter, at: group::Position) -> bool { + let mut latency = Latency::default(); + let _ = self.subscription.poll(waiter, |subscription| { + latency = subscription.latency; + Poll::<()>::Pending + }); + + let mut cap = None; + let _ = self.cap.poll(waiter, |current| { + cap = **current; + Poll::<()>::Pending + }); + let cap = super::subscription::min_some(cap, self.bound); + + let mut expired = false; + let _ = self.state.poll(waiter, |state| { + let budget = clamp_latency(latency, state.latency_bound()).max; + loop { + let edge = state.live_edge(cap); + expired = state.is_stale(self.sequence, Some(at), edge, budget); + if expired { + break; + } + + // A first timestamp can change the presentation-time verdict without + // mutating the track. Register on the candidate and every unstamped + // group that could supersede the current presentation edge. If one + // raced this scan, resolve the edge again before returning Pending. + let mut timestamp_raced = false; + if let Some(slot) = state.lookup.get(&self.sequence) { + let group = &slot.group; + if group.timestamp().is_none() + && group.poll_timestamp(waiter).is_ready() + && group.timestamp().is_some() + { + timestamp_raced = true; + } + } + let presentation_sequence = edge + .and_then(|edge| edge.presentation) + .map_or(self.sequence, |edge| edge.sequence.max(self.sequence)); + for slot in state.lookup.values() { + let group = &slot.group; + if slot.visible + && group.sequence > presentation_sequence + && cap.is_none_or(|cap| group.sequence <= cap) + && !group.is_aborted() + && group.poll_timestamp(waiter).is_ready() + && group.timestamp().is_some() + { + timestamp_raced = true; + break; + } + } + if !timestamp_raced { + break; + } + } + + // Register on track changes even though the current answer is known: a + // newer group can move either live edge while this group read is pending. + Poll::<()>::Pending + }); + + expired + } +} + +/// The group a poll's drift is measured against, identified well enough to tell it apart +/// from whatever may occupy its sequence by the time a candidate is judged. +#[derive(Clone, Copy)] +struct Edge { + wall: WallEdge, + presentation: Option, +} + +/// The newest servable group, including an empty group with no media timestamp. +#[derive(Clone, Copy)] +struct WallEdge { + sequence: u64, + /// The slot incarnation this arrival time was read from, so an eviction or a re-served + /// sequence between resolving the anchor and using it is detectable. + stamp: u32, + arrived: web_async::time::Instant, +} + +/// The newest servable group that has presented at least one frame. +#[derive(Clone, Copy)] +struct PresentationEdge { + sequence: u64, + /// The slot incarnation this timestamp was read from, so an eviction or a re-served + /// sequence between resolving the anchor and using it is detectable. + stamp: u32, + timestamp: Timestamp, +} + /// The cursor state for a subscription over a single (per-session) track. struct PlainSubscriber { state: kio::Consumer, @@ -2454,9 +2770,27 @@ struct PlainSubscriber { /// are parked here instead of dropped). Keyed by sequence so the lowest is /// re-offered first. parked: BTreeMap, + /// A cap imposed by a reader wrapping this cursor (a [`super::resume::Subscriber`] + /// segment), folded into the drift anchor only. Delivery is still bounded by + /// `end_sequence`, which stays unset on a segment so its completion is visible. + stale_cap: Option, + /// Shared effective cap used by groups after this cursor hands them out. + drift_cap: kio::Producer>, + /// Groups the drift budget skipped since the count was last drained. Accumulated + /// here rather than metered in place because the handle that owns the stats scope + /// is the outer [`Subscriber`], which may be reading this cursor through a + /// [`super::resume::Subscriber`] segment (untagged, so the outer wrapper is the + /// only place attribution happens once). + stale: stats::Content, } impl PlainSubscriber { + fn update_drift_cap(&mut self) { + if let Ok(mut cap) = self.drift_cap.write() { + *cap = servable_cap(self.end_sequence, self.stale_cap); + } + } + // A helper to automatically apply Dropped if the state is closed without an error. fn poll(&self, waiter: &kio::Waiter, f: F) -> Poll> where @@ -2469,6 +2803,59 @@ impl PlainSubscriber { }) } + /// Take the groups skipped since the last call, for the owner to meter. + fn take_stale(&mut self) -> stats::Content { + std::mem::take(&mut self.stale) + } + + /// Note a group an outer reader skipped on this cursor's behalf, so it lands in the + /// same counter as the ones skipped here. + fn note_stale(&mut self, group: &group::Consumer) { + self.stale.add(group.content()); + } + + /// This subscriber's clamped drift budget and the live edge to measure against, + /// resolved once per poll. + /// + /// Read fresh each poll, so a mid-stream [`SubscriberControl::update`] applies to the + /// very next group, and shared across every candidate that poll walks off, so + /// discarding a backlog of N groups costs one scan rather than N. Only ever + /// [`Poll::Ready`]; the track ending surfaces as the error the caller was going to + /// get anyway. + fn poll_drift(&self, waiter: &kio::Waiter) -> Poll> { + let mut latency = Latency::default(); + let _ = self.subscription.poll(waiter, |subscription| { + latency = subscription.latency; + Poll::<()>::Pending + }); + let cap = servable_cap(self.end_sequence, self.stale_cap); + self.poll(waiter, move |state| { + Poll::Ready(Ok(Drift { + budget: clamp_latency(latency, state.latency_bound()).max, + edge: state.live_edge(cap), + })) + }) + } + + /// Whether the drift budget says to skip `group`, against a [`Drift`] already resolved + /// for this poll. + fn poll_stale(&self, group: &group::Consumer, drift: Drift, waiter: &kio::Waiter) -> Poll> { + self.poll(waiter, move |state| { + Poll::Ready(Ok(state.is_stale(group.sequence, None, drift.edge, drift.budget))) + }) + } + + fn with_expiry(&self, group: group::Consumer) -> group::Consumer { + let sequence = group.sequence; + group.with_expiry(Arc::new(GroupExpiry { + state: self.state.weak(), + subscription: self.subscription.consume(), + cap: self.drift_cap.consume(), + bound: None, + sequence, + })) + } + fn poll_recv_group(&mut self, waiter: &kio::Waiter) -> Poll>> { // An eviction aborts a parked group without touching any cursor this // subscriber polls, so each entry needs a waiter or this poll would never @@ -2490,38 +2877,51 @@ impl PlainSubscriber { self.parked .retain(|sequence, group| *sequence >= min_sequence && watch(group)); - // Re-offer the lowest parked group back inside the cap once it rises. - if let Some(&sequence) = self.parked.keys().next() - && self.end_sequence.is_none_or(|end| sequence <= end) - { - return Poll::Ready(Ok(self.parked.remove(&sequence))); - } + // One scan for the whole poll, so walking a backlog off stays linear in its size. + let drift = ready!(self.poll_drift(waiter))?; loop { - let Some((consumer, found_index)) = - ready!(self.poll(waiter, |state| state.poll_recv_group(self.index, self.min_sequence))?) - else { - // Parked groups survive a finished track: they become deliverable - // again if the cap rises, so the stream isn't over while any are held. - if self.parked.is_empty() { - return Poll::Ready(Ok(None)); + // Re-offer the lowest parked group back inside the cap once it rises, + // ahead of the arrival cursor: it is the oldest thing still owed. + let consumer = match self.parked.keys().next().copied() { + Some(sequence) if self.end_sequence.is_none_or(|end| sequence <= end) => { + self.parked.remove(&sequence).expect("just looked it up") } - return Poll::Pending; - }; - self.index = found_index + 1; - - // Park a group beyond the cap instead of dropping it, and keep scanning - // so an in-range group that arrived behind it still flows. - if self.end_sequence.is_some_and(|end| consumer.sequence > end) { - // Watch it from the moment it parks: the retain pass above already - // ran, so an entry admitted here would otherwise sit unwatched for - // the rest of this poll, and an abort could wake nobody. - if watch(&consumer) { - self.parked.insert(consumer.sequence, consumer); + _ => { + let Some((consumer, found_index)) = + ready!(self.poll(waiter, |state| state.poll_recv_group(self.index, self.min_sequence))?) + else { + // Parked groups survive a finished track: they become deliverable + // again if the cap rises, so the stream isn't over while any are held. + if self.parked.is_empty() { + return Poll::Ready(Ok(None)); + } + return Poll::Pending; + }; + self.index = found_index + 1; + + // Park a group beyond the cap instead of dropping it, and keep scanning + // so an in-range group that arrived behind it still flows. + if self.end_sequence.is_some_and(|end| consumer.sequence > end) { + // Watch it from the moment it parks: the retain pass above already + // ran, so an entry admitted here would otherwise sit unwatched for + // the rest of this poll, and an abort could wake nobody. + if watch(&consumer) { + self.parked.insert(consumer.sequence, consumer); + } + continue; + } + consumer } + }; + + // Drop a group the drift budget has given up on and keep scanning, so one + // poll walks a whole backlog off rather than handing it out group by group. + if ready!(self.poll_stale(&consumer, drift, waiter))? { + self.stale.add(consumer.content()); continue; } - return Poll::Ready(Ok(Some(consumer))); + return Poll::Ready(Ok(Some(self.with_expiry(consumer)))); } } @@ -2538,25 +2938,38 @@ impl PlainSubscriber { } fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { - let floor = self.next_sequence.max(self.min_sequence); - let Some(group) = ready!(self.poll(waiter, |state| state.poll_next_in_range(floor, self.end_sequence))?) else { - return Poll::Ready(Ok(None)); - }; - self.next_sequence = group.sequence.saturating_add(1); - Poll::Ready(Ok(Some(group))) + let drift = ready!(self.poll_drift(waiter))?; + + loop { + let floor = self.next_sequence.max(self.min_sequence); + let Some(group) = ready!(self.poll(waiter, |state| state.poll_next_in_range(floor, self.end_sequence))?) + else { + return Poll::Ready(Ok(None)); + }; + // Advance before the budget check: a skipped group is consumed, not retried. + self.next_sequence = group.sequence.saturating_add(1); + if ready!(self.poll_stale(&group, drift, waiter))? { + self.stale.add(group.content()); + continue; + } + return Poll::Ready(Ok(Some(self.with_expiry(group)))); + } } fn poll_read_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { + let drift = ready!(self.poll_drift(waiter))?; let lower = self.min_sequence.max(self.next_sequence); - let Some((frame, found_index, sequence)) = - ready!(self.poll(waiter, |state| { state.poll_read_frame(self.index, lower, waiter) })?) - else { + let scan = ready!(self.poll(waiter, |state| { + state.poll_read_frame(self.index, lower, drift, waiter) + })?); + self.stale.add(scan.stale); + let Some(hit) = scan.hit else { return Poll::Ready(Ok(None)); }; - self.index = found_index + 1; - self.next_sequence = sequence.saturating_add(1); - Poll::Ready(Ok(Some(frame))) + self.index = hit.index + 1; + self.next_sequence = hit.sequence.saturating_add(1); + Poll::Ready(Ok(Some(hit.frame))) } } @@ -2608,6 +3021,59 @@ impl Subscriber { &self.broadcast } + /// Attribute the groups the drift budget skipped since the last read. + /// + /// Drained rather than metered where the skip happens, for the same reason a + /// delivered group is metered here: a spliced subscriber reads through untagged + /// per-segment cursors, so this wrapper is the one place that counts exactly once. + fn count_stale(&mut self, meter: &stats::Meter) { + // An untagged subscriber leaves the count where it is. A spliced reader polls + // its segments through this same method, and those segments are untagged, so + // draining here would throw the count away before the tagged handle wrapping + // them ever sees it. + if meter.is_tracked() { + meter.stale(self.take_stale()); + } + } + + /// Take the groups the drift budget skipped since the last call, so a nesting + /// handle (a spliced subscriber reading this one as a segment) can attribute them. + pub(crate) fn take_stale(&mut self) -> stats::Content { + match &mut self.inner { + SubscriberKind::Plain(plain) => plain.take_stale(), + SubscriberKind::Spliced(spliced) => spliced.take_stale(), + } + } + + /// Bound the drift anchor from outside, for a reader that caps this subscriber + /// without capping its cursor. + /// + /// A [`super::resume::Subscriber`] segment is deliberately left uncapped + /// ([`Self::end_at`] would park boundary-crossing groups where its completion can't + /// be seen), so its own cap has to reach the anchor this way or the segment measures + /// drift against groups its reader will never be served. + pub(crate) fn set_stale_cap(&mut self, cap: Option) { + if let SubscriberKind::Plain(plain) = &mut self.inner { + plain.stale_cap = cap; + plain.update_drift_cap(); + } + } + + /// Whether the drift budget says to skip `group`, for a reader holding a group this + /// subscriber handed it earlier (a parked one, re-offered once a cap rose). Counts + /// the skip here so it reaches the stats with the rest. + pub(crate) fn poll_stale(&mut self, group: &group::Consumer, waiter: &kio::Waiter) -> Poll> { + let SubscriberKind::Plain(plain) = &mut self.inner else { + return Poll::Ready(Ok(false)); + }; + let drift = ready!(plain.poll_drift(waiter))?; + let stale = ready!(plain.poll_stale(group, drift, waiter))?; + if stale { + plain.note_stale(group); + } + Poll::Ready(Ok(stale)) + } + /// Create a handle for updating this subscriber's delivery preferences. pub fn control(&self) -> SubscriberControl { SubscriberControl { @@ -2620,9 +3086,21 @@ impl Subscriber { /// Poll for the next group in arrival order, without blocking. /// - /// Returns every group exactly once in the order it landed on the wire, which may be - /// out of sequence due to network reordering or loss. Use [`Self::poll_next_group`] if - /// you only want groups whose sequence number is higher than any previously returned. + /// Returns each group it delivers exactly once, in the order it landed on the wire, + /// which may be out of sequence due to network reordering or loss. Use + /// [`Self::poll_next_group`] if you only want groups whose sequence number is higher + /// than any previously returned. + /// + /// Groups are semi-reliable, and the [`Subscription::latency`] budget is the other + /// thing (alongside eviction and a moving start) that decides which of them arrive: + /// one that has drifted further behind the live edge than the budget tolerates is + /// skipped rather than handed over, so a single poll walks off a whole backlog. The + /// default is [`Latency::REAL_TIME`](crate::Latency::REAL_TIME), which takes the live + /// edge and writes the rest off; raise it to read history. [`Self::start_at`] and + /// [`Subscription::start`] are filters, not exemptions: backfill needs a budget that + /// covers it. [`Consumer::fetch_group`] is the way to ask for one old group outright. + /// The budget remains attached to a returned group: if it stalls while newer data + /// advances, its pending frame read ends with [`Error::Old`]. /// /// Honors the floor set by [`Self::start_at`] and the cap set by [`Self::end_at`]: /// a group beyond the cap is parked (not dropped) and re-offered once the cap rises @@ -2640,6 +3118,7 @@ impl Subscriber { SubscriberKind::Plain(plain) => plain.poll_recv_group(waiter), SubscriberKind::Spliced(spliced) => spliced.poll_recv_group(waiter), }; + self.count_stale(&meter); res.map(|res| res.map(|group| group.map(|group| group.with_meter(meter)))) } @@ -2693,6 +3172,9 @@ impl Subscriber { /// produces a monotonically increasing sequence at the cost of dropping out-of-order /// groups. Use [`Self::poll_recv_group`] to see every group in arrival order instead. /// + /// The [`Subscription::latency`] budget applies here too, on the same terms; see + /// [`Self::poll_recv_group`]. + /// /// Honors the cap set by [`Self::end_at`]: groups with sequence past the cap are left /// in the producer's cache and become eligible again if the cap is raised or removed. pub fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Poll>> { @@ -2701,6 +3183,7 @@ impl Subscriber { SubscriberKind::Plain(plain) => plain.poll_next_group(waiter), SubscriberKind::Spliced(spliced) => spliced.poll_next_group(waiter), }; + self.count_stale(&meter); res.map(|res| res.map(|group| group.map(|group| group.with_meter(meter)))) } @@ -2720,8 +3203,12 @@ impl Subscriber { let meter = self.stats.meter(); let res = match &mut self.inner { SubscriberKind::Plain(plain) => plain.poll_read_frame(waiter), - SubscriberKind::Spliced(spliced) => spliced.poll_read_frame(waiter), + SubscriberKind::Spliced(spliced) => { + spliced.set_stale_meter(meter.clone()); + spliced.poll_read_frame(waiter) + } }; + self.count_stale(&meter); // This helper collapses a group to its first frame: count the group, the one // frame, and the bytes actually read. if let Poll::Ready(Ok(Some(frame))) = &res { @@ -2795,7 +3282,10 @@ impl Subscriber { /// consumer's current cursor parks the consumer until the cap is raised. pub fn end_at(&mut self, sequence: impl Into>) { match &mut self.inner { - SubscriberKind::Plain(plain) => plain.end_sequence = sequence.into(), + SubscriberKind::Plain(plain) => { + plain.end_sequence = sequence.into(); + plain.update_drift_cap(); + } SubscriberKind::Spliced(spliced) => spliced.end_at(sequence), } } @@ -3049,6 +3539,11 @@ mod test { Producer::new(Arc::new(broadcast::Info::default()), name, info) } + /// A bounded replay window for tests whose subject requires every buffered group. + fn replay() -> Subscription { + Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(30))) + } + /// Helper: count live cached groups in state. fn live_groups(state: &TrackState) -> usize { state.lookup.len() @@ -3493,13 +3988,13 @@ mod test { // waited for longer than the publisher keeps it. The subscriber's own preference // is stored verbatim, so what it asked for stays readable. let mut subscriber = - producer.subscribe(Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(10)))); assert_eq!(subscriber.subscription().latency.max, Duration::from_secs(10)); assert_eq!(producer.subscription().unwrap().latency.max, Duration::from_secs(2)); // A budget within the cache is left alone, and ZERO (skip immediately) stays ZERO. subscriber - .update(Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))) + .update(Subscription::default().with_latency(crate::Latency::max(Duration::from_millis(500)))) .unwrap(); assert_eq!(producer.subscription().unwrap().latency.max, Duration::from_millis(500)); @@ -3567,7 +4062,7 @@ mod test { #[test] fn latency_max_clamped_via_every_update_path() { let producer = track_producer("test", Info::default().with_latency_max(Duration::from_secs(2))); - let over = Subscription::default().with_latency(Latency::max(Duration::from_secs(10))); + let over = Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(10))); // The clamp lives in the aggregation, so it applies no matter which entry point // wrote the raw preference. Previously only `Subscriber::update` clamped. @@ -3587,12 +4082,654 @@ mod test { // The aggregate takes the max, then clamps once. Equivalent to clamping each // subscriber first, since `min` distributes over `max`. - let _a = producer.subscribe(Subscription::default().with_latency(Latency::max(Duration::from_millis(500)))); - let _b = producer.subscribe(Subscription::default().with_latency(Latency::max(Duration::from_secs(10)))); + let _a = + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_millis(500)))); + let _b = producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(10)))); assert_eq!(producer.subscription().unwrap().latency.max, Duration::from_secs(2)); } + /// Append a finished group presenting at `millis`, so the track carries a media + /// timeline for the drift budget to measure against. + fn append_at(producer: &mut Producer, millis: u64) -> u64 { + let mut group = producer.append_group().unwrap(); + group + .write_frame(Timestamp::from_millis(millis).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + group.finish().unwrap(); + group.sequence + } + + /// Every group the subscriber can read right now, in delivery order. + fn drain(subscriber: &mut Subscriber) -> Vec { + let mut sequences = Vec::new(); + while let Some(Ok(Some(group))) = subscriber.recv_group().now_or_never() { + sequences.push(group.sequence); + } + sequences + } + + #[test] + fn real_time_skips_a_backlog_to_the_live_edge() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // The default budget is REAL_TIME: a subscriber joining a track that already + // holds five seconds of history takes the live edge, not the history. This is + // the ceiling a takeover backlog runs into. + let mut subscriber = producer.subscribe(None); + assert_eq!(drain(&mut subscriber), vec![4]); + + // And it stays caught up: the next group is live when it lands. + append_at(&mut producer, 5000); + assert_eq!(drain(&mut subscriber), vec![5]); + } + + #[test] + fn a_budget_admits_groups_within_it() { + let mut producer = track_producer("test", None); + for second in 0..5 { + append_at(&mut producer, second * 1000); + } + + // Two seconds of tolerance keeps the groups presenting within 2s of the live + // edge (2s, 3s, 4s) and drops the two below it. + let mut subscriber = + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(2)))); + assert_eq!(drain(&mut subscriber), vec![2, 3, 4]); + } + + #[test] + fn drift_is_measured_in_presentation_time_not_arrival_time() { + let mut producer = track_producer("test", None); + // A relay ingesting a backlog creates every group at once, so arrival time says + // they are all equally fresh. Their timestamps say otherwise, which is the whole + // point of measuring in presentation time. + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + let mut subscriber = + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_millis(1500)))); + assert_eq!(drain(&mut subscriber), vec![2, 3]); + } + + #[tokio::test] + async fn wall_clock_expires_an_unstamped_group() { + tokio::time::pause(); + + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + producer.append_group().unwrap(); // seq 0 stalls before its first frame + + tokio::time::advance(Duration::from_secs(1)).await; + append_at(&mut producer, 1000); // seq 1 proves the live feed moved on + + // With the real-time budget, wall-clock age backstops the missing timestamp. + assert_eq!(drain(&mut subscriber), vec![1]); + } + + #[tokio::test] + async fn a_handed_out_group_expires_while_its_first_frame_is_stalled() { + tokio::time::pause(); + + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + producer.append_group().unwrap(); + + let mut stalled = subscriber.recv_group().await.unwrap().expect("stalled group"); + let pending = tokio::spawn(async move { stalled.read_frame().await }); + tokio::task::yield_now().await; + assert!( + !pending.is_finished(), + "the empty live edge still waits for its first frame" + ); + + tokio::time::advance(Duration::from_secs(1)).await; + append_at(&mut producer, 1000); + + // It ends rather than fails: the reader took every frame the group ever had + // (none), so nothing was truncated. What it was waiting for was the producer, + // and a group abandoned where its reader stands looks exactly like one that + // ended there. + let result = pending.await.unwrap(); + assert!(matches!(result, Ok(None)), "the held group ends: {result:?}"); + } + + #[tokio::test] + async fn a_handed_out_group_wakes_when_a_newer_group_gets_its_first_timestamp() { + let mut producer = track_producer("test", None); + let mut subscriber = + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_millis(500)))); + let mut old = producer.append_group().unwrap(); + old.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"old")) + .unwrap(); + + let mut held = subscriber.recv_group().await.unwrap().expect("old group"); + assert!(held.read_frame().await.unwrap().is_some()); + let mut live = producer.append_group().unwrap(); + let pending = tokio::spawn(async move { held.read_frame().await }); + tokio::task::yield_now().await; + assert!(!pending.is_finished(), "the newer group has no timestamp yet"); + + live.write_frame( + Timestamp::from_millis(1000).unwrap(), + bytes::Bytes::from_static(b"live"), + ) + .unwrap(); + tokio::task::yield_now().await; + + assert!(pending.is_finished(), "the new presentation edge wakes the held reader"); + // Drained, so the budget ends the group rather than truncating it. + let result = pending.await.unwrap(); + assert!(matches!(result, Ok(None)), "the held group ends: {result:?}"); + } + + /// The ordinary live case, at the default real-time budget: 2s GOPs produced one at + /// a time and read as they arrive. The budget must take the live edge without + /// shortening the group the reader is already on, so every frame of every group is + /// delivered and each group *ends* rather than fails at its boundary. + /// + /// Two things would break this. Measuring drift from a group's first frame rather + /// than its reader's position convicts every group the moment its successor opens, + /// since a live reader is always a little behind the edge. And the reader is parked + /// at its group's end when that happens, because the FIN and the next group's first + /// frame are separate events and the wire does not order them. + #[tokio::test] + async fn real_time_reads_a_live_stream_without_truncating_it() { + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + + let gop = |n: u64| { + [ + Timestamp::from_millis(n * 2000).unwrap(), + Timestamp::from_millis(n * 2000 + 1900).unwrap(), + ] + }; + let write = |group: &mut group::Producer, timestamp| { + group.write_frame(timestamp, bytes::Bytes::from_static(b"x")).unwrap(); + }; + + let mut open = producer.append_group().unwrap(); + write(&mut open, gop(0)[0]); + write(&mut open, gop(0)[1]); + let mut reading = subscriber.recv_group().await.unwrap().expect("the live group"); + + let mut read = Vec::new(); + for n in 1..5u64 { + let sequence = reading.sequence; + let mut frames = 0; + while let Some(res) = reading.read_frame().now_or_never() { + match res.expect("no truncation while draining") { + Some(_) => frames += 1, + None => panic!("group {sequence} ended early"), + } + } + read.push((sequence, frames)); + + let next = { + // Parked at the end of the current group: every frame is read and no FIN + // has landed. + let mut end = std::pin::pin!(reading.read_frame()); + assert!(futures::poll!(end.as_mut()).is_pending(), "parked on the FIN"); + + // The next keyframe opens its group. The verdict is taken here, in the + // window before the previous group's FIN arrives. + let mut opened = producer.append_group().unwrap(); + write(&mut opened, gop(n)[0]); + let verdict = futures::poll!(end.as_mut()); + + open.finish().unwrap(); + let res = match verdict { + Poll::Ready(res) => res, + Poll::Pending => end.await, + }; + assert!( + matches!(res, Ok(None)), + "group {sequence} ends at the boundary rather than failing: {res:?}" + ); + opened + }; + let mut next = next; + write(&mut next, gop(n)[1]); + + reading = subscriber.recv_group().await.unwrap().expect("the next live group"); + open = next; + } + + assert_eq!(read, vec![(0, 2), (1, 2), (2, 2), (3, 2)], "every frame of every group"); + } + + /// A budget is spent from where the reader stands, not from where its group opened. + /// + /// A 2s GOP with a 1s budget: the reader has drained to 1900ms when the next group + /// opens at 2000ms, so it is 100ms behind the live edge and well inside what it + /// asked for. A straggling frame of the old group arriving after the new one opened + /// (which is ordinary, the two are separate streams) must still reach it. + /// + /// Measuring from the group's first frame instead makes the drift 2000ms, so a + /// budget shorter than one GOP would drop the tail of every GOP. + #[tokio::test] + async fn a_budget_is_measured_from_the_readers_position() { + let mut producer = track_producer("test", None); + let mut subscriber = + producer.subscribe(Subscription::default().with_latency(Latency::max(Duration::from_secs(1)))); + + let mut open = producer.append_group().unwrap(); + open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"key")) + .unwrap(); + open.write_frame( + Timestamp::from_millis(1900).unwrap(), + bytes::Bytes::from_static(b"tail"), + ) + .unwrap(); + + let mut reading = subscriber.recv_group().await.unwrap().expect("the live group"); + assert!(reading.read_frame().await.unwrap().is_some()); + assert!(reading.read_frame().await.unwrap().is_some()); + + let mut end = std::pin::pin!(reading.read_frame()); + assert!(futures::poll!(end.as_mut()).is_pending(), "parked at 1900ms"); + + // The next GOP opens. The reader is 100ms behind it, inside its 1s budget. + let mut next = producer.append_group().unwrap(); + next.write_frame(Timestamp::from_millis(2000).unwrap(), bytes::Bytes::from_static(b"key")) + .unwrap(); + assert!( + futures::poll!(end.as_mut()).is_pending(), + "a reader inside its budget is not expired by the next group opening" + ); + + // A straggler from the old group, still within the budget. + open.write_frame( + Timestamp::from_millis(1950).unwrap(), + bytes::Bytes::from_static(b"late"), + ) + .unwrap(); + let late = end.await.expect("the straggler is not truncated"); + assert_eq!( + late.map(|frame| frame.timestamp), + Some(Timestamp::from_millis(1950).unwrap()) + ); + } + + /// A group the budget ends rather than fails stays ended. `expired` alone would + /// turn the clean answer into [`Error::Old`] on the next poll, and a caller is + /// allowed to probe again past the end of a group. + #[tokio::test] + async fn an_ended_group_stays_ended_when_probed_again() { + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + let mut open = producer.append_group().unwrap(); + open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"a")) + .unwrap(); + + let mut group = subscriber.recv_group().await.unwrap().expect("group"); + assert!(group.read_frame().await.unwrap().is_some()); + + let probes = tokio::spawn(async move { + let first = group.read_frame().await; + let second = group.read_frame().await; + let finished = group.finished().await; + (first, second, finished) + }); + tokio::task::yield_now().await; + + append_at(&mut producer, 1000); + + let (first, second, finished) = probes.await.unwrap(); + assert!(matches!(first, Ok(None)), "the group ends: {first:?}"); + assert!(matches!(second, Ok(None)), "and stays ended: {second:?}"); + assert!(matches!(finished, Ok(1)), "reporting what it delivered: {finished:?}"); + } + + #[tokio::test] + async fn a_drained_group_finishes_cleanly_after_the_live_edge_advances() { + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + append_at(&mut producer, 0); + + let mut group = subscriber.recv_group().await.unwrap().expect("first group"); + assert!(group.read_frame().await.unwrap().is_some()); + + append_at(&mut producer, 1000); + + assert!(group.read_frame().await.unwrap().is_none()); + assert!(!group.latency_expired()); + } + + #[tokio::test] + async fn a_handed_out_partial_frame_expires_while_its_payload_is_stalled() { + tokio::time::pause(); + + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + let mut source = producer.append_group().unwrap(); + let mut writing = source + .create_frame(frame::Info { + size: 6, + timestamp: Timestamp::ZERO, + }) + .unwrap(); + writing.write(bytes::Bytes::from_static(b"old")).unwrap(); + + let mut group = subscriber.recv_group().await.unwrap().expect("partial group"); + let mut frame = group.next_frame().await.unwrap().expect("partial frame"); + assert_eq!( + frame.read_chunk().await.unwrap(), + Some(bytes::Bytes::from_static(b"old")) + ); + let pending = tokio::spawn(async move { frame.read_chunk().await }); + tokio::task::yield_now().await; + assert!(!pending.is_finished(), "the partial payload is still stalled"); + + tokio::time::advance(Duration::from_secs(1)).await; + append_at(&mut producer, 1000); + + let result = pending.await.unwrap(); + assert!( + matches!(result, Err(Error::Old)), + "the in-flight frame expires: {result:?}" + ); + writing.abort(Error::Cancel).unwrap(); + } + + #[tokio::test] + async fn widening_latency_wakes_a_pending_frame_read() { + tokio::time::pause(); + + let mut producer = track_producer("test", None); + let mut subscriber = producer.subscribe(None); + let control = subscriber.control(); + + append_at(&mut producer, 0); + tokio::time::advance(Duration::from_secs(1)).await; + let _edge = producer.append_group().unwrap(); + + let pending = tokio::spawn(async move { subscriber.read_frame().await }); + tokio::task::yield_now().await; + assert!(!pending.is_finished(), "the real-time budget skips the old frame"); + + control + .update(Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(2)))) + .unwrap(); + + let frame = pending + .await + .unwrap() + .unwrap() + .expect("the wider budget admits the frame"); + assert_eq!(frame.payload, bytes::Bytes::from_static(b"x")); + } + + #[test] + fn latency_max_bounds_the_budget() { + // The publisher only keeps a group around for 500ms, so a subscriber asking to + // wait ten seconds for one still gives up at 500ms: the same clamp the aggregate + // applies, on the subscriber's own side of it. + let mut producer = track_producer("test", Info::default().with_latency_max(Duration::from_millis(500))); + append_at(&mut producer, 0); + append_at(&mut producer, 1000); + + let mut subscriber = + producer.subscribe(Subscription::default().with_latency(crate::Latency::max(Duration::from_secs(10)))); + assert_eq!(drain(&mut subscriber), vec![1]); + } + + #[test] + fn an_explicit_start_gets_no_exemption_from_the_budget() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // Asking to start at the beginning is a filter, not a request for reliability. + // Backfill needs a budget that covers it; without one the live edge still wins. + let mut subscriber = producer.subscribe(Subscription::default().with_start(Position::group(0))); + subscriber.start_at(0); + assert_eq!(drain(&mut subscriber), vec![3]); + + let mut patient = producer.subscribe( + Subscription::default() + .with_start(Position::group(0)) + .with_latency(crate::Latency::max(Duration::from_secs(10))), + ); + patient.start_at(0); + assert_eq!(drain(&mut patient), vec![0, 1, 2, 3]); + } + + #[test] + fn next_group_skips_stale_groups_too() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // Sequence-ordered reads run the same budget: a relay serves in arrival order, + // but a decoder reading by sequence must not be handed a backlog either. + let mut subscriber = producer.subscribe(None); + let group = subscriber.next_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(group.sequence, 3); + assert!(subscriber.next_group().now_or_never().is_none()); + } + + #[tokio::test] + async fn real_time_skips_older_sequences_with_equal_ages() { + tokio::time::pause(); + + let mut producer = track_producer("test", None); + append_at(&mut producer, 0); + append_at(&mut producer, 0); + + let mut subscriber = producer.subscribe(None); + assert_eq!(drain(&mut subscriber), vec![1]); + } + + #[test] + fn fetch_ignores_the_budget() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // A fetch names one old group explicitly, so there is no live edge to drift + // from: the budget bounds a subscription, not a request for a specific group. + let consumer = producer.consume(); + let group = consumer.fetch_group(0, None).now_or_never().unwrap().unwrap(); + assert_eq!(group.sequence, 0); + } + + #[tokio::test] + async fn read_frame_honors_the_budget() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // The frame-level helper is the group-level read with the group thrown away, so + // it gives up on a backlog on the same terms. Reading one frame at a time makes + // nothing fresher. + let mut subscriber = producer.subscribe(None); + let frame = subscriber.read_frame().await.unwrap().expect("a frame"); + assert_eq!(frame.timestamp, Timestamp::from_millis(3000).unwrap()); + assert!( + subscriber.read_frame().now_or_never().is_none(), + "the skipped groups are gone, not queued" + ); + } + + /// A one-shot fetch populates the shared cache but never the live arrival cursor, + /// so it cannot make content available to a subscription look stale. + #[tokio::test] + async fn fetched_group_is_not_a_live_drift_edge() { + let mut producer = track_producer("test", None); + let dynamic = producer.dynamic(); + let consumer = producer.consume(); + append_at(&mut producer, 0); + + let pending = consumer.fetch_group(100, None); + let req = dynamic + .requested_group() + .now_or_never() + .expect("fetch request is ready") + .unwrap(); + let mut fetched = req.accept(None).unwrap(); + fetched + .write_frame( + Timestamp::from_millis(100_000).unwrap(), + bytes::Bytes::from_static(b"fetched"), + ) + .unwrap(); + fetched.finish().unwrap(); + pending.await.unwrap(); + + let mut groups = producer.subscribe(None); + assert_eq!(groups.assert_group().sequence, 0); + groups.assert_no_group(); + + let mut frames = producer.subscribe(None); + let frame = frames + .read_frame() + .now_or_never() + .expect("live frame is ready") + .unwrap() + .expect("live frame"); + assert_eq!(frame.timestamp.as_millis(), 0); + assert!(frames.read_frame().now_or_never().is_none()); + } + + /// The live edge is resolved once per poll and applied to every group that poll + /// walks off, so it has to be revalidated before it convicts anything: an eviction + /// in between would otherwise discard a group on the strength of content that is no + /// longer there to jump to. + #[test] + fn an_evicted_live_edge_convicts_nothing() { + let mut producer = track_producer("test", None); + append_at(&mut producer, 0); + let edge = append_at(&mut producer, 30_000); + + let state = producer.state.read(); + let drift = Drift { + budget: Duration::ZERO, + edge: state.live_edge(None), + }; + assert!( + state.is_stale(0, None, drift.edge, drift.budget), + "stale against a live edge" + ); + drop(state); + + // The edge dies between resolving it and judging the candidate. + let slot = producer.modify().unwrap().lookup.remove(&edge).unwrap(); + let _ = slot.group.abort(Error::Evicted); + + let state = producer.state.read(); + assert!( + !state.is_stale(0, None, drift.edge, drift.budget), + "a vanished edge is no reason to drop what is left" + ); + } + + #[tokio::test] + async fn read_frame_counts_what_it_skips() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // A silent skip is indistinguishable from loss whichever read did it, so the + // frame-level path reports its drops like the group-level ones. + let mut subscriber = producer.subscribe(None); + subscriber.read_frame().await.unwrap().expect("a frame"); + let stale = subscriber.take_stale(); + assert_eq!(stale.groups, 3); + assert_eq!(stale.frames, 3); + } + + #[tokio::test] + async fn read_frame_counts_stale_groups_at_eof() { + let mut producer = track_producer("test", None); + append_at(&mut producer, 0); + append_at(&mut producer, 1000); + + // The live edge starts past frame zero, so the frame helper cannot read it. + // The two older groups are still stale and must be reported when the scan + // reaches the clean end without returning a frame. + let mut edge = producer.append_group().unwrap(); + edge.start_at(1).unwrap(); + edge.write_frame(Timestamp::from_millis(2000).unwrap(), b"edge".to_vec()) + .unwrap(); + edge.finish().unwrap(); + producer.finish().unwrap(); + + let mut subscriber = producer.subscribe(None); + assert!(subscriber.read_frame().await.unwrap().is_none()); + let stale = subscriber.take_stale(); + assert_eq!(stale.groups, 2); + assert_eq!(stale.frames, 2); + } + + #[tokio::test] + async fn a_lower_sequence_is_never_the_live_edge() { + tokio::time::pause(); + let mut producer = track_producer("test", None); + // A high timestamp on a lower sequence is not a live edge: backfill served on + // demand sits there, and so does the tail of a timeline the publisher rewound. + // Only groups above the candidate anchor the measure, so neither can convict + // the group that follows it. + let mut straggler = producer.create_group(0u64.into()).unwrap(); + straggler + .write_frame(Timestamp::from_millis(60_000).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + straggler.finish().unwrap(); + + let mut rewound = producer.create_group(1u64.into()).unwrap(); + rewound + .write_frame(Timestamp::from_millis(0).unwrap(), bytes::Bytes::from_static(b"x")) + .unwrap(); + rewound.finish().unwrap(); + + let mut subscriber = producer.subscribe(replay()); + assert_eq!(drain(&mut subscriber), vec![0, 1]); + } + + #[test] + fn a_requested_end_does_not_cap_the_live_edge() { + let mut producer = track_producer("test", None); + for second in 0..4 { + append_at(&mut producer, second * 1000); + } + + // `Subscription::end` is a request to the publisher, folded in with every other + // subscriber's, and it does not filter this handle: the groups above it arrive + // anyway. Capping the live edge with it would pin the edge below them, leaving + // everything past it with nothing newer to be late against. + let mut subscriber = producer.subscribe(Subscription::default().with_end(Position::after_group(1))); + assert_eq!(drain(&mut subscriber), vec![3]); + } + + #[test] + fn a_capped_subscriber_measures_drift_against_its_cap() { + let mut producer = track_producer("test", None); + append_at(&mut producer, 0); + append_at(&mut producer, 1000); + + // Capped at group 0: the route running on past the cap is data this subscriber + // can never be served, so it isn't a live edge to be late against. This is what + // keeps a spliced segment from dropping the groups either side of a takeover + // boundary. + let mut subscriber = producer.subscribe(Subscription::default().with_end(Position::after_group(0))); + subscriber.end_at(0); + assert_eq!(drain(&mut subscriber), vec![0]); + + // Raising the cap re-offers the parked group, now measured against the wider + // edge it just admitted. + subscriber.end_at(None); + assert_eq!(drain(&mut subscriber), vec![1]); + } + #[test] fn subscriber_control_updates_while_read_future_is_pending() { let producer = track_producer("test", None); @@ -4014,7 +5151,7 @@ mod test { #[tokio::test] async fn next_group_returns_arrivals_in_order() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); // Seq 3 arrives first, then seq 5. Both should be returned in arrival order. producer.create_group(group::Info { sequence: 3 }).unwrap(); @@ -4040,7 +5177,7 @@ mod test { #[tokio::test] async fn next_group_and_recv_group_use_independent_cursors() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); // Out-of-order arrivals: seq 5 first, then seq 3. producer.create_group(group::Info { sequence: 5 }).unwrap(); @@ -4064,7 +5201,7 @@ mod test { #[tokio::test] async fn end_at_caps_next_group() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); for s in 0..6 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -4096,7 +5233,7 @@ mod test { #[tokio::test] async fn end_at_release_drains_cached_groups() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); for s in 0..6 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -4141,7 +5278,7 @@ mod test { #[tokio::test] async fn end_at_lower_than_cursor_parks_consumer() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); for s in 0..3 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -4185,7 +5322,7 @@ mod test { #[tokio::test] async fn end_at_toggling_around_late_arrivals() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); consumer.end_at(5); @@ -4231,7 +5368,7 @@ mod test { #[tokio::test] async fn end_at_parks_recv_group() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); for s in 0..3 { producer.create_group(group::Info { sequence: s }).unwrap(); @@ -4271,7 +5408,7 @@ mod test { #[tokio::test] async fn recv_group_serves_arrivals_behind_the_cap() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); consumer.end_at(1); @@ -4401,7 +5538,7 @@ mod test { #[tokio::test] async fn read_frame_returns_single_frame_per_group() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); producer.write_frame(Timestamp::ZERO, b"hello".as_slice()).unwrap(); producer.write_frame(Timestamp::ZERO, b"world".as_slice()).unwrap(); @@ -4468,7 +5605,7 @@ mod test { #[tokio::test] async fn read_frame_discards_rest_of_multi_frame_group() { let mut producer = track_producer("test", None); - let mut consumer = producer.subscribe(None); + let mut consumer = producer.subscribe(replay()); // Group 0 has two frames; only the first is returned. let mut g0 = producer.create_group(group::Info { sequence: 0 }).unwrap(); @@ -4957,7 +6094,7 @@ mod test { assert!(pool.used() <= 21_000, "usage hovers near capacity: {}", pool.used()); // A fresh subscriber skips the evicted groups entirely. - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(replay()); assert!(subscriber.assert_group().sequence > 0, "evicted group is not delivered"); } @@ -5401,7 +6538,7 @@ mod test { producer.create_group(2u64.into()).unwrap().finish().unwrap(); producer.create_group(1u64.into()).unwrap().finish().unwrap(); - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(replay()); assert_eq!(subscriber.assert_group().sequence, 0); assert_eq!(subscriber.assert_group().sequence, 2); assert_eq!( @@ -5522,7 +6659,7 @@ mod test { // The backfill serves by sequence, but never in arrival order. assert!(consumer.peek_group(1).is_some()); - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(replay()); assert_eq!(subscriber.assert_group().sequence, 0); assert_eq!(subscriber.assert_group().sequence, 2); subscriber.assert_no_group(); @@ -5695,7 +6832,7 @@ mod test { assert!(consumer.peek_group(2).is_some(), "backfill is cached for later fetches"); // ...but an arrival-order subscriber only sees the live groups. - let mut subscriber = producer.subscribe(None); + let mut subscriber = producer.subscribe(replay()); assert_eq!(subscriber.assert_group().sequence, 5); assert_eq!(subscriber.assert_group().sequence, 6); subscriber.assert_no_group(); diff --git a/rs/moq-net/src/stats.rs b/rs/moq-net/src/stats.rs index 7130bf00f3c..9403aab5144 100644 --- a/rs/moq-net/src/stats.rs +++ b/rs/moq-net/src/stats.rs @@ -151,6 +151,36 @@ pub(crate) struct Counters { groups: AtomicU64, // Subset of `groups` carried over an unreliable QUIC datagram. datagrams: AtomicU64, + // Content the drift budget gave up on before delivery. Disjoint from the + // top-level payload counters, which count only what was handed over. + stale: ContentCounters, +} + +/// Atomic backing for one [`Content`] readout. +#[derive(Default, Debug)] +struct ContentCounters { + bytes: AtomicU64, + frames: AtomicU64, + groups: AtomicU64, + datagrams: AtomicU64, +} + +impl ContentCounters { + fn snapshot(&self) -> Content { + Content { + bytes: self.bytes.load(Ordering::Relaxed), + frames: self.frames.load(Ordering::Relaxed), + groups: self.groups.load(Ordering::Relaxed), + datagrams: self.datagrams.load(Ordering::Relaxed), + } + } + + fn add(&self, content: Content) { + self.bytes.fetch_add(content.bytes, Ordering::Relaxed); + self.frames.fetch_add(content.frames, Ordering::Relaxed); + self.groups.fetch_add(content.groups, Ordering::Relaxed); + self.datagrams.fetch_add(content.datagrams, Ordering::Relaxed); + } } impl Counters { @@ -174,6 +204,7 @@ impl Counters { let frames = self.frames.load(Ordering::Relaxed); let groups = self.groups.load(Ordering::Relaxed); let datagrams = self.datagrams.load(Ordering::Relaxed); + let stale = self.stale.snapshot(); Traffic { announced, announced_closed, @@ -187,10 +218,40 @@ impl Counters { frames, groups, datagrams, + stale, } } } +/// Payload-volume counters for content with the same delivery outcome. +/// +/// This is the nested shape used by [`Traffic::stale`]. The successfully +/// delivered equivalents remain as top-level [`Traffic`] fields for wire +/// compatibility with existing stats consumers. +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +#[non_exhaustive] +pub struct Content { + /// Cumulative payload bytes. + pub bytes: u64, + /// Cumulative frames. + pub frames: u64, + /// Cumulative groups. + pub groups: u64, + /// Cumulative single-frame groups carried as unreliable datagrams. + pub datagrams: u64, +} + +impl Content { + /// Fold another readout into this one, counter by counter. + pub(crate) fn add(&mut self, other: Self) { + self.bytes += other.bytes; + self.frames += other.frames; + self.groups += other.groups; + self.datagrams += other.datagrams; + } +} + /// Per-(tier, root) session gauge. One of these is shared (via `Arc`) by every /// [`Session`] guard for the same auth root on the same tier: `sessions` /// bumps on connect, `sessions_closed` on disconnect. @@ -257,6 +318,11 @@ pub struct Traffic { /// A subset of `groups`: each one also counts there and its payload in /// `frames` / `bytes`. pub datagrams: u64, + /// Content skipped because it drifted past a subscriber's + /// [`Latency`](crate::Latency) budget. Disjoint from the top-level payload + /// counters: skipped content is never handed over. A steady rate here means + /// subscribers are consistently behind the live edge. + pub stale: Content, } impl Traffic { @@ -274,6 +340,7 @@ impl Traffic { self.frames += other.frames; self.groups += other.groups; self.datagrams += other.datagrams; + self.stale.add(other.stale); } /// True while the broadcast is announced (an announce guard is open). @@ -997,6 +1064,20 @@ impl Meter { } } + /// Whether this meter attributes anything, i.e. the broadcast is tracked and the + /// handle was tagged. A caller holding a count that has to land exactly once can + /// keep it rather than drop it into an untagged meter. + pub(crate) fn is_tracked(&self) -> bool { + self.counters.is_some() + } + + /// Record content skipped before delivery by the drift budget. + pub(crate) fn stale(&self, content: Content) { + if let Some(counters) = self.counters() { + counters.stale.add(content); + } + } + /// Bump `bytes` by `n`. pub(crate) fn bytes(&self, n: u64) { if n == 0 { diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index b48812ddf18..bbf03181452 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -263,6 +263,30 @@ fn render_metrics(snap: &moq_net::stats::Snapshot, listeners: &[moq_tokio::accep "Single-frame groups carried over unreliable QUIC datagrams; a subset of groups.", |c| c.datagrams, ); + counter( + &mut out, + "moq_relay_stale_bytes_total", + "Media payload bytes skipped after drifting beyond a subscriber's latency budget.", + |c| c.stale.bytes, + ); + counter( + &mut out, + "moq_relay_stale_frames_total", + "Media frames skipped after drifting beyond a subscriber's latency budget.", + |c| c.stale.frames, + ); + counter( + &mut out, + "moq_relay_stale_groups_total", + "Media groups skipped after drifting beyond a subscriber's latency budget.", + |c| c.stale.groups, + ); + counter( + &mut out, + "moq_relay_stale_datagrams_total", + "Media datagrams skipped after drifting beyond a subscriber's latency budget.", + |c| c.stale.datagrams, + ); counter( &mut out, "moq_relay_fetches_total", @@ -580,12 +604,21 @@ mod tests { tokio::time::sleep(std::time::Duration::from_millis(1)).await; tokio::time::sleep(std::time::Duration::from_millis(1)).await; - // Read 1234 egress bytes out of the default-tier broadcast. + // Leave 46 bytes across two frames behind the live edge, then read 1234 + // egress bytes out of the default-tier broadcast. let bc = announced.next().await.unwrap().broadcast.unwrap(); let mut egress_sub = bc.track("video").unwrap().subscribe(None).await.unwrap(); { let mut group = pub_track.append_group().unwrap(); - group.write_frame(Timestamp::ZERO, vec![0u8; 1234]).unwrap(); + group.write_frame(Timestamp::ZERO, vec![0u8; 12]).unwrap(); + group.write_frame(Timestamp::ZERO, vec![0u8; 34]).unwrap(); + group.finish().unwrap(); + } + { + let mut group = pub_track.append_group().unwrap(); + group + .write_frame(Timestamp::from_millis(10_000).unwrap(), vec![0u8; 1234]) + .unwrap(); group.finish().unwrap(); } let mut group = egress_sub.recv_group().await.unwrap().unwrap(); @@ -612,6 +645,22 @@ mod tests { body.contains("moq_relay_bytes_total{tier=\"region/sjc\",role=\"subscriber\"} 56"), "named tier gets its own row:\n{body}" ); + assert!( + body.contains("moq_relay_stale_bytes_total{tier=\"\",role=\"publisher\"} 46"), + "stale egress bytes:\n{body}" + ); + assert!( + body.contains("moq_relay_stale_frames_total{tier=\"\",role=\"publisher\"} 2"), + "stale egress frames:\n{body}" + ); + assert!( + body.contains("moq_relay_stale_groups_total{tier=\"\",role=\"publisher\"} 1"), + "stale egress groups:\n{body}" + ); + assert!( + body.contains("moq_relay_stale_datagrams_total{tier=\"\",role=\"publisher\"} 0"), + "stale egress datagrams:\n{body}" + ); assert!( body.contains("moq_relay_sessions_opened_total{tier=\"\"} 1"), "session presence:\n{body}" diff --git a/rs/moq-relay/tests/cluster_unknown.rs b/rs/moq-relay/tests/cluster_unknown.rs index 69634f38329..e20c5ef7fe4 100644 --- a/rs/moq-relay/tests/cluster_unknown.rs +++ b/rs/moq-relay/tests/cluster_unknown.rs @@ -148,10 +148,18 @@ async fn read_first_frame(port: u16) -> Result, String> { .map_err(|_| "announced_broadcast timed out".to_string())? .ok_or_else(|| "origin closed before the broadcast was announced".to_string())?; - let mut track = tokio::time::timeout(TIMEOUT, broadcast.track("video").expect("track handle").subscribe(None)) - .await - .map_err(|_| "subscribe timed out".to_string())? - .map_err(|err| format!("subscribe failed: {err}"))?; + // This verifies route propagation rather than real-time backlog skipping. Give + // every hop enough tolerance for the next 100ms group to arrive while the + // selected group's frame is still crossing the redundant mesh. + let subscription = + moq_net::track::Subscription::default().with_latency(moq_net::Latency::max(Duration::from_secs(1))); + let mut track = tokio::time::timeout( + TIMEOUT, + broadcast.track("video").expect("track handle").subscribe(subscription), + ) + .await + .map_err(|_| "subscribe timed out".to_string())? + .map_err(|err| format!("subscribe failed: {err}"))?; let mut group = tokio::time::timeout(TIMEOUT, track.recv_group()) .await diff --git a/rs/moq-relay/tests/goaway_cluster.rs b/rs/moq-relay/tests/goaway_cluster.rs index aac238499e5..3196b6a197b 100644 --- a/rs/moq-relay/tests/goaway_cluster.rs +++ b/rs/moq-relay/tests/goaway_cluster.rs @@ -453,11 +453,18 @@ async fn cluster_diamond_goaway_seamless_failover_inner() { // A live (unordered) subscription transmits the newest group first, so a // back-to-back burst legally arrives inverted; `ordered` is the protocol's // way to ask every hop for sequence-order transmission instead. + // + // The latency budget is the other half of that ask: this test asserts every group + // arrives exactly once, which is more than the default REAL_TIME budget promises. + // A subscriber that wants completeness across a failover has to say how far behind + // the live edge it is willing to sit (clamped to what the publisher retains). let mut sub = within( "subscribe to the video track", - bc.track("video") - .expect("track handle") - .subscribe(moq_net::track::Subscription::default().with_ordered(true)), + bc.track("video").expect("track handle").subscribe( + moq_net::track::Subscription::default() + .with_ordered(true) + .with_latency(moq_net::Latency::max(Duration::from_secs(60))), + ), ) .await .expect("subscribe"); diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index bd382608d5c..a1ff93a6da6 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -40,13 +40,17 @@ impl Consumer { let name = name.into(); let track = broadcast .track(&name)? - .subscribe(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video)) + .subscribe( + moq_net::track::Subscription::default() + .with_priority(hang::catalog::PRIORITY.video) + .with_latency(config.latency), + ) .await?; // The catalog says how the track is framed, and it is not always the legacy // wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a // varint timestamp plus a payload decodes to garbage rather than failing. let container = moq_mux::catalog::hang::Container::try_from(&catalog.container)?; - let track = moq_mux::container::Consumer::new(track, container).with_latency(config.latency); + let track = moq_mux::container::Consumer::new(track, container); Ok(Self { decoder, @@ -131,7 +135,12 @@ mod tests { .await .unwrap(); let source = moq_mux::Source::new(origin.consume(), "test"); - let mut export = moq_mux::container::fmp4::Export::new(source, catalog); + // Both frames are encoded before the export runs, so the exporter needs a budget + // wide enough to read them: its REAL_TIME default keeps only the live edge, and + // the second `next()` would then block forever waiting for a group that was + // skipped. + let mut export = moq_mux::container::fmp4::Export::new(source, catalog) + .with_latency(moq_mux::Latency::max(std::time::Duration::from_secs(30))); let init = export.next().await.unwrap().expect("CMAF init"); let fragment = export.next().await.unwrap().expect("CMAF fragment"); diff --git a/rs/moq-video/src/decode/decoder.rs b/rs/moq-video/src/decode/decoder.rs index dd180c9e764..9b38cf6af0a 100644 --- a/rs/moq-video/src/decode/decoder.rs +++ b/rs/moq-video/src/decode/decoder.rs @@ -45,8 +45,8 @@ pub struct Config { /// How far playback may drift from the live edge before a stalled group is /// skipped. Defaults to [`Latency::REAL_TIME`](moq_mux::Latency::REAL_TIME) /// (skip aggressively); set [`Latency::max`](moq_mux::Latency::max) to your - /// playout buffer for a softer skip. Forwarded to - /// [`moq_mux::container::Consumer::with_latency`]. + /// playout buffer for a softer skip. Applied to the initial transport + /// subscription and inherited by [`moq_mux::container::Consumer`]. pub latency: moq_mux::Latency, /// Ask the decoder to emit frames at this size (both dimensions even) instead /// of the stream's native one. Best effort: a hardware decoder with a