diff --git a/quest/m0/README.md b/quest/m0/README.md index 884cffb42f1..de0fb0ff338 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -66,5 +66,6 @@ remain and no release waits on them. - [Idle fronts](/quest/m0/idle-fronts.md) - a front nobody has read for the linger ends with its per-path state, so a standing claim stops accumulating fronts and sources - [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on moq-dev/web-transport#412 and #413 to merge and ship, which qmux credit bumps to - [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines +- [JS track takeover](/quest/m0/js-track-takeover.md) - JS `createTrack` answers a queued request and continues its sequences, as Rust does, so a re-announced `@moq/publish` catalog never restarts its groups - [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh route epoch, the newest wins a path, and only routes with the same epoch resume a subscription - [moq-noq 2.0.2 on main](/quest/m0/noq-2.0.2.md) - `main` carries the max datagram size fix `release` gets in 1.3.4 diff --git a/quest/m0/broadcast-epoch/publish-catalog-restart.md b/quest/m0/broadcast-epoch/publish-catalog-restart.md index 4c4b80fda48..251f0a0c3d2 100644 --- a/quest/m0/broadcast-epoch/publish-catalog-restart.md +++ b/quest/m0/broadcast-epoch/publish-catalog-restart.md @@ -22,11 +22,15 @@ re-announce. `js/publish/src/broadcast.ts` mints the epoch once and keeps the publisher across unannounce and announce on purpose, which points at continuing the sequence. -#4929 (merged) made an on-demand producer continue a name's sequences -across replacements in both languages, but JS `createTrack` and -`insertTrack` still start at 0 (`doc/lib/js/net.md`). If this reproduces, -consider fixing it there, in `@moq/net`'s `createTrack`, so every JS -publisher continues the sequence, rather than in `@moq/publish` alone. +Decided 2026-10-08: the `@moq/net` fix belongs to +[JS track takeover](/quest/m0/js-track-takeover.md), so every JS publisher +continues a name's sequences; this quest does not fix `createTrack` itself. +Re-run the test once it lands and fix `@moq/publish` only if it still +restarts. Public API: none expected. Wire: none. +## Required + +- [JS track takeover](/quest/m0/js-track-takeover.md) - JS `createTrack` and `insertTrack` continue a name's sequences, which fixes the restart at its source + diff --git a/quest/m0/broadcast-epoch/restart.md b/quest/m0/broadcast-epoch/restart.md index 52ba06ce794..07ff434a62c 100644 --- a/quest/m0/broadcast-epoch/restart.md +++ b/quest/m0/broadcast-epoch/restart.md @@ -171,12 +171,13 @@ the downstream relay gets a `Restart` of `pool` (END then START on lite-06), dro the nested paths, and the next subscribes reach the right workers, the moved path on its new worker and the rest on theirs. Run `just drafts check` and `just test interop --all`. -Docs: open PR #5033 rewrites the publisher-restart docs to match today's -hard switch; land it first, then update `doc/concept/moq-lite.md` (publisher -epochs), the `doc/lib/{rs,js}` announce sections, and the gateway and -cluster pages under `doc/bin` wherever they still describe the hard switch -(a reconnect replacing the stale viewer, stale subscriptions ending with -`Unroutable`, a flapping lite-07 link cutting viewers). +Docs: #5033 (merged) rewrote the publisher-restart docs to match today's +hard switch. Update `doc/concept/moq-lite.md` (publisher epochs), the +`doc/lib/{rs,js}` announce sections, and every page that still describes the +hard switch (a reconnect replacing the stale viewer, stale subscriptions +ending with `Unroutable`, a flapping lite-07 link cutting viewers): +`doc/bin/rtmp.md`, `doc/bin/srt.md`, `doc/bin/cli.md`, and +`doc/setup/upgrade.md`. Public API: breaking, a new `AnnounceEvent::Restart` variant (Rust) and `"restart"` kind (JS). Wire: a new lite-07 announce message; older versions diff --git a/quest/m0/broadcast-epoch/stats-split.md b/quest/m0/broadcast-epoch/stats-split.md index b0c33d1fda0..b633b022a69 100644 --- a/quest/m0/broadcast-epoch/stats-split.md +++ b/quest/m0/broadcast-epoch/stats-split.md @@ -96,10 +96,9 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): - **Sessions** (decided 2026-10-05). `sessions.json` is keyed by auth root and loses pruned roots the same way, so fold per-tier `Presence` into the totals (session counts) and serve per-root detail as a requested track, - the same model as prefix tracks. Open PR #5046 (session outcomes) adds to - `sessions.json`, which this retires; it is rewritten against these totals - and the per-root requested track, and lands after this (decided - 2026-10-08). + the same model as prefix tracks. + [Session outcomes](/quest/m1/session-outcomes.md) Requires this and rides + these totals and the per-root requested track (decided 2026-10-08). - **Retire the map tracks** (`publisher.json`, `subscriber.json`, `sessions.json`, and their `.json.z` siblings) in the same release. Decide while implementing whether totals and prefix tracks keep `.json.z` @@ -113,7 +112,9 @@ Decided 2026-10-05 (planned from moq-dev/moq.pro#2202): same format it reads. Decided 2026-10-08: if prefix tracks and self counters hold up the rest, -split them into a follow-up quest and land totals and sessions first. The +split them into a follow-up quest and land totals and sessions first; the +per-root requested track stays in the first release, since session outcomes +rides it and `sessions.json` retires with it. The per-path map retirement moves with prefix tracks and self counters into that follow-up: the maps are the only per-path source until prefix tracks exist, and moq.pro's Broadcasts page reads prefix tracks the moment the maps retire, @@ -130,4 +131,5 @@ customer stats feed serves this format summed across nodes. - [Media stats](/quest/m1/stats/README.md) - publisher and viewer media stats stay hang tracks, separate from the relay's stats +- [Session outcomes](/quest/m1/session-outcomes.md) - adds refusal and end counters to the totals and per-root track this introduces - [QoS](/quest/m1/qos/README.md) - stats-split lands first; the egress lag histogram split out of #4133 requires it and rebases onto the totals and prefix tracks diff --git a/quest/m1/js-track-takeover.md b/quest/m0/js-track-takeover.md similarity index 88% rename from quest/m1/js-track-takeover.md rename to quest/m0/js-track-takeover.md index 4db7d467ff0..84ca2b8c1b7 100644 --- a/quest/m1/js-track-takeover.md +++ b/quest/m0/js-track-takeover.md @@ -10,6 +10,10 @@ sequences that were written within the broadcast. ## Plan +Decided 2026-10-08: moved to m0, since +[publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) +gates the release and its fix is this one. + Decided 2026-10-06 while settling #4929: that PR coalesces JS publishing-side subscriptions per name and accepts the `duplicate track` throw for now; this quest brings JS to parity. Drop unused entries only when no track holds them diff --git a/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md b/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md index f8dbd0bcb9e..4a34d8e3e9c 100644 --- a/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md +++ b/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md @@ -11,18 +11,18 @@ sideways. ## Plan The rest of #933 is done: the renderer applies `catalog.video.rotation` -(`js/watch/src/video/renderer.ts:187-198`) and file import rotates stored -footage (`js/publish/src/source/file.ts:283`, `:303-305`). Live camera capture -never sets the field. +(`#render` in `js/watch/src/video/renderer.ts`) and file import rotates stored footage +(`rotator` in `js/publish/src/source/file.ts`). Live camera capture never sets +the field. -- Add `rotation: Getter` beside `flip` in the broadcast inputs - (`js/publish/src/broadcast.ts:25-26`) and write `section.rotation` next to - `section.flip` (`:178`). +- Add `rotation: Getter` beside the `flip` input in + `js/publish/src/broadcast.ts` and write `section.rotation` next to + `section.flip`. - Detect orientation in `js/publish/src/source/camera.ts` (the track's settings, `screen.orientation`, or `VideoFrame.rotation`) and re-publish on change. - Wire the signal through `` beside `#flip` - (`js/publish/src/element.ts:121-122`). + (`js/publish/src/element.ts`). - `demo/web` sets neither `flip` nor `rotation`, so nothing changes there. Additive on `@moq/publish`, so it lands on main. diff --git a/quest/m1/README.md b/quest/m1/README.md index d39e15b6875..c71ef10325b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -54,35 +54,35 @@ were done or not worth their cost. - [Hang changelog](/quest/m1/hang-changelog-04.md) - the hang draft lists under -03 only what -03 published - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it - [lite-07 Live flag](/quest/m1/lite-live.md) - a separate `Live` field on lite-07 SUBSCRIBE, so merged floors never starve a subscriber; late lower groups build on it +- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are +- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - our FETCH_OK carries the track properties SUBSCRIBE_OK does, as draft 16+ requires - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges in either order and replaces FETCH; relays fill misses by range, including over moq-transport - [Cross-relay bursts re-run](/quest/m1/cross-relay-bursts.md) - condition: the #4349 reporter re-runs their A/B/C comparison against current cdn.moq.pro - [Cross-relay FETCH on any peer link](/quest/m1/ietf-peer-fetch-old.md) - a lite or moq-transport peer link serves held groups instead of refusing them as old, and the drill covers both - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does - [Flate stream budget](/quest/m1/flate-stream-budget.md) - a flate stream refuses an oversized append without ending, sharing one DEFLATE bound with json -- [JS track takeover](/quest/m1/js-track-takeover.md) - JS `createTrack` answers a queued request and continues its sequences, as Rust does - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets - [Dogfood hosted worklets](/quest/m1/dogfood-assets.md) - moq.dev and the moq.pro dashboard host the worklets and call `assets()` after the release - [Media audio-tone check](/quest/m1/media-audio-tone.md) - the media lane's audio-tone check passes under load, fixed at its cause - [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 - [moq-uring tests under load](/quest/m1/uring-tests-under-load.md) - uring tests pass while parallel checks share locked memory -- [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi and moq-c drive moq on a multi-thread runtime instead of one thread +- [FFI runtime](/quest/m1/ffi-runtime.md) - moq-ffi drives moq on a multi-thread runtime instead of one thread - [Audio group duration](/quest/m1/audio-group-duration.md) - audio groups span at least 20 ms by default, so small frames don't mint a group each - [Browser interop cells](/quest/m1/interop-browser-timeouts.md) - `go -> js` and `python -> js` pass, fixed at the cause rather than by a longer timeout - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Kotlin wrapper POMs](/quest/m1/kt-ffi-pom.md) - Maven builds of `dev.moq:moq` resolve a published moq-ffi instead of the missing `0.0.0-dev` -- [Homebrew moq-gst](/quest/m1/gst-brew-path.md) - `brew install moq-gst` installs the plugin from the tarball's `lib/gstreamer-1.0/` +- [Installable moq-gst](/quest/m1/gst-brew-path.md) - `brew install moq-gst` installs the plugin from the tarball's `lib/gstreamer-1.0/`, and the Nix package carries `x264enc`, `avenc_aac`, and `avdec_h264` - [Same-epoch importers](/quest/m1/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives - [moq.sh deploys from CI](/quest/m1/moq-sh-deploy.md) - the first `release` run of the moq.sh workflow deploys with the Workers Editor token - [Plan: untimed verbatim PES](/quest/m1/plan-ts-pes-untimed.md) - decide how a verbatim TS track carries a PES that has no PTS, then write the implementation quest - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()` - [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - @moq/json and @moq/flate consumers return each value's timestamp, with snapshot `next()` and `latest()` -- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are -- [FETCH_OK properties](/quest/m1/fetch-ok-properties.md) - our FETCH_OK carries the track properties SUBSCRIBE_OK does, as draft 16+ requires - [IETF object gaps](/quest/m1/ietf-object-gaps.md) - a gapped object ID is refused loudly like a subgroup in Rust and JS, and an overflowing one closes the session in Rust - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [Relay session limits](/quest/m1/relay-session-limits.md) - moq-relay sets per-session request limits, tighter for clients than peers, and the bindings name a refused request - [Churn with held subscriptions](/quest/m1/session-churn-held.md) - opening and closing a request costs the same with 1 or 1,024 held subscriptions +- [Catalog track identity](/quest/m1/catalog-tracks.md) - a track's codec and description never change for its name; resolution changes in band below ceilings fixed at creation, and anything else mints a new rendition or epoch - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Claim epochs](/quest/m1/claim-epochs.md) - a lite-07 claim's answer carries its broadcast's epoch, so a worker restarting an output under an unchanged claim route is a new source; moved from m0 on 2026-10-08 since lite-07 is opt-in @@ -106,10 +106,10 @@ were done or not worth their cost. - [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 - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms - [Session outcomes](/quest/m1/session-outcomes.md) - the relay's session stats count refusals by reason and ends by kind, per root and tier +- [Typed refusal reason](/quest/m1/refusal-reason.md) - an auth server's 403 names the reason (including `expired`) and the root and tier, so the relay's session outcomes count and attribute refusals - [Catalog rendition IDs](/quest/m1/catalog-track-id.md) - catalog rendition keys become IDs unique across video and audio, with an optional `track` name, so one catalog lists renditions from several broadcasts - [Media stats](/quest/m1/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 - [JS track handover](/quest/m1/js-group-handover.md) - a JS track subscription resumes across a route swap from the first frame it lacks, so `test/drain` passes at zero latency budget -- [JS startup hole](/quest/m1/js-startup-hole.md) - a `@moq/hang` consumer delivers its first live group at once, even when an empty group died before it - [Drain handshakes](/quest/m1/drain-handshakes.md) - a drain GOAWAYs and waits for sessions still in their handshake instead of exiting under them - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over without dropping a group - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants @@ -132,7 +132,7 @@ were done or not worth their cost. - [io_uring handshake deadline](/quest/m1/listener-deadlines.md) - the io_uring workers apply `listen.timeout` to the handshake - [HTTP listener deadlines](/quest/m1/listener-deadlines-http.md) - the HTTPS and internal listeners drop a connection with no request in flight for `listen.timeout` - [iroh keep-alive](/quest/m1/iroh-keep-alive.md) - the iroh backend honors `quic.keep_alive` -- [Rust papercuts](/quest/m1/papercuts-rs.md) - HTTP refusals are counted, a `u64::MAX` resume is unbounded, GOING_AWAY falls forward, and GRO stride 0 cannot panic +- [Rust papercuts](/quest/m1/papercuts-rs.md) - HTTP refusals are counted, and a `u64::MAX` resume is unbounded - [JS papercuts](/quest/m1/papercuts-js.md) - IETF status 0 keeps the subgroup open, a muted rendition change settles, and bad element attributes warn - [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [Route wakes](/quest/m1/route-wakes.md) - a route change wakes only the fronts it can move, so pool churn stops scaling with served paths diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index 1b7d0286050..5fc4a7ec3ab 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -172,5 +172,5 @@ owned by that prerequisite, not duplicated in archive storage. ## Related -- [Catalog track identity](/quest/m2/catalog-tracks.md) - a track's definition never changes for its name, so any recorded catalog describes every group of the tracks it lists +- [Catalog track identity](/quest/m1/catalog-tracks.md) - a track's definition never changes for its name, so any recorded catalog describes every group of the tracks it lists - [e2ee](/quest/m1/e2ee/README.md) - protected broadcasts are excluded initially diff --git a/quest/m1/archive/replay-catalog.md b/quest/m1/archive/replay-catalog.md index 643e4ab942a..b658701e423 100644 --- a/quest/m1/archive/replay-catalog.md +++ b/quest/m1/archive/replay-catalog.md @@ -9,10 +9,24 @@ its recorded catalog live, stamped with the recording's `store` and `version`, so an exporter in history mode treats its timeline as durable and lists past `--window`. A `--follow` replay grows like an event playlist. -A track's definition never changes for its name -([Catalog track identity](/quest/m2/catalog-tracks.md)), so the newest -recorded catalog describes every group of the tracks it lists; nothing here -picks a catalog per group. +[Catalog track identity](/quest/m1/catalog-tracks.md) guarantees a track's +identity never changes for its name, and resolution changes in band below +its ceilings, so one catalog describes every group of the tracks it lists; +nothing here picks a catalog per group. + +Decided 2026-10-08 (review): the catalog at the live edge is the union of +every rendition recorded, so a rendition removed mid-recording stays +discoverable; one no longer live is listed with `enabled: false`. VOD +consumers (HLS archive mode, DVR) list a rendition that has recorded media +regardless of `enabled`; live watch keeps filtering disabled ones. HLS +segments every playlist from one reference rendition (`reference()` in +`rs/moq-hls/src/export/mod.rs`), so when the reference's recording ends +while another continues, archive mode advances the reference to the +continuing one without dropping earlier rows, or the union stalls the +playlist at the old rendition's end. Paced +replay (m3) replays the catalog history instead. Test a rendition removed +before the recording ends, including the reference while another +continues: both the first segment and the tail stay listed. ## Plan @@ -21,9 +35,8 @@ is FETCH-only, so a SUBSCRIBE to it on the replay broadcast never sees a group and `moq-hls` never finds the `archive` entry. The HLS archive tests work around this by hand-building a catalog. -- Republish each recorded catalog group live in its timeline's order, so the newest - one is at the live edge and a `--follow` replay picks up catalogs recorded - after it opened. +- Republish the recorded catalog live as that union, updated in timeline + order so a `--follow` replay picks up renditions recorded after it opened. - Stamp `store` with the URL passed to `import archive`, and `version` with the recording format. Refuse a URL carrying userinfo and strip its query so credentials never land in a catalog, and let the importer opt out of @@ -69,4 +82,5 @@ loudly on a recording with no catalog. ## Required +- [Catalog track identity](/quest/m1/catalog-tracks.md) - the guarantee that one recorded catalog describes every group - [History from the start](/quest/m1/archive/replay-history.md) - history mode lists a recording from its start, which "lists the whole recording" needs diff --git a/quest/m1/audio-jitter-target/watch.md b/quest/m1/audio-jitter-target/watch.md index 543af19a990..d3d0bc88d7a 100644 --- a/quest/m1/audio-jitter-target/watch.md +++ b/quest/m1/audio-jitter-target/watch.md @@ -49,9 +49,11 @@ about 22 s with skip-aheads on the way down. 88 to 275 ms/s drift the issue reported stand unconfirmed. If drift survives, the suspects are `writeFrame` opening a group per audio frame under WebTransport stream credit and the main-thread task queue delivering encoder - output. The audio encoder's `groupDuration` (#4910, default 0: a group per - frame) tests the first: A/B it against a group of 100 ms or so in the same - run. Turn that into its own quest rather than fixing it here. + output. The first suspect is now owned by + [audio group duration](/quest/m1/audio-group-duration.md), which defaults + `groupDuration` to 20 ms. A/B the default against a group of 100 ms or so + in the same run; once that quest lands, the baseline is 20 ms groups, not a + group per frame. Decided 2026-10-08: moves to m1 with the rest of the line. The estimator defaults on and only this manual proof is left, so it no longer gates a @@ -59,4 +61,5 @@ release. ## Related +- [Audio group duration](/quest/m1/audio-group-duration.md) - owns the group-per-frame suspect and changes this run's A/B baseline - [A/V clock](/quest/m1/av-clock.md) - reshapes `SyncInput` around the per-track target this line produces diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index 21c8575b6d5..d9be181e769 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -95,7 +95,6 @@ published version in place, so AUTH and its stream code land in ## Required - [WebSocket refusal](/quest/m1/auth/ws-unauthorized.md) - the relay serves WebSocket through moq-tokio, so a refused token closes the session as Unauthorized, as QUIC does -- [AUTH on the wip version](/quest/m1/auth/wip-version.md) - lite AUTH and UNAUTHORIZED move from lite-06 to `moq-lite-07-wip`, so no published version changes in place - [Lite NOT_SUPPORTED](/quest/m1/auth/not-supported.md) - a lite acceptor answers AUTH_ERROR NOT_SUPPORTED after a grant too, with a lite session code for `Error::Unsupported` - [AUTH violations](/quest/m1/auth/violations.md) - every AUTH protocol violation closes the session in Rust and JS, lite and IETF - [Malformed grant](/quest/m1/auth/malformed-grant.md) - a malformed or @@ -112,9 +111,6 @@ published version in place, so AUTH and its stream code land in - [WebTransport transport](/quest/m1/auth/webtransport-transport.md) - an auth decider sees `webtransport` for a WebTransport session and `quic` only for native QUIC -- [Typed refusal reason](/quest/m1/auth/refusal-reason.md) - an auth - server's 403 names the reason (including `expired`) and the root and tier, - so the relay's session outcomes count and attribute refusals - [Bindings](/quest/m1/auth/bindings.md) - grants and tokens reach every binding through moq-ffi - [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index aeae78291cc..98db62feb42 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -18,9 +18,9 @@ request token authorizing its own request (the fallback after the session grant, refresh by REQUEST_UPDATE, and a per-request relay lease on `moq_auth::Client`) is deferred until a moq-transport peer needs it; re-plan it then from [#4675](https://github.com/moq-dev/moq/pull/4675), which built -it. #4675 is too large to review as one change, so it splits: the -decode-and-close part lands first as this quest, and the grant and lease work -parks on its branch. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) +it. #4675 was too large to review as one change and closed unmerged; its +branch is gone, so the grant and lease work survives only at its head commit +`29ed74e78`. The decode-and-close part lands as this quest. The decode needs neither [Relay tokens](/quest/m1/auth/relay-refresh.md) nor a lease. - Decode with the SETUP option's structure and rules @@ -44,11 +44,11 @@ nor a lease. same per-message decode. - 0x13 and 0x17 join the shared session registry: `SessionError` (`rs/moq-net/src/error.rs`) and `SessionCode` (`js/net/src/error.ts`). - Lite codes below 32 carry moq-transport's meaning, so add both rows to the - Session Error Codes table in `drafts/draft-lcurley-moq-lite.md` and to - `session_codes_round_trip`, as [Malformed moq-transport - input](/quest/m2/ietf-malformed-close.md) does for its codes. No - per-version mapping. That adds two codes to moq-lite's wire registry. + That registry is moq-lite's too, and lite codes below 32 carry + moq-transport's meaning, so add both rows to the Session Error Codes table + in `drafts/draft-lcurley-moq-lite.md` and to the + `session_codes_round_trip` test. No per-version mapping. That adds two + codes to moq-lite's wire registry. - `js/net` mirrors the decode. - Tests, one legacy and one strict draft, Rust and JS: a `REGISTER` token on a request closes with `AUTH_TOKEN_CACHE_OVERFLOW`, a `DELETE` or diff --git a/quest/m1/auth/wip-version.md b/quest/m1/auth/wip-version.md deleted file mode 100644 index 7f6d064d047..00000000000 --- a/quest/m1/auth/wip-version.md +++ /dev/null @@ -1,39 +0,0 @@ -# [M] AUTH on the wip lite version - -## Goal - -The lite Auth Stream (0x7) and the 0x3B UNAUTHORIZED stream code exist only -on the wip lite version (`moq-lite-07-wip` today), in Rust, JS, the draft, -and the interop matrix. A lite-06 session never opens or accepts an Auth -Stream, so no published version changes in place. - -## Plan - -The line built AUTH on lite-06 before the maintainer decided on 2026-10-05 -that wire work targets the wip version until it is cut, never a published -version (see the README and [Finalize moq-lite-07](/quest/m1/lite07-finalize.md)). -The gate is one predicate on each side: `Version::has_auth` -(`rs/moq-net/src/lite/version.rs`) and `hasAuth` (`js/net/src/lite/version.ts`). - -- Make both false for lite-06; the URL credential already covers peers - without the stream, so a lite-06 session keeps working on its URL token. -- Move the Auth Stream and UNAUTHORIZED entries in - `drafts/draft-lcurley-moq-lite.md` from the lite-06 changelog to lite-07's, - and run `just drafts check`. -- Tests that negotiate the default version for AUTH must ask for - `moq-lite-07-wip` explicitly, since the default version sets leave it out: - `rs/moq-net/tests/auth.rs` (`LITE_06`), `js/net/src/auth.test.ts`, - `rs/moq-relay/tests/auth_lifetime.rs`, and the AUTH rounds of - `test/interop/interop.sh`. Add one test per language that a lite-06 session - has no grant and opens no Auth Stream. -- Check the docs (`doc/concept`, `doc/lib/rs/moq-net.md`, `doc/lib/js/net.md`) - name the wip version, not lite-06. -- Renumber UNAUTHORIZED from 0x3A to 0x3B in Rust, JS, and the draft - (decided 2026-10-08): `main` gave 0x3A to NOT_FETCHABLE. - -Public API: none. Wire: AUTH and UNAUTHORIZED leave lite-06; the line has not -landed, so no released peer speaks them there. - -## Related - -- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - the cut that publishes AUTH with lite-07 diff --git a/quest/m1/catalog-tracks.md b/quest/m1/catalog-tracks.md new file mode 100644 index 00000000000..fb6817cc946 --- /dev/null +++ b/quest/m1/catalog-tracks.md @@ -0,0 +1,79 @@ +# [M] Catalog track identity + +## Goal + +A track's catalog identity never changes for its name, so live and recorded +playback never guess which configuration applies to a group. Identity is the +codec and its description, plus anything else a decoder must be configured +with (audio sample rate and channel count). `codedWidth` and `codedHeight` +are ceilings fixed when the track is created: resolution changes in band +below them, and the codec string advertises the level the ceiling needs. +`bitrate` and `framerate` are the maximum so far, which only rises. A change +to identity, or past the coded size, publishes a new rendition name or a new +broadcast epoch instead of mutating the track. Live state (`enabled`, the +jitter and delay figures, `warmup`, a rise in `bitrate` or `framerate`) +changes freely +under the same name, as do the broadcast-level display properties +(`display`, `rotation`, `flip`), which describe presentation, not decoding. + +## Plan + +Decided in the 2026-09-30 audit: track identity is immutable. Mutable +definitions with a configuration identity that groups reference (the old +option 2) are out, because they contradict the rule that a track name always +means the same content, and MoQ has no ETag-style invalidation. + +Decided 2026-10-08: identity versus ceilings versus live state, as in the +Goal, and moved to m1 ahead of the archive line, since a replayed catalog +relies on it. Reasons: + +- Resolution must change without a new name: VP8, VP9, and AV1 keyframes + carry their size, and H.264/H.265 carry it in in-band parameter sets + (avc3/hev1). A `description` holding parameter sets pins the resolution, so + that track changes it only by minting a new identity. CMAF keeps its + exception (`doc/concept/hang.md`): an avc3/hev1 CMAF track keeps a + configuration record with no parameter sets as its `description` for the + NAL length size, which is framing, not resolution. +- Ceilings let a decoder be configured once for the largest picture, so a + smaller one never needs a catalog update. +- Decided 2026-10-08 (review): `bitrate` and `framerate` are monotone + maxima. An encoding publisher declares its configured cap. An importer + that cannot know them up front may only raise them, as moq-mux's + estimator's running max does today (`rs/moq-mux/src/catalog/estimate.rs`), + and a rise is a live-state update, never a new identity, since neither + configures a decoder. Updates stay rare because the maximum converges. + Watch's selection (`js/watch/src/video/source.ts`) and HLS `BANDWIDTH` + read the current value, so a quiet start never understates a rendition + for good. An importer fills unknown coded dimensions once from the first + keyframe (`catalog/tracks.rs`); growth past them mints a new identity. + Test: a quiet-start import that rises to a sustained 5 Mb/s reselects a + 0.5 Mb/s rung on a 2 Mb/s connection. +- A change to codec or description, or past a ceiling, mints a new rendition + name through a [catalog rendition ID](/quest/m1/catalog-track-id.md) when + the catalog can keep both, or a new + [broadcast epoch](/quest/m0/broadcast-epoch/README.md) when the whole + broadcast restarts. The catalog may still add and remove tracks; a removed + name is never reused for different content. + +Known violation: the JS publisher rewrites `codedWidth` and `codedHeight` +when the capture resizes (`#runCatalog` in `js/publish/src/video/encoder.ts`). +Fix it to publish the ceiling and resize in band. Audit the other Rust and JS +publishers for fields that change mid-track today the same way. + +Name the identity, ceiling, and live-state split in the hang draft +(`drafts/draft-lcurley-moq-hang.md`, `just drafts check`) and the catalog +docs, so a catalog update that changes only live state is never mistaken for +a new identity. + +Cover codec changes, resolution changes below and past the ceiling, +rendition switches, reconnects, and late joiners in Rust, JS, and HLS/watch +tests. + +Public API: the catalog contract tightens; no type changes expected. Wire: +the hang catalog's field semantics, documented in its draft. + +## Related + +- [Catalog rendition IDs](/quest/m1/catalog-track-id.md) - lets a catalog list a new track name for a changed rendition +- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a restart is a new epoch rather than a changed track +- [Archive](/quest/m1/archive/README.md) - storage and replay consume the identity contract diff --git a/quest/m1/e2ee/README.md b/quest/m1/e2ee/README.md index 0de561fa755..7ceddc73694 100644 --- a/quest/m1/e2ee/README.md +++ b/quest/m1/e2ee/README.md @@ -41,7 +41,7 @@ The Rust and TypeScript cores expose the same surface, and nothing else: - Deterministic secret-derived physical names hide catalog, codec, role, quality, timeline, and custom-track semantics. Authorized clients derive the encrypted catalog track name, then learn the remaining opaque names from its decrypted contents. Every catalog representation is encrypted; Rust publishers must not emit a plaintext MSF catalog. - A platform that forwards and meters protected bytes must never preview, record, archive, transmux, transcode, transcribe, compose, or inspect them, rejecting those paths before opening a processing session or writing product state. Applications needing those operations terminate E2EE outside the platform. A platform classifies protected broadcasts by its own credential or product state, never by name; the moq.pro (downstream) exclusion classifier and dashboard work stay downstream. -- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams. JavaScript has no MoQ Transport datagram delivery until [#4979](https://github.com/moq-dev/moq/pull/4979) (open) lands; once it does, the proof covers MoQ Transport datagrams too. +- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams. JavaScript carries MoQ Transport datagrams since [#4979](https://github.com/moq-dev/moq/pull/4979), so the proof covers them too. ## Required diff --git a/quest/m1/e2ee/interop.md b/quest/m1/e2ee/interop.md index 4576434ed87..c241d5acba7 100644 --- a/quest/m1/e2ee/interop.md +++ b/quest/m1/e2ee/interop.md @@ -10,7 +10,7 @@ Ordinary relays forward, cache, and meter the proof without receiving a content - Add automated browser-to-CLI and CLI-to-browser audio/video cases for both transport dialects using the same application credential and public client APIs. - Assert successful late subscription and decode, plaintext absence at the relay boundary, opaque physical names, deterministic failure under ciphertext or identity tampering, and that a restarted publisher lands under a new epoch that the old keys cannot open. -- Exercise grouped frames on both transport dialects and datagrams on moq-lite against the shared known-answer and negative vectors, and exchange datagrams browser-to-CLI and CLI-to-browser, not only vectors. Add MoQ Transport datagrams once [#4979](https://github.com/moq-dev/moq/pull/4979) gives JavaScript that delivery. Include relocation across tracks, groups, frames, epochs, and transport domains, plus replay-window and sequence-exhaustion cases. +- Exercise grouped frames and datagrams on both transport dialects against the shared known-answer and negative vectors, and exchange datagrams browser-to-CLI and CLI-to-browser, not only vectors. JavaScript carries MoQ Transport datagrams since [#4979](https://github.com/moq-dev/moq/pull/4979). Include relocation across tracks, groups, frames, epochs, and transport domains, plus replay-window and sequence-exhaustion cases. - Verify the documented browser queue and native processing bounds under 20 ms Opus and representative video. Keep the proof deterministic rather than choosing new implementation defaults or adding timing sleeps. ## Required diff --git a/quest/m1/ffi-runtime.md b/quest/m1/ffi-runtime.md index 368e49b467b..ba15c0bd0c0 100644 --- a/quest/m1/ffi-runtime.md +++ b/quest/m1/ffi-runtime.md @@ -2,7 +2,7 @@ ## Goal -moq-ffi and moq-c drive moq on a multi-thread tokio runtime instead of one +moq-ffi drives moq on a multi-thread tokio runtime instead of one `current_thread` runtime thread, so noq's endpoint and connection drivers run beside a busy session, and Go, Python, Swift, Kotlin, and Dart apps get the parallelism their own runtimes already have. @@ -13,8 +13,8 @@ Decided 2026-10-08 in a `/quest-plan` interview (paper trail in the PR that added this quest): - Today `runtime()` in `rs/moq-ffi/src/ffi.rs` builds - `new_current_thread().enable_all()` on one dedicated `moq-ffi` thread, and - `rs/moq-c/src/ffi.rs` does the same (`moq-c`). Everything shares it: noq's + `new_current_thread().enable_all()` on one dedicated `moq-ffi` thread. + Everything shares it: noq's endpoint and connection drivers, the moq-tokio reconnect loop, the session driver, and the origin driver. The pattern was copied from libmoq (#732, #1071) with no stated reason. @@ -35,8 +35,11 @@ added this quest): - Shutdown keeps its meaning: when `moq_ffi_shutdown` returns, no task runs and no callback into the host is in flight, so Python's `atexit` and JVM exit stay clean. `shutdown_background()` no longer gives - that with N workers; the shutdown must wait for them. moq-c exports no - shutdown and is being [retired](/quest/m1/c/retire.md), so it gets none. + that with N workers; the shutdown must wait for them. +- Decided 2026-10-08: moq-ffi only. The + [generated C bindings](/quest/m1/c/README.md) sit on moq-ffi and inherit + it; the hand-written `rs/moq-c` stays untouched until it is + [retired](/quest/m1/c/retire.md), so effort there is wasted. - Watch [Kotlin/JVM exit](/quest/m2/kt-jvm-exit.md), which depends on how the runtime thread stops. - Test: the interop go and python publishers on a pinned single CPU and on @@ -50,3 +53,4 @@ Public API: callbacks may fire concurrently on any runtime thread - [Serve budget](/quest/m0/serve-budget.md) - the root fix for a task hogging its thread - [Kotlin/JVM exit](/quest/m2/kt-jvm-exit.md) - runtime-thread shutdown +- [Generated C bindings](/quest/m1/c/README.md) - inherits the moq-ffi runtime, so hand-written moq-c needs no change diff --git a/quest/m1/gst-brew-path.md b/quest/m1/gst-brew-path.md index 5083f766afc..2675cb935af 100644 --- a/quest/m1/gst-brew-path.md +++ b/quest/m1/gst-brew-path.md @@ -1,4 +1,4 @@ -# [S] Homebrew installs the moq-gst plugin +# [S] Homebrew and Nix install a working moq-gst ## Goal @@ -8,6 +8,13 @@ keeps the plugin under `lib/gstreamer-1.0/`, so the glob matches nothing and the formula installs nothing without an error. The published tap formula (0.4.12) matches the template. +The Nix `moq-gst` package (`moq-gst` in `nix/overlay.nix`) also carries the +encoders and decoders a moq-gst pipeline needs. Its plugin path has core, +base, good, and bad today; add gst-plugins-ugly (`x264enc`) and gst-libav +(`avenc_aac`, `avdec_h264`). moq.pro's +[gst-install-upstream](https://github.com/moq-dev/moq.pro/blob/main/quest/m1/gst-install-upstream.md) +waits on this, so its install can drop its own GStreamer setup. + ## Plan - `.github/homebrew/Formula/moq-gst.rb.tmpl` installs from @@ -20,6 +27,9 @@ the formula installs nothing without an error. The published tap formula - [moq#4555](https://github.com/moq-dev/moq/pull/4555) carried this fix with a Nix wrapper change and closed unmerged on 2026-09-29. Nothing has owned it since. +- Nix: add gst-plugins-ugly and gst-libav to the `moq-gst` plugin path. + Check `nix shell .#moq-gst --command gst-inspect-1.0` finds `x264enc`, + `avenc_aac`, and `avdec_h264`, and add that check to CI. - Regression check: the moq-gst workflow's macOS job installs the rendered formula against the tarball it just built and runs `brew test moq-gst`, so a formula and tarball that disagree fail before release. diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index 5ab16a9fa80..36c7e9189a3 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -25,6 +25,11 @@ no `NotFetchable` code, since nothing would send it. Only lite-07 has the code, and lite-07 drops FETCH for [ranges](/quest/m1/subscribe-ranges/lite.md); lite-05 and lite-06 answer `NotFound`. +Since #4974, a native fetch-only request asks TRACK_STATUS before its first +FETCH, so the `@moq/net` publisher answers TRACK_STATUS too (a #4974 +follow-up, folded in here because answering only matters once JS serves +FETCH). + Verify with an in-memory application responder: a browser publisher serves a native IETF subscriber after a group is evicted or was never cached. Run the supported-draft matrix and `just test interop --all` through CI. diff --git a/quest/m1/js-startup-hole.md b/quest/m1/js-startup-hole.md deleted file mode 100644 index 309bab92185..00000000000 --- a/quest/m1/js-startup-hole.md +++ /dev/null @@ -1,44 +0,0 @@ -# [S] A JS consumer's first group is never held behind a hole - -## Goal - -`@moq/hang`'s container `Consumer` delivers the first group that carries -frames as soon as it arrives, whatever died before it. Today, if the first -group dies before a frame is read and the next arriving group is not adjacent -(16 reset, then 18), `next()` delivers nothing until a later group lets -`#checkMaxDelay` skip, which can cost a whole group (2.5 s of video) before the -first picture after a reattach. - -## Plan - -Root cause (verified 2026-10-06): a hole only exists relative to presented -content, but `next()`'s promotion guard in -`js/hang/src/container/consumer.ts` needs `maxDelay === 0` or a defined -`#presentedEnd` to promote a head that is not contiguous with `#active`. -Two paths reach it with nothing presented: - -- The reporter's: the first group is reset empty and `#runGroup`'s finally - moves `#active` to `sequence + 1` with nothing buffered. -- An empty group adjacent to the dead first group closes cleanly, and - `next()`'s done branch advances `#active` again (16 open, 17 empty and - closed, 16 reset, then 19). - -Decided 2026-10-06: fix it in the promotion guard, the one place every path -converges, not in each site that moves `#active` (the reporter's finally -fix misses the second path). While nothing has been presented, the head is -promotable. Keep this out of `skipHole`, so startup reports no -discontinuity, matching the "start with the first group" policy. - -Open for the implementer: which field means "nothing presented". -`#presentedEnd` can stay undefined after frames were delivered when -`#checkMaxDelay` drops the delivered group without `#recordPresented`; -`#deliveredGroup === undefined` may be the sounder predicate. - -Tests: both paths above, as bun tests with mocked or flushed time, deliver -the live group from its keyframe with no warning. - -Public API: none. Wire: none. - -## Closes - -- [#4951](https://github.com/moq-dev/moq/issues/4951) - a consumer whose first group dies empty parks its cursor on a group that never comes diff --git a/quest/m1/kt-ffi-pom.md b/quest/m1/kt-ffi-pom.md index 7d293fb2491..ab30a52c1ad 100644 --- a/quest/m1/kt-ffi-pom.md +++ b/quest/m1/kt-ffi-pom.md @@ -6,7 +6,9 @@ The `dev.moq:moq-jvm` and `dev.moq:moq-android` POMs on Maven Central depend on a published `moq-ffi` variant, so a Maven build resolves the wrapper. Today 0.5.0 and 0.5.1 depend on `moq-ffi-jvm` and `moq-ffi-android` version `0.0.0-dev`, which was never published, so every Maven consumer fails to -resolve. A PR check refuses a generated POM naming that version. +resolve. A PR check refuses a generated POM naming that version. moq.pro's +[Kotlin sample](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/kotlin-sample.md) +is a consumer: it builds against the published wrapper. ## Plan diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index bf5251df988..f96f99fa694 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -74,7 +74,7 @@ is published; older versions are unchanged. - [lite-07 Live flag](/quest/m1/lite-live.md) - SUBSCRIBE carries `Live` apart from its floor - [Restart](/quest/m0/broadcast-epoch/restart.md) - lite-07 carries the `Restart` announce -- [AUTH on the wip lite version](/quest/m1/auth/wip-version.md) - lite-07 carries the Auth Stream and UNAUTHORIZED +- [In-band auth](/quest/m1/auth/README.md) - lite-07 carries the Auth Stream and UNAUTHORIZED (0x3B) - [Routes and announces](/quest/m1/cluster-routing/routes.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the hop list gone - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - lite-07 restores SUBSCRIBE_DROP in place of `Stream Count` - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - SUBSCRIBE carries ranges and an order and lite FETCH is gone, in Rust and JS diff --git a/quest/m1/perf/announce-replay.md b/quest/m1/perf/announce-replay.md index 2785d9bd79e..54abc2dbc2c 100644 --- a/quest/m1/perf/announce-replay.md +++ b/quest/m1/perf/announce-replay.md @@ -10,8 +10,8 @@ with thousands of routes connects as fast per route as one joining a handful. The moq-lite publisher's initial replay (`AnnounceRun::init` in `rs/moq-net/src/lite/publisher.rs`) de-duplicates by scanning the pending list -for every route it drains: `initial.retain` on Lite05+, `init.contains` on -the Lite01/02 init. That is quadratic in the replay size. +for every route it drains: `initial.retain` on Lite05+, and `init.retain` +then `init.push` on the Lite01/02 init. That is quadratic in the replay size. Measured with `session_join_broadcasts` (2026-09-25, one relay, Apple M4): lite-06 join takes 128 µs with 1 announced broadcast, 317 µs with 64, and diff --git a/quest/m1/quest-flat-lines.md b/quest/m1/quest-flat-lines.md index 8953badbc79..c29fa1443be 100644 --- a/quest/m1/quest-flat-lines.md +++ b/quest/m1/quest-flat-lines.md @@ -72,9 +72,6 @@ Remaining: - #4133 qos: lag-splice landed on the line (#5009). Its egress `lag` histogram splits into its own quest requiring stats-split (decided 2026-10-08); follow the qos README for what the line lands without it. -- Child PRs still based on a line merge into it first, or GitHub closes them - with the branch: #4675 (auth/request-token) needs the updated auth line - merged in. Done when `flake.nix` pins the new quest, no `quest/*README` branch remains, and `quest check` passes. diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 804fcf49782..4421ec0b39f 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -74,6 +74,5 @@ The BBR app-limited fixes land in `moq-quic` without waiting for the switch. - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in the fork, 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 by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer -- [GCC egress experiment](/quest/m3/quic-gcc.md) - a receive-timestamps measurement spike, the - first step toward WebRTC-style delay control +- [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 +- [QUIC receive-timestamps spike](/quest/m3/quic-gcc.md) - measures whether receive timestamps give a cheaper, more accurate forward delay than half the RTT diff --git a/quest/m1/quic/peer-limits.md b/quest/m1/quic/peer-limits.md index f75245209bf..dcfec85634f 100644 --- a/quest/m1/quic/peer-limits.md +++ b/quest/m1/quic/peer-limits.md @@ -10,19 +10,28 @@ stay small so one client cannot reserve a relay's memory. ## Plan -noq-proto already exposes runtime `Connection::set_max_concurrent_streams`, -`set_receive_window`, and `set_send_window`; a raise queues `MAX_STREAMS` and -`MAX_DATA` on the next packet, and a shrink is a debt paid as the peer -consumes credit. Nothing MoQ builds on top needs a fork change. - -- `web-transport-moq` (and the trait, with an unsupported default for the - browser) exposes a `set_limits(Limits)` on the session, `Limits` carrying - the three values. -- moq-tokio's `[quic]` section gains a `peer` sub-table with the same three - window fields plus `max_streams`, defaulting to an order of magnitude above - the client defaults. `moq-relay` applies it once SETUP identifies the - session as a cluster peer (the cluster extension's role, not the peer's - address), on the io_uring workers too. +The in-tree `moq-quic` `Connection` (`rs/moq-quic/src/connection/mod.rs`) +already exposes runtime `set_max_concurrent_streams`, `set_receive_window`, +and `set_send_window`; a raise queues `MAX_STREAMS` and `MAX_DATA` on the next +packet, and a shrink is a debt paid as the peer consumes credit. The core +needs no change; the work waits only for +[the fork switch](/quest/m1/quic/fork/README.md), so moq-tokio and moq-uring +run on `moq-quic` instead of `moq-noq`. + +Decided 2026-10-08: [relay session limits](/quest/m1/relay-session-limits.md) +lands first and introduces the relay's peer config surface (classifying a +session as a cluster peer, and a peer table); this quest extends that +surface with the QUIC values rather than adding its own. + +- moq-net's transport trait gains `set_limits(Limits)` on the session, + `Limits` carrying the three values, implemented by the moq-tokio and + moq-uring adapters over `moq-quic` after the fork switch; every other + backend, the browser included, reports it unsupported. +- The peer table gains the same three values (the stream limit and the two + windows), + defaulting to an order of magnitude above the client defaults. `moq-relay` + applies it once a session is classified as a cluster peer, on the io_uring + workers too. - Refuse a `peer` value below the client default rather than silently shrinking. @@ -32,4 +41,6 @@ viewer session does not; the io_uring path applies the same values; a ## Required -- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork +- [Relay session limits](/quest/m1/relay-session-limits.md) - introduces the peer classification and config table this extends +- [Hard fork](/quest/m1/quic/fork/README.md) - moq-tokio and moq-uring run on `moq-quic`, whose setters this calls + diff --git a/quest/m1/auth/refusal-reason.md b/quest/m1/refusal-reason.md similarity index 95% rename from quest/m1/auth/refusal-reason.md rename to quest/m1/refusal-reason.md index 7e474cc4710..2f146993885 100644 --- a/quest/m1/auth/refusal-reason.md +++ b/quest/m1/refusal-reason.md @@ -12,6 +12,9 @@ refusal to that root and tier. ## Plan +Decided 2026-10-08: moved out of the auth line to m1, since it extends +session outcomes and the HTTP auth contract, not in-band AUTH. + Decided 2026-10-08 (split from [Session outcomes](/quest/m1/session-outcomes.md)): - **Why.** `TokenExpired` is raised only in moq-auth's key check diff --git a/quest/m1/relay-session-limits.md b/quest/m1/relay-session-limits.md index 0531245a987..b865d3e2eae 100644 --- a/quest/m1/relay-session-limits.md +++ b/quest/m1/relay-session-limits.md @@ -15,6 +15,12 @@ get loose limits. The relay knows which sessions are peers, so it picks the limit per session. Propose the flag and TOML names in the PR. +Decided 2026-10-08: this quest lands before +[peer limits](/quest/m1/quic/peer-limits.md) and introduces the peer config +surface both use: how the relay classifies a session as a cluster peer, and a +peer table holding the request limits. Peer limits adds its QUIC values to +that table. + Past a cap the session closes with TOO_MANY_REQUESTS, so until cluster peers get higher caps (or none), a link carrying more than 10,000 subscriptions closes and flaps on reconnect. This does not gate a release (decided @@ -25,3 +31,7 @@ Sync table. Public API: a relay config field and flag, and a new error kind in moq-ffi and the bindings. Wire: none. + +## Related + +- [Peer limits](/quest/m1/quic/peer-limits.md) - extends the peer table with QUIC stream and data limits diff --git a/quest/m1/session-outcomes.md b/quest/m1/session-outcomes.md index 0fef8927006..b2c26bbd02a 100644 --- a/quest/m1/session-outcomes.md +++ b/quest/m1/session-outcomes.md @@ -8,7 +8,7 @@ refused, by reason, and how many ended abnormally, by kind: idle timeout, transport error, application error, or token expired. A dashboard computes an error rate from the stats feed alone, with no log scraping. Refusals count unattributed, on the default tier, until -[Typed refusal reason](/quest/m1/auth/refusal-reason.md) adds `expired` and +[Typed refusal reason](/quest/m1/refusal-reason.md) adds `expired` and attributes a refusal to the root and tier the auth server resolved. ## Plan @@ -28,7 +28,7 @@ rolling out browser playback wants an error rate it cannot see client-side): on first sight and following stats-split's linger and epoch; a project's group never sees it. Sessions admitted under the empty root (public rules) share that group. `expired` and per-root attribution need the decider to - say so, which [Typed refusal reason](/quest/m1/auth/refusal-reason.md) adds. + say so, which [Typed refusal reason](/quest/m1/refusal-reason.md) adds. - **Ends are classified from a typed close kind, not a string.** A peer's application close is already typed (`Error::from_transport` decodes it into `Error::Session`), but `moq_net::Error::Transport(String)` still flattens @@ -65,7 +65,7 @@ rolling out browser playback wants an error rate it cannot see client-side): - [WebTransport transport](/quest/m1/auth/webtransport-transport.md) - the same consumer's per-transport session split -- [Typed refusal reason](/quest/m1/auth/refusal-reason.md) - adds `expired` +- [Typed refusal reason](/quest/m1/refusal-reason.md) - adds `expired` and per-root, per-tier refusal attribution on top of these counters - [Own the QUIC stack](/quest/m1/quic/README.md) - where a typed close kind is natural once `moq-quic` owns the connection diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 55a62fa7758..f76a1d2af32 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -126,8 +126,8 @@ connection view and the dashboard flow. ## Related -- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters; whether a - combined per-broadcast verdict reads both is open in - [client health](/quest/m1/stats/health.md) +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters; the + combined per-broadcast verdict reading both lives in moq.pro's + [health badge](https://github.com/moq-dev/moq.pro/blob/main/quest/m1/qos/badge.md) - [Encoder feedback](/quest/m3/stats-encoder-feedback.md) - a Rust encoder adapts its bitrate to what its viewers report diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index c42b0f3bffa..8531b9b21a4 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -27,8 +27,12 @@ first, earlier in-flight groups can be lost. #4387 (merged 09-28) fixed that case, but the tail lanes still fail on this quest's PR #4225 after it: Interop run 37139033242 (2026-10-03) failed `tail rust -> rust`, `rust -> js-native-node`, and `rust -> js-native-bun`. Merge `main` (after #4741 and -#4813) into #4225, rerun, and record here whatever defect still fails; the -cause is untracked until then. +#4813) into #4225, rerun, and record here whatever defect still fails. + +Found 2026-10-08: #4225's `go -> *` lanes fail on the +[serve budget](/quest/m0/serve-budget.md) stall, where the go publisher's +serve loop starves its own QUIC driver until the relay times it out. Rerun +the lanes once that lands. Decided in the 2026-09-30 audit: the lite-07 drop case moved into [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)'s tests, so the basic Rust and @@ -37,6 +41,10 @@ JS tail interop lands now instead of waiting on that [L] quest. QUIC on localhost rarely reorders, so this is a smoke check that the end is delivered and clean. The ordering race itself stays in the unit tests. +## Required + +- [Serve budget](/quest/m0/serve-budget.md) - is meant to fix the stall that fails #4225's go lanes; rerun them once it lands + ## Related - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - owns the lite-07 drop case on top of this harness diff --git a/quest/m1/ts-passthrough.md b/quest/m1/ts-passthrough.md index ab0856c0d13..38e21af912f 100644 --- a/quest/m1/ts-passthrough.md +++ b/quest/m1/ts-passthrough.md @@ -100,9 +100,9 @@ fixture with the PCR on its audio PID starts groups at video random access points only. PCR discovery finds a PCR PID that differs from the PMT PID, with the PMT section split across packets. Two exporters fed the same objects with different arrival skew emit identical bytes; when only one misses a deadline, -its output is the other's less that object's packets. A flagged backward PCR -discontinuity publishes two broadcasts, and the same rewind unflagged errors. -A dropped object is counted, and the rest still go out on time. Rerun the +its output matches the other's except for the missed object's packets. A +backward PCR errors, flagged or not. A dropped object is counted, and the +rest still go out on time. Rerun the #4613 netem rig (10% loss, 120 s) against it. Lands in two PRs (decided 2026-10-08): #5003 is the import half and the diff --git a/quest/m2/README.md b/quest/m2/README.md index 4b398f77a68..27c690f2188 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -16,16 +16,16 @@ consumer yet, waits in [m3](/quest/m3/README.md). ## Required - [RTSP import](/quest/m2/rtsp-import.md) - `moq import rtsp` publishes an IP camera from its own network, through a `moq-rtsp` crate whose one-session ingest a caller can supervise itself -- [One port](/quest/m2/one-port/README.md) - a relay speaks QUIC and STUN on one UDP port and HTTP, RTMP, and RTMPS on one TCP port; `moq-rtc` serves WebRTC media from the same UDP port +- [One port](/quest/m2/one-port/README.md) - one UDP port carries QUIC, SRT, and WebRTC media through an embedder hook, and one TCP port carries HTTP, RTMP, and RTMPS - [Bitrate claim](/quest/m2/rate-claim.md) - tokens and auth grants cap a session's upload and download bitrate, refused where unenforced and always on HTTP - [QUIC caps](/quest/m2/rate-quic.md) - paced MAX_DATA credit in and a capped pacer out hold a QUIC session to its token's bitrate - [WebSocket caps](/quest/m2/rate-websocket.md) - paced reads and writes over bounded socket buffers hold WebSocket to the same caps - [Publishers learn their cap](/quest/m2/rate-grant.md) - the AUTH grant carries the caps and publishers clamp their encoder to them -- [One port on the io_uring workers](/quest/m2/uring-demux.md) - `moq-uring`'s workers host the UDP demux, so a ring relay keeps STUN, WebRTC, and SRT on its QUIC port +- [One port on the io_uring workers](/quest/m2/uring-demux.md) - `moq-uring`'s workers host the UDP demux, so a ring relay keeps WebRTC media and SRT on its QUIC port - [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio - [Hitless TS legs](/quest/m2/ts-hitless.md) - two `--sync` export legs emit packet-identical TS for ST 2022-7 -- [DVB E-AC-3](/quest/m2/ts-eac3.md) - E-AC-3 private data is split per sync frame and buffer-modelled in TS export +- [DVB E-AC-3](/quest/m2/ts-eac3.md) - E-AC-3 private data is split per access unit (independent frame plus its dependent substreams) and buffer-modelled in TS export - [T-STD controls](/quest/m2/tstd-controls.md) - the harness gains an MB-overflow control and an AAC broadcast reference - [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 @@ -57,11 +57,11 @@ consumer yet, waits in [m3](/quest/m3/README.md). - [Refusal reasons](/quest/m2/refusal-reasons.md) - refused-session metrics tell an expired token from an invalid one, and count gateway admissions - [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then moq-mux containers - [mTLS on tls://](/quest/m2/tls-listener-mtls.md) - a `tls://` listener can identify a cluster peer by its client certificate -- [Link quality](/quest/m2/link-quality.md) - a radio link's cost follows its measured quality without flapping routes, once a consumer names a radio mesh +- [Link quality](/quest/m2/link-quality.md) - a radio link's cost follows its measured quality without flapping routes - [One transport adapter](/quest/m2/transport-adapter-dedup.md) - the poll transport adapter exists once, and the 64 KiB cap in moq-net's default `poll_read_buf` (not in the adapter) has a test -- [Catalog track identity](/quest/m2/catalog-tracks.md) - a changed track configuration becomes a new track name or epoch, never a mutated definition - [Archive S3 wire proof](/quest/m2/archive-s3.md) - the archive proof also runs through the S3 client against an in-process S3-compatible server - [Archive recovery listing](/quest/m2/archive-recovery-listing.md) - a resumed DVR lists what changed since its checkpoint, not every stored group +- [Range-addressed HLS playlists](/quest/m2/hls-ranges.md) - `moq-hls` lists a start-to-end range of a recording as its own playlist, for moq.pro's managed HLS - [DASH rendition URLs](/quest/m2/dash-rendition-uri.md) - DASH init and segment URLs percent-encode the rendition name, so a name with a slash resolves to its own rendition - [IETF on the ring](/quest/m2/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol - [Dropped uring session closes](/quest/m2/uring-drop-close.md) - a moq-uring session dropped without close() closes its connection @@ -78,14 +78,14 @@ consumer yet, waits in [m3](/quest/m3/README.md). - [#2848](/quest/m2/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [NVENC buffer pool](/quest/m2/nvenc-pool.md) - NVENC reuses input and output buffers instead of allocating per frame, if a benchmark shows it wins - [Direct3D11 render import](/quest/m2/render-d3d11.md) - Windows presents without downloading every frame to system memory -- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - video with periodic intra refresh publishes, imports, and tunes in cleanly with one group per sweep and a catalog `warmup` +- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - video with periodic intra refresh imports and plays back cleanly with one group per sweep and a catalog `warmup` - [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - moq-video: validate PipeWire DMA-BUFs into the Vulkan renderer on hardware - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation -- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into registered buffers with no copy, once a profile says where +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into caller-owned buffers with no copy, once a profile says where - [BBR media study](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference, and where our BBR differs from Google's - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [Viewer up-switch](/quest/m2/viewer-upswitch.md) - a viewer capped by its small rendition finds headroom through PROBE and moves up -- [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer +- [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 - [Socket close](/quest/m2/noq-socket-close.md) - moq-tokio's QUIC endpoint releases its socket on close, so it drops its wrapper - [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability @@ -108,6 +108,6 @@ consumer yet, waits in [m3](/quest/m3/README.md). - [moq-transport request codes](/quest/m2/ietf-request-codes.md) - Range Filters (INVALID_FILTER), reserved namespaces, and RENDEZVOUS_TIMEOUT get the draft's answer, or a recorded fallback code, and the deliberate deviations are documented - [Native enabled](/quest/m2/native-enabled.md) - native players and the ffi/C paths never select a disabled rendition - [Kotlin JVM exit](/quest/m2/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 -- [JS audio ranking](/quest/m2/js-audio-ranked.md) - @moq/hang and HLS rank audio renditions like Rust +- [JS audio ranking](/quest/m2/js-audio-ranked.md) - @moq/hang ranks audio and video renditions like Rust, enabled first, and HLS lists audio by that rank - [ts::Export catalog stream](/quest/m2/ts-export-catalog.md) - TS export takes (source, catalog) like the other exporters - [Load-balancer refusals](/quest/m2/listener-lb-refusals.md) - refuse ignored or conflicting QUIC load-balancer settings diff --git a/quest/m2/catalog-tracks.md b/quest/m2/catalog-tracks.md deleted file mode 100644 index 91bf4d6f4c6..00000000000 --- a/quest/m2/catalog-tracks.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Catalog track identity - -## Goal - -A track's catalog definition never changes for its name, so live and recorded -playback never guess which configuration applies to a group. A publisher whose -track configuration changes either refuses the change or publishes it under a -new track name or a new broadcast epoch. This is independent of DVR and does -not gate archives. - -## Plan - -Decided in the 2026-09-30 audit: track identity is immutable. Mutable -definitions with a configuration identity that groups reference (the old -option 2) are out, because they contradict the rule that a track name always -means the same content, and MoQ has no ETag-style invalidation. - -Audit publishers in Rust and JS for the properties that change mid-track -today (codec/config bytes, resolution, audio layout, rendition metadata) and -make each one either refuse the change or mint a new identity: a new track -name through a [catalog rendition ID](/quest/m1/catalog-track-id.md) when the -catalog can keep both, or a new [broadcast epoch](/quest/m0/broadcast-epoch/README.md) -when the whole broadcast restarts. The catalog may still add and remove -tracks; a removed name is never reused for different content. - -Only a track's defining fields are immutable: codec and its config bytes, -resolution, audio layout, and anything else a decoder needs. Live state that -describes the track's delivery changes freely under the same name: `enabled`, -the jitter and delay figures, and `warmup`. Name the split in the catalog -docs and the hang draft so a catalog update that changes only live state is -never mistaken for a new identity (split in the 2026-10-08 audit). - -Cover codec changes, rendition switches, reconnects, and late joiners in Rust, -JS, and HLS/watch tests. - -## Related - -- [Catalog rendition IDs](/quest/m1/catalog-track-id.md) - lets a catalog list a new track name for a changed rendition -- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - a restart is a new epoch rather than a changed track -- [Archive](/quest/m1/archive/README.md) - storage and replay consume the identity contract diff --git a/quest/m2/gpu-health.md b/quest/m2/gpu-health.md index 8c83301b6a0..f8c0dec199b 100644 --- a/quest/m2/gpu-health.md +++ b/quest/m2/gpu-health.md @@ -8,9 +8,8 @@ and any hard session limit, memory used and available, and engine utilization. It also reports device health (whether the device is usable, lost, or reset) and the GPU model, which moq.pro's admission keys its per-model limits on. The same API works on NVIDIA, AMD, and Intel, keyed by -the device's render node `dev_t`, the identity -`Surface::Vulkan` carries, so a caller writes no -vendor code. A value a driver cannot provide is absent, never guessed. +the device identity `Surface::Vulkan` carries (`frame::vulkan::Device`), so a +caller writes no vendor code. A value a driver cannot provide is absent, never guessed. Not here: admission policy, thresholds, frame-lateness tracking, or draining. Those are the caller's. @@ -25,10 +24,14 @@ first-class, so an NVML-shaped API would be rewritten once they land. moq.pro's transcode admission and its benchmarks assume NVML today; they adopt this instead. -Decided 2026-10-05: one device identity everywhere, the render node's -`dev_t`, shared with [VA-API import](/quest/m2/vaapi-vulkan-import.md). +Decided 2026-10-05: one device identity wherever a render node exists, the +render node's `dev_t`, shared with [VA-API import](/quest/m2/vaapi-vulkan-import.md). NVIDIA's device UUID maps to its node through `VK_EXT_physical_device_drm`. -The external GPU surface (#4975) carries that identity. +The external GPU surface (#4975) carries that identity as +`frame::vulkan::Device { device_uuid, driver_uuid, render_node: Option }`. +`render_node` is absent when the exporter has no DRM render node; key such a +device by its `device_uuid`, which every Vulkan device has, so a report never +merges two devices or drops one. Guidance, to be settled while building: diff --git a/quest/m2/hls-ranges.md b/quest/m2/hls-ranges.md new file mode 100644 index 00000000000..5997e4c55da --- /dev/null +++ b/quest/m2/hls-ranges.md @@ -0,0 +1,48 @@ +# [M] Range-addressed HLS playlists + +## Goal + +`moq-hls` serves a playlist addressed by a start and end over a durable +(archived) timeline: it lists only the segments covering that range, and +ends with `EXT-X-ENDLIST` once the range is fully in the past, so a player +gets a VOD clip of a recording without the embedder building its own +playlist. Today `moq_hls::export::Config` (`rs/moq-hls/src/export/mod.rs`) +has only `window` and `history`, so a playlist is either the live window or +everything stored. + +The consumer is moq.pro's managed HLS, which Requires this quest. + +## Plan + +Decided 2026-10-08: range playlists belong upstream in `moq-hls`, in m2, so +moq.pro builds on the stock exporter instead of a fork of its playlist code. + +Open, to settle in the PR with a recommendation: + +- How a request names the range. Recommended: `start` and `end` on the + playlist URL in the timeline's media time, so one exporter serves any + number of clips and an edge cache keys on the URL. +- Which edges a range snaps to. Recommended: the segments that overlap it, + with the start widened back to the preceding sync point (or refused when + none is held), since a long GOP spans several segments. Test over the + existing split-GOP fixture in `rs/moq-hls/src/export/mod.rs`. +- What a range over a timeline that is not durable, or outside what the + store holds, returns. Refuse it with a clear HTTP error rather than list a + partial range. + +A range that ends in the future grows like an event playlist until its end +passes. Every edge must list the same segments and `EXT-X-MEDIA-SEQUENCE` for the +same range, regardless of when it joined. `Config::history` starts at the +records restated when an exporter joins, so this relies on +[replay history](/quest/m1/archive/replay-history.md); test two edges that +join at different times. + +Tests: a recording longer than the default window, clipped at its start, in +its middle, and across the live edge; a range on a live-only timeline is +refused. Document it in `doc/bin/hls.md`. + +Public API: `moq-hls` export gains range addressing. Wire: none. + +## Required + +- [History from the start](/quest/m1/archive/replay-history.md) - reads stored timeline groups, which a range older than the restated records needs diff --git a/quest/m2/ietf-malformed-close.md b/quest/m2/ietf-malformed-close.md index 40a570d11ca..02744cc9aba 100644 --- a/quest/m2/ietf-malformed-close.md +++ b/quest/m2/ietf-malformed-close.md @@ -53,8 +53,10 @@ Decided with the maintainer on 2026-10-04 and 2026-10-05: in drafts 18 and 21. That registry is moq-lite's too, and lite codes below 32 carry moq-transport's meaning, so add the rows to the Session Error Codes table in `drafts/draft-lcurley-moq-lite.md` and to - `session_codes_round_trip`. No per-version mapping. Where a code is a - real burden, the PROTOCOL_VIOLATION fallback in the Goal applies. + `session_codes_round_trip`, as [Request + tokens](/quest/m1/auth/request-token.md) does for 0x13 and 0x17. No + per-version mapping. Where a code is a real burden, the PROTOCOL_VIOLATION + fallback in the Goal applies. - **Regression tests, not a CI job for the validator.** Add one session or codec test per case, each failing without its fix and asserting the draft's code, or PROTOCOL_VIOLATION where the fallback is recorded in @@ -64,6 +66,10 @@ Decided with the maintainer on 2026-10-04 and 2026-10-05: `--publisher-no-fetch`, one scenario per run, on a track of about 150 kbps. A full-bitrate track floods the runner's event log and aborts the run. +- **Record fallbacks** in the "Deliberate deviations" subsection of + `doc/concept/standard.md`, dropping the hard-coded count from its intro, + and update the "Refused, not fatal" bullet above it wherever a case here + now closes the session. - **Mirror in `js/net/src/ietf`** in the same PR. - Request tokens are out of scope here. AUTH_TOKEN_CACHE_OVERFLOW and the request-token decode belong to [Request diff --git a/quest/m2/ietf-request-codes.md b/quest/m2/ietf-request-codes.md index 74a9cb9f8c7..078bfe12aae 100644 --- a/quest/m2/ietf-request-codes.md +++ b/quest/m2/ietf-request-codes.md @@ -3,7 +3,7 @@ ## Goal On draft-18 and draft-21, `rs/moq-net` and `js/net` answer these requests -the way the drafts say, without closing the session. Each answer uses the +the way the drafts say, without closing the session unless noted. Each answer uses the draft's code, or an existing code where the exact one costs more than it is worth and the fallback is recorded in `doc/concept/standard.md`: @@ -31,6 +31,12 @@ is worth and the fallback is recorded in `doc/concept/standard.md`: on REQUEST_UPDATE are accepted and ignored, as SUBSCRIBE already does (`ietf/subscribe.rs`). Today `ietf/request_stream.rs` decodes both and marks the update unsupported. +- **REQUEST_UPDATE on a SUBSCRIBE_NAMESPACE stream** is read, so its + TRACK_NAMESPACE_PREFIX applies (a #5028 follow-up). +- **TRACK_PROPERTY_FILTER on a subscription's REQUEST_UPDATE** closes the + session with PROTOCOL_VIOLATION instead of answering REQUEST_ERROR: + draft-19 allows it only on SUBSCRIBE_TRACKS and its updates (a #5028 + follow-up). ## Plan @@ -41,9 +47,11 @@ Decided with the maintainer on 2026-10-04 and 2026-10-05: SUBGROUP_DELIVERY_TIMEOUT never drop an object or reset a subgroup: they would need wall-clock delivery deadlines, and moq-net's latency enforcement is presentation time only (#2890). The rendezvous wait is - capped at 0. Each deviation gets a line under - "moq-transport" in `doc/concept/standard.md`, so the next validator run - has a reason to point at. + capped at 0. Each deviation gets a line in the "Deliberate deviations" + subsection of `doc/concept/standard.md`, so the next validator run has a + reason to point at. Drop the hard-coded count from that subsection's + intro, and update the "Refused, not fatal" bullet above it for the + answers this quest changes. - **Exact codes when cheap.** INVALID_FILTER becomes a request code. Where one costs more than it is worth, the fallback in the Goal applies. - **TIMEOUT, not a timer.** The 0 cap means nothing waits, so no request is diff --git a/quest/m2/intra-refresh/h265-import.md b/quest/m2/intra-refresh/h265-import.md index 3ffac61723f..6b193564b11 100644 --- a/quest/m2/intra-refresh/h265-import.md +++ b/quest/m2/intra-refresh/h265-import.md @@ -28,8 +28,8 @@ a track with no keyframes at all and fails the group invariant. exactly as the H.264 quest does, sharing the measurement and catalog mutation. - Fixture: synthetic NAL sequences beside the existing suffix-SEI tests, since - x265's intra refresh emits no recovery-point SEI; a real NVENC HEVC clip is verified by hand - when the NVENC quest lands. + x265's intra refresh emits no recovery-point SEI. Verify by hand with an + externally encoded clip (ffmpeg `hevc_nvenc` with intra refresh). ## Required diff --git a/quest/m2/js-audio-ranked.md b/quest/m2/js-audio-ranked.md index d4c1f5467e8..9e7c634f66b 100644 --- a/quest/m2/js-audio-ranked.md +++ b/quest/m2/js-audio-ranked.md @@ -3,10 +3,23 @@ ## Goal `@moq/hang` orders audio renditions the way Rust `hang::catalog::Audio::ranked` -(#4993) does: highest bitrate, then sample rate, then channels, unknown -bitrate last, ties in name order. The HLS exporter orders audio renditions by -that rank instead of by name. +(#4993) does: enabled first, then highest bitrate, sample rate, and channels, +unknown bitrate last, ties in name order. JS video `ranked` gains the same +enabled-first rule Rust's has (today it ranks by area, bitrate, and name). The Rust HLS exporter +(`rs/moq-hls/src/export/renditions.rs`) lists audio renditions by +`Audio::ranked` instead of by name. ## Plan -Mirror `Catalog.ranked` for video (#4988). Name it to match Rust per AGENTS.md. +Decided 2026-10-08: the JS ranking includes `enabled` first, like Rust, and +this quest also fixes JS video `ranked` (`js/hang/src/catalog/video.ts`), +which ranks by picture area without it, so both kinds agree with Rust. The +HLS exporter is Rust, so it calls `Audio::ranked` directly; no JS is +involved there. + +Mirror `ranked` for video (#4988). Name it to match Rust per AGENTS.md. +Test each ordering rule in both languages, including a disabled rendition +that would otherwise rank first. + +Public API: a new `@moq/hang` audio `ranked`, and a behavior change to video +`ranked`. Wire: none. diff --git a/quest/m2/kt-jvm-exit.md b/quest/m2/kt-jvm-exit.md index 71fbe5e1159..2ea4eb025dc 100644 --- a/quest/m2/kt-jvm-exit.md +++ b/quest/m2/kt-jvm-exit.md @@ -2,8 +2,8 @@ ## Goal -A Kotlin/JVM program using moq exits cleanly whatever the moq-ffi runtime -thread is doing at the time, proven by a regression test that forces the +A Kotlin/JVM program using moq exits cleanly whatever any moq-ffi runtime +worker thread is doing at the time, proven by a regression test that forces the racing order. The Python binding hit this class of crash (a runtime-thread callback into a host that has begun finalizing) about one run in four under load; the JVM has the same shape and nothing exercises it today. Android is @@ -11,21 +11,25 @@ out of scope: it kills the process rather than destroying the VM. ## Plan +Decided 2026-10-08: plan for any runtime worker thread, not one runtime +thread, since [FFI runtime](/quest/m1/ffi-runtime.md) moves moq-ffi to a +worker pool. + - Audit first. uniffi delivers async continuations as JNA callbacks (`UniffiRustFutureContinuationCallback` in `kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/moq/moq.kt`, bound with - `Native.register`) invoked on the `moq-ffi` runtime thread. Establish what + `Native.register`) invoked on any runtime worker thread. Establish what a JNA callback does when it fires after `DestroyJavaVM` has begun, or after the last non-daemon thread exits: attach failure, `Callback after VM shutdown` abort, or a hang. Reproduce with a child JVM that delays a - continuation on the runtime thread while `main` returns. + continuation on a runtime worker thread while `main` returns. - Fix only what reproduces. The expected fix is a hand-written Kotlin file in `kt/moq-ffi` (not the generated `moq.kt`, and not only the `kt/moq` wrapper, since raw uniffi consumers exist) that binds `moq_ffi_shutdown` through JNA against the same library and registers `Runtime.addShutdownHook` on first load. Shutdown hooks run before VM - destruction, so the thread finishes its current callback and never starts - another. The hook must never run on the runtime thread itself, which would + destruction, so every worker finishes its current callback and none starts + another. The hook must never run on a runtime worker thread, which would wait on itself. - Regression test: a JUnit test in `kt/moq-ffi` that forks a JVM in the racing order (mirror `py/moq-ffi/tests/exit_inside_callback.py`) and @@ -34,3 +38,7 @@ out of scope: it kills the process rather than destroying the VM. exit code. Run it in the existing `kt` CI job. Public API: none; the hook is internal to the binding. Wire: none. + +## Related + +- [FFI runtime](/quest/m1/ffi-runtime.md) - moves moq-ffi to a multi-thread runtime, so callbacks fire on any worker thread diff --git a/quest/m2/link-quality.md b/quest/m2/link-quality.md index dcb32776f09..78900841124 100644 --- a/quest/m2/link-quality.md +++ b/quest/m2/link-quality.md @@ -27,8 +27,7 @@ the default and measured cost is opt-in, so the line ships without it. [priced topology](https://github.com/moq-dev/moq.pro/blob/main/quest/m3/priced-topology.md) keeps RTT out of monetary costs, and that stays true because measured cost is opt-in on links the operator chooses. -- A lossy-link fixture over the mock transport with mocked time, reusable by - the line's drone-mesh end-to-end test. +- A lossy-link fixture over the mock transport with mocked time. Public API: a per-link way to ask for measured cost in the peer entry. Wire: none. diff --git a/quest/m2/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md index 083930bc2c2..d5f795a5a3b 100644 --- a/quest/m2/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -37,6 +37,12 @@ ALPN to the router. A connection with no ALPN keeps the decrypted-byte sniff, since RTMPS clients negotiate none (`moq-rtmp` documents an empty ALPN list): `0x03` is RTMP, anything else is HTTP. +Decided 2026-10-08: under one acceptor, the client-certificate request from +[mTLS on tls://](/quest/m2/tls-listener-mtls.md) is optional (never required) +and sits on the moq-ALPN TLS config only, so browsers and RTMPS clients on +the same port are never asked for one. Whichever lands second keeps `tls://` +client-certificate verification and the `MtlsUnsupported` lift working. + Keep the accepted `TcpStream`'s handle reachable after it is boxed: the relay already captures socket stats at accept for qmux (`SocketStats` in `web.rs`), and [WebSocket bitrate caps](/quest/m2/rate-websocket.md) set @@ -49,4 +55,5 @@ right arm. ## Related - [UDP demux](/quest/m2/one-port/udp-demux.md) - the UDP half +- [mTLS on tls://](/quest/m2/tls-listener-mtls.md) - client-certificate verification on the `tls://` arm this acceptor carries - [WebSocket bitrate caps](/quest/m2/rate-websocket.md) - sizes the kernel buffers of the socket this acceptor boxes diff --git a/quest/m2/quic-deadline.md b/quest/m2/quic-deadline.md index a16118483f6..145ae3ee3ce 100644 --- a/quest/m2/quic-deadline.md +++ b/quest/m2/quic-deadline.md @@ -21,8 +21,8 @@ Implement in the fork. - On loss detection, before queueing a retransmission for a stream with a deadline, estimate the arrival instant as now plus the forward one-way delay. Start with `min_rtt / 2`, corrected by the peer's reported ACK delay; - the [GCC experiment](/quest/m3/quic-gcc.md)'s receive timestamps replace that - guess with a measured forward delay. If the estimate is past the deadline, + the [receive-timestamps spike](/quest/m3/quic-gcc.md) measures whether + receive timestamps should replace that guess with a measured forward delay. If the estimate is past the deadline, reset the stream with a dedicated error code and drop its retransmit ranges, including bytes already lost, so flow control is returned in one step. - Proactive tail-loss probe: when the newest in-flight packet carries deadline @@ -57,8 +57,8 @@ Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. ## Related -- [QUIC GCC](/quest/m3/quic-gcc.md) - its receive timestamps give a measured - forward delay that replaces the half-RTT estimate +- [QUIC receive-timestamps spike](/quest/m3/quic-gcc.md) - measures whether + receive timestamps give a forward delay worth replacing the half-RTT estimate - [ACK hook](/quest/m2/quic-ack-hook.md) - the same pattern for a moq-net method backed by `moq-quic` - [Discover media headroom](/quest/m2/quic-probe.md) - can reuse retransmission machinery if redundant capacity probes prove worthwhile diff --git a/quest/m2/quic-io-boundary.md b/quest/m2/quic-io-boundary.md index 333ed07f00f..9e6807648c8 100644 --- a/quest/m2/quic-io-boundary.md +++ b/quest/m2/quic-io-boundary.md @@ -3,8 +3,10 @@ ## Goal `moq-quic`'s sans-IO boundary lets moq-uring receive from the kernel's -buffer ring and transmit into registered buffers, with no copy between the -kernel and the crypto. The API may break; it is in-tree. +buffer ring and transmit into caller-owned buffers, with no copy between the +kernel and the crypto. This quest owns the transmit contract; registering +those buffers with the ring is +[#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)'s. The API may break; it is in-tree. ## Plan @@ -18,13 +20,17 @@ Candidates, to be ranked by the profile: - `Endpoint::handle` accepts a foreign-owned buffer (a buffer-ring slot), and stream frames keep references to it instead of requiring an owned `BytesMut`. -- `poll_transmit` writes into a caller slice or registered buffer as a - contract, not by relying on `Vec` capacity. +- `poll_transmit` writes into a caller-owned slice as a contract, not by + relying on `Vec` capacity. - One `handle` call takes a whole GRO batch. -Registered TX buffers ([#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)) -and `SENDMSG_ZC` ([#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md)) -build on the transmit contract. Report relay CPU per Gbps before and after on +Decided 2026-10-08: `SENDMSG_ZC` +([#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md)) +and registered TX buffers +([#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)) +Require this quest and build on its transmit contract, so the contract is +settled once; registering buffers stays with #3204, which measures whether +it pays. Report relay CPU per Gbps before and after on the same workloads. ## Related diff --git a/quest/m2/quic-probe.md b/quest/m2/quic-probe.md index 6256b0946ee..afb417ec2ac 100644 --- a/quest/m2/quic-probe.md +++ b/quest/m2/quic-probe.md @@ -52,6 +52,6 @@ retain the baseline and record why before exposing an ineffective option. - [Viewer up-switch](/quest/m2/viewer-upswitch.md) - the viewer side, which requires this - [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - separate ProbeRTT policy experiment -- [GCC egress experiment](/quest/m3/quic-gcc.md) - delay control changes what headroom means +- [QUIC receive-timestamps spike](/quest/m3/quic-gcc.md) - measures forward delay, which a later delay-based controller would read headroom from - [noq#811](https://github.com/n0-computer/noq/issues/811) - probing while app-limited, proposed to n0 - [noq#476](https://github.com/n0-computer/noq/issues/476) - the earlier bitrate-probing ask diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index c85b56ffc8e..b43360fc938 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -18,7 +18,7 @@ re-clamps a live encoder. The grant's wire shape is specified in `drafts/draft-lcurley-moq-auth.md` (which the in-band auth line adds); update it in the same PR and run `just drafts check`. Wire work targets the wip lite version until it is cut -(decided 2026-10-05, see [AUTH on the wip version](/quest/m1/auth/wip-version.md)), +(decided 2026-10-05, see [In-band auth](/quest/m1/auth/README.md)), and the Auth Stream exists only there, so the rates ride only the wip version's grant. diff --git a/quest/m2/rate-quic.md b/quest/m2/rate-quic.md index 324057823f8..15b3d653caf 100644 --- a/quest/m2/rate-quic.md +++ b/quest/m2/rate-quic.md @@ -35,8 +35,8 @@ backpressure the peer cannot ignore, rather than metering and closing. cannot bank a full default window and spend it after a low cap arrives. After auth the relay raises it through the `set_limits` seam: the normal window for an uncapped session, paced credit for a capped one. A lowered - cap (revalidation, a union shrinking) uses noq-proto's shrink-as-debt - `set_receive_window` behavior, described in + cap (revalidation, a union shrinking) uses `moq-quic`'s shrink-as-debt + `Connection::set_receive_window` (`rs/moq-quic/src/connection/mod.rs`), described in [peer limits](/quest/m1/quic/peer-limits.md), so the overshoot is bounded by the credit outstanding at the change and the test asserts that bound. @@ -47,7 +47,8 @@ backpressure the peer cannot ignore, rather than metering and closing. rides the CONNECT URL or arrives in band), so it is set on a live connection and reset on revalidation or a union change. Reuse the runtime limits seam [peer limits](/quest/m1/quic/peer-limits.md) adds - (`set_limits(Limits)` on the `web-transport-moq` session), extended with + (`set_limits(Limits)` on moq-net's transport trait, implemented by the + moq-tokio and moq-uring adapters after the fork switch), extended with the two rates. - Lands in `moq-quic`, so it waits for the [fork](/quest/m1/quic/fork/README.md). The relay drops its refusal for QUIC sessions in the same PR. diff --git a/quest/m2/tls-listener-mtls.md b/quest/m2/tls-listener-mtls.md index 95a2d3f1341..9c5ff1cccb4 100644 --- a/quest/m2/tls-listener-mtls.md +++ b/quest/m2/tls-listener-mtls.md @@ -29,8 +29,15 @@ them there. Once a `tls://` listener verifies the certificate, this quest lifts that refusal for a server with a `tls://` listener and updates the refusal's test. +Decided 2026-10-08: request the certificate optionally, never require it, +and only on the moq-ALPN TLS config, so once +[the TCP acceptor](/quest/m2/one-port/tcp-demux.md) shares the port with +HTTP and RTMPS, those clients are never asked for one. Whichever lands second +keeps both working. + Public API: relay config may gain a listener option. Wire: none. ## Related +- [TCP acceptor](/quest/m2/one-port/tcp-demux.md) - carries `tls://` on the shared TCP port, where the certificate request stays on the moq ALPN - [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - moves qmux in-tree; if it lands first, the peer-certificate accessor lands here instead of upstream diff --git a/quest/m2/transport-adapter-dedup.md b/quest/m2/transport-adapter-dedup.md index 39f0dbc1d36..2e557dcdf2d 100644 --- a/quest/m2/transport-adapter-dedup.md +++ b/quest/m2/transport-adapter-dedup.md @@ -14,4 +14,17 @@ Revisit that here: share one copy from an existing crate (for example moq-net be feature, or one backend re-exporting it to the others), or record why the copies stay. Add the `poll_read_buf` cap test either way. +Decided 2026-10-08: backend-specific `moq-quic` methods (`poll_acked`, +`set_deadline`, `set_limits`) stay out of the shared generic adapter; moq-tokio +and moq-uring keep their own adapter code for those. The shared copy covers +only what every backend implements the same way, so a QUIC-only seam never +forces a default onto the browser, wasm, or FFI backends. + Public API: possibly a feature-gated module. Wire: none. + +## Related + +- [poll_acked on moq-net's send stream](/quest/m2/quic-ack-hook.md) - a backend-specific method the moq-tokio and moq-uring adapters keep +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - adds `set_deadline`, also kept out of the shared adapter +- [QUIC caps](/quest/m2/rate-quic.md) - extends `set_limits` with the bitrate caps +- [Peer limits](/quest/m1/quic/peer-limits.md) - adds the `set_limits` seam diff --git a/quest/m2/vaapi-vulkan-import.md b/quest/m2/vaapi-vulkan-import.md index 688c0b18317..38e41d74dfe 100644 --- a/quest/m2/vaapi-vulkan-import.md +++ b/quest/m2/vaapi-vulkan-import.md @@ -6,7 +6,10 @@ An external `Surface::Vulkan` exported as a DMA-BUF with a DRM format modifier, from a producer that synchronizes explicitly through a timeline, encodes through VA-API on Intel (iHD) without a CPU round trip. An ignored hardware test proves it on an Arrow Lake iGPU, and -`Kind::Auto` picks VA-API for a surface on an Intel device. +`Kind::Auto` picks VA-API for a surface on an Intel device, through the same +seam as [Vulkan encode](/quest/m2/vulkan-encode.md): `encode::Config::input` +and a VA-API candidate with `vulkan: true` in +`rs/moq-video/src/encode/backend/mod.rs`. This is the by-design proof that the surface is not shaped around one vendor: the same type reaches CUDA, Vulkan Video, and VA-API. @@ -44,6 +47,9 @@ sync_file import, so an explicit-sync producer races it. render node's `dev_t` in the surface, read from its own `VK_EXT_physical_device_drm`, and VA-API opens that node. It is the one device identity [GPU health](/quest/m2/gpu-health.md) keys by too. + It landed in #4975 as `frame::vulkan::Device { device_uuid, driver_uuid, + render_node: Option }`. VA-API refuses a surface with no + `render_node`, since it has no other way to pick a node. Rejected: mapping the surface's UUID to a node on the VA-API side, which needs a Vulkan instance there. @@ -59,7 +65,7 @@ the two-node host, also check that a surface carrying `renderD129`'s first render node: the second-node check moved here from [Video hardware validation](/quest/m3/video-hardware.md) (2026-10-06 audit). -Public API: none beyond the surface quest's. Wire: none. +Public API: none; the surface landed in #4975. Wire: none. ## Related diff --git a/quest/m2/vulkan-encode.md b/quest/m2/vulkan-encode.md index ed52c93e109..7c4b01f34d8 100644 --- a/quest/m2/vulkan-encode.md +++ b/quest/m2/vulkan-encode.md @@ -6,7 +6,9 @@ moq-video encodes an external `Surface::Vulkan` with Vulkan Video on AMD (RADV), in H.264 and H.265, scaled per rendition on the GPU, with no CPU round trip. An ignored hardware test proves it on an RX 9070, and `Kind::Auto` picks this backend for a surface on an AMD device -with no caller change. +with no caller change: the caller sets `encode::Config::input`, and the +backend registers as a hardware candidate with `vulkan: true` in +`rs/moq-video/src/encode/backend/mod.rs`. Non-goal: running CARLA itself on AMD. @@ -31,7 +33,7 @@ added this quest): `VK_KHR_external_memory_fd` and `VK_KHR_external_semaphore_fd` itself. That lets it import the producer's `OPAQUE_FD` BGRA image as a dedicated allocation with create info identical to the exporter's. It also leaves - intra refresh and AV1 possible later. + AV1 possible later. - H.264 and H.265. AV1 is out of scope. - The bar is no CPU round trip; GPU-side copies are allowed. @@ -53,13 +55,11 @@ Building it: - It carries the final `VK_KHR_video_encode_queue`, `_h264`, `_h265`, and `VK_KHR_video_maintenance1`, with the tuning, buffer, and B-frame fields above. - - It lacks `VK_KHR_video_encode_intra_refresh`, `_quantization_map`, and - `_av1`. Those need a newer ash and are out of scope; refresh mode is - refused on this backend. - - moq-video uses ash 0.38 only as a dev-dependency (the Vulkan/CUDA test - producer, through the workspace's `ash = "0.38"`). wgpu-hal 30, under - `render`, depends on the same 0.38. Make it a normal optional dependency - of this backend's feature. + - It lacks `_quantization_map` and `_av1`, which need a newer ash and are + out of scope. + - ash is already an optional dependency of moq-video (#4975, used by the + `nvidia` feature). This backend's feature enables `dep:ash` the same way. + wgpu-hal 30, under `render`, depends on the same 0.38. - Packaging: Fedora's stock Mesa omits the H.264 and H.265 encoders. A device without the extensions is refused with an error naming them, and the hardware recipe reports them as missing instead of failing obscurely. @@ -76,4 +76,4 @@ Public API: a new encoder backend and feature. Wire: none. ## Related - [VA-API encodes an external Vulkan image](/quest/m2/vaapi-vulkan-import.md) - the Intel half of the same proof -- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - refresh mode this backend refuses until ash carries the extension +- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - import and playback of intra-refresh video, which this encoder does not produce diff --git a/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md index 260460eddf6..539160eaf9d 100644 --- a/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md +++ b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md @@ -41,6 +41,7 @@ ships in no package. ## Required +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - owns the transmit contract zero-copy sends build on - [A physical-NIC peer for the zero-copy sweep](/quest/m3/zero-copy-peer.md) - loopback only measures the forced copy ## Closes diff --git a/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md index 05aa724c3d3..5dfc39bdd24 100644 --- a/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md +++ b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md @@ -40,6 +40,7 @@ experiment it builds on moved to m3 too. ## Required +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - owns the transmit contract; this quest owns registering its buffers - [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - the zero-copy send experiment this extends ## Closes diff --git a/quest/m3/README.md b/quest/m3/README.md index a9f48084298..a1782fd6129 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -26,13 +26,13 @@ m4's upstream waits in here and moved m2 work with no consumer. - [Catalog colour model](/quest/m3/color-catalog.md) - the catalog describes a rendition's colour and HDR properties once a renderer consumes them - [#2147](/quest/m3/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - NVIDIA Main10 encode, once a 10-bit source exists in the pipeline - [Embedded video](/quest/m3/video-embedded.md) - verify a Pi 4/5 presents through the existing Vulkan and CPU paths, adding EGL import only if that fails -- [Multi-plane PipeWire cameras](/quest/m3/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane capture, if the hardware pass finds one +- [Multi-plane PipeWire cameras](/quest/m3/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane capture - [Video codec coverage](/quest/m3/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps once a consumer asks - [A physical-NIC peer for the zero-copy sweep](/quest/m3/zero-copy-peer.md) - the rig the zero-copy sweep runs on - [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first - [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends - [Stream sessions on the ring](/quest/m3/uring-tcp/README.md) - WebSocket and HTTP on the io_uring workers, gated on the ablation; no fleet asks for ring TCP yet -- [#3202](/quest/m3/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: fixed-file slots for worker UDP sockets, if the ablation measures a win +- [#3202](/quest/m3/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: fixed-file slots for worker UDP sockets, if its own benchmark measures a win - [#3129](/quest/m3/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring writes the WebTransport stream header at open and settles the open contract, once a caller hits it - [QUIC receive timestamps](/quest/m3/quic-gcc.md) - a spike measuring receive timestamps in ACKs on native and relay-to-relay egress; delay-based control only if it justifies one - [L4S on the backbone](/quest/m3/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement, if the ECN measurement says marks survive @@ -43,7 +43,7 @@ m4's upstream waits in here and moved m2 work with no consumer. - [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the same tarball to `conan install` - [Linux OBS GPU input](/quest/m3/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination - [Routing cost domains](/quest/m3/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs -- [moq-transport cluster peers](/quest/m3/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, once a moq-transport relay operator asks +- [moq-transport cluster peers](/quest/m3/ietf-cluster-peers.md) - the cluster draft carries the route layer, so moq-transport relays peer again, once a moq-transport relay operator asks - [The moq.pro mesh runs lite-07](/quest/m3/lite07-mesh.md) - the deployment that makes the exemption dead code - [Drop the hidden cluster exemption](/quest/m3/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire - [Robot teleoperation primitive](/quest/m3/teleop-robot.md) - a `moq-robot` crate for video down and control up, once a robotics consumer appears @@ -66,7 +66,7 @@ m4's upstream waits in here and moved m2 work with no consumer. - [Paced replay](/quest/m3/archive-paced-replay.md) - a replay pushes its 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 -- [Closure counters](/quest/m3/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw +- [Closure counters](/quest/m3/closure-counters.md) - document and pin that a same-epoch rejoin within the grace may regress the closure counters retire advanced - [Interop runner withdraws before disconnecting](/quest/m3/interop-runner-approval.md) - condition: the maintainer approves posting and a released moq-tokio and @moq/net carry close() withdrawals - [Safari ships the WebKit 319818 fix](/quest/m3/webkit-319818.md) - the Safari release the gate admits - [Safari WebTransport](/quest/m3/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed diff --git a/quest/m3/archive-browser.md b/quest/m3/archive-browser.md index 1f909533d3d..6db8577b6ea 100644 --- a/quest/m3/archive-browser.md +++ b/quest/m3/archive-browser.md @@ -18,7 +18,7 @@ the object keys, envelope bytes, `.info` property values, and timeline discovery the Rust writer uses, per the [Recording section](/drafts/draft-lcurley-moq-hang.md#recording), without inferring catalog-to-group applicability. -[Catalog track identity](/quest/m2/catalog-tracks.md) addresses that separately. +[Catalog track identity](/quest/m1/catalog-tracks.md) addresses that separately. Use [JS ranges](/quest/m1/subscribe-ranges/js.md)'s on-demand range requests to answer cache misses from memory or OPFS after relay eviction. This quest owns diff --git a/quest/m3/archive-paced-replay.md b/quest/m3/archive-paced-replay.md index 845037ef644..69a87aea287 100644 --- a/quest/m3/archive-paced-replay.md +++ b/quest/m3/archive-paced-replay.md @@ -12,6 +12,15 @@ who joins late joins mid-replay. - Today `moq_archive::Reader` publishes only the timeline track live and serves media groups on FETCH through `broadcast::Dynamic`, so a subscriber sees none. + [Replay catalog](/quest/m1/archive/replay-catalog.md) adds the recorded + catalog live too. +- Decided 2026-10-08: the catalog paces on the same clock as the media, each + recorded catalog group emitted at its recorded time, so a viewer sees the + state that applied then. Left at its final live edge, a recording that ends + muted (`enabled: false`) or removes a rendition hides the earlier video, + since watch filters disabled renditions before subscribing. Test both. + At equal recorded timestamps the catalog goes first, so a media group never + arrives before the catalog update that lists it. - One clock per import, not per subscriber. It starts at the earliest recorded timestamp across the selected tracks and every track paces against it, so tracks stay in sync and every viewer sees the same moment. @@ -27,3 +36,7 @@ who joins late joins mid-replay. current group, and that two tracks stay aligned. - Deferred in the 2026-09-30 audit and moved to m3 in the 2026-10-05 audit: no named consumer; FETCH replay already serves DVR and HLS. + +## Required + +- [Replay catalog](/quest/m1/archive/replay-catalog.md) - publishes the recorded catalog live, which a live player needs before any paced media diff --git a/quest/m3/closure-counters.md b/quest/m3/closure-counters.md index 1682c1b5fa0..6596f2f1ee8 100644 --- a/quest/m3/closure-counters.md +++ b/quest/m3/closure-counters.md @@ -2,10 +2,11 @@ ## Goal -`moq_stats::aggregate` documents, and one test pins, what a same-lifetime +`moq_stats::aggregate` documents, and one test pins, what a same-epoch rejoin within the grace does to the `*_ended` counters that `Traffic`'s -`Mergeable::retire` advanced on departure, beside the existing restart -contract in `rs/moq-stats/src/aggregate.rs`. +`Mergeable::retire` advanced on departure: they may regress. A restart is not +this case: since #4904 it announces a new epoch, whose counters add to the +old one's kept contribution (`rs/moq-stats/src/aggregate.rs`). ## Plan @@ -24,8 +25,9 @@ counters intact, can show a lower `*_ended` value. The stickiness fix P2. Decided 2026-10-08: keep the current behavior (retire on departure, accept an -`*_ended` regression on rejoin), since it follows the same fresh-segment rule -as a restart and no consumer has asked for anything else. Rejected: keeping +`*_ended` regression on a same-epoch rejoin within the grace), since the +regression is bounded by the closures retire assumed, it ends once the node's +own counters pass them, and no consumer has asked for anything else. Rejected: keeping the retired values as a floor until the node's own counters pass them, which suppresses a still-live node's closures after a transient reader failure. Document it in the consumer-facing contract and add one test of a rejoin diff --git a/quest/m3/color-catalog.md b/quest/m3/color-catalog.md index 129dd936599..d786a726823 100644 --- a/quest/m3/color-catalog.md +++ b/quest/m3/color-catalog.md @@ -10,7 +10,8 @@ instead of guessing or reparsing the bitstream. ## Plan Deferred to m2 in the 2026-09-30 audit: no renderer consumes colour today, so -the model waits for one. Encoder colour correctness stays in m1 as +the model waits for one. Decided 2026-10-08: moved to m3; no renderer +consumes colour. Encoder colour correctness stays in m1 as [Encoder colour](/quest/m1/color-model.md). `rs/hang/src/catalog/video/mod.rs` has carried a bare `// TODO color space` since diff --git a/quest/m3/cpp-conan.md b/quest/m3/cpp-conan.md index 6c5acea7d9f..caa44a777a2 100644 --- a/quest/m3/cpp-conan.md +++ b/quest/m3/cpp-conan.md @@ -23,7 +23,11 @@ first. The vcpkg registry, which this reuses, is parked in m3 too (decided - CI: a consumer smoke project (`conan install` then CMake) built nightly on all three platforms. - conan-center is out of scope; it wants source builds. +- Decided 2026-10-08: like the vcpkg port, this needs the first C++ package + release, which #4079 adds as its own quest (`quest/m1/cpp-release.md`). + Once that file is on `main`, it replaces the line README as Required here. ## Required +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the release tarballs the recipe packages - [vcpkg registry](/quest/m3/cpp-vcpkg.md) - the release manifest and bump automation this reuses diff --git a/quest/m3/lite07-mesh.md b/quest/m3/lite07-mesh.md index ff8c5a92447..27de6b80481 100644 --- a/quest/m3/lite07-mesh.md +++ b/quest/m3/lite07-mesh.md @@ -10,11 +10,9 @@ this quest and every `Required` entry that links it. ## Plan -As of 2026-09-30 lite-07 ships only as the off-by-default `moq-lite-07-wip` -ALPN, and moq.pro still has its lite-07 rollout quest open -(`quest/m1/lite07.md` in moq-dev/moq.pro). That rollout waits on -[Finalize moq-lite-07](/quest/m1/lite07-finalize.md), so this condition cannot -clear before a release carries the final version. +moq.pro's lite-07 rollout is `quest/m2/lite07.md` in moq-dev/moq.pro. It +waits on [Finalize moq-lite-07](/quest/m1/lite07-finalize.md), so this +condition cannot clear before a release carries the final version. Decided 2026-10-05: [Cluster routing](/quest/m1/cluster-routing/README.md)'s route layer lands in lite-07, so the final lite-07 carries ROUTE and diff --git a/quest/m3/stats-encoder-feedback.md b/quest/m3/stats-encoder-feedback.md index 34932e0970e..1e8232607c8 100644 --- a/quest/m3/stats-encoder-feedback.md +++ b/quest/m3/stats-encoder-feedback.md @@ -29,8 +29,10 @@ covers the encode producers and `moq import --echo`, which need no ladder. - It folds the reports into one signal: the share of viewers stalled over the last interval and their late frame rate, weighted equally per viewer. - The counters are cumulative, so the handle keeps the previous snapshot - per viewer and diffs it. A counter that goes backwards means a restarted - viewer and resets that baseline. + per viewer, keyed by (path, epoch) like `moq_stats::aggregate`, and diffs + it. A restarted viewer announces a new epoch and gets a fresh baseline. + Only on a route without an epoch does a counter that goes backwards mean + a restart and reset that baseline. - A viewer counts toward a rendition while its latest snapshot has a row for that ID, so viewers of other rungs, or ones that switched away, never dilute the share. The announcement, not the age of its last diff --git a/quest/m3/uring-tcp/relay.md b/quest/m3/uring-tcp/relay.md index ebb4506edf5..4f05109b6f0 100644 --- a/quest/m3/uring-tcp/relay.md +++ b/quest/m3/uring-tcp/relay.md @@ -10,7 +10,8 @@ then pinned to one thread for its whole life, exactly like a QUIC one. `uring::Workers::bind` (`rs/moq-relay/src/uring.rs`) ignores `listen`'s `tcp`/`unix` listeners and points the operator at a separate `init_streams` -tokio server; the only thing it refuses is `tls.generate`. Replace the silent skip with real support: each +tokio server; it refuses only settings a worker cannot serve +(`tls.generate`, `lb_id`, several certificates). Replace the silent skip with real support: each worker binds its own listener in the reuseport group and runs the router from [stream](/quest/m3/uring-tcp/stream.md) on it.