diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 7dd2a07581f..4b94a3b0d9a 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -81,7 +81,7 @@ This README owns the end-to-end proof and the guide once every child lands: ## Required -- [Mid-group subscriptions widen](/quest/m1/compress/app-range-widen.md) - an application range starting mid-group on a compressed track widens to frame 0 at the subscriber instead of failing with `Lagged` +- [moq-transport mid-group subscriptions widen](/quest/m1/compress/ietf-range-widen.md) - an application range starting mid-group on a compressed track widens to frame 0 at a moq-transport subscriber instead of failing with `Lagged` - [Migrate](/quest/m1/compress/migrate.md) - catalogs, stats, and timelines publish one compressed track; moq-flate, @moq/flate, and every `.z` name are gone ## Related diff --git a/quest/m1/compress/app-range-widen.md b/quest/m1/compress/app-range-widen.md deleted file mode 100644 index 75fcfed2326..00000000000 --- a/quest/m1/compress/app-range-widen.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] A mid-group subscription to a compressed track widens to frame 0 - -## Goal - -An application subscription whose range starts mid-group on a compressed -track succeeds: the subscriber's requesting model widens the request to frame -0 of that group before it leaves, and the reader gets the frames it asked for. -Today it fails with `Lagged`. The server never widens and keeps serving -exactly what is asked. - -## Plan - -Decided with the maintainer on 2026-10-20, from -[#5928](https://github.com/moq-dev/moq/pull/5928)'s Decision 6, which the -[epic](/quest/m1/compress/README.md)'s Ranges rule records: the subscriber -widens, never the server. - -- Route-change resume already widens to frame 0. This covers ranges an - application supplies, through the same requesting-model path rather than a - second rule. -- Widen only when the subscriber lacks the group's prefix; one that holds - frames 0..N-1 still asks from N. -- The reader still starts at the frame it asked for: the widened prefix only - feeds the inflater. - -Regression test on mock time, in Rust: a mid-group application subscribe on a -compressed track returns the requested frames instead of `Lagged`, and the -wire request starts at frame 0. Mirror it in `js/net`, which carries -compressed tracks too. - -Public API: none. Wire: none. diff --git a/quest/m1/compress/ietf-range-widen.md b/quest/m1/compress/ietf-range-widen.md new file mode 100644 index 00000000000..62b818c0fc0 --- /dev/null +++ b/quest/m1/compress/ietf-range-widen.md @@ -0,0 +1,58 @@ +# [M] A moq-transport mid-group subscription to a compressed track widens to frame 0 + +## Goal + +An application range starting mid-group on a compressed track, requested over +moq-transport draft-17+ with the Flate extension negotiated, reads the frames +it asked for instead of failing with `Lagged` against a publisher that serves +exactly the requested Object range. The requesting IETF subscriber widens the +SUBSCRIBE start to Object 0 when it lacks the group's prefix, as lite-07 does +since [moq-dev/moq#6242](https://github.com/moq-dev/moq/pull/6242). The server +never widens and keeps serving exactly what is asked. + +## Plan + +The rule is the [epic](/quest/m1/compress/README.md)'s Ranges rule, decided +with the maintainer on 2026-10-20: the subscriber widens, never the server; +one that holds frames 0..N-1 still asks from N; the reader still starts at the +frame it asked for. Lite-07 applies it through `track::Producer::widen_compressed` +(`rs/moq-net/src/model/track.rs`), which a warm IETF copy can reuse. + +Split from #6242 because a two-hop matrix (lite-07 and moq-transport-17, 18 +and 22 on either hop) found three gaps under the IETF requester that are not +about compression: + +- A cold SUBSCRIBE (`Target::Request` in `rs/moq-net/src/ietf/subscriber.rs`) + learns the track is compressed only from SUBSCRIBE_OK. Widening every cold + mid-group start on a Flate session would make plain tracks pay for the + prefix too. Decide between learning the properties first (TRACK_STATUS where + `TrackStatusOk::describes_track` holds) and widening cold starts only on + Flate sessions. +- Readers get IETF-received groups whole: `track::Subscriber::deliver` skips + the frame window when `group.relayed()`, since Object IDs may not be frame + ordinals. An application on an IETF hop therefore already reads frames below + its start on plain tracks, and widening would hand it more. Filter by + ordinal when the copy's Object IDs are dense, or by Object ID. +- REQUEST_UPDATE carries no range, so a live range change never reaches + upstream; [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) owns + that. + +In the matrix, our own IETF publisher served the whole group for a mid-group +Absolute start, so the `Lagged` failure needs a publisher that honors the +exact start; test against the publisher model directly. + +`js/net` needs no mirror: its subscriptions carry group ranges only +(`Subscription.groups`), so a JS SUBSCRIBE always starts at frame 0, and a +compressed group that does not is refused with `TooFarBehind`. + +Regression: extend +`application_ranges_keep_their_filter_after_requesting_the_compressed_prefix` +(`rs/moq-net/tests/integration/compress.rs`) over moq-transport-17, 18 and 22 +hops. + +Public API: none. Wire: none. + +## Related + +- [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - carries a live range change upstream on REQUEST_UPDATE +- [Bounded tails](/quest/m1/subscribe-ranges/bounded-tail.md) - a copy cut at a request's end must accept its tail before a warm prefix can be extended diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index a8e1a1611a2..77d4b797449 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -100,6 +100,7 @@ every sequence delivered or dropped. - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft - [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream - [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity +- [Bounded tails](/quest/m1/subscribe-ranges/bounded-tail.md) - a copy cut at a request's mid-group end accepts the rest of its group instead of rejecting it as `Duplicate` ## Related diff --git a/quest/m1/subscribe-ranges/bounded-tail.md b/quest/m1/subscribe-ranges/bounded-tail.md new file mode 100644 index 00000000000..edd6a9065f1 --- /dev/null +++ b/quest/m1/subscribe-ranges/bounded-tail.md @@ -0,0 +1,42 @@ +# [M] A copy that stopped at a request's end bound accepts its tail + +## Goal + +A group received for a request whose end falls mid-group stays open to the +rest of that group. When later demand asks the same sequence past that end, +the tail is accepted instead of rejected as `Duplicate`, so a second +subscriber on the same relay reads the frames it asked for. This holds for +plain and compressed tracks on every version that carries frame bounds. + +## Plan + +Found on [moq-dev/moq#6242](https://github.com/moq-dev/moq/pull/6242) while +answering Codex's +[P1](https://github.com/moq-dev/moq/pull/6242#discussion_r4345457940): through +one relay, a subscriber reads group 5 frames 0..3 and a second then asks for +3..5. The tail never arrives, on a plain track and on a compressed one alike. + +- `GroupRecv` (`rs/moq-net/src/lite/subscriber.rs`) calls `group.finish()` + when a group stream ends cleanly, including one that ended only because the + request's end bound was reached. The truncated copy then looks complete. +- `claim_sequence` and `covering_group` (`rs/moq-net/src/model/track.rs`) + judge a copy only by its first frame, so every later stream for that + sequence is `Duplicate`, whatever frame it was asked from. +- Fix it in the receive path: a stream that stopped at the request's end + bound is not the group's end. Weigh leaving the copy unfinished so a tail + appends from its end (one copy; a compressed group keeps inflating against + its own prefix, which `widen_compressed` relies on when it keeps a request at + N) against letting a bounded copy stop covering a request past its end so + the new stream replaces it (compressed requests would then widen to frame 0 + again). +- A peer must not be able to pass off an early FIN as reaching the bound. + +Test on mock time through a relay: a bounded first subscriber, then a second +asking past its end, on plain and compressed lite-07 tracks, and on +moq-transport draft-20+ if its Absolute end reaches the same path. + +Public API: none expected. Wire: none. + +## Related + +- [Compressed tracks](/quest/m1/compress/README.md) - its Ranges rule keeps a warm request at N, which this makes reachable diff --git a/rs/moq-net/benches/codec.rs b/rs/moq-net/benches/codec.rs index 39f6dad9347..651e4c8b636 100644 --- a/rs/moq-net/benches/codec.rs +++ b/rs/moq-net/benches/codec.rs @@ -68,5 +68,45 @@ fn bench(c: &mut Criterion) { group.finish(); } -criterion_group!(benches, bench); +/// An outgoing request reads the counted aggregate and checks only its named group, +/// independent of the audience beside it and the cache's unrelated groups. +fn compressed_request(c: &mut Criterion) { + use moq_net::{broadcast, track}; + use std::hint::black_box; + let mut bench = c.benchmark_group("codec_compressed_request"); + for groups in [1, 64, 1024] { + for readers in [1, 64, 1024] { + for held in [false, true] { + let broadcast = broadcast::Info::default().produce(); + let track = broadcast + .create_track("compressed", track::Info::default().with_compress(true)) + .unwrap(); + for _ in 0..groups { + let mut group = track.append_group().unwrap(); + group.write_frame(None, bytes::Bytes::from_static(b"prefix")).unwrap(); + group.finish().unwrap(); + } + let sequence = if held { groups - 1 } else { groups }; + let subscription = track::Subscription::default().with_ranges([track::Range { + start: track::Anchor::Absolute(track::Position { + group: sequence, + frame: 1, + }), + end: None, + }]); + let _readers: Vec<_> = (0..readers).map(|_| track.subscribe(subscription.clone())).collect(); + bench.bench_function(BenchmarkId::new(format!("held_{held}_{readers}r"), groups), |b| { + b.iter(|| { + let mut subscription = track.subscription().unwrap(); + moq_net::fuzz::widen_compressed(&track, &mut subscription); + black_box(subscription); + }); + }); + } + } + } + bench.finish(); +} + +criterion_group!(benches, bench, compressed_request); criterion_main!(benches); diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index e917c812417..2c752971a7f 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -73,6 +73,11 @@ pub fn object_group(frames: usize, properties: bool) -> (broadcast::Producer, tr (broadcast, track, group) } +/// Normalize a compressed wire request for the private requesting-model benchmark. +pub fn widen_compressed(track: &track::Producer, subscription: &mut track::Subscription) { + track.widen_compressed(subscription); +} + /// Every target, keyed by the name of its `fuzz_targets/.rs` shim. pub const TARGETS: &[(&str, Target)] = &[ ("lite", lite_wire), diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 817fb1d9f01..320e1b4e97e 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -4308,6 +4308,54 @@ mod tests { } } + /// A partial prefix, a tail, or a released group cannot seed the inflater. Only + /// a complete live prefix permits requesting the tail without widening its start. + #[moq_clock::test] + async fn compressed_frame_bounds_require_the_entire_cached_prefix() { + for (first, count, aborted, expected) in [ + (0, 0, false, 0), + (0, 2, false, 0), + (0, 3, false, 3), + (1, 3, false, 0), + (0, 3, true, 0), + ] { + let mut h = Harness::new(Version::Lite07); + h.producer = h + ._broadcast + .create_track("compressed", track::Info::timed().with_compress(true)) + .unwrap(); + let mut group = h.producer.create_group(crate::group::Info { sequence: 5 }).unwrap(); + group.start_at(first).unwrap(); + for frame in first..first + count { + group + .write_frame(crate::Timestamp::from_millis(frame).unwrap(), b"prefix".as_ref()) + .unwrap(); + } + if aborted { + group.abort(Error::Cancel).unwrap(); + } else { + group.finish().unwrap(); + } + let mut sub = Sub::None; + h.serve + .handle_subscription(&mut h.producer, &mut sub, Some(mid_group_demand()), true) + .await + .unwrap(); + let wire = h.wire(); + let mut wire = wire.as_slice(); + assert_eq!( + crate::coding::decode_buf(&mut wire, Version::Lite07, lite::ControlType::decode).unwrap(), + lite::ControlType::Subscribe + ); + let msg = crate::coding::decode_buf(&mut wire, Version::Lite07, lite::Subscribe::decode).unwrap(); + assert_eq!( + (msg.start_group, msg.start_frame, msg.end_group, msg.end_frame), + (Some(5), expected, Some(5), Some(7)), + "first={first}, count={count}, aborted={aborted}" + ); + } + } + /// The model's exclusive end maps back to the wire's inclusive pair. /// /// The two disagree deliberately (see [`Position::after_group`]), so this pins the seam: @@ -6217,6 +6265,7 @@ impl TrackServe { // The wire carries one range: the span of every range asked for, which the // subscribers' own reads narrow again. subscription.set_bounds(subscription.start(), subscription.end()); + producer.widen_compressed(&mut subscription); self.widen_frame_bounds(&mut subscription); match sub { Sub::None => { diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index a35f014980f..8207fa631a5 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -1932,6 +1932,13 @@ impl Handle { state.abort.is_none().then_some(state.offset) } + /// Whether this copy still holds every committed frame below `end`, so a compressed + /// tail requested there can inflate against it. Sparse object IDs are not ordinals. + pub(super) fn holds_prefix(&self, end: u64) -> bool { + let state = self.state.read(); + state.abort.is_none() && state.offset == 0 && !state.sparse() && state.committed as u64 >= end + } + /// One past the last frame committed to an unfinished group, when that is past its /// first: where a replacement route resumes. `None` once the group is finished, or /// while it holds nothing a replacement could continue. diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 5a0f04c654d..53b19382dce 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -3340,6 +3340,45 @@ impl Producer { poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter).map(Ok) } + /// Widen outgoing compressed ranges that cannot inflate from a cached prefix. + /// Only requesters call this: the original preferences keep filtering local reads, + /// and a server serves the frame bounds it was actually asked for. + /// + /// A range kept mid-group relies on the cached prefix, so it counts as a read of that + /// copy and normal eviction takes it last. Nothing pins it: a prefix still lost + /// before its tail lands fails that group with [`Error::Lagged`], which takes a + /// consumer slower than the cache's turnover. + #[cfg_attr( + not(feature = "async"), + allow(dead_code, reason = "Only session adapters request upstream.") + )] + // private: capability gap + pub(crate) fn widen_compressed(&self, subscription: &mut Subscription) { + if !self.info.compress { + return; + } + let state = self.state.read(); + for range in &mut subscription.ranges { + if range.is_empty() { + continue; + } + let Anchor::Absolute(start) = &mut range.start else { + continue; + }; + if start.frame == 0 { + continue; + } + let prefix = state + .lookup + .get(&start.group) + .and_then(|slot| slot.copies().find(|group| group.holds_prefix(start.frame))); + match prefix { + Some(group) => group.cache_refresh(), + None => start.frame = 0, + } + } + } + /// Create a [`Dynamic`] handle that serves on-demand fetches of uncached /// (old) groups. Most producers never need this; a relay creates one to fetch /// past groups from upstream. @@ -14694,6 +14733,56 @@ mod test { assert!(consumer.peek_group(1).is_none(), "unread group is evicted instead"); } + /// Requesting a compressed tail from frame N reads the cached prefix it relies on, as a + /// FETCH hit does, so pressure evicts a never-read group first and the prefix stays to + /// seed the tail's inflater. + #[test] + fn a_requested_prefix_survives_eviction() { + let (producer, pool) = pooled_producer(u64::MAX); + let producer = Producer::new( + producer.broadcast.clone(), + "compressed", + Info::timed().with_compress(true), + ); + let consumer = producer.consume(); + // Incompressible, so each group caches about its payload. + let mut seed = 1u32; + let mut append = || { + let payload: Vec = (0..3_000) + .map(|_| { + seed = seed.wrapping_mul(1_103_515_245).wrapping_add(12_345); + (seed >> 16) as u8 + }) + .collect(); + let mut group = producer.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, payload).unwrap(); + group.finish().unwrap(); + }; + + append(); // seq 0 + elapse(&producer, Duration::from_secs(1)); + append(); // seq 1 + elapse(&producer, Duration::from_secs(1)); + let used = pool.used(); + append(); // seq 2 + // Room for the three groups and a little more, so each later append evicts one. + pool.resize(pool.used() + (pool.used() - used) / 3); + elapse(&producer, Duration::from_millis(500)); + + let start = Anchor::Absolute(Position { group: 0, frame: 1 }); + let mut request = Subscription::default().with_ranges([Range { start, end: None }]); + producer.widen_compressed(&mut request); + assert_eq!(request.ranges[0].start, start, "a held prefix keeps the request at N"); + elapse(&producer, Duration::from_millis(500)); + + append(); // seq 3 + elapse(&producer, Duration::from_secs(1)); + append(); // seq 4 + + assert!(consumer.peek_group(0).is_some(), "the requested prefix survives"); + assert!(consumer.peek_group(1).is_none(), "an unread group is evicted instead"); + } + /// A consumer holding an evicted group surfaces the eviction, not a hang or a /// truncated clean end. #[moq_clock::test] diff --git a/rs/moq-net/tests/integration/compress.rs b/rs/moq-net/tests/integration/compress.rs index e562a73f998..a846b1efac3 100644 --- a/rs/moq-net/tests/integration/compress.rs +++ b/rs/moq-net/tests/integration/compress.rs @@ -54,6 +54,11 @@ struct Fixture { /// A compressed track crosses a relay between the requested protocols. async fn connect(upstream: &str, downstream: &str) -> Fixture { + connect_with(upstream, downstream, moq_net::track::Subscription::default()).await +} + +/// As [`connect`], with the downstream application asking for `subscription`. +async fn connect_with(upstream: &str, downstream: &str, subscription: moq_net::track::Subscription) -> Fixture { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); let track = broadcast.create_track("data", compressed()).unwrap(); @@ -74,7 +79,7 @@ async fn connect(upstream: &str, downstream: &str) -> Fixture { let consumer = origin.consume(); consumer.routed("bcast").await.unwrap(); let remote = consumer.request_broadcast("bcast", None).await.unwrap(); - let subscriber = remote.track("data").unwrap().subscribe(None).await.unwrap(); + let subscriber = remote.track("data").unwrap().subscribe(subscription).await.unwrap(); support::harness::subscribed(&track).await; Fixture { @@ -86,6 +91,54 @@ async fn connect(upstream: &str, downstream: &str) -> Fixture { } } +/// A cold subscriber needs the compressed prefix, but its application sees only its +/// requested half-open frame range, including when it changes that range while live. +#[moq_clock::test] +async fn application_ranges_keep_their_filter_after_requesting_the_compressed_prefix() { + use moq_net::track::{Anchor, Position, Range, Subscription}; + moq_clock::timeout(TIMEOUT, async { + let range = |group, start, end| { + Subscription::default().with_ranges([Range { + start: Anchor::Absolute(Position { group, frame: start }), + end: Some(Anchor::Absolute(Position { group, frame: end })), + }]) + }; + let mut fixture = connect_with("moq-lite-07-wip", "moq-lite-07-wip", range(5, 2, 4)).await; + assert_eq!( + fixture.track.subscription_changed().await.unwrap().unwrap().ranges[0].start, + Anchor::Absolute(Position::group(5)), + "upstream asks for the prefix" + ); + for sequence in [5, 6] { + if sequence == 6 { + fixture.subscriber.update(range(6, 1, 3)).unwrap(); + let updated = fixture.track.subscription_changed().await.unwrap().unwrap(); + // Old route copies can keep their earlier floor until a newer group arrives. + // The updated end must already permit the newly requested group. + assert_eq!( + updated.ranges[0].end, + Some(Anchor::Absolute(Position { group: 6, frame: 3 })) + ); + } + let mut group = fixture.track.create_group(moq_net::group::Info { sequence }).unwrap(); + for index in 0..5 { + group + .write_frame(Timestamp::from_millis(index).unwrap(), payload(index)) + .unwrap(); + } + group.finish().unwrap(); + let mut reading = fixture.subscriber.recv_group().await.unwrap().unwrap(); + let (start, end) = if sequence == 5 { (2, 4) } else { (1, 3) }; + for index in start..end { + assert_eq!(reading.read_frame().await.unwrap().unwrap().payload, payload(index)); + } + assert!(reading.read_frame().await.unwrap().is_none()); + } + }) + .await + .expect("the requested frames arrive"); +} + /// Whole and chunked frames on a compressed track read back as written on every version, /// and only a peer that can signal it learns the track is compressed. #[moq_clock::test]