From 1ee4d0e23184768beacadd2a22096da5449aafeb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 17:55:55 -0700 Subject: [PATCH 01/18] quest(m1): claim public-model/serve From 007e502b54f0a81708bdce914c7f8450ac4af730 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 18:15:20 -0700 Subject: [PATCH 02/18] refactor(net)!: public serving cursor and group expiry in Rust One consuming with_range builder on track::Subscriber, track::Ordered, group::Consumer, and Subscription assigns the floor and cap. poll_start, poll_drop, group::Consumer::poll_expired, Position::final_sequence, and Subscription::{start, end, with_start, with_end} are public. poll_live and latest_sequence wait on the track-live quest; Consumer::final_sequence on the deferred quest. Co-Authored-By: Claude Opus 5.5 --- quest/m1/public-model/deferred.md | 4 +- rs/moq-archive/src/reader/tests.rs | 2 +- rs/moq-audio/src/decode/consumer.rs | 2 +- rs/moq-cli/src/play/media.rs | 2 +- rs/moq-flate/src/snapshot/consumer.rs | 2 +- rs/moq-hls/src/export/archive_tests.rs | 2 +- rs/moq-hls/src/export/history.rs | 2 +- rs/moq-hls/src/export/rendition.rs | 2 +- rs/moq-json/src/snapshot/consumer.rs | 2 +- rs/moq-json/src/window/mod.rs | 2 +- rs/moq-mux/src/container/consumer.rs | 12 +- rs/moq-mux/src/container/source.rs | 2 +- rs/moq-mux/src/container/ts/export_test.rs | 2 +- rs/moq-net/benches/group.rs | 2 +- rs/moq-net/benches/origin.rs | 8 +- rs/moq-net/benches/track.rs | 12 +- rs/moq-net/src/ietf/publisher.rs | 38 +- rs/moq-net/src/ietf/subscriber.rs | 16 +- rs/moq-net/src/lite/publisher.rs | 158 +++---- rs/moq-net/src/lite/subscriber.rs | 15 +- rs/moq-net/src/model/group.rs | 137 ++++--- rs/moq-net/src/model/mod.rs | 2 - rs/moq-net/src/model/resume.rs | 137 +++---- rs/moq-net/src/model/subscription.rs | 136 +++---- rs/moq-net/src/model/track.rs | 384 +++++++++--------- rs/moq-net/src/model/track/demand.rs | 2 +- .../tests/integration/announce_to_serve.rs | 2 +- .../integration/finished_broadcast_mock.rs | 2 +- rs/moq-net/tests/integration/finite_relay.rs | 2 +- rs/moq-net/tests/integration/group_order.rs | 2 +- .../tests/integration/history_groups.rs | 4 +- rs/moq-net/tests/integration/partial_group.rs | 2 +- rs/moq-net/tests/integration/quiet_catalog.rs | 2 +- .../tests/integration/received_rewind.rs | 2 +- .../integration/settled_end_survives_abort.rs | 2 +- .../tests/integration/subscribe_ranges.rs | 2 +- .../integration/subscription_end_integrity.rs | 4 +- rs/moq-net/tests/integration/track_tail.rs | 8 +- rs/moq-net/tests/integration/untimed.rs | 2 +- rs/moq-net/tests/loom.rs | 6 +- rs/moq-room/src/chat.rs | 9 +- rs/moq-stats/src/produce.rs | 2 +- rs/moq-tokio/tests/integration/broadcast.rs | 2 +- rs/moq-video/src/decode/consumer.rs | 2 +- test/interop/clients/rust/tail.rs | 2 +- 45 files changed, 555 insertions(+), 589 deletions(-) diff --git a/quest/m1/public-model/deferred.md b/quest/m1/public-model/deferred.md index 87c752e6700..487bdb87b85 100644 --- a/quest/m1/public-model/deferred.md +++ b/quest/m1/public-model/deferred.md @@ -24,7 +24,9 @@ the prerequisites will have deleted or renamed most of these. the need. Model ranges replaces per-group requests with ranges, and its public range answer is the ingest path. - Cache peeks (Rust `track::Consumer::peek_latest`, `peek_before`, - `peek_group`, `is_live`; IETF publisher, for Largest Object and FETCH) + `peek_group`, `is_live`, and `final_sequence`, which a FETCH reads for + END_OF_TRACK with no subscriber to poll the end on; IETF publisher, for + Largest Object and FETCH) and JS `Track.Subscriber.fork`: remove the need, since IETF FETCH is served from ranges and the largest location is public. If either still has a caller, bring the shape back to the maintainer rather than publishing diff --git a/rs/moq-archive/src/reader/tests.rs b/rs/moq-archive/src/reader/tests.rs index 3cf641605e3..b5025468ffc 100644 --- a/rs/moq-archive/src/reader/tests.rs +++ b/rs/moq-archive/src/reader/tests.rs @@ -894,7 +894,7 @@ async fn benchmark_timeline_fetch_fanout() { broadcast.info().pool.gc(now, &kio::Waiter::noop()); } let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(60)); let mut retained = broadcast .consume() diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index a77ad17ebe7..ad16cb89914 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -201,7 +201,7 @@ impl Consumer { && warmup.is_zero() && let Some(live_edge) = subscriber.largest().await { - subscriber.set_groups(live_edge.group..); + subscriber = subscriber.with_range(live_edge.group..); } let track = subscriber; let retention = track.info().max_age; diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index 7aa884a844d..acce6e3cf86 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -263,7 +263,7 @@ impl Media { // once the feed is live, so wait for it rather than read the backlog of // a warm copy still waiting on its source; the wait ends with the track. if let Some(largest) = subscriber.largest().await { - subscriber.set_groups(largest.group..); + subscriber = subscriber.with_range(largest.group..); } let format = catalog::hang::Container::try_from(config)?; Ok::<_, anyhow::Error>((moq_mux::container::Consumer::new(subscriber, format), decoder)) diff --git a/rs/moq-flate/src/snapshot/consumer.rs b/rs/moq-flate/src/snapshot/consumer.rs index 0fea756618d..a2a57acac84 100644 --- a/rs/moq-flate/src/snapshot/consumer.rs +++ b/rs/moq-flate/src/snapshot/consumer.rs @@ -224,7 +224,7 @@ mod timestamps { .create_track("data", moq_net::track::Info::default()) .unwrap(); let mut subscriber = track.subscribe(None); - subscriber.set_groups(..5); + subscriber = subscriber.with_range(..5); let config = crate::snapshot::Config::default(); let mut producer = crate::snapshot::Producer::new(track, config.clone()); let mut consumer = Consumer::new(subscriber, config); diff --git a/rs/moq-hls/src/export/archive_tests.rs b/rs/moq-hls/src/export/archive_tests.rs index df5f9227aa4..87a15bdf271 100644 --- a/rs/moq-hls/src/export/archive_tests.rs +++ b/rs/moq-hls/src/export/archive_tests.rs @@ -768,7 +768,7 @@ async fn history_after_expiry(finished: bool) { .pool .gc(now + Duration::from_secs(31), &kio::Waiter::noop()); let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis((1_u64 << 62) - 1)); let mut retained = broadcast .consume() diff --git a/rs/moq-hls/src/export/history.rs b/rs/moq-hls/src/export/history.rs index 5586906f824..9b934662076 100644 --- a/rs/moq-hls/src/export/history.rs +++ b/rs/moq-hls/src/export/history.rs @@ -34,7 +34,7 @@ pub(super) async fn read( // Effectively unbounded, so no history group is skipped as late: 2^53 - 1 ms is the largest // delay every implementation decodes (js/net reads it as a safe integer). let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis((1_u64 << 53) - 1)); let mut live = track.subscribe(subscription).await?.ordered(); let mut decoder = window::Decoder::::new(window::ConsumerConfig::default().with_compression(true)); diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 3fb4778fafb..eac9b205b5f 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -1224,7 +1224,7 @@ async fn fetch( match track.fetch_group(start.group, options).await { Ok(mut group) => { if let Some(end) = end { - group.set_frames(..end); + group = group.with_range(..end); } Ok(Ok(group)) } diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index e630536ce56..af8a9632aa2 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -285,7 +285,7 @@ mod timestamps { .create_track("data", moq_net::track::Info::default()) .unwrap(); let mut subscriber = track.subscribe(None); - subscriber.set_groups(..5); + subscriber = subscriber.with_range(..5); let mut producer = crate::snapshot::Producer::new(track, crate::snapshot::Config::default()); let mut consumer = Consumer::::new(subscriber, Default::default()); let waiter = kio::Waiter::noop(); diff --git a/rs/moq-json/src/window/mod.rs b/rs/moq-json/src/window/mod.rs index 82c5fdc0eea..cc99d97f71e 100644 --- a/rs/moq-json/src/window/mod.rs +++ b/rs/moq-json/src/window/mod.rs @@ -461,7 +461,7 @@ mod test { .flatten() .map(|position| position.group) .unwrap(); - subscriber.set_groups(largest..); + subscriber = subscriber.with_range(largest..); let mut fresh = consumer(subscriber, false); producer.finish().unwrap(); diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 150766f8345..6086fc7f76b 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1188,7 +1188,7 @@ mod tests { let track = track_producer("data", info); let subscription = moq_net::track::Subscription::default() .with_max_delay(hour) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1218,7 +1218,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1317,7 +1317,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1382,7 +1382,7 @@ mod tests { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscription = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(10)) - .with_groups(0..); + .with_range(0..); let mut reader = Consumer::new( track.subscribe(subscription), Container::Legacy(crate::container::Kind::Data), @@ -1609,7 +1609,7 @@ mod tests { _ => panic!("the empty group is the largest"), }; assert_eq!(edge.group, 1); - subscriber.set_groups(edge.group..); + subscriber = subscriber.with_range(edge.group..); let mut consumer = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Audio)); write_group(&mut track, 2, &[ts(1_000_000), ts(1_600_000)]); @@ -2561,7 +2561,7 @@ mod tests { let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer_track = track.subscribe( moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_millis(500)), ); let mut consumer = Consumer::new(consumer_track, Container::Legacy(crate::container::Kind::Data)); diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 0f57a1dd450..8c7ff3b8202 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -369,7 +369,7 @@ impl ExportSource { }; let mut subscription = moq_net::track::Subscription::default().with_max_delay(self.max_delay); if let Some(start) = self.start { - subscription = subscription.with_groups(start..); + subscription = subscription.with_range(start..); } self.state = SourceState::Subscribing(broadcast.track(&name)?.subscribe(subscription)); } diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 83f5a3659a7..76985b00e7c 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -2768,7 +2768,7 @@ async fn read_si_groups(consumer: &moq_net::broadcast::Consumer, name: &str) -> .unwrap() .subscribe( moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(5)), ) .await diff --git a/rs/moq-net/benches/group.rs b/rs/moq-net/benches/group.rs index 54b1b22ca3d..fa4cb5d1737 100644 --- a/rs/moq-net/benches/group.rs +++ b/rs/moq-net/benches/group.rs @@ -223,7 +223,7 @@ fn filled_track(n: usize, payload: &Bytes) -> TrackCtx { fn replay() -> track::Subscription { track::Subscription::default() .with_max_delay(Duration::MAX) - .with_groups(0..) + .with_range(0..) } /// Drain N cached groups from a track, in arrival order and in sequence order. diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 4cd654e56cb..3bb4f94247f 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -1378,12 +1378,12 @@ async fn resume_overlap(readers: usize, retained: usize, routes: usize, ordered: let subscription = track::Subscription::default().with_max_delay(Duration::from_secs(3600)); let mut subscribers = Vec::with_capacity(readers); for _ in 0..readers { - let mut subscriber = moq_clock::timeout(COPY_WAIT, track.subscribe(subscription.clone())) + let subscriber = moq_clock::timeout(COPY_WAIT, track.subscribe(subscription.clone())) .await .expect("track did not splice") .expect("subscribe failed"); // Held back until the drain, so every route's copy is kept for its unread groups. - subscriber.set_groups(..0); + let subscriber = subscriber.with_range(..0); subscribers.push(subscriber); } let waiter = kio::Waiter::noop(); @@ -1402,11 +1402,9 @@ async fn resume_overlap(readers: usize, retained: usize, routes: usize, ordered: ); } } - for subscriber in &mut subscribers { - subscriber.set_groups(..); - } let readers = subscribers .into_iter() + .map(|subscriber| subscriber.with_range(..)) .map(|subscriber| match ordered { true => ResumeReader::Sequence(subscriber.ordered()), false => ResumeReader::Arrival(subscriber), diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 45c61b29b30..30257691009 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -714,14 +714,14 @@ fn bench_subscriber_join(c: &mut Criterion) { /// Each held reader asks for distinct values, so the aggregate's tables grow with the audience. fn bench_subscriber_preferences(c: &mut Criterion) { let ordinary = track::Subscription::default() - .with_groups(100..200) + .with_range(100..200) .with_order(track::Order::Ascending); let held = |i: usize| { let i = i as u64; track::Subscription::default() .with_priority((i % 255) as u8) .with_max_delay(Duration::from_micros(i)) - .with_groups(100 + i..200 + i) + .with_range(100 + i..200 + i) .with_order(track::Order::Ascending) }; let extreme = track::Subscription::default() @@ -777,7 +777,7 @@ fn bench_range_demand(c: &mut Criterion) { // Far past every held range, so each move adds one run and removes another. let away = |offset: u64| { let group = (1 << 40) + offset; - track::Subscription::default().with_groups(group..=group) + track::Subscription::default().with_range(group..=group) }; let mut group = c.benchmark_group("track_range_demand"); for steady in STEADY { @@ -789,7 +789,7 @@ fn bench_range_demand(c: &mut Criterion) { // Overlapping, so the held ranges union into one run. let start = (i % distinct) as u64 * 10; subscriber - .update(track::Subscription::default().with_groups(start..start + 1000)) + .update(track::Subscription::default().with_range(start..start + 1000)) .unwrap(); } let mut viewer = setup.track.subscribe(away(0)); @@ -816,7 +816,7 @@ fn bench_subscription_ranges(c: &mut Criterion) { let viewers: Vec<_> = (0..ranges) .map(|i| { let start = i * (span + 1); - track.subscribe(track::Subscription::default().with_groups(start..start + span)) + track.subscribe(track::Subscription::default().with_range(start..start + span)) }) .collect(); assert_eq!(track.subscription().unwrap().ranges.len(), ranges as usize); @@ -1232,7 +1232,7 @@ fn bench_range_widening(c: &mut Criterion) { } let narrow = track::Subscription::default() .with_max_delay(AGED_BUDGET) - .with_groups(0..1); + .with_range(0..1); let mid = cached / 2; let wide = narrow .clone() diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 4e7d6e9ef59..d39546bcc02 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -4148,21 +4148,18 @@ struct TrackServe { impl TrackServe { fn new( session: S, - mut track: track::Subscriber, + track: track::Subscriber, request_id: RequestId, version: Version, range: ServeRange, timescale: Option, ) -> Self { - match range.start { - Some(start) => track.start_at(start.group), - None => { - if let Some(latest) = track.latest_sequence() { - track.start_at(latest); - } - } - } - track.end_at(range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group))); + let floor = match range.start { + Some(start) => start.group, + None => track.latest_sequence().unwrap_or(0), + }; + let end = range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group)); + let track = track.with_range((Bound::Included(floor), end)); let datagrams = session.max_datagram_size() > 0; // A Timestamp whose units were not declared is worse than none. Drafts 14-16 // never write TIMESCALE, whatever the caller passed in, so datagrams and group @@ -4786,7 +4783,7 @@ impl GroupServe { ) -> Self { if group.wire().is_none() { group.skip_to(slice.skip); - group.end_at(slice.until.map_or(Bound::Unbounded, Bound::Excluded)); + group = group.with_range((Bound::Unbounded, slice.until.map_or(Bound::Unbounded, Bound::Excluded))); } Self { session, @@ -4881,7 +4878,7 @@ impl GroupServe { // 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) { + if self.group.poll_expired(waiter) { break 'serve Err(Error::Old); } return Poll::Pending; @@ -4900,7 +4897,7 @@ impl GroupServe { // 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) { + if self.group.poll_expired(waiter) { break 'serve Err(Error::Old); } return Poll::Pending; @@ -5079,7 +5076,7 @@ impl GroupServe { // Those bytes still hold the connection until acknowledged, so a // group gone stale meanwhile releases them like one still serving: // dropping the writer resets the stream. - Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + Poll::Pending if self.group.poll_expired(waiter) => { self.state = GroupState::Done; return Poll::Ready(Err(Error::Old)); } @@ -15419,16 +15416,15 @@ struct ServeRange { impl ServeRange { /// Bound `subscription` to this range. fn apply(&self, subscription: &mut Subscription) { - subscription.set_bounds( - self.start.map(|start| track::Position { + *subscription = std::mem::take(subscription) + .with_start(self.start.map(|start| track::Position { group: start.group, frame: start.object, - }), - self.end.and_then(|end| match end.object { + })) + .with_end(self.end.and_then(|end| match end.object { Some(object) => track::Position::after(end.group, object), None => track::Position::after_group(end.group), - }), - ); + })); } } @@ -15622,7 +15618,7 @@ mod range_tests { // Next Group against a live edge of 8 asks for 9, which does not exist yet. let mut subscriber = track.subscribe(None); - subscriber.start_at(9); + subscriber.set_range(9..); assert!( futures::poll!(std::pin::pin!(subscriber.recv_group())).is_pending(), "a future start must wait for its group rather than serving the live edge" diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index d590a411019..d02ee09ac0d 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -13908,8 +13908,12 @@ mod stitch_tests { let mut whole = h.stream().await; h.subscriber.clone().recv_group(&mut whole).await.expect("the group"); - let mut group = consumer.recv_group().await.unwrap().expect("the group arrived"); - group.start_at(0); + let mut group = consumer + .recv_group() + .await + .unwrap() + .expect("the group arrived") + .with_range(0..); assert_eq!(group.index(), 2, "the group starts where the subscription asked"); assert_eq!(&group.read_frame().await.unwrap().unwrap().payload[..], b"2"); assert!(group.read_frame().await.unwrap().is_none()); @@ -13936,8 +13940,12 @@ mod stitch_tests { h.subscriber.clone().recv_fill(&mut fill).await.expect("fill"); h.subscriber.clone().recv_group(&mut tail).await.expect("tail"); - let mut group = consumer.recv_group().await.unwrap().expect("the group arrived"); - group.start_at(0); + let mut group = consumer + .recv_group() + .await + .unwrap() + .expect("the group arrived") + .with_range(0..); assert_eq!(group.index(), 2, "the group starts where the subscription asked"); let mut frames = Vec::new(); while let Some(frame) = group.read_frame().await.unwrap() { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 2850cf0f487..f51cbe8dfcf 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -106,7 +106,7 @@ fn serving_max_delay(version: Version, requested: Duration) -> Duration { } } -/// Position a subscription's read cursor for the wire serving it. +/// The floor of a subscription's read cursor for the wire serving it. /// /// On lite-06 there is nothing to do: `Consumer::subscribe` resolves the cursor from the /// subscription itself, at the oldest group its own max delay still considers fresh, floored @@ -120,14 +120,11 @@ fn serving_max_delay(version: Version, requested: Duration) -> Duration { /// /// `latest` is the newest group when the SUBSCRIBE arrived, not once the subscription /// resolved: anything written in between is newer, so it is delivered. -fn position_cursor(track: &mut track::Subscriber, version: Version, start_group: Option, latest: Option) { +fn cursor_floor(version: Version, start_group: Option, latest: Option) -> u64 { if version.resolves_start() || start_group.is_some() { - return; - } - - if let Some(latest) = latest { - track.start_at(latest); + return 0; } + latest.unwrap_or(0) } impl Shared { @@ -1962,7 +1959,7 @@ enum SubscribeServe { /// Boxed: the request is far larger than the other states' handles. msg: Box>, subscribing: track::Subscribing, - /// The newest group when the SUBSCRIBE arrived; see [`position_cursor`]. + /// The newest group when the SUBSCRIBE arrived; see [`cursor_floor`]. latest: Option, update: Option, }, @@ -2037,7 +2034,7 @@ impl Request for SubscribeServe { match self { Self::Confirm { subscribing, .. } => { let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); - let mut track = ready!(subscribing.poll_ok(waiter))?; + let track = ready!(subscribing.poll_ok(waiter))?; let Self::Confirm { msg, latest, update, .. } = std::mem::replace( @@ -2098,8 +2095,8 @@ impl Request for SubscribeServe { }; let bounds = Bounds::from(msg.as_ref()); - position_cursor(&mut track, shared.version, bounds.start_group, latest); - let mut run = TrackRun::new(sub, track, bounds, steer_tx); + let floor = cursor_floor(shared.version, bounds.start_group, latest); + let mut run = TrackRun::new(sub, track, bounds, floor, steer_tx); if let Some(update) = update { run.update(update); } @@ -2213,7 +2210,7 @@ impl Request for FetchServe { Self::Fetch { msg, fetching } => { // Before the group: a fetched group polled while this waited would be lost. let ietf = ready!(shared.peer_setup.poll_ietf(waiter)); - let mut group = ready!(kio::Task::poll(fetching, waiter))?; + let group = ready!(kio::Task::poll(fetching, waiter))?; // The response carries no header, so a short run is indistinguishable // from one that started elsewhere: only serve a range we can cover @@ -2225,7 +2222,10 @@ impl Request for FetchServe { // The end is a serving cap only: the cached group runs to the end of // the group so it stays usable for anyone else (see // `group::Fetch::frame_start`). - group.end_at(msg.end_frame.map_or(Bound::Unbounded, Bound::Included)); + let group = group.with_range(( + Bound::Unbounded, + msg.end_frame.map_or(Bound::Unbounded, Bound::Included), + )); // Matches the timescale TRACK_INFO declared for the track. let timescale = shared.version.wire_timescale(group.timescale()); @@ -2379,21 +2379,21 @@ mod test { "the unbounded budget alone resolves to the whole cache" ); - let mut legacy = served(Version::Lite01); - position_cursor(&mut legacy, Version::Lite01, None, producer.latest_sequence()); + let legacy = served(Version::Lite01); + let mut legacy = legacy.with_range(cursor_floor(Version::Lite01, None, producer.latest_sequence())..); assert_eq!(drain(&mut legacy), vec![2]); // Lite03-05 declare a budget, but their drafts define it as a staleness tolerance // and an absent start as the latest group, so they are pinned all the same. - let mut tolerant = + let tolerant = producer.subscribe(track::Subscription::default().with_max_delay(std::time::Duration::from_secs(5))); - position_cursor(&mut tolerant, Version::Lite05, None, producer.latest_sequence()); + let mut tolerant = tolerant.with_range(cursor_floor(Version::Lite05, None, producer.latest_sequence())..); assert_eq!(drain(&mut tolerant), vec![2]); // On lite-06 the declared budget is what resolves the start, so it stands. - let mut declared = + let declared = producer.subscribe(track::Subscription::default().with_max_delay(std::time::Duration::from_secs(5))); - position_cursor(&mut declared, Version::Lite06, None, producer.latest_sequence()); + let mut declared = declared.with_range(cursor_floor(Version::Lite06, None, producer.latest_sequence())..); assert_eq!(drain(&mut declared), vec![0, 1, 2]); } @@ -2421,7 +2421,7 @@ mod test { match recv_next(&mut subscriber, false, false).await.unwrap() { Recv::Group(group) => { assert_eq!(group.sequence, 7); - subscriber.start_at(group.sequence); + subscriber.set_range(group.sequence..); } _ => panic!("expected the first group"), } @@ -3385,33 +3385,31 @@ async fn recv_next(track: &mut track::Subscriber, datagrams: bool, emit_boundary kio::wait(|waiter| poll_recv_next(track, datagrams, emit_boundary, waiter)).await } -/// Bound `group` to what this subscription asked for, reporting whether it can be served +/// Bound `group` to what this subscription asked for, or `None` when it cannot be served /// at all. /// /// Frame bounds qualify the start and end group only; everything in between is served -/// whole. `false` means the group's head is missing and the subscriber never asked for a +/// whole. `None` means the group's head is missing and the subscriber never asked for a /// partial group, so it must be skipped: a group is the unit of decodability, and only /// the subscriber knows whether a partial one is any use to it. -fn position_group(group: &mut group::Consumer, start: Option<(u64, u64)>, end: Option<(u64, u64)>) -> bool { +fn position_group( + group: group::Consumer, + start: Option<(u64, u64)>, + end: Option<(u64, u64)>, +) -> Option { let expected = match start { Some((sequence, frame)) if sequence == group.sequence => frame, _ => 0, }; + let end = match end { + Some((sequence, frame)) if sequence == group.sequence => Bound::Included(frame), + _ => Bound::Unbounded, + }; - // `start_at` clamps up to the first frame the group still holds, so landing higher + // The start clamps up to the first frame the group still holds, so landing higher // than asked means the frames below it are gone. - group.start_at(expected); - if group.index() != expected { - return false; - } - - if let Some((sequence, frame)) = end - && sequence == group.sequence - { - group.end_at(Bound::Included(frame)); - } - - true + let group = group.with_range((Bound::Included(expected), end)); + (group.index() == expected).then_some(group) } /// A subscription's requested delivery range, exactly as it arrived on the wire. @@ -3651,6 +3649,9 @@ impl Subscription { struct TrackRun { ctx: Subscription, track: track::Subscriber, + // The read cursor's floor and cap, assigned together on every move. + floor: u64, + cap: Bound, /// Broadcasts SUBSCRIBE_UPDATE priorities to the in-flight group machines. steer_tx: kio::Producer, // Frame bounds qualify the start and end group only; everything in between is @@ -3683,10 +3684,17 @@ struct TrackRun { } impl TrackRun { - fn new(ctx: Subscription, mut track: track::Subscriber, bounds: Bounds, steer_tx: kio::Producer) -> Self { + fn new( + ctx: Subscription, + track: track::Subscriber, + bounds: Bounds, + floor: u64, + steer_tx: kio::Producer, + ) -> Self { // Apply the initial cap from the original Subscribe. Subsequent updates // flow through the SUBSCRIBE_UPDATE arm below. - track.end_at(bounds.end_group.map_or(Bound::Unbounded, Bound::Included)); + let cap = bounds.end_group.map_or(Bound::Unbounded, Bound::Included); + let track = track.with_range((Bound::Included(floor), cap)); let emit_range = ctx.version.has_track_stream(); let datagrams = ctx.version.has_datagrams() && ctx.session.max_datagram_size() > 0; @@ -3698,6 +3706,8 @@ impl TrackRun { end_frame: bounds.end_frame(), ctx, track, + floor, + cap, steer_tx, emit_range, start: None, @@ -3771,7 +3781,7 @@ impl TrackRun { floor => floor, }; if let Some(start) = floor { - self.track.start_at(start); + self.floor = start; // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. if let Some(resolved) = self.start { // A lowered floor owes the groups it newly asks for, so the end sweep covers them. @@ -3780,12 +3790,25 @@ impl TrackRun { self.start = Some(resolved.min(start)); } } - self.track - .end_at(upd.end_group.map_or(Bound::Unbounded, Bound::Included)); + self.cap = upd.end_group.map_or(Bound::Unbounded, Bound::Included); + self.move_cursor(); self.start_frame = bounds.start_frame(); self.end_frame = bounds.end_frame(); } + /// Apply [`Self::floor`] and [`Self::cap`] to the read cursor. + fn move_cursor(&mut self) { + self.track.set_range((Bound::Included(self.floor), self.cap)); + } + + /// Raise the read cursor's floor to `start`, keeping any higher floor already set. + fn raise_floor(&mut self, start: u64) { + if start > self.floor { + self.floor = start; + self.move_cursor(); + } + } + /// Serve until the live edge reaches the track's boundary. #[cfg(test)] fn poll(&mut self, writer: &mut Writer, waiter: &kio::Waiter) -> Poll> { @@ -3863,7 +3886,7 @@ impl TrackRun { group: start.group, largest: Some(largest), }))?; - self.track.raise_start_to(start.group); + self.raise_floor(start.group); return Poll::Ready(Ok(ControlFlow::Continue(()))); } @@ -3874,7 +3897,7 @@ impl TrackRun { let emit_boundary = self.emit_range && !self.end_sent; if let Poll::Ready(res) = poll_recv_next(&mut self.track, self.datagrams, emit_boundary, waiter) { match res? { - Recv::Group(mut group) => { + Recv::Group(group) => { // Never a second stream for a sequence this subscription already accounted // for (served, sent as a datagram, or dropped): a group re-created after its // DROP stays dropped, since the subscriber may settle before it arrives. @@ -3885,24 +3908,25 @@ impl TrackRun { { return Poll::Ready(Ok(ControlFlow::Continue(()))); } - if !position_group(&mut group, self.start_frame, self.end_frame) { + let sequence = group.sequence; + let Some(group) = position_group(group, self.start_frame, self.end_frame) else { // Its head is gone, and this subscriber didn't ask for a // partial group. Skip it rather than open a stream that can // only be reset; the next servable group resolves the start. - tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence = group.sequence, "skipping group with a missing head"); + tracing::debug!(subscribe = self.ctx.id, track = %self.ctx.track_name, sequence, "skipping group with a missing head"); if self.emit_range && self.start.is_none() { // At u64::MAX no later group can resolve a start past this one. - if let Some(end) = group.sequence.checked_add(1) { - self.skipped.insert(group.sequence..end); + if let Some(end) = sequence.checked_add(1) { + self.skipped.insert(sequence..end); } } else if self.start.is_some() - && let Some(end) = group.sequence.checked_add(1) + && let Some(end) = sequence.checked_add(1) { // Lite-05+ names it now; a no-op on other versions. - self.drop_range(group.sequence..end, writer)?; + self.drop_range(sequence..end, writer)?; } return Poll::Ready(Ok(ControlFlow::Continue(()))); - } + }; match self.emit_range && self.start.is_none() { true => self.first = Some(group), false => self.serve(group), @@ -4064,7 +4088,7 @@ impl TrackRun { // that 0 is group 0, so it is not pinned. Raised, not assigned: an update that // landed while the group was held may already have raised it past. if self.track.subscription().start().is_none() && !self.ctx.version.resolves_start() { - self.track.raise_start_to(start); + self.raise_floor(start); } self.serve(group); Ok(()) @@ -4317,7 +4341,7 @@ impl GroupServe { // 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) { + if self.group.poll_expired(waiter) { break 'serve Err(Error::Old); } return Poll::Pending; @@ -4336,7 +4360,7 @@ impl GroupServe { // 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) { + if self.group.poll_expired(waiter) { break 'serve Err(Error::Old); } return Poll::Pending; @@ -4461,7 +4485,7 @@ impl GroupServe { Poll::Ready(res) => res, // Those bytes still hold the connection until acknowledged, so a // group gone stale meanwhile releases them like one still serving. - Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + Poll::Pending if self.group.poll_expired(waiter) => { let GroupState::Closed { writer } = std::mem::replace(&mut self.state, GroupState::Done) else { unreachable!() @@ -4564,23 +4588,19 @@ mod serve_group_test { group.write_frame(Timestamp::ZERO, b"tail".to_vec()).unwrap(); // Asked for whole groups, so the missing frames 0..5 make this unservable. - let mut consumer = group.consume(); - assert!(!position_group(&mut consumer, None, None)); + assert!(position_group(group.consume(), None, None).is_none()); // Asked for exactly where it starts: servable, and positioned there. - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, Some((3, 5)), None)); + let consumer = position_group(group.consume(), Some((3, 5)), None).unwrap(); assert_eq!(consumer.index(), 5); // Asked for an earlier frame than the group holds: still a hole, still skipped. - let mut consumer = group.consume(); - assert!(!position_group(&mut consumer, Some((3, 2)), None)); + assert!(position_group(group.consume(), Some((3, 2)), None).is_none()); // The offset belongs to the start group only; a later group is served whole. let mut other = track.create_group(group::Info { sequence: 4 }).unwrap(); other.write_frame(Timestamp::ZERO, b"whole".to_vec()).unwrap(); - let mut consumer = other.consume(); - assert!(position_group(&mut consumer, Some((3, 5)), None)); + let consumer = position_group(other.consume(), Some((3, 5)), None).unwrap(); assert_eq!(consumer.index(), 0); } @@ -4598,8 +4618,7 @@ mod serve_group_test { } group.finish().unwrap(); - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, None, Some((7, 1)))); + let mut consumer = position_group(group.consume(), None, Some((7, 1))).unwrap(); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -4614,8 +4633,7 @@ mod serve_group_test { ); // A cap naming another group leaves this one uncapped. - let mut consumer = group.consume(); - assert!(position_group(&mut consumer, None, Some((8, 1)))); + let mut consumer = position_group(group.consume(), None, Some((8, 1))).unwrap(); for i in 0..4u8 { assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], @@ -5098,7 +5116,7 @@ mod serve_group_test { end_group: None, end_frame: None, }; - (TrackRun::new(ctx, track, bounds, steer), writer, log) + (TrackRun::new(ctx, track, bounds, 0, steer), writer, log) } #[moq_clock::test] @@ -5769,7 +5787,7 @@ mod serve_group_test { .unwrap() .subscribe( track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(Duration::from_secs(60)), ) .await @@ -5790,7 +5808,7 @@ mod serve_group_test { let mut live = remote .track("test") .unwrap() - .subscribe(track::Subscription::default().with_groups(0..)) + .subscribe(track::Subscription::default().with_range(0..)) .await .unwrap(); assert_eq!(live.recv_group().await.unwrap().unwrap().sequence, 2); @@ -6230,7 +6248,7 @@ mod serve_group_test { end_frame: None, }; Self { - run: TrackRun::new(ctx, subscriber, bounds, steer), + run: TrackRun::new(ctx, subscriber, bounds, 0, steer), writer, session, outcomes, diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 825dcbe86ec..310c7db5a35 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1941,7 +1941,7 @@ mod tests { } moq_clock::sleep(crate::tail::GRACE * 2).await; - let lowered = Some(Subscription::default().with_groups(2..)); + let lowered = Some(Subscription::default().with_range(2..)); // The SUBSCRIBE in force, already answered. let floor = Position::group(if update { 5 } else { 2 }); let mut sub = Sub::Active(SubStream { @@ -5587,10 +5587,8 @@ impl TrackServe { // subscriber holds, so ask from the head of its group instead: the first frame then // arrives at once and says where the live feed is. if !self.subscriber.version.has_largest() { - subscription.set_bounds( - subscription.start().map(|start| Position::group(start.group)), - subscription.end(), - ); + let start = subscription.start().map(|start| Position::group(start.group)); + *subscription = std::mem::take(subscription).with_start(start); } if self.subscriber.version.has_frame_bounds() { return; @@ -5614,7 +5612,7 @@ impl TrackServe { "widening frame bounds to whole groups for an older peer" ); } - subscription.set_bounds(start, end); + *subscription = std::mem::take(subscription).with_start(start).with_end(end); } /// Apply a subscription-demand change: hand back an [`Establish`] to open the @@ -5640,7 +5638,8 @@ impl TrackServe { Some(mut subscription) => { // 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()); + let start = subscription.start(); + subscription = subscription.with_start(start); self.widen_frame_bounds(&mut subscription); match sub { Sub::None => { @@ -5648,7 +5647,7 @@ impl TrackServe { // the subscriber has no start of its own: a quiet track (a catalog) sends // that group again, which says the cache is current. if subscription.start().is_none() { - subscription.set_bounds(producer.idle_newest().map(Position::group), subscription.end()); + subscription = subscription.with_start(producer.idle_newest().map(Position::group)); } // The track's arrivals outlive a subscription, and this one asks for // its groups only now. diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 6498967b55d..d7ed4481bdd 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -10,16 +10,16 @@ //! Frames are numbered from 0 in write order. A group can be short at its front or its //! back but never in the middle: [Producer::start_at] starts it later, so a handle can //! carry the tail of a group whose leading frames came from somewhere else, and -//! [Producer::finish] ends it wherever writing stopped. [Consumer::set_frames] bounds a reader to a sub-range the same way [`track::Subscriber`] +//! [Producer::finish] ends it wherever writing stopped. [Consumer::with_range] bounds a reader to a sub-range the same way [`track::Subscriber`] //! bounds group sequences. //! //! The stream is closed with [Error] when all writers or readers are dropped. use crate::cache; use crate::frame::{self, Frame, FrameBuf}; -use crate::{Cap, Timescale, stats, track}; +use crate::{Timescale, stats, track}; use std::collections::VecDeque; use std::mem::MaybeUninit; -use std::ops::{Bound, RangeBounds}; +use std::ops::RangeBounds; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::{Arc, Mutex, PoisonError, Weak}; use std::task::{Poll, ready}; @@ -878,7 +878,7 @@ impl Producer { /// head of the group, typically another route serving the same track (see /// [`crate::track::Subscriber`]). /// - /// The counterpart of [`Consumer::set_frames`], which positions a *reader* the same + /// The counterpart of [`Consumer::with_range`], which positions a *reader* the same /// way. Where the group begins is part of its shape, so this must come before the /// first frame; afterwards it returns [`Error::Closed`]. pub fn start_at(&mut self, index: u64) -> Result<()> { @@ -1946,7 +1946,7 @@ struct Cursor { // NOTE: Cloned readers inherit this offset, but then run in parallel. index: usize, - // Exclusive cap on `index`, set by [`Consumer::set_frames`]. Reads end cleanly at it. + // Exclusive cap on `index`, set by [`Consumer::with_range`]. Reads end cleanly at it. end: Option, // A batch of completed frames drained ahead under one lock (whole-frame reads only). @@ -2154,10 +2154,15 @@ impl Consumer { } } - /// Check the parent subscription while a wire publisher drains detached payload. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { - self.poll_expired_while_pending(waiter, false) + /// Whether the subscription this group was handed out under has given up on it, waking + /// once it does. + /// + /// A publisher still writing the group polls this while it waits on its own transport, + /// which the group's reads cannot see: once the subscription's + /// [`max_delay`](crate::track::Subscription::max_delay) expires the group, it abandons + /// the stream, even with every frame already read off. Stays `true` once set. + pub fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { + self.poll_expiry(waiter, true) } /// Apply the drift budget to a read that found nothing and is about to park, failing @@ -2177,17 +2182,17 @@ impl Consumer { /// policy walks the track's group cache under its lock, which is shared by every /// subscriber of that track. fn poll_expired_if_blocked(&mut self, waiter: &kio::Waiter, res: Poll>) -> Poll> { - match res.is_pending() && self.poll_expired(waiter) { + match res.is_pending() && self.poll_expiry(waiter, false) { true => Poll::Ready(Err(Error::Old)), false => res, } } - /// Keep checking expiry while a wire publisher still owns buffered group data. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn poll_expired_while_pending(&mut self, waiter: &kio::Waiter, pending: bool) -> bool { + /// Apply the drift budget, judging even a group whose cursor has nothing left to + /// discard when `held`, since its reader still holds data from it. + fn poll_expiry(&mut self, waiter: &kio::Waiter, held: bool) -> bool { if !self.expired - && (pending || self.expiry_pending()) + && (held || self.expiry_pending()) && self.expiry.as_ref().is_some_and(|expiry| { let budget = self.recover.as_ref().and_then(|recover| recover.poll_budget(waiter)); expiry.is_expired(budget, waiter) @@ -2223,58 +2228,38 @@ impl Consumer { /// The index of the next frame this consumer will return. /// - /// Starts at 0, or at the group's first available frame once [`Self::set_frames`] has + /// Starts at 0, or at the group's first available frame once [`Self::with_range`] has /// clamped it, and advances by one per frame read. pub fn index(&self) -> u64 { self.cursor.index as u64 } - /// Limit subsequent reads to these frame indices without rewinding read progress. + /// Limit subsequent reads to these frame indices without rewinding read progress, + /// returning `self` for chaining. /// - /// `2..=5` includes frames 2 through 5; `2..5` excludes frame 5. An omitted - /// start preserves read progress, and an omitted end removes the cap. - /// Raising the cap makes unread cached frames available again. - pub fn set_frames(&mut self, frames: impl RangeBounds) { + /// `2..=5` includes frames 2 through 5; `2..5` excludes frame 5, and `..0` is the empty + /// range. The start skips ahead, clamped *up* to the group's first available frame: + /// frames the group never held (see [`Producer::start_at`]) can't be returned, so read + /// [`Self::index`] back to learn where the cursor landed. A start below the cursor is + /// ignored, since those frames may already have been handed out. The end is assigned: + /// reads past it end cleanly (`None`), as if the group finished there, and an omitted + /// end removes the cap. Raising the cap re-offers frames that are still cached. + pub fn with_range(mut self, frames: impl RangeBounds) -> Self { let (start, end) = super::subscription::sequence_bounds(frames); - self.start_at(start); - self.end_at(end.map_or(Bound::Unbounded, Bound::Excluded)); - } - - /// Skip ahead so the next frame returned is `index`, discarding anything buffered - /// below it. - /// - /// Clamped *up* to the group's first available frame: frames the group never held - /// (see [`Producer::start_at`]) can't be returned, so asking for one just starts at - /// the first that exists. Read [`Self::index`] back to learn where the cursor - /// actually landed. - /// Only moves forward; a lower `index` is ignored, since the frames behind the - /// cursor may already have been handed out. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn start_at(&mut self, index: u64) { - self.cursor.start_at(index); + self.cursor.start_at(start); + self.cursor.end = end.map(|end| usize::try_from(end).unwrap_or(usize::MAX)); + self } /// Advance the read cursor to `index`, skipping every frame below it. /// - /// Unlike [`Self::set_frames`], this does not clamp past a requested frame the group + /// Unlike [`Self::with_range`], this does not clamp past a requested frame the group /// never held. A [`Producer::start_at`] floor above `index` still surfaces as /// [`Error::Lagged`]. pub fn skip_to(&mut self, index: u64) { self.cursor.skip_to(index); } - /// Stop reading at `end`, or remove the cap with `..`. - /// - /// `..=2` reads through frame 2, `..2` stops before it, and `..0` is the empty range: - /// no frame is delivered. Reads past the cap end cleanly (`None`), as if the group - /// finished there. The cap can move in either direction: raising it re-offers - /// frames that are still cached. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn end_at(&mut self, end: impl Into) { - let end = end.into().exclusive(); - self.cursor.end = end.map(|end| usize::try_from(end).unwrap_or(usize::MAX)); - } - /// The number of frames written so far (completed plus any in-flight), independent of /// how many this consumer has read. The final total once the group is finished. pub fn frame_count(&self) -> usize { @@ -2291,7 +2276,7 @@ impl Consumer { /// Poll for the next frame, without blocking. /// /// Returns None if the group is finished and the index is out of range, or the cursor - /// passed the [`Self::set_frames`] cap. + /// passed the [`Self::with_range`] cap. pub fn poll_next_frame(&mut self, waiter: &kio::Waiter) -> Poll>> { if self.recover.is_none() { return self.poll_next_frame_once(waiter); @@ -2639,7 +2624,7 @@ pub struct Fetch { /// cached locally and only the tail is missing. /// /// There is no matching end: a fetch always runs to the end of the group, and a - /// caller wanting less caps the returned consumer with [`Consumer::set_frames`]. Stopping + /// caller wanting less caps the returned consumer with [`Consumer::with_range`]. Stopping /// the *fetch* short would put a group in the cache that is indistinguishable from a /// complete one, so a later fetch of the whole group would resolve from it and come /// up short. @@ -3068,10 +3053,10 @@ mod test { group }) .collect(); - subscriber.set_groups(..0); + subscriber.set_range(..0); let waiter = kio::Waiter::noop(); assert!(subscriber.poll_recv_group(&waiter).is_pending()); - subscriber.set_groups(..1); + subscriber.set_range(..1); let _unrelated = groups[2].handle.state.read(); let Poll::Ready(Ok(Some(group))) = subscriber.poll_recv_group(&waiter) else { panic!("group zero is in range") @@ -3296,8 +3281,7 @@ mod test { if wired_first { tail.set_wire(wire.clone()).unwrap(); } - let mut reader = tail.consume(); - reader.start_at(2); + let mut reader = tail.consume().with_range(2..); let before = pool.used(); tail.handle.adopt_head(&head); assert!(pool.used() >= before + 2, "the adopted frames are charged"); @@ -3851,8 +3835,7 @@ mod test { producer.write_frame(Timestamp::ZERO, Bytes::from_static(b"d")).unwrap(); producer.finish().unwrap(); - let mut consumer = producer.consume(); - consumer.start_at(1); + let mut consumer = producer.consume().with_range(1..); assert_eq!(consumer.index(), 3, "clamped up to the first frame that exists"); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, @@ -3872,7 +3855,7 @@ mod test { producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(..2); + consumer = consumer.with_range(..2); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -3886,7 +3869,7 @@ mod test { "capped reads end cleanly" ); - consumer.set_frames(..); + consumer = consumer.with_range(..); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 2 @@ -3902,19 +3885,19 @@ mod test { } producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(1..=1); + consumer = consumer.with_range(1..=1); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 1 ); assert!(consumer.read_frame().now_or_never().unwrap().unwrap().is_none()); - consumer.set_frames(..3); + consumer = consumer.with_range(..3); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 2 ); assert!(consumer.read_frame().now_or_never().unwrap().unwrap().is_none()); - consumer.set_frames(0..=3); + consumer = consumer.with_range(0..=3); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 3 @@ -3931,13 +3914,13 @@ mod test { producer.finish().unwrap(); let mut consumer = producer.consume(); - consumer.set_frames(..0); + consumer = consumer.with_range(..0); assert!( consumer.read_frame().now_or_never().unwrap().unwrap().is_none(), "empty cap delivers nothing" ); - consumer.set_frames(..1); + consumer = consumer.with_range(..1); assert_eq!( consumer.read_frame().now_or_never().unwrap().unwrap().unwrap().payload, Bytes::from_static(b"x") @@ -4126,4 +4109,30 @@ mod test { assert!(matches!(next.poll_next_frame(&waiter), Poll::Ready(Err(Error::Old)))); assert!(matches!(finished.poll_finished(&waiter), Poll::Ready(Err(Error::Old)))); } + + /// A publisher that read every frame of a finished group still learns when the budget + /// gives up on it, so it can abandon the stream it is still writing. + #[test] + fn a_fully_read_group_still_reports_its_expiry() { + let mut producer = Info { sequence: 0 }.produce(); + producer + .write_frame(crate::Timestamp::ZERO, Bytes::from_static(b"a")) + .unwrap(); + producer.finish().unwrap(); + + let expired = Arc::new(AtomicBool::new(false)); + let mut group = producer.consume().with_expiry(Arc::new(Switch(expired.clone()))); + let waiter = kio::Waiter::noop(); + assert!(matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); + assert!( + matches!(group.poll_read_frame(&waiter), Poll::Ready(Ok(None))), + "read whole" + ); + assert!(!group.poll_expired(&waiter)); + + expired.store(true, Ordering::Relaxed); + assert!(group.poll_expired(&waiter), "the writer abandons its stream"); + expired.store(false, Ordering::Relaxed); + assert!(group.poll_expired(&waiter), "and the verdict stands"); + } } diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 6d8fcd85ef8..cf10f331ab3 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -41,8 +41,6 @@ use requests::Requests; use weak_cache::{WeakCache, WeakEntry}; pub use bytes::*; -// pending: /quest/m1/public-model/serve.md -pub(crate) use subscription::Cap; // Datagram stays flat at the crate root (a small track-adjacent wire type), // not under a role module. pub use datagram::*; diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index f23b4d8f831..e7fde980e95 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -21,13 +21,14 @@ //! sequence its [`track::Subscriber`] already handed out, the same record that keeps a //! direct reader from taking a re-created group twice. +use std::ops::Bound; use std::sync::{Arc, Mutex, MutexGuard, PoisonError, Weak}; use std::task::{Poll, ready}; use crate::{Error, Result, StreamError, group, stats, track}; use super::delivered::Delivered; -use super::subscription::{Anchor, Cap, Position, Resolved, Subscription, Window}; +use super::subscription::{Anchor, Position, Resolved, Subscription, Window}; /// What the front says about a logical track: the copy to read now, and how it ended. #[derive(Default)] @@ -188,7 +189,7 @@ impl Consumer { newest: None, window, datagram: None, - groups: (floor, Cap::from(..)), + groups: (floor, None), groups_read: false, peeked: None, }) @@ -351,18 +352,26 @@ impl Copy { } /// The subscription, once the copy answered. `Err` once it refused. - fn poll_ready(&mut self, groups: (u64, Cap), waiter: &kio::Waiter) -> Poll> { + fn poll_ready(&mut self, groups: (u64, Option), waiter: &kio::Waiter) -> Poll> { if let Sub::Pending(pending) = &self.sub { - let mut sub = ready!(pending.poll_ok(waiter))?; + let sub = ready!(pending.poll_ok(waiter))?; // An anchor the wire kept may resolve below where the reader got to. - sub.raise_start_to(self.floor.map_or(groups.0, |floor| groups.0.max(floor.group))); - sub.end_at(groups.1); + let sub = sub.with_range(( + Bound::Included(self.start(groups.0)), + groups.1.map_or(Bound::Unbounded, Bound::Excluded), + )); self.sub = Sub::Ready(Box::new(sub)); } let Sub::Ready(sub) = &mut self.sub else { unreachable!() }; Poll::Ready(Ok(sub)) } + /// The local floor `start` as this copy applies it: never below its own resume point, + /// since groups under it were handed out by an earlier route, or never owed. + fn start(&self, start: u64) -> u64 { + self.floor.map_or(start, |floor| start.max(floor.group)) + } + /// Whether this copy is still needed: it serves, or a group read from or backed by it is /// still out. Even once its channel ran out, since a failure continues from what it holds. fn needed(&self, serving: bool) -> bool { @@ -483,21 +492,9 @@ impl Subscriber { } } - /// Raise the local read floor; see [`track::Subscriber::set_groups`]. - pub(super) fn raise_start_to(&mut self, start: u64) { - self.reader().raise_start_to(start) - } - - /// Move the local read floor to `start`, including downward. - /// See [`track::Subscriber::start_at`]. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - pub(super) fn start_at(&mut self, start: u64) { - self.reader().start_at(start) - } - - /// Cap local reads at `end`; see [`track::Subscriber::set_groups`]. - pub(super) fn end_at(&mut self, end: Cap) { - self.reader().end_at(end) + /// Assign the local read floor and exclusive cap; see [`track::Subscriber::with_range`]. + pub(super) fn set_range(&mut self, start: u64, end: Option) { + self.reader().set_range(start, end) } /// Whether any subscribed copy still has a group matching `unread`. @@ -528,10 +525,7 @@ impl Subscriber { /// The local group filter, as [`track::Subscriber::poll_largest`] reports within it. pub(super) fn bounds(&self) -> track::Bounds { let (start, end) = self.reader().groups; - track::Bounds { - start, - end: end.exclusive(), - } + track::Bounds { start, end } } /// The groups the copies' drift budget skipped since the last call, counted against @@ -585,8 +579,8 @@ struct Reader { window: Window, /// The newest datagram handed out, by Group and Object ID. datagram: Option<(u64, u64)>, - /// The local group filter; see [`track::Subscriber::set_groups`]. - groups: (u64, Cap), + /// The local floor and exclusive cap; see [`track::Subscriber::with_range`]. + groups: (u64, Option), /// Whether groups were read, so a datagram read keeps the copies they still need. groups_read: bool, } @@ -1127,37 +1121,15 @@ impl Reader { } } - fn raise_start_to(&mut self, start: u64) { + /// Assign the local floor and cap. A copy still waiting on its info takes them when it + /// resolves; one already reading has to be moved, or a group it skipped stays skipped. + fn set_range(&mut self, start: u64, end: Option) { self.peeked = None; - self.groups.0 = self.groups.0.max(start); + self.groups = (start, end); for copy in &mut self.copies { + let start = copy.start(start); if let Sub::Ready(sub) = &mut copy.sub { - sub.raise_start_to(start); - } - } - } - - /// Assign the local floor. A copy still waiting on its info takes the floor - /// from the mirrored subscription when it resolves; one already reading has - /// to be moved, or a group it skipped stays skipped. Never below a copy's own - /// resume point: groups under it were handed out by an earlier route, or never owed. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - fn start_at(&mut self, start: u64) { - self.peeked = None; - self.groups.0 = start; - for copy in &mut self.copies { - if let Sub::Ready(sub) = &mut copy.sub { - sub.start_at(copy.floor.map_or(start, |floor| start.max(floor.group))); - } - } - } - - fn end_at(&mut self, end: Cap) { - self.peeked = None; - self.groups.1 = end; - for copy in &mut self.copies { - if let Sub::Ready(sub) = &mut copy.sub { - sub.end_at(end); + sub.set_range((Bound::Included(start), end.map_or(Bound::Unbounded, Bound::Excluded))); } } } @@ -1325,9 +1297,9 @@ impl Recover { if copy.generation == self.generation { return None; } - let mut group = copy.track.peek_group(self.sequence)?; + let group = copy.track.peek_group(self.sequence)?; lend_head(&self.handoff, self.sequence, ©.track, &group); - group.start_at(index); + let group = group.with_range(index..); (group.index() == index).then(|| Replacement { group, generation: copy.generation, @@ -1348,9 +1320,9 @@ impl Recover { // A newer copy's subscription delivered it: continue from there. The copy that // failed delivered it already, so its subscription will not again. let same = generation == self.generation; - if !same && let Poll::Ready(Some(mut group)) = serving.poll_group(self.sequence, waiter) { + if !same && let Poll::Ready(Some(group)) = serving.poll_group(self.sequence, waiter) { lend_head(&self.handoff, self.sequence, serving, &group); - group.start_at(index); + let group = group.with_range(index..); if group.index() == index { return Poll::Ready(Ok(Replacement { group, @@ -1377,9 +1349,9 @@ impl Recover { Fetch::Refused(err) if route_failed(err) || copy_failed(serving) => return Poll::Pending, Fetch::Refused(err) => err.clone(), Fetch::Pending(pending) => match ready!(kio::Task::poll(&mut **pending, waiter)) { - Ok(mut group) => { + Ok(group) => { lend_head(&self.handoff, self.sequence, serving, &group); - group.start_at(index); + let group = group.with_range(index..); if group.index() == index { return Poll::Ready(Ok(Replacement { group, @@ -1952,9 +1924,9 @@ mod test { for sequence in 0..5 { write(&a, sequence); } - sub.set_groups(..3); + sub.set_range(..3); assert!(sub.largest().now_or_never().is_none(), "the largest is past the cap"); - sub.set_groups(..); + sub.set_range(..); assert_eq!(sub.largest().now_or_never(), Some(Some(Position::group(4)))); } @@ -1967,7 +1939,7 @@ mod test { let logical = logical(&routes); let a = copy(); routes.serve(a.consume()); - let subscription = Subscription::default().with_max_delay(HOUR).with_groups(8..); + let subscription = Subscription::default().with_max_delay(HOUR).with_range(8..); let mut sub = logical .consume() .subscribe(subscription) @@ -2053,6 +2025,27 @@ mod test { } } + /// Lowering a front reader's local floor offers the cached groups below the old one it + /// passed over, as a plain reader does. + #[test] + fn a_lowered_range_reoffers_the_unread_cached_groups() { + let routes = Producer::new(); + let logical = logical(&routes); + let a = copy(); + routes.serve(a.consume()); + let mut sub = subscribe(&logical, HOUR).with_range(4..); + for sequence in 0..6 { + write(&a, sequence); + } + assert_eq!(drain(&mut sub, false), vec![4, 5]); + + let mut sub = sub.with_range(1..); + assert_eq!(drain(&mut sub, false), vec![1, 2, 3], "passed below the floor"); + let mut sub = sub.with_range(..); + assert_eq!(drain(&mut sub, false), vec![0]); + assert_eq!(drain(&mut sub, false), Vec::::new(), "nothing goes out twice"); + } + /// A replaced copy is bounded only once the new copy delivers its first group: a group /// buffered on it must be read before a later group on the serving copy. #[test] @@ -2423,7 +2416,7 @@ mod test { let a = copy(); routes.serve(a.consume()); let mut sub = subscribe(&logical, HOUR); - sub.end_at(Cap::from(..=0)); + sub.set_range(..=0); let mut held = a.create_group(group::Info { sequence: 0 }).unwrap(); held.write_frame(ts(0), b"a".as_ref()).unwrap(); let Poll::Ready(Ok(Some(reading))) = sub.poll_recv_group(&kio::Waiter::noop()) else { @@ -2441,11 +2434,11 @@ mod test { } assert_eq!(drain(&mut sub, false), Vec::::new()); - sub.end_at(Cap::from(..)); + sub.set_range(..); let mut seen = drain(&mut sub, false); seen.sort_unstable(); assert_eq!(seen, [1, 2, 3]); - sub.start_at(0); + sub.set_range(..); assert_eq!(drain(&mut sub, false), Vec::::new()); // The replaced copy finishes with the held group. @@ -2520,7 +2513,7 @@ mod test { group.finish().unwrap(); } - sub.start_at(0); + sub.set_range(..); assert_eq!(recv(&mut sub).sequence, 6); } @@ -2591,7 +2584,7 @@ mod test { assert!(matches!(copy.sub, Sub::Pending(_))); copy.update(&updated); assert_eq!(copy.wire(&updated).ranges, ranges); - assert!(copy.poll_ready((0, Cap::from(..)), &kio::Waiter::noop()).is_ready()); + assert!(copy.poll_ready((0, None), &kio::Waiter::noop()).is_ready()); assert_eq!(copy.wire(&updated).ranges, ranges); } @@ -3640,9 +3633,9 @@ mod test { routes.serve(b.consume()); assert!(sub.recv_datagram().now_or_never().is_none()); if raise_floor { - sub.set_groups(1..); + sub.set_range(1..); } else { - sub.set_groups(..0); + sub.set_range(..0); } assert!( if ordered { @@ -3653,7 +3646,7 @@ mod test { .is_pending() ); if !raise_floor { - sub.set_groups(..); + sub.set_range(..); let next = if ordered { sub.poll_next_group(&kio::Waiter::noop()) } else { diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 81f53a38461..60d8be2bc17 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -1,5 +1,5 @@ use std::{ - ops::{Bound, RangeBounds, RangeFull, RangeTo, RangeToInclusive}, + ops::{Bound, RangeBounds}, time::Duration, }; @@ -75,7 +75,7 @@ pub struct Subscription { /// A request to the publisher, aggregated across every live subscriber as the union of /// their ranges, and this subscriber's read filter: it reads only the groups its own /// ranges cover, whatever another subscriber widens the union to. - /// [`crate::track::Subscriber::set_groups`] narrows the reads further. See [Local cursor + /// [`crate::track::Subscriber::with_range`] narrows the reads further. See [Local cursor /// vs wire preference](crate::track::Subscriber#local-cursor-vs-wire-preference). pub ranges: Vec, /// Which pending group the publisher sends first; see [`Order`]. @@ -273,7 +273,7 @@ impl Subscription { /// Request the whole groups in `groups` as the only range; see [`Range::groups`]. /// Returns `self` for chaining. - pub fn with_groups(self, groups: impl RangeBounds) -> Self { + pub fn with_range(self, groups: impl RangeBounds) -> Self { self.with_ranges([Range::groups(groups)]) } @@ -287,8 +287,7 @@ impl Subscription { /// from the latest group (or none is asked for). /// /// The form a wire without ranges carries: a floor below which nothing is requested. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn start(&self) -> Option { + pub fn start(&self) -> Option { let mut floor: Option = None; for range in &self.ranges { let Anchor::Absolute(start) = range.start else { @@ -303,9 +302,7 @@ impl Subscription { /// the latest group. An empty list is the empty range, `Position::group(0)`. /// /// The form a wire without ranges carries, alongside [`Self::start`]. - #[cfg(any(feature = "async", test))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn end(&self) -> Option { + pub fn end(&self) -> Option { let mut end = Some(Position::default()); for range in &self.ranges { let Some(Anchor::Absolute(next)) = range.end else { @@ -316,31 +313,25 @@ impl Subscription { end } - /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) to `end`: the form - /// a wire without ranges carries. - #[cfg(any(feature = "async", test))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn set_bounds(&mut self, start: Option, end: Option) { - self.ranges = vec![Range { - start: start.map_or(Range::oldest().start, Anchor::Absolute), - end: end.map(Anchor::Absolute), - }]; + /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) up to [`Self::end`], + /// returning `self` for chaining: the form a wire without ranges carries. + pub fn with_start(self, start: impl Into>) -> Self { + let end = self.end(); + self.with_span(start.into(), end) } - /// Replace the start of [`Self::set_bounds`]'s one range, keeping its end. - #[cfg(feature = "async")] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn with_start(mut self, start: impl Into>) -> Self { - self.set_bounds(start.into(), self.end()); - self + /// Replace the ranges with one from [`Self::start`] up to the exclusive `end`, or onward + /// for `None`, returning `self` for chaining: the form a wire without ranges carries. + pub fn with_end(self, end: impl Into>) -> Self { + let start = self.start(); + self.with_span(start, end.into()) } - /// Replace the end of [`Self::set_bounds`]'s one range, keeping its start. - #[cfg(any(feature = "async", test))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn with_end(mut self, end: impl Into>) -> Self { - self.set_bounds(self.start(), end.into()); - self + fn with_span(self, start: Option, end: Option) -> Self { + self.with_ranges([Range { + start: start.map_or(Range::oldest().start, Anchor::Absolute), + end: end.map(Anchor::Absolute), + }]) } /// These preferences with every range raised to start no earlier than `floor` and @@ -476,7 +467,7 @@ impl Position { } /// The bound this exclusive end puts on a group cursor, for - /// [`crate::track::Subscriber::set_groups`]. + /// [`crate::track::Subscriber::with_range`]. /// /// A head-of-group end excludes its group. A mid-group end includes it, so a frame /// cap can apply within that group. @@ -488,56 +479,21 @@ impl Position { } } - /// The first group this exclusive end excludes whole, `None` past the last group. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn final_sequence(self) -> Option { + /// The first group this exclusive end excludes whole, `None` past the last group: the + /// boundary a wire that cannot name a frame carries as the track's end. + pub fn final_sequence(self) -> Option { self.group.checked_add(u64::from(self.frame != 0)) } } -/// Where a read cursor stops: a group sequence or frame index it will not deliver. -/// -/// Built from a range so the call site says whether its bound is delivered: `..5` stops -/// before 5, `..=5` reads through it, and `..` removes the cap. A [`Bound`] converts -/// too, for callers holding one (a decoded wire field, or [`Position::group_end`]). -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -// pending: /quest/m1/public-model/serve.md -pub(crate) struct Cap(Option); - -impl Cap { - /// The first index withheld, or `None` for no cap. Cursors store this form and - /// compare with [`before_end`]. An inclusive bound at `u64::MAX` has nothing above - /// it, so it is no cap at all. - pub(super) fn exclusive(self) -> Option { - self.0 - } -} - -impl From> for Cap { - fn from(bound: Bound) -> Self { - Self(match bound { - Bound::Included(index) => index.checked_add(1), - Bound::Excluded(index) => Some(index), - Bound::Unbounded => None, - }) - } -} - -impl From> for Cap { - fn from(range: RangeTo) -> Self { - Self(Some(range.end)) - } -} - -impl From> for Cap { - fn from(range: RangeToInclusive) -> Self { - Bound::Included(range.end).into() - } -} - -impl From for Cap { - fn from(_: RangeFull) -> Self { - Self(None) +/// The first index an end bound withholds, or `None` for no cap: the form cursors store +/// and compare with [`before_end`]. An inclusive bound at `u64::MAX` has nothing above it, +/// so it is no cap at all. +fn exclusive_end(bound: Bound<&u64>) -> Option { + match bound { + Bound::Included(index) => index.checked_add(1), + Bound::Excluded(&index) => Some(index), + Bound::Unbounded => None, } } @@ -551,7 +507,7 @@ pub(super) fn sequence_bounds(range: impl RangeBounds) -> (u64, Option }, Bound::Unbounded => 0, }; - (start, Cap::from(range.end_bound().cloned()).exclusive()) + (start, exclusive_end(range.end_bound())) } /// Whether `sequence` is strictly below an exclusive cap. `None` is unbounded. @@ -595,7 +551,7 @@ mod tests { // Through the last group is unbounded, as `after_group` spells it. assert_eq!(Range::groups(..=u64::MAX).end, None); - let sub = Subscription::default().with_groups(2..=5).with_groups(..); + let sub = Subscription::default().with_range(2..=5).with_range(..); assert_eq!(sub, Subscription::default()); } @@ -617,12 +573,14 @@ mod tests { // A cursor cap is the first index it withholds; an inclusive bound at the last // index withholds nothing. - assert_eq!(Cap::from(..0).exclusive(), Some(0)); - assert_eq!(Cap::from(..=5).exclusive(), Some(6)); - assert_eq!(Cap::from(..=u64::MAX).exclusive(), None); - assert_eq!(Cap::from(..).exclusive(), None); - assert_eq!(Cap::from(Bound::Included(5)), Cap::from(..6)); - assert_eq!(Cap::from(Bound::Unbounded), Cap::from(..)); + assert_eq!(sequence_bounds(..0), (0, Some(0))); + assert_eq!(sequence_bounds(..=5), (0, Some(6))); + assert_eq!(sequence_bounds(..=u64::MAX), (0, None)); + assert_eq!(sequence_bounds(..), (0, None)); + assert_eq!( + sequence_bounds((Bound::Unbounded, Bound::Included(5))), + sequence_bounds(..6) + ); } /// A relative start counts back from the latest group and clamps at group 0. Before any @@ -667,7 +625,7 @@ mod tests { ); // An explicit group 0 is a floor, unlike the default. - let sub = Subscription::default().with_groups(0..); + let sub = Subscription::default().with_range(0..); assert_eq!((sub.start(), sub.end()), (Some(Position::group(0)), None)); let sub = Subscription::default().with_ranges([Range::groups(2..4), Range::live()]); @@ -680,14 +638,14 @@ mod tests { let sub = Subscription::default().with_ranges([]); assert_eq!(sub.end(), Some(Position::group(0))); - let mut sub = Subscription::default(); - sub.set_bounds(Some(Position { group: 5, frame: 2 }), Position::after_group(9)); + let sub = Subscription::default() + .with_start(Position { group: 5, frame: 2 }) + .with_end(Position::after_group(9)); assert_eq!( (sub.start(), sub.end()), (Some(Position { group: 5, frame: 2 }), Some(Position::group(10))) ); - sub.set_bounds(None, None); - assert_eq!(sub, Subscription::default()); + assert_eq!(sub.with_start(None).with_end(None), Subscription::default()); } /// The aggregate is the union: overlapping and adjacent absolute ranges merge, an open diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 5a7d2f66c1b..b809c0d245d 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -20,7 +20,6 @@ use super::delivered::Delivered; use super::ledger::{self, Ledger}; use super::{Datagram, Requests}; -use super::Cap; pub use super::subscription::{Anchor, Order, Position, Range, Subscription}; use super::subscription::{Resolved, Window}; use rangemap::{RangeInclusiveSet, RangeSet}; @@ -976,7 +975,7 @@ impl TrackState { /// would make walking a backlog of N groups off in one poll cost O(N^2). /// /// Bounded because a group can only be late relative to data that would actually be - /// served in its place: a reader capped by [`Subscriber::set_groups`] can't jump past + /// served in its place: a reader capped by [`Subscriber::with_range`] can't jump past /// the cap, and one reading disjoint ranges never reads the gap between them, so the /// groups it still wants aren't stale just because the track ran on. /// Fetched backfill is absent from `arrival`, so it cannot age subscription content @@ -2855,7 +2854,7 @@ impl Producer { } #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md pub(crate) fn latest_sequence(&self) -> Option { self.state.read().max_sequence } @@ -4160,7 +4159,7 @@ impl Consumer { kio::wait(|waiter| self.poll_largest(waiter)).await } - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md pub(crate) fn latest_sequence(&self) -> Option { if let Some(serving) = self.serving() { return serving.latest_sequence(); @@ -4170,7 +4169,7 @@ impl Consumer { /// The first group the declared end excludes whole, or `None` while the track is open ended. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/public-model/deferred.md pub(crate) fn final_sequence(&self) -> Option { if let Some(serving) = self.serving() { return serving.final_sequence(); @@ -4592,9 +4591,11 @@ impl kio::Task for Fetching { sequence, max_delay: self.max_delay, }); - let resolve = |mut group: group::Consumer| { - group.start_at(frame_start); - group.with_meter(self.stats.meter()).with_expiry(expiry.clone()) + let resolve = |group: group::Consumer| { + group + .with_range(frame_start..) + .with_meter(self.stats.meter()) + .with_expiry(expiry.clone()) }; if let Some(group) = &self.hit { return Poll::Ready(Ok(resolve((**group).clone()))); @@ -4681,7 +4682,7 @@ impl kio::Task for Fetching { /// every live subscriber, but each subscriber reads only the groups its own ranges cover, /// resolved where it is served: a relative anchor counted back from the latest group (or /// the first to arrive, before any exists), again whenever the ranges are replaced. -/// - [`Self::set_groups`] narrows **this subscriber's reads** further, without changing the +/// - [`Self::with_range`] narrows **this subscriber's reads** further, without changing the /// publisher's demand. /// /// A group outside either is held rather than skipped past, so widening either one later @@ -4954,7 +4955,7 @@ struct Cursor { index: usize, /// Arrival-order cursor used by `recv_datagram`, independent of groups. datagram_index: usize, - /// Minimum sequence to return from any `recv` method. Set by `start_at`. + /// Minimum sequence to return from any `recv` method. Set by `set_range`. min_sequence: u64, /// This subscriber's own ranges, resolved. Boxed: every reader embeds a cursor. filter: Box, @@ -4965,8 +4966,8 @@ struct Cursor { /// The exact candidate a route-copy selection inspected, including its arrival /// position. Consuming it must not look up a different group after eviction. peeked: Option>, - /// Exclusive upper sequence bound for `next_group` and `recv_group`, in the form - /// [`Cap::exclusive`] produces. `None` means no cap. Set by `end_at`; + /// Exclusive upper sequence bound for `next_group` and `recv_group`. `None` means no + /// cap. Set by `set_range`; /// can be raised, lowered, or unset at any time. Groups at or past the cap stay in /// the producer's cache and become eligible again when the cap rises (or is removed). /// `Some(0)` is the empty range. @@ -5665,7 +5666,7 @@ impl Cursor { /// the entry waits in [`Self::seek_pending`], where a delivered group removes itself /// (see [`Self::poll_next_group`]). `committed` must be the sequence watermark (one /// past the last delivery), which only rises. The seek's floor is NOT that: it - /// includes `start_at`, which can be lowered again, and a conviction it flushed could + /// includes the local floor, which can be lowered again, and a conviction it flushed could /// then be delivered after all. fn commit_seek_stale(&mut self, committed: u64) { let keep = self.seek_pending.split_off(&committed); @@ -5811,7 +5812,7 @@ impl Subscriber { /// 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 [`Duration::ZERO`], which takes the live - /// edge and writes the rest off; raise it to read history. [`Self::set_groups`] and + /// edge and writes the rest off; raise it to read history. [`Self::with_range`] and /// [`Subscription::ranges`] are filters, not exemptions: backfill needs a budget that /// covers it. [`Consumer::fetch_group`] is the way to ask for one old group outright. /// Across same-epoch route copies, the lowest next buffered group is delivered @@ -5819,7 +5820,7 @@ impl Subscriber { /// 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 group range set by [`Self::set_groups`]: a group beyond the cap is + /// Honors the group range set by [`Self::with_range`]: a group beyond the cap is /// passed without blocking in-range groups that arrive behind it, and holds nothing /// here. Raising the cap, or widening the ranges, offers the groups it newly covers /// that the cache still holds, lowest sequence first. Once the track finishes, a @@ -5960,7 +5961,7 @@ impl Subscriber { /// Every group sequence is returned at most once, in the order it landed on the wire, which may /// be out of sequence due to network reordering or loss. Use [`Self::ordered`] if you /// only want groups whose sequence number is higher than any previously returned. - /// See [`Self::poll_recv_group`] for how [`Self::set_groups`] applies. + /// See [`Self::poll_recv_group`] for how [`Self::with_range`] applies. #[cfg(feature = "async")] pub async fn recv_group(&mut self) -> Result> { kio::wait(|waiter| self.poll_recv_group(waiter)).await @@ -6051,11 +6052,9 @@ impl Subscriber { } /// Poll for where the source's feed starts, raised to this cursor's floor, once - /// resolved; see [`Subscriber::poll_start`]. A feed starting below the floor serves the - /// floor's group too. `None` when the source declares none. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn poll_start(&mut self, waiter: &kio::Waiter) -> Poll> { + /// resolved: the first group a publisher tells its peer it serves. A feed starting + /// below the floor serves the floor's group too. `None` when the source declares none. + pub fn poll_start(&mut self, waiter: &kio::Waiter) -> Poll> { let cursor = match &mut self.inner { Inner::Plain(cursor) => cursor, Inner::Resume(resume, _) => return resume.poll_start(waiter), @@ -6112,13 +6111,12 @@ impl Subscriber { } } - /// Poll for sequences this subscription gave up without serving. + /// Poll for a run of sequences this subscription gave up without serving, so a + /// publisher can tell its peer not to wait for them. /// - /// Stale skips are recorded only once this has been polled, so a cursor no wire - /// publisher forwards drops for keeps none. - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn poll_drop(&mut self, waiter: &kio::Waiter) -> Poll> { + /// Stale skips are recorded only once this has been polled, so a reader that never + /// forwards drops keeps none. + pub fn poll_drop(&mut self, waiter: &kio::Waiter) -> Poll> { match &mut self.inner { Inner::Plain(cursor) => cursor.poll_drop(waiter), Inner::Resume(resume, _) => resume.poll_drop(waiter), @@ -6129,7 +6127,7 @@ impl Subscriber { /// largest position it holds; `None` for a track with nothing yet. A front's logical /// track answers for the route serving it. See [`Producer::set_idle`]. #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md pub(crate) fn poll_live(&mut self, waiter: &kio::Waiter) -> Poll> { let cursor = match &mut self.inner { Inner::Plain(cursor) => cursor, @@ -6167,77 +6165,37 @@ impl Subscriber { kio::wait(|waiter| self.poll_finished(waiter)).await } - /// Limit subsequent reads to these group sequences without rewinding read progress. + /// Limit subsequent reads to these group sequences, returning `self` for chaining. /// - /// `2..=5` includes groups 2 through 5; `2..5` excludes group 5. An omitted - /// start preserves the current floor, and an omitted end removes the cap. - /// Groups above the end stay cached and can be read after raising the cap. - /// [`Self::poll_largest`] reports within these bounds. - /// This narrows only local delivery, within [`Subscription::ranges`]; use those and - /// [`Self::update`] to change the requested groups. - pub fn set_groups(&mut self, groups: impl RangeBounds) { - let (start, end) = super::subscription::sequence_bounds(groups); - self.raise_start_to(start); - self.end_at(end.map_or(Bound::Unbounded, Bound::Excluded)); - } - - /// Start this subscriber's read cursor at the given sequence. + /// `2..=5` includes groups 2 through 5; `2..5` excludes group 5, and `..0` is the + /// empty range. Both bounds are assigned, in either direction: an omitted start is + /// group 0 and an omitted end removes the cap. Lowering the floor or raising the cap + /// offers the groups it newly covers that the cache still holds and this reader never + /// handed out, lowest first; a group is never handed out twice. Groups past the cap + /// stay cached, and lowering the cap below the cursor waits until it rises again or + /// the track finishes. [`Self::poll_largest`] reports within these bounds. /// - /// A local filter, not a request: it doesn't tell the publisher anything, so the - /// skipped groups are still delivered and simply not returned. To ask the publisher - /// to start there too, set [`Subscription::ranges`] via [`Self::update`]. - /// See [Local cursor vs wire preference](Self#local-cursor-vs-wire-preference). - #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md - pub(crate) fn start_at(&mut self, sequence: u64) { - match &mut self.inner { - Inner::Plain(cursor) => { - cursor.peeked = None; - cursor.min_sequence = sequence; - } - // Assigns, including downward. A front serves every viewer of a path, - // and a later SUBSCRIBE_UPDATE can widen the floor; raising only would - // leave a finished group below the old floor unread. - Inner::Resume(resume, _) => resume.start_at(sequence), - } - self.largest.bounds_moved(); - } - - /// Raise the read cursor's floor to `sequence`, keeping any higher floor already set. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn raise_start_to(&mut self, sequence: u64) { - match &mut self.inner { - Inner::Plain(cursor) => { - cursor.peeked = None; - cursor.min_sequence = cursor.min_sequence.max(sequence); - } - Inner::Resume(resume, _) => resume.raise_start_to(sequence), - } - self.largest.bounds_moved(); + /// A local filter, not a request: it tells the publisher nothing, so groups outside it + /// are still delivered and simply not returned. To change what is requested, set + /// [`Subscription::ranges`] via [`Self::update`]. See [Local cursor vs wire + /// preference](Self#local-cursor-vs-wire-preference). + pub fn with_range(mut self, groups: impl RangeBounds) -> Self { + self.set_range(groups); + self } - /// Cap this subscriber's read cursor at `end`, or remove the cap with `..`. - /// - /// The range says whether its sequence is delivered: `..=5` serves through group 5, - /// `..5` stops before it. `..0` is the empty range: no group is delivered. - /// [`Position::group_end`] translates a range's absolute end. - /// - /// A local filter, not a request; [`Subscription::ranges`] are the wire-level - /// counterpart. See [Local cursor vs wire preference](Self#local-cursor-vs-wire-preference). - /// - /// Groups beyond the cap stay in the cache, so a later call to [`Self::set_groups`] - /// with a higher bound (or unbounded) offers the ones still cached. Lowering the cap - /// below the consumer's current cursor waits until the cap is raised, or the track - /// finishes. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn end_at(&mut self, end: impl Into) { + /// [`Self::with_range`] on a reader held in place. + // private: tuning + pub(crate) fn set_range(&mut self, groups: impl RangeBounds) { + let (start, end) = super::subscription::sequence_bounds(groups); match &mut self.inner { Inner::Plain(cursor) => { cursor.peeked = None; - cursor.end_sequence = end.into().exclusive(); + cursor.min_sequence = start; + cursor.end_sequence = end; cursor.update_servable(); } - Inner::Resume(resume, _) => resume.end_at(end.into()), + Inner::Resume(resume, _) => resume.set_range(start, end), } self.largest.bounds_moved(); } @@ -6279,7 +6237,7 @@ impl Subscriber { Ok(()) } - /// Poll for the track's largest location within [`Self::set_groups`]: the current one, then each newer one, and `None` once the track ends. + /// Poll for the track's largest location within [`Self::with_range`]: the current one, then each newer one, and `None` once the track ends. /// /// The largest is the newest group or datagram at the newest frame (0 while empty), as /// the source reported it and its live feed delivered since, so nothing reports until @@ -6323,13 +6281,13 @@ impl Subscriber { } } - /// The largest location within [`Self::set_groups`]; see [`Self::poll_largest`]. + /// The largest location within [`Self::with_range`]; see [`Self::poll_largest`]. #[cfg(feature = "async")] pub async fn largest(&mut self) -> Option { kio::wait(|waiter| self.poll_largest(waiter)).await } - /// The track's largest location known now, ignoring [`Self::set_groups`], without waiting + /// The track's largest location known now, ignoring [`Self::with_range`], without waiting /// or moving [`Self::poll_largest`] on: past what the cache holds once the source /// reported a newer one. #[cfg_attr(not(feature = "async"), allow(dead_code))] @@ -6346,7 +6304,7 @@ impl Subscriber { } #[cfg_attr(not(feature = "async"), allow(dead_code))] - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md pub(crate) fn latest_sequence(&self) -> Option { match &self.inner { Inner::Plain(cursor) => cursor.state.read().max_sequence, @@ -6420,7 +6378,7 @@ impl Ordered { /// Poll for the next group with a higher sequence number than any previously /// returned, without blocking. /// - /// Honors the group range set by [`Self::set_groups`]: + /// Honors the group range set by [`Self::with_range`]: /// a group past the cap stays in the producer's cache and becomes eligible again if /// the cap rises or is removed. /// @@ -6461,11 +6419,18 @@ impl Ordered { kio::wait(|waiter| self.poll_recv_datagram(waiter)).await } - /// Limit subsequent reads to these group sequences without rewinding read progress. + /// Limit subsequent reads to these group sequences, returning `self` for chaining. /// - /// See [`Subscriber::set_groups`] for inclusive, exclusive, and omitted bounds. - pub fn set_groups(&mut self, groups: impl RangeBounds) { - self.inner.set_groups(groups); + /// See [`Subscriber::with_range`] for how the bounds apply. An ordered read never goes + /// back, so lowering the floor below a group it already returned offers nothing. + pub fn with_range(mut self, groups: impl RangeBounds) -> Self { + self.set_range(groups); + self + } + + /// [`Self::with_range`] on a reader held in place. + fn set_range(&mut self, groups: impl RangeBounds) { + self.inner.set_range(groups); } /// Create a handle for updating this subscriber's delivery preferences without @@ -6500,12 +6465,12 @@ impl Ordered { kio::wait(|waiter| self.poll_finished(waiter)).await } - /// Poll for the largest location within [`Self::set_groups`]; see [`Subscriber::poll_largest`]. + /// Poll for the largest location within [`Self::with_range`]; see [`Subscriber::poll_largest`]. pub fn poll_largest(&mut self, waiter: &kio::Waiter) -> Poll> { self.inner.poll_largest(waiter) } - /// The largest location within [`Self::set_groups`]; see [`Subscriber::poll_largest`]. + /// The largest location within [`Self::with_range`]; see [`Subscriber::poll_largest`]. #[cfg(feature = "async")] pub async fn largest(&mut self) -> Option { kio::wait(|waiter| self.poll_largest(waiter)).await @@ -7005,7 +6970,7 @@ mod test { panic!("the empty group is the largest"); }; assert_eq!(edge, Position::group(1)); - reader.set_groups(edge.group..); + reader.set_range(edge.group..); empty.finish().unwrap(); let mut next = producer.append_group().unwrap(); @@ -7128,19 +7093,19 @@ mod test { let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 2)).collect(); let mut capped = producer.subscribe(replay()); - capped.set_groups(..3); + capped.set_range(..3); assert!(capped.poll_largest(&noop).is_pending(), "the largest is past the cap"); // An inclusive cap reports the group it names. let mut ordered = producer.subscribe(replay()).ordered(); - ordered.set_groups(..=5); + ordered.set_range(..=5); assert_eq!( ordered.poll_largest(&noop), Poll::Ready(Some(Position { group: 5, frame: 1 })) ); let mut floored = producer.subscribe(replay()); - floored.set_groups(8..); + floored.set_range(8..); assert!( floored.poll_largest(&noop).is_pending(), "the largest is below the floor" @@ -7158,27 +7123,27 @@ mod test { let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 1)).collect(); let mut reader = producer.subscribe(replay()).ordered(); - reader.set_groups(..3); + reader.set_range(..3); let (flag, waiter) = Flag::waiter(); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..); + reader.set_range(..); assert!(flag.take(), "lifting the cap woke the reader"); assert_eq!(reader.poll_largest(&noop), Poll::Ready(Some(Position::group(5)))); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..2); + reader.set_range(..2); assert!(flag.take(), "lowering the cap woke the reader"); assert!( reader.poll_largest(&noop).is_pending(), "the largest is past the new cap" ); - reader.set_groups(..); + reader.set_range(..); assert!( reader.poll_largest(&noop).is_pending(), "lifting it again leaves the last report standing" ); - reader.set_groups(3..); + reader.set_range(3..); assert!( reader.poll_largest(&noop).is_pending(), "a floor below the largest leaves it where it was" @@ -7195,9 +7160,9 @@ mod test { let noop = kio::Waiter::noop(); let mut reader = producer.subscribe(replay()); - reader.set_groups(..3); + reader.set_range(..3); assert_eq!(reader.poll_largest(&noop), Poll::Ready(None)); - reader.set_groups(..); + reader.set_range(..); assert_eq!( reader.poll_largest(&noop), Poll::Ready(None), @@ -7213,7 +7178,7 @@ mod test { let (flag, waiter) = Flag::waiter(); assert!(reader.poll_largest(&waiter).is_pending()); drop(waiter); - reader.set_groups(..); + reader.set_range(..); assert!(!flag.take(), "the dropped poll was not woken"); } @@ -7225,11 +7190,11 @@ mod test { let mut reader = producer.subscribe(replay()); let (flag, waiter) = Flag::waiter(); assert_eq!(reader.poll_largest(&waiter), Poll::Ready(Some(Position::group(0)))); - reader.set_groups(..); + reader.set_range(..); assert!(!flag.take(), "the finished poll was not woken"); assert!(reader.poll_largest(&waiter).is_pending()); - reader.set_groups(..); + reader.set_range(..); assert!(flag.take(), "the parked poll was woken"); } @@ -7244,7 +7209,7 @@ mod test { let mut reader = producer.subscribe(replay()); assert_eq!(reader.poll_largest(&noop), Poll::Ready(Some(Position::group(2)))); producer.set_idle(); - reader.set_groups(..); + reader.set_range(..); assert!(reader.poll_largest(&noop).is_pending(), "the copy is idle"); producer.set_live(Some(Position::group(2))); @@ -7500,7 +7465,7 @@ mod test { .unwrap(); drop(group); - let mut reader = producer.subscribe(Subscription::default().with_groups(0..)); + let mut reader = producer.subscribe(Subscription::default().with_range(0..)); assert!(reader.poll_recv_group(&kio::Waiter::noop()).is_pending()); let mut replacement = producer .create_group(group::Info { sequence: 3 }) @@ -7788,7 +7753,7 @@ mod test { fn the_group_range_bounds_datagrams() { let mut producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(Subscription::default().with_start(Position::group(5))); - subscriber.set_groups(..7); + subscriber.set_range(..7); for sequence in [4, 5, 7, 6] { producer .insert_datagram(sequence, Timestamp::ZERO, bytes::Bytes::from_static(b"x")) @@ -7832,12 +7797,12 @@ mod test { .unwrap(); } - subscriber.set_groups(2..4); + subscriber.set_range(2..4); assert_eq!(recv_datagram(&mut subscriber).sequence, 2); assert_eq!(recv_datagram(&mut subscriber).sequence, 3); assert!(subscriber.poll_recv_datagram(&kio::Waiter::noop()).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); assert!(subscriber.poll_recv_datagram(&kio::Waiter::noop()).is_pending()); producer .insert_datagram(5, Timestamp::ZERO, bytes::Bytes::from_static(b"x")) @@ -8124,7 +8089,7 @@ mod test { async fn parked_reoffer_restarts_the_expiry_clock() { let producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(None); - subscriber.set_groups(..1); + subscriber.set_range(..1); for seq in 0..2u64 { let mut group = producer.create_group(seq.into()).unwrap(); @@ -8138,7 +8103,7 @@ mod test { // Just inside the window, the cap rises and the re-offer stamps group 1. elapse(&producer, cache::DEFAULT_EXPIRY - Duration::from_secs(1)); - subscriber.set_groups(..2); + subscriber.set_range(..2); let mut reading = subscriber.assert_group(); assert_eq!(reading.sequence, 1); @@ -9752,7 +9717,7 @@ mod test { // 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); + subscriber.set_range(0..); assert_eq!(drain(&mut subscriber), vec![3]); let mut patient = producer.subscribe( @@ -9760,7 +9725,7 @@ mod test { .with_start(Position::group(0)) .with_max_delay(Duration::from_secs(10)), ); - patient.start_at(0); + patient.set_range(0..); assert_eq!(drain(&mut patient), vec![0, 1, 2, 3]); } @@ -9917,7 +9882,7 @@ mod test { } let mut subscriber = producer.subscribe(Subscription::default().with_end(Position::group(3))); - subscriber.end_at(Position::group(3).group_end()); + subscriber.set_range((Bound::Unbounded, Position::group(3).group_end())); assert_eq!(drain(&mut subscriber), vec![2]); } @@ -10293,9 +10258,9 @@ mod test { // Drift is measured under where the range ends, so with no budget its own newest // group is still fresh: the groups past it are not ones it reads. - let mut subscriber = producer.subscribe(Subscription::default().with_groups(0..2)); + let mut subscriber = producer.subscribe(Subscription::default().with_range(0..2)); assert_eq!(drain(&mut subscriber), vec![1]); - let mut subscriber = producer.subscribe(Subscription::default().with_groups(0..2)).ordered(); + let mut subscriber = producer.subscribe(Subscription::default().with_range(0..2)).ordered(); let next = subscriber.next_group().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(next.sequence, 1); @@ -10344,7 +10309,7 @@ mod test { let mut held = subscriber.recv_group().await.unwrap().expect("group 0"); assert!(held.read_frame().await.unwrap().is_some()); - subscriber.update(budget.with_groups(10..20)).unwrap(); + subscriber.update(budget.with_range(10..20)).unwrap(); for (sequence, millis) in [(1, 1000), (10, 10_000), (19, 19_000)] { let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.write_frame(at(millis), bytes::Bytes::from_static(b"x")).unwrap(); @@ -10405,7 +10370,7 @@ mod test { let current = cursor.published.read(); (current.servable.clone(), current.cap) }; - let ranges = Subscription::default().with_groups(10..20); + let ranges = Subscription::default().with_range(10..20); // Nothing in 10..20 sits below a cap at 5. let expected = (Servable::new(RangeInclusiveSet::new()), Some(5)); for order in ["ranges first", "cap first", "cap between"] { @@ -10415,15 +10380,15 @@ mod test { match order { "ranges first" => { control.update(ranges.clone()).unwrap(); - subscriber.set_groups(..5); + subscriber.set_range(..5); } "cap first" => { - subscriber.set_groups(..5); + subscriber.set_range(..5); control.update(ranges.clone()).unwrap(); } _ => { control.subscription.update(ranges.clone()).unwrap(); - subscriber.set_groups(..5); + subscriber.set_range(..5); control.republish.as_ref().unwrap().publish(&control.subscription); } } @@ -10448,7 +10413,7 @@ mod test { let mut held = subscriber.recv_group().await.unwrap().expect("group 0"); assert!(held.read_frame().await.unwrap().is_some()); - subscriber.control().update(budget.with_groups(10..20)).unwrap(); + subscriber.control().update(budget.with_range(10..20)).unwrap(); for (sequence, millis) in [(1, 1000), (10, 10_000), (19, 19_000)] { let mut group = producer.create_group(group::Info { sequence }).unwrap(); group.write_frame(at(millis), bytes::Bytes::from_static(b"x")).unwrap(); @@ -10471,12 +10436,12 @@ mod test { // 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. let mut subscriber = producer.subscribe(Subscription::default()); - subscriber.set_groups(..1); + subscriber.set_range(..1); 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.set_groups(..); + subscriber.set_range(..); assert_eq!(drain(&mut subscriber), vec![1]); } @@ -10897,7 +10862,7 @@ mod test { pool.sweep(); assert!(consumer.peek_group(5).is_none(), "payload cache expired"); let mut sub = consumer.subscribe(replay()).now_or_never().unwrap().unwrap(); - sub.end_at(Bound::Excluded(5)); + sub.set_range(..5); assert_eq!( sub.poll_finished(&kio::Waiter::noop()).map(|result| result.unwrap()), Poll::Ready(end) @@ -11506,7 +11471,7 @@ mod test { producer.finish_at(Position::group(2)).unwrap(); producer.abort(Error::Timeout).unwrap(); - consumer.set_groups(..1); + consumer.set_range(..1); assert_eq!(drain_ordered(&mut consumer), [0]); let end = consumer .next_group() @@ -11530,7 +11495,7 @@ mod test { producer.finish_at(Position::group(3)).unwrap(); producer.abort(Error::Timeout).unwrap(); - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!(drain_ordered(&mut consumer), [0]); let end = consumer .next_group() @@ -11673,15 +11638,15 @@ mod test { Poll::Ready(Some(1)) ); if raise_floor { - subscriber.set_groups(2..); + subscriber.set_range(2..); let Poll::Ready(Ok(Some(group))) = subscriber.poll_group(ordered, &waiter) else { panic!("group 2 is inside the new floor"); }; assert_eq!(group.sequence, 2); } else { - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_group(ordered, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); let Poll::Ready(Ok(Some(group))) = subscriber.poll_group(ordered, &waiter) else { panic!("group 1 was parked, not consumed"); }; @@ -11724,7 +11689,7 @@ mod test { fn peeking_keeps_a_re_offered_group_owed() { let producer = track_producer("test", Info::timed()); let mut subscriber = producer.subscribe(replay()); - subscriber.set_groups(..0); + subscriber.set_range(..0); for sequence in [1, 2] { producer .create_group(group::Info { sequence }) @@ -11734,7 +11699,7 @@ mod test { } let waiter = kio::Waiter::noop(); assert!(subscriber.poll_group(false, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); for _ in 0..2 { assert_eq!( subscriber.poll_peek_group(false, &waiter).map(Result::unwrap), @@ -11773,9 +11738,9 @@ mod test { }; assert_eq!(group.sequence, first); let second = if ordered { 2 } else { 1 }; - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_peek_group(ordered, &waiter).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); assert_eq!( subscriber.poll_peek_group(ordered, &waiter).map(Result::unwrap), Poll::Ready(Some(second)) @@ -11830,7 +11795,7 @@ mod test { .unwrap(); } - consumer.set_groups(..3); + consumer.set_range(..3); // Groups 0, 1, 2 are within the cap. assert_eq!( @@ -11867,7 +11832,7 @@ mod test { .unwrap(); } - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -11879,7 +11844,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none(), "capped at 2"); // Raise the cap; previously-blocked cached groups become available again. - consumer.set_groups(..5); + consumer.set_range(..5); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 @@ -11895,7 +11860,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none(), "capped at 5"); // Remove the cap; everything remaining flows. - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 5 @@ -11932,7 +11897,7 @@ mod test { ); // Lower the cap below the cursor. New groups beyond the cap are blocked. - consumer.set_groups(..2); + consumer.set_range(..2); producer .create_group(group::Info { sequence: 3 }) .unwrap() @@ -11949,7 +11914,7 @@ mod test { ); // Restoring the cap to no-limit (or any value >= cursor) releases them. - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 3 @@ -11966,7 +11931,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); - consumer.set_groups(..6); + consumer.set_range(..6); // Out-of-order arrivals all within the cap. producer @@ -12017,7 +11982,7 @@ mod test { assert!(consumer.next_group().now_or_never().is_none()); // Raise the cap; cached seq 8 is finally served. - consumer.set_groups(..11); + consumer.set_range(..11); assert_eq!( consumer.next_group().now_or_never().unwrap().unwrap().unwrap().sequence, 8 @@ -12041,7 +12006,7 @@ mod test { .unwrap(); } - consumer.set_groups(..2); + consumer.set_range(..2); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -12052,13 +12017,13 @@ mod test { ); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 2"); - consumer.set_groups(..); + consumer.set_range(..); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 ); - consumer.set_groups(..3); + consumer.set_range(..3); let _open = producer.create_group(group::Info { sequence: 3 }).unwrap(); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 3"); producer.finish().unwrap(); @@ -12076,7 +12041,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()); - consumer.set_groups(..2); + consumer.set_range(..2); // Reordered burst: the beyond-cap group arrives first. producer @@ -12105,7 +12070,7 @@ mod test { ); assert!(consumer.recv_group().now_or_never().is_none(), "capped at 2"); - consumer.set_groups(..3); + consumer.set_range(..3); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2 @@ -12117,14 +12082,14 @@ mod test { async fn group_ranges_preserve_the_floor_when_the_cap_changes() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); - consumer.set_groups(2..=2); + consumer.set_range(2..=2); producer .create_group(group::Info { sequence: 2 }) .unwrap() .finish() .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 2); - consumer.set_groups(..4); + consumer.set_range(..4); producer .create_group(group::Info { sequence: 1 }) .unwrap() @@ -12136,7 +12101,7 @@ mod test { .finish() .unwrap(); assert_eq!(consumer.recv_group().await.unwrap().unwrap().sequence, 3); - consumer.set_groups(0..=4); + consumer.set_range(0..=4); producer .create_group(group::Info { sequence: 0 }) .unwrap() @@ -12154,11 +12119,11 @@ mod test { /// them once the cap rises. #[test] #[cfg(feature = "async")] - fn start_at_drops_parked_recv_groups() { + fn a_raised_floor_drops_parked_recv_groups() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(None); - consumer.set_groups(..1); + consumer.set_range(..1); producer .create_group(group::Info { sequence: 1 }) .unwrap() @@ -12169,8 +12134,7 @@ mod test { "group 1 parked at the cap" ); - consumer.start_at(2); - consumer.set_groups(..); + consumer.set_range(2..); producer .create_group(group::Info { sequence: 2 }) .unwrap() @@ -12202,7 +12166,7 @@ mod test { 0 ); - consumer.set_groups(..1); + consumer.set_range(..1); let straggler = producer.create_group(group::Info { sequence: 1 }).unwrap(); assert!( consumer.recv_group().now_or_never().is_none(), @@ -12213,7 +12177,7 @@ mod test { straggler.abort(Error::Old).unwrap(); producer.finish().unwrap(); - consumer.set_groups(..); + consumer.set_range(..); assert!( matches!(consumer.recv_group().now_or_never(), Some(Ok(None))), "a dead parked group must not be delivered or hold the stream open" @@ -12237,13 +12201,13 @@ mod test { .finish() .unwrap(); - consumer.set_groups(..0); + consumer.set_range(..0); assert!( consumer.recv_group().now_or_never().is_none(), "empty cap delivers nothing" ); - consumer.set_groups(..1); + consumer.set_range(..1); assert_eq!( consumer.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0 @@ -12259,7 +12223,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut everything = producer.subscribe(replay()); let mut empty = producer.subscribe(replay()); - empty.set_groups((Bound::Unbounded, Position::group(0).group_end())); + empty.set_range((Bound::Unbounded, Position::group(0).group_end())); for s in 0..3 { producer @@ -12284,12 +12248,12 @@ mod test { "local empty cap must not ride the unbounded aggregate" ); - empty.set_groups(..2); + empty.set_range(..2); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 0); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 1); assert!(empty.recv_group().now_or_never().is_none(), "still capped at 2"); - empty.set_groups(..); + empty.set_range(..); assert_eq!(empty.recv_group().now_or_never().unwrap().unwrap().unwrap().sequence, 2); } @@ -12300,7 +12264,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); let end = Position::after(1, 1).unwrap(); - consumer.set_groups((Bound::Unbounded, end.group_end())); + consumer.set_range((Bound::Unbounded, end.group_end())); for s in 0..3u64 { let mut group = producer.create_group(group::Info { sequence: s }).unwrap(); @@ -12316,7 +12280,7 @@ mod test { ); let mut last = consumer.next_group().now_or_never().unwrap().unwrap().unwrap(); assert_eq!(last.sequence, 1); - last.set_frames(..end.frame); + last = last.with_range(..end.frame); assert_eq!( last.read_frame().now_or_never().unwrap().unwrap().unwrap().payload[0], 0 @@ -12341,7 +12305,7 @@ mod test { fn end_at_maximum_group_is_unbounded() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); - consumer.set_groups(..=u64::MAX); + consumer.set_range(..=u64::MAX); producer .create_group(group::Info { sequence: 0 }) @@ -12816,9 +12780,9 @@ mod test { live.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"delta2")) .unwrap(); let mut sub = producer.subscribe(None); - let mut group = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + let group = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); // Positioning at the start clamps up to the live group's first frame. - group.start_at(0); + let mut group = group.with_range(0..); assert_eq!(group.index(), 1); assert_eq!( group.read_frame().await.unwrap().unwrap().payload, @@ -12924,11 +12888,11 @@ mod test { let producer = track_producer("test", Info::timed()); let (live, _head) = live_group_with_head(&producer).await; let mut subscriber = producer.subscribe(replay()); - subscriber.set_groups(..0); + subscriber.set_range(..0); assert!(subscriber.poll_recv_group(&kio::Waiter::noop()).is_pending()); live.abort(Error::Cancel).unwrap(); assert!(subscriber.poll_recv_group(&kio::Waiter::noop()).is_pending()); - subscriber.set_groups(..); + subscriber.set_range(..); let mut group = subscriber.recv_group().await.unwrap().unwrap(); assert_eq!( group.read_frame().await.unwrap().unwrap().payload, @@ -14047,7 +14011,7 @@ mod test { let dynamic = producer.dynamic(); let consumer = producer.consume(); producer.create_group(5u64.into()).unwrap().finish().unwrap(); - let mut subscriber = producer.subscribe(replay().with_groups(5..)); + let mut subscriber = producer.subscribe(replay().with_range(5..)); assert_eq!(subscriber.assert_group().sequence, 5); let pending = consumer.fetch_group(2, None); @@ -14064,7 +14028,7 @@ mod test { pending.await.unwrap(); let mut withheld = producer.receive_group(group::Info { sequence: 3 }).unwrap(); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); subscriber.assert_no_group(); withheld @@ -14076,9 +14040,9 @@ mod test { // A cursor floor lowered before the next read counts only shown groups as unread. let mut lowered = producer.subscribe(replay()); - lowered.start_at(5); + lowered.set_range(5..); assert_eq!(lowered.assert_group().sequence, 5); - lowered.start_at(0); + lowered.set_range(0..); let delivered = super::super::delivered::Delivered::default(); let unread = Unread { start: 0, @@ -14275,7 +14239,7 @@ mod test { fn a_fixed_start_is_no_join() { let producer = track_producer("test", Info::default().with_refresh(1)); refresh_group(&producer, 4); - let _subscriber = producer.subscribe(Subscription::default().with_groups(0..)); + let _subscriber = producer.subscribe(Subscription::default().with_range(0..)); assert_eq!(producer.demand().wanted(), Some(0)); } @@ -14692,7 +14656,7 @@ mod test { #[cfg(feature = "async")] fn a_live_range_merged_with_one_above_the_live_edge_gets_the_newest_group() { let mut producer = quiet_track(3); - let mut ahead = producer.subscribe(replay().with_groups(4..)); + let mut ahead = producer.subscribe(replay().with_range(4..)); let mut live = producer.subscribe(replay().with_ranges([Range::live()])); assert_eq!( producer.subscription().unwrap().ranges, @@ -14801,7 +14765,7 @@ mod test { #[cfg(feature = "async")] fn a_buffering_range_merged_with_one_above_the_live_edge_keeps_its_backlog() { let mut producer = quiet_track(5); - let mut ahead = producer.subscribe(replay().with_groups(8..)); + let mut ahead = producer.subscribe(replay().with_range(8..)); let buffering = Range { start: Anchor::Relative(2), end: None, @@ -14847,7 +14811,7 @@ mod test { elapse(&producer, Duration::from_secs(1)); } let budget = Duration::from_millis(1500); - let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget).with_groups(0..)); + let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget).with_range(0..)); assert_eq!(drain(&mut subscriber), vec![3, 4]); } @@ -15064,17 +15028,17 @@ mod test { #[cfg(feature = "async")] fn replaced_ranges_resolve_again() { let mut producer = track_producer("test", Info::timed()); - let mut subscriber = producer.subscribe(replay().with_groups(0..2)); + let mut subscriber = producer.subscribe(replay().with_range(0..2)); for second in 0..4 { append_at(&mut producer, second * 1000); } assert_eq!(drain(&mut subscriber), vec![0, 1]); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), vec![2, 3], "held back, now in range"); // The latest group is 3 now, so one back is 2, already read: only new groups follow. - let mut late = producer.subscribe(replay().with_groups(..1)); + let mut late = producer.subscribe(replay().with_range(..1)); assert_eq!(drain(&mut late), vec![0]); late.update(replay().with_ranges([Range { start: Anchor::Relative(1), @@ -15094,7 +15058,7 @@ mod test { fn a_narrow_reader_holds_nothing_for_excluded_groups() { let producer = track_producer("test", Info::timed()); let _wide = producer.subscribe(replay()); - let mut narrow = producer.subscribe(replay().with_groups(0..2)); + let mut narrow = producer.subscribe(replay().with_range(0..2)); for sequence in 0..1000 { producer .create_group(group::Info { sequence }) @@ -15113,10 +15077,10 @@ mod test { .update(replay().with_ranges([Range::groups(0..2), Range::groups(5..8)])) .unwrap(); assert_eq!(drain(&mut narrow), vec![5, 6, 7]); - narrow.set_groups(..9); - narrow.update(replay().with_groups(0..)).unwrap(); + narrow.set_range(..9); + narrow.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut narrow), vec![2, 3, 4, 8]); - narrow.set_groups(..); + narrow.set_range(..); assert_eq!(drain(&mut narrow), (9..1000).collect::>()); } @@ -15129,28 +15093,50 @@ mod test { for second in 0..6 { append_at(&mut producer, second * 1000); } - let mut subscriber = producer.subscribe(replay().with_groups(5..)); + let mut subscriber = producer.subscribe(replay().with_range(5..)); assert_eq!(drain(&mut subscriber), vec![5]); - subscriber.update(replay().with_groups(2..)).unwrap(); + subscriber.update(replay().with_range(2..)).unwrap(); assert_eq!( drain(&mut subscriber), vec![2, 3, 4], "passed below the floor, now in range" ); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), vec![0, 1]); // Raising and lowering it again re-offers only what is cached in between, and // nothing already served goes out twice. - subscriber.update(replay().with_groups(4..)).unwrap(); + subscriber.update(replay().with_range(4..)).unwrap(); assert_eq!(drain(&mut subscriber), Vec::::new()); - subscriber.update(replay().with_groups(0..)).unwrap(); + subscriber.update(replay().with_range(0..)).unwrap(); assert_eq!(drain(&mut subscriber), Vec::::new()); append_at(&mut producer, 6000); assert_eq!(drain(&mut subscriber), vec![6]); } + /// Lowering a reader's local floor offers the cached groups below the old one that it + /// passed over, lowest first, and never a group twice. + #[test] + #[cfg(feature = "async")] + fn a_lowered_range_reoffers_the_unread_cached_groups() { + let mut producer = track_producer("test", Info::timed()); + for second in 0..6 { + append_at(&mut producer, second * 1000); + } + let mut subscriber = producer.subscribe(replay()).with_range(4..); + assert_eq!(drain(&mut subscriber), vec![4, 5]); + + let mut subscriber = subscriber.with_range(1..); + assert_eq!(drain(&mut subscriber), vec![1, 2, 3], "passed below the floor"); + let mut subscriber = subscriber.with_range(..=1); + assert_eq!(drain(&mut subscriber), vec![0], "the floor and the cap both assign"); + let mut subscriber = subscriber.with_range(..); + assert_eq!(drain(&mut subscriber), Vec::::new(), "nothing goes out twice"); + append_at(&mut producer, 6000); + assert_eq!(drain(&mut subscriber), vec![6]); + } + /// Datagrams outside a subscriber's ranges are dropped like the groups. #[test] #[cfg(feature = "async")] diff --git a/rs/moq-net/src/model/track/demand.rs b/rs/moq-net/src/model/track/demand.rs index b415c026944..85714134ae0 100644 --- a/rs/moq-net/src/model/track/demand.rs +++ b/rs/moq-net/src/model/track/demand.rs @@ -375,7 +375,7 @@ mod tests { assert!(producer.poll_subscription_changed(&waiter).is_pending()); let mut weak = producer.subscribe( Subscription::default() - .with_groups(100..200) + .with_range(100..200) .with_order(Order::Ascending), ); weak.update(Subscription::default().with_priority(5)).unwrap(); diff --git a/rs/moq-net/tests/integration/announce_to_serve.rs b/rs/moq-net/tests/integration/announce_to_serve.rs index ddc00e258a2..eb71f54291c 100644 --- a/rs/moq-net/tests/integration/announce_to_serve.rs +++ b/rs/moq-net/tests/integration/announce_to_serve.rs @@ -78,7 +78,7 @@ fn outcome(result: &Result) -> String { /// group's frames and then how the subscription ended. Read continuously, as a /// real subscriber would, so the subscription is driven the whole time. async fn read(broadcast: &moq_net::broadcast::Consumer, name: &str) -> mpsc::UnboundedReceiver { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = broadcast .track(name) .unwrap() diff --git a/rs/moq-net/tests/integration/finished_broadcast_mock.rs b/rs/moq-net/tests/integration/finished_broadcast_mock.rs index cec34b90745..7c8701f3e6d 100644 --- a/rs/moq-net/tests/integration/finished_broadcast_mock.rs +++ b/rs/moq-net/tests/integration/finished_broadcast_mock.rs @@ -60,7 +60,7 @@ async fn round(finish_broadcast: bool) -> (Vec>, Option) .expect("broadcast resolves"); let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() diff --git a/rs/moq-net/tests/integration/finite_relay.rs b/rs/moq-net/tests/integration/finite_relay.rs index 2ec6bc63e75..ff700f21e43 100644 --- a/rs/moq-net/tests/integration/finite_relay.rs +++ b/rs/moq-net/tests/integration/finite_relay.rs @@ -88,7 +88,7 @@ async fn round(name: &str, arrival: Arrival) -> (Vec, Result<(), moq_net::E let (mut heads, mut opened) = futures::channel::mpsc::unbounded(); let reader = moq_clock::sim::spawn(async move { - let subscription = Subscription::default().with_max_delay(MAX_DELAY).with_groups(0..); + let subscription = Subscription::default().with_max_delay(MAX_DELAY).with_range(0..); let mut sub = remote .track("tail") .unwrap() diff --git a/rs/moq-net/tests/integration/group_order.rs b/rs/moq-net/tests/integration/group_order.rs index 36a4197d418..581fe3c63bc 100644 --- a/rs/moq-net/tests/integration/group_order.rs +++ b/rs/moq-net/tests/integration/group_order.rs @@ -57,7 +57,7 @@ fn read_arrivals(origin: moq_net::origin::Producer, order: Order) -> moq_clock:: .expect("broadcast resolves"); let subscription = Subscription::default() .with_max_delay(FOREVER) - .with_groups(0..) + .with_range(0..) .with_order(order); let mut sub = remote .track("ordered") diff --git a/rs/moq-net/tests/integration/history_groups.rs b/rs/moq-net/tests/integration/history_groups.rs index a70687b8a5f..e7ada798343 100644 --- a/rs/moq-net/tests/integration/history_groups.rs +++ b/rs/moq-net/tests/integration/history_groups.rs @@ -82,7 +82,7 @@ async fn round(version: &str, relay: bool, newest_first: bool) -> Vec<(u64, usiz .expect("broadcast resolves"); let reader = moq_clock::sim::spawn(async move { - let subscription = Subscription::default().with_max_delay(FOREVER).with_groups(0..); + let subscription = Subscription::default().with_max_delay(FOREVER).with_range(0..); let mut sub = remote .track("history") .unwrap() @@ -223,7 +223,7 @@ async fn a_late_subscriber_receives_the_relays_cached_history() { let consumer = first.consume(); consumer.routed("bcast").await.unwrap(); let remote = consumer.request_broadcast("bcast", None).await.unwrap(); - let subscription = Subscription::default().with_max_delay(FOREVER).with_groups(0..); + let subscription = Subscription::default().with_max_delay(FOREVER).with_range(0..); let first_subscription = subscription.clone(); let first_reader = moq_clock::sim::spawn(async move { let mut sub = remote diff --git a/rs/moq-net/tests/integration/partial_group.rs b/rs/moq-net/tests/integration/partial_group.rs index 54c35c6f7e6..609ee7e5462 100644 --- a/rs/moq-net/tests/integration/partial_group.rs +++ b/rs/moq-net/tests/integration/partial_group.rs @@ -102,7 +102,7 @@ async fn round(version: &str) -> Option, moq_net::Error>> { remote.track("data").unwrap().subscribe( Subscription::default() .with_max_delay(Duration::from_secs(3600)) - .with_groups(0..), + .with_range(0..), ), ) .await diff --git a/rs/moq-net/tests/integration/quiet_catalog.rs b/rs/moq-net/tests/integration/quiet_catalog.rs index b5254bc2740..dab2e9e4a32 100644 --- a/rs/moq-net/tests/integration/quiet_catalog.rs +++ b/rs/moq-net/tests/integration/quiet_catalog.rs @@ -174,7 +174,7 @@ async fn resume_then_fresh(version: Version, in_process: bool) -> Result<(), Str let _sub = resume_remote .track("catalog.json") .unwrap() - .subscribe(track::Subscription::default().with_groups(1..)) + .subscribe(track::Subscription::default().with_range(1..)) .await .expect("resume subscribe"); moq_clock::sleep(Duration::from_secs(60)).await; diff --git a/rs/moq-net/tests/integration/received_rewind.rs b/rs/moq-net/tests/integration/received_rewind.rs index 5cc999f7143..5fb6028c952 100644 --- a/rs/moq-net/tests/integration/received_rewind.rs +++ b/rs/moq-net/tests/integration/received_rewind.rs @@ -63,7 +63,7 @@ async fn relay(downstream: &str) -> (Option, Vec) { .expect("resolve timeout") .expect("broadcast resolves"); - let subscription = Subscription::default().with_max_delay(BUDGET).with_groups(0..); + let subscription = Subscription::default().with_max_delay(BUDGET).with_range(0..); let reader = moq_clock::sim::spawn(async move { let mut sub = remote .track("data") diff --git a/rs/moq-net/tests/integration/settled_end_survives_abort.rs b/rs/moq-net/tests/integration/settled_end_survives_abort.rs index 0c4658610b7..090336763ea 100644 --- a/rs/moq-net/tests/integration/settled_end_survives_abort.rs +++ b/rs/moq-net/tests/integration/settled_end_survives_abort.rs @@ -32,7 +32,7 @@ async fn round(abort: bool, ordered: bool) -> (Vec, Option) { // From the first group with a replay window: a late reader is owed the whole track, // not the live edge. let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(std::time::Duration::from_secs(30)); let mut consumer = track.subscribe(subscription); diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index e998f67226e..7375b7f8eb7 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -105,7 +105,7 @@ async fn ahead_then_live(version: Option<&str>, relay: bool) -> (Vec, Vec (Vec>, Option) { let (go_tx, go_rx) = futures::channel::oneshot::channel::<()>(); let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -225,7 +225,7 @@ async fn killed(version: &str, local: bool) -> (Option, Option Outcome { } = connect(version).await; let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -279,7 +279,7 @@ async fn ietf_leaving_cancels_a_blocked_end_of_track() { _keep, } = connect(version).await; - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -335,7 +335,7 @@ async fn a_lost_datagram_delays_the_end() { } = connect(version).await; let reader = moq_clock::sim::spawn(async move { - let subscription = moq_net::track::Subscription::default().with_groups(0..); + let subscription = moq_net::track::Subscription::default().with_range(0..); let mut sub = remote .track("video") .unwrap() @@ -395,7 +395,7 @@ async fn a_group_whose_first_frame_trails_its_header_is_delivered() { let reader = moq_clock::sim::spawn(async move { let subscription = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(TIMEOUT); let mut sub = remote .track("video") diff --git a/rs/moq-net/tests/integration/untimed.rs b/rs/moq-net/tests/integration/untimed.rs index fce1facdfa8..957b75b27e8 100644 --- a/rs/moq-net/tests/integration/untimed.rs +++ b/rs/moq-net/tests/integration/untimed.rs @@ -194,7 +194,7 @@ async fn an_explicit_start_holds_on_an_untimed_track() { let consumer = chain.nodes[1].consume().request_broadcast("room", None).await.unwrap(); let subscription = track::Subscription::default() - .with_groups(2..) + .with_range(2..) .with_max_delay(Duration::from_secs(30)); let mut subscriber = moq_clock::timeout(TIMEOUT, consumer.track("data").unwrap().subscribe(subscription)) .await diff --git a/rs/moq-net/tests/loom.rs b/rs/moq-net/tests/loom.rs index 5623ac5b4f6..e6b8138785e 100644 --- a/rs/moq-net/tests/loom.rs +++ b/rs/moq-net/tests/loom.rs @@ -94,7 +94,7 @@ fn back_to_back_groups_arrive_in_order() { let consumer = broadcast.consume(); let track = broadcast.create_track("video", None).expect("create track"); let from_start = moq_net::track::Subscription::default() - .with_groups(0..) + .with_range(0..) .with_max_delay(std::time::Duration::MAX); let subscribing = consumer.track("video").expect("track").subscribe(from_start); @@ -557,8 +557,8 @@ fn an_aborted_parked_group_releases_a_finished_track() { let track = broadcast.create_track("parked", timed()).unwrap(); let mut group = track.append_group().unwrap(); group.finish().unwrap(); - let mut subscriber = track.subscribe(moq_net::track::Subscription::default().with_groups(0..)); - subscriber.set_groups(..0); + let mut subscriber = track.subscribe(moq_net::track::Subscription::default().with_range(0..)); + subscriber = subscriber.with_range(..0); track.finish().unwrap(); let aborting = thread::spawn(move || group.abort(Error::Old).unwrap()); assert!(block_on(subscriber.recv_group()).unwrap().is_none()); diff --git a/rs/moq-room/src/chat.rs b/rs/moq-room/src/chat.rs index 22ebb790c6c..00bb7c59476 100644 --- a/rs/moq-room/src/chat.rs +++ b/rs/moq-room/src/chat.rs @@ -158,11 +158,12 @@ impl Subscriber { // The newest window is known only once the feed is live: a relay copy still waiting // on its source reports nothing yet, so wait rather than replay its backlog. The // wait ends with the track. - if let Some(largest) = ready!(track.poll_largest(waiter)) { - track.set_groups(largest.group..); + let largest = ready!(track.poll_largest(waiter)); + let mut track = *pending.take().expect("positioning holds the track"); + if let Some(largest) = largest { + track = track.with_range(largest.group..); } - let track = pending.take().expect("positioning holds the track"); - self.state = State::Reading(Box::new(moq_json::window::Consumer::new(*track, Default::default()))); + self.state = State::Reading(Box::new(moq_json::window::Consumer::new(track, Default::default()))); } let State::Reading(consumer) = &mut self.state else { unreachable!("positioned above"); diff --git a/rs/moq-stats/src/produce.rs b/rs/moq-stats/src/produce.rs index 4f21883c188..3c1c63204da 100644 --- a/rs/moq-stats/src/produce.rs +++ b/rs/moq-stats/src/produce.rs @@ -1611,7 +1611,7 @@ mod tests { let subscribing = consumer .track(name) .unwrap() - .subscribe(track::Subscription::default().with_groups(floor..)); + .subscribe(track::Subscription::default().with_range(floor..)); family.adopt_pair( &broadcast, &mut requested, diff --git a/rs/moq-tokio/tests/integration/broadcast.rs b/rs/moq-tokio/tests/integration/broadcast.rs index a9021e1cdd8..a81d78ca6b7 100644 --- a/rs/moq-tokio/tests/integration/broadcast.rs +++ b/rs/moq-tokio/tests/integration/broadcast.rs @@ -1117,7 +1117,7 @@ async fn broadcast_route_migration() { // Resolve and subscribe: the cheaper route (A) serves the track. let subscription = moq_net::track::Subscription::default() - .with_groups(1..) + .with_range(1..) .with_max_delay(Duration::from_secs(10)); let broadcast = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test", None)) .await diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index e982a8ac425..6841487ba3f 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -295,7 +295,7 @@ impl Reader { if options.start == Start::Latest && let Some(live_edge) = subscriber.largest().await { - subscriber.set_groups(live_edge.group.saturating_sub(lookback)..); + subscriber = subscriber.with_range(live_edge.group.saturating_sub(lookback)..); } let track = subscriber; // The catalog says how the track is framed, and it is not always the legacy diff --git a/test/interop/clients/rust/tail.rs b/test/interop/clients/rust/tail.rs index 7aba491c29d..a79fe35e98f 100644 --- a/test/interop/clients/rust/tail.rs +++ b/test/interop/clients/rust/tail.rs @@ -74,7 +74,7 @@ async fn main() -> anyhow::Result<()> { let broadcast = consumer.routed_broadcast(&args[3]).await?; let options = moq_net::track::Subscription::default() .with_max_delay(Duration::from_secs(if drop { 60 } else { 5 })) - .with_groups(0..); + .with_range(0..); let mut track = broadcast.track("tail")?.subscribe(Some(options)).await?; let mut seen = Vec::new(); while let Some(mut group) = track.recv_group().await? { From 1bea3f9776892620d7b7a3379396b8faf9f72e14 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 20 Oct 2026 18:56:28 -0700 Subject: [PATCH 03/18] refactor(net)!: public serving cursor, Recv, and track info hold in JS Mirror the Rust with_range in @moq/net: withRange replaces setGroups, withGroups, and hooks.replaceGroups, assigning both bounds and re-offering unread cached groups below a lowered floor. tryRecvGroup returns the Recv union with a public groupChanged wake, Ordered gains tryNextGroup, and finalSequence and Track.Consumer.info({ hold }) are public, so the lite and IETF publishers drop their hooks. The json and flate snapshot consumers drain held groups instead of raising the floor, keeping the caller's cap. Narrow the serve quest to the JS group expiry decision, move the live-edge answers to track-live, and add MIGRATE entries for both packages. Co-Authored-By: Claude Opus 5.5 --- js/flate/src/snapshot/consumer.ts | 68 +++++--- js/flate/src/snapshot/snapshot.test.ts | 14 ++ js/json/src/snapshot/consumer.ts | 18 +- js/json/src/snapshot/snapshot.test.ts | 14 ++ js/json/src/window/window.test.ts | 4 +- js/net/MIGRATE.md | 35 +++- js/net/bench/resume.ts | 7 +- js/net/bench/track.ts | 7 +- js/net/src/ietf/publisher.ts | 14 +- js/net/src/ietf/subscriber.ts | 11 +- js/net/src/internal.ts | 62 +------ js/net/src/lite/publisher.test.ts | 32 ++-- js/net/src/lite/publisher.ts | 93 ++++++----- js/net/src/lite/subscribe.ts | 2 +- js/net/src/resume.test-util.ts | 4 +- js/net/src/resume.test.ts | 32 ++-- js/net/src/resume.ts | 15 +- js/net/src/track.test.ts | 192 +++++++++++----------- js/net/src/track.ts | 168 ++++++++++++------- js/net/src/wire.ts | 8 +- js/room/src/chat.ts | 2 +- quest/m1/egress-held-state.md | 2 +- quest/m1/public-model/README.md | 2 +- quest/m1/public-model/serve.md | 179 ++++---------------- quest/m1/subscribe-drop-errors.md | 2 +- quest/m1/subscribe-ranges/frame-bounds.md | 2 +- quest/m1/track-live.md | 14 +- rs/moq-net/MIGRATE.md | 27 ++- 28 files changed, 519 insertions(+), 511 deletions(-) diff --git a/js/flate/src/snapshot/consumer.ts b/js/flate/src/snapshot/consumer.ts index 0a7a9ed281b..af5565bc22c 100644 --- a/js/flate/src/snapshot/consumer.ts +++ b/js/flate/src/snapshot/consumer.ts @@ -5,6 +5,14 @@ import { Decoder as Flate } from "../codec.ts"; import { isDeflate } from "../compression.ts"; import type { Config as CodecConfig } from "./producer.ts"; +// Group errors that lose only that group, matching the JSON snapshot consumer. +const GAPS: Moq.StreamCode[] = [ + Moq.StreamCode.TooFarBehind, + Moq.StreamCode.Old, + Moq.StreamCode.Evicted, + Moq.StreamCode.GroupTooLarge, +]; + /** * Consumes an opaque value from a track, yielding each with the timestamp of its frame. * @@ -17,8 +25,8 @@ export class Consumer { #track: Moq.Track.Ordered; #decompress: boolean; - // The group the current window belongs to, so a boundary restarts it. - #group?: number; + // The group being read. + #group?: Moq.Group.Consumer; // The DEFLATE window for the current group, present while decompressing. A snapshot group is // normally one frame, but the window is per group either way. #flate?: Flate; @@ -44,9 +52,9 @@ export class Consumer { /** * Get the newest value, or `undefined` once the track ends. * - * Every group is a complete value, so any older group is already superseded. Raising the read - * floor to the newest sequence before each read does two things: it discards a backlog instead - * of decoding every superseded value in turn, and it abandons a group a newer one has + * Every group is a complete value, so any older group is already superseded. Jumping to the + * newest group the reader holds before each read does two things: it discards a backlog + * instead of decoding every superseded value in turn, and it abandons a group a newer one has * superseded rather than waiting out its close. A reader's latency therefore never grows with * the queue, and never depends on a stale group's FIN arriving. */ @@ -57,35 +65,53 @@ export class Consumer { async #read(skip: boolean): Promise | undefined> { for (;;) { if (skip) { - const latest = await this.#track.largest(); - if (latest !== undefined) this.#track.setGroups({ start: { included: latest.group } }); + // Jump to the newest group the reader already has; a newer one supersedes the rest. + // Taking groups, not the track's largest position, ignores datagrams (which share + // the sequence space) and stays inside any range the caller set on the reader. + // Mirrors the Rust consumer. + for (let recv = this.#track.tryNextGroup(); recv.kind === "group"; recv = this.#track.tryNextGroup()) { + this.#open(recv.group); + } + } + + if (!this.#group) { + const group = await this.#track.nextGroup(); + if (!group) return undefined; + this.#open(group); } + const group = this.#group; + if (!group) continue; - let next: Awaited>; + let next: Moq.Group.Frame | undefined; try { - next = await this.#track.readFrame(); + next = await group.readFrame(); } catch (err) { - // Falling behind a group's eviction window is recoverable: the next group carries a - // complete value of its own, so resync there rather than surfacing a partial read. - // Anything else is the track's terminal error, which every later read would throw - // again; swallowing it would spin here instead of telling the caller the - // subscription died. - if (!(err instanceof Moq.Error.TooFarBehind)) throw err; + // Losing one group (reset, or fallen behind its eviction window) is recoverable: the + // next group carries a complete value of its own, so resync there rather than + // surfacing a partial read. Anything else is the track's terminal error, which every + // later read would throw again; swallowing it would spin here instead of telling the + // caller the subscription died. + if (!(err instanceof Moq.Error.Stream && GAPS.includes(err.code))) throw err; + this.#group = undefined; continue; } - if (!next) return undefined; - - // Each group is its own compressed stream, so a boundary starts a cold window. - if (next.group !== this.#group) { - this.#group = next.group; - this.#flate = this.#decompress ? new Flate() : undefined; + if (!next) { + this.#group = undefined; + continue; } return { value: this.#flate ? this.#flate.frame(next.payload) : next.payload, at: next.timestamp }; } } + // Each group is its own compressed stream, so a boundary starts a cold window. + #open(group: Moq.Group.Consumer): void { + this.#group?.close(); + this.#group = group; + this.#flate = this.#decompress ? new Flate() : undefined; + } + /** Iterate over every value in group order, as {@link next} yields them, until the track ends. */ async *[Symbol.asyncIterator](): AsyncIterator> { for (;;) { diff --git a/js/flate/src/snapshot/snapshot.test.ts b/js/flate/src/snapshot/snapshot.test.ts index 2ea8ba6170e..63c6ccef229 100644 --- a/js/flate/src/snapshot/snapshot.test.ts +++ b/js/flate/src/snapshot/snapshot.test.ts @@ -145,6 +145,20 @@ test("latest lets a newer group preempt an open one", async () => { track.close(); }); +// Skipping to the head never widens the reader's range: a capped reader reads the newest value +// below its cap, and a datagram past every group does not strand it. +test("latest stays inside the reader's range", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track }); + const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).withRange({ end: { excluded: 2 } }); + const consumer = new Consumer({ track: subscriber }); + + for (let n = 0; n < 4; n++) producer.update({ value: bytes(n) }); + track.appendDatagram(Time.Timestamp.now(), bytes(9)); + expect((await consumer.latest())?.value).toEqual(bytes(1)); + producer.finish(); +}); + test("an aborted track surfaces its error instead of spinning", async () => { // Every read after an abort throws the same terminal error, so swallowing it as if it were a // recoverable Lagged would loop forever on a rejected promise rather than telling the caller diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index a42a2a929ed..f1262046280 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -63,16 +63,16 @@ export class Consumer { async #read(skip: boolean): Promise | undefined> { for (;;) { if (skip) { - // A newer group supersedes everything the current one still holds: it restarts from a - // full snapshot, so switching mid-group loses nothing but stale state (mirrors the Rust - // consumer). Older groups only hold superseded state too, so raise the floor to the - // newest instead of replaying each one. - const latest = await this.#track.largest(); - if (this.#group !== undefined && latest !== undefined && latest.group > this.#group.sequence) { - this.#group.close(); - this.#group = undefined; + // Jump to the newest group the reader already has; a newer one supersedes the rest. + // Taking groups, not the track's largest position, ignores datagrams (which share + // the sequence space) and stays inside any range the caller set on the reader. + // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses + // nothing but stale state. + for (let recv = this.#track.tryNextGroup(); recv.kind === "group"; recv = this.#track.tryNextGroup()) { + this.#group?.close(); + this.#group = recv.group; + this.#framesRead = 0; } - if (!this.#group && latest !== undefined) this.#track.setGroups({ start: { included: latest.group } }); } if (!this.#group) { diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 2b513b922d8..bba31f26799 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -160,6 +160,20 @@ test("latest abandons a held group when a newer snapshot group rolls", async () expect(await consumer.latest()).toBeUndefined(); }); +// Skipping to the head never widens the reader's range: a capped reader reads the newest state +// below its cap, and a datagram past every group does not strand it. +test("latest stays inside the reader's range", async () => { + const track = new Track.Producer("test"); + const producer = new Producer({ track, deltaRatio: 0 }); + const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).withRange({ end: { excluded: 2 } }); + const consumer = new Consumer({ track: subscriber }); + + for (let n = 0; n < 4; n++) producer.update({ value: { a: n } }); + track.appendDatagram(Time.Timestamp.now(), new Uint8Array([0])); + expect((await consumer.latest())?.value).toEqual({ a: 1 }); + producer.finish(); +}); + // `next()` finishes the held group before the newer one, so a playhead sees every state. test("next reads a held group out before a newer snapshot group", async () => { const track = new Track.Producer("test"); diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index bd0c3da9a0f..62cd85d6646 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -261,7 +261,7 @@ test("a lagging consumer is told what it missed", async () => { producer.push({ value: { n } }); producer.pop(1); } - subscriber.setGroups({ start: { included: (await subscriber.largest())?.group ?? 0 } }); + subscriber.withRange({ start: { included: (await subscriber.largest())?.group ?? 0 } }); const events = await live.finish(); const skipped = events.flatMap((e) => ("skip" in e ? span(e.skip) : [])); @@ -314,7 +314,7 @@ test("a fresh consumer adopts the current offset", async () => { producer.pop(3); const subscriber = track.subscribe(); - subscriber.setGroups({ start: { included: (await subscriber.largest())?.group ?? 0 } }); + subscriber.withRange({ start: { included: (await subscriber.largest())?.group ?? 0 } }); const consumer = new Consumer({ track: subscriber }); producer.finish(); const events: Event[] = []; diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 4d7076305f6..e7bc383686a 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -4,13 +4,42 @@ How to update your code for each breaking change, newest first. ## Unreleased -### `largest()` reports within a reader's `setGroups` bounds +### One `withRange` bounds a reader -`Track.Subscriber.largest()` and `Track.Ordered.largest()` report the track's largest only while it is within the bounds set with `setGroups` or `withGroups`, where they used to ignore the bounds. +`Track.Subscriber.setGroups`, `withGroups`, and their `Track.Ordered` twins are replaced by `withRange(groups)`, which returns the reader. +Both bounds now assign: an omitted start is group 0, where `setGroups` kept the floor, so pass the floor you want to keep. +Lowering the floor offers the cached groups below the old one that the reader never read; a group is still handed out once. + +```ts +// Before +subscriber.setGroups({ end: { excluded: 10 } }); +// After +subscriber.withRange({ start: { included: floor }, end: { excluded: 10 } }); +``` + +### `tryRecvGroup` says why it returned no group + +`Track.Subscriber.tryRecvGroup()` returns a `Track.Recv` instead of a group or `undefined`, and no longer throws the track's error. +Read `recv.group` when `recv.kind === "group"`; `idle` and `boundary` may change once `groupChanged(fn)` fires, `done` is the end, and `error` carries what it used to throw. +`{ drops: true }` also reports the sequences the cursor gave up. + +```ts +// Before +const group = subscriber.tryRecvGroup(); +// After +const recv = subscriber.tryRecvGroup(); +const group = recv.kind === "group" ? recv.group : undefined; +``` + +`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, and `Track.Consumer.info({ hold })` are new. + +### `largest()` reports within a reader's `withRange` bounds + +`Track.Subscriber.largest()` and `Track.Ordered.largest()` report the track's largest only while it is within the bounds set with `withRange`, where they used to ignore the bounds. A largest past the cap or below the floor reports nothing; the cache never stands in for it. A cap moved below the largest stays pending. Moving the bounds wakes a pending read, which reports the largest once it is within them and newer than the last report. Unbounded readers and `Track.Producer.largest()` are unchanged. -To read the track's edge from a capped reader, lift the cap with `setGroups({})` first. +To read the track's edge from a capped reader, lift the cap with `withRange({})` first. ### Lite-07 accounts for groups with `SUBSCRIBE_DROP` diff --git a/js/net/bench/resume.ts b/js/net/bench/resume.ts index 88731886ea0..42d28d796bd 100644 --- a/js/net/bench/resume.ts +++ b/js/net/bench/resume.ts @@ -27,14 +27,15 @@ const flush = () => new Promise((resolve) => setImmediate(resolve)); function read(subscribers: Subscriber[]) { for (const subscriber of subscribers) { - const group = subscriber.tryRecvGroup(); - if (!group) throw new Error("group was not delivered"); + const recv = subscriber.tryRecvGroup(); + if (recv.kind !== "group") throw new Error("group was not delivered"); + const group = recv.group; const frame = group.tryReadFrame(); if (!frame) throw new Error("frame was not delivered"); checksum += frame.payload.byteLength; group.close(); // Read until idle, as a reader parked on the next group does. - if (subscriber.tryRecvGroup()) throw new Error("group delivered twice"); + if (subscriber.tryRecvGroup().kind === "group") throw new Error("group delivered twice"); } } diff --git a/js/net/bench/track.ts b/js/net/bench/track.ts index 03abcf0147e..4a2f9352117 100644 --- a/js/net/bench/track.ts +++ b/js/net/bench/track.ts @@ -32,8 +32,9 @@ const flush = () => new Promise((resolve) => setImmediate(resolve)); function receive(subscribers: Subscriber[]): GroupConsumer[] { const received: GroupConsumer[] = []; for (const subscriber of subscribers) { - const group = subscriber.tryRecvGroup(); - if (!group) throw new Error("group was not delivered"); + const recv = subscriber.tryRecvGroup(); + if (recv.kind !== "group") throw new Error("group was not delivered"); + const group = recv.group; const frame = group.tryReadFrame(); if (!frame) throw new Error("frame was not delivered"); checksum += frame.payload.byteLength; @@ -99,7 +100,7 @@ async function measure( clock += CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8 + 1; const idleStart = now(); const replay = producer.subscribe({ maxDelay: window }); - if (replay.tryRecvGroup()) throw new Error("idle cache entries were retained"); + if (replay.tryRecvGroup().kind === "group") throw new Error("idle cache entries were retained"); const idle = (now() - idleStart) * 1000; replay.close(); return { publish: (elapsed * 1000) / groups, end, idle }; diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 2d48c91f4da..3be9261763f 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -513,7 +513,7 @@ export class Publisher { // A range that resolves without the live edge has a fixed start, which is no join: // bound the subscription before subscribing so the refresh ratio never judges it. const fixed = subscribeRange(msg, {}, version); - const track = wireOf(broadcast).subscribe(msg.trackName, { + const track = broadcast.track(msg.trackName).subscribe({ priority, order, // An absent budget preserves everything retained by the producer. @@ -572,7 +572,7 @@ export class Publisher { groups: rangeGroups(range), }); const startGroup = range.start ? Number(range.start.group) : hooks.latestSequence(track); - if (startGroup !== undefined) track.setGroups({ start: { included: startGroup } }); + if (startGroup !== undefined) track.withRange({ start: { included: startGroup } }); // A fill reads the group cache through its own consumer, independent of the // subscription's cursor. Forked from this subscriber rather than resolved through @@ -730,7 +730,7 @@ export class Publisher { const group = await track.recvGroup(); if (!group) return; - // Past the filter's end. Dropped here rather than through `setGroups`, which + // Past the filter's end. Dropped here rather than through `withRange`, which // parks a capped group instead: this range is fixed for the life of the // subscription, so a group above it is never coming back in, and holding // one keeps the loop from ever ending. A producer that publishes beyond @@ -2058,7 +2058,7 @@ export class Publisher { let answer: TrackStatusOk; try { const broadcast = await this.#resolve(name, hold.signal, msg.epoch); - const info = await wireOf(broadcast).resolveTrackInfo(msg.trackName, hold.signal); + const info = await broadcast.track(msg.trackName).info({ hold: hold.signal }); const largest = wireOf(broadcast).largest(msg.trackName); answer = new TrackStatusOk({ requestId: @@ -2283,8 +2283,10 @@ type FillServe = */ function takeGroup(cache: TrackSubscriber, sequence: number): group.Consumer { for (;;) { - const group = cache.tryRecvGroup(); - if (!group) throw new Error(`group not found: ${sequence}`); + const recv = cache.tryRecvGroup(); + if (recv.kind === "error") throw recv.error; + if (recv.kind !== "group") throw new Error(`group not found: ${sequence}`); + const group = recv.group; if (group.sequence === sequence) return group; group.close(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index bf621937bc1..276cac27e0c 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -20,20 +20,13 @@ import { } from "../error.ts"; import * as netGroup from "../group.ts"; import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; -import { - finalSequence, - groupBounds, - hiddenBelow, - hooks, - scopeCaptures, - scopeHead, - scopeOverlaps, -} from "../internal.ts"; +import { groupBounds, hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import { type Cursor, Reader, type Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; import type { Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; +import { finalSequence } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, requestOptions } from "../util/deadline.ts"; import { abandoned as demandAbandoned, isAbandoned, unwanted } from "../util/demand.ts"; diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index c342ed8218a..d21912e9f89 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -15,7 +15,7 @@ import type { Frame, Consumer as GroupConsumer, Producer as GroupProducer } from import { isAnonymous, type Route } from "./hop.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; -import type { Groups, Info, Location, Producer, Request, Subscriber, Subscription } from "./track.ts"; +import type { Groups, Info, Location, Producer, Recv, Request, Subscriber, Subscription } from "./track.ts"; import type { Advertised, Advertisements } from "./wire.ts"; // private: plumbing @@ -143,24 +143,6 @@ export function runGaps(runs: readonly Run[], start: number, end: number): Run[] return gaps; } -/** - * What a non-blocking group read found, which is everything the caller needs to decide what - * to do next: no second look at the track's closed state, and no ordering rule to get wrong. - */ -export type Recv = - /** A group to serve. It has already left the buffer, so dropping this is dropping the group. */ - | { kind: "group"; group: GroupConsumer } - /** Sequences `[start, end)` this cursor gave up without serving. */ - | { kind: "drop"; start: number; end: number } - /** Nothing readable, but the track is live and may produce more. */ - | { kind: "idle" } - /** The producer finished, yet groups above the cap are still held: raising it releases them. */ - | { kind: "boundary" } - /** The producer finished and the buffer is drained. Nothing can follow. */ - | { kind: "done" } - /** The track aborted. */ - | { kind: "error"; error: Error }; - /** A package-internal frame read the wire publisher completes once written. */ export interface ReadGroupFrame { /** Frame sequence within the group. */ @@ -329,12 +311,6 @@ export interface TrackRequestOptions { pending: Set; } -// pending: /quest/m1/public-model/serve.md -/** The first group an exclusive track end excludes whole: one past the last group that may exist. */ -export function finalSequence(end: Location): number { - return end.group + (end.frame === 0 ? 0 : 1); -} - // private: plumbing /** Hooks assigned in static blocks by the owning class. */ export const hooks: { @@ -383,10 +359,10 @@ export const hooks: { // private: capability gap /** Seed a received track from the publisher's reported edge; assigned by `track.ts`. */ reportedLargest: (producer: Producer, largest: Location | undefined) => void; - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md /** Snapshot the latest group sequence for wire positioning; assigned by `track.ts`. */ latestSequence: (subscriber: Subscriber) => number | undefined; - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md /** The newest frame buffered for a subscriber, which wire answers name; assigned by `track.ts`. */ bufferedLargest: (subscriber: Subscriber) => Location | undefined; /** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */ @@ -394,18 +370,9 @@ export const hooks: { // pending: /quest/m1/public-model/ingest.md /** Record sequences `[start, end)` an upstream publisher explicitly gave up. */ dropTrackGroups: (producer: Producer, start: number, end: number) => void; - // pending: /quest/m1/public-model/serve.md - /** - * Take the next group the subscriber's cursor allows, without waiting; assigned by `track.ts`. - * - * Synchronous so a caller can pop a group and act on it in the same turn. Park on - * {@link groupChanged} when it reports `idle` or `boundary`. With `dispositions`, what - * the cursor gives up is reported once as a `drop`. - */ - tryRecvGroup: (subscriber: Subscriber, dispositions: boolean) => Recv; - /** The sequence {@link tryNextGroup} (`ordered`) or {@link tryRecvGroup} would take next, without taking it. */ + /** The sequence {@link tryNextGroup} (`ordered`) or `tryRecvGroup` would take next, without taking it. */ peekGroup: (subscriber: Subscriber, ordered: boolean) => number | undefined; - /** Take the next group in sequence order without waiting, as {@link tryRecvGroup} does in arrival order. */ + /** Take the next group in sequence order without waiting, as `tryRecvGroup` does in arrival order. */ tryNextGroup: (subscriber: Subscriber) => Recv; /** Wake once a subscriber's datagram cursor may read differently; fires at most once. */ datagramChanged: (subscriber: Subscriber, fn: () => void) => Dispose; @@ -434,18 +401,8 @@ export const hooks: { subscription: Subscription | undefined, source: (shell: ResumeShell) => ResumeSource, ) => Subscriber; - // pending: /quest/m1/public-model/serve.md - /** Wake once a subscriber's group cursor may read differently; assigned by `track.ts`. */ - groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; /** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */ fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void; - // pending: /quest/m1/public-model/serve.md - /** - * Replace a serving cursor. An omitted start keeps the current floor; a provided start - * can lower it. Wire publishers apply SUBSCRIBE_UPDATE here rather than through - * `setGroups`, which never rewinds. - */ - replaceGroups: (subscriber: Subscriber, groups: Groups) => void; /** * Bind a group to its track's timedness, so a frame whose timestamp disagrees is refused. * Throws `TimestampMismatch` if a buffered frame already disagrees. @@ -542,9 +499,6 @@ export const hooks: { dropTrackGroups: () => { throw new Error("track.ts not loaded"); }, - tryRecvGroup: () => { - throw new Error("track.ts not loaded"); - }, tryNextGroup: () => { throw new Error("track.ts not loaded"); }, @@ -584,15 +538,9 @@ export const hooks: { resumeSubscriber: () => { throw new Error("track.ts not loaded"); }, - groupChanged: () => { - throw new Error("track.ts not loaded"); - }, fetchBudget: () => { throw new Error("track.ts not loaded"); }, - replaceGroups: () => { - throw new Error("track.ts not loaded"); - }, bindGroupTimed: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index c4f7d66c1c2..e8cdcf76461 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -13,6 +13,7 @@ import * as Path from "../path.ts"; import { sendOrder } from "../priority.ts"; import { Reader, Stream, Writer } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; +import { Subscriber as TrackSubscriber } from "../track.ts"; import { type AnnounceBroadcast, AnnounceOk, AnnounceRequest, decodeAnnounceBroadcast } from "./announce.ts"; import { Fetch } from "./fetch.ts"; import { Group as GroupMessage } from "./group.ts"; @@ -544,7 +545,7 @@ const IDLE_MS = 500; const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); function lastGroups(ranges: ReturnType) { - return ranges.mock.calls.at(-1)?.[1]; + return ranges.mock.calls.at(-1)?.[0]; } // Wraps a writable so its writes park until `release()`, giving a test a window inside @@ -913,7 +914,7 @@ test("lite draft-06: an omitted group start still serves a group below the first // to the next pop rather than reaching backward into this one. test("lite draft-05: a group popped before a cap update is still served", async () => { const sub = await servedSubscription({ startGroup: 1, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(1); await sub.parked; @@ -941,7 +942,7 @@ test("lite draft-05: a group popped before a cap update is still served", async // poll order. test("lite draft-06: a queued floor update applies before the next group pop", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 0, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -967,7 +968,7 @@ test("lite draft-06: a queued floor update applies before the next group pop", a }); // SUBSCRIBE_START pins the floor to the first served group. A later update can still -// widen it: public setGroups would keep the pin, so serving uses replaceGroups. +// widen it, serving the cached groups below the old floor. test("lite draft-06: a widening update lowers the serving floor", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 10 }); try { @@ -995,7 +996,7 @@ test("lite draft-06: a queued frame floor applies before the next group pop", as frames: ["a", "b", "c"], gated: true, }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -1086,7 +1087,7 @@ test("lite draft-06: a burst of updates coalesces before the next group pop", as sub.serve(0); await sub.parked; sub.serve(1); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { // Two updates land back to back, the second superseding the first. @@ -1105,7 +1106,8 @@ test("lite draft-06: a burst of updates coalesces before the next group pop", as // Group 1 is popped under the latest state, with no application of the older one. expect(await sub.servedGroup()).toEqual({ sequence: 1, frameStart: 0, payloads: ["a"] }); expect(ranges).toHaveBeenCalledTimes(1); - expect(lastGroups(ranges)).toEqual({ start: undefined, end: { included: 1 } }); + // Draft-06 encodes a floor of group 0 as no floor, which assigns 0. + expect(lastGroups(ranges)).toEqual({ start: { included: 0 }, end: { included: 1 } }); } finally { ranges.mockRestore(); } @@ -1123,11 +1125,13 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" gated: true, }); let second!: Promise; - const replaceGroups = hooks.replaceGroups; - const ranges = spyOn(hooks, "replaceGroups").mockImplementation((subscriber, groups) => { - if (groups.start === undefined) - second ??= replayUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); - return replaceGroups(subscriber, groups); + const withRange = TrackSubscriber.prototype.withRange; + const ranges = spyOn(TrackSubscriber.prototype, "withRange").mockImplementation(function ( + this: TrackSubscriber, + groups, + ) { + second ??= replayUpdate({ priority: 0, endGroup: 1 }).encode(sub.client.writer, Version.DRAFT_06); + return withRange.call(this, groups); }); try { @@ -1159,7 +1163,7 @@ test("lite draft-06: a newer update wins before a buffered group backlog drains" // The full update remains atomic to observers, while the local range cursor stays serialized. test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", async () => { const sub = await servedSubscription({ version: Version.DRAFT_06, startGroup: 0, gated: true }); - const ranges = spyOn(hooks, "replaceGroups"); + const ranges = spyOn(TrackSubscriber.prototype, "withRange"); try { sub.serve(0); await sub.parked; @@ -1179,7 +1183,7 @@ test("lite draft-06: scheduling updates apply while SUBSCRIBE_START is blocked", sub.release(); expect(await sub.servedSequence()).toBe(0); while (ranges.mock.calls.length === 0) await flush(); - expect(lastGroups(ranges)).toEqual({ start: undefined, end: { included: 5 } }); + expect(lastGroups(ranges)).toEqual({ start: { included: 0 }, end: { included: 5 } }); } finally { ranges.mockRestore(); sub.release(); diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index c9e64cc4336..d93bb3ca1fc 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -10,13 +10,14 @@ import * as DatagramStream from "../datagram_stream.ts"; import { error, NotFound, ProtocolViolation, reason, StreamCode, StreamError, unauthorized } from "../error.ts"; import type * as group from "../group.ts"; import { Cost, type Hop, type Route, routesEqual } from "../hop.ts"; -import { finalSequence, hiddenBelow, hooks, insertRun, presented, type Run, runGaps } from "../internal.ts"; +import { hiddenBelow, hooks, insertRun, presented, type Run, runGaps } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; import { Priority, sendOrder } from "../priority.ts"; import { type Reader, type Stream, Writer } from "../stream.ts"; import { type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; +import { finalSequence } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Interests, LIMITS, type Limits, Slots } from "../util/limits.ts"; import { nextTask } from "../util/yield.ts"; @@ -137,7 +138,7 @@ type FrameBounds = { * The frames of `sequence` a subscription asked for, as a start index and an inclusive end. * * The frame bounds qualify the start and end group only; every other group is served whole. - * Which groups are served at all is the subscriber's read cursor (`replaceGroups`), + * Which groups are served at all is the subscriber's read cursor (`withRange`), * applied when a group is popped rather than re-checked here. * * The serving loop calls this synchronously after the pop, before any SUBSCRIBE_UPDATE can @@ -315,7 +316,7 @@ function waitForSubscription( for (const close of dispose) close(); resolve(); }; - dispose.push(controls.changed(wake), hooks.groupChanged(subscriber, wake)); + dispose.push(controls.changed(wake), subscriber.groupChanged(wake)); dispose.push(drops.changed(wake)); }); } @@ -338,10 +339,10 @@ function carriesMaxDelay(version: Version): boolean { } /** - * Position a subscription's read cursor for the wire serving it. + * The floor of a subscription's read cursor for the wire serving it. * - * On lite-06 there is nothing to do: the cursor is floored at the group the subscription - * named (or 0), and its max delay decides what above the floor is worth delivering. + * On lite-06 it is the group the subscription named (or 0), and its max delay decides what + * above the floor is worth delivering. * * Pre-06 wires are the exception: their drafts define an absent `Group Start` as the * latest group, so say so explicitly rather than letting the budget reach back. Lite-03/04/05 @@ -349,11 +350,10 @@ function carriesMaxDelay(version: Version): boolean { * an unbounded budget so nothing is dropped under them (see {@link servingMaxDelay}), which * must not read as a request to replay the whole cache on join. */ -function positionCursor(track: track.Subscriber, version: Version, startGroup: number | undefined) { - if (resolvesStart(version) || startGroup !== undefined) return; - - const latest = hooks.latestSequence(track); - if (latest !== undefined) hooks.replaceGroups(track, { start: { included: latest } }); +function cursorFloor(version: Version, startGroup: number | undefined, latest: number | undefined): number { + if (startGroup !== undefined) return startGroup; + if (resolvesStart(version)) return 0; + return latest ?? 0; } /** @@ -827,7 +827,7 @@ export class Publisher { } const endGroup = exclusiveGroupEnd(msg.endGroup); - const track = wireOf(front).subscribe(msg.track, { + const track = front.track(msg.track).subscribe({ priority: msg.priority, order: msg.order, maxDelay: Milli(servingMaxDelay(this.version, msg.maxDelay)), @@ -837,8 +837,11 @@ export class Publisher { }, }); serving(track); - positionCursor(track, this.version, msg.startGroup); - hooks.replaceGroups(track, { end: endGroup === undefined ? undefined : { excluded: endGroup } }); + const floor = cursorFloor(this.version, msg.startGroup, hooks.latestSequence(track)); + track.withRange({ + start: { included: floor }, + end: endGroup === undefined ? undefined : { excluded: endGroup }, + }); // The best-effort datagram loop, started once serving begins. It parks when the // track finishes (recvDatagram returns undefined), so #runTrack alone ends the @@ -915,6 +918,7 @@ export class Publisher { broadcast: msg.broadcast, timescale, served, + floor, bounds: { startGroup: msg.startGroup, startFrame: msg.startFrame, @@ -1030,7 +1034,7 @@ export class Publisher { hold.abort(); } // A group that has not arrived yet holds this FETCH's slot until the requester leaves. - group = await wireOf(front).fetchGroup(msg.track, msg.group, { + group = await front.track(msg.track).fetchGroup(msg.group, { priority: msg.priority, maxDelay: msg.maxDelay, signal: left.signal, @@ -1083,10 +1087,25 @@ export class Publisher { broadcast: Path.Valid; timescale: Timescale | undefined; served: Run[] | undefined; + // The read cursor's floor; see {@link cursorFloor}. + floor: number; bounds: FrameBounds; }, ): Promise { const { sub, broadcast, timescale, served, bounds } = serving; + // The read cursor's floor, assigned with the cap in {@link bounds} on every move. + let floor = serving.floor; + const moveCursor = () => + track.withRange({ + start: { included: floor }, + end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, + }); + // Raise the floor to `start`, keeping any higher floor already set. + const raiseFloor = (start: number) => { + if (start <= floor) return; + floor = start; + moveCursor(); + }; // Lite-05+ resolves the range on the subscribe stream: SUBSCRIBE_START once the // first group is known, SUBSCRIBE_END when the track finishes. const emitRange = hasTrackStream(this.version); @@ -1170,33 +1189,33 @@ export class Publisher { case "update": { const update = control.update; console.debug(`subscribe update: broadcast=${broadcast} track=${track.name}`); - // `positionCursor` pins an unfloored pre-06 SUBSCRIBE to the latest + // `cursorFloor` pins an unfloored pre-06 SUBSCRIBE to the latest // group, so an update that drops a named floor re-pins there too. On // an empty track the next group is the latest, whatever its sequence. + // Lite-06 encodes an absent start as no floor, so it drops back to 0: + // the cursor only rises on its own, and a finished group below the old + // floor (a quiet catalog) is never served otherwise. const requested = bounds.startGroup; const start = update.startGroup === undefined && requested !== undefined && !resolvesStart(this.version) ? (hooks.latestSequence(track) ?? 0) - : update.startGroup; - hooks.replaceGroups(track, { - start: start === undefined ? undefined : { included: start }, - end: update.endGroup === undefined ? undefined : { included: update.endGroup }, - }); - // Lite-06 encodes an absent start as no floor, so it drops back to 0. - const floor = start ?? (resolvesStart(this.version) ? 0 : undefined); - // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. - if (floor !== undefined && startSequence !== undefined) { - // A lowered floor owes the groups it newly asks for, so the end sweep covers them. - // A raised one sends no early drop: the subscriber already stops owing below - // its floor, and a later update may lower it again to reopen those groups. - startSequence = Math.min(startSequence, floor); + : (update.startGroup ?? (resolvesStart(this.version) ? 0 : undefined)); + if (start !== undefined) { + floor = start; + // Before SUBSCRIBE_START nothing is owed yet; the start accounts for it. + // A lowered floor owes the groups it newly asks for, so the end sweep + // covers them. A raised one sends no early drop: the subscriber already + // stops owing below its floor, and a later update may lower it again to + // reopen those groups. + if (startSequence !== undefined) startSequence = Math.min(startSequence, start); } bounds.startGroup = update.startGroup; bounds.startFrame = update.startFrame; bounds.endGroup = update.endGroup; bounds.endFrame = update.endFrame; + moveCursor(); // A microtask is too short: decoding one framed update crosses several // awaits, each of which can requeue behind the serving continuation. A // task boundary lets the decoder finish whatever the transport already @@ -1217,7 +1236,7 @@ export class Publisher { !startSent && hasLargest(this.version) ? newer(hooks.bufferedLargest(track), hooks.peekLargest(track).largest) : undefined; - const recv = hooks.tryRecvGroup(track, startSent); + const recv = track.tryRecvGroup({ drops: startSent }); switch (recv.kind) { case "error": throw recv.error; @@ -1238,10 +1257,7 @@ export class Publisher { ) { startSent = true; startSequence = bounds.startGroup; - hooks.replaceGroups(track, { - start: { included: bounds.startGroup }, - end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, - }); + raiseFloor(bounds.startGroup); const start = new SubscribeStart(bounds.startGroup, largest); if ( !(await controls.response(encodeSubscribeResponse(stream, { start }, this.version))) @@ -1302,12 +1318,7 @@ export class Publisher { // A pre-06 subscribe that named no group is the exception: an absent // Group Start is the latest group, and this sequence becomes the floor. // Lite-06 encodes a floor of group 0 as 0, so an omitted start is not pinned. - if (bounds.startGroup === undefined && !resolvesStart(this.version)) { - hooks.replaceGroups(track, { - start: { included: group.sequence }, - end: bounds.endGroup === undefined ? undefined : { included: bounds.endGroup }, - }); - } + if (bounds.startGroup === undefined && !resolvesStart(this.version)) raiseFloor(group.sequence); if ( !(await controls.response( encodeSubscribeResponse( @@ -1433,7 +1444,7 @@ export class Publisher { if (!entry || entry.release.signal.aborted) { const release = new AbortController(); const info = (async () => { - const info = await wireOf(front).resolveTrackInfo(track, release.signal); + const info = await front.track(track).info({ hold: release.signal }); return new TrackInfoMessage({ priority: info.priority, refresh: info.refresh, diff --git a/js/net/src/lite/subscribe.ts b/js/net/src/lite/subscribe.ts index b2a6903997d..ce6ddb9111b 100644 --- a/js/net/src/lite/subscribe.ts +++ b/js/net/src/lite/subscribe.ts @@ -146,7 +146,7 @@ async function encodeOrder(w: Writer, version: Version, order: Order) { /** * Exclusive model/local cap from a decoded inclusive last group. * - * The wire's `Group End` is inclusive once decoded; the track model and `setGroups` are + * The wire's `Group End` is inclusive once decoded; the track model and `withRange` are * exclusive. `undefined` stays unbounded. */ export function exclusiveGroupEnd(inclusive?: number): number | undefined { diff --git a/js/net/src/resume.test-util.ts b/js/net/src/resume.test-util.ts index 8599606f7fb..da067f73a68 100644 --- a/js/net/src/resume.test-util.ts +++ b/js/net/src/resume.test-util.ts @@ -12,9 +12,7 @@ export function readsFrom(active: BroadcastConsumer | undefined, source: Broadca group.close(); const sub = active.track(name).subscribe(); try { - return sub.tryRecvGroup() !== undefined; - } catch { - return false; + return sub.tryRecvGroup().kind === "group"; } finally { sub.close(); track.close(); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 0693e5bbbe9..207b9d1b60f 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -3,7 +3,7 @@ import { Milli } from "@moq/clock"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import * as Epoch from "./epoch.ts"; import { NotFound, StreamCode, StreamError } from "./error.ts"; -import { Producer as GroupProducer } from "./group.ts"; +import { type Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import { Route } from "./hop.ts"; import { hooks } from "./internal.ts"; import { Producer } from "./origin.ts"; @@ -18,6 +18,12 @@ const path = Path.from("live"); const enc = new TextEncoder(); const dec = new TextDecoder(); +/** The group a non-blocking read took, if any, throwing the track's error. */ +function taken(recv: track.Recv): GroupConsumer | undefined { + if (recv.kind === "error") throw recv.error; + return recv.kind === "group" ? recv.group : undefined; +} + async function settle() { await new Promise((resolve) => setTimeout(resolve, 0)); } @@ -61,7 +67,7 @@ function copy(source: BroadcastProducer) { /** Every group sequence readable without waiting. */ function drain(sub: track.Subscriber): number[] { const sequences: number[] = []; - for (let group = sub.tryRecvGroup(); group; group = sub.tryRecvGroup()) { + for (let group = taken(sub.tryRecvGroup()); group; group = taken(sub.tryRecvGroup())) { sequences.push(group.sequence); group.close(); } @@ -253,7 +259,7 @@ test("a stalled group continues from the replacement at the next frame", async ( const tb = copy(b); const sub = active.track("seq").subscribe(); ta.write(0, 1, false); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -274,7 +280,7 @@ test("a group whose route fails continues from the replacement", async () => { const tb = copy(b); const sub = active.track("seq").subscribe(); const stalled = ta.write(0, 1, false); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -296,7 +302,7 @@ test("a group no route continues is given up once a newer one supersedes it", as const tb = copy(b); const sub = active.track("seq").subscribe(); const stalled = ta.write(0, 1, false); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); await group.readFrame(); @@ -323,7 +329,7 @@ test("a replacement claiming different track properties is refused once the old // The old copy failing with its route is what ends the track. old.close(new StreamError(StreamCode.SessionClosed)); await settle(); - expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); + expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); sub.close(); close(); @@ -576,7 +582,7 @@ test("a replacement spliced before the first copy answers is still checked again old.close(new StreamError(StreamCode.SessionClosed)); await settle(); - expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); + expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); sub.close(); front.consumer.close(); @@ -625,7 +631,7 @@ test("a late subscriber's first route is checked against properties an earlier s front.serve(b.consume()); const sub = front.consumer.track("seq").subscribe(); await settle(); - expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); + expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); sub.close(); front.consumer.close(); @@ -644,7 +650,7 @@ test("a recovery fetch a later route supersedes is abandoned", async () => { const stalled = ta.write(0, 1, false); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -733,7 +739,7 @@ test("a failed group on a route whose replacement was refused ends with the refu const stalled = new GroupProducer(0); ta.writeGroup(stalled); stalled.writeFrame({ payload: enc.encode("0.0") }); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); await group.readFrame(); await sub.info(); @@ -1100,7 +1106,7 @@ test("a group handed out already failed with its route still continues on the ne // The old route fails group 0 before the reader takes it. const failed = ta.write(0, 1, false); failed.close(new StreamError(StreamCode.SessionClosed)); - const group = sub.tryRecvGroup(); + const group = taken(sub.tryRecvGroup()); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); const read = group.readFrame(); @@ -1293,13 +1299,13 @@ test("the largest honours the reader's bounds on the serving copy", async () => const capped = front.consumer .track("seq") .subscribe() - .withGroups({ end: { excluded: 3 } }); + .withRange({ end: { excluded: 3 } }); const floored = front.consumer.track("seq").subscribe({ groups: { start: { included: 8 } } }); for (let sequence = 0; sequence < 5; sequence++) ta.write(sequence); const next = capped.largest(); expect(await isPending(next)).toBe(true); - capped.setGroups({}); + capped.withRange({}); expect(await next).toEqual({ group: 4, frame: 0 }); const floor = floored.largest(); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index afc76f21b2b..6a34d7d9d8f 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -33,7 +33,6 @@ import { type GroupRecover, groupBounds, hooks, - type Recv, type RecvDatagram, type Replacement, type ResumeShell, @@ -234,8 +233,8 @@ function subscribe(wire: BroadcastWire, name: string, subscription: track.Subscr } /** Take a copy's next group, in sequence or arrival order. */ -function take(copy: Copy, ordered: boolean): Recv { - return ordered ? hooks.tryNextGroup(copy.sub) : hooks.tryRecvGroup(copy.sub, false); +function take(copy: Copy, ordered: boolean): track.Recv { + return ordered ? hooks.tryNextGroup(copy.sub) : copy.sub.tryRecvGroup(); } /** The first group past where `copy` was replaced: 0 for one replaced before any group. */ @@ -369,7 +368,7 @@ class Reader implements ResumeSource { const start = Math.max(cursor.start, copy.floor ?? 0); const replaced = copyEnd(copy); const end = replaced === undefined ? cursor.end : Math.min(cursor.end ?? replaced, replaced); - hooks.replaceGroups(copy.sub, { + copy.sub.withRange({ start: { included: start }, end: end === undefined ? undefined : { excluded: end }, }); @@ -417,7 +416,7 @@ class Reader implements ResumeSource { return (end === undefined || sequence < end) && !delivered.has(sequence); } - tryGroup(ordered: boolean, delivered: Delivered): Recv { + tryGroup(ordered: boolean, delivered: Delivered): track.Recv { this.sync(); // The lowest group any copy holds next, in either order: a replaced copy's buffered group // comes before a later one the serving copy already has. Arrival order still delivers a @@ -510,7 +509,7 @@ class Reader implements ResumeSource { #end( channel: "groups" | "datagrams", done: (copy: Copy) => Error | null | undefined, - ): Recv & { kind: "idle" | "done" | "error" } { + ): track.Recv & { kind: "idle" | "done" | "error" } { const route = this.route; const last = this.#copies.at(-1); const serving = last?.generation === this.#generation ? last : undefined; @@ -535,7 +534,7 @@ class Reader implements ResumeSource { // End the logical track on a failure, or cleanly once both channels drained: groups and // datagrams end apart, and one running out leaves the other's backlog readable. - #finish(end: T, channel: "groups" | "datagrams"): T { + #finish(end: T, channel: "groups" | "datagrams"): T { if (end.kind === "error") { this.#shell.close(end.error); return end; @@ -597,7 +596,7 @@ class Reader implements ResumeSource { }; disposes.push(this.route.changed.changed(once), this.#changed.changed(once)); for (const copy of this.#copies) - disposes.push(hooks.groupChanged(copy.sub, once), hooks.datagramChanged(copy.sub, once)); + disposes.push(copy.sub.groupChanged(once), hooks.datagramChanged(copy.sub, once)); return dispose; } diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index e5929cce134..39241f1d445 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2,16 +2,22 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import { ProtocolViolation, StreamCode, TimestampMismatch, TooFarBehind } from "./error.ts"; -import { Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; +import { type Consumer as GroupConsumer, Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; -import { infoDefaults, type Subscription, Producer as TrackProducer } from "./track.ts"; +import { infoDefaults, type Recv, type Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); +/** The group a non-blocking read took, if any, throwing the track's error. */ +function taken(recv: Recv): GroupConsumer | undefined { + if (recv.kind === "error") throw recv.error; + return recv.kind === "group" ? recv.group : undefined; +} + // Matches the private idle cache window and Rust cache::DEFAULT_EXPIRY. const CACHE_WINDOW_MS = 30_000; @@ -239,8 +245,7 @@ test("appendDatagram delivers to a subscriber", async () => { // range is what dropped the others. test("the group range bounds datagrams", async () => { const producer = new TrackProducer("test"); - const track = producer.subscribe({ groups: { start: { included: 5 } } }); - track.setGroups({ end: { excluded: 7 } }); + const track = producer.subscribe().withRange({ start: { included: 5 }, end: { excluded: 7 } }); for (const sequence of [4, 5, 7, 6]) { producer.insertDatagram(sequence, Timestamp.fromMillis(0), enc.encode("x")); } @@ -1207,7 +1212,7 @@ test("a parked read wakes at its wall deadline", async () => { const track = producer.subscribe({ maxDelay: Milli(1000) }); const held = producer.appendGroup(); held.writeFrame({ payload: enc.encode("x"), timestamp: timescale && Timestamp.fromMillis(0) }); - const group = track.tryRecvGroup(); + const group = taken(track.tryRecvGroup()); if (!group) throw new Error("missing group"); expect(await group.readString()).toBe("x"); @@ -1273,8 +1278,8 @@ test("a live track retains its newest closed group through idle expiry", async ( } await clock.advance(10_000 + CACHE_WINDOW_MS + 200); const replay = producer.subscribe({ maxDelay: Milli(100) }); - expect(replay.tryRecvGroup()?.sequence).toBe(2); - expect(replay.tryRecvGroup()).toBeUndefined(); + expect(taken(replay.tryRecvGroup())?.sequence).toBe(2); + expect(taken(replay.tryRecvGroup())).toBeUndefined(); replay.close(); } finally { producer.close(); @@ -1526,11 +1531,11 @@ test("an aborted live-edge anchor does not make older content stale", async () = track.close(); }); -test("setGroups with an excluded end of 0 is the empty range and does not ride another subscriber's demand", async () => { +test("withRange with an excluded end of 0 is the empty range and does not ride another subscriber's demand", async () => { const producer = new TrackProducer("test"); const everything = producer.subscribe({ maxDelay: Milli(5000) }); const empty = producer.subscribe({ maxDelay: Milli(5000), groups: { end: { excluded: 0 } } }); - empty.setGroups({ end: { excluded: 0 } }); + empty.withRange({ end: { excluded: 0 } }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); @@ -1538,34 +1543,34 @@ test("setGroups with an excluded end of 0 is the empty range and does not ride a const pending = empty.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - empty.setGroups({ end: { excluded: 2 } }); + empty.withRange({ end: { excluded: 2 } }); expect((await pending)?.sequence).toBe(0); expect((await empty.recvGroup())?.sequence).toBe(1); - empty.setGroups({}); + empty.withRange({}); expect((await empty.recvGroup())?.sequence).toBe(2); }); -test("setGroups caps the live edge used by the latency budget", async () => { +test("withRange caps the live edge used by the latency budget", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); for (const timestamp of [0, 1000, 2000]) { producer.writeFrame({ payload: enc.encode(`${timestamp}`), timestamp: Timestamp.fromMillis(timestamp) }); } expect((await track.recvGroup())?.sequence).toBe(1); - track.setGroups({}); + track.withRange({}); expect((await track.recvGroup())?.sequence).toBe(2); }); // The frame helpers ride the group cursor, so its bounds apply to them too: a group // above the cap parks (surviving a clean close) until the cap admits it. -test("setGroups caps frame-level reads like the group cursor", async () => { +test("withRange caps frame-level reads like the group cursor", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeFrame({ payload: enc.encode("zero"), timestamp: Timestamp.fromMillis(0) }); producer.writeFrame({ payload: enc.encode("one"), timestamp: Timestamp.fromMillis(1) }); @@ -1579,7 +1584,7 @@ test("setGroups caps frame-level reads like the group cursor", async () => { expect(await Promise.race([parked, timeout])).toBe("pending"); // Raising the cap releases the parked group, frames intact. - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await parked)?.group).toBe(1); expect(await track.readFrame()).toBeUndefined(); }); @@ -1590,16 +1595,14 @@ test("local cursor bounds can skip, pause, and release buffered groups", async ( for (let sequence = 0; sequence < 5; sequence++) producer.writeGroup(new GroupProducer(sequence)); - track.setGroups({ start: { included: 1 } }); - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ start: { included: 1 }, end: { excluded: 3 } }); expect((await track.nextGroup())?.sequence).toBe(1); expect((await track.nextGroup())?.sequence).toBe(2); const pending = track.nextGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ start: { included: 4 } }); - track.setGroups({ end: { excluded: 5 } }); + track.withRange({ start: { included: 4 }, end: { excluded: 5 } }); expect((await pending)?.sequence).toBe(4); }); @@ -1623,15 +1626,15 @@ test("recvGroup serves a late arrival after a newer group", async () => { expect(await track.recvGroup()).toBeUndefined(); }); -// recvGroup honors the setGroups cap by parking, like nextGroup: beyond-cap groups are +// recvGroup honors the withRange cap by parking, like nextGroup: beyond-cap groups are // held, not dropped, and a raised cap re-offers them, even after a clean close. -test("setGroups parks recvGroup beyond the cap and a raised cap re-offers", async () => { +test("withRange parks recvGroup beyond the cap and a raised cap re-offers", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); for (let sequence = 0; sequence < 3; sequence++) producer.writeGroup(new GroupProducer(sequence)); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await track.recvGroup())?.sequence).toBe(0); expect((await track.recvGroup())?.sequence).toBe(1); @@ -1644,7 +1647,7 @@ test("setGroups parks recvGroup beyond the cap and a raised cap re-offers", asyn "parked", ); - track.setGroups({}); + track.withRange({}); expect((await pending)?.sequence).toBe(2); expect(await track.recvGroup()).toBeUndefined(); }); @@ -1655,7 +1658,7 @@ test("recvGroup serves in-range groups that arrive behind a capped one", async ( const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); // Reordered burst: the beyond-cap group arrives first. producer.writeGroup(new GroupProducer(2)); @@ -1668,23 +1671,22 @@ test("recvGroup serves in-range groups that arrive behind a capped one", async ( const pending = track.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ end: { excluded: 3 } }); expect((await pending)?.sequence).toBe(2); }); -// A raised setGroups drops parked groups it overtook instead of re-offering them -// once the cap rises. -test("setGroups drops groups recvGroup parked at the cap", async () => { +// A raised floor drops parked groups it overtook instead of re-offering them once the cap +// rises. +test("withRange drops groups recvGroup parked at the cap", async () => { const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); - track.setGroups({ start: { included: 2 } }); - track.setGroups({}); + track.withRange({ start: { included: 2 } }); producer.writeGroup(new GroupProducer(2)); // The overtaken parked group is dropped, not re-offered. @@ -1729,7 +1731,7 @@ test("closing the subscriber releases a recvGroup parked after a clean close", a const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); @@ -1746,7 +1748,7 @@ test("closing the subscriber releases a recvGroup parked while the producer is l const producer = new TrackProducer("test"); const track = producer.subscribe(); - track.setGroups({ end: { excluded: 1 } }); + track.withRange({ end: { excluded: 1 } }); producer.writeGroup(new GroupProducer(1)); const pending = track.recvGroup(); @@ -1832,7 +1834,7 @@ test("a closed track still delivers a group parked above the cap once the cap is producer.writeGroup(group); } - track.setGroups({ end: { excluded: 2 } }); + track.withRange({ end: { excluded: 2 } }); expect((await track.nextGroup())?.sequence).toBe(0); expect((await track.nextGroup())?.sequence).toBe(1); @@ -1843,7 +1845,7 @@ test("a closed track still delivers a group parked above the cap once the cap is expect(await Promise.race([parked, timeout])).toBe("pending"); // Raising the cap after close releases the buffered group, frames intact. - track.setGroups({ end: { excluded: 3 } }); + track.withRange({ end: { excluded: 3 } }); const released = await parked; expect(released?.sequence).toBe(2); expect(await released?.readString()).toBe("frame-2"); @@ -2052,17 +2054,17 @@ test("largest reports only within the bounds", async () => { const producer = new TrackProducer("test").accept({}); for (let sequence = 0; sequence < 6; sequence++) framedGroup(producer, sequence, 2); - const capped = producer.subscribe().withGroups({ end: { excluded: 3 } }); + const capped = producer.subscribe().withRange({ end: { excluded: 3 } }); expect(await isPending(capped.largest())).toBe(true); // An inclusive cap reports the group it names. const ordered = producer .subscribe() .ordered() - .withGroups({ end: { included: 5 } }); + .withRange({ end: { included: 5 } }); expect(await ordered.largest()).toEqual({ group: 5, frame: 1 }); - const floored = producer.subscribe().withGroups({ start: { included: 8 } }); + const floored = producer.subscribe().withRange({ start: { included: 8 } }); const next = floored.largest(); expect(await isPending(next)).toBe(true); framedGroup(producer, 8, 0); @@ -2079,23 +2081,23 @@ test("largest follows the bounds as they move", async () => { const reader = producer .subscribe() .ordered() - .withGroups({ end: { excluded: 3 } }); + .withRange({ end: { excluded: 3 } }); let next = reader.largest(); expect(await isPending(next)).toBe(true); - reader.setGroups({}); + reader.withRange({}); expect(await next).toEqual({ group: 5, frame: 0 }); next = reader.largest(); expect(await isPending(next)).toBe(true); - reader.setGroups({ end: { excluded: 2 } }); + reader.withRange({ end: { excluded: 2 } }); expect(await isPending(next)).toBe(true); // Lifting it again leaves the last report standing. - reader.setGroups({}); + reader.withRange({}); expect(await isPending(next)).toBe(true); framedGroup(producer, 6, 0); expect(await next).toEqual({ group: 6, frame: 0 }); - reader.setGroups({ start: { included: 3 } }); + reader.withRange({ start: { included: 3 } }); expect(await isPending(reader.largest())).toBe(true); producer.close(); }); @@ -2107,9 +2109,9 @@ test("largest stays ended when the bounds widen", async () => { framedGroup(producer, 5, 1).close(); producer.close(); - const reader = producer.subscribe().withGroups({ end: { excluded: 3 } }); + const reader = producer.subscribe().withRange({ end: { excluded: 3 } }); expect(await reader.largest()).toBeUndefined(); - reader.setGroups({}); + reader.withRange({}); expect(await reader.largest()).toBeUndefined(); }); @@ -2125,7 +2127,7 @@ test("a live-edge reader starts on an empty largest group", async () => { const reader = producer.subscribe({ maxDelay: Milli(30_000) }); const edge = await reader.largest(); expect(edge).toEqual({ group: 1, frame: 0 }); - reader.setGroups({ start: { included: edge?.group ?? 0 } }); + reader.withRange({ start: { included: edge?.group ?? 0 } }); empty.close(); const next = producer.appendGroup(); @@ -2160,40 +2162,43 @@ test("group ranges preserve progress and spell out inclusion", async () => { const producer = new TrackProducer("test"); const track = producer .subscribe({ maxDelay: Milli(5000) }) - .withGroups({ start: { included: 1 }, end: { included: 1 } }); + .withRange({ start: { included: 1 }, end: { included: 1 } }); for (let sequence = 0; sequence < 4; sequence++) producer.writeGroup(new GroupProducer(sequence)); - expect(track.tryRecvGroup()?.sequence).toBe(1); - expect(track.tryRecvGroup()).toBeUndefined(); - track.setGroups({ end: { excluded: 3 } }); - expect(track.tryRecvGroup()?.sequence).toBe(2); - expect(track.tryRecvGroup()).toBeUndefined(); - track.setGroups({ start: { included: 0 } }); - expect(track.tryRecvGroup()?.sequence).toBe(3); + expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + expect(taken(track.tryRecvGroup())).toBeUndefined(); + track.withRange({ start: { included: 1 }, end: { excluded: 3 } }); + expect(taken(track.tryRecvGroup())?.sequence).toBe(2); + expect(taken(track.tryRecvGroup())).toBeUndefined(); + track.withRange({ start: { included: 1 } }); + expect(taken(track.tryRecvGroup())?.sequence).toBe(3); track.close(); }); -test("serving replaceGroups can lower the floor that setGroups keeps", () => { +// Mirrors the Rust `a_lowered_range_reoffers_the_unread_cached_groups`. +test("a lowered range re-offers the unread cached groups", () => { const producer = new TrackProducer("test"); - const kept = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); - const lowered = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); for (const sequence of [5, 6, 10]) producer.writeGroup(new GroupProducer(sequence)); - - kept.setGroups({ start: { included: 5 } }); - expect(kept.tryRecvGroup()?.sequence).toBe(10); - - hooks.replaceGroups(lowered, { start: { included: 5 } }); - expect(lowered.tryRecvGroup()?.sequence).toBe(5); - expect(lowered.tryRecvGroup()?.sequence).toBe(6); - kept.close(); - lowered.close(); + expect(taken(track.tryRecvGroup())?.sequence).toBe(10); + expect(taken(track.tryRecvGroup())).toBeUndefined(); + + track.withRange({ start: { included: 6 } }); + expect(taken(track.tryRecvGroup())?.sequence).toBe(6); + track.withRange({ end: { included: 5 } }); + expect(taken(track.tryRecvGroup())?.sequence).toBe(5); + track.withRange({}); + expect(taken(track.tryRecvGroup())).toBeUndefined(); + producer.writeGroup(new GroupProducer(11)); + expect(taken(track.tryRecvGroup())?.sequence).toBe(11); + track.close(); }); test("malformed group bounds do not partially advance the cursor", () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); producer.writeGroup(new GroupProducer(0)); - expect(() => track.setGroups({ start: { included: 3 }, end: { excluded: -1 } })).toThrow(); - expect(track.tryRecvGroup()?.sequence).toBe(0); + expect(() => track.withRange({ start: { included: 3 }, end: { excluded: -1 } })).toThrow(); + expect(taken(track.tryRecvGroup())?.sequence).toBe(0); track.close(); }); @@ -2354,8 +2359,8 @@ test("an omitted publisher limit still ages idle groups out", async () => { // A scan runs at most once per slice of the window, so step past the next one. clock.set(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); const after = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(after.tryRecvGroup()?.sequence).toBe(1); - expect(after.tryRecvGroup()).toBeUndefined(); + expect(taken(after.tryRecvGroup())?.sequence).toBe(1); + expect(taken(after.tryRecvGroup())).toBeUndefined(); after.close(); } finally { producer.close(); @@ -2376,7 +2381,7 @@ test("a live track does not pin an aborted newest group", () => { clock.set(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); const late = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(late.tryRecvGroup()).toBeUndefined(); + expect(taken(late.tryRecvGroup())).toBeUndefined(); late.close(); } finally { producer.close(); @@ -2402,7 +2407,7 @@ test("closing a track keeps an idle newest group for subscribers to drain", asyn // The close restarted its window, which now runs out like any other. clock.set(10_000 + 2 * (CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8)); const late = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(late.tryRecvGroup()).toBeUndefined(); + expect(taken(late.tryRecvGroup())).toBeUndefined(); late.close(); } finally { clock.restore(); @@ -2511,8 +2516,8 @@ test("an ended track's buffered groups age out for a stale subscriber", async () // Nothing writes after close, so only the scheduled cache cleanup runs. await clock.advance(10_000 + CACHE_WINDOW_MS + 100); - if (abort) expect(() => stale.tryRecvGroup()).toThrow(abort); - else expect(stale.tryRecvGroup()).toBeUndefined(); + if (abort) expect(() => taken(stale.tryRecvGroup())).toThrow(abort); + else expect(taken(stale.tryRecvGroup())).toBeUndefined(); } finally { producer.close(); clock.restore(); @@ -2537,9 +2542,10 @@ test("an abort leaves a group already taken readable, then reports the abort", a }); /** Every group a subscriber can take right now, by sequence. */ -function drain(track: { tryRecvGroup(): { sequence: number } | undefined }): number[] { +function drain(track: { tryRecvGroup(): Recv }): number[] { const sequences: number[] = []; - for (let group = track.tryRecvGroup(); group; group = track.tryRecvGroup()) sequences.push(group.sequence); + for (let group = taken(track.tryRecvGroup()); group; group = taken(track.tryRecvGroup())) + sequences.push(group.sequence); return sequences; } @@ -2651,7 +2657,7 @@ test("an untimed subscriber without a start begins at the latest group under its const producer = untimedTrack(5); // As the lite publisher serves a SUBSCRIBE with an end and no start. const subscriber = producer.subscribe({ groups: { end: { excluded: 3 } } }); - subscriber.setGroups({ end: { excluded: 3 } }); + subscriber.withRange({ end: { excluded: 3 } }); expect(drain(subscriber)).toEqual([2]); }); @@ -2677,7 +2683,7 @@ test("a single-frame write that throws aborts its group", () => { producer.writeFrame({ payload: enc.encode("y") }); // The failed group ends in that error instead of leaving a reader waiting on it. - const failed = subscriber.tryRecvGroup(); + const failed = taken(subscriber.tryRecvGroup()); expect(failed?.sequence).toBe(0); expect(failed?.closed.peek()).toBeInstanceOf(TimestampMismatch); expect(drain(subscriber)).toEqual([1]); @@ -2698,13 +2704,13 @@ test("explicit and producer-cut drops survive outside the group cache", async () const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); hooks.dropTrackGroups(producer, 3, 4); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 3, end: 4 }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 3, end: 4 }); const group = new GroupProducer(4); producer.writeGroup(group); group.close(new Error("cut")); await settle(); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 4, end: 5 }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 4, end: 5 }); reader.close(); producer.close(); @@ -2714,10 +2720,10 @@ test("a drop below the window is reported once the window lowers to it", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000), groups: { start: { included: 5 } } }); hooks.dropTrackGroups(producer, 2, 3); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "idle" }); - hooks.replaceGroups(reader, { start: { included: 0 } }); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 3 }); + reader.withRange({ start: { included: 0 } }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 2, end: 3 }); reader.close(); producer.close(); @@ -2734,7 +2740,7 @@ test("a re-created cut group is served, not dropped", async () => { const retry = new GroupProducer(4); producer.writeGroup(retry); await settle(); - const recv = hooks.tryRecvGroup(reader, true); + const recv = reader.tryRecvGroup({ drops: true }); expect(recv.kind === "group" ? recv.group.sequence : recv).toBe(4); reader.close(); @@ -2745,13 +2751,13 @@ test("a wide drop is held and reported as one run", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); hooks.dropTrackGroups(producer, 2, 2 ** 40); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 2 ** 40 }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 2, end: 2 ** 40 }); // A wider drop reports only what this cursor has not reported yet. hooks.dropTrackGroups(producer, 1, 2 ** 40 + 2); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 1, end: 2 }); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2 ** 40, end: 2 ** 40 + 2 }); - expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 1, end: 2 }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 2 ** 40, end: 2 ** 40 + 2 }); + expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "idle" }); reader.close(); producer.close(); @@ -2770,7 +2776,7 @@ test("a mid-group end survives eviction and a filtered late reader", async () => await clock.advance(10_000 + CACHE_WINDOW_MS + 1); expect(await producer.subscribe().largest()).toEqual({ group: 5, frame: 4 }); // The cap excludes the only group, so nothing is within it. - const reader = producer.subscribe().withGroups({ end: { excluded: 5 } }); + const reader = producer.subscribe().withRange({ end: { excluded: 5 } }); expect(await reader.largest()).toBeUndefined(); expect(reader.end()).toEqual({ group: 5, frame: 5 }); reader.close(); @@ -2848,7 +2854,7 @@ function stampGroup(producer: TrackProducer, sequence: number, ms: number): Grou function drainGroups(subscriber: ReturnType): number[] { const sequences: number[] = []; - for (let group = subscriber.tryRecvGroup(); group; group = subscriber.tryRecvGroup()) + for (let group = taken(subscriber.tryRecvGroup()); group; group = taken(subscriber.tryRecvGroup())) sequences.push(group.sequence); return sequences; } @@ -3211,7 +3217,7 @@ test("an evicted group still fills a pending tail", async () => { clock.set(CACHE_WINDOW_MS + 1000); write(2); // A late subscriber replays only what the cache still holds. - expect(producer.subscribe({ maxDelay: Milli(60_000) }).tryRecvGroup()?.sequence).toBe(2); + expect(taken(producer.subscribe({ maxDelay: Milli(60_000) }).tryRecvGroup())?.sequence).toBe(2); expect((await reader.recvGroup())?.sequence).toBe(2); expect(await reader.recvGroup()).toBeUndefined(); producer.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index d6f11592e30..42d61d95e28 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -11,11 +11,9 @@ import { Delivered } from "./delivered.ts"; import { GroupTooLarge, ProtocolViolation, TimestampMismatch, TooFarBehind } from "./error.ts"; import { type Frame, type Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import { - finalSequence, groupBounds, hooks, insertRun, - type Recv, type RecvDatagram, type ResumeSource, type Run, @@ -31,6 +29,29 @@ import { type Broadcast as BroadcastWire, registerTrackConsumer } from "./wire.t export type { Datagram } from "./datagram.ts"; +/** The first group an exclusive track end excludes whole: one past the last group that may exist. */ +export function finalSequence(end: Location): number { + return end.group + (end.frame === 0 ? 0 : 1); +} + +/** + * What a non-blocking group read found, which is everything the caller needs to decide what + * to do next: no second look at the track's closed state, and no ordering rule to get wrong. + */ +export type Recv = + /** A group to serve. It has already left the buffer, so dropping this is dropping the group. */ + | { kind: "group"; group: GroupConsumer } + /** Sequences `[start, end)` this cursor gave up without serving. */ + | { kind: "drop"; start: number; end: number } + /** Nothing readable, but the track is live and may produce more. */ + | { kind: "idle" } + /** The producer finished, yet groups above the cap are still held: raising it releases them. */ + | { kind: "boundary" } + /** The producer finished and the buffer is drained. Nothing can follow. */ + | { kind: "done" } + /** The track aborted. */ + | { kind: "error"; error: Error }; + // Wall-clock bound for idle cached content, matching Rust cache::DEFAULT_EXPIRY. // Media maxDelay only bounds how far behind the live edge a reader may fall. const CACHE_WINDOW = Nano.fromMilli(Milli(30_000)); @@ -380,9 +401,15 @@ export class Consumer { return this.#broadcast.subscribe(this.name, options); } - /** Fetch the track's immutable publisher properties without subscribing. */ - info(): Promise { - return this.#broadcast.resolveTrackInfo(this.name); + /** + * Fetch the track's immutable publisher properties without subscribing. + * + * A pending lookup keeps the track wanted. With `hold`, it stays wanted until `hold` aborts, + * as a held Rust `query` does, so a publisher can keep a track alive while it answers for + * it; aborting before the answer abandons the lookup. + */ + info(options?: { hold?: AbortSignal }): Promise { + return this.#broadcast.resolveTrackInfo(this.name, options?.hold); } /** Fetch a single group by sequence without holding a live subscription. */ @@ -557,6 +584,15 @@ let bindProducerSequence: (producer: Producer, sequence: TrackSequence) => void; let cachedMirror: (producer: Producer, sequence: number) => GroupConsumer | undefined; // Whether the producer still caches a group that has not failed; assigned in its static block. let cachedHolds: (producer: Producer, sequence: number) => boolean; +// Mirror the cached groups in `[start, end)` that `offer` accepts into a sink again, for a +// reader whose floor moved below them; assigned in the producer's static block. +let reofferCached: ( + producer: Producer, + sink: TrackState, + start: number, + end: number, + offer: (sequence: number) => boolean, +) => void; // The sequence-order cursor lives inside `Subscriber` (it shares the group buffer and the // drift anchor with the arrival cursor), so `Ordered` reaches it through this bridge, @@ -564,6 +600,7 @@ let cachedHolds: (producer: Producer, sequence: number) => boolean; let makeOrdered: (subscriber: Subscriber) => Ordered; let ordered_: { nextGroup(subscriber: Subscriber): Promise; + tryNextGroup(subscriber: Subscriber): Recv; readFrame(subscriber: Subscriber): Promise<({ group: number; frame: number } & Frame) | undefined>; readString(subscriber: Subscriber): Promise; readJson(subscriber: Subscriber): Promise; @@ -766,6 +803,15 @@ export class Producer { hooks.arriveGroup(mirror, entry.arrived); return mirror; }; + reofferCached = (producer, sink, start, end, offer) => { + const held = new Set(sink.groups.peek().map((group) => group.sequence)); + for (const entry of producer.#cache) { + const sequence = entry.group.sequence; + if (sequence < start || sequence >= end || held.has(sequence)) continue; + if (entry.group.closed.peek() instanceof Error || !offer(sequence)) continue; + producer.#mirror(entry, sink); + } + }; hooks.dropTrackGroups = (producer, start, end) => producer.#drop(start, end); } @@ -1790,7 +1836,6 @@ export class Subscriber { if (subscriber.#resume) subscriber.#resume.join(); else if (subscriber.#state.producer) hooks.joinProducer(subscriber.#state.producer); }; - hooks.tryRecvGroup = (subscriber, started) => subscriber.#tryRecvGroup(started); hooks.tryNextGroup = (subscriber) => subscriber.#tryNextGroup(); hooks.peekGroup = (subscriber, ordered) => subscriber.#peekGroup(ordered); hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); @@ -1879,15 +1924,14 @@ export class Subscriber { }; return dispose; }; - hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); hooks.fetchBudget = (subscriber, maxDelay) => { subscriber.#fetchBudget = maxDelay ?? Number.POSITIVE_INFINITY; }; - hooks.replaceGroups = (subscriber, groups) => subscriber.#replaceGroups(groups); // The sequence cursor lives here (it shares the buffer and the drift anchor with // the arrival cursor); `Ordered` is the handle that reaches it. ordered_ = { nextGroup: (subscriber) => subscriber.#nextGroup(), + tryNextGroup: (subscriber) => subscriber.#tryNextGroup(), readFrame: (subscriber) => subscriber.#readFrame(), readString: (subscriber) => subscriber.#readString(), readJson: (subscriber) => subscriber.#readJson(), @@ -1957,7 +2001,7 @@ export class Subscriber { } /** - * The largest location within {@link setGroups}: the current one at first, then each newer + * The largest location within {@link withRange}: the current one at first, then each newer * one (skipping any in between), and `undefined` once the track ends. * * The largest is the track's newest group or datagram at the newest frame (0 while empty), as @@ -2032,37 +2076,32 @@ export class Subscriber { return producer.subscribe(options); } - /** Limit subsequent reads to these groups and return this reader for chaining. */ - withGroups(groups: Groups): this { - this.setGroups(groups); - return this; - } - /** - * Limit subsequent reads without rewinding read progress or changing the wire request. - * An omitted start preserves the current floor; an omitted end removes the cap. - * Raising the end makes unread buffered groups available again. - * {@link largest} reports within these bounds. + * Limit subsequent reads to these groups and return this reader for chaining. Mirrors the + * Rust `with_range`. + * + * Both bounds are assigned, in either direction: an omitted start is group 0 and an + * omitted end removes the cap. Lowering the floor or raising the cap offers the groups it + * newly covers that the track still caches and this reader never handed out; a group is + * never handed out twice. A local filter, not a request: it leaves the wire subscription + * alone. {@link largest} reports within these bounds. */ - setGroups(groups: Groups): void { - const { start, end } = groupBounds(groups); - this.#cursor.update((cursor) => ({ start: Math.max(cursor.start, start), end })); - } - - // Serving counterpart of setGroups: a named start replaces the floor, matching - // Rust `start_at`. Local readers stay monotonic; only the wire publisher lowers. - #replaceGroups(groups: Groups): void { + withRange(groups: Groups): this { const { start, end } = groupBounds(groups); - this.#cursor.update((cursor) => ({ - start: groups.start === undefined ? cursor.start : start, - end, - })); + const before = this.#cursor.peek(); + this.#cursor.set({ start, end }); + const producer = this.#state.producer; + if (!this.#resume && producer && start < before.start) { + // The arrival cursor let go of what it passed below the old floor. + reofferCached(producer, this.#state, start, before.start, (sequence) => !this.#delivered.has(sequence)); + } + return this; } /** Close the track (optionally with an error), closing any pending groups. Idempotent. */ close(abort?: Error) { // Settle if we're first (the producer may already have); either way drop anything - // still buffered. Groups parked at the setGroups cap deliberately outlive a clean + // still buffered. Groups parked at the withRange cap deliberately outlive a clean // producer close, so the subscriber leaving is what must release them: closing // and clearing wakes a pending read to observe the end instead of hanging. closeTrackState(this.#state, abort); @@ -2086,7 +2125,7 @@ export class Subscriber { * is still delivered. When several groups are buffered, the lowest sequence is * returned first. * - * Honors the range set by {@link setGroups}: a group + * Honors the range set by {@link withRange}: a group * beyond the cap stays buffered (not dropped) and is offered once the cap rises, even * after a clean close, without blocking in-range groups that arrive behind it. * A group whose presentation time is further behind the live edge than this @@ -2127,8 +2166,7 @@ export class Subscriber { }); } - // Package-internal synchronous half of recvGroup. The lite publisher uses this so applying - // control state, popping the group, and positioning its frames are one JavaScript turn. + // The synchronous half of recvGroup, behind the public tryRecvGroup. #tryRecvGroup(dispositions = false): Recv { if (this.#resume) return this.#tryResumed(false); const groups = this.#state.groups.peek(); @@ -2227,9 +2265,7 @@ export class Subscriber { return end !== undefined && this.#state.received.peek() >= finalSequence(end) && !this.#state.owed.peek(); } - // Package-internal readiness half of recvGroup. Each registration fires at most once, and - // the caller disposes the losers after whichever source wakes it. A declared end wakes it - // too, so a publisher can forward the end before the live edge reaches it. + // The readiness half of recvGroup, behind the public groupChanged. #groupChanged(fn: () => void): Dispose { if (this.#resume) { const resumed = [this.#resume.changed(fn), this.#cursor.changed(fn), this.#state.closed.changed(fn)]; @@ -2252,21 +2288,28 @@ export class Subscriber { } /** - * Take the next buffered group without blocking, honoring the same cursor bounds as - * {@link recvGroup}. + * Take the next group without waiting, honoring the same cursor bounds as + * {@link recvGroup}, or say why there is none. + * + * Synchronous, so a publisher can pop a group and act on it in the same turn. `idle` and + * `boundary` may read differently once {@link groupChanged} fires; `done` and `error` are + * final. With `drops`, each run of sequences the cursor gives up is reported once as a + * `drop`, which a publisher forwards to its peer; without it they pass silently. * - * Returns `undefined` when nothing is deliverable right now, which is not by itself the - * end of the track: a group may still arrive, or one may be parked beyond the - * {@link setGroups} cap. Use it to drain what the retained window already holds, where - * waiting for a sequence nothing will republish would park forever. + * The first call commits this track to arrival order, as {@link recvGroup} does. */ - tryRecvGroup(): GroupConsumer | undefined { + tryRecvGroup(options?: { drops?: boolean }): Recv { this.#live(); this.#mode = "arrival"; - const recv = this.#tryRecvGroup(); - if (recv.kind === "group") return recv.group; - if (recv.kind === "error") throw recv.error; - return undefined; + return this.#tryRecvGroup(options?.drops ?? false); + } + + /** + * Call `fn` once when {@link tryRecvGroup} may read differently, including when the track + * declares its end, and return the disposer. + */ + groupChanged(fn: () => void): Dispose { + return this.#groupChanged(fn); } /** @@ -2555,7 +2598,7 @@ export class Ordered { return this.#subscriber.subscription; } - /** The largest location within {@link setGroups}; see {@link Subscriber.largest}. */ + /** The largest location within {@link withRange}; see {@link Subscriber.largest}. */ largest(): Promise { return this.#subscriber.largest(); } @@ -2570,17 +2613,16 @@ export class Ordered { return this.#subscriber.finished(); } - /** Limit subsequent reads to these groups and return this reader for chaining. */ - withGroups(groups: Groups): this { - this.setGroups(groups); + /** + * Limit subsequent reads to these groups and return this reader for chaining; see + * {@link Subscriber.withRange}. An ordered read never goes back, so lowering the floor + * below a group it already returned offers nothing. + */ + withRange(groups: Groups): this { + this.#subscriber.withRange(groups); return this; } - /** Limit subsequent reads to these groups; see {@link Subscriber.setGroups}. */ - setGroups(groups: Groups): void { - this.#subscriber.setGroups(groups); - } - /** Update this subscription's options; see {@link Subscriber.update}. */ update(options: Subscription) { this.#subscriber.update(options); @@ -2597,12 +2639,20 @@ export class Ordered { * Late arrivals (sequence at or below the last returned) are silently skipped, as is a * group whose every frame is further behind the live edge than `maxDelay` (the default of * zero keeps only what nothing newer has superseded). Honors the bounds set by - * {@link setGroups}. + * {@link withRange}. */ nextGroup(): Promise { return ordered_.nextGroup(this.#subscriber); } + /** + * Take the next group as {@link nextGroup} would without waiting, or say why there is none; + * see {@link Subscriber.tryRecvGroup}. Mirrors the Rust `poll_next_group`. + */ + tryNextGroup(): Recv { + return ordered_.tryNextGroup(this.#subscriber); + } + /** * Read the next frame across groups, in sequence order, with its group and frame numbers. * diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index 1ae5b386c53..a7d68234169 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -19,15 +19,15 @@ import type * as track from "./track.ts"; /** The protocol-facing operations behind a broadcast handle. */ export interface Broadcast { - // pending: /quest/m1/public-model/serve.md + // private: plumbing subscribe(name: string, options?: track.Subscription): track.Subscriber; - // pending: /quest/m1/public-model/serve.md + // private: plumbing /** The track's properties; `hold` keeps the track wanted until it aborts, the way a held TRACK stream does, and aborting it before the answer abandons the lookup. */ resolveTrackInfo(name: string, hold?: AbortSignal): Promise; - // pending: /quest/m1/public-model/serve.md + // pending: /quest/m1/track-live.md /** The newest frame the track's cache holds, read without subscribing; `undefined` while it holds none. */ largest(name: string): track.Location | undefined; - // pending: /quest/m1/public-model/serve.md + // private: plumbing fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise; // pending: /quest/m1/public-model/answer.md requested(): Promise; diff --git a/js/room/src/chat.ts b/js/room/src/chat.ts index d322d4905b8..be7190533ab 100644 --- a/js/room/src/chat.ts +++ b/js/room/src/chat.ts @@ -88,7 +88,7 @@ export class Subscriber { this.#track = track; this.#consumer = new Json.Window.Consumer({ track }); this.#positioned = track.largest().then((largest) => { - if (largest) track.setGroups({ start: { included: largest.group } }); + if (largest) track.withRange({ start: { included: largest.group } }); }); } diff --git a/quest/m1/egress-held-state.md b/quest/m1/egress-held-state.md index d8ec6f65399..f07eca09330 100644 --- a/quest/m1/egress-held-state.md +++ b/quest/m1/egress-held-state.md @@ -114,6 +114,6 @@ none on the wire; possibly a relay default). - [Bound incomplete messages](/quest/m1/quic/receive-memory.md) - the ingress counterpart: a receiver withholds QUIC credit to bound what it holds, and this quest bounds what the sender holds while it does - [Rust request credit](/quest/m1/rs-request-credit.md) - requests fail fast without stream credit; publisher group streams are left to this quest - [Scope track priority](/quest/m1/track-priority-scope.md) - who gets the next stream across subscriptions and tenants -- [Public serving](/quest/m1/public-model/serve.md) - makes group expiry while serving public; coordinate the publisher serve loops with it +- [Public group expiry in JS](/quest/m1/public-model/serve.md) - makes JS group expiry while serving public; coordinate the publisher serve loops with it - [Treat network input as untrusted](https://github.com/moq-dev/moq/pull/5961) - the rule this quest applies - [Resumed group head](https://github.com/moq-dev/moq/pull/5958) - the audit that found this, and bounded held heads by the cache pool diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index 3f5981bacde..b6fd1b95c07 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -102,7 +102,7 @@ Work owned by this README, after the children land: ## Required - [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls -- [Public serving](/quest/m1/public-model/serve.md) - a custom publisher reads a track's start, cursor, and group expiry for its wire through public calls +- [Public group expiry in JS](/quest/m1/public-model/serve.md) - a custom JS publisher learns when a group it is still writing has expired, the last serving item left - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/serve.md b/quest/m1/public-model/serve.md index e08d6b52774..cf0e2e6eaf5 100644 --- a/quest/m1/public-model/serve.md +++ b/quest/m1/public-model/serve.md @@ -1,156 +1,41 @@ -# [L] Public serving +# [S] Public group expiry in JS ## Goal -A custom publisher reads a track for its wire through public moq-net and -@moq/net calls only: where the feed starts, a read cursor its peer can move in -either direction, the track's end in wire terms, and when a group it is still -writing has expired. The built-in lite and IETF publishers use the same calls. +A custom `@moq/net` publisher learns, through public calls, when a group it is +still writing has expired, as the Rust `group::Consumer::poll_expired` already +lets it. The built-in lite and IETF publishers use the same call. ## Plan -Rules, carve-outs, and the inventory method are in the -[epic](/quest/m1/public-model/README.md). Rerun the inventory first; the -recommendations below are the planning quest's, and the ones marked -**decision** were settled by the maintainer on 2026-10-16 (#5717). - -Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: - -- `track::Subscriber::poll_start` (lite publisher): public. A publisher - reports the resolved start to its peer (SUBSCRIBE_START, SUBSCRIBE_OK). -- `track::Subscriber::poll_live` (both publishers): remove the need through - the public `poll_largest` (#5725). It now waits out an idle copy too - (#5924), but it follows the source's reported largest, which can name a - frame the cache does not hold yet, so the publishers still answer with the - buffered edge. A public live signal is - [its own quest](/quest/m1/track-live.md). Decide here whether wire answers move to it, and - with them `latest_sequence` on `track::{Producer,Consumer,Subscriber}`, - the private snapshot that replaced the public `latest()` (#5725). -- **Cursor** (`track::Subscriber::start_at`, `raise_start_to`, `end_at`, - `subscription::Cap`; both publishers). **Decision**: - - ✅ One public consuming builder assigns the floor and the cap in either - direction: `with_range(self, range) -> Self` on `track::Subscriber` and - `track::Ordered` (JS `withRange`), replacing `set_groups` and the - chaining `withGroups`. The maintainer decided "range" on 2026-10-19, - replacing the 2026-10-18 `limit` and the earlier `set_bounds`. Each - reader already hands a sequence out once (#5446), so a SUBSCRIBE_UPDATE - that widens the start re-offers only unread groups. - `start_at`, `raise_start_to`, `end_at`, and `Cap` go. Precondition: - lowering the floor re-offers unread cached groups in every mode. Today - only the resume cursor does; the arrival-order (Plain) cursor walks a - monotonic arrival index, so it must rescan below its old floor for - groups it never handed out. Rewrite the doc ("without rewinding read - progress") to say what lowering does. - - Rebinding: a consuming builder fits readers bounded once at creation, - but these callers move a live reader's bounds through `&mut` today, so - the rename needs a way to rebind (take and replace the reader, or a - crate-private setter the builder wraps): - - `rs/moq-c/src/consume.rs` `RawReader::apply` re-applies the range on - every subscription update, counting a relative start from the track - `Consumer`'s unbounded largest. `set_groups` only raises the floor, so an - update cannot lower a floor an earlier one put above the live edge - (Codex on #5924). Making the floor assign fixes it; land that with a - moq-c test where a later relative update delivers the next group. - - The lite and IETF publishers move the cursor on SUBSCRIBE_UPDATE - (`start_at`, `end_at`; JS `hooks.replaceGroups` and the IETF - publisher's `setGroups({ start })`). - - `js/json` snapshot and `js/flate` `latest()` raise the floor of the same - reader on each read; `js/room` chat sets it after `largest()` resolves. - The snapshot consumers (`js/json/src/snapshot/consumer.ts` `#read`, - `js/flate/src/snapshot/consumer.ts` `latest()`) call - `setGroups({ start: { included: latest.group } })`, whose omitted end - removes the caller's cap. The rebinding must keep that cap; land it with - a regression test where a capped snapshot reader stays below its cap. - A datagram also advances `largest()` past every group, stranding the - read. The Rust consumers instead drain the groups the reader already - has and keep the newest (#5677), which needs no floor at all. - - `rs/moq-hls` export narrows a fetched group with `set_frames(..end)`. - - Readers that set a floor once right after `poll_largest` (moq-audio, - moq-video, moq-cli play, moq-json window, moq-mux) fit the builder. - - ✅ The range floor counts as a local bound (maintainer, 2026-10-19): - `largest()` reports within both the floor and the cap, so a reader whose - floor sits above the live edge reports nothing until a group reaches it - (#5924). - - ✅ `largest()` reports only upstream-confirmed state (maintainer, - 2026-10-19): the source's reported largest and what its live feed - delivered since, never a cache-derived stand-in. It waits while the copy - is idle, though cached groups are still served, and past the cap it - reports nothing rather than the newest cached group below it (#5924). - - A second public `replace_groups`. -- **Bounds naming** (decided 2026-10-16 in #5717, changed to "range" by the - maintainer on 2026-10-19): ✅ the siblings follow: - `Subscription::with_range` replaces `with_groups` as the single-range form - of `with_ranges`, and `group::Consumer::set_frames` becomes the consuming - `with_range`, with the JS mirrors. -- `group::Consumer::start_at`, `end_at` (both publishers): remove the need; - the public `with_range` (today `set_frames`) and `skip_to` cover them. -- `Subscription::{start, end, set_bounds, with_start, with_end}` (both - publishers, IETF subscriber, from #5732): the covering span a wire without - ranges carries. Derive it from the public `ranges` instead, or make it - public. -- `subscription::Position::final_sequence` (lite publisher): public, the - one-line wire translation of an exclusive end that both languages - already duplicate. `track::Consumer::final_sequence` (IETF publisher) goes; - callers read `poll_finished` and translate. -- **Group expiry while writing** (`group::Consumer::poll_expired`, - `poll_expired_while_pending`; both publishers): public as one - `poll_expired`. A publisher that already read frames off a group must - still abandon its stream once the subscription's max delay expires the - group. Fold the `pending` flag in, or keep it private as tuning if it only - saves a poll. -- **Cache peeks** (`track::Consumer::peek_latest`, `peek_before`, - `peek_group`, `is_live`; IETF publisher, for Largest Object and FETCH): - moved to [the deferred quest](/quest/m1/public-model/deferred.md), which - waits on Model ranges. -- Passthrough, stay private and marked: `group::Consumer::wire`, - `end_object`, `last_object`, `first_frame`, `poll_read_object`, - `poll_read_objects`, `frame::Object`, `frame::Consumer::fields`, - `track::Subscriber::poll_recv_wire_datagram`. -- Test-only: `track::Consumer::poll_group`, `resume_position`. - -JS items (`js/net/src/`): - -- `hooks.replaceGroups` (lite publisher): mirror the cursor decision, so - `Track.Subscriber.withRange` assigns the floor and the hook goes. -- `hooks.tryRecvGroup` with its `Recv` union, and `hooks.groupChanged` - (lite publisher). The public `Subscriber.tryRecvGroup()` returns - `undefined` for both a held boundary and a drained end, so a synchronous - publisher cannot tell them apart or park. **Decision**: - - ✅ Public. Return the `Recv` union from the public method and expose - the change wake (a signal or a promise, matching the package's style). - The union deliberately has no Rust type: Rust's lite publisher builds - its private `Recv` from the public `poll_recv_group` (Pending versus - `Ready(None)`) and `poll_finished`, which a third party composes the - same way. - - Mirror Rust exactly: a distinct drained result and a synchronous end - check instead of the union, plus the wake. -- `hooks.guardGroup`, `hooks.readGroupFrame` with `ReadGroupFrame` (both - publishers): mirror the Rust group expiry as one public call. Reading a - frame the publisher `complete()`s holds the group's `closed` until it is - written; keep that behavior behind the public read rather than a second - method if it can be. -- `Track.Subscriber.fork` (`@internal`, IETF publisher fill and cache - reads): moved to the deferred quest with the cache peeks. -- `wire.ts` `Broadcast.subscribe`, `fetchGroup`: remove the need; the public - `Broadcast.Consumer.track(name)` paths cover them. -- `wire.ts` `Broadcast.largest`, `hooks.cachedLargest`, - `hooks.bufferedLargest`, and `hooks.latestSequence`: remove the need through the public `largest()` - stream (#5725), under the same caveat as `poll_live`. -- `wire.ts` `Broadcast.resolveTrackInfo(name, hold)` (both publishers): - public as an option on the track's info lookup (an `AbortSignal` that keeps - the track wanted until it fires), mirrored by whatever Rust's `query` - holds. Check Rust parity first; drop the hold if Rust has no equivalent - need. -- `internal.ts` `groupBounds`: stays a private helper; a third party passes - the public `Groups`. -- `priority.ts` `sendOrder`, `Priority`: stay private. They rank streams on - a `stream.ts` writer, which is wire plumbing in both languages. - -Tests: lowering the floor re-offers an unread cached group in both cursor -modes. Each public call gets a mock-time test in its language, and the -built-in publishers move onto the public calls, so their existing suites -cover the behavior. +The rest of public serving landed: the `with_range`/`withRange` cursor, public +`poll_start`, `poll_drop`, `poll_expired`, `Position::final_sequence`, +`Subscription::{start, end, with_start, with_end}`, and in JS the `Recv` union +from `tryRecvGroup`, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, +and `Track.Consumer.info({ hold })`. The live-edge answers moved to +[track-live](/quest/m1/track-live.md), and `track::Consumer::final_sequence` +to [the deferred quest](/quest/m1/public-model/deferred.md). + +Left: `hooks.guardGroup` and `hooks.readGroupFrame` with `ReadGroupFrame` +(both publishers, `js/net/src/group.ts`). A publisher that already read frames +off a group must still abandon its stream once the subscription's max delay +expires the group. Reading a frame the publisher `complete()`s holds the +group's `closed` until it is written. **Decision** on the public shape: + +- A public `expired` promise on `Group.Consumer`, resolving with the `Old` + error once the budget gives up on the group, which a publisher races its + writes against; the pending hold folds into `readFrame` (a read holds + `closed` until the next read or close). Recommended: it mirrors + `poll_expired` and adds no second read method. +- A public `guard(operation)` taking a thunk, as the hook does today. Shorter + call sites, but a callback parameter. +- Keep both hooks private as plumbing, on the grounds that a JS publisher + needs the wire stream types anyway. + +Tests: a mock-time test that a fully read, unfinished group still reports its +expiry, mirroring the Rust `a_fully_read_group_still_reports_its_expiry`. ## Related -- [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - the cache peeks and `fork`, split out of this quest +- [Public model](/quest/m1/public-model/README.md) - the epic, its rules, and the inventory method +- [A reader can tell when its track is live](/quest/m1/track-live.md) - owns the publishers' live-edge answers diff --git a/quest/m1/subscribe-drop-errors.md b/quest/m1/subscribe-drop-errors.md index d1ef8126f79..bf74a5d8bb8 100644 --- a/quest/m1/subscribe-drop-errors.md +++ b/quest/m1/subscribe-drop-errors.md @@ -57,7 +57,7 @@ Learned from the shelved [#4998](https://github.com/moq-dev/moq/pull/4998) - Fetched backfill that is abandoned, and a `DeliveryTimeout` reset, are deliberate holes, not cuts, like old, evicted, and lagged groups. - A cut above a reader's group cap is skipped for good, so a reader whose cap - `set_groups` later raises over it must still see the cut, not a clean end. + `with_range` later raises over it must still see the cut, not a clean end. - moq-tokio's `subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` flakes under load (`Ok(None)` with 10 of 20 frames, #4332): the code can diff --git a/quest/m1/subscribe-ranges/frame-bounds.md b/quest/m1/subscribe-ranges/frame-bounds.md index 23c940af714..91b87dadd5b 100644 --- a/quest/m1/subscribe-ranges/frame-bounds.md +++ b/quest/m1/subscribe-ranges/frame-bounds.md @@ -21,7 +21,7 @@ subscription (`position_group` in `rs/moq-net/src/lite/publisher.rs`, and the sa shape in `js/net/src/lite/publisher.ts`). - Keep each range's absolute frame bounds in the `Window` beside its group runs. -- Position every group the cursor hands out (`group::Consumer::start_at`/`end_at`), on +- Position every group the cursor hands out (`group::Consumer::with_range`), on the arrival, ordered, and re-offer paths, using the bounds of the range that covers it. A group whose head is gone and that was asked for from frame 0 stays a miss, as `position_group` does today. diff --git a/quest/m1/track-live.md b/quest/m1/track-live.md index f5c5532e5d9..e15bae28d5f 100644 --- a/quest/m1/track-live.md +++ b/quest/m1/track-live.md @@ -17,9 +17,15 @@ what an ended feed left; this quest makes the signal itself public. `readable()` in `rs/moq-net/src/model/track.rs`, the crate-private `resume` `poll_live`, and the crate-private `Producer::is_live`. Expose one reader-side `poll_live`/`live()` (or `is_live`) on `track::Subscriber` and - `track::Ordered`, and decide whether the publishers' crate-private - `poll_live` folds into it (see - [Public serving](/quest/m1/public-model/serve.md)). + `track::Ordered`. +- The publishers' wire answers (SUBSCRIBE_START, SUBSCRIBE_OK, TRACK_STATUS + Largest) are marked here: `track::Subscriber::poll_live` and + `latest_sequence` on `track::{Producer,Consumer,Subscriber}` in Rust, and + `wire.ts` `Broadcast.largest`, `hooks.latestSequence`, and + `hooks.bufferedLargest` in JS. `largest()` follows the source's reported + largest, which can name a frame the cache does not hold yet, so the + publishers answer with the buffered edge instead. Fold them into the public + signal, or keep them private as passthrough. - JS has no equivalent: a track never goes idle, so its reader is live from the start. Mirror the name, and the idle state if JS gains warm copies. - Decide what a reader does with groups served before live: keep serving @@ -28,4 +34,4 @@ what an ended feed left; this quest makes the signal itself public. ## Related -- [Public serving](/quest/m1/public-model/serve.md) - the publishers' `poll_live` and the `largest()` decision +- [Public serving](/quest/m1/public-model/serve.md) - moved the publishers' `poll_live` and the JS largest hooks here diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index f86f29361e9..ce3ec3fccbb 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,21 @@ How to update your code for each breaking change, newest first. ## Unreleased +### One `with_range` bounds a reader + +`track::Subscriber::set_groups`, `track::Ordered::set_groups`, and `track::Subscription::with_groups` are replaced by the consuming `with_range(range) -> Self`, and `group::Consumer::set_frames` by `group::Consumer::with_range`. +On a track reader both bounds now assign: an omitted start is group 0, where `set_groups` kept the floor, so pass the floor you want to keep. +Lowering the floor offers the cached groups below the old one that the reader never read; a group is still handed out once. + +```rust +// Before +subscriber.set_groups(5..); +// After +let subscriber = subscriber.with_range(5..); +``` + +A custom publisher can now reach what the built-in ones use: `track::Subscriber::poll_start`, `track::Subscriber::poll_drop`, `group::Consumer::poll_expired`, `subscription::Position::final_sequence`, and `Subscription::{start, end, with_start, with_end}` for the covering span. + ### Each group has one writer (#6020) `group::Producer` no longer implements `Clone`: keep one writer and move it by value between owners, or put it behind a lock when several callers write it. @@ -17,16 +32,16 @@ Dropping an unfinished writer now aborts the group with `Error::Dropped` immedia A `track::Subscriber` now reads only the groups its own `Subscription::ranges` cover, resolved again whenever `update` replaces them; before, they only set where its reads started. A reader that relied on groups another subscriber asked for must widen its own ranges. -Once a track finishes, a subscriber with nothing left under its `set_groups` cap ends rather than waiting for the cap to rise; raise it before the track finishes to read past it. +Once a track finishes, a subscriber with nothing left under its `with_range` cap ends rather than waiting for the cap to rise; raise it before the track finishes to read past it. -### `largest()` reports only upstream state, within a reader's `set_groups` bounds +### `largest()` reports only upstream state, within a reader's `with_range` bounds -`track::Subscriber::largest()` and `track::Ordered::largest()` (and their `poll_largest`) report the track's largest only while it is within the bounds set with `set_groups`, where they used to ignore the bounds. +`track::Subscriber::largest()` and `track::Ordered::largest()` (and their `poll_largest`) report the track's largest only while it is within the bounds set with `with_range`, where they used to ignore the bounds. A largest past the cap or below the floor reports nothing; the cache never stands in for it. A cap moved below the largest stays pending. Moving the bounds wakes a pending read, which reports the largest once it is within them and newer than the last report. Every `largest()`, `track::Producer` and `track::Consumer` included, now waits while a relay's copy is idle and reports once its new upstream subscription is live, rather than the largest an ended feed left. Cached groups are still served meanwhile. -To read the track's edge from a capped reader, lift the cap with `set_groups(..)` first. +To read the track's edge from a capped reader, lift the cap with `with_range(..)` first. ### Lite-07 accounts for groups with `SUBSCRIBE_DROP` @@ -82,8 +97,8 @@ session.retag(tier, &label); ### Subscriptions carry group ranges (#5732) -`track::Subscription::start` and `end` are replaced by `ranges: Vec`, and `with_start` and `with_end` are gone. -Use `with_groups(start..end)` for one span of groups, or `with_ranges` with `Range::live()`, `Range::oldest()` (the default), or `Range::groups(..)`. +The `track::Subscription::start` and `end` fields are replaced by `ranges: Vec`; the `start()` and `end()` methods and the `with_start` and `with_end` builders read and set the span covering them. +Use `with_range(start..end)` for one span of groups, or `with_ranges` with `Range::live()`, `Range::oldest()` (the default), or `Range::groups(..)`. ### Receive estimates come from `Session::recv_bandwidth` (#5777) From ee27a0dad0f7e7fbad40c81002899dd7fa4f0101 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 11:28:15 -0700 Subject: [PATCH 04/18] feat(js/net): a public group expired promise replaces the serving hooks Group.Consumer.expired settles with the Old error once the subscription's budget gives up on a group, even after every frame was read, mirroring the Rust poll_expired. It watches the budget only while raced, so a race per write leaks nothing. The lite and IETF publishers race their writes against it, and hooks.guardGroup, hooks.readGroupFrame, and ReadGroupFrame go away. A read no longer holds the consumer's closed open while the frame is written: expired already judges a group read whole, and holding closed on every read would hang a reader that stops at the last frame without a trailing read. serve.md keeps the one serving item left, the crate-private Rust poll_abandoned that #6140 added. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 2 +- js/net/src/group.ts | 202 ++++++++++++++++++------------ js/net/src/ietf/publisher.test.ts | 11 +- js/net/src/ietf/publisher.ts | 32 +++-- js/net/src/internal.ts | 24 +--- js/net/src/lite/publisher.ts | 46 +++---- js/net/src/resume.test.ts | 2 +- js/net/src/track.test.ts | 87 ++++++------- quest/m1/public-model/README.md | 2 +- quest/m1/public-model/serve.md | 53 ++++---- 10 files changed, 242 insertions(+), 219 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 4607b1efc26..844a4f6db87 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -31,7 +31,7 @@ const recv = subscriber.tryRecvGroup(); const group = recv.kind === "group" ? recv.group : undefined; ``` -`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, and `Track.Consumer.info({ hold })` are new. +`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, `Track.Consumer.info({ hold })`, and `Group.Consumer.expired` are new; a custom publisher races its writes against `expired` and resets the stream once it settles. ### A claim answers by publishing (#5678) diff --git a/js/net/src/group.ts b/js/net/src/group.ts index b2f6274f3be..71189a79343 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -14,7 +14,7 @@ import { TimestampMismatch, TooFarBehind, } from "./error.ts"; -import { type Expiry, type GroupRecover, hooks, type ReadGroupFrame, type Replacement } from "./internal.ts"; +import { type Expiry, type GroupRecover, hooks, type Replacement } from "./internal.ts"; import type { Timestamp } from "./time.ts"; /** Maximum bytes of frames in a group. A write that would exceed this aborts with {@link GroupTooLarge}. */ @@ -374,6 +374,86 @@ interface Attempt { replacement?: Replacement; } +// `Consumer.expired`: judges the drift budget only while something listens, so racing it once +// per write leaks nothing, and a group nobody watches pays nothing. The verdict latches. +class Expired implements GetPromise { + #judge: () => Error | undefined; + #changed: () => readonly Getter[]; + #listeners = new Set<(value: Error | undefined) => void>(); + // The drift inputs watched while anything listens. + #unwatch?: Dispose[]; + + constructor(judge: () => Error | undefined, changed: () => readonly Getter[]) { + this.#judge = judge; + this.#changed = changed; + } + + peek(): Error | undefined { + return this.#judge(); + } + + subscribe(fn: (value: Error | undefined) => void): Dispose { + this.#listeners.add(fn); + this.#watch(); + return () => { + this.#listeners.delete(fn); + if (this.#listeners.size === 0) this.#stop(); + }; + } + + changed(): Promise; + changed(fn: (value: Error | undefined) => void): Dispose; + changed(fn?: (value: Error | undefined) => void): Promise | Dispose { + if (!fn) return new Promise((resolve) => this.changed(resolve)); + const dispose = this.subscribe((value) => { + dispose(); + fn(value); + }); + return dispose; + } + + // biome-ignore lint/suspicious/noThenProperty: Expired is intentionally awaitable. + then( + onFulfilled?: ((value: Error) => R1 | PromiseLike) | null, + onRejected?: ((reason: unknown) => R2 | PromiseLike) | null, + ): PromiseLike { + return new Promise((resolve) => { + const value = this.peek(); + if (value) resolve(value); + else this.changed((value) => value && resolve(value)); + }).then(onFulfilled, onRejected); + } + + // Watch the current drift inputs again, since an adopted copy brings its own. + refresh(): void { + if (!this.#unwatch) return; + this.#stop(); + this.#watch(); + } + + #watch(): void { + if (this.#unwatch) return; + this.#unwatch = this.#changed().map((changed) => changed.subscribe(() => this.#check())); + // Judging arms the wall-clock wakeup; a verdict already reached notifies after `subscribe` + // returns, as a signal would. + if (this.peek()) queueMicrotask(() => this.#check()); + } + + #check(): void { + const value = this.peek(); + if (!value) return; + this.#stop(); + const listeners = [...this.#listeners]; + this.#listeners.clear(); + for (const fn of listeners) fn(value); + } + + #stop(): void { + for (const dispose of this.#unwatch ?? []) dispose(); + this.#unwatch = undefined; + } +} + // A consumer can finish from its own expiry verdict or from the shared group state. Keep // one stable public handle while letting peek() observe either source synchronously, before // signal subscribers run in the next microtask. The source is re-read on every check, since a @@ -481,7 +561,7 @@ export class Consumer { #terminal?: Error; #verdict = new Once(); #closed?: CombinedClosed; - #pendingFrames = 0; + #expired?: Expired; // Closed by its reader, which ends it whatever is left unread. #released = false; @@ -502,11 +582,31 @@ export class Consumer { (value) => value instanceof Error ? !this.#recovers(value) - : this.#released || (this.#bufferedFrames().length === 0 && this.#pendingFrames === 0), + : this.#released || this.#bufferedFrames().length === 0, ); return this.#closed; } + /** + * Settles with a `StreamError` of code `Old` once the subscription's `maxDelay` gives up + * on this group, even after every frame was read or the group closed: a publisher still + * writing or draining it races its writes against this and abandons the stream once it + * settles. Peek it synchronously (`undefined` while within budget), or race it, which + * stops watching the budget once the race ends. + */ + get expired(): GetPromise { + this.#expired ??= new Expired( + () => { + this.#expire(); + return this.#terminal instanceof StreamError && this.#terminal.code === StreamCode.Old + ? this.#terminal + : undefined; + }, + () => this.#expiry?.changed ?? [], + ); + return this.#expired; + } + // Whether a failure of the copy being read may still be continued from another route. #recovers(failed: Error): boolean { return !this.#terminal && this.#recover?.wants(failed) === true; @@ -533,8 +633,6 @@ export class Consumer { if (group.#closed?.peek() instanceof Error && group.#verdict.peek() === undefined) group.#closed = undefined; }; - hooks.guardGroup = (group, operation) => group.#guard(operation); - hooks.readGroupFrame = (group, from) => group.#readFramePosition(true, from); hooks.evictGroup = (group) => { group.#evict(); }; @@ -559,40 +657,6 @@ export class Consumer { return true; } - // Takes a thunk rather than a started promise, so a group already past its budget - // never begins the write: an abandoned write would reject later with no handler. - #guard(operation: () => Promise): Promise { - this.#expire(); - if (this.#terminal) return Promise.reject(this.#terminal); - const expiry = this.#expiry; - if (!expiry) return operation(); - - return new Promise((resolve, reject) => { - let settled = false; - const disposes: Dispose[] = []; - const finish = (fn: () => void) => { - if (settled) return; - settled = true; - for (const dispose of disposes) dispose(); - fn(); - }; - const check = () => { - this.#expire(); - if (this.#terminal) { - const error = this.#terminal; - finish(() => reject(error)); - } - }; - - for (const changed of expiry.changed) disposes.push(changed.subscribe(check)); - operation().then( - (value) => finish(() => resolve(value)), - (error: unknown) => finish(() => reject(error)), - ); - check(); - }); - } - #evict() { const frames = this.#bufferedFrames(); if (frames.length > 0) { @@ -699,6 +763,7 @@ export class Consumer { this.#expiry = replacement.expiry; this.#skip = index; this.#closed?.refresh(); + this.#expired?.refresh(); } // The unread frames. Every look at the buffer goes through here, so readiness, reads and @@ -713,24 +778,12 @@ export class Consumer { return frames; } - #readBufferedFrame(pending = false): ReadGroupFrame | undefined { - const frames = this.#bufferedFrames(); - const buffered = frames.shift(); - if (!buffered) return undefined; - + #readBufferedFrame(): { sequence: number; frame: Frame } | undefined { + const frame = this.#bufferedFrames().shift(); + if (!frame) return undefined; const sequence = this.#state.start++; - if (pending) this.#pendingFrames++; - let completed = false; - return { - sequence, - frame: buffered, - complete: () => { - if (completed) return; - completed = true; - if (pending) this.#pendingFrames--; - this.#closed?.refresh(); - }, - }; + this.#closed?.refresh(); + return { sequence, frame }; } /** True once no further frames can be read: the group has closed and every buffered frame is read. */ @@ -768,9 +821,7 @@ export class Consumer { */ tryReadFrame(): Frame | undefined { if (this.#terminal) return undefined; - const read = this.#readBufferedFrame(); - read?.complete(); - return read?.frame; + return this.#readBufferedFrame()?.frame; } /** Like {@link tryReadFrame} but also reports the frame's sequence number within the group. */ @@ -778,7 +829,6 @@ export class Consumer { if (this.#terminal) return undefined; const read = this.#readBufferedFrame(); if (!read) return undefined; - read.complete(); return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; } @@ -811,23 +861,29 @@ export class Consumer { * Treat the returned frame bytes as read-only; they are shared with other consumers. */ async readFrame(): Promise { - return (await this.#readFramePosition())?.frame; + return (await this.#readFrame(0))?.frame; } - async #readFramePosition(pending = false, from = 0): Promise { + /** + * Reads the next frame along with its sequence number within the group. + * Treat the returned frame bytes as read-only; they are shared with other consumers. + */ + async readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> { + const read = await this.#readFrame(options?.from ?? 0); + if (!read) return undefined; + return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; + } + + async #readFrame(from: number): Promise<{ sequence: number; frame: Frame } | undefined> { for (;;) { if (this.#terminal) { this.#abandon(); throw this.#terminal; } - const read = this.#readBufferedFrame(pending); + const read = this.#readBufferedFrame(); if (read) { - if (read.sequence < from) { - read.complete(); - continue; - } - if (!pending) read.complete(); + if (read.sequence < from) continue; return read; } @@ -856,16 +912,6 @@ export class Consumer { } } - /** - * Reads the next frame along with its sequence number within the group. - * Treat the returned frame bytes as read-only; they are shared with other consumers. - */ - async readFrameSequence(options?: ReadOptions): Promise<({ sequence: number } & Frame) | undefined> { - const read = await this.#readFramePosition(false, options?.from ?? 0); - if (!read) return undefined; - return { sequence: read.sequence, payload: read.frame.payload, timestamp: read.frame.timestamp }; - } - /** Reads the next frame and decodes its payload as a UTF-8 string. */ async readString(): Promise { const frame = await this.readFrame(); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 857b58c2697..ec0d19d92c5 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -3295,16 +3295,21 @@ test("draft-20: an inline terminal reset after its FIN falls back to a standalon const header = await GroupMessage.decode(reader, V20); for (let i = 0; i < 5; i++) await reader.decode((c) => Frame.decode(c, header.flags, undefined)); - // The group stream's close fails from here on, like a reset after its FIN. + // The group stream's close fails once it FINs, like a reset after its FIN. const closed = Object.getOwnPropertyDescriptor(Writer.prototype, "closed")?.get; if (!closed) throw new Error("Writer.closed is not a getter"); + const stream = opened[0]; + const fin = stream.close.bind(stream); let reset = false; - Object.defineProperty(opened[0], "closed", { + stream.close = () => { + reset = true; + fin(); + }; + Object.defineProperty(stream, "closed", { get(this: Writer) { return reset ? Promise.reject(new Error("reset after FIN")) : closed.call(this); }, }); - reset = true; track.finishAt({ group: 5, frame: 5 }); group.close(); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index cfcb98e3b67..75e681bebc3 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -939,8 +939,15 @@ export class Publisher { }, }); + // The subscription's budget may give up on the group mid-write, which abandons the stream. + // A group already past it never starts the write. + const write = async (op: () => Promise) => { + const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); + if (expired) throw expired; + }; + try { - await hooks.guardGroup(group, () => header.encode(stream, this.#session.version)); + await write(() => header.encode(stream, this.#session.version)); // The first written object goes on the wire as its absolute id, so a trimmed // head shows the true numbering rather than a silently renumbered group. let first = true; @@ -957,24 +964,15 @@ export class Publisher { // Reading from the filter's start drops the objects below it: they are outside // the requested range, so skipping them is not a gap. - const read = await race([hooks.readGroupFrame(group, slice.skip), stream.closed]); + const read = await race([group.readFrameSequence({ from: slice.skip }), stream.closed]); if (!read) break; next = read.sequence + 1; - if (slice.until !== undefined && read.sequence >= slice.until) { - read.complete(); - break; - } + if (slice.until !== undefined && read.sequence >= slice.until) break; - try { - const obj = new Frame({ payload: read.frame.payload, timestamp: read.frame.timestamp }); - const delta = first ? read.sequence : 0; - first = false; - await hooks.guardGroup(group, () => - obj.encode(stream, header.flags, timescale, this.#session.version, delta), - ); - } finally { - read.complete(); - } + const obj = new Frame({ payload: read.payload, timestamp: read.timestamp }); + const delta = first ? read.sequence : 0; + first = false; + await write(() => obj.encode(stream, header.flags, timescale, this.#session.version, delta)); } // The track ends right after this group's last object, so the marker rides this @@ -997,7 +995,7 @@ export class Publisher { // even without a marker: PUBLISH_DONE waits on this group, so the track, whose // timeline judges the budget, stays open until the stream settles. const delivered = await race([ - hooks.guardGroup(group, () => stream.closed).then(() => true), + write(() => stream.closed).then(() => true), unsubscribed.then(() => false), ]); // Only a stream that closed cleanly delivered the marker: one reset after its FIN diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index b398a4fbfec..c6009d79ff0 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -11,7 +11,7 @@ import type { Consumer as BroadcastConsumer, Producer as BroadcastProducer } fro import type { Datagram } from "./datagram.ts"; import type { Delivered } from "./delivered.ts"; import type * as Epoch from "./epoch.ts"; -import type { Frame, Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; +import type { Consumer as GroupConsumer, Producer as GroupProducer } from "./group.ts"; import { isAnonymous, type Route } from "./hop.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; @@ -143,16 +143,6 @@ export function runGaps(runs: readonly Run[], start: number, end: number): Run[] return gaps; } -/** A package-internal frame read the wire publisher completes once written. */ -export interface ReadGroupFrame { - /** Frame sequence within the group. */ - sequence: number; - /** Frame returned to the publisher. */ - frame: Frame; - /** Mark the frame delivered or deliberately skipped by the wire publisher. */ - complete(): void; -} - /** One past the highest sequence written under a broadcast track's name, by any of its producers. */ export interface TrackSequence { next: number; @@ -456,12 +446,6 @@ export const hooks: { expireGroup: (group: GroupConsumer, expiry: Expiry) => void; /** Carry a handed-out group across its logical track's route changes. */ recoverGroup: (group: GroupConsumer, recover: GroupRecover) => void; - // pending: /quest/m1/public-model/serve.md - /** Start a group operation unless the handed-out group has expired, and stop it if the group expires mid-flight. */ - guardGroup: (group: GroupConsumer, operation: () => Promise) => Promise; - // pending: /quest/m1/public-model/serve.md - /** Read a frame the wire publisher completes (or skips) once written. */ - readGroupFrame: (group: GroupConsumer, from?: number) => Promise; /** Make an evicted mirror terminal while its track timeline still contains it. */ evictGroup: (group: GroupConsumer) => void; /** Attach the origin advertisement of a created broadcast. */ @@ -604,12 +588,6 @@ export const hooks: { recoverGroup: () => { throw new Error("group.ts not loaded"); }, - guardGroup: () => { - throw new Error("group.ts not loaded"); - }, - readGroupFrame: () => { - throw new Error("group.ts not loaded"); - }, evictGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 720f2e9385c..cb0697049a0 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -1605,6 +1605,12 @@ export class Publisher { // This model holds whole groups, so frame `startFrame` is always reachable unless // the group ends first. Declaring it up front keeps the stream self-describing. const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, frameStart: startFrame }); + // The subscription's budget may give up on the group mid-write, which abandons the stream. + // A group already past it never starts the write. + const write = async (op: () => Promise) => { + const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); + if (expired) throw expired; + }; // Everything past this point runs inside the cleanup scope, so a failure never leaves // a finished group's stream being ranked. try { @@ -1612,7 +1618,7 @@ export class Publisher { // follows it too rather than keeping a stale rank until it finishes. priority.add(stream, group.sequence, startFrame); - await hooks.guardGroup(group, async () => { + await write(async () => { await stream.u53(0); // stream type await msg.encode(stream, this.version); }); @@ -1623,7 +1629,7 @@ export class Publisher { let reached = startFrame === 0; for (;;) { - const read = await race([hooks.readGroupFrame(group), stream.closed]); + const read = await race([group.readFrameSequence(), stream.closed]); if (!read) { // The group ended before the frame the subscriber asked to start // at, so this publisher can't serve the range at all. FINning here @@ -1633,26 +1639,22 @@ export class Publisher { break; } - try { - // A group that ends exactly at the start is a valid, empty range. - if (read.sequence + 1 >= startFrame) reached = true; - // Frames below the requested start were excluded, and the receiver - // numbers what it gets from `startFrame`. - if (read.sequence < startFrame) continue; - if (endFrame !== undefined && read.sequence > endFrame) break; - - if (timescale !== undefined) { - // Convert each frame to the track's wire timescale. - const ts = BigInt(wireTime(read.frame.timestamp, timescale)); - await hooks.guardGroup(group, () => stream.u62(zigzag(ts - prevTs))); - prevTs = ts; - } - - await hooks.guardGroup(group, () => stream.u53(read.frame.payload.byteLength)); - await hooks.guardGroup(group, () => stream.write(read.frame.payload)); - } finally { - read.complete(); + // A group that ends exactly at the start is a valid, empty range. + if (read.sequence + 1 >= startFrame) reached = true; + // Frames below the requested start were excluded, and the receiver + // numbers what it gets from `startFrame`. + if (read.sequence < startFrame) continue; + if (endFrame !== undefined && read.sequence > endFrame) break; + + if (timescale !== undefined) { + // Convert each frame to the track's wire timescale. + const ts = BigInt(wireTime(read.timestamp, timescale)); + await write(() => stream.u62(zigzag(ts - prevTs))); + prevTs = ts; } + + await write(() => stream.u53(read.payload.byteLength)); + await write(() => stream.write(read.payload)); } stream.close(); @@ -1660,7 +1662,7 @@ export class Publisher { // A stream that fails after its FIN may have lost its header, so report it for a DROP. // Its bytes still hold the connection until acknowledged, so a group gone stale // meanwhile is reset like one still serving, as the Rust `GroupServe` does. - await hooks.guardGroup(group, () => stream.closed); + await write(() => stream.closed); return undefined; } catch (err: unknown) { const e = error(err); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index a96acb512ee..edd476f8733 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1571,7 +1571,7 @@ test.each([false, true])( copy(b); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(10_000) }); - expect(sub.tryRecvGroup()).toBeUndefined(); + expect(sub.tryRecvGroup().kind).toBe("idle"); expect(hooks.tryRecvDatagram(sub).kind).toBe("idle"); ta.write(0); front.serve(b.consume()); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 39241f1d445..5dc0fb262f7 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1,5 +1,6 @@ import { expect, setSystemTime, spyOn, test } from "bun:test"; import { Manual, Milli, Nano } from "@moq/clock"; +import { race } from "@moq/signals"; import { Producer as BroadcastProducer } from "./broadcast.ts"; import { ProtocolViolation, StreamCode, TimestampMismatch, TooFarBehind } from "./error.ts"; import { type Consumer as GroupConsumer, Producer as GroupProducer, MAX_GROUP_FRAMES } from "./group.ts"; @@ -1020,7 +1021,7 @@ test("committing track info wakes a group newly outside the retention window", a await expect(waiting).rejects.toMatchObject({ code: StreamCode.Old }); }); -test("a handed-out frame cancels its in-flight operation when it expires", async () => { +test("a handed-out group reports its expiry to a writer racing it", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(5000) }); const track = producer.subscribe(); producer.writeFrame(textFrame("old")); @@ -1029,18 +1030,15 @@ test("a handed-out frame cancels its in-flight operation when it expires", async if (!group) throw new Error("missing group"); expect(await group.readString()).toBe("old"); - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + const write = new Promise(() => {}); + const raced = race([write, group.expired]); producer.writeFrame(textFrame("new")); - await expect(guarded).rejects.toThrow("max delay budget"); - release(); + expect(await raced).toMatchObject({ code: StreamCode.Old, message: expect.stringContaining("max delay budget") }); + expect(group.expired.peek()).toMatchObject({ code: StreamCode.Old }); }); -test("a guarded write keeps the position of the frame removed from the buffer", async () => { +test("a frame still being written is judged against the budget", async () => { const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); const track = producer.subscribe({ maxDelay: Milli(100) }); const source = producer.appendGroup(); @@ -1049,54 +1047,49 @@ test("a guarded write keeps the position of the frame removed from the buffer", const group = await track.recvGroup(); if (!group) throw new Error("missing group"); - const read = await hooks.readGroupFrame(group); - if (!read) throw new Error("missing frame"); - - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + expect(await group.readFrame()).toBeDefined(); + const raced = race([new Promise(() => {}), group.expired]); producer.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); // A group beyond the edge, so group 0's reach (1s) is provably behind it: a group is // bounded by where its successor begins, so the successor alone never convicts it. producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); - await expect(guarded).rejects.toThrow("max delay budget"); - read.complete(); - release(); + expect(await raced).toMatchObject({ code: StreamCode.Old }); }); -test("clean source closure stays provisional while a frame write can expire", async () => { - const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI, maxAge: Milli(100) }); - const track = producer.subscribe({ maxDelay: Milli(100) }); - const source = producer.appendGroup(); - source.writeFrame({ payload: enc.encode("old"), timestamp: Timestamp.fromMillis(0) }); - source.close(); +// Mirrors the Rust `a_fully_read_group_still_reports_its_expiry`: a publisher still draining a +// group it read whole abandons the stream once the budget gives up on the group. +test("a fully read group still reports its expiry", async () => { + const clock = manualTime(10_000); + const producer = new TrackProducer("test").accept({ timescale: Timescale.MILLI }); + try { + const track = producer.subscribe({ maxDelay: Milli(1000) }); + const source = producer.appendGroup(); + source.writeFrame({ payload: enc.encode("a"), timestamp: Timestamp.fromMillis(0) }); + source.close(); - const group = await track.recvGroup(); - if (!group) throw new Error("missing group"); - const closed = group.closed; - expect(closed.peek()).toBeUndefined(); - - const read = await hooks.readGroupFrame(group); - if (!read) throw new Error("missing frame"); - let release!: () => void; - const operation = new Promise((resolve) => { - release = resolve; - }); - const guarded = hooks.guardGroup(group, () => operation); + const group = await track.recvGroup(); + if (!group) throw new Error("missing group"); + expect(await group.readFrame()).toBeDefined(); + expect(await group.readFrame()).toBeUndefined(); + expect(await group.closed).toBeNull(); + expect(group.expired.peek()).toBeUndefined(); - const edge = producer.appendGroup(); - edge.writeFrame({ payload: enc.encode("edge"), timestamp: Timestamp.fromMillis(1_000) }); - // See above: a group is bounded by where its successor begins, so convicting group 0 - // needs a group beyond that successor. - producer.writeFrame({ payload: enc.encode("later"), timestamp: Timestamp.fromMillis(2_000) }); - await expect(guarded).rejects.toThrow("max delay budget"); - expect(await closed).toBeInstanceOf(Error); + // Frozen media time, so only the wall clock since the successor arrived convicts it. + producer.writeFrame({ payload: enc.encode("b"), timestamp: Timestamp.fromMillis(0) }); + const raced = race([new Promise(() => {}), group.expired]); + await settle(); + clock.set(10_999); + await settle(); + expect(group.expired.peek()).toBeUndefined(); - read.complete(); - release(); + clock.set(11_000); + expect(await raced).toMatchObject({ code: StreamCode.Old }); + expect(group.expired.peek()).toMatchObject({ code: StreamCode.Old }); + } finally { + producer.close(); + clock.restore(); + } }); test("a drained group finishes cleanly after the live edge advances", async () => { diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index b6fd1b95c07..565aa9f0a15 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -102,7 +102,7 @@ Work owned by this README, after the children land: ## Required - [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls -- [Public group expiry in JS](/quest/m1/public-model/serve.md) - a custom JS publisher learns when a group it is still writing has expired, the last serving item left +- [Public group abandonment in Rust](/quest/m1/public-model/serve.md) - a custom Rust publisher parked on its transport learns when to give up on a group, the last serving item left - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/serve.md b/quest/m1/public-model/serve.md index cf0e2e6eaf5..833605dbfe5 100644 --- a/quest/m1/public-model/serve.md +++ b/quest/m1/public-model/serve.md @@ -1,10 +1,12 @@ -# [S] Public group expiry in JS +# [XS] Public group abandonment in Rust ## Goal -A custom `@moq/net` publisher learns, through public calls, when a group it is -still writing has expired, as the Rust `group::Consumer::poll_expired` already -lets it. The built-in lite and IETF publishers use the same call. +A custom `moq-net` publisher waiting on its transport, for stream credit or to +drain, learns through a public call when to give up on a group: the budget +expired it, or its copy was aborted before the publisher read it all and no +route will continue it. The built-in lite and IETF publishers use the same +call. ## Plan @@ -12,28 +14,27 @@ The rest of public serving landed: the `with_range`/`withRange` cursor, public `poll_start`, `poll_drop`, `poll_expired`, `Position::final_sequence`, `Subscription::{start, end, with_start, with_end}`, and in JS the `Recv` union from `tryRecvGroup`, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, -and `Track.Consumer.info({ hold })`. The live-edge answers moved to -[track-live](/quest/m1/track-live.md), and `track::Consumer::final_sequence` -to [the deferred quest](/quest/m1/public-model/deferred.md). - -Left: `hooks.guardGroup` and `hooks.readGroupFrame` with `ReadGroupFrame` -(both publishers, `js/net/src/group.ts`). A publisher that already read frames -off a group must still abandon its stream once the subscription's max delay -expires the group. Reading a frame the publisher `complete()`s holds the -group's `closed` until it is written. **Decision** on the public shape: - -- A public `expired` promise on `Group.Consumer`, resolving with the `Old` - error once the budget gives up on the group, which a publisher races its - writes against; the pending hold folds into `readFrame` (a read holds - `closed` until the next read or close). Recommended: it mirrors - `poll_expired` and adds no second read method. -- A public `guard(operation)` taking a thunk, as the hook does today. Shorter - call sites, but a callback parameter. -- Keep both hooks private as plumbing, on the grounds that a JS publisher - needs the wire stream types anyway. - -Tests: a mock-time test that a fully read, unfinished group still reports its -expiry, mirroring the Rust `a_fully_read_group_still_reports_its_expiry`. +`Track.Consumer.info({ hold })`, and `Group.Consumer.expired`. The live-edge +answers moved to [track-live](/quest/m1/track-live.md), and +`track::Consumer::final_sequence` to +[the deferred quest](/quest/m1/public-model/deferred.md). + +Left: the crate-private `group::Consumer::poll_abandoned(waiter, held)`, +which [#6140](https://github.com/moq-dev/moq/pull/6140) added so a group +parked on stream credit gives up. It answers `poll_expired` plus the aborted +copy. **Decision** on the public shape: + +- Make `poll_abandoned` public and `poll_expired` private, dropping the + `held` flag the way `poll_expired` did (`poll_open` passes `false` today, so + an empty finished group parked on credit would then expire). Recommended: + one call answers "stop writing this group". +- Keep both public, with `held` exposed. A bool parameter callers must reason + about. +- Keep `poll_abandoned` private: a custom publisher reads the abort on its + next frame read instead, but holds the credit it waited for until then. + +Check whether the JS publishers need the same: `Group.Consumer.expired` +covers the budget, not an aborted copy parked on credit. ## Related From 9b9a1c1141cddefda8c50782107f392e64a3eaf5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 11:36:04 -0700 Subject: [PATCH 05/18] fix(js/net): satisfy biome on the expiry race Co-Authored-By: Claude Opus 5.5 --- js/net/src/group.ts | 4 +--- js/net/src/ietf/publisher.ts | 2 +- js/net/src/lite/publisher.ts | 2 +- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 71189a79343..311d851307f 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -580,9 +580,7 @@ export class Consumer { this.#verdict, () => this.#state.closed, (value) => - value instanceof Error - ? !this.#recovers(value) - : this.#released || this.#bufferedFrames().length === 0, + value instanceof Error ? !this.#recovers(value) : this.#released || this.#bufferedFrames().length === 0, ); return this.#closed; } diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 75e681bebc3..ec23aefb483 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -943,7 +943,7 @@ export class Publisher { // A group already past it never starts the write. const write = async (op: () => Promise) => { const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); - if (expired) throw expired; + if (expired !== undefined) throw expired; }; try { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index cb0697049a0..4452d7dc458 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -1609,7 +1609,7 @@ export class Publisher { // A group already past it never starts the write. const write = async (op: () => Promise) => { const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); - if (expired) throw expired; + if (expired !== undefined) throw expired; }; // Everything past this point runs inside the cleanup scope, so a failure never leaves // a finished group's stream being ranked. From 08a0c34c0ccc58aa661379998c12d34b52b6c8b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 17:52:50 -0700 Subject: [PATCH 06/18] fix(js/net): a lowered range re-offers cuts and never a closed reader A cut group is handed out with its error since #6143, so lowering the floor re-offers it like any other cached group. A reader that closed itself stays closed: withRange no longer refills its buffer. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 45 ++++++++++++++++++++++++++++++++++++++++ js/net/src/track.ts | 14 ++++++++----- 2 files changed, 54 insertions(+), 5 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 2d83f718646..a898f618468 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -2186,6 +2186,51 @@ test("a lowered range re-offers the unread cached groups", () => { track.close(); }); +test("a lowered range re-offers a cached cut with its error", async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + const cut = new GroupProducer(0); + producer.writeGroup(cut); + const error = new StreamError(StreamCode(70), { message: "cut" }); + cut.close(error); + producer.writeGroup(new GroupProducer(1)); + expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + + track.withRange({}); + const group = taken(track.tryRecvGroup()); + expect(group?.sequence).toBe(0); + await expect(group?.readString()).rejects.toBe(error); + track.close(); + producer.close(); +}); + +test("a lowered range still re-offers after the producer closes", () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); + expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + producer.close(); + + track.withRange({}); + expect(taken(track.tryRecvGroup())?.sequence).toBe(0); + expect(track.tryRecvGroup()).toEqual({ kind: "done" }); + track.close(); +}); + +for (const abort of [undefined, new Error("gone")]) { + test(`a lowered range offers nothing to a reader that ${abort ? "aborted" : "closed"}`, () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); + for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); + expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + track.close(abort); + + track.withRange({}); + expect(track.tryRecvGroup()).toEqual(abort ? { kind: "error", error: abort } : { kind: "done" }); + producer.close(); + }); +} + test("malformed group bounds do not partially advance the cursor", () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000) }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 753ef51a1f1..cb674bd5e41 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -608,8 +608,9 @@ let bindProducerSequence: (producer: Producer, sequence: TrackSequence) => void; let cachedMirror: (producer: Producer, sequence: number) => GroupConsumer | undefined; // Whether the producer still caches a group that has not failed; assigned in its static block. let cachedHolds: (producer: Producer, sequence: number) => boolean; -// Mirror the cached groups in `[start, end)` that `offer` accepts into a sink again, for a -// reader whose floor moved below them; assigned in the producer's static block. +// Mirror the cached groups in `[start, end)` that `offer` accepts into a sink again, cut ones +// included as a fresh sink gets them, for a reader whose floor moved below them; assigned in +// the producer's static block. let reofferCached: ( producer: Producer, sink: TrackState, @@ -833,8 +834,7 @@ export class Producer { const held = new Set(sink.groups.peek().map((group) => group.sequence)); for (const entry of producer.#cache) { const sequence = entry.group.sequence; - if (sequence < start || sequence >= end || held.has(sequence)) continue; - if (entry.group.closed.peek() instanceof Error || !offer(sequence)) continue; + if (sequence < start || sequence >= end || held.has(sequence) || !offer(sequence)) continue; producer.#mirror(entry, sink); } }; @@ -1695,6 +1695,9 @@ export class Subscriber { // Every group sequence this reader handed out, so a re-created group or one a second route // delivers is handed out once. #delivered = new Delivered(); + // This reader closed itself, so lowering its floor offers nothing: a producer's clean close + // alone leaves the cache readable, but the reader leaving must stay terminal. + #closed = false; // What {@link largest} last reported, and whether it ended: moving the bounds afterwards // does not bring it back. #largestSeen?: Location; @@ -2155,7 +2158,7 @@ export class Subscriber { const before = this.#cursor.peek(); this.#cursor.set({ start, end }); const producer = this.#state.producer; - if (!this.#resume && producer && start < before.start) { + if (!this.#resume && !this.#closed && producer && start < before.start) { // The arrival cursor let go of what it passed below the old floor. reofferCached(producer, this.#state, start, before.start, (sequence) => !this.#delivered.has(sequence)); } @@ -2164,6 +2167,7 @@ export class Subscriber { /** Close the track (optionally with an error), closing any pending groups. Idempotent. */ close(abort?: Error) { + this.#closed = true; // Settle if we're first (the producer may already have); either way drop anything // still buffered. Groups parked at the withRange cap deliberately outlive a clean // producer close, so the subscriber leaving is what must release them: closing From 5fa2d1734fe65df376f055fc542c9ab890a7718a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 23:58:21 -0700 Subject: [PATCH 07/18] fix(net): give up a written group on closed errors as well as expiry A publisher writing a group now stops once `expired` settles or `closed` fails (Rust: `poll_expired`, or `poll_finished` erring), so an eviction of what it has yet to read resets a stream blocked on flow control. Racing `expired` alone missed it. - Delete JS `hooks.guardGroup` and Rust `group::Consumer::poll_abandoned`. Both publishers share a session-side helper over the public calls. - Rust `poll_finished` ends cleanly at a `with_range` frame cap, as reads do, so a served range is not reset when frames past it fail upstream. - A closed JS subscriber keeps its groups' arrival times, so a group read from a copy the resumed reader let go of still expires at its budget. - serve.md drops the settled abandonment decision, leaving JS `sourceStart`. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 3 +- js/net/bench/track.ts | 6 +- js/net/src/group.ts | 42 ++------------ js/net/src/ietf/publisher.ts | 20 ++++--- js/net/src/internal.ts | 6 -- js/net/src/lite/publisher.ts | 17 +++--- js/net/src/parked-expiry.test.ts | 96 ++++++++++++++++++++++++++++++++ js/net/src/resume.test.ts | 52 +++++++++++++++++ js/net/src/track.ts | 33 +++++++++-- js/net/src/util/given_up.ts | 27 +++++++++ quest/m1/public-model/README.md | 2 +- quest/m1/public-model/serve.md | 42 ++++---------- rs/moq-net/MIGRATE.md | 3 + rs/moq-net/src/ietf/publisher.rs | 28 +++++++--- rs/moq-net/src/lite/publisher.rs | 28 +++++++--- rs/moq-net/src/model/group.rs | 78 ++++++++++++-------------- 16 files changed, 323 insertions(+), 160 deletions(-) create mode 100644 js/net/src/util/given_up.ts diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 5842a5f30a2..2c6e1190137 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -31,7 +31,8 @@ const recv = subscriber.tryRecvGroup(); const group = recv.kind === "group" ? recv.group : undefined; ``` -`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, `Track.Consumer.info({ hold })`, and `Group.Consumer.expired` are new; a custom publisher races its writes against `expired` and resets the stream once it settles. +`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, `Track.Consumer.info({ hold })`, and `Group.Consumer.expired` are new. +A custom publisher races its writes against `expired` and against `closed` settling with an error (an eviction, or an aborted copy no route continues), and resets the stream once either does. ### A dropped or cut group ends its reader with an error (#6143) diff --git a/js/net/bench/track.ts b/js/net/bench/track.ts index ee4d122a496..c0452c1e32a 100644 --- a/js/net/bench/track.ts +++ b/js/net/bench/track.ts @@ -2,9 +2,9 @@ import { Milli } from "@moq/clock"; import { type Consumer as GroupConsumer, Producer as GroupProducer } from "../src/group.ts"; -import { hooks } from "../src/internal.ts"; import { Timescale, Timestamp } from "../src/time.ts"; import { Producer, type Subscriber } from "../src/track.ts"; +import { untilGivenUp } from "../src/util/given_up.ts"; const retainedCounts = [25, 100, 400, 1500]; const subscriberCounts = [1, 4, 16]; @@ -83,10 +83,10 @@ async function measure( for (const consumer of received) { if (hold.operation === "read") reads.push(consumer.readFrame()); else { - // The guard a publisher holds while a group stream waits for credit. + // The watch a publisher holds while a group stream waits for credit. const opening = Promise.withResolvers(); opened.push(opening.resolve); - reads.push(hooks.guardGroup(consumer, () => opening.promise)); + reads.push(untilGivenUp(consumer, () => opening.promise)); } } } diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 85de965a3a7..876b476d74f 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -588,9 +588,10 @@ export class Consumer { /** * Settles with a `StreamError` of code `Old` once the subscription's `maxDelay` gives up * on this group, even after every frame was read or the group closed: a publisher still - * writing or draining it races its writes against this and abandons the stream once it - * settles. Peek it synchronously (`undefined` while within budget), or race it, which - * stops watching the budget once the race ends. + * writing or draining it races its writes against this, and against {@link closed} + * settling with an error, and abandons the stream once either does. Peek it synchronously + * (`undefined` while within budget), or race it, which stops watching the budget once the + * race ends. */ get expired(): GetPromise { this.#expired ??= new Expired( @@ -631,7 +632,6 @@ export class Consumer { if (group.#closed?.peek() instanceof Error && group.#verdict.peek() === undefined) group.#closed = undefined; }; - hooks.guardGroup = (group, operation) => group.#guard(operation); hooks.evictGroup = (group) => { group.#evict(); }; @@ -656,40 +656,6 @@ export class Consumer { return true; } - // Takes a thunk rather than a started promise, so a group already past its budget - // never begins the operation: an abandoned one would reject later with no handler. - #guard(operation: () => Promise): Promise { - this.#expire(); - if (this.#terminal) return Promise.reject(this.#terminal); - const expiry = this.#expiry; - if (!expiry) return operation(); - - return new Promise((resolve, reject) => { - let settled = false; - const disposes: Dispose[] = []; - const finish = (fn: () => void) => { - if (settled) return; - settled = true; - for (const dispose of disposes) dispose(); - fn(); - }; - const check = () => { - this.#expire(); - if (this.#terminal) { - const error = this.#terminal; - finish(() => reject(error)); - } - }; - - for (const changed of expiry.changed) disposes.push(changed.subscribe(check)); - operation().then( - (value) => finish(() => resolve(value)), - (error: unknown) => finish(() => reject(error)), - ); - check(); - }); - } - #evict() { const frames = this.#bufferedFrames(); if (frames.length > 0) { diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 13383bbb05e..0c6cb99c501 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -32,6 +32,7 @@ import { Timescale } from "../time.ts"; import type { Groups, Location as TrackLocation, Subscriber as TrackSubscriber } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, REQUEST_TIMEOUT_MS, requestOptions } from "../util/deadline.ts"; +import { untilGivenUp } from "../util/given_up.ts"; import { LIMITS, type Limits, Slots } from "../util/limits.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; import * as Varint from "../varint.ts"; @@ -908,11 +909,9 @@ export class Publisher { // once the open settles. tryOpen owns resetting a slot that arrives too late. const opened = Promise.withResolvers(); let failure: Error | undefined; - const abandoned = hooks - .guardGroup(group, () => opened.promise) - .catch((err: unknown) => { - failure = error(err); - }); + const abandoned = untilGivenUp(group, () => opened.promise).then((stop) => { + failure = stop; + }); let stream: Writer | undefined; try { stream = await Writer.tryOpen(this.#quic, { @@ -953,11 +952,11 @@ export class Publisher { }, }); - // The subscription's budget may give up on the group mid-write, which abandons the stream. - // A group already past it never starts the write. + // The subscription's budget, or an eviction of what is left to read, may give up on the + // group mid-write, which abandons the stream. A group already given up never starts the write. const write = async (op: () => Promise) => { - const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); - if (expired !== undefined) throw expired; + const stop = await untilGivenUp(group, op); + if (stop) throw stop; }; try { @@ -1004,6 +1003,9 @@ export class Publisher { } stream.close(); + // The stream holds every byte it owes, so frames past a range's end failing upstream + // can no longer give it up: release the read, leaving the budget. + group.close(); // Its bytes still hold the connection until acknowledged, so a group gone stale // meanwhile is reset like one still serving, as the Rust `GroupServe` does. Awaited // even without a marker: PUBLISH_DONE waits on this group, so the track, whose diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index a72bb3c1c05..15d75b35b12 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -499,9 +499,6 @@ export const hooks: { expireGroup: (group: GroupConsumer, expiry: Expiry) => void; /** Carry a handed-out group across its logical track's route changes. */ recoverGroup: (group: GroupConsumer, recover: GroupRecover) => void; - // pending: /quest/m1/public-model/serve.md - /** Start a group operation unless the handed-out group has expired, and stop it if the group expires mid-flight. */ - guardGroup: (group: GroupConsumer, operation: () => Promise) => Promise; /** Make an evicted mirror terminal while its track timeline still contains it. */ evictGroup: (group: GroupConsumer) => void; /** Attach the origin advertisement of a created broadcast. */ @@ -653,9 +650,6 @@ export const hooks: { recoverGroup: () => { throw new Error("group.ts not loaded"); }, - guardGroup: () => { - throw new Error("group.ts not loaded"); - }, evictGroup: () => { throw new Error("group.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index c11de799522..dc7249b6b68 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -19,6 +19,7 @@ import { type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { finalSequence } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; +import { untilGivenUp } from "../util/given_up.ts"; import { Interests, LIMITS, type Limits, Slots } from "../util/limits.ts"; import { nextTask } from "../util/yield.ts"; import { type Advertised, type Advertisements, sameInstance, wireOf } from "../wire.ts"; @@ -1613,11 +1614,9 @@ export class Publisher { // once the open settles. tryOpen owns resetting a slot that arrives too late. const opened = Promise.withResolvers(); let failure: Error | undefined; - const abandoned = hooks - .guardGroup(group, () => opened.promise) - .catch((err: unknown) => { - failure = error(err); - }); + const abandoned = untilGivenUp(group, () => opened.promise).then((stop) => { + failure = stop; + }); let stream: Writer | undefined; try { stream = await Writer.tryOpen(this.#quic, { @@ -1652,11 +1651,11 @@ export class Publisher { // This model holds whole groups, so frame `startFrame` is always reachable unless // the group ends first. Declaring it up front keeps the stream self-describing. const msg = new GroupMessage({ subscribe: sub, sequence: group.sequence, frameStart: startFrame }); - // The subscription's budget may give up on the group mid-write, which abandons the stream. - // A group already past it never starts the write. + // The subscription's budget, or an eviction of what is left to read, may give up on the + // group mid-write, which abandons the stream. A group already given up never starts the write. const write = async (op: () => Promise) => { - const expired = group.expired.peek() ?? (await race([op().then(() => undefined), group.expired])); - if (expired !== undefined) throw expired; + const stop = await untilGivenUp(group, op); + if (stop) throw stop; }; // Everything past this point runs inside the cleanup scope, so a failure never leaves // a finished group's stream being ranked. diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index 8265fe8526d..911fac9e5ae 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -147,3 +147,99 @@ for (const protocol of protocols) { }, ); } + +for (const protocol of protocols) { + test(`${protocol.alpn}: a blocked group write ends when eviction takes what it has yet to read`, async () => { + const clock = new Manual(); + const restore = clock.install(); + const pair = createMockTransportPair(protocol.alpn); + const origin = new Origin(); + const broadcast = origin.createBroadcast(Path.from("parked")); + broadcast.announce(); + const track = broadcast.createTrack("video", { timescale: Timescale.MILLI }); + const write = (sequence: number, frames: number) => { + const group = new Group(sequence); + for (let frame = 0; frame < frames; frame++) { + group.writeFrame({ payload: new Uint8Array([frame]), timestamp: Timestamp.fromMillis(0) }); + } + group.close(); + track.writeGroup(group); + }; + + // Two frames, so the second is still unread while the stream's first write waits on credit. + write(0, 2); + + const blocked = Promise.withResolvers(); + const credit = Promise.withResolvers(); + let writes = 0; + let resets = 0; + const stalled = new WritableStream({ + write: async () => { + writes++; + blocked.resolve(); + await credit.promise; + }, + abort: () => { + resets++; + }, + }); + const opening = spyOn(pair.server, "createUnidirectionalStream").mockImplementationOnce(async () => stalled); + const client = await Stream.open(pair.client, { version: protocol.version }); + const server = await Stream.accept(pair.server, protocol.version); + if (!server) throw new Error("missing subscribe stream"); + // A budget past the eviction, so only the eviction can give the group up. + const budget = 60_000; + let running: Promise; + let close = () => {}; + if (protocol.kind === "lite") { + const publisher = new LitePublisher(pair.server, protocol.version, randomHop(), origin.consume()); + close = () => publisher.close(); + running = publisher.runSubscribe( + new LiteSubscribe({ + id: 0n, + broadcast: Path.from("parked"), + track: "video", + priority: 0, + maxDelay: budget, + }), + server, + ); + } else { + const publisher = new IetfPublisher({ + quic: pair.server, + session: new NativeSession(pair.server, protocol.version, true), + publish: origin.consume(), + requiresSolicitation: false, + }); + running = publisher.runSubscribe( + new IetfSubscribe({ + requestId: 0n, + trackNamespace: Path.from("parked"), + trackName: "video", + subscriberPriority: 0, + maxAge: budget, + }), + server, + ); + } + try { + await blocked.promise; + write(1, 1); + await clock.advanceAsync(Nano.fromMilli(Milli(33_750))); + // The write already handed to the stream finishes, and the stream is reset after it. + credit.resolve(); + await clock.advanceAsync(Nano.zero); + expect(writes).toBe(1); + expect(resets).toBe(1); + } finally { + credit.resolve(); + close(); + client.close(); + broadcast.close(); + origin.close(); + await running; + opening.mockRestore(); + restore(); + } + }); +} diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 5f412a76399..73a9812afbe 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1550,6 +1550,58 @@ test.each(["lands", "dropped", "expired"])( }, ); +test("a group read whole still expires once the reader lets go of its copy", async () => { + const { clock, restore } = manual(); + const front = new Front(); + const a = new BroadcastProducer(); + const b = new BroadcastProducer(); + const ta = copy(a); + const tb = copy(b); + front.serve(a.consume()); + const sub = front.consumer.track("seq").subscribe({ maxDelay: SECOND }); + try { + ta.write(0); + const group = taken(sub.tryRecvGroup()); + if (!group) throw new Error("expected group 0"); + // Read whole and released, as a publisher does before it drains the stream it wrote it to. + expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); + expect(await group.readFrame()).toBeUndefined(); + group.close(); + + front.serve(b.consume()); + await settle(); + tb.write(2); + expect(drain(sub)).toEqual([2]); + // Its successor lands on the replaced copy, starting the budget there. + const half = Nano.fromMilli(Milli(SECOND / 2)); + await clock.advanceAsync(half); + ta.write(1); + drain(sub); + + let expired: Error | undefined; + void group.expired.then((err) => { + expired = err; + }); + // A budget after the swap, the next read lets go of the replaced copy, closing its subscription. + await clock.advanceAsync(half); + expect(drain(sub)).toEqual([]); + await settle(); + expect(ta.producer.demand().wanted.peek()).toBeUndefined(); + expect(expired).toBeUndefined(); + + await clock.advanceAsync(half); + await settle(); + expect(expired).toBeInstanceOf(StreamError); + expect((expired as StreamError).code).toBe(StreamCode.Old); + } finally { + sub.close(); + front.consumer.close(); + a.close(); + b.close(); + restore(); + } +}); + test("an ordered reader keeps no copy for a group it passed", async () => { const front = new Front(); const a = new BroadcastProducer(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index bdc536e7e8a..d128c308f12 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -1746,6 +1746,10 @@ export class Subscriber { revision: new Signal(0), at: Number.POSITIVE_INFINITY, }; + // When each group the timeline held at close arrived, failed ones left out. A group handed + // out earlier can outlive this subscriber, as one a resumed reader still writes from a copy + // it let go of, and its budget still runs from its successor's arrival. + #arrivals?: { sequence: number; arrived: Instant }[]; #drift(): Drift { const { end } = this.#cursor.peek(); @@ -1808,22 +1812,30 @@ export class Subscriber { // // The wall clock judges it too: a group is also stale once its successor arrived a full // budget ago, so a peer whose timestamps stop advancing, an untimed track, or an empty - // successor that never presents cannot pin a superseded group. The successor is re-read, - // not latched, like the reach. The newest group has no successor, so neither clock ever + // successor that never presents cannot pin a superseded group. While open, the successor is + // re-read, not latched, like the reach. The newest group has no successor, so neither clock ever // convicts it. `wake` arms a timer for the wall deadline, for a held read that waits on it. #isStale(group: GroupConsumer, drift: Drift, wake = false): boolean { - if (this.#state.timeline[timelineIndex(this.#state.timeline, group.sequence)] !== group) return false; + const timeline = this.#state.timeline; + if (!this.#arrivals && timeline[timelineIndex(timeline, group.sequence)] !== group) return false; return this.#staleAt(group.sequence, drift, wake); } // The drift verdict for `sequence` by its successor alone, whether or not this track holds it. + // Once closed, only the wall clock judges it, from the arrivals kept at close. #staleAt(sequence: number, drift: Drift, wake = false): boolean { - const successor = this.#successor(sequence, drift.end); - if (!successor) return false; + const successor = this.#arrivals ? undefined : this.#successor(sequence, drift.end); + const arrived = successor + ? hooks.groupArrived(successor) + : this.#arrivals?.find( + (entry) => entry.sequence > sequence && (drift.end === undefined || entry.sequence < drift.end), + )?.arrived; + if (arrived === undefined) return false; // Plain arithmetic: an unenforced budget is infinite, which no duration brand holds. - const deadline = hooks.groupArrived(successor) + drift.budget * 1_000_000; + const deadline = arrived + drift.budget * 1_000_000; if (now() >= deadline) return true; if (wake) this.#wakeAt(deadline); + if (!successor) return false; const reach = hooks.groupTimestamp(successor)?.asMillis(); return ( @@ -2192,6 +2204,13 @@ export class Subscriber { /** Close the track (optionally with an error), closing any pending groups. Idempotent. */ close(abort?: Error) { + if (!this.#closed) { + const arrivals = this.#state.timeline.filter((group) => !(group.closed.peek() instanceof Error)); + this.#arrivals = arrivals.map((group) => ({ + sequence: group.sequence, + arrived: hooks.groupArrived(group), + })); + } this.#closed = true; // Settle if we're first (the producer may already have); either way drop anything // still buffered. Groups parked at the withRange cap deliberately outlive a clean @@ -2208,6 +2227,8 @@ export class Subscriber { this.#state.timeline.length = 0; this.#wall.timer?.abort(); this.#wall.timer = undefined; + // A deadline kept in #arrivals may still arm a wakeup. + this.#wall.at = Number.POSITIVE_INFINITY; } /** diff --git a/js/net/src/util/given_up.ts b/js/net/src/util/given_up.ts new file mode 100644 index 00000000000..3c9db18a2aa --- /dev/null +++ b/js/net/src/util/given_up.ts @@ -0,0 +1,27 @@ +import { race } from "@moq/signals"; +import type { Consumer as GroupConsumer } from "../group.ts"; + +// Why to stop writing `group`: the subscription's budget gave it up, or it failed for good +// before it was read whole (evicted, or its copy aborted with no route to continue it). +function reason(group: GroupConsumer): Error | undefined { + const closed = group.closed.peek(); + return group.expired.peek() ?? (closed instanceof Error ? closed : undefined); +} + +/** + * Run a publisher's write of `group`, settling with why to stop it instead if that comes + * first: `expired`, or `closed` with an error. A clean close is no reason, and a group + * already given up never starts the write. Rejects if the write does. Mirrors the Rust + * publishers' `poll_given_up`. + */ +export async function untilGivenUp(group: GroupConsumer, write: () => Promise): Promise { + let stop = reason(group); + if (stop) return stop; + const done = write().then(() => true as const); + for (;;) { + const closed = group.closed.peek() === undefined ? [group.closed] : []; + if ((await race([done, group.expired, ...closed])) === true) return undefined; + stop = reason(group); + if (stop) return stop; + } +} diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index 9c0677d3b33..b56b029eddd 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -103,7 +103,7 @@ Work owned by this README, after the children land: - [Claim request type](/quest/m1/public-model/claim-request-type.md) - accepting an application claim's request fails to compile instead of panicking - [Public ingest](/quest/m1/public-model/ingest.md) - a custom subscriber writes received groups, frames, starts, and ends into a track through public calls -- [Public group abandonment and JS feed start](/quest/m1/public-model/serve.md) - a custom Rust publisher parked on its transport learns when to give up on a group, and a JS one where the feed starts, the last serving items left +- [Public JS feed start](/quest/m1/public-model/serve.md) - a custom JS publisher learns where the source's feed starts, the last serving item left - [Public routes and answering](/quest/m1/public-model/answer.md) - a custom relay ingests routes, answers broadcast and track requests on demand, and advertises without echoing a peer's routes back - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/serve.md b/quest/m1/public-model/serve.md index 59ab96bffbe..b495f1b50fb 100644 --- a/quest/m1/public-model/serve.md +++ b/quest/m1/public-model/serve.md @@ -1,13 +1,10 @@ -# [S] Public group abandonment and JS feed start +# [XS] Public JS feed start ## Goal -A custom `moq-net` publisher waiting on its transport, for stream credit or to -drain, learns through a public call when to give up on a group: the budget -expired it, or its copy was aborted before the publisher read it all and no -route will continue it. A custom `@moq/net` publisher learns where the -source's feed starts, as the public Rust `poll_start` answers. The built-in -lite and IETF publishers use the same calls. +A custom `@moq/net` publisher learns where the source's feed starts, as the +public Rust `track::Subscriber::poll_start` answers. The built-in lite +publisher uses the same call. ## Plan @@ -15,37 +12,18 @@ The rest of public serving landed: the `with_range`/`withRange` cursor, public `poll_start`, `poll_drop`, `poll_expired`, `Position::final_sequence`, `Subscription::{start, end, with_start, with_end}`, and in JS the `Recv` union from `tryRecvGroup`, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, -`Track.Consumer.info({ hold })`, and `Group.Consumer.expired`. The live-edge -answers moved to [track-live](/quest/m1/track-live.md), and -`track::Consumer::final_sequence` to -[the deferred quest](/quest/m1/public-model/deferred.md). +`Track.Consumer.info({ hold })`, and `Group.Consumer.expired`. A publisher +gives up on a group it is still writing once `expired` settles, or `closed` +(Rust `poll_finished`) fails. The live-edge answers moved to +[track-live](/quest/m1/track-live.md), and `track::Consumer::final_sequence` +to [the deferred quest](/quest/m1/public-model/deferred.md). -Left: the crate-private `group::Consumer::poll_abandoned(waiter, held)`, -which [#6140](https://github.com/moq-dev/moq/pull/6140) added so a group -parked on stream credit gives up. It answers `poll_expired` plus the aborted -copy. **Decision** on the public shape: - -- Make `poll_abandoned` public and `poll_expired` private, dropping the - `held` flag the way `poll_expired` did (`poll_open` passes `false` today, so - an empty finished group parked on credit would then expire). Recommended: - one call answers "stop writing this group". -- Keep both public, with `held` exposed. A bool parameter callers must reason - about. -- Keep `poll_abandoned` private: a custom publisher reads the abort on its - next frame read instead, but holds the credit it waited for until then. - -Also left: the JS `hooks.sourceStart`, which +Left: the JS `hooks.sourceStart`, which [#6206](https://github.com/moq-dev/moq/pull/6206) added after this cut so the lite publisher keeps a descending feed's start. It is the JS counterpart of `poll_start` (the source's start, raised to the cursor floor, or `"pending"` until the upstream START arrives); make it a public `Track.Subscriber` call. -JS has the same gap: [#6214](https://github.com/moq-dev/moq/pull/6214) races a -parked group open against the private `hooks.guardGroup`, since -`Group.Consumer.expired` covers the budget but not an evicted copy. Settle its -public shape with `poll_abandoned`'s, as an `abandoned` promise beside -`expired` or by widening `expired` to every terminal give-up. - ## Related - [Public model](/quest/m1/public-model/README.md) - the epic, its rules, and the inventory method diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 7a3e4540c17..41efc6aa79f 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -17,7 +17,10 @@ subscriber.set_groups(5..); let subscriber = subscriber.with_range(5..); ``` +`group::Consumer::finished` (and `poll_finished`) now ends cleanly once a `with_range` frame cap is reached, where it waited for the group itself to end, as reads already do. + A custom publisher can now reach what the built-in ones use: `track::Subscriber::poll_start`, `track::Subscriber::poll_drop`, `group::Consumer::poll_expired`, `subscription::Position::final_sequence`, and `Subscription::{start, end, with_start, with_end}` for the covering span. +It gives up on a group it is still writing once `poll_expired` is true, or `poll_finished` fails because the frames it has yet to read are gone. ### A dropped or cut group ends its reader with an error (#6143) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index b7a87869433..8970ccf3ee5 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -4888,6 +4888,22 @@ impl Queued { } } +/// Why to stop writing `group` while the transport parks it: the subscription's budget gave +/// it up, or the frames this cursor has yet to read are gone with no route to continue them. +/// A clean finish is no reason. +/// +/// Waking on every frame written to a parked group costs what a reader parked at the live +/// edge already pays: each of its pending reads judges the budget too. +fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option { + if group.poll_expired(waiter) { + return Some(Error::Old); + } + match group.poll_finished(waiter) { + Poll::Ready(Err(err)) => Some(err), + _ => None, + } +} + /// Serves one group on its own unidirectional stream in the moq-transport /// subgroup format. struct GroupServe { @@ -4993,7 +5009,7 @@ impl GroupServe { if !matches!(self.state, GroupState::Open) { return Poll::Ready(Ok(())); } - if let Some(err) = self.group.poll_abandoned(waiter, false) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { self.state = GroupState::Done; return Poll::Ready(Err(err)); } @@ -5061,10 +5077,9 @@ impl GroupServe { // 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, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -5081,10 +5096,9 @@ impl GroupServe { // 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, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 3693df77de6..b038d7005b3 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -4281,6 +4281,22 @@ enum Rank { Queue(PriorityHandle), } +/// Why to stop writing `group` while the transport parks it: the subscription's budget gave +/// it up, or the frames this cursor has yet to read are gone with no route to continue them. +/// A clean finish is no reason. +/// +/// Waking on every frame written to a parked group costs what a reader parked at the live +/// edge already pays: each of its pending reads judges the budget too. +fn poll_given_up(group: &mut group::Consumer, waiter: &kio::Waiter) -> Option { + if group.poll_expired(waiter) { + return Some(Error::Old); + } + match group.poll_finished(waiter) { + Poll::Ready(Err(err)) => Some(err), + _ => None, + } +} + /// Serves one group on its own unidirectional stream: the header, then every /// frame, applying queue and SUBSCRIBE_UPDATE priority changes as they land. struct GroupServe { @@ -4367,7 +4383,7 @@ impl GroupServe { if !matches!(self.state, GroupState::Open) { return Poll::Ready(Ok(())); } - if let Some(err) = self.group.poll_abandoned(waiter, false) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { self.settle_open(false); self.state = GroupState::Done; return Poll::Ready(Err(err)); @@ -4488,10 +4504,9 @@ impl GroupServe { // 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, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; @@ -4508,10 +4523,9 @@ impl GroupServe { // 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, or one - // whose unread rest the cache evicted. `true` because the transport - // still owns bytes the cursor has released. + // whose unread rest the cache evicted. Poll::Pending => { - if let Some(err) = self.group.poll_abandoned(waiter, true) { + if let Some(err) = poll_given_up(&mut self.group, waiter) { break 'serve Err(err); } return Poll::Pending; diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index baea1d10ed7..4d076ad0282 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2655,7 +2655,8 @@ impl Consumer { /// A publisher still writing the group polls this while it waits on its own transport, /// which the group's reads cannot see: once the subscription's /// [`max_delay`](crate::track::Subscription::max_delay) expires the group, it abandons - /// the stream, even with every frame already read off. Stays `true` once set. + /// the stream, even with every frame already read off. It abandons it too once + /// [`Self::poll_finished`] fails. Stays `true` once set. pub fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { self.poll_expiry(waiter, true) } @@ -2700,44 +2701,6 @@ impl Consumer { self.expired } - /// Why a wire publisher waiting on the transport, for stream credit or to drain, should - /// give up on this group: the drift budget convicted it ([`Error::Old`]), or its copy - /// was aborted (evicted, cut, or failed upstream) before this cursor read it all and no - /// route will continue it. `held` as in [`Self::poll_expiry`]. - /// - /// A machine parked on stream credit reads nothing, so without this an aborted group, - /// which never expires, would wait for credit it could only spend on a reset. - // pending: /quest/m1/public-model/serve.md - pub(crate) fn poll_abandoned(&mut self, waiter: &kio::Waiter, held: bool) -> Option { - if self.poll_expiry(waiter, held) { - return Some(Error::Old); - } - // Registered on the close alone: an abort closes the channel, and waking on every - // frame written to a parked group would cost a stalled subscriber per frame. - if self.cursor.state.poll_closed(waiter).is_pending() { - return None; - } - let aborted = { - let state = self.cursor.state.read(); - let unread = !self.cursor.capped() && state.fin.is_none_or(|fin| self.cursor.index < fin); - match &state.abort { - // The rest of the group is gone; what was read already is not. - Some(err) if unread => err.clone(), - // Read to its end, or finished and closed with its last producer: still servable. - _ => return None, - } - }; - // A front's reader may continue the group from another route's copy when it reads. - if self - .recover - .as_ref() - .is_some_and(|recover| recover.wants(Some(&aborted), waiter)) - { - return None; - } - Some(aborted) - } - /// Whether expiry can still discard content or unblock a group that may grow. fn expiry_pending(&self) -> bool { self.cursor.expiry_pending() @@ -2942,7 +2905,12 @@ impl Consumer { Ok(out.filled_mut()) } - /// Poll until the group terminates, returning this cursor's next frame index. + /// Poll until the group terminates, or this cursor reaches the end of its range, returning + /// its next frame index. + /// + /// A publisher still writing the group races its transport against this and + /// [`Self::poll_expired`]: an error here means the frames it has yet to read are gone + /// (evicted, cut, or failed upstream) and no route will continue them. pub fn poll_finished(&mut self, waiter: &kio::Waiter) -> Poll> { if self.recover.is_none() { return self.poll_finished_once(waiter); @@ -2958,6 +2926,10 @@ impl Consumer { return Poll::Ready(Err(Error::Old)); } let index = self.cursor.index; + // Reads end cleanly at the range's end, whatever becomes of the frames past it. + if self.cursor.capped() { + return Poll::Ready(Ok(index as u64)); + } let res = self .cursor .poll(waiter, |state| state.poll_end(index)) @@ -2965,7 +2937,8 @@ impl Consumer { self.poll_expired_if_blocked(waiter, res) } - /// Block until the group terminates, returning this cursor's next frame index. + /// Block until the group terminates, or this cursor reaches the end of its range, returning + /// its next frame index. /// /// This answers for the cursor, not the group: a reader that drained every frame gets the /// clean end even if the group was aborted afterwards to release its cache, while one that @@ -5023,6 +4996,29 @@ mod test { assert!(matches!(finished.poll_finished(&waiter), Poll::Ready(Err(Error::Old)))); } + /// A reader capped by its range finishes there cleanly whatever becomes of the frames past + /// it, so a publisher that served the range keeps its stream when the rest fails upstream. + #[test] + fn a_capped_reader_finishes_at_its_range_end() { + let mut producer = Info { sequence: 0 }.produce(); + for payload in [b"a", b"b"] { + producer + .write_frame(crate::Timestamp::ZERO, Bytes::from_static(payload)) + .unwrap(); + } + let waiter = kio::Waiter::noop(); + let mut capped = producer.consume().with_range(..1); + let mut whole = producer.consume(); + assert!(capped.poll_finished(&waiter).is_pending(), "its frame is still unread"); + for reader in [&mut capped, &mut whole] { + assert!(matches!(reader.poll_read_frame(&waiter), Poll::Ready(Ok(Some(_))))); + } + + producer.abort(Error::Cancel).unwrap(); + assert!(matches!(capped.poll_finished(&waiter), Poll::Ready(Ok(1)))); + assert!(matches!(whole.poll_finished(&waiter), Poll::Ready(Err(Error::Cancel)))); + } + /// A publisher that read every frame of a finished group still learns when the budget /// gives up on it, so it can abandon the stream it is still writing. #[test] From bde8ad949c5879737e56e7acc88b78b261aac36b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 15:31:27 -0700 Subject: [PATCH 08/18] fix(json): move the PR's snapshot and window tests onto main's API; plan resumed drops and floor quests Co-Authored-By: Claude Opus 5.5 --- js/json/src/snapshot/snapshot.test.ts | 2 +- js/json/src/window/window.test.ts | 2 +- js/net/src/resume.ts | 5 +++- quest/m1/README.md | 2 ++ quest/m1/resume-drops.md | 36 +++++++++++++++++++++++++++ quest/m1/resume-floor.md | 36 +++++++++++++++++++++++++++ 6 files changed, 80 insertions(+), 3 deletions(-) create mode 100644 quest/m1/resume-drops.md create mode 100644 quest/m1/resume-floor.md diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 046f98b5e6a..cbe6ba971e7 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -153,7 +153,7 @@ test("latest abandons a held group when a newer snapshot group rolls", async () // below its cap, and a datagram past every group does not strand it. test("latest stays inside the reader's range", async () => { const track = new Track.Producer("test"); - const producer = new Producer({ track, deltaRatio: 0 }); + const producer = new Producer({ track, deltas: false }); const subscriber = track.subscribe({ maxDelay: REPLAY_LATENCY }).withRange({ end: { excluded: 2 } }); const consumer = new Consumer({ track: subscriber }); diff --git a/js/json/src/window/window.test.ts b/js/json/src/window/window.test.ts index 78a20d7bf15..b5a08fb9c39 100644 --- a/js/json/src/window/window.test.ts +++ b/js/json/src/window/window.test.ts @@ -594,7 +594,7 @@ test("events carry their frame's timestamp, and a header's restated records get producer.cut(); producer.push({ value: { n: 3 }, at: at(400) }); producer.finish(); - late.setGroups({ start: { included: 1 } }); + late.withRange({ start: { included: 1 } }); const events: Timed>[] = []; for await (const event of new Consumer({ track: late })) events.push(event); expect(events.map((event) => event.value)).toEqual([ diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index f6a6f3dd960..d9bd0d4c25d 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -889,7 +889,10 @@ class Reader implements ResumeSource { this.wake(); } else if (declared.group === end.group && declared.frame === end.frame) { return; - } else if (track.finalSequence(declared) === track.finalSequence(end) && (declared.frame === 0 || end.frame === 0)) { + } else if ( + track.finalSequence(declared) === track.finalSequence(end) && + (declared.frame === 0 || end.frame === 0) + ) { if (declared.frame === 0) this.#declared = end; } else { this.#refuse(); diff --git a/quest/m1/README.md b/quest/m1/README.md index 9388d63fe5b..06a73c4fd74 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -131,6 +131,8 @@ tracks, so per-group stats stop costing cluster announces. - [Rust resume holds a declared end](/quest/m1/resume-rust-end.md) - a resumed Rust track keeps a declared end across copies, dedupes flapping copies, and judges retention inside the reader's window - [Rust resume checks compression](/quest/m1/resume-compress.md) - a same-epoch route copy with a different `compress` is refused instead of corrupting framing - [Rust resume backs single-route groups](/quest/m1/resume-handed-out.md) - a group first read from one route keeps the later copy that holds it, with a passthrough benchmark +- [JS resume reports drops](/quest/m1/resume-drops.md) - a routed JS subscriber reports its copies' dropped groups, so publishers forward SUBSCRIBE_DROP +- [Lowered resume floor](/quest/m1/resume-floor.md) - lowering a resumed reader's floor re-offers groups only a released copy cached - [WebGPU on Safari](/quest/m1/webgpu-safari.md) - the WebGPU renderer is verified on Safari 26 for macOS and iOS - [Interop finish](/quest/m1/interop-finish.md) - the interop matrix proves a clean broadcast finish across implementations - [Exporters follow a rendition to a new track](/quest/m1/export-rendition-rebind.md) - the fMP4, TS, MKV and FLV exporters rebuild a rendition whose resolved `track` or `broadcast` changes under the same ID diff --git a/quest/m1/resume-drops.md b/quest/m1/resume-drops.md new file mode 100644 index 00000000000..65c6af2476b --- /dev/null +++ b/quest/m1/resume-drops.md @@ -0,0 +1,36 @@ +# [S] JS resume reports drops + +## Goal + +`tryRecvGroup({ drops: true })` on a routed (resumed) `@moq/net` +`Track.Subscriber` reports the groups its copies gave up as a `drop`, as a +direct subscriber does and as the Rust resume reader forwards its serving +copy's `poll_drop`. A lite or IETF publisher serving a routed track then sends +`SUBSCRIBE_DROP` for them instead of leaving its peer waiting on groups that +never arrive. + +## Plan + +Found by Codex on [moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138) +and present on `main` before it: `#tryRecvGroup` hands a resumed subscriber to +`#tryResumed`, and `resume.ts` `take()` reads each copy without `drops`, so an +upstream `SUBSCRIBE_DROP` or a budget skip on a copy is consumed silently. + +Open decisions, to settle before implementing: + +- Which copy reports drops across a switch. Recommended: the serving copy + only, as Rust does in `model/resume.rs`. +- Whether a group that failed on one copy but that another copy may still + deliver counts as a drop. Recommended: no, until no copy can deliver it. +- How a reported run joins the resumed reader's delivered record, so a later + copy never serves a group already reported dropped. + +Regression test: a resumed subscriber whose serving copy receives +`SUBSCRIBE_DROP` reports it through `tryRecvGroup({ drops: true })`, and a +downstream lite-07 publisher forwards it. + +Public API: behavior only. Wire: none. + +## Related + +- [Public JS feed start](/quest/m1/public-model/serve.md) - the public serving calls this rides on diff --git a/quest/m1/resume-floor.md b/quest/m1/resume-floor.md new file mode 100644 index 00000000000..8133cc7069c --- /dev/null +++ b/quest/m1/resume-floor.md @@ -0,0 +1,36 @@ +# [S] A lowered resume floor re-offers a released copy's groups + +## Goal + +Lowering a resumed reader's floor with `with_range` (JS `withRange`) offers +every group below the old floor that some route still caches and the reader +never read, as it does for a direct reader. Today, in Rust, a reader that +switches routes while its floor is high lets go of the replaced copy that +cached the lower groups, so a later lowering re-offers only what the serving +copy holds: `Copy::start` clamps the requested floor to that copy's resume +point. + +## Plan + +Found by Codex on [moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138), +which made lowering a floor assign. Its Rust test covers one copy only. + +Open decision, to settle before implementing: + +- Recommended: once the floor drops below a released copy's groups, ask the + serving route for them on demand, rather than keeping every replaced copy + alive in case the floor drops later, which holds memory for a lowering that + may never come. +- Alternative: narrow the `with_range` contract to the copies the reader still + holds, and document it. + +Check the JS resume reader for the same gap, and cover both with a two-copy +test: switch routes with a high floor, release the old copy, lower the floor, +and expect the groups only it cached. + +Public API: behavior only. Wire: none. + +## Related + +- [Public JS feed start](/quest/m1/public-model/serve.md) - the public serving cursor this extends +- [Rust resume backs single-route groups](/quest/m1/resume-handed-out.md) - also edits which replaced copies the Rust reader keeps From 09b8eeea53dcc6618c50c845bb094b98d1a10271 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 02:13:51 -0700 Subject: [PATCH 09/18] fix(net): keep the IETF drain's pause answer from main, and format The group drain races the pause itself, so only the header and object writes race it through `send`; `write` stays the budget and eviction guard. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.ts | 12 ++++++++---- rs/moq-net/src/model/resume.rs | 5 ++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 9686d07b0dd..ae05a1331ed 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -1134,13 +1134,17 @@ export class Publisher { // The subscription's budget, or an eviction of what is left to read, may give up on the // group mid-write, which abandons the stream. A group already given up never starts the write. const write = async (op: () => Promise) => { - const stop = await race([untilGivenUp(group, op), cancelled]); - if (left) throw new Error("unsubscribed while serving the group"); + const stop = await untilGivenUp(group, op); if (stop) throw stop; }; + // Writing the group stops for the pause too; the drain below answers it without a reset. + const send = async (op: () => Promise) => { + await race([write(op), cancelled]); + if (left) throw new Error("unsubscribed while serving the group"); + }; try { - await write(() => header.encode(stream, this.#session.version)); + await send(() => header.encode(stream, this.#session.version)); // The first written object goes on the wire as its absolute id, so a trimmed // head shows the true numbering rather than a silently renumbered group. let first = true; @@ -1166,7 +1170,7 @@ export class Publisher { const obj = new Frame({ payload: read.payload, timestamp: read.timestamp }); const delta = first ? read.sequence : 0; first = false; - await write(() => obj.encode(stream, header.flags, timescale, this.#session.version, delta)); + await send(() => obj.encode(stream, header.flags, timescale, this.#session.version, delta)); } // The track ends right after this group's last object, so the marker rides this diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 37d67ac6f50..43830171a44 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -983,7 +983,10 @@ impl Reader { copy.floor = copy.floor.max(self.newest.map(Position::group)); let start = copy.start(self.groups.0); if let (Sub::Ready(sub), Some(_)) = (&mut copy.sub, copy.floor) { - sub.set_range((Bound::Included(start), self.groups.1.map_or(Bound::Unbounded, Bound::Excluded))); + sub.set_range(( + Bound::Included(start), + self.groups.1.map_or(Bound::Unbounded, Bound::Excluded), + )); } copy.update(&self.mirrored); self.copies.push(copy); From 87eab68515d9505831601926b8aeb85b654fd3d5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 11:38:20 -0700 Subject: [PATCH 10/18] refactor(net)!: keep the serving items internal, public with_range only The public-model goal is dropped (moq-dev/moq#6581): items go public only with a non-session consumer. with_range and the bug fixes stay; the serving calls the sessions use go back to pub(crate) in Rust and hooks or @internal in JS. Ordered.tryNextGroup stays public as GroupConsumer | undefined, mirroring Rust poll_next_group, for js/json and js/flate. Co-Authored-By: Claude Opus 5.5 --- js/flate/src/snapshot/consumer.ts | 4 +- js/json/src/snapshot/consumer.ts | 4 +- js/net/MIGRATE.md | 17 --- js/net/bench/resume.ts | 15 ++- js/net/bench/track.ts | 7 +- js/net/src/group.ts | 2 + js/net/src/ietf/publisher.ts | 12 +- js/net/src/ietf/subscriber.ts | 11 +- js/net/src/internal.ts | 52 ++++++++- js/net/src/lite/publisher.ts | 10 +- js/net/src/resume.test-util.ts | 2 +- js/net/src/resume.test.ts | 53 ++++----- js/net/src/resume.ts | 23 ++-- js/net/src/track.test.ts | 97 +++++++--------- js/net/src/track.ts | 87 ++++++-------- js/net/src/wire.ts | 8 +- quest/m1/public-model/README.md | 2 +- quest/m1/public-model/deferred.md | 4 +- quest/m1/public-model/serve.md | 168 +++++++++++++++++++++++---- quest/m1/resume-drops.md | 10 +- quest/m1/resume-floor.md | 1 - quest/m1/track-live.md | 14 +-- rs/moq-net/MIGRATE.md | 5 +- rs/moq-net/src/model/group.rs | 8 +- rs/moq-net/src/model/subscription.rs | 20 +++- rs/moq-net/src/model/track.rs | 18 +-- sh/rs/model-markers.py | 2 +- 27 files changed, 387 insertions(+), 269 deletions(-) diff --git a/js/flate/src/snapshot/consumer.ts b/js/flate/src/snapshot/consumer.ts index af5565bc22c..fe2258f2e99 100644 --- a/js/flate/src/snapshot/consumer.ts +++ b/js/flate/src/snapshot/consumer.ts @@ -69,8 +69,8 @@ export class Consumer { // Taking groups, not the track's largest position, ignores datagrams (which share // the sequence space) and stays inside any range the caller set on the reader. // Mirrors the Rust consumer. - for (let recv = this.#track.tryNextGroup(); recv.kind === "group"; recv = this.#track.tryNextGroup()) { - this.#open(recv.group); + for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { + this.#open(group); } } diff --git a/js/json/src/snapshot/consumer.ts b/js/json/src/snapshot/consumer.ts index f1262046280..240508c214b 100644 --- a/js/json/src/snapshot/consumer.ts +++ b/js/json/src/snapshot/consumer.ts @@ -68,9 +68,9 @@ export class Consumer { // the sequence space) and stays inside any range the caller set on the reader. // Mirrors the Rust consumer. A newer group restarts from a full snapshot, so switching mid-group loses // nothing but stale state. - for (let recv = this.#track.tryNextGroup(); recv.kind === "group"; recv = this.#track.tryNextGroup()) { + for (let group = this.#track.tryNextGroup(); group; group = this.#track.tryNextGroup()) { this.#group?.close(); - this.#group = recv.group; + this.#group = group; this.#framesRead = 0; } } diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index ef3fcd3546c..c1e69dd93af 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -17,23 +17,6 @@ subscriber.setGroups({ end: { excluded: 10 } }); subscriber.withRange({ start: { included: floor }, end: { excluded: 10 } }); ``` -### `tryRecvGroup` says why it returned no group - -`Track.Subscriber.tryRecvGroup()` returns a `Track.Recv` instead of a group or `undefined`, and no longer throws the track's error. -Read `recv.group` when `recv.kind === "group"`; `idle` and `boundary` may change once `groupChanged(fn)` fires, `done` is the end, and `error` carries what it used to throw. -`{ drops: true }` also reports the sequences the cursor gave up. - -```ts -// Before -const group = subscriber.tryRecvGroup(); -// After -const recv = subscriber.tryRecvGroup(); -const group = recv.kind === "group" ? recv.group : undefined; -``` - -`Track.Ordered.tryNextGroup()`, `Track.finalSequence(end)`, `Track.Consumer.info({ hold })`, and `Group.Consumer.expired` are new. -A custom publisher races its writes against `expired` and against `closed` settling with an error (an eviction, or an aborted copy no route continues), and resets the stream once either does. - ### A listing says whether a removed track finished (#6399) `Broadcast.TracksEvent` gains `{ kind: "finished", name }`: the track left the listing because it finished. `{ kind: "removed", name }` now means it left unfinished. Handle both where you matched `"removed"`. diff --git a/js/net/bench/resume.ts b/js/net/bench/resume.ts index 47f7184967f..59b93166500 100644 --- a/js/net/bench/resume.ts +++ b/js/net/bench/resume.ts @@ -28,15 +28,14 @@ const flush = () => new Promise((resolve) => setImmediate(resolve)); function read(subscribers: Subscriber[]) { for (const subscriber of subscribers) { - const recv = subscriber.tryRecvGroup(); - if (recv.kind !== "group") throw new Error("group was not delivered"); - const group = recv.group; + const group = subscriber.tryRecvGroup(); + if (!group) throw new Error("group was not delivered"); const frame = group.tryReadFrame(); if (!frame) throw new Error("frame was not delivered"); checksum += frame.payload.byteLength; group.close(); // Read until idle, as a reader parked on the next group does. - if (subscriber.tryRecvGroup().kind === "group") throw new Error("group delivered twice"); + if (subscriber.tryRecvGroup()) throw new Error("group delivered twice"); } } @@ -155,9 +154,9 @@ async function measureFlaps(readers: number, flaps: number): Promise { front.consumer.track("seq").subscribe({ maxDelay: Milli(3_600_000) }), ); const held = subscribers.map((subscriber) => { - const recv = subscriber.tryRecvGroup(); - if (recv.kind !== "group") throw new Error("missing held group"); - return recv.group; + const group = subscriber.tryRecvGroup(); + if (!group) throw new Error("missing held group"); + return group; }); await flush(); const start = performance.now(); @@ -165,7 +164,7 @@ async function measureFlaps(readers: number, flaps: number): Promise { front.serve(handles[(flap + 1) % 2]); await flush(); for (const subscriber of subscribers) { - if (subscriber.tryRecvGroup().kind === "group") throw new Error("repeated held group"); + if (subscriber.tryRecvGroup()) throw new Error("repeated held group"); } } const elapsed = performance.now() - start; diff --git a/js/net/bench/track.ts b/js/net/bench/track.ts index c0452c1e32a..2a2e00adbc2 100644 --- a/js/net/bench/track.ts +++ b/js/net/bench/track.ts @@ -38,9 +38,8 @@ const flush = () => new Promise((resolve) => setImmediate(resolve)); function receive(subscribers: Subscriber[]): GroupConsumer[] { const received: GroupConsumer[] = []; for (const subscriber of subscribers) { - const recv = subscriber.tryRecvGroup(); - if (recv.kind !== "group") throw new Error("group was not delivered"); - const group = recv.group; + const group = subscriber.tryRecvGroup(); + if (!group) throw new Error("group was not delivered"); const frame = group.tryReadFrame(); if (!frame) throw new Error("frame was not delivered"); checksum += frame.payload.byteLength; @@ -117,7 +116,7 @@ async function measure( clock += CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8 + 1; const idleStart = now(); const replay = producer.subscribe({ maxDelay: window }); - if (replay.tryRecvGroup().kind === "group") throw new Error("idle cache entries were retained"); + if (replay.tryRecvGroup()) throw new Error("idle cache entries were retained"); const idle = (now() - idleStart) * 1000; replay.close(); return { publish: (elapsed * 1000) / groups, end, idle }; diff --git a/js/net/src/group.ts b/js/net/src/group.ts index 02d4182cd45..e8f2fc18b62 100644 --- a/js/net/src/group.ts +++ b/js/net/src/group.ts @@ -640,6 +640,8 @@ export class Consumer { * settling with an error, and abandons the stream once either does. Peek it synchronously * (`undefined` while within budget), or race it, which stops watching the budget once the * race ends. + * + * @internal Wire publishers only. */ get expired(): GetPromise { this.#expired ??= new Expired( diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index f9d20c3f268..3486ab46b12 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -2235,7 +2235,7 @@ export class Publisher { let answer: TrackStatusOk; try { const broadcast = await this.#resolve(name, hold.signal, msg.epoch); - const info = await broadcast.track(msg.trackName).info({ hold: hold.signal }); + const info = await wireOf(broadcast).resolveTrackInfo(msg.trackName, hold.signal); const largest = wireOf(broadcast).largest(msg.trackName); answer = new TrackStatusOk({ requestId: @@ -2934,7 +2934,7 @@ interface ServeRange { /** Read within a fixed filter, ending at its cap once the track itself finishes. */ async function servingGroup(track: TrackSubscriber): Promise { for (;;) { - const recv = track.tryRecvGroup(); + const recv = hooks.tryRecvGroup(track, false); if (recv.kind === "group") return recv.group; if (recv.kind === "error") throw recv.error; // A local reader holds this boundary for a possible cap raise; a fixed wire @@ -2942,7 +2942,7 @@ async function servingGroup(track: TrackSubscriber): Promise((resolve) => { - const dispose = track.groupChanged(() => { + const dispose = hooks.groupChanged(track, () => { dispose(); resolve(); }); @@ -3000,10 +3000,8 @@ type FillServe = */ function takeGroup(cache: TrackSubscriber, sequence: number): group.Consumer { for (;;) { - const recv = cache.tryRecvGroup(); - if (recv.kind === "error") throw recv.error; - if (recv.kind !== "group") throw new Error(`group not found: ${sequence}`); - const group = recv.group; + const group = cache.tryRecvGroup(); + if (!group) throw new Error(`group not found: ${sequence}`); if (group.sequence === sequence) return group; group.close(); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index f9b4a0f8d1e..faded4b31bd 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -20,14 +20,21 @@ import { } from "../error.ts"; import * as netGroup from "../group.ts"; import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; -import { groupBounds, hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; +import { + finalSequence, + groupBounds, + hiddenBelow, + hooks, + scopeCaptures, + scopeHead, + scopeOverlaps, +} from "../internal.ts"; import type { Lister } from "../listing.ts"; import * as Path from "../path.ts"; import { type Cursor, Reader, type Stream } from "../stream.ts"; import { Tail } from "../tail.ts"; import type { Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; -import { finalSequence } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { Deadline, requestOptions } from "../util/deadline.ts"; import { abandoned as demandAbandoned, isAbandoned, unwanted } from "../util/demand.ts"; diff --git a/js/net/src/internal.ts b/js/net/src/internal.ts index 92f80c7c942..b0762eb201d 100644 --- a/js/net/src/internal.ts +++ b/js/net/src/internal.ts @@ -16,7 +16,7 @@ import type { Frame, Consumer as GroupConsumer, Producer as GroupProducer } from import { isAnonymous, type Route } from "./hop.ts"; import * as Path from "./path.ts"; import type { Timestamp } from "./time.ts"; -import type { Groups, Info, Location, Producer, Recv, Request, Subscriber, Subscription } from "./track.ts"; +import type { Groups, Info, Location, Producer, Request, Subscriber, Subscription } from "./track.ts"; import type { Advertised, Advertisements } from "./wire.ts"; // private: plumbing @@ -174,6 +174,24 @@ export function runGaps(runs: readonly Run[], start: number, end: number): Run[] return gaps; } +/** + * What a non-blocking group read found, which is everything the caller needs to decide what + * to do next: no second look at the track's closed state, and no ordering rule to get wrong. + */ +export type Recv = + /** A group to serve. It has already left the buffer, so dropping this is dropping the group. */ + | { kind: "group"; group: GroupConsumer } + /** Sequences `[start, end)` this cursor gave up without serving, and why. */ + | { kind: "drop"; start: number; end: number; error: Error } + /** Nothing readable, but the track is live and may produce more. */ + | { kind: "idle" } + /** The producer finished, yet groups above the cap are still held: raising it releases them. */ + | { kind: "boundary" } + /** The producer finished and the buffer is drained. Nothing can follow. */ + | { kind: "done" } + /** The track aborted. */ + | { kind: "error"; error: Error }; + /** A package-internal frame read as the group stores it. */ export interface ReadGroupFrame { /** Frame sequence within the group. */ @@ -367,6 +385,12 @@ export interface TrackRequestOptions { /** Maximum buffered datagrams per subscriber; mirrors Rust's bounded send buffer. */ export const MAX_DATAGRAMS = 64; +// private: plumbing +/** The first group an exclusive track end excludes whole: one past the last group that may exist. */ +export function finalSequence(end: Location): number { + return end.group + (end.frame === 0 ? 0 : 1); +} + // private: plumbing /** Hooks assigned in static blocks by the owning class. */ export const hooks: { @@ -419,7 +443,7 @@ export const hooks: { // private: capability gap /** Seed a received track from the publisher's reported edge; assigned by `track.ts`. */ reportedLargest: (producer: Producer, largest: Location | undefined) => void; - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md /** Snapshot the latest group sequence for wire positioning; assigned by `track.ts`. */ latestSequence: (subscriber: Subscriber) => number | undefined; // pending: /quest/m1/public-model/serve.md @@ -428,14 +452,23 @@ export const hooks: { * the upstream START that resolves it has yet to arrive; assigned by `track.ts`. */ sourceStart: (subscriber: Subscriber) => number | "pending" | undefined; - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md /** The newest frame buffered for a subscriber, which wire answers name; assigned by `track.ts`. */ bufferedLargest: (subscriber: Subscriber) => Location | undefined; /** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */ groupProgress: (group: GroupProducer, fn: (total: number) => void) => Dispose; - /** The sequence {@link tryNextGroup} (`ordered`) or `tryRecvGroup` would take next, without taking it. */ + // private: plumbing + /** + * Take the next group the subscriber's cursor allows, without waiting; assigned by `track.ts`. + * + * Synchronous so a caller can pop a group and act on it in the same turn. Park on + * {@link groupChanged} when it reports `idle` or `boundary`. With `dispositions`, what + * the cursor gives up is reported once as a `drop`. + */ + tryRecvGroup: (subscriber: Subscriber, dispositions: boolean) => Recv; + /** The sequence {@link tryNextGroup} (`ordered`) or {@link tryRecvGroup} would take next, without taking it. */ peekGroup: (subscriber: Subscriber, ordered: boolean) => number | undefined; - /** Take the next group in sequence order without waiting, as `tryRecvGroup` does in arrival order. */ + /** Take the next group in sequence order without waiting, as {@link tryRecvGroup} does in arrival order. */ tryNextGroup: (subscriber: Subscriber) => Recv; /** Wake once a subscriber's datagram cursor may read differently; fires at most once. */ datagramChanged: (subscriber: Subscriber, fn: () => void) => Dispose; @@ -473,6 +506,9 @@ export const hooks: { subscription: Subscription | undefined, source: (shell: ResumeShell) => ResumeSource, ) => Subscriber; + // private: plumbing + /** Wake once a subscriber's group cursor may read differently, including when the track declares its end; assigned by `track.ts`. */ + groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose; /** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */ fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void; /** @@ -587,6 +623,9 @@ export const hooks: { groupProgress: () => { throw new Error("group.ts not loaded"); }, + tryRecvGroup: () => { + throw new Error("track.ts not loaded"); + }, tryNextGroup: () => { throw new Error("track.ts not loaded"); }, @@ -635,6 +674,9 @@ export const hooks: { resumeSubscriber: () => { throw new Error("track.ts not loaded"); }, + groupChanged: () => { + throw new Error("track.ts not loaded"); + }, fetchBudget: () => { throw new Error("track.ts not loaded"); }, diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 64409f8667b..b46c3ffda31 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -11,14 +11,14 @@ import { error, NotFound, ProtocolViolation, reason, StreamCode, StreamError, un import { stored } from "../flate/group.ts"; import type * as group from "../group.ts"; import { Cost, type Hop, type Route, routesEqual } from "../hop.ts"; -import { hiddenBelow, hooks, insertRun, presented, type Run, runGaps } from "../internal.ts"; +import { finalSequence, hiddenBelow, hooks, insertRun, presented, type Run, runGaps } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; import { Priority, sendOrder } from "../priority.ts"; import { type Reader, type Stream, Writer } from "../stream.ts"; import { type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; -import { finalSequence, liteTimescale } from "../track.ts"; +import { liteTimescale } from "../track.ts"; import { untilAborted } from "../util/abort.ts"; import { nextChange } from "../util/change.ts"; import { untilGivenUp } from "../util/given_up.ts"; @@ -355,7 +355,7 @@ function waitForSubscription( for (const close of dispose) close(); resolve(); }; - dispose.push(controls.changed(wake), subscriber.groupChanged(wake)); + dispose.push(controls.changed(wake), hooks.groupChanged(subscriber, wake)); dispose.push(drops.changed(wake)); }); } @@ -1300,7 +1300,7 @@ export class Publisher { : undefined; const recv = first ? ({ kind: "group", group: first.group } as const) - : track.tryRecvGroup({ drops: emitRange }); + : hooks.tryRecvGroup(track, emitRange); first = undefined; switch (recv.kind) { case "error": @@ -1599,7 +1599,7 @@ export class Publisher { if (!entry || entry.release.signal.aborted) { const release = new AbortController(); const info = (async () => - trackInfoMessage(await front.track(track).info({ hold: release.signal }), this.version))(); + trackInfoMessage(await wireOf(front).resolveTrackInfo(track, release.signal), this.version))(); const created: TrackInfoEntry = { info, holders: 0, answered: false, release }; info.then( diff --git a/js/net/src/resume.test-util.ts b/js/net/src/resume.test-util.ts index da067f73a68..01bca3d581a 100644 --- a/js/net/src/resume.test-util.ts +++ b/js/net/src/resume.test-util.ts @@ -12,7 +12,7 @@ export function readsFrom(active: BroadcastConsumer | undefined, source: Broadca group.close(); const sub = active.track(name).subscribe(); try { - return sub.tryRecvGroup().kind === "group"; + return sub.tryRecvGroup() !== undefined; } finally { sub.close(); track.close(); diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index f4cab884640..58bf0a3b01a 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -21,12 +21,6 @@ const path = Path.from("live"); const enc = new TextEncoder(); const dec = new TextDecoder(); -/** The group a non-blocking read took, if any, throwing the track's error. */ -function taken(recv: track.Recv): GroupConsumer | undefined { - if (recv.kind === "error") throw recv.error; - return recv.kind === "group" ? recv.group : undefined; -} - async function settle() { await new Promise((resolve) => setTimeout(resolve, 0)); } @@ -70,7 +64,7 @@ function copy(source: BroadcastProducer) { /** Every group sequence readable without waiting. */ function drain(sub: track.Subscriber): number[] { const sequences: number[] = []; - for (let group = taken(sub.tryRecvGroup()); group; group = taken(sub.tryRecvGroup())) { + for (let group = sub.tryRecvGroup(); group; group = sub.tryRecvGroup()) { sequences.push(group.sequence); group.close(); } @@ -123,13 +117,13 @@ test("returning to a route reuses its subscription and held group", async () => const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(3_600_000) }); try { await clock.advance(Nano.zero); - const held = taken(sub.tryRecvGroup()); + const held = sub.tryRecvGroup(); if (!held) throw new Error("expected the held group"); expect(dec.decode((await held.readFrame())?.payload)).toBe("0.0"); for (let round = 0; round < 32; round++) { front.serve(handles[round % 2]); await clock.advance(Nano.zero); - expect(taken(sub.tryRecvGroup())).toBeUndefined(); + expect(sub.tryRecvGroup()).toBeUndefined(); expect(mirrored.mock.calls.length).toBe(1); } tracks[1].write(1); @@ -165,7 +159,7 @@ test("a returning route resumes where a fresh copy would", async () => { const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(3_600_000) }); try { await clock.advance(Nano.zero); - const held = taken(sub.tryRecvGroup()); + const held = sub.tryRecvGroup(); if (!held) throw new Error("expected the held group"); front.serve(handles[1]); await clock.advance(Nano.zero); @@ -452,7 +446,7 @@ test("a lagging same-epoch replica resumes from one publisher's bytes exactly on successor.close(); expect(seen).toEqual(Array.from({ length: 12 }, (_, index) => `${Math.floor(index / 4)}.${index % 4}`)); await clock.advance(Nano(0)); - expect(taken(sub.tryRecvGroup())).toBeUndefined(); + expect(sub.tryRecvGroup()).toBeUndefined(); // The source is still open, so the resumed subscription must stay live. expect(sub.closed.peek()).toBeUndefined(); } finally { @@ -506,7 +500,7 @@ test("a stalled group continues from the replacement at the next frame", async ( const tb = copy(b); const sub = active.track("seq").subscribe(); ta.write(0, 1, false); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -527,7 +521,7 @@ test("a group whose route fails continues from the replacement", async () => { const tb = copy(b); const sub = active.track("seq").subscribe(); const stalled = ta.write(0, 1, false); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -549,7 +543,7 @@ test("a group no route continues is given up once a newer one supersedes it", as const tb = copy(b); const sub = active.track("seq").subscribe(); const stalled = ta.write(0, 1, false); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); await group.readFrame(); @@ -576,7 +570,7 @@ test("a replacement claiming different track properties is refused once the old // The old copy failing with its route is what ends the track. old.close(new StreamError(StreamCode.SessionClosed)); await settle(); - expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); + expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); sub.close(); close(); @@ -909,7 +903,7 @@ test("a replacement spliced before the first copy answers is still checked again old.close(new StreamError(StreamCode.SessionClosed)); await settle(); - expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); + expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); sub.close(); front.consumer.close(); @@ -958,7 +952,7 @@ test("a late subscriber's first route is checked against properties an earlier s front.serve(b.consume()); const sub = front.consumer.track("seq").subscribe(); await settle(); - expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); + expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); sub.close(); front.consumer.close(); @@ -977,7 +971,7 @@ test("a recovery fetch a later route supersedes is abandoned", async () => { const stalled = ta.write(0, 1, false); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -1016,9 +1010,8 @@ for (const fails of [true, false]) { const stalled = ta.write(0, 1, false); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(60_000) }); - const recv = sub.tryRecvGroup(); - if (recv.kind !== "group") throw new Error("expected group 0"); - const group = recv.group; + const group = sub.tryRecvGroup(); + if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); if (fails) stalled.close(new StreamError(StreamCode.SessionClosed)); @@ -1105,7 +1098,7 @@ test("a failed group on a route whose replacement was refused ends with the refu const stalled = new GroupProducer(0); ta.writeGroup(stalled); stalled.writeFrame({ payload: enc.encode("0.0") }); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); await group.readFrame(); await sub.info(); @@ -1472,7 +1465,7 @@ test("a group handed out already failed with its route still continues on the ne // The old route fails group 0 before the reader takes it. const failed = ta.write(0, 1, false); failed.close(new StreamError(StreamCode.SessionClosed)); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); const read = group.readFrame(); @@ -1788,7 +1781,7 @@ test("a group read whole still expires once the reader lets go of its copy", asy const sub = front.consumer.track("seq").subscribe({ maxDelay: SECOND }); try { ta.write(0); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); // Read whole and released, as a publisher does before it drains the stream it wrote it to. expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -1990,7 +1983,7 @@ test.each([false, true])( copy(b); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe({ maxDelay: Milli(10_000) }); - expect(sub.tryRecvGroup().kind).toBe("idle"); + expect(hooks.tryRecvGroup(sub, false).kind).toBe("idle"); expect(hooks.tryRecvDatagram(sub).kind).toBe("idle"); ta.write(0); front.serve(b.consume()); @@ -2232,7 +2225,7 @@ test("closing with an abort settles a recovery in flight with it", async () => { const stalled = ta.write(0, 1, false); front.serve(a.consume()); const sub = front.consumer.track("seq").subscribe(); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); @@ -2446,7 +2439,7 @@ test.each(["handed out", "buffered"])("an end below a group another copy %s is r // The new route ends the track before a group the old one has. tb.producer.finishAt({ group: 3, frame: 0 }); await settle(); - expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); + expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); expect(sub.closed.peek()).toBeInstanceOf(Error); } finally { sub.close(); @@ -2502,7 +2495,7 @@ test("a group past the declared end on another copy is refused", async () => { // The new route has a group the end says never exists. tb.write(3); await settle(); - expect(() => taken(sub.tryRecvGroup())).toThrow("changed its properties"); + expect(() => sub.tryRecvGroup()).toThrow("changed its properties"); expect(sub.closed.peek()).toBeInstanceOf(Error); } finally { sub.close(); @@ -2611,7 +2604,7 @@ for (const fetched of [false, true]) { }); const sub = front.consumer.track("seq").subscribe(); front.serve(route); - const group = fetched ? await front.consumer.track("seq").fetchGroup(0) : taken(sub.tryRecvGroup()); + const group = fetched ? await front.consumer.track("seq").fetchGroup(0) : sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); asked.length = 0; @@ -2639,7 +2632,7 @@ test("a verdict every route repeats moves to the newer route once, then ends the const routeB = counted(b); front.serve(routeA.route); const sub = front.consumer.track("seq").subscribe(); - const group = taken(sub.tryRecvGroup()); + const group = sub.tryRecvGroup(); if (!group) throw new Error("expected group 0"); expect(dec.decode((await group.readFrame())?.payload)).toBe("0.0"); diff --git a/js/net/src/resume.ts b/js/net/src/resume.ts index 72f7f0897f0..a95b5b5c3d5 100644 --- a/js/net/src/resume.ts +++ b/js/net/src/resume.ts @@ -41,10 +41,12 @@ import { Delivered } from "./delivered.ts"; import { NotFound, SessionError, StreamCode, StreamError, sessionClosed } from "./error.ts"; import type { Consumer as GroupConsumer } from "./group.ts"; import { + finalSequence, type GroupRecover, groupBounds, hooks, MAX_DATAGRAMS, + type Recv, type RecvDatagram, type Replacement, type ResumeShell, @@ -247,8 +249,8 @@ function subscribe(wire: BroadcastWire, name: string, subscription: track.Subscr } /** Take a copy's next group, in sequence or arrival order. */ -function take(copy: Copy, ordered: boolean): track.Recv { - return ordered ? hooks.tryNextGroup(copy.sub) : copy.sub.tryRecvGroup(); +function take(copy: Copy, ordered: boolean): Recv { + return ordered ? hooks.tryNextGroup(copy.sub) : hooks.tryRecvGroup(copy.sub, false); } /** The first group past where `copy` was replaced: 0 for one replaced before any group. */ @@ -501,7 +503,7 @@ class Reader implements ResumeSource { return (end === undefined || sequence < end) && !delivered.has(sequence); } - tryGroup(ordered: boolean, delivered: Delivered): track.Recv { + tryGroup(ordered: boolean, delivered: Delivered): Recv { this.#delivered = delivered; this.sync(); // Before anything is handed out, so a copy claiming other content hands out none of it. @@ -620,7 +622,7 @@ class Reader implements ResumeSource { * Whether the track ended, once the serving copy's channel (as `done` reads it) ran out: * cleanly, or with a verdict a route failure does not excuse. */ - #end(done: (copy: Copy) => Error | null | undefined): track.Recv & { kind: "idle" | "done" | "error" } { + #end(done: (copy: Copy) => Error | null | undefined): Recv & { kind: "idle" | "done" | "error" } { const route = this.route; const last = this.#copies.at(-1); const serving = last?.generation === this.#generation ? last : undefined; @@ -643,7 +645,7 @@ class Reader implements ResumeSource { return { kind: "idle" }; } - #fail(error: Error): track.Recv & { kind: "error" } { + #fail(error: Error): Recv & { kind: "error" } { this.#shell.close(error); return { kind: "error", error }; } @@ -761,7 +763,7 @@ class Reader implements ResumeSource { const declared = this.#declared; const until = declared !== undefined - ? track.finalSequence(declared) - 1 + ? finalSequence(declared) - 1 : Math.max(this.#newest ?? -1, hooks.latestSequence(serving.sub) ?? -1); for (const copy of this.#copies) { if (!copy.replaced || copy.until !== undefined) continue; @@ -853,7 +855,7 @@ class Reader implements ResumeSource { }; disposes.push(this.route.changed.changed(once), this.#changed.changed(once)); for (const copy of this.#copies) - disposes.push(copy.sub.groupChanged(once), hooks.datagramChanged(copy.sub, once)); + disposes.push(hooks.groupChanged(copy.sub, once), hooks.datagramChanged(copy.sub, once)); return dispose; } @@ -886,7 +888,7 @@ class Reader implements ResumeSource { } const declared = this.#declared; if (declared && !this.#closed) { - const final = track.finalSequence(declared); + const final = finalSequence(declared); const seen = (sequence: number | undefined) => sequence !== undefined && sequence >= final; if ( seen(this.#newest) || @@ -912,10 +914,7 @@ class Reader implements ResumeSource { this.wake(); } else if (declared.group === end.group && declared.frame === end.frame) { return; - } else if ( - track.finalSequence(declared) === track.finalSequence(end) && - (declared.frame === 0 || end.frame === 0) - ) { + } else if (finalSequence(declared) === finalSequence(end) && (declared.frame === 0 || end.frame === 0)) { if (declared.frame === 0) this.#declared = end; } else { this.#refuse(); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 4cf7f4ccd84..79762c95adb 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -8,18 +8,12 @@ import { Version as IetfVersion } from "./ietf/version.ts"; import { hooks } from "./internal.ts"; import { textFrame } from "./mock.ts"; import { Timescale, Timestamp } from "./time.ts"; -import { infoDefaults, type Recv, type Subscription, Producer as TrackProducer } from "./track.ts"; +import { infoDefaults, type Subscription, Producer as TrackProducer } from "./track.ts"; import { unwanted } from "./util/demand.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); -/** The group a non-blocking read took, if any, throwing the track's error. */ -function taken(recv: Recv): GroupConsumer | undefined { - if (recv.kind === "error") throw recv.error; - return recv.kind === "group" ? recv.group : undefined; -} - // Matches the private idle cache window and Rust cache::DEFAULT_EXPIRY. const CACHE_WINDOW_MS = 30_000; @@ -1201,7 +1195,7 @@ test("a parked read wakes at its wall deadline", async () => { const track = producer.subscribe({ maxDelay: Milli(1000) }); const held = producer.appendGroup(); held.writeFrame({ payload: enc.encode("x"), timestamp: timescale && Timestamp.fromMillis(0) }); - const group = taken(track.tryRecvGroup()); + const group = track.tryRecvGroup(); if (!group) throw new Error("missing group"); expect(await group.readString()).toBe("x"); @@ -1267,8 +1261,8 @@ test("a live track retains its newest closed group through idle expiry", async ( } await clock.advance(10_000 + CACHE_WINDOW_MS + 200); const replay = producer.subscribe({ maxDelay: Milli(100) }); - expect(taken(replay.tryRecvGroup())?.sequence).toBe(2); - expect(taken(replay.tryRecvGroup())).toBeUndefined(); + expect(replay.tryRecvGroup()?.sequence).toBe(2); + expect(replay.tryRecvGroup()).toBeUndefined(); replay.close(); } finally { producer.close(); @@ -2253,13 +2247,13 @@ test("group ranges preserve progress and spell out inclusion", async () => { .subscribe({ maxDelay: Milli(5000) }) .withRange({ start: { included: 1 }, end: { included: 1 } }); for (let sequence = 0; sequence < 4; sequence++) producer.writeGroup(new GroupProducer(sequence)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(1); - expect(taken(track.tryRecvGroup())).toBeUndefined(); + expect(track.tryRecvGroup()?.sequence).toBe(1); + expect(track.tryRecvGroup()).toBeUndefined(); track.withRange({ start: { included: 1 }, end: { excluded: 3 } }); - expect(taken(track.tryRecvGroup())?.sequence).toBe(2); - expect(taken(track.tryRecvGroup())).toBeUndefined(); + expect(track.tryRecvGroup()?.sequence).toBe(2); + expect(track.tryRecvGroup()).toBeUndefined(); track.withRange({ start: { included: 1 } }); - expect(taken(track.tryRecvGroup())?.sequence).toBe(3); + expect(track.tryRecvGroup()?.sequence).toBe(3); track.close(); }); @@ -2268,17 +2262,17 @@ test("a lowered range re-offers the unread cached groups", () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 10 } } }); for (const sequence of [5, 6, 10]) producer.writeGroup(new GroupProducer(sequence)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(10); - expect(taken(track.tryRecvGroup())).toBeUndefined(); + expect(track.tryRecvGroup()?.sequence).toBe(10); + expect(track.tryRecvGroup()).toBeUndefined(); track.withRange({ start: { included: 6 } }); - expect(taken(track.tryRecvGroup())?.sequence).toBe(6); + expect(track.tryRecvGroup()?.sequence).toBe(6); track.withRange({ end: { included: 5 } }); - expect(taken(track.tryRecvGroup())?.sequence).toBe(5); + expect(track.tryRecvGroup()?.sequence).toBe(5); track.withRange({}); - expect(taken(track.tryRecvGroup())).toBeUndefined(); + expect(track.tryRecvGroup()).toBeUndefined(); producer.writeGroup(new GroupProducer(11)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(11); + expect(track.tryRecvGroup()?.sequence).toBe(11); track.close(); }); @@ -2290,10 +2284,10 @@ test("a lowered range re-offers a cached cut with its error", async () => { const error = new StreamError(StreamCode(70), { message: "cut" }); cut.close(error); producer.writeGroup(new GroupProducer(1)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + expect(track.tryRecvGroup()?.sequence).toBe(1); track.withRange({}); - const group = taken(track.tryRecvGroup()); + const group = track.tryRecvGroup(); expect(group?.sequence).toBe(0); await expect(group?.readString()).rejects.toBe(error); track.close(); @@ -2304,12 +2298,12 @@ test("a lowered range still re-offers after the producer closes", () => { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + expect(track.tryRecvGroup()?.sequence).toBe(1); producer.close(); track.withRange({}); - expect(taken(track.tryRecvGroup())?.sequence).toBe(0); - expect(track.tryRecvGroup()).toEqual({ kind: "done" }); + expect(track.tryRecvGroup()?.sequence).toBe(0); + expect(hooks.tryRecvGroup(track, false)).toEqual({ kind: "done" }); track.close(); }); @@ -2318,11 +2312,11 @@ for (const abort of [undefined, new Error("gone")]) { const producer = new TrackProducer("test"); const track = producer.subscribe({ maxDelay: Milli(5000), groups: { start: { included: 1 } } }); for (const sequence of [0, 1]) producer.writeGroup(new GroupProducer(sequence)); - expect(taken(track.tryRecvGroup())?.sequence).toBe(1); + expect(track.tryRecvGroup()?.sequence).toBe(1); track.close(abort); track.withRange({}); - expect(track.tryRecvGroup()).toEqual(abort ? { kind: "error", error: abort } : { kind: "done" }); + expect(hooks.tryRecvGroup(track, false)).toEqual(abort ? { kind: "error", error: abort } : { kind: "done" }); producer.close(); }); } @@ -2332,7 +2326,7 @@ test("malformed group bounds do not partially advance the cursor", () => { const track = producer.subscribe({ maxDelay: Milli(5000) }); producer.writeGroup(new GroupProducer(0)); expect(() => track.withRange({ start: { included: 3 }, end: { excluded: -1 } })).toThrow(); - expect(taken(track.tryRecvGroup())?.sequence).toBe(0); + expect(track.tryRecvGroup()?.sequence).toBe(0); track.close(); }); @@ -2487,8 +2481,8 @@ test("an omitted publisher limit still ages idle groups out", async () => { // A scan runs at most once per slice of the window, so step past the next one. clock.set(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); const after = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(taken(after.tryRecvGroup())?.sequence).toBe(1); - expect(taken(after.tryRecvGroup())).toBeUndefined(); + expect(after.tryRecvGroup()?.sequence).toBe(1); + expect(after.tryRecvGroup()).toBeUndefined(); after.close(); } finally { producer.close(); @@ -2509,7 +2503,7 @@ test("a live track does not pin an aborted newest group", () => { clock.set(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); const late = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(taken(late.tryRecvGroup())).toBeUndefined(); + expect(late.tryRecvGroup()).toBeUndefined(); late.close(); } finally { producer.close(); @@ -2535,7 +2529,7 @@ test("closing a track keeps an idle newest group for subscribers to drain", asyn // The close restarted its window, which now runs out like any other. clock.set(10_000 + 2 * (CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8)); const late = producer.subscribe({ maxDelay: Milli(100_000) }); - expect(taken(late.tryRecvGroup())).toBeUndefined(); + expect(late.tryRecvGroup()).toBeUndefined(); late.close(); } finally { clock.restore(); @@ -2644,8 +2638,8 @@ test("an ended track's buffered groups age out for a stale subscriber", async () // Nothing writes after close; the scheduled cleanup can lag by one scan slice. await clock.advance(10_000 + CACHE_WINDOW_MS + CACHE_WINDOW_MS / 8); - if (abort) expect(() => taken(stale.tryRecvGroup())).toThrow(abort); - else expect(taken(stale.tryRecvGroup())).toBeUndefined(); + if (abort) expect(() => stale.tryRecvGroup()).toThrow(abort); + else expect(stale.tryRecvGroup()).toBeUndefined(); } finally { producer.close(); clock.restore(); @@ -2670,10 +2664,9 @@ test("an abort leaves a group already taken readable, then reports the abort", a }); /** Every group a subscriber can take right now, by sequence. */ -function drain(track: { tryRecvGroup(): Recv }): number[] { +function drain(track: { tryRecvGroup(): GroupConsumer | undefined }): number[] { const sequences: number[] = []; - for (let group = taken(track.tryRecvGroup()); group; group = taken(track.tryRecvGroup())) - sequences.push(group.sequence); + for (let group = track.tryRecvGroup(); group; group = track.tryRecvGroup()) sequences.push(group.sequence); return sequences; } @@ -2824,7 +2817,7 @@ test("a single-frame write that throws aborts its group", () => { producer.writeFrame({ payload: enc.encode("y") }); // The failed group ends in that error instead of leaving a reader waiting on it. - const failed = taken(subscriber.tryRecvGroup()); + const failed = subscriber.tryRecvGroup(); expect(failed?.sequence).toBe(0); expect(failed?.closed.peek()).toBeInstanceOf(TimestampMismatch); expect(drain(subscriber)).toEqual([1]); @@ -2848,14 +2841,14 @@ test("explicit and producer-cut drops survive outside the group cache", async () const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); producer.dropGroups(3, 4, DROPPED); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 3, end: 4, error: DROPPED }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 3, end: 4, error: DROPPED }); const group = new GroupProducer(4); producer.writeGroup(group); const cut = new Error("cut"); group.close(cut); await settle(); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 4, end: 5, error: cut }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 4, end: 5, error: cut }); reader.close(); producer.close(); @@ -2913,10 +2906,10 @@ test("a drop below the window is reported once the window lowers to it", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000), groups: { start: { included: 5 } } }); producer.dropGroups(2, 3, DROPPED); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "idle" }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); reader.withRange({ start: { included: 0 } }); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 2, end: 3, error: DROPPED }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 3, error: DROPPED }); reader.close(); producer.close(); @@ -2933,7 +2926,7 @@ test("a re-created cut group is served, not dropped", async () => { const retry = new GroupProducer(4); producer.writeGroup(retry); await settle(); - const recv = reader.tryRecvGroup({ drops: true }); + const recv = hooks.tryRecvGroup(reader, true); expect(recv.kind === "group" ? recv.group.sequence : recv).toBe(4); reader.close(); @@ -2944,19 +2937,19 @@ test("a wide drop is held and reported as one run", () => { const producer = new TrackProducer("video").accept({}); const reader = producer.subscribe({ maxDelay: Milli(60_000) }); producer.dropGroups(2, 2 ** 40, DROPPED); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 2, end: 2 ** 40, error: DROPPED }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2, end: 2 ** 40, error: DROPPED }); // A wider drop reports only what this cursor has not reported yet, with its own error. const wider = new StreamError(StreamCode.Old, { message: "old" }); producer.dropGroups(1, 2 ** 40 + 2, wider); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "drop", start: 1, end: 2, error: wider }); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 1, end: 2, error: wider }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "drop", start: 2 ** 40, end: 2 ** 40 + 2, error: wider, }); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "idle" }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); reader.close(); producer.close(); @@ -2969,9 +2962,9 @@ test("adjacent drops with the same code merge into one run", () => { for (let sequence = 2; sequence < 5; sequence++) { producer.dropGroups(sequence, sequence + 1, new StreamError(StreamCode.NotFound, { message: "dropped" })); } - const recv = reader.tryRecvGroup({ drops: true }); + const recv = hooks.tryRecvGroup(reader, true); expect(recv.kind === "drop" ? [recv.start, recv.end, recv.error] : recv).toEqual([2, 5, DROPPED]); - expect(reader.tryRecvGroup({ drops: true })).toEqual({ kind: "idle" }); + expect(hooks.tryRecvGroup(reader, true)).toEqual({ kind: "idle" }); reader.close(); producer.close(); @@ -3068,7 +3061,7 @@ function stampGroup(producer: TrackProducer, sequence: number, ms: number): Grou function drainGroups(subscriber: ReturnType): number[] { const sequences: number[] = []; - for (let group = taken(subscriber.tryRecvGroup()); group; group = taken(subscriber.tryRecvGroup())) + for (let group = subscriber.tryRecvGroup(); group; group = subscriber.tryRecvGroup()) sequences.push(group.sequence); return sequences; } @@ -3473,7 +3466,7 @@ test("an evicted group still fills a pending tail", async () => { clock.set(CACHE_WINDOW_MS + 1000); write(2); // A late subscriber replays only what the cache still holds. - expect(taken(producer.subscribe({ maxDelay: Milli(60_000) }).tryRecvGroup())?.sequence).toBe(2); + expect(producer.subscribe({ maxDelay: Milli(60_000) }).tryRecvGroup()?.sequence).toBe(2); expect((await reader.recvGroup())?.sequence).toBe(2); expect(await reader.recvGroup()).toBeUndefined(); producer.close(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 2e3530458cd..e80441580e9 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -23,12 +23,14 @@ import type { IetfVersion } from "./ietf/version.ts"; import { type DropRun, dropAt, + finalSequence, groupBounds, hooks, insertDrop, insertRun, type Land, MAX_DATAGRAMS, + type Recv, type RecvDatagram, type ResumeSource, type Run, @@ -44,29 +46,17 @@ import { type Broadcast as BroadcastWire, registerTrackConsumer } from "./wire.t export type { Datagram } from "./datagram.ts"; -/** The first group an exclusive track end excludes whole: one past the last group that may exist. */ -export function finalSequence(end: Location): number { - return end.group + (end.frame === 0 ? 0 : 1); +// The group a non-blocking read takes, skipping drops and throwing the track's error; +// `undefined` when nothing is deliverable now. +function taken(read: () => Recv): GroupConsumer | undefined { + for (;;) { + const recv = read(); + if (recv.kind === "group") return recv.group; + if (recv.kind === "error") throw recv.error; + if (recv.kind !== "drop") return undefined; + } } -/** - * What a non-blocking group read found, which is everything the caller needs to decide what - * to do next: no second look at the track's closed state, and no ordering rule to get wrong. - */ -export type Recv = - /** A group to serve. It has already left the buffer, so dropping this is dropping the group. */ - | { kind: "group"; group: GroupConsumer } - /** Sequences `[start, end)` this cursor gave up without serving, and why. */ - | { kind: "drop"; start: number; end: number; error: Error } - /** Nothing readable, but the track is live and may produce more. */ - | { kind: "idle" } - /** The producer finished, yet groups above the cap are still held: raising it releases them. */ - | { kind: "boundary" } - /** The producer finished and the buffer is drained. Nothing can follow. */ - | { kind: "done" } - /** The track aborted. */ - | { kind: "error"; error: Error }; - // Wall-clock bound for idle cached content, matching Rust cache::DEFAULT_EXPIRY. // Media maxDelay only bounds how far behind the live edge a reader may fall. const CACHE_WINDOW = Nano.fromMilli(Milli(30_000)); @@ -493,15 +483,9 @@ export class Consumer { return this.#broadcast.subscribe(this.name, options); } - /** - * Fetch the track's immutable publisher properties without subscribing. - * - * A pending lookup keeps the track wanted. With `hold`, it stays wanted until `hold` aborts, - * as a held Rust `query` does, so a publisher can keep a track alive while it answers for - * it; aborting before the answer abandons the lookup. - */ - info(options?: { hold?: AbortSignal }): Promise { - return this.#broadcast.resolveTrackInfo(this.name, options?.hold); + /** Fetch the track's immutable publisher properties without subscribing. */ + info(): Promise { + return this.#broadcast.resolveTrackInfo(this.name); } /** Fetch a single group by sequence without holding a live subscription. */ @@ -2083,6 +2067,7 @@ export class Subscriber { if (start === undefined || start === "pending") return start; return Math.max(start, subscriber.#cursor.peek().start); }; + hooks.tryRecvGroup = (subscriber, dispositions) => subscriber.#tryRecvGroup(dispositions); hooks.tryNextGroup = (subscriber) => subscriber.#tryNextGroup(); hooks.peekGroup = (subscriber, ordered) => subscriber.#peekGroup(ordered); hooks.forgetPastBudget = (subscriber, delivered) => subscriber.#forgetPastBudget(delivered); @@ -2196,6 +2181,7 @@ export class Subscriber { }; return dispose; }; + hooks.groupChanged = (subscriber, fn) => subscriber.#groupChanged(fn); hooks.fetchBudget = (subscriber, maxDelay) => { subscriber.#fetchBudget = maxDelay ?? Number.POSITIVE_INFINITY; }; @@ -2449,7 +2435,8 @@ export class Subscriber { }); } - // The synchronous half of recvGroup, behind the public tryRecvGroup. + // Package-internal synchronous half of recvGroup. The lite publisher uses this so applying + // control state, popping the group, and positioning its frames are one JavaScript turn. #tryRecvGroup(dispositions = false): Recv { if (this.#resume) return this.#tryResumed(false); const groups = this.#state.groups.peek(); @@ -2546,7 +2533,9 @@ export class Subscriber { return end !== undefined && this.#state.received.peek() >= finalSequence(end) && !this.#state.owed.peek(); } - // The readiness half of recvGroup, behind the public groupChanged. + // Package-internal readiness half of recvGroup. Each registration fires at most once, and + // the caller disposes the losers after whichever source wakes it. A declared end wakes it + // too, so a publisher can forward the end before the live edge reaches it. #groupChanged(fn: () => void): Dispose { if (this.#resume) { const resumed = [this.#resume.changed(fn), this.#cursor.changed(fn), this.#state.closed.changed(fn)]; @@ -2570,28 +2559,18 @@ export class Subscriber { } /** - * Take the next group without waiting, honoring the same cursor bounds as - * {@link recvGroup}, or say why there is none. + * Take the next buffered group without blocking, honoring the same cursor bounds as + * {@link recvGroup}. * - * Synchronous, so a publisher can pop a group and act on it in the same turn. `idle` and - * `boundary` may read differently once {@link groupChanged} fires; `done` and `error` are - * final. With `drops`, each run of sequences the cursor gives up is reported once as a - * `drop`, which a publisher forwards to its peer; without it they pass silently. - * - * The first call commits this track to arrival order, as {@link recvGroup} does. + * Returns `undefined` when nothing is deliverable right now, which is not by itself the + * end of the track: a group may still arrive, or one may be parked beyond the + * {@link withRange} cap. Use it to drain what the retained window already holds, where + * waiting for a sequence nothing will republish would park forever. */ - tryRecvGroup(options?: { drops?: boolean }): Recv { + tryRecvGroup(): GroupConsumer | undefined { this.#live(); this.#mode = "arrival"; - return this.#tryRecvGroup(options?.drops ?? false); - } - - /** - * Call `fn` once when {@link tryRecvGroup} may read differently, including when the track - * declares its end, and return the disposer. - */ - groupChanged(fn: () => void): Dispose { - return this.#groupChanged(fn); + return taken(() => this.#tryRecvGroup()); } /** @@ -2929,11 +2908,11 @@ export class Ordered { } /** - * Take the next group as {@link nextGroup} would without waiting, or say why there is none; - * see {@link Subscriber.tryRecvGroup}. Mirrors the Rust `poll_next_group`. + * Take the next group as {@link nextGroup} would, without waiting; see + * {@link Subscriber.tryRecvGroup}. Mirrors the Rust `poll_next_group`. */ - tryNextGroup(): Recv { - return ordered_.tryNextGroup(this.#subscriber); + tryNextGroup(): GroupConsumer | undefined { + return taken(() => ordered_.tryNextGroup(this.#subscriber)); } /** diff --git a/js/net/src/wire.ts b/js/net/src/wire.ts index e6c9fb5cee9..709302ca558 100644 --- a/js/net/src/wire.ts +++ b/js/net/src/wire.ts @@ -20,15 +20,15 @@ import type * as track from "./track.ts"; /** The protocol-facing operations behind a broadcast handle. */ export interface Broadcast { - // private: plumbing + // pending: /quest/m1/public-model/serve.md subscribe(name: string, options?: track.Subscription): track.Subscriber; - // private: plumbing + // pending: /quest/m1/public-model/serve.md /** The track's properties; `hold` keeps the track wanted until it aborts, the way a held TRACK stream does, and aborting it before the answer abandons the lookup. */ resolveTrackInfo(name: string, hold?: AbortSignal): Promise; - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md /** The newest frame the track's cache holds, read without subscribing; `undefined` while it holds none. */ largest(name: string): track.Location | undefined; - // private: plumbing + // pending: /quest/m1/public-model/serve.md fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise; // pending: /quest/m1/public-model/answer.md requested(): Promise; diff --git a/quest/m1/public-model/README.md b/quest/m1/public-model/README.md index b93613b8659..2d3df7a7f04 100644 --- a/quest/m1/public-model/README.md +++ b/quest/m1/public-model/README.md @@ -103,7 +103,7 @@ Work owned by this README, after the children land: ## Required - [Claim request type](/quest/m1/public-model/claim-request-type.md) - accepting an application claim's request fails to compile instead of panicking -- [Public JS feed start](/quest/m1/public-model/serve.md) - a custom JS publisher learns where the source's feed starts, the last serving item left +- [Public serving](/quest/m1/public-model/serve.md) - a custom publisher reads a track's start, cursor, and group expiry for its wire through public calls - [Public answering](/quest/m1/public-model/answer.md) - a custom relay answers broadcast and track requests on demand and closes them once unused - [Public routes](/quest/m1/public-model/routes.md) - a custom relay ingests routes under a peer's identity and advertises without echoing them back, once cluster routing lands - [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - fetch and track-info answering, the cache peeks, JS `fork`/`mirror`, and JS `endTrack`, once the quests that reshape them land diff --git a/quest/m1/public-model/deferred.md b/quest/m1/public-model/deferred.md index e835b2c323a..6287e4dc746 100644 --- a/quest/m1/public-model/deferred.md +++ b/quest/m1/public-model/deferred.md @@ -25,9 +25,7 @@ the prerequisites will have deleted or renamed most of these. the need. Model ranges replaces per-group requests with ranges, and its public range answer is the ingest path. - Cache peeks (Rust `track::Consumer::peek_latest`, `peek_before`, - `peek_group`, `is_live`, and `final_sequence`, which a FETCH reads for - END_OF_TRACK with no subscriber to poll the end on; IETF publisher, for - Largest Object and FETCH) + `peek_group`, `is_live`; IETF publisher, for Largest Object and FETCH) and JS `Track.Subscriber.fork`: remove the need, since IETF FETCH is served from ranges and the largest location is public. If either still has a caller, bring the shape back to the maintainer rather than publishing diff --git a/quest/m1/public-model/serve.md b/quest/m1/public-model/serve.md index b495f1b50fb..e08d6b52774 100644 --- a/quest/m1/public-model/serve.md +++ b/quest/m1/public-model/serve.md @@ -1,30 +1,156 @@ -# [XS] Public JS feed start +# [L] Public serving ## Goal -A custom `@moq/net` publisher learns where the source's feed starts, as the -public Rust `track::Subscriber::poll_start` answers. The built-in lite -publisher uses the same call. +A custom publisher reads a track for its wire through public moq-net and +@moq/net calls only: where the feed starts, a read cursor its peer can move in +either direction, the track's end in wire terms, and when a group it is still +writing has expired. The built-in lite and IETF publishers use the same calls. ## Plan -The rest of public serving landed: the `with_range`/`withRange` cursor, public -`poll_start`, `poll_drop`, `poll_expired`, `Position::final_sequence`, -`Subscription::{start, end, with_start, with_end}`, and in JS the `Recv` union -from `tryRecvGroup`, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, -`Track.Consumer.info({ hold })`, and `Group.Consumer.expired`. A publisher -gives up on a group it is still writing once `expired` settles, or `closed` -(Rust `poll_finished`) fails. The live-edge answers moved to -[track-live](/quest/m1/track-live.md), and `track::Consumer::final_sequence` -to [the deferred quest](/quest/m1/public-model/deferred.md). - -Left: the JS `hooks.sourceStart`, which -[#6206](https://github.com/moq-dev/moq/pull/6206) added after this cut so the -lite publisher keeps a descending feed's start. It is the JS counterpart of -`poll_start` (the source's start, raised to the cursor floor, or `"pending"` -until the upstream START arrives); make it a public `Track.Subscriber` call. +Rules, carve-outs, and the inventory method are in the +[epic](/quest/m1/public-model/README.md). Rerun the inventory first; the +recommendations below are the planning quest's, and the ones marked +**decision** were settled by the maintainer on 2026-10-16 (#5717). + +Rust items (`rs/moq-net/src/model/`), as they stood at b4eab0db1: + +- `track::Subscriber::poll_start` (lite publisher): public. A publisher + reports the resolved start to its peer (SUBSCRIBE_START, SUBSCRIBE_OK). +- `track::Subscriber::poll_live` (both publishers): remove the need through + the public `poll_largest` (#5725). It now waits out an idle copy too + (#5924), but it follows the source's reported largest, which can name a + frame the cache does not hold yet, so the publishers still answer with the + buffered edge. A public live signal is + [its own quest](/quest/m1/track-live.md). Decide here whether wire answers move to it, and + with them `latest_sequence` on `track::{Producer,Consumer,Subscriber}`, + the private snapshot that replaced the public `latest()` (#5725). +- **Cursor** (`track::Subscriber::start_at`, `raise_start_to`, `end_at`, + `subscription::Cap`; both publishers). **Decision**: + - ✅ One public consuming builder assigns the floor and the cap in either + direction: `with_range(self, range) -> Self` on `track::Subscriber` and + `track::Ordered` (JS `withRange`), replacing `set_groups` and the + chaining `withGroups`. The maintainer decided "range" on 2026-10-19, + replacing the 2026-10-18 `limit` and the earlier `set_bounds`. Each + reader already hands a sequence out once (#5446), so a SUBSCRIBE_UPDATE + that widens the start re-offers only unread groups. + `start_at`, `raise_start_to`, `end_at`, and `Cap` go. Precondition: + lowering the floor re-offers unread cached groups in every mode. Today + only the resume cursor does; the arrival-order (Plain) cursor walks a + monotonic arrival index, so it must rescan below its old floor for + groups it never handed out. Rewrite the doc ("without rewinding read + progress") to say what lowering does. + - Rebinding: a consuming builder fits readers bounded once at creation, + but these callers move a live reader's bounds through `&mut` today, so + the rename needs a way to rebind (take and replace the reader, or a + crate-private setter the builder wraps): + - `rs/moq-c/src/consume.rs` `RawReader::apply` re-applies the range on + every subscription update, counting a relative start from the track + `Consumer`'s unbounded largest. `set_groups` only raises the floor, so an + update cannot lower a floor an earlier one put above the live edge + (Codex on #5924). Making the floor assign fixes it; land that with a + moq-c test where a later relative update delivers the next group. + - The lite and IETF publishers move the cursor on SUBSCRIBE_UPDATE + (`start_at`, `end_at`; JS `hooks.replaceGroups` and the IETF + publisher's `setGroups({ start })`). + - `js/json` snapshot and `js/flate` `latest()` raise the floor of the same + reader on each read; `js/room` chat sets it after `largest()` resolves. + The snapshot consumers (`js/json/src/snapshot/consumer.ts` `#read`, + `js/flate/src/snapshot/consumer.ts` `latest()`) call + `setGroups({ start: { included: latest.group } })`, whose omitted end + removes the caller's cap. The rebinding must keep that cap; land it with + a regression test where a capped snapshot reader stays below its cap. + A datagram also advances `largest()` past every group, stranding the + read. The Rust consumers instead drain the groups the reader already + has and keep the newest (#5677), which needs no floor at all. + - `rs/moq-hls` export narrows a fetched group with `set_frames(..end)`. + - Readers that set a floor once right after `poll_largest` (moq-audio, + moq-video, moq-cli play, moq-json window, moq-mux) fit the builder. + - ✅ The range floor counts as a local bound (maintainer, 2026-10-19): + `largest()` reports within both the floor and the cap, so a reader whose + floor sits above the live edge reports nothing until a group reaches it + (#5924). + - ✅ `largest()` reports only upstream-confirmed state (maintainer, + 2026-10-19): the source's reported largest and what its live feed + delivered since, never a cache-derived stand-in. It waits while the copy + is idle, though cached groups are still served, and past the cap it + reports nothing rather than the newest cached group below it (#5924). + - A second public `replace_groups`. +- **Bounds naming** (decided 2026-10-16 in #5717, changed to "range" by the + maintainer on 2026-10-19): ✅ the siblings follow: + `Subscription::with_range` replaces `with_groups` as the single-range form + of `with_ranges`, and `group::Consumer::set_frames` becomes the consuming + `with_range`, with the JS mirrors. +- `group::Consumer::start_at`, `end_at` (both publishers): remove the need; + the public `with_range` (today `set_frames`) and `skip_to` cover them. +- `Subscription::{start, end, set_bounds, with_start, with_end}` (both + publishers, IETF subscriber, from #5732): the covering span a wire without + ranges carries. Derive it from the public `ranges` instead, or make it + public. +- `subscription::Position::final_sequence` (lite publisher): public, the + one-line wire translation of an exclusive end that both languages + already duplicate. `track::Consumer::final_sequence` (IETF publisher) goes; + callers read `poll_finished` and translate. +- **Group expiry while writing** (`group::Consumer::poll_expired`, + `poll_expired_while_pending`; both publishers): public as one + `poll_expired`. A publisher that already read frames off a group must + still abandon its stream once the subscription's max delay expires the + group. Fold the `pending` flag in, or keep it private as tuning if it only + saves a poll. +- **Cache peeks** (`track::Consumer::peek_latest`, `peek_before`, + `peek_group`, `is_live`; IETF publisher, for Largest Object and FETCH): + moved to [the deferred quest](/quest/m1/public-model/deferred.md), which + waits on Model ranges. +- Passthrough, stay private and marked: `group::Consumer::wire`, + `end_object`, `last_object`, `first_frame`, `poll_read_object`, + `poll_read_objects`, `frame::Object`, `frame::Consumer::fields`, + `track::Subscriber::poll_recv_wire_datagram`. +- Test-only: `track::Consumer::poll_group`, `resume_position`. + +JS items (`js/net/src/`): + +- `hooks.replaceGroups` (lite publisher): mirror the cursor decision, so + `Track.Subscriber.withRange` assigns the floor and the hook goes. +- `hooks.tryRecvGroup` with its `Recv` union, and `hooks.groupChanged` + (lite publisher). The public `Subscriber.tryRecvGroup()` returns + `undefined` for both a held boundary and a drained end, so a synchronous + publisher cannot tell them apart or park. **Decision**: + - ✅ Public. Return the `Recv` union from the public method and expose + the change wake (a signal or a promise, matching the package's style). + The union deliberately has no Rust type: Rust's lite publisher builds + its private `Recv` from the public `poll_recv_group` (Pending versus + `Ready(None)`) and `poll_finished`, which a third party composes the + same way. + - Mirror Rust exactly: a distinct drained result and a synchronous end + check instead of the union, plus the wake. +- `hooks.guardGroup`, `hooks.readGroupFrame` with `ReadGroupFrame` (both + publishers): mirror the Rust group expiry as one public call. Reading a + frame the publisher `complete()`s holds the group's `closed` until it is + written; keep that behavior behind the public read rather than a second + method if it can be. +- `Track.Subscriber.fork` (`@internal`, IETF publisher fill and cache + reads): moved to the deferred quest with the cache peeks. +- `wire.ts` `Broadcast.subscribe`, `fetchGroup`: remove the need; the public + `Broadcast.Consumer.track(name)` paths cover them. +- `wire.ts` `Broadcast.largest`, `hooks.cachedLargest`, + `hooks.bufferedLargest`, and `hooks.latestSequence`: remove the need through the public `largest()` + stream (#5725), under the same caveat as `poll_live`. +- `wire.ts` `Broadcast.resolveTrackInfo(name, hold)` (both publishers): + public as an option on the track's info lookup (an `AbortSignal` that keeps + the track wanted until it fires), mirrored by whatever Rust's `query` + holds. Check Rust parity first; drop the hold if Rust has no equivalent + need. +- `internal.ts` `groupBounds`: stays a private helper; a third party passes + the public `Groups`. +- `priority.ts` `sendOrder`, `Priority`: stay private. They rank streams on + a `stream.ts` writer, which is wire plumbing in both languages. + +Tests: lowering the floor re-offers an unread cached group in both cursor +modes. Each public call gets a mock-time test in its language, and the +built-in publishers move onto the public calls, so their existing suites +cover the behavior. ## Related -- [Public model](/quest/m1/public-model/README.md) - the epic, its rules, and the inventory method -- [A reader can tell when its track is live](/quest/m1/track-live.md) - owns the publishers' live-edge answers +- [Public model after ranges, handover, and the JS tail](/quest/m1/public-model/deferred.md) - the cache peeks and `fork`, split out of this quest diff --git a/quest/m1/resume-drops.md b/quest/m1/resume-drops.md index 65c6af2476b..935a3fd283d 100644 --- a/quest/m1/resume-drops.md +++ b/quest/m1/resume-drops.md @@ -2,8 +2,8 @@ ## Goal -`tryRecvGroup({ drops: true })` on a routed (resumed) `@moq/net` -`Track.Subscriber` reports the groups its copies gave up as a `drop`, as a +The package-internal `hooks.tryRecvGroup(subscriber, true)` on a routed +(resumed) `@moq/net` `Track.Subscriber` reports the groups its copies gave up as a `drop`, as a direct subscriber does and as the Rust resume reader forwards its serving copy's `poll_drop`. A lite or IETF publisher serving a routed track then sends `SUBSCRIBE_DROP` for them instead of leaving its peer waiting on groups that @@ -26,11 +26,7 @@ Open decisions, to settle before implementing: copy never serves a group already reported dropped. Regression test: a resumed subscriber whose serving copy receives -`SUBSCRIBE_DROP` reports it through `tryRecvGroup({ drops: true })`, and a +`SUBSCRIBE_DROP` reports it through `hooks.tryRecvGroup(subscriber, true)`, and a downstream lite-07 publisher forwards it. Public API: behavior only. Wire: none. - -## Related - -- [Public JS feed start](/quest/m1/public-model/serve.md) - the public serving calls this rides on diff --git a/quest/m1/resume-floor.md b/quest/m1/resume-floor.md index 8133cc7069c..803bafa2357 100644 --- a/quest/m1/resume-floor.md +++ b/quest/m1/resume-floor.md @@ -32,5 +32,4 @@ Public API: behavior only. Wire: none. ## Related -- [Public JS feed start](/quest/m1/public-model/serve.md) - the public serving cursor this extends - [Rust resume backs single-route groups](/quest/m1/resume-handed-out.md) - also edits which replaced copies the Rust reader keeps diff --git a/quest/m1/track-live.md b/quest/m1/track-live.md index e15bae28d5f..f5c5532e5d9 100644 --- a/quest/m1/track-live.md +++ b/quest/m1/track-live.md @@ -17,15 +17,9 @@ what an ended feed left; this quest makes the signal itself public. `readable()` in `rs/moq-net/src/model/track.rs`, the crate-private `resume` `poll_live`, and the crate-private `Producer::is_live`. Expose one reader-side `poll_live`/`live()` (or `is_live`) on `track::Subscriber` and - `track::Ordered`. -- The publishers' wire answers (SUBSCRIBE_START, SUBSCRIBE_OK, TRACK_STATUS - Largest) are marked here: `track::Subscriber::poll_live` and - `latest_sequence` on `track::{Producer,Consumer,Subscriber}` in Rust, and - `wire.ts` `Broadcast.largest`, `hooks.latestSequence`, and - `hooks.bufferedLargest` in JS. `largest()` follows the source's reported - largest, which can name a frame the cache does not hold yet, so the - publishers answer with the buffered edge instead. Fold them into the public - signal, or keep them private as passthrough. + `track::Ordered`, and decide whether the publishers' crate-private + `poll_live` folds into it (see + [Public serving](/quest/m1/public-model/serve.md)). - JS has no equivalent: a track never goes idle, so its reader is live from the start. Mirror the name, and the idle state if JS gains warm copies. - Decide what a reader does with groups served before live: keep serving @@ -34,4 +28,4 @@ what an ended feed left; this quest makes the signal itself public. ## Related -- [Public serving](/quest/m1/public-model/serve.md) - moved the publishers' `poll_live` and the JS largest hooks here +- [Public serving](/quest/m1/public-model/serve.md) - the publishers' `poll_live` and the `largest()` decision diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 9ea1c27e8d8..ee5f3c9b877 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -19,9 +19,6 @@ let subscriber = subscriber.with_range(5..); `group::Consumer::finished` (and `poll_finished`) now ends cleanly once a `with_range` frame cap is reached, where it waited for the group itself to end, as reads already do. -A custom publisher can now reach what the built-in ones use: `track::Subscriber::poll_start`, `track::Subscriber::poll_drop`, `group::Consumer::poll_expired`, `subscription::Position::final_sequence`, and `Subscription::{start, end, with_start, with_end}` for the covering span. -It gives up on a group it is still writing once `poll_expired` is true, or `poll_finished` fails because the frames it has yet to read are gone. - ### A listing says whether a removed track finished (#6399) `broadcast::TracksEvent` gains `Finished { name }`: the track left the listing because its producer declared its end. `Removed { name }` now means it left unfinished (dropped or aborted without an end, or its route withdrawn). Handle both where you matched `Removed`. @@ -255,7 +252,7 @@ session.retag(tier, &label); ### Subscriptions carry group ranges (#5732) -The `track::Subscription::start` and `end` fields are replaced by `ranges: Vec`; the `start()` and `end()` methods and the `with_start` and `with_end` builders read and set the span covering them. +`track::Subscription::start` and `end` are replaced by `ranges: Vec`, and `with_start` and `with_end` are gone. Use `with_range(start..end)` for one span of groups, or `with_ranges` with `Range::live()`, `Range::oldest()` (the default), or `Range::groups(..)`. ### Receive estimates come from `Session::recv_bandwidth` (#5777) diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 4722baba322..3895a8dac39 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2709,7 +2709,8 @@ impl Consumer { /// [`max_delay`](crate::track::Subscription::max_delay) expires the group, it abandons /// the stream, even with every frame already read off. It abandons it too once /// [`Self::poll_finished`] fails. Stays `true` once set. - pub fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { + // private: capability gap + pub(crate) fn poll_expired(&mut self, waiter: &kio::Waiter) -> bool { self.poll_expiry(waiter, true) } @@ -2968,9 +2969,8 @@ impl Consumer { /// Poll until the group terminates, or this cursor reaches the end of its range, returning /// its next frame index. /// - /// A publisher still writing the group races its transport against this and - /// [`Self::poll_expired`]: an error here means the frames it has yet to read are gone - /// (evicted, cut, or failed upstream) and no route will continue them. + /// An error means the frames this cursor has yet to read are gone (evicted, cut, or + /// failed upstream) and no route will continue them. pub fn poll_finished(&mut self, waiter: &kio::Waiter) -> Poll> { if self.recover.is_none() { return self.poll_finished_once(waiter); diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index f20b66ff591..27ed399e630 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -306,7 +306,9 @@ impl Subscription { /// from the latest group (or none is asked for). /// /// The form a wire without ranges carries: a floor below which nothing is requested. - pub fn start(&self) -> Option { + #[cfg(any(feature = "async", test))] + // private: capability gap + pub(crate) fn start(&self) -> Option { let mut floor: Option = None; for range in &self.ranges { let Anchor::Absolute(start) = range.start else { @@ -321,7 +323,9 @@ impl Subscription { /// the latest group. An empty list is the empty range, `Position::group(0)`. /// /// The form a wire without ranges carries, alongside [`Self::start`]. - pub fn end(&self) -> Option { + #[cfg(any(feature = "async", test))] + // private: capability gap + pub(crate) fn end(&self) -> Option { let mut end = Some(Position::default()); for range in &self.ranges { let Some(Anchor::Absolute(next)) = range.end else { @@ -334,18 +338,23 @@ impl Subscription { /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) up to [`Self::end`], /// returning `self` for chaining: the form a wire without ranges carries. - pub fn with_start(self, start: impl Into>) -> Self { + #[cfg(feature = "async")] + // private: capability gap + pub(crate) fn with_start(self, start: impl Into>) -> Self { let end = self.end(); self.with_span(start.into(), end) } /// Replace the ranges with one from [`Self::start`] up to the exclusive `end`, or onward /// for `None`, returning `self` for chaining: the form a wire without ranges carries. - pub fn with_end(self, end: impl Into>) -> Self { + #[cfg(any(feature = "async", test))] + // private: capability gap + pub(crate) fn with_end(self, end: impl Into>) -> Self { let start = self.start(); self.with_span(start, end.into()) } + #[cfg(any(feature = "async", test))] fn with_span(self, start: Option, end: Option) -> Self { self.with_ranges([Range { start: start.map_or(Range::oldest().start, Anchor::Absolute), @@ -515,7 +524,8 @@ impl Position { /// The first group this exclusive end excludes whole, `None` past the last group: the /// boundary a wire that cannot name a frame carries as the track's end. - pub fn final_sequence(self) -> Option { + // private: capability gap + pub(crate) fn final_sequence(self) -> Option { self.group.checked_add(u64::from(self.frame != 0)) } } diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 1d794dbb695..09ab82a9729 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -3182,7 +3182,7 @@ impl Producer { } #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md pub(crate) fn latest_sequence(&self) -> Option { self.state.read().max_sequence } @@ -4655,7 +4655,7 @@ impl Consumer { kio::wait(|waiter| self.poll_largest(waiter)).await } - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md pub(crate) fn latest_sequence(&self) -> Option { if let Some(serving) = self.serving() { return serving.latest_sequence(); @@ -4665,7 +4665,7 @@ impl Consumer { /// The first group the declared end excludes whole, or `None` while the track is open ended. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - // pending: /quest/m1/public-model/deferred.md + // pending: /quest/m1/public-model/serve.md pub(crate) fn final_sequence(&self) -> Option { if let Some(serving) = self.serving() { return serving.final_sequence(); @@ -6770,7 +6770,9 @@ impl Subscriber { /// Poll for where the source's feed starts, raised to this cursor's floor, once /// resolved: the first group a publisher tells its peer it serves. A feed starting /// below the floor serves the floor's group too. `None` when the source declares none. - pub fn poll_start(&mut self, waiter: &kio::Waiter) -> Poll> { + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + // private: capability gap + pub(crate) fn poll_start(&mut self, waiter: &kio::Waiter) -> Poll> { let cursor = match &mut self.inner { Inner::Plain(cursor) => cursor, Inner::Resume(resume, _) => return resume.poll_start(waiter), @@ -6834,7 +6836,9 @@ impl Subscriber { /// /// Stale skips are recorded only once this has been polled, so a reader that never /// forwards drops keeps none. - pub fn poll_drop(&mut self, waiter: &kio::Waiter) -> Poll<(ops::Range, StreamError)> { + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + // private: capability gap + pub(crate) fn poll_drop(&mut self, waiter: &kio::Waiter) -> Poll<(ops::Range, StreamError)> { match &mut self.inner { Inner::Plain(cursor) => cursor.poll_drop(waiter), Inner::Resume(resume, _) => resume.poll_drop(waiter), @@ -6845,7 +6849,7 @@ impl Subscriber { /// largest position it holds; `None` for a track with nothing yet. A front's logical /// track answers for the route serving it. See [`Producer::set_idle`]. #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md pub(crate) fn poll_live(&mut self, waiter: &kio::Waiter) -> Poll> { let cursor = match &mut self.inner { Inner::Plain(cursor) => cursor, @@ -7024,7 +7028,7 @@ impl Subscriber { } #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] - // pending: /quest/m1/track-live.md + // pending: /quest/m1/public-model/serve.md pub(crate) fn latest_sequence(&self) -> Option { match &self.inner { Inner::Plain(cursor) => cursor.state.read().max_sequence, diff --git a/sh/rs/model-markers.py b/sh/rs/model-markers.py index 1e717fd2c9c..3e6988b01e5 100644 --- a/sh/rs/model-markers.py +++ b/sh/rs/model-markers.py @@ -254,7 +254,7 @@ def code(text): def reads(text, binding): """The members session code reads off `binding`, a local name or a dotted path.""" - return sorted(set(re.findall(rf"(?` reads are followed, so refuse any other use, like destructuring. From 70535bed0b8de75020b61d241349df5a68432a1c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 16:47:00 -0700 Subject: [PATCH 11/18] fix(js/net): tryNextGroup abandons the frame helpers' passed group An ordered reader that interleaved readFrame() with tryNextGroup() kept draining the group the take had moved past, so frame reads ran backwards. The cleanup nextGroup did now lives in the shared non-blocking take. Co-Authored-By: Claude Opus 5.5 --- js/net/src/track.test.ts | 62 +++++++++++++++++++++------------------- js/net/src/track.ts | 18 +++++++----- 2 files changed, 43 insertions(+), 37 deletions(-) diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 79762c95adb..84856e83d01 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -685,38 +685,40 @@ test("ordered frame reads follow the budget", async () => { expect(await live.readString()).toBe("2000"); }); -// Interleaving nextGroup with the frame helpers is still one cursor: a nextGroup that +// Interleaving a group take with the frame helpers is still one cursor: a take that // moves past the group the frame helpers were draining abandons it, so a later frame // read never runs backwards. -test("nextGroup abandons the frame helpers' group when it passes it", async () => { - const producer = new TrackProducer("test"); - const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); - - const zero = new GroupProducer(0); - zero.writeFrame(textFrame("0.0")); - zero.writeFrame(textFrame("0.1")); - zero.close(); - producer.writeGroup(zero); - - const one = new GroupProducer(1); - one.writeFrame(textFrame("1.0")); - one.close(); - producer.writeGroup(one); - - const two = new GroupProducer(2); - two.writeFrame(textFrame("2.0")); - two.close(); - producer.writeGroup(two); - - // The frame path enters group 0; a direct nextGroup then takes group 1. - expect((await track.readFrame())?.group).toBe(0); - expect((await track.nextGroup())?.sequence).toBe(1); - - // The frame path must not resume group 0 behind the cursor: it continues at 2. - const next = await track.readFrame(); - expect(next?.group).toBe(2); - expect(dec.decode(next?.payload)).toBe("2.0"); -}); +for (const take of ["nextGroup", "tryNextGroup"] as const) { + test(`${take} abandons the frame helpers' group when it passes it`, async () => { + const producer = new TrackProducer("test"); + const track = producer.subscribe({ maxDelay: Milli(5000) }).ordered(); + + const zero = new GroupProducer(0); + zero.writeFrame(textFrame("0.0")); + zero.writeFrame(textFrame("0.1")); + zero.close(); + producer.writeGroup(zero); + + const one = new GroupProducer(1); + one.writeFrame(textFrame("1.0")); + one.close(); + producer.writeGroup(one); + + const two = new GroupProducer(2); + two.writeFrame(textFrame("2.0")); + two.close(); + producer.writeGroup(two); + + // The frame path enters group 0; a direct take then claims group 1. + expect((await track.readFrame())?.group).toBe(0); + expect((await track[take]())?.sequence).toBe(1); + + // The frame path must not resume group 0 behind the cursor: it continues at 2. + const next = await track.readFrame(); + expect(next?.group).toBe(2); + expect(dec.decode(next?.payload)).toBe("2.0"); + }); +} // The frame helpers ride the same sequence cursor as nextGroup: a lower group arriving // after a higher one was read is skipped, never fed to the caller backwards. diff --git a/js/net/src/track.ts b/js/net/src/track.ts index e80441580e9..bf56f147ebc 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -2643,12 +2643,6 @@ export class Subscriber { const recv = this.#tryNextGroup(); switch (recv.kind) { case "group": - // One cursor: the frame helpers must not keep draining a group this - // read just moved past, or interleaved reads would run backwards. - if (this.#frameGroup && this.#frameGroup.sequence < recv.group.sequence) { - this.#frameGroup.close(); - this.#frameGroup = undefined; - } return recv.group; case "done": return undefined; @@ -2675,7 +2669,17 @@ export class Subscriber { // The synchronous half of #nextGroup. #tryNextGroup(): Recv { - if (this.#resume) return this.#tryResumed(true); + const recv = this.#resume ? this.#tryResumed(true) : this.#tryNextBuffered(); + // One cursor: the frame helpers must not keep draining a group this read just + // moved past, or interleaved reads would run backwards. + if (recv.kind === "group" && this.#frameGroup && this.#frameGroup.sequence < recv.group.sequence) { + this.#frameGroup.close(); + this.#frameGroup = undefined; + } + return recv; + } + + #tryNextBuffered(): Recv { const groups = this.#state.groups.peek(); const cursor = this.#cursor.peek(); const start = Math.max(cursor.start, this.#nextSequence); From f62f146d20539760c44ed46c09f7068fa43fb75f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 16:48:45 -0700 Subject: [PATCH 12/18] quest(m1): finish api-audit/serve The maintainer kept JS Track.Ordered.tryNextGroup() public, mirroring Rust track::Ordered::poll_next_group and Subscriber.tryRecvGroup(), since the js/json and js/flate latest() fixes need a non-blocking ordered read. Everything else the quest named stays internal, so this PR finishes it. Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/README.md | 1 - quest/m1/api-audit/serve.md | 31 ------------------------------- 2 files changed, 32 deletions(-) delete mode 100644 quest/m1/api-audit/serve.md diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index c2ff4761432..e689edb8494 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -90,7 +90,6 @@ Rejected in planning: - [Auth and clock names](/quest/m1/api-audit/auth-clock-names.md) - refusal and reason types have distinct names, and the Rust and JS clocks mirror each other - [Session-only items stay private](/quest/m1/api-audit/model-private.md) - model items only the built-in sessions use are private - [Only sessions accept a request](/quest/m1/api-audit/claim-request-type.md) - accepting an application claim's request fails to compile, and the peer-route hatches are crate-private -- [One range setter](/quest/m1/api-audit/serve.md) - `with_range` replaces seven cursor setters and nothing else of the serving cursor goes public - [A request's source enforces its validity](/quest/m1/api-audit/answer.md) - a stale source refuses new track requests by itself, with no public additions - [moq-transport stays private](/quest/m1/api-audit/ietf-private.md) - no public moq-net item exists only for moq-transport, and a client names its request target once as a URL - [One lifecycle vocabulary](/quest/m1/api-audit/lifecycle.md) - finish, abort, closed, and close mean one thing on every handle, and Rust and JS observers fire alike diff --git a/quest/m1/api-audit/serve.md b/quest/m1/api-audit/serve.md deleted file mode 100644 index 0cc48b9f85b..00000000000 --- a/quest/m1/api-audit/serve.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] One range setter - -## Goal - -A reader moves its cursor with one consuming `with_range(self, range)` (JS -`withRange`) on `track::Subscriber`, `track::Ordered`, `track::Subscription`, -and `group::Consumer`, replacing `set_groups`, `with_groups`, `start_at`, -`raise_start_to`, `end_at`, `subscription::Cap`, and -`group::Consumer::set_frames`. Nothing else becomes public. - -## Plan - -Decided 2026-10-23 (maintainer), reshaping -[moq-dev/moq#6138](https://github.com/moq-dev/moq/pull/6138) after the -public-model goal was dropped -([session-only items stay private](/quest/m1/api-audit/model-private.md)): - -- Keep `with_range` and the bug fixes #6138 carries: js/json and js/flate - `latest()` keeping the caller's cap, `group::Consumer::poll_finished` - ending cleanly at a frame cap, and a closed JS subscriber's groups still - expiring. -- Everything else #6138 made public for custom publishers stays internal: - `track::Subscriber::{poll_start, poll_drop}`, - `group::Consumer::poll_expired`, `Position::final_sequence`, - `Subscription::{start, end, with_start, with_end}`, and the JS `Recv` - union, `groupChanged`, `Ordered.tryNextGroup`, `finalSequence`, - `Consumer.info({ hold })`, and `Group.Consumer.expired`. The sessions call - them through `pub(crate)` and `@internal` (or the existing hooks). - -Public API: moq-net and `@moq/net` breaking (`with_range` replaces the -setters). Wire: none. From 370dbcb33bf6c0dcd9a856b344b4311328f3e1f5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 17:20:16 -0700 Subject: [PATCH 13/18] fix(net): cap served groups at the end only, keeping a missing prefix fatal with_range also moved the start, which clamps up past a prefix the group never held, so an IETF subgroup or lite FETCH could serve a group's tail as the whole group instead of failing with Lagged. Both now set only the end, as main's end_at did. Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/ietf/publisher.rs | 43 +++++++++++++++++++++++++++++++- rs/moq-net/src/lite/publisher.rs | 8 +++--- rs/moq-net/src/model/group.rs | 8 +++--- 3 files changed, 49 insertions(+), 10 deletions(-) diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index c7266e3d3d9..e8f101eb135 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -5237,8 +5237,10 @@ impl GroupServe { slice: GroupSlice, ) -> Self { if group.wire().is_none() { + // Only the end: a start would clamp past a prefix the group never held, + // which `skip_to` leaves to fail as `Lagged`. group.skip_to(slice.skip); - group = group.with_range((Bound::Unbounded, slice.until.map_or(Bound::Unbounded, Bound::Excluded))); + group = group.with_end(slice.until); } Self { session, @@ -6505,6 +6507,45 @@ mod group_priority_test { assert!(matches!(serving.await, Err(Error::Old))); } + /// A local group that never held the requested prefix fails rather than serving its + /// tail as the whole group, with or without an end inside it. + #[moq_clock::test] + async fn a_group_missing_its_prefix_fails() { + for until in [None, Some(5)] { + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "test", + crate::track::Info::timed(), + ); + let mut subscriber = track.subscribe(None); + let mut producer = track.create_group(group::Info { sequence: 0 }).unwrap(); + producer.start_at(1).unwrap(); + producer + .write_frame(crate::Timestamp::ZERO, b"tail".as_slice()) + .unwrap(); + producer.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("the group"); + + let mut serve = GroupServe::new( + SinkSession::new(Default::default()), + ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + Rank::solo(kio::Producer::new(0).consume()), + group, + Some(Timescale::MILLI), + Version::Draft19, + GroupSlice { skip: 0, until }, + ); + let served = kio::wait(|waiter| serve.poll_serve(waiter)).await; + assert!(matches!(served, Err(Error::Lagged)), "until {until:?}: {served:?}"); + } + } + /// A FIN holds the subgroup's bytes until the peer acknowledges it, so a subgroup /// that goes stale while waiting still expires instead of pinning them. #[moq_clock::test] diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 0e3354ab02f..ae610cb956f 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2314,11 +2314,9 @@ impl Request for FetchServe { } // The end is a serving cap only: the cached group runs to the end of // the group so it stays usable for anyone else (see - // `group::Fetch::frame_start`). - let mut group = group.with_range(( - Bound::Unbounded, - msg.end_frame.map_or(Bound::Unbounded, Bound::Included), - )); + // `group::Fetch::frame_start`). Only the end, so the start stays where + // the check above found it. + let mut group = group.with_end(msg.end_frame.and_then(|end| end.checked_add(1))); // Matches the timescale TRACK_INFO declared for the track. let stamp = Stamp::new(shared.version, group.lite_timescale(ietf)); diff --git a/rs/moq-net/src/model/group.rs b/rs/moq-net/src/model/group.rs index 00876a33c40..019ccc79b58 100644 --- a/rs/moq-net/src/model/group.rs +++ b/rs/moq-net/src/model/group.rs @@ -2787,10 +2787,10 @@ impl Consumer { self } - /// Cap reads before frame `end` without moving the start, which [`Self::with_range`] - /// would clamp up to the first available frame. - pub(super) fn with_end(mut self, end: u64) -> Self { - self.cursor.end = Some(usize::try_from(end).unwrap_or(usize::MAX)); + /// Cap reads before frame `end`, or remove the cap with `None`, without moving the + /// start, which [`Self::with_range`] would clamp up to the first available frame. + pub(crate) fn with_end(mut self, end: impl Into>) -> Self { + self.cursor.end = end.into().map(|end| usize::try_from(end).unwrap_or(usize::MAX)); self } From d4bee306b0234fc5d45e80bc23e43f04d6cfa6f8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 17:50:56 -0700 Subject: [PATCH 14/18] docs(net): lift a reader's cap without dropping its floor in MIGRATE Also gate Subscription::with_start on test like its siblings, since its unit test calls it. Co-Authored-By: Claude Opus 5.5 --- js/net/MIGRATE.md | 2 +- rs/moq-net/MIGRATE.md | 2 +- rs/moq-net/src/model/subscription.rs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/js/net/MIGRATE.md b/js/net/MIGRATE.md index 39368e0d9fa..6390b7ebb06 100644 --- a/js/net/MIGRATE.md +++ b/js/net/MIGRATE.md @@ -72,7 +72,7 @@ Close the claim and claim again to change it, and close an answer's producer to A largest past the cap or below the floor reports nothing; the cache never stands in for it. A cap moved below the largest stays pending. Moving the bounds wakes a pending read, which reports the largest once it is within them and newer than the last report. Unbounded readers are unchanged. -To read the track's edge from a capped reader, lift the cap with `withRange({})` first. +To read the track's edge from a capped reader, lift the cap first with `withRange({ start: { included: floor } })`, passing the floor you want to keep. ### Lite-07 accounts for groups with `SUBSCRIBE_DROP` diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 1aee2ccf7bd..d57b502c3f0 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -203,7 +203,7 @@ A largest past the cap or below the floor reports nothing; the cache never stand A cap moved below the largest stays pending. Moving the bounds wakes a pending read, which reports the largest once it is within them and newer than the last report. Every `largest()`, `track::Producer` and `track::Consumer` included, now waits while a relay's copy is idle and reports once its new upstream subscription is live, rather than the largest an ended feed left. Cached groups are still served meanwhile. -To read the track's edge from a capped reader, lift the cap with `with_range(..)` first. +To read the track's edge from a capped reader, lift the cap first with `with_range(floor..)`, passing the floor you want to keep. ### Lite-07 accounts for groups with `SUBSCRIBE_DROP` diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index eaaa19b9ccd..b9543c75904 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -336,7 +336,7 @@ impl Subscription { /// Replace the ranges with one from `start` (or [`Range::oldest`]'s) up to [`Self::end`], /// returning `self` for chaining: the form a wire without ranges carries. - #[cfg(feature = "async")] + #[cfg(any(feature = "async", test))] pub(crate) fn with_start(self, start: impl Into>) -> Self { let end = self.end(); self.with_span(start.into(), end) From 46ae4edb25c5335ee2b8f7c11cb83e658a29e7bc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 24 Oct 2026 00:40:48 -0700 Subject: [PATCH 15/18] test(net): close the installed manual clock as main's helpers now do Co-Authored-By: Claude Opus 5.5 --- js/net/src/parked-expiry.test.ts | 4 ++-- js/net/src/resume.test.ts | 4 ++-- js/net/src/track.test.ts | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/js/net/src/parked-expiry.test.ts b/js/net/src/parked-expiry.test.ts index dc0c704fb10..a30b7862e54 100644 --- a/js/net/src/parked-expiry.test.ts +++ b/js/net/src/parked-expiry.test.ts @@ -151,7 +151,7 @@ for (const protocol of protocols) { for (const protocol of protocols) { test(`${protocol.alpn}: a blocked group write ends when eviction takes what it has yet to read`, async () => { const clock = new Manual(); - const restore = clock.install(); + const installed = clock.install(); const pair = createMockTransportPair(protocol.alpn); const origin = new Origin(); const broadcast = origin.createBroadcast(Path.from("parked")); @@ -239,7 +239,7 @@ for (const protocol of protocols) { origin.close(); await running; opening.mockRestore(); - restore(); + installed.close(); } }); } diff --git a/js/net/src/resume.test.ts b/js/net/src/resume.test.ts index 8732bec670a..2593bc96c61 100644 --- a/js/net/src/resume.test.ts +++ b/js/net/src/resume.test.ts @@ -1823,7 +1823,7 @@ test.each(["lands", "dropped", "expired"])( ); test("a group read whole still expires once the reader lets go of its copy", async () => { - const { clock, restore } = manual(); + const { clock, installed } = manual(); const front = new Front(); const a = new BroadcastProducer(); const b = new BroadcastProducer(); @@ -1870,7 +1870,7 @@ test("a group read whole still expires once the reader lets go of its copy", asy front.consumer.close(); a.close(); b.close(); - restore(); + installed.close(); } }); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index 18f0196c691..d0f280fb76b 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -1116,7 +1116,7 @@ test("a fully read group still reports its expiry", async () => { expect(group.expired.peek()).toMatchObject({ code: StreamCode.Old }); } finally { producer.close(); - clock.restore(); + clock.installed.close(); } }); From acfba05e09f36cdd9e53fe2134d0a2f22fb9d659 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 24 Oct 2026 01:02:51 -0700 Subject: [PATCH 16/18] test(net): poll main's held-successor tests through the folded poll_expired Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 9317c58362b..f8c7b75e539 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -9772,7 +9772,7 @@ mod test { let waiter = kio::Waiter::noop(); let expired = |held: &mut [group::Consumer; 2]| { held.each_mut() - .map(|group| group.poll_expired_while_pending(&waiter, true)) + .map(|group| group.poll_expired(&waiter)) }; // Frozen timestamps, so the wall clock alone convicts. @@ -9820,7 +9820,7 @@ mod test { newest = subscriber.assert_group(); } elapse(&producer, budget * 2); - assert!(!newest.poll_expired_while_pending(&waiter, true), "the newest group"); + assert!(!newest.poll_expired(&waiter), "the newest group"); } /// A recorded successor that failed hands the clock on to the next live group even once @@ -9834,7 +9834,7 @@ mod test { let waiter = kio::Waiter::noop(); let expired = |held: &mut [group::Consumer; 2]| { held.each_mut() - .map(|group| group.poll_expired_while_pending(&waiter, true)) + .map(|group| group.poll_expired(&waiter)) }; append_at(&mut producer, 0); @@ -9892,7 +9892,7 @@ mod test { pool.step(Duration::from_secs(1)); append_at(&mut producer, 0); // the successor assert!( - !held.poll_expired_while_pending(&waiter, true), + !held.poll_expired(&waiter), "the successor is recorded" ); let state = producer.state.downgrade(); @@ -9909,11 +9909,11 @@ mod test { Some(true), "expired in place" ); - assert!(!held.poll_expired_while_pending(&waiter, true), "early"); + assert!(!held.poll_expired(&waiter), "early"); pool.step(budget - idle); assert!( - held.poll_expired_while_pending(&waiter, true), + held.poll_expired(&waiter), "the successor arrived a budget ago" ); } From bffc24817f300f61d1f44c0452d614837ec27e41 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 24 Oct 2026 01:03:36 -0700 Subject: [PATCH 17/18] style(net): format the adapted held-successor tests Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index f8c7b75e539..daf6a7af273 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -9770,10 +9770,7 @@ mod test { let budget = cache::DEFAULT_EXPIRY * 2; let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget)); let waiter = kio::Waiter::noop(); - let expired = |held: &mut [group::Consumer; 2]| { - held.each_mut() - .map(|group| group.poll_expired(&waiter)) - }; + let expired = |held: &mut [group::Consumer; 2]| held.each_mut().map(|group| group.poll_expired(&waiter)); // Frozen timestamps, so the wall clock alone convicts. append_at(&mut producer, 0); @@ -9832,10 +9829,7 @@ mod test { let budget = cache::DEFAULT_EXPIRY * 2; let mut subscriber = producer.subscribe(Subscription::default().with_max_delay(budget)); let waiter = kio::Waiter::noop(); - let expired = |held: &mut [group::Consumer; 2]| { - held.each_mut() - .map(|group| group.poll_expired(&waiter)) - }; + let expired = |held: &mut [group::Consumer; 2]| held.each_mut().map(|group| group.poll_expired(&waiter)); append_at(&mut producer, 0); let fetch = group::Fetch::default().with_max_delay(budget); @@ -9891,10 +9885,7 @@ mod test { pool.step(Duration::from_secs(1)); append_at(&mut producer, 0); // the successor - assert!( - !held.poll_expired(&waiter), - "the successor is recorded" - ); + assert!(!held.poll_expired(&waiter), "the successor is recorded"); let state = producer.state.downgrade(); producer.finish().unwrap(); drop(producer); @@ -9912,10 +9903,7 @@ mod test { assert!(!held.poll_expired(&waiter), "early"); pool.step(budget - idle); - assert!( - held.poll_expired(&waiter), - "the successor arrived a budget ago" - ); + assert!(held.poll_expired(&waiter), "the successor arrived a budget ago"); } /// Empty groups are handed out like any other and retired by the wall clock like an From c26994291428cd08e1113acfa953b7854bee25b6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 24 Oct 2026 05:52:52 -0700 Subject: [PATCH 18/18] fix(net): rename main's new set_groups uses to with_range Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/track.rs | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c70978a2463..e2dabd0828c 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -6940,7 +6940,7 @@ impl Subscriber { } /// The lowest group this subscriber's ranges name, as resolved here when it last read, - /// raised to the start of [`Self::set_groups`]: `None` while one reaches back to the + /// raised to the start of [`Self::with_range`]: `None` while one reaches back to the /// oldest group still around, or a relative start still waits on the first group from /// the live feed. /// @@ -6955,7 +6955,7 @@ impl Subscriber { } /// The lowest group at or above `from` this subscriber's ranges and - /// [`Self::set_groups`] floor cover, `None` when none does: the groups between are + /// [`Self::with_range`] floor cover, `None` when none does: the groups between are /// never read, so a reader waiting on each group in sequence need not wait for them. /// `Some` from there while a relative anchor waits on the first group, which can't /// say yet. @@ -8180,24 +8180,22 @@ mod test { /// The floor a reader waiting on each group starts at is the higher of its ranges' and /// its local one, so it never waits on a group the local floor withholds. #[test] - fn floor_honors_set_groups() { + fn floor_honors_with_range() { let producer = track_producer("test", Info::default()); let _groups: Vec<_> = (0..6).map(|sequence| framed(&producer, sequence, 2)).collect(); - let mut reader = producer.subscribe(replay().with_groups(2..)); + let reader = producer.subscribe(replay().with_range(2..)); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(2), Some(2))); - reader.set_groups(4..); + let reader = reader.with_range(4..); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(4), Some(4))); assert_eq!(reader.next_in_range(5), Some(5)); // Below the ranges' floor, the ranges still decide. - let mut reader = producer.subscribe(replay().with_groups(3..)); - reader.set_groups(1..); + let reader = producer.subscribe(replay().with_range(3..)).with_range(1..); assert_eq!((reader.floor(), reader.next_in_range(0)), (Some(3), Some(3))); // A floor reaching back to the oldest group stays unknown. - let mut reader = producer.subscribe(replay()); - reader.set_groups(4..); + let reader = producer.subscribe(replay()).with_range(4..); assert_eq!(reader.floor(), None); }