diff --git a/quest/m1/README.md b/quest/m1/README.md index fab044d765c..b79e8e3b60a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -67,6 +67,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 drives 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 - [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 - [Kotlin wrapper POMs](/quest/m1/kt-ffi-pom.md) - Maven builds of `dev.moq:moq` resolve a published moq-ffi instead of the missing `0.0.0-dev` - [Installable moq-gst](/quest/m1/gst-brew-path.md) - `brew install moq-gst` installs the plugin from the tarball's `lib/gstreamer-1.0/`, and the Nix package carries `x264enc`, `avenc_aac`, and `avdec_h264` diff --git a/quest/m1/fetch-ok-properties.md b/quest/m1/fetch-ok-properties.md index 95bb2acde07..6115a3676d5 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. It defaults to sending the properties; at 0 the block is present but empty. `fetch.rs` decodes it into `Fetch::properties_wanted`, which the publisher does not honour yet. @@ -39,8 +39,9 @@ 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`. + +## 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/README.md b/quest/m1/pipeline-requests/README.md new file mode 100644 index 00000000000..9a44961ed12 --- /dev/null +++ b/quest/m1/pipeline-requests/README.md @@ -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 diff --git a/quest/m2/pipeline-fetch-info.md b/quest/m1/pipeline-requests/fetch.md similarity index 55% rename from quest/m2/pipeline-fetch-info.md rename to quest/m1/pipeline-requests/fetch.md index e22829f224b..4f5c73e9ff7 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 (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. ## 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,30 @@ 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, 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. 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 +- [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/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 new file mode 100644 index 00000000000..fadb81be329 --- /dev/null +++ b/quest/m1/pipeline-requests/subscribe.md @@ -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 diff --git a/quest/m1/subscribe-ranges/ietf.md b/quest/m1/subscribe-ranges/ietf.md index 4b670810928..ec206c9ef53 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. 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 diff --git a/quest/m2/README.md b/quest/m2/README.md index f34913e5930..90cf97ad00b 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