Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion quest/m2/audio-playout/browser-audio-hole-skip.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,4 @@ Work:
## Related

- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - settles the wait rule this moves into the transport
- [moq-net publishes no item without a caller](/quest/m2/unused-api/net.md) - the Rust container reader moving onto `Gap`, this quest's native counterpart
- [moq-net's last pub items with a single container-reader caller go private](/quest/m2/unused-api/net.md) - the Rust container reader moving onto `Gap`, this quest's native counterpart
1 change: 0 additions & 1 deletion quest/m2/net-renames.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
4 changes: 0 additions & 4 deletions quest/m2/sockets/remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,3 @@ Public API: breaking for `main`-only API in every language; nothing on
## Required

- [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
91 changes: 21 additions & 70 deletions quest/m2/unused-api/net.md
Original file line number Diff line number Diff line change
@@ -1,82 +1,33 @@
# [S] moq-net publishes no item without a caller
# [S] moq-net's last pub items with a single container-reader caller go private

## 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.
`track::Subscriber::next_in_range`, `is_skipped`, and `poll_start` are
crate-private, and so is `Subscriber::with_range` if its last production
caller can leave. Their one consumer is moq-mux's container reader, which
orders groups itself; `track::Ordered` reports a `Gap`, so the reader can
move onto it.

## 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.
What is left of the moq-net sweep, which removed or hid every other item
without a caller.

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.
- `next_in_range`, `is_skipped`, and `poll_start` go crate-private in the
same PR that moves the container reader onto `Ordered`'s `Gap`.
- `Subscriber::with_range` stays `pub` for now: its last production caller is
`rs/moq-mux/src/container/source.rs`'s resubscription, which resumes from
the group after the one it already read. A time start names the group
containing it, so a `Subscription` range cannot leave that group out. If
the reader can skip it through `Gap` or its own cursor, make `with_range`
crate-private and move the callers in moq-mux and moq-json tests to
`Subscription::ranges`; otherwise it stays, and this quest records why.
- `origin::Consumer::covering` stays `pub`: moq.pro and moq-net's own
`benches/origin.rs` call it.

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.
`track::Ordered` now reports a `Gap`; 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).

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.
Public API: breaking, removals only. Wire: none.

## Related

- [Browser audio holes](/quest/m2/audio-playout/browser-audio-hole-skip.md) - the browser counterpart of the reader moving onto `Gap`
- [moq-net's node, version, handshake, and route priority](/quest/m2/net-renames.md) - makes `Version` opaque
42 changes: 42 additions & 0 deletions quest/m3/control-stream-recv.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# [M] Every control stream reads a typed Recv outcome

## Goal

The announce, probe, tracks, auth, and publisher control-stream readers in
moq-lite tell a reset, a clean end, and malformed bytes apart through
`coding::Reader::poll_recv`'s `Recv`, the way the subscriber's response reads
already do. `lite::error::control` and `auth::protocol_error`, which
classify an `Error` by matching its variants, are deleted (AGENTS.md: never
match on errors).

## Plan

The first `Recv` readers landed with
[moq-dev/moq#8931](https://github.com/moq-dev/moq/pull/8931): `Recovery`, the
live subscription's response read, and the drain after FINISH. Those three
reads in `rs/moq-net/src/lite/subscriber.rs` and `subscriber/fills.rs` are
the pattern: the reader classifies where it knows (a transport reset or a FIN
inside a message is `Reset`, a decode failure is `Malformed`), and the caller
branches on the outcome.

Callers left, from `rg 'error::control|protocol_error' rs/moq-net/src`:

- `lite::error::control`: the publisher's control stream
(`lite/publisher.rs`), the subscriber's other control reads
(`lite/subscriber.rs`, `subscriber/route_stream.rs`).
- `auth::protocol_error`: the auth token presenter (`lite/session.rs`), the
publisher's auth serve (`lite/publisher.rs`), and `lite::error::control`
itself.

Each reader returns the outcome typed, and the session close on a malformed
message (`SessionError::ProtocolViolation`) moves to where `Malformed` is
read. Check the IETF side (`ietf/session.rs` `control_stream_error`) for the
same pattern and leave it out only if it cannot share the reader.

Public API: none. Wire: none. Cover each reader with a test of the three
outcomes, as `a_read_tells_a_cut_stream_from_malformed_bytes` does for the
reader.

## Related

- [moq-net's last pub items with a single container-reader caller go private](/quest/m2/unused-api/net.md) - the rest of the moq-net sweep
108 changes: 104 additions & 4 deletions rs/moq-net/src/coding/reader.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,34 @@ pub struct Reader<S: RecvStream, V> {
/// 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<T> {
/// 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<Fault> 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 {
Expand Down Expand Up @@ -142,16 +170,30 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
&mut self,
waiter: &kio::Waiter,
consume: bool,
mut decode: impl FnMut(&mut Decoder<'_>) -> Result<T, DecodeError>,
decode: impl FnMut(&mut Decoder<'_>) -> Result<T, DecodeError>,
) -> Poll<Result<(T, usize), Error>>
where
V: Into<Form> + 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<T>(
&mut self,
waiter: &kio::Waiter,
consume: bool,
mut decode: impl FnMut(&mut Decoder<'_>) -> Result<T, DecodeError>,
) -> Poll<Result<(T, usize), Fault>>
where
V: Into<Form> + Copy,
{
let form = self.version.into();
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.
Expand Down Expand Up @@ -196,7 +238,7 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
// 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() {
Expand All @@ -205,7 +247,7 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
}
// 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
Expand Down Expand Up @@ -298,6 +340,24 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
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<T: for<'a> Decode<'a, V> + Debug>(&mut self, waiter: &kio::Waiter) -> Poll<Recv<T>>
where
V: Into<Form> + 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<T: for<'a> Decode<'a, V> + Debug>(
Expand Down Expand Up @@ -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::<lite::Probe>(waiter),
Poll::Ready(Recv::Message(_))
));
assert!(matches!(
reader.poll_recv::<lite::Probe>(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::<lite::Probe>(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::<lite::Probe>(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.
Expand Down
Loading