From 07fde934be328b52eee08c2e5eb876c297e87098 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 05:50:01 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m2/unused-api/net.md Quest-Claim: 857f514b2297b0e6 From 7504a5280432af4009fccffae72bc5349b955475 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 06:10:06 -0800 Subject: [PATCH 2/2] feat(net)!: moq-net publishes no item without a caller Remove Position::after, after_group, and group_end; make the 17 public lite::Version predicates crate-private; make Ordered::with_range test-only; move moq-audio's live start onto Range::live(). The lite subscriber tells a reset from malformed bytes through a typed Recv outcome from the reader instead of matching error variants. Co-Authored-By: Claude Sonnet 5.5 --- quest/m2/group-drops.md | 11 +++ quest/m2/net-renames.md | 1 - quest/m2/sockets/remove.md | 4 - quest/m2/unused-api/net.md | 85 ------------------- quest/m4/readers-range-live.md | 3 +- rs/moq-audio/src/decode/consumer.rs | 28 +++--- rs/moq-net/src/coding/reader.rs | 108 +++++++++++++++++++++++- rs/moq-net/src/lite/subscriber.rs | 39 ++++++--- rs/moq-net/src/lite/subscriber/fills.rs | 44 +++++----- rs/moq-net/src/lite/version.rs | 34 ++++---- rs/moq-net/src/model/subscription.rs | 50 +---------- rs/moq-net/src/model/track.rs | 22 ++--- 12 files changed, 204 insertions(+), 225 deletions(-) delete mode 100644 quest/m2/unused-api/net.md diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 69d44aa0fe5..42756598822 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -66,6 +66,17 @@ groups plus reported spans cover everything sent. At HEAD count of keys, which [the wire rewrite](/quest/m2/time-addressing/lite07.md) turns into the span's end. +Decided 2026-11-16 (the unused moq-net API sweep): once the container reader +reads gaps through `Gap`, `track::Subscriber::next_in_range`, `is_skipped`, +and `poll_start` (their one consumer is moq-mux's container reader, which +orders groups itself) go crate-private in the same PR. So does +`Subscriber::with_range`, whose last production caller is +`rs/moq-mux/src/container/source.rs`'s resubscription, which leaves out the +group it already read (a time start names the group containing it, so a +`Subscription` range cannot exclude one); if the reader can skip that group +through `Gap` or its own cursor, the sweep's other callers (tests in moq-mux +and moq-json) move to `Subscription::ranges`, otherwise it stays. + Public API: breaking for `track::Ordered` only. Its one read, `poll_next_group` (and its async wrapper), returns `Result>` instead of `Result>`, where diff --git a/quest/m2/net-renames.md b/quest/m2/net-renames.md index c0d08a2a2ca..c430636491d 100644 --- a/quest/m2/net-renames.md +++ b/quest/m2/net-renames.md @@ -83,4 +83,3 @@ them. Wire: none. - [The route switch](/quest/m2/multicast/switch.md) - removes the route key beside the node identity this renames - [Session close codes](/quest/m2/session-codes.md) - the other public moq-net cleanup in `error.rs` -- [Unused moq-net API](/quest/m2/unused-api/net.md) - makes the lite version predicates crate-private beside the opaque `Version` diff --git a/quest/m2/sockets/remove.md b/quest/m2/sockets/remove.md index a078b6f91c6..d3fefba104b 100644 --- a/quest/m2/sockets/remove.md +++ b/quest/m2/sockets/remove.md @@ -90,7 +90,3 @@ Public API: breaking for `main`-only API in every language; nothing on - [MoQ Boy viewers publish their commands again](/quest/m2/sockets/boy.md) - the emulator and its element stop using `moq_net::socket` and `@moq/net`'s `Socket` - [CARLA drivers publish their controls again](/quest/m2/sockets/carla.md) - the worker stops using the Python wrapper and the player `@moq/net`'s `Socket` - -## Related - -- [moq-net publishes no item without a caller](/quest/m2/unused-api/net.md) - the sweep this keeps `is_endpoint` out of diff --git a/quest/m2/unused-api/net.md b/quest/m2/unused-api/net.md deleted file mode 100644 index 6ab781f3d9b..00000000000 --- a/quest/m2/unused-api/net.md +++ /dev/null @@ -1,85 +0,0 @@ -# [S] moq-net publishes no item without a caller - -## Goal - -The moq-net crate the cut publishes has no public item that nothing outside -it calls: each one below is removed or made `pub(crate)`, and the one place -moq-lite's subscriber tells outcomes apart by matching error variants reads -a typed outcome instead. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ remove -or hide every public item the audit found without a caller, one sweep quest -per area, each item re-checked for a downstream caller first (rejected: -keeping them until someone complains; one sweep across every crate). An item -stays private until a consumer needs it, and adding it back later is -additive while removing it after the cut is a break. - -Before removing an item, grep Kixel and moq.pro for a caller (the -maintainer's condition). Keep what one uses, and name the caller in the PR. - -Items, each with the grep that showed no caller at `80ca9787e3` (over `rs`, -`js`, `py`, `swift`, `kt`, `dart`, `cpp`, `go`, `demo`, and `test`, outside -`rs/moq-net/`): - -- `track::Position::after`, `after_group`, and `group_end` - (`rs/moq-net/src/model/subscription.rs:610`, `:622`, `:631`): remove. - `grep -rnF 'Position::after('`, `'after_group('`, and `'.group_end()'` - find 0 lines outside moq-net; inside, only unit tests and `after` calling - `after_group`. `after_group` is `start + 1`, which no longer names the - next group now that groups are addressed by start. -- `origin::Consumer::covering` (`rs/moq-net/src/model/origin.rs:7734`): make - `pub(crate)`. `grep -rnF '.covering()'` finds 0 lines outside moq-net; the - lite and moq-transport sessions call it, and its doc says "a session - serving its peer always uses this view". -- `track::Subscriber::with_range` and `track::Ordered::with_range` - (`rs/moq-net/src/model/track.rs:10427`, `:10756`): make `pub(crate)` after - moving their two production callers - (`rs/moq-mux/src/container/source.rs:621`, - `rs/moq-audio/src/decode/consumer.rs:243`) to `Subscription::ranges`, which - is already the subscriber's read filter. The audio caller's comment gives - a reason, that a range is aggregated across subscribers and can rewind the - publisher for everyone, that `Range::live()` no longer has. If either - caller cannot move, keep the method and say why in the PR. Sessions and - resume keep using it inside the crate. -- The 17 `pub fn` predicates of `lite::Version` - (`rs/moq-net/src/lite/version.rs`, `has_track_stream` to `has_route_cost`): - make `pub(crate)`. They are reachable today only through the public - `Version::Lite` variant, and no caller exists outside moq-net; the relay - uses only the crate-level `Version::has_request_path`. Each would - otherwise be a public name to keep or break as lite-08 moves the cut-offs. - [The opaque `Version`](/quest/m2/net-renames.md) closes the same door from - the other side; either order works. -- `Recovery` (`rs/moq-net/src/lite/subscriber/fills.rs:691-695`) matches - `Error::Decode(DecodeError::Short)` and then - `matches!(err, Error::ProtocolViolation)` to tell a reset from malformed - bytes, against AGENTS.md's "never match on errors". The reader returns a - typed outcome (ended, reset, malformed) that both `Recovery` and the live - subscription read. No API change. - -Not in this sweep, with their owners: - -- `Subscriber::next_in_range`, `is_skipped`, and `poll_start` have one - consumer, moq-mux's container reader, which orders groups itself. - [Group drops](/quest/m2/group-drops.md) adds `Gap` to `track::Ordered`; - once the container reader moves onto it these three can go private. -- `socket::is_endpoint` leaves with - [socket endpoints](/quest/m2/sockets/remove.md). -- `origin::Producer::update_hold`, `with_proxy`, `Source`, `source()`, - `Consumer::local()`, `origin::RouteKey`, and `Config::route_key` belong to - [the route switch](/quest/m2/multicast/switch.md). -- `setup::Extensions` belongs to - [the `ietf` extension](/quest/m2/ietf-records-per-track.md). - -Run `just api-diff rust` after the change and list -every item it shows removed in the PR's Impact section. - -Public API: breaking, removals only (`Position::after`, `after_group`, -`group_end`, `origin::Consumer::covering`, `Subscriber::with_range`, -`Ordered::with_range`, and the `lite::Version` predicates). Wire: none. - -## Related - -- [moq-net's node, version, handshake, and route priority](/quest/m2/net-renames.md) - makes `Version` opaque -- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - gives the container reader the `Gap` that frees three more methods diff --git a/quest/m4/readers-range-live.md b/quest/m4/readers-range-live.md index fdace3f2515..83fae1e00f8 100644 --- a/quest/m4/readers-range-live.md +++ b/quest/m4/readers-range-live.md @@ -3,7 +3,8 @@ ## Goal The readers that wait for the largest group and raise their floor to -start near it (moq-audio, moq-video, and `@moq/room` chat) +start near it (moq-video and `@moq/room` chat; moq-audio already subscribes +with `Range::live()`) subscribe with a relative range instead, with no change in what they play: `Range::live()` for a start at the newest group, and a relative start for a reader that looks back, such as moq-video's warmup lane, which keeps its diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index f3d0da8fe1f..1ec27cf84b7 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -225,22 +225,20 @@ impl Consumer { // The whole delay from the start, as the container keeps it: the transport enforces the // max too, so a narrower one while joining would drop the groups queued behind a reader // slow to take its first, and the publisher should never see a stated zero min first. - let mut subscriber = track - .subscribe( - playout - .subscription(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)), - ) - .await?; + let mut subscription = + playout.subscription(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)); // Latest skips cached history; a warmup is primed by trimming the newest group's - // start, like any other join. Move the local cursor, not Subscription::ranges: the - // latter is aggregated across subscribers and can ask the publisher to rewind for - // everyone. The live edge is known only 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 options.start == Start::Latest - && let Some(live_edge) = subscriber.largest().await - { - subscriber = subscriber.with_range(live_edge.group..); + // start, like any other join. A live start counts from the latest group each hop + // holds from its live feed, so it names no cached group that would ask the publisher + // to rewind for everyone reading. + if options.start == Start::Latest { + subscription = subscription.with_ranges([moq_net::track::Range::live()]); + } + let mut subscriber = track.subscribe(subscription).await?; + // The live edge is known only 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 options.start == Start::Latest { + subscriber.largest().await; } let track = subscriber; let max_age = track.info().max_age; diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index 3d06c29b81b..9ce817db08d 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -42,6 +42,34 @@ pub struct Reader { /// enough that an ordinary burst is still one wake. const WAKE_BUDGET: usize = 64 * 1024; +/// How a [`Reader`] read ended, told apart where the reader knows which it was, so a caller +/// never has to match an [`Error`] to tell a cut stream from malformed bytes. +pub(crate) enum Recv { + /// The next message. + Message(T), + /// The stream finished cleanly between messages. + Ended, + /// The stream was reset, or finished inside a message: the reason it gave. + Reset(Error), + /// The bytes are not a valid message. + Malformed(DecodeError), +} + +/// Why a read gave up, before a caller picks [`Recv`] or an [`Error`]. +enum Fault { + Reset(Error), + Malformed(DecodeError), +} + +impl From for Error { + fn from(fault: Fault) -> Self { + match fault { + Fault::Reset(err) => err, + Fault::Malformed(err) => err.into(), + } + } +} + /// A stream ingest may stop reading to pace a group's writer, which holds its receive /// credit meanwhile. pub(crate) trait Pause { @@ -142,8 +170,21 @@ impl Reader { &mut self, waiter: &kio::Waiter, consume: bool, - mut decode: impl FnMut(&mut Decoder<'_>) -> Result, + decode: impl FnMut(&mut Decoder<'_>) -> Result, ) -> Poll> + where + V: Into
+ Copy, + { + self.poll_fault(waiter, consume, decode).map_err(Error::from) + } + + /// [`Self::poll_with_sized`], keeping a reset apart from malformed bytes. + fn poll_fault( + &mut self, + waiter: &kio::Waiter, + consume: bool, + mut decode: impl FnMut(&mut Decoder<'_>) -> Result, + ) -> Poll> where V: Into + Copy, { @@ -151,7 +192,8 @@ impl Reader { loop { let want = self.want.max(1); let version = &self.version; - let mut lease = ready!(self.stream.poll_lease(waiter, want)).map_err(|err| version.transport_error(err))?; + let mut lease = ready!(self.stream.poll_lease(waiter, want)) + .map_err(|err| Fault::Reset(version.transport_error(err)))?; // Decode against the first chunk, or a copy of as much as the last attempt needed // when that spans chunks. Only a message cut across chunks pays for the copy. @@ -196,7 +238,7 @@ impl Reader { // A short read inside a complete body is malformed, but reports what it // needed from the body, so always ask for at least one byte more. Err(DecodeError::Short) => r.need().max(buf.len() + 1), - Err(e) => return Poll::Ready(Err(e.into())), + Err(e) => return Poll::Ready(Err(Fault::Malformed(e))), }; if need <= lease.remaining() { @@ -205,7 +247,7 @@ impl Reader { } // Stream closed while we still need more data. if lease.is_fin() { - return Poll::Ready(Err(DecodeError::Short.into())); + return Poll::Ready(Err(Fault::Reset(DecodeError::Short.into()))); } self.want = need; // The lease keeps every byte for the retry, which copies them again, so a @@ -298,6 +340,24 @@ impl Reader { self.poll_with_maybe(waiter, true, |r| T::decode(r, version)) } + /// The next message, or how the stream ended instead. + pub(crate) fn poll_recv Decode<'a, V> + Debug>(&mut self, waiter: &kio::Waiter) -> Poll> + where + V: Into + Copy, + { + match ready!(self.poll_has_more(waiter)) { + Err(err) => return Poll::Ready(Recv::Reset(err)), + Ok(false) => return Poll::Ready(Recv::Ended), + Ok(true) => {} + } + let version = self.version; + Poll::Ready(match ready!(self.poll_fault(waiter, true, |r| T::decode(r, version))) { + Ok((message, _)) => Recv::Message(message), + Err(Fault::Reset(err)) => Recv::Reset(err), + Err(Fault::Malformed(err)) => Recv::Malformed(err), + }) + } + /// The next message without consuming it, or `None` if the stream closes cleanly first. #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_decode_peek_maybe Decode<'a, V> + Debug>( @@ -686,6 +746,46 @@ mod tests { assert_eq!(counted(), [vec![auth], probes(2)].concat()); } + /// A read tells a message, a clean end, a stream cut inside a message, and malformed + /// bytes apart, without a caller matching the error. + #[test] + fn a_read_tells_a_cut_stream_from_malformed_bytes() { + use crate::lite; + let version = lite::Version::Lite07; + let waiter = &kio::Waiter::noop(); + let probe = lite::Probe { + bitrate: Some(123), + rtt: Some(4), + }; + let bytes: &'static [u8] = probe.encode_bytes(version).unwrap().to_vec().leak(); + + let mut reader = queue(&[bytes], version); + reader.stream.get_mut().fin = true; + assert!(matches!( + reader.poll_recv::(waiter), + Poll::Ready(Recv::Message(_)) + )); + assert!(matches!( + reader.poll_recv::(waiter), + Poll::Ready(Recv::Ended) + )); + + // The stream finishes inside the message: a cut, not a violation. + let mut reader = queue(&[&bytes[..2]], version); + reader.stream.get_mut().fin = true; + assert!(matches!( + reader.poll_recv::(waiter), + Poll::Ready(Recv::Reset(_)) + )); + + // A body cut short inside its declared size is malformed. + let mut reader = queue(&[&[1, 0x80]], version); + assert!(matches!( + reader.poll_recv::(waiter), + Poll::Ready(Recv::Malformed(_)) + )); + } + /// STOP_SENDING refuses a stream, so it must carry a stream code. Reusing the session /// table here would have the peer decode it against the wrong registry: `Cancel` would /// arrive as INTERNAL_ERROR, and `Unauthorized` as DELIVERY_TIMEOUT. diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index 2dcfa8c5857..99926d95295 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -10,7 +10,7 @@ use std::{ use crate::{ Error, Path, Timescale, Timestamp, bandwidth, - coding::{Decode as _, Reader, Stream}, + coding::{Decode as _, Reader, Recv, Stream}, lite, track::{Anchor, Position, Subscription}, util::SendCell, @@ -13133,19 +13133,23 @@ impl TrackServeRun { // to the session's other tasks while a peer streams them. let mut budget = kio::coop::Budget::new(32); while let Some(stream) = reader - && let Poll::Ready(res) = stream.poll_decode_maybe::(waiter) + && let Poll::Ready(res) = stream.poll_recv::(waiter) { match res { - Ok(Some(_)) => {} + Recv::Message(_) => {} // The publisher's FIN in reply, or a reset: the stream is done. - Ok(None) => { + Recv::Ended | Recv::Reset(_) => { *reader = None; break; } // Malformed bytes are a protocol violation here as on any Subscribe - // Stream, which closes the session; a short read at a FIN is not. - Err(err) => { - let _ = lite::error::control(&mut self.serve.subscriber.session.clone(), err); + // Stream, which closes the session; a reset or a FIN inside a message + // is not. + Recv::Malformed(_) => { + let _ = lite::error::control( + &mut self.serve.subscriber.session.clone(), + Error::ProtocolViolation, + ); *reader = None; break; } @@ -14315,10 +14319,7 @@ impl ServeLoop { // (4) The upstream subscribe stream closed, or carried a START/END/DROP. // Partial message bytes persist in the reader's buffer across turns. if let Sub::Active(active) = &mut self.sub - && let Poll::Ready(res) = active - .stream - .reader - .poll_decode_maybe::(waiter) + && let Poll::Ready(res) = active.stream.reader.poll_recv::(waiter) { // The publisher answered the SUBSCRIBE, so its demand stands on the // subscription now. A query still held once that subscription ends @@ -14326,7 +14327,7 @@ impl ServeLoop { self.held = None; active.unanswered = None; match res { - Ok(Some(msg)) => { + Recv::Message(msg) => { if let Err(err) = self.apply_response(serve, msg) { return Poll::Ready(ServeEnd::GiveBack(err)); } @@ -14335,7 +14336,7 @@ impl ServeLoop { ready!(budget.poll_yield(waiter)); continue; } - Ok(None) => { + Recv::Ended => { // The publisher ends the subscription only once it declared the // track's end: with SUBSCRIBE_FINISH from lite-05, which lite-07 // reads into the tail without a FIN. @@ -14355,7 +14356,17 @@ impl ServeLoop { }; continue; } - Err(err) => { + // Malformed bytes are a protocol violation, which closes the session; a + // reset gives up the subscription with its reason. + Recv::Malformed(err) => { + tracing::warn!(broadcast = %serve.subscriber.log_path(&serve.path), track = %serve.name, %err, "subscribe error"); + self.mode = ServeMode::Failed { + err: Error::ProtocolViolation, + tail: active.tail.consume(), + }; + continue; + } + Recv::Reset(err) => { tracing::warn!(broadcast = %serve.subscriber.log_path(&serve.path), track = %serve.name, %err, "subscribe error"); self.mode = ServeMode::Failed { err, diff --git a/rs/moq-net/src/lite/subscriber/fills.rs b/rs/moq-net/src/lite/subscriber/fills.rs index 3b1d481e8a5..059305058a4 100644 --- a/rs/moq-net/src/lite/subscriber/fills.rs +++ b/rs/moq-net/src/lite/subscriber/fills.rs @@ -11,7 +11,9 @@ use rangemap::{RangeMap, RangeSet}; use super::{Establish, SubStream, Tail, TrackServe}; use crate::{ - Error, StreamError, group, lite, + Error, StreamError, + coding::Recv, + group, lite, track::{self, Delay, Order, Position, Subscription}, }; @@ -619,12 +621,7 @@ impl Recovery { if let Poll::Ready(Err(err)) = active.stream.writer.poll_flush(waiter) { tracing::debug!(%err, "recovery subscribe write failed"); } - let res = ready!( - active - .stream - .reader - .poll_decode_maybe::(waiter) - ); + let res = ready!(active.stream.reader.poll_recv::(waiter)); let now = self.serve.subscriber.runtime.now(); let version = self.serve.subscriber.version; let groups = self.groups.clone(); @@ -641,7 +638,7 @@ impl Recovery { }; match res { // One start, for its one range. - Ok(Some(lite::SubscribeResponse::Start(start))) + Recv::Message(lite::SubscribeResponse::Start(start)) if active.started.is_none() && start.starts.len() == 1 => { // Below its start the publisher delivers nothing. @@ -652,49 +649,46 @@ impl Recovery { ); active.started = Some(start.starts[0]); } - Ok(Some(lite::SubscribeResponse::Drop(dropped))) => { + Recv::Message(lite::SubscribeResponse::Drop(dropped)) => { given_up(dropped.groups.clone(), Refusal::dropped(dropped.error(version))); } // Never produced, such as the keys between two sparse group starts: the copy // records the skip, as the subscription itself does, and a fill owing one // is answered rather than asked again. - Ok(Some(lite::SubscribeResponse::Skip(skipped))) => { + Recv::Message(lite::SubscribeResponse::Skip(skipped)) => { if !skipped.groups.is_empty() { self.serving.skip_received(skipped.groups.clone()); given_up(skipped.groups, Refusal::dropped(StreamError::NotFound)); } } // Nothing at or past the track's end will be produced. - Ok(Some(lite::SubscribeResponse::Finish(finish))) if active.end.is_none() => { + Recv::Message(lite::SubscribeResponse::Finish(finish)) if active.end.is_none() => { given_up( finish.group.max(groups.start)..groups.end, Refusal::dropped(StreamError::NotFound), ); active.end = Some(finish); } - Ok(Some(lite::SubscribeResponse::Ok(_))) => {} + Recv::Message(lite::SubscribeResponse::Ok(_)) => {} // A second START or FINISH, or a STARTED for a range no update added. - Ok(Some(msg)) => { + Recv::Message(msg) => { tracing::warn!(?msg, "unexpected recovery subscribe response"); return Poll::Ready(Err(Error::ProtocolViolation)); } // The publisher FINs in reply to ours, or once it finished the track. - Ok(None) if *finished || active.end.is_some() => self.end(StreamError::NotFound), + Recv::Ended if *finished || active.end.is_some() => self.end(StreamError::NotFound), - Ok(None) => { + Recv::Ended => { tracing::warn!("recovery subscribe ended without SUBSCRIBE_FINISH"); return Poll::Ready(Err(Error::ProtocolViolation)); } - Err(err) => { - // Malformed bytes are a violation, as on the subscription itself; a - // reset gives up what is left with its reason. - let err = match err { - Error::Decode(crate::DecodeError::Short) => err, - err => crate::auth::protocol_error(err), - }; - if matches!(err, Error::ProtocolViolation) { - return Poll::Ready(Err(err)); - } + // Malformed bytes are a violation, as on the subscription itself. + Recv::Malformed(err) => { + tracing::warn!(%err, "malformed recovery subscribe response"); + return Poll::Ready(Err(Error::ProtocolViolation)); + } + // A reset, or a FIN inside a message, gives up what is left with its reason. + Recv::Reset(err) => { tracing::debug!(%err, "recovery subscribe ended"); self.end(StreamError::from(&err)); } diff --git a/rs/moq-net/src/lite/version.rs b/rs/moq-net/src/lite/version.rs index ed399c5e5ff..8471de9d1b8 100644 --- a/rs/moq-net/src/lite/version.rs +++ b/rs/moq-net/src/lite/version.rs @@ -61,28 +61,28 @@ impl Version { /// /// This is the common feature boundary for TRACK_INFO, FETCH streams, /// SUBSCRIBE_START/END, and per-frame timestamp prefixes. - pub fn has_track_stream(self) -> bool { + pub(crate) fn has_track_stream(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04) } /// Whether the PROBE message carries the RTT field. Added in lite-04; lite-03 /// carries the bitrate alone, so a report with only an RTT to give says nothing /// there and must not be sent. - pub fn has_probe_rtt(self) -> bool { + pub(crate) fn has_probe_rtt(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03) } /// Whether the session opens a unidirectional Setup Stream carrying a single SETUP /// message (capabilities + optional Path). Added in lite-05; the older bidirectional /// setup exchange (Lite01/02) and the no-setup drafts (Lite03/04) don't use it. - pub fn has_setup_stream(self) -> bool { + pub(crate) fn has_setup_stream(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04) } /// Whether the session may carry unreliable QUIC datagrams (lite-05 §6.4): single-frame /// groups on lite-05/06, a datagram track's datagrams on lite-07, which adds a leading /// type and padding. Older than lite-05 never sends or accepts datagrams. - pub fn has_datagrams(self) -> bool { + pub(crate) fn has_datagrams(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04) } @@ -98,19 +98,19 @@ impl Version { /// Whether announce streams begin with ANNOUNCE_OK and omit the sender's origin /// from each announcement's hop chain. Added in lite-05. - pub fn has_announce_ok(self) -> bool { + pub(crate) fn has_announce_ok(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04) } /// Whether the session supports the GOAWAY control stream (0x5) for graceful /// shutdown and migration. Added in lite-04. - pub fn has_goaway(self) -> bool { + pub(crate) fn has_goaway(self) -> bool { !matches!(self, Self::Lite01 | Self::Lite02 | Self::Lite03) } /// Whether either endpoint may open an Auth Stream (0x7) to present a token and /// learn its grant. Added in lite-07. - pub fn has_auth(self) -> bool { + pub(crate) fn has_auth(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -127,7 +127,7 @@ impl Version { /// Whether a subscriber may open a Tracks Stream (0x8) to list a broadcast's /// tracks. Added in lite-07. - pub fn has_tracks(self) -> bool { + pub(crate) fn has_tracks(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -137,7 +137,7 @@ impl Version { /// Whether announcements carry implicit announce ids: each `active` /// ANNOUNCE_BROADCAST assigns the next per-stream ordinal, and `ended`/`restart` /// reference that id instead of repeating the path. Added in lite-06. - pub fn has_announce_id(self) -> bool { + pub(crate) fn has_announce_id(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 @@ -156,7 +156,7 @@ impl Version { /// /// Unlike the gates above, this lists the versions that *have* the field: it was /// removed rather than added, so future versions default to not carrying it. - pub fn has_exclude_hop(self) -> bool { + pub(crate) fn has_exclude_hop(self) -> bool { matches!(self, Self::Lite04 | Self::Lite05) } @@ -166,7 +166,7 @@ impl Version { /// /// Older versions only address whole groups, so a route change has to wait for the /// next group before it can resume. - pub fn has_frame_bounds(self) -> bool { + pub(crate) fn has_frame_bounds(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 @@ -261,7 +261,7 @@ impl Version { /// Whether ANNOUNCE_REQUEST carries the hidden opt-in. Added in lite-07; older /// requests decode as not opted in. - pub fn has_hidden(self) -> bool { + pub(crate) fn has_hidden(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -270,7 +270,7 @@ impl Version { /// Whether ANNOUNCE_START may copy a path head from a live /// announcement on the same stream. Added in lite-07. - pub fn has_announce_compression(self) -> bool { + pub(crate) fn has_announce_compression(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -350,7 +350,7 @@ impl Version { /// Whether announcements carry their instance and epoch, and track requests the /// instance they pin. Added in lite-07. Older versions carry nothing, so the /// receiving session mints an instance for each announcement. - pub fn has_instance(self) -> bool { + pub(crate) fn has_instance(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -378,7 +378,7 @@ impl Version { /// Whether the announce stream has ANNOUNCE_RESTART: another publisher instance /// replacing an advertisement in place. Added in lite-07. Older versions send an /// ANNOUNCE_END then an ANNOUNCE_START. - pub fn has_announce_restart(self) -> bool { + pub(crate) fn has_announce_restart(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -418,7 +418,7 @@ impl Version { } /// Whether discovery streams end their initial set with SYNCED rather than a count. - pub fn has_synced(self) -> bool { + pub(crate) fn has_synced(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 | Self::Lite06 @@ -429,7 +429,7 @@ impl Version { /// the broadcast via this route, accumulated per link. Added in lite-06. /// Older versions carry nothing, so a received route stays at zero and ranks /// on hop count alone, exactly as before. - pub fn has_route_cost(self) -> bool { + pub(crate) fn has_route_cost(self) -> bool { !matches!( self, Self::Lite01 | Self::Lite02 | Self::Lite03 | Self::Lite04 | Self::Lite05 diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 984a08420bf..998f9986864 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -602,40 +602,6 @@ impl Position { Self { group, frame: 0 } } - /// The position just past `frame` of `group`: the exclusive end that includes it. - /// - /// `None` when there is no such position, i.e. the very last frame of the very last - /// group. That is past everything, which an open [`Range::end`] spells `None` too, so - /// the two meanings line up. - pub fn after(group: u64, frame: u64) -> Option { - match frame.checked_add(1) { - Some(frame) => Some(Self { group, frame }), - // Past the last frame of a group is the head of the next one. - None => Self::after_group(group), - } - } - - /// The position just past every frame of `group`: the exclusive end that includes - /// the group whole. - /// - /// `None` past the last group, for the reason given on [`Self::after`]. - pub fn after_group(group: u64) -> Option { - Some(Self::group(group.checked_add(1)?)) - } - - /// The bound this exclusive end puts on a group cursor, for - /// [`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. - pub fn group_end(self) -> Bound { - if self.frame == 0 { - Bound::Excluded(self.group) - } else { - Bound::Included(self.group) - } - } - /// 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(crate) fn final_key(self) -> Option { @@ -741,21 +707,7 @@ mod tests { } #[test] - fn positions_are_total_at_the_extremes() { - // Past the last frame of a group is the head of the next one, not a wider frame - // in the same group. - assert_eq!(Position::after(5, u64::MAX), Some(Position::group(6))); - - // Past everything has no position. An open range spells that `None` too, so the - // meanings coincide and the group is included rather than dropped. - assert_eq!(Position::after_group(u64::MAX), None); - assert_eq!(Position::after(u64::MAX, u64::MAX), None); - - // A head-of-group end excludes that group; a mid-group end includes it. - assert_eq!(Position::group(0).group_end(), Bound::Excluded(0)); - assert_eq!(Position::after_group(5).unwrap().group_end(), Bound::Excluded(6)); - assert_eq!(Position::after(5, 2).unwrap().group_end(), Bound::Included(5)); - + fn cursor_bounds_are_total_at_the_extremes() { // A cursor cap is the first index it withholds; an inclusive bound at the last // index withholds nothing. assert_eq!(key_bounds(..0), (0, Some(0))); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index eeda631ad97..cfc6d3cab5e 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -10764,7 +10764,7 @@ impl Ordered { /// The next group with a higher key than any previously returned. /// - /// Honors the group range set by [`Self::with_range`]: + /// Honors the group range set by [`Subscriber::with_range`] before [`Subscriber::ordered`]: /// a group past the cap stays in the producer's cache and becomes eligible again if /// the cap rises or is removed. Ranges that all end end the read once they are /// accounted for, as for [`Subscriber::poll_recv_group`]. @@ -10779,16 +10779,18 @@ impl Ordered { self.inner.poll_next_group(waiter) } - /// Limit subsequent reads to these group keys, returning `self` for chaining. - /// - /// 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 { + /// Narrow subsequent reads to these group keys, as [`Subscriber::with_range`] does: a + /// read in key order never goes back, so lowering the floor below a group it already + /// returned offers nothing. + #[cfg(test)] + #[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))] + pub(crate) fn with_range(mut self, groups: impl RangeBounds) -> Self { self.set_range(groups); self } /// [`Self::with_range`] on a reader held in place. + #[cfg(test)] fn set_range(&mut self, groups: impl RangeBounds) { self.inner.set_range(groups); } @@ -10820,7 +10822,7 @@ impl Ordered { self.inner.poll_finished(waiter) } - /// The largest location within [`Self::with_range`]; see [`Subscriber::poll_largest`]. + /// The largest location within [`Subscriber::with_range`]; see [`Subscriber::poll_largest`]. #[cfg_attr(feature = "async", kio::wrapper)] pub fn poll_largest(&mut self, waiter: &kio::Waiter) -> Poll> { self.inner.poll_largest(waiter) @@ -19144,7 +19146,7 @@ mod test { let producer = track_producer("test", Info::timed()); let mut everything = producer.subscribe(replay()); let mut empty = producer.subscribe(replay().with_order(Order::Ascending)); - empty.set_range((Bound::Unbounded, Position::group(0).group_end())); + empty.set_range((Bound::Unbounded, Bound::Excluded(0))); for s in 0..3 { producer @@ -19178,8 +19180,8 @@ mod test { fn end_at_frame_limited_last_group() { let producer = track_producer("test", Info::timed()); let mut consumer = producer.subscribe(replay()).ordered(); - let end = Position::after(1, 1).unwrap(); - consumer.set_range((Bound::Unbounded, end.group_end())); + let end = Position::new(1, 2); + consumer.set_range((Bound::Unbounded, Bound::Included(end.group))); for s in 0..3u64 { let mut group = producer.create_group(group::Info { start: s }).unwrap();