From 8ff24f61a87c6f027a87f890814aab87fd5a3826 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 10:03:55 -0700 Subject: [PATCH 1/7] quest: plan pipelined SUBSCRIBE and FETCH A subscriber waits a round trip for TRACK_INFO before sending SUBSCRIBE, at every hop, in Rust and JS. The draft already allows sending them together. A new m1 questline pipelines SUBSCRIBE with TRACK and moves the first-FETCH pipelining quest in from m2, keeping legacy serial peers working. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/pipeline-requests/README.md | 26 ++++++++ .../pipeline-requests/fetch.md} | 30 ++++++--- quest/m1/pipeline-requests/subscribe.md | 66 +++++++++++++++++++ quest/m2/README.md | 1 - 5 files changed, 115 insertions(+), 9 deletions(-) create mode 100644 quest/m1/pipeline-requests/README.md rename quest/{m2/pipeline-fetch-info.md => m1/pipeline-requests/fetch.md} (61%) create mode 100644 quest/m1/pipeline-requests/subscribe.md diff --git a/quest/m1/README.md b/quest/m1/README.md index fc409e32aba..78f152177df 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -69,6 +69,7 @@ were done or not worth their cost. - [moq-uring tests under load](/quest/m1/uring-tests-under-load.md) - uring tests pass while parallel checks share locked memory - [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi and moq-c drive moq on a multi-thread runtime instead of one thread - [Audio group duration](/quest/m1/audio-group-duration.md) - audio groups span at least 20 ms by default, so small frames don't mint a group each +- [Pipelined requests](/quest/m1/pipeline-requests/README.md) - SUBSCRIBE and the first FETCH go out with the track-info request at every hop, so first data arrives a round trip sooner per hop - [Browser interop cells](/quest/m1/interop-browser-timeouts.md) - `go -> js` and `python -> js` pass, fixed at the cause rather than by a longer timeout - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives diff --git a/quest/m1/pipeline-requests/README.md b/quest/m1/pipeline-requests/README.md new file mode 100644 index 00000000000..cccec56e7b1 --- /dev/null +++ b/quest/m1/pipeline-requests/README.md @@ -0,0 +1,26 @@ +# Pipelined requests + +## Goal + +A track request never waits a round trip for the track's info before the +request that carries data goes out: SUBSCRIBE and the first FETCH travel with +TRACK (lite) or TRACK_STATUS (moq-transport) at every hop, so first data +arrives one round trip sooner per hop. Peers that send them serially keep +working unchanged. + +## Plan + +Decided 2026-10-08 in a `/quest-plan` interview: the extra round trip is not +worth keeping, for SUBSCRIBE and FETCH alike. Shared rules for both children: + +- Data that arrives before the info stays unread in QUIC until the info lands. +- A failed or reset info request fails the data request. +- Legacy serial peers keep working, proven by mixed-mode tests in Rust and JS. + +End to end: measure time to first frame and first fetched group across one +and two relay hops, before and after the line. + +## Required + +- [SUBSCRIBE goes out with TRACK](/quest/m1/pipeline-requests/subscribe.md) - subscribers open TRACK and SUBSCRIBE together in Rust and JS +- [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - a fetch-only reader's first FETCH goes out with the info request, on lite and moq-transport diff --git a/quest/m2/pipeline-fetch-info.md b/quest/m1/pipeline-requests/fetch.md similarity index 61% rename from quest/m2/pipeline-fetch-info.md rename to quest/m1/pipeline-requests/fetch.md index e22829f224b..372f4c787c5 100644 --- a/quest/m2/pipeline-fetch-info.md +++ b/quest/m1/pipeline-requests/fetch.md @@ -3,14 +3,18 @@ ## Goal A fetch-only reader's first FETCH goes upstream together with the request for -the track's info, on moq-lite and moq-transport, removing a round trip per hop. -The fetched group is still handed out only once that route's info is known -and passes the origin's consistency check. +the track's info, on moq-lite and moq-transport, at every hop, removing a +round trip per hop. The fetched group is still handed out only once that +route's info is known and passes the origin's consistency check. Peers that +send them serially keep working unchanged. ## Plan Decided 2026-10-07, while landing #4974 (fetch-only IETF demand), which keeps -a sequential TRACK_STATUS before the first FETCH. +a sequential TRACK_STATUS before the first FETCH. Moved from m2 into +[Pipelined requests](/quest/m1/pipeline-requests/README.md) on 2026-10-08: +the maintainer called the extra round trip not worth keeping, for FETCH as +for SUBSCRIBE, without waiting on a latency measurement. Why the round trip exists (facts, 2026-10-07): nothing in a FETCH request needs the info. Two serial gates do: @@ -33,17 +37,27 @@ What needs the info is decoding the response and approving the group, so: info is in flight (a staged generation), resolving only once that copy is spliced. On a refused or mismatched info, or a detach, drop the pending fetch and re-issue on the next route, as failover already does. Never hand - out a group before the info check passes. + out a group before the info check passes. This gate is FETCH's alone: + subscription demand already reaches a copy before it is spliced. - lite: register the fetch handler up front and run FETCH alongside TRACK_INFO, leaving the response unread in the QUIC stream until the info lands (which also covers lite-07 untimed framing). On a failed TRACK_INFO, reject the fetch and reset the stream. - moq-transport: send TRACK_STATUS alongside the FETCH and take timestamps' - units from it (or FETCH_OK properties where present). + units from it (or FETCH_OK properties where present). Draft-17's + TRACK_STATUS answer carries no properties, so draft-17 keeps #4974's + fallback and is not pipelined. + +The line's shared decisions apply: early response data stays unread in QUIC, +a failed info fails the fetch, and legacy serial peers keep working. Tests: a fetch-only reader's FETCH is on the wire before the info answer; a refused info drops the fetch and retries the next route; a group is never -released before its route's info passes. Measure the first-fetch latency -before and after. +released before its route's info passes; a serial peer against a pipelining +one and the reverse. Measure the first-fetch latency before and after. Public API: none. Wire: none (ordering only). + +## Related + +- [Pipelined SUBSCRIBE](/quest/m1/pipeline-requests/subscribe.md) - the same change for subscriptions diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md new file mode 100644 index 00000000000..0e96db5d6ab --- /dev/null +++ b/quest/m1/pipeline-requests/subscribe.md @@ -0,0 +1,66 @@ +# [M] SUBSCRIBE goes out with TRACK + +## Goal + +On moq-lite 05 and later, a subscriber opens its TRACK and SUBSCRIBE streams +together instead of waiting for TRACK_INFO before sending SUBSCRIBE, in Rust +and JS, at every hop: the viewer's session and each relay's upstream session. +First data arrives one round trip sooner per hop. A peer that still sends +them serially, and lite-03/04 with no track stream, keep working unchanged. + +## Plan + +Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that +added this quest). It starts after #5053 lands and reverses that PR's "not +pipelining" decision: the draft already allows it +(`drafts/draft-lcurley-moq-lite.md`, Track Stream: the subscriber "MAY open +the Track and Subscribe streams concurrently"), and the round trip is not +worth keeping. + +Facts (2026-10-08, `origin/main` 4a79178d2): + +- Rust: `TrackServeRun::poll` waits on `info.poll_fetch` before building its + `ServeLoop` (`rs/moq-net/src/lite/subscriber.rs:3996`), and only then does + `begin_subscription` and `Establish` write SUBSCRIBE. +- JS: `#openSubscribe` awaits `#trackInfo` before `Stream.open` and the + SUBSCRIBE write (`js/net/src/lite/subscriber.ts:693`). The receive path + already waits for the timescale (`runGroup`) and drops datagrams that beat + TRACK_INFO. +- No SUBSCRIBE field needs TRACK_INFO, and neither publisher needs a TRACK + before a SUBSCRIBE (`SubscribeServe::start` subscribes the model track + directly). +- The relay front already hands demand to a copy before splicing it + (`model/origin.rs` `Action::Query`), so the gap is in the session. + +Decisions: + +- Both streams open at once. Group streams that arrive before TRACK_INFO stay + unread in QUIC until it lands (flow control bounds them; no buffering, no + copies). Datagrams that beat it are dropped, as JS does today. Rejected: + buffering decoded bytes in memory. +- A TRACK that fails or is reset while its SUBSCRIBE is live fails the + subscription with TRACK's error and resets the SUBSCRIBE stream. Rejected: + keeping the subscription and learning the info another way. +- Drop the Rust `max_age_bound()` clamp (`model/track.rs`): SUBSCRIBE carries + the subscriber's own max age and the publisher enforces its own. Rejected: + a SUBSCRIBE_UPDATE once TRACK_INFO lands. +- Publishers send a track's TRACK_INFO at a higher stream priority than that + track's groups, in Rust and JS, as the draft's SHOULD asks, so the unread + wait stays one round trip. +- Keep #5053's held TRACK stream: demand still has to hold across either + arrival order and for serial peers. +- Legacy: mixed-mode integration tests in Rust and JS, a serial subscriber + against a pipelining publisher and relay and the reverse, on lite-05/06/07, + with lite-03/04 unchanged. `just test interop --all` covers the + cross-language pairs. + +Tests also: SUBSCRIBE is on the wire before TRACK_INFO; groups that arrive +first are read only after it; a reset TRACK fails the subscription; TRACK_INFO +outranks the track's groups. Measure time to first frame across one and two +relay hops before and after. + +Public API: none. Wire: none (ordering only; the draft already permits it). + +## Related + +- [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - the same change for fetch-only readers diff --git a/quest/m2/README.md b/quest/m2/README.md index 4b398f77a68..591ec7cb61d 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -103,7 +103,6 @@ consumer yet, waits in [m3](/quest/m3/README.md). - [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - an explicit-sync DMA-BUF reaches Intel's encoder, proven on Arrow Lake - [GPU capacity and health](/quest/m2/gpu-health.md) - moq-video reports each device's sessions, memory, utilization, and health on NVIDIA, AMD, and Intel alike - [A release carries multi-vendor GPU input](/quest/m2/gpu-release.md) - `release` ships all three so a pinned consumer drops its vendor code -- [Pipelined first FETCH](/quest/m2/pipeline-fetch-info.md) - a fetch-only reader's first FETCH goes out with the track-info request, on lite and moq-transport, if the first-fetch latency is measured to matter - [Malformed moq-transport input](/quest/m2/ietf-malformed-close.md) - malformed draft-18 and draft-21 control input closes the session with the draft's code, or PROTOCOL_VIOLATION where a code is a real burden and the fallback is recorded in `doc/concept/standard.md`, in moq-net and js/net - [moq-transport request codes](/quest/m2/ietf-request-codes.md) - Range Filters (INVALID_FILTER), reserved namespaces, and RENDEZVOUS_TIMEOUT get the draft's answer, or a recorded fallback code, and the deliberate deviations are documented - [Native enabled](/quest/m2/native-enabled.md) - native players and the ffi/C paths never select a disabled rendition From d1bfc8f2a1f083c2278ee213c24a8a26c2d2204a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 10:10:33 -0700 Subject: [PATCH 2/7] quest: note draft-17 FETCH_OK timescale is not surfaced Co-Authored-By: Claude Opus 5.5 --- quest/m1/pipeline-requests/fetch.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/quest/m1/pipeline-requests/fetch.md b/quest/m1/pipeline-requests/fetch.md index 372f4c787c5..aa8acc9f418 100644 --- a/quest/m1/pipeline-requests/fetch.md +++ b/quest/m1/pipeline-requests/fetch.md @@ -45,8 +45,9 @@ What needs the info is decoding the response and approving the group, so: reject the fetch and reset the stream. - moq-transport: send TRACK_STATUS alongside the FETCH and take timestamps' units from it (or FETCH_OK properties where present). Draft-17's - TRACK_STATUS answer carries no properties, so draft-17 keeps #4974's - fallback and is not pipelined. + TRACK_STATUS answer carries no properties, and its FETCH_OK timescale is + decoded but not surfaced (`ietf/fetch.rs`), so draft-17 keeps #4974's + SUBSCRIBE fallback and is not pipelined. The line's shared decisions apply: early response data stays unread in QUIC, a failed info fails the fetch, and legacy serial peers keep working. From 94c5fb416c6b9c1b8c8bad1c4fca9cf7832b3924 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 11:29:22 -0700 Subject: [PATCH 3/7] quest: align pipelined requests with track-stream-demand, ranges, and FETCH_OK properties SUBSCRIBE pipelining requires the held TRACK stream and replaces its "not pipelining" decision; cross-link ranges, Live, max age, and FETCH_OK properties, and drop the satisfied #4974 ordering note. Co-Authored-By: Claude Opus 5.5 --- quest/m0/track-stream-demand.md | 6 ++++-- quest/m1/fetch-ok-properties.md | 16 ++++++++-------- quest/m1/pipeline-requests/fetch.md | 2 ++ quest/m1/pipeline-requests/subscribe.md | 15 ++++++++++++++- quest/m1/subscribe-ranges/ietf.md | 6 +++++- 5 files changed, 33 insertions(+), 12 deletions(-) diff --git a/quest/m0/track-stream-demand.md b/quest/m0/track-stream-demand.md index dde4dd19e4b..3eac70cb4c6 100644 --- a/quest/m0/track-stream-demand.md +++ b/quest/m0/track-stream-demand.md @@ -51,8 +51,10 @@ Decisions (2026-10-07): TRACK's reservation instead of needing a second, so a session at the cap can still turn its held TRACKs into subscriptions (decided 2026-10-08 from review). -- Not pipelining TRACK and SUBSCRIBE, which the draft already allows: it - still races, and every hop would have to buffer frames until TRACK_INFO. +- Not pipelined here; see + [SUBSCRIBE goes out with TRACK](/quest/m1/pipeline-requests/subscribe.md), + which builds on this hold. Decided 2026-10-08: the round trip is not worth + keeping, and early groups stay unread in QUIC rather than buffered. - Consumers never debounce demand; the docs promise clean edges. - JS query lifetime (folded in from the JS probe-lifetime quest, 2026-10-08: the same publisher plumbing). Rust's query is a consumer of the track state diff --git a/quest/m1/fetch-ok-properties.md b/quest/m1/fetch-ok-properties.md index 35364c36aff..80e423aa32b 100644 --- a/quest/m1/fetch-ok-properties.md +++ b/quest/m1/fetch-ok-properties.md @@ -27,11 +27,11 @@ opts out with INCLUDE_PROPERTIES = 0. Other fetch-only readers still need it. legal to remove the property."). [#4822](https://github.com/moq-dev/moq/pull/4822) makes the standalone FETCH keep each object's Timestamp in the track's units, since a subscribed relay treats a timed track's object without one as malformed. What's left here is - FETCH_OK declaring the track's TIMESCALE, so a fetch-only reader is timed - exactly when the track is, as the untimed model requires. Today our - subscriber takes the units only from SUBSCRIBE_OK, and a fetch-only reader - is untimed. Rejected: omitting timescale from FETCH_OK and leaving - fetch-only readers untimed. + FETCH_OK declaring the track's TIMESCALE, so a third-party fetch-only reader + is timed exactly when the track is, as the untimed model requires. Since + #4974 our own subscriber learns it from SUBSCRIBE_OK or TRACK_STATUS_OK. + Rejected: omitting timescale from FETCH_OK and leaving those readers + untimed. - Honour INCLUDE_PROPERTIES (0x35) on FETCH from draft 20, once [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) serves draft-20 FETCH at all (today our publisher refuses every one). It defaults to sending the @@ -41,9 +41,6 @@ opts out with INCLUDE_PROPERTIES = 0. Other fetch-only readers still need it. carry, a standalone FETCH's objects arrive stamped, and INCLUDE_PROPERTIES = 0 empties the block. -Decided 2026-10-08: #4974 (fetch without SUBSCRIBE) lands first, since both -change how a fetch-only reader learns the track's properties. - Public API: none. Wire: FETCH_OK gains its properties on drafts that define the block. Interop: run `just test interop --all`. @@ -51,3 +48,6 @@ the block. Interop: run `just test interop --all`. - [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - draft-20 FETCH is served at all, and edits the same `run_fetch_stream` +## Related + +- [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - takes a track's units from FETCH_OK properties where present diff --git a/quest/m1/pipeline-requests/fetch.md b/quest/m1/pipeline-requests/fetch.md index aa8acc9f418..8346a52873c 100644 --- a/quest/m1/pipeline-requests/fetch.md +++ b/quest/m1/pipeline-requests/fetch.md @@ -62,3 +62,5 @@ Public API: none. Wire: none (ordering only). ## Related - [Pipelined SUBSCRIBE](/quest/m1/pipeline-requests/subscribe.md) - the same change for subscriptions +- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - fills the FETCH_OK properties this reads where present +- [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - adjacent code in `ietf/subscriber.rs` and `model/origin.rs`; this lands first and ranges rebases diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md index 0e96db5d6ab..b5932387f04 100644 --- a/quest/m1/pipeline-requests/subscribe.md +++ b/quest/m1/pipeline-requests/subscribe.md @@ -43,7 +43,11 @@ Decisions: keeping the subscription and learning the info another way. - Drop the Rust `max_age_bound()` clamp (`model/track.rs`): SUBSCRIBE carries the subscriber's own max age and the publisher enforces its own. Rejected: - a SUBSCRIBE_UPDATE once TRACK_INFO lands. + a SUBSCRIBE_UPDATE once TRACK_INFO lands. Decided 2026-10-08: this agrees + with [One max_age meaning](/quest/m1/cache-max-age.md). Both budgets apply + one staleness rule, so a group is stale under the smaller budget exactly + when it is stale under either. Only the aggregate's clamp goes; the + publisher's read-path clamp (`poll_drift`) is how it enforces its own. - Publishers send a track's TRACK_INFO at a higher stream priority than that track's groups, in Rust and JS, as the draft's SHOULD asks, so the unread wait stays one round trip. @@ -60,7 +64,16 @@ outranks the track's groups. Measure time to first frame across one and two relay hops before and after. Public API: none. Wire: none (ordering only; the draft already permits it). +Decided 2026-10-08: pipelining is ordering-only, so it neither waits on nor +blocks the Related quests below; whichever lands second rebases. + +## Required + +- [TRACK stream demand](/quest/m0/track-stream-demand.md) - the held TRACK stream this keeps (#5053) ## Related - [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - the same change for fetch-only readers +- [lite-07 Live flag](/quest/m1/lite-live.md) - reshapes the same SUBSCRIBE fields +- [One max_age meaning](/quest/m1/cache-max-age.md) - the staleness rule that makes the dropped clamp redundant +- [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - replaces the SUBSCRIBE floor with ranges diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 5ee9b445c16..1491a6d85f7 100644 --- a/quest/m1/subscribe-ranges/ietf.md +++ b/quest/m1/subscribe-ranges/ietf.md @@ -16,7 +16,7 @@ one stream. Absent sequences between the FETCH's groups become drops, and a group already cached is discarded as a duplicate. Cap a downstream FETCH at the Largest Object, as the moq-transport drafts require. A relay with only fetch demand learns the upstream's Largest from TRACK_STATUS without a -SUBSCRIBE, as open #4974 does for fetch-only demand. +SUBSCRIBE, since #4974. [Cross-relay FETCH over moq-transport](/quest/m1/ietf-peer-fetch-old.md) fixes the same FETCH path refusing held groups as `old`. @@ -30,3 +30,7 @@ serves it. - [Model ranges](/quest/m1/subscribe-ranges/model.md) - the range requests this answers - [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - serves draft-20 FETCH through the same group-span path this widens (#4971) + +## Related + +- [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - sends TRACK_STATUS alongside the FETCH in adjacent code (`ietf/subscriber.rs`, `model/origin.rs`); decided 2026-10-08 it lands first, since it is unblocked and this is not, and this rebases onto it From 438b1ef7824de5d3cd2f8f7aa6bf7083c558617c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 11:55:16 -0700 Subject: [PATCH 4/7] quest: narrow the max-age decision and add pre-accept state to pipelined SUBSCRIBE Co-Authored-By: Claude Opus 5.5 --- quest/m1/pipeline-requests/README.md | 3 +- quest/m1/pipeline-requests/subscribe.md | 42 +++++++++++++++++-------- 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/quest/m1/pipeline-requests/README.md b/quest/m1/pipeline-requests/README.md index cccec56e7b1..a1d24f71637 100644 --- a/quest/m1/pipeline-requests/README.md +++ b/quest/m1/pipeline-requests/README.md @@ -13,7 +13,8 @@ working unchanged. Decided 2026-10-08 in a `/quest-plan` interview: the extra round trip is not worth keeping, for SUBSCRIBE and FETCH alike. Shared rules for both children: -- Data that arrives before the info stays unread in QUIC until the info lands. +- Streamed data that arrives before the info stays unread in QUIC until the + info lands. Datagrams can't wait unread, so they are dropped until then. - A failed or reset info request fails the data request. - Legacy serial peers keep working, proven by mixed-mode tests in Rust and JS. diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md index b5932387f04..2ad2581d87a 100644 --- a/quest/m1/pipeline-requests/subscribe.md +++ b/quest/m1/pipeline-requests/subscribe.md @@ -1,4 +1,4 @@ -# [M] SUBSCRIBE goes out with TRACK +# [L] SUBSCRIBE goes out with TRACK ## Goal @@ -31,6 +31,12 @@ Facts (2026-10-08, `origin/main` 4a79178d2): directly). - The relay front already hands demand to a copy before splicing it (`model/origin.rs` `Action::Query`), so the gap is in the session. +- Both stacks route groups only to an accepted subscription. Rust's + `ServeLoop::new` accepts the request with the info, and + `begin_subscription` registers a `TrackEntry` holding that producer and its + timescale; a group whose id has no entry is cancelled, not left unread. JS + `runGroup` drops a group for an id with no registered subscription, and + writes the group before it waits on the timescale. Decisions: @@ -38,16 +44,25 @@ Decisions: unread in QUIC until it lands (flow control bounds them; no buffering, no copies). Datagrams that beat it are dropped, as JS does today. Rejected: buffering decoded bytes in memory. -- A TRACK that fails or is reset while its SUBSCRIBE is live fails the - subscription with TRACK's error and resets the SUBSCRIBE stream. Rejected: - keeping the subscription and learning the info another way. -- Drop the Rust `max_age_bound()` clamp (`model/track.rs`): SUBSCRIBE carries - the subscriber's own max age and the publisher enforces its own. Rejected: - a SUBSCRIBE_UPDATE once TRACK_INFO lands. Decided 2026-10-08: this agrees - with [One max_age meaning](/quest/m1/cache-max-age.md). Both budgets apply - one staleness rule, so a group is stale under the smaller budget exactly - when it is stale under either. Only the aggregate's clamp goes; the - publisher's read-path clamp (`poll_drift`) is how it enforces its own. +- Each subscription gets a pending state before accept, in both stacks: + SUBSCRIBE is built from the request's subscription before the info is + known, and its entry is registered under the id before SUBSCRIBE is written, + with the producer and timescale deferred. A group stream that arrives early + parks after its header and resumes on accept. +- A TRACK that fails or is reset while its SUBSCRIBE is live rejects the + request, so the origin fails over as today, and resets the SUBSCRIBE + stream. Rejected: keeping the subscription and learning the info another + way. +- Only the max age SUBSCRIBE and SUBSCRIBE_UPDATE carry on the wire stops + being clamped by TRACK_INFO (`max_age_bound()`, `model/track.rs`): it is the + subscribers' own, and the publisher enforces its own. The local cache + ceiling, the per-reader lateness budget, and the drift check keep + `max_age_bound()`. Accepting TRACK_INFO never emits a SUBSCRIBE_UPDATE. + Rejected: a SUBSCRIBE_UPDATE once TRACK_INFO lands. Narrowed 2026-10-08 + from review. This agrees with + [One max_age meaning](/quest/m1/cache-max-age.md): both budgets apply one + staleness rule, so a group is stale under the smaller budget exactly when it + is stale under either. - Publishers send a track's TRACK_INFO at a higher stream priority than that track's groups, in Rust and JS, as the draft's SHOULD asks, so the unread wait stays one round trip. @@ -59,7 +74,8 @@ Decisions: cross-language pairs. Tests also: SUBSCRIBE is on the wire before TRACK_INFO; groups that arrive -first are read only after it; a reset TRACK fails the subscription; TRACK_INFO +first are read only after it; a reset TRACK rejects the request and the +origin fails over; accepting TRACK_INFO sends no SUBSCRIBE_UPDATE; TRACK_INFO outranks the track's groups. Measure time to first frame across one and two relay hops before and after. @@ -75,5 +91,5 @@ blocks the Related quests below; whichever lands second rebases. - [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - the same change for fetch-only readers - [lite-07 Live flag](/quest/m1/lite-live.md) - reshapes the same SUBSCRIBE fields -- [One max_age meaning](/quest/m1/cache-max-age.md) - the staleness rule that makes the dropped clamp redundant +- [One max_age meaning](/quest/m1/cache-max-age.md) - the staleness rule that makes the wire clamp redundant - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - replaces the SUBSCRIBE floor with ranges From 0062d982b5e5d97ad5fd99e2c6f9f24aca31232d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 12:47:02 -0700 Subject: [PATCH 5/7] quest: exclude draft-17 from the pipelined FETCH goal and name the max-age sites Co-Authored-By: Claude Opus 5.5 --- quest/m1/pipeline-requests/README.md | 5 +++-- quest/m1/pipeline-requests/subscribe.md | 12 +++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/quest/m1/pipeline-requests/README.md b/quest/m1/pipeline-requests/README.md index a1d24f71637..dc4d7a3b6ef 100644 --- a/quest/m1/pipeline-requests/README.md +++ b/quest/m1/pipeline-requests/README.md @@ -5,8 +5,9 @@ A track request never waits a round trip for the track's info before the request that carries data goes out: SUBSCRIBE and the first FETCH travel with TRACK (lite) or TRACK_STATUS (moq-transport) at every hop, so first data -arrives one round trip sooner per hop. Peers that send them serially keep -working unchanged. +arrives one round trip sooner per hop. Draft-17's first FETCH stays serial +(see [the FETCH quest](/quest/m1/pipeline-requests/fetch.md)). Peers that send +them serially keep working unchanged. ## Plan diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md index 96a1edd4fb1..0c42ea29ee9 100644 --- a/quest/m1/pipeline-requests/subscribe.md +++ b/quest/m1/pipeline-requests/subscribe.md @@ -56,11 +56,13 @@ Decisions: way. - Only the max age SUBSCRIBE and SUBSCRIBE_UPDATE carry on the wire stops being clamped by TRACK_INFO (`max_age_bound()`, `model/track.rs`): it is the - subscribers' own, and the publisher enforces its own. The local cache - ceiling, the per-reader lateness budget, and the drift check keep - `max_age_bound()`. Accepting TRACK_INFO never emits a SUBSCRIBE_UPDATE. - Rejected: a SUBSCRIBE_UPDATE once TRACK_INFO lands. Narrowed 2026-10-08 - from review. This agrees with + subscribers' own, still capped by the local cache ceiling (which needs no + info), and the publisher enforces its own. The per-reader lateness budget + (`is_expired`) and the drift check (`poll_drift`) keep `max_age_bound()`. + Accepting TRACK_INFO never emits a SUBSCRIBE_UPDATE. Reword the docs that + promise a clamped aggregate (`track::Producer::subscription`, + `max_age_bounds_the_budget`). Rejected: a SUBSCRIBE_UPDATE once TRACK_INFO + lands. Narrowed 2026-10-08 from review. This agrees with [One max_age meaning](/quest/m1/cache-max-age.md): both budgets apply one staleness rule, so a group is stale under the smaller budget exactly when it is stale under either. From 931eeb72fc59abb4b0ef90c7ac9ea4fdf9c89c83 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 13:22:11 -0700 Subject: [PATCH 6/7] quest: make bare track handles lazy before pipelined SUBSCRIBE Co-Authored-By: Claude Opus 5.5 --- quest/m1/pipeline-requests/README.md | 4 ++- quest/m1/pipeline-requests/lazy-handles.md | 39 ++++++++++++++++++++++ quest/m1/pipeline-requests/subscribe.md | 4 +++ 3 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 quest/m1/pipeline-requests/lazy-handles.md diff --git a/quest/m1/pipeline-requests/README.md b/quest/m1/pipeline-requests/README.md index dc4d7a3b6ef..9a44961ed12 100644 --- a/quest/m1/pipeline-requests/README.md +++ b/quest/m1/pipeline-requests/README.md @@ -12,7 +12,8 @@ them serially keep working unchanged. ## Plan Decided 2026-10-08 in a `/quest-plan` interview: the extra round trip is not -worth keeping, for SUBSCRIBE and FETCH alike. Shared rules for both children: +worth keeping, for SUBSCRIBE and FETCH alike. Shared rules for the SUBSCRIBE +and FETCH children: - Streamed data that arrives before the info stays unread in QUIC until the info lands. Datagrams can't wait unread, so they are dropped until then. @@ -24,5 +25,6 @@ and two relay hops, before and after the line. ## Required +- [Bare track handles are lazy](/quest/m1/pipeline-requests/lazy-handles.md) - a bare Rust `track::Consumer` sends nothing and counts as no demand until it queries or subscribes, like JS - [SUBSCRIBE goes out with TRACK](/quest/m1/pipeline-requests/subscribe.md) - subscribers open TRACK and SUBSCRIBE together in Rust and JS - [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - a fetch-only reader's first FETCH goes out with the info request, on lite and moq-transport diff --git a/quest/m1/pipeline-requests/lazy-handles.md b/quest/m1/pipeline-requests/lazy-handles.md new file mode 100644 index 00000000000..dd8470e9384 --- /dev/null +++ b/quest/m1/pipeline-requests/lazy-handles.md @@ -0,0 +1,39 @@ +# [M] Bare track handles are lazy + +## Goal + +A bare Rust `track::Consumer` (no query, no subscription) sends nothing on the +wire and counts as no demand until it queries or subscribes, matching JS. The +publisher sees demand only for queries and subscriptions. + +## Plan + +Decided 2026-10-08 in a `/quest-plan` round on #5053's open options. It +reverses #5053's option 1 ("a held handle is interest end to end") in favor +of its option 3 ("lazy, like JS"). + +- Query interest becomes visible at the front: a held query is counted on the + track and mirrored onto the copy, so a query still reaches upstream. That is + the part of #5053's option 2 that option 3 needs. +- Local `Demand` stops counting an idle bare handle. That also closes #5053's + documented gap (after a subscription ends with a bare handle held, the + publisher saw `unused` while local `Demand` read `used`), so remove that + comment where `ServeLoop` releases the TRACK + (`rs/moq-net/src/lite/subscriber.rs:4528` at `11ee77d5d`). +- Update the `track::Consumer` rustdoc and `doc/lib/rs/moq-net.md`. + moq-transcode already stops holding idle source handles (#5053). + +Rejected: option 2 alone (a demand pulse for bare handles, with the gap still +open), and keeping #5053's behavior. + +Tests: a held bare handle sends no TRACK and leaves the publisher's demand +unused; a query on it opens TRACK and reaches upstream through a relay; after +a subscription ends with the handle held, demand reads `unused` both locally +and at the publisher. + +Public API: `track::Consumer` demand semantics change (documented). Wire: +none. + +## Related + +- [SUBSCRIBE goes out with TRACK](/quest/m1/pipeline-requests/subscribe.md) - builds on this demand model diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md index 0c42ea29ee9..26639969062 100644 --- a/quest/m1/pipeline-requests/subscribe.md +++ b/quest/m1/pipeline-requests/subscribe.md @@ -86,6 +86,10 @@ Public API: none. Wire: none (ordering only; the draft already permits it). Decided 2026-10-08: pipelining is ordering-only, so it neither waits on nor blocks the Related quests below; whichever lands second rebases. +## Required + +- [Bare track handles are lazy](/quest/m1/pipeline-requests/lazy-handles.md) - demand comes only from queries and subscriptions, so it lands first + ## Related - [Pipelined first FETCH](/quest/m1/pipeline-requests/fetch.md) - the same change for fetch-only readers From 1fc56b5d4686d9e4eb0aff1fd5a170ee9110383e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 8 Oct 2026 23:29:30 -0700 Subject: [PATCH 7/7] quest: carve draft-17 out of the pipelined FETCH goal and tighten the JS unknown-id fact Co-Authored-By: Claude Opus 5.5 --- quest/m1/pipeline-requests/fetch.md | 4 ++-- quest/m1/pipeline-requests/subscribe.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/quest/m1/pipeline-requests/fetch.md b/quest/m1/pipeline-requests/fetch.md index 8346a52873c..4f5c73e9ff7 100644 --- a/quest/m1/pipeline-requests/fetch.md +++ b/quest/m1/pipeline-requests/fetch.md @@ -3,8 +3,8 @@ ## Goal A fetch-only reader's first FETCH goes upstream together with the request for -the track's info, on moq-lite and moq-transport, at every hop, removing a -round trip per hop. The fetched group is still handed out only once that +the track's info, on moq-lite and moq-transport (except draft-17, which stays +serial), at every hop, removing a round trip per hop. The fetched group is still handed out only once that route's info is known and passes the origin's consistency check. Peers that send them serially keep working unchanged. diff --git a/quest/m1/pipeline-requests/subscribe.md b/quest/m1/pipeline-requests/subscribe.md index 26639969062..fadb81be329 100644 --- a/quest/m1/pipeline-requests/subscribe.md +++ b/quest/m1/pipeline-requests/subscribe.md @@ -36,7 +36,8 @@ Facts (2026-10-08, `origin/main` 11ee77d5d, after #5053): `begin_subscription` registers a `TrackEntry` holding that producer and its timescale; a group whose id has no entry is cancelled, not left unread (`subscriber.rs:816`). JS `runGroup` (`subscriber.ts:1145`) drops a group - for an id with no registered subscription, and writes the group before it + for a past id with no registered subscription (an id it has not allocated + yet is a protocol error), and writes the group before it waits on the timescale. Decisions: