Repository navigation
quest: plan pipelined SUBSCRIBE and FETCH #5061
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
8ff24f6
d1bfc8f
94c5fb4
438b1ef
c76a8e9
0062d98
931eeb7
643dd3c
1fc56b5
724bcf0
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| # 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. 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 | ||
|
|
||
| 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 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. | ||
| - 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 | ||
|
|
||
| - [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 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| # [L] 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 builds on #5053 (merged) 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` 11ee77d5d, after #5053): | ||
|
|
||
| - Rust: `TrackServeRun::poll` waits on `info.poll_fetch` before building its | ||
| `ServeLoop` (`rs/moq-net/src/lite/subscriber.rs:4144`), 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:704`). 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. | ||
| - 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 | ||
| (`subscriber.rs:816`). JS `runGroup` (`subscriber.ts:1145`) drops a group | ||
| 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: | ||
|
|
||
| - 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. | ||
| - 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, 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. | ||
| - 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 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. | ||
|
|
||
| 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 | ||
| - [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 wire clamp redundant | ||
| - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - replaces the SUBSCRIBE floor with ranges |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Keep the draft-17 FETCH-only fallback. This statement needs a draft-specific condition. In draft-17, TRACK_STATUS does not describe track properties, so the FETCH-only fallback uses SUBSCRIBE. State that TRACK_STATUS supplies Based on learnings, the draft-17 fallback uses SUBSCRIBE because TRACK_STATUS does not describe track properties. 🤖 Prompt for AI AgentsSource: Learnings |
||
|
|
||
| Serving downstream lifts the one-group refusal ("FETCH spanning several | ||
| groups not supported") in `run_fetch_stream` | ||
|
|
@@ -34,3 +34,7 @@ a live track's Largest Object, and test both cases. | |
| ## Required | ||
|
|
||
| - [Model ranges](/quest/m1/subscribe-ranges/model.md) - the range requests this answers | ||
|
|
||
| ## 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 | ||
Uh oh!
There was an error while loading. Please reload this page.