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
7 changes: 3 additions & 4 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,9 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut):
publishes for the first time at this cut;
auth key validation; the
RTMPS connect signature;
usage's derived settings; and three
API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md),
the capture selections, and
[the acknowledgment hook's trait](/quest/m2/api-ack-hook-trait.md). None
usage's derived settings; and two
API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md) and
the capture selections. None
is on the routes chain, which stays the critical path.
- ✅ Under the path rule a route keeps one sticky down-only flag beside its
path; see the [routes epic](/quest/m2/cluster-routes/README.md).
Expand Down
31 changes: 0 additions & 31 deletions quest/m2/api-ack-hook-trait.md

This file was deleted.

56 changes: 56 additions & 0 deletions quest/m2/api-ack-one-primitive.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# [M] The send-stream trait reports acknowledgment one way

## Goal

`moq_net::transport::poll::SendStream` carries one acknowledgment primitive
when the cut freezes it: `Offset`, `offset()` and `poll_acked`. The trait is
public and unsealed, so each method that ships becomes one every out-of-tree
transport implements for good.

- `acknowledged()` and `OpenStream::acknowledged` are gone. The debug log in
`rs/moq-net/src/transport/open.rs` that counts acknowledged open streams
asks `poll_acked` at each stream's current offset instead.
- `delivered()` and `poll_delivered()` are gone. Egress stats
(`stats::Delivery`, driven from `coding::writer`) bill a frame's bytes once
`poll_acked` reports an offset past them as delivered. When it reports
`Unsupported`, they bill the bytes the stream accepted from the writer, as the
writer's fallback does today. They stop billing once it errors.
- Egress over QUIC stays acknowledgment-based: moq-tokio's and moq-uring's
`quic::web` adapters implement `poll_acked` over their drivers before the
stats move, or QUIC egress silently falls back to bytes taken.

## Plan

Found by the pre-cut feature review
([moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)) against
[moq-dev/moq#8739](https://github.com/moq-dev/moq/pull/8739), which added
`offset`/`poll_acked` beside the two older shapes. Decided 2026-11-15
(maintainer): land #8739 as it is and collapse the shapes here, keeping
`offset`/`poll_acked`.

Decided 2026-11-15 (maintainer): qmux keeps reporting `Acked::Unsupported`
(writing into TCP is not delivery, as decided 2026-10-22 in
[quic-ack-hook](/quest/m3/quic-ack-hook.md)), so qmux egress falls back to the
bytes taken. That is the count the stream accepted from the writer, not what
qmux's `delivered()` reports today (what the link took). The two differ only
while the link is blocked and holds accepted bytes. Rejected: giving the hook
qmux's "the link took it" meaning.

Guidance:

- `Delivery` can keep one outstanding offset per stream rather than one per
frame: mint `offset()` at the bytes written when a frame waits, bill
through it once delivered, then mint the next. That bounds memory per
stream. The cost is that a reset can leave unbilled the bytes acknowledged
past the last offset asked about. Measure that against per-frame offsets
before picking.
- moq-quic's `send::Stream::poll_acked` is already public and handles the
reset and STOP_SENDING cases. The adapters forward the driver's offset,
which counts the WebTransport header, so no adjustment is needed. A web
stream that was reset no longer has a driver handle, so it keeps the offset
and the acknowledged prefix it had at the reset.
- The memory transport stands in for acknowledgment with the bytes its reader
took, and moq-net's tests bill against it, so it gets a real `u64` offset.
- This takes part of [quic-ack-hook](/quest/m3/quic-ack-hook.md)'s driver
half (the adapters' `poll_acked`). Update that quest to keep only the public
driver API and its trap tests.
23 changes: 13 additions & 10 deletions quest/m3/quic-ack-hook.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ layers. Add an offset type and two methods to `SendStream`, in the trait's
poll style:

```rust
type Offset: Copy;
type Offset: 'static;
fn offset(&self) -> Self::Offset;
fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll<Result<Acked, Self::Error>>;
fn poll_acked(&self, waiter: &kio::Waiter, offset: &Self::Offset) -> Poll<Result<Acked, Self::Error>>;

#[non_exhaustive]
pub enum Acked { Delivered, Unsupported }
Expand Down Expand Up @@ -82,7 +82,7 @@ lives:
counting the bytes it writes. A layer that writes its own prefix mints
offsets that already include it, so `quic::web` forwards the driver's
`Offset` and its WebTransport header needs no adjustment. A backend that
cannot see acknowledgments mints a `u64` byte count and keeps the default
cannot see acknowledgments uses `type Offset = ()` and keeps the default
`poll_acked`.

The moq-tokio and moq-uring adapters implement the trait method over the
Expand Down Expand Up @@ -113,12 +113,15 @@ Decided in the 2026-09-30 audit: moved to m2 with its consumers, the
delivery-delay histogram, whose plan was deleted on 2026-11-09.

Split 2026-11-12 (maintainer, /quest-audit before the cut): the trait shape
(`Offset`, `offset()`, and a defaulted `poll_acked`) lands in m2 as
[its own quest](/quest/m2/api-ack-hook-trait.md), because
`poll::SendStream` is public and unsealed and the cut would freeze it. This
(`Offset`, `offset()`, `Acked`, and a defaulted `poll_acked`) landed in m2,
because `poll::SendStream` is public and unsealed and the cut would freeze it.
As landed, `Offset` has no `Clone` or `Copy` bound and `poll_acked` takes it
by reference, since a caller retries the poll with the same offset anyway and
moq-net's boxed stream erases it behind a `Box<dyn Any>` it only borrows from
(decided 2026-11-14, maintainer); a backend without acknowledgments uses
`type Offset = ()` rather than a byte count. Every in-tree backend, including
moq-tokio's and moq-uring's `quic::web`, is on `()` with the default. This
quest keeps the driver half: moq-quic's `poll_acked` leaves `#[cfg(test)]`,
and the moq-tokio and moq-uring adapters implement the hook.
and the moq-tokio and moq-uring adapters switch `Offset` to the driver's
`send::Offset` (which is `Copy`, so they pass `*offset`) and implement the hook.

## Required

- [The send-stream trait has its acknowledgment hook](/quest/m2/api-ack-hook-trait.md) - the trait methods the drivers implement
3 changes: 3 additions & 0 deletions rs/moq-net/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -932,6 +932,9 @@ mod tests {
impl crate::transport::poll::SendStream for FakeSendStream {
type Error = FakeError;
type Group = crate::transport::poll::Ungrouped;
type Offset = ();

fn offset(&self) -> Self::Offset {}

fn poll_write(&mut self, _waiter: &kio::Waiter, buf: &[u8]) -> Poll<Result<usize, Self::Error>> {
self.writes.lock().unwrap().put_slice(buf);
Expand Down
6 changes: 6 additions & 0 deletions rs/moq-net/src/coding/writer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,9 @@ mod tests {
impl crate::transport::poll::SendStream for Stopped {
type Error = Self;
type Group = crate::transport::poll::Ungrouped;
type Offset = ();

fn offset(&self) -> Self::Offset {}

fn poll_write(&mut self, _: &kio::Waiter, _: &[u8]) -> Poll<Result<usize, Self::Error>> {
Poll::Ready(Err(self.clone()))
Expand Down Expand Up @@ -575,6 +578,9 @@ mod tests {
impl crate::transport::poll::SendStream for Acked {
type Error = Stopped;
type Group = crate::transport::poll::Ungrouped;
type Offset = ();

fn offset(&self) -> Self::Offset {}

fn poll_write(&mut self, _: &kio::Waiter, buf: &[u8]) -> Poll<Result<usize, Self::Error>> {
Poll::Ready(Ok(buf.len()))
Expand Down
3 changes: 3 additions & 0 deletions rs/moq-net/src/fuzz/session.rs
Original file line number Diff line number Diff line change
Expand Up @@ -977,6 +977,9 @@ impl Recorder {
impl poll::SendStream for Recorded<memory::SendStream> {
type Error = memory::Error;
type Group = poll::Ungrouped;
type Offset = ();

fn offset(&self) -> Self::Offset {}

fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll<Result<usize, Self::Error>> {
let written = std::task::ready!(self.inner.poll_write(waiter, buf))?;
Expand Down
13 changes: 13 additions & 0 deletions rs/moq-net/src/ietf/publisher.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7330,6 +7330,19 @@ impl<T: crate::transport::poll::SendStream> RankedInner<T> {
impl<T: crate::transport::poll::SendStream> crate::transport::poll::SendStream for Ranked<T> {
type Error = T::Error;
type Group = T::Group;
type Offset = T::Offset;

fn offset(&self) -> Self::Offset {
self.inner.lock().unwrap().stream.offset()
}

fn poll_acked(
&self,
waiter: &kio::Waiter,
offset: &Self::Offset,
) -> Poll<Result<crate::transport::poll::Acked, Self::Error>> {
self.inner.lock().unwrap().stream.poll_acked(waiter, offset)
}

fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll<Result<usize, Self::Error>> {
let inner = self.get_mut();
Expand Down
3 changes: 3 additions & 0 deletions rs/moq-net/src/lite/test_transport.rs
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,9 @@ impl SinkSend {
impl poll::SendStream for SinkSend {
type Error = SinkError;
type Group = SinkGroup;
type Offset = ();

fn offset(&self) -> Self::Offset {}

fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll<Result<usize, Self::Error>> {
if self.log.writes_fail.load(Ordering::Relaxed) {
Expand Down
3 changes: 3 additions & 0 deletions rs/moq-net/src/server.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1662,6 +1662,9 @@ mod tests {
impl crate::transport::poll::SendStream for FakeSend {
type Error = FakeError;
type Group = crate::transport::poll::Ungrouped;
type Offset = ();

fn offset(&self) -> Self::Offset {}
fn poll_write(&mut self, _waiter: &kio::Waiter, buf: &[u8]) -> std::task::Poll<Result<usize, Self::Error>> {
match self.withheld {
true => std::task::Poll::Pending,
Expand Down
38 changes: 36 additions & 2 deletions rs/moq-net/src/transport.rs
Original file line number Diff line number Diff line change
Expand Up @@ -631,12 +631,18 @@ pub mod poll {
/// Boxing is what compiles the session code once per binary rather than once per
/// transport.
pub trait Boxable:
Session<SendStream: Send + Sync + SendStream<Group: Send + Sync>, RecvStream: Send + Sync> + Send + Sync
Session<SendStream: Send + Sync + SendStream<Group: Send + Sync, Offset: Send + Sync>, RecvStream: Send + Sync>
+ Send
+ Sync
{
}

impl<S> Boxable for S where
S: Session<SendStream: Send + Sync + SendStream<Group: Send + Sync>, RecvStream: Send + Sync> + Send + Sync
S: Session<
SendStream: Send + Sync + SendStream<Group: Send + Sync, Offset: Send + Sync>,
RecvStream: Send + Sync,
> + Send
+ Sync
{
}

Expand Down Expand Up @@ -691,6 +697,16 @@ pub mod poll {
}
}

/// What [`SendStream::poll_acked`] learned about the bytes below an offset.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Acked {
/// The peer acknowledged every byte below the offset.
Delivered,
/// The transport cannot see acknowledgments, so delivery is unknown, never assumed.
Unsupported,
}

/// An outgoing stream with partial writes, priorities, and reset codes.
pub trait SendStream: 'static {
/// The error type for every operation on this stream.
Expand All @@ -699,6 +715,24 @@ pub mod poll {
/// The transport's send group, [`Ungrouped`] for a transport without them.
type Group: SendGroup;

/// A position in the stream, minted only by [`offset`](Self::offset), for
/// [`poll_acked`](Self::poll_acked). `()` for a transport that cannot see acknowledgments.
type Offset: 'static;

/// The position just past every byte written so far.
fn offset(&self) -> Self::Offset;

/// Poll until the peer acknowledged every byte below `offset`.
///
/// Errors once those bytes can never be acknowledged: the stream was reset by either
/// side or the session closed. A transport that cannot see acknowledgments is ready
/// with [`Acked::Unsupported`] immediately, the default, on every stream, so a caller
/// can decide once per session. An offset minted by another stream may panic.
fn poll_acked(&self, waiter: &kio::Waiter, offset: &Self::Offset) -> Poll<Result<Acked, Self::Error>> {
let _ = (waiter, offset);
Poll::Ready(Ok(Acked::Unsupported))
}

/// Poll to write some of the buffer to the stream, returning how many bytes were
/// written. See [`poll_write_buf`](Self::poll_write_buf) for the partial-write
/// contract, which this shares.
Expand Down
Loading