diff --git a/quest/m0/README.md b/quest/m0/README.md index 742605584cc..2c2a0505296 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -75,6 +75,11 @@ the runner moved here from Watch (maintainer, 2026-10-13). The other red jobs have fixes on `main`: macOS tests (#5335), drill-sensitivity (#5338), loom (#5389) and Windows tests (#5339). +Flakes (2026-10-20, maintainer): the redundant failover drift moved here from +the m1 [load round](/quest/m1/test-flakes-2/README.md). It fails loaded +`just check` runs, the local gate every merge waits on, and may hide a TS +export bug. + Hygiene (decided 2026-10-19): the audits sit at the end of this list. Each recurs once per major release: its PR adds the next run to the following milestone, gated from m2 onward on the [release cut](/quest/m2/release/cut.md). @@ -83,6 +88,7 @@ Each lands its fixes in its own PR and plans only what needs a decision. ## Required - [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in the merge queue as one `just ci` pass, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last +- [Redundant failover drift](/quest/m0/redundant-failover-drift.md) - a stitching TS export switches back to the surviving importer behind bufferbloat instead of failing on a stalled clock - [qmux 0.5.3](/quest/m0/qmux-0.5.3.md) - crates.io publishes qmux 0.5.3 with the builder session config the release backport of #5609 needs - [Release shutdown backport](/quest/m0/ffi-shutdown-backport.md) - `release` publishes a non-breaking moq-ffi with an async `drain()` and qmux sessions on the QUIC stream limit - [Release fixed delay](/quest/m0/release-fixed-delay.md) - a fixed latency on `release`, which moq.dev runs, ignores the catalog's jitter and delay as `main` already does diff --git a/quest/m1/test-flakes-2/redundant-failover-drift.md b/quest/m0/redundant-failover-drift.md similarity index 90% rename from quest/m1/test-flakes-2/redundant-failover-drift.md rename to quest/m0/redundant-failover-drift.md index 4701cd08ee6..060a2967303 100644 --- a/quest/m1/test-flakes-2/redundant-failover-drift.md +++ b/quest/m0/redundant-failover-drift.md @@ -11,7 +11,9 @@ slowest test in the queue suite (37 s, past nextest's 30 s SLOW mark). ## Plan Found by the 2026-10-19 test cost audit, with the exporter's stderr captured -on a failing run. After the test kills the newest importer, the exporter +on a failing run. Moved from the m1 +[load round](/quest/m1/test-flakes-2/README.md) to m0 on 2026-10-20 +(maintainer), since it fails loaded `just check` runs. After the test kills the newest importer, the exporter fails instead of switching back to the survivor: > export failed with the broadcast still up, so not lingering ... the diff --git a/quest/m1/README.md b/quest/m1/README.md index e8509e003ed..bbf5a6796dc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -45,21 +45,29 @@ Added 2026-10-16: refresh, ranked after moq-transport passthrough, whose dynamic-groups path it promotes. It is a breaking `Demand` change, so it lands before the cut. +Added 2026-10-20 (maintainer): the probe target, native probing, and the +native rung disable moved up from the [m2 probe epic](/quest/m2/probe/README.md), +so Rust, FFI, and OBS publishers recover a stopped rendition in this release; +padding and the browser's rung disable stay in m2, with only padding's +lite-07 stream type here. + ## Required - [Epoch correctness](/quest/m0/broadcast-epoch/README.md) - publisher identity, duplicate suppression, and catalog pinning gate the breaking cut -- [Sink restart follow](/quest/m1/sink-restart-follow.md) - moq-cli's server and push sinks follow an epochless `Restart` where their output can mark it, and fail loud otherwise +- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - every moq-cli and moq-gst reader, moqsrc and `moq play` included, follows instances through `announced_broadcast` and an epochless `Restart` where its output can mark it; otherwise it stays on the old instance and fails once that route dies - [Cluster routing](/quest/m1/cluster-routing/README.md) - prove shared routing contracts, implement per-origin routes, and connect outbound local clusters - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [Controlled time](/quest/m1/time/README.md) - every crate and package reads time through moq-clock or @moq/clock, with regression tests for the changed contracts - [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding -- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - qmux runs in-tree over `moq-quic`'s stream state machine, returning credit for every byte and delivering its close frame +- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - qmux runs in-tree over `moq-quic`'s stream state machine, returning credit for every byte, delivering its close frame, and ending an unfinished read after its buffered data once the session closes +- [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves a padding stream type that receivers read and discard, for the browser's padding probes - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [moq-transport passthrough](/quest/m1/ietf-extension/README.md) - object IDs, properties, end status, datagram objects, and unknown track properties survive moq-transport -> moq-relay (and a relay cluster) -> moq-transport; moxygen's moq-test sections 1-7 pass nightly, except cases that use a subgroup other than 0 - [Refresh](/quest/m1/refresh/README.md) - a join asks for a fresh group once the current group's deltas exceed a publisher-advertised byte ratio, at every hop; replaces `Demand::used`/`unused` and moq-json's `delta_ratio` - [Compressed tracks](/quest/m1/compress/README.md) - a track flagged `compress` is DEFLATEd per group by moq-net, forwarded compressed, and inflated once on the relay for peers that cannot signal it; `catalog.json.z` and moq-flate go away - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure +- [IETF setup waits under validity](/quest/m1/ietf-setup-validity.md) - every IETF subscriber setup wait ends once its request's route retires or its grant is revoked - [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 - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone @@ -77,10 +85,15 @@ lands before the cut. - [Identity and recovery guide](/quest/m1/identity-guide.md) - explain pinned catalogs, lazy jobs, takeover, restart and version compatibility - [Reference epoch bindings](/quest/m1/reference-epoch-bindings.md) - the UniFFI bindings and C ABI expose and honor a catalog reference's optional `epoch` - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq -- [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants +- [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, sent and received, and a shared cluster session is fair across tenants +- [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - a handed-out group the cache evicted goes stale once its successor's arrival plus the budget passes, so its stalled stream resets +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender validates headroom up to the target +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund and resume them once probing raises the estimate - [Audio jitter target](/quest/m1/audio-jitter-target/README.md) - the playout target is default in both languages; a manual browser proof and a native trace replay remain - [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence, and the media fixture's cold-start audio-tone flake is fixed at its cause +- [moq --listen admission test](/quest/m1/listen-admission-test.md) - an in-process test proves `moq --listen` bounds admission by `listen.timeout` - [Relay signal install](/quest/m1/relay-signal-install.md) - a shutdown signal after the relay starts serving drains it, without leaking handlers into an embedder whose startup failed - [JS redirect keys strip userinfo](/quest/m1/js-reload-userinfo.md) - js/net keys a reconnect endpoint without URL userinfo, matching Rust - [Container reads drop backfill](/quest/m1/read-backfill.md) - the JS container consumer drops groups below its read cursor like Rust @@ -91,7 +104,9 @@ lands before the cut. - [A widened max age re-offers cached groups](/quest/m1/resolved-demand.md) - a warm relay serves a reader with a wider max age the cached groups a cold relay would, with no wire change - [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 - [Resumed close](/quest/m1/resume-closed.md) - a resumed JS track keeps its declared end across copies, and its `closed` and `largest()` settle on a clean end +- [Replica resume](/quest/m1/replica-resume.md) - a lagging same-epoch replica resumes with every frame exactly once and in order, on lite-07 and on moq-transport - [Resumed datagrams](/quest/m1/resume-datagrams.md) - a resumed track skips only datagrams it already delivered, not every lower sequence +- [Recovery verdicts](/quest/m1/recovery-verdicts.md) - group recovery refetches only on errors a new copy can fix, so a repeating error ends the group instead of looping - [Rust resume holds a declared end](/quest/m1/resume-rust-end.md) - a resumed Rust track keeps a declared end across copies, dedupes flapping copies, and judges retention inside the reader's window - [JS answers SUBSCRIBE_START like Rust](/quest/m1/js-start-parity.md) - a JS publisher's START names where its backlog starts, not its newest group - [Received timestamps are media time](/quest/m1/lite-time-provenance.md) - a received timed track's timestamps are media time, so the rewind check can run across hops diff --git a/quest/m1/audit-compile-time.md b/quest/m1/audit-compile-time.md index adfd07acbef..5c8764fb33c 100644 --- a/quest/m1/audit-compile-time.md +++ b/quest/m1/audit-compile-time.md @@ -88,7 +88,7 @@ selected 29 Rust packages (moq-net and every dependent, including C, FFI, GStreamer and WASM). Phases: rustdoc 1m41s (678 hits, 76 misses, 34 bypassed), WASM clippy 18.8 s, io-uring clippy 33.5 s, test build 5m40s (524 hits, 83 misses, 5 bypassed). Nextest started 7,890 tests and stopped after 663 on the -known [failover flake](/quest/m1/test-flakes-2/redundant-failover-drift.md). +known [failover flake](/quest/m0/redundant-failover-drift.md). Cargo rebuilds every dependent when an upstream crate's source changes at all, even a comment, so the test build is the bulk of the compile cost. diff --git a/quest/m1/audit-test-cost.md b/quest/m1/audit-test-cost.md index f9db6a07e1c..4594e22a945 100644 --- a/quest/m1/audit-test-cost.md +++ b/quest/m1/audit-test-cost.md @@ -32,7 +32,7 @@ the stats session graph's recursive Send proof (send-depth and fuzz), bench/ffi-gen's stale wasm-bindgen lock, moq-uring's fixed 1 ms calibration slack, the Nightly JS benchmark stall, the CI selection test's feature count, and the stats producer benchmark lint. It planned -[redundant failover drift](/quest/m1/test-flakes-2/redundant-failover-drift.md) +[redundant failover drift](/quest/m0/redundant-failover-drift.md) and [macOS QUIC connects](https://github.com/moq-dev/moq/pull/6110). Baselines from queue run diff --git a/quest/m1/close-tail-drain.md b/quest/m1/close-tail-drain.md index ec8038905d2..825ccfce7c0 100644 --- a/quest/m1/close-tail-drain.md +++ b/quest/m1/close-tail-drain.md @@ -76,6 +76,10 @@ moq-tokio's `quic::web` path) for the same ordering. Public API: none. Wire: none. +## Required + +- [qmux on the QUIC stream state machine](/quest/m1/quic-qmux.md) - an unfinished qmux read ends after its buffered data once the session closes, which the drain relies on over qmux + ## Related - [QUIC ack hook](/quest/m2/quic-ack-hook.md) - a FIN/ack hook in the QUIC layer diff --git a/quest/m1/compress/README.md b/quest/m1/compress/README.md index 173f88607ce..378dc8bc388 100644 --- a/quest/m1/compress/README.md +++ b/quest/m1/compress/README.md @@ -80,6 +80,7 @@ This README owns the end-to-end proof and the guide once every child lands: ## Required +- [Mid-group subscriptions widen](/quest/m1/compress/app-range-widen.md) - an application range starting mid-group on a compressed track widens to frame 0 at the subscriber instead of failing with `Lagged` - [IETF extension](/quest/m1/compress/ietf.md) - moq-transport draft-16+ peers that negotiate the extension exchange compressed tracks - [JavaScript](/quest/m1/compress/js.md) - js/net publishes and consumes compressed tracks on lite-07 - [Migrate](/quest/m1/compress/migrate.md) - catalogs, stats, and timelines publish one compressed track; moq-flate, @moq/flate, and every `.z` name are gone diff --git a/quest/m1/compress/app-range-widen.md b/quest/m1/compress/app-range-widen.md new file mode 100644 index 00000000000..6aab29b3b3b --- /dev/null +++ b/quest/m1/compress/app-range-widen.md @@ -0,0 +1,31 @@ +# [S] A mid-group subscription to a compressed track widens to frame 0 + +## Goal + +An application subscription whose range starts mid-group on a compressed +track succeeds: the subscriber's requesting model widens the request to frame +0 of that group before it leaves, and the reader gets the frames it asked for. +Today it fails with `Lagged`. The server never widens and keeps serving +exactly what is asked. + +## Plan + +Decided with the maintainer on 2026-10-20, from +[#5928](https://github.com/moq-dev/moq/pull/5928)'s Decision 6, which the +[epic](/quest/m1/compress/README.md)'s Ranges rule records: the subscriber +widens, never the server. + +- Route-change resume already widens to frame 0. This covers ranges an + application supplies, through the same requesting-model path rather than a + second rule. +- Widen only when the subscriber lacks the group's prefix; one that holds + frames 0..N-1 still asks from N. +- The reader still starts at the frame it asked for: the widened prefix only + feeds the inflater. + +Regression test on mock time, in Rust: a mid-group application subscribe on a +compressed track returns the requested frames instead of `Lagged`, and the +wire request starts at frame 0. Mirror it in `js/net` if +[JavaScript](/quest/m1/compress/js.md) has landed compressed tracks by then. + +Public API: none. Wire: none. diff --git a/quest/m1/drop-set.md b/quest/m1/drop-set.md index c2922d8a5bf..957622b3b20 100644 --- a/quest/m1/drop-set.md +++ b/quest/m1/drop-set.md @@ -219,5 +219,6 @@ unchanged. ## Related +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - the sibling for groups a reader already holds after the cache evicts them - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - fills the cache miss an evicted run leaves - [JS unbounded groups](/quest/m2/unbounded-groups/js.md) - the JS byte bound for groups and the runs between them; not required, since JS runs never outgrow the JS cache diff --git a/quest/m1/evicted-group-stale.md b/quest/m1/evicted-group-stale.md new file mode 100644 index 00000000000..0fa8f8dee59 --- /dev/null +++ b/quest/m1/evicted-group-stale.md @@ -0,0 +1,50 @@ +# [S] An evicted group is judged stale by its successor + +## Goal + +A group already handed to a reader stays judgeable after the cache evicts +it: once its successor's arrival plus the reader's budget has passed, the +group is stale, the same verdict `hooks.staleAt` already gives a resumed +copy's group by sequence alone. A serve loop that waits on such a group (a +group stream whose FIN never completes) is then reset as `Old`, whatever the +budget. + +Today the verdict needs the group to still be cached. Rust `GroupExpiry` +(`rs/moq-net/src/model/track.rs`) requires the sequence in the cache lookup, +and JS `#isStale` (`js/net/src/track.ts`) requires the group in the +timeline. Both caches evict an idle group after their window (Rust +`cache::DEFAULT_EXPIRY`, JS `CACHE_WINDOW`, both 30 s), so under a budget of +about 30 s or more a stalled group is never convicted. Since +[#6059](https://github.com/moq-dev/moq/pull/6059) the same stalled stream +also holds the IETF PUBLISH_DONE, which waits on a finished group's FIN +under the budget. + +## Plan + +Found in #6059's follow-ups and decided with the maintainer on 2026-10-20 as +a sibling of [Drop set](/quest/m1/drop-set.md): that quest judges missing +groups, this one judges groups a reader already holds. + +- Judge by the successor, as `#staleAt` does for a sequence the track does + not hold. The verdict needs the successor's arrival (and its reach, for the + media-time arm), not the evicted group itself. +- Find out what the cache-membership checks guard before dropping them, such + as a different copy now occupying the sequence, and keep that guard. +- Settle what the verdict reads once the successor is evicted too. It must + never convict early: any later group arrived no earlier than the successor, + and the newest group is never stale. +- Check `FetchExpiry` beside `GroupExpiry`, which has the same cache-lookup + condition. + +Regression tests on mock time, Rust and JS, each failing without the fix, +with a budget of at least the cache window: a handed-out group whose stream +never completes is evicted, then reset as `Old` once its successor's arrival +plus the budget passes, and on IETF the PUBLISH_DONE then goes out. The +newest group is still never convicted. + +Public API: none. Wire: none. + +## Related + +- [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget +- [#6059](https://github.com/moq-dev/moq/pull/6059) - bounds a stalled group stream's FIN wait by the age budget, which this extends past eviction diff --git a/quest/m1/ietf-setup-validity.md b/quest/m1/ietf-setup-validity.md new file mode 100644 index 00000000000..1eecd054e89 --- /dev/null +++ b/quest/m1/ietf-setup-validity.md @@ -0,0 +1,46 @@ +# [XS] Every IETF setup wait runs under request validity + +## Goal + +Every wait while the IETF subscriber sets up a request ends as soon as the +request stops being valid (its route retired, or its grant revoked, narrowed, +or expired), with the same local refusal and peer cancellation that the +SUBSCRIBE's request-ID and SUBSCRIBE_OK waits give since +[#6061](https://github.com/moq-dev/moq/pull/6061). In +`rs/moq-net/src/ietf/subscriber.rs` that covers: + +- `Stream::open` for SUBSCRIBE, TRACK_STATUS, the cache-miss group FETCH, + and the joining FETCH on draft 17+; +- the request-ID wait for a fetch-only TRACK_STATUS; +- the cache-miss group FETCH's request-ID and response waits, whose response + wait still uses a `retired` flag. + +Today each is bounded only by QUIC stream credit or the ten-second +request-ID give-up. + +## Plan + +Decided with the maintainer on 2026-10-20, from #6061's follow-ups: + +- Reuse #6061's poll-native shape: poll the gate and `validity` beside + `Control::poll_credit(waiter, &mut Deadline)` or the response read inside + one wait, rather than racing the whole setup future. An allocated ID is + still sent on drafts 14-16, since the peer grants MAX_REQUEST_ID credit + back only for requests it receives; the response wait then cancels it. +- Refuse the request locally before awaiting the peer's acknowledgement of + the cancellation, as #6061 does. +- If [Rust request credit](/quest/m1/rs-request-credit.md) lands first, + `Stream::open` no longer waits for stream credit, and only the request-ID + and response waits remain here. + +Regression tests on sim time, one per wait, each failing on main by timing +out: a revoked, narrowed, and expired grant and a route retirement during +the wait each refuse the request promptly, on drafts 14 and 16 and on 17+ +where the wait differs. + +Public API: none. Wire: none. + +## Related + +- [#6061](https://github.com/moq-dev/moq/pull/6061) - brings the SUBSCRIBE's own request-ID and SUBSCRIBE_OK waits under the grant +- [Rust request credit](/quest/m1/rs-request-credit.md) - a request without stream credit fails at once instead of waiting in `Stream::open` diff --git a/quest/m1/listen-admission-test.md b/quest/m1/listen-admission-test.md new file mode 100644 index 00000000000..20c3f1d6f37 --- /dev/null +++ b/quest/m1/listen-admission-test.md @@ -0,0 +1,26 @@ +# [XS] Test that moq --listen bounds admission + +## Goal + +An in-process test proves that `moq --listen` bounds auth admission by +`listen.timeout`: an admission that never answers closes at the deadline, one +answered just inside it is admitted, and `"0"` waits. Today +`rs/moq-cli/tests/listen.rs` drives the binary with `--auth-public`, where +admission never waits, so nothing covers `serve_client` +(`rs/moq-cli/src/main.rs`) running admission under the handshake deadline. + +## Plan + +Decided with the maintainer on 2026-10-20, from the follow-ups of +[#5765](https://github.com/moq-dev/moq/pull/5765), which landed the +deadline. + +- Drive `moq --listen`'s listener in process on controlled time, through the + path that runs admission under the handshake deadline (#5765's + `Request::within`), with an auth decider that can stall, rather than the + binary on wall time. Calling `serve_client` alone would leave the deadline + out. If the listener cannot be driven that way, open the smallest seam that + lets it. +- Match the relay's `auth_lifetime` cases so the two listeners stay alike. + +Public API: none. Wire: none. diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 968fa4ab57d..db471527f73 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -68,6 +68,10 @@ On 2026-10-19 TRACKS, a per-broadcast track listing, replaced SUBSCRIBE_ALL and kept that slot. The `Time(pts)` range end rides in Subscribe ranges, already Required. +Decided 2026-10-20: the padding stream type joins Required, so the m2 +browser [padding probes](/quest/m2/probe/padding.md) can use lite-07 without +a new version. + Rust's lite-07 varints already carry the full 64 bits the draft specifies, so no codec work waits on the cut. @@ -88,6 +92,7 @@ is published; older versions are unchanged. - [Announcement takeover](/quest/m1/announce-takeover.md) - ANNOUNCE_TAKEOVER preserves a proven instance under a new independent route - [Compressed tracks in js/net](/quest/m1/compress/js.md) - JS reads and writes compressed lite-07 tracks instead of refusing them - [TRACKS in js/net](/quest/m1/archive/tracks-js.md) - JS speaks lite-07's Tracks Stream, which Rust already does +- [lite-07 padding](/quest/m1/lite07-padding.md) - lite-07 reserves the padding stream type the browser probes with ## Related diff --git a/quest/m1/lite07-padding.md b/quest/m1/lite07-padding.md new file mode 100644 index 00000000000..4acbbb337b0 --- /dev/null +++ b/quest/m1/lite07-padding.md @@ -0,0 +1,26 @@ +# [XS] lite-07 reserves a padding stream + +## Goal + +lite-07 defines a unidirectional padding stream type that a receiver reads +and discards, in `rs/moq-net`, `js/net`, and `drafts/draft-lcurley-moq-lite.md`, +so the browser's [padding probes](/quest/m2/probe/padding.md) can send it +once lite-07 is published. This quest adds no sender. + +## Plan + +Decided with the maintainer on 2026-10-20: the padding sender stays in m2, +but its stream type joins lite-07 now, since lite-07's wire freezes at the +[cut](/quest/m1/lite07-finalize.md). + +- Match moq-transport's PADDING, which moq-net already discards + (`rs/moq-net/src/ietf/session.rs`). +- A padding stream is untrusted input: discard bytes as they arrive and + return their credit, so it holds nothing beyond the stream itself. +- Peers on lite-06 and older keep resetting an unknown stream without + closing the session. + +Tests: Rust and JS receivers discard a padding stream and the session stays +up, across languages; `just drafts check` passes. + +Public API: none. Wire: lite-07 (unpublished) gains the padding stream type. diff --git a/quest/m2/probe/native.md b/quest/m1/probe-native.md similarity index 55% rename from quest/m2/probe/native.md rename to quest/m1/probe-native.md index 9f2580b8252..8ccd6929279 100644 --- a/quest/m2/probe/native.md +++ b/quest/m1/probe-native.md @@ -7,11 +7,17 @@ retransmits in-flight STREAM data (sent, unacknowledged, and not yet expired) to fill BBR3's ProbeBW_UP phase, so that phase's sample isn't app-limited and the estimate rises when the path has room. Media frames keep their deadlines, redundant bytes stay within budget, and unique goodput is counted once. -Sessions on moq-tokio and moq-uring then advertise PROBE `Increase`. A -measured no-go is a valid outcome. +Sessions on moq-tokio and moq-uring then have a sender, so +[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE +`Increase` for them. A measured no-go is a valid outcome. ## Plan +Decided with the maintainer on 2026-10-20: this moved to m1 with the +[target](/quest/m1/probe-target.md), since the native +[rung disable](/quest/m1/simulcast-rung-disable.md) requires it to resume a +stopped rendition. + Decided with the maintainer on 2026-10-17 (see the [epic](/quest/m2/probe/README.md)), replacing the old plan's "measure which mechanism wins first" step: @@ -29,19 +35,33 @@ mechanism wins first" step: replace capacity with the encoder rate because the source plateaus. Keep current goodput, historical capacity and its age, and the desired rate distinct; preserving an old estimate does not discover capacity. +- **Expired means reset.** Both moq-net publishers reset a stale group's + stream as `Old`, even after its FIN while bytes await acknowledgment + (`poll_expired_while_pending`), and moq-quic never resends a reset stream's + bytes, so probing never sends past a group's expiry. A group the cache + evicted is only judged once [evicted-group staleness](/quest/m1/evicted-group-stale.md) + lands, so it is required, with a test that evicts a group mid-probe. Rejected: requiring + [per-stream deadlines](/quest/m2/quic-deadline.md) first. They predict + whether bytes can still arrive before the deadline, which tightens loss + recovery too, but expiry itself already reaches moq-quic as a reset. - Evaluate the IMMEDIATE_ACK extension so ACK delay doesn't obscure a short sample. -- Implement the [target](/quest/m2/probe/target.md) quest's sender hook in +- Implement the [target](/quest/m1/probe-target.md) quest's sender hook in moq-quic's recovery and pacing layer and the moq-tokio and moq-uring - adapters. A controller with no ProbeBW_UP phase can't, so its sessions - fall back to [padding](/quest/m2/probe/padding.md). + adapters. A controller with no ProbeBW_UP phase (such as the + [realtime controller](/quest/m2/quic-realtime/README.md)) can't, so its + sessions keep `Report`: [padding](/quest/m2/probe/padding.md) is + browser-only. Nor can a session with no media in flight; the native rung + disable keeps its lowest rung encoding for that reason. Acceptance, in moq-quic's seeded simulation (`rs/moq-quic/src/tests/`, extending `Bottleneck` to step its rate) and wired into CI at least nightly: an illustrative 2 Mbit/s source seeking 4 Mbit/s while the path steps 3 to 12 to 3 Mbit/s, on identical media traces and wire budgets. Cover keyframes, idle -restart, stale high estimates, receiver credit limits, compressed ACKs, and -competing CUBIC and BBR flows. Add a congested arm below the media bitrate +restart, stale high estimates, receiver credit limits, compressed ACKs, +competing CUBIC and BBR flows, a group that expires mid-probe (no probe +bytes for its stream after the reset), and a peer target far above the path, whose +redundant bytes stay within the overhead budget. Add a congested arm below the media bitrate behind a deep but finite queue for impairment acceptance and performance. Verify actual overflow drops, adding competing loss-based traffic if BBR alone will not fill it. Sweep queue depth separately. Random or scripted burst loss may @@ -51,14 +71,16 @@ upward adaptation, downward reaction, estimate age, frame deadlines, queue delay, unique goodput, and redundant bytes, against a no-probing baseline. A successful small burst is not proof of full path capacity. -On a no-go, keep the baseline, record why, and leave padding as moq-quic's -sender; the [viewer up-switch](/quest/m2/probe/viewer-upswitch.md) then -requires padding instead of this. Padding can't reach moq-transport drafts 14 -to 17, so sessions on those drafts would keep `Report`. +On a no-go, keep the baseline, record why, and native sessions keep `Report`. +Padding is browser-only, so the native +[rung disable](/quest/m1/simulcast-rung-disable.md) and the +[viewer up-switch](/quest/m2/probe/viewer-upswitch.md) then go back to the +maintainer instead of falling back to it. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the target this probes to and the sender hook it implements +- [Session send target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - an evicted group's stream resets once stale, so probing never retransmits it ## Related diff --git a/quest/m1/probe-target.md b/quest/m1/probe-target.md new file mode 100644 index 00000000000..8d05ca4356a --- /dev/null +++ b/quest/m1/probe-target.md @@ -0,0 +1,66 @@ +# [M] Session send target + +## Goal + +A moq-net session keeps one send target: the sum of its publisher +reservations, so several broadcasts on one connection add up without the +application coordinating them. The session hands it to +whichever sender its transport has, which probes up to it. Without a sender, +behavior is today's: nothing probes. This is what the native +[rung disable](/quest/m1/simulcast-rung-disable.md) needs to resume a stopped +rendition; targets a peer asks for are the m2 +[viewer targets](/quest/m2/probe/viewer-target.md) quest. The `js/net` +mirror lands with its only sender, [padding](/quest/m2/probe/padding.md). + +## Plan + +Decided with the maintainer on 2026-10-20: this moved to m1 with +[native probing](/quest/m1/probe-native.md) and the native rung disable, so a +native publisher's stopped rendition can resume in the next breaking release. +Later that day the maintainer split it: m1 keeps only the send target native +rung recovery needs, and viewer handles, viewer grants, the peer's PROBE +target, and advertising `Increase` moved back to m2 as +[viewer targets](/quest/m2/probe/viewer-target.md), whose consumers (players +and the viewer up-switch) are there. Review of +[#6102](https://github.com/moq-dev/moq/pull/6102) then moved the `js/net` +send target to padding, since without a sender it would be API with no +behavior until m2. + +Decided with the maintainer on 2026-10-17 (see the +[epic](/quest/m2/probe/README.md)): + +- **Reuse the reservation.** The send target is the sum of the `max` ceilings + of every live `Reservation` on the connection's `bandwidth::Allocator`, + including a disabled rung's and an undemanded track's, because rung disable + needs recovery that doesn't depend on demand: viewers deselect a disabled + rung, so its demand goes away. Dropping a reservation removes it from the + sum. No new publisher handle, and publishers need no catalog reader. + Rejected: summing only demanded reservations, and an opt-in flag per + reservation. +- **Automatic, opt-out.** The target is on by default; an application can + override it or disable probing. +- **The sender seam.** Define the hook a transport implements to probe up to + a rate. [Native](/quest/m1/probe-native.md) implements it in moq-quic, and + [padding](/quest/m2/probe/padding.md) in the browser. This quest only needs + a test sender. Probing to a local target is invisible on the wire, so SETUP + keeps advertising `Report`; `Increase` promises to probe to the peer's + target, which viewer targets adds. + +Notes for the implementer: + +- Rust callers build their `Allocator` from `send_bandwidth()` themselves + (`rs/moq-cli`, `rs/moq-c`, `rs/moq-ffi`), so the session can't see their + reservations. Settle who owns it, and keep it across reconnects the way the + estimate is. +- Wire: none. Report the public API in the PR, shaped so the `js/net` mirror + can match it, and carry it through moq-ffi and the bindings per the + cross-package sync table. + +Tests with mocked time, in Rust: the send target follows reservations +being added, updated, and dropped, demanded or not; the session hands it to +its sender; opting out probes nothing; SETUP still advertises `Report`; after +a reconnect, reservation changes still move the new session's target. + +The sum fans out over reservations, so add a benchmark sweeping their count, +wired into the benchmark CI, so an update that rescans every reservation +shows up as a slope. diff --git a/quest/m1/quic-qmux.md b/quest/m1/quic-qmux.md index a2838ccd0b9..43dadeffaf1 100644 --- a/quest/m1/quic-qmux.md +++ b/quest/m1/quic-qmux.md @@ -75,7 +75,17 @@ are no longer pursued): a session returns connection-level credit for every byte receives, whether the app reads it, drops the stream unread, or it arrives after STOP_SENDING, so a long-lived session never stalls on MAX_DATA; and `close()` delivers its APPLICATION_CLOSE frame before the transport drops, whenever the transport stays writable -within the close bound. Test both. If +within the close bound. Test both. + +Also decided 2026-10-20 (maintainer): an unfinished read ends once the session +closes, after its buffered data, so a reader drains what already arrived and +then sees the close instead of hanging. The moq-gst tests +`a_closed_publisher_session_resumes_on_the_next_start` and +`a_moqsink_restart_keeps_pads_when_caps_arrive_at_different_times` +(`rs/moq-gst/src/source/imp.rs`) hang today with the qmux 0.6.3 teardown; +both pass on the in-tree qmux before this lands. + +If [Rust request credit](/quest/m1/rs-request-credit.md) landed first, the session also implements its non-waiting open, so a request without stream credit fails at once on qmux too. Preserve rejection of diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 5253f7be4f4..bfce7cb65c1 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -76,7 +76,7 @@ cache limits remain separate; bitrate pacing composes with this memory cap. qmux port onto `moq-quic`'s stream state - [Scope track priority](/quest/m1/track-priority-scope.md) - the per-broadcast fairness policy on cluster sessions -- [Native probing](/quest/m2/probe/native.md) - moq-quic retransmits in-flight data during ProbeBW_UP to probe up to a session's target +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during ProbeBW_UP to probe up to a session's target - [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in `moq-quic`, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m3/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive from the idle timeout](/quest/m2/quic-keep-alive.md) - the keep-alive interval defaults to a fraction of the negotiated idle timeout; an explicit `quic.keep_alive` overrides diff --git a/quest/m1/recovery-verdicts.md b/quest/m1/recovery-verdicts.md new file mode 100644 index 00000000000..452beb3444d --- /dev/null +++ b/quest/m1/recovery-verdicts.md @@ -0,0 +1,38 @@ +# [S] Group recovery refetches only on errors a new copy can fix + +## Goal + +A resumed group's recovery asks a route for a new copy only when the failure +was about delivery (the route or session went away, the stream was reset by a +peer that is leaving), never when it was about the group itself and would +repeat on every copy. Such a failure ends the group with its error once, +instead of looping on refetches. Rust and JS agree. + +## Plan + +From the follow-ups of [#5878](https://github.com/moq-dev/moq/pull/5878), +decided with the maintainer on 2026-10-20. Rust `Recover::wants` +(`rs/moq-net/src/model/resume.rs`) and JS `verdict` (`js/net/src/resume.ts`) +treat `Old`, `Evicted`, and an application code as verdicts, and JS also +`TooFarBehind`, which Rust does not; every other error is read as no verdict +and refetched. An error that repeats on every copy therefore loops. #5878's eviction reports `Evicted`, a verdict, so it no +longer triggers this, but other errors still can. + +- Classify by error, with one list mirrored in Rust and JS, settling + `TooFarBehind` on both sides. Keep the existing rule that an error from a + copy whose route failed is never a verdict. Rust `route_failed` is + narrower than JS `ROUTE_FAILURES`, and adding the JS guard in Rust hangs + `partial_group` ([moq-dev/moq#6143](https://github.com/moq-dev/moq/pull/6143)); + align the two lists, fixing that hang at its cause. +- A content error from one route may not repeat on another. Settle whether + such an error may move to a different route once; it never asks the same + route again. +- A hostile route can answer every refetch with bad data. Bound that by the + classification itself, not by a retry count. + +Regression tests on mock time, Rust and JS: a group whose every copy fails +with the same content error ends once with that error, a route-loss failure +still recovers the group on the next route, and both languages classify every +listed error alike. + +Public API: none. Wire: none. diff --git a/quest/m1/replica-resume.md b/quest/m1/replica-resume.md new file mode 100644 index 00000000000..c6fed73973b --- /dev/null +++ b/quest/m1/replica-resume.md @@ -0,0 +1,34 @@ +# [S] A lagging same-epoch replica resumes on every epoch wire + +## Goal + +One publisher announced through two relays under its epoch, one of them +lagging: when the route a subscriber reads dies mid-group, the subscriber +resumes on the other route and sees every frame exactly once, in order. This +holds on lite-07 and on moq-transport with the MoQ Epoch extension (draft +17+), since epochs ride moq-transport as of +[#5932](https://github.com/moq-dev/moq/pull/5932). + +## Plan + +Decided with the maintainer on 2026-10-20. Today +`lite_resumes_after_a_lagging_route_dies` +(`rs/moq-net/tests/integration/route_change.rs`) covers the lagging case on +lite-07 only, and the route-flap tests cover moq-transport 22 without a lag. + +- Run the lagging scenario on moq-transport 17 and 22 as well. Lite carries + the resume point upstream; find what moq-transport carries instead, and fix + a duplicate or gap it shows at its cause rather than weakening the + assertion. +- A shared epoch here means true replicas of one publisher's bytes, never two + independent publishers. +- Mirror the case in `js/net` if its resume tests can drive a lagging route. + +Mocked time, wired into CI with the other integration tests. + +Public API: none. Wire: none. + +## Related + +- [Claim answer epochs](https://github.com/moq-dev/moq/pull/5678) - changed how a claim answers, so this contract is rechecked after it +- [Resume through an outage](https://github.com/moq-dev/moq/pull/6183) - landed the same-epoch resume after an unclosed route dies diff --git a/quest/m1/resume-rust-end.md b/quest/m1/resume-rust-end.md index 0d2c5cc9cfa..4bd411aa365 100644 --- a/quest/m1/resume-rust-end.md +++ b/quest/m1/resume-rust-end.md @@ -10,7 +10,9 @@ replaced copy is kept only for groups inside the reader's window. ## Plan -Decided 2026-10-21 with the maintainer: one quest for three Rust resume gaps. +Decided 2026-10-21 with the maintainer: one quest for three Rust resume gaps. A fourth, the +narrower Rust `route_failed`, moved to +[Recovery verdicts](/quest/m1/recovery-verdicts.md). - **Declared end.** `poll_finished` reads only the serving copy, so an end declared on a replaced copy is lost after a swap. Answer from the first @@ -22,13 +24,6 @@ Decided 2026-10-21 with the maintainer: one quest for three Rust resume gaps. - **Window.** The "may still land" check ignores the reader's `Window`, so a sparse-range reader keeps a replaced copy up to its budget for a gap outside its ranges (#6141). Judge it inside the window. -- **Route failures.** Rust `route_failed` is narrower than JS - `ROUTE_FAILURES` (`js/net/src/resume.ts`), and adding the JS guard in Rust - hangs `partial_group` - ([moq-dev/moq#6143](https://github.com/moq-dev/moq/pull/6143)). This belongs - to the recovery-verdicts quest planned in - [moq-dev/moq#6102](https://github.com/moq-dev/moq/pull/6102); fold it there - if that lands first, otherwise align the two here. Regression test per gap, on a mocked clock, mirrored in JS where JS lacks one. @@ -36,5 +31,6 @@ Public API: behavior only. Wire: none. ## Related +- [Recovery verdicts](/quest/m1/recovery-verdicts.md) - aligns Rust `route_failed` with JS in the same file - [Resumed close](/quest/m1/resume-closed.md) - the JS half of a declared end across copies - [Resumed datagrams](/quest/m1/resume-datagrams.md) - the other resume reader fix in the same file diff --git a/quest/m2/probe/simulcast-rung-disable.md b/quest/m1/simulcast-rung-disable.md similarity index 54% rename from quest/m2/probe/simulcast-rung-disable.md rename to quest/m1/simulcast-rung-disable.md index c723ab1496e..1a765439179 100644 --- a/quest/m2/probe/simulcast-rung-disable.md +++ b/quest/m1/simulcast-rung-disable.md @@ -1,4 +1,4 @@ -# [L] Publishers disable simulcast rungs the grant cannot fund +# [L] Native publishers disable simulcast rungs the grant cannot fund ## Goal @@ -6,22 +6,26 @@ A publisher encoding several video renditions of one source stops encoding its top renditions when its bandwidth grant cannot fund them, advertising each as `enabled: false` in the catalog, and re-enables them with hysteresis once the grant recovers. The lower renditions keep their share instead of -every rung degrading together. Covers the JS publisher (`js/publish`), the -Rust and FFI publishers (the `rs/moq-video` producer under the `rs/moq-mux` -rate policy), and the OBS plugin. `@moq/watch`, `moq play`, `moqsrc`, WHEP, -HLS and DASH export, and the moq-mux exports already skip disabled renditions -and follow one that flips; moq-ffi and moq-c refuse to subscribe one and leave -the fallback pick to the application. +every rung degrading together. Covers the Rust and FFI publishers (the +`rs/moq-video` producer under the `rs/moq-mux` rate policy) and the OBS +plugin; the JS publisher is +[JS rung disable](/quest/m2/probe/rung-disable-js.md). `@moq/watch`, +`moq play`, `moqsrc`, WHEP, HLS and DASH export, and the moq-mux exports +already skip disabled renditions and follow one that flips; moq-ffi and moq-c +refuse to subscribe one and leave the fallback pick to the application. ## Plan Today each video encoder reserves its configured ceiling and follows its own -grant down (`js/publish/src/video/encoder.ts`, -`rs/moq-video/src/encode/producer.rs`), so a congested uplink squeezes every -rendition at once and a top rung starved of most of its share keeps -encoding. JS also takes a manual `enabled` input that already publishes -`enabled: false` and stops encoding; this quest drives that state from the -grant. +grant down (`rs/moq-video/src/encode/producer.rs`), so a congested uplink +squeezes every rendition at once and a top rung starved of most of its share +keeps encoding. + +Decided with the maintainer on 2026-10-20: the native publishers moved to m1 +and require the [session target](/quest/m1/probe-target.md) and +[native probing](/quest/m1/probe-native.md), not padding, which is +browser-only. The JS publisher split into its own m2 quest, since it probes +with padding. - One rule, one home. Put the disable and re-enable decision in `moq_mux::rate` beside `Control`, so audio @@ -30,7 +34,7 @@ grant. it. Start from the ladder's band boundary (`disable = (max + 2 * lower) / 3`, see the [ladder questline](/quest/m3/ladder/README.md)) unless measurement argues - otherwise. JS mirrors the same rule and constants. + otherwise. The JS quest mirrors the same rule and constants. - Catalog state follows what the encoder applied, not what the policy asked. Never rewrite the advertised maximum bitrate or remove the rendition. - Recovery must not depend on demand. Once viewers deselect a disabled rung @@ -41,6 +45,14 @@ grant. reservation at its ceiling. The session's probe target sums every live reservation, so it keeps probing for the stopped rung and the estimate can rise to fund it. No padding handle or burst schedule is driven from `Rung`. +- The lowest rendition never disables. Native probing retransmits in-flight + data, so a session with every rung stopped has nothing to probe with once + its last packets are acknowledged, and could never re-enable a rung. +- Disable only on a session with a sender. Native probing needs moq-quic's + BBR3, so a session without it (iroh on noq, or moq-quic configured for + CUBIC or no congestion control) could never raise its estimate to resume a + stopped rung; there every rung keeps encoding and follows its grant down, + as today. Padding stays browser-only rather than covering these. - Assign descending track priority down the renditions so the allocator fills lower rungs first; [Scope track priority](/quest/m1/track-priority-scope.md) settles how that number also orders sends. @@ -52,19 +64,22 @@ grant. Tests with mocked time: a shrinking grant disables the top rung first and keeps the lower ones at their share; a recovering grant re-enables it only past the hysteresis and after its viewers left; a jittering grant near the -boundary does not flap the catalog. Prove one shaped-uplink run in the -browser and one through moq-ffi. +boundary does not flap the catalog; a grant below every boundary keeps the +lowest rung encoding; a session without a sender never disables a rung. +Prove one shaped-uplink run through moq-ffi, including +a path that reopens after the grant fell below the lowest rung. Public API: the shared rule in `moq_mux::rate` and whatever knobs the publishers expose for it. Wire: none; `enabled` already exists. ## Required -- [Session probe target](/quest/m2/probe/target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited -- [Padding probes](/quest/m2/probe/padding.md) - the sender a browser publisher probes with, and any transport without native probing +- [Session send target](/quest/m1/probe-target.md) - a disabled rung's reservation keeps the session probing for it, since the estimators stop learning while app-limited +- [Native probing](/quest/m1/probe-native.md) - the sender that raises the estimate so a disabled rung can resume ## Related +- [JS rung disable](/quest/m2/probe/rung-disable-js.md) - the same rule in `js/publish`, probing with padding - [Ladder controller](/quest/m3/ladder/controller.md) - the same rung disable for generated transcode ladders - [OBS multitrack](/quest/m2/obs-multitrack.md) - OBS's native multitrack encoders as the renditions this disables - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - the viewer side of moving between renditions as capacity changes diff --git a/quest/m1/sink-restart-follow.md b/quest/m1/sink-restart-follow.md index 533f73963c1..9dd6b97ab60 100644 --- a/quest/m1/sink-restart-follow.md +++ b/quest/m1/sink-restart-follow.md @@ -1,19 +1,41 @@ -# [M] Server and push sinks handle a broadcast's restarts +# [L] moq-cli and moq-gst readers follow a broadcast's restarts ## Goal -Every moq-cli sink that resolves a broadcast and keeps serving it handles an -epochless `Restart` on purpose: it follows the new publisher instance where -its output can mark the break. A route change alone is never fatal: a sink -that cannot follow stays on the old instance while its publisher serves it, -and fails once that route dies, since its subscriptions then end with an -error. +Every moq-cli and moq-gst reader that resolves a broadcast and keeps reading +it follows publisher instances through moq-net's +`origin::Consumer::announced_broadcast` +([#5925](https://github.com/moq-dev/moq/pull/5925)) instead of a hand-rolled +`origin.follow` loop. Each handles an epochless +`Restart` on purpose: it follows the new instance where its output can mark +the break. A route change alone is never fatal: a reader that cannot follow +stays on the old instance while its publisher serves it, and fails once that +route dies, since its subscriptions then end with an error. ## Plan -The stdout exports already do this: TS follows with `--stitch`, and the other -formats ride the old instance until its route dies and its tracks error. Audit -and fix the rest the same way: +Decided with the maintainer on 2026-10-20: widened from the server and push +sinks to every moq-cli and moq-gst reader. Following a catalog's references +to other broadcasts stays with +[reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md). + +Readers with their own follow loop today move onto `announced_broadcast`: + +- moqsrc: `follow_path` in `rs/moq-gst/src/source/imp.rs` drains + `origin.follow` and re-requests on each start, holding its pads across + instances. +- `moq play`: `play` in `rs/moq-cli/src/play/media.rs` does the same and + resets its presentation per instance. +- The TS stitching follower (`rs/moq-mux/src/container/ts/follower.rs`), if + `announced_broadcast` fits how it marks a break. + +A finite read such as `fetch` stays on the one instance it resolved. + +The stdout exports (`subscribe`) already follow only where the output marks +the break: TS with `--stitch`. Every other format, and TS without `--stitch`, +stays pinned to the old instance until its route dies and its tracks error, +never concatenating independent instances into one stream. Keep that rule. +Audit and fix the rest the same way: - `export hls`: `moq-hls`'s server resolves per request; check that a restart moves new requests to the new instance and how a playlist marks the break @@ -29,8 +51,7 @@ and fix the rest the same way: Share one helper (a `moq_mux` `Source::follow`-style API per [reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md)) -rather than one rule per sink, built on -`origin::Consumer::announced_broadcast` rather than another hand-rolled loop. Each fix lands with a test that replaces the -publisher while the sink runs. +rather than one rule per reader, built on `announced_broadcast`. Each fix +lands with a test that replaces the publisher while the reader runs. Public API: possibly a shared follow helper in `moq-mux`. Wire: none. diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md index 0e9f891b49e..ad707232fed 100644 --- a/quest/m1/test-flakes-2/README.md +++ b/quest/m1/test-flakes-2/README.md @@ -33,9 +33,10 @@ This README's own work, after the children: run `just check --all` several times on a loaded machine, as the first round did. Added 2026-10-19 (maintainer): three more, the redial pair first since CI -hit it. The same day's test cost audit added the macOS QUIC connects, and the -redundant failover drift first: it may hide a TS export bug and failed two of -three loaded `just check` runs. +hit it. The same day's test cost audit added the macOS QUIC connects and the +[redundant failover drift](/quest/m0/redundant-failover-drift.md), which moved +to m0 on 2026-10-20 (maintainer): it may hide a TS export bug and fails loaded +`just check` runs. Added 2026-10-20 (maintainer): three more from that day's merge batch, the draft-16 cancel race first since it fails on a mocked clock and so may hide @@ -52,7 +53,6 @@ Public API: none. Wire: none. ## Required -- [Redundant failover drift](/quest/m1/test-flakes-2/redundant-failover-drift.md) - a stitching TS export switches back to the surviving importer behind bufferbloat instead of failing on a stalled clock - [Three flakes and fresh-worktree interop](/quest/m1/test-flakes-2/three-flakes.md) - OBS stop drain, the js/net RSS test, the audio harness RTT sample, and interop's bun install ## Related diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 9fb29bb5ccc..fa7da515250 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -43,8 +43,9 @@ default so a single-tenant deployment keeps strict priority across the link. A tenant-keyed domain (one bucket per customer, however many broadcasts they run) needs the tenant identity from the auth line first and is a later refinement of the same tier, not a different design. Opening more -subscriptions or broadcasts must never buy more bandwidth than the bucket -allows. +subscriptions must never buy a broadcast more than its bucket allows. Until +tenant keying lands, a peer that opens more broadcasts does get more shares, +on send and receive alike; tenant keying is what closes that. Decided 2026-10-08: the signed priority type lands here, so the priority API breaks once instead of twice. Subscribe ranges owns group order, so this quest @@ -85,6 +86,30 @@ Direction to settle in the draft first, then the code: gives moq-net's `poll::Session::send_group(priority)` a domain, so land that in the same trait break and implementers break once. +Receive ranks, folded in from +[#5878](https://github.com/moq-dev/moq/pull/5878)'s follow-ups by the +maintainer on 2026-10-20. When the receive window is stuck, #5878 evicts the +lowest subscription priority first across every broadcast on the session, +then the group its subscription would deliver last, and sets a stream's rank +once, when its header decodes: + +- With fairness on, rank received groups within their broadcast's domain + first, as sends are, so one broadcast's priorities never evict another's + partial groups. Received FETCH streams map to a domain through the same + carrier the send side settles, or fall out with it if the goal narrows to + subscription delivery. +- Ranking inside domains still leaves the session-wide window to share, so + a broadcast that fills it would block every other one. Add a fair domain + tier ahead of the ranks, mirroring the byte-fair send tier: a stuck window + evicts from the domain holding the most beyond an even share of the window + across the domains with partial groups, then by rank within that domain. + A broadcast that fills the window alone may keep it until another arrives. + A full window admits no newcomer's bytes, so settle what enters a broadcast + into the fair set first (its subscription, or the header of a stream the + stuck-window eviction made room for), and test that it gets in. +- Re-rank a receive stream when its subscription's priority or group order + changes, instead of keeping the rank from its header. + Signed priority, decided with the maintainer: - moq-lite carries `p + 128` (flip the top bit). The mapping is one-to-one @@ -115,7 +140,11 @@ Signed priority, decided with the maintainer: Prove scoping with the existing lite publisher tests extended to two broadcasts on one session with fairness on: neither starves, a downstream 255 does not change the upstream order, and with fairness off the strict order is -unchanged. The io_uring workers apply the same setting. Move +unchanged. On the receive side, with fairness on, a high priority in one +broadcast never makes a stuck window evict another broadcast's partial groups +first, a broadcast that filled the window before another began receiving +yields down to its even share instead of blocking the newcomer, and a priority +or order update moves an already-ranked stream. The io_uring workers apply the same setting. Move `doc/concept/moq-lite.md` (the 0..255 knob) and `doc/concept/standard.md` (IETF 128 maps to 127) to the new range and mapping. diff --git a/quest/m2/README.md b/quest/m2/README.md index 7f161f908cd..7f17b667024 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -56,7 +56,8 @@ ranked just below deterministic TS legs, which it requires. - [VA-API renderer tests](/quest/m2/vaapi-render-tests.md) - the ignored VA-API renderer import tests run in `just rs gpu` on AMD and Intel and fail instead of skipping - [Vendor-free CARLA bridge](/quest/m2/carla-bridge.md) - the CARLA demo's GPU bridge lets moq-video pick the encoder, and its stand-in test runs on AMD as well as NVIDIA - [V4L2 virtual camera](/quest/m2/v4l2-virtual-camera.md) - V4L2 capture runs nightly against the `vivid` virtual driver instead of only on a developer's camera -- [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches +- [Probe](/quest/m2/probe/README.md) - a session probes up to the bitrate it wants to send or receive, so a stopped simulcast rendition resumes and a viewer up-switches; the browser pads where native sessions retransmit +- [Failed groups reach the publisher](/quest/m2/group-failed.md) - Rust and both JS publishers surface a group whose delivery a subscriber's stream gave up on, with one shape - [A finished PROBE stops reporting](/quest/m2/probe-end-stale.md) - the Rust receive estimate reads unknown once its PROBE stream ends - [Wire stats](/quest/m2/wire-stats/README.md) - `Presence` counts each root's transport bytes on the wire, `wire_tx` and `wire_rx`, from QUIC, WebSocket, and embedder gateway sources - [Media stats](/quest/m2/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and one model turns both into a health verdict and a preflight report @@ -107,6 +108,7 @@ ranked just below deterministic TS legs, which it requires. - [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end - [fMP4 edit lists](/quest/m2/fmp4-edit-lists.md) - the fMP4 importer applies edit lists to frame timestamps - [MKV import refuses out-of-range values](/quest/m2/mkv-dimension-overflow.md) - the Matroska importer errors on a dimension, channel count, or sample rate that would truncate +- [Importers fill the VR fields](/quest/m2/mux-vr-fields.md) - MP4, Matroska, and Opus imports set the catalog's projection, stereo, and ambisonic layout - [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback - [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback diff --git a/quest/m2/group-failed.md b/quest/m2/group-failed.md new file mode 100644 index 00000000000..7e0d1fa52a7 --- /dev/null +++ b/quest/m2/group-failed.md @@ -0,0 +1,42 @@ +# [M] Publishers learn which groups failed to deliver + +## Goal + +A publisher can observe a group it produced whose delivery a subscriber's +stream gave up on (reset as `Old`, evicted, or the stream failed), with one +shape in Rust `moq-net` and in both `js/net` publishers, lite and IETF. + +## Plan + +Decided with the maintainer on 2026-10-20, from +[#6059](https://github.com/moq-dev/moq/pull/6059), which dropped JS +`Track.Producer.failed` because Rust had no counterpart and it covered only +the lite publisher. + +- Name the consumer first, such as an encoder that forces a keyframe or a + stats counter, and let it decide what the notification carries. If none + exists by the time this starts, propose deleting the quest. +- Return a handle or an event stream, not a callback. +- A relay fans a track out to many subscribers, and a hostile subscriber can + fail streams on purpose. Coalesce per group, keyed by the publisher's track + and the group's sequence (the track belongs to one broadcast instance), so + N subscribers or retries failing one group cost one event, and benchmark + the path swept over subscribers and groups. +- Coalescing per group still leaves one notification per distinct sequence, + so a subscriber that fails every live group while the consumer is slow or + absent would grow an event queue. Keep what a track retains bounded + whatever the notification carries: coalesced latest state (such as the + newest failed sequence and a count since the last read), not a queue. +- Carry it through moq-ffi and the bindings only once a binding consumer + asks. + +Tests on mock time, Rust and JS: a group reset as `Old`, an evicted group, and +a failed stream each surface once, on lite and IETF, and a long run of +distinct failed groups with no consumer reading keeps the track's retained +state constant. + +Public API: new, mirrored across Rust and JS. Wire: none. + +## Related + +- [An evicted group is judged stale](/quest/m1/evicted-group-stale.md) - more stalled groups reset as `Old`, which this would surface diff --git a/quest/m2/mux-vr-fields.md b/quest/m2/mux-vr-fields.md new file mode 100644 index 00000000000..84cfaaf65ca --- /dev/null +++ b/quest/m2/mux-vr-fields.md @@ -0,0 +1,55 @@ +# [S] moq-mux importers fill the VR catalog fields + +## Goal + +The `moq-mux` importers fill the hang catalog's spatial fields from +[#5543](https://github.com/moq-dev/moq/pull/5543): a video rendition's +`projection` and `stereo` from MP4 `st3d`/`sv3d` (Spherical Video V2) and +Matroska `Projection`/`StereoMode`, and an audio rendition's +`layout: "ambisonic"` from Opus channel mapping family 2. Media without these +boxes or elements imports as today. + +## Plan + +Decided with the maintainer on 2026-10-20, from #5543's follow-ups. #5543 has +landed the fields. + +- The fields are live state like `color` (#5543), so fill them the way the + importers fill color (`rs/moq-mux/src/codec/color.rs`) and update them when + the source's config changes. +- Derive `fov` from the equirectangular bounds. The catalog's `fov` is a + longitude span centred straight ahead over the full 180 degrees of latitude + (`rs/hang/src/catalog/video/projection.rs`), so refuse asymmetric left and + right bounds, any top or bottom crop, and a nonzero pose (`sv3d`'s `prhd`, + Matroska `ProjectionPoseYaw`/`Pitch`/`Roll`): importing them would silently + recenter or rotate the video. +- Refuse what the catalog cannot describe, since an absent field claims flat + video or plain channels: a cubemap or mesh projection, so Google's + mesh-based VR180 is refused until the catalog has a mesh kind. The same + goes for any stereo packing or eye order beyond mono, left-right, and + top-bottom (such as `st3d` right-left, or a Matroska right-eye-first, + interleaved, or anaglyph `StereoMode`), each with a fixture. For Opus + family 2, RFC 8486 allows `(1 + n)^2 + 2j` channels with `j` 0 or 1; only + `j = 0` with `n` of at least 1 (4, 9, 16, ... channels) maps to + `ambisonic`, and zeroth order or a non-diegetic stereo pair (1, 3, 6, 11, + ... channels) is refused. A count RFC 8486 forbids is malformed and refused + the same way. +- `mp4-atom` 0.16.2 has no `st3d` or `sv3d` atom; add them in + kixelated/mp4-atom. `webm-iterable` already names the Matroska elements. +- An fMP4 Opus track needs the `dOps` mapping table that + [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) adds, so ambisonic + fMP4 follows it; Matroska and raw Opus do not wait. +- Exporters writing the fields back are out of scope. + +Tests: a fixture per source (MP4 360, a 180-degree equirectangular MP4 with +`equi` bounds, Matroska stereo, Opus first-order ambisonics) imports with the +expected fields, and a cubemap, a mesh VR180, an equirectangular source with +asymmetric bounds, a vertical crop, or a nonzero pose, an ambisonic stream +with non-diegetic stereo, and a malformed one are refused. + +Public API: none beyond the catalog fields #5543 adds. Wire: none. + +## Related + +- [WebXR playback](/quest/m3/watch-webxr.md) - `` renders these fields +- [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) - the `dOps` mapping table an ambisonic fMP4 track needs diff --git a/quest/m2/obs-multitrack.md b/quest/m2/obs-multitrack.md index bc11950f249..80ae07948ba 100644 --- a/quest/m2/obs-multitrack.md +++ b/quest/m2/obs-multitrack.md @@ -7,7 +7,7 @@ simulcast renditions of one broadcast, one rendition per track, each with its own size and bitrate in the catalog. A user configures them the way OBS multitrack video is configured, including over obs-websocket. Disabling the top renditions as the bandwidth grant falls is -[simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md)'s work, not +[simulcast rung disable](/quest/m1/simulcast-rung-disable.md)'s work, not this quest's. ## Plan @@ -34,6 +34,6 @@ at least two video tracks watched in ``. ## Related -- [Simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md) - the grant-driven rung disable these renditions follow +- [Simulcast rung disable](/quest/m1/simulcast-rung-disable.md) - the grant-driven rung disable these renditions follow - [MoQ in obs-studio](/quest/m2/obs-studio/README.md) - the native output this configuration carries into - [OBS native codecs](/quest/m2/obs-moq-video/README.md) - the encoders behind each track when MoQ encoders are chosen diff --git a/quest/m2/probe/README.md b/quest/m2/probe/README.md index 78471c82442..6b8f86a2b9d 100644 --- a/quest/m2/probe/README.md +++ b/quest/m2/probe/README.md @@ -28,7 +28,8 @@ publisher-local padding handle: - **One session target.** The session probes to the larger of its local target and the peer's PROBE target. PROBE `Increase` is the wire signal; retransmission or padding is the mechanism. The - [target](/quest/m2/probe/target.md) quest owns it. + [send target](/quest/m1/probe-target.md) owns the local half and + [viewer targets](/quest/m2/probe/viewer-target.md) the peer's. - **Viewers are in scope.** The viewer up-switch joined the epic, since a viewer's target is the same session target sent the other way. - **moq-net stays catalog-agnostic, and each hop is independent.** A relay @@ -39,11 +40,33 @@ publisher-local padding handle: - **Automatic, opt-out.** Our publishers (through their reservations) and players set targets by default, so probing works without an application knowing about it. -- **Native first, padding as the fallback.** Where moq-quic sends, it +- **Native retransmits, the browser pads.** Where moq-quic sends, it retransmits in-flight data during BBR3's ProbeBW_UP phase - ([native](/quest/m2/probe/native.md)). Where the stack can't (browsers over - WebTransport, other QUIC backends), a lowest-priority padding stream on an - ALR probe schedule does ([padding](/quest/m2/probe/padding.md)). + ([native](/quest/m1/probe-native.md)). A browser over WebTransport can't + reach its controller, so a lowest-priority padding stream on an ALR probe + schedule does ([padding](/quest/m2/probe/padding.md)). + +Decided with the maintainer on 2026-10-20: + +- The [target](/quest/m1/probe-target.md), [native](/quest/m1/probe-native.md), + and the native publishers' [rung disable](/quest/m1/simulcast-rung-disable.md) + moved to m1, so Rust, FFI, and OBS publishers recover a stopped rendition in + the next breaking release. Their rung disable needs the target and native + probing, not padding. +- Padding is browser-only (WebTransport in `js/net`). moq-quic with BBR3 is + the only native backend with a probing hook; other native backends (iroh + on noq, moq-quic under CUBIC) have no sender, keep `Report`, and never + disable a rung. lite-07 reserves its stream + type before the cut ([lite-07 padding](/quest/m1/lite07-padding.md)), and + the sender stays here. +- The JS publisher's rung disable split into its own quest here, since it + probes with padding. +- The target then split: m1 keeps the [send target](/quest/m1/probe-target.md) + native rung recovery needs, and viewer handles, viewer grants, the peer's + PROBE target, and `Increase` came back here as + [viewer targets](/quest/m2/probe/viewer-target.md), beside their consumers. + The `js/net` send target moved to [padding](/quest/m2/probe/padding.md), its + only sender. This README's own work, once the children land: @@ -59,11 +82,13 @@ This README's own work, once the children land: ## Required -- [Session probe target](/quest/m2/probe/target.md) - a session probes up to its reservations or the peer's PROBE target, sends its viewer handles as its own PROBE target, and advertises `Increase` where a sender exists -- [Native probing](/quest/m2/probe/native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender still validates headroom up to the target -- [Padding probes](/quest/m2/probe/padding.md) - a lowest-priority padding stream probes on an ALR schedule where the stack can't retransmit, in browsers and on other QUIC backends +- [Session send target](/quest/m1/probe-target.md) - a session probes up to the sum of its publisher reservations through whichever sender its transport has +- [Native probing](/quest/m1/probe-native.md) - moq-quic retransmits in-flight data during BBR3's ProbeBW_UP so an app-limited sender still validates headroom up to the target +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - Rust/FFI and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis +- [Padding probes](/quest/m2/probe/padding.md) - a browser probes with a lowest-priority padding stream on an ALR schedule +- [JS rung disable](/quest/m2/probe/rung-disable-js.md) - `@moq/publish` applies the native rung rule, recovering through padding +- [Viewer targets](/quest/m2/probe/viewer-target.md) - a session sends its viewer handles as its PROBE target, probes to the peer's, splits the receive estimate into viewer grants, and advertises `Increase` where a sender exists - [Players set viewer targets](/quest/m2/probe/players.md) - players hold a viewer handle per watched broadcast at its highest enabled rendition's bitrate -- [Simulcast rung disable](/quest/m2/probe/simulcast-rung-disable.md) - JS, Rust/FFI, and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis - [Viewer up-switch](/quest/m2/probe/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up ## Related diff --git a/quest/m2/probe/padding.md b/quest/m2/probe/padding.md index def47818650..74eda97b146 100644 --- a/quest/m2/probe/padding.md +++ b/quest/m2/probe/padding.md @@ -1,63 +1,79 @@ -# [L] Padding probes where the stack can't retransmit +# [L] Padding probes from the browser ## Goal -Where a session's transport has no native probe (a browser over WebTransport -through `js/net`, a moq-net session on another QUIC backend), the session -probes up to its target with a padding stream at the lowest send priority. On -an ALR schedule, while app-limited below the target, it sends a short probe -cluster at about twice the estimate, capped at the target, about every five -seconds, with a follow-up probe when one validates. When the path has room -the estimate rises; when it doesn't, padding stays within its overhead and -media frame-delay budgets. Such sessions then advertise PROBE `Increase`. +A browser session (`js/net` over WebTransport) can't reach its congestion +controller, so it probes up to its target with a padding stream at the lowest +send priority. On an ALR schedule, while app-limited below the target, it +sends a short probe cluster at about twice the estimate, capped at the target, +about every five seconds, with a follow-up probe when one validates. When the +path has room the estimate rises; when it doesn't, padding stays within its +overhead and media frame-delay budgets. Such sessions on lite-07 or IETF +draft-18 and later then have a sender, so +[viewer targets](/quest/m2/probe/viewer-target.md) can advertise PROBE +`Increase` for them. ## Plan Decided with the maintainer on 2026-10-17 (see the [epic](/quest/m2/probe/README.md)): -- **Padding is the fallback, not the first choice.** A browser can't reach - its congestion controller, and other backends lack - [native probing](/quest/m2/probe/native.md), so padding is ordinary stream - data that any controller counts and paces. It implements the - [target](/quest/m2/probe/target.md) quest's sender hook wherever the - transport doesn't. +- **Padding is the browser's sender.** Native sessions retransmit in-flight + data instead ([native probing](/quest/m1/probe-native.md)). Padding is + ordinary stream data that any controller counts and paces, and it + implements the [target](/quest/m1/probe-target.md) quest's sender hook in + `js/net`. Decided 2026-10-20: browser-only. A native session without + native probing (iroh on noq, or moq-quic under CUBIC) has no sender, so + [native rung disable](/quest/m1/simulcast-rung-disable.md) never stops a + rung there. +- **The browser's send target.** The `js/net` mirror of the + [send target](/quest/m1/probe-target.md) lands here, beside the sender that + uses it: the same reservation sum, opt-out, and sender seam, matching the + Rust API. `js/net` already owns its connection's `Allocator` + (`js/net/src/connection/reload.ts`). Moved here in review of + [#6102](https://github.com/moq-dev/moq/pull/6102), so m1 ships no browser + target without a sender. - **WebRTC's schedule.** Model it on GoogCC's `ProbeController` ALR probing. Rejected: [#5863](https://github.com/moq-dev/moq/pull/5863)'s exponential backoff to 60 s, which leaves a rendition waiting up to a minute after the path opens. A cluster that finds congestion (a falling estimate) ends early. -- **Wire: a moq-lite padding stream** (kept from #5863's analysis). Add a - unidirectional stream type the receiver reads and discards, matching - moq-transport's PADDING, which moq-net already discards - (`rs/moq-net/src/ietf/session.rs`). A moq-lite peer that predates it resets - the unknown stream without closing the session, so the probe just ends. - On moq-transport, send PADDING only from draft-18 on: drafts 14 to 17 close - the session on an unknown stream type (`UniType::classify`), so refuse to - pad there and keep `Report`. Update `drafts/draft-lcurley-moq-lite.md` and - `drafts/draft-lcurley-moq-probe.md` in this PR and run `just drafts check`. +- **Wire.** lite-07 reserves the padding stream type + ([lite-07 padding](/quest/m1/lite07-padding.md)), matching moq-transport's + PADDING. Pad only on lite-07 and, on moq-transport, from draft-18 on. On + lite-05 and lite-06 the peer resets every padding stream, so the estimate + can never rise, and drafts 14 to 17 close the session on an unknown stream + type (`UniType::classify`). Those sessions have no sender: refuse to pad + and keep `Report`. Update `drafts/draft-lcurley-moq-probe.md` if the sender changes + what it says, and run `just drafts check`. - A browser sender can't see whether it is app-limited; settle how to judge it from what it sends against the estimate. +- Settle how the schedule stays within its overhead budget: how padding's + share of sent bytes is counted over time, and what a cluster does once it + would exceed the budget. -Tests, with mocked time: - -- The schedule, Rust and JS: nothing while media meets the target or the - sender isn't app-limited; a cluster about every five seconds at twice the - estimate, capped at the target; a follow-up after one that validates; an - early end when the estimate falls. -- moq-net under its simulated transport: padding goes out at the lowest - priority; lite and IETF draft-18 receivers discard it; an old lite peer - resets it and the session stays up; drafts 14 to 17 pad nothing. -- `js/net`: the padding writer over a fake WebTransport under `@moq/clock`'s - `Manual`. -- moq-quic's seeded simulation with a stepped bottleneck and native probing - off: with padding the estimate rises past the media, without it it stays - frozen. On a path held below the target, report media frame delay and - deadline misses against budgets set before tuning: lowest priority can't - preempt padding already in flight or queued at the bottleneck, so a frame - ready just after a cluster can still wait behind it. Wire it into CI at - least nightly. +Tests, on `@moq/clock`'s `Manual`: + +- The send target: it follows reservations being added, updated, and + dropped, demanded or not, reaches the padding sender, and opting out pads + nothing, as in the Rust tests. +- The schedule: nothing while media meets the target or the sender isn't + app-limited; a cluster about every five seconds at twice the estimate, + capped at the target; a follow-up after one that validates; an early end + when the estimate falls. +- The padding writer over a fake WebTransport: padding goes out at the lowest + priority on lite-07 and IETF draft-18, while lite-05, lite-06, and drafts + 14 to 17 pad nothing and negotiate `Report`. +- In Chrome through a shaped link: with padding the estimate rises past the + media, without it it stays frozen. On a path held below the target, report + media frame delay and deadline misses against budgets set before tuning: + lowest priority can't preempt padding already in flight or queued at the + bottleneck, so a frame ready just after a cluster can still wait behind it. + Assert that repeated clusters on a path with no room stay within the + overhead budget. + Wire it into CI at least nightly, sharing the epic's shaped-uplink setup. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the target this probes to and the sender hook it implements +- [Session send target](/quest/m1/probe-target.md) - the target this probes to and the sender hook it implements +- [lite-07 padding](/quest/m1/lite07-padding.md) - the stream type the padding is sent on diff --git a/quest/m2/probe/players.md b/quest/m2/probe/players.md index 191a6fbdcc7..eadf39e9eef 100644 --- a/quest/m2/probe/players.md +++ b/quest/m2/probe/players.md @@ -16,7 +16,7 @@ Decided with the maintainer on 2026-10-17 (see the already reads the catalog, which keeps moq-net catalog-agnostic, and only an enabled rendition is one it could switch to. Targets are on by default. -- The handle comes from the [target](/quest/m2/probe/target.md) quest; this +- The handle comes from the [viewer targets](/quest/m2/probe/viewer-target.md) quest; this quest only decides its `max`. - Settle what a rendition without a catalog bitrate contributes. - A probe that reaches the target must make the rendition selectable. @@ -31,4 +31,4 @@ and yields to an application override. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the per-broadcast viewer handle +- [Viewer targets](/quest/m2/probe/viewer-target.md) - the per-broadcast viewer handle diff --git a/quest/m2/probe/rung-disable-js.md b/quest/m2/probe/rung-disable-js.md new file mode 100644 index 00000000000..09de623431f --- /dev/null +++ b/quest/m2/probe/rung-disable-js.md @@ -0,0 +1,38 @@ +# [M] The browser publisher disables simulcast rungs the grant cannot fund + +## Goal + +`@moq/publish` (`js/publish`) stops encoding its top video renditions when its +bandwidth grant cannot fund them, advertising each as `enabled: false`, and +re-enables them with hysteresis once padding probes raise the estimate. The +lower renditions keep their share instead of every rung degrading together. + +## Plan + +Split from [native rung disable](/quest/m1/simulcast-rung-disable.md) by the +maintainer on 2026-10-20: the native publishers moved to m1 on native +probing, while a browser can only probe with +[padding](/quest/m2/probe/padding.md), which stays in m2. + +- Mirror the native quest's rule and constants from `moq_mux::rate`, rather + than tuning a JS-only one. Its decisions hold here too: catalog state + follows what the encoder applied, recovery does not depend on demand, and a + disabled rung keeps its reservation at its ceiling so the session keeps + probing for it. The lowest rendition never disables either. +- Today each encoder reserves its ceiling and follows its own grant down + (`js/publish/src/video/encoder.ts`). The manual `enabled` input already + publishes `enabled: false` and stops encoding; this drives that state from + the grant and settles how the two inputs combine. + +Tests on `@moq/clock`'s `Manual`: a shrinking grant disables the top rung +first and keeps the lower ones at their share; a recovering grant re-enables +it only past the hysteresis and after its viewers left; a jittering grant near +the boundary does not flap the catalog. The epic's shaped-uplink browser test +proves recovery end to end. + +Public API: whatever knob `@moq/publish` exposes for the rule. Wire: none. + +## Required + +- [Native rung disable](/quest/m1/simulcast-rung-disable.md) - the shared rule and constants this mirrors +- [Padding probes](/quest/m2/probe/padding.md) - the browser's sender, which raises the estimate so a disabled rung can resume diff --git a/quest/m2/probe/target.md b/quest/m2/probe/target.md deleted file mode 100644 index 452531ff4de..00000000000 --- a/quest/m2/probe/target.md +++ /dev/null @@ -1,95 +0,0 @@ -# [L] Session probe target - -## Goal - -A moq-net session and a `js/net` connection each keep one target per -direction, so several broadcasts on one connection add up without the -application coordinating them. The send target is the larger of what the -session wants to send (the sum of its publisher reservations) and the peer's -PROBE target; the session hands it to whichever sender its transport has and -advertises PROBE `Increase` where one exists. The receive target is the sum of -its viewer handles, sent to the peer as its PROBE target. The two never mix: a -session that publishes and watches doesn't probe its uplink for what it -watches. Without a sender, behavior is today's: `Report`, and nothing probes. - -Each viewer handle also reads a grant: its share of the session's receive -estimate, so several broadcasts watched over one connection each select -against their own share instead of the whole downlink. - -## Plan - -Decided with the maintainer on 2026-10-17 (see the -[epic](/quest/m2/probe/README.md)): - -- **Publisher side: reuse the reservation.** The local send target is the sum - of the `max` ceilings of every live `Reservation` on the connection's - `bandwidth::Allocator`, including a disabled rung's and an undemanded - track's, because [rung disable](/quest/m2/probe/simulcast-rung-disable.md) - needs recovery that doesn't depend on demand: viewers deselect a disabled - rung, so its demand goes away. Dropping a reservation removes it from the - sum. No new publisher handle, and publishers need no catalog reader. - Rejected: summing only demanded reservations, and an opt-in flag per - reservation. -- **Viewer side: a handle per broadcast.** The subscriber session hands out a - reservation-like handle carrying a `max`, one per watched broadcast; the - session sums the live handles and sends the sum as its PROBE target. - Updating or dropping a handle changes the sum. Rejected: one target the - application sums, which pushes the multi-broadcast case onto every app. - [Players](/quest/m2/probe/players.md) hold these handles. -- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer - handle carries a grant the way a publisher `Reservation` does, splitting the - receive estimate across live handles max-min fair by `max`, the split the - send `Allocator` applies within one priority tier - (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even - cut takes all of it and leaves the rest to the others. Today every - `` on a pooled connection selects against 0.8x the whole - `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each - watcher measuring its own subscription's rate, which stays app-limited and - can't see headroom, and dividing the estimate by the watcher count, which - ignores each handle's `max`. - Handles carry no priority: subscription priorities are per track and fixed - by kind, so no per-broadcast priority exists to divide by. Add one when a - player needs to favor one broadcast over another. -- **Peer target.** A sending session probes to the larger of its own target - and the peer's PROBE target. Each hop is independent: a relay never forwards - a viewer's target upstream, and the PROBE target stays per connection, with - no per-track wire field. moq-net reads no catalog. A peer's target is - untrusted, but it only sets how high to probe: each probe scales the - current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under - congestion control, so a huge target costs no more than one just above the - estimate. Clamp it to the session's rate cap where one exists - ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. -- **Automatic, opt-out.** Targets are on by default; an application can - override the session's target or disable probing. -- **The sender seam.** Define the hook a transport implements to probe up to a - rate, and advertise `Increase` in SETUP only when the session has a sender - behind it. [Native](/quest/m2/probe/native.md) implements it in moq-quic, - and [padding](/quest/m2/probe/padding.md) is the fallback for transports - that don't. This quest only needs a test sender. - -Notes for the implementer: - -- `js/net` already owns its connection's `Allocator` - (`js/net/src/connection/reload.ts`), but Rust callers build one from - `send_bandwidth()` themselves (`rs/moq-cli`, `rs/moq-c`, `rs/moq-ffi`), so - the session can't see their reservations. Settle who owns the Rust - allocator, and keep it across reconnects the way the estimate is. -- Rust sessions request PROBE today only while an owned `recv_bandwidth()` - consumer is held (`doc/concept/standard.md`); the viewer handle may subsume - that. -- Wire: none. PROBE already carries a target and SETUP the `Increase` level - (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). - Report the public API in the PR, mirrored across Rust and JS, and carry it - through moq-ffi and the bindings per the cross-package sync table. - -Tests with mocked time, Rust and JS: the send target follows reservations -being added, updated, and dropped, demanded or not; viewer handles sum into -the PROBE target sent to the peer; the session probes to the larger of its -reservations and the peer's target; a session that publishes and watches -keeps the two directions apart; viewer grants split the receive estimate -max-min fair by `max` and never sum above it; `Increase` is advertised only with a sender; -opting out sends no target and probes nothing. - -The sums fan out over reservations and viewer handles, so add a benchmark -sweeping both counts independently, wired into the benchmark CI, so an update -that rescans every handle shows up as a slope. diff --git a/quest/m2/probe/viewer-target.md b/quest/m2/probe/viewer-target.md new file mode 100644 index 00000000000..92f6cb12a12 --- /dev/null +++ b/quest/m2/probe/viewer-target.md @@ -0,0 +1,92 @@ +# [M] Viewer probe targets and grants + +## Goal + +A moq-net session and a `js/net` connection each keep a receive target: the +sum of their viewer handles, sent to the peer as the PROBE target. A sending +session probes to the larger of its own [send target](/quest/m1/probe-target.md) +(in `js/net`, the one [padding](/quest/m2/probe/padding.md) adds) and the +peer's PROBE target, and advertises PROBE `Increase` where it has a +sender. The two directions never mix: a session that publishes and watches +doesn't probe its uplink for what it watches. + +Each viewer handle also reads a grant: its share of the session's receive +estimate, so several broadcasts watched over one connection each select +against their own share instead of the whole downlink. + +## Plan + +Split from the [send target](/quest/m1/probe-target.md) by the maintainer on +2026-10-20: m1 native rung recovery needs only the send target, while these +handles' consumers ([players](/quest/m2/probe/players.md) and the +[viewer up-switch](/quest/m2/probe/viewer-upswitch.md)) are in m2. + +Decided with the maintainer on 2026-10-17 (see the +[epic](/quest/m2/probe/README.md)): + +- **A viewer handle per broadcast.** The subscriber session hands out a + reservation-like handle carrying a `max`, one per watched broadcast; the + session sums the live handles and sends the sum as its PROBE target. + Updating or dropping a handle changes the sum. Rejected: one target the + application sums, which pushes the multi-broadcast case onto every app. + Players hold these handles. +- **Viewer grants.** Decided with the maintainer on 2026-10-19: a viewer + handle carries a grant the way a publisher `Reservation` does, splitting the + receive estimate across live handles max-min fair by `max`, the split the + send `Allocator` applies within one priority tier + (`rs/moq-net/src/model/bandwidth.rs`). A handle asking for less than an even + cut takes all of it and leaves the rest to the others. Today every + `` on a pooled connection selects against 0.8x the whole + `estimatedRecvRate`, so N watchers over-select about N times. Rejected: each + watcher measuring its own subscription's rate, which stays app-limited and + can't see headroom, and dividing the estimate by the watcher count, which + ignores each handle's `max`. + Handles carry no priority: subscription priorities are per track and fixed + by kind, so no per-broadcast priority exists to divide by. Add one when a + player needs to favor one broadcast over another. +- **Peer target.** A sending session probes to the larger of its own target + and the peer's PROBE target. Each hop is independent: a relay never forwards + a viewer's target upstream, and the PROBE target stays per connection, with + no per-track wire field. moq-net reads no catalog. A peer's target is + untrusted, but it only sets how high to probe: each probe scales the + current estimate (BBR's 1.25x phase, padding's 2x cluster) and stays under + congestion control. Repeated cycles can still walk the estimate up to the + path's capacity, so a huge target costs the redundant bytes of probing that + far, held to the overhead budget [native](/quest/m1/probe-native.md) sets + before tuning; a peer that subscribes to more media can already cost the + sender that much. Clamp it to the session's rate cap where one exists + ([rate grant](/quest/m2/rate-grant.md)) rather than adding a constant. +- **`Increase` only with a sender.** SETUP advertises `Increase` only when + the session has a sender behind the seam the send target defines: native + probing on moq-quic, padding in the browser. A browser session on a version + [padding](/quest/m2/probe/padding.md) refuses (lite-05, lite-06, IETF + drafts 14 to 17) has none, so it keeps `Report`. +- **Automatic, opt-out.** Targets are on by default; an application can + override them or disable probing. + +Notes for the implementer: + +- Rust sessions request PROBE today only while an owned `recv_bandwidth()` + consumer is held (`doc/concept/standard.md`). If the viewer handle subsumes + that, migrate those callers in the same change; a held consumer never + silently stops requesting PROBE. +- Wire: none. PROBE already carries a target and SETUP the `Increase` level + (`drafts/draft-lcurley-moq-lite.md`, `drafts/draft-lcurley-moq-probe.md`). + Report the public API in the PR, mirrored across Rust and JS, and carry it + through moq-ffi and the bindings per the cross-package sync table. + +Tests with mocked time, Rust and JS: viewer handles sum into the PROBE target +sent to the peer; the session probes to the larger of its reservations and +the peer's target; a session that publishes and watches keeps the two +directions apart; viewer grants split the receive estimate max-min fair by +`max` and never sum above it; `Increase` is advertised only with a sender, and never by a browser session +on a version padding refuses; +opting out sends no target. + +The sum fans out over viewer handles, so add a benchmark sweeping their count, +wired into the benchmark CI, so an update that rescans every handle shows up +as a slope. + +## Required + +- [Session send target](/quest/m1/probe-target.md) - the sender seam and the local target the peer's is compared against diff --git a/quest/m2/probe/viewer-upswitch.md b/quest/m2/probe/viewer-upswitch.md index 1713d5ac940..7471d2f5656 100644 --- a/quest/m2/probe/viewer-upswitch.md +++ b/quest/m2/probe/viewer-upswitch.md @@ -19,15 +19,16 @@ estimate. Decided with the maintainer on 2026-10-17: this joined the [probe epic](/quest/m2/probe/README.md). [Players](/quest/m2/probe/players.md) -set the viewer target, the [session](/quest/m2/probe/target.md) sends it as +set the viewer target, the [session](/quest/m2/probe/viewer-target.md) sends it as its PROBE target, and the relay's sender probes the downlink up to it; this quest makes selection act on the estimate that rises. The relay runs -moq-quic, so it requires [native probing](/quest/m2/probe/native.md); if that -ends in a measured no-go, require [padding](/quest/m2/probe/padding.md) -instead rather than leaving this blocked. +moq-quic, so it requires [native probing](/quest/m1/probe-native.md). If that +ends in a measured no-go, take this back to the maintainer rather than +leaving it blocked: [padding](/quest/m2/probe/padding.md) is browser-only +since 2026-10-20, so the relay has no other sender. Selection reads its broadcast's viewer grant from the -[target](/quest/m2/probe/target.md) quest, not the connection's whole +[viewer targets](/quest/m2/probe/viewer-target.md) quest, not the connection's whole `estimatedRecvRate`, so several watchers on one pooled connection don't each select against the full downlink (decided with the maintainer on 2026-10-19). @@ -38,8 +39,8 @@ and audio, or selection stops discounting a probed estimate. ## Required -- [Session probe target](/quest/m2/probe/target.md) - the viewer handle the session sends as its PROBE target -- [Native probing](/quest/m2/probe/native.md) - the relay validates headroom above the media it sends +- [Viewer targets](/quest/m2/probe/viewer-target.md) - the viewer handle the session sends as its PROBE target, and the relay probing up to it +- [Native probing](/quest/m1/probe-native.md) - the relay validates headroom above the media it sends - [Players set viewer targets](/quest/m2/probe/players.md) - `@moq/watch` asks for its highest enabled rendition ## Closes diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index 134c89dc161..cf2a7826da6 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -108,4 +108,4 @@ separately; it does not adopt any of them in advance. ## Related - [TS validation](/test/ts/README.md) - shaped paths, whole-group shedding, and measured baselines -- [Native probing](/quest/m2/probe/native.md) - preserving an estimate and discovering spare capacity are separate problems +- [Native probing](/quest/m1/probe-native.md) - preserving an estimate and discovering spare capacity are separate problems diff --git a/quest/m2/quic-deadline.md b/quest/m2/quic-deadline.md index 9222b1cd289..6473519d4b2 100644 --- a/quest/m2/quic-deadline.md +++ b/quest/m2/quic-deadline.md @@ -53,12 +53,14 @@ retransmitted past their deadline (must be zero), spurious resets under reordering, and probe overhead versus the default PTO. A proactive probe that raises loss or latency under any profile stays off by default. -Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. +Decided in the 2026-09-30 audit: moved to m2. No m1 quest needs it: +[native probing](/quest/m1/probe-native.md) learns of expiry from the stream +reset moq-net already sends. ## Related - [QUIC receive-timestamps spike](/quest/m2/quic-realtime/receive-ts.md) - measures whether receive-time differences improve an explicit delay estimator over half-RTT - [ACK hook](/quest/m2/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic` -- [Native probing](/quest/m2/probe/native.md) - retransmits in-flight data +- [Native probing](/quest/m1/probe-native.md) - retransmits in-flight data to probe, and must not resend what a deadline has expired diff --git a/quest/m3/README.md b/quest/m3/README.md index 00e5db6741f..b97158d639d 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -63,6 +63,7 @@ m4's upstream waits in here and moved m2 work with no consumer. - [MSFTS convergence](/quest/m3/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where they differ, once an MSFTS implementer engages - [#2279](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [CEA-608/708](/quest/m3/captions-cea.md) - captions carried inside video SEI become a real text rendition at import +- [WebXR playback](/quest/m3/watch-webxr.md) - `` renders equirectangular and stereo renditions through WebXR layers on a headset - [Paced replay](/quest/m3/archive-paced-replay.md) - an archive consumer pushes stored groups to live subscribers on one shared clock, so any live player plays it - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder reads its viewers' feedback and adapts its bitrate diff --git a/quest/m3/watch-webxr.md b/quest/m3/watch-webxr.md new file mode 100644 index 00000000000..b3ce89065ca --- /dev/null +++ b/quest/m3/watch-webxr.md @@ -0,0 +1,34 @@ +# [M] The watch element renders spatial video through WebXR layers + +## Goal + +On a headset browser with WebXR layers, `` presents a rendition +whose catalog says `projection: equirectangular` in an immersive session +through an `XREquirectLayer`: the horizontal span comes from `fov`, and the +layer layout from `stereo`, mapping `left-right` to `stereo-left-right`, +`top-bottom` to `stereo-top-bottom`, and `mono` or absent to `mono`. A flat +rendition, and a browser without WebXR layers, play as today. + +## Plan + +Decided with the maintainer on 2026-10-20, from the follow-ups of +[#5543](https://github.com/moq-dev/moq/pull/5543), which landed the fields. + +- `XRMediaBinding` layers take an `HTMLVideoElement`, which `` + does not use (it decodes with WebCodecs), so an `XRWebGLBinding` layer fed + each decoded frame is the likely path. Check whether a WebGPU XR binding is + usable yet. +- Entering an immersive session needs a user gesture, so the UI offers it + only when the browser supports layers and the rendition is spatial. +- Ambisonic audio playback is out of scope; propose it as a follow-up. + +Tests: a mocked XR session checks the layer each catalog produces, all three +layouts included, and is wired +into CI; a manual run on a headset browser proves playback. + +Public API: possibly a `` attribute to enter or disable immersive +playback. Wire: none. + +## Related + +- [moq-mux importers fill the VR fields](/quest/m2/mux-vr-fields.md) - native sources that carry these fields