Skip to content
Open
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/m1/credit-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,6 @@ Public API: none. Wire: none.

## Related

- [Paused-stream allowance](/quest/m1/paused-allowance.md) - the design this model checks before it merges
- [Unsealed frame credit](/quest/m4/unsealed-frame-credit.md) - returns credit as bytes are read, which the model must then cover
- [Overcommitted receive-window cells](/quest/m3/receive-windows-evicted.md) - the benchmark side of the same mechanism
- [Send-credit stall counters](/quest/m3/send-credit-stalls.md) - what an operator sees when the sender waits on credit
24 changes: 0 additions & 24 deletions quest/m1/paused-allowance.md

This file was deleted.

4 changes: 1 addition & 3 deletions quest/m3/release/cut.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,8 +234,7 @@ Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit):
Decided 2026-11-20 (maintainer, /quest-plan of the pre-cut flow-control
audit): ✅ the cut waits on the [credit model](/quest/m1/credit-model.md),
[#9210](https://github.com/moq-dev/moq/pull/9210)'s
[paused-stream allowance](/quest/m1/paused-allowance.md), which merges once
the model passes on it, and a [bounded relay cache by
paused-stream allowance, which merges once the model passes on it, and a [bounded relay cache by
default](/quest/m1/relay-memory-default.md). Rejected: cutting with flow
control unverified; landing #9210 after the cut. The
[JS frame cap](/quest/m1/js-frame-cap.md) ships with the cut only if it
Expand All @@ -260,6 +259,5 @@ check that Release remeasure opened or updated its pin PR, as RELEASE.md describ
- [Interop and Video pass on main](/quest/m0/interop-green/README.md) - the cut PR's release gate runs `interop.yml`, which failed on `main` every day through 2026-11-12
- [Nightly passes on main](/quest/m0/nightly/README.md) - the release gate runs `features.yml`, red in the 2026-11-12 Nightly
- [Credit model](/quest/m1/credit-model.md) - receive credit, pausing, and the sender's credit wait never deadlock
- [Paused-stream allowance](/quest/m1/paused-allowance.md) - #9210 merges with its design checked
- [Relay memory default](/quest/m1/relay-memory-default.md) - a stock relay's cache is bounded
- [Claim new npm names](/quest/m3/release/npm-first-publish.md) - trusted publishing can publish every new `@moq/*` package
42 changes: 42 additions & 0 deletions quest/m4/unsealed-frame-credit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# [L] A frame's bytes return their credit as they are read, not at its seal

## Goal

About 200 concurrent groups, each writing 64 KiB frames over one connection,
arrive losslessly when every reader is slower than its writer. Today they
evict with no paused stream refused, at the default 4 MiB connection window.

A stream mid-frame holds its unsealed bytes' connection credit until the
segment seals, so N such streams in flight at once need N frames of
connection window, less what paused streams hold. [#9210](https://github.com/moq-dev/moq/pull/9210)
sized a paused stream's allowance so any number pause, and the sim at 64 KiB
frames now meets this limit first: about 150 groups pass and 200 evict. The
limit holds for streams that have not paused yet, so no allowance split lifts
it.

## Plan

Possible direction, not decided: return a stream's credit as its bytes are
read, instead of at the seal. The obstacle is that a segment's bytes are
allocated against the origin's budget until it seals (`rs/moq-net/src/model`),
and the lease is released per segment
(`rs/moq-quic/src/connection/streams/lease.rs`), so crediting earlier means
either the budget charges a segment as it fills or the transport holds
credit for bytes the model already counts. It is a design change of its own,
as [unbounded groups](/quest/m3/unbounded-groups/README.md) made the release
per segment.

Reproduce with `quic_sim::many_groups_carry_bulk_transfers_losslessly` at 200
groups instead of `MANY`. The fix raises `MANY` until a frame's worth of
credit per stream no longer bounds it, or says what bounds it instead.

Whatever lands updates the [credit model](/quest/m1/credit-model.md): early
return changes when credit comes back, and its safety property (credit held
together never exceeds the window) must still hold.

Public API: none expected. Wire: none.

## Related

- [Credit model](/quest/m1/credit-model.md) - models the credit this changes
- [Unbounded groups](/quest/m3/unbounded-groups/README.md) - decided the per-segment release
2 changes: 2 additions & 0 deletions rs/justfile
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,8 @@ quic-sim:
# Forward delay against RTT as a queue-growth signal: deterministic in the simulation, then over real sockets through each cellular moq-shaper preset, one at a time so they do not add to each other's noise.
bash sh/rs/nextest.sh cargo nextest run --locked --release -p moq-quic --lib --run-ignored only --no-capture -E 'test(/^tests::receive_ts::/)'
bash sh/rs/nextest.sh cargo nextest run --locked --release -p moq-tokio --test integration --run-ignored only --no-capture --test-threads 1 -E 'test(/^receive_ts::/)'
# A hundred bulk transfers on one relay connection all pause losslessly, where the merge gate runs twelve.
bash sh/rs/nextest.sh cargo nextest run --locked --release -p moq-relay --features test-support --test integration --run-ignored only -E 'test(/^quic_sim::many_/)'
# Each realtime congestion controller against BBR3 over sim replicas of the cellular presets: queueing delay, throughput, reaction to the drop, and share beside CUBIC.
bash sh/rs/nextest.sh cargo nextest run --locked --release -p moq-quic --lib --run-ignored only --no-capture -E 'test(/^tests::realtime::/)'

Expand Down
146 changes: 120 additions & 26 deletions rs/moq-net/src/coding/reader.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ pub struct Reader<S: RecvStream, V> {
scratch: Vec<u8>,
/// Bytes taken into a frame's unsealed segment, whose receive credit returns once it seals.
unreleased: u64,
/// The declared size of the last frame admitted. A group pauses when its next frame does
/// not fit, up to a frame short of its window, so the stream's credit stops that short
/// too, judging the next frame by this one.
frame: u64,
stats: crate::stats::Session,
}

Expand Down Expand Up @@ -76,14 +80,18 @@ pub(crate) trait Pause {
/// How far the group's writer reads this stream ahead of its fastest reader before
/// pausing: the stream's receive credit, capped at the live tail's ahead half (see
/// [`crate::model::pace::window`]). A stream outside any session takes the cap.
fn window(&self) -> u64 {
fn window(&mut self) -> u64 {
crate::model::pace::AHEAD
}

/// Reserve the credit this stream may hold while paused, its stream window and the `taken`
/// bytes it read whose credit it has yet to return, returning whether it may pause. A
/// Let the peer send only what the group's writer has `room` for, at least the `unsealed`
/// rest of the segment being written, so the stream holds little once it pauses; `None`
/// while no reader holds the writer back.
fn shape(&mut self, _room: Option<u64>, _unsealed: u64) {}

/// Reserve the credit this stream holds while paused, returning whether it may pause. A
/// stream outside any session always may.
fn pause(&mut self, _taken: u64) -> bool {
fn pause(&mut self) -> bool {
true
}

Expand All @@ -92,12 +100,16 @@ pub(crate) trait Pause {
}

impl Pause for crate::transport::boxed::RecvStream {
fn window(&self) -> u64 {
fn window(&mut self) -> u64 {
crate::transport::boxed::RecvStream::window(self)
}

fn pause(&mut self, taken: u64) -> bool {
crate::transport::boxed::RecvStream::pause(self, taken)
fn shape(&mut self, room: Option<u64>, unsealed: u64) {
crate::transport::boxed::RecvStream::shape(self, room, unsealed)
}

fn pause(&mut self) -> bool {
crate::transport::boxed::RecvStream::pause(self)
}

fn resume(&mut self) {
Expand Down Expand Up @@ -129,6 +141,7 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
want: 0,
scratch: Vec::new(),
unreleased: 0,
frame: 0,
stats: Default::default(),
}
}
Expand Down Expand Up @@ -454,8 +467,17 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {

let result = loop {
// A writer too far ahead of the group's fastest reader leaves the rest in the
// stream, so flow control pushes back upstream.
let lease = match self.poll_pace(waiter, frame.poll_ready(waiter, self.stream.window())) {
// stream, so flow control pushes back upstream. One partway into a segment reads
// on to its seal first, so a paused stream never holds a segment's credit.
let paced = match self.unreleased {
0 => {
let window = self.stream.window();
let paced = frame.poll_ready(waiter, window);
self.poll_pace(waiter, paced, || frame.room(window), frame.unsealed() as u64)
}
_ => Poll::Ready(Ok(())),
};
let mut lease = match match paced {
// The stream alone, so `unreleased` can count while the lease is out.
Poll::Ready(Ok(())) => {
let version = &self.version;
Expand All @@ -465,8 +487,7 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
}
Poll::Ready(Err(err)) => break Err(err),
Poll::Pending => Poll::Pending,
};
let mut lease = match lease {
} {
Poll::Pending => {
if owed > 0 {
frame.notify();
Expand Down Expand Up @@ -515,6 +536,11 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
frame.notify();
owed = 0;
}
// The transport grants credit from what was taken when it next sends, so the
// room is measured from here, the chunk taken.
let window = self.stream.window();
let room = frame.room(window).map(|room| room.saturating_sub(self.frame));
self.stream.shape(room, frame.unsealed() as u64);
}
if complete {
break Ok(());
Expand Down Expand Up @@ -543,24 +569,37 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
where
S: Pause,
{
self.poll_pace(waiter, group.poll_admit(waiter, header, self.stream.window()))
self.frame = header.info.size;
let window = self.stream.window();
let paced = group.poll_admit(waiter, header, window);
self.poll_pace(waiter, paced, || group.room(window), 0)
}

/// Wait out `paced`, the group's pace gate, if the session has room for the credit this
/// stream holds while paused (see [`Pause`]); otherwise read on, and the group sheds.
/// Once open, the stream's credit is sized to the `room` the writer has left, at least
/// the `unsealed` rest of its segment.
///
/// A paused stream is not read, so it is watched for a reset instead, which fails the
/// wait rather than leaving it to the group's reader to notice.
fn poll_pace(&mut self, waiter: &kio::Waiter, paced: Poll<()>) -> Poll<Result<(), Error>>
fn poll_pace(
&mut self,
waiter: &kio::Waiter,
paced: Poll<()>,
room: impl FnOnce() -> Option<u64>,
unsealed: u64,
) -> Poll<Result<(), Error>>
where
S: Pause,
{
match paced {
Poll::Ready(()) => {
self.stream.resume();
let room = room().map(|room| room.saturating_sub(self.frame));
self.stream.shape(room, unsealed);
Poll::Ready(Ok(()))
}
Poll::Pending if self.stream.pause(self.unreleased) => {
Poll::Pending if self.stream.pause() => {
let err = ready!(self.stream.poll_reset(waiter));
Poll::Ready(Err(self.version.transport_error(err)))
}
Expand Down Expand Up @@ -630,6 +669,7 @@ impl<S: RecvStream, V: StreamCodes> Reader<S, V> {
want: self.want,
scratch: self.scratch,
unreleased: self.unreleased,
frame: self.frame,
stats: self.stats,
}
}
Expand Down Expand Up @@ -1260,22 +1300,28 @@ mod tests {
released: usize,
/// The pacing window, or the cap when zero.
window: u64,
/// The taken bytes each pause reserved for.
paused: Vec<u64>,
/// The credit held at each pause.
paused: Vec<usize>,
/// The room and unsealed rest each shaping was given.
shaped: Vec<(Option<u64>, u64)>,
}

struct CreditedLease<'a>(&'a mut Credited);

impl Pause for Credited {
fn window(&self) -> u64 {
fn window(&mut self) -> u64 {
match self.window {
0 => crate::model::pace::AHEAD,
window => window,
}
}

fn pause(&mut self, taken: u64) -> bool {
self.paused.push(taken);
fn shape(&mut self, room: Option<u64>, unsealed: u64) {
self.shaped.push((room, unsealed));
}

fn pause(&mut self) -> bool {
self.paused.push(self.held);
true
}
}
Expand Down Expand Up @@ -1367,10 +1413,11 @@ mod tests {
assert_eq!(read, data);
}

/// A stream paused partway through a segment still holds the credit of what it took of
/// it, so the pause reserves that along with the stream window.
/// A stream paced partway through a segment reads on to its seal before pausing, so a
/// paused stream never holds the credit of a segment it has yet to seal, and its credit
/// stays sized to at least the rest of that segment meanwhile.
#[test]
fn a_pause_mid_segment_reserves_what_it_took() {
fn a_stream_reads_on_to_the_seal_before_pausing() {
use crate::frame::SEGMENT;
const CHUNK: usize = 100_000;

Expand All @@ -1392,14 +1439,61 @@ mod tests {
..Default::default()
};
let mut reader = Reader::new(stream, crate::lite::Version::Lite05);
for _ in 0..SEGMENT / CHUNK {
// One chunk straddles the seal.
for _ in 0..SEGMENT / CHUNK + 1 {
reader.stream.chunks.push_back(Bytes::from(vec![0u8; CHUNK]));
}
let noop = &kio::Waiter::noop();
assert!(reader.poll_read_frame(noop, &mut frame).is_pending(), "paced mid-frame");
assert!(
reader.poll_read_frame(noop, &mut frame).is_pending(),
"paced at the seal"
);

let stream = &reader.stream;
assert!(stream.held > 0 && stream.held < SEGMENT, "{} bytes held", stream.held);
assert_eq!(stream.paused, [stream.held as u64], "the pause reserves what it holds");
assert_eq!(stream.released, SEGMENT, "read on past the window to the seal");
assert_eq!(stream.paused, [0], "paused holding nothing taken");
let (room, unsealed) = *stream.shaped.last().expect("shaped as it read");
assert_eq!(room, Some(0), "no room left");
assert_eq!(unsealed, SEGMENT as u64, "but the next segment to seal");
}

/// While a reader holds the group back, ingest sizes the stream's credit to the room the
/// group has left, a frame short, since it pauses once the next frame does not fit.
#[test]
fn credit_is_shaped_a_frame_short_of_the_room() {
const FRAME: usize = 1000;
const WINDOW: u64 = 100_000;

let group = crate::group::Info { start: 0 }.produce();
let _idle = group.consume();
let mut group = crate::recv::Group::new(group);
let info = crate::frame::Info {
size: FRAME as u64,
timestamp: crate::Timestamp::ZERO,
};
let stream = Credited {
window: WINDOW,
..Default::default()
};
let mut reader = Reader::new(stream, crate::lite::Version::Lite05);
let noop = &kio::Waiter::noop();
let mut room = None;
for _ in 0..3 {
assert!(matches!(
reader.poll_admit(noop, &group, &info.into()),
Poll::Ready(Ok(()))
));
let mut frame = group.create_object(info.into()).unwrap();
reader.stream.chunks.push_back(Bytes::from(vec![0u8; FRAME]));
assert!(matches!(reader.poll_read_frame(noop, &mut frame), Poll::Ready(Ok(()))));
room = frame.room(WINDOW);
group.restore(frame.finish().unwrap());
}

let room = room.expect("a reader holds it back");
assert!(room <= WINDOW - 3 * FRAME as u64, "the frames took room");
let (shaped, unsealed) = *reader.stream.shaped.last().unwrap();
assert_eq!(shaped, Some(room - FRAME as u64), "a frame short");
assert_eq!(unsealed, 0, "between frames");
}
}
7 changes: 7 additions & 0 deletions rs/moq-net/src/model/frame.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1390,6 +1390,13 @@ impl Producer {
.poll_paced(waiter, self.buf.written(Ordering::Acquire) as u64, window)
}

/// How many more bytes of this frame the group's writer may take before
/// [`Self::poll_ready`] holds it at `window`, or `None` while nothing would.
#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))]
pub(crate) fn room(&self, window: u64) -> Option<u64> {
self.group().room(self.buf.written(Ordering::Acquire) as u64, window)
}

/// Publish what has been written so far, waking consumers parked on the group.
#[cfg_attr(not(feature = "async"), allow(dead_code, reason = "async-only"))]
pub(crate) fn notify(&self) {
Expand Down
Loading