From 4e0896516a85f0bb7d45f8f7e79ec4c2d33c8d51 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 05:15:29 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m2/api-ack-hook-trait.md Quest-Claim: 4289671bb3de1a05 From 7cf50731a030abfa870c2679fd307d34053c5b15 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 06:02:05 -0800 Subject: [PATCH 2/6] feat(moq-net)!: poll::SendStream gets the acknowledgment hook's shape Adds the Offset associated type, offset(), and poll_acked with a default that reports Acked::Unsupported, so the m3 drivers can implement the hook without breaking the trait after the cut. Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 7 +- quest/m2/api-ack-hook-trait.md | 31 ------ quest/m3/quic-ack-hook.md | 19 ++-- rs/moq-net/src/client.rs | 3 + rs/moq-net/src/coding/writer.rs | 6 + rs/moq-net/src/fuzz/session.rs | 3 + rs/moq-net/src/ietf/publisher.rs | 13 +++ rs/moq-net/src/lite/test_transport.rs | 3 + rs/moq-net/src/server.rs | 3 + rs/moq-net/src/transport.rs | 38 ++++++- rs/moq-net/src/transport/boxed.rs | 111 ++++++++++++++++++- rs/moq-net/src/transport/memory.rs | 3 + rs/moq-net/tests/integration/support/mock.rs | 3 + rs/moq-tokio/src/quic/web/send.rs | 3 + rs/moq-tokio/src/server.rs | 3 + rs/moq-uring/src/quic/web/send.rs | 3 + rs/moq-uring/src/transport/local.rs | 9 ++ rs/qmux/src/session.rs | 3 + 18 files changed, 215 insertions(+), 49 deletions(-) delete mode 100644 quest/m2/api-ack-hook-trait.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 86bb7a1ffb7..23d0009749d 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -44,10 +44,9 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): [auth key validation](/quest/m2/auth-key-validation.md); the [RTMPS connect](/quest/m2/rtmp-rtmps-tcurl.md) signature; [usage's derived settings](/quest/m2/usage-derive-settings.md); - [first-publish versions](/quest/m2/first-publish-versions.md); and three - API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md), - [the capture selections](/quest/m2/api-capture-fences.md), and - [the acknowledgment hook's trait](/quest/m2/api-ack-hook-trait.md). None + [first-publish versions](/quest/m2/first-publish-versions.md); and two + API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md) and + [the capture selections](/quest/m2/api-capture-fences.md). 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). diff --git a/quest/m2/api-ack-hook-trait.md b/quest/m2/api-ack-hook-trait.md deleted file mode 100644 index 7d0c05b63f9..00000000000 --- a/quest/m2/api-ack-hook-trait.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] The send-stream trait has its acknowledgment hook - -## Goal - -`moq_net::transport::poll::SendStream` gains the shape the acknowledgment -hook needs: an associated `Offset` type, `offset()`, and `poll_acked` with a -default that reports the hook as unsupported. Every transport in the tree -compiles against it, and none has to implement the hook yet. The trait is -public and unsealed, so adding these after the cut would break every -implementer. - -## Plan - -Decided 2026-11-12 (maintainer, /quest-audit before the cut): ✅ land the -trait shape in m2 and leave the drivers to the -[acknowledgment hook](/quest/m3/quic-ack-hook.md) (rejected: an extension -trait after the cut, which puts a new bound on moq-net's generic session -code and is itself a break; accepting another moq-net break later). - -- Take the shape from the hook quest's Plan; the tokio driver already has an - `Offset` (`rs/moq-tokio/src/quic/driver/send.rs`, from - [moq-dev/moq#6950](https://github.com/moq-dev/moq/pull/6950)), and - moq-quic's `poll_acked` exists behind `#[cfg(test)]`. -- "Unsupported" is a typed answer a caller can branch on at setup, not an - error it must match at runtime: a session decides once whether its - transport reports acknowledgments. -- JS has no counterpart: WebTransport exposes no acknowledgment, so `js/net` - is unchanged; say so in the PR. - -Public API: breaking for transports implementing `poll::SendStream` outside -the tree only if a method lacks a default; aim for none. Wire: none. diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index 6348c6116af..1b23215835a 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -25,7 +25,7 @@ layers. Add an offset type and two methods to `SendStream`, in the trait's poll style: ```rust -type Offset: Copy; +type Offset: Clone; fn offset(&self) -> Self::Offset; fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll>; @@ -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 @@ -113,12 +113,13 @@ 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` is `Clone` rather than `Copy`, since moq-net's boxed +stream erases it behind an `Arc`, and 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` 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 diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 1d3277e2c3b..43e87ec89f5 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -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> { self.writes.lock().unwrap().put_slice(buf); diff --git a/rs/moq-net/src/coding/writer.rs b/rs/moq-net/src/coding/writer.rs index 86f19607783..581cc14d4f1 100644 --- a/rs/moq-net/src/coding/writer.rs +++ b/rs/moq-net/src/coding/writer.rs @@ -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> { Poll::Ready(Err(self.clone())) @@ -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> { Poll::Ready(Ok(buf.len())) diff --git a/rs/moq-net/src/fuzz/session.rs b/rs/moq-net/src/fuzz/session.rs index a9efec37dae..d4670925c0e 100644 --- a/rs/moq-net/src/fuzz/session.rs +++ b/rs/moq-net/src/fuzz/session.rs @@ -977,6 +977,9 @@ impl Recorder { impl poll::SendStream for Recorded { 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> { let written = std::task::ready!(self.inner.poll_write(waiter, buf))?; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 57f5221c68e..ec4aa4986fe 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -7330,6 +7330,19 @@ impl RankedInner { impl crate::transport::poll::SendStream for Ranked { 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> { + self.inner.lock().unwrap().stream.poll_acked(waiter, offset) + } fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { let inner = self.get_mut(); diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index d0b6ab5a8a7..1f08ac1dc54 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -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> { if self.log.writes_fail.load(Ordering::Relaxed) { diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index aa817efae8f..715507d5cd9 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -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> { match self.withheld { true => std::task::Poll::Pending, diff --git a/rs/moq-net/src/transport.rs b/rs/moq-net/src/transport.rs index aed519661f0..3dead25d02b 100644 --- a/rs/moq-net/src/transport.rs +++ b/rs/moq-net/src/transport.rs @@ -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, RecvStream: Send + Sync> + Send + Sync + Session, RecvStream: Send + Sync> + + Send + + Sync { } impl Boxable for S where - S: Session, RecvStream: Send + Sync> + Send + Sync + S: Session< + SendStream: Send + Sync + SendStream, + RecvStream: Send + Sync, + > + Send + + Sync { } @@ -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. @@ -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: Clone + '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> { + 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. diff --git a/rs/moq-net/src/transport/boxed.rs b/rs/moq-net/src/transport/boxed.rs index 110d0df768f..ea8806a53d5 100644 --- a/rs/moq-net/src/transport/boxed.rs +++ b/rs/moq-net/src/transport/boxed.rs @@ -258,6 +258,10 @@ impl poll::SendGroup for Group { } } +/// A boxed stream's offset, holding the transport's own behind the boundary. +#[derive(Clone)] +pub(crate) struct Offset(Arc); + /// A boxed outgoing stream. pub(crate) struct SendStream(Sender); @@ -270,11 +274,11 @@ enum Sender { impl SendStream { /// Box a stream, keeping its own send-group type behind the boundary. #[cfg(test)] - pub(crate) fn new(stream: impl poll::SendStream + Send + Sync) -> Self { + pub(crate) fn new(stream: impl poll::SendStream + Send + Sync) -> Self { Self(Sender::Own(Box::new(stream))) } - fn own(stream: impl poll::SendStream + Send + Sync + 'static) -> Self { + fn own(stream: impl poll::SendStream + Send + Sync + 'static) -> Self { Self(Sender::Own(Box::new(stream))) } @@ -603,6 +607,8 @@ trait ErasedSend: Send + Sync { fn acknowledged(&self) -> Option; fn delivered(&self) -> Option; fn poll_delivered(&self, waiter: &kio::Waiter) -> Poll<()>; + fn offset(&self) -> Offset; + fn poll_acked(&self, waiter: &kio::Waiter, offset: &Offset) -> Poll>; } trait ErasedRecv: Send + Sync { @@ -745,7 +751,7 @@ impl ErasedGroup for G { } } -impl + Send + Sync> ErasedSend for T { +impl + Send + Sync> ErasedSend for T { fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { poll::SendStream::poll_write(self, waiter, buf).map_err(Error::new) } @@ -791,6 +797,19 @@ impl + Send + Sync> ErasedSend for T { fn poll_delivered(&self, waiter: &kio::Waiter) -> Poll<()> { poll::SendStream::poll_delivered(self, waiter) } + + fn offset(&self) -> Offset { + Offset(Arc::new(poll::SendStream::offset(self))) + } + + fn poll_acked(&self, waiter: &kio::Waiter, offset: &Offset) -> Poll> { + let offset = offset + .0 + .downcast_ref::() + .expect("offset belongs to another transport") + .clone(); + poll::SendStream::poll_acked(self, waiter, offset).map_err(Error::new) + } } impl ErasedRecv for Budgeted { @@ -947,6 +966,15 @@ impl poll::Session for Session { impl poll::SendStream for SendStream { type Error = Error; type Group = Group; + type Offset = Offset; + + fn offset(&self) -> Offset { + self.get().offset() + } + + fn poll_acked(&self, waiter: &kio::Waiter, offset: Offset) -> Poll> { + self.get().poll_acked(waiter, &offset) + } fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { self.poll_writing(waiter, |stream| stream.poll_write(waiter, buf)) @@ -1179,6 +1207,83 @@ mod test { /// A listed stream reports the peer acknowledging what was written to it, and a reset one /// never is. + /// A stream that counts written bytes as its offset and reports them acknowledged up to + /// a mark, to check the boxed layer carries its offset through and back. + struct Acking { + written: u64, + acked: u64, + } + + impl poll::SendStream for Acking { + type Error = super::super::memory::Error; + type Group = poll::Ungrouped; + type Offset = u64; + + fn offset(&self) -> u64 { + self.written + } + + fn poll_acked(&self, _: &kio::Waiter, offset: u64) -> Poll> { + match offset <= self.acked { + true => Poll::Ready(Ok(poll::Acked::Delivered)), + false => Poll::Pending, + } + } + + fn poll_write(&mut self, _: &kio::Waiter, buf: &[u8]) -> Poll> { + self.written += buf.len() as u64; + Poll::Ready(Ok(buf.len())) + } + + fn set_priority(&mut self, _: i64) {} + + fn set_group(&mut self, group: &Self::Group) { + match *group {} + } + + fn finish(&mut self) -> Result<(), Self::Error> { + Ok(()) + } + + fn reset(&mut self, _: u32) {} + + fn poll_closed(&self, _: &kio::Waiter) -> Poll> { + Poll::Pending + } + } + + /// A boxed stream hands back the transport's own offset, and reports a transport + /// without acknowledgments as unsupported, listed or not. + #[test] + fn a_boxed_stream_forwards_acknowledgment() { + let waiter = kio::Waiter::noop(); + let mut stream = SendStream::new(Acking { written: 0, acked: 3 }); + assert!(matches!( + poll::SendStream::poll_write(&mut stream, &waiter, b"abc"), + Poll::Ready(Ok(3)) + )); + let three = poll::SendStream::offset(&stream); + assert!(matches!( + poll::SendStream::poll_write(&mut stream, &waiter, b"de"), + Poll::Ready(Ok(2)) + )); + let five = poll::SendStream::offset(&stream); + assert!(matches!( + poll::SendStream::poll_acked(&stream, &waiter, three), + Poll::Ready(Ok(poll::Acked::Delivered)) + )); + assert!(poll::SendStream::poll_acked(&stream, &waiter, five).is_pending()); + + let (a, _b) = super::super::memory::pair(Default::default()); + let session = Session::new(a); + let listed = open_group(&session, ungrouped(0)); + let offset = poll::SendStream::offset(&listed); + assert!(matches!( + poll::SendStream::poll_acked(&listed, &waiter, offset), + Poll::Ready(Ok(poll::Acked::Unsupported)) + )); + } + #[test] fn a_listed_stream_reports_its_acknowledgement() { let (a, b) = super::super::memory::pair(Default::default()); diff --git a/rs/moq-net/src/transport/memory.rs b/rs/moq-net/src/transport/memory.rs index 8ceb0eb83e9..e6ba814f325 100644 --- a/rs/moq-net/src/transport/memory.rs +++ b/rs/moq-net/src/transport/memory.rs @@ -571,6 +571,9 @@ pub struct SendStream { impl poll::SendStream for SendStream { type Error = Error; type Group = crate::transport::poll::Ungrouped; + type Offset = (); + + fn offset(&self) -> Self::Offset {} fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { let mut buf = buf; diff --git a/rs/moq-net/tests/integration/support/mock.rs b/rs/moq-net/tests/integration/support/mock.rs index 455f0422578..50f5523e97b 100644 --- a/rs/moq-net/tests/integration/support/mock.rs +++ b/rs/moq-net/tests/integration/support/mock.rs @@ -214,6 +214,9 @@ impl MockSendStream { impl poll::SendStream for MockSendStream { 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> { if self.conn.hold_writes.load(Ordering::Relaxed) { diff --git a/rs/moq-tokio/src/quic/web/send.rs b/rs/moq-tokio/src/quic/web/send.rs index d32aa1969b9..6402acef3db 100644 --- a/rs/moq-tokio/src/quic/web/send.rs +++ b/rs/moq-tokio/src/quic/web/send.rs @@ -315,6 +315,9 @@ impl tokio::io::AsyncWrite for Stream { impl moq_net::transport::poll::SendStream for Stream { type Error = Error; type Group = send::Group; + type Offset = (); + + fn offset(&self) -> Self::Offset {} fn poll_write(&mut self, waiter: &kio::Waiter, mut buf: &[u8]) -> Poll> { self.poll_write_buf(waiter, &mut buf) diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index bc429ec99f3..2ce48e67324 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -2362,6 +2362,9 @@ mod tests { impl moq_net::transport::poll::SendStream for ScriptedSend { type Error = ScriptedError; type Group = moq_net::transport::poll::Ungrouped; + type Offset = (); + + fn offset(&self) -> Self::Offset {} fn poll_write(&mut self, _: &kio::Waiter, buf: &[u8]) -> std::task::Poll> { if self.stalled { return std::task::Poll::Pending; diff --git a/rs/moq-uring/src/quic/web/send.rs b/rs/moq-uring/src/quic/web/send.rs index 20fd5cb1d34..881627e6e6c 100644 --- a/rs/moq-uring/src/quic/web/send.rs +++ b/rs/moq-uring/src/quic/web/send.rs @@ -284,6 +284,9 @@ impl Drop for Stream { impl moq_net::transport::poll::SendStream for Stream { type Error = Error; type Group = send::Group; + type Offset = (); + + fn offset(&self) -> Self::Offset {} fn poll_write(&mut self, waiter: &kio::Waiter, mut buf: &[u8]) -> Poll> { self.poll_write_buf(waiter, &mut buf) diff --git a/rs/moq-uring/src/transport/local.rs b/rs/moq-uring/src/transport/local.rs index 5c868b3c327..7bcb15c5076 100644 --- a/rs/moq-uring/src/transport/local.rs +++ b/rs/moq-uring/src/transport/local.rs @@ -126,6 +126,15 @@ impl poll::Session for Local { impl poll::SendStream for Local { type Error = T::Error; type Group = Local; + type Offset = T::Offset; + + fn offset(&self) -> Self::Offset { + self.0.offset() + } + + fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll> { + self.0.poll_acked(waiter, offset) + } fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { self.0.poll_write(waiter, buf) diff --git a/rs/qmux/src/session.rs b/rs/qmux/src/session.rs index 10255f612cd..79b6f303fb9 100644 --- a/rs/qmux/src/session.rs +++ b/rs/qmux/src/session.rs @@ -529,6 +529,9 @@ impl SendStream { impl poll::SendStream for SendStream { type Error = Error; type Group = SendGroup; + type Offset = (); + + fn offset(&self) -> Self::Offset {} fn poll_write(&mut self, waiter: &kio::Waiter, mut buf: &[u8]) -> Poll> { self.poll_write_buf(waiter, &mut buf) From ba99f5a5279cefbf6a8826cd80282f4c3329f1fc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 09:28:04 -0800 Subject: [PATCH 3/6] test(moq-net): put the listed-stream test's doc back above it Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/transport/boxed.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/transport/boxed.rs b/rs/moq-net/src/transport/boxed.rs index ea8806a53d5..f566d4066c0 100644 --- a/rs/moq-net/src/transport/boxed.rs +++ b/rs/moq-net/src/transport/boxed.rs @@ -1205,8 +1205,6 @@ mod test { assert!(session.open_streams().is_empty()); } - /// A listed stream reports the peer acknowledging what was written to it, and a reset one - /// never is. /// A stream that counts written bytes as its offset and reports them acknowledged up to /// a mark, to check the boxed layer carries its offset through and back. struct Acking { @@ -1284,6 +1282,8 @@ mod test { )); } + /// A listed stream reports the peer acknowledging what was written to it, and a reset one + /// never is. #[test] fn a_listed_stream_reports_its_acknowledgement() { let (a, b) = super::super::memory::pair(Default::default()); From 366e378be2a656f693932b56d243a09f412183b2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 11:17:36 -0800 Subject: [PATCH 4/6] feat(moq-net)!: poll_acked borrows the offset, which needs no Clone A caller retries the poll with the same offset until it's ready, so it keeps the offset anyway. Borrowing it lets the boxed stream hold a Box and pass downcast_ref straight through, with no Arc and no clone per poll. Co-Authored-By: Claude Opus 5.5 --- quest/m3/quic-ack-hook.md | 12 +++++++----- rs/moq-net/src/ietf/publisher.rs | 2 +- rs/moq-net/src/transport.rs | 4 ++-- rs/moq-net/src/transport/boxed.rs | 22 ++++++++++------------ rs/moq-uring/src/transport/local.rs | 2 +- 5 files changed, 21 insertions(+), 21 deletions(-) diff --git a/quest/m3/quic-ack-hook.md b/quest/m3/quic-ack-hook.md index 1b23215835a..5efc741a9cf 100644 --- a/quest/m3/quic-ack-hook.md +++ b/quest/m3/quic-ack-hook.md @@ -25,9 +25,9 @@ layers. Add an offset type and two methods to `SendStream`, in the trait's poll style: ```rust -type Offset: Clone; +type Offset: 'static; fn offset(&self) -> Self::Offset; -fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll>; +fn poll_acked(&self, waiter: &kio::Waiter, offset: &Self::Offset) -> Poll>; #[non_exhaustive] pub enum Acked { Delivered, Unsupported } @@ -115,11 +115,13 @@ 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()`, `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` is `Clone` rather than `Copy`, since moq-net's boxed -stream erases it behind an `Arc`, and a backend without acknowledgments uses +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` 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 switch `Offset` to the driver's -`send::Offset` and implement the hook. +`send::Offset` (which is `Copy`, so they pass `*offset`) and implement the hook. diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index ec4aa4986fe..296a8179116 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -7339,7 +7339,7 @@ impl crate::transport::poll::SendStream f fn poll_acked( &self, waiter: &kio::Waiter, - offset: Self::Offset, + offset: &Self::Offset, ) -> Poll> { self.inner.lock().unwrap().stream.poll_acked(waiter, offset) } diff --git a/rs/moq-net/src/transport.rs b/rs/moq-net/src/transport.rs index 3dead25d02b..ede3bf407b9 100644 --- a/rs/moq-net/src/transport.rs +++ b/rs/moq-net/src/transport.rs @@ -717,7 +717,7 @@ pub mod poll { /// 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: Clone + 'static; + type Offset: 'static; /// The position just past every byte written so far. fn offset(&self) -> Self::Offset; @@ -728,7 +728,7 @@ pub mod poll { /// 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> { + fn poll_acked(&self, waiter: &kio::Waiter, offset: &Self::Offset) -> Poll> { let _ = (waiter, offset); Poll::Ready(Ok(Acked::Unsupported)) } diff --git a/rs/moq-net/src/transport/boxed.rs b/rs/moq-net/src/transport/boxed.rs index f566d4066c0..7d5fb91a21c 100644 --- a/rs/moq-net/src/transport/boxed.rs +++ b/rs/moq-net/src/transport/boxed.rs @@ -259,8 +259,7 @@ impl poll::SendGroup for Group { } /// A boxed stream's offset, holding the transport's own behind the boundary. -#[derive(Clone)] -pub(crate) struct Offset(Arc); +pub(crate) struct Offset(Box); /// A boxed outgoing stream. pub(crate) struct SendStream(Sender); @@ -799,15 +798,14 @@ impl + Send + Sync> } fn offset(&self) -> Offset { - Offset(Arc::new(poll::SendStream::offset(self))) + Offset(Box::new(poll::SendStream::offset(self))) } fn poll_acked(&self, waiter: &kio::Waiter, offset: &Offset) -> Poll> { let offset = offset .0 .downcast_ref::() - .expect("offset belongs to another transport") - .clone(); + .expect("offset belongs to another transport"); poll::SendStream::poll_acked(self, waiter, offset).map_err(Error::new) } } @@ -972,8 +970,8 @@ impl poll::SendStream for SendStream { self.get().offset() } - fn poll_acked(&self, waiter: &kio::Waiter, offset: Offset) -> Poll> { - self.get().poll_acked(waiter, &offset) + fn poll_acked(&self, waiter: &kio::Waiter, offset: &Offset) -> Poll> { + self.get().poll_acked(waiter, offset) } fn poll_write(&mut self, waiter: &kio::Waiter, buf: &[u8]) -> Poll> { @@ -1221,8 +1219,8 @@ mod test { self.written } - fn poll_acked(&self, _: &kio::Waiter, offset: u64) -> Poll> { - match offset <= self.acked { + fn poll_acked(&self, _: &kio::Waiter, offset: &u64) -> Poll> { + match *offset <= self.acked { true => Poll::Ready(Ok(poll::Acked::Delivered)), false => Poll::Pending, } @@ -1267,17 +1265,17 @@ mod test { )); let five = poll::SendStream::offset(&stream); assert!(matches!( - poll::SendStream::poll_acked(&stream, &waiter, three), + poll::SendStream::poll_acked(&stream, &waiter, &three), Poll::Ready(Ok(poll::Acked::Delivered)) )); - assert!(poll::SendStream::poll_acked(&stream, &waiter, five).is_pending()); + assert!(poll::SendStream::poll_acked(&stream, &waiter, &five).is_pending()); let (a, _b) = super::super::memory::pair(Default::default()); let session = Session::new(a); let listed = open_group(&session, ungrouped(0)); let offset = poll::SendStream::offset(&listed); assert!(matches!( - poll::SendStream::poll_acked(&listed, &waiter, offset), + poll::SendStream::poll_acked(&listed, &waiter, &offset), Poll::Ready(Ok(poll::Acked::Unsupported)) )); } diff --git a/rs/moq-uring/src/transport/local.rs b/rs/moq-uring/src/transport/local.rs index 7bcb15c5076..0b2d247f00e 100644 --- a/rs/moq-uring/src/transport/local.rs +++ b/rs/moq-uring/src/transport/local.rs @@ -132,7 +132,7 @@ impl poll::SendStream for Local { self.0.offset() } - fn poll_acked(&self, waiter: &kio::Waiter, offset: Self::Offset) -> Poll> { + fn poll_acked(&self, waiter: &kio::Waiter, offset: &Self::Offset) -> Poll> { self.0.poll_acked(waiter, offset) } From 5f4a2a78ee833641fd0d75d53c1d834a2332bf73 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 21:49:55 -0800 Subject: [PATCH 5/6] quest(m2): one acknowledgment primitive on poll::SendStream, as a follow-up to #8739 Co-Authored-By: Claude Opus 5.5 --- quest/m2/api-ack-one-primitive.md | 53 +++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 quest/m2/api-ack-one-primitive.md diff --git a/quest/m2/api-ack-one-primitive.md b/quest/m2/api-ack-one-primitive.md new file mode 100644 index 00000000000..51eb9a5b80e --- /dev/null +++ b/quest/m2/api-ack-one-primitive.md @@ -0,0 +1,53 @@ +# [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. They bill the bytes the + stream took when it reports `Unsupported`, and 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 bills the bytes +the link took, the same number `delivered()` reports for it today. 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. From ef745c99ba56c0155779a161218cb3a7fb1fa449 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 22:07:51 -0800 Subject: [PATCH 6/6] quest(m2): name the count qmux egress falls back to Co-Authored-By: Claude Opus 5.5 --- quest/m2/api-ack-one-primitive.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/quest/m2/api-ack-one-primitive.md b/quest/m2/api-ack-one-primitive.md index 51eb9a5b80e..8e0f143be3d 100644 --- a/quest/m2/api-ack-one-primitive.md +++ b/quest/m2/api-ack-one-primitive.md @@ -12,8 +12,9 @@ transport implements for good. 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. They bill the bytes the - stream took when it reports `Unsupported`, and stop billing once it errors. + `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. @@ -29,9 +30,11 @@ Found by the pre-cut feature review 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 bills the bytes -the link took, the same number `delivered()` reports for it today. Rejected: -giving the hook qmux's "the link took it" meaning. +[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: