From 39e9acd0fae2175ad4eef71596334fee5d578f8b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 01:31:31 -0800 Subject: [PATCH] quest: plan what the pre-cut audit decided An audit of everything on main since release, and of the lite-07 draft, ahead of the 0.22 cut. The maintainer decided each finding; this records them as m2 quests, moves and deletes the quests they supersede, and rewords two AGENTS.md rules. Co-Authored-By: Claude Fable 5.2 --- AGENTS.md | 4 +- quest/m0/test-flakes-3/py-socket-abort.md | 8 + quest/m1/README.md | 6 +- quest/m2/README.md | 86 ++++++++- quest/m2/archive-v2.md | 84 +++++++++ quest/m2/audio-sink-names.md | 48 +++++ quest/m2/auth-attach-token.md | 68 +++++++ quest/m2/auth-claims.md | 96 ++++++++++ quest/m2/auth-grants.md | 110 +++++++++++ quest/m2/browser-packages.md | 96 ++++++++++ quest/m2/catalog-at-timestamp.md | 4 + quest/m2/cluster-routes/acceptance.md | 6 + quest/m2/congestion-names.md | 86 +++++++++ quest/m2/dart-experimental.md | 73 ++++++++ quest/m2/delay-hole-wait.md | 73 ++++++++ quest/m2/drafts-retire.md | 69 +++++++ quest/m2/e2ee-crate.md | 110 +++++++++++ quest/m2/ffi-open-selectors.md | 95 ++++++++++ quest/m2/finish-sweep.md | 77 ++++++++ quest/m2/gateway-align.md | 99 ++++++++++ quest/m2/group-api.md | 112 ++++++++++++ quest/m2/group-drops.md | 21 ++- quest/m2/hang04/README.md | 55 ++++++ quest/m2/hang04/entry-version.md | 76 ++++++++ quest/m2/hang04/m2ts.md | 70 +++++++ quest/m2/hang04/shape.md | 90 +++++++++ quest/m2/hang04/sync.md | 93 ++++++++++ quest/m2/hang04/video-warmup.md | 102 +++++++++++ quest/m2/ietf-records-per-track.md | 89 +++++++++ quest/{m4 => m2}/ietf-time-addressing.md | 30 ++- quest/m2/js-net-api.md | 87 +++++++++ quest/m2/json-write-at.md | 66 +++++++ quest/m2/libmoq-name.md | 90 +++++++++ quest/m2/lite07-finalize.md | 36 +++- quest/m2/min-age-join.md | 89 +++++++++ quest/m2/multicast/README.md | 16 ++ quest/m2/multicast/switch.md | 114 +++++++++++- quest/m2/native-media-config.md | 84 +++++++++ quest/m2/net-renames.md | 86 +++++++++ quest/m2/path-escape.md | 92 ++++++++++ quest/m2/reconnect-off.md | 88 +++++++++ quest/m2/refresh-interval.md | 118 ++++++++---- quest/m2/relay-014-leftovers.md | 80 ++++++++ quest/m2/relay-config-names.md | 96 ++++++++++ quest/m2/relay-connect-keys.md | 72 ++++++++ quest/m2/relay-memory.md | 77 ++++++++ quest/m2/session-codes.md | 68 +++++++ quest/m2/signals-semantics.md | 78 ++++++++ quest/m2/sockets/README.md | 55 ++++++ quest/m2/sockets/boy.md | 83 +++++++++ quest/m2/sockets/carla.md | 89 +++++++++ quest/m2/sockets/remove.md | 96 ++++++++++ quest/m2/stats-old-names.md | 77 ++++++++ quest/m2/str0m-upstream.md | 106 +++++++++++ quest/m2/subscriber-min-age.md | 24 --- quest/m2/time-addressing/bindings.md | 20 ++ quest/m2/time-addressing/consumers.md | 145 +++++++++++++++ quest/m2/time-addressing/js.md | 17 ++ quest/m2/time-addressing/lite07.md | 126 +++++++++++-- quest/m2/transport-names.md | 87 +++++++++ quest/m2/ts-typed-outcomes.md | 78 ++++++++ quest/m2/ui-private.md | 79 ++++++++ quest/m2/unused-api/README.md | 43 +++++ quest/m2/unused-api/js.md | 105 +++++++++++ quest/m2/unused-api/media.md | 103 +++++++++++ quest/m2/unused-api/net.md | 85 +++++++++ quest/m2/unused-api/transport.md | 122 ++++++++++++ quest/m2/vaapi-exports.md | 55 ++++++ quest/m2/video-producer.md | 74 ++++++++ quest/m2/webrtc-bind.md | 84 +++++++++ quest/m2/yield-defer.md | 109 +++++++++++ quest/m3/README.md | 4 +- quest/m3/audio-playout-library.md | 13 ++ quest/m3/c/README.md | 12 +- quest/m3/crates-trusted-publisher.md | 14 +- quest/m3/e2ee-format.md | 173 ++++++++++++++++++ quest/m3/ffi-exporter.md | 47 ++++- quest/m3/group-takeover.md | 79 ++++++-- quest/m3/groups-never-overlap.md | 2 + quest/m3/ietf-finish.md | 35 ---- quest/m3/ietf-hole-stall.md | 46 ----- quest/m3/ietf-join-pin-head.md | 6 +- quest/m3/lite-finished-across-updates.md | 36 ---- quest/m3/obs-moq-video/adapter.md | 2 +- quest/m3/one-port/rtc-feed.md | 5 +- quest/m3/release/api-review.md | 58 ++++-- quest/m3/release/c-publish.md | 18 +- quest/m3/release/c-retire.md | 43 ++--- quest/m3/release/cut.md | 25 +++ quest/m3/release/dart-publish.md | 8 + quest/m3/release/demo-sockets-deploy.md | 51 ------ quest/m3/release/demos-deploy.md | 62 +++++++ quest/m3/release/feature-flags.md | 7 +- quest/m3/release/feature-review.md | 32 ++++ quest/m3/release/libmoq-final-release.md | 20 -- quest/m3/release/libmoq-retire.md | 18 -- quest/m3/release/npm-first-publish.md | 9 +- quest/m3/release/retired-names.md | 17 +- quest/m3/rtc-pacing.md | 19 +- quest/m3/srt-rate-handle.md | 11 +- quest/m3/time-addressing-consumers.md | 64 ------- quest/m3/vendor-sync/webrtc-stack.md | 6 + quest/m3/webrtc/README.md | 65 +++++-- quest/m3/webrtc/dtls-after-ice.md | 6 + quest/m3/webrtc/dtls-timeout.md | 14 ++ quest/m3/whip-whep-browser.md | 10 +- quest/m4/hang-thumbnail.md | 7 +- quest/m4/ietf-range-fetch.md | 8 +- quest/m4/intra-refresh/README.md | 15 +- quest/m4/intra-refresh/catalog-warmup.md | 46 +++++ quest/m4/intra-refresh/consumer-warmup.md | 7 +- quest/m4/intra-refresh/dual-decoder.md | 16 +- quest/m4/intra-refresh/h264-import.md | 4 + quest/m4/track-info-docs.md | 6 +- quest/m4/upstream-reports.md | 13 +- quest/m4/webrtc-browser-only.md | 2 + quest/m4/webrtc-clock.md | 2 + quest/m4/webrtc-dead-api.md | 2 + quest/m4/webrtc-sdp-bandwidth.md | 6 +- quest/m5/carla-bridge.md | 6 + quest/m5/e2ee/README.md | 16 +- quest/m5/e2ee/cli.md | 6 +- quest/m5/e2ee/consumer.md | 15 +- quest/m5/e2ee/js-undeclared-names.md | 4 +- quest/m5/e2ee/rust-publish.md | 17 +- quest/m5/ffi-e2ee.md | 19 +- quest/m5/net-wrap/README.md | 2 +- quest/m5/net-wrap/e2ee.md | 76 ++++---- quest/m5/net-wrap/js.md | 16 +- quest/m5/net-wrap/json.md | 4 +- quest/m5/net-wrap/mux.md | 2 +- quest/m5/net-wrap/traits.md | 2 +- quest/m5/probe-padding.md | 13 +- quest/{m3 => m5}/ts-multi-program-restart.md | 11 ++ .../tests/integration/subscribe_ranges.rs | 10 - sh/gh/test-inventory.allow | 3 - test/interop/README.md | 5 +- test/interop/interop.sh | 4 +- 138 files changed, 6135 insertions(+), 602 deletions(-) create mode 100644 quest/m2/archive-v2.md create mode 100644 quest/m2/audio-sink-names.md create mode 100644 quest/m2/auth-attach-token.md create mode 100644 quest/m2/auth-claims.md create mode 100644 quest/m2/auth-grants.md create mode 100644 quest/m2/browser-packages.md create mode 100644 quest/m2/congestion-names.md create mode 100644 quest/m2/dart-experimental.md create mode 100644 quest/m2/delay-hole-wait.md create mode 100644 quest/m2/drafts-retire.md create mode 100644 quest/m2/e2ee-crate.md create mode 100644 quest/m2/ffi-open-selectors.md create mode 100644 quest/m2/finish-sweep.md create mode 100644 quest/m2/gateway-align.md create mode 100644 quest/m2/group-api.md create mode 100644 quest/m2/hang04/README.md create mode 100644 quest/m2/hang04/entry-version.md create mode 100644 quest/m2/hang04/m2ts.md create mode 100644 quest/m2/hang04/shape.md create mode 100644 quest/m2/hang04/sync.md create mode 100644 quest/m2/hang04/video-warmup.md create mode 100644 quest/m2/ietf-records-per-track.md rename quest/{m4 => m2}/ietf-time-addressing.md (67%) create mode 100644 quest/m2/js-net-api.md create mode 100644 quest/m2/json-write-at.md create mode 100644 quest/m2/libmoq-name.md create mode 100644 quest/m2/min-age-join.md create mode 100644 quest/m2/native-media-config.md create mode 100644 quest/m2/net-renames.md create mode 100644 quest/m2/path-escape.md create mode 100644 quest/m2/reconnect-off.md create mode 100644 quest/m2/relay-014-leftovers.md create mode 100644 quest/m2/relay-config-names.md create mode 100644 quest/m2/relay-connect-keys.md create mode 100644 quest/m2/relay-memory.md create mode 100644 quest/m2/session-codes.md create mode 100644 quest/m2/signals-semantics.md create mode 100644 quest/m2/sockets/README.md create mode 100644 quest/m2/sockets/boy.md create mode 100644 quest/m2/sockets/carla.md create mode 100644 quest/m2/sockets/remove.md create mode 100644 quest/m2/stats-old-names.md create mode 100644 quest/m2/str0m-upstream.md delete mode 100644 quest/m2/subscriber-min-age.md create mode 100644 quest/m2/time-addressing/consumers.md create mode 100644 quest/m2/transport-names.md create mode 100644 quest/m2/ts-typed-outcomes.md create mode 100644 quest/m2/ui-private.md create mode 100644 quest/m2/unused-api/README.md create mode 100644 quest/m2/unused-api/js.md create mode 100644 quest/m2/unused-api/media.md create mode 100644 quest/m2/unused-api/net.md create mode 100644 quest/m2/unused-api/transport.md create mode 100644 quest/m2/vaapi-exports.md create mode 100644 quest/m2/video-producer.md create mode 100644 quest/m2/webrtc-bind.md create mode 100644 quest/m2/yield-defer.md create mode 100644 quest/m3/e2ee-format.md delete mode 100644 quest/m3/ietf-finish.md delete mode 100644 quest/m3/ietf-hole-stall.md delete mode 100644 quest/m3/lite-finished-across-updates.md delete mode 100644 quest/m3/release/demo-sockets-deploy.md create mode 100644 quest/m3/release/demos-deploy.md delete mode 100644 quest/m3/release/libmoq-final-release.md delete mode 100644 quest/m3/release/libmoq-retire.md delete mode 100644 quest/m3/time-addressing-consumers.md create mode 100644 quest/m4/intra-refresh/catalog-warmup.md rename quest/{m3 => m5}/ts-multi-program-restart.md (74%) diff --git a/AGENTS.md b/AGENTS.md index a3c59a50e4c..97897a61201 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ The API is the most important thing to get right: a bad shape costs a breaking c - Nest related API, configuration, and output fields under their shared role. - Mirror API names across Rust, JS, and the bindings. - Keep package boundaries modular and reusable; prefer a module in an existing package over a one-off package. -- Never mark a special case inside a value: not a huge number like `u64::MAX` (it is the longest varint), and not a reserved prefix or character in a string. Use 0, a separate message or type, a typed field, or a boolean. +- Never mark a special case inside a value: not a huge number like `u64::MAX` (it is the longest varint), and not a reserved prefix or character in a string. Use 0, a separate message or type, a typed field, or a boolean. The one exception is a path segment's leading `.`, which hides the path from announce discovery. - Enforce a policy where the thing is created, not where it is checked: the signer bounds a token's lifetime, and the verifier accepts what a valid token carries. Don't add `allow-*` opt-out flags; move or generalize the rule. # Development @@ -50,7 +50,7 @@ Review locally with one reviewer, not the pair: `quest review --harness codex`, # Cross-Package Sync -`moq-ffi` powers every SDK except Rust and JS. Keep all languages and wrappers at the same functionality. +`moq-ffi` powers every SDK except Rust and JS. A feature reaches the bindings when a binding user needs it; every language and wrapper then gets it together. A Rust change with a JS counterpart updates both in the same PR: `moq-net` and `js/net`, `hang` and `js/hang`, `moq-auth` and `js/auth`. A wire-format change updates its matching draft in the same PR: framing, fields, enum values, and version negotiation. Wire, `moq-ffi`, or gateway changes also run `just test interop --all`; plain `interop` is Rust-only. diff --git a/quest/m0/test-flakes-3/py-socket-abort.md b/quest/m0/test-flakes-3/py-socket-abort.md index 0a812ac15fd..8e96b579410 100644 --- a/quest/m0/test-flakes-3/py-socket-abort.md +++ b/quest/m0/test-flakes-3/py-socket-abort.md @@ -21,4 +21,12 @@ ending of a socket endpoint run its cleanup and likely fixes it: run the test alone in a loop on a base that includes it. If it no longer fails, delete this quest; if it does, the cause lies elsewhere. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): socket +endpoints leave moq for Kixel, and +[their removal](/quest/m2/sockets/remove.md) deletes this test with the +Python wrapper. So do not fix the endpoint here. If the test still flakes +before the removal lands, skip it with the removal quest as its owner and +delete this quest; the removal deletes this quest otherwise. Kixel's port +inherits the race, which goes in that PR's follow-ups for Kixel's tree. + Public API: none. Wire: none. diff --git a/quest/m1/README.md b/quest/m1/README.md index e0eff517573..691309b210e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -24,6 +24,8 @@ because a downstream iGPU transcode trial needs it now. Decided 2026-11-13 (maintainer, /quest-run): stream-credit stays in m1 and no longer gates m2, since takeover, its only wire change, moved to m3. +Its YIELDED continuations leave lite-07 again in m2 +([yield-defer](/quest/m2/yield-defer.md), 2026-11-16). Decided 2026-11-12 (maintainer, /quest-audit before the cut): @@ -38,7 +40,9 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): a downstream application builds on them from `main` now. Superseded 2026-11-13, below, and 2026-11-14 (maintainer): byte streams moved to Kixel, which builds its own on moq-net's public API, and sockets dropped their - `tcp` protocol. + `tcp` protocol. Socket endpoints followed on 2026-11-16 (maintainer, + /quest-plan of the pre-cut audit): [they leave moq](/quest/m2/sockets/README.md) + for Kixel before the cut. - ✅ Also moved here: the two reconnect fixes whose bugs came from PRs that are on `main` and not on `release`, so the cut would publish them; the Go module proxy, since the mirror repository nears 1 GB; and the ashpd bump. diff --git a/quest/m2/README.md b/quest/m2/README.md index 44f31144ac8..99aebcab693 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -9,6 +9,82 @@ complete it before cutting main into release. ## Plan +Decided 2026-11-16 (maintainer, /quest-plan of an audit of everything on +`main` since `release`, and of the lite-07 draft): the cut also waits on what +that audit found. Fifteen reviewers judged about 480 work lines for a +long-term purpose and a caller, against moq.pro's and Kixel's roadmaps; the +maintainer decided each finding in a 15-round interview, and each quest's +Plan records its decision with what was rejected. The audit reopened the 50 +work lines the 2026-11-14 [feature review](/quest/m3/release/feature-review.md) +judged "ship as is". Everything below is breaking by this milestone's rule: a +removal, a rename, or a wire, catalog, or format change that is free until +0.22 publishes it. + +- **lite-07 wire.** [YIELDED continuations](/quest/m2/yield-defer.md) leave + for lite-08; [the ietf extension](/quest/m2/ietf-records-per-track.md) + costs nothing on a moq-lite track; [the path escape](/quest/m2/path-escape.md) + is finished; [Subscriber Min Age](/quest/m2/min-age-join.md) stays and + gains its reader, reversing 2026-11-14; and + [lite-07 by start](/quest/m2/time-addressing/lite07.md) carries the + smaller wire fixes. [Refresh](/quest/m2/refresh-interval.md) and + [group drops](/quest/m2/group-drops.md) took simpler contracts. + [moq-transport time addressing](/quest/m2/ietf-time-addressing.md) + returned from m4, and the two moq-transport interop quests in m3 were + deleted. Kept as they are: datagram tracks with their lite-05/06 bridge, + all seven lite versions, the hidden `.` path prefix, and the route plan + of [cache-aware multicast](/quest/m2/multicast/README.md), whose + [switch](/quest/m2/multicast/switch.md) also settles the public route API + and retires the moq-cluster draft. +- **moq-net API.** [Groups](/quest/m2/group-api.md), + [reconnect](/quest/m2/reconnect-off.md), [names](/quest/m2/net-renames.md), + and [session codes](/quest/m2/session-codes.md). + [Socket endpoints](/quest/m2/sockets/README.md) leave for Kixel, and the + demos return to their earlier format. +- **Unused API.** [One sweep per area](/quest/m2/unused-api/README.md), each + item re-checked for a downstream caller first. +- **Relay and transports.** [Memory](/quest/m2/relay-memory.md), which the + cut waits on by name; [congestion names](/quest/m2/congestion-names.md); + [config names](/quest/m2/relay-config-names.md), + [the two dial keys](/quest/m2/relay-connect-keys.md), and + [the 0.14 leftovers](/quest/m2/relay-014-leftovers.md); + [transport names](/quest/m2/transport-names.md); and + [stats names](/quest/m2/stats-old-names.md). +- **Auth and crypto.** [Grants](/quest/m2/auth-grants.md), + [claims](/quest/m2/auth-claims.md), and + [the attached token](/quest/m2/auth-attach-token.md). End-to-end encryption + [is its own unpublished crate again](/quest/m2/e2ee-crate.md); its + [finished format](/quest/m3/e2ee-format.md) follows in m3. +- **Catalog, drafts, and formats.** [hang-04](/quest/m2/hang04/README.md) + (the `sync` section, a version per entry, no video `warmup`, `m2ts` under + `mpegts`, one strict rule); [dead drafts](/quest/m2/drafts-retire.md); + [the archive as version 2](/quest/m2/archive-v2.md); + [declared ends](/quest/m2/time-addressing/consumers.md), back from m3; + [finish](/quest/m2/finish-sweep.md), [TS outcomes](/quest/m2/ts-typed-outcomes.md), + and [moq-json writes](/quest/m2/json-write-at.md). +- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md), + [the hole wait](/quest/m2/delay-hole-wait.md), + [device and cursor](/quest/m2/native-media-config.md), + [sink names](/quest/m2/audio-sink-names.md), + [moq-vaapi's exports](/quest/m2/vaapi-exports.md), + [the WebRTC bind](/quest/m2/webrtc-bind.md), + [gateway admission](/quest/m2/gateway-align.md), and + [upstream str0m](/quest/m2/str0m-upstream.md), which reverses the + 2026-10-30 vendoring. +- **JS and browser.** [`@moq/net`](/quest/m2/js-net-api.md), + [signals](/quest/m2/signals-semantics.md), [`@moq/ui`](/quest/m2/ui-private.md), + and [room, publish, and OBS names](/quest/m2/browser-packages.md). +- **Bindings.** [Open selectors](/quest/m2/ffi-open-selectors.md), + [Dart as experimental](/quest/m2/dart-experimental.md), and + [the C API as `libmoq`](/quest/m2/libmoq-name.md), reversing 2026-10-25. + The bindings break twice by decision: at 0.22, and again at + [the exporter switch](/quest/m3/ffi-exporter.md). + +Two rules changed with it (AGENTS.md): a feature reaches the bindings when a +binding user needs it, and a path segment's leading `.` is the one marker +allowed inside a value. Not reopened: AUTH_ERROR's retry codes (2026-11-14) +and AUTH_OK's rate fields, which wait for lite-08 +([rate grant](/quest/m5/rate-grant.md)). + Decided 2026-11-15 (maintainer, /quest-plan on the whole route layer): ✅ the cut waits on [cache-aware multicast](/quest/m2/multicast/README.md), which replaces lite-07's route layer before it freezes (rejected: lite-08). The @@ -232,10 +308,12 @@ what would need a breaking release had it landed right after the cut: returned to m2 on 2026-11-15 (maintainer, on [moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)) and became the request quest of [cache-aware multicast](/quest/m2/multicast/README.md); - [media consumers](/quest/m3/time-addressing-consumers.md) to m3 (its API - breaks ride the model; dropping hang's markers is tolerated by readers); - [moq-transport time addressing](/quest/m4/ietf-time-addressing.md) to m4 - (low-priority compatibility, no named consumer); and the + [media consumers](/quest/m2/time-addressing/consumers.md) to m3 (its API + breaks ride the model; dropping hang's markers is tolerated by readers), + until it returned to m2 on 2026-11-16; + [moq-transport time addressing](/quest/m2/ietf-time-addressing.md) to m4 + (low-priority compatibility, no named consumer), until it returned to m2 + on 2026-11-16; and the [Playwright bump](/quest/m1/playwright-pin.md) to m1, which the release cut requires in place of lite07-finalize (its strict interop lane needs Chromium 158), with lite07-finalize checking Chromium 158 once by hand. The E2EE nonce diff --git a/quest/m2/archive-v2.md b/quest/m2/archive-v2.md new file mode 100644 index 00000000000..d674381facb --- /dev/null +++ b/quest/m2/archive-v2.md @@ -0,0 +1,84 @@ +# [M] The archive format ships as version 2, and readers accept only it + +## Goal + +The stored format `moq-archive` writes at the cut is version 2, the +successor to the version 1 that `release` ships, and it is one format: the +reader accepts exactly version 2 and names the version it refused. The code +for the layouts main called 2, 3, and 4, none of which was ever published, +is gone, and `rs/moq-archive/src/lib.rs`'s format description matches what +the reader uses. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Ship as version 2, and the reader accepts exactly it (rejected: + bumping to 5 as the one version at the cut; keeping 4 and deleting only + the legacy paths; freezing as is). The number counts published formats: + 2, 3, and 4 only ever existed on main. + +Facts found by the audit: + +- `rs/moq-archive/src/lib.rs` has `VERSION = 4` and `VERSION_MIN = 2`; + `origin/release` has `VERSION = 1`, a different layout that main already + cannot read. +- The reader still carries the unpublished layouts: + `rs/moq-archive/src/layout.rs` (`LEGACY_GROUP`, `legacy = version < 4`, + the three-field entry) and `rs/moq-archive/src/info.rs` (the version 2 + priority byte, and the `VERSION_MIN..=VERSION` range checks in both + files). +- [moq-dev/moq#8638](https://github.com/moq-dev/moq/pull/8638) changed + what version 4 means without bumping it: the entry sequence and the + key's group field became the group's start + (`rs/moq-archive/src/producer/track.rs`, `let sequence = group.start`). + A version 4 archive written before it and one written after disagree. +- The object key is `--`. Since #8638 the consumer + drops the third field: `rs/moq-archive/src/consumer/index.rs` keeps + `(start.group, start.frame)` and says "a group's sequence is its start, + so these sort by time too", while `lib.rs` still says the listing + "answers group and time lookups". The producer reads `pts` back to + resume (`producer/track.rs`). +- `.info` and the layout structs use `deny_unknown_fields` + (`info.rs`, `layout.rs` twice), so no field can be added without a + version bump. + +Recommendations for the PR (not decided): + +- The key's ``: use it or remove it. A field every implementer must + write and validate, and no reader uses, is what a freeze makes + permanent. Removing it needs the producer's resume to recover the + timestamp another way (the object's first frame); if that costs a GET + per resume, keeping the field and making the consumer's time lookup use + it is the better end. Say which in the PR. +- Tolerate unknown fields in `.info` and the layout records, so version 2 + can gain an optional field without becoming version 3. Keep + `deny_unknown_fields` only where an ignored field would change what the + bytes mean. +- Decide on purpose whether per-frame timestamps stay absolute while + sequences are delta coded; the audit had low confidence it matters. + +For the PR: + +- First check moq.pro for stores written by a main build (its staging + recorder): those archives say 2, 3, or 4 and mean something else. The + format is unpublished, so they are rewritten or discarded, not read; + the Impact section says so. A deployed store that must stay readable is + the one thing that reopens the decision. +- A version 1 archive stays unreadable, as on main today; the error names + the version found and the one supported, so nobody mistakes a release + archive for a corrupt one. +- Update `doc/concept/archives.md` and the crate docs to the one format. + +Tests: a version 2 archive round-trips through producer and consumer; an +`.info` or layout that says 1, 3, or 4 is refused with the typed version +error; resume after a restart finds the last object; if unknown fields are +tolerated, a record with an extra field reads. + +Public API: none expected beyond the version constants. Wire: the stored +archive format; archives written by any main build before this are not +read. + +## Related + +- [Media consumers address groups by start](/quest/m2/time-addressing/consumers.md) - the model that made the key's group field a start diff --git a/quest/m2/audio-sink-names.md b/quest/m2/audio-sink-names.md new file mode 100644 index 00000000000..4eda8640092 --- /dev/null +++ b/quest/m2/audio-sink-names.md @@ -0,0 +1,48 @@ +# [XS] The audio sink's silence markers say what they declare + +## Goal + +`moq_audio::playback::Sink` declares a publisher's announced silence and the +start of the next utterance under names that say so (recommended: +`silence()` and `resume()`), not `end()` and `next()`. `end()` no longer sits +beside `finish()` on a type it does not end. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Rename the two methods before the cut (rejected: keep; hide the sink's + placement methods until the playout library lands). A name is free to + change only until moq-audio publishes with it. + +Facts found by the audit: + +- `Sink::end()` (`rs/moq-audio/src/playback/sink.rs:228`) declares silence + the publisher announced; it does not end the sink, which `finish(self)` + does (`:150`). `Sink::next()` (`:238`) starts the next utterance. +- The publisher calls the same marker `discontinuity` + (`rs/moq-audio/src/encode/producer.rs:668`), and the decoder reports it as + `Read::End`. +- One caller: `moq play`, four call sites in `rs/moq-cli/src/play/media.rs` + (`:889`, `:900`, `:912`, `:1029`) through the output trait at + `rs/moq-cli/src/play/output.rs:59`, `:62`. No binding, GStreamer element, + or OBS source calls them. + +For the PR: settle the names against the publisher's `discontinuity` and the +decoder's `Read::End`, so the three read as one idea, and rename the trait +methods in `rs/moq-cli/src/play/output.rs` to match. The sink's placement +methods (`output_latency`, `set_latency`, `due`) stay as they are: +[the playout library](/quest/m3/audio-playout-library.md) decides their +future after the cut (2026-11-14). + +Recommended in the same PR, not decided by the maintainer: +`encode::Producer::reanchor()` (`rs/moq-audio/src/encode/producer.rs:366`) +and `discontinuity()` (`:668`) are a lazy and an immediate marker for one +idea, and moq-ffi exposes only `reanchor`. Keep one public method, or say in +the docs why a caller needs both. + +Public API: moq-audio breaks (two method names). Wire: none. + +## Related + +- [Native audio playout is a library](/quest/m3/audio-playout-library.md) - builds on the sink after the cut diff --git a/quest/m2/auth-attach-token.md b/quest/m2/auth-attach-token.md new file mode 100644 index 00000000000..bfc316983e6 --- /dev/null +++ b/quest/m2/auth-attach-token.md @@ -0,0 +1,68 @@ +# [S] An attached token arrives as a token, not in the query + +## Goal + +When a client attaches a credential in band, the relay's `attach` request +to the auth server carries it in `Request.token` and leaves `query` exactly +as the client dialed it. The relay no longer knows the name `jwt`, and an +in-band token need not be UTF-8. `moq auth serve` and the docs read the +attached credential from `token`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ the +in-band token rides `Request.token` and the query stays as dialed (rejected: +keeping the rewrite and documenting it; a third field for the attached +credential). The contract says nothing is parsed on the relay's behalf, and +the rewrite is the one place the relay breaks that. + +Facts found by the audit: + +- The contract: "Nothing is parsed on the relay's behalf" and `query` is + "The raw query string" (`rs/moq-auth/src/request.rs:13,60`). +- For an in-band token the relay clones the connection's request, replaces + or appends a `jwt=` pair in `query`, and clears `token` + (`rs/moq-relay/src/auth/refresh.rs:259-265`, `with_jwt` at `:497-523`). + So an `attach` request carries a query the client never dialed, and a + server whose credential is not called `jwt` reads its own parameter at + `connect` and `jwt` at `attach`. +- The lite draft's token is opaque bytes, but the relay refuses one that is + not UTF-8 (`refresh.rs:259-262`), only because it must fit a query string. + A binary token works in SETUP (`token.value` is base64url) and fails in + band. +- `jwt` is also fixed in `presents_token` + (`rs/moq-relay/src/auth.rs:878-885`) and in the clients + (`rs/moq-net/src/auth/tokens.rs:456-532`, + `js/net/src/connection/tokens.ts:25-50`). +- `token`'s docs still say "a moq-transport client" + (`request.rs:63`, `js/auth/src/contract.ts:123`), though lite-07's Token + Setup Parameter lands there with `kind` 0. + +For the PR: + +- Relay: on `attach`, set `token` to `{kind: 0, value}` and leave `query` + alone. Delete `with_jwt` and the UTF-8 refusal. `presents_token` is the + relay's only other reader of `jwt`; replace it with a fact the request + already has, or move the question to the server, so the relay holds no + parameter name. +- `moq auth serve` verifies `token` when `event` is `attach`. Today it + counts a query `jwt` and a SETUP token once when equal and refuses when + they differ (`rs/moq-auth/src/serve.rs:195-197`); on `attach` the dialed + query still holds the first credential, so that rule must not fire there. +- The clients keep `?jwt=` only as the fallback for versions before + lite-07. Don't change them here. +- Both downstream auth servers read `attach` requests. This is a contract + break for them: record it in the Impact section, and check moq.pro's and + Kixel's handlers before merging. +- Update `request.rs`, `contract.ts`, and `doc/bin/relay/auth.md` (the + `token` field's description and the `attach` event). +- Tests: an attached binary token reaches the server unchanged; an `attach` + request's `query` equals the dialed one; `moq auth serve` renews a session + whose dialed query holds an expired `jwt`. + +Public API: none in Rust or JS beyond doc comments. HTTP contract: breaking +for `attach` (the credential moves from `query` to `token`). Wire: none. + +## Related + +- [A relay refuses a grant it does not fully understand](/quest/m2/auth-grants.md) - the other change to the same request and its docs diff --git a/quest/m2/auth-claims.md b/quest/m2/auth-claims.md new file mode 100644 index 00000000000..b14f70f06b6 --- /dev/null +++ b/quest/m2/auth-claims.md @@ -0,0 +1,96 @@ +# [M] Tokens are written as documented, with a typed jti + +## Goal + +A token minted by `moq-auth` or `@moq/auth` carries its grants as `publish` +and `subscribe`, the claims `doc/bin/relay/auth.md` documents, and never as +the 2024 `put` and `get` prefixes; both libraries still read `put` and `get` +from old tokens. `jti` is a typed, bounded string that a signer can set and +a verifier returns. `Algorithm` is an open enum. Claims and key sets are +read through the same names in Rust and JS. `KeyOperation` names only what +the libraries do. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ New tokens are written with `publish` and `subscribe` only, and old + `put` and `get` are still read (rejected: writing both forever and + documenting `put` and `get` as part of the format). The support rule is + the newest and previous release, and `release` already reads the pattern + claims. +- ✅ `jti` is a typed, bounded string that both libraries can mint and + return (rejected: reading any JSON value and dropping it). Tightening it + after the cut would refuse tokens accepted today. +- ✅ Claim and key set accessors have the same names in Rust and JS + (rejected: leaving each language its own). +- ✅ `Algorithm` is `#[non_exhaustive]` (rejected: a break for the next + algorithm). +- ✅ `KeyOperation::{Encrypt, Decrypt}` and JS `"encrypt"` and `"decrypt"` + are removed, as part of the audit's rule that unused public API goes, + once Kixel and moq.pro are checked for a caller. + +Facts found by the audit: + +- `Grants::encode` writes a subtree-only grant as `put` and `get` + (`rs/moq-auth/src/wire.rs:224-250`; JS `encodeGrants`, + `js/auth/src/wire.ts:166`). So `moq auth sign --publish 'alice/**'` writes + `{"put":["alice"]}`, while the claims table documents only `root`, + `publish`, and `subscribe` (`doc/bin/relay/auth.md:232-236`). A verifier + written from the docs refuses the most common token this project mints. +- The pinned reason is moq-relay 0.14 with `moq-token` 0.7 + (`rs/moq-auth/tests/released_token.rs:3-9`). `release` ships moq-auth + 0.2.4, which reads `publish` and `subscribe`. +- `jti` parses as `Option` (`wire.rs:54`) and + `z.optional(z.unknown())` (`js/auth/src/claims.ts:82`), and is dropped. + `Claims` is `#[non_exhaustive]`, so the field is additive in Rust. Token + revocation, which moq.pro plans, needs an identifier. +- Names differ: Rust `Claims.{expires, issued, not_before}` + (`rs/moq-auth/src/claims.rs:139-146`) against JS `exp`, `iat`, `nbf` + (`claims.ts:69-73`), while JS `Grant` says `expires`; `Claims::authorize` + and `Scope::allows` (`claims.rs:225,53`) against free `authorize()` and + `scopeAllows()` (`claims.ts:160,203`); `KeySet::{to_public_set, find_key}` + (`rs/moq-auth/src/set.rs:93,104`) against JS `KeySet.{public, find}`. +- `Algorithm` has no `#[non_exhaustive]` (`rs/moq-auth/src/algorithm.rs:10`), + and its doc comment says "there's currently no point using public key + crypto" (`:6`) while the docs recommend ES256. +- `KeyOperation::{Decrypt, Encrypt}` (`rs/moq-auth/src/key.rs:21-24`) and + `OperationSchema`'s `"decrypt"` and `"encrypt"` (`js/auth/src/key.ts:25`) + load and do nothing: `grep -rn 'KeyOperation::\(Encrypt\|Decrypt\)' rs` + finds no use outside `key.rs`. + +For the PR: + +- Writing: delete the prefix branch of `Grants::encode` and its JS twin, and + the helpers only it used (`Pattern::as_prefix` if nothing else calls it). + Keep the readers and the mixed-encoding refusal. Rewrite + `tests/released_token.rs` to pin what is still promised: an old `put` and + `get` token verifies with the same scope, and a new token is the + documented shape. Tokens minted by 0.22 stop verifying on moq-relay 0.14 + and earlier; say so in the Impact section. +- `jti`: pick the bound in the PR (the same in Rust and JS), refuse a `jti` + that is not a string or is over it, and add both cases to the shared + corpus. `moq auth sign` and the JS CLI take an optional value; neither + invents one. `doc/bin/relay/auth.md:237` stops saying `jti` is ignored. + Revocation itself is not in scope. +- Names: recommended to spell claims as the grant already does (`expires`, + `issued`, `not_before` in Rust, `expires`, `issued`, `notBefore` in JS; + the wire stays `exp`, `iat`, `nbf`), make `authorize` and `allows` methods + or free functions in both, and use `KeySet::{public, find}` in both. This + touches the same JS claims transform that + [the nested role type](/quest/m2/auth-grants.md) rewrites, so it lands + after it. +- `KeyOperation`: a key file whose `key_ops` lists `encrypt` or `decrypt` is + refused after the removal, which is what strict key parsing already does + for an unknown operation. Record it for `MIGRATE.md`. Keep the variants if + the downstream check finds a key file that names them. +- Fix `Algorithm`'s doc comment while there. + +Public API: breaking in `moq-auth` and `@moq/auth` (accessor names, the +`KeyOperation` variants, `Algorithm` made non-exhaustive); `jti` is +additive. Token format: new tokens no longer verify on moq-relay 0.14 and +earlier; a `jti` that is not a bounded string is refused. Wire: none. + +## Required + +- [A relay refuses a grant it does not fully understand](/quest/m2/auth-grants.md) - the nested role type, which rewrites the claims transform these renames touch diff --git a/quest/m2/auth-grants.md b/quest/m2/auth-grants.md new file mode 100644 index 00000000000..bfee317adaf --- /dev/null +++ b/quest/m2/auth-grants.md @@ -0,0 +1,110 @@ +# [M] A relay refuses a grant it does not fully understand + +## Goal + +A grant is what the relay enforces, so the relay reads it as strictly as it +reads a token's claims: a grant with a field the relay does not know is +refused and the session is not admitted. Every request to the auth server +carries the relay's product and version, so a server can tell what the relay +reads before it answers. The Rust and JS grant types have the shape of the +wire: one role value holds a direction's patterns and its rate cap, so a +typed server cannot write a cap the relay ignores. A cluster link is one +`link` field instead of the `peer` and `upstream` booleans, and the request's +`Event` and `Role` are open enums. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ The relay refuses a grant with an unknown field, as it refuses unknown + claims (rejected: refusing only top-level `publish_rate` and + `subscribe_rate`; keeping the lenient reader). A field added later may + narrow a grant, and a reader that ignores it widens the session. +- ✅ The request carries the relay's product and version token, in the + `name/version` form `implementation` already carries for the client + (rejected: leaving a server to guess what a relay reads). It is the lever + a server needs once grants are strict: no token means a relay older than + 0.22, which ignores unknown fields. +- ✅ The Rust and JS grant types take the nested wire shape (rejected: + keeping `publish` beside `publish_rate`). AGENTS.md nests related fields + under their shared role, and the wire already does. +- ✅ `peer` plus `upstream` become one `link` enum (rejected: two booleans + with an invalid fourth state). +- ✅ `Event` and `Role` are `#[non_exhaustive]` (rejected: another break at + the next event). + +Facts found by the audit: + +- `wire::Claims` is `deny_unknown_fields` (`rs/moq-auth/src/wire.rs:24`). + `wire::Grant` is not: "A field it does not know is ignored, so an auth + server may answer more than this reader takes" (`wire.rs:337-338`), and + `GrantSchema` is a stripping `z.object` (`js/auth/src/contract.ts:180`). +- Two cases already exist. `upstream` narrows a peer + (`rs/moq-auth/src/grant.rs:60-63`), and a `release` relay ignores it and + treats the session as a full peer, while AGENTS.md has the newest and + previous releases run side by side. The decoded JS `Grant` has + `publish_rate` and `subscribe_rate`, which are not wire fields, so a + TypeScript server that returns the typed object gets an uncapped session + with no error; the package documents the trap ("a bare `publish_rate` + field is ignored by the relay", `contract.ts:176-178`). +- The flat shape repeats in `moq_auth::Claims` (`claims.rs:130,136`), + `moq_auth::Grant` (`grant.rs:25,31`), `serve::Rule`, and + `moq_relay::auth::Token` (`rs/moq-relay/src/auth.rs:444-446`), and is why + `js/auth/src/wire.ts` exports `decodeRoles`, `nestRates`, `encodeRoles`, + and `encodeGrants`, and `contract.ts` exports `encodeGrant`. +- `moq auth serve` already says `link = peer|upstream` + (`rs/moq-auth/src/serve.rs:58-66`); the grant says `peer: bool` and + `upstream: bool`, with "Requires `peer`" as prose (`grant.rs:58-63`) and a + `z.refine` in JS (`contract.ts:217-218`). +- `Event` and `Role` have no `#[non_exhaustive]` + (`rs/moq-auth/src/request.rs:158,233`); `Transport` beside them does + (`:180`). `Event` gained `Attach` in this window as a break. + +For the PR: + +- Claims and grants share the role encoding (`wire.rs:279`), so the nested + role type replaces the flat pair in `Claims`, `Grant`, `serve::Rule`, and + the relay's `auth::Token` together, in Rust and JS, and the five JS + helpers go. `moq_auth::Role` is taken by the SETUP direction + (`request.rs:233`), so pick the nested type's name in the PR, the same in + both languages. The wire does not change for roles. +- Not decided: the capped role's `path` key holds a list of patterns and + has never been published. The audit rated a rename low confidence, and + moq.pro's plans already say `publish.rate`. Recommended: keep `path`. +- `link` fails closed on a relay that predates it only once grants are + strict, so land both here. `peer` is live on `release`: keep reading and + writing it as a clearly marked temporary alias that the next version + migration deletes, and refuse a grant where the two disagree. +- A strict grant is a rollout hazard for a server that already sends extra + fields. Check `moq auth serve`, the relay tests, and moq.pro's answers + against the strict reader before merging, and say in `doc/bin/relay/auth.md` + that a server branches on the relay's token before sending a field newer + than 0.22. +- A grant the relay cannot read refuses the session and is logged as the + server's fault, not the client's. Recommended: final for that session + rather than an outage the client retries, since a retry gets the same + answer. +- Recommended: the token is a body field next to `node`, not only an HTTP + header, because the JSON body is the contract servers already parse. + Name it in the PR. +- JS reads an unknown `transport` as `Unknown` (`contract.ts:32-38`). Give + `event` the same treatment or say why a server must refuse one. +- Stale text to fix while in these files: `doc/bin/relay/auth.md:100` says + "There is no shared secret" while the same page documents + `--listen-secret`, and `rs/moq-relay/src/auth.rs:1009` still explains a + rule by "the LAN mesh credential", which left for Kixel. +- Tests: the shared Rust and JS corpus gains a grant with an unknown field + (refused), a grant with both `link` and a disagreeing `peer` (refused), + and a capped role round trip through the typed API in both languages. + Update `doc/bin/relay/auth.md` and `doc/lib/js/auth.md`. + +Public API: breaking in `moq-auth`, `@moq/auth`, and `moq_relay::auth` +(the role type, `link`, two enums made non-exhaustive, five JS helpers +removed). HTTP contract: a grant with an unknown field is refused, the +request gains the relay token, and `link` replaces `peer` and `upstream` +behind a temporary alias. Wire: none. + +## Related + +- [Tokens are written as documented](/quest/m2/auth-claims.md) - the token side of the same types +- [An attached token arrives as a token](/quest/m2/auth-attach-token.md) - the other change to the request the server reads diff --git a/quest/m2/browser-packages.md b/quest/m2/browser-packages.md new file mode 100644 index 00000000000..edfb4855289 --- /dev/null +++ b/quest/m2/browser-packages.md @@ -0,0 +1,96 @@ +# [M] Room, publish, and OBS names say what they hold + +## Goal + +Three browser packages lose their confusing names before the cut publishes +them: + +- `@moq/room`: `Room.Local` nests each device's state under the device: + `local.camera`, `local.microphone`, and `local.screen` each hold their + `enabled` switch, capture source, and what they publish, so no two fields + named after one device are different objects. +- `@moq/publish`: ``'s `capture="hold|release"` attribute has a + name that says what is held, and the feedback path is `echo-path` as an + attribute, `echoPath` as a control, and `echoPath` as the + `Publish.Broadcast` input. +- `@moq/obs`: a destination's `layers` is `renditions`, and the settings + type `configure` takes is `Config`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `Room.Local` nests by device (rejected: moving only the audio addition + beside its device; keep). AGENTS.md: "Nest related API ... under their + shared role." +- ✅ Rename `` and align `echo-path`, `echoPath`, and + `echo` (rejected: only the `echoPath` rename; keep). +- ✅ `@moq/obs` says `renditions` and `Config` (rejected: keep). `layers` + is OBS's word; the rest of the stack says renditions. + +Facts found by the audit, re-checked at `80ca9787e3`: + +- `js/room/src/local.ts:62-89`: `webcam` is the `Source.Camera` while + `camera` is its `Publish.Broadcast`; `share` is the `Source.Screen` while + `screen` is its broadcast; `microphone` is a `Source.Microphone` while + `audio.microphone` holds its `volume` and `root`; `audio.screen` is a + third object beside `screen`. `cameraEnabled`, `microphoneEnabled`, + `screenEnabled` (`:47-51`), `cameraCapture`, and `screenCapture` + (`:74-76`) sit flat beside them. The only caller outside the package is + `demo/web/src/meet.ts` (5 references). +- `capture` (`js/publish/src/element.ts:55`, `CaptureMode` at `:79`) is + "what a muted or invisible track does with its capture". `el.capture` is + that policy string while `el.video.capture` and `el.audio.capture` are + `Capture` objects, and HTML's own `capture` attribute on `` picks + a camera. The name was the implementing agent's pick in + [moq-dev/moq#7746](https://github.com/moq-dev/moq/pull/7746), not a + recorded decision. No page or doc sets it; only + `test/interop/clients/js/publish-ui.browser.ts` does. +- The publish attribute is `echo-path` and the control `echoPath` + (`element.ts:54`, `:175`), but the input under them is + `Broadcast.in.echo` (`js/publish/src/broadcast.ts:86`). The CLI flag is + `--echo-path`. `` takes the viewer's feedback name, one + path segment (`js/watch/src/element.ts:119`), which is a different + thing and keeps its name. +- `Destination.layers` (`js/obs/src/obs.ts:62`) is documented as "video + renditions to publish", and [layers](/quest/m3/layers/README.md) uses + the word for composed broadcasts. `configure(publish: Publish)` + (`:255`) names its settings type `Publish` (`:73`), the sibling + package's name. `@moq/obs` is unpublished. + +For the PR: + +- Room, recommended shape: `local.camera.{enabled, source, capture, + broadcast}`, `local.microphone.{enabled, source, volume, root}`, + `local.screen.{enabled, source, capture, broadcast, audio}`. The props + that seed the switches (`cameraEnabled` and its two siblings, `:22-26`) + nest the same way. Leave `TRACK.location` and `HangCatalog.location` + (`js/room/src/metadata.ts:36`, `:91`): the package doc calls them + app-defined extensions, and removing them is not part of this decision. +- Capture attribute, recommended name: `devices="hold|release"` (the + audit's pick). It also governs a screen share and a file, so if that + reads wrong, `idle="hold|release"` is the alternative; pick one and say + why in the PR. The type, the control, and the parse error follow the + attribute. It is new in this cycle, so it needs no tombstone attribute. +- Rename `BroadcastInput.echo` to `echoPath`; the catalog's `echo` section + keeps its name, since that is the wire. +- `MAX_LAYERS` and the range error in `obs.ts` follow `renditions`; the + OBS setting `WHIPSimulcastTotalLayers` keeps OBS's name. Update + [the dock's simulcast check](/quest/m3/obs-multitrack-check.md) if it + names the field. +- Update each package's `api/*.api.md`, README, and `MIGRATE.md` + (`js/obs` has none: it has never been published), plus + `doc/lib/js/publish.md`. + +Tests: the existing room, element, and obs suites pass under the new +names; `just dev` shows the meet demo publishing camera, microphone, and +screen. + +Public API: breaking for `@moq/room` (`Room.Local` and its props), +`@moq/publish` (one element attribute and control, one `Broadcast` input), +and the unpublished `@moq/obs`. Wire: none. + +## Related + +- [@moq/ui is a workspace package](/quest/m2/ui-private.md) - the packaging change to the same overlays +- [Unused media API](/quest/m2/unused-api/media.md) - the browser exports removed beside these renames diff --git a/quest/m2/catalog-at-timestamp.md b/quest/m2/catalog-at-timestamp.md index 3ac4c6ade02..48b8ef2e77d 100644 --- a/quest/m2/catalog-at-timestamp.md +++ b/quest/m2/catalog-at-timestamp.md @@ -24,6 +24,10 @@ value.value)`), and `js/hang` does likewise; both return it with the catalog. A consumer that reads an update ahead of its timestamp holds it until media reaches that time; one that reads it late applies it at once. +The clock itself is the catalog section +[`sync`](/quest/m2/hang04/sync.md) names (`media.clock` on main today), so +the draft's rule cites whichever name has landed. + A scale-less broadcast's catalog has no media time to wait for, so it applies on arrival, as today. diff --git a/quest/m2/cluster-routes/acceptance.md b/quest/m2/cluster-routes/acceptance.md index 003f627db02..899a661edc1 100644 --- a/quest/m2/cluster-routes/acceptance.md +++ b/quest/m2/cluster-routes/acceptance.md @@ -33,6 +33,12 @@ waits for [the switch](/quest/m2/multicast/switch.md), which rewrites these fixtures' assertions for the new rule and deletes the Required quests it makes moot. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): the +switch makes `origin::Config::update_hold` crate-private, since nothing +outside moq-net sets it, and puts whatever of the three mitigations survives +here under one named lite-06 marker. So retiring them below changes no +public API, and one that a lite-06 mesh keeps is already marked temporary. + What remains: - Retire the quarantine, the dedup, and the hold once the Required quests diff --git a/quest/m2/congestion-names.md b/quest/m2/congestion-names.md new file mode 100644 index 00000000000..24ef7e3ebfa --- /dev/null +++ b/quest/m2/congestion-names.md @@ -0,0 +1,86 @@ +# [M] Congestion control is chosen by algorithm name, from one enum + +## Goal + +A QUIC endpoint picks its congestion controller by the algorithm's name: +`bbr` (the default), `cubic`, or `unlimited`, in `quic.congestion_control`, +its flag and environment variable, the Rust API, and every binding. One enum +in moq-tokio says so, both runtimes build their controller from it, and no +application can install a controller of its own. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ One enum of algorithm names, no families (rejected: the family names + `loss`, `delay`, `none` kept; algorithm names beside goal names such as + `real-time`, which the maintainer raised and then dropped: "just do + algorithms no families"). A family name stops meaning one thing once two + delay-based algorithms exist, and the enum's own doc already promises "a + new algorithm joins as a variant named after it". +- ✅ Delete the moq-uring duplicate and `quic::Config::controller` (rejected: + keeping the application hook). The hook publishes + `moq_congestion::Controller` as a plugin interface while that trait is + still moving. + +Facts found by the audit: + +- `moq_tokio::quic::CongestionControl { Loss, Delay, None }` + (`rs/moq-tokio/src/quic.rs:97`) and `moq_uring::quic::Congestion { Loss, + Delay, None }` (`rs/moq-uring/src/quic/mod.rs:50`) are the same enum, each + with its own mapping to a factory (`rs/moq-tokio/src/quic/backend.rs:29`, + `rs/moq-uring/src/quic/mod.rs:62`). moq-relay maps one onto the other + variant by variant (`rs/moq-relay/src/uring.rs:507-514`), so a new + algorithm is three edits. +- `quic::Controller` and `quic::Config::controller` + (`rs/moq-tokio/src/quic.rs:80`, `:248`, `:668`) are set only by moq-tokio's + own unit tests (`rs/moq-tokio/src/quic/backend.rs:1377`, `:1411`): + `grep -rn 'controller:' rs` outside moq-quic and moq-congestion finds + nothing else, and no binding, doc, or downstream quest names it. + `Controller` gained `on_loss` before `on_ack` on 2026-11-15 + ([moq-dev/moq#8807](https://github.com/moq-dev/moq/pull/8807)). +- The field is `Option`, so `None` is "the default, BBR" + and `Some(None)` is "no congestion control". moq-congestion calls the + second `Unlimited`. +- GCC and SCReAM sit behind moq-congestion's `lab` feature for the + [realtime bake-off](/quest/m4/quic-realtime.md). Both are delay-based, so + the family names cannot name the bake-off's winner. +- moq-ffi already changed the selector's shape in every binding in + [moq-dev/moq#8850](https://github.com/moq-dev/moq/pull/8850) + (`MoqCongestionControl`, `rs/moq-ffi/src/session.rs:148`), so the bindings + take new names at no extra break. +- `loss`, `delay`, and `none` are published: `release` has both enums. + +For the PR: + +- Name the variants `Bbr`, `Cubic`, `Unlimited`, spelled `bbr`, `cubic`, + `unlimited`. Keep the enum `#[non_exhaustive]`. The default stays BBR v3, + and "which BBR" lives in the variant's doc, not its name. +- moq-uring takes the moq-tokio enum or, since its `transport::Config` + already takes a factory, no enum at all; the relay's variant-by-variant + match and its `bail!` for an unknown family go. +- Recommended, the maintainer did not pick: `loss`, `delay`, and `none` are + refused at startup with a message naming `cubic`, `bbr`, and `unlimited`, + as other removed settings are (`moq_tokio::cli::Deprecated`), rather than + accepted as aliases. A silent alias keeps the family names alive in every + deployed config. +- Rename the moq-ffi constructors and every wrapper to match (Swift, Kotlin, + Dart, Python, Go, C, C++), and their `MIGRATE.md` notes. `@moq/net` has no + QUIC stack to configure: it passes the browser's own `congestionControl` + hint (`js/net/src/connection/connect.ts:836`), which is unchanged. +- Update `doc/bin/relay/config.md` (`congestion_control = "delay"` at line + 119, and the `none` paragraph), the CLI docs, and `rs/moq-tokio/MIGRATE.md`. +- Tests: each spelling parses from TOML, flag, and environment; each old + spelling refuses naming its replacement; an io_uring relay and a tokio relay + given `cubic` both run CUBIC. + +Public API: breaking for `moq_tokio::quic` (`CongestionControl` variants, +`Config::controller` and `Controller` removed), `moq_uring::quic` +(`Congestion` removed), and the moq-ffi selector in every binding. Config +and CLI: `quic.congestion_control` takes `bbr`, `cubic`, `unlimited`. Wire: +none. + +## Related + +- [Realtime uplink congestion control](/quest/m4/quic-realtime.md) - its winner joins this enum under its own name +- [Open-set selectors in the bindings](/quest/m2/ffi-open-selectors.md) - the rule the binding selector already follows diff --git a/quest/m2/dart-experimental.md b/quest/m2/dart-experimental.md new file mode 100644 index 00000000000..f6cfcc92eb7 --- /dev/null +++ b/quest/m2/dart-experimental.md @@ -0,0 +1,73 @@ +# [S] Dart ships as experimental, with its bindings generated at build time + +## Goal + +The Dart packages say what they are: experimental. `dart/moq/README.md`, +`doc/lib/dart`, and the language table in `doc/lib/index.md` label Dart +experimental, and the `moq` wrapper on pub.dev keeps its own 0.x version +instead of joining the shared 0.22 minor, so the 0.22 announcement does not +promise Dart what it promises Swift, Kotlin, Python, Go, and C++. + +`dart/moq_ffi/lib/src/moq.dart` and `uniffi_runtime.dart` are no longer in +git. They are generated when the package is checked, tested, and published, +and the published `moq_ffi` archive still contains them. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ Dart +is experimental, off the shared minor, and its generated layer is built +instead of checked in (rejected: shipping it beside the other languages as +planned; publishing only `moq_ffi` and dropping the wrapper). The other +languages each have evidence Dart lacks, and a 0.22 version would claim it. + +Facts found by the audit: + +- No user: neither moq.pro nor Kixel has a quest that names Dart. C++ has + `cpp/obs`; Dart has nothing in the tree. +- Never loaded on its main platform: + [Dart on iOS](/quest/m4/dart-ios.md) says nobody has loaded it. There is + no example application (`dart/README.md` says so), and no Dart client in + `test/interop/clients` (c, cpp, go, js, js-native, python, rust). A tag + has never published the wrapper unattended + ([Dart publication](/quest/m3/release/dart-publish.md)). +- It is kept in step mechanically, so it is maintained, not proven. +- `dart/moq_ffi/lib/src/moq.dart` is 25,932 generated lines in git, and 163 + first-parent commits since the last release rewrote it + (`git log --oneline d0b086e71b..HEAD -- dart/moq_ffi/lib/src/moq.dart`). + No other language commits its generated layer. `sh/dart/check.sh:88-93` + diffs the checked-in file against a fresh generation and fails when it is + stale, which is the only reason it is committed. +- The wrapper is already versioned on its own (0.1.1 on pub.dev), but + `sh/version.py` lists it in `WRAPPERS` (`:52`), so the cut's + `just version` would set it to the shared minor. + +For the PR: + +- Add `"dart": ["moq"]` to `version.json`'s exemptions. `moq_ffi` keeps + tracking `rs/moq-ffi`'s version, since it is that crate's artifact and + its native asset download is keyed by it. Say in `RELEASE.md` why Dart is + exempt and what ends the exemption: an interop client or the iOS proof. +- Untrack both generated files and ignore them. `just dart check`, + `dart test`, and the Native Assets hook generate them first + (`sh/dart/generate.sh` already writes them); drop the staleness diff. + `release-dart-ffi.yml` generates before `dart pub publish`, and the PR + shows with `dart pub publish --dry-run` that the archive holds both + files. A consumer installing from pub.dev must not need the generator. +- Label: one sentence at the top of `dart/moq/README.md`, + `dart/moq_ffi/README.md`, and `doc/lib/dart/index.md` saying the API may + change in any release and what is unproven, and "experimental" in the + Dart row of `doc/lib/index.md`. +- Dart still follows AGENTS.md's Cross-Package Sync: a binding feature + reaches it with the other languages. Experimental describes the promise, + not the upkeep. +- Update [Dart publication](/quest/m3/release/dart-publish.md)'s floor + check if the exemption changes what `just version` writes into + `dart/moq/pubspec.yaml`. + +Public API: none changes; the Dart wrapper's version stays below the shared +minor. Wire: none. + +## Related + +- [Dart on iOS](/quest/m4/dart-ios.md) - the proof that would end the experimental label +- [A Dart tag publishes unattended](/quest/m3/release/dart-publish.md) - the publish this changes the inputs of diff --git a/quest/m2/delay-hole-wait.md b/quest/m2/delay-hole-wait.md new file mode 100644 index 00000000000..d577b32691c --- /dev/null +++ b/quest/m2/delay-hole-wait.md @@ -0,0 +1,73 @@ +# [M] A hole is waited for by the subscription's delay, with no third knob + +## Goal + +The container consumer has no separate hole wait: `set_wait` in +`moq_mux::container::Consumer` and `ConsumerProps.wait` in `@moq/hang` are +gone. A missing group is waited for the subscription's stated `Delay::min`, +or `Delay::max` when no minimum is stated, in Rust and JS alike. A native +audio player whose playout delay is a live estimate still skips a hole once +that delay has passed, as it does today. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Fold the hole wait into `Delay` (rejected: keep `set_wait` as a third + delay knob and stop calling it a duplicate; drop it with no replacement + rule). `Delay { min, max }` already says how far behind live the reader + plays and how late a group stays useful; a third duration set through a + setter is one more thing each player has to keep in step. + +Facts found by the audit: + +- `set_wait` (`rs/moq-mux/src/container/consumer.rs:1381`) caps the wait at + the max delay (`:840`). Its one production caller is native audio, which + refreshes it before every poll with `self.delay()` + (`rs/moq-audio/src/decode/consumer.rs:598`), the live jitter estimate when + `Options::estimate` is on (`:339`). So the [API review](/quest/m3/release/api-review.md)'s + note that native audio "sets it to the `min` it already passes" is not + always true, and a plain delete regresses + [moq-dev/moq#8531](https://github.com/moq-dev/moq/pull/8531). +- JS mirrors the knob as `ConsumerProps.wait` + (`js/hang/src/container/consumer.ts:43`), passed by two callers, both as + `sync.out.maxDelay` (`js/watch/src/audio/decoder.ts:921`, + `js/watch/src/audio/replay.ts:260`). +- Three days after #8531, + [moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) gave the JS + consumer the player's clock (`playhead`): a hole ends when the clock + reaches the group past it. The clock already trails live by the estimate, + so it carries the moving value the wait was added for. + +For the PR, settle the home of native audio's live estimate first. Two ways: + +1. Recommended: the playhead is the home. Once + [native players skip a hole their clock passed](/quest/m2/audio-playout/rust-playhead-holes.md), + the clock ends a hole at the estimate, and the static rule (`min`, else + `max`) is only the fallback for a reader with no clock. Prove it by + deleting the `set_wait` call and running #8531's regression tests + (`rs/moq-mux/src/container/consumer.rs:2161`, `:2308`, `:2369` and + moq-audio's reorder tests) with the playhead in place. +2. moq-audio writes its estimate into the subscription's `Delay::min` as it + moves. `min` is Subscriber Min Age on the lite-07 wire, so each change is + a SUBSCRIBE_UPDATE, and since [a cold join reaches back by it](/quest/m2/min-age-join.md) + it would also move where a join starts. Take this only with a coarse step + and a measured update rate, and say why the playhead did not do. + +Then delete the setter and the prop, apply the one rule in both languages, +and update the consumer docs that name the wait +(`rs/moq-mux/src/container/consumer.rs:74`, the `ConsumerProps` docs). If +neither way keeps #8531's behaviour, report it on the PR before keeping the +knob: the maintainer rejected that end state. + +Public API: `moq-mux` loses `container::Consumer::set_wait`; `@moq/hang` +loses `ConsumerProps.wait`. Wire: none. + +## Required + +- [Native players stop waiting on a hole their clock passed](/quest/m2/audio-playout/rust-playhead-holes.md) - gives the Rust consumer the clock that replaces the live wait + +## Related + +- [A cold join reaches back by Min Age](/quest/m2/min-age-join.md) - gives `Delay::min` a reader on the wire, which rules out using it as a fast-moving estimate +- [Native audio playout is a library](/quest/m3/audio-playout-library.md) - moves the placement this wait feeds into moq-audio diff --git a/quest/m2/drafts-retire.md b/quest/m2/drafts-retire.md new file mode 100644 index 00000000000..97fae7b3df3 --- /dev/null +++ b/quest/m2/drafts-retire.md @@ -0,0 +1,69 @@ +# [S] The drafts directory holds only drafts the code implements + +## Goal + +`drafts/` contains no document that describes nothing in the repository. +`draft-lcurley-moq-epoch.md` and `draft-lcurley-moq-use-cases.md` are +deleted, `draft-lcurley-moq-probe.md` is deleted or reduced to a pointer at +the lite draft's Probe section, and no draft, doc page, or quest links to +them. `drafts/README.md`'s claim that each draft is "implemented by the Rust +and JS code elsewhere in this repo" is then true. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Delete the dead drafts (rejected: keep them in a `drafts/proposals/` + directory that the doc site does not render as specifications). An + announcement points readers at `/draft/`, and each of these says it was + generated from an implementation that does not exist. + +Facts found by the audit (datatracker state queried 2026-11-15): + +- **epoch** (204 lines, never published): implemented 2026-10-19 and + removed 2026-11-01 in + [moq-dev/moq#7239](https://github.com/moq-dev/moq/pull/7239) because "no + third party implements it". Keeping the draft "as an unimplemented + proposal" was the implementing agent's choice against a reviewer, not a + recorded decision. Its EPOCH is what lite-07 calls an Instance, so the + name now misleads. `drafts/draft-lcurley-moq-cluster.md` leans on it in + five places (`grep -n -i epoch`), and `doc/concept/standard.md` links it. +- **use-cases** (443 lines, -01 published): no commit in the window. It + names "moq-karp", a `timeline` track, and aligning tracks by Group + Sequence, all gone. +- **probe** (220 lines, -00 published): no code sends or reads its stream + type (`grep -rni 0x950BE rs js` is empty), and + `js/net/src/ietf/connection.ts` says "moq-transport has no PROBE". + lite-07's own PROBE uses bits per second and RTT, not this draft's + kilobits and elapsed time. `doc/concept/standard.md` lists it among the + drafts that "extend the IETF wire" and then describes lite behaviour. + `quest/m5/probe-padding.md` tells its PR to update the draft. + +For the PR: + +- Recommended for probe: delete it. A published -00 stays on the + datatracker and expires on its own; a body that only points elsewhere is + not a draft. Keep the pointer form only if something outside the + repository links `/draft/moq-probe`. +- Delete the files, then follow `grep -rn 'moq-epoch\|moq-probe\|use-cases' drafts doc quest`: + the five epoch passages in the cluster draft, the two links in + `doc/concept/standard.md` (rewrite that paragraph to say what Rust + sessions do on lite, and that moq-transport sessions mint an instance per + announcement, with no proposal behind it), and the probe sentence in + `quest/m5/probe-padding.md`. The doc site's draft list is generated from + `drafts/` (`doc/.vitepress/drafts.ts`), so it follows. +- The cluster draft is not this quest's: the + [route switch](/quest/m2/multicast/switch.md) retires it. If that lands + first, the five epoch passages are already gone. +- While in `drafts/`: the `ietf` and `hidden` drafts each carry a + "Since ...-00 (in progress)" changelog heading for a -00 that was never + published. `drafts/AGENTS.md` says "never add a section for an unpublished + next version"; remove both headings if that rule covers a first version. + +Run `just drafts check`. + +Public API: none. Wire: none. Docs: three `/draft/` pages disappear. + +## Related + +- [The route switch](/quest/m2/multicast/switch.md) - retires the moq-cluster draft that cites epoch diff --git a/quest/m2/e2ee-crate.md b/quest/m2/e2ee-crate.md new file mode 100644 index 00000000000..0f089f89d1c --- /dev/null +++ b/quest/m2/e2ee-crate.md @@ -0,0 +1,110 @@ +# [M] End-to-end encryption is its own unpublished crate again + +## Goal + +The end-to-end encryption code lives in `rs/moq-e2ee` (crate `moq-e2ee`, +`publish = false`), not in `moq-crypto`, and the 0.22 cut publishes none of +it. `moq-crypto` is the crypto the transports share: the rind provider and +the CPU check, with no `e2ee` feature, and it no longer pulls `moq-net`, +`uuid`, or `base64` into any build for encryption. The docs stop saying a +hang broadcast can be encrypted, since no publisher, player, CLI, or binding +can make or play one. Nothing left in the tree mentions the deleted signing +module. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ E2EE moves back to its own `moq-e2ee` crate, because it is "not ready + yet" (rejected: shipping it in moq-crypto 0.22 as a default feature under + a new profile string, the pick made earlier the same day; leaving it and + marking the module outside semver). This reverses the E2EE half of the + 2026-11-02 merge + ([moq-dev/moq#7702](https://github.com/moq-dev/moq/pull/7702)), which + joined two wrappers that shared a timestamp check: signing left in + [moq-dev/moq#8855](https://github.com/moq-dev/moq/pull/8855), so the + reason is gone. +- ✅ `moq-e2ee` is unpublished at the cut and until + [the finished format](/quest/m3/e2ee-format.md) lands (rejected: + publishing it as it stands, which would put an interim format out under + `moq-e2ee-01` and force a third label on the finished one). +- ✅ The docs stop advertising encrypted hang. +- The format and API changes the audit decided are not lost: they are + [the finished format](/quest/m3/e2ee-format.md)'s, after the cut. + +Facts found by the audit: + +- Nothing uses it: `grep -rl 'moq_crypto::e2ee' rs --include=*.rs` finds no + file outside `rs/moq-crypto`, and no JS package imports `@moq/crypto`, + which is `private` at 0.0.0 (`js/crypto/package.json:4,12`). No catalog + field, CLI flag, or binding names it. +- It is a default feature (`rs/moq-crypto/Cargo.toml:21`) of the crate all + ten transport and gateway crates depend on for `cpu` or `provider`, so + each planned break to the wrappers + ([moq-e2ee implements the moq-net traits](/quest/m5/net-wrap/e2ee.md)) + would be a breaking release of that crate. +- crates.io has `moq-e2ee` 0.0.25 (2026-11-11, from `release`), profile + `moq-e2ee-00` with the old derivation: one-way physical names from + `HKDF-Expand(prk, "moq-e2ee-00 name", 16)`. `main` uses the same label + (`rs/moq-crypto/src/e2ee/limits.rs:2`) for AES-GCM reversible names and + keys bound to the semantic name, so the two agree on a profile and a path + and then find no track. `moq-crypto` has never been published (checked + 2026-11-12). +- The docs promise it: `doc/index.md:56` ("end-to-end encrypt your + content"), `doc/concept/hang.md:13-17` and its Encryption section + (`:227-241`), `doc/lib/rs/index.md:42`, and `doc/setup/repository.md:34`. +- Signing residue: the `signature` keyword (`rs/moq-crypto/Cargo.toml:12`), + `rs/moq-crypto/MIGRATE.md:23-38` on `moq_crypto::sign` and `moq-sign`, + which never shipped, and + [the feature list](/quest/m3/release/feature-flags.md)'s `sign` feature. + +For the PR: + +- Move `rs/moq-crypto/src/e2ee`, its tests, `benches/protect.rs`, and the + E2EE half of the README to `rs/moq-e2ee`, at a version above crates.io's + 0.0.25 so the later publish needs no jump. It depends on `moq-crypto` for + `cpu` only, until + [moq-dev/moq#8432](https://github.com/moq-dev/moq/pull/8432) removes that + check. Update `rs/justfile` (`crypto-key` and the coroutine and doc + lines that name `e2ee`), `.github/workflows/release-gate.yml`, the + Nightly bench, `nix/Cargo.nix`, and `sh/api-diff` if it lists the crate. +- `moq-crypto` keeps `cpu`, `provider`, and `endpoint`; its description and + keywords say so. `endpoint` and the mandatory `data-encoding` dependency + are [the route switch](/quest/m2/multicast/switch.md)'s to delete with the + Route Key, not this quest's. +- Recommended, not decided: `js/crypto` becomes `js/e2ee` (`@moq/e2ee`, + still `private`), so the two halves share a name as AGENTS.md asks. It is + free while the package is unpublished. +- Recommended, not decided: rename the profile on `main` to + `moq-e2ee-01-wip` here (constant, salt, labels, `drafts/moq-e2ee-00.json` + and `.ts`, the draft's Profile Version section), so nothing on `main` + calls two derivations `moq-e2ee-00`, and an unpublished `-wip` label may + keep changing. [The finished format](/quest/m3/e2ee-format.md) drops the + suffix. The draft's changelog already heads the new derivation + `draft-lcurley-moq-e2ee-01`. +- Docs: `doc/index.md` and `doc/concept/hang.md` describe only what ships, + so the Encryption section and the opening paragraph's sentence go, and + `doc/lib/rs/index.md` and `doc/setup/repository.md` list `moq-e2ee` as + unpublished and experimental or drop the row. The draft's own page stays: a + draft is not a shipped feature. +- Residue: drop the `signature` keyword, and delete the `MIGRATE.md` + entries for names that never shipped (`moq_crypto::sign`, `moq-sign`, the + `sign` and `e2ee` features); + [the migrate audit](/quest/m3/release/migrate-audit.md) owns the rest of + that file. `rs/moq-crypto/MIGRATE.md` then has nothing to + say about `moq-e2ee` users, who have nowhere to move yet. +- `release` still holds `rs/moq-e2ee` at 0.0.25 and publishes it. After the + cut it holds this crate with `publish = false`; check release-plz proposes + nothing for it. +- `just check` and `just test interop --all` do not change behavior; the + proof is that the workspace builds with every feature set `rs/justfile` + checks and that `cargo tree -p moq-quic` shows no `uuid`. + +Public API: `moq-crypto` loses its `e2ee` module and feature before its +first publish; `moq-e2ee` is unpublished, so nothing published breaks. +Wire: none (the profile label, if renamed, is unpublished). + +## Related + +- [The finished E2EE format](/quest/m3/e2ee-format.md) - the format and API changes, and the publish, that this defers +- [Retired package names](/quest/m3/release/retired-names.md) - `moq-e2ee` is no longer a retired name diff --git a/quest/m2/ffi-open-selectors.md b/quest/m2/ffi-open-selectors.md new file mode 100644 index 00000000000..c3cd0497c92 --- /dev/null +++ b/quest/m2/ffi-open-selectors.md @@ -0,0 +1,95 @@ +# [M] Binding selectors can grow, and a null max age means unlimited + +## Goal + +A value in the bindings that names an open set, one Rust can add a member +to, never forces a breaking binding release when it grows. +`rs/moq-ffi/AGENTS.md` states the rule: a selector a caller passes is an +object with constructors, and an enum a caller reads has a catch-all. `MoqVideoCodec` and +`MoqCompression` are objects, as `MoqAudioCodec` and `MoqCongestionControl` +already are; `MoqTransport` and `MoqVideoSurface` have an unknown variant in +moq-ffi, so the wrappers' hand-written fences are gone. + +In `MoqTrackInfo`, a null `max_age` means no limit, as a null `MoqDelay.max` +does and as Rust, JS, and Python already read it, and `max_age_unlimited` is +gone. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Open the selectors: one rule in `rs/moq-ffi/AGENTS.md`, applied to + `MoqVideoCodec`, `MoqTransport`, `MoqVideoSurface`, and `MoqCompression` + (rejected: leaving them and treating every new variant as a break; also + collapsing `MoqError`, which is worth it only if the bindings were not + about to change exporter). +- ✅ `TrackInfo.max_age` null means unlimited and `max_age_unlimited` is + deleted (rejected: keeping both fields; leaving it for the exporter). +- Not selected, so unchanged: the `Moq` facade Kotlin and Dart start from, + where the other languages start from `Client`. +- The maintainer accepted that the bindings break again when + [the exporter switch](/quest/m3/ffi-exporter.md) lands, so this quest + makes only the reshapes that outlive the generator: a rule and these six + types. + +Facts found by the audit: + +- Swift, Kotlin, and Dart switch over enums exhaustively and the wrappers + alias the generated enums, so a new variant breaks source. Two selectors + were made objects for this reason: `MoqAudioCodec` + (`rs/moq-ffi/src/audio.rs:58-62`, "so adding a codec later does not break + callers switching over a closed enum") and `MoqCongestionControl` + (`session.rs:148`). +- Their siblings are closed while the Rust they mirror is open: + `MoqVideoCodec` (`video.rs:40`, two variants; AV1 or VP9 is a break); + `MoqTransport` (`server.rs:429`), where an unmapped transport makes + `transport()` fail with `Unsupported` (`:452`); `MoqVideoSurface` + (`video.rs:1126`), one variant with Android's `HardwareBuffer` planned, + which each wrapper fences by hand (`swift/Sources/Moq/Video.swift:62-75`, + and Swift's fence is itself a closed enum); `MoqCompression` + (`producer.rs:69`), one variant. +- `MoqTrackInfo.max_age` is "null for the default, zero", with + `max_age_unlimited` overriding it (`producer.rs:42-51`, conversion at + `:88-92`), while reading inverts it: `info()` reports unlimited as + `max_age: None` plus the flag (`:120`). `MoqDelay.max` is null for no + limit. Swift, Kotlin, Dart, C++, and generated C see the raw record, so + `TrackInfo(maxAge: nil)` serves only the live edge. + +For the PR: + +- Write the rule first, in `rs/moq-ffi/AGENTS.md`: a selector naming an open + set is an object; an enum a caller reads carries a catch-all in moq-ffi, + not in each wrapper; a null duration means no limit. Recommended third + clause: a new variant of a closed enum waits for an API cut, since + `sh/api-diff/run.sh` counts a line added inside an existing declaration as + a break (`:54-79`). +- `MoqVideoCodec` and `MoqCompression` become objects with one constructor + per member and a name accessor, following `MoqAudioCodec`. `MoqCompression` + is also read back from `info()`, so it needs equality or a name a caller + can compare. +- `MoqTransport` and `MoqVideoSurface` gain the catch-all; `transport()` + stops failing on a transport it cannot name; delete each wrapper's fence + (Swift, Dart, Python, Kotlin, Go) and take the generated one. +- `max_age` becomes a required field with no default, null for unlimited, + as `MoqSubscription.delay` is required. Python, Go, and Dart already + default an omitted value in the wrapper; check each still defaults to + zero, and that Swift and Kotlin callers must now state it. Remove the + flag from moq-ffi, the hand-written C API (`rs/moq-c/src/api.rs`), every + wrapper, and their tests. +- Follow the sync table from `rs/moq-ffi` outward: every wrapper, `cpp/moq`, + `cpp/obs` if it names a codec, each `doc/lib` page, and the Impact section + for each package's `MIGRATE.md`. Run `just test interop --all`. +- Fix `swift/README.md:67` while in the Swift docs: it says each `MoqError` + case carries `message: String`, which `swift/Sources/Moq/Errors.swift` + does not have. +- [Track info docs](/quest/m4/track-info-docs.md) describes the record after + this lands. + +Public API: breaking in every binding (two enums become objects, two gain a +variant, `max_age` changes meaning and `max_age_unlimited` is removed). +Wire: none. + +## Related + +- [Switch moq's bindings to rust2's exporter](/quest/m3/ffi-exporter.md) - the second binding break, which must keep these shapes +- [Bindings address groups by start](/quest/m2/time-addressing/bindings.md) - the other binding rename before the cut diff --git a/quest/m2/finish-sweep.md b/quest/m2/finish-sweep.md new file mode 100644 index 00000000000..e5befe53efd --- /dev/null +++ b/quest/m2/finish-sweep.md @@ -0,0 +1,77 @@ +# [M] Finishing an importer or the video producer returns a Finished handle + +## Goal + +Every media producer finishes the same way. The ten codec importers in +`rs/moq-mux/src/codec`, the two import front doors that wrap them +(`moq_mux::import::Track` and `TrackStream` in +`rs/moq-mux/src/import/track.rs`), and `moq_video::encode::Producer` take +`finish(self)` and return a `Finished` handle that keeps the track and its +catalog rendition published and can still `abort`. After `finish`, nothing +can publish another frame, because nothing holds the producer. The bindings +and every caller in the tree follow. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): this +completes the 2026-11-07 decision that +[moq-dev/moq#8395](https://github.com/moq-dev/moq/pull/8395) carried out +("finishing a media producer returns a Finished handle", settled in m2 +before the cut). The audit found the sweep stopped short; no new decision +was needed, and none was recorded for leaving these out. + +Facts found by the audit: + +- #8395 converted the moq-mux container producers + (`container::Producer::finish(self) -> Result>`), + moq-json, and + `moq_audio::encode::Producer::finish(self) -> Result`. + The container importers (`fmp4`, `flv`, `mkv`, `ts`) consume and return + a `Finished` too. +- The video twin still borrows: + `rs/moq-video/src/encode/producer.rs`, + `pub fn finish(&mut self) -> Result<(), Error>`, documented as "borrows + rather than consumes, so a later abort can still run after a successful + finish". That is the case the `Finished` handle exists for, and after + `finish`, `publish` is still callable. +- Ten codec importers still take `finish(&mut self) -> Result<()>`: + `aac`, `av1`, `flac`, `h264`, `h265`, `legacy`, `mp3`, `opus`, `vp8`, and + `vp9` under `rs/moq-mux/src/codec` (re-run + `grep -rn 'pub fn finish(&mut self)' rs/moq-mux/src/codec rs/moq-mux/src/import`). + Each ends in `self.track.end_with(None)` on a `container::Producer` that + already has the consuming `finish`. +- `rs/AGENTS.md`: "Terminal operations consume `self`". + +For the PR: + +- Importers first: each `finish(self)` returns the `Finished` of the + container producer it wraps (or a small `Finished` of its own exposing + `name`, `track`, and `abort`, if the wrapped type should stay private). + One shape for all ten; do not invent a per-codec handle. +- `import::Track` and `TrackStream` then return a `Finished` over + whichever importer they hold. Their comment "the import stays, keeping + the finished track and its rendition published" becomes the handle's + job. +- `moq_video::encode::Producer::finish(self) -> Result`, + with `Finished::abort`, matching the audio producer line for line. This + type is being renamed by + [the frame-taking video producer](/quest/m2/video-producer.md); whichever + lands second merges main and keeps both changes. +- Callers hold these behind locks in moq-ffi and moq-c + (`rs/moq-ffi/src/{video,media,audio}.rs`, `rs/moq-c/src/{video,publish}.rs`): + move the producer out of its slot on finish and store the `Finished`, as + the audio encoder bindings already do. moq-cli, moq-gst, moq-rtsp, and + moq-boy follow. The bindings' own API does not change shape. +- Add a `compile_fail` doctest per type, as `container::Finished` has, that + writing after finish does not compile. +- Leave the internal `finish(&mut self)` helpers that are not producers + (`ts::demux`, `ts::video`, `mkv::ebml`, `ts::stats`). + +Public API: breaking for Rust: `finish` on the ten `moq_mux::codec` +importers, `moq_mux::import::{Track, TrackStream}`, and +`moq_video::encode::Producer`. Wire: none. + +## Related + +- [The frame-taking video producer](/quest/m2/video-producer.md) - renames the video type this changes +- [TS import reports typed outcomes](/quest/m2/ts-typed-outcomes.md) - changes the TS importers' `finish` error type diff --git a/quest/m2/gateway-align.md b/quest/m2/gateway-align.md new file mode 100644 index 00000000000..2eb39fa42b5 --- /dev/null +++ b/quest/m2/gateway-align.md @@ -0,0 +1,99 @@ +# [M] The gateways admit a session the same way + +## Goal + +moq-webrtc, moq-rtmp, moq-srt, and moq-rtsp read as one family. An ingest's +rate cap is a field of `moq_mux::Ingest`, so WHIP, SRT, RTMP, and RTSP +ingest are capped by one setting. Every accept, pull, and publish in +moq-rtmp and moq-srt takes a `#[non_exhaustive]` request struct, as +moq-webrtc's do, so a later option is a new field. The WHEP pull is +`moq_webrtc::Client::pull`, like the other three. The CLI endpoint is +`moq import webrtc` and `moq export webrtc`; `rtc` is refused at startup +with a message naming the new spelling. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Align the gateways before the cut: the cap on the shared ingest type, + `subscribe` renamed `pull`, and request structs in moq-rtmp and moq-srt + (rejected: only the two renames and the cap's home; keep and take the + breaks in m3). moq-rtmp and moq-srt already break in this cut and + moq-webrtc has never been published, so the cut pays for it either way. +- ✅ The CLI endpoint becomes `webrtc`, with `rtc` refused by name + (rejected: keep `rtc`; name the endpoints `whip` and `whep`, since each is + both directions under `import` and `export`). The crate is `moq-webrtc` + and the auth transport an operator sees is `"webrtc"` + (`rs/moq-auth/src/request.rs`). + +Facts found by the audit: + +- Four admission shapes. WebRTC: a free function and a `#[non_exhaustive]` + struct, `whip::accept(&server, whip::Request { .. })` + (`rs/moq-webrtc/src/server/whip.rs:98`, `:160`) and `whep::accept` + (`rs/moq-webrtc/src/server/whep.rs:111`, `:155`). RTMP: positional + arguments and setters, `Publish::accept(self, origin, path, &ingest)` + (`rs/moq-rtmp/src/server.rs:601`) and `Play::with_delay(..).accept(origin, + path)` (`:750`, `:762`); its client is `publish(self, stream_key, source)` + and `pull(self, stream_key, origin, path, ingest)` + (`rs/moq-rtmp/src/dial.rs:294`, `:382`). SRT: the same on the server + (`rs/moq-srt/src/server.rs:360`, `:379`, `:432`, `:440`, `:451`) and a + half-converted client, where `publish(&self, origin, dial::Publish)` takes + a struct and `pull(&self, origin, path, ingest)` does not + (`rs/moq-srt/src/dial.rs:106`, `:122`, `:151`). RTSP: + `Client::pull(&self, ..)` (`rs/moq-rtsp/src/client.rs:121`). +- Names: the WHEP pull is `moq_webrtc::Client::subscribe` + (`rs/moq-webrtc/src/client/mod.rs:65`); the other three say `pull`. + RTMP's server egress request is `Play`, SRT's is `Subscribe`, and + `moq_srt::dial::Publish` sits beside the unrelated server-side + `moq_srt::Publish`. +- Two recorded decisions (2026-11-07, in + [the SRT rate handle](/quest/m3/srt-rate-handle.md) and + [WHEP pacing](/quest/m3/rtc-pacing.md)) say a rate handle reaches a + session as a struct field, never a `with_*` setter. SRT egress has only + setters, so its m3 cap would break the signature or the decision. +- The ingest cap is split: WHIP carries `whip::Request.rate` + (`rs/moq-webrtc/src/server/whip.rs:108`), while the SRT quest proposes "a + field on `moq_mux::Ingest`" (`rs/moq-mux/src/ingest.rs:12`, which already + holds `max_age`, `bandwidth`, and `linger`). +- The CLI spells the endpoint `rtc`: `ImportSource::Rtc` and + `ExportSink::Rtc` (`rs/moq-cli/src/args.rs:861`, `:1095`, `"rtc"` at + `:1113`), guide at `doc/bin/rtc.md`. The crate rename + ([moq-dev/moq#8122](https://github.com/moq-dev/moq/pull/8122)) did not + consider the endpoint. + +For the PR, in this order: + +1. `rate: Option` on `moq_mux::Ingest`; delete + `whip::Request.rate` and read the ingest's. WHIP keeps enforcing it + (TIAS, REMB, and the meter); SRT, RTMP, and RTSP ingest carry the field + and enforce it when their own quests land, and say so in the field's + docs, so an embedder is not told a cap holds where it does not yet. + Update [the SRT rate handle](/quest/m3/srt-rate-handle.md)'s API line. +2. Request structs for moq-rtmp (`Publish`, `Play`, and the client's + `publish` and `pull`) and moq-srt (`Publish`, `Subscribe`, and the + client's `pull`), replacing positional arguments and `with_*` setters. + Settle the two name clashes while the types move: one word for the + server egress request across RTMP and SRT, and `dial::Publish` against + the server's `Publish`. +3. `moq_webrtc::Client::subscribe` becomes `pull`. +4. `import webrtc` and `export webrtc`, with `rtc` kept as a hidden legacy + spelling refused at startup, the way renamed flags already are + ([moq-dev/moq#8747](https://github.com/moq-dev/moq/pull/8747)); + `doc/bin/rtc.md` moves to `doc/bin/webrtc.md` with its inbound links, and + `rs/moq-cli/src/rtc.rs` follows. + +Each crate's `MIGRATE.md` gets its note; `rs/moq-webrtc/MIGRATE.md` is still +titled "Migrating moq-rtc". No behaviour changes, so the existing gateway +tests are the proof, plus one CLI test that `import rtc` is refused with the +new name in the message. + +Public API: moq-rtmp, moq-srt, and moq-mux break; moq-webrtc changes while +unpublished. CLI: the `rtc` endpoint is renamed. Wire: none. + +## Related + +- [moq-webrtc's server binds at startup](/quest/m2/webrtc-bind.md) - changes the same crate's server constructor and the same CLI file +- [TS import reports its outcomes as values](/quest/m2/ts-typed-outcomes.md) - removes the CLI's downcasts of moq-srt and moq-rtsp errors +- [moq-srt per-connection rate handle](/quest/m3/srt-rate-handle.md) - enforces the ingest cap this gives a home, and adds the egress cap as a request field +- [moq-webrtc paces WHEP viewers](/quest/m3/rtc-pacing.md) - adds `rate` to `whep::Request` diff --git a/quest/m2/group-api.md b/quest/m2/group-api.md new file mode 100644 index 00000000000..ddd92c7fd0a --- /dev/null +++ b/quest/m2/group-api.md @@ -0,0 +1,112 @@ +# [L] Writing a group needs no invented start, and its end has one word + +## Goal + +A publisher opens the next group without computing its start, ends a group +with `finish`, and ends a track in error with a call of its own: + +- `track::Producer::append_group` takes an optional start. None means the + next start, one past the largest the track holds, so a track with no media + clock (a catalog, JSON, chat, input) never restates a number. +- `group::Producer::finish()` ends a group without declaring where it ends + (today's `close()`), and `finish_at(end)` ends it at a declared end + (today's `finish(end)`), the pair `track::Producer` already has. +- `track::Producer::finish_at(end)` is always a clean end. The errored end + that keeps the track's history is a separate call that takes the error. +- `track::Fill` is an enum the handler matches: a run of groups to serve, or + a time lookup that owes no group. + +Rust, `@moq/net`, moq-ffi, moq-c, and every wrapper carry the same shapes +and names. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `append_group` takes an optional start, none meaning next (rejected: a + public `append_next()` beside `append_group(start)`; keeping the required + start and documenting the idiom). It is the crate's existing convention + (`create_track(name, None)`, `subscribe(None)`), and JS and moq-ffi already + take no argument. +- ✅ A group's `close()` becomes `finish()` and `finish(end)` becomes + `finish_at(end)` (rejected: one `finish(end: impl Into>)`; + keeping `close()`). `close` already means releasing a handle or ending a + broadcast for good, and moq-ffi and JS already say `finish`. +- ✅ The errored end is its own call instead of + `finish_at(end, Some(err))` (rejected: keeping the optional error). + [moq-dev/moq#6750](https://github.com/moq-dev/moq/pull/6750) made `finish` + the clean end and `abort` the error. +- ✅ `Fill` becomes an enum (rejected: keeping one type told apart by + `time()`). AGENTS.md asks for one enum whose variants carry their data. + +Facts found by the audit, counted again at `80ca9787e3` over `rs/` outside +`rs/moq-net/`: + +- `track.largest().map_or(0, |largest| largest.group + 1)` is written out + 108 times in 38 files, in production in moq-audio, moq-boy, moq-json, and + moq-mux; moq-ffi (`rs/moq-ffi/src/producer.rs:105`) and moq-c + (`rs/moq-c/src/publish.rs:117`) each keep a private `next_start` for it. + moq-net already has the operation: `append_next` + (`rs/moq-net/src/model/track.rs:4366`) is `pub(crate)` and test-only. +- `group.close()` appears 252 times; `group.finish(end)` on a + `group::Producer` 3 times, one in production + (`rs/moq-mux/src/container/producer.rs:807`). The other 124 + `group.finish()` lines are wrapper types of other crates. +- moq-ffi's `MoqGroupProducer::finish()` calls Rust's `close()` + (`rs/moq-ffi/src/producer.rs:1065`), and JS has `finish()` + (`js/net/src/group.ts:706`), so only Rust changes its group names. +- The three production callers that pass an error to `finish_at` each + compute the live edge first + (`rs/moq-mux/src/container/producer.rs:1079`, + `rs/moq-audio/src/encode/producer.rs`, + `rs/moq-archive/src/consumer/track.rs:138`). +- Every fill handler branches on `Fill::time()` before anything else + (`rs/moq-archive/src/consumer/track.rs:148`, + `rs/moq-ffi/src/producer.rs:493`, `rs/moq-c/src/publish.rs:1049`), and a + lookup's `wanted` is `None` and `is_wanted` false throughout + (`rs/moq-net/src/model/track/fill.rs:949`). + +For the PR: + +- `append_group(start: impl Into>)`: existing calls with a `u64` + still compile. Delete `append_next`, the 108 copies, both `next_start` + helpers, and what `rs/moq-mux/src/start.rs` (85 lines) keeps only for this. + The first group of an empty track starts at 0, as the idiom did. +- `finish()` keeps `close()`'s meaning: every frame written reaches its + readers, and they cannot tell the group is whole. Say so in its docs, since + [media consumers](/quest/m2/time-addressing/consumers.md) read the declared + end `finish_at` writes. +- Recommended name for the errored end: `fail(err)`, ending at the live edge, + which all three callers want; add an end argument only if a caller needs + one. `abort` keeps discarding history. The name is the PR's to settle and + must mirror across languages (JS `finishAt(end, error?)` at + `js/net/src/track.ts:2212` loses its second argument). +- Recommended `Fill` variants: `Groups` and `Lookup`, so a lookup has no + `wanted`, `drop_groups`, or `end` to misuse. `MoqFill` in moq-ffi and the + moq-c fill handle take the same split. +- A scale-less group's `write_frame` still restates the group's start as + `Timestamp::unscaled(key)` (102 lines outside moq-net). Not decided here; + raise it in the PR if the optional start makes the restatement removable + for free. +- Rename the remaining `key` parameters that mean a group's start to `start` + where this PR touches the signature. +- [JavaScript](/quest/m2/time-addressing/js.md) and + [the bindings](/quest/m2/time-addressing/bindings.md) rename `sequence` to + `start`; whichever lands second mirrors these shapes, not the Rust they + replaced. Each binding's `MIGRATE.md` note rides this PR's Impact section. + +Tests: an empty track's first `append_group(None)` starts at 0 and the next +is one past the largest; a group ended by `finish()` reads whole with no +declared end; a track ended by the errored call serves every group below its +end and then yields the error. Run `just test interop --all`. + +Public API: breaking in Rust (`group::Producer::{close, finish}`, +`track::Producer::finish_at`, `track::Fill`), JS (`finishAt`), and the fill +handles of moq-ffi and moq-c. Wire: none. + +## Related + +- [@moq/net addresses groups by start](/quest/m2/time-addressing/js.md) - mirrors these names +- [Bindings address groups by start](/quest/m2/time-addressing/bindings.md) - mirrors these names +- [Media consumers address groups by start](/quest/m2/time-addressing/consumers.md) - reads what `finish_at` declares +- [Refresh a track by interval](/quest/m2/refresh-interval.md) - changes `track::Demand` beside these calls diff --git a/quest/m2/group-drops.md b/quest/m2/group-drops.md index 40edd71b95d..69d44aa0fe5 100644 --- a/quest/m2/group-drops.md +++ b/quest/m2/group-drops.md @@ -49,10 +49,22 @@ the container consumer's `Read::Gap` (`rs/moq-mux/src/container/consumer.rs`); `recv_group` is unchanged (rejected: a separate `recv_drop` read; a drop variant on `recv_group`). -Open, for whoever starts this, with the maintainer: a `Gap`'s start-keyed -`range` doesn't say how many groups it covers once starts are sparse, yet -the Goal has readers count losses. Recommended: `Gap` also carries the -number of groups dropped, which the drop set's runs already know. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ a +drop is a span and nothing more: SUBSCRIBE_DROP carries no group count on +lite-07, and `Gap` reports its start-keyed `range` with no count (rejected: +a count on SUBSCRIBE_DROP that `Gap` passes on, which would also have let a +skip become a drop with a count of 0). This settles the question left open +here on 2026-11-07, against its recommendation. Once starts are sparse a +span's length is not a number of groups, and only the node that dropped +them could count; a relay's downstream would need the count carried on the +wire at every hop for a number few readers use. A reader that needs a count +measures what it lost in time, which the span gives, or counts the groups +it did receive. So "count losses" in the Goal means account for every span: +the receive-windows benchmark's overcommitted cells finish when delivered +groups plus reported spans cover everything sent. At HEAD +`SubscribeDrop`'s `Group Count` (`rs/moq-net/src/lite/subscribe.rs`) is a +count of keys, which [the wire rewrite](/quest/m2/time-addressing/lite07.md) +turns into the span's end. Public API: breaking for `track::Ordered` only. Its one read, `poll_next_group` (and its async wrapper), returns @@ -67,4 +79,5 @@ Wire: none. ## Related +- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - SUBSCRIBE_DROP names the time spans `Gap` reports - [The receive-windows benchmark](/quest/m3/receive-windows-evicted.md) - its overcommitted cells wait on this (skipped by [moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838) until it lands) diff --git a/quest/m2/hang04/README.md b/quest/m2/hang04/README.md new file mode 100644 index 00000000000..e4d7b2aab49 --- /dev/null +++ b/quest/m2/hang04/README.md @@ -0,0 +1,55 @@ +# hang-04 freezes a catalog worth keeping + +## Goal + +The catalog JSON that the cut publishes as moq-hang-04 is the one a later +version can grow from: the broadcast's clock and join interval sit in a +section named for what they are, a player skips an entry it cannot read +instead of losing the whole catalog, nothing is promised that no producer +writes, and a mis-shaped section means one thing. Each child changes that +JSON, in `rs/hang`, `js/hang`, and `drafts/draft-lcurley-moq-hang.md`, while +hang-04 is still unpublished and every change is free. + +This README's own work is the last read before the freeze: once the children +have landed, the draft's `moq-hang-04` changelog describes the catalog that +ships (not the steps main took to reach it), `js/hang`'s +`catalog/parity.test.ts` and the Rust fixtures cover every section the draft +defines, and `just drafts check` passes. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit). The audit +read the catalog as a frozen format: hang-03 is what the datatracker and +`release` carry, so every hang-04 change on main is still open, and the 0.22 +readers are the first that check `version` at all. Each child's Plan records +its own decisions. + +The children land in any order. They overlap in three places, so whichever +lands second merges main first: + +- [Entry versions](/quest/m2/hang04/entry-version.md) and + [video warmup](/quest/m2/hang04/video-warmup.md) both edit the version + computation (`min_version` in `rs/hang/src/catalog/root.rs`, `minVersion` + in `js/hang/src/catalog/root.ts`) and the draft's Version section. +- [The sync section](/quest/m2/hang04/sync.md) is born strict, under the + rule [one strict rule](/quest/m2/hang04/shape.md) applies to the sections + that exist today. +- [The MPEG-TS section](/quest/m2/hang04/m2ts.md) removes a root member + that the strict rule would otherwise cover. + +What the audit judged and kept, so nobody reopens it without new evidence: +`include`, `track` apart from the ID, `instance` on references, `enabled`, +`preference`, `reorder`, `color`, `projection`, `stereo`, audio `layout`, +`interlaced`, audio `warmup`, `jitter`, the data tracks' estimates, `stats`, +and `echo`. + +The hang draft's duration and discontinuity marker rules are rewritten by +[media consumers](/quest/m2/time-addressing/consumers.md), which now lands +before the cut, so hang-04 never specifies the markers. + +Public API: each child's. Wire: the hang-04 catalog JSON, unpublished. + +## Related + +- [hang applies catalog updates at their timestamp](/quest/m2/catalog-at-timestamp.md) - the other catalog rule that freezes with hang-04 +- [Media consumers address groups by start](/quest/m2/time-addressing/consumers.md) - removes the markers from the draft's container rules diff --git a/quest/m2/hang04/entry-version.md b/quest/m2/hang04/entry-version.md new file mode 100644 index 00000000000..c2c143549e6 --- /dev/null +++ b/quest/m2/hang04/entry-version.md @@ -0,0 +1,76 @@ +# [M] A player skips a catalog entry newer than it reads + +## Goal + +A hang catalog entry (a rendition, a data track, an include) can carry its +own `version`: the oldest moq-hang draft that reads that entry correctly. A +reader skips an entry whose `version` is above its own and plays the rest, +and can tell its user that something was skipped. The root `version` stays, +and still refuses the whole catalog, for a change that reshapes the root. +hang-04's one remaining trigger, a `track` that differs from the entry's ID, +moves from the root to the entry. `rs/hang`, `js/hang`, and the hang draft +agree. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Skip per entry (rejected: keep the root gate and tell publishers never + to mix new-style and compatibility renditions in one catalog; keep as + is). Both hang-04 triggers are per-rendition features, so one such + rendition takes the whole catalog from an older reader, including the + compatibility rendition the draft tells publishers to add. + +Facts found by the audit: + +- A reader "MUST refuse a catalog whose `version` is above the draft it + implements" (the draft's Version section). `min_version` in + `rs/hang/src/catalog/root.rs` and `minVersion` in + `js/hang/src/catalog/root.ts` raise it to 4 for a renamed `track` or a + video `warmup`, both properties of one entry. +- [moq-dev/moq#5806](https://github.com/moq-dev/moq/pull/5806) saw this + cost and avoided it for `enabled` ("a live rendition toggle would flip + the whole catalog unreadable"). +- The draft already has the gentler tool: an unknown `container.kind`, + text `format`, or data `mode` ignores that entry alone. +- Published 0.21 readers check no `version`, so 4 protects nobody deployed + today. 0.22 is the first reader that checks, and the rule it ships is the + only forward-compatibility lever every later catalog change gets. + +Recommendations for the PR: + +- The entry member is named `version`, an integer, absent while it is 3. + Both serializers compute it from the entry, as the root's is computed + today, so a caller cannot claim less than the entry uses. +- A reader checks an entry's `version` before it validates the entry, as + `Probe` reads the root's before any section: a newer entry may have a + shape this reader would call malformed, and the malformed-rendition rule + refuses the whole catalog. +- A skipped entry is reported, not silent: the parsed catalog says which + IDs were skipped and the highest version among them, the per-entry twin + of `Error::UnsupportedVersion` and JS `UnsupportedVersion`, so a player + can say "upgrade to see everything". +- With [video warmup](/quest/m2/hang04/video-warmup.md) out of hang-04, the + renamed `track` is the only trigger, and nothing in hang-04 raises the + root `version`. Keep the root check and its tests: it is what a reshaped + root will use. +- An include is an entry too. Decide whether a skipped include is reported + the same way, and say so in the draft. +- A reference that an entry makes to a skipped entry (if any section can) + is the case to look for before settling the rule. + +Tests, in both languages and in the parity fixtures: a catalog holding a +compatibility rendition and a version-5 rendition reads as the +compatibility rendition alone and reports the skip; a version-5 entry that +would be malformed to this reader is skipped, not refused; a root +`version` of 5 still refuses; a duplicate `version` member in an entry is +refused as the root's is. + +Public API: additive on the parsed catalog (the skipped-entries report); +the computed root `version` changes for a catalog with a renamed `track`. +Wire: the hang-04 catalog JSON, unpublished. + +## Related + +- [Video warmup leaves hang-04](/quest/m2/hang04/video-warmup.md) - removes the other trigger from the same lines +- [Audio languages](/quest/m3/audio-lang.md) - a later rendition a 0.22 player should skip can be marked with this diff --git a/quest/m2/hang04/m2ts.md b/quest/m2/hang04/m2ts.md new file mode 100644 index 00000000000..4288f258531 --- /dev/null +++ b/quest/m2/hang04/m2ts.md @@ -0,0 +1,70 @@ +# [M] A transport stream carried whole is listed under the mpegts section + +## Goal + +The hang catalog has one MPEG-TS section. The track that carries a +transport stream whole (today the root `m2ts` section) is listed inside +`mpegts`, beside the description of a demultiplexed stream, and the section +has one `muxRate`. `hang::Catalog` has no MPEG-TS field, so the Rust and JS +core catalogs hold the same sections, and the MPEG-TS draft and the hang +draft agree on where the section is defined. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `m2ts` nests under `mpegts` with one `muxRate` (rejected: keep the + root key and add it to `js/hang` and the hang draft's root schema; keep + as is). + +Facts found by the audit: + +- `m2ts` ([moq-dev/moq#5003](https://github.com/moq-dev/moq/pull/5003)) is + a typed field of the core catalog (`rs/hang/src/catalog/root.rs`, + `rs/hang/src/catalog/m2ts.rs`), while its sibling `mpegts` is a moq-mux + extension section (`Mpegts` and `Ext` in + `rs/moq-mux/src/container/ts/catalog.rs`). Both are specified in + `drafts/draft-lcurley-moq-mpegts.md`, neither in the hang draft's root + schema. +- `js/hang` parses neither (`grep -rn 'm2ts\|mpegts' js/hang/src/catalog` + is empty), so the two core catalogs disagree about a root member. +- Both sections carry `muxRate` (`M2ts::mux_rate`, `Mpegts::mux_rate`), and + a track may appear in only one of them. +- The names do not say which is which, and `.m2ts` usually means 192-byte + Blu-ray packets, which the section refuses. +- Users of `M2ts`: `rs/moq-mux/src/container/ts/{passthrough,release}.rs`, + `rs/moq-mux/src/catalog/producer.rs`, `rs/moq-mux/src/import/format.rs`, + and `rs/moq-cli/src/{args,publish,subscribe}.rs`. + +Recommendations for the PR: + +- Shape: `mpegts.passthrough: { track, randomAccess }`, with the rate in + the section's existing `muxRate`. Pick the member name in the PR; + `passthrough` matches `moq import ts --passthrough` and the module. +- `M2ts` leaves `hang` for `moq_mux::container::ts` beside `Mpegts`. Check + first why `rs/moq-mux/src/catalog/producer.rs` reads it from the base + catalog and not the extension: that is the one thing that could make the + move cost more than a rename. +- JS gets no MPEG-TS schema: nothing in JS reads a transport stream, and + with the root member gone Rust and JS agree on the core catalog. Say so + where `js/hang`'s root schema lists its sections. (This reads the + decision's "in Rust, JS, and the draft" as parity of the core catalog; a + typed `mpegts` schema in `@moq/hang` waits for a JS reader.) +- Drafts: the MPEG-TS draft's `m2ts` section becomes a member of its + `mpegts` section, with one `muxRate` definition, and its MSFTS mapping + follows. The hang draft's "MPEG-TS Service Information" section, 51 + lines that repeat the MPEG-TS draft's `si` and SI track sections, is + replaced by a pointer. +- An older main build that wrote a root `m2ts` is unpublished, so no reader + keeps the old key. + +Tests: the passthrough round trip (`passthrough_test.rs`, `release_test.rs`) +reads the track from the nested member; a catalog with both a demultiplexed +description and a passthrough track is refused if they name the same track. + +Public API: breaking. Rust `hang::catalog::M2ts` and `Catalog::m2ts` move to +moq-mux. Wire: the unpublished `m2ts` root section of the catalog. + +## Related + +- [One rule refuses a mis-shaped catalog section](/quest/m2/hang04/shape.md) - `m2ts` is one of the root keys its rule would otherwise cover diff --git a/quest/m2/hang04/shape.md b/quest/m2/hang04/shape.md new file mode 100644 index 00000000000..5b325a7272d --- /dev/null +++ b/quest/m2/hang04/shape.md @@ -0,0 +1,90 @@ +# [S] One rule refuses a mis-shaped catalog section + +## Goal + +One rule decides what a hang catalog section with the wrong shape means: a +root key the hang draft defines has its shape, or the catalog is refused. +An application keeps its own root data under a namespaced key. `rs/hang` +and `js/hang` implement the one rule, and the draft states it once. The +draft's `delay` definition, its worked example, and the Rust and JS doc +comments for `delay` and `jitter` describe what the publisher measures, and +the stale passages in the hang draft are gone. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ One strict rule (rejected: one lenient rule for every key; keep the + per-key rules). Fail loud: a section that silently reads as empty hides a + publisher bug. +- ✅ The draft adopts the code's `delay` rule, with a corrected example and + doc comments (rejected: the code returns to the maximum shortfall). The + code's rule is the one that was measured. + +Facts found by the audit: + +- A mis-shaped section is, by key: refused (`video`, `audio`, `include`, + `m2ts`, `version`); empty unless it is an object (`media`, + `deserialize_media`); empty unless it has its map key (`text`, `json`, + `binary`, `deserialize_section`); absent unless it has a string field + (`stats`, `echo`, `deserialize_named`); absent on any error + (`media.join`, `DefaultOnError`). The decoders are in + `rs/hang/src/catalog/mod.rs`, mirrored by `section`, `named`, and + `object` in `js/hang/src/catalog/section.ts`. +- The lenient rules exist because an application "may already carry" the + key. `media`, `stats`, and `echo` are new since hang-03, added in the + same window as "an application SHOULD name its own root sections with a + namespaced key", and `include`, also new, got the strict rule. `text`, + `json`, and `binary` are in hang-03's root schema, so they were already + reserved. +- `delay` is defined three ways. The draft: "the maximum amount" a frame + trailed another rendition, with an example whose answer is 20. The code + since [moq-dev/moq#7689](https://github.com/moq-dev/moq/pull/7689): the + least a frame trailed within a window, and the largest of those windows + (`rs/moq-mux/src/catalog/estimate.rs`, "a window's delay is the least of + those trails"), which gives 0 on the draft's example. The JS comment + (`js/hang/src/catalog/video.ts`): "behind the broadcast's earliest + rendition". +- `jitter`: the draft says a frame written in presentation order + contributes none "regardless of frame rate", while + `rs/hang/src/catalog/video/mod.rs` and `video.ts` still say "if each + frame is flushed immediately, this would be 1000/fps". + +For the PR: + +- Rule: `stats`, `echo`, `text`, `json`, and `binary` decode strictly. + Delete `deserialize_section`'s and `deserialize_named`'s fallbacks and + their JS twins, keep `deserialize_object`, and replace the draft's + per-key "is ignored" and "treat as absent" sentences with one statement + in the Root section. [The sync section](/quest/m2/hang04/sync.md) and + [the MPEG-TS section](/quest/m2/hang04/m2ts.md) own their keys; whichever + lands second meets the rule already in place. +- Before deleting a fallback, search the tree and the docs for an + application that writes its own value under one of those keys + (`js/room` writes a root `hang` section, which no rule here touches). + One found in a published package is the evidence that would keep that + key lenient; record it. +- `delay`: rewrite the field section to the per-window least and the + largest window, with an example that yields a nonzero value under that + rule, and align the "never subtract one rendition's `delay` from + another's" sentence. Fix the `delay` and `jitter` doc comments on audio + and video in both languages. +- Stale draft text, none of which changes the format: delete Discovery + (it uses `ANNOUNCE_PLEASE` and `active=true`, which lite-07 does not + have, and names rooms `/room/alice.hang` where the Rooms section and + `js/room` use `{identity}/camera.hang`); the abstract's "real-time + conferencing protocol" becomes what the document is, the media format + every gateway shares; `JsonSchema` and `BinarySchema` gain the `instance` + the code carries. +- Not here: the duplicated MPEG-TS SI section goes with + [the MPEG-TS section](/quest/m2/hang04/m2ts.md), the dual-decoder + sentences with [video warmup](/quest/m2/hang04/video-warmup.md), and the + marker rules with + [media consumers](/quest/m2/time-addressing/consumers.md). + +Tests: for each key, a wrong-shaped value refuses the catalog in both +languages (the existing `a_foreign_media_value_is_ignored_but_a_bad_clock_refuses` +style tests flip); `parity.test.ts` covers the same documents. + +Public API: none. Wire: the reading rule for a catalog that is already +wrong; a document that read as "section absent" is now refused. diff --git a/quest/m2/hang04/sync.md b/quest/m2/hang04/sync.md new file mode 100644 index 00000000000..90458a616b8 --- /dev/null +++ b/quest/m2/hang04/sync.md @@ -0,0 +1,93 @@ +# [M] The catalog's clock and join interval live under a sync section + +## Goal + +The hang catalog's root section for the broadcast's timeline is named `sync` +and is flat: `sync.clock` is the wall-clock time of PTS zero, and +`sync.interval` is how often a viewer can join every audio and video track. +The `media` section, its nested `join` object, and their Rust and JS types +are gone. `rs/hang`, `js/hang`, the hang draft, the docs, and every reader +and writer in the tree use the new shape. + +```json +{ "sync": { "clock": { "wall": 1751846400000000 }, "interval": 2000 } } +``` + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ The section is named `sync` (rejected: `clock` back at the root with + `media` keeping only `join`, the audit's recommendation; keeping `media` + and redefining it in the draft as the broadcast's timeline; leaving it). + `media` is defined as "what applies to every audio and video track", and + the clock applies to more than those. +- ✅ The interval is `sync.interval` (rejected: `sync.join.interval`). The + nesting only left room for "a later join mechanism that is not a fixed + grid", which nothing plans. + +Facts found by the audit: + +- [moq-dev/moq#7652](https://github.com/moq-dev/moq/pull/7652) moved the + root `clock` under a new `media` section and gave no reason beyond + grouping it with the new interval. +- The clock times text cues, data tracks, `m2ts` frames, stats `arrival`, + and the catalog track itself + (`rs/hang/src/catalog/root.rs`: "snapshots share the broadcast clock with + media"), which + [catalog at timestamp](/quest/m2/catalog-at-timestamp.md) makes normative. + The draft's own Clock section calls it "the broadcast's one continuous + clock". +- hang-03 and `release` carry `clock` at the root, so a published 0.21 + player already loses wall-clock time against main. That stays true: a + second copy at the root would have to be written forever, so recommend + writing none and saying so in the Impact section. +- moq.pro's staging build has already ported to `media.clock` and ports + again. +- The section touches about 30 files: `rs/hang/src/catalog/{media,root,mod}.rs`, + moq-mux (13 files, `catalog/interval.rs` and the producers), moq-hls (8, + the grid), moq-transcode, moq-video, moq-audio, moq-cli, moq-gst, and the + moq-c and moq-ffi tests; `js/hang/src/catalog/{media,root,clock,include}.ts` + and `js/publish` (5 files); `doc/bin/hls.md`, `doc/concept/{hang,archives}.md`, + `doc/setup/upgrade.md`, and the interop clients. Find them with + `grep -rn 'media\.clock\|media\.join\|media\.interval()\|catalog::Join'`. + +For the PR: + +- Rust: `hang::catalog::Media` becomes `Sync` with `clock` and `interval` + (`Option`, whole milliseconds rounded up, as `Join::interval` is + today), `Catalog::media` becomes `Catalog::sync`, and `Join`, `JoinWire`, + and `Media::interval()` go. JS mirrors it: `root.sync`, `SyncSchema`. +- The section is strict from its first day, under the rule + [one strict rule](/quest/m2/hang04/shape.md) applies to the rest: a `sync` + that is not an object, a malformed `clock`, or an `interval` that is not a + positive integer refuses the catalog. Delete `deserialize_media` and its + JS twin, the `DefaultOnError` on the interval, and the draft's "belongs to + another application" and "MUST treat it as absent" sentences. A root + `media` key is then an application's own again, and is ignored like the + retired root `clock` (`a_retired_root_clock_and_hls_field_are_ignored`). +- Draft: rename the Media section and its anchors, fold Join into it, and + rewrite the hang-04 changelog lines that describe `media`. The mpegts + draft and the HLS section cite the interval by name. +- Rename the quests that quote the old names in the same PR: + `quest/m3/layers/`, `quest/m4/hang-thumbnail.md`, and + `quest/m2/time-addressing/consumers.md`. +- moq-hls reads the interval for its grid, so fix its stale crate metadata + while there: `rs/moq-hls/Cargo.toml` (description and the `ll-hls` + keyword) and `rs/moq-hls/src/lib.rs` advertise LL-HLS, which the crate + does not implement (no `EXT-X-PART`, `PRELOAD-HINT`, or `_HLS_msn` in + `rs/moq-hls/src`), and describe "HLS record tracks", which #7652 removed. + +Tests: the catalog fixtures and `parity.test.ts` round-trip the new shape in +both languages; a non-object `sync` and a zero `interval` refuse; a catalog +carrying the old `media` section reads with no clock and no interval. + +Public API: breaking. Rust `hang::catalog::{Media, Join}` and +`Catalog::media`; JS `root.media`, `MediaSchema`, `JoinSchema`. Wire: the +hang-04 catalog JSON, unpublished; a main-built reader of `media.clock` +finds no clock in a new catalog. + +## Related + +- [hang applies catalog updates at their timestamp](/quest/m2/catalog-at-timestamp.md) - puts the catalog track itself on this clock +- [One rule refuses a mis-shaped catalog section](/quest/m2/hang04/shape.md) - the rule this section follows from the start diff --git a/quest/m2/hang04/video-warmup.md b/quest/m2/hang04/video-warmup.md new file mode 100644 index 00000000000..8ae3d5de379 --- /dev/null +++ b/quest/m2/hang04/video-warmup.md @@ -0,0 +1,102 @@ +# [M] Video warmup leaves hang-04, and the players stop reading it + +## Goal + +moq-hang-04 defines `warmup` for audio renditions only. A video rendition +has no `warmup`, every video group starts with a keyframe again, and no +`version` rule mentions it. No player carries a video warmup path: `@moq/watch`, +`moq_video::decode`, `moq play`, moq-gst, and the bindings read a video +rendition as one whose groups each decode on their own. Audio `warmup` +(Opus pre-roll) and the container consumer's reach that serves it are +unchanged. Video warmup returns in a later catalog version with the +producer that writes it +([the intra-refresh epic](/quest/m4/intra-refresh/README.md)). + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Video `warmup` is dropped from hang-04 and audio `warmup` stays + (rejected: keep it and make a passing Safari and Firefox run a gate for + the cut; keep it as is). No producer writes it, two engines have never + run it, and a 0.22 player that claims catalog version 4 would accept a + later producer's rendition and mis-decode it instead of refusing it. +- ✅ The same quest deletes the players' video warmup path (rejected: keep + the path merged with no catalog that can carry the field; close the PR + that built it). + +A correction to the second decision. The question the maintainer answered +said [moq-dev/moq#8857](https://github.com/moq-dev/moq/pull/8857) ("a +warmup rendition plays through one decoder") was open, and the pick read +"delete the path, park #8857". It was not open: it merged 2026-11-15 +22:35Z, about ten hours before the question. So there is no PR to park and +no dual decoder left to delete (#8857 removed it). What this quest deletes +is the one-decoder path #8857 landed. The option the maintainer turned +down, "land #8857 anyway, so the one-decoder path exists and is tested +before any producer does", is the state main is in. The pick stands as +recorded, but it was made on a wrong fact, so the PR says this at the top +of its body for the maintainer to confirm or reverse before it merges. + +Facts found by the audit: + +- No producer sets a video `warmup`: the only writers are the Opus + importers and encoders. The import that would write it, + [H.264 import](/quest/m4/intra-refresh/h264-import.md), moved to m4 on + 2026-11-12 for want of a consumer. +- In browsers the path rests on inserting a recovery-point SEI for + Chromium (`insertRecoveryPoint`, `js/watch/src/video/decoder.ts`). + Firefox and Safari are unverified, and Chromium refuses a non-IRAP H.265 + frame sent as `key`, so an HEVC refresh rendition fails + ([second decoder](/quest/m4/intra-refresh/dual-decoder.md)). +- The draft makes video `warmup` above zero one of two triggers for + `version` 4 (`min_version`, `rs/hang/src/catalog/root.rs`; `minVersion`, + `js/hang/src/catalog/root.ts`), and lets a video group start at "a + picture from which decoding converges within that duration" (the + Container section's group rules). + +For the PR, what goes (find the rest with `grep -rn -i warmup rs js doc`): + +- Catalog: `warmup` on `hang::catalog::Video` + (`rs/hang/src/catalog/video/mod.rs`) and the video schema in + `js/hang/src/catalog/video.ts`; the warmup trigger in both version + computations; the MSF mapping for video + (`rs/moq-mux/src/catalog/msf/consumer.rs`, `js/watch/src/msf.ts`). A + video `warmup` in a catalog is then an unknown field, ignored like any + other. +- Browser: the warmup hold in `js/watch/src/video/recovery.ts` (its + leading-picture refusal stays), `insertRecoveryPoint` and the widened + subscription in `decoder.ts`, the `config.ts` field, + `js/watch/bench/warmup.ts` if it measures only video, and the paragraph + in `doc/lib/js/watch.md`. +- Rust: the warmup in `rs/moq-video/src/decode/consumer.rs`; the video + buffer's hold in `rs/moq-cli/src/play/{video,buffer,media}.rs`; the video + `warmup` in moq-ffi (`rs/moq-ffi/src/{video,media}.rs`) and every wrapper, + and `warmup_us` with `has_warmup` on moq-c's video config + (`rs/moq-c/src/api.rs`); moq-gst's video branch + (`rs/moq-gst/src/source/imp.rs`). +- What stays: `moq_mux::container::Playout { delay, warmup }`, the + consumer's reach in both languages, and every audio use. Check that no + audio test lost its coverage by leaning on a video case. +- Draft: the `warmup` field section describes audio pre-roll only, and + loses the sentences about a consumer that "also decodes from an earlier + group start" and "the earlier decoder's frames", which describe the dual + decoder #8857 removed. The group rule returns to "a video group MUST + start with a keyframe". The Version section and the hang-04 changelog + drop video `warmup`. +- Revert by hand rather than with `git revert`: #8857 also deleted the + dual decoder (`rs/moq-video/src/decode/select.rs`, 808 lines), which + must stay deleted. + +Tests: a catalog whose video rendition carries `warmup` parses with the +field ignored and no `version`; the players' join and skip tests pass with +the hold gone; the audio warmup tests are untouched. + +Public API: breaking. Rust `hang::catalog::Video::warmup`, the video +decoder's warmup options, the moq-ffi and moq-c video `warmup` fields; JS +the video schema's `warmup` and the watch config field. Wire: the hang-04 +catalog JSON and group rule, unpublished. + +## Related + +- [Video warmup returns with its producer](/quest/m4/intra-refresh/catalog-warmup.md) - restores this from history as the next catalog version +- [A player skips a catalog entry newer than it reads](/quest/m2/hang04/entry-version.md) - how a 0.22 player will refuse that later rendition; edits the same version lines diff --git a/quest/m2/ietf-records-per-track.md b/quest/m2/ietf-records-per-track.md new file mode 100644 index 00000000000..8ce3d627882 --- /dev/null +++ b/quest/m2/ietf-records-per-track.md @@ -0,0 +1,89 @@ +# [M] The ietf extension costs nothing on a moq-lite track + +## Goal + +On a lite-07 session that negotiated the `ietf` extension, object records and +a Group State ride only the Group Streams, FETCH responses, and datagrams of +a track whose TRACK_PROPERTIES Version is nonzero, meaning a moq-transport +publisher made it. A track published over moq-lite is byte-for-byte what it +is on a session without the extension. `setup::Extensions` and +`with_extensions` leave the public API and the `extensions` config tables: +moq-relay turns the extension on for its own links through a crate-private +door, and no other caller can. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Keep the extension; records and Group State ride only tracks with a + nonzero Version, and `setup::Extensions` leaves the public API and config + with the relay enabling it internally (rejected: take the extension out of + the cut until a consumer is named; keep as is). The 2026-11-09 decision to + keep the extension stands. The maintainer asked what "pay only when used" + would be: it is the Version the track already carries, which says whether + its original publisher spoke moq-transport, so no new flag is needed. + +Facts found by the audit: + +- A record precedes every frame on every relay link, plain media included. + `lite::ietf::Records::new(self.ctx.ietf, ..)` + (`rs/moq-net/src/lite/publisher.rs:6575`) keys on the session, not the + track, and the draft says so: "In a plain group, every record has a `Skip` + of 0" (`drafts/draft-lcurley-moq-ietf.md`, Object). + [moq-dev/moq#6058](https://github.com/moq-dev/moq/pull/6058) measured it + at 2 bytes per frame. +- The per-track fact already exists: `object_records: ietf && + track.info().ietf().is_some()` (`rs/moq-net/src/lite/publisher.rs:2556`), + added by [moq-dev/moq#8843](https://github.com/moq-dev/moq/pull/8843) so a + plain track can yield. Only the framing ignores it. +- moq-relay forces the extension on for both directions after loading its + config, whatever the file says (`rs/moq-relay/src/config.rs:339-340`), so + `[listen.extensions] ietf` and `[connect.extensions] ietf` are settings + nobody can use. Nothing else sets it. +- `solicit`, the struct's other field, is "moq-transport only" by its own + doc (`rs/moq-net/src/setup.rs:81-88`). Every caller that sets it false is + a test or a benchmark (`rs/moq-net/benches/auth.rs`, + `rs/moq-relay/tests/integration/auth_lifetime.rs`, `rs/moq-ffi/src/test.rs`, + `rs/moq-c/src/test.rs`). JS has the same one-field `Extensions` + (`js/net/src/connection/extensions.ts`). +- `rs/moq-net/AGENTS.md`: a moq-transport feature never adds public API. The + root file: no opt-out flags. + +Guidance for the PR: + +- Wire: the receiver knows a track's Version from its Track Stream before + any group arrives, so both sides agree on the framing with no per-stream + marker. A track with Version 0 has no Group State and no records, so + `drafts/draft-lcurley-moq-ietf.md` says the extension changes nothing for + it, and its rules for a plain group shrink to whatever a track with a + Version still needs. Rename the draft's "Since -00 (in progress)" heading + while there: no -00 was published, which `drafts/AGENTS.md` forbids. +- API: delete `setup::Extensions`, `Client::with_extensions`, + `Server::with_extensions`, the `extensions` field on moq-tokio's + `connect::Config` and `listen::Config`, the relay's two TOML tables + (`doc/bin/relay/config.md`), and JS `extensions`. Solicit is always + offered. The relay reaches the `ietf` offer through a hidden door + (`#[doc(hidden)]` or a moq-relay-only feature), since moq-relay is a + separate crate; pick whichever keeps it out of rustdoc and the API diff. + A config file that still names either table is refused with a message + naming the removal, as other removed keys are. +- Tests and benchmarks that set `solicit = false` to act as a peer without + it move to a test-support constructor. +- Tests: a plain track over a link with the extension encodes the same bytes + as over one without; a moq-transport track still crosses two relays with + its Object IDs, gaps, and properties (the path the 2026-11-09 decision + kept, which #8843 noted "is not exercised end to end": add that test). +- With [YIELDED deferred](/quest/m2/yield-defer.md), the "never reset with + YIELDED" rule for such tracks is already gone; if this lands first, leave + that sentence to it. +- Run `just test interop --all`. + +Public API: `setup::Extensions` and both `with_extensions` leave moq-net, +`extensions` leaves moq-tokio's configs and `@moq/net`. Config: +`listen.extensions` and `connect.extensions` are refused. Wire: lite-07-wip +with the `ietf` extension only; a moq-lite track loses its records. + +## Related + +- [YIELDED deferred](/quest/m2/yield-defer.md) - deletes the extension's yield exception +- [moq-transport time addressing](/quest/m2/ietf-time-addressing.md) - changes what moq-transport state a track carries diff --git a/quest/m4/ietf-time-addressing.md b/quest/m2/ietf-time-addressing.md similarity index 67% rename from quest/m4/ietf-time-addressing.md rename to quest/m2/ietf-time-addressing.md index c30ac2ba033..76847389de1 100644 --- a/quest/m4/ietf-time-addressing.md +++ b/quest/m2/ietf-time-addressing.md @@ -10,15 +10,27 @@ only between two moq-transport peers. ## Plan -Moved from m2 to m4 2026-11-14 (the m2 triage before the cut, under -/quest-afk, for the maintainer's review): ✅ m4 (rejected: m2; m3, where the -cut's re-split would keep a moq-transport wire change in the next cycle's -wire phase). The verbatim group ID, the only part this cut needs, rides -[the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). What is left changes only -what moq-net sends third-party moq-transport peers, adds no public API, and -has no named consumer, and AGENTS.md ranks moq-transport compatibility below -moq-lite's. It sits beside the other moq-transport quests in m4, such as -[range FETCH](/quest/m4/ietf-range-fetch.md). +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ back +in m2, so the Timestamp deletion lands before the cut (rejected: leaving it +in m4; confirming the deferral knowingly). This reverses the 2026-11-14 move +to m4, made by the m2 triage under /quest-afk for the maintainer's review on +the grounds that what is left changes only what moq-net sends third-party +moq-transport peers and has no named consumer. The audit's point: 0.22 would +otherwise publish TIMESTAMP behaviour that a quest already schedules for +deletion, to peers who would then see it withdrawn one release later. The +verbatim group ID, the other half, already rides +[the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). + +Decided the same day: ✅ `quest/m3/ietf-finish.md` and +`quest/m3/ietf-hole-stall.md` are deleted (rejected: keeping them as m3 +work). Both polished moq-transport interop between our own languages, which +AGENTS.md says does not matter: our libraries prefer moq-lite, so +moq-transport compatibility counts only against third-party implementations. +The interop `finish` case stays recorded as skipped on a pinned +moq-transport pass, and the ignored range-read test that waited on the +second quest is gone. So this quest's tests cover what it changes and do +not take on either gap. [Range FETCH](/quest/m4/ietf-range-fetch.md) stays +in m4 with its outside reporter. Decided 2026-11-03 (maintainer, the `/quest-import` grill of [moq-dev/moq#7573](https://github.com/moq-dev/moq/issues/7573)), replacing diff --git a/quest/m2/js-net-api.md b/quest/m2/js-net-api.md new file mode 100644 index 00000000000..0b256320f19 --- /dev/null +++ b/quest/m2/js-net-api.md @@ -0,0 +1,87 @@ +# [M] @moq/net requests are awaitable, and its last odd names match Rust + +## Goal + +Three `@moq/net` shapes change before the cut freezes them: + +- `await origin.request(path)` returns the `Broadcast.Consumer`, or throws + the refusal, as `origin.request(path).await?` does in Rust. The handle + keeps `active`, `closed`, and `close()` for reactive callers. + `js/net/examples/subscribe.ts` and every hand-rolled wait loop use it. +- `Connection.Props.delay`, the reconnect backoff, is named `backoff`. +- `Connection.Session.closed` and `Auth.Credential.closed` are + `GetPromise`, so a caller can peek them, as on every other + handle. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `Origin.Requesting` is a thenable that settles once (rejected: + `request()` returning a bare `Promise` while only `follow()` returns a + handle, which breaks the entry `@moq/watch` shares between the two; + keeping the handle and only fixing the example). Reactive callers lose + nothing, and one-shot callers stop writing a loop that never ends. +- ✅ `delay` becomes `backoff` (rejected: keep). Rust, moq-tokio, and + moq-ffi all say `backoff`, and `delay` already means two other things in + this package. +- ✅ Both `closed` fields become `GetPromise` (rejected: keep). It is the + package's own lifecycle rule. + +Facts found by the audit, re-checked at `80ca9787e3`: + +- `Requesting` (`js/net/src/origin.ts:2022`) holds + `active: Getter` and + `closed: GetPromise`. A refused request settles `closed` and + leaves `active` undefined: its doc says it "fails `Unroutable` while + pending once discovery syncs without a route". Rust's `Requesting` + resolves to the broadcast or the error (`poll_ok`, + `rs/moq-net/src/model/origin.rs:7191`). +- The package's hello world waits on `active.changed()` alone + (`js/net/examples/subscribe.ts:12-16`), so it hangs when the broadcast + does not exist. `grep 'active\.changed()'` over `js`, `demo`, and `test` + finds 26 waits; 17 files outside tests hold one, and only + `test/interop/clients/js-native/replace.ts` and `claims.ts` also watch + `closed`. +- `Once` is already a thenable over a signal + (`js/signals/src/index.ts:374`), so the pattern exists. +- `Connection.Props.delay` is `js/net/src/connection/pool.ts:74`, typed + `ReloadDelay` and re-exported as `Connection.Backoff` (`pool.ts:419`). + Rust: `pub backoff: Backoff` (`rs/moq-net/src/reconnect.rs:174`). The + other two meanings of `delay`: `WebSocketProps.delay`, the fallback's head + start, and `Track.Subscription.delay`, the `{min, max}` playout bound. + No caller outside `js/net` sets the reconnect option. +- `Connection.Session.closed` is a mutable `Promise` + (`js/net/src/connection/session.ts:99`) and `Auth.Credential.closed` a + `PromiseLike` (`js/net/src/auth.ts:56`). `js/AGENTS.md`: + "Terminal state is one `closed: GetPromise`". + +For the PR: + +- Awaiting resolves once `active` first holds a broadcast and rejects with + the `Error` that `closed` carries when the request ends first. `closed` + can also settle `null` while pending, when the caller closes the handle; + recommended: that rejects too, with one named cancellation error, so an + `await` never hangs. `Following` stays a plain handle: it never settles. +- Replace every loop the grep above lists with the `await`, starting with + the example and `test/smoke/clients/js-native/subscribe.ts`. Add a test + that awaiting a request for a missing broadcast rejects `Unroutable`. +- Rename the option, the `ReloadDelay` type to match its `Backoff` export, + the "delay cannot be shared" refusal in `pool.ts`, and `DEFAULT_DELAY`. + Leave the two other `delay` options alone. +- `Session.closed` also becomes `readonly`. Recommended, not decided: + `Auth.Issued.closed` and the `@internal` `Auth.Request.closed` + (`auth.ts:78`, `:109`) take the same type in the same PR, since they are + the only other `PromiseLike` terminal fields. +- Update `js/net/api/*.api.md` and `js/net/MIGRATE.md`, and any doc page + that shows the wait loop. + +Public API: breaking for `@moq/net`: `Connection.Props.delay` is renamed. +`Requesting` gains `then` and the two `closed` fields widen, both +compatible with code that awaits them. Wire: none. + +## Related + +- [Reconnect, absent means off](/quest/m2/reconnect-off.md) - changes the same reconnect options and names GOAWAY once +- [@moq/net addresses groups by start](/quest/m2/time-addressing/js.md) - the other `@moq/net` rename before the cut +- [Unused @moq/net exports](/quest/m2/unused-api/js.md) - the removals that land beside these diff --git a/quest/m2/json-write-at.md b/quest/m2/json-write-at.md new file mode 100644 index 00000000000..a270e2a2c89 --- /dev/null +++ b/quest/m2/json-write-at.md @@ -0,0 +1,66 @@ +# [M] moq-json writes take a value and a time + +## Goal + +Every moq-json write takes `(value, at)`: the value, then the timestamp it +applies at. `Timed` is what a read returns and appears in no write +signature. This holds for snapshot, stream, and window producers in +`rs/moq-json` and `@moq/json`, and for the catalog-registered wrappers in +`moq_mux::json`, so a caller who has learned one mode's producer knows the +others. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Writes take `(value, at)` and `Timed` stays on reads only, in Rust + and JS (rejected: `Timed` everywhere, including `mutate`, `modify`, and + `moq_mux::json`; keep as is). + +Facts found by the audit: + +- Rust passes the write time three ways. `snapshot::Producer::update(Timed<&T>)` + but `mutate(f, at)` and `modify(at)` on the same type + (`rs/moq-json/src/snapshot/producer.rs`); + `stream::Producer::append(Timed<&T>)`; + `window::Producer::push(Timed<&T>)` and `pop(count: Timed)` + (`rs/moq-json/src/window/producer.rs`), where a count is not a timed + value. +- `moq_mux::json::Snapshot::update(&T, timestamp)` and + `Stream::append(&T, timestamp)` (`rs/moq-mux/src/json.rs`) are already + positional. +- JS is mixed the same way: `update({ value, at })`, `append({ value, at })`, + and `push({ value, at })` take a `Timed`, while `mutate(fn, at)` and + `pop(count, at)` are positional (`js/json/src/{snapshot,stream,window}/producer.ts`). +- Users outside the crate, by files that name a mode: Rust moq-stats (6), + moq-hls (5), moq-c (4), moq-mux (2), hang, moq-boy, moq-cli, moq-ffi; + JS `js/publish` (8), `js/watch` (5), `js/hang`, `js/room`, `demo/carla` + (3 each), `js/stats`, `demo/web`, `js/msf`, `demo/boy`. + +For the PR: + +- Rust: `update(&T, at)`, `append(&T, at)`, `push(&T, at)`, and + `pop(count, at)`. JS: `update(value, at)`, `append(value, at)`, and + `push(value, at)`. `Timed` keeps its place on `next()`, `latest()`, and + the iterators. +- The bindings' JSON producers (`rs/moq-ffi`, `rs/moq-c`, and the + wrappers) already take the value and the time as two arguments; check + each and leave them. +- Recommended while the signatures are open, as one rename each: the + config types follow one scheme per mode (`producer::Config` and + `consumer::Config`), replacing `snapshot::Config` with + `snapshot::consumer::Config`, `stream::Config`, and + `window::{ProducerConfig, ConsumerConfig}`. Drop this if it grows the PR + past a mechanical change. +- Not changed: `snapshot::Consumer::new` takes a `track::Consumer` and + subscribes itself, while stream and window take a `track::Subscriber` + ([moq-dev/moq#7736](https://github.com/moq-dev/moq/pull/7736), on + purpose). Document the difference on the three constructors. +- [The catalog at its timestamp](/quest/m2/catalog-at-timestamp.md) reads + `Timed.at` from the catalog consumer; it is a read and is untouched. + +Tests: the existing producer tests, rewritten to the new calls; no +behaviour changes. + +Public API: breaking. Rust `moq_json::{snapshot,stream,window}::Producer` +write methods; JS the same three producers in `@moq/json`. Wire: none. diff --git a/quest/m2/libmoq-name.md b/quest/m2/libmoq-name.md new file mode 100644 index 00000000000..9ecd71bc818 --- /dev/null +++ b/quest/m2/libmoq-name.md @@ -0,0 +1,90 @@ +# [M] The hand-written C API ships as libmoq, its final line + +## Goal + +The hand-written C API is published at the cut as `libmoq` 0.22, under the +package identity its users already have: the `libmoq` crate, the +`libmoq-v*` tag family and release archives, and the CMake and pkg-config +names `release` ships. A C user moves from 0.6 to 0.22 by following +`MIGRATE.md` for the API, with no package rename on top. 0.22 is that +line's last minor: afterwards it takes fixes only. + +`moq-c` and `moq::c` name only the generated package (`c/moq`), which stays +unpublished until it is ready. The code-free `rs/libmoq` stub is gone, and +the docs no longer call either C API a stable ABI. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ ship +the hand-written API as `libmoq` 0.22 and keep `moq-c` unpublished for the +generated API (rejected: publishing it as `moq-c` and replacing that +package's whole API one minor later; shipping no C at 0.22). This reverses +the 2026-10-25 decision that the hand-written crate ships as `moq-c`, and +the rename in [moq-dev/moq#4288](https://github.com/moq-dev/moq/pull/4288). +C users were facing three names and two rewrites; this leaves one rename, +at the same moment as the API change that needs a rewrite anyway. + +Facts found by the audit: + +- Two packages in the tree claim one identity. `rs/moq-c` (hand-written): + `project(moq-c)` (`rs/moq-c/CMakeLists.txt:17`), `moq::c` (`:66`), + `moq-c.pc`, crate `moq-c` 0.7.0. `c/moq` (generated): `project(moq-c)` + (`c/moq/CMakeLists.txt:10`), `moq::c` (`:61`), `OUTPUT_NAME moq` (`:64`). +- `moq-c` has never been published in either form: there are 79 + `libmoq-v*` tags, newest `libmoq-v0.6.25`, and no `moq-c-v*` or `c-v*` + tag. `release` ships crate `libmoq` 0.6.26 with `project(moq)`, an + interface target `moq`, `moq.pc`, and `.github/workflows/libmoq.yml`. +- The generated line cannot ship at this cut: its type names and callback + contract change with [the exporter switch](/quest/m3/ffi-exporter.md). +- The plan this replaces published the hand-written crate as `moq-c` for + one minor and then gave the name to a total rewrite (CamelCase types, + `MoqError *` returns, task handles in place of `u32` ids), and no quest + planned the pointer release for the crate that would die. +- `doc/lib/index.md:43` and `doc/lib/c/index.md:3,11` call the hand-written + API a "stable ABI", though it is deleted once the generated one ships. +- `rs/libmoq` on `main` is a code-free stub at 0.6.12 whose description + reads "Renamed to moq-c". + +For the PR: + +- Replace the stub: `rs/moq-c` becomes `rs/libmoq`, crate `libmoq`, at a + version the cut's `just version` raises to the shared minor. Restore the + CMake project, target, and pkg-config names `release` has + (`git show origin/release:rs/libmoq/CMakeLists.txt`), and name the + workflow and tag family `libmoq` again. Diff the installed layout + (`include/`, `lib/`, `lib/cmake`, `lib/pkgconfig`) against a + `libmoq-v0.6.25` archive and explain every difference in the PR. +- Follow every reader: `.github/workflows/moq-c.yml`, `nix/overlay.nix` and + `flake.nix` (the `moq-c` package), `rs/justfile` (`package-moq-c`), + `sh/api-diff/ffi.sh` (it already accepts both tag families), + `sh/version.py`, `test/interop/clients/c`, `test/smoke/clients/c`, + `doc/lib/c`, and `RELEASE.md`'s `moq-c-v*` release family. +- `rs/moq-c/native-libs/` and `cpp/moq/cmake/moq-ffi.cmake` are read by the + generated package and C++ too; keep one source and repoint the readers + (`rg 'moq-c/native-libs|moq-ffi\.cmake'`). +- `MIGRATE.md`: the hand-written file's "Unreleased" section becomes + `libmoq` 0.6 to 0.22 and loses the package-rename steps. `c/moq/MIGRATE.md` + keeps the move to the generated API for when that publishes. +- The Nightly size report names four `moq-c-` archives, and + `sh/size/report.py` refuses a renamed series. Rename them in the report + and restart the history as + [the size history reset](/quest/m2/size-history-reset.md) does, or land + with it. +- Docs: strike "stable ABI" from `doc/lib/index.md` and `doc/lib/c`, and say + what is true: `libmoq` 0.22 is the hand-written API's last minor, and a + generated `moq-c` replaces it. +- Recommended: say in `rs/libmoq/README.md` that the crate takes fixes only + after the cut, so new moq-ffi features stop being mirrored into its 261 + hand-written exports. That is AGENTS.md's bindings rule + ("a feature reaches the bindings when a binding user needs it") applied + to C. +- Verify with `just rs check` for the crate, its `c-tests`, the C doc + samples, and `just test interop --all`. + +Public API: none beyond what `main` already changed; the package identity +returns to `libmoq`, so the published name does not change. Wire: none. + +## Related + +- [Retire the hand-written C crate](/quest/m3/release/c-retire.md) - deletes this crate once the generated `moq-c` publishes +- [Generated C bindings](/quest/m3/c/README.md) - the package that takes the `moq-c` name diff --git a/quest/m2/lite07-finalize.md b/quest/m2/lite07-finalize.md index bb1dbb5193a..61236df1487 100644 --- a/quest/m2/lite07-finalize.md +++ b/quest/m2/lite07-finalize.md @@ -164,13 +164,47 @@ Route Key Parameter, so the 2026-11-10 wait on its symbolic model and the route key lane's early signal above end when [the switch](/quest/m2/multicast/switch.md) lands. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit, which also +audited the lite-07 draft for what it could lose): + +- ✅ [YIELDED continuations](/quest/m2/yield-defer.md) leave lite-07 for + lite-08, where they are designed with takeover (rejected: keep them). +- ✅ The `ietf` extension stays, and + [rides only moq-transport tracks](/quest/m2/ietf-records-per-track.md) + (rejected: as it is, where every frame on a relay link carries a record). +- ✅ [The `\` path escape is finished](/quest/m2/path-escape.md) rather than + removed: moq-transport names a track by a tuple, and the escape is how a + moq-lite path carries one. +- ✅ Subscriber Min Age stays, reversing the 2026-11-14 pick, and + [gains its reader](/quest/m2/min-age-join.md); + [moq-dev/moq#8839](https://github.com/moq-dev/moq/pull/8839), which + removed it, was closed. +- ✅ Kept as they are: datagram tracks, including the lite-05/06 bridge (a + named consumer wants them); all seven lite versions, which keep + negotiating with today's behaviour; the hidden `.` path prefix; and the + route plan of [cache-aware multicast](/quest/m2/multicast/README.md) + (rejected: routing as a separately versioned SETUP extension). +- The smaller wire fixes ride [lite-07 by start](/quest/m2/time-addressing/lite07.md), + which rewrites the same messages: Max Age as value plus one, no GROUP + `Frame Start`, no Padding stream or datagram type, a kind in the track + listing, and drops as spans with no count. +- Not reopened: AUTH_ERROR's retry codes (2026-11-14) and AUTH_OK's rate + fields, which wait for lite-08 ([rate grant](/quest/m5/rate-grant.md)). + +The padding paragraph above is superseded: lite-07 freezes with no Padding +type, and [the padding probes](/quest/m5/probe-padding.md) bring one back in +the version that ships them. + ## Required +- [YIELDED deferred](/quest/m2/yield-defer.md) - removes reset code 0x3C and continuations from the lite-07 wire +- [ietf records per track](/quest/m2/ietf-records-per-track.md) - changes the extension's framing on relay links +- [Path escape](/quest/m2/path-escape.md) - defines a path segment when a path carries an escape +- [Min Age join](/quest/m2/min-age-join.md) - makes Subscriber Min Age normative - [Cache-aware multicast](/quest/m2/multicast/README.md) - lite-07 carries the redesigned route layer: routes to forwarding nodes, no holds or doubt, claims crossing trust boundaries by a chain, and no Route Key - [Routes and announces](/quest/m2/cluster-routes/README.md) - lite-07 carries the route layer: ROUTE per origin node and path-less ANNOUNCE, with the native hop list gone (only the temporary lite-06 compatibility chain remains) - [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - lite-07 carries group starts, previous-start links, GROUP_END, and time bounds instead of sequence numbers - [@moq/net by start](/quest/m2/time-addressing/js.md) - JS speaks the same lite-07 wire -- [Subscriber Min Age](/quest/m2/subscriber-min-age.md) - removes SUBSCRIBE's minimum age, which nothing reads ## Related diff --git a/quest/m2/min-age-join.md b/quest/m2/min-age-join.md new file mode 100644 index 00000000000..69e76eed1ea --- /dev/null +++ b/quest/m2/min-age-join.md @@ -0,0 +1,89 @@ +# [M] A cold join reaches back by Subscriber Min Age + +## Goal + +`Subscriber Min Age` stays on lite-07's SUBSCRIBE and SUBSCRIBE_UPDATE and +has a reader. A subscription that joins live and states one starts that far +behind the live edge: the publisher or relay answering it begins with the +cached group that covers the live edge minus Min Age, so a player's buffer +arrives full instead of filling in real time. A subscription that states +none starts where it does today. `Delay { min, max }` keeps its shape in +moq-net and `@moq/net`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Keep the wire field (rejected: drop it and keep `Delay::min` local). + This reverses the 2026-11-14 pick on + [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764), whose PR, + [moq-dev/moq#8839](https://github.com/moq-dev/moq/pull/8839), was closed + unmerged on 2026-11-16. The 2026-11-14 reason was that a field frozen with + no reader costs every relay an aggregate and a forward; the answer is to + give it the reader, not to remove it. +- ✅ The reader: a cold join reaches back by Min Age, from the answering + node's cache (rejected: leave it a hint with no defined behaviour). + +Facts found by the audit: + +- `Delay::min` documents itself as "the `Subscriber Min Age` on the + moq-lite-07 wire" and says "A publisher may use it, such as to start a + cold join that far back; nothing reads it there yet" + (`rs/moq-net/src/model/subscription.rs:57-68`). The draft calls it "a + hint that asks for nothing". +- It is already stated by players: `rs/moq-audio/src/decode/consumer.rs`, + `rs/moq-cli/src/play/video.rs`, and `js/watch/src/audio/decoder.ts` set + `delay.min` to the latency they hold, and both codecs encode it. The + publisher decodes it into the subscription + (`rs/moq-net/src/lite/publisher.rs:3084`, `:5285`) and nothing looks. +- Where a subscription starts is decided by one rule today: "A `Start` is a + floor ... The publisher SHOULD start at the oldest group at or above the + floor that Expiration has not expired" (draft, SUBSCRIBE). So a reader + gets everything its Max Age allows or, with the default start, only the + latest group. Neither is "as much as I am going to buffer": a lossless + reader (no Max Age) asking from the oldest gets the whole cache. +- The aggregate across readers is the smallest stated value + (`subscription.rs:553-556`), which a relay forwards upstream. + +Recommendations for the PR (the maintainer decided the behaviour, not these +details): + +- The rule, in the draft's SUBSCRIBE text beside the floor rule: a + subscription that follows the live edge and states Min Age starts at the + newest group that began at or before the live edge minus Min Age, never + below its `Start` floor and never at an expired group; with no such group + cached it starts at the oldest one it may. It stays best effort ("from + its cache"): the node never fetches upstream to satisfy it. The field's + text loses "a hint that asks for nothing". +- The live edge is the newest frame the node holds. On a timed track the + distance is in media time, from group starts; on a scale-less track it is + arrival age on the node's own clock, as expiry already measures it. +- An explicit `Time` start or a resumed position wins: Min Age applies only + to a join that would otherwise start at the latest group or the oldest + unexpired one. +- The aggregate a relay forwards: recommend the largest stated value in + place of the smallest. A relay that subscribes upstream cold fills its + cache from where the upstream starts, and each reader's own Min Age then + bounds what the relay hands it, so the smallest starves the reader that + buffers most. Nothing else reads the aggregate. Unstated still never + counts. This changes one SHOULD in the draft; settle it in the PR. +- Implement where a subscription's first group is picked in the model, so + the Rust publisher, the relay, and a moq-transport or pre-07 reader + (which state none) share it, and mirror it in `js/net`'s lite publisher. + SUBSCRIBE_UPDATE changing Min Age later moves nothing already started. +- Tests, with time mocked: a track of 500 ms groups and a join stating 2 s + starts four groups back and plays through to live with no gap; a join + stating none starts at the latest group as before; a join stating more + than the cache holds gets what there is; a two-relay chain with a cold + edge gives the reader its reach-back; a scale-less track reaches back by + arrival age. Update `doc/concept/moq-lite.md` and the lite-07 changelog + line for the field. Run `just test interop --all`. + +Public API: none; `Delay::min`'s doc changes from "nothing reads it" to the +rule. Wire: lite-07-wip keeps the field; its meaning becomes normative, and +the aggregate rule changes if the recommendation is taken. + +## Related + +- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - rewrites the same SUBSCRIBE fields, and gives the group starts this measures by +- [Refresh a track by interval](/quest/m2/refresh-interval.md) - the other thing a live join does: it may ask for a new group diff --git a/quest/m2/multicast/README.md b/quest/m2/multicast/README.md index 1d61475b7be..060a6bb29a8 100644 --- a/quest/m2/multicast/README.md +++ b/quest/m2/multicast/README.md @@ -168,6 +168,22 @@ flagged as costly, on standby wherever a second route exists, which about doubles a track's subscription state across the cluster). +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit, which +judged the route layer at this plan's end state): + +13. ✅ **The plan stands as item 2 has it** (rejected: freezing lite-07 with + claims only and moving the route exchange behind a negotiated SETUP + parameter with a version of its own, so the cut stops waiting on the + router and the switch and a third-party client implements no route + layer; keeping the plan with a fallback written down now). The audit's + case was the schedule, three XL quests in series before the freeze on a + rule re-decided on six days, and that an endpoint must parse a protocol + only relays speak. What it leaves is in + [the switch](/quest/m2/multicast/switch.md): the public route API and + config that would freeze by omission, the half `js/net` implements, what + a non-forwarding endpoint must parse, and the moq-cluster draft, which + still specifies the warm discount item 5 forbids. + The shape those decisions give, for the children to confirm or improve; each departure is a decision to list in its PR: diff --git a/quest/m2/multicast/switch.md b/quest/m2/multicast/switch.md index 21ab958223a..674ad8d35cc 100644 --- a/quest/m2/multicast/switch.md +++ b/quest/m2/multicast/switch.md @@ -2,7 +2,7 @@ ## Goal -Every lite-07 session in Rust and `js/net` drives the +Every lite-07 session in Rust drives the [new router](/quest/m2/multicast/router.md) on one announce stream per side, the draft specifies it, and the old rule is gone: ROUTE_HOLD, the doubt, DEAD's moved list, the Route Key Parameter with its proof and symbolic model, @@ -10,6 +10,13 @@ qualified Node IDs, routes per prefix with their Route Suffix and Route Depth, `path::Router`, and `RouteHandoff.tla`. The draft's routing text is shorter than today's and the announce stream carries fewer message types. +`js/net` implements the endpoint half only: it picks among the routes it +receives and sends claims, and it holds no router and declares no Node ID. + +The cut then publishes no route API or config that the old rule needed or +that nothing calls, and the moq-cluster draft, which specifies a routing +rule this one abandons, is retired with its moq-transport binding. + ## Plan Decided 2026-11-15 (maintainer, /quest-plan): lite-07 carries the new rule @@ -17,6 +24,29 @@ and the cut waits for it ([epic](/quest/m2/multicast/README.md) item 2). lite-07 is `-wip`, so relays pinned to `main` roll together, as each earlier lite-07 wire change did. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ The plan stands ([epic](/quest/m2/multicast/README.md) item 13; + rejected: the route exchange as a separately versioned SETUP extension; + the plan with a written fallback). +- ✅ `js/net` is an endpoint (rejected: porting the router to JS). The wire + below already says an endpoint that never forwards declares no Node ID + and sends claims, not routes; the Goal used to say every JS session + "drives the new router". This is where JS's dedicated route code + shrinks, about 2,270 lines by the audit's count + (`js/net/src/lite/floors.ts`, `route_key.ts`, and the announce handling + around them). +- ✅ The public route API and config the old rule needed are removed here, + and the route items nothing outside moq-net calls become crate-private, + listed under "Public surface" below (rejected: `#[doc(hidden)]` until + later; shipping them and breaking again). The cut freezes whatever this + PR leaves public. +- ✅ `moq_crypto::endpoint` goes with the Route Key, its only caller. +- ✅ The moq-cluster draft is retired with this PR (rejected: reconciling + the draft; an "out of date" note). If a third-party moq-transport relay + turns out to negotiate the extension, rewrite the draft to what ships + instead and say who. + Recommended wire, for the implementer to confirm or improve; each departure is a decision to list in the PR: @@ -35,12 +65,48 @@ is a decision to list in the PR: - The link mark stays as `upstream`. moq-net's per-link `proxy` switch, which the relay hard-wires on, goes if nothing else needs it; that is a public API change to report. +- Recommended by the audit, not decided: one identity per node. Once + qualified Node IDs are gone, a Node ID and a Hop ID differ only when a + Node ID rotates, which the draft requires when an origin's Revision would + reach 2^64 - 1 (`drafts/draft-lcurley-moq-lite.md:518`, `:536`). No origin + makes 2^64 changes. Drop the rotation rule and the Hop ID with it; + ROUTE_START's Node ID is then the first hop of its path and can go too. +- Recommended, not decided: the Rendezvous Hash is normative FNV-1a with a + private offset basis, `0x420C0DECB00B` (`draft:602`, + `rs/moq-net/src/model/origin.rs:796`). Every node must rank alike, and an + implementer who reaches for a stock FNV-1a will not. Use the standard + basis, or add a sentence saying the basis is deliberate. +- Recommended, not decided: number the Announce Stream's message types + densely when the set shrinks. `-wip` peers refuse each other by ALPN + anyway, and the holes freeze otherwise. Delete with the old rule: - `rs/moq-net/src/route/proof.rs`, `js/net/src/lite/route_key.ts`, `rs/moq-net/verify/route-key/`, the `verify-route-key` skill, and the interop route key lane (`test/interop/clients/js/route-key.ts`). +- The Route Key's public pieces, which the list above does not reach: + `origin::RouteKey` (`rs/moq-net/src/route/mod.rs:35`), + `origin::Config::route_key` (`rs/moq-net/src/model/origin.rs:112`), and + the relay's `cluster.route_key` with `--cluster-route-key` and + `MOQ_CLUSTER_ROUTE_KEY` (`rs/moq-relay/src/cluster.rs:741-748`, read at + `:1471`). The key is new since release, so it needs no refusal. +- `moq_crypto::endpoint` (the persistent Ed25519 node key, its z-base-32 + ID, the `serde` feature, and `just rs crypto-key`): its one caller is the + Route Key load at `rs/moq-relay/src/cluster.rs:1472`. A public key type + for Kixel's trust layer is Kixel's to add. +- The moq-cluster extension: `drafts/draft-lcurley-moq-cluster.md` (361 + lines), `rs/moq-net/src/ietf/cluster.rs` (536), `js/net/src/ietf/cluster.ts` + (263), its four code points (`rs/moq-net/src/ietf/mod.rs:99-114`), its + uses in `ietf/peer.rs`, `ietf/parameters.rs`, and `publish_namespace`, + and its mentions in `doc/concept/standard.md:53` and + `doc/bin/relay/cluster.md`. The draft still tells a relay to advertise a + lower cost for a namespace it already carries (line 52), the warm + discount that formed pull cycles here, and lets a link cost 0 (line 88), + which `route::Error::ZeroCost` refuses. The code implements neither, and + item 10 of the epic makes a moq-transport session an endpoint, which has + no path to carry. `cluster.max_hops` then bounds lite-03 to lite-06 only + ([config names](/quest/m2/relay-config-names.md)). - `rs/moq-net/verify/route/` and the `verify-route` skill, or rewrite the skill for the exhaustive search. - [Firefox tabs prove their route key](/quest/m5/routes-browser-proof.md), @@ -52,6 +118,45 @@ Delete with the old rule: whatever of [route fan-out](/quest/m2/cluster-routes/route-fanout.md) the new router answers, with the fixtures that pin them. +Public surface, to settle in this PR because the cut freezes it by +omission. All in `rs/moq-net/src/model/origin.rs`: + +- `Config::update_hold` (`:155`): no reader or writer outside moq-net + except one test sleep (`rs/moq-cli/src/play/media.rs:2478`). Crate-private + now; [acceptance](/quest/m2/cluster-routes/acceptance.md) retires the + hold itself. +- `Producer::with_proxy` (`:2404`): one caller, + `rs/moq-relay/src/cluster.rs`, always `true`. Remove it or make it + crate-private, as the wire bullet above says. +- `Source` (`:588`), `RouteInfo::source()` (`:704`), and + `Consumer::local()` (`:7701`): called only under `#[cfg(test)]` in + moq-relay. `Source::Peer(0)` means "named none", a special case inside a + value, which AGENTS.md forbids in public API. Crate-private. +- Before hiding each, grep Kixel and moq.pro for a caller (the maintainer's + condition for every unused-API removal) and keep what one uses. +- Two renames ride [the moq-net renames](/quest/m2/net-renames.md), not + this PR: `Config::hop` to `node`, and `with_preference` to `priority`. + Whichever lands second rebases; this PR must not reintroduce the old + names. The Route Offer's priority byte stays on the wire: the relay has + no key to set it yet, and + [outbound federation](/quest/m3/cluster-routing/federation.md) adds one. +- moq-ffi exposes only a route's `cost` and `available` + (`rs/moq-ffi/src/origin.rs`), so no binding changes. + +The announce-churn mitigations (`DEFAULT_UPDATE_HOLD` 300 ms at `:159`, +`RETRACT_QUARANTINE` 2 s at `:164`, and the same-clock dedup) sit in the +announce cursor every version shares and carry no marker saying they are +temporary. Whatever [acceptance](/quest/m2/cluster-routes/acceptance.md) +does not retire, this PR gates on the lite-06 session path under one named +marker, as the Lite-06 Chain is marked +(`rs/moq-net/src/lite/setup.rs:24-25`). The claim chain replaces the +Lite-06 Chain here, so update or delete that marker too: today it promises +a deletion at lite-08 that this plan makes permanent in another form. + +The route plan says what an endpoint sends. Say in the draft what an +endpoint that never forwards must parse of routes, dead hops, and floors, +and what it may ignore: a third-party client implements that list. + Rewrite the assertions of the acceptance fixtures (`tests/integration/route_acceptance.rs`, `route_failover.rs`, `route_cluster.rs`) for the new rule, keeping their topologies. @@ -71,7 +176,12 @@ sections, the message sections, the Setup Parameters, and the lite-07 changelog, and `doc/bin/relay/cluster.md`. Run `just check`, `just test interop --all`, and `just drafts check`. -Public API: the per-link `proxy` switch, if removed. Wire: lite-07-wip only. +Public API: breaking. `origin::RouteKey`, `Config::route_key`, and +`moq_crypto::endpoint` are removed; `Config::update_hold`, +`Producer::with_proxy`, `Source`, `RouteInfo::source()`, and +`Consumer::local()` leave the public API. Config and CLI: `cluster.route_key` +is removed (never released). Wire: lite-07-wip only; the moq-cluster +extension on moq-transport is no longer sent or read. ## Required diff --git a/quest/m2/native-media-config.md b/quest/m2/native-media-config.md new file mode 100644 index 00000000000..d94378de62d --- /dev/null +++ b/quest/m2/native-media-config.md @@ -0,0 +1,84 @@ +# [M] moq-video configs pick a device and a cursor mode with one typed field each + +## Goal + +Every moq-video config that opens hardware carries one `device` selector: a +typed value, present on every platform and feature set, honoured by whichever +backend opens and ignored otherwise, NVIDIA included. A caller sets it +without repeating moq-video's `cfg` gates or naming a backend. +`capture::Config::cursor` is an open enum (`Drawn`, `Hidden`) instead of a +bool, so a third mode is a new variant. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ One typed, always-present `device` selector per config (rejected: keep + the backend-named path fields and only drop their `cfg` gates, which + leaves NVIDIA unselectable; keep them and correct the crate doc). The + reference user is a transcode host with more than one GPU, which cannot + place NVIDIA work on a chosen GPU today. +- ✅ `capture::Config::cursor` becomes a `#[non_exhaustive]` enum with + `Drawn` and `Hidden` (rejected: keep the bool and add a second field for + the planned third mode). [The cursor apart from the frame](/quest/m4/capture-cursor.md) + adds a mode the portal already has, and a bool plus a second field can + say "drawn and also apart". + +Facts found by the audit: + +- [moq-dev/moq#8305](https://github.com/moq-dev/moq/pull/8305) replaced + environment reads with fields, and left backend-named, `cfg`-gated paths + on five public structs: `encode::Config` + (`rs/moq-video/src/encode/encoder.rs:210`, `:215`), `decode::Config` + (`rs/moq-video/src/decode/decoder.rs:94`, `:99`), `resize::Config` + (`rs/moq-video/src/resize.rs:24`), `encode::Capture` + (`rs/moq-video/src/encode/producer.rs:315`, `:318`), and + `moq_transcode::Config` (`rs/moq-transcode/src/config.rs:61`, `:66`, `:71`). +- A field that exists only under + `cfg(all(target_os = "linux", feature = "vaapi"))` makes every caller + repeat the gate: `grep -rn 'feature = "vaapi"\|feature = "v4l2"'` finds 23 + lines in `rs/moq-cli/src` and 10 in `rs/moq-transcode/src`. A dependent + crate has to mirror moq-video's feature names to compile. +- The crate doc promises the opposite: no public type, signature, or error + variant names a backend (`rs/moq-video/src/lib.rs:58`). +- NVIDIA has no selector: NVDEC opens device 0 + (`rs/moq-video/src/decode/backend/nvdec.rs:140`), and NVENC opens device 0 + (`rs/moq-video/src/encode/backend/nvenc.rs:467`) unless `Config::input`, a + `frame::vulkan::Device`, picks one by UUID (`:471`-`:478`). +- [GPU health](/quest/m3/gpu-health.md) already decided the vendor-neutral + identity (2026-10-05): the render node, carried on `frame::vulkan::Device`. +- `pub cursor: bool` is at `rs/moq-video/src/capture/mod.rs:305`, with five + readers: `capture/pipewire.rs:72`, `screencapture.rs:161`, `x11.rs:296`, + `wgc/native.rs:263`, and `rs/moq-cli/src/publish.rs:1135`. + +For the PR: + +- Shape the selector as a `#[non_exhaustive]` enum, such as a DRM render + node path and a V4L2 node path, defaulting to automatic choice. Settle in + the PR how a config that needs two nodes says so (moq-transcode names a + V4L2 decoder and a V4L2 encoder node separately today): one selector per + direction is the likely answer, since decode and encode configs are + already separate. +- NVIDIA maps a render node to its CUDA ordinal the way `Config::input` + already maps a Vulkan device, so NVDEC and NVENC both honour it. Test it + where two devices exist, or with the mapping function fed two fake + identities; skip, as the other NVIDIA tests do, on a host with none. +- A named device that fails to open is an error, as a named VA-API node is + today; only the automatic choice falls back. +- CLI flags keep their names (`--vaapi-device`, `--v4l2-encoder`, + `--v4l2-decoder`, `--no-cursor`) and lose their `cfg` gates where the + selector makes that possible. +- Recommended in the same PR, not decided by the maintainer: fence + `capture::Mode` (`rs/moq-video/src/capture/mod.rs:203`), the one listing + struct [moq-dev/moq#8742](https://github.com/moq-dev/moq/pull/8742) left + without `#[non_exhaustive]`. +- Update `doc/lib/rs/moq-video.md` and `rs/moq-video/MIGRATE.md`. + +Public API: moq-video and moq-transcode break (device fields on five +configs, `capture::Config::cursor`). CLI: none. Wire: none. + +## Related + +- [moq-video has a producer that takes frames](/quest/m2/video-producer.md) - changes `encode::Capture` and its driver in the same crate +- [GPU health](/quest/m3/gpu-health.md) - the render-node identity the selector reuses +- [The cursor apart from the frame](/quest/m4/capture-cursor.md) - adds the third cursor variant diff --git a/quest/m2/net-renames.md b/quest/m2/net-renames.md new file mode 100644 index 00000000000..c0d08a2a2ca --- /dev/null +++ b/quest/m2/net-renames.md @@ -0,0 +1,86 @@ +# [S] moq-net's node, version, handshake, and route priority carry their wire names + +## Goal + +Four public moq-net names match what they name before the cut publishes them: + +- An origin's identity is its `node`: `origin::Config::node`, + `origin::Producer::node()`, and `origin::Consumer::node()` replace `hop`, + matching the Node ID the lite-07 wire and SETUP carry. +- `moq_net::Version` is an opaque type. A caller parses it, prints it, and + asks `is_lite()`, `alpn()`, and `as_str()`; no variant is public, so adding + or dropping a draft is never an API change. +- `Server::handshake(now, session)` replaces `Server::accept_request`. +- A route's rank is its `priority`, as the Route Offer's byte is named: + `origin::Producer::with_priority` and `origin::Priority` replace + `with_preference` and `Preference`. + +Each rename mirrors into `@moq/net` and the bindings wherever the name exists +there. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `origin::Config::hop` becomes `node` (rejected: keeping `hop`). Hop + chains went private in the window, so `hop` is a word with no public + referent, and the wire says Node ID + (`rs/moq-net/src/lite/setup.rs`). +- ✅ `Version` becomes opaque (rejected: keeping the enum). Its variants hold + `lite::Version` and `ietf::Version`, and both modules are private + (`rs/moq-net/src/lib.rs:107,110`), so no caller can build or match a draft. +- ✅ `Server::accept_request` becomes `handshake` (rejected: keeping it). It + is named for a `Request` type that no longer exists and returns an `Accept` + that yields a `Handshake`. +- ✅ Route `with_preference` becomes `priority` (rejected: making it private + until federation needs it; keeping the name). The API says preference + while the wire and the draft say priority. + +Facts found by the audit, checked at `80ca9787e3`: + +- `hop` is public at `rs/moq-net/src/model/origin.rs:107` (the field), + `:2459`, and `:7483` (the accessors). `Client::with_peer_hop` and + `peer_hop` name the peer's identity the same way and are read by moq-tokio + (`rs/moq-tokio/src/connection.rs:967`) and moq-relay + (`rs/moq-relay/src/incoming.rs:88`). `origin::Config::max_hops` counts the + hops of a path and keeps its name; + [the route switch](/quest/m2/multicast/switch.md) marks it legacy. +- The one match on a `Version` variant outside moq-net is a test + (`rs/moq-relay/tests/integration/runtime_uring.rs:436`), which + `is_lite()` replaces. `rs/moq-net/AGENTS.md` already says to branch on + `is_lite()` and `alpn()` outside the crate. The relay also calls the + crate-level `Version::has_request_path` (`rs/moq-relay/src/cluster.rs:1779`, + `:2334`), which stays. +- `accept_request` (`rs/moq-net/src/server.rs:396`) has callers in 18 files + across moq-net, moq-relay, moq-tokio, and moq-uring. +- `with_preference` (`rs/moq-net/src/model/origin.rs:2390`) has no caller + outside moq-net and its integration tests; `doc/lib/rs/moq-net.md:21` + documents it for ranking several CDNs. Its planned consumer is + [outbound federation](/quest/m3/cluster-routing/federation.md), which adds + the relay's key for it. + +For the PR: + +- Rename `peer_hop` and `with_peer_hop` to `peer_node` and `with_peer_node` + in the same pass, so one word names an identity. The relay's + `cluster.node` key is a URL, not this number: keep them apart in docs, and + say in the PR if the collision argues for another word. +- `Version`: keep `ALL`, `FromStr`, `Display`, and serde as they are. If a + caller turns up that must tell one draft from another, add a method for + that question instead of exposing the variant. +- `origin::Priority` keeps `Preference`'s range and meaning (higher wins, 0 + is neutral, negative demotes). `track::Subscription` already has a + `priority`; say in the docs which is which. +- Update `doc/lib/rs/moq-net.md`, `doc/concept/moq-lite.md`, and each + package's `MIGRATE.md` note through the PR's Impact section. + +Public API: breaking renames in Rust (`origin::Config::hop`, the `hop()` +accessors, `peer_hop`, the `Version` variants, `Server::accept_request`, +`with_preference`, `Preference`) and wherever JS and the bindings mirror +them. Wire: none. + +## Related + +- [The route switch](/quest/m2/multicast/switch.md) - removes the route key beside the node identity this renames +- [Session close codes](/quest/m2/session-codes.md) - the other public moq-net cleanup in `error.rs` +- [Unused moq-net API](/quest/m2/unused-api/net.md) - makes the lite version predicates crate-private beside the opaque `Version` diff --git a/quest/m2/path-escape.md b/quest/m2/path-escape.md new file mode 100644 index 00000000000..02d85a3bbbf --- /dev/null +++ b/quest/m2/path-escape.md @@ -0,0 +1,92 @@ +# [L] An escaped slash never splits a path segment + +## Goal + +A path segment is the text between two unescaped `/`: `a\/b` is one segment +that holds a `/`, everywhere. The 32-segment limit, prefix matching, `head`, +hidden detection, announce compression, auth patterns, discovery, stats +buckets, and `@moq/net` all read segments through one escape-aware walk, so +a moq-transport namespace tuple maps to the same segments on both wires, and +the lite draft says what a segment is. Today the escape is only validated: +every one of those places still splits at every `/`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Finish the escape (rejected: lite paths have no escape and the + moq-transport layer owns the mapping; keep the escape and only write the + split-everywhere reading into the draft). The maintainer's reason: + moq-transport namespaces are tuples, and `\` is the delimiter rule we + invented to carry one in a path, so it has to be complete before it + freezes. + +Facts found by the audit: + +- `Path::new` checks escapes (`validate_escapes`, + `rs/moq-net/src/path/mod.rs:87`) and its own doc says "Segments still + split at every `/`". `Path::parts` is `split_terminator('/')`, and the + segment limit (`MAX_PARTS`, `:663`, `:672`) and `is_hidden` (`:299`) are + built on it. `Path::head(n)` returns `None` when the cut would land on an + escaped `/` (`:259`), so such a prefix can't be taken at all. +- The moq-transport mapping already walks real segments: + `escaped_fields` splits "at every `/` no escape covers" + (`rs/moq-net/src/ietf/namespace.rs:7`). So a namespace field holding `/` + is one tuple field on moq-transport and two segments on moq-lite: it + counts twice against the limit, a pattern's `*` matches half of it, and + `a\/.b` is hidden though no field starts with `.`. +- The draft defines the escape (Broadcast section: "A `\` (0x5C) escapes + the `\` or `/` that follows it") and matches "per path segment", without + saying which reading of a segment applies. +- Splitters outside moq-net, each `split('/')` on a path: + `rs/moq-auth/src/path.rs:39`, `rs/moq-auth/src/tier.rs:14`, + `rs/moq-pattern/src/pattern.rs:795,814`, `rs/moq-relay/src/auth.rs:1017`, + `rs/moq-stats/src/produce.rs:1338`, `rs/moq-cli/src/report.rs:492`, + `rs/moq-cli/src/archive.rs:69,274`, `rs/moq-hls/src/export/route.rs:96`. + JS: `js/net/src/path.ts:99,254,286,289,314,317,366,369`, + `js/net/src/origin.ts:728,775,791`, `js/stats/src/track.ts:40`. Sort + each into "a broadcast path" (change it) or "a URL or file path" (leave + it); `rs/moq-relay/src/web.rs:1059` and `cluster/key.rs:46` look like + URLs. + +Guidance for the PR: + +- One walk owns the rule: `Path::parts` yields segments split only at an + unescaped `/`, still escaped as written, and `escaped_fields` becomes a + caller of it. `head`, `has_prefix`, `strip_prefix`, `join`, `Relative`'s + resolution, the limit, and `is_hidden` follow, and `head` stops returning + `None` for an escape. Give other crates the walk and, where one compares + a segment's content, its unescaped bytes; no crate outside moq-net + splits a broadcast path by hand afterwards. +- `parts` is on the route table's lookup path, so keep a path with no `\` + on the plain split and show `rs/moq-net/benches/path.rs` and + `benches/routes.rs` unchanged for it. +- Hidden detection reads the first byte of the unescaped segment. Patterns + in `moq-pattern` and auth grants match whole segments; decide in the PR + whether a pattern itself may contain an escape, and recommend yes, with + the same grammar, so a grant can name a field holding `/`. +- A path that maps to a file or URL (archive directories, HLS routes, + stats bucket names) needs an encoding for a segment holding `/` or `\` + that can't escape its directory; refuse such a segment there unless one + already exists. +- Mirror it in `js/net/src/path.ts` first, since `origin.ts` and + `@moq/stats` build on it. The bindings take paths as strings and need no + API change; add one escaped path to their interop cases. +- Draft: one sentence in Broadcast defining a segment as above, and that a + prefix never ends inside an escape. `doc/concept` wherever paths are + described. +- Tests: a moq-transport publisher whose namespace field holds `/` crosses + a relay to a moq-lite reader and back with the same tuple; a grant + pattern matches that field as one segment; a 32-field namespace with + escaped separators is accepted; the fuzz target for paths + (`rs/moq-net/src/fuzz.rs`) covers the walk. Run `just test interop + --all`. + +Public API: `Path::parts`, `head`, and the prefix operations change what +they return for a path with an escaped `/`, in Rust and `@moq/net`; no +signature changes. Wire: lite-07-wip, for paths that contain an escape +only (segment count, prefix and pattern matching, hidden detection). + +## Related + +- [Finalize lite-07](/quest/m2/lite07-finalize.md) - freezes the path rules this completes diff --git a/quest/m2/reconnect-off.md b/quest/m2/reconnect-off.md new file mode 100644 index 00000000000..06994a68e43 --- /dev/null +++ b/quest/m2/reconnect-off.md @@ -0,0 +1,88 @@ +# [M] Reconnect settings mean the same in every layer, and GOAWAY has one name + +## Goal + +A reconnect or GOAWAY duration reads the same in moq-net, moq-tokio's flags +and config, `@moq/net`, moq-ffi, and moq-c: an absent value turns the bound +off, and zero means zero (give up at the first failure, retry at once, close +now). `Restart::Wait` is gone. The message a peer sends to drain a session +has one name in Rust and JS, and a session sends it with one call. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ one +quest before the cut that deletes `Restart::Wait`, makes an absent value mean +"off" and zero mean zero in every layer, and gives GOAWAY one name and one +send call (rejected: only the variant and the zero rule; leaving it to +[the connect policy's state](/quest/m4/connect-policy-state.md) in m4, where +it would be a break after the cut). The same field name means opposite +things in a browser and in Swift today, and the cut would publish both. + +Facts found by the audit, checked at `80ca9787e3`: + +- `Restart::Wait` (`rs/moq-net/src/reconnect.rs:156`) is set only by tests + (`rs/moq-relay/tests/integration/handoff.rs:115`, + `rs/moq-tokio/src/connection.rs:2861`, `rs/moq-net/src/reconnect/tests.rs`). + It was the cluster's policy until + [moq-dev/moq#8596](https://github.com/moq-dev/moq/pull/8596) moved the + relay to `Handoff` (`rs/moq-relay/src/cluster.rs:2291`), which covers the + same address at the cost of one session. +- `moq_net::reconnect::Backoff::timeout`: "Zero gives up at the first + failure", `None` retries forever (`rs/moq-net/src/reconnect.rs:89`), and + JS agrees (`js/net/src/connection/reload.ts`: `null` unlimited, zero gives + up). moq-tokio reads zero as off: "A configured zero turns the bound off" + (`rs/moq-tokio/src/connection.rs:191`), and so does moq-ffi: "0 retries + forever", "0 leaves it uncapped" (`rs/moq-ffi/src/session.rs:211-224`). + [moq-dev/moq#8265](https://github.com/moq-dev/moq/pull/8265) moved the core + to `Option` and left these two layers behind. +- `Goaway::with_timeout(Duration::ZERO)` means no deadline + (`rs/moq-net/src/goaway.rs:79`), and its one production caller + special-cases it: "the opposite of what was asked for" + (`rs/moq-relay/src/shutdown.rs:391`). `Server::with_timeout` in the same + crate takes `Option`. +- Rust has three public types named `Goaway`: the message + (`rs/moq-net/src/goaway.rs:34`), the reaction policy + (`rs/moq-net/src/reconnect.rs:116`), and moq-tokio's flags + (`rs/moq-tokio/src/connection.rs:290`). JS calls the message `Drain` and + the policy `GoawayProps` (`js/net/src/connection/goaway.ts:14,36`). +- `Session::drain()` returns a `goaway::Producer` whose only method is + `send`, and it hands out another each call (`rs/moq-net/src/session.rs:422`). + +For the PR: + +- Delete `Restart::Wait`, its branch (`reconnect.rs:603`), and its tests; the + relay handoff test that wants the old session to stay ignores the GOAWAY + instead. Run `/verify-reconnect`, since the model covers the restart rule. +- Each layer needs three states for `max` and `timeout`: unset (the + default), off, and a value. JS already has them (`undefined`, `null`, a + duration). Recommended: moq-tokio's flags and config keep "unset" as the + default and take a word (`none`) for off, refusing nothing that parses + today except that `0` now means zero; moq-ffi's `MoqBackoff` and moq-c's + `has_*` flags spell off as the absent value and document the default. + Whatever the spelling, write it once in `doc/` and mirror it. +- `connect.backoff.{max,timeout} = 0` changes meaning in existing config + files. The migration note names it; a warning at load when either is zero + is worth one release. +- `Goaway::with_timeout(Option)`, with zero closing at once. +- One name for the received message in Rust and JS, and one send call. + Recommended: `Goaway` stays the message in Rust and JS renames `Drain` to + it; the policy type becomes `reconnect::Handover` (its fields are + `redirect` and `handover`); `session.goaway(Goaway)` replaces + `drain().send(..)`, and `draining()` stays. The names are the PR's to + settle, mirrored in moq-ffi and moq-c. +- Leave what [a first session refused at SETUP](/quest/m1/first-dial-refusal.md) + owns ([moq-dev/moq#8817](https://github.com/moq-dev/moq/pull/8817)). + +Tests: one table of (unset, off, zero, value) per field run against +moq-net, moq-tokio's config parse, JS, and moq-ffi, asserting the same +behavior from each. + +Public API: breaking in Rust (`Restart`, `Goaway::with_timeout`, the +`Goaway` names, `Session::drain`), JS (`Drain`), moq-ffi, and moq-c. +Config and CLI: `connect.backoff.max` and `connect.backoff.timeout` of zero +change meaning. Wire: none. + +## Related + +- [The connect policy's state lives in one place, in both languages](/quest/m4/connect-policy-state.md) - reworks the same policy after the cut +- [A first session refused at SETUP fails fast](/quest/m1/first-dial-refusal.md) - changes the first dial's rule in the same files diff --git a/quest/m2/refresh-interval.md b/quest/m2/refresh-interval.md index da89cbe3bd5..00b77de809f 100644 --- a/quest/m2/refresh-interval.md +++ b/quest/m2/refresh-interval.md @@ -4,11 +4,13 @@ A publisher can declare in TRACK_INFO a refresh interval: a live join asks for a new group only once the newest group arrived at least that long ago. -A reader can also ask for one with a public `refresh()` on the track -subscriber, in Rust and `@moq/net`, judged by the same interval. Every hop -coalesces requests and judges them against its own cache, so the -publisher's interval caps how often new groups are made, by design rather -than by a per-hop rate limiter. +A reader can also ask for one with a public, no-argument `refresh()` on the +track subscriber, in Rust and `@moq/net`, judged by the same interval. A +request says only "a group newer than the newest this node holds": it +raises SUBSCRIBE_UPDATE's existing `Wanted Group` and adds no field, no +request number, and no tag on groups. Every hop coalesces requests and +judges them against its own cache, so the publisher's interval caps how +often new groups are made, by design rather than by a per-hop rate limiter. The interval is a duration, encoded and read like `max_age`, so it means the same on a timed and a scale-less track. A group's age is measured on the @@ -21,8 +23,11 @@ A track of one-frame groups, such as a [thumbnail](/quest/m4/hang-thumbnail.md), then produces a fresh group when a reader arrives or asks, and never more often than its interval, however many readers fan out behind the relays. A track with no group yet needs no interval: its first reader asks for the -first group at once, as the first consumer of an empty track does today -(`wanted()` is `Some(0)`), and the interval applies from that group on. +first group at once, and the interval applies from that group on. + +On the publishing side `track::Demand::wanted()` is a boolean, like every +other `wanted`, beside one refresh signal that says a new group is asked +for. ## Plan @@ -31,7 +36,7 @@ kixel.ai). The consumer is Kixel's desktop host, which serves an agent's screenshot from a lossless thumbnail and wants dashboard previews from the same track. -Decided: +Decided 2026-11-13: - ✅ moq m2, in lite-07 (rejected: m4 and lite-08). Its consumer is later work, which would put it in m4, but it changes lite-07-wip, and missing @@ -40,7 +45,43 @@ Decided: only the byte-ratio check; a per-hop rate limiter). The interval bounds the request rate by what the publisher declares. -Facts found while planning: +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `refresh()` takes no argument and raises `Wanted Group`, which + [time addressing](/quest/m2/time-addressing/lite07.md) makes a start + time: the node asks for a group that starts after the newest it holds + (rejected: a request counter riding SUBSCRIBE_UPDATE's update number, + with every group tagged by the highest update its publisher had seen, + which was this quest's 2026-11-13 recommendation; a caller-supplied + timestamp argument now; the interval alone with no `refresh()`). The + counter rode a field deleted the day after it was recommended: on + 2026-11-14 OLD drops became final and `Update` left lite-07. Rebuilding + per-hop numbering and a tag on GROUP for one reader costs more wire than + it earns. +- ✅ No timestamp argument yet. The maintainer's use is a thumbnail on + demand and, later, a robot that asks before each frame, like a PLI + (WebRTC's "send me a keyframe") with a way to deduplicate requests. + `Wanted Group` already deduplicates: every request made while the same + group is newest raises it to the same value, so a hop forwards at most + one update per group, and a publisher ignores a value its newest group + already passes. An argument ("a group at or after this time") can be + added later without a wire change, since the field is already a time. +- ✅ `track::Demand::wanted()` returns a boolean and a separate signal + reports a pending refresh (rejected: keep `Option` and add + `refresh_pending()`; keep). This quest takes that break because it is + already changing this API. + +What the guarantee is, and is not: `refresh()` resolves with the first +group that starts after the newest group the node held when it was called. +A group already in flight toward the node, created before the request +reached the publisher, satisfies it. So "a still taken after my action" is +best effort across hops: it holds at the publisher itself, and a remote +caller that needs it puts its own marker in the frame and reads until it +sees it. The [thumbnail](/quest/m4/hang-thumbnail.md) promises that much +and no more. The interval may delay the new group, never substitute an +older one. Rust and `@moq/net` share this contract. + +Facts found while planning and by the audit: - `Refresh` is a byte ratio today. `over_refresh` (`rs/moq-net/src/model/group.rs`) tests `cache - first > first * ratio`, @@ -49,10 +90,19 @@ Facts found while planning: The only trigger is a live-edge subscribe, and no reader can ask for a group. - SUBSCRIBE_UPDATE's `Wanted Group` already carries a relay's coalesced - demand upstream, and [time addressing](/quest/m2/time-addressing/lite07.md) - turns it into a start time. Build on that rather than adding a second - field. The request barrier above rides the update numbers, not that start - time, so it needs no clock shared between hops. + demand upstream: "the newest group the subscriber's live-edge joins want + ... A publisher MUST ignore a value at or below its largest group" (the + draft's SUBSCRIBE_UPDATE). +- `track::Demand::wanted()` returns `Option` + (`rs/moq-net/src/model/track.rs:5725`) where `broadcast::Demand`, + `group::Demand`, and `bandwidth::Demand` return `bool`. Callers outside + moq-net either test `.is_some()` (moq-transcode, moq-video, moq-ffi, + moq-stats) or compare it with their own largest group to detect a + pending refresh, written out three times (`rs/moq-json/src/refresh.rs`, + `rs/moq-stats/src/produce.rs`, `rs/moq-video/src/encode/producer.rs`). + Since groups are keyed by start the number is "one past every key + written", which is not the start the next group will have. JS mirrors it + as `get wanted(): Getter` (`js/net/src/track.ts`). - `rs/moq-video/src/encode/producer.rs` forces a keyframe on a join; it keeps working on the byte ratio. @@ -62,31 +112,30 @@ Recommendations for the PR: a typed choice. A track may want both (video wants a keyframe when the GOP is long, and not more than once a second), so recommend both, either one firing within the interval. -- `refresh()` has a request barrier, and it must be causal at the publisher: - a group already in flight when the request reached a relay would pass an - arrival check while showing the state before the request. So a group - answers a request only if the publisher created it after receiving that - request. Recommend reusing SUBSCRIBE_UPDATE's update number: each hop - forwards a request as a new update after it receives it (coalescing - requests that arrive between two forwards), the publisher tags each group - it creates with the highest update it had seen, and `refresh()` resolves - only with a group tagged at or past the update its request rode. The PR - settles the field's place in the draft and measures its cost; if it costs - more wire than it earns, weaken the guarantee to "a group that reached the - node after the request", state that post-action freshness is then best - effort, and change the thumbnail's promise to match. The interval may - delay the new group, never substitute an older one. Rust and `@moq/net` - share this contract. -- Update the lite draft (TRACK_INFO, SUBSCRIBE_UPDATE, and the changelog), - `doc/concept/moq-lite.md`, and the matching JS. Run `just test interop - --all`. +- The refresh signal's shape on `Demand`: recommend one awaitable that + resolves each time a new group is asked for and is cleared by the next + `append_group`, so the three hand-written comparisons become one call and + no caller sees a group number. `Fill::wanted()` returns `Option` + with a third meaning (the next group to serve); leave it, or rename it in + the same PR if it reads as the same thing. +- Mirror `wanted` and the signal in `@moq/net` and the bindings' demand + handle, with MIGRATE notes: this is the breaking part. +- Update the lite draft (TRACK_INFO's interval, `Wanted Group`'s text, and + the changelog), `doc/concept/moq-lite.md`, and the matching JS. Run + `just test interop --all`. +- Land after [time addressing](/quest/m2/time-addressing/lite07.md), so + `Wanted Group` is written once, as a time. Tests: a relay chain where many readers join and call `refresh()` on a one-frame track produces one group per interval at the publisher, with time -mocked. +mocked; repeated `refresh()` calls while one group is newest send one +SUBSCRIBE_UPDATE per hop; a publisher whose `Demand` reports a refresh opens +exactly one group for it. -Public API: additive (`refresh()`, the interval on `Info`). Wire: -lite-07-wip TRACK_INFO and SUBSCRIBE_UPDATE. +Public API: breaking for `track::Demand::wanted()` in Rust, `@moq/net`, and +the bindings; additive otherwise (`refresh()`, the interval on `Info`). +Wire: lite-07-wip TRACK_INFO gains the interval; SUBSCRIBE_UPDATE keeps +`Wanted Group` and gains nothing. ## Required @@ -95,3 +144,4 @@ lite-07-wip TRACK_INFO and SUBSCRIBE_UPDATE. ## Related - [Hang thumbnails](/quest/m4/hang-thumbnail.md) - the one-frame track this refreshes +- [Writing a group needs no invented start](/quest/m2/group-api.md) - changes `append_group` beside the `Demand` this changes diff --git a/quest/m2/relay-014-leftovers.md b/quest/m2/relay-014-leftovers.md new file mode 100644 index 00000000000..94453109d35 --- /dev/null +++ b/quest/m2/relay-014-leftovers.md @@ -0,0 +1,80 @@ +# [S] The relay drops its 0.14 upgrade leftovers + +## Goal + +moq-relay parses no setting that exists only to refuse a 0.14 config: the +ten hidden `--auth-*` flags with their environment variables and the six +hidden `[auth]` keys are gone, so each is an unknown flag or key like any +other. A public or mTLS rule may name exactly one broadcast: `anon` is the +broadcast `anon`, and the guard that refused a pattern without a wildcard is +gone from the relay and from `moq auth serve`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Remove the hidden flags, the hidden keys, and the upgrade guard + (rejected: keeping them another release). They guard an upgrade from 0.14 + that the `release` line (0.17) already forced, and the guard forbids a + grant that is otherwise legal, for good. + +Facts found by the audit: + +- `rs/moq-relay/src/auth.rs:133-186` declares `Legacy`: `--auth-key`, + `--auth-key-dir`, `--auth-api`, `--auth-public-api`, `--auth-domain`, + `--auth-mtls-tier`, `--auth-tls-root`, `--auth-tls-cert`, + `--auth-tls-key`, and `--auth-tls-disable-verify`, each hidden, each with + a `MOQ_AUTH_*` variable. `:93-110` keeps the TOML keys `key`, `key_dir`, + `auth_api`, `domains`, `mtls_tier`, and `tls` as `IgnoredAny`. + `Config::deprecated` (`:199-266`) pairs each with its replacement, and + `validate` refuses to start on any. +- All of it except the `tls` key is already on `release` + (`origin/release:rs/moq-relay/src/auth.rs:81-135`), so an operator coming + from 0.14 met the refusal one release ago. No quest owned the removal. +- `validate` also refuses a public pattern with no wildcard + (`rs/moq-relay/src/auth.rs:281-301`), because 0.14 read `anon` as the + prefix `anon/` and a pattern reads it as one broadcast. + `moq auth serve` repeats it (`rs/moq-cli/src/auth.rs:638-664`). A + deployment that wants to open exactly one broadcast to the public cannot + say so. +- Tests that pin the leftovers: `released_auth_keys_refuse_to_boot`, + the `RELEASED_AUTH_ENV` cases, and `released_auth_flag_refuses_to_boot` + (`rs/moq-relay/src/config.rs:700-800`), + `a_public_pattern_without_a_wildcard_refuses_to_start` + (`rs/moq-relay/src/auth.rs:1810`), and its twin at + `rs/moq-cli/src/auth.rs:1266`. The frozen list of released flags + (`rs/moq-relay/tests/integration/released_cli.rs`) does not name the ten: + they were hidden before the last release. + +For the PR: + +- Delete `Legacy`, the six keys, their entries in `Config::deprecated` + (and the method, if nothing else is left in it), and their tests. + `[auth]` is `deny_unknown_fields` like the rest of the config, so an old + key still stops startup, with serde's message instead of a tailored one. + Check that a `MOQ_AUTH_KEY` left in the environment is harmless: a relay + with `auth.url` set ignores it, and a relay with no other auth setting + already refuses to start as one that admits nobody, so neither boots + open. The danger the refusal was written for, `key` beside `public` + booting with every token ignored, is then a relay that serves its + public rules and says so in its startup log. +- Delete both guards and their tests. `anon` then grants the one broadcast + `anon`; an empty pattern names the root broadcast. Add the positive test: + a literal public pattern admits exactly that path and nothing beneath it. +- `doc/bin/relay/auth.md:315` ("no wildcard, such as `anon`, refuses to + start") becomes the plain rule: a pattern without a wildcard names one + broadcast, and `anon/**` names the subtree. +- Migration note for moq-relay: the tailored refusals for 0.14 settings are + gone, and a wildcard-free pattern is now accepted with its literal + meaning. +- Leave the refusals for names removed since `release` (`[client]`, + `[server.quic]`, `--server-quic-lb-*`): those protect the upgrade this cut + asks for. + +Public API: none (`Legacy` is crate-private). Config and CLI: ten hidden +flags, their variables, and six hidden keys stop parsing; a wildcard-free +public or mTLS pattern is accepted. Wire: none. + +## Related + +- [The relay's config names](/quest/m2/relay-config-names.md) - the old spellings this cut does refuse by name diff --git a/quest/m2/relay-config-names.md b/quest/m2/relay-config-names.md new file mode 100644 index 00000000000..0aa217860cd --- /dev/null +++ b/quest/m2/relay-config-names.md @@ -0,0 +1,96 @@ +# [S] The relay's config names agree with each other at the freeze + +## Goal + +Four names in moq-relay's configuration follow the rules the rest of it +already keeps. The QUIC-LB flags join their section and key +(`--listen-lb-*` for `[listen.lb]`). The peer-list endpoint's CA is +`cluster.api.root`, as the auth endpoint's is `auth.root`. The NixOS module's +`cluster.rootUrl` is `cluster.connect`. `cluster.max_hops` says it bounds +only the older wire versions. Each old spelling is refused with the new one +named. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `--listen-quic-lb-*` becomes `--listen-lb-*` (rejected: renaming the + table to `[listen.quic_lb]`; documenting a third exception). The docs' + rule is that a flag joins the section and key, and the table is the + shorter name. +- ✅ `cluster.api.tls.root` becomes `cluster.api.root` (rejected: keeping + the nested table). Both are "the CA for an HTTP endpoint the relay + calls", and a one-key `tls` table nests nothing. +- ✅ The nix option `cluster.rootUrl` becomes `cluster.connect` (rejected: + keeping a name from the root and leaf mode, which + [moq-dev/moq#8854](https://github.com/moq-dev/moq/pull/8854) removed). +- ✅ `cluster.max_hops` is marked legacy (rejected: deleting it now, which + leaves lite-03 to lite-06 meshes without their bound while the relay + still negotiates them). + +Facts found by the audit: + +- `doc/bin/relay/config.md:8-11`: "Every key is also a CLI flag and + environment variable that joins the section and key", with `listen.bind` + and the two `extensions` keys as the listed exceptions. `[listen.lb]` + (`rs/moq-tokio/src/listen.rs:204`) is spelled `--listen-quic-lb-id`, + `-nonce`, and `-forward-bind`, `-key`, `-peers` (`:387-462`), an unlisted + third. `release` has `--listen-quic-lb-id` and `-nonce`; the three + `forward` flags are new. `--server-quic-lb-*` is already refused naming + `--listen-quic-lb-*` (`:387-396`, `:664`). +- `auth.root` (`rs/moq-relay/src/auth.rs:46`) is flat; + `cluster.api.tls.root` (`rs/moq-relay/src/cluster/api.rs:38-46`) is new + since release and is the only key in its table. +- `nix/modules/moq-relay.nix:110` declares `cluster.rootUrl`, which sets + `MOQ_CLUSTER_CONNECT` (`:376-378`) and is named in two other options' + docs and an assertion (`:144`, `:162`, `:232-237`). `release` has the + option, setting `MOQ_CLUSTER_ROOT`. +- `cluster.max_hops` (`rs/moq-relay/src/cluster.rs:755`) bounds a hop list + that only lite-03 to lite-06 and the moq-cluster extension carry; a + lite-07 route has no hop list to bound. Nothing in its doc says so. +- `rs/moq-relay/src/cluster.rs:728`: "Hop-based routing on broadcasts + prevents announcement loops regardless of topology." Stale since lite-07. + +For the PR: + +- Flags and environment variables: `--listen-lb-id`, `--listen-lb-nonce`, + `--listen-lb-forward-bind`, `-key`, `-peers`, with `MOQ_LISTEN_LB_*`. + Refuse `--listen-quic-lb-*` and `--server-quic-lb-*` (and their + environment variables) through `moq_tokio::cli::Deprecated`, naming the + new spelling, as `--server-quic-lb-*` is refused today. The TOML keys do + not move. +- `cluster.api.root`, `--cluster-api-root`, `MOQ_CLUSTER_API_ROOT`. The old + key was never released, so it needs no refusal; an unknown key already + stops startup. +- Nix: rename the option and its mentions. Recommended: + `lib.mkRemovedOptionModule` naming `cluster.connect`, since the option is + on `release` and the repository refuses old names rather than aliasing + them. No other module in this repository sets it; downstream NixOS + configs do, so the PR's Impact section names the rename. +- `cluster.max_hops`: its doc, `doc/bin/relay/config.md`, and + `doc/bin/relay/cluster.md` say it applies to moq-lite-03 through 06 (and + moq-transport's cluster extension while + [the switch](/quest/m2/multicast/switch.md) keeps it) and leaves with + lite-06. `origin::Config::max_hops` gets the same sentence. If the switch + retires the cluster extension first, drop that clause. +- Fix the struct doc at `cluster.rs:728`. +- Update `doc/bin/relay/config.md`, `doc/bin/relay/cluster.md`, + the migration notes for moq-relay and moq-tokio, and + `rs/moq-relay/tests/integration/released_cli.rs`, the frozen list of + released spellings that must keep parsing: it gains + `listen-quic-lb-id` and `listen-quic-lb-nonce`. +- Tests: each old flag and variable refuses with the new name in the + message; the new ones parse; `nix flake check` covers the module. + +Not picked up, recorded so the next audit does not reopen them without new +evidence: `web.https.cert` not falling back to `listen.tls.cert` (additive +later), and `listen` against `bind` for socket keys (already on release). + +Public API: `moq_tokio::listen` flag names only. Config and CLI: breaking, +five flags and their variables renamed (two released), one unreleased TOML +key renamed, one nix option renamed. Wire: none. + +## Related + +- [The relay refuses dial keys it never uses](/quest/m2/relay-connect-keys.md) - the other config change at this freeze +- [The switch](/quest/m2/multicast/switch.md) - retires what else reads a hop bound diff --git a/quest/m2/relay-connect-keys.md b/quest/m2/relay-connect-keys.md new file mode 100644 index 00000000000..398fddb76d6 --- /dev/null +++ b/quest/m2/relay-connect-keys.md @@ -0,0 +1,72 @@ +# [S] The relay refuses the two dial keys it has no use for + +## Goal + +`moq-relay` stops at startup when given `connect.url` (`--connect`, +`MOQ_CONNECT`) or `connect.tokens` (`--connect-token`, +`MOQ_CONNECT_TOKEN`), with a message naming `cluster.connect` and +`cluster.token`. A relay's cluster dials carry only the credentials the +cluster settings name, so no token reaches a peer the operator did not +choose it for, a LAN peer included. The other `[connect]` keys (bind, TLS, +versions, timeouts) keep working as the template for cluster dials. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Refuse both keys by name (rejected: splitting the `[connect]` fragment + so the relay flattens only the dial settings, a larger change to a type + the clients share; documenting them as they behave). +- ✅ Reproduce the token reaching a cluster dial before changing anything: + the audit found it by reading, ran nothing, and no test covers it. + +Facts found by the audit: + +- The relay flattens the whole client fragment + (`rs/moq-relay/src/config.rs:42`, `pub connect: + moq_tokio::connect::Config`). +- `connect.url` (`rs/moq-tokio/src/connect.rs:513-514`) is read only by + `Client::publish` and `Client::consume` (`rs/moq-tokio/src/client.rs:164`, + `:346`, `:356`). Nothing in `rs/moq-relay/src` reads it, so + `moq-relay --connect https://peer` parses and does nothing, where the + operator meant `--cluster-connect`. The relay's rule elsewhere is that a + setting nothing reads stops startup. +- `connect.tokens` (`rs/moq-tokio/src/connect.rs:524-530`, new since + release) is documented as "credentials to present on every dial". + `peer_client` (`rs/moq-relay/src/cluster.rs:2316-2345`) clones the whole + template for each cluster dial, `rs/moq-tokio/src/client.rs:165` keeps its + tokens, and `rs/moq-tokio/src/connection.rs:952` presents them. The LAN + branch (`cluster.rs:2330`) narrows versions and pins a fingerprint but + leaves the tokens, while `doc/bin/relay/cluster.md:250-251` says a LAN + peer "is never handed `cluster.token`". So `connect.tokens` is an + undocumented second cluster credential that goes to every peer. + +For the PR: + +1. Write the failing test first: a relay configured with `connect.tokens` + and a static peer, then a LAN peer, and assert what each peer's SETUP and + AUTH streams receive. If no token arrives, the leak is not real: say so + in the PR, and the refusal still lands for the unread key. +2. Refuse both in `Config::resolve` (`rs/moq-relay/src/config.rs:322`), + beside the released `[client]` table it already names `[connect]` for. + The message names the flag, the environment variable, and the TOML key in + use, and what replaces each: `cluster.connect` for the URL, and + `cluster.token` or a peer's `token` for the credential. +3. Clear the template's tokens in `peer_client` as well, so an embedder that + builds a `Cluster` with `with_connect` gets the same guarantee as the + binary. +4. `moq-relay --help` and `doc/bin/relay/config.md` stop listing the two + keys under `[connect]`; `doc/bin/relay/cluster.md` keeps its sentence + about LAN peers, now true by construction. + +Tests: the refusal names each spelling; the reproduction from step 1 passes +with no token on any cluster dial; a relay with the remaining `[connect]` +keys still dials its peers. + +Public API: none (`Cluster::with_connect` keeps its type; its tokens are +ignored). Config and CLI: breaking for moq-relay only, `connect.url` and +`connect.tokens` refused. Wire: none. + +## Related + +- [The relay's config names](/quest/m2/relay-config-names.md) - the renames at this freeze diff --git a/quest/m2/relay-memory.md b/quest/m2/relay-memory.md new file mode 100644 index 00000000000..5e96a40648f --- /dev/null +++ b/quest/m2/relay-memory.md @@ -0,0 +1,77 @@ +# [M] The relay's memory growth since release is explained before the cut + +## Goal + +The relay's extra memory per connection on `main` against `release` has a +named cause, and the cut ships with it either fixed or written down as the +price of a feature. The release comparison reports memory beside CPU, so the +next one cannot miss it. Nothing here changes an API or the wire. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Profile it and fix or record it before the cut, and the cut waits + (rejected: writing the number into the report and shipping; leaving it to + the [performance audit](/quest/m3/audit-perf.md), whose release run comes + after the cut by its own `Required`). A regression found after 0.22 is + announced costs a patch release and a correction. +- ✅ The release comparison reports memory (rejected: CPU only, as today). + +Facts found by the audit: + +- `.github/release-perf.json` is the 2026-11-05 pairing of `release` + (`dc3478a863`) against `main` (`56d7989c78`), seven alternating rounds. + The median of `summaries[*].rss_bytes` per workload, relay process: + + | Workload | release | main | Change | + | --- | --- | --- | --- | + | `video` | 31.0 MiB | 28.4 MiB | -8% | + | `fanout` | 35.8 MiB | 35.5 MiB | -1% | + | `chat` (2,001 connections) | 428.3 MiB | 501.8 MiB | +17% | + + The `chat` ranges never overlap (428.1 to 429.0 against 499.6 to 503.1), + and the difference is about 37 KiB per connection. +- `.github/release-perf.md`, the report written from that file, never + mentions RSS, memory, or MiB (`grep -n -i 'rss\|memory\|MiB'` finds + nothing), so nobody read the number. +- The only earlier memory evidence for the in-tree QUIC stack is + [moq-dev/moq#5664](https://github.com/moq-dev/moq/pull/5664): 256 + sessions, measured on a host at load 20 to 56. A downstream deployment's + condition for relying on the stack is that relay memory matches the old + one. +- The comparison is of whole relays, so the growth may be the QUIC stack + (per-connection buffers, the 8 MiB socket buffers), moq-net (per-session + route and announce state), or the allocator. `grep -rni rss quest/` finds + only benchmark plumbing: no quest owned it. + +For the PR: + +1. Reproduce on today's `main` and `origin/release` with + `bench/workloads/chat.toml`, alternating rounds, recording + `/proc/loadavg`, with the evidence kept outside the checkout. `main` has + moved about 850 commits since the pairing, so the number comes first. +2. Attribute it with a heap profile of the relay on both sides + (`moq_tokio::jemalloc` is on-demand heap profiling; the pairing itself + ran the system allocator). Report bytes per connection by owner: + transport, session, origin, other. +3. Fix what is accidental in this PR. A cost that pays for a feature stays, + recorded in `.github/release-perf.md` with the feature and its PR, as + the performance audit records accepted CPU costs. A fix too large to + review here is a follow-up quest in m2, and this quest lists it under + `Required` until it lands. +4. Report RSS per workload in the release comparison. Each run's summary + already records `rss_bytes` (`bench/summary.py:91`), but + `bench/compare.py` never compares it, and the Release baseline section + of `quest/m3/audit-perf.md` never asks for it. It gets the same + accept-or-fix rule as CPU. + +Do not set a threshold: the outcome is a cause and a decision, not a number. +If the cause turns out to be a public default (a buffer size, a window), +changing it is the maintainer's call; bring the profile. + +Public API: none. Wire: none. Config: none expected. + +## Related + +- [Performance audit](/quest/m3/audit-perf.md) - reruns the release pairing after the cut and inherits the memory column diff --git a/quest/m2/session-codes.md b/quest/m2/session-codes.md new file mode 100644 index 00000000000..9f62cb040c0 --- /dev/null +++ b/quest/m2/session-codes.md @@ -0,0 +1,68 @@ +# [M] Session close codes name only moq-lite's registry, and errors classify themselves + +## Goal + +`moq_net::SessionError` has a variant only for a code in moq-lite's registry. +The seven codes only moq-transport defines decode to +`SessionError::Unknown(code)`, which already keeps the number, and are gone +from moq-ffi's `MoqProtocolKind`, moq-c's `MOQ_PROTOCOL_KIND_*`, and JS's +session codes. `moq_net::Error` has a public method that answers what a +caller does next (retry on the same source, find another route, or stop), so +no crate matches error variants to decide, and moq-gst uses it. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ the +seven moq-transport-only codes decode to `Unknown(code)` and a classification +method becomes public (rejected: also folding the flat `Error` variants into +the two registries now; keeping the variants). AGENTS.md says never to add +API for functionality only moq-transport has, and never to match on errors; +today the first forces the second. + +Facts found by the audit, checked at `80ca9787e3`: + +- The seven are `InvalidRequestId`, `KeyValueFormatting`, `InvalidPath`, + `AuthTokenCacheOverflow`, `UnknownAuthTokenAlias`, `InvalidAuthority`, and + `TooManyRequestUpdates` (`rs/moq-net/src/error.rs:90,39,94,57,69,98,74`). + None is in the lite-07 registry in `drafts/draft-lcurley-moq-lite.md`, + which removed KEY_VALUE_FORMATTING_ERROR in lite-07. Six were added in the + window. +- Each is mirrored into moq-ffi (`rs/moq-ffi/src/error.rs`) and moq-c + (`rs/moq-c/src/error.rs`), 7 lines each, and JS lists them in + `js/net/src/error.ts:43-63`. +- The only classification, `Error::retryable`, `unroutable`, and `transient` + (`rs/moq-net/src/error.rs:609-620`), is `pub(crate)`. moq-gst rebuilt it by + matching variants, two of the seven among them + (`rs/moq-gst/src/source/imp.rs:1034-1049`, `source_lost`). +- `Error` says "unauthorized" three ways (`Error::Unauthorized`, + `Session(SessionError::Unauthorized)`, `Stream(StreamError::Unauthorized)`), + and its doc defers folding them to "a later decision" + (`rs/moq-net/src/error.rs:342`). That fold stays deferred. + +For the PR: + +- The moq-transport layer keeps a private table to send these codes; only + decoding and the public enum change. A code received from a peer is + logged with its number. +- Design the public method from its callers, not from the private three: + moq-gst asks "did the source go away, or did it refuse me", and resume + asks "same source or another route". Recommended: one method returning a + small `#[non_exhaustive]` enum (for example `Retry::{Same, Reroute, Never}`) + rather than three booleans, mirrored by JS's `routeFailed` + (`js/net/src/resume.ts`). Survey every match on a `moq_net::Error` variant + outside moq-net first (about 50 lines by grep) and move each caller the + method answers; list the ones it cannot answer in the PR. +- moq-gst's `source_lost` and `catalog_lost` become calls to it. +- Mirror the removal in moq-ffi, moq-c, each wrapper's error type, and JS. + +Tests: each of the seven code numbers received on a moq-transport session +closes it with `Unknown(code)` and the same classification as before; moq-gst +holds its pads on a lost source and fails on a refusal, as today. + +Public API: breaking in Rust (`SessionError` variants), moq-ffi +(`MoqProtocolKind`), moq-c (`moq.h` constants), the wrappers, and JS; adds +the classification method. Wire: none. + +## Related + +- [moq-net's node, version, handshake, and route priority](/quest/m2/net-renames.md) - the renames beside this in the same crate diff --git a/quest/m2/signals-semantics.md b/quest/m2/signals-semantics.md new file mode 100644 index 00000000000..0fab86931bb --- /dev/null +++ b/quest/m2/signals-semantics.md @@ -0,0 +1,78 @@ +# [M] A signal notifies on a change, however it was written + +## Goal + +In `@moq/signals`, `Signal.update(fn)` notifies only when the value changed, +exactly as `set(value)` does. `mutate(fn)` always notifies and takes no +flag. The silent write, `set(value, false)`, and `Effect.timeout` are gone. +One spelling forces a notify, for the few callers that publish the same +value on purpose. The rest of the package's shape (`Signal`, `Computed`, +`Derived`, `Once`, `Effect`, `Getter`, `Setter`) freezes as it is. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `update` compares like `set` (rejected: documenting that `update` + forces; keep). Two writes of the same value should not differ by which + method wrote it. +- ✅ `mutate` always notifies and loses its parameter (rejected: keep the + flag). A mutation in place cannot be compared, so notifying is its only + correct behaviour. +- ✅ The silent `set(value, false)` goes (rejected: keep). Nothing outside + the package's own tests uses it. +- ✅ `Effect.timeout` goes (rejected: keep). It has no caller, and it reads + as `setTimeout` beside `Effect.timer`, which is that. + +Facts found by the audit, re-checked at `80ca9787e3`: + +- `set(value, notify?)` (`js/signals/src/index.ts:100`) notifies on a + change when `notify` is omitted, always on `true`, never on `false`. + `update(fn, notify = true)` (`:196`) and `mutate(fn, notify = true)` + (`:205`) pass `true`, so both force: `s.set(1)` on a signal holding 1 + delivers nothing, while `s.update((v) => v)` delivers once. +- `grep -E '\.update\('` finds 185 call sites outside tests in `js`, + `demo`, and `test` (some are not signals); none passes a second + argument. `.mutate(` has 65, none with a flag. +- `set(value, false)` on a `Signal`: only + `js/signals/src/index.test.ts:143` and `react.test.ts:206`. The + three-argument `effect.set(signal, value, cleanup)` is a different + method and stays. +- `set(value, true)` outside tests: `js/net/src/track.ts:4057`, + `js/net/src/ietf/publisher.ts:963`, `js/watch/src/broadcast.ts:589`, + `:590`, `:651`, `demo/boy/src/game.ts:225`, + `demo/carla/web/src/truck.ts:295`, `:299`. The demos send a repeated + command on purpose. +- `Effect.timeout` (`index.ts:876`): one caller, + `js/signals/src/index.test.ts:1045`. + +For the PR: + +- The risk is an effect that relies on `update`'s forced notify, such as + `update((list) => { list.push(x); return list; })`, which returns the same + object and would now deliver nothing. Before changing the method, find + them: make `update` throw in tests when `fn` returns its argument + unchanged, run every JS package's tests and the browser interop lane, and + move each hit to `mutate`. Record the count in the PR. +- Keep one forcing spelling. Recommended: `set(value, true)` stays as the + only use of the second parameter, typed `true` so `false` no longer + compiles (the audit's pick); a named method is the alternative if the + boolean reads badly. `js/AGENTS.md` names `set(v, true)`, so update that + line if the spelling changes. +- Not in scope, noted by the audit: `Effect.animate` hands its callback a + bare `DOMHighResTimeStamp`, the one bare millisecond number left in the + core packages, with about six callers. Leave it unless the PR finds it + free. +- `@moq/signals/react` and `@moq/signals/dom` are unchanged. +- Update `js/signals/api/*.api.md`, the package's `MIGRATE.md`, and the + Signals section of `js/AGENTS.md`. + +Tests: `update` returning an equal value delivers nothing and returning a +different one delivers once; `mutate` delivers once per call; a forced write +of an equal value delivers once. Verify playback and publish in a real +browser with `just dev`, since a missed notify shows up as a stuck UI, not a +failed unit test. + +Public API: breaking for `@moq/signals`: `update` stops notifying on an +equal value, `update` and `mutate` lose their second parameter, +`set(value, false)` and `Effect.timeout` are removed. Wire: none. diff --git a/quest/m2/sockets/README.md b/quest/m2/sockets/README.md new file mode 100644 index 00000000000..26a8c32cdde --- /dev/null +++ b/quest/m2/sockets/README.md @@ -0,0 +1,55 @@ +# Socket endpoints leave moq for Kixel + +## Goal + +The cut publishes no socket endpoint API. `moq_net::socket`, `@moq/net`'s +`Socket`, and the socket handles of moq-ffi, moq-c, and every wrapper are +gone, with their concept page and interop lane, and the two demos that used +them, MoQ Boy and CARLA, send input the way they did before sockets: the +viewer publishes a broadcast and the publisher follows it. Kixel, the one +downstream that builds on sockets, carries its own copy on moq-net's public +API. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ revert +the socket endpoint and put it in Kixel, and go back to the old wire format +for CARLA and MoQ Boy (rejected: confirming sockets as a moq feature, which +was the audit's recommendation; keeping them and trimming the leftover +`_track` vocabulary). AGENTS.md puts work a large live-media platform would +not use in Kixel. Byte streams and the sockets' `tcp` protocol already moved +there on 2026-11-14 +([moq-dev/moq#8772](https://github.com/moq-dev/moq/pull/8772)), which left +one downstream consumer, two demos, and a wrapper in every binding. + +Facts found by the audit: + +- Sockets are a naming convention over public API: a hidden broadcast per + endpoint (`/.server/`, `/.client/`) and a track + each way per session. `rs/moq-net/src/model/socket.rs` (1,150 lines) uses + one crate-private call, `reserve_unlisted_track` + (`rs/moq-net/src/model/broadcast.rs:406`). +- The surface that leaves: `js/net/src/socket.ts` (541 lines, 694 of tests), + `rs/moq-ffi/src/socket.rs` (318), `rs/moq-c/src/socket.rs` (511), a wrapper + in Python, Swift, Kotlin, Dart, and Go, `doc/concept/socket.md` (225), and + `test/interop/socket.sh` with four clients. +- It was built by the m1 socket epic between 2026-10-28 and 2026-11-15: + [moq-dev/moq#7677](https://github.com/moq-dev/moq/pull/7677), + [#7883](https://github.com/moq-dev/moq/pull/7883), + [#7884](https://github.com/moq-dev/moq/pull/7884), + [#8115](https://github.com/moq-dev/moq/pull/8115), + [#8468](https://github.com/moq-dev/moq/pull/8468), + [#8741](https://github.com/moq-dev/moq/pull/8741), + [#8825](https://github.com/moq-dev/moq/pull/8825), and the demo ports + [#8008](https://github.com/moq-dev/moq/pull/8008) and + [#8011](https://github.com/moq-dev/moq/pull/8011). None of it is on + `release`, so nothing published breaks. + +Order: the two demos move first, each in its own PR, and +[the removal](/quest/m2/sockets/remove.md) lands once nothing in the +repository dials or accepts. Kixel ports the code from history, from the +removal PR's parent commit; that port is planned in Kixel's tree, not here. + +## Related + +- [moq.dev's hosted demos run the cut](/quest/m3/release/demos-deploy.md) - deploys the demos these children restore diff --git a/quest/m2/sockets/boy.md b/quest/m2/sockets/boy.md new file mode 100644 index 00000000000..2939503f47e --- /dev/null +++ b/quest/m2/sockets/boy.md @@ -0,0 +1,83 @@ +# [M] MoQ Boy viewers publish their commands again + +## Goal + +MoQ Boy sends input without socket endpoints, in the format `release` still +runs. Each viewer publishes a broadcast under the viewer prefix with a +`command` track; the emulator follows the announcements under that prefix, +reads each viewer's commands, and reports every viewer's latency in the +shared `status` track. A `release` viewer and a `main` emulator interoperate +again, and neither side needs lite-07 on every hop. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ go back +to the old wire format (rejected: keeping the demo on sockets, which would +have to depend on Kixel once [sockets leave](/quest/m2/sockets/README.md)). + +The old format, as `origin/release` and +`ed8fe966538c^` (the parent of +[moq-dev/moq#8008](https://github.com/moq-dev/moq/pull/8008)) have it: + +- **Viewer** (`js/moq-boy/src/game.ts` then, `demo/boy/src/game.ts` now): + on first input it opens a route at + `{prefix-viewer}/{game}/{viewer id}`, a random six-character id, and + creates a `command` track with a millisecond timescale. Each command is a + `moq-json` snapshot update: `{"type":"buttons","buttons":[..], + "timestamps":[{"label","ts"}]}` or `{"type":"reset"}`. The route closes + after 60 s without input. +- **Emulator** (`rs/moq-boy/src/input.rs`): follows announcements under + `{prefix-viewer}/{game}/`, reads each broadcast's `command` track through + `moq_json` so snapshots and merge-patch deltas rebuild a whole command, + and treats a broadcast going offline as that viewer leaving. +- **Status** (`rs/moq-boy/src/status.rs`): `latency` is a map from viewer id + to that viewer's ordered latency components, on the shared `status` track. + The player count is the number of keys. +- `--prefix-viewer` (default `{prefix}/viewer`) and the element's + `prefix-viewer` attribute name the viewer prefix. The relay lets anonymous + viewers publish under it (`demo/viewer/**` on moq.dev). + +What #8008 changed and this undoes: the socket `Endpoint` on both sides, +`players` in place of `latency` on `status`, `Game.latency` in place of +`Game.viewerId`, `GameConfig.endpoint`, the `viewer-*` name refusal, the +default offer of only `moq-lite-07-wip` +(`rs/moq-boy/src/main.rs:127`, `demo/boy/src/element.ts:21`), and the +refusal of `--prefix-viewer` through `Deprecated::removed`. + +Restore the format, not the commit: the tree moved since. For the PR: + +- The element lives in the private `demo/boy` now + ([moq-dev/moq#8446](https://github.com/moq-dev/moq/pull/8446)), and + moq-json and the announce listing changed API in between; write against + today's API and keep today's tests where they still apply. +- Keep the fixes #8008's reviews found that are not about sockets: a command + group lost as `Old`, `Evicted`, `TooFarBehind`, or `GroupTooLarge` is + skipped, not fatal, and the command reader takes a zero delay budget. +- Re-decide rather than restore, each with a recommendation: + - The anonymous publish grant. Recommended: `demo/viewer/**`, as `release` + and moq.dev's auth server have it today, so the hosted deploy changes no + grant. It lets any viewer publish under another's id, as before; the + emulator trusts nothing in a command beyond a button state. + - The version list. Recommended: both sides offer their default list + again, and `demo/relay/localhost.toml` and `prod.toml` drop the comment + that lite-07 is listed for sockets. + - `status`. Recommended: `latency` returns and `players` goes, so a + `release` viewer reads a `main` emulator. Every viewer sees every + viewer's latency again, which #8008 had fixed; say so in the PR. +- `rs/moq-boy/MIGRATE.md` and `demo/boy`'s notes drop the entries #8008 + added, since nothing released ever saw the socket form. +- Update `doc/bin/demo.md` (the Sockets bullet) and the demo relay configs. + +Tests: the emulator's command tests (malformed command skipped, a superseded +command skipped, each viewer broadcast its own viewer, a viewer leaving) and +the element's round trip (input publishes, the idle timer closes the route). +Then run the demo locally and press a button from a browser. + +Public API: none published (`moq-boy` is `publish = false` and `demo/boy` +is private). CLI: `--prefix-viewer` returns. Wire (app level): `status` +carries `latency` again. + +## Related + +- [moq.dev's hosted demos run the cut](/quest/m3/release/demos-deploy.md) - deploys this +- [moq-json writes take a value and a time](/quest/m2/json-write-at.md) - changes the write the `command` track uses diff --git a/quest/m2/sockets/carla.md b/quest/m2/sockets/carla.md new file mode 100644 index 00000000000..d63709a1525 --- /dev/null +++ b/quest/m2/sockets/carla.md @@ -0,0 +1,89 @@ +# [M] CARLA drivers publish their controls again + +## Goal + +The CARLA demo drives trucks without socket endpoints, in the format it had +before [moq-dev/moq#8011](https://github.com/moq-dev/moq/pull/8011). Each +driver publishes a broadcast at `viewer/carla/{truck}/{driver}` with a +`control` track; the worker follows the announcements under +`viewer/carla/{truck}/` for each truck and feeds every driver's controls +into the safety gate; acknowledgements ride the truck's shared `status` +track. The worker and the player need no version that carries hidden +endpoint broadcasts. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ go back +to the old wire format (rejected: keeping the demo on sockets). The demo +itself stays in this repository because moq.dev hosts it (same date). + +The old format, as `4d51f9c051fd^` (the parent of #8011) has it: + +- **Paths** (`demo/carla/web/src/paths.ts`, `demo/carla/README.md`): cameras + at `carla/{truck}/{camera}.hang`; one broadcast per driver at + `viewer/carla/{truck}/{driverId}` with a `control` track of `moq-json` + snapshots. +- **Controls**: `{"type":"drive","sequence":42,"steering":..}`, `estop`, + `reset_estop`, and `respawn`, each with a `sequence` and `timestamps`. +- **Worker** (`demo/carla/sim/moq_carla_sim/publish.py`): an announce, + follow, and request loop per truck. It lists `viewer/carla/{truck}/`, + follows each driver path across that driver's runs, and pumps one run's + `control` track at a time into the command queue, ending a run when + another takes over or it goes offline. +- **Lease** (`drive.py`): bound to `(driver id, run counter)`. The counter + is process-wide and local to the worker, from + [moq-dev/moq#7678](https://github.com/moq-dev/moq/pull/7678): the bindings + hand out a run's broadcast without its route instance, and the count keeps + a run's late `driver_left` from releasing a later run of the same driver. +- **Status**: `driver`, `estop_by`, `sequence`, and `media_pipeline` on the + truck's shared `status` track; the status is the control echo. +- **E-stop**: the holder's rides its control track; a bystander latches and + resets through a short-lived `safety-` broadcast without taking the + lease. +- **Grants**: anonymous viewers publish under `demo/viewer/**`; the worker's + token publishes `carla/**` and subscribes `viewer/carla/**`. + +What #8011 changed and this undoes: `publish.Drivers` and the endpoint at +`carla/.server/{truck}`, the lease bound to a session id, replies on the +driver's session, the player's endpoint and its own origin, the +`VERSIONS` pin (`demo/carla/sim/moq_carla_sim/main.py:43`, +`demo/carla/web/src/paths.ts:39`), and the `demo/carla/.client/*` grant. + +Restore the format, not the commit. For the PR: + +- Keep what #8011's reviews fixed that is not about sockets (a bystander's + e-stop failure surfaces; shutdown does not hang on a full queue), and the + one-heartbeat (250 ms) delay budget on controls, so a reset right before a + drive still arrives whole. +- Re-decide rather than restore, each with a recommendation: + - The lease's run identity. Recommended: the local run counter returns as + it was. The alternative, an `instance()` accessor on the bindings' + broadcast consumer, was deferred on 2026-11-03 "if the move to sockets + doesn't make that counter moot"; sockets are gone, so it is open again, + and the bindings rule now adds an accessor only when a binding user + needs it. The demo works without it. + - The anonymous grant. Recommended: `demo/viewer/**` returns to + `demo/relay/prod.toml` and the `packaging/moq-relay/relay.toml` sample, + shared with [MoQ Boy](/quest/m2/sockets/boy.md). Anyone who can publish + under `viewer/carla/` can claim a driver id; the lease stays + cooperative, and the README says so as it did. + - The version list. Recommended: the worker and the player offer their + defaults again. + - Whether the player's element keeps the origin it took for the endpoint. + Recommended: whichever is less code against today's `@moq/net`; the + driver's control broadcast needs an origin to publish into either way. +- Update `demo/carla/README.md`, `doc/bin/demo.md` (the control bullet), the + installer text under `demo/carla/sim/systemd/`, and the token example. + +Tests: `just carla check` (the worker's lease, watchdog, and e-stop tests +against the restored loop) and `bun test` in `demo/carla/web`. The live +simulator needs the GPU image: drive a truck from a browser after deploying, +including a bystander e-stop, as #8011 asked. + +Public API: none. Wire (app level): controls and acknowledgements move back +to broadcasts; the worker and the player deploy together. + +## Related + +- [moq.dev's hosted demos run the cut](/quest/m3/release/demos-deploy.md) - deploys this +- [moq-json writes take a value and a time](/quest/m2/json-write-at.md) - changes the write the `control` track uses diff --git a/quest/m2/sockets/remove.md b/quest/m2/sockets/remove.md new file mode 100644 index 00000000000..a078b6f91c6 --- /dev/null +++ b/quest/m2/sockets/remove.md @@ -0,0 +1,96 @@ +# [M] moq-net, @moq/net, and the bindings have no socket endpoints + +## Goal + +No package this repository publishes has a socket endpoint: `moq_net::socket` +is deleted from Rust, `Socket` from `@moq/net`, the socket handles from +moq-ffi and moq-c, and the wrapper from Python, Swift, Kotlin, Dart, and Go, +with `doc/concept/socket.md`, the interop sockets lane, and +`socket::is_endpoint` in every language. What exists in moq-net only for +sockets goes with them, except the one private call Kixel's copy needs, which +becomes public. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ socket +endpoints leave for Kixel +([the epic](/quest/m2/sockets/README.md) has the reasons and the rejected +options). `is_endpoint`, which the unused-API sweep had listed for the FFI, +leaves here instead. + +Delete, as listed at `80ca9787e3`: + +- Rust: `rs/moq-net/src/model/socket.rs` and its `pub mod socket` + (`rs/moq-net/src/model/mod.rs:7`), `rs/moq-net/tests/integration/socket.rs`, + `rs/moq-relay/tests/integration/socket_auth.rs`, and the CHANGELOG and + `doc/lib/rs/moq-net.md` entries. +- JS: `js/net/src/socket.ts`, `socket.test.ts`, `js/net/bench/socket.ts`, + the `Socket` export (`js/net/src/index.ts:39`), `js/net/api/index.api.md`, + and `doc/lib/js/net.md`. +- Bindings: `rs/moq-ffi/src/socket.rs` (and the `MoqSocketEndpoint` entry in + `rs/moq-ffi/uniffi.toml`), `rs/moq-c/src/socket.rs` and its `moq.h` + functions, `py/moq-rs/moq/socket.py` with `tests/test_socket.py` and the + `sockets` bench in `benches/ffi.py`, `swift/Sources/Moq/Socket.swift`, + `kt/moq/.../socket/Socket.kt`, `dart/moq/lib/socket.dart`, + `go/wrapper/socket/`, their tests (`rs/moq-ffi/src/test.rs`, + `rs/moq-c/src/test/parity.rs`), README and docs mentions + (`rs/moq-c/README.md`, `py/moq-rs/README.md`, `doc/lib/py/index.md`), and + the generated Dart file's socket classes. +- Interop: `test/interop/socket.sh`, the `--sockets` lane and `run_sockets` + in `test/interop/interop.sh`, `clients/rust/socket.rs`, + `clients/rust/socket-js.rs`, `clients/js-native/socket.ts`, + `clients/python/sockets.py`, the `interop-socket` and `interop-socket-js` + examples in `rs/moq-cli/Cargo.toml`, and the README's sockets paragraph. +- Docs: `doc/concept/socket.md`, its sidebar entry + (`doc/.vitepress/config.ts:120`), and its line in `doc/concept/index.md`. +- Each package's `MIGRATE.md` entries that describe a socket API change + (`rs/moq-ffi`, `rs/moq-tokio`, `js/net`, `py/moq-rs`, `kt/moq`, `cpp/moq`): + nothing published ever had sockets, so the entries go rather than gain a + removal note. Check `origin/release` for each before deleting it. + +What exists only for sockets, to check before deleting: + +- `broadcast::Producer::reserve_unlisted_track` + (`rs/moq-net/src/model/broadcast.rs:406`), `pub(super)`: a track a peer + who knows its name finds, never announced or listed. Sockets are its one + caller. Kixel's copy is built on moq-net's public API and needs exactly + this. Recommended: make it public, with Kixel as its named consumer, + instead of deleting it; the alternative is that Kixel's session tracks + appear in track listings. +- `origin::Consumer::hidden_withheld` and the hold a pre-lite-07 client + session takes on it (`rs/moq-net/src/lite/session.rs:311-315`), which make + a dial fail `Unsupported` while a hop cannot carry hidden broadcasts. + Sockets are its one reader (`socket.rs:442`). Recommended: delete it, + unless Kixel's port names a need. +- Hidden (`.`-named) broadcasts themselves are not socket-only: HLS, the CLI, + and `RouteOptions::hidden()` use them + (`rs/moq-hls/src/server/mod.rs:191`, `doc/concept/identity.md:196`). They + stay. +- `rs/moq-net/src/auth.rs` tests use `.socket` only as a pattern string; + they stay. + +For the PR: + +- Start by grepping for `socket::`, `Socket.Endpoint`, `MoqSocket`, + `moq_socket_`, `dial_track`, `accept_track`, `.server/`, and `.client/` + across `rs`, `js`, `py`, `swift`, `kt`, `dart`, `go`, `cpp`, `demo`, + `test`, and `doc`; the list above is that grep on the base, and both demos + must already be off it. +- Record the PR's parent commit in the PR body: it is the reference Kixel + ports from. +- If [the closed-endpoint flake](/quest/m0/test-flakes-3/py-socket-abort.md) + is still open, delete it here: its test leaves. +- Run `just test interop --all` (moq-ffi changes) and `just api-diff`. + +Public API: breaking for `main`-only API in every language; nothing on +`release` has sockets. Adds `reserve_unlisted_track` if kept. Wire: none +(sockets were a path and track naming convention). + +## Required + +- [MoQ Boy viewers publish their commands again](/quest/m2/sockets/boy.md) - the emulator and its element stop using `moq_net::socket` and `@moq/net`'s `Socket` +- [CARLA drivers publish their controls again](/quest/m2/sockets/carla.md) - the worker stops using the Python wrapper and the player `@moq/net`'s `Socket` + +## Related + +- [moq-net publishes no item without a caller](/quest/m2/unused-api/net.md) - the sweep this keeps `is_endpoint` out of diff --git a/quest/m2/stats-old-names.md b/quest/m2/stats-old-names.md new file mode 100644 index 00000000000..89aaceda6e6 --- /dev/null +++ b/quest/m2/stats-old-names.md @@ -0,0 +1,77 @@ +# [S] Stats frames carry each counter under one name + +## Goal + +A stats frame writes each counter once, under its current name +(`announces_started`, `sessions_ended`, and so on). The eight spellings from +before the May 2026 rename are neither written nor read, in moq-net or in +`@moq/stats`, and `Traffic` and `Presence` derive their serde shapes instead +of hand-writing a second copy of them. The track names, the remaining +fields, and the collection stay as they are. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Drop the old spellings, derive the serializers, and remove the + `@moq/stats` fallback (rejected: keeping them one more release). The + format is documented well enough for others to read, so what the cut + ships is a contract, and nothing can reach the old names any more. + +Not picked, recorded so they are not reopened without new evidence: renaming +`wire_tx` and `wire_rx` to match `sent_bytes` and `received_bytes` (a +downstream reader already names them), and moving the relay's admission +counters (`RefusalKind`, `Refusals`, `Handle::refuse`) out of moq-net. + +Facts found by the audit: + +- `Traffic` writes six counters twice and `Presence` two: + `announces_started` and `announced`, `announces_ended` and + `announced_closed`, `broadcasts_*`, `subscriptions_*` + (`rs/moq-net/src/stats.rs:548-656`), and `sessions_started` and + `sessions`, `sessions_ended` and `sessions_closed` (`:735-825`). Each has + a hand-written `Ser` and `De` twin, with `counter_edge` (`:544`) + preferring the current name on read. About 220 lines. +- `@moq/stats` carries the same fallback as `legacy()` + (`js/stats/src/frame.ts:9-31`, `:74-75`). The package is at 0.0.1 and has + never been published. +- `release` already writes both spellings and prefers the current one + (`git grep -c announces_started origin/release -- rs/moq-net/src/stats.rs` + gives 30), so a reader built from this cut reads a `release` relay + without the shim, and the two newest releases interoperate as relays. +- The track layout changed in the window + ([moq-dev/moq#6428](https://github.com/moq-dev/moq/pull/6428)): `release` + publishes `[/]{publisher,subscriber,sessions}.json[.z]`, and `main` + publishes `totals.json`, `bucket..json`, `presence.json`, and + `prefix.json` and refuses other names. A reader old enough to know only + the old spellings cannot find a track on `main` at all, so the duplicate + fields reach nobody. +- `rs/AGENTS.md` asks for derived wire shapes over hand-written copies. + +For the PR: + +- Delete `TrafficSer`, `TrafficDe`, `PresenceSer`, `PresenceDe`, `Edge`, + and `counter_edge`; derive `Serialize` and `Deserialize` on `Traffic` and + `Presence` with `#[serde(default)]`, so a missing counter still reads as + zero and an unknown one is ignored, as today. +- Delete the tests that pin the old shape (`older shape parses`, + `counter_edge_*`, around `stats.rs:3091` and `:3649-3702`) and keep one + that a frame round-trips and that a frame missing a counter reads zero. +- `@moq/stats`: delete `legacy()` and its two uses; the schemas keep their + zero defaults. +- Check `rs/moq-stats`, `rs/moq-relay` (`/metrics`), and + `doc/concept/stats.md` for an old name; the doc should list each counter + once. +- Before merging, confirm with moq.pro's readers (dashboard and billing) + that none reads an old name. One that does moves in the same deploy; say + so in the PR's Impact section. + +Tests: the round trip above in Rust and JS, and `just test interop` if a +stats frame crosses it. + +Public API: none in Rust (the serde shape of two public types narrows). +Wire: the stats JSON loses eight duplicate fields; nothing is renamed. + +## Related + +- [Wire stats](/quest/m3/wire-stats/README.md) - adds counters to the same frames after the cut diff --git a/quest/m2/str0m-upstream.md b/quest/m2/str0m-upstream.md new file mode 100644 index 00000000000..37927fb7966 --- /dev/null +++ b/quest/m2/str0m-upstream.md @@ -0,0 +1,106 @@ +# [L] moq-webrtc runs on upstream str0m + +## Goal + +moq-webrtc depends on crates.io str0m 0.25 and its DTLS, with rind as the +crypto provider through the published `rind-str0m` and `rind-dimpl` +adapters, and `rs/moq-webrtc/src/vendor/` is gone: about 98,600 vendored +lines and 1.6 MB of packet captures. The WHIP and WHEP gateway behaves as it +does today, an offered data channel is still refused, and `cargo deny` sees +the stack's advisories again. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Return to upstream str0m (rejected: keep the vendored stack and gate + the cut on a browser test, which the audit recommended; keep as is). This + reverses the 2026-10-30 decision to own the stack + ([the WebRTC epic](/quest/m3/webrtc/README.md)). What changed since: none + of the four fixes that motivated vendoring has landed; peer-to-peer and + data channels left on 2026-11-14 + ([moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771)), so the + stack serves one WHIP and WHEP gateway; upstream 0.25 has the pluggable + crypto provider the rind port needed; and nobody merges upstream fixes + into a vendored copy. The vendored modules are private, so the switch + breaks no caller. + +The choice is unverified: nobody has built moq-webrtc against 0.25. So the +PR starts by finding out, and reports before it deletes. + +Facts found by the audit: + +- Vendored size, by `find rs/moq-webrtc/src/vendor -name '*.rs' | xargs wc + -l`: 98,582 lines (str0m 62,368; dimpl 23,998; `is` 8,962; netem 1,467; + `str0m_proto` 1,360; `str0m_rind` 372). Hand-written moq-webrtc is 6,997 + lines. +- The vendored revision is str0m "0.24.1+" at `dc317173` and dimpl 0.9.0 + (`rs/moq-webrtc/src/vendor/mod.rs:14-20`). crates.io has str0m 0.25.0, + dimpl 0.9.0, `rind-str0m` 0.25.2, and `rind-dimpl` 0.9.3 + (`cargo search`, 2026-11-16). +- Six commits touched the vendored tree + (`git log --first-parent -- rs/moq-webrtc/src/vendor`): the vendoring and + trim ([moq-dev/moq#8163](https://github.com/moq-dev/moq/pull/8163)), the + move to rind (#8229, #8248), a doc sweep (#8392, #8608), and the SCTP cut + (#8771). None is one of the four planned fixes; their quests are all open. +- moq-webrtc reaches the stack through `crate::vendor::str0m` in 13 files + outside `vendor/` (`grep -rln 'vendor::str0m' rs/moq-webrtc/src`). +- The workarounds vendoring was meant to remove are still in moq-webrtc and + work against upstream as written: the `b=TIAS` splice + (`rs/moq-webrtc/src/sdp.rs:49`), the early DTLS failure reported as a + timeout ([moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379)), + and eleven `into_std()` clock conversions. + +For the PR: + +1. Build against str0m 0.25 with the two adapters on a branch that keeps + `vendor/` in place, and write down what differs. Check at least: + - rind: the adapters must target the rind the workspace pins. + [rind 0.4](/quest/m0/rind-adapters.md) is about to move that pin, and + its Non-goal says the vendored providers "depend on neither rind-dimpl + nor rind-str0m"; after this quest they do, so land after it or carry + the adapter bump here. + - Data channels: the vendored copy cut SCTP and answers an offered + `m=application` rejected (the test at `rs/moq-webrtc/src/sdp.rs:117`). + Upstream compiles data channels in, so find how 0.25 refuses one (a + feature or a config) and keep that test green. + - DTLS 1.2 only: the vendored dimpl dropped 1.3 and version + auto-selection. Pin 1.2 through configuration, or record that 1.3 is + now offered and that a browser run covered it. + - The typed DTLS timeout: the vendored `dtls.rs` carries dimpl's error + through where upstream flattened it to a string + ([its quest](/quest/m3/webrtc/dtls-timeout.md)). See what 0.25 returns. + - Anything str0m's API renamed between `dc317173` and 0.25.0. +2. If something the gateway needs cannot be had from upstream, stop and + report it on the PR with the evidence, for the maintainer to weigh + against the decision, before deleting anything. +3. Otherwise switch those imports, delete `vendor/` with its `LICENSE-*` + files and the `exclude` in `rs/moq-webrtc/Cargo.toml:15`, and drop the + module's lint allows. Run moq-webrtc's own tests, moq-cli's WHIP and WHEP + tests, and one manual Chrome publish and play, since + [no test drives a browser yet](/quest/m3/whip-whep-browser.md). +4. Leave the quest tree accurate. Delete the quests that exist only for the + vendored copy: [the vendored stack's sync](/quest/m3/vendor-sync/webrtc-stack.md) + (with its paragraph in `quest/m3/vendor-sync/README.md`), + [kio clock time](/quest/m4/webrtc-clock.md), + [the dead-API trim](/quest/m4/webrtc-dead-api.md), and + [the browser-only trim](/quest/m4/webrtc-browser-only.md), and the + vendored-tree line in `quest/m4/test-inventory-followups.md`. The four + fixes become work at moq-webrtc's boundary or upstream reports; their + quests already say so ([DTLS waits for ICE](/quest/m3/webrtc/dtls-after-ice.md), + [the typed DTLS timeout](/quest/m3/webrtc/dtls-timeout.md), + [several bandwidth lines](/quest/m4/webrtc-sdp-bandwidth.md), + [WHEP pacing](/quest/m3/rtc-pacing.md)). + +Docs: `doc/lib/rs` and `rs/moq-webrtc/README.md` where they say the stack +is vendored. + +Public API: none (`mod vendor` is private). Dependencies: str0m, dimpl, +`rind-str0m`, and `rind-dimpl` join the published graph. Wire: none intended +toward browsers; record any change step 1 finds. + +## Related + +- [MoQ builds against rind 0.4](/quest/m0/rind-adapters.md) - moves the rind pin the adapters must match, and edits vendored files this deletes +- [moq-webrtc's server binds at startup](/quest/m2/webrtc-bind.md) - changes the same crate's server +- [The gateways admit a session the same way](/quest/m2/gateway-align.md) - changes the same crate's request types diff --git a/quest/m2/subscriber-min-age.md b/quest/m2/subscriber-min-age.md deleted file mode 100644 index 0c8e61c22b4..00000000000 --- a/quest/m2/subscriber-min-age.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] lite-07 drops Subscriber Min Age - -## Goal - -SUBSCRIBE and SUBSCRIBE_UPDATE carry no `Subscriber Min Age`, relays stop -aggregating and forwarding it, and `Delay::min` stays a local setting. - -## Plan - -Found 2026-11-14 by the [feature review](/quest/m3/release/feature-review.md). -`Delay::min` (`rs/moq-net/src/model/subscription.rs`) is "the `Subscriber Min -Age` on the moq-lite-07 wire", and its own doc says "A publisher may use it, -such as to start a cold join that far back; nothing reads it there yet". It -is still encoded in Rust and JS, aggregated across subscribers in a -`BTreeMap` in `demand.rs`, and forwarded upstream by every relay. - -A field frozen with no reader costs every relay an -aggregate and a forward, and a later wire version can add it with its reader. - -Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) drop the wire field and its aggregate; `Delay::min` stays a local setting (rejected: (b) plan the publisher's cold-join reader). - -Public API: none if `Delay::min` stays local. Wire: lite-07-wip SUBSCRIBE and -SUBSCRIBE_UPDATE lose the field. - diff --git a/quest/m2/time-addressing/bindings.md b/quest/m2/time-addressing/bindings.md index 5163fac0ad2..6c99ce4ba50 100644 --- a/quest/m2/time-addressing/bindings.md +++ b/quest/m2/time-addressing/bindings.md @@ -28,4 +28,24 @@ way in moq-ffi, `moq-c`, and every binding, mirroring Rust's `group::Info`. It stays in m2 because the rename is breaking and the cut would otherwise publish a `sequence` that holds a start. +Found 2026-11-16 (/quest-plan of the pre-cut audit): that inventory is +short. The producer side says `sequence` too, in +`rs/moq-ffi/src/producer.rs`: `MoqFill::accept`, `is_wanted`, and `unwanted` +take `sequence` (`:582-601`); `MoqTrackProducer::create_group(sequence)` +(`:859`) already passes it as `group::Info { start }`; +`finish_at(final_sequence)` (`:950`); `MoqGroupProducer::sequence()` +(`:1002`, filled from `group.start` at `:993`); and `MoqPosition.group`'s +doc calls it "The group sequence" (`:17`). The hand-written C API has +`moq_group_request_sequence` (`rs/moq-c/src/api.rs:4035`) and +`moq_publish_group_sequence` (`:4154`). Rename all of them in the same PR, +then grep every wrapper and `doc/lib` page for `sequence` once more: a name +left behind is a second breaking release. + +Decided 2026-11-16 (maintainer, same run): the hand-written C API ships as +`libmoq` ([its name](/quest/m2/libmoq-name.md)), so where this quest says +`moq-c` it means that crate, whichever name it carries when this lands. The +JS half renames a frame's `sequence` to `index` +([JS](/quest/m2/time-addressing/js.md)); a frame's position in the bindings +takes the same name if any binding exposes one. + Public API: breaking in every binding. Wire: none. diff --git a/quest/m2/time-addressing/consumers.md b/quest/m2/time-addressing/consumers.md new file mode 100644 index 00000000000..3634505149a --- /dev/null +++ b/quest/m2/time-addressing/consumers.md @@ -0,0 +1,145 @@ +# [L] Media readers take declared ends from the group, and hang writes no markers + +## Goal + +A hang reader learns where a group, its last frame, and a declared stop end +from the group's own end: lite-07's GROUP_END carries the exclusive end +timestamp, and the Rust and JS container consumers turn it into the frame +end and `Read::End` that a marker produces today. hang then stops writing +the empty duration frames and discontinuity marker groups, and the hang +draft specifies neither, so moq-hang-04 never asks a publisher for them. +Every first-party consumer that numbered groups works by start timestamp, +in Rust and JS, and the HLS/DASH export places each group on the declared +join interval grid by its start. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ The whole change lands before the cut, readers and publishers both + (rejected: only the reader half in m2, with the markers dropped in m3; + keeping the 2026-11-14 plan and recording that 0.22 readers degrade). + This reverses the 2026-11-14 move to m3, which rested on "what remains + breaks nothing". The maintainer's reason: the point of GROUP_END was to + carry the duration as a timestamp, and it does, so the markers have no + job left. + +What the audit found against "readers already tolerate their absence": + +- The Rust reader produces `Read::End` only from a marker: + `rs/moq-mux/src/container/consumer.rs` pops a marker into + `Event::FrameEnd { end, opens }`, and `opens: true` becomes `Item::End` + and then `Read::End`. The lite-07 group end is read in the same file and + feeds only `presented_end`; it never becomes a `Read::End` or a + per-frame end. JS is the same (`js/hang/src/container/consumer.ts`, + `this.#format.end?.(sample)` and the `kind: "end"` emit). +- The producer writes both today: `rs/moq-mux/src/container/producer.rs` + ends a group through `finish_group` (the marker) and the group's + declared end, and `discontinuity()` writes marker groups. +- `Read::End` is matched in more than 20 Rust files outside the consumer + (moq-audio decode, moq-c, moq-ffi, moq-gst, moq-cli play, moq-video) and + in `js/watch`'s audio and video decoders. It is how a player learns of a + declared stop: push to talk, declared silence, a drained encoder. +- So if the markers went after the cut, a published 0.22 reader against a + newer publisher would stop reporting declared ends and lose the last + frame's duration, and `Producer::discontinuity`, `Container::end`, and + `Container::finish_group` would change meaning one release after they + shipped. After the cut, 0.22 is the old player. + +For the PR, in this order: + +1. Settle what a reader can know without a marker group, first, with the + maintainer if the answer costs API. A marker group tells a reader of a + declared pause at once; a group's end alone does not distinguish "the + publisher paused here" from "the next group follows", until the next + group starts above that end or fails to arrive. Recommended: `Read::End` + reports every group's declared end as it is read, a player treats media + as ended at that time until a group starts, and a next group starting + at the end is plain continuity. That gives a push-to-talk player the + stop when the group ends, which is when the marker told it. +2. Readers: the Rust and JS container consumers derive the last frame's + end, the group's end, and `Read::End` from the group's declared end and + the next group's start. Add the test the audit asked for: a group that + carries only a declared end, and no marker, yields the same reads as + one with a marker. +3. Publishers: `container::Producer` stops writing the duration marker + (`cut`, `close`, `finish_group`) and `discontinuity()` stops writing a + marker group; it ends the open group at its declared end and the next + group starts later. Remove or repurpose `Container::end` and + `Container::finish_group`, and say in the PR what `discontinuity()` + means now, or delete it if a declared end says it all. `js/publish` + follows. Check audio's terminal-trim marker before deleting it: the + draft has an empty payload give the source's exclusive end ahead of the + codec's drain packets, so a decoder discards samples past it. A group + end below its last packet's extent says the same; prove it with the + Opus drain test, or keep that one marker and say why. +4. Readers stop accepting markers only if that deletes real code and no + supported peer still sends them: a lite-05 or lite-06 session has no + GROUP_END, so legacy ingest from an old publisher still carries + markers. Keep reading them there; the 2026-10-25 rule below covers the + other direction. +5. The hang draft's Container section: delete the duration and + discontinuity marker rules, including the data-track marker + ([moq-dev/moq#5815](https://github.com/moq-dev/moq/pull/5815)), and say + that a group's end is the transport's. + +Decided 2026-10-25 (maintainer), from the spike: + +- GROUP_END replaces hang's empty-frame duration marker + (`rs/moq-mux/src/container/producer.rs`, `cut` and `close`), so moq-mux + stops writing empty frames. +- Discontinuity marker groups go away (`producer.rs`, `discontinuity`): a gap is a + previous end below the next start, and a missing group is a + previous-start link that doesn't match. +- Legacy egress synthesizes neither: a player on lite-05 or lite-06 loses + end durations and pause markers. That is the best-effort service old + versions get; it no longer describes a 0.22 reader, which reads the + group's end. + +Decided 2026-11-02 (maintainer): removing the HLS records, the per-rendition +`hls` field, and A/V segment alignment moved to m0 as the HLS grid, +landed in [moq-dev/moq#7652](https://github.com/moq-dev/moq/pull/7652), which also added +`media.join.interval`, moved `clock` to `media.clock` (both renamed by +[the sync section](/quest/m2/hang04/sync.md)), and settled the +segmentation rules decided here on 2026-10-27/28. It places groups by their +first frame's pts; this quest swaps that for the group start, without +changing the segment numbers. + +Convert each consumer that numbers groups: hang and moq-mux timelines, +HLS/DASH export, `seek` for GOP-aligned failover in moq-mux, HLS import's +discontinuity packing, transcode's 1:1 numbering, archive keys and resume, +relay and CLI `fetch --group`, and player continuity checks in the Rust and +JS container consumers and `js/watch`. Update the hang draft and the docs +each one makes stale. Rename no CLI flag. +[The model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) +([moq-dev/moq#8638](https://github.com/moq-dev/moq/pull/8638)) already +converted the Rust consumers whose API named group numbers: `moq fetch +--group` and the relay's `/fetch?group=` keep their names and take a start, +moq-mux `seek` and reads carry starts, and moq-hls, moq-archive, and +moq-transcode key by start. `@moq/hang`'s `Read.group` keeps its name and +carries whatever `@moq/net` keys by. + +Tests: the marker tests in `rs/moq-mux/src/container/producer.rs` +(`discontinuity_publishes_an_empty_group` and its neighbours) become tests +of declared ends; a push-to-talk stop reaches a Rust and a JS reader as an +end with no marker on the wire; a lite-06 session still reads an old +publisher's markers. Run `just test interop --all`. + +Public API: breaking. Rust `moq_mux::container`: `Producer::discontinuity`, +`Container::end`, and `Container::finish_group` change or go, and +`Read::End` is reported from a group's declared end; `@moq/hang`'s container +consumer and producer mirror it. Wire: hang drops empty duration frames and +discontinuity marker groups on lite-07; the hang-04 draft never specifies +them. + +## Required + +- [@moq/net by start](/quest/m2/time-addressing/js.md) - the JS API these consume +- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - GROUP_END carries the end the duration marker did + +## Related + +- [Writing a group needs no invented start, and its end has one word](/quest/m2/group-api.md) - names the call that declares a group's end +- [The catalog's clock and join interval live under a sync section](/quest/m2/hang04/sync.md) - renames the interval the HLS grid reads +- [The archive format ships as version 2](/quest/m2/archive-v2.md) - freezes the keys this made starts +- [A group's frames present before the next group starts](/quest/m3/groups-never-overlap.md) - tightens the group rule a declared end relies on diff --git a/quest/m2/time-addressing/js.md b/quest/m2/time-addressing/js.md index c83855b7d4d..6a60cc8dcf6 100644 --- a/quest/m2/time-addressing/js.md +++ b/quest/m2/time-addressing/js.md @@ -29,6 +29,23 @@ Lite-07 FETCH is single-group only ([moq-dev/moq#8616](https://github.com/moq-de which moves JS multi-group fills (`js/net/src/lite/subscriber.ts` `#runFills`) onto the subscription this rekeys. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ a +frame's position in its group is its `index`, renamed in this PR (rejected: +a later rename; keeping `sequence`). Once groups are keyed by `start`, +`sequence` would survive in JS meaning only a frame index, while Rust says +`group::Consumer::index()`, `skip_to(index)`, and `start_at(index)` +(`rs/moq-net/src/model/group.rs:4203`, `:4243`, `:1757`), and JS's own +`Track.Position.frame` and `js/net/INTEGERS.md` already say index. Renamed: +`Frame.Consumer.sequence` (`js/net/src/frame.ts:251`), and +`Group.Consumer.readFrameSequence` and `tryReadFrameSequence` +(`js/net/src/group.ts:1406`, `:1363`), whose result field is `sequence`. +Callers outside `js/net/src`: `js/crypto/src/e2ee/group.ts` (2) and two +benches. ✅ In the same PR, `Time.keyOf` becomes a getter on `Timestamp` +(rejected: keeping the free function). It is an `export let` assigned from +inside the class (`js/net/src/time.ts:53`, `:128`) with one caller, +`js/json/src/time.ts:11` and `:23`; the split between `value` and the exact +key stays as decided 2026-11-08. + Public API: breaking, mirroring Rust's. Wire: as the lite-07 quest. ## Required diff --git a/quest/m2/time-addressing/lite07.md b/quest/m2/time-addressing/lite07.md index ad5417b1b2b..0f03820d24d 100644 --- a/quest/m2/time-addressing/lite07.md +++ b/quest/m2/time-addressing/lite07.md @@ -1,4 +1,4 @@ -# [M] The lite-07 wire addresses groups by start +# [L] The lite-07 wire addresses groups by start ## Goal @@ -7,6 +7,11 @@ its predecessor's start, GROUP_END says where a whole group ends, and every subscription bound and drop is a time. Datagrams keep a sequence of their own on their own track kind. Rust speaks it, the lite draft specifies it, and lite-01..06 are unchanged. +The same rewrite carries the smaller lite-07 fixes the pre-cut audit decided +on 2026-11-16, listed in the Plan: an encoding for "no limit" in +`Subscriber Max Age`, GROUP without `Frame Start`, no Padding stream or +datagram, and a track listing that says each track's kind. + ## Plan Decided 2026-10-25 (maintainer), from the spike: @@ -70,20 +75,119 @@ in [moq-dev/moq#7670](https://github.com/moq-dev/moq/pull/7670), then [moq-dev/moq#8546](https://github.com/moq-dev/moq/pull/8546), [moq-dev/moq#8551](https://github.com/moq-dev/moq/pull/8551), and [moq-dev/moq#8584](https://github.com/moq-dev/moq/pull/8584), and still has -an open model finding (`StreamWins.cfg`, owned by -[finished across updates](/quest/m3/lite-finished-across-updates.md)). The -case it serves is a relay reader whose budget widens after the upstream +an open model finding (`StreamWins.cfg`, which the finished-across-updates +quest owned until it was deleted on 2026-11-16: its premise was this +reopen). The case it serves is a relay reader whose budget widens after the upstream dropped a group as OLD. Since this quest rewrites SUBSCRIBE_DROP, SUBSCRIBE_UPDATE, and SUBSCRIBE_SKIP anyway, it can make OLD final on its subscription: the widening reader asks with a SUBSCRIBE of its own, as the draft already requires for delivered or finally dropped groups, and the -`Update` numbers, re-offers, reopen rules, and their model configs go, while -YIELDED continuations keep their hold. Also check whether GROUP's -previous-start link makes SUBSCRIBE_SKIP redundant. +`Update` numbers, re-offers, reopen rules, and their model configs go. Also +check whether GROUP's previous-start link makes SUBSCRIBE_SKIP redundant. +The review wrote that YIELDED continuations would keep their hold; on +2026-11-16 they left lite-07 too ([YIELDED deferred](/quest/m2/yield-defer.md)), +so after both PRs a group has a second stream on one subscription only as +a duplicate, and no "held unread until the earlier stream ends" rule +remains for this rewrite to preserve. + +Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) OLD drops are final on their subscription: this rewrite deletes `Update`, the reopen and re-offer paths, and their model configs (rejected: (b) keep reopening and finish the finished-across-updates quest, deleted 2026-11-16). + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit). These +ride this PR because it already rewrites the messages they touch, and each +is free only until lite-07 freezes: + +- ✅ SUBSCRIBE and SUBSCRIBE_UPDATE encode `Subscriber Max Age` as + milliseconds plus one, 0 meaning no limit (rejected: write 2^53 - 1 into + the draft as "no limit"; leave it). FETCH's field of the same name and + TRACK_INFO's `Publisher Max Age` already do. Today Rust sends + `MAX_SAFE_DELAY_MS = 2^53 - 1` for `Delay::max == None` + (`rs/moq-net/src/lite/publisher.rs:119`, `lite/subscriber.rs:12354`) and + JS sends `NO_MAX_DELAY = Varint.MAX_U53` and reads it back by comparison + (`js/net/src/internal.ts:41`, `js/net/src/fill.ts:626`). The draft never + names that value, and a third implementation that picks a larger + "forever" is refused by JS's 53-bit read. Both constants go on lite-07. +- ✅ GROUP loses `Frame Start` (rejected: keep it and state the one case + that sets it). A subscription delivers whole groups, FETCH has no GROUP + header, and the last case that set it, a continuation, leaves with + [YIELDED](/quest/m2/yield-defer.md). The Rust publisher says "A lite-07 + range covers whole groups, so it has none", and JS sets `frameStart` only + from a lite-06 SUBSCRIBE's bound. Before deleting it, grep both + publishers for a lite-07 path that opens a Group Stream past frame 0; if + yield-defer has not landed, the continuation is one, and the field goes + with whichever PR lands second. lite-06 keeps its field. +- ✅ The Padding Stream (0x2) and Padding Datagram (0x1) types are removed; + the datagram `Type` stays (rejected: keep the datagram one, as the + 2026-10-30 decision preferred; keep both). Both are received and + discarded, nothing sends either outside a test and a benchmark, and their + one planned sender is parked with no named consumer + ([probe padding](/quest/m5/probe-padding.md), which would add its type + back in a later version or an extension). An unknown + stream type is reset and an unknown datagram type discarded, so adding + either back later touches no message a lite-07 peer parses. +- ✅ The track listing carries each track's kind, so a datagram track can be + listed (rejected: datagram tracks move to an extension draft; listings + never show them). Datagram tracks stay in core with everything they have + today, including the lite-05/06 group-datagram bridge and the bindings: a + named consumer wants them. Today "TRACK_INFO does not say which kind a + Track is", so `a_datagram_track_is_never_listed` + (`rs/moq-net/src/model/listing.rs`). Recommended shape: TRACKS_ADD gains a + `Kind` before its info, which is then a TRACK_INFO or a DATAGRAMS_INFO; + the model's listing entry, `@moq/net`, and the bindings' listing report + the kind, which is additive there. + +- ✅ SUBSCRIBE_DROP names a span and carries no group count (rejected: a + count, which would also have let SUBSCRIBE_SKIP become a drop with a + count of 0). Today's `Group Count` is a count of keys, so it becomes the + span's end. [Group drops](/quest/m2/group-drops.md) reports the span. -Decided 2026-11-14 (maintainer, pick on [moq-dev/moq#8764](https://github.com/moq-dev/moq/pull/8764)): ✅ (a) OLD drops are final on their subscription: this rewrite deletes `Update`, the reopen and re-offer paths, and their model configs (rejected: (b) keep reopening and finish [finished across updates](/quest/m3/lite-finished-across-updates.md)). +Recommendations for the same PR, not decided: + +- GROUP_END takes the value FRAME reserves, a `Payload Length` of 0, + followed by the end timestamp. [Takeover](/quest/m3/group-takeover.md) + planned a marker with the same name and the same reserved value that + pauses a group instead; it now designs its own marker in lite-08. +- Anchor types 1 (Absolute) and 3 (Time) are aliases once a group's key is + its start: the publisher maps both to `Anchor::Time`, and the model + already has only `Oldest`, `Relative`, and `Time`. Keep one type with one + end rule (today type 1's end is exclusive and type 3's inclusive), and + read it with the full 2^61 width in JS, which decodes a Time anchor with + `u53()` today. +- GROUP's previous start is optional: encode it plus one with 0 for none, + as the draft's other optional integers are. +- SUBSCRIBE_SKIP stays for spans a subscriber can't infer, such as the tail + of a bounded Range where starts are sparse, and GROUP's previous-start + link carries the gap between two delivered groups, so the Subscribe + Stream no longer carries one SKIP per group (`append_group` skips the + keys between appends, and lite-07 forwards each today). With no count + on a drop, a skip and a drop stay two messages. +- Delete the draft's binding 5 (Qmux over RTCDataChannel): its table row, + its two paragraphs, its changelog line, and the DTLS clause in Security + Considerations. [moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771) + removed the implementation with peer-to-peer. +- At the rename to `moq-lite-07`, delete what describes earlier versions' + encodings in the body and in the lite-07 changelog, which itself says + "Removed rules for mapping onto earlier versions": the changelog lines + about what moq-lite-05 and moq-lite-06 do with a `Timescale` of 0 and + with SUBSCRIBE_DROP bounds. The 2^61 timestamp bound stays, and its + "so every version can carry it" is its only reason. + +Kept as they are, so this rewrite leaves them alone: every lite version +from 01 to 06 keeps negotiating with today's behaviour, and a path segment +starting with `.` still hides a claim, with no typed flag (both decided +2026-11-16; AGENTS.md records the dot as the exception to its +reserved-prefix rule). Not reopened by the audit: AUTH_ERROR's retry codes +(the 2026-11-14 pick stands), and AUTH_OK's rate fields, which wait for +lite-08 with [the rate grant](/quest/m5/rate-grant.md). Public API: none beyond [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md). -Wire: lite-07-wip GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, -SUBSCRIBE_OK, SUBSCRIBE_STARTED, SUBSCRIBE_FINISH, SUBSCRIBE_SKIP, and -SUBSCRIBE_DROP change. +`@moq/net` and the bindings' track listing gain a kind. Wire: lite-07-wip +GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, SUBSCRIBE_OK, +SUBSCRIBE_STARTED, SUBSCRIBE_FINISH, SUBSCRIBE_SKIP, SUBSCRIBE_DROP, and +TRACKS_ADD change, and the Padding stream and datagram types go. + +## Related + +- [YIELDED deferred](/quest/m2/yield-defer.md) - removes continuations, the last use of GROUP's `Frame Start` +- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - reads the spans SUBSCRIBE_DROP names +- [Refresh a track](/quest/m2/refresh-interval.md) - raises the `Wanted Group` this turns into a start time +- [A cold join reaches back](/quest/m2/min-age-join.md) - gives SUBSCRIBE's `Subscriber Min Age` its reader diff --git a/quest/m2/transport-names.md b/quest/m2/transport-names.md new file mode 100644 index 00000000000..a3c7cb56c89 --- /dev/null +++ b/quest/m2/transport-names.md @@ -0,0 +1,87 @@ +# [S] A TLS stream link reports tls, and @moq/qmux has one stream limit + +## Goal + +A session over `tls://` reports its transport as `tls`, in +`moq_tokio::Transport`, in `moq_auth::Transport`, in the auth request an +endpoint receives, and in the bindings, so an auth server, a log line, and +the relay's own checks can tell an encrypted stream link from plaintext +`tcp://`. `@moq/qmux` takes one `maxStreams`, applied to each direction, as +Rust's `Limits::max_streams` and `@moq/net`'s `websocket.maxStreams` already +do. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Add `Tls` to both `Transport` enums and report it for `tls://` + (rejected: only fixing the moq-tokio doc that says "plaintext"). Both + enums are non-exhaustive, so the variant is additive in Rust, but + changing what an existing link reports moves every policy and metric + keyed on `"tcp"`. That is cheapest before the name is announced. +- ✅ `@moq/qmux` takes a single `maxStreams` (rejected: also nesting its + windows under `limits` to mirror Rust; keeping the bidirectional and + unidirectional pair). +- LAN discovery stays in moq-tokio: the audit proposed moving + `moq_tokio::mdns` into moq-relay, and the maintainer did not take it. + Don't reopen it without a new reason, such as a measured build cost. + +Facts found by the audit: + +- `moq_tokio::Transport::Tcp` is documented "A plaintext TCP connection + using qmux framing" (`rs/moq-tokio/src/transport.rs:11-12`), yet a + `tls://` dial returns it (`rs/moq-tokio/src/client.rs:496-506`) and the + accept side reports it for every stream link + (`rs/moq-tokio/src/server.rs:1298`). `moq_auth::Transport::Tcp` says + "plaintext or TLS" (`rs/moq-auth/src/request.rs:186-187`). +- The relay maps one enum onto the other (`rs/moq-relay/src/auth.rs:1288`), + so an auth endpoint sees `"tcp"` for an mTLS cluster link unless a client + certificate happens to be attached. `moq`'s `is_public_transport` + (`rs/moq-cli/src/main.rs:226-231`) treats `Tcp` as always public. +- The strings are a contract: `Transport::as_str` + (`rs/moq-tokio/src/transport.rs:22-33`), the serde names in moq-auth + (`rs/moq-auth/src/request.rs:212`), `js/auth/src/contract.ts:35`, and + `MoqTransport` in moq-ffi (`rs/moq-ffi/src/server.rs:449`). +- `@moq/qmux`'s `Config` has `maxStreamsBidi` and `maxStreamsUni` + (`js/qmux/src/session.ts:33-35`, `js/qmux/api/index.api.md:19-20`). Its + one consumer sets both from one number + (`js/net/src/connection/connect.ts:549-560`), and Rust has one + `Limits::max_streams` (`rs/moq-quic/src/limits.rs:21`). + The package moves into this repository at this cut, so the rename rides + a break it already has. +- `ws://` and `wss://` share `WebSocket` in the same way. Not picked: a + WebSocket's TLS belongs to the HTTP server in front of it, which the relay + often cannot see. + +For the PR: + +- Add `Tls`, spelled `"tls"`, to `moq_tokio::Transport` and + `moq_auth::Transport`. Report it from the `tls://` dial and from the TLS + branch of the stream acceptor. Fix the `Tcp` docs to say plaintext in both + crates. Extend the relay's mapping and `is_public_transport` (a TLS link + is public the same way plaintext TCP is; say so in its doc). +- Mirror it in `@moq/auth`'s contract enum and in `MoqTransport` with every + wrapper. If [open-set selectors](/quest/m2/ffi-open-selectors.md) has + landed, `MoqTransport` is already an object and this adds a constructor. +- Grep for consumers of the `"tcp"` string: relay metrics labels + (`rs/moq-relay/src/internal.rs` uses `"tcp"` for the listener, which + stays, since the listener is one TCP port), stats labels, `doc/bin/relay`, + and `doc/concept/transport.md`. The auth docs get a line: a server keying + policy on `transport == "tcp"` for cluster links over TLS now sees `"tls"`. +- `@moq/qmux`: one `maxStreams?: bigint` on `Config` and its default; delete + the pair; `@moq/net` passes it once. Update `js/qmux/api/index.api.md`, + the README, and the migration note. +- Tests: a `tls://` session reports `tls` on both ends and in the auth + request; a `tcp://` session still reports `tcp`; `@moq/qmux` advertises + the one limit for both directions. + +Public API: additive in Rust (`Transport::Tls` on two non-exhaustive +enums) and a new binding selector; breaking for `@moq/qmux` +(`maxStreamsBidi` and `maxStreamsUni` become `maxStreams`). Behaviour: the +transport string for `tls://` changes from `tcp` to `tls` in auth requests +and logs. Wire: none. + +## Related + +- [Open-set selectors in the bindings](/quest/m2/ffi-open-selectors.md) - makes `MoqTransport` able to grow without a break +- [The unused transport API](/quest/m2/unused-api/transport.md) - removes `Transport::WebRtc` from the same enum diff --git a/quest/m2/ts-typed-outcomes.md b/quest/m2/ts-typed-outcomes.md new file mode 100644 index 00000000000..50a345d8f32 --- /dev/null +++ b/quest/m2/ts-typed-outcomes.md @@ -0,0 +1,78 @@ +# [M] TS import reports typed outcomes, and no caller downcasts an error + +## Goal + +`moq_mux::container::ts` reports what happened through types. Its public +functions return a `ts::Error` enum, not `anyhow`; a source switch comes +back as a value (`Restart`), not as an error that carries the unread +input; a stream with several programs is a variant a caller matches on. +`moq_mux::Error::Other` is gone. The callers, moq-cli (`import ts`, +`import srt`, and `import rtsp`) and moq-srt, read the typed result and +contain no `downcast_ref` or `is::()` on an error. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Typed TS outcomes: a `ts::Error` enum, restart as a value, + `Error::Other` dropped, and the CLI stops downcasting, rtsp included + (rejected: keep `anyhow` inside and expose only the two outcomes as + typed values; keep as is). AGENTS.md: "Never match on errors; it's + brittle", and `rs/AGENTS.md` asks libraries for `thiserror`. + +Facts found by the audit: + +- `rs/moq-mux/src/container/ts/import.rs`: `pub fn decode(&mut self, data: + &[u8]) -> anyhow::Result<()>`, with `seek` and `finish` the same. The + internal `decode_or_restart` beside it already returns + `anyhow::Result>`, the shape the public one should have. + `programs.rs` (`decode`, `finish`) and `republish.rs` (`decode`, + `finish`) return `anyhow` too. +- `MultipleProgramsError` (`import.rs`) is a second outcome sent as an + error, and `moq_mux::Error::Other(Arc)` + (`rs/moq-mux/src/error.rs`) exists to carry it; 8 sites in + `rs/moq-mux/src` build or name `Other`. +- Callers that match on the error: + `rs/moq-cli/src/publish.rs` (`err.is::()`), + `rs/moq-cli/src/srt.rs` (the same through two error layers), + `rs/moq-srt/src/ts.rs` (`downcast_ref::()`), + and `rs/moq-cli/src/rtsp.rs` (`downcast_ref::()`). +- [moq-dev/moq#8831](https://github.com/moq-dev/moq/pull/8831) moved the + `Restart` handling into one `ts::Republish` but left the signatures. + +For the PR: + +- `ts::Error` is a `thiserror` enum, `#[non_exhaustive]`, with a variant + for several programs that carries what the caller prints today, and + variants for the failures the callers or tests tell apart. Do not + enumerate every internal `anyhow!`: a damaged packet that the importer + already counts and survives is not an error, and what remains groups + into a handful of causes. It converts into `moq_mux::Error` by a typed + variant, which is what lets `Other` go. +- `Import::decode` returns `Result, ts::Error>`; + `Programs` and `Republish` return the same error. Internal helpers may + keep `anyhow` only if the boundary maps every case; prefer converting + them, since 18 public `ts` functions name `anyhow::Result` today. +- moq-rtsp: give the CLI what it downcasts for as a typed result from the + call it makes, so `rs/moq-cli/src/rtsp.rs` matches a `moq_rtsp::Error` + it was handed, not one it dug out of an `anyhow` chain. +- Out of scope: `rs/moq-cli/src/play/media.rs` downcasts the CLI's own + private `Unplayable`, and `rs/moq-srt/src/dial.rs` reads a libsrt + rejection from an `io::Error`; neither crosses a library API of ours. +- [moq-dev/moq#8830](https://github.com/moq-dev/moq/pull/8830) is open on + the TS export; it does not touch these signatures. + +Tests: the existing TS import tests assert on variants where they assert +on message text today; a multi-program input returns the variant from +`decode`; a source switch returns `Some(Restart)` and the importer keeps +decoding the next source. + +Public API: breaking for Rust: the return types of `ts::Import`, +`ts::Programs`, and `ts::Republish`; `ts::MultipleProgramsError` becomes a +variant; `moq_mux::Error::Other` is removed. Wire: none. CLI: messages may +change wording, exit codes do not. + +## Related + +- [A multi-program TS import survives a source switch](/quest/m5/ts-multi-program-restart.md) - deferred; would add a restart value to `Programs` +- [Finishing an importer or the video producer returns a Finished handle](/quest/m2/finish-sweep.md) - the other change to importer signatures diff --git a/quest/m2/ui-private.md b/quest/m2/ui-private.md new file mode 100644 index 00000000000..f33a7cc79db --- /dev/null +++ b/quest/m2/ui-private.md @@ -0,0 +1,79 @@ +# [M] @moq/ui is a workspace package, bundled into watch and publish + +## Goal + +`@moq/ui` is `private: true` and never reaches npm. `@moq/watch` and +`@moq/publish` bundle its code and its types, so their published packages +import nothing from it and no cross-package contract hides behind +`@internal`. `@moq/video` exports nothing marked `@internal` to another +package either. The npm name is not claimed, and the docs, the API reports, +and the release list drop it. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Workspace-private and bundled (rejected: keeping it published with the + helpers as a typed public API under `just api-diff`; keeping it as is with + watch and publish pinned to its exact version). The package exists to + share code between two packages, which is a build concern, and its name + promises a player UI it does not hold. + +Facts found by the audit, re-checked at `80ca9787e3`: + +- Its public API is one abstract class, `Support`, and four types + (`js/ui/src/index.ts:18`). What watch and publish take at runtime is + `controlButton`, `fullscreenButton`, `settingsButton`, `icon`, `graph`, + `statCard`, `statLine`, and four formatters, all tagged `@internal` + (`js/ui/src/index.ts:10-17`), from 17 import sites (10 in `js/watch`, 7 + in `js/publish`). +- `stripInternal` removes those from the published types, but the published + watch and publish keep every `@moq/*` import external + (`js/watch/vite.config.ts:25`, `js/publish/vite.config.ts:23`) and depend + on `^` of the workspace version (`js/common/package.ts:85`). So changing + an `@internal` helper in a patch breaks an installed watch or publish: + the contract is real, untyped, and outside the API reports. +- `Support`, `Report`, and `Show` are part of watch's and publish's own + public types (`js/publish/api/support-element.api.md:4-7`, + `js/watch/src/support/element.ts:9-12`), so bundling must inline the + types, not only the code. +- `@moq/video` does the same thing once: `rotateVideoDimensions` is + `@internal` (`js/video/src/index.ts:26-27`) and imported by + `js/watch/src/video/decoder.ts:18`, `js/publish/src/broadcast.ts:7`, and + `js/publish/src/preview.ts:99`. +- Nothing is published under the name: `@moq/ui` returned 404 on + 2026-11-12 ([first publish](/quest/m3/release/npm-first-publish.md)). + `js/crypto` is already `private: true`. +- The package is 783 lines of source and CSS, so a page loading both + overlays carries that much twice. + +For the PR: + +- Set `private: true`, drop the `release` script, and remove `@moq/ui` + from each vite `external` rule and from the dependencies `package.ts` + rewrites, so the build fails if a published package still imports it. + `just js check` already rejects an undeclared `@moq/*` import; make it + reject a published package depending on a private one. +- Bundle the types: the support elements' declarations must resolve + without `@moq/ui` installed. The `test-dts` checks in `js/publish` are + where to prove it, with one for `js/watch`. +- `stats.css` (`js/ui/package.json` exports `./stats.css`) is bundled the + same way. +- For `@moq/video`, recommended: export `rotateVideoDimensions` as public + API, since it is a five-line pure helper (alternative: inline it in the + two callers). +- Drop the name from `doc/lib/js/index.md`, `doc/setup/upgrade.md`, + `doc/.vitepress/api/package.json`, and `js/ui/api/`. Delete + `js/ui/MIGRATE.md`; the README says what the package is for inside the + workspace. +- Measure `@moq/watch/element` and `@moq/publish/element` first-load size + before and after with `sh/size/bundles.ts` and put both in the PR. + +Public API: `@moq/ui` is never published; `@moq/watch` and `@moq/publish` +keep the same exported names, now declared in their own types. `@moq/video` +gains one export. Wire: none. + +## Related + +- [Claim the new @moq npm names](/quest/m3/release/npm-first-publish.md) - no longer claims `@moq/ui` +- [Browser package names](/quest/m2/browser-packages.md) - the other browser package changes before the cut diff --git a/quest/m2/unused-api/README.md b/quest/m2/unused-api/README.md new file mode 100644 index 00000000000..5e66951e21b --- /dev/null +++ b/quest/m2/unused-api/README.md @@ -0,0 +1,43 @@ +# The cut publishes no API without a caller + +## Goal + +Every public item the 0.22 cut would publish for the first time has a caller +outside its own crate or package and its tests, or it is private, hidden, or +gone before the cut. The sweep runs once per area, one child each, and has +no work of its own: it completes when every child merges. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ remove +or hide every unused public item the audit found, one sweep quest per area +(rejected: keeping them as harmless; one sweep across the whole tree). An +unused item costs nothing to delete now, and costs a breaking release once +0.22 has published it. A feature returns as additive work when a consumer +needs it. + +The maintainer's condition applies to every child: before removing an item, +check Kixel and moq.pro for a caller, and keep what one uses. Both pin a +`main` commit and call API that nothing in this repository does. Each child +lists its items with the grep that found no caller here, so its PR re-runs +the grep on its own head and adds the downstream check. + +Removal is the default. Hide an item (`pub(crate)`, `#[doc(hidden)]`, +`@internal`, a `test-support` or `lab` feature) only when code in this +repository still needs it across a crate or package boundary. + +The same rule now covers the bindings (AGENTS.md, 2026-11-16): a feature +reaches them when a binding user needs it, so the sweep mirrors nothing new +into moq-ffi. + +Not part of the sweep, because each has its own quest: socket endpoints +([removed for Kixel](/quest/m2/sockets/README.md)), `setup::Extensions` +([the ietf extension](/quest/m2/ietf-records-per-track.md)), the public +route API ([the route switch](/quest/m2/multicast/switch.md)), and the +bindings' selectors ([open selectors](/quest/m2/ffi-open-selectors.md)). + +Public API: each child lists what leaves. Wire: none. + +## Related + +- [API shape review](/quest/m3/release/api-review.md) - the recurring review that should have caught these; its Plan records what this run learned diff --git a/quest/m2/unused-api/js.md b/quest/m2/unused-api/js.md new file mode 100644 index 00000000000..ce0c6613ffa --- /dev/null +++ b/quest/m2/unused-api/js.md @@ -0,0 +1,105 @@ +# [S] @moq/net exports only what something outside it uses + +## Goal + +`@moq/net` publishes no export that nothing outside the package calls, and +none under a name that hides what it is. The `@moq/net/zod` subpath and the +`zod` peer dependency are gone; the wire-internal `Varint` and `Path` +helpers, `Track.Subscriber.tryRecvGroup`, and `Track.Request` are internal; +`rescale` and `rescaleIn` are reached through `Track`; and +`Broadcast.Consumer`'s subclass hooks are `@internal`. An export Kixel or +moq.pro calls stays. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Remove or hide every public item with no consumer, in one sweep per + area, each item first re-checked for a caller in Kixel and moq.pro + (rejected: shipping them; removing without the downstream check). + Adding an export later is free; removing one after the cut is a break. + +Before deleting anything, grep Kixel's and moq.pro's current `main` for +each item below and keep what either calls, naming the caller in the PR. + +Items, each with the grep that showed no caller, re-run at `80ca9787e3` +over `js` (outside `js/net/src` and `js/net/api`), `demo`, `test`, and +`doc`: + +- **`@moq/net/zod`** (`js/net/package.json:15`; `js/net/src/zod.ts`, 19 + lines, one `read(source, schema)`). `grep 'net/zod'` finds only its API + report, a MIGRATE line, and a comment in `doc/.vitepress/api/router.ts`. + Its `write` twin was already dropped. It is the only importer of `zod` + in `js/net/src`, so the peer dependency (`package.json:31`) goes with + it. Delete `zod.ts`, `zod.test.ts`, `api/zod.api.md`, and the export. + `@moq/json` is the schema-validated JSON path. +- **`Varint`** (`js/net/src/varint.ts`): `encodeLeadingOnes`, + `encodeLeadingOnesTo`, `decodeLeadingOnes`, `encodeTo`, `size`, and + `MAX_U6`, `MAX_U14`, `MAX_U30`, `MAX_U53` have no reference outside the + package's own `bench/`, which imports `../src/varint.ts` directly. + `Varint.encode`, `decode`, and `decodeBigInt` are used (`js/hang`, + `js/loc`) and stay. Mark the rest `@internal`. +- **`Path`** (`js/net/src/path.ts:107`, `:124`, `:57`): `Path.encode` and + `Path.decode` have no caller, and both validate rather than encode; + `Path.MAX_PARTS` has none. One doc comment in `js/auth/src/path.ts:24` + names `Path.decode`; reword it. +- **`Track.Subscriber.tryRecvGroup`** (`js/net/src/track.ts:4700`): only + `js/net/bench` calls it, and the benches already reach internals through + `hooks` (`src/internal.ts`). Move it there. +- **`Track.Request`** (`js/net/src/track.ts:470`) is `@public`, but no + public API returns one: its doc says it is "created internally by the + broadcast". Hide it. + [Broadcast requests](/quest/m4/net-broadcast-requests.md) publishes it + with `Broadcast.Producer.requests()` after the cut, which is additive. +- **`Datagram.rescale` and `Datagram.rescaleIn`** + (`js/net/src/datagram.ts:13`, from `rescale.ts`) take any + `{timescale}`, and `@moq/crypto` calls `rescaleIn` for a stream track's + frame (`js/crypto/src/e2ee/group.ts:67`, `datagram.ts:92`). Rust has + `track::Info::rescale` and `rescale_in` + (`rs/moq-net/src/model/track.rs:289`, `:300`). Export them under `Track` + and drop the `Datagram` export. +- **`Broadcast.Consumer`** publishes `protected constructor(shared?: never)` + and `protected shareState(): never` (`js/net/src/broadcast.ts:550`, + `:647`), an in-package subclass hook. Mark both `@internal`; + [the JS wrappers](/quest/m5/net-wrap/js.md) replace subclassing later. + +Recommended in the same PR, from the audit, not individually decided: + +- `Group.Producer.isClosed` and `Group.Consumer.isClosed` + (`js/net/src/group.ts:698`, `:1330`) duplicate + `closed.peek() !== undefined`, which `js/AGENTS.md` names as the way to + ask. Two callers outside the package (`js/crypto/src/e2ee/group.ts:91`, + `js/hang/bench/buffered.ts:179`). Remove them and move the callers. +- `Connection.Transport` includes `"webrtc"` + (`js/net/src/connection/transport.ts:2`). Nothing produces that label + outside two tests since peer-to-peer left in + [moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771). A supplied + transport may still label itself, so drop it only if the Kixel check + finds no use, with Rust's `Transport::WebRtc` + ([transport sweep](/quest/m2/unused-api/transport.md)). + +Kept on purpose although nothing in the repository calls them: +`peerImplementation`, `setCost`, `Error.RefusedRedirect`, +`Error.ConnectTimeout`, and `Auth.Unsupported`. They mirror Rust or exist +for `instanceof`. `Track.Requests` and `Track.Fill` stay: they mirror +Rust, and the interop clients use them. + +Not here: sockets leave `@moq/net` with +[the socket move](/quest/m2/sockets/README.md), and the `NO_MAX_DELAY` +sentinel (`js/net/src/internal.ts`) goes with the Max Age change in +[the lite-07 wire](/quest/m2/time-addressing/lite07.md). The browser media +packages' leftovers are [their own sweep](/quest/m2/unused-api/media.md). + +For the PR: regenerate `js/net/api/index.api.md` and check that every +removed name is gone from it; add each removal to `js/net/MIGRATE.md`; +`just js check` builds the declarations, which catches an `@internal` +type that a public signature still names. + +Public API: breaking for `@moq/net`: the `./zod` subpath and the names +above are removed or hidden, and `rescale` moves from `Datagram` to +`Track`. Wire: none. + +## Related + +- [@moq/net requests are awaitable](/quest/m2/js-net-api.md) - the other `@moq/net` API changes before the cut +- [Broadcast requests](/quest/m4/net-broadcast-requests.md) - republishes `Track.Request` with its accessor diff --git a/quest/m2/unused-api/media.md b/quest/m2/unused-api/media.md new file mode 100644 index 00000000000..d91a25cad9f --- /dev/null +++ b/quest/m2/unused-api/media.md @@ -0,0 +1,103 @@ +# [M] The media and gateway packages publish no API without a caller + +## Goal + +The media crates and browser packages the cut publishes export nothing that +only their own tests call. Each item below is deleted, made crate-private, +or marked `@internal`, in Rust and JS together where both have it, unless +the PR finds a downstream caller, in which case it stays and the PR says +who calls it. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Remove or hide every unused public item, one sweep per area, each + re-checked for a downstream caller first (rejected: ship them; decide + item by item in the [API review](/quest/m3/release/api-review.md) after + the cut, when each removal is a break). Publishing later is additive; + removing later is not. + +Before touching an item, search Kixel and moq.pro for a caller (the +maintainer's condition) and keep what one uses. The greps below cover this +repository only, at `80ca9787e3`. + +Rust: + +- `moq_mux::container::fmp4::Fragmenter`, `fragment::Config`, and + `Muxer::fragmenter` (`rs/moq-mux/src/container/fmp4/fragmenter.rs`, 644 + lines; `muxer.rs:330`): delete. `grep -rln 'Fragmenter\|fragmenter()' rs` + finds only four files in `container/fmp4/`, and the callers are the + type's own tests. Drop its bullet from + [the fMP4 group start](/quest/m3/fmp4-group-start-tfdt.md), which lists + `Fragmenter::emit` as a site to fix. +- `moq_video::encode::Applied`, `Encoder::applied` + (`rs/moq-video/src/encode/encoder.rs:83`, `:437`), `Sink::applied` + (`rs/moq-video/src/encode/sink.rs:82`), and + `moq_transcode::active::Rendition::applied` + (`rs/moq-transcode/src/active.rs:124`): crate-private. + `grep -rn '\.applied()' rs` finds callers only inside moq-video, one + setter in `rs/moq-transcode/src/rung.rs:1148`, and a test (`:1630`, + `:1635`). `Applied` also does three jobs in one struct: a confirmed + preset that sets the catalog's `reorder` and `delay`, a display string, + and the `cut` capability. moq-transcode keeps what it needs through a + `pub(crate)` path or a narrower accessor. +- `moq_video::encode::Config::preset` (`rs/moq-video/src/encode/encoder.rs:174`): + crate-private, with `Preset` if nothing else names it. Outside the crate + only `rs/moq-video/examples/encode-presets.rs` sets it and one + moq-transcode test reads it. The audit's reviewer would have kept + `Preset` as a small fenced enum; the maintainer chose to hide the set. + [The OBS adapter](/quest/m3/obs-moq-video/adapter.md) is the planned + consumer of both types and publishes them again, in the shape its Stats + panel needs, which is additive on a `#[non_exhaustive]` config. +- `hang::health` (`rs/hang/src/health.rs`, 737 lines; `rs/hang/src/lib.rs:28`) + and `Hang.Health` (`js/hang/src/health.ts`, 422 lines, 14 exports; + `js/hang/src/index.ts:19`): private in both languages until + [client health has a reader](/quest/m3/stats/health-consumers.md). + No Rust crate names `hang::health`, and the JS export line is the only + reference outside the module and its test. That quest re-measures every + threshold and adds a per-connection counter the grade needs, and + `Sample.interval`, `Sample.age`, and `Thresholds.stale` are still bare + millisecond numbers, so the shape would change after publishing. +- Recommended, not on the maintainer's list: `moq_rtmp::PUBLISH_IDLE_TIMEOUT` + (`rs/moq-rtmp/src/lib.rs:78`) has no user outside the crate. + +JS: + +- The `supported` input on the watch sources: remove + `SourceInput.supported` on `Video.Source` and `Audio.Source` + (`js/watch/src/video/source.ts:41`, `js/watch/src/audio/source.ts:30`), + the `Video.Supported` and `Audio.Supported` types, the statics + `Video.Decoder.supported` and `Audio.Decoder.supported` + (`js/watch/src/video/decoder.ts:552`, `js/watch/src/audio/decoder.ts:1183`), + and the `supportCacheKey` protocol in `js/watch/src/support-probe.ts`. + The sources always use the decoder's probe. Every caller passes exactly + that default: `js/watch/src/player.ts:159`, `:165`, + `demo/vr/src/index.ts:11-12`, `demo/boy/src/game.ts:144`, `:151`. It is + a callback parameter, which AGENTS.md asks to replace, and + [the watch worker](/quest/m4/watch-worker.md) would have to carry it + across a thread boundary. If a caller needs "can this browser play this + config", keep one read-only helper and say so. +- `Report.INTERVAL` (`js/hang/src/report.ts:11`) is a bare `1000`; both + callers wrap it in `Duration.millis` (`js/publish/src/broadcast.ts:409`, + `js/watch/src/echo.ts:151`). Export a `Duration`, as + `Container.DELAY_MAX` is, or stop exporting it. +- `SyncOutput.reference` (`js/watch/src/sync.ts:76`) is a public bare + millisecond number read only by `js/watch/src/audio/buffer.ts:382`, + `:515`: mark it `@internal` (`js/tsconfig.json` strips those). +- `BroadcastInput.tail` (`js/watch/src/broadcast.ts:245`) is a public input + only `Player` can drive correctly: mark it `@internal`. + +For the PR: delete rather than hide wherever nothing in the crate needs the +item. Each crate's and package's `MIGRATE.md` names what left, and +`doc/lib` drops what it documented. If one PR is too wide to review, split +Rust from JS; `Health` moves in both halves or neither. + +Public API: moq-mux, moq-video, moq-transcode, hang, `@moq/hang`, and +`@moq/watch` lose the items above. Wire: none. + +## Related + +- [moq-video has a producer that takes frames](/quest/m2/video-producer.md) - reworks the encode module these items sit in +- [Client health in use](/quest/m3/stats/health-consumers.md) - publishes `Health` once something reads it +- [The OBS adapter](/quest/m3/obs-moq-video/adapter.md) - the planned consumer of `Preset` and `Applied` diff --git a/quest/m2/unused-api/net.md b/quest/m2/unused-api/net.md new file mode 100644 index 00000000000..6ab781f3d9b --- /dev/null +++ b/quest/m2/unused-api/net.md @@ -0,0 +1,85 @@ +# [S] moq-net publishes no item without a caller + +## Goal + +The moq-net crate the cut publishes has no public item that nothing outside +it calls: each one below is removed or made `pub(crate)`, and the one place +moq-lite's subscriber tells outcomes apart by matching error variants reads +a typed outcome instead. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ remove +or hide every public item the audit found without a caller, one sweep quest +per area, each item re-checked for a downstream caller first (rejected: +keeping them until someone complains; one sweep across every crate). An item +stays private until a consumer needs it, and adding it back later is +additive while removing it after the cut is a break. + +Before removing an item, grep Kixel and moq.pro for a caller (the +maintainer's condition). Keep what one uses, and name the caller in the PR. + +Items, each with the grep that showed no caller at `80ca9787e3` (over `rs`, +`js`, `py`, `swift`, `kt`, `dart`, `cpp`, `go`, `demo`, and `test`, outside +`rs/moq-net/`): + +- `track::Position::after`, `after_group`, and `group_end` + (`rs/moq-net/src/model/subscription.rs:610`, `:622`, `:631`): remove. + `grep -rnF 'Position::after('`, `'after_group('`, and `'.group_end()'` + find 0 lines outside moq-net; inside, only unit tests and `after` calling + `after_group`. `after_group` is `start + 1`, which no longer names the + next group now that groups are addressed by start. +- `origin::Consumer::covering` (`rs/moq-net/src/model/origin.rs:7734`): make + `pub(crate)`. `grep -rnF '.covering()'` finds 0 lines outside moq-net; the + lite and moq-transport sessions call it, and its doc says "a session + serving its peer always uses this view". +- `track::Subscriber::with_range` and `track::Ordered::with_range` + (`rs/moq-net/src/model/track.rs:10427`, `:10756`): make `pub(crate)` after + moving their two production callers + (`rs/moq-mux/src/container/source.rs:621`, + `rs/moq-audio/src/decode/consumer.rs:243`) to `Subscription::ranges`, which + is already the subscriber's read filter. The audio caller's comment gives + a reason, that a range is aggregated across subscribers and can rewind the + publisher for everyone, that `Range::live()` no longer has. If either + caller cannot move, keep the method and say why in the PR. Sessions and + resume keep using it inside the crate. +- The 17 `pub fn` predicates of `lite::Version` + (`rs/moq-net/src/lite/version.rs`, `has_track_stream` to `has_route_cost`): + make `pub(crate)`. They are reachable today only through the public + `Version::Lite` variant, and no caller exists outside moq-net; the relay + uses only the crate-level `Version::has_request_path`. Each would + otherwise be a public name to keep or break as lite-08 moves the cut-offs. + [The opaque `Version`](/quest/m2/net-renames.md) closes the same door from + the other side; either order works. +- `Recovery` (`rs/moq-net/src/lite/subscriber/fills.rs:691-695`) matches + `Error::Decode(DecodeError::Short)` and then + `matches!(err, Error::ProtocolViolation)` to tell a reset from malformed + bytes, against AGENTS.md's "never match on errors". The reader returns a + typed outcome (ended, reset, malformed) that both `Recovery` and the live + subscription read. No API change. + +Not in this sweep, with their owners: + +- `Subscriber::next_in_range`, `is_skipped`, and `poll_start` have one + consumer, moq-mux's container reader, which orders groups itself. + [Group drops](/quest/m2/group-drops.md) adds `Gap` to `track::Ordered`; + once the container reader moves onto it these three can go private. +- `socket::is_endpoint` leaves with + [socket endpoints](/quest/m2/sockets/remove.md). +- `origin::Producer::update_hold`, `with_proxy`, `Source`, `source()`, + `Consumer::local()`, `origin::RouteKey`, and `Config::route_key` belong to + [the route switch](/quest/m2/multicast/switch.md). +- `setup::Extensions` belongs to + [the `ietf` extension](/quest/m2/ietf-records-per-track.md). + +Run `just api-diff rust` after the change and list +every item it shows removed in the PR's Impact section. + +Public API: breaking, removals only (`Position::after`, `after_group`, +`group_end`, `origin::Consumer::covering`, `Subscriber::with_range`, +`Ordered::with_range`, and the `lite::Version` predicates). Wire: none. + +## Related + +- [moq-net's node, version, handshake, and route priority](/quest/m2/net-renames.md) - makes `Version` opaque +- [A group a subscriber gives up on is always reported](/quest/m2/group-drops.md) - gives the container reader the `Gap` that frees three more methods diff --git a/quest/m2/unused-api/transport.md b/quest/m2/unused-api/transport.md new file mode 100644 index 00000000000..ae2bd01daac --- /dev/null +++ b/quest/m2/unused-api/transport.md @@ -0,0 +1,122 @@ +# [M] The transport crates publish only what something calls + +## Goal + +moq-tokio, qmux, moq-congestion, and moq-sock publish no item that nothing +outside its own crate and tests calls. What is left of MoQ over a WebRTC +data channel is gone. moq-tokio's in-tree QUIC driver and WebTransport layer +are reachable only through a test-support feature, so the crate's stable API +is MoQ. Each item below is removed, made crate-private, or gated, unless +the first step finds a caller. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Remove or hide every item below before the cut, one sweep per area + (rejected: shipping them and breaking again; `#[doc(hidden)]`, which the + repository bans). A removal after 0.22 is a breaking release; an addition + later is free. +- ✅ Each item is re-checked for a caller in Kixel and moq.pro first, and + kept if one uses it. The audit could read their quests, not all of their + code. + +Do first: for each item, grep both downstream checkouts for the name. Record +the command and its result in the PR body, one line per item. An item with a +caller stays public, with the caller named beside it. + +The items, with the grep that showed no caller in this repository: + +1. **`moq_tokio::quic::driver` and `quic::web`** + (`rs/moq-tokio/src/quic.rs:21`, `:24`): quinn's async layer and a + WebTransport library, 161 of the crate's roughly 535 public items by + the audit's count. `grep -rn 'quic::driver::\|quic::web::' rs` outside + `rs/moq-tokio/src` and `rs/moq-uring/src` finds tests, benches, the + interop example, and one field moq-relay already gates on its own + `test-support` feature (`rs/moq-relay/src/cluster.rs:1055`). + [moq-dev/moq#5664](https://github.com/moq-dev/moq/pull/5664) made them + `#[doc(hidden)] pub` saying "they are not a stable API"; + [moq-dev/moq#8392](https://github.com/moq-dev/moq/pull/8392) banned + `doc(hidden)`, which turned them into documented API, and + `doc/concept/transport.md:37` now advertises `quic::web` as "a + WebTransport library usable without MoQ". The + [runtime-free driver](/quest/m4/quic-sansio-driver.md) rebuilds both after + the cut, so this is the surface most likely to break next. Gate both + behind one documented feature for tests (moq-tokio has `sim`, moq-relay + has `test-support`; use one name for both crates) and drop the doc line. + `moq_uring::quic::web` stays public: moq-relay's io_uring path calls it + (`rs/moq-relay/src/uring.rs:704`). +2. **`Client::connect_with`** (`rs/moq-tokio/src/client.rs:374`), + **`Listener::accept_with`** and **`Listener::admission`** + (`rs/moq-tokio/src/server.rs:770`, `:785`): take a qmux session + established elsewhere. `grep -rn 'connect_with\|accept_with' rs` finds no + caller outside the two files since + [moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771) removed + peer-to-peer. Delete all three, and the doc lines that name data channels + (`rs/moq-tokio/src/lib.rs:9`, `server.rs:761`, `:1515`). +3. **`moq_tokio::Transport::WebRtc`** (`rs/moq-tokio/src/transport.rs:17`): + "a WebRTC data channel using qmux framing". Nothing constructs it; only + `accept_with`'s caller could. Delete it with its arm in the relay's + mapping (`rs/moq-relay/src/auth.rs:1295`). moq-ffi's `MoqTransport` + never mirrored it (`rs/moq-ffi/src/server.rs:443-455` refuses it as + unsupported). `moq_auth::Transport::WebRtc` stays: WHIP and WHEP + sessions report it. +4. **`qmux::Config::fixed_receive_window`** (`rs/qmux/src/config.rs:86`): + set only by `rs/qmux/src/session/tests.rs:285`. Delete the field and the + two checks that read it (`rs/qmux/src/session.rs:243`, `:414`). +5. **`moq_tokio::tls::Peers`** and `listen.tls.peers` + (`rs/moq-tokio/src/tls.rs:414`, `:1332`): a live set of pinned client + fingerprints, from the mesh era. It is settable only from code, and + `grep -rn 'tls::Peers' rs` outside moq-tokio finds one test + (`rs/moq-relay/src/web.rs:2219`). This is the item most likely to have a + Kixel caller, since its mesh pins fingerprints: keep it if so. The + client-side pin, `connect.tls.fingerprint`, is separate and stays. +6. **`Controller::paces_probe` and `Controller::on_probe_target`** + (`rs/moq-congestion/src/lib.rs:147`, `:160`): overridden only by GCC + (`rs/moq-congestion/src/gcc/mod.rs:502`, `:506`), which compiles under + `lab`. moq-quic calls them in production, where they are always `false` + and a no-op (`rs/moq-quic/src/connection/bandwidth_probe.rs:245`, + `connection/mod.rs:1661-1680`, `:3457`). Gate the two methods and their + call sites on `lab`. A default trait method is additive later; a removal + is a break of a crate that publishes for the first time at this cut. +7. **moq-sock's ICMP error queue**: `enable_transport_errors`, + `recv_transport_error`, `TransportError`, and `TransportErrorPayload` + (`rs/moq-sock/src/udp/unix.rs:225`, `:253`, `udp/mod.rs:172`, `:197`, + with the reader in `udp/linux.rs`). `grep -rn + 'transport_error\|TransportErrorPayload' rs` outside `rs/moq-sock` finds + nothing. Delete them with the fuzz seeds that feed the reader, then + delete [the truncated error-queue quest](/quest/m5/errqueue-truncation.md) + with `quest rm`, since it repairs code this removes. +8. **moq-sock's buffer size accessors**: `set_send_buffer_size`, + `set_recv_buffer_size`, `send_buffer_size`, and `recv_buffer_size` + (`rs/moq-sock/src/udp/unix.rs:289-318`, and the Windows twins). Called + only by `rs/moq-sock/src/bind.rs:206-207` and the crate's tests. Make + them crate-private. + +Already settled since the audit, so not an item: the unreachable +`TcpTls::new` under a `cfg` that could never hold went with the feature +flags in [moq-dev/moq#8852](https://github.com/moq-dev/moq/pull/8852), and +moq-webrtc's `p2p` and moq-relay's `stun` features went in +[moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771). The +[API review](/quest/m3/release/api-review.md) still lists all three. + +Left alone, with the reason: `moq_tokio::mdns` stays where it is (see +[transport names](/quest/m2/transport-names.md)); plaintext `tcp://` and +`unix://` are small and a same-host sidecar is a plausible use; kio's +`PushError` and `Queue::poll_push_with` have no outside caller but belong to +a foundation crate whose surface is otherwise tight. + +For the PR: one commit per item keeps the review and any revert small. +Update each crate's migration note and `just api-diff`'s expectations. Run +`just check`, and `just test interop --all` since item 1 moves what the +interop example and moq-uring's tests import. + +Public API: breaking removals in moq-tokio (items 1 to 3 and 5), qmux (4), +and moq-sock (7, 8); moq-congestion (6) publishes without two trait +methods. The bindings are unchanged. Wire: none. + +## Related + +- [Transport names](/quest/m2/transport-names.md) - adds `Tls` to the enum item 3 trims +- [Congestion control by algorithm name](/quest/m2/congestion-names.md) - removes `quic::Config::controller`, the other unused transport hook +- [A runtime-free QUIC driver](/quest/m4/quic-sansio-driver.md) - rebuilds the modules item 1 hides diff --git a/quest/m2/vaapi-exports.md b/quest/m2/vaapi-exports.md new file mode 100644 index 00000000000..5ee6f542f94 --- /dev/null +++ b/quest/m2/vaapi-exports.md @@ -0,0 +1,55 @@ +# [S] moq-vaapi exports only what moq-video names + +## Goal + +The published `moq-vaapi` crate exports the items its one consumer, +moq-video, uses, not every constant and struct bindgen generates, and its +manifest describes the crate without "(AI GENERATED)". + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Narrow the re-exports and fix the description before the cut (rejected: + keep as is and let the [vendor sync](/quest/m3/vendor-sync/vaapi.md) track + upstream fixes only). Both are public API or metadata of a crate the cut + publishes under the project's name. + +Facts found by the audit: + +- `rs/moq-vaapi/src/lib.rs:57` does `pub use bindings::*`, so all 22,389 + generated lines of `src/bindings/libva.rs` are public API of a published + crate. Lines `:58`-`:68` glob-export nine more modules. +- moq-video is the only dependent, and names a short list + (`grep -rn 'moq_vaapi::' rs/moq-video/src`): `Display`, + `DrmDeviceIterator`, `Surface`, `Image`, `Codec`, `Color`, + `UsageHint`, `DrmPrimeSurfaceDescriptor`, the `encode`, `decode`, `vpp`, + and `dmabuf` modules, and seven `VA_FOURCC_*` and `VA_RT_FORMAT_*` + constants. +- `rs/moq-vaapi/Cargo.toml:8` opens the description with "(AI GENERATED)". + The crate is a fork of cros-libva and cros-codecs moved in-tree by + [moq-dev/moq#8235](https://github.com/moq-dev/moq/pull/8235); the label + reads as a statement about the whole release. + +For the PR: + +- Replace the globs with named exports, the raw bindings behind a + crate-private module, and let the compiler find what moq-video still + needs. Check Kixel and moq.pro for a direct `moq_vaapi` dependency first + and keep what one uses. +- Rewrite the description to say what the crate is: VA-API H.264 and H.265 + encode and decode, forked from cros-libva and cros-codecs, with libva + loaded at runtime. +- Not needed for the cut, since no dependent sees them, but cheap while + here: `bindgen.sh` already fetches the libva headers by tag, so the roughly + 17.9k in-tree lines under `rs/moq-vaapi/libva/` can go once the tag is + pinned in the script, and a function allowlist (the bindings declare 77 + `va*` functions and the crate calls about 35) would halve the generated + file. Do them here only if they stay mechanical. + +Public API: moq-vaapi breaks (already marked a break in the API diff). +Wire: none. + +## Related + +- [VA-API vendor sync](/quest/m3/vendor-sync/vaapi.md) - ports upstream fixes into the same crate diff --git a/quest/m2/video-producer.md b/quest/m2/video-producer.md new file mode 100644 index 00000000000..35a7d2ee21c --- /dev/null +++ b/quest/m2/video-producer.md @@ -0,0 +1,74 @@ +# [L] moq-video has a producer that takes frames + +## Goal + +`moq_video::encode::Producer` takes raw frames, owns its encoder, and follows +the uplink grant, as `moq_audio::encode::Producer` does for PCM. The type +that publishes already encoded access units keeps working under a name that +says what it takes (recommended: `encode::Publisher`). moq-boy, moq-ffi, and +moq-c publish video through the new producer, so the probe, catalog +reservation, encode loop, and grant following exist once, in moq-video. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Rename today's type and build the frame-taking producer before the cut + (rejected: rename only and add the producer after the cut under the freed + name; keep both names and add the frame-taking type later under a third). + The maintainer: "Rename and build it now." A name that means two layers in + sibling crates freezes at the cut, and the freed name is only worth + reserving if the type that earns it ships with it. + +Facts found by the audit: + +- `moq_audio::encode::Producer` takes PCM (`write`, + `rs/moq-audio/src/encode/producer.rs:407`), owns its encoder, and follows + the grant through `Options::bandwidth` (`:43`). + `moq_video::encode::Producer` takes encoded access units (`publish`, + `rs/moq-video/src/encode/producer.rs:163`) and knows no encoder or grant. + Same name, same module path, different layer. +- Every caller with its own frames assembles the video path by hand: probe + the config, reserve a catalog slot with the effective join, build the + producer, run the encode, receive, publish loop. `rs/moq-boy/src/video.rs:59-65` + is the shortest witness; `rs/moq-ffi/src/video.rs` (2,129 lines) and + `rs/moq-c/src/video.rs` (1,820 lines) carry the rest. +- Grant following with rung disable, the part that is easy to get wrong, + exists three times: private in the capture driver + (`rs/moq-video/src/encode/producer.rs:718`, `:840`, `:940`), in moq-ffi + (`rs/moq-ffi/src/video.rs:370`, `:524`), and in moq-c + (`rs/moq-c/src/video.rs:286`, `:319`, `:363`). +- No quest owns it: [the grant getter](/quest/m3/video-publish-grant.md) + only adds a getter to the capture handle, and + [the mux wrap](/quest/m5/net-wrap/mux.md) only makes the producer generic. + +For the PR: + +- Rename first, as its own commit: mechanical, about 19 references outside + moq-audio (`grep -rn 'encode::Producer' rs`). The rename also reaches the + docs (`doc/lib/rs/moq-video.md`) and `rs/moq-video/README.md`. +- Lift the frame-taking producer out of the capture driver + (`publish_capture`'s `Driver`), which then runs on it, so the capture path + and a caller's own frames share one encode loop and one grant follower. + Shape it after audio: an `Options` with `bandwidth`, `write(&Frame)`, and + `finish(self) -> Result` from the start (the + [finish sweep](/quest/m2/finish-sweep.md) converts the renamed type). +- Move moq-boy, moq-ffi, and moq-c onto it and delete their copies of the + grant follower. A binding option the lifted type cannot express (moq-ffi's + `lower` rendition for the simulcast ladder, `rs/moq-ffi/src/video.rs:370`) + becomes an option of the producer, not a reason to keep a copy. +- If lifting the driver would change a backend's behaviour in a way the cut + cannot absorb, stop and say so on the PR instead of shipping the rename + alone: the maintainer rejected that end state. +- Tests: the capture driver's grant tests run against the lifted type; a + frame-taking producer follows a falling and recovering grant and disables + and re-enables its rendition; `just test interop --all` for moq-ffi. + +Public API: moq-video breaks (`encode::Producer` changes meaning; the encoded +publisher is renamed). moq-ffi and moq-c keep their names. Wire: none. + +## Related + +- [Terminal operations consume](/quest/m2/finish-sweep.md) - gives the renamed type `finish(self)`; whichever lands second rebases +- [One device selector](/quest/m2/native-media-config.md) - changes `encode::Config` in the same crate +- [A published capture exposes its grant](/quest/m3/video-publish-grant.md) - adds a getter to the capture handle this runs on diff --git a/quest/m2/webrtc-bind.md b/quest/m2/webrtc-bind.md new file mode 100644 index 00000000000..2fcb6ad4877 --- /dev/null +++ b/quest/m2/webrtc-bind.md @@ -0,0 +1,84 @@ +# [M] moq-webrtc's server binds its UDP socket at startup + +## Goal + +`moq_webrtc::Server::bind(config).await` binds the shared UDP socket and +fails if it cannot, so `moq import|export webrtc --listen` reports a taken +or unbindable `--udp-bind` port at startup, before it says it is ready. +`--public-addr 203.0.113.1:5000` advertises port 5000, as written. The +server's socket shape can take the planned shared-port feed without another +break, and the client config carries no field nothing sets. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ `Server::bind(config)` binds at construction (rejected: land the m3 + shared-port feed before the cut so the two-variant socket ships; keep the + lazy bind and take a break in the release after). It matches + `moq_rtmp::Server::bind` and `moq_srt::Server::bind`, and a gateway that + logs "serving" with no socket bound fails late, in front of a browser. +- ✅ `--public-addr` honors the port it is given (rejected: change the type + to an IP and rename the flag `--public-ip`; keep and document). The type + is `SocketAddr`, and a mapped port behind a NAT is what the port is for. +- ✅ `client::Config::ice_candidates` is deleted until a caller sets it. + +Facts found by the audit: + +- `Server::new(config) -> Self` binds nothing + (`rs/moq-webrtc/src/server/mod.rs:181`). The socket binds inside `mux()` + on the first accept (`:170`, `:192`-`:196`), "so `Server::new` can stay + synchronous". +- The CLI logs "serving WebRTC" and calls `notify_ready()` with no UDP + socket bound (`rs/moq-cli/src/rtc.rs:144`-`:147`), so a bad `--udp-bind` + surfaces as an HTTP error on the first WHIP or WHEP request. +- `server::Config` and `server::Socket` derive `Clone` + (`rs/moq-webrtc/src/server/mod.rs:129`, `:149`), and `Socket` has one + variant, `Bind(SocketAddr)` (`:153`). The second is the m3 + [shared-port feed](/quest/m3/one-port/rtc-feed.md), which holds a channel + receiver and cannot be `Clone`; that quest already notes the fed socket + "may belong in the server's constructor rather than the config". Either + answer is a break once the crate is published. +- The session keeps only the IP of each advertised address: + `advertise.iter().map(|addr| SocketAddr::new(addr.ip(), port))` with the + bound port (`rs/moq-webrtc/src/session.rs:715`). +- `client::Config::ice_candidates` + (`rs/moq-webrtc/src/client/mod.rs:21`) is read at + `client/whip.rs:28` and `client/whep.rs:27` and set by nothing: both CLI + call sites pass `client::Config::default()` + (`rs/moq-cli/src/rtc.rs:103`, `:125`). +- `moq-webrtc` has never been published under this name (the API diff marks + it new), so all of this is free until the cut. + +For the PR: + +- Settle where the socket lives so the feed is additive. Recommended: the + socket is an argument of the constructor, not a field of a `Clone` + config, and the single-variant `Socket` enum is deleted until the feed + adds its own constructor. The alternative, dropping `Clone` from `Config` + and `Socket`, keeps one constructor but freezes a config that cannot be + copied. Write the choice into [the feed quest](/quest/m3/one-port/rtc-feed.md). +- `Server::bind` is async and returns the bind error. Reproduce the late + failure first: a test that binds the UDP port, starts the server on it, + and expects the constructor to fail. +- An advertised candidate is sent exactly as given. Keep the existing + default for an unspecified bind address (loopback with the bound port). + Test that a `--public-addr` with its own port reaches the SDP answer. +- Fix the flag's `requires = "rtc-listen"` + (`rs/moq-cli/src/rtc.rs:34`), which names no flag. +- Recommended, not decided by the maintainer: record the crate's version + line in the PR. The manifest reads `0.3.12` + (`rs/moq-webrtc/Cargo.toml:8`), so `just version 0.22.0` moves it onto the + shared line; that is right, since published moq-cli depends on it. +- Update `doc/bin/rtc.md` (renamed by [the gateway alignment](/quest/m2/gateway-align.md)) + and `rs/moq-webrtc/MIGRATE.md`. + +Public API: moq-webrtc breaks (`Server::new` becomes `Server::bind`, the +socket's place, `client::Config::ice_candidates`), free while unpublished. +CLI: `--public-addr` now advertises its port. Wire: none. + +## Related + +- [The gateways admit a session the same way](/quest/m2/gateway-align.md) - changes the same crate's request and client names, and renames the CLI endpoint +- [moq-webrtc runs on upstream str0m](/quest/m2/str0m-upstream.md) - swaps the stack under the same session code +- [A WebRTC feed on the shared port](/quest/m3/one-port/rtc-feed.md) - adds the second socket source this leaves room for diff --git a/quest/m2/yield-defer.md b/quest/m2/yield-defer.md new file mode 100644 index 00000000000..2acfc71aa2c --- /dev/null +++ b/quest/m2/yield-defer.md @@ -0,0 +1,109 @@ +# [L] lite-07 freezes without YIELDED continuations + +## Goal + +On lite-07 a Group Stream reset to make room for a higher-priority one is a +final drop of its group on that subscription, as on lite-06: the publisher +names the group in SUBSCRIBE_DROP, and a reader that still wants the rest +FETCHes it from the frame it reached. No group pauses, no stream continues +another, and a group has two streams on one subscription only as a +duplicate. The YIELDED (0x3C) code, paused groups, and continuations leave +the draft, `rs/moq-net`, and `js/net`, and come back in lite-08 with +[takeover](/quest/m3/group-takeover.md), designed as one feature. FRAME +still leads with `Payload Length`. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Defer YIELDED continuations to lite-08 with takeover (rejected: keep + them but stop pausing a group on a reset that arrives without its code; + keep as is). This reverses the 2026-11-04 pick that stream credit lands + before the cut, and the 2026-11-12 pick on + [moq-dev/moq#8545](https://github.com/moq-dev/moq/pull/8545) of YIELDED + over "TOO_FAR_BEHIND plus a drop". What changed since: OLD drops became + final on 2026-11-14, which made "ask again yourself" the rule for every + other lost group; takeover, the other half, moved past the cut on + 2026-11-13; and the facts below. + +Facts found by the audit: + +- The named consumer is a lossless reader of several hundred tracks under a + browser's stream cap, which is later work downstream. Nothing planned for + 0.22 reads that way. +- Browsers lose the signal the pause depends on. Chromium drops a reset that + lands right after the stream's data and Firefox drops its code + ([browser reset reports](/quest/m4/browser-reset-reports.md)), so the draft + tells a subscriber to pause on any reset without a code (`#yield`), and + only JS does: [moq-dev/moq#8673](https://github.com/moq-dev/moq/pull/8673) + was "JS only, Rust unchanged". A drop on the Subscribe Stream needs no code + from the reset. +- No relay link yielded until + [moq-dev/moq#8843](https://github.com/moq-dev/moq/pull/8843) on + 2026-11-15, because every relay link negotiated object records + (`GroupServe::yields`, `rs/moq-net/src/lite/publisher.rs`). Fixing that + uncovered a panic in the paused group's writer and a protocol violation on + continuations. +- A continuation restarts at the reset stream's own `Frame Start`, so it + resends the frames the reader holds. That is what a FETCH from a frame + index returns without the resend, and `resume::Recover` + (`rs/moq-net/src/model/resume.rs`) already issues one. A FETCH reply rides + a stream the subscriber opened, outside the incoming cap that caused the + reset. +- Cost, by `grep -ci 'yield\|paus\|continu'`: 188 lines in + `lite/publisher.rs` and 264 in `lite/subscriber.rs`, plus + `tests/integration/stream_credit.rs` (857 lines), the `test/stream-credit` + browser harness, `Continuation.cfg`, and three of the seven rules in + `rs/moq-net/verify/subscribe/SubscribeAccounting.tla`. The other four + rules cover reopened OLD drops, which + [time addressing](/quest/m2/time-addressing/lite07.md) deletes. + +What goes: + +- Draft: the Yield section, the YIELDED row (0x3C), the paused clauses in + SUBSCRIBE_DROP's accounting rule, the continuation exception to the + duplicate-stream rule with its "held unread" and "MAY end the earlier + stream" rules, the `ietf` extension's never-yields sentence, and both + changelog lines. The reset rule reads as lite-06's: the publisher resets + the lowest-priority Group Stream and drops the group. +- Rust: `StreamError::Yielded` and `has_yield` (`rs/moq-net/src/error.rs`, + `lite/version.rs`); the publisher's `TrackRun.paused`, `paused_tasks`, + `continuing`, `GroupServe.rewind`, `give_way`, `shed`, `pause`, + `best_paused`, and `drop_given_up_paused`; the subscriber's `PausedGroup`, + `YieldVerdict`, `TrackEntry.paused`, `yielding`, `yield_streams`, and + `Duplicate.paused`. The priority scheduling that picks which stream to + reset stays. +- JS: the same in `js/net/src/lite/{publisher,subscriber}.ts`, `open.ts`, + and `error.ts`, including the paths that infer a pause from a reset without + a code or from a later stream for the same group. +- `verify/subscribe`: with this and OLD-final, none of the seven rules + describes shipped behaviour. Re-derive the model around what remains + (final drops, duplicate streams, the tail) or delete it with its skill + (`.claude/skills/verify-subscribe`) and nightly job; recommended: + re-derive, since tail accounting stays. Whichever PR lands second, this + or time addressing's, does it. + +Guidance for the PR: + +- Land after or with [time addressing](/quest/m2/time-addressing/lite07.md) + if both are open, since both rewrite SUBSCRIBE_DROP's accounting text; + neither blocks the other. +- Keep `test/stream-credit` and `stream_credit.rs`, rewritten to the new + contract: more live tracks than the cap, the highest-priority groups get + the streams, every group the reader misses is named in a drop, and a + reader that FETCHes a dropped group gets it whole. Run it on lite-06 and + lite-07 in Chromium and Firefox, where both now behave alike. +- Check that the ordered reader and `Recover` do FETCH a group dropped as + TOO_FAR_BEHIND when the reader has no max age, and say in + `doc/concept/moq-lite.md` what a lossless reader under a stream cap sees. +- Run `just test interop --all`. + +Public API: `StreamError::Yielded` leaves Rust and `@moq/net`. Wire: +lite-07-wip loses reset code 0x3C and the continuation rules; lite-01..06 +are unchanged. + +## Related + +- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - rewrites the same SUBSCRIBE_DROP accounting text and deletes the model's other four rules +- [Takeover](/quest/m3/group-takeover.md) - designs paused groups and continuations again, with takeover, for lite-08 +- [Browser reset reports](/quest/m4/browser-reset-reports.md) - the browser bugs that made the pause depend on a lost signal diff --git a/quest/m3/README.md b/quest/m3/README.md index 1e8543595d7..9385bd8c7da 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -35,7 +35,9 @@ federation) land. Superseded 2026-11-12 (maintainer, /quest-audit): both moved to [m1](/quest/m1/README.md), since the cut no longer waits on m1. The mesh libraries came back 2026-11-13, below; byte streams moved to Kixel 2026-11-14. The mesh libraries left moq for Kixel on 2026-11-14 (maintainer): moq keeps -what a large live-media platform would use. +what a large live-media platform would use. Socket endpoints, the first of +those prerequisites, [leave for Kixel too](/quest/m2/sockets/README.md) +(2026-11-16). Decided 2026-11-12 (maintainer, /quest-audit before the cut), from a read of every quest against the code and the downstream quest trees: diff --git a/quest/m3/audio-playout-library.md b/quest/m3/audio-playout-library.md index 1040430cc56..81c2eae722f 100644 --- a/quest/m3/audio-playout-library.md +++ b/quest/m3/audio-playout-library.md @@ -30,6 +30,19 @@ the lag rule, and no declared-silence or stretch handling. - Move `media.rs`'s audio tests with the code; then bump studio so `moq-scene` adopts the type and deletes its copy. +Added 2026-11-16 by the pre-cut audit (/quest-plan): native video has no +delay estimator. In the browser each video track measures its own target +from its arrivals, and the shared delay is the largest target of any track +(`js/watch/src/video/decoder.ts`, `js/watch/src/sync.ts`). In `moq play` +the delay follows audio's estimate alone and is a constant 100 ms with no +audio (`rs/moq-cli/src/play/args.rs:14-19`, `:137`), though the +[audio playout](/quest/m2/audio-playout/README.md) epic promises one +written algorithm both players implement. Recommended: the library gives a +video reader the same arrival estimator audio has +(`moq_audio::decode::Options::estimate`), fed through the shared clock, so +`auto` means the same in both players; if it stays out of scope, say so in +`doc/concept/audio-jitter.md`. Behaviour only, so it can land after the cut. + It waits so the epic's remaining children land first and this breaks nothing in the cut. diff --git a/quest/m3/c/README.md b/quest/m3/c/README.md index 39f425a9142..5d9a7cacbb3 100644 --- a/quest/m3/c/README.md +++ b/quest/m3/c/README.md @@ -35,10 +35,14 @@ Decided earlier, still standing: (`err->protocol`). Infallible calls return their value directly, optional scalars are `{has_value, value}`, each async function has its own callback typedef, and unnamed variant fields are `v1`, as in C++. -- The generated package takes over the `moq-c` name and `moq::c` target at - the shared minor of the cut that ships it, after the hand-written crate's - 0.22 (RELEASE.md's [Versions](/RELEASE.md#versions), - [moq-dev/moq#7610](https://github.com/moq-dev/moq/pull/7610)). +- The generated package is the first published `moq-c`, with the `moq::c` + target, at the shared minor of the cut that ships it (RELEASE.md's + [Versions](/RELEASE.md#versions), + [moq-dev/moq#7610](https://github.com/moq-dev/moq/pull/7610)). Amended + 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): the + hand-written API ships at 0.22 as `libmoq`, not `moq-c` + ([its name](/quest/m2/libmoq-name.md)), so the generated package takes + over no published name and C users rename once, when the API changes. - Docs change inline: the consumer quest rewrites `doc/lib/c`, and its Impact bullet carries the move for the package's `MIGRATE.md`. diff --git a/quest/m3/crates-trusted-publisher.md b/quest/m3/crates-trusted-publisher.md index 4e78cc58791..038a85a67f7 100644 --- a/quest/m3/crates-trusted-publisher.md +++ b/quest/m3/crates-trusted-publisher.md @@ -8,12 +8,16 @@ for `moq-dev/moq`, workflow `release-rs.yml`, and environment `publish`, so Delete this quest once every crate has one. Corrected 2026-11-12 (/quest-audit): moq-bench leaves the list, since it -sets `publish = false`; seven crates remain. +sets `publish = false`; seven crates remain. Corrected 2026-11-16 +(/quest-plan of the pre-cut audit): moq-c leaves it too, since the +hand-written C API ships as `libmoq`, which has a trusted publisher, and +`moq-c` stays unpublished for the generated API +([the C crate's name](/quest/m2/libmoq-name.md)); six remain. ## Waiting - Maintainer: after [the cut](/quest/m3/release/cut.md) publishes kio-macros, - moq-c, moq-congestion, moq-crypto, moq-quic, moq-rtsp, and moq-webrtc by token, add + moq-congestion, moq-crypto, moq-quic, moq-rtsp, and moq-webrtc by token, add their trusted publishers the same way. Settings pages need a crates.io login, so check with a `release-rs.yml` run that publishes through OIDC. @@ -58,7 +62,11 @@ crates.io has none of the seven in Waiting. Decided 2026-11-05 (maintainer, /quest-audit): moq-e2ee, published but retired in favor of moq-crypto, gets no trusted publisher; a later change took it out of the -workspace instead. +workspace instead. Reversed 2026-11-16 (maintainer, /quest-plan of the +pre-cut audit): moq-e2ee is a crate again, unpublished at the cut +([the crate move](/quest/m2/e2ee-crate.md)), and gets its trusted publisher +when [the finished format](/quest/m3/e2ee-format.md) publishes it, which +that quest's `Waiting` item tracks. ## Required diff --git a/quest/m3/e2ee-format.md b/quest/m3/e2ee-format.md new file mode 100644 index 00000000000..526f7cf12b8 --- /dev/null +++ b/quest/m3/e2ee-format.md @@ -0,0 +1,173 @@ +# [L] moq-e2ee publishes its finished format + +## Goal + +`moq-e2ee` and its JS twin implement one finished format, profile +`moq-e2ee-01`, and the crate publishes again. In that format: + +- A key binds the broadcast it protects, so a relay cannot answer a request + for one broadcast with another broadcast under the same credential. +- Each group has its own key, so no broadcast ever has to restart because a + key ran out. +- An application can encrypt a single track it already holds under a name + both ends agree on, without the broadcast wrapper choosing the name. +- A publisher run is identified by moq-net's `Instance`; there is no + separate `Epoch` type. +- The wrapper's names and signatures match moq-net's, in Rust and JS. +- The payload is ciphertext plus tag with no compression metadata, and a + credential names its profile. + +Encryption stays inside the payload: a relay sees nothing that says a track +is encrypted, and moq-net and the wire carry nothing for it. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ Bind the semantic broadcast name into key derivation, the same string + the application passes to `credential.path(semantic)` and never the wire + path (rejected: dropping the argument so `context` alone names the + broadcast; documenting that `context` must be unique per broadcast). The + wire path is not stable: a relay may serve one broadcast under a prefix or + a vanity host, so two ends can disagree on it while agreeing on the name. +- ✅ One key per group; `Exhausted` and the budget accounting are deleted + (rejected: an in-payload re-key signal; documenting the restart). +- ✅ The per-track wrap is public (rejected: adding it when someone asks; + dropping the broadcast wrappers and name hiding). +- ✅ `e2ee::Epoch` becomes `moq_net::Instance` (rejected: renaming it + `e2ee::Instance` and keeping UUIDv7; documenting the difference). +- ✅ Wrapper fixes: `abort` takes an error, `create_group` is deleted, the + subscribe shape and names match moq-net, `name()` means one thing, and + `Config`, `Frame`, `Datagram`, and `Event` are `#[non_exhaustive]`. +- ✅ No compression in the profile, and `Config` gains `profile` (rejected: + designing the inner header now; shipping and planning a third label). +- ✅ Nothing on the moq-net layer or the wire says a payload is encrypted or + how. The maintainer weighed a track property that would let a relay parse + the scheme and dropped it: a relay that strips the tag to transcode has + defeated the purpose. +- ✅ The finished format is `moq-e2ee-01`, and the crate stays unpublished + until it is (see [the crate move](/quest/m2/e2ee-crate.md)). + +Facts found by the audit (paths as of 2026-11-16, before the crate move, so +under `rs/moq-crypto/src/e2ee`): + +- Broadcast swap. `scope` is `context || epoch || kid` + (`generation.rs:171-176`), and the semantic broadcast name enters only the + path derivation (`credential.rs:108-115`). `credential.consume(epoch)` + takes no broadcast (`credential.rs:104`). A room that shares one + credential and publishes two broadcasts has two paths and two epochs; a + relay that answers a request for the first path with the second's + Instance and tracks is accepted, because the subscriber derives names and + keys from the epoch the relay gave it. The draft's "A relay that presents + a wrong epoch causes authentication failure" is false when the wrong epoch + is another broadcast's real one. +- Key limits. One AES key per track per epoch, capped at 2^36 plaintext + bytes and 2^24 operations (`limits.rs:35,38`). 2^36 bytes is 19.1 hours at + 8 Mb/s; 2^24 frames is 4.7 hours for a 1 kHz datagram track. After that + every write is `Error::Exhausted` (`key.rs:76,80`) and the only remedy is + a new generation: a new Instance and new names for every track. Failed + opens count, so a relay can spend a subscriber's budget. The consuming + side's claim maps are never evicted (`generation.rs:31-35`). +- Per-track entry. `generation::Consumer::{consume, consume_datagrams}` and + `generation::Producer::{produce, produce_datagrams}` exist and are + `pub(crate)` (`generation.rs:111,120,231,248`). Keys bind the semantic + name, not the physical one (`generation.rs:146-153`), so a track under a + plain wire name seals and opens with the same derivation. Kixel's one + recorded wish for encryption is a single control track. +- `Epoch` is a UUIDv7 announced as the route's Instance (`epoch.rs:5-12`), + while lite-07's Epoch is a counter inside one Instance and + `moq_stats::Epoch` is a bucket's run. Nothing outside tests compares + epochs, so UUIDv7 ordering has no reader; it costs a type, an error, + `epoch.json`, and the `uuid` dependency in both languages. A publisher + that forgets `with_instance` gets no error and no subscriber finds a key. +- Wrapper drift. `track::Producer::abort`, `group::Producer::abort`, and + the datagram producer's take no error (`track.rs:83`, `group.rs:109`, + `datagram.rs:148`), while `broadcast::Producer::abort` does + (`broadcast.rs:300`). `create_group(start)` (`track.rs:57`) cannot go back + as moq-net's can, since a claim refuses a start at or below the highest + allocated. `e2ee::track::Consumer` (`track.rs:211`) is what moq-net calls + `track::Subscriber`. `name()` is the physical name on the track and + datagram halves (`track.rs:30,229`, `datagram.rs:75,240`) and the semantic + name on both `Request` types (`track.rs:130`, `datagram.rs:196`). Only + `Epoch` and `Error` are `#[non_exhaustive]`. Rust and JS already disagree + (`append_group(start)` against `appendGroup()`, group `close()` against + `finish()`, an `Error` enum against `Failure` with a `code`). +- Compression. The draft says "There is no inner header" + (`drafts/draft-lcurley-moq-e2ee.md:266`) and also that a compressed track + compresses before AEAD (`:286`), and + [the trait quest](/quest/m5/net-wrap/e2ee.md) planned an authenticated + flag and inflated size inside each sealed object. Compressing before + encrypting leaks length when one frame mixes a secret with input another + party chooses. `Config` has no profile field (`credential.rs:18-25`), + though the draft says the profile is named beside the credential and a + mismatch MUST be refused (`:88`); that is how `main` came to carry a second + derivation under the published `moq-e2ee-00` label. + +For the PR (one PR, since every item changes the derivation or the same +types, and the vectors regenerate once): + +- Broadcast binding: recommended as + `scope = context || broadcast || instance || kid`, with + `credential.produce(semantic)` and `credential.consume(semantic, instance)` + taking the name, so `path(semantic)` and the generation cannot disagree. + Add a test that a subscriber for one broadcast refuses another broadcast's + Instance and tracks under the same credential, and correct the draft's + sentence. +- Per-group keys: add the group's wire ID (its start, after + [lite-07 addresses groups by start](/quest/m2/time-addressing/lite07.md)) + to `key_info`. For datagram tracks recommend the sequence's high bits as + the key index, so one HKDF-Expand covers a run of datagrams; settle the + split in the PR and bench it with `benches/protect.rs`. Then delete + `Exhausted`, both counters, failed-open accounting, and the consuming + claim maps. The producing claims that stop a nonce repeating stay. +- Per-track wrap: make the four `generation` methods public, taking any + moq-net track and the semantic name. Raw seal and open with caller-chosen + identities stay private, as the epic decided: the claim is what makes + nonce reuse unrepresentable. +- Instance: `credential.produce(..)` mints a `moq_net::Instance`, + `generation.instance()` returns it, and `consume` takes one. Delete + `Epoch`, `epoch.json`, and `uuid`. The wrapper cannot see whether the + route was announced with that Instance (a producer's + `broadcast::Info.instance` is `None`), so say in the docs what a + subscriber sees when it was not, or have the broadcast wrapper announce + the route itself. +- Wrapper: `abort(self, Error)` everywhere; delete `create_group`; + `broadcast::Consumer::track(name)` then `.subscribe(..)` in place of + `subscribe`; rename `track::Consumer` to `track::Subscriber`; `name()` is + the semantic name everywhere, with the physical one under another name; + `Frame.plaintext` becomes `payload`; group `close()` follows + [moq-net's group API](/quest/m2/group-api.md) to `finish()`. JS takes the + same names in the same PR. Error conversion into `moq_net::Error` stays + with [the trait quest](/quest/m5/net-wrap/e2ee.md). +- Profile: `Config.profile` is a `#[non_exhaustive]` enum with one variant, + and a credential naming another profile is refused. Delete the draft's + compression rule and the Catalogs section's `.z` sibling rule; an + application compresses its own plaintext. +- Label: rename to `moq-e2ee-01` everywhere (constant, salt, labels, the + vector file and its `profile` field, `drafts/moq-e2ee-00.ts`, both + READMEs, [the epic](/quest/m5/e2ee/README.md)). While in the draft: it + still says "the group's sequence" for the nonce, `invalid_secret` has no + Rust form, and the datagram allowance is 28 bytes, not the epic's 24. +- Publish: remove `publish = false`, and restore the doc rows + [the crate move](/quest/m2/e2ee-crate.md) dropped, still marked + experimental. Submitting the draft's -01 revision to the datatracker is + the maintainer's, below. + +Public API: `moq-e2ee` and its JS twin, both unpublished until this lands. +Wire: the E2EE payload format changes from the published `moq-e2ee-00` to +`moq-e2ee-01`; the two do not interoperate and say so by profile. moq-net +and moq-lite: none. + +## Waiting + +- Maintainer: submit `draft-lcurley-moq-e2ee-01` to the datatracker once the PR merges, and add a crates.io trusted publisher for `moq-e2ee` (repository `moq-dev/moq`, workflow `release-rs.yml`, environment `publish`); both need a login an agent does not hold. Done when the datatracker shows -01 and a `release-rs.yml` run publishes `moq-e2ee` through OIDC. + +## Required + +- [End-to-end encryption is its own unpublished crate again](/quest/m2/e2ee-crate.md) - the `moq-e2ee` crate this changes and publishes +- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - the group identity the per-group key and the nonce bind + +## Related + +- [End-to-end encrypted MoQ](/quest/m5/e2ee/README.md) - the questline that builds publishers and players on this format +- [moq-e2ee implements the moq-net traits](/quest/m5/net-wrap/e2ee.md) - the later reshape onto moq-net's traits, which this shrinks diff --git a/quest/m3/ffi-exporter.md b/quest/m3/ffi-exporter.md index b7aa4a4bf51..9c097c78409 100644 --- a/quest/m3/ffi-exporter.md +++ b/quest/m3/ffi-exporter.md @@ -8,8 +8,10 @@ moq's bindings (Kotlin, Swift, Python, Go, Dart, C++, and C) come from attributes. moq-ffi shrinks to the remainder that is genuinely new API. `rs/uniffi-bindgen`, `nix/uniffi-dart-*`, the per-generator pins, and the UniFFI dependency are deleted, and the three `kixelated/uniffi-*` generator -forks are archived. Wrapper APIs do not change except where a decision below -says so. +forks are archived. The switch is a breaking release of every binding +(decided 2026-11-16): the hand-written parts of each wrapper keep their API +except where a decision below says so, and the generated names the wrappers +re-export may change. ## Plan @@ -114,14 +116,43 @@ the generated binding renames stays open, kept out of that run's m0 to m2 scope, since the binding API changes anyway in the rust2 migration expected around 2026-12-15. -Public API: moq-ffi's dependency names change, generated C type names become -CamelCase, and the generated record `MoqAudioEncoderFinished` becomes -`MoqAudioEncoderFinish` in every language; wrapper APIs do not change except -Dart's `MoqRoute.instanceId()`, which takes the exporter's name. Wire: none. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit), settling +that `Waiting` item: ✅ accept two breaks. 0.22 ships the bindings on +UniFFI, and the switch is a second breaking binding release (rejected: +announcing the binding packages as a preview that freezes at the switch; +holding the binding packages off the shared minor until the switch; counting +only the hand-written wrappers as public API, the old option B). -## Waiting +Option B's premise does not hold, which is why it was not offered again: the +generated layer is public API in most languages, counted 2026-11-16. -- Maintainer: whether the generated binding renames may land after the cut. The switch renames C types to CamelCase, `MoqAudioEncoderFinished` to `MoqAudioEncoderFinish` in every generated binding, and Dart `moq_ffi`'s `instanceId`, which would force a binding-breaking release. (A) Accept one binding-breaking release when the switch lands. (B) Count only the hand-written wrappers as public API, since they already alias these names (for example `instance()` in `dart/moq/lib/src/client.dart`), so the generated renames ship as non-breaking. I recommend B; C costs nothing either way, since no `c-v*` tag ships before the cut. +- Kotlin: 187 `typealias` lines under `kt/moq/src/jvmAndAndroidMain` onto + `uniffi.moq.*` classes, handles included (104 in `Aliases.kt`), and a test + requires one for every generated record and handle + (`SmokeTest.kt:224`). +- Dart: 157 `typedef` lines under `dart/moq/lib`. +- Swift wraps handles but has 102 `typealias` lines under + `swift/Sources/Moq` (46 in `Aliases.swift`), among them `MoqError`, + `ProtocolKind`, `AnnounceEvent`, and `ConnectionPhase`. +- C++ and the generated C are generated entirely. + +So "wrapper APIs do not change" in the bullets above, carried over from the +abandoned fork plan, is a property to measure, not assume: the switch's PR diffs each +language's public API (`sh/api-diff`) and its Impact section lists every +rename for the packages' `MIGRATE.md`. Reshapes that outlive the generator +land before the cut instead, in +[the selector quest](/quest/m2/ffi-open-selectors.md) and +[the group rename](/quest/m2/time-addressing/bindings.md); the switch keeps +those shapes. The audit's other binding findings were not picked: the `Moq` +facade Kotlin and Dart start from stays, and `MoqError`'s variants stay as +they are. + +Public API: breaking in every binding. moq-ffi's dependency names change, +generated C type names become CamelCase, the generated record +`MoqAudioEncoderFinished` becomes `MoqAudioEncoderFinish` in every language, +Dart's `MoqRoute.instanceId()` takes the exporter's name, and any other +generated name the wrappers re-export may change, each listed in the PR. +Wire: none. ## Required diff --git a/quest/m3/group-takeover.md b/quest/m3/group-takeover.md index 7f7bb7e12ad..766dfd50a5d 100644 --- a/quest/m3/group-takeover.md +++ b/quest/m3/group-takeover.md @@ -1,21 +1,71 @@ -# [L] A higher-priority group takes over an acknowledged stream in a later lite version +# [XL] A preempted group pauses and continues in lite-08, by reset or by takeover ## Goal -In a lite version after lite-07, when an open waits for credit and a lower-priority group stream's -sent data is all acknowledged, the new group takes that stream over at once: -the group stream ends one group with GROUP_END and starts another, needing no -credit. The group that lost its stream pauses and a later stream continues -it, as a YIELDED reset's group already does. moq-transport, lite-07, and older lite -versions keep reset only. +In lite-08, a group that loses its stream to a higher-priority one is paused +instead of dropped, and a later stream continues it. It loses the stream one +of two ways, designed together: the publisher resets the lowest-priority +Group Stream to free stream credit, or, when that stream's sent data is all +acknowledged, the new group takes the stream over at once with an in-band +marker and needs no credit. lite-07 and older, and moq-transport, keep the +reset as a final drop that the reader FETCHes around. ## Plan +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ paused +groups and continuations leave lite-07 +([YIELDED deferred](/quest/m2/yield-defer.md)) and are designed again here, +with takeover, as one lite-08 feature (rejected: keep YIELDED in lite-07 and +add takeover later; keep it but stop pausing on a reset without a code). +lite-07 would have frozen the half that still needs a new stream per +continuation, on a signal browsers lose. The decisions below still hold +where they don't conflict with these, with "lite-07" and "a later lite +version" read as lite-08: + +- **The marker needs a new name and encoding.** The 2026-11-12 pick below + made takeover's GROUP_END a FRAME whose `Payload Length` is 0, which + pauses the group. lite-07 now freezes a GROUP_END with that name on that + reserved value meaning the opposite: the group is whole, and here is its + exclusive end timestamp + ([time addressing](/quest/m2/time-addressing/lite07.md)). Recommended: a + distinct marker (say GROUP_PAUSE), laid out so one zero `Payload Length` + leads to either; lite-08 is a new version, so it may re-lay what follows + the zero. +- **The pause must not hang on a reset's error code.** Chromium loses a + reset that lands right after stream data and Firefox loses its code + ([browser reset reports](/quest/m4/browser-reset-reports.md)), which is + why lite-07-wip's draft told a subscriber to pause on any reset without a + code, and only JS did. Recommended: the publisher says a group is paused + on the Subscribe Stream, or with the in-band marker, and Rust and JS read + the same signal. +- **A continuation should not resend.** lite-07-wip's continuation restarted + at the reset stream's own `Frame Start`, since a reset can discard frames + the transport acknowledged, so the reader skipped what it held. Weigh a + continuation that starts where the reader says it stopped, which is what + a FETCH from a frame index already is. +- **Tracks carrying moq-transport object records** never yielded in + lite-07-wip. Say what they do here. +- **Measure first.** Before either half is built, measure a lossless reader + of more tracks than the stream cap: how often a group is preempted, and + what a drop plus FETCH (lite-07's behaviour) costs against a continuation. + The 2026-11-13 decision below asked this of takeover's round trip; it now + covers both halves. If the drop plus FETCH is close, delete this quest. + +What lite-07-wip built is in history to start from: +[moq-dev/moq#8545](https://github.com/moq-dev/moq/pull/8545) (YIELDED, +paused groups, continuations, `SubscribeAccounting.tla`), +[moq-dev/moq#8673](https://github.com/moq-dev/moq/pull/8673) (the browser +workarounds), and +[moq-dev/moq#8843](https://github.com/moq-dev/moq/pull/8843) (yielding on +relay links). The `test/stream-credit` harness stays on `main`, checking +drops. + Decided 2026-11-13 (maintainer, /quest-run): ✅ move this quest from m1 to m3 (rejected: keep it in m1 before lite-07 finalizes; delete it). [moq-dev/moq#8545](https://github.com/moq-dev/moq/pull/8545)'s YIELDED reset -already gives stream credit to the highest-priority groups under a browser's -~100-stream cap; takeover saves only the ~1 RTT a reset waits for +already gave stream credit to the highest-priority groups under a browser's +~100-stream cap (as the plain reset still does after 2026-11-16); takeover +saves only the ~1 RTT a reset waits for MAX_STREAMS, at the cost of a new wire message (GROUP_END) and multi-group streams in Rust and JS, and lite-07's finalization does not need it. Takeover comes in a later lite version only if measurements show that round @@ -71,10 +121,13 @@ subscription whose stream it takes over), since stream credit is session-wide and the waiting higher-priority group is usually another track's. `GroupRecv` rebinds the stream at each GROUP message. -Public API: none. Wire: GROUP_END and group stream takeover in a later lite -version. +Public API: `StreamError::Yielded`, or whatever replaces it, returns to Rust +and `@moq/net`. Wire: lite-08 paused groups, continuations, a takeover +marker, and multi-group streams. ## Related -- [YIELDED reset](https://github.com/moq-dev/moq/pull/8545) - the reset-based priority scheduling this would shave a round trip off -- [Finalize lite-07](/quest/m2/lite07-finalize.md) - freezes lite-07 without takeover +- [YIELDED deferred](/quest/m2/yield-defer.md) - removes paused groups and continuations from lite-07 +- [YIELDED reset](https://github.com/moq-dev/moq/pull/8545) - the lite-07-wip design this starts from +- [The lite-07 wire addresses groups by start](/quest/m2/time-addressing/lite07.md) - freezes the GROUP_END this must not collide with +- [Finalize lite-07](/quest/m2/lite07-finalize.md) - freezes lite-07 without takeover or continuations diff --git a/quest/m3/groups-never-overlap.md b/quest/m3/groups-never-overlap.md index 3a0082170c7..09898408baf 100644 --- a/quest/m3/groups-never-overlap.md +++ b/quest/m3/groups-never-overlap.md @@ -60,4 +60,6 @@ Public API: none expected. Wire: none; the draft's group rule tightens. ## Related +- [Media readers take declared ends from the group](/quest/m2/time-addressing/consumers.md) - a group's declared end (lite-07 GROUP_END) is what a reader bounds it by; this rule keeps every frame below the next start + - [An fMP4 group start never rewinds the decode timeline](/quest/m3/fmp4-group-start-tfdt.md) - a keyframe repeating its predecessor's timestamp would now continue the group; check which of its cases remain diff --git a/quest/m3/ietf-finish.md b/quest/m3/ietf-finish.md deleted file mode 100644 index d2c12cf7046..00000000000 --- a/quest/m3/ietf-finish.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] moq-transport finish interop - -## Goal - -The interop `finish` case passes on every even moq-transport draft, not only -moq-lite: each reader that joins a finished broadcast while its publisher retains it -(moq-mux's fixed linger) gets the whole ten-frame tail, natural media and catalog EOF, the exact broadcast's -withdrawal, and the publisher's later health broadcast through the same -session. Until then `interop.sh` records those cells as skipped; delete that -skip in `run_finishes` and its README note. - -## Plan - -Observed on 2026-10-22 with `just test interop --finish --all --versions ietf` -(lite passes 45/45): - -- Draft 18: late readers see the finished catalog end empty, a short - tail, or a refused joining FETCH (`publish done: internal error`). This is - the pre-draft-22 join after a finish, which - [moq-dev/moq#7306](https://github.com/moq-dev/moq/pull/7306) (merged) fixes - for Rust publishers. The rerun of these drafts since #7306 is still owed - (2026-11-12 audit); start there, and leave whatever still fails with a Rust - publisher once the head is held to - [the kept join](/quest/m3/ietf-join-pin-head.md), which owns the draft-18 - `tail` and `finish` cells with a Rust publisher. -- Draft 22: several readers time out after the withdrawal (C and C++ - on the health broadcast), JS readers see `publish done: internal error`, and - native JS refuses a "malformed request stream message" from the relay. - Reproduce each between two clients before fixing; they may be separate bugs. - -A failing reader fails its whole publisher row, since the publisher waits for -every reader's acknowledgement, so judge each cell from its reader's log. - -Public API: none. Wire: none expected; any fix that changes framing updates -its draft. diff --git a/quest/m3/ietf-hole-stall.md b/quest/m3/ietf-hole-stall.md deleted file mode 100644 index a87198763c6..00000000000 --- a/quest/m3/ietf-hole-stall.md +++ /dev/null @@ -1,46 +0,0 @@ -# [M] A moq-transport read skips a hole its max age rules out - -## Goal - -A Rust moq-transport reader, arrival or ordered, skips a missing group once -its max age makes that group impossible to arrive, and ends with the track -instead of stalling. The PR un-ignores -`a_relay_with_holes_answers_a_wide_past_range_plus_live_over_moq_transport` in -`rs/moq-net/tests/integration/subscribe_ranges.rs`, which then passes on -drafts 18 and 22, and drops its `sh/gh/test-inventory.allow` entry. - -## Plan - -The rule (maintainer, on [moq-dev/moq#8762](https://github.com/moq-dev/moq/pull/8762)): -do as the ordered consumer does, and skip a hole once max age renders it -impossible to arrive. Reuse the existing stale verdict (`TrackState::drifted`, -which already judges an uncached sequence by its successor's reach, and the -give-ups `Misses::expire` records); don't add a second mechanism. - -What #8762 measured, with groups 0 to 9 stamped within a second, group 4 -aborted, group 7 never produced, a 60s subscriber budget, and live group 10 -at 100s, read through an origin (`[groups(0..8), live]`, direct or through a -relay): - -- The moq-transport copy's own cursor reaches the feed's end with nothing - waiting and both holes already given up as stale (`given_up = {4..5, 7..8}`). -- The reader the origin hands out still never ends: the arrival reader stalls - after every existing group, and the ordered reader stalls at group 4. So the - copy's stale verdict is lost in the front's reader (`rs/moq-net/src/model/resume.rs`: - `exhausted`, `poll_end`, and how a copy's given-up runs reach the logical - reader). lite-07 takes the same path and ends, because its holes arrive as - SUBSCRIBE_DROP. -- A live-only range with a finite budget already ends on moq-transport. - -Fix it where the front's reader settles a copy's runs, so both readers count a -copy's stale give-ups. Run `/verify-resume` when the change touches -`resume.rs`. - -Not in scope: with no max age at all (subscriber budget `None`), nothing makes -a moq-transport hole impossible, since moq-transport egress never sends the -publisher's max age (`Info::max_age` in `rs/moq-net/src/model/track.rs`), so -the reader waits by design, as the ordered reader's docs say. - -## Related - -- [moq-transport FETCH answers ranges over known holes](/quest/m4/ietf-range-fetch.md) - widens what a range FETCH answers diff --git a/quest/m3/ietf-join-pin-head.md b/quest/m3/ietf-join-pin-head.md index f11a7446644..8ed1b2c990e 100644 --- a/quest/m3/ietf-join-pin-head.md +++ b/quest/m3/ietf-join-pin-head.md @@ -27,10 +27,6 @@ and the late FETCH gets a loud refusal (accepted by its quest's Plan). - Test: finish then drop the producer, then a late joining FETCH on draft 18 still gets the head. - Rerun the draft-18 interop `tail` and `finish` cells with the Rust - publisher, as [IETF finish](/quest/m3/ietf-finish.md) asks. + publisher. Public API: none. Wire: none. - -## Related - -- [IETF finish](/quest/m3/ietf-finish.md) - owns the interop cells diff --git a/quest/m3/lite-finished-across-updates.md b/quest/m3/lite-finished-across-updates.md deleted file mode 100644 index a480d888f24..00000000000 --- a/quest/m3/lite-finished-across-updates.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] A group read to its FIN stays finished across updates - -## Goal - -A lite-07 subscriber that read a group's stream to its FIN never records that -group stale, however many SUBSCRIBE_UPDATEs it sent since, so the publisher -never serves it again or names it in another drop, as the draft promises. - -## Plan - -Found 2026-11-10 by the subscribe model ([moq-dev/moq#8447](https://github.com/moq-dev/moq/pull/8447)): -`rs/moq-net/verify/subscribe/StreamWins.cfg` breaks `StreamWins`. The -subscriber reads a group whole, then sends an update; the group goes stale -before the publisher sees the FIN acknowledged, so it is named in a stale drop -under that update. `Tail::updated` in `rs/moq-net/src/tail.rs` already cleared -`Tail::finished`, so once the cache evicted the group the subscriber records -it stale and owes it again: the publisher resends it whole, or drops it again -on every later update. `residual_a_stale_unacknowledged_fin_drops_and_resends_a_served_group` -in `lite/publisher.rs` pins the publisher's half; -`a_finished_group_wins_over_a_late_stale_drop_once_evicted` in -`lite/subscriber.rs` pins the subscriber's. - -Decided 2026-11-10 (maintainer, /quest-plan): ✅ the subscriber keeps -`Tail::finished` across updates, bounded by forgetting entries below the -tail's floor, and `js/net/src/lite/subscriber.ts` does the same (rejected: the -publisher skipping the drop for a stream that expires after its FIN, which -leaves a subscriber whose stream was lost waiting out its grace period). The -model passes all four rules with this change (about 1.9M states). - -Flip both tests, move `StreamWins` into `SubscribeAccounting.cfg`, delete -`StreamWins.cfg`, and update the `verify-subscribe` skill. - -Caused by: [moq-dev/moq#7670](https://github.com/moq-dev/moq/pull/7670), which -added budget-qualified stale drops and the per-update `finished` record. - -Public API: none. Wire: none. diff --git a/quest/m3/obs-moq-video/adapter.md b/quest/m3/obs-moq-video/adapter.md index ebe3bbefebc..5f1b3cbe0a3 100644 --- a/quest/m3/obs-moq-video/adapter.md +++ b/quest/m3/obs-moq-video/adapter.md @@ -9,7 +9,7 @@ One opt-in Use MoQ encoders choice publishes OBS video and audio through moq-vid - Register an internal OBS video encoder, backed by `moq_video::encode::Sink`. Retain `MoQOutput::EncodedPacket` and existing catalog handling. Do not replace the output with raw publication: OBS's encoded-output flag is output-wide, and bypassing it would duplicate A/V integration. - Drive the codec-only `video.Encoder` rather than adding an encoder type here. It has owned handles and packet draining; `video.Producer` couples encoding to publication and is not the packet adapter. - Start with H.264 by default and HEVC where supported. Keep reordering disabled; resolve Annex-B headers/decoder configuration, DTS/PTS and drain semantics explicitly, since Rust encoded output carries only timestamp, payload, and keyframe flag. Do not advertise unsupported AV1 encoding. -- Use the shared Low latency, Balanced, and Quality presets with bitrate separate, defaulting to Balanced: `moq_video::encode::Preset` in, `Applied` (the preset and controls that took effect) out for Stats. Neither reaches moq-ffi yet, so carry both through it and its bindings. Expose a single Use MoQ encoders option only once audio and video adapters both work. Retain the existing OBS encoder selection as an explicit alternative; do not silently switch back to OBS codecs after a MoQ codec failure. +- Use the shared Low latency, Balanced, and Quality presets with bitrate separate, defaulting to Balanced: `moq_video::encode::Preset` in, `Applied` (the preset and controls that took effect) out for Stats. Neither reaches moq-ffi yet, so carry both through it and its bindings. Since 2026-11-16 (maintainer, /quest-plan of the pre-cut audit) [the unused-API sweep](/quest/m2/unused-api/media.md) makes `Applied`, the `applied()` accessors, and `Config::preset` crate-private before the cut, because nothing outside moq-video used them; this quest publishes them again in the shape the Stats panel needs, with the `cut` capability split from the preset report. Expose a single Use MoQ encoders option only once audio and video adapters both work. Retain the existing OBS encoder selection as an explicit alternative; do not silently switch back to OBS codecs after a MoQ codec failure. - Establish bounded submission/packet queues, explicit raw-frame drop behavior, thread confinement, cancellation, late completion, device loss, resize and color metadata. Never block OBS's graphics thread on network backpressure. The CPU path is a correctness/fallback baseline; platform quests establish accelerated input. - The audio side is the internal `moq_opus` encoder, whose settings are `bitrate` (kbps) and `preset` (`low_latency`, `balanced`, `quality`). Use MoQ encoders creates it in place of `ffmpeg_opus`; it is the only audio choice the combined mode offers until AAC encoding lands. - Test rejection, saturation, drain, stop during encode, delayed completion, and repeated start/stop. Validate real decoded pixels and audio continuity, matched timestamps, preset reporting, and frame-to-packet latency. Validate the new binding docs, feature combinations, package dependencies and native plugin linking. diff --git a/quest/m3/one-port/rtc-feed.md b/quest/m3/one-port/rtc-feed.md index ed8a765f039..36473bd16f6 100644 --- a/quest/m3/one-port/rtc-feed.md +++ b/quest/m3/one-port/rtc-feed.md @@ -80,7 +80,10 @@ returns `None` once the listener is gone. Things to watch: the server config is `Clone` today and a receiver is not, so the fed socket may belong in the server's constructor rather than the -config. The fed mux has nothing to bind lazily, and a dropped feed should +config. Since 2026-11-16 (maintainer, /quest-plan of the pre-cut audit) +[the bind at startup](/quest/m2/webrtc-bind.md) settles this before the cut: +the server becomes `Server::bind(config)`, and that PR picks where the +socket lives and writes it here, so the feed is an addition, not a break. The fed mux has nothing to bind lazily, and a dropped feed should fail the server loudly rather than idle. Noted 2026-10-31 from [moq-dev/moq#7095](https://github.com/moq-dev/moq/pull/7095): diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 8c7594c4df1..866d733ba58 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -58,26 +58,44 @@ The [feature review](/quest/m3/release/feature-review.md)'s first pass later removed; judge each here. Recommended: drop each unless a consumer turns up. -- moq-ffi's `MoqTrackProducer::largest` and `MoqBroadcastConsumer::closed`, - added for browser parity ([moq-dev/moq#7304](https://github.com/moq-dev/moq/pull/7304)) - just before WASM support was removed - ([moq-dev/moq#7475](https://github.com/moq-dev/moq/pull/7475)); only - wrappers and tests call them. -- The byte-stream rung of `MoqMediaProducer`'s simulcast ladder - ([moq-dev/moq#7699](https://github.com/moq-dev/moq/pull/7699)), raised by - an automated reviewer; nothing passes a stream producer as `lower`, and it - changed `lower`'s type in every binding. Recommended: keep, since reverting - is another break. -- `moq_mux` container consumer's `set_wait`, a third delay knob beside - `Delay { min, max }`; native audio sets it to the `min` it already passes. -- `moq_transcode`'s `active::Rendition::applied()` and - `moq_video::encode::Applied`, with no caller outside their crates. -- moq-sock's ICMP error queue, `qmux::Config::fixed_receive_window` (used only - by the unconsumed p2p module), moq-webrtc's `p2p` feature, and moq-relay's - `stun` feature, none of which a shipped build uses. -- `moq_tokio`'s `TcpTls::new` under `cfg(all(feature = "tcp", not(feature = - "_certs")))`, a cfg that can never hold (`tcp` enables `_certs`) and whose - arity no longer matches its caller: delete it. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ every +unused public item is removed or hidden before the cut, in +[one sweep per area](/quest/m2/unused-api/README.md), each re-checked for a +downstream caller first (rejected: judging them after m2 lands). That audit +re-read this list, so it is settled: + +- moq-ffi's `MoqTrackProducer::largest` and `MoqBroadcastConsumer::closed` + stay: both have callers (the first pass's claim fell on a re-read). +- The byte-stream rung of `MoqMediaProducer`'s simulcast ladder stays: + removing it changes `lower`'s type in every binding again. +- `moq_mux`'s `set_wait` folds into `Delay` + ([the hole wait](/quest/m2/delay-hole-wait.md)). The first pass was wrong + that native audio sets it to the `min` it already passes: it passes its + live estimate, which that quest gives a home. +- `Rendition::applied()` and `moq_video::encode::Applied` go in + [the media sweep](/quest/m2/unused-api/media.md); moq-sock's ICMP error + queue and `qmux::Config::fixed_receive_window` in + [the transport sweep](/quest/m2/unused-api/transport.md). +- Already gone: `TcpTls::new` + ([moq-dev/moq#8852](https://github.com/moq-dev/moq/pull/8852)), and the + `p2p` and `stun` features + ([moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771)). + +What that audit learned, for the run after m2 and the next cut's: + +- `just api-diff` lists breaks only for Rust, and nothing for a surface it + marks `new`. Most of what the audit changed was in surfaces never + published, whose whole API is free to change: diff their source by hand. +- Ask of each export who calls it outside its crate and tests, with the + grep in the finding: the sweep's four children list what had none. Kixel + and moq.pro pin `main` and call API nothing here does, so check them too. +- Shapes that recurred: a sentinel inside a value (a huge number for "no + limit", a null that means zero in one record and unlimited in another), + a closed enum the bindings switch over exhaustively, two names for one + thing across Rust and JS, and a config key the code reads in two places. +- Judge what is absent as well: a missing piece that would break the shape + when added later (a listing with no kind, a catalog with one version for + every entry) is cheaper now than a removal is later. ## Required diff --git a/quest/m3/release/c-publish.md b/quest/m3/release/c-publish.md index 44504faca90..15b83bbfd6f 100644 --- a/quest/m3/release/c-publish.md +++ b/quest/m3/release/c-publish.md @@ -11,13 +11,17 @@ archive instead of the hand-written one. The generated C line proves the same cases with the built archive before publication. This quest proves registry/release delivery after publication -and records the artifact versions and results. The hand-written `moq-c` -ships at the next cut (decided 2026-10-25), so the generated package -supersedes a published one; its source stays until -[c-retire](/quest/m3/release/c-retire.md). On `main` the two read 0.7.0 -(`rs/moq-c/Cargo.toml`) and 0.8.0 (`c/moq/VERSION`), but the cut's -`just version` sets both to the shared minor (`sh/version.py`), so neither -number survives it and both `moq-c` lines carry the same version. +and records the artifact versions and results. + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit, replacing +2026-10-25's "the hand-written `moq-c` ships at the next cut"): the +hand-written API ships at the cut as `libmoq` 0.22, its final line +([the C crate's name](/quest/m2/libmoq-name.md)), and `moq-c` stays +unpublished until this quest. So this is the first `moq-c` anyone can +install: it supersedes no published `moq-c`, and the published package it +replaces for C users is `libmoq`, whose source stays until +[c-retire](/quest/m3/release/c-retire.md). Its version is the shared minor +of the cut that ships it (`sh/version.py`). The smoke client moves here rather than with [C consumers](/quest/m3/c/consumers.md) because it checks a published archive, diff --git a/quest/m3/release/c-retire.md b/quest/m3/release/c-retire.md index 2fd2f0d70dc..bdb6d645c72 100644 --- a/quest/m3/release/c-retire.md +++ b/quest/m3/release/c-retire.md @@ -1,36 +1,37 @@ -# [S] Retire the hand-written moq-c crate +# [S] Retire the hand-written libmoq crate ## Goal -The hand-written C crate is gone: its source, workflows, and docs that only -served it are deleted once the generated `moq-c` publishes. The generated -`moq-c` package's `MIGRATE.md` tells C users how to move. +The hand-written C crate, `libmoq`, is gone: its source, workflows, and docs +that only served it are deleted once the generated `moq-c` publishes. The +generated `moq-c` package's `MIGRATE.md` tells C users how to move, and the +last `libmoq` on crates.io and the last `libmoq-v*` release say `moq-c` +replaces them. ## Plan -- #4288 renamed libmoq to `moq-c` (`rs/moq-c`); this quest deletes that - hand-written crate. -- Decided 2026-10-25 (maintainer): the hand-written `moq-c` ships at the - next cut, so it is a published package when the generated one replaces it - (0.7.0 and 0.8.0 on `main`; `just version` sets both to the cut's shared - minor). - Its `MIGRATE.md` history carries into the generated package. This replaces - the 2026-10-20 premise that it never published. -- `rs/moq-c/native-libs/` serves the generated package too, and +- Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): the + hand-written API ships at the cut as `libmoq` 0.22, its final line, and + `moq-c` names only the generated package + ([the C crate's name](/quest/m2/libmoq-name.md)). This replaces the + 2026-10-25 decision that it ships as `moq-c`, and with it the code-free + `rs/libmoq` stub and its two quests: there is no stub at this cut. +- So the crate this deletes is `rs/libmoq`. Before its source goes, publish + the pointer: a final `libmoq` patch whose README and description name + `moq-c`, as [retired names](/quest/m3/release/retired-names.md) does for + the other renames, since the hand-written crate is a published package + when the generated one replaces it. Its `MIGRATE.md` history carries into + the generated package. +- The crate's `native-libs/` serves the generated package too, and `cpp/moq/cmake/moq-ffi.cmake` serves both C++ and C. Move them to a neutral home shared by both packages before deleting the crate, update every - reader of either path (`rg 'moq-c/native-libs|moq-ffi\.cmake'`), and check + reader of either path (`rg 'native-libs|moq-ffi\.cmake'`), and check that the installed C and C++ CMake configs still link the native libraries. -- `AGENTS.md`'s Cross-Package Sync table keeps the hand-written crate beside - `c/moq` while it ships. Drop `rs/moq-c` from the `rs/moq-ffi` row and point - the `rs/moq-c` C ABI row at the generated `c/moq` header (``). -- Deleting the crate removes its four `moq-c-` archives from the +- Deleting the crate removes its four per-target archives from the Nightly size report, which `sh/size/report.py` refuses as missing. Add a way to retire one artifact's series without dropping the rest of the history (decided 2026-10-28, from [moq-dev/moq#7132](https://github.com/moq-dev/moq/pull/7132)), rather than deleting every `nightly-size-history` artifact. -- The code-free `rs/libmoq` stub left under the old name is - [Retire the libmoq stub](/quest/m3/release/libmoq-retire.md)'s, separately. ## Required @@ -40,4 +41,4 @@ served it are deleted once the generated `moq-c` publishes. The generated ## Related -- [Retire the libmoq stub](/quest/m3/release/libmoq-retire.md) - deletes the `rs/libmoq` stub under the old name +- [The hand-written C API ships as libmoq](/quest/m2/libmoq-name.md) - the name this crate ships under until then diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 5abb8c04ad9..097f453f8dd 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -209,9 +209,34 @@ after [moq-dev/moq#7942](https://github.com/moq-dev/moq/pull/7942) until the re-run fixed them. Run those browser checks by hand on the cut tree, along with the suites above. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + +- ✅ The cut waits on [the relay's memory growth](/quest/m2/relay-memory.md) + by name: the chat scenario's relay uses about 17% more memory on `main` + than on `release`, and 0.22 is not announced with that unexplained + (rejected: cutting and investigating after). +- ✅ The cut waits on [the rind 0.4 adapters](/quest/m0/rind-adapters.md) + ([moq-dev/moq#8432](https://github.com/moq-dev/moq/pull/8432)), so the + `UnsupportedCpu` error that exists only for rind 0.3 is never published. +- ✅ [The FFI abort](/quest/m1/ffi-abort-unwanted.md) lands first: it adds a + method to an existing binding object, which the API diff counts as a + break once 0.22 is published. +- ✅ End-to-end encryption does not publish at this cut + ([its own unpublished crate](/quest/m2/e2ee-crate.md)), so `moq-e2ee` is + no longer a retired name, and the paragraph above about publishing a + pointer above 0.0.25 no longer applies: the name is held for + [the finished format](/quest/m3/e2ee-format.md). +- ✅ The hand-written C API publishes as `libmoq` 0.22 + ([its final line](/quest/m2/libmoq-name.md)), reversing 2026-10-25, so the + cut gate's "hand-written `moq-c`" below reads `libmoq`, and the two + quests for a code-free `libmoq` stub were deleted. + ## Required - [Breaking release readiness](/quest/m2/README.md) - code, protocol and package proofs +- [Relay memory](/quest/m2/relay-memory.md) - the relay's memory growth since `release` is fixed or recorded before 0.22 is announced +- [rind 0.4 adapters](/quest/m0/rind-adapters.md) - `UnsupportedCpu`, which exists only for rind 0.3, never publishes +- [FFI abort](/quest/m1/ffi-abort-unwanted.md) - a new method on an existing binding object is a break once 0.22 is out - [Migration audit](/quest/m3/release/migrate-audit.md) - every break on the cut PR has its MIGRATE.md entry - [API shape review](/quest/m3/release/api-review.md) - every new or changed public API was reviewed for a better shape, and approved changes landed - [Feature review](/quest/m3/release/feature-review.md) - every major work line since the last release was judged end to end, and its follow-ups landed diff --git a/quest/m3/release/dart-publish.md b/quest/m3/release/dart-publish.md index 0dd1ffd8af9..59157d1684b 100644 --- a/quest/m3/release/dart-publish.md +++ b/quest/m3/release/dart-publish.md @@ -17,6 +17,14 @@ unproven. Trusted-publishing configuration and checks of already-published artifacts can proceed independently; cutting the tag cannot. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): Dart +ships as experimental. The `moq` wrapper keeps its own 0.x version instead +of the shared 0.22 minor, and `moq_ffi`'s generated sources are built at +publish time rather than checked in +([Dart is experimental](/quest/m2/dart-experimental.md)). So the tag this +quest cuts is the wrapper's own next 0.x, and the clean-machine check below +must also find `moq.dart` inside the published `moq_ffi` archive. + - Trusted publishing for `moq` is fixed: its repository field read `moq/moq-dev` (owner and name swapped), so pub.dev refused the `moq-dart-v0.1.1` tag's token. On 2026-11-11 the maintainer set it to diff --git a/quest/m3/release/demo-sockets-deploy.md b/quest/m3/release/demo-sockets-deploy.md deleted file mode 100644 index 5ec3007fe97..00000000000 --- a/quest/m3/release/demo-sockets-deploy.md +++ /dev/null @@ -1,51 +0,0 @@ -# [S] moq.dev's hosted demos run on sockets - -## Goal - -moq.dev's hosted MoQ Boy and CARLA demos work with the socket versions the -cut publishes: the relays accept lite-07, the auth server and the emulator's -and worker's tokens carry the socket grants, and the site builds `` -from `demo/boy` without a viewer prefix. - -## Plan - -Decided 2026-11-06 (maintainer, follow-up planning in `/quest-complete`): the -hosted demos ship from `release`, so they switch when the cut lands. Not -chosen: an m2 cut gate; deploying now in m0. - -Main's moq-boy ([moq-dev/moq#8008](https://github.com/moq-dev/moq/pull/8008)) -and CARLA ([moq-dev/moq#8011](https://github.com/moq-dev/moq/pull/8011)) talk -over sockets, which need lite-07 (or moq-transport) on every hop, so the -sockets `` can't connect until moq.dev's relays accept it. -The grants below are the server and client socket roles that -`demo/relay/prod.toml` documents. - -The cut publishes no MoQ Boy package -([moq-dev/moq#8446](https://github.com/moq-dev/moq/pull/8446), 2026-11-10): -the `moq-boy` crate is `publish = false` and the element lives in the private -`demo/boy` (`@moq/demo-boy`), which has no `exports`. The site builds the -element from its `moq` submodule, and on 2026-11-12 it still lists the -`moq/js/moq-boy` workspace and imports `@moq/boy/element`, both gone at the -cut. The demo hosts keep building the emulator from the flake's `moq-boy` -package. - -## Waiting - -- Maintainer: after the cut publishes, deploy moq.dev: - - Relays accept lite-07 in `listen.version` (the opt-in - `moq-lite-07-wip` until the cut finalizes it). - - The auth server's anonymous rules match `demo/relay/prod.toml`: publish - `demo/boy/.client/*` and `demo/carla/.client/*`, subscribe their - `.server/**`, and no `demo/viewer/**`. - - The emulator's token publishes `demo/boy/.server/` and subscribes - `demo/boy/.client/**`; the CARLA worker's token publishes its trucks' - `.server/` endpoints and subscribes `demo/carla/.client/**`. - - The site's `moq` submodule moves to the cut, its `moq/js/moq-boy` - workspace becomes `moq/demo/boy`, and `src/components/boy.tsx` imports the - element from there (`src/element.tsx`) and drops `prefix-viewer`, which - the element no longer reads. - - Then open both demos in a browser and drive a truck and a game; an agent can - drive Chrome for that check. - -Public API: none. Wire: none. diff --git a/quest/m3/release/demos-deploy.md b/quest/m3/release/demos-deploy.md new file mode 100644 index 00000000000..68690fb71f7 --- /dev/null +++ b/quest/m3/release/demos-deploy.md @@ -0,0 +1,62 @@ +# [S] moq.dev's hosted demos run the cut + +## Goal + +moq.dev's hosted MoQ Boy and CARLA demos work with the versions the cut +publishes. Neither uses socket endpoints: viewers and drivers publish their +input as broadcasts under the anonymous viewer prefix, so the auth server +and the tokens keep the grants that format needs, and the site builds +`` from `demo/boy`. + +## Plan + +Decided 2026-11-06 (maintainer, follow-up planning in `/quest-complete`): the +hosted demos ship from `release`, so they switch when the cut lands. Not +chosen: an m2 cut gate; deploying now in m0. + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ the +demos go back to their format before sockets, since +[socket endpoints leave moq](/quest/m2/sockets/README.md) (rejected: the +2026-11-06 plan, which deployed socket grants and lite-07 on every hop for +them). This quest was "moq.dev's hosted demos run on sockets" until then. + +What that changes here: MoQ Boy on `release` already speaks the restored +format ([its quest](/quest/m2/sockets/boy.md)), so the hosted relays need no +new version for it and the auth server keeps `demo/viewer/**`. CARLA was +added on `main` after `release` branched; its restored format +([its quest](/quest/m2/sockets/carla.md)) uses the same grant. Read both +quests' merged PRs for the grants they settled before deploying, since each +re-decides its grant rather than restoring it blindly. + +The cut publishes no MoQ Boy package +([moq-dev/moq#8446](https://github.com/moq-dev/moq/pull/8446), 2026-11-10): +the `moq-boy` crate is `publish = false` and the element lives in the private +`demo/boy` (`@moq/demo-boy`), which has no `exports`. The site builds the +element from its `moq` submodule, and on 2026-11-12 it still lists the +`moq/js/moq-boy` workspace and imports `@moq/boy/element`, both gone at the +cut. The demo hosts keep building the emulator from the flake's `moq-boy` +package. + +## Waiting + +- Maintainer: after the cut publishes, deploy moq.dev: + - The auth server's anonymous rules match `demo/relay/prod.toml` as the two + demo quests leave it: publish under the viewer prefix (`demo/viewer/**` + unless a demo quest narrowed it), and no `.client/*` or `.server/**` + socket grant. + - The emulator's token publishes its game under `demo/boy/` and subscribes + the viewer prefix; the CARLA worker's token publishes `carla/**` and + subscribes `viewer/carla/**`, each under the relay's `demo` root. + - The site's `moq` submodule moves to the cut, its `moq/js/moq-boy` + workspace becomes `moq/demo/boy`, and `src/components/boy.tsx` imports + the element from there (`src/element.tsx`), keeping `prefix-viewer`. + + Then open both demos in a browser and drive a truck and a game; an agent can + drive Chrome for that check. + +Public API: none. Wire: none. + +## Required + +- [MoQ Boy viewers publish their commands again](/quest/m2/sockets/boy.md) - settles the emulator's and viewers' grants this deploys +- [CARLA drivers publish their controls again](/quest/m2/sockets/carla.md) - settles the worker's and drivers' grants this deploys diff --git a/quest/m3/release/feature-flags.md b/quest/m3/release/feature-flags.md index e24c7661691..2975eb1e483 100644 --- a/quest/m3/release/feature-flags.md +++ b/quest/m3/release/feature-flags.md @@ -58,8 +58,11 @@ judged, so this pass reads only the difference: build); moq-cli's `s3`, `gcs`, and `azure`. - Large HTTP stacks a library embedder owns: moq-auth's `client` (reqwest) and `serve` (axum), moq-hls's and moq-webrtc's `server` (axum). - - moq-crypto's `sign`, `e2ee`, `cpu`, and `provider`: they keep moq-net out - of moq-quic's graph, a layering need rather than a trim. + - moq-crypto's `endpoint`, `cpu`, and `provider`: they keep moq-net out + of moq-quic's graph, a layering need rather than a trim. Corrected + 2026-11-16: `sign` left in + [moq-dev/moq#8855](https://github.com/moq-dev/moq/pull/8855), and `e2ee` + leaves with [the crate move](/quest/m2/e2ee-crate.md). - `serde` in kio, moq-pattern, and moq-crypto: an optional dependency, by ecosystem convention. - moq-video's `capture`: device I/O the bindings deliberately leave to the diff --git a/quest/m3/release/feature-review.md b/quest/m3/release/feature-review.md index 36a2c2159df..c8cc392ed96 100644 --- a/quest/m3/release/feature-review.md +++ b/quest/m3/release/feature-review.md @@ -44,6 +44,38 @@ every line the first pass would ship as is ships as is, and its follow-ups carry the maintainer's picks; the VR catalog fields stay, since a VR demo ([moq-dev/moq#6373](https://github.com/moq-dev/moq/pull/6373)) reads them. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ the +2026-11-14 pick is reopened. The maintainer asked for an exhaustive audit of +the same window before the 0.22 announcement, with every addition judged for +a long-term purpose and a caller, and the lite-07 draft audited for what it +could lose. It covered `d0b086e71` to `6ac78b68ee` (about 3,800 commits): +a digest of moq.pro's and Kixel's roadmaps, fifteen read-only reviewers, and +a 15-round interview. Its decisions are m2 quests, listed in +[m2's Plan](/quest/m2/README.md) under the same date. Of the lines the +first pass would ship as is, some left (YIELDED continuations, socket +endpoints, video `warmup`, the vendored WebRTC stack, the unused exports) +and more were renamed or reshaped. + +The delta pass now starts from `6ac78b68ee`, and its second bullet below is +done: the gateway lifecycles, CLI flags, JSON snapshots, the codec split, +and moqsink were read in full by that audit. + +What the 2026-11-16 audit learned, beyond the first pass's list below: + +- Give every reviewer the downstream roadmaps as a digest, with what each + project stopped needing. "Nobody planned, anywhere" was the strongest + finding, and "a named consumer needs it" the strongest defence. +- Ask what a feature costs when unused. Several of the largest findings + were costs everyone pays for a feature few use: a record before every + frame on a relay link, memory per connection, and a pause that depends on + a signal browsers drop. +- A feature whose other half moved past the cut does not freeze alone: + defer both halves together (YIELDED continuations and takeover). +- Check a PR's state when the question is asked, not when the inventory was + taken: the audit asked about a PR as open ten hours after it merged. +- Reviewers' counts still need a re-run before they become quests: three + more fell (110 sites that were 108, 127 that were 3, 119 that were 185). + The delta pass: - Inventory `git log --first-parent ce616b52c..origin/main` by area, and the diff --git a/quest/m3/release/libmoq-final-release.md b/quest/m3/release/libmoq-final-release.md deleted file mode 100644 index bd48837587f..00000000000 --- a/quest/m3/release/libmoq-final-release.md +++ /dev/null @@ -1,20 +0,0 @@ -# [XS] The final libmoq release is the stub - -## Goal - -The newest `libmoq` on crates.io is the code-free stub that `main`'s -`rs/libmoq` holds, whose README points at `moq-c`. Since #4738 publishing runs -only from `release`, so the condition clears at the next `main`-to-`release` -cut, which must take `main`'s stub for `rs/libmoq` at a version above -crates.io's current `max_version`. `main`'s stub is at 0.6.12, below versions -crates.io already holds as full crates, so the cut bumps it or the stub never -publishes. - -This quest tracks a condition outside the repository. When it holds, delete -this quest and every `Required` entry that links it. - -## Plan - -As of 2026-10-25 the newest release is libmoq 0.6.18 (2026-10-23), still cut -from `release`'s full crate, not the stub; patch releases keep raising it. Check with -`curl -s https://crates.io/api/v1/crates/libmoq` for a newer `max_version`. diff --git a/quest/m3/release/libmoq-retire.md b/quest/m3/release/libmoq-retire.md deleted file mode 100644 index 5b35874910b..00000000000 --- a/quest/m3/release/libmoq-retire.md +++ /dev/null @@ -1,18 +0,0 @@ -# [XS] Retire the libmoq stub - -## Goal - -`rs/libmoq` is gone and the `libmoq` crate is no longer published. Its last -release, a code-free crate whose README points at `moq-c`, stays on crates.io -for anyone still resolving the old name. - -## Plan - -- Delete `rs/libmoq` and its workspace member once that release is on - crates.io, so release-plz never publishes it again. -- Grep for any remaining `libmoq` that names the crate rather than the - `libmoq.a` file. - -## Required - -- [The final libmoq release is the stub](/quest/m3/release/libmoq-final-release.md) - the published crate points at `moq-c` before the source goes diff --git a/quest/m3/release/npm-first-publish.md b/quest/m3/release/npm-first-publish.md index a256a44245d..8d88945463d 100644 --- a/quest/m3/release/npm-first-publish.md +++ b/quest/m3/release/npm-first-publish.md @@ -2,12 +2,12 @@ ## Goal -`@moq/clock`, `@moq/libav`, `@moq/stats`, `@moq/ui`, and `@moq/video` exist on npm, each with trusted +`@moq/clock`, `@moq/libav`, `@moq/stats`, and `@moq/video` exist on npm, each with trusted publishing attached to `moq-dev/moq` and the `npm` Environment. The cut's release workflow can then publish their real versions. A maintainer does this by hand. Delete this quest once the checks pass: -- `npm view @moq/` resolves for all five, and the package settings show +- `npm view @moq/` resolves for all four, and the package settings show the `moq-dev/moq` trusted publisher with Environment `npm`. ## Plan @@ -26,6 +26,11 @@ at 0.1.0 with a release script, and the name returns 404. Nothing published depends on it, so a miss fails only its own publish. All five still returned 404 on 2026-11-12. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): `@moq/ui` +becomes a workspace-private package bundled into watch and publish +([its quest](/quest/m2/ui-private.md), which the cut waits on), so its name +is not claimed and it left this list, which had five names. + Decided 2026-10-22 (maintainer): publish a minimal `0.0.0` placeholder (README only) per name to claim it, then attach the trusted publisher. The cut publishes the real `0.1.0` (`0.0.1` for `@moq/stats`) through the workflow with provenance, so no diff --git a/quest/m3/release/retired-names.md b/quest/m3/release/retired-names.md index 8d40bd1a832..7395a8027d7 100644 --- a/quest/m3/release/retired-names.md +++ b/quest/m3/release/retired-names.md @@ -12,11 +12,18 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut): ✅ pointer stubs for renames, deprecation for removals (rejected: deprecation only; doing nothing). -- Pointer stub, as `libmoq` has: `moq-rtc` (renamed to `moq-webrtc` in - [moq-dev/moq#8122](https://github.com/moq-dev/moq/pull/8122)) and - `moq-e2ee`. crates.io's newest `moq-e2ee` is a full 0.0.25 crate published - 2026-11-11, not the stub an earlier plan assumed (the stub was 0.0.22), so - the pointer publishes above 0.0.25. +- Pointer stub: `moq-rtc` (renamed to `moq-webrtc` in + [moq-dev/moq#8122](https://github.com/moq-dev/moq/pull/8122)). +- Not retired (decided 2026-11-16, maintainer, /quest-plan of the pre-cut + audit, replacing the pointer this list planned for both): + - `moq-e2ee` is a crate again and stays unpublished until + [its finished format](/quest/m3/e2ee-format.md) publishes it, so it gets + no pointer. crates.io keeps the full 0.0.25 (2026-11-11) as its newest + until then; don't publish a stub over it. + - `libmoq` is the name the hand-written C API ships under at 0.22 + ([the C crate's name](/quest/m2/libmoq-name.md)), so it gets no pointer + at this cut. Its pointer at `moq-c` comes when the generated package + publishes ([c-retire](/quest/m3/release/c-retire.md)). - Deprecate with a message: `moq-room` and `moq-native` ([moq-dev/moq#8450](https://github.com/moq-dev/moq/pull/8450)), `moq-binary`, and `moq-boy` with `@moq/boy`, which diff --git a/quest/m3/rtc-pacing.md b/quest/m3/rtc-pacing.md index 62b21304542..a62e924fc22 100644 --- a/quest/m3/rtc-pacing.md +++ b/quest/m3/rtc-pacing.md @@ -33,9 +33,18 @@ WHEP enforcement needs it and nobody owned it. its video send buffer (`rs/moq-webrtc/src/session.rs`), so charging needs a hook on that path. Decided 2026-10-30 (maintainer): add it to the vendored str0m ([WebRTC epic](/quest/m3/webrtc/README.md)) rather than upstream. + Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): + moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md), so + there is no vendored copy to add the hook to. Start by finding out + whether str0m 0.25's public API can charge or withhold a resend (its RTP + mode, or turning off its own NACK handling and serving resends from a + buffer moq-webrtc keeps). If not, the hook is a change inside str0m: + write the report for [upstream reports](/quest/m4/upstream-reports.md). + If the cap cannot wait for upstream, bring the evidence to the maintainer, + who decides whether this fix is the one worth a fork. - Decided 2026-10-30 (maintainer): the pacer is moq-congestion's, made public and extended with payload credit here, so moq-quic and moq-webrtc share one - pacer; the vendored str0m's leaky pacer is deleted. + pacer. str0m's own leaky pacer stays unused, as it is today. - A per-session rate handle sets the cap and accepts live updates. The pacer counts media; the docs advise headroom for RTP overhead. - WHIP ingest follow-ups (2026-10-31, from @@ -60,9 +69,12 @@ Public API: a rate handle on moq-webrtc's WHEP server. Decided 2026-10-30 (maintainer): `whep::accept` takes the same shape as `whip::accept`, a `whep::Request` struct, rather than a fifth argument. That struct exists, `#[non_exhaustive]`, so this quest adds a `rate: Option` -field to it, as `whip::Request` has, never a +field to it, never a `with_rate` setter (2026-11-07, maintainer, /quest-plan from the API sweep -of open PRs and remaining quests). The handle +of open PRs and remaining quests). `whip::Request` had the same field until +[the gateway alignment](/quest/m2/gateway-align.md) moved the ingest cap +onto `moq_mux::Ingest` (2026-11-16); the WHEP cap is per viewer, so it +stays on the request. The handle is `moq_net::bandwidth::Limit`, which replaced moq-webrtc's own `rate::{Cap, Limit}` (2026-11-07, maintainer, /quest-plan from the API shape audit). Wire: none. @@ -70,3 +82,4 @@ audit). Wire: none. ## Related - [SRT rate handle](/quest/m3/srt-rate-handle.md) - the same pacing and retransmit charging on SRT +- [moq-webrtc runs on upstream str0m](/quest/m2/str0m-upstream.md) - removes the vendored copy the NACK hook was planned for diff --git a/quest/m3/srt-rate-handle.md b/quest/m3/srt-rate-handle.md index f083c0c9811..a63004796b0 100644 --- a/quest/m3/srt-rate-handle.md +++ b/quest/m3/srt-rate-handle.md @@ -54,9 +54,13 @@ enforcement needs it and nobody owned it. Public API: a rate handle and a rate-limit close reason on moq-srt's server. The handle is `moq_net::bandwidth::Limit`, the one WHIP takes in `whip::Request.rate` (2026-11-07, maintainer, /quest-plan from the API shape -audit), not a moq-srt copy. It reaches a server ingest as a field on -`moq_mux::Ingest` or a new `#[non_exhaustive]` request, and a dial-out push -as a field on `moq_srt::dial::Publish`, never as a `with_*` setter. Wire: none. +audit), not a moq-srt copy. It reaches a server ingest as the `rate` field +on `moq_mux::Ingest`, which [the gateway alignment](/quest/m2/gateway-align.md) +adds before the cut in place of `whip::Request.rate` (2026-11-16, +maintainer, /quest-plan of the pre-cut audit), so this quest enforces a +field that already exists. The egress cap is a field on the SRT egress +request struct the same quest adds, and a dial-out push takes it as a field +on `moq_srt::dial::Publish`, never as a `with_*` setter. Wire: none. ## Required @@ -65,4 +69,5 @@ as a field on `moq_srt::dial::Publish`, never as a `with_*` setter. Wire: none. ## Related - [moq-webrtc pacing](/quest/m3/rtc-pacing.md) - the same pacing and retransmit charging on WHEP +- [The gateways admit a session the same way](/quest/m2/gateway-align.md) - adds `Ingest::rate` and the request structs the caps ride - [moq-srt wire source](/quest/m3/wire-stats/srt.md) - per-connection byte counts from the same socket diff --git a/quest/m3/time-addressing-consumers.md b/quest/m3/time-addressing-consumers.md deleted file mode 100644 index 87994c29927..00000000000 --- a/quest/m3/time-addressing-consumers.md +++ /dev/null @@ -1,64 +0,0 @@ -# [M] Media consumers address groups by start - -## Goal - -hang stops writing the duration and discontinuity markers that group ends -and gaps now carry, and the hang draft says so. Every first-party consumer -that numbered groups works by start timestamp, in Rust and JS, and the -HLS/DASH export places each group on the declared `media.join.interval` grid -by its start. - -## Plan - -Moved from m2 to m3 2026-11-14 (the m2 triage before the cut, under -/quest-afk, for the maintainer's review): ✅ m3, since what remains breaks -nothing (rejected: m2; splitting a breaking part out, since none is left). -[The model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) -([moq-dev/moq#8638](https://github.com/moq-dev/moq/pull/8638)) converts the -Rust consumers whose API named group numbers: `moq fetch --group` and the -relay's `/fetch?group=` keep their names and take a start, moq-mux `seek` and reads carry starts, -and moq-hls, moq-archive, and moq-transcode key by start. `@moq/hang`'s -`Read.group` keeps its name and carries whatever `@moq/net` keys by. Dropping -the markers is no break either: readers already tolerate their absence -(2026-10-25, below). What remains: the markers, the JS consumers' -continuity checks once [@moq/net by start](/quest/m2/time-addressing/js.md) -lands, the hang draft, and a pass over the list below for anything the model -left numbering groups. Resized from L to M with it. - -Decided 2026-10-25 (maintainer), from the spike: - -- GROUP_END replaces hang's empty-frame duration marker - (`rs/moq-mux/src/container/producer.rs`, `cut` and `close`), so moq-mux - stops writing empty frames. -- Discontinuity marker groups go away (`producer.rs`, `discontinuity`): a gap is a - previous end below the next start, and a missing group is a - previous-start link that doesn't match. -- Legacy egress synthesizes neither: old players lose end durations and - pause markers, which they already tolerate being absent. - -Decided 2026-11-02 (maintainer): removing the HLS records, the per-rendition -`hls` field, and A/V segment alignment moved to m0 as the HLS grid, -landed in [moq-dev/moq#7652](https://github.com/moq-dev/moq/pull/7652), which also added -`media.join.interval`, moved `clock` to `media.clock`, and settled the -segmentation rules decided here on 2026-10-27/28. It places groups by their -first frame's pts; this quest swaps that for the group start, without -changing the segment numbers. - -Convert each consumer that numbers groups: hang and moq-mux timelines, -HLS/DASH export, `seek` for GOP-aligned failover in moq-mux, HLS import's -discontinuity packing, transcode's 1:1 numbering, archive keys and resume, -relay and CLI `fetch --group`, and player continuity checks in the Rust and -JS container consumers and `js/watch`. Update the hang draft and the docs -each one makes stale. Rename no CLI flag: that breaks callers, which m3 -cannot. - -Public API: none left. The model keeps `moq fetch --group` and the relay's -`/fetch?group=`, whose value now names the group starting there, and keys -archives by start. -Wire: hang drops empty duration frames and discontinuity marker groups, which -readers already tolerate. - -## Required - -- [@moq/net by start](/quest/m2/time-addressing/js.md) - the JS API these consume -- [Lite-07 by start](/quest/m2/time-addressing/lite07.md) - GROUP_END carries the end the duration marker did diff --git a/quest/m3/vendor-sync/webrtc-stack.md b/quest/m3/vendor-sync/webrtc-stack.md index 2776f12aa7b..5286b899731 100644 --- a/quest/m3/vendor-sync/webrtc-stack.md +++ b/quest/m3/vendor-sync/webrtc-stack.md @@ -11,6 +11,12 @@ newest upstream commit checked for each. ## Plan +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc +[returns to upstream str0m](/quest/m2/str0m-upstream.md) before the cut, +and that quest's PR deletes this one with the vendored copy, since +`cargo deny` then sees the stack's advisories. This quest stays only if that +PR reports it cannot make the switch. + Recurring child of the [vendor sync](/quest/m3/vendor-sync/README.md), which says how each run works and recurs. New in the 2026-11-12 audit: the stack was vendored on 2026-11-07 in diff --git a/quest/m3/webrtc/README.md b/quest/m3/webrtc/README.md index e9d7228e0bb..d8412cb69e5 100644 --- a/quest/m3/webrtc/README.md +++ b/quest/m3/webrtc/README.md @@ -1,23 +1,62 @@ -# We own our WebRTC stack +# moq-webrtc is a gateway on upstream str0m ## Goal -All of MoQ's WebRTC lives in one published crate, `moq-webrtc`, holding the WHIP/WHEP gateway, the ICE driver, and vendored copies of str0m, dimpl, and `is`. Fixes to the stack land in normal MoQ PRs instead of waiting on upstream, and code MoQ doesn't use is gone. +`moq-webrtc` is one published crate holding the WHIP and WHEP gateway and +its ICE driver, on crates.io str0m and its DTLS with rind as the crypto +provider. The places str0m does not fit are handled at moq-webrtc's +boundary or fixed upstream, and each is written down: the DTLS handshake +racing ICE, the DTLS timeout's type, one `b=` line per media section, and +retransmits that cannot be charged to a rate cap. -Non-goals: TURN; DTLS 1.3; data channels; replacing a vendored layer before there's a reason to. +Non-goals: TURN; DTLS 1.3 as a requirement; data channels; a fork or a +vendored copy before a fix has been shown to need one. ## Plan -Decided 2026-10-30 with the maintainer (planning interview), after the str0m workarounds piled up: one `b=` line per SDP media section ([moq-dev/moq#7373](https://github.com/moq-dev/moq/pull/7373)), DTLS retransmits running out before ICE connects ([moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379)), no hook to charge or serve NACK resends ([rtc-pacing](/quest/m3/rtc-pacing.md)), and `std::time::Instant` in a `kio::clock` workspace. No upstream reports were approved; vendoring replaces them. - -- **Vendor, then replace.** Copy the upstream crates in, trim them, and fix them in-tree. Replacing a layer with our own (SDP, RTP/RTCP, SRTP) is a later child once a concrete need appears; none is planned yet. -- **One crate.** The ICE driver (once `moq-ice`) lives in `moq-webrtc`, which depends on moq-tokio rather than the reverse, so moq-tokio needs no ICE. The vendored crates become private modules, not separate published crates, keeping their MIT/Apache-2.0 notices (str0m's `packet/` carries webrtc-rs's Apache notice). -- **What goes** (from the 2026-10-30 inventory: we use frame mode, full ICE, and DTLS 1.2, and never enable str0m's BWE, pacer, or stats): GCC bandwidth estimation (8k lines; GCC is ported into `moq-congestion` as `moq_congestion::gcc`), the leaky pacer (replaced by moq-congestion's pacer, made public by [rtc-pacing](/quest/m3/rtc-pacing.md)), H.266, RED, DTMF, G.7xx and comfort noise, VLA and simulcast layers, RTCP app feedback, stats, internal test exports, and dimpl's DTLS 1.3 and version auto-selection. RTCP XR stays: its RRTR/DLRR blocks are the receive side's only RTT measurement, which sets NACK retries and the video recovery deadline. Roughly 17k of str0m's 72k lines and 11k of dimpl's 33k. -- **DTLS 1.2 only.** Every browser negotiates 1.2 today, and the vendored rind crypto provider offers 1.2 only to match. -- **No SCTP.** Decided 2026-11-14 (maintainer): peer-to-peer routing, the only data-channel consumer, left the repository, so sctp-proto and str0m's data channels are cut and an offered `m=application` line is answered rejected. -- **Upstream fixes:** after vendoring, nobody merges upstream automatically. The vendored upstream commits are recorded in `rs/moq-webrtc/src/vendor/mod.rs`'s `Upstream` section; the [vendor sync](/quest/m3/vendor-sync/webrtc-stack.md) checks the upstream changes once per release cycle for security fixes (malformed SRTP/RTCP input, for example) and ports them. -- Docs a change makes stale (crate names, `doc/lib/rs`, `doc/setup/upgrade.md`, other quests naming a crate or module) change in the PR that makes them stale. +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ +return to upstream str0m (rejected: keep the vendored stack and gate the cut +on a browser test; keep as is). This reverses the 2026-10-30 decision below, +and [the switch](/quest/m2/str0m-upstream.md) lands before the cut. What +changed: none of the four fixes that motivated vendoring had landed by the +audit, peer-to-peer and data channels left on 2026-11-14 +([moq-dev/moq#8771](https://github.com/moq-dev/moq/pull/8771)), upstream +0.25 has the pluggable crypto provider, and a vendored copy of about 98,600 +lines gets no upstream fix unless someone ports it. + +History: decided 2026-10-30 (maintainer, planning interview) to vendor +str0m, dimpl, and `is` into private modules, after the workarounds piled +up: one `b=` line per SDP media section +([moq-dev/moq#7373](https://github.com/moq-dev/moq/pull/7373)), DTLS +retransmits running out before ICE connects +([moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379)), no hook to +charge or serve NACK resends ([rtc-pacing](/quest/m3/rtc-pacing.md)), and +`std::time::Instant` in a `kio::clock` workspace. Vendoring landed on +2026-11-07 ([moq-dev/moq#8163](https://github.com/moq-dev/moq/pull/8163)) +with a trim of what MoQ did not use. + +What still holds from that plan: + +- **One crate.** The ICE driver lives in `moq-webrtc`, which depends on + moq-tokio rather than the reverse, so moq-tokio needs no ICE. +- **No SCTP.** Decided 2026-11-14 (maintainer): an offered `m=application` + line is answered rejected. On upstream this is a configuration, not a + deletion; the switch keeps the test that proves it. +- **DTLS 1.2** is what the rind provider offers and every browser + negotiates today. + +What changes for the four fixes: each is first tried through str0m's public +API. One that needs a change inside str0m becomes an upstream report, filed +only once the maintainer approves it +([upstream reports](/quest/m4/upstream-reports.md)), and its workaround +stays until upstream ships. Vendoring again is the maintainer's call, made +on evidence that a needed fix cannot land any other way. + +Docs a change makes stale (crate names, `doc/lib/rs`, +`doc/setup/upgrade.md`, other quests naming a crate or module) change in the +PR that makes them stale. ## Related -- [moq-webrtc paces WHEP viewers](/quest/m3/rtc-pacing.md) - adds the NACK hook and the shared pacer on the vendored stack +- [moq-webrtc runs on upstream str0m](/quest/m2/str0m-upstream.md) - deletes the vendored stack before the cut +- [moq-webrtc paces WHEP viewers](/quest/m3/rtc-pacing.md) - needs retransmits charged to the cap, which upstream has no hook for diff --git a/quest/m3/webrtc/dtls-after-ice.md b/quest/m3/webrtc/dtls-after-ice.md index d2e360b44e2..0e7715f0322 100644 --- a/quest/m3/webrtc/dtls-after-ice.md +++ b/quest/m3/webrtc/dtls-after-ice.md @@ -8,4 +8,10 @@ DTLS sends its first flight only once ICE has nominated a pair, so a peer whose Decided 2026-10-30 with the maintainer (planning interview). Today DTLS starts before ICE connects and dimpl gives up after 1+2+4+8+16 s with jitter (`rs/moq-webrtc/src/vendor/dimpl/config.rs:86-88`), racing moq-webrtc's ICE module's 30 s deadline; [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379) papered over the race by reporting an early DTLS failure as a timeout. Hold DTLS activation (str0m's `Rtc::init_dtls` in `rs/moq-webrtc/src/vendor/str0m/lib.rs`) until nomination, then remove #7379's remapping if nothing else needs it. Test on the paused clock: ICE nominating at 29 s still completes DTLS. Added 2026-10-31 from [moq-dev/moq#7379](https://github.com/moq-dev/moq/pull/7379): also test that a DTLS failure after ICE has connected still reports a DTLS error (moq-webrtc's `ice::Error::Rtc`, or the [typed handshake timeout](/quest/m3/webrtc/dtls-timeout.md)), not `Timeout` (moq-webrtc's `IceTimeout`), so the remapping (or its removal) only ever changes a failure before nomination. +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md), so `Rtc::init_dtls` is no longer ours to move. Start by reading how str0m 0.25 starts DTLS and whether its public API can hold the first flight until ICE nominates. If it can, do it there and keep the tests above. If it cannot, the fix is a change inside str0m: write the report for [upstream reports](/quest/m4/upstream-reports.md), which the maintainer approves before it is filed, keep #7379's remapping, and reduce this quest to waiting on upstream. + Public API: none. Wire: none. + +## Required + +- [moq-webrtc runs on upstream str0m](/quest/m2/str0m-upstream.md) - settles which stack starts DTLS diff --git a/quest/m3/webrtc/dtls-timeout.md b/quest/m3/webrtc/dtls-timeout.md index 563ffe21ebd..1ca61f29312 100644 --- a/quest/m3/webrtc/dtls-timeout.md +++ b/quest/m3/webrtc/dtls-timeout.md @@ -25,8 +25,22 @@ where upstream flattened it into `CryptoError::Other(String)`. recommended: an ICE timeout means no path, a DTLS timeout means a path that never finished the handshake. +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): +moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md), where +the vendored copy's typed pass-through is gone and the timeout arrived as +`CryptoError::Other(String)` at the vendored revision. That quest records +what 0.25 returns. If it is typed, classify it as planned. If it is still a +string, don't match on its text (AGENTS.md): the typed error is a change +inside str0m, so write the report for +[upstream reports](/quest/m4/upstream-reports.md) and reduce this quest to +waiting on upstream. + Public API: additive variants on non-exhaustive error enums. Wire: none. +## Required + +- [moq-webrtc runs on upstream str0m](/quest/m2/str0m-upstream.md) - settles what type the timeout arrives as + ## Related - [DTLS waits for ICE](/quest/m3/webrtc/dtls-after-ice.md) - after it, every DTLS handshake timeout comes after nomination, which is the case this types diff --git a/quest/m3/whip-whep-browser.md b/quest/m3/whip-whep-browser.md index 334469a2639..ae67ee1e9d7 100644 --- a/quest/m3/whip-whep-browser.md +++ b/quest/m3/whip-whep-browser.md @@ -5,7 +5,7 @@ A `test/` recipe publishes from Chromium and Firefox over WHIP to a relay with moq-webrtc and plays the broadcast back over WHEP, with fake media, and asserts from `getStats()` that DTLS and SRTP connected and the viewer decoded -frames. It guards the vendored WebRTC stack's crypto and negotiation against +frames. It guards moq-webrtc's crypto and negotiation, str0m on rind, against real browsers. ## Plan @@ -18,6 +18,14 @@ WHIP or WHEP. Moved to m3 2026-11-12 (maintainer, /quest-audit): a downstream deployment serves WHIP and WHEP from this stack. +Kept in m3 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): the +audit recommended making this recipe a gate for the cut while the stack +stayed vendored; the maintainer chose to +[return to upstream str0m](/quest/m2/str0m-upstream.md) instead (rejected: +keep the vendored stack and gate the cut on this). That switch is checked by +one manual Chrome publish and play, so this recipe is still the first +automated browser run against the gateway. + - Reuse the Playwright setup the interop and audio-quality harnesses use (`test/interop/clients/js/`), with the browsers' fake capture devices. - Run it where the other browser tests run; it is slow, so nightly, not the diff --git a/quest/m4/hang-thumbnail.md b/quest/m4/hang-thumbnail.md index 3f798a709d5..78fcf025d83 100644 --- a/quest/m4/hang-thumbnail.md +++ b/quest/m4/hang-thumbnail.md @@ -51,7 +51,12 @@ Recommendations for the PR: time, so it lines up with the video at its timestamp. - Each still is encoded after the request that asks for it, from the newest frame the capture has delivered by then, and never reuses an earlier - encode, so it meets the `refresh()` request barrier. A capture that + encode, so at the publisher a still always follows the request that + made it. Across relays `refresh()` promises only a group newer than the + newest the asking node held (decided 2026-11-16 on + [refresh](/quest/m2/refresh-interval.md): no request counter and no tag + on groups), so a remote caller that needs "after my action" reads until + the still's timestamp passes the time of its action. A capture that delivers frames only on change (PipeWire does) has its last frame as the current screen, so the producer must not wait for a newer one. A caller that needs the result of an action calls `refresh()` once the action has diff --git a/quest/m4/ietf-range-fetch.md b/quest/m4/ietf-range-fetch.md index 48fe0a2f697..549080d23d8 100644 --- a/quest/m4/ietf-range-fetch.md +++ b/quest/m4/ietf-range-fetch.md @@ -30,7 +30,7 @@ frozen scope `doc/concept/standard.md` states, which kept only joining `FETCH`. What makes it possible: moq-transport's Prior Group ID Gap object extension, -which [IETF time addressing](/quest/m4/ietf-time-addressing.md) sends on +which [IETF time addressing](/quest/m2/ietf-time-addressing.md) sends on egress and reads on ingest as a best-effort SUBSCRIBE_SKIP. What counts as proven: @@ -71,12 +71,8 @@ Public API: none. Wire: none (draft-defined messages only). ## Required -- [IETF time addressing](/quest/m4/ietf-time-addressing.md) - reads Prior Group ID Gap on ingest +- [IETF time addressing](/quest/m2/ietf-time-addressing.md) - reads Prior Group ID Gap on ingest ## Closes - [#8577](https://github.com/moq-dev/moq/issues/8577) - a Standalone FETCH that spans more than one group is refused - -## Related - -- [moq-transport read ends over a hole](/quest/m3/ietf-hole-stall.md) - settles the holes a refused range leaves diff --git a/quest/m4/intra-refresh/README.md b/quest/m4/intra-refresh/README.md index e30d277ea0a..61ed817d308 100644 --- a/quest/m4/intra-refresh/README.md +++ b/quest/m4/intra-refresh/README.md @@ -26,6 +26,18 @@ broadcast feeds that only do intra refresh. Decisions the quests share: +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ video +`warmup` is not in moq-hang-04 (rejected: freezing it with Chromium-only +evidence; gating the cut on a Safari and Firefox run). No producer wrote it, +and a 0.22 player claiming to read it would mis-decode a later producer's +rendition instead of refusing it. The m2 quest +`quest/m2/hang04/video-warmup.md` removed the field and the one-decoder +player path that +[moq-dev/moq#8857](https://github.com/moq-dev/moq/pull/8857) had landed the +day before. [Catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) +brings both back, from that history, as the next catalog version, and every +other quest here builds on it. Audio `warmup` stayed in hang-04. + Decided 2026-11-15 (maintainer, /quest-complete): ✅ a catalog `warmup` is a hint nothing enforces (rejected: refusing the stream once a sweep exceeds the published `warmup`; a bound published before the content it covers; a fixed @@ -38,7 +50,8 @@ refresh stripes a little longer: a cosmetic cost, not a correctness one. - One group per refresh cycle. A group starts at the recovery point, the frame that begins a sweep, so a viewer joining at any group boundary is clean after exactly one cycle and relay shedding keeps its meaning. -- The catalog carries a `warmup` duration per rendition. The transcoder +- The catalog carries a `warmup` duration per rendition (for video, from + the catalog version after hang-04). The transcoder decodes enough preceding groups to cover it as history before each group it transcodes. A player joins that much earlier and hides that much after each join or skip, so an imprecise `warmup` shows stripes or hides clean pictures. diff --git a/quest/m4/intra-refresh/catalog-warmup.md b/quest/m4/intra-refresh/catalog-warmup.md new file mode 100644 index 00000000000..c7e6c3948bd --- /dev/null +++ b/quest/m4/intra-refresh/catalog-warmup.md @@ -0,0 +1,46 @@ +# [M] Video warmup returns to the catalog and the players + +## Goal + +A video rendition can declare `warmup` again, as a feature of the catalog +version after moq-hang-04, and every player plays such a rendition through +one decoder: `@moq/watch`, `moq_video::decode`, `moq play`, moq-gst, and the +bindings join one group earlier and hide the warmup after each join or +skip. The entry carries the `version` that makes a 0.22 player skip it +instead of mis-decoding it. + +## Plan + +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): video +`warmup` left hang-04 and the players' path was deleted before the cut +([moq-dev/moq#8857](https://github.com/moq-dev/moq/pull/8857) had landed +that path on 2026-11-15), because no producer wrote the field, Firefox and +Safari had never run it, an HEVC refresh rendition fails in Chromium, and a +0.22 player that claimed to read it would mis-decode a later producer's +rendition. It returns here, with the producers this epic adds. + +- Restore from history, not from scratch: #8857 is the design (one + decoder, the container consumer's warmup reach, `Recovery`'s hold, the + recovery-point SEI Chromium needs), and the PR that removed it before the + cut is its inverse. Read both, then re-apply by hand against the tree as + it is. +- The field comes back in the hang draft's next version, with the group + rule that lets a video group start at a picture from which decoding + converges. It raises the entry's `version`, not the root's (the + per-entry rule hang-04 ships, planned as `quest/m2/hang04/entry-version.md`), + so a player that cannot play it keeps the other renditions. +- Audio `warmup` never left; reuse `moq_mux::container::Playout` and the + JS consumer's `warmup` reach as they are. +- The draft says which engines play it. The Firefox and Safari check in + [second decoder](/quest/m4/intra-refresh/dual-decoder.md) needs a real + intra-refresh stream, so it runs after the + [H.264 import](/quest/m4/intra-refresh/h264-import.md); until it passes, + the draft's text and `doc/lib/js/watch.md` name Chromium only, and the + new catalog version is not published. + +Tests: the ones #8857 carried, restored with the path: a cold join and a +skip of a warmup rendition each show one clean picture after the warmup, +in the browser decoder and in `moq_video::decode`. + +Public API: additive in Rust, JS, and the bindings (the video `warmup` +field and the decoders' handling). Wire: the next hang catalog version. diff --git a/quest/m4/intra-refresh/consumer-warmup.md b/quest/m4/intra-refresh/consumer-warmup.md index 52b76b200a7..409a6c58683 100644 --- a/quest/m4/intra-refresh/consumer-warmup.md +++ b/quest/m4/intra-refresh/consumer-warmup.md @@ -7,7 +7,8 @@ picture its decoder has not fully recovered. Every group it transcodes, whether fetched on demand for a rung or read live after a skip, is preceded by enough earlier groups decoded as history that its first picture is clean. Players instead join a group earlier and hide the warmup after each join or -skip, in `@moq/watch` and the native `moq_video::decode::Consumer`. +skip, in `@moq/watch` and the native `moq_video::decode::Consumer`, once +[catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) restores that. Renditions without `warmup` behave exactly as today. ## Plan @@ -56,3 +57,7 @@ The fix is history rather than a withhold rule: feed start and a feed skip both decode history before forwarding; an IDR group needs no history; a rendition without `warmup` fetches and reads exactly as today. + +## Required + +- [Catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) - the video `warmup` field a source rendition declares diff --git a/quest/m4/intra-refresh/dual-decoder.md b/quest/m4/intra-refresh/dual-decoder.md index 49be709516c..20118f1217e 100644 --- a/quest/m4/intra-refresh/dual-decoder.md +++ b/quest/m4/intra-refresh/dual-decoder.md @@ -4,9 +4,10 @@ Measure what a second decoder would buy a viewer of an intra-refresh rendition (catalog `warmup` set), and either add it to `@moq/watch`, `moq_video::decode`, -and `moq play` or delete this quest. Today each player decodes through one -decoder that joins one group earlier and hides the warmup after each join or -skip, so a skip freezes the picture for one sweep. +and `moq play` or delete this quest. Once +[catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) restores it, each +player decodes through one decoder that joins one group earlier and hides the +warmup after each join or skip, so a skip freezes the picture for one sweep. ## Plan @@ -15,7 +16,10 @@ one decoder ships, and two are revisited here with measurements. [moq-dev/moq#8857](https://github.com/moq-dev/moq/pull/8857) removed the earlier pair: a min-delay decoder that showed stripes and drove the clock, and a max-delay decoder a sweep behind whose clean pictures replaced them once it -caught up. That pair decoded twice for the whole session, since the max-delay +caught up. The one-decoder path itself left before the cut with video +`warmup` (2026-11-16, see the [epic](/quest/m4/intra-refresh/README.md)) and +returns with [catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md). +That pair decoded twice for the whole session, since the max-delay lane never stops in steady state, to improve only the moments after a join or skip. Its Rust and JS selection policies also differed (Rust held a sticky source, JS picked per picture). @@ -43,6 +47,10 @@ than for the whole session, is the variant to measure first. - linux - Chromium and Firefox - macos - Safari and VideoToolbox +## Required + +- [Catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) - the one-decoder players this measures against + ## Related - [H.264 import](/quest/m4/intra-refresh/h264-import.md) - publishes the real `warmup` for an end-to-end x264 check diff --git a/quest/m4/intra-refresh/h264-import.md b/quest/m4/intra-refresh/h264-import.md index b22059f5e73..261689c83b3 100644 --- a/quest/m4/intra-refresh/h264-import.md +++ b/quest/m4/intra-refresh/h264-import.md @@ -55,3 +55,7 @@ follows the hang draft, which rounds up length-prefixed path; and a real clip generated with x264 `intra-refresh=1` added as a second round-trip in `test/ts/run.sh` next to the closed-GOP one, asserting the catalog `warmup` and the group count. + +## Required + +- [Catalog warmup](/quest/m4/intra-refresh/catalog-warmup.md) - the video `warmup` field this writes, absent from hang-04 diff --git a/quest/m4/track-info-docs.md b/quest/m4/track-info-docs.md index 265dc0ad532..01ec9b81587 100644 --- a/quest/m4/track-info-docs.md +++ b/quest/m4/track-info-docs.md @@ -17,8 +17,10 @@ The docs say "priority, ordering, latency budget, and timescale" (Kotlin, Dart) and "priority, group ordering, max age, and timescale" (Swift). `MoqTrackInfo` (`rs/moq-ffi/src/producer.rs`) has `priority`, `max_age`, `refresh`, `timescale` and `compression`. Ordering and delay are subscriber-side -(`MoqSubscription`). #7729 adds `max_age_unlimited`, so describe the record -as it stands when this lands. +(`MoqSubscription`). #7729 added `max_age_unlimited`, which +[the selector quest](/quest/m2/ffi-open-selectors.md) deletes in favor of a +null `max_age` (decided 2026-11-16), so describe the record as it stands +when this lands. - Name the fields, or describe the record's purpose without a list that can drift. Prefer the one-line purpose plus a pointer to the record, so a new diff --git a/quest/m4/upstream-reports.md b/quest/m4/upstream-reports.md index 942a0d5236d..01c9deb3d6c 100644 --- a/quest/m4/upstream-reports.md +++ b/quest/m4/upstream-reports.md @@ -50,8 +50,15 @@ maintainer a draft instead: Not to be filed: - **str0m/dimpl:** the DTLS retry budget runs out before ICE picks a - path, found in #7379. The [WebRTC epic](/quest/m3/webrtc/README.md) - vendors str0m instead of reporting upstream, and - [DTLS waits for ICE](/quest/m3/webrtc/dtls-after-ice.md) fixes it there. + path, found in #7379. Not filed while the + [WebRTC epic](/quest/m3/webrtc/README.md) vendored str0m. Since + 2026-11-16 moq-webrtc [returns to upstream](/quest/m2/str0m-upstream.md), + so this and three more become candidates once their quests show the + public API cannot do it: [DTLS waits for ICE](/quest/m3/webrtc/dtls-after-ice.md), + [the typed DTLS timeout](/quest/m3/webrtc/dtls-timeout.md), + [several bandwidth lines](/quest/m4/webrtc-sdp-bandwidth.md), and the + NACK hook of [WHEP pacing](/quest/m3/rtc-pacing.md). Each needs the + maintainer's approval and a read of the repository's AI policy before it + is filed. Public API: none. Wire: none. diff --git a/quest/m4/webrtc-browser-only.md b/quest/m4/webrtc-browser-only.md index 2aa6232d7c5..a178a35d5b2 100644 --- a/quest/m4/webrtc-browser-only.md +++ b/quest/m4/webrtc-browser-only.md @@ -9,6 +9,8 @@ browser peer stays compiled. ## Plan +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md) before the cut, and that quest's PR deletes this one with the vendored copy. It stays only if that PR reports it cannot make the switch. + Planned 2026-11-07 (maintainer, /quest-complete), a follow-up of [moq-dev/moq#8163](https://github.com/moq-dev/moq/pull/8163). The maintainer widened the suggestion from PSK alone: delete anything browsers don't use diff --git a/quest/m4/webrtc-clock.md b/quest/m4/webrtc-clock.md index f0b6d9d65d6..9c9264d4cd6 100644 --- a/quest/m4/webrtc-clock.md +++ b/quest/m4/webrtc-clock.md @@ -6,6 +6,8 @@ The vendored str0m and dimpl take `kio::clock::Instant` instead of `std::time::I ## Plan +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md) before the cut, and that quest's PR deletes this one with the vendored copy. It stays only if that PR reports it cannot make the switch. + Decided 2026-10-30 with the maintainer (planning interview). Every call into str0m converts with `Instant::into_std` today, the way the workspace handles any third-party API that takes `std::time::Instant`. Change the vendored modules' time type, delete the conversions, and move any moq-webrtc test that pauses tokio time onto the sim. Public API: none. Wire: none. diff --git a/quest/m4/webrtc-dead-api.md b/quest/m4/webrtc-dead-api.md index e5fc6185791..26396b8eb34 100644 --- a/quest/m4/webrtc-dead-api.md +++ b/quest/m4/webrtc-dead-api.md @@ -7,6 +7,8 @@ tests; dead upstream API is deleted. ## Plan +Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md) before the cut, and that quest's PR deletes this one with the vendored copy. It stays only if that PR reports it cannot make the switch. + Planned 2026-11-07 (maintainer, /quest-complete), a follow-up of [moq-dev/moq#8163](https://github.com/moq-dev/moq/pull/8163). It waits on the clock quest, which reshapes the time seams moq-webrtc calls through, as diff --git a/quest/m4/webrtc-sdp-bandwidth.md b/quest/m4/webrtc-sdp-bandwidth.md index 7efca10b550..3bc732635e4 100644 --- a/quest/m4/webrtc-sdp-bandwidth.md +++ b/quest/m4/webrtc-sdp-bandwidth.md @@ -2,10 +2,12 @@ ## Goal -The vendored SDP parser and writer accept and emit several `b=` lines per media section, so a capped WHIP answer carries both `b=TIAS` and `b=AS` natively and moq-webrtc stops string-splicing `b=TIAS` into the answer. +A capped WHIP answer carries both `b=TIAS` and `b=AS`, and moq-webrtc stops string-splicing `b=TIAS` into the answer, because str0m's SDP parser and writer accept and emit several `b=` lines per media section. ## Plan -Decided 2026-10-30 with the maintainer (planning interview). The vendored str0m reads `optional(bandwidth_line())` (`rs/moq-webrtc/src/vendor/str0m/sdp/parser.rs:51,320`) into `bw: Option` (`sdp/data.rs:174,288`), so a second line made the whole answer unparseable and [moq-dev/moq#7373](https://github.com/moq-dev/moq/pull/7373) shipped TIAS only through `sdp::cap_answer`. Make it a `Vec`, emit both lines on a capped answer as the original Goal asked, delete the splice, and test that our own WHIP client parses the answer. +Decided 2026-10-30 with the maintainer (planning interview) as a change to the vendored str0m. Changed 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): moq-webrtc [returns to upstream str0m](/quest/m2/str0m-upstream.md), so the parser is upstream's again. + +At the vendored revision str0m read `optional(bandwidth_line())` into `bw: Option`, so a second line made the whole answer unparseable, and [moq-dev/moq#7373](https://github.com/moq-dev/moq/pull/7373) shipped TIAS only through `sdp::cap_answer` (`rs/moq-webrtc/src/sdp.rs`). Check whether 0.25 still does. If it does, the change (a `Vec`) is upstream's to take: write the report for [upstream reports](/quest/m4/upstream-reports.md), which the maintainer approves before it is filed, and keep the splice until a release carries it. Then emit both lines on a capped answer, delete the splice, and test that our own WHIP client parses the answer. Public API: none. Wire: capped answers gain `b=AS`. diff --git a/quest/m5/carla-bridge.md b/quest/m5/carla-bridge.md index 250901a4757..367791e8058 100644 --- a/quest/m5/carla-bridge.md +++ b/quest/m5/carla-bridge.md @@ -15,6 +15,12 @@ itself stays on NVIDIA; the stand-in proves the bridge elsewhere. ## Plan +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): the CARLA +demo stays in this repository for now, because moq.dev hosts it as a demo +(rejected: moving it to Kixel, where AGENTS.md sends robotics work). The +bridge therefore stays a consumer of moq-video's external Vulkan images +(`frame::vulkan`). + moq-video owns the surface, the backend selection, the Vulkan Video backend, and its hardware tests. This quest only removes what the bridge still pins. diff --git a/quest/m5/e2ee/README.md b/quest/m5/e2ee/README.md index cee7f9c51ed..65fc5610fba 100644 --- a/quest/m5/e2ee/README.md +++ b/quest/m5/e2ee/README.md @@ -8,6 +8,8 @@ Every application payload and semantic track name is confidential and authentica ## Plan +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): E2EE is "not ready yet". It lives in its own unpublished `moq-e2ee` crate again ([the crate move](/quest/m2/e2ee-crate.md)), and [the finished format](/quest/m3/e2ee-format.md) ships as profile `moq-e2ee-01` before any quest in this epic builds on it. That quest changes decisions recorded below, each marked where it stands: keys bind the semantic broadcast name, each group has its own key (no per-key limits), the per-track wrap is public, `Epoch` is `moq_net::Instance`, and the profile carries no compression. Encryption stays in the payload, invisible to relays, with nothing on the moq-net layer. + The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), profile `moq-e2ee-00`, with `drafts/moq-e2ee-00.json` as the shared primitive vectors. It starts from IETF Secure Objects where the object model maps exactly, specifies the moq-lite and datagram bindings that draft does not cover, and records intentional differences from SFrame and the experimental `moq-secure` format linked from [#3023](https://github.com/moq-dev/moq/issues/3023). ### Security boundary @@ -19,13 +21,13 @@ The contract is [draft-lcurley-moq-e2ee](/drafts/draft-lcurley-moq-e2ee.md), pro ### Epoch and identity -- Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is `moq_crypto::e2ee::Epoch`, announced as the route's [instance](/doc/concept/moq-lite.md#publisher-instances). Subscribers resolve `` and take the epoch from its route's instance; on a wire that carries no instance the session mints one, so the application supplies the epoch. +- Every publisher instance mints an epoch, a UUIDv7 in lowercase text, and publishes at `` with the epoch on its route, where `` derives from the credential and the semantic broadcast name without the epoch. The epoch is an input to every HKDF derivation, so a restart, takeover, or explicit group sequence cannot repeat a nonce under a key: nothing is persisted across instances and no generation counter is redistributed. The epoch is `moq_e2ee::Epoch` today and becomes `moq_net::Instance` itself (decided 2026-11-16, [the finished format](/quest/m3/e2ee-format.md)), announced as the route's [instance](/doc/concept/moq-lite.md#publisher-instances). Subscribers resolve `` and take the epoch from its route's instance; on a wire that carries no instance the session mints one, so the application supplies the epoch. - An encrypting publisher refuses a shared or explicit epoch (maintainer, 2026-10-08). Two producers handed one epoch would derive the same keys and repeat every nonce. Both cores produce only under an epoch they minted themselves; consuming still binds a discovered one. Rejected: a per-instance salt. State the rule in the draft's epoch section. - The epoch is untrusted and unauthenticated. A wrong epoch fails authentication and a withheld one denies service; neither can make a nonce repeat, because only the publisher instance chooses what it encrypts under. This is the same trust a cache needs to serve the right instance. First-party plaintext publishers already mint the same route epoch. - Nothing in the path says the bytes are encrypted. The format after decryption (`meeting.hang`) is inside the opaque name; a plaintext player, exporter, or matcher that opens a protected broadcast finds no catalog it can read and fails with its usual typed refusal, the same as for any format it does not support. -- One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains. A grouped frame uses a 96-bit nonce of a 64-bit group identity and `uint32_be(frame)`. `group` is the group's wire ID, which is its start once [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) keys groups by start, so the nonce input needs no change; [lite-07 by start](/quest/m2/time-addressing/lite07.md) updates the draft's wording. A datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. +- One 32-byte secret authorizes the whole broadcast; HKDF-SHA-256 derives separate AES-128-GCM keys for each physical track and for grouped-frame versus datagram domains, and from `moq-e2ee-01` for each group, with the semantic broadcast name bound into every derivation (decided 2026-11-16). A grouped frame uses a 96-bit nonce of a 64-bit group identity and `uint32_be(frame)`. `group` is the group's wire ID, which is its start once [the model](https://github.com/moq-dev/moq/blob/7d1bee79cb8fcb4d816fc53f0547ef8b2b19756a/quest/m2/time-addressing/model.md) keys groups by start, so the nonce input needs no change; [lite-07 by start](/quest/m2/time-addressing/lite07.md) updates the draft's wording. A datagram uses its sequence with frame zero under the datagram domain. Empty AAD: every immutable end-to-end field is in the HKDF info or the nonce. - Within an instance, group and datagram sequences are allocated monotonically and frames are numbered in write order, which is the whole reuse rule. There is no ciphertext retention or retransmission API: relays forward bytes unchanged, and an application that needs to resend encrypts nothing twice because it never gets the same identity twice. -- Per-key limits are `2^24` AEAD invocations (failed opens included) and `2^36` plaintext bytes. The generation handle owns each key's accounting, shared by every track and subscription through it and never evicted while the application holds it; binding the epoch again starts fresh, since remembering retired epochs would be state a relay grows (maintainer, 2026-10-24). Rejected: a credential-level registry of live generations, and refusing to re-bind a released epoch. Datagram plaintext is capped at `1200 - 24 - 16` bytes against the widest moq-lite header; a publisher cannot see the Subscribe ID each hop encodes, so the library does not pretend to budget it. +- Superseded 2026-11-16 by [one key per group](/quest/m3/e2ee-format.md), which makes the limits unreachable and deletes the accounting: per-key limits were `2^24` AEAD invocations (failed opens included) and `2^36` plaintext bytes, owned by the generation handle (maintainer, 2026-10-24), which forced a whole-broadcast restart after 19 hours at 8 Mb/s. Datagram plaintext is capped at `1200 - 28 - 16` bytes against the widest moq-lite header; a publisher cannot see the Subscribe ID each hop encodes, so the library does not pretend to budget it. ### Library shape @@ -33,9 +35,9 @@ The Rust and TypeScript cores expose the same surface, and nothing else: - `Credential { context, kid, secret }` accepts the application-owned secret. The application generates and distributes it over its authenticated channel; the library does not mint a secret it cannot return. `credential.path(semantic)` derives the epoch-free opaque broadcast name. Credential is cheap to clone, never serializes the secret, and redacts it from `Debug`. - A core produces only under an epoch it minted itself (decided 2026-10-08). Only `credential.produce()` mints a producing generation, and it takes no epoch: it mints a fresh UUIDv7 and returns a `generation::Producer` owning `epoch()` for the route and `name(semantic)` for opaque track names. `credential.consume(epoch)` binds a discovered epoch as a consume-only `generation::Consumer` with `name(semantic)`. The two are separate types, so producing under a discovered or shared epoch does not compile (names decided 2026-10-11 in [#5313](https://github.com/moq-dev/moq/pull/5313)). Clones of a producing generation share publisher claims so reopening a track cannot reset its nonce counters. -- Applications only handle semantic track names (maintainer, 2026-10-17). `broadcast::Producer` wraps a `moq-net` broadcast under a producing generation and `broadcast::Consumer` wraps one under a consuming generation; each derives the physical name, so only the CDN sees physical names. `generation` no longer opens tracks itself. The broadcast wrappers merged in [#5876](https://github.com/moq-dev/moq/pull/5876). +- Applications only handle semantic track names (maintainer, 2026-10-17). `broadcast::Producer` wraps a `moq-net` broadcast under a producing generation and `broadcast::Consumer` wraps one under a consuming generation; each derives the physical name, so only the CDN sees physical names. The broadcast wrappers merged in [#5876](https://github.com/moq-dev/moq/pull/5876), which made `generation`'s track-level entries private. Amended 2026-11-16 ([the finished format](/quest/m3/e2ee-format.md)): those entries are public again, so an application can encrypt one track it already holds under a name both ends agree on; the broadcast wrappers stay as the convenience that hides names. - The wrappers implement the [moq-net traits](/quest/m5/net-wrap/README.md) at the broadcast, track, group, and frame levels, datagrams included (decided 2026-10-20, maintainer, because one encrypted broadcast then works with every writer and reader). moq-mux, moq-json, hang, and the CLI publish and consume an encrypted broadcast unchanged, under semantic names, and every AEAD call still has the canonical physical name and transport identity. The e2ee mux bridge ([#5822](https://github.com/moq-dev/moq/pull/5822)) is closed and superseded. -- Errors are the draft's typed codes plus the transport's. Nothing catalog-, hang-, or MSF-shaped lives here: a catalog is a track under a derived name. The catalog owner sets logical `track::Info.compression`; the [e2ee wrapper](/quest/m5/net-wrap/e2ee.md) compresses before AEAD and authenticates the logical compression metadata. +- Errors are the draft's typed codes plus the transport's. Nothing catalog-, hang-, or MSF-shaped lives here: a catalog is a track under a derived name. Decided 2026-11-16 ([the finished format](/quest/m3/e2ee-format.md)), replacing the 2026-10-20 plan to compress before AEAD and authenticate the compression metadata: the profile carries no compression, so an application compresses its own plaintext. - Stateless `seal`/`open` primitives with caller-chosen identities, HKDF labels and info builders, raw key bytes, and process-global claims are not public. The vectors are tested inside each core. ### Application and platform shape @@ -73,6 +75,10 @@ Before `@moq/crypto` is first published, add its entrypoints to the API Extractor declaration checks, which analyze only published packages since [moq-dev/moq#6794](https://github.com/moq-dev/moq/pull/6794). +## Required + +- [moq-e2ee publishes the finished format](/quest/m3/e2ee-format.md) - the `moq-e2ee-01` format and wrapper shape every child builds on + ## Closes - [#3023](https://github.com/moq-dev/moq/issues/3023) - close this issue when the quest finishes diff --git a/quest/m5/e2ee/cli.md b/quest/m5/e2ee/cli.md index 18a7215c31e..4d4e4858f50 100644 --- a/quest/m5/e2ee/cli.md +++ b/quest/m5/e2ee/cli.md @@ -8,8 +8,10 @@ Existing plaintext commands remain the default; an explicit application credenti ## Plan -`moq-crypto` is already publishable: its manifest (`rs/moq-crypto/Cargo.toml`) -no longer sets `publish = false`. +`moq-e2ee` is unpublished (decided 2026-11-16, maintainer) until +[the finished format](/quest/m3/e2ee-format.md) publishes it, which the +epic requires, so the published CLI can depend on it by the time this +starts. - Hand the [trait-generic CLI paths](/quest/m5/net-wrap/cli.md) an encrypted broadcast for publication and playback. Keep codec, capture, playback, and synchronization logic outside the crypto layer. - Accept the credential through a dedicated file descriptor, otherwise-unused stdin, or a permission-checked file (`0600` on Unix), never a command argument or environment variable. Redact errors and tracing, zeroize owned secret bytes, and document shell-safe invocation. diff --git a/quest/m5/e2ee/consumer.md b/quest/m5/e2ee/consumer.md index df007830528..a6ddcef5a92 100644 --- a/quest/m5/e2ee/consumer.md +++ b/quest/m5/e2ee/consumer.md @@ -9,7 +9,7 @@ reinvent decryption and physical-name mapping. ## Plan Decided 2026-10-20 (maintainer): the shape is the moq-net consumer traits. -`moq_crypto::e2ee::broadcast::Consumer` and its track and group consumers implement +`moq_e2ee::broadcast::Consumer` and its track and group consumers implement them ([net-wrap](/quest/m5/net-wrap/README.md)), so a Rust player, the CLI, and `@moq/watch` open an encrypted broadcast as they open any other, because every reader already takes the traits. Kept in m2 (decided @@ -21,15 +21,18 @@ What remains here: application on a wire without route epochs), and bind it with `credential.consume(epoch)` in one call each player shares, in Rust and JS with matching names. -- Keep that generation while the route keeps the same epoch, across - re-announcements: each key's AEAD budget lives in the generation, so - re-binding on every announce would let a relay that withdraws and - re-announces reset it. +- Keep that generation while the route keeps the same Instance, across + re-announcements, so keys are not derived again on every announce. The + AEAD budget that used to make this a security rule is gone with + [one key per group](/quest/m3/e2ee-format.md) (decided 2026-11-16). +- `credential.consume` takes the semantic broadcast name with the Instance + (decided 2026-11-16, the same quest), so the shared call cannot bind one + broadcast's keys to another's route. - Decrypt the protected catalog before the existing selection. - Rust and JS only (decided 2026-10-20, maintainer): the e2ee publisher has no moq-ffi half either, so an FFI consumer waits for a quest that adds both. -Public API: an e2ee consumer entry point in `moq-crypto` and `@moq/crypto`. +Public API: an e2ee consumer entry point in `moq-e2ee` and `@moq/crypto`. Wire: none. ## Required diff --git a/quest/m5/e2ee/js-undeclared-names.md b/quest/m5/e2ee/js-undeclared-names.md index fcac24009c1..7ebd8e52425 100644 --- a/quest/m5/e2ee/js-undeclared-names.md +++ b/quest/m5/e2ee/js-undeclared-names.md @@ -4,7 +4,7 @@ `@moq/crypto`'s broadcast producer answers requests for track names it never created, under semantic names, through `@moq/net`'s public broadcast request -handler, as `moq_crypto::e2ee::broadcast::Requests` does in Rust. A JS +handler, as `moq_e2ee::broadcast::Requests` does in Rust. A JS application then serves on-demand tracks from a plaintext or encrypted broadcast the same way. @@ -24,7 +24,7 @@ Decided with the maintainer on 2026-10-24: 2026-10-17 refusal, so every identity stays unique and a handler can serve a dropped name again). - The handler offers the lister, taking semantic names and listing their - physical names, as Rust's `moq_crypto::e2ee::broadcast::Lister` does, over + physical names, as Rust's `moq_e2ee::broadcast::Lister` does, over the broadcast lister `@moq/net` exports with its handler. - Port Rust's `requests_refuse_names_the_generation_did_not_issue` and `requests_serve_a_dropped_name_above_its_marks` tests: a relay-forged name, an older epoch's name, diff --git a/quest/m5/e2ee/rust-publish.md b/quest/m5/e2ee/rust-publish.md index 4c83f3498f3..1bcd6202128 100644 --- a/quest/m5/e2ee/rust-publish.md +++ b/quest/m5/e2ee/rust-publish.md @@ -20,26 +20,29 @@ timeline publishers already publish into an encrypted broadcast under semantic names with no change here. This quest keeps only what the traits do not cover. Every track these publishers serve is declared in advance, so it never needed the undeclared-name handler (maintainer, -2026-10-19), which `moq_crypto::e2ee::broadcast::Producer::requests` now provides. +2026-10-19), which `moq_e2ee::broadcast::Producer::requests` now provides. - Catalog naming: derive the protected catalog name from its well-known logical role, then put media roles, codecs, quality, timelines, and custom-track mappings only inside the encrypted catalog. - Encrypt the single Hang `catalog.json` left by the [m1 compression migration](https://github.com/moq-dev/moq/pull/7046), and encrypt or - suppress the MSF catalog. Set logical `compression` on protected catalog - tracks; the [e2ee wrapper](/quest/m5/net-wrap/e2ee.md) compresses before - encryption. Retain ordinary plaintext publication unchanged outside E2EE mode. + suppress the MSF catalog. The profile carries no compression (decided + 2026-11-16, maintainer, replacing "the wrapper compresses before + encryption"), so a protected catalog ships uncompressed unless the + publisher compresses its own plaintext; follow what the + [e2ee wrapper](/quest/m5/net-wrap/e2ee.md) settles. Retain ordinary + plaintext publication unchanged outside E2EE mode. - Cover every current Rust importer and capture path so a convenience API cannot emit a plaintext semantic catalog. - A re-created track resumes (decided 2026-10-25, maintainer, replacing the - 2026-10-17 refusal): moq-crypto never releases a name's claim, and a track + 2026-10-17 refusal): moq-e2ee never releases a name's claim, and a track created again under a claimed name continues above its high-water marks, - so nonces never repeat. moq-crypto's `create_track` already does this. + so nonces never repeat. moq-e2ee's `create_track` already does this. Public API: none. Wire: none. ## Required -- [moq-crypto's e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - the encrypted broadcast moq-mux publishes into +- [moq-e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - the encrypted broadcast moq-mux publishes into - [moq-mux takes the traits](/quest/m5/net-wrap/mux.md) - the mux and capture publishers this relies on to stay unchanged diff --git a/quest/m5/ffi-e2ee.md b/quest/m5/ffi-e2ee.md index a0b680b7c6a..ceab50a1bd9 100644 --- a/quest/m5/ffi-e2ee.md +++ b/quest/m5/ffi-e2ee.md @@ -2,7 +2,7 @@ ## Goal -The Swift and Kotlin bindings publish and consume moq-crypto protected +The Swift and Kotlin bindings publish and consume moq-e2ee protected broadcasts under an application-supplied `(context, kid, secret)` credential, interoperating with `@moq/crypto` in both directions, with the same epoch rules and typed authentication failures as Rust and JS. @@ -18,7 +18,7 @@ for a downstream application's mobile client, which has since decided on no end-to-end encryption and on a transport that does not go through moq-ffi. It stays parked here until a binding user asks for encrypted broadcasts. -Wrap `moq-crypto`'s producer and consumer entry points without new crypto in +Wrap `moq-e2ee`'s producer and consumer entry points without new crypto in the binding layer, and keep the encrypting publisher's refusal of a shared or explicit epoch. Add a binding test that decrypts a JS-published broadcast and the reverse to the interop suite. @@ -26,19 +26,20 @@ the reverse to the interop suite. ✅ Decided 2026-11-07 (maintainer, /quest-complete): wait for [net-wrap's e2ee](/quest/m5/net-wrap/e2ee.md) and wrap its types once, reversing the API sweep's earlier "don't wait on net-wrap". net-wrap/e2ee -reshapes moq-crypto's `broadcast::{Producer, Consumer}` (`abort` with an -error, `create_group` taking `group::Info`, `track(semantic)` then -`.subscribe(..)`, errors converting into `moq_net::Error`), so a binding -over today's types would break when it lands. There is no interim binding -over the existing encrypted broadcast types (rejected: binding the existing -encrypted types now; dropping ffi-e2ee). Encrypted media publishing through +puts moq-e2ee's `broadcast::{Producer, Consumer}` behind moq-net's traits +with errors converting into `moq_net::Error`, after +[the finished format](/quest/m3/e2ee-format.md) (decided 2026-11-16) has +already changed `abort`, `create_group`, the subscribe shape, and the key +derivation, so a binding over today's types would break twice. There is no +interim binding over the existing encrypted broadcast types (rejected: +binding the existing encrypted types now; dropping ffi-e2ee). Encrypted media publishing through moq-mux's catalog and codec publishers comes with [Rust protected publisher seams](/quest/m5/e2ee/rust-publish.md), and the bindings pick it up then without a break. ## Required -- [moq-crypto's e2ee implements the moq-net traits](/quest/m5/net-wrap/e2ee.md) - the encrypted broadcast, track, and group types these bindings wrap, in their final shape +- [moq-e2ee implements the moq-net traits](/quest/m5/net-wrap/e2ee.md) - the encrypted broadcast, track, and group types these bindings wrap, in their final shape ## Related diff --git a/quest/m5/net-wrap/README.md b/quest/m5/net-wrap/README.md index b0163c0814f..0bf8e36d820 100644 --- a/quest/m5/net-wrap/README.md +++ b/quest/m5/net-wrap/README.md @@ -39,7 +39,7 @@ and its trait-versus-bridge comparison: `next_frame`, `read_chunk`, the broadcast consumer's `tracks` listing (maintainer, 2026-10-24), and their `poll_*` forms. A wrapper adapts - to moq-net, not the other way around: `moq_crypto::e2ee::Error` converts into + to moq-net, not the other way around: `moq_e2ee::Error` converts into `moq_net::Error`. - **Datagrams follow the datagram types.** Datagram tracks have their own producer and consumer types (`datagram::Producer::append` and `insert`, diff --git a/quest/m5/net-wrap/e2ee.md b/quest/m5/net-wrap/e2ee.md index c5e0ac4b18c..655e517d92e 100644 --- a/quest/m5/net-wrap/e2ee.md +++ b/quest/m5/net-wrap/e2ee.md @@ -1,8 +1,8 @@ -# [M] moq-crypto's e2ee implements the moq-net traits +# [M] moq-e2ee implements the moq-net traits ## Goal -moq-crypto's e2ee broadcast, track, and group wrappers implement the +moq-e2ee broadcast, track, and group wrappers implement the [moq-net traits](/quest/m5/net-wrap/traits.md), so anything generic over them publishes or consumes an encrypted broadcast unchanged, under semantic track names. @@ -12,56 +12,42 @@ names. The wrappers merged in #5876 diverge from moq-net, and they adapt to it, not the reverse (decided 2026-10-20, maintainer): -- `finish(self)` and `abort(self)` without an error become moq-net's - `finish` and `abort(self, Error)`. -- `track::Producer::create_group(u64)` takes `group::Info`. -- `broadcast::Consumer::subscribe(semantic, ..)`, which returns a - `kio::Pending`, becomes `track(semantic)` then `.subscribe(..)`. -- `moq_crypto::e2ee::Error` converts into `moq_net::Error`, keeping the draft's +- Done before this by [the finished format](/quest/m3/e2ee-format.md) + (decided 2026-11-16, maintainer, /quest-plan of the pre-cut audit): + `abort` takes an error, `broadcast::Consumer::subscribe` becomes + `track(semantic)` then `.subscribe(..)`, `track::Consumer` is renamed + `track::Subscriber`, and `name()` is the semantic name everywhere. + `track::Producer::create_group` is deleted there rather than changed to + take `group::Info`: a claim refuses any start at or below the highest + allocated, so it cannot go back as moq-net's can. The trait's + `create_group` therefore has no encrypted form; settle here whether the + trait splits it out or the wrapper answers it with a typed refusal. +- `moq_e2ee::Error` converts into `moq_net::Error`, keeping the draft's typed codes (such as an authentication failure) distinguishable rather than collapsing into `Error::Dropped`. - Datagrams: the wrapper's datagram producer and consumer match the separate datagram track types, so the trait read yields only authenticated datagrams. A datagram that fails authentication, or a duplicate, is dropped there and the track continues. The draft's `authentication` - event stays on moq-crypto's own consumer, outside the trait, for callers + event stays on moq-e2ee's own consumer, outside the trait, for callers that hold the concrete type. A trait read can't carry it without breaking the exact mirror. -- `track::Info.compression` is logical. Ciphertext doesn't compress, so the - wrapper compresses each group, and each datagram alone with a fresh - window, with moq-net's - [track compression](/doc/concept/compression.md) before AEAD, creates the - physical track uncompressed, and inflates after decryption. Sessions drop - a sealed datagram past the transport's datagram size as they drop an - oversized plaintext one, so document that the AEAD tag and any compression - growth count against the caller's payload budget. The physical size - describes ciphertext, so each sealed frame and datagram carries its - inflated size inside the authenticated payload: `frame::Info.size` stays - the logical size, the subscriber reserves only that declared size against - the same group and pool limits as a plain frame, and an inflate that - differs from it is an error, as moq-net's compression contract requires. - This keeps - [rust-publish](/quest/m5/e2ee/rust-publish.md)'s rule that protected - catalogs compress before encryption, and needs moq-net to expose its group - codec to the wrapper. `@moq/crypto` does the same in - [JS](/quest/m5/net-wrap/js.md). -- The subscriber's wrapper learns the logical flag from authenticated E2EE - metadata, never from the physical track (decided 2026-10-20, maintainer): - the physical track's `compression` is always `Compression::None`, so it can't signal it. - The metadata lives in the E2EE track mapping, and a flag that fails - authentication fails the track loudly. Not the encrypted catalog: the - catalog track is itself compressed, so a subscriber would need the flag - before it could inflate the catalog that carries it. The - [E2EE epic](/quest/m5/e2ee/README.md) also keeps catalog formats out of - moq-crypto, and the [compression migration](https://github.com/moq-dev/moq/pull/7046) dropped hang's - `compression` field. The subscriber needs the flag before inflating, - without changing moq-net's `track(name)`; propose the encoding in the PR. - Record it in `draft-lcurley-moq-e2ee.md`, replacing the Catalogs section's - `.z` sibling rule. +- Compression (decided 2026-11-16, maintainer, replacing the 2026-10-20 + plan to compress before AEAD and carry an authenticated flag and inflated + size): the profile carries no compression, so the payload stays + ciphertext plus tag and the draft gains nothing here. Compressing before + encrypting leaks length when a frame mixes a secret with input another + party chooses. An application that wants compression compresses its own + plaintext. What a trait writer's `track::Info.compression` means on an + encrypted track is this quest's to settle. Recommended: the wrapper + creates the physical track uncompressed and reports the logical track as + uncompressed, so writers work unchanged and a protected catalog ships + uncompressed; [rust-publish](/quest/m5/e2ee/rust-publish.md) and + [JS](/quest/m5/net-wrap/js.md) follow. - Datagram header allowance: a moq-lite datagram carries only Type, Subscribe ID, Sequence, and Timestamp, since datagram tracks dropped the relayed `ietf` fields and the Inflated Size from it, so - `MAX_DATAGRAM_HEADER` (28, `rs/moq-crypto/src/e2ee/limits.rs` and + `MAX_DATAGRAM_HEADER` (28, `rs/moq-e2ee/src/limits.rs` and `js/crypto/src/e2ee/limits.ts`) covers moq-lite. [moq-dev/moq#7959](https://github.com/moq-dev/moq/pull/7959) restores moq-transport datagrams using existing OBJECT_DATAGRAM framing, without adding header fields. Re-check the allowance if that framing changes. @@ -86,15 +72,15 @@ the reverse (decided 2026-10-20, maintainer): - Keep the nonce rules the epic specifies: a group producer still owns its frame numbering, and a re-created or re-served track name resumes above its high-water marks (decided 2026-10-25, maintainer, replacing the - refusal; moq-crypto's claims already resume). + refusal; moq-e2ee's claims already resume). - Test the wrappers against the questline's pass-through test cases. The moq-json round trip through an encrypted track waits for [moq-json to take the traits](/quest/m5/net-wrap/json.md). -Public API: the moq-crypto wrapper signatures change to moq-net's. Wire: -`draft-lcurley-moq-e2ee.md` gains the authenticated logical `compress` flag -and each compressed object's authenticated inflated size. +Public API: the moq-e2ee wrappers implement moq-net's traits and their +errors convert into `moq_net::Error`. Wire: none. ## Required - [moq-net traits](/quest/m5/net-wrap/traits.md) - the traits this implements +- [moq-e2ee publishes the finished format](/quest/m3/e2ee-format.md) - the wrapper names and signatures this starts from diff --git a/quest/m5/net-wrap/js.md b/quest/m5/net-wrap/js.md index f240f67ac67..f33ba22eac8 100644 --- a/quest/m5/net-wrap/js.md +++ b/quest/m5/net-wrap/js.md @@ -17,22 +17,22 @@ its own decryption path. `@moq/hang`'s catalog and container code, `@moq/publish`'s broadcast, and `@moq/watch`'s subscriptions. - `@moq/crypto`'s broadcast, track, and group wrappers adapt to `@moq/net`'s - method shapes, as moq-crypto does in Rust, with its errors mapped to - `@moq/net`'s. Like moq-crypto, it compresses a `compression: "deflate"` track before - encryption, publishes the physical track uncompressed, and carries the - logical flag in the same authenticated E2EE metadata - ([e2ee](/quest/m5/net-wrap/e2ee.md)). + method shapes, as moq-e2ee does in Rust, with its errors mapped to + `@moq/net`'s. Like moq-e2ee, it does not compress (decided 2026-11-16, + maintainer: the profile carries no compression): it publishes the + physical track uncompressed and follows whatever + [e2ee](/quest/m5/net-wrap/e2ee.md) settles for a logical + `compression: "deflate"` track. - Demand and preference cross the wrapper: a publisher with no viewer through an encrypted track stays idle. - Test publish and watch round trips through a pass-through wrapper and through `@moq/crypto`. Public API: new `@moq/net` interfaces; `@moq/crypto` wrapper signatures change. -Wire: the `draft-lcurley-moq-e2ee.md` compress flag from -[e2ee](/quest/m5/net-wrap/e2ee.md). +Wire: none. ## Required - [moq-net traits](/quest/m5/net-wrap/traits.md) - the names and methods this mirrors -- [moq-crypto's e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - owns the authenticated logical compression encoding this mirrors +- [moq-e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - settles what a logical compression flag means on an encrypted track, which this mirrors diff --git a/quest/m5/net-wrap/json.md b/quest/m5/net-wrap/json.md index 22ed8ddce23..514c33876f3 100644 --- a/quest/m5/net-wrap/json.md +++ b/quest/m5/net-wrap/json.md @@ -24,7 +24,7 @@ types, so each publishes into and reads from a wrapped track unchanged. wrapper, as do demand-gated encoders. - Existing tests keep passing with the defaults. Add one round trip per crate through moq-net's shared pass-through test wrapper, and a moq-json snapshot - round trip through an encrypted track in moq-crypto's tests. + round trip through an encrypted track in moq-e2ee's tests. Public API: generic type parameters with moq-net defaults on moq-json, moq-stats, and hang. Wire: none. @@ -32,4 +32,4 @@ moq-stats, and hang. Wire: none. ## Required - [moq-net traits](/quest/m5/net-wrap/traits.md) - the traits these take -- [moq-crypto's e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - the encrypted track the snapshot round trip runs through +- [moq-e2ee implements the traits](/quest/m5/net-wrap/e2ee.md) - the encrypted track the snapshot round trip runs through diff --git a/quest/m5/net-wrap/mux.md b/quest/m5/net-wrap/mux.md index f49a7f76cc3..4c6f6aef4cf 100644 --- a/quest/m5/net-wrap/mux.md +++ b/quest/m5/net-wrap/mux.md @@ -30,7 +30,7 @@ exporter reads one, without knowing. - No behavior change with the defaults. Keep the `containers` Criterion bench flat before and after. - Test an import and export round trip (fMP4 and TS) through the moq-net - pass-through test wrapper, plus one through moq-crypto's wrappers once + pass-through test wrapper, plus one through moq-e2ee's wrappers once [they implement the traits](/quest/m5/net-wrap/e2ee.md). Public API: generic type parameters with moq-net defaults across moq-mux. diff --git a/quest/m5/net-wrap/traits.md b/quest/m5/net-wrap/traits.md index d8bebbc5399..b503a70218c 100644 --- a/quest/m5/net-wrap/traits.md +++ b/quest/m5/net-wrap/traits.md @@ -29,7 +29,7 @@ the methods exactly as moq-net has them today. - Requests: a broadcast producer's `requests` returns its own `broadcast::Requests`, whose `requested_track` yields its own `track::Request`, so generic code serves undeclared names (as - `moq_crypto::e2ee::broadcast::Requests` does). A + `moq_e2ee::broadcast::Requests` does). A `track::Requests`'s `requested_fill` yields its own `track::Fill`, whose `accept` returns its own group producer and whose `drop_groups` names the rest dropped. diff --git a/quest/m5/probe-padding.md b/quest/m5/probe-padding.md index 0d4bda6ced0..605f6a968d4 100644 --- a/quest/m5/probe-padding.md +++ b/quest/m5/probe-padding.md @@ -14,6 +14,15 @@ probe to the larger of their send target and the peer's PROBE target. ## Plan +Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ lite-07 +freezes without the Padding Stream (0x2) and Padding Datagram (0x1) types, +removed by [the time-addressing rewrite](/quest/m2/time-addressing/lite07.md) +(rejected: keep the receive-only types for this quest). Nothing sent either. +If the rethink below still lands on padding, it adds its stream type in a +later lite version or a SETUP extension: an unaware peer resets an unknown +stream type and discards an unknown datagram type, so that costs no message +a lite-07 peer parses. + Moved to m5 2026-11-12 (maintainer, /quest-audit): parked for a rethink with no named consumer. Parked 2026-11-06 (maintainer, /quest-unblock): the maintainer doesn't think @@ -60,7 +69,9 @@ Decided with the maintainer on 2026-10-17 (see the lite-05 and lite-06 the peer resets every padding stream, so the estimate can never rise. Those sessions have no sender: refuse to pad and keep `Report`. Update `drafts/draft-lcurley-moq-probe.md` if the sender changes - what it says, and run `just drafts check`. + what it says (or the lite draft's Probe section, if + [the drafts cleanup](/quest/m2/drafts-retire.md) deleted that draft), and + run `just drafts check`. - A browser sender can't see whether it is app-limited; settle how to judge it from what it sends against the estimate. - Decided 2026-11-06 (maintainer, /quest-unblock): ✅ keep `setTarget` on diff --git a/quest/m3/ts-multi-program-restart.md b/quest/m5/ts-multi-program-restart.md similarity index 74% rename from quest/m3/ts-multi-program-restart.md rename to quest/m5/ts-multi-program-restart.md index f040776c5b8..4487bcd914a 100644 --- a/quest/m3/ts-multi-program-restart.md +++ b/quest/m5/ts-multi-program-restart.md @@ -13,6 +13,14 @@ multi-program sources back to back, one with a different ## Plan +Deferred 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ moved +from m3 to m5 (rejected: keeping it in m3 as work a named consumer waits +on). Nobody has asked for it: no downstream plan names `--program all`, and +the [MPEG-TS guide](/doc/bin/ts.md#programs-and-changes) marks that path +through a relay as "Rust tests only". What exists (`Programs`, about 1,040 +production lines) stays, finished and tested; it grows again when someone +asks. Start by confirming a user exists. + Planned 2026-11-04 with the maintainer, from #7780. That PR gave the single-program `Import` a restart for an identity change (`Step::Identity`: a PAT naming another identity restarts at that PAT rather than failing with @@ -32,5 +40,8 @@ import. rules for PAT changes that aren't a source switch (a moved PMT PID, a program added or removed) as they are. +[Typed TS outcomes](/quest/m2/ts-typed-outcomes.md) makes `Import`'s restart +a returned value; give `Programs` the same shape, not a second one. + Public API: possibly additive on `Programs` (a restart result like `Import`'s). Wire: none. diff --git a/rs/moq-net/tests/integration/subscribe_ranges.rs b/rs/moq-net/tests/integration/subscribe_ranges.rs index a335e9441e5..36b901cf566 100644 --- a/rs/moq-net/tests/integration/subscribe_ranges.rs +++ b/rs/moq-net/tests/integration/subscribe_ranges.rs @@ -778,16 +778,6 @@ async fn a_relay_with_holes_answers_a_wide_past_range_plus_live() { } } -/// [`a_relay_with_holes_answers_a_wide_past_range_plus_live`] over moq-transport, which marks -/// no hole, so one is skipped only once the reader's max age rules it out. -#[kio::test] -#[ignore = "stalls on a hole until /quest/m3/ietf-hole-stall.md"] -async fn a_relay_with_holes_answers_a_wide_past_range_plus_live_over_moq_transport() { - for version in ["moq-transport-18", "moq-transport-22"] { - holes_through_a_relay(version, Some(BUDGET)).await; - } -} - /// A budget the past range stays inside while it's read, and the live group then leaves behind. const BUDGET: Duration = Duration::from_secs(60); diff --git a/sh/gh/test-inventory.allow b/sh/gh/test-inventory.allow index cafe7bd985e..bca817e34d6 100644 --- a/sh/gh/test-inventory.allow +++ b/sh/gh/test-inventory.allow @@ -35,6 +35,3 @@ ignore moq-video::frame::tests::d3d11_resize_defaults_to_the_gpu /quest/m5/video ignore moq-video::frame::tests::d3d11_resize_matches_cpu /quest/m5/video-hardware.md ignore moq-video::render::export::dx12::tests::exports_an_nv12_texture /quest/m5/video-hardware.md ignore moq-video::render::export::dx12::tests::media_foundation_encodes_the_export_in_place /quest/m5/video-hardware.md - -# Fails until its quest fixes the bug it reproduces. -ignore moq-net::subscribe_ranges::a_relay_with_holes_answers_a_wide_past_range_plus_live_over_moq_transport /quest/m3/ietf-hole-stall.md diff --git a/test/interop/README.md b/test/interop/README.md index 5927bc14502..b6d234875ad 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -122,8 +122,9 @@ GStreamer checks the late tail alone. `moqsrc` keeps watching a finished broadcast, since an announcement means online/offline, so it has no end, withdrawal, or session to report. It joins once the broadcast has finished and requires exactly ten nonempty video buffers; its cell passes with the end check -marked N/A. A pinned moq-transport pass records the case as skipped until -[`quest/m3/ietf-finish.md`](../../quest/m3/ietf-finish.md) makes it pass. +marked N/A. A pinned moq-transport pass records the case as skipped: +moq-transport is a compatibility layer, and a finished broadcast's late tail +between our own clients is not planned work. Every client closes its session on the way out: publishers stop when their input ends (the browser on SIGTERM), and subscribers close once they have their frame. diff --git a/test/interop/interop.sh b/test/interop/interop.sh index fbd959d6539..a26849da70b 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -1778,13 +1778,13 @@ finish_marker() { run_finishes() { local pub sub name broadcast grant pid ack ack_fd reader_fd i started late - # moq-transport does not yet deliver a finished broadcast's late tail, withdrawal, and + # moq-transport does not deliver a finished broadcast's late tail, withdrawal, and # same-session health across clients, so a pinned moq-transport pass records the case as # skipped rather than red. if [[ "$VERSION" == moq-transport-* ]]; then for pub in "${PUB_LIST[@]}"; do for sub in "${SUB_LIST[@]}"; do - record skip case=finish publisher="$pub" subscriber="$sub" detail="moq-transport finish: quest/m3/ietf-finish.md" + record skip case=finish publisher="$pub" subscriber="$sub" detail="moq-transport finish: not supported" done done return