From 77a18486a41fccdd02d9bf71e2f13643a2e6b7d6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 08:50:01 -0800 Subject: [PATCH 1/3] quest: plan reporting every group a subscriber gives up on A subscriber can drop a group without recv_group ever returning it, when the stream is stopped or evicted before its header is read. That stalls the receive-windows benchmark's overcommitted cells (#7838). The m1 quest makes the wire name every abandoned group and makes the drop signal public; the benchmark quest now requires it. Co-Authored-By: Claude Opus 5.5 --- quest/m0/nightly/receive-windows-evicted.md | 4 ++ quest/m1/README.md | 1 + quest/m1/group-drops.md | 56 +++++++++++++++++++++ 3 files changed, 61 insertions(+) create mode 100644 quest/m1/group-drops.md diff --git a/quest/m0/nightly/receive-windows-evicted.md b/quest/m0/nightly/receive-windows-evicted.md index 23a8f17f928..0dae60889b3 100644 --- a/quest/m0/nightly/receive-windows-evicted.md +++ b/quest/m0/nightly/receive-windows-evicted.md @@ -32,3 +32,7 @@ benchmark at #7597's parent and at #7597. its cases runnable. Public API: none. Wire: none. + +## Required + +- [A group a subscriber gives up on is always reported](/quest/m1/group-drops.md) - overcommitted cells need the subscriber to report groups it abandons, or the paced writer stalls diff --git a/quest/m1/README.md b/quest/m1/README.md index c7eb95cf0bb..f60ff619637 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -151,6 +151,7 @@ their end report, so an embedder's drain alert pages on real cuts. - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - a job's route inherits its claim's instance, replacing the ANNOUNCE_TAKEOVER predecessor design - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 +- [A group a subscriber gives up on is always reported](/quest/m1/group-drops.md) - the wire names every abandoned group and the drop signal is public, so readers count losses instead of stalling - [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport - [A routed JS read wakes when its track aborts](/quest/m1/js-follow-abort-wake.md) - a pending `readFrame()` on a group found through `request()`/`follow()` rejects on `track.abort()` - [Stream credit by priority](/quest/m1/stream-credit/README.md) - every stream opens through one priority entry point, and a higher-priority group takes over or resets a lower one when credit runs out diff --git a/quest/m1/group-drops.md b/quest/m1/group-drops.md new file mode 100644 index 00000000000..58e36d2dddf --- /dev/null +++ b/quest/m1/group-drops.md @@ -0,0 +1,56 @@ +# [M] A group a subscriber gives up on is always reported + +## Goal + +Every group a subscriber gives up on surfaces to the application: no group +vanishes because its stream was stopped or evicted before its header was read. +On the wire, the subscriber always learns the sequence of a group it abandoned. +In the API, `track::Subscriber`'s drop signal (today the crate-private +`poll_drop`, which the ordered reader and resume use to skip gaps) is public in +Rust, mirrored in `@moq/net` and the bindings, so an application, and the +receive-windows benchmark, can count losses instead of waiting forever. + +## Plan + +Planned 2026-11-04 with the maintainer, from +[moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838). Under that +benchmark's overload policy, overcommitted cells hang. Sometimes the subscriber +drops a group without `recv_group` ever returning it: either the group's stream +was evicted before its header was read, or the group was evicted and so was the +FETCH that refetched it. No public API reports that group, so a reader that +paces on delivered-or-evicted groups stalls. The 4 MiB-frame cell hits this on +every run; the 256-stream cell sometimes does. + +- ✅ **Milestone m1** (maintainer, 2026-11-04): it changes public API and + possibly lite-07 wire, so it lands before the cut. +- ✅ **The wire mechanism is this quest's call, with numbers** (maintainer, + 2026-11-04). Compare: + - **The publisher answers STOP_SENDING with SUBSCRIBE_DROP.** Lite already + sends SUBSCRIBE_DROP on the control stream when a group fails at the + publisher (`GroupServe::settle_failed`, `rs/moq-net/src/lite/publisher.rs`, + versions with a track stream), but a subscriber's STOP_SENDING doesn't + produce one. + - **The subscriber reads a group's header before it stops or evicts that + stream.** + + Doing both is fine if each is needed. Start with the maintainer's question: + why does the subscriber stop or evict a stream before reading its header at + all? If receive-window eviction can wait for the header, the wire half may + shrink to that. Cover moq-transport too, or say why it differs. +- **Public drop signal.** Make the drop signal public, naming it to match the + existing read methods (`recv_group` and friends; for example `recv_drop` + returning the given-up run and its error), with the same shape in JS and the + bindings. The ordered reader and resume keep using it internally. Its first + consumers are the receive-windows benchmark and applications; the + [API audit](/quest/m1/api-audit/README.md) rule for new surface is met. +- Stay consistent with the [drop set](/quest/m1/drop-set.md), which owns the + per-cursor drop runs and their reasons. This quest reports what a cursor + gives up; it doesn't change how a cursor judges a missing group. + +Public API: additive (a public drop read in Rust, `@moq/net` and the bindings). +Wire: possibly lite-07 (SUBSCRIBE_DROP for a stopped group), decided here. + +## Related + +- [Drop set](/quest/m1/drop-set.md) - owns the per-cursor drop runs this reports +- [The receive-windows benchmark runs to the end](/quest/m0/nightly/receive-windows-evicted.md) - waits on this to count losses in overcommitted cells From 5a81676712b9c8298612b6b62421e317aa699743 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 09:12:09 -0800 Subject: [PATCH 2/3] quest: scope group drops to moq-lite, name its measurement, order it after the drop set - The Goal promises every abandoned group on moq-lite; moq-transport reports what its wire allows. - The receive-windows benchmark's overcommitted cells decide the wire mechanism. - The public API lands after the drop set reshapes poll_drop, and JS and the bindings mirror it only for a named consumer. - The m0 benchmark quest no longer Requires this m1 quest; #7838 skips those cells and its remainder waits on this as an outside condition. Co-Authored-By: Claude Opus 5.5 --- quest/m0/nightly/receive-windows-evicted.md | 4 -- quest/m1/group-drops.md | 56 ++++++++++++++------- 2 files changed, 37 insertions(+), 23 deletions(-) diff --git a/quest/m0/nightly/receive-windows-evicted.md b/quest/m0/nightly/receive-windows-evicted.md index 0dae60889b3..23a8f17f928 100644 --- a/quest/m0/nightly/receive-windows-evicted.md +++ b/quest/m0/nightly/receive-windows-evicted.md @@ -32,7 +32,3 @@ benchmark at #7597's parent and at #7597. its cases runnable. Public API: none. Wire: none. - -## Required - -- [A group a subscriber gives up on is always reported](/quest/m1/group-drops.md) - overcommitted cells need the subscriber to report groups it abandons, or the paced writer stalls diff --git a/quest/m1/group-drops.md b/quest/m1/group-drops.md index 58e36d2dddf..dc8bf279672 100644 --- a/quest/m1/group-drops.md +++ b/quest/m1/group-drops.md @@ -2,13 +2,15 @@ ## Goal -Every group a subscriber gives up on surfaces to the application: no group -vanishes because its stream was stopped or evicted before its header was read. -On the wire, the subscriber always learns the sequence of a group it abandoned. +Every group a moq-lite subscriber gives up on surfaces to the application: no +group vanishes because its stream was stopped or evicted before its header was +read. On the wire, the subscriber always learns the sequence of a group it +abandoned; moq-transport reports what its wire allows, and the PR records any +gap there. In the API, `track::Subscriber`'s drop signal (today the crate-private -`poll_drop`, which the ordered reader and resume use to skip gaps) is public in -Rust, mirrored in `@moq/net` and the bindings, so an application, and the -receive-windows benchmark, can count losses instead of waiting forever. +`poll_drop`, which the ordered reader and resume use to skip gaps) is public, +so the receive-windows benchmark and applications can count losses instead of +waiting forever. ## Plan @@ -33,24 +35,40 @@ every run; the 256-stream cell sometimes does. - **The subscriber reads a group's header before it stops or evicts that stream.** - Doing both is fine if each is needed. Start with the maintainer's question: + Doing both is fine if each is needed. The numbers come from the + receive-windows benchmark's overcommitted cells (256 streams, 4 MiB frames, + follow; `rs/moq-tokio/tests/integration/receive_credit.rs`), which + [moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838) skips until + this lands: each must finish, with `delivered_frames` plus the reported + drops accounting for every group sent. Compare their throughput and the + control-stream bytes each mechanism adds. Start with the maintainer's question: why does the subscriber stop or evict a stream before reading its header at all? If receive-window eviction can wait for the header, the wire half may shrink to that. Cover moq-transport too, or say why it differs. -- **Public drop signal.** Make the drop signal public, naming it to match the - existing read methods (`recv_group` and friends; for example `recv_drop` - returning the given-up run and its error), with the same shape in JS and the - bindings. The ordered reader and resume keep using it internally. Its first - consumers are the receive-windows benchmark and applications; the - [API audit](/quest/m1/api-audit/README.md) rule for new surface is met. -- Stay consistent with the [drop set](/quest/m1/drop-set.md), which owns the - per-cursor drop runs and their reasons. This quest reports what a cursor - gives up; it doesn't change how a cursor judges a missing group. - -Public API: additive (a public drop read in Rust, `@moq/net` and the bindings). +- **Public drop signal.** Make the drop signal public in Rust. Choose its + shape here: a separate read named like the existing ones (for example + `recv_drop` returning the given-up run and its error), or a drop variant on + `recv_group`, the way container consumers already read `Frame | Gap | End`. + Prefer folding it into an existing read if that reads as naturally. The + ordered reader and resume keep using it internally. Its first consumer is + the receive-windows benchmark. Mirror it in `@moq/net` and the bindings only + for a named consumer (for example a player or container reader that skips + gaps), per the [API audit](/quest/m1/api-audit/README.md) rule that new + surface needs one; name it in the PR or leave the mirror out. +- **Order with the [drop set](/quest/m1/drop-set.md).** The drop set + replaces `poll_drop`'s `Delivered` argument and the skipped record, and + edits the lite-07 SUBSCRIBE_DROP wording. Land the wire half whenever it's + ready, but publish the API after the drop set, against its final + disposition record, so the public shape doesn't change twice. +- The drop set owns the per-cursor drop runs and their reasons. This quest + reports what a cursor gives up; it doesn't change how a cursor judges a + missing group. + +Public API: additive (a public drop read in Rust; `@moq/net` and the bindings +only with a named consumer). Wire: possibly lite-07 (SUBSCRIBE_DROP for a stopped group), decided here. ## Related - [Drop set](/quest/m1/drop-set.md) - owns the per-cursor drop runs this reports -- [The receive-windows benchmark runs to the end](/quest/m0/nightly/receive-windows-evicted.md) - waits on this to count losses in overcommitted cells +- [The receive-windows benchmark](/quest/m0/nightly/receive-windows-evicted.md) - its overcommitted cells wait on this (skipped by [moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838) until it lands) From 8d233f18ffda2f79002ffbe39264e4010f0db4b9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 4 Nov 2026 09:22:54 -0800 Subject: [PATCH 3/3] quest: group drops' API impact depends on its shape Co-Authored-By: Claude Opus 5.5 --- quest/m1/group-drops.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quest/m1/group-drops.md b/quest/m1/group-drops.md index dc8bf279672..786670d8a4b 100644 --- a/quest/m1/group-drops.md +++ b/quest/m1/group-drops.md @@ -64,8 +64,9 @@ every run; the 256-stream cell sometimes does. reports what a cursor gives up; it doesn't change how a cursor judges a missing group. -Public API: additive (a public drop read in Rust; `@moq/net` and the bindings -only with a named consumer). +Public API: additive for a separate read; breaking if folded into `recv_group` +(its `Result>` return changes for every caller), with +MIGRATE notes. `@moq/net` and the bindings mirror it only with a named consumer. Wire: possibly lite-07 (SUBSCRIBE_DROP for a stopped group), decided here. ## Related