From 31d051e31045ca68816fb83556b631000b695b39 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 09:18:13 -0700 Subject: [PATCH 1/2] quest: plan the API audit of main against release Audit release (36f392f492) against main (d44813cb70) and plan the fixes: a new m1 epic, quest/m1/api-audit, with 27 children that remove unconsumed surfaces, collapse overlapping operations, mirror names across Rust, JS, and the bindings, and fill MIGRATE gaps. Two bug quests (NixOS cluster variable, Wayland display id), an m2 binding-durations quest, and updates to av-clock, ffi-poll-protocol, and the rate quests that the plan touches. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 3 + quest/m1/api-audit/README.md | 104 +++++++++++++++++++++ quest/m1/api-audit/announce-owner.md | 32 +++++++ quest/m1/api-audit/auth-access.md | 32 +++++++ quest/m1/api-audit/auth-clock-names.md | 23 +++++ quest/m1/api-audit/binding-state.md | 30 ++++++ quest/m1/api-audit/binding-trim.md | 32 +++++++ quest/m1/api-audit/clean-close.md | 20 ++++ quest/m1/api-audit/cli-flags.md | 39 ++++++++ quest/m1/api-audit/container-format.md | 38 ++++++++ quest/m1/api-audit/decode-read.md | 24 +++++ quest/m1/api-audit/derived-origin-close.md | 22 +++++ quest/m1/api-audit/gateway-api.md | 29 ++++++ quest/m1/api-audit/js-prepared.md | 36 +++++++ quest/m1/api-audit/largest-getter.md | 24 +++++ quest/m1/api-audit/media-trim.md | 49 ++++++++++ quest/m1/api-audit/migrate.md | 54 +++++++++++ quest/m1/api-audit/net-exports.md | 55 +++++++++++ quest/m1/api-audit/qmux-shape.md | 34 +++++++ quest/m1/api-audit/ranges-wire.md | 27 ++++++ quest/m1/api-audit/relay-config.md | 44 +++++++++ quest/m1/api-audit/resolve.md | 77 +++++++++++++++ quest/m1/api-audit/session-limits.md | 30 ++++++ quest/m1/api-audit/stats-naming.md | 41 ++++++++ quest/m1/api-audit/sync-wait.md | 42 +++++++++ quest/m1/api-audit/transport-config.md | 44 +++++++++ quest/m1/api-audit/unpublish.md | 38 ++++++++ quest/m1/api-audit/watch-trim.md | 34 +++++++ quest/m1/api-audit/wrapper-config.md | 23 +++++ quest/m1/av-clock.md | 9 +- quest/m1/nix-cluster-connect.md | 16 ++++ quest/m1/wayland-display-id.md | 23 +++++ quest/m2/README.md | 1 + quest/m2/ffi-durations.md | 22 +++++ quest/m2/ffi-poll-protocol.md | 10 ++ quest/m2/rate-grant.md | 2 +- quest/m2/rate-quic.md | 5 + quest/m2/rate-websocket.md | 5 + 38 files changed, 1168 insertions(+), 5 deletions(-) create mode 100644 quest/m1/api-audit/README.md create mode 100644 quest/m1/api-audit/announce-owner.md create mode 100644 quest/m1/api-audit/auth-access.md create mode 100644 quest/m1/api-audit/auth-clock-names.md create mode 100644 quest/m1/api-audit/binding-state.md create mode 100644 quest/m1/api-audit/binding-trim.md create mode 100644 quest/m1/api-audit/clean-close.md create mode 100644 quest/m1/api-audit/cli-flags.md create mode 100644 quest/m1/api-audit/container-format.md create mode 100644 quest/m1/api-audit/decode-read.md create mode 100644 quest/m1/api-audit/derived-origin-close.md create mode 100644 quest/m1/api-audit/gateway-api.md create mode 100644 quest/m1/api-audit/js-prepared.md create mode 100644 quest/m1/api-audit/largest-getter.md create mode 100644 quest/m1/api-audit/media-trim.md create mode 100644 quest/m1/api-audit/migrate.md create mode 100644 quest/m1/api-audit/net-exports.md create mode 100644 quest/m1/api-audit/qmux-shape.md create mode 100644 quest/m1/api-audit/ranges-wire.md create mode 100644 quest/m1/api-audit/relay-config.md create mode 100644 quest/m1/api-audit/resolve.md create mode 100644 quest/m1/api-audit/session-limits.md create mode 100644 quest/m1/api-audit/stats-naming.md create mode 100644 quest/m1/api-audit/sync-wait.md create mode 100644 quest/m1/api-audit/transport-config.md create mode 100644 quest/m1/api-audit/unpublish.md create mode 100644 quest/m1/api-audit/watch-trim.md create mode 100644 quest/m1/api-audit/wrapper-config.md create mode 100644 quest/m1/nix-cluster-connect.md create mode 100644 quest/m1/wayland-display-id.md create mode 100644 quest/m2/ffi-durations.md diff --git a/quest/m1/README.md b/quest/m1/README.md index c46e8eec290..049999521fd 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -81,6 +81,7 @@ lite-07 stream type here. - [Moxygen minimal interop](/quest/m1/smoke-moxygen.md) - waiting on Moxygen to send a registered filter type, then the smoke lane stops hiding its failure - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone +- [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break has its MIGRATE entry - [FETCH_OK whole group](/quest/m1/ietf-fetch-end-location.md) - on drafts 14 to 19, FETCH_OK End Object 0 means the whole group in both directions, and a FETCH ending at the maximum group is refused as unsupported - [Pause an IETF SUBSCRIBE](/quest/m1/ietf-subscribe-pause.md) - Forward=0 pauses a SUBSCRIBE without demand upstream and Forward=1 resumes it, instead of ending it - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface @@ -107,6 +108,8 @@ lite-07 stream type here. - [Track live signal](/quest/m1/track-live.md) - a reader can wait for its track's feed to be live, so a player skips old cached groups while a fresh upstream subscription starts - [moq-net compiles once](/quest/m1/net-erase-transport.md) - the session drivers stop monomorphizing per transport and per crate, saving several MiB of the relay, FFI library, `libmoq` and CLI - [Audio devices on ARM](/quest/m1/audio-devices-arm.md) - `just rs audio-devices` passes on the hosted ARM runner +- [NixOS leaf dials its root](/quest/m1/nix-cluster-connect.md) - the NixOS relay module sets the cluster variable the relay reads, so a leaf joins its root instead of running standalone +- [Wayland display id](/quest/m1/wayland-display-id.md) - a requested display id off X11 is refused or honored, never silently replaced by a portal pick shared across publications - [CI housekeeping](/quest/m1/ci-housekeeping.md) - validate queue nextest at 24 threads and remove the actionlint queue ignore after its release - [Interop audio delivery](/quest/m1/interop-audio.md) - every interop subscriber decodes and checks the publishers' 440 Hz tone, and the Rust publisher sends Opus and AAC - [Native audio decode conformance](/quest/m1/audio-decode-conformance.md) - Opus and AAC decode through every moq-audio backend, moq-c, and moq-ffi is checked against known tones and clips, like moq-video's suite diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md new file mode 100644 index 00000000000..47499d7e397 --- /dev/null +++ b/quest/m1/api-audit/README.md @@ -0,0 +1,104 @@ +# A smaller, safer API than release + +## Goal + +When `main` is cut into `release`, its public API is net smaller and harder +to misuse than `release`'s. Every surface added since release has a consumer +or is removed or made private. Overlapping operations are collapsed into one. +Names mirror across Rust, JS, and the bindings. Every break has its +`MIGRATE.md` entry. + +Non-goals: redesigning surfaces that already have their own quest (the +[public model](/quest/m1/public-model/README.md), +[subscribe ranges](/quest/m1/subscribe-ranges/README.md), +[archives](/quest/m1/archive/README.md), +[compressed tracks](/quest/m1/compress/README.md), +[A/V clock](/quest/m1/av-clock.md)), and inherited debt that a later quest +already reshapes. + +## Plan + +Planned 2026-10-22 from an audit of `release` (36f392f492) against `main` +(d44813cb70), 3,725 files changed. Seven read-only audits covered Rust +moq-net, `@moq/net`, the media crates, the bindings, `@moq/watch` and +`@moq/publish`, the native, relay, and transport crates, and the gateway and +misc crates. Consumers were checked in this repository, moq.pro (excluding its +vendored checkout), and moq.dev, the npm consumer of `@moq/watch` and +`@moq/publish`. A prior external audit was folded in; its corrections are +recorded where they matter. The maintainer approved every recommendation +wholesale ("quest-plan anything that you recommend"), so the choices in each +child's Plan are settled. + +Rules every child follows: + +- Removal beats addition. A surface with no consumer in the repository, + moq.pro, or moq.dev goes private or away. A consumer planned in a quest + counts only when that quest is in m1. +- Inherited debt is fixed here only when it is cheap or sits on a surface + this release breaks anyway. Otherwise it joins the later quest that + reshapes it (the ordered track reader joins + [foreign poll](/quest/m2/ffi-poll-protocol.md); binding durations get + [their own m2 quest](/quest/m2/ffi-durations.md)). +- Each child lists its public API and wire impact in its PR and writes its + own `MIGRATE.md` entries. + +Already gated elsewhere, so not children: the archive `Producer` and `Reader` +disagree on layout while both claim version 2 +([archive consumer](/quest/m1/archive/consumer.md)), and the binary-to-flate +fold is followed by flate's removal ([compress migrate](/quest/m1/compress/migrate.md)). +Both are in m1, so the cut waits for them. hang's +`Archive::replay_epoch` goes with the root `archive` section in +[catalog HLS](/quest/m1/archive/catalog-hls.md). + +Rejected in planning: + +- Restoring `track::Demand::{used, unused}`: [refresh](/quest/m1/refresh/README.md) + decided one `wanted()` signal. +- Removing `Audio.Decoder.arrivals()`: moq.dev has a planned consumer + waiting on this release. Only the video handle goes + ([watch trim](/quest/m1/api-audit/watch-trim.md)). +- Pulling hang's `Projection`, `Stereo`, and `AudioLayout`: the maintainer + decided 2026-10-20 to land the fields first. +- One terminal verb across bindings: Kotlin's `end` exists only because + `close` collides with `AutoCloseable`, and no single verb fits every + language's reserved names. +- A follow policy enum folding `linger` and `stitch`: one name per meaning + ([CLI flags](/quest/m1/api-audit/cli-flags.md)) fixes the confusion more + cheaply. + +## Required + +- [MIGRATE matches release](/quest/m1/api-audit/migrate.md) - every break already on main has a correct entry measured against release, and entries for unreleased packages are gone +- [Two broadcast resolutions](/quest/m1/api-audit/resolve.md) - Rust, JS, and the bindings resolve a broadcast with `request(path, epoch)` or `follow(path, epoch)`, and every racy two-step caller is gone +- [JS prepared answers](/quest/m1/api-audit/js-prepared.md) - a leaked or abandoned `Prepared` refuses its request instead of blocking the path +- [The origin announces](/quest/m1/api-audit/announce-owner.md) - a broadcast producer cannot announce; the origin hands out the announcement, so `Prepared` and standalone broadcasts lose methods that always fail +- [Sync.wait says what happened](/quest/m1/api-audit/sync-wait.md) - the decoder-facing `Sync` calls are internal and report present or skip; `jitter`, `probe`, and the `` compat shims are gone +- [Auth access is patterns](/quest/m1/api-audit/auth-access.md) - token claims and grants carry path patterns only until a rate quest enforces caps, and `Key::decode` is gone +- [Unpublish what nothing uses](/quest/m1/api-audit/unpublish.md) - packages, features, and listeners with no consumer stop shipping or stop being on by default +- [Container formats name inputs](/quest/m1/api-audit/container-format.md) - `ContainerFormat` names what is parsed, never how it is packaged; `ContainerStream` and TS passthrough internals are gone +- [Binding connection state](/quest/m1/api-audit/binding-state.md) - one `state()` snapshot and `state_changed()` replace `status`, `connects`, and both `failure` polls +- [moq-net exports with a consumer](/quest/m1/api-audit/net-exports.md) - Rust and JS model exports without a consumer go private, wrong ones are deleted, and JS names mirror Rust +- [largest is a getter](/quest/m1/api-audit/largest-getter.md) - `track::Producer::largest` is a plain read in Rust and JS, never a shared cursor +- [One clean close](/quest/m1/api-audit/clean-close.md) - a clean session close has one spelling and failures are recorded inside moq-net +- [Session limits only where needed](/quest/m1/api-audit/session-limits.md) - `session::Limits` keeps only bounds that nothing else enforces, and its documented example compiles +- [Ranges refuse what the wire drops](/quest/m1/api-audit/ranges-wire.md) - relative and time anchors fail loud where a wire cannot carry them, `floor()` honors the subscription, and bindings take an optional max delay +- [Derived origins borrow](/quest/m1/api-audit/derived-origin-close.md) - closing a JS `scope()` or `withPreference()` handle releases only that handle +- [Binding surface trim](/quest/m1/api-audit/binding-trim.md) - route input is separate from route observation, watch verbs are uniform, and unused binding objects are gone +- [Wrapper config names](/quest/m1/api-audit/wrapper-config.md) - Python, Go, and Dart client options use the FFI's names and nesting +- [One decode read](/quest/m1/api-audit/decode-read.md) - audio and video decoders yield the same `Frame`, `Gap`, `End` read as moq-mux containers +- [Watch and publish trim](/quest/m1/api-audit/watch-trim.md) - the clock is re-exported, unused watch outputs are gone, and derived publish state is read-only +- [Media surface trim](/quest/m1/api-audit/media-trim.md) - media crate items with no consumer go private, and Rust/JS media names agree +- [Stats names](/quest/m1/api-audit/stats-naming.md) - each stats track and reader has one name, and "stats" means one thing in the CLI +- [Gateway crate API](/quest/m1/api-audit/gateway-api.md) - rtmp and srt drop their unused `run` entry points and share builder names, and rtc has one router path +- [CLI and gst flags](/quest/m1/api-audit/cli-flags.md) - one flag name per meaning across CLI subcommands and gst elements, and `linger` means one thing +- [qmux shape](/quest/m1/api-audit/qmux-shape.md) - qmux binds framing at connect, shares flow-control names with moq-tokio, and JS drops the legacy wire +- [Transport config](/quest/m1/api-audit/transport-config.md) - moq-tokio and moq-quic configs have one meaning for unset, enums for modes, no order-dependent setters, and no leftover features +- [Relay config](/quest/m1/api-audit/relay-config.md) - moq-relay and its embedders load config through one path that refuses old spellings, under names that do not collide +- [Auth and clock names](/quest/m1/api-audit/auth-clock-names.md) - refusal and reason types have distinct names, and the Rust and JS clocks mirror each other + +## Related + +- [Claim request type](/quest/m1/public-model/claim-request-type.md) - removes `accept` from application requests; [the origin announces](/quest/m1/api-audit/announce-owner.md) narrows `Prepared` beside it +- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - moves readers onto the follow operation that [two broadcast resolutions](/quest/m1/api-audit/resolve.md) names +- [API-diff check on release PRs](/quest/m2/release/migrate-audit.md) - the backstop that catches breaks this epic misses +- [Main is no slower than release](/quest/m1/release-perf/README.md) - the other release-readiness check diff --git a/quest/m1/api-audit/announce-owner.md b/quest/m1/api-audit/announce-owner.md new file mode 100644 index 00000000000..8b06e16b98f --- /dev/null +++ b/quest/m1/api-audit/announce-owner.md @@ -0,0 +1,32 @@ +# [M] The origin announces + +## Goal + +A `broadcast::Producer` fills tracks; it cannot announce. Announcing is a +handle the origin hands out, so a `Prepared` answer and a standalone +`Info::produce()` broadcast no longer expose `announce`, `unannounce`, or +`route` calls that can only fail. + +## Plan + +Decided 2026-10-22 (API audit). Today `Prepared::broadcast()` +(`rs/moq-net/src/model/origin.rs`) returns a cloneable producer whose +`announce` fails with `Error::Closed` (documented in `MIGRATE.md`), and a +standalone broadcast's `announce`, `unannounce`, and `route` can never work +(inherited). The prior audit called the `Prepared` case a panic; it is an +error. + +- `origin::Producer::create_broadcast` (and `publish`) return the broadcast + plus an origin-owned announcement handle that carries `route`/`unannounce`. +- `Prepared` exposes only the fill surface; `publish` stays the one way to + answer. +- Mirror the shape in `@moq/net` if its producer has the same trap, and in + moq-ffi where the binding exposes announce on the broadcast. + +Public API: breaking in moq-net (and `@moq/net`/moq-ffi if they mirror the +trap). Wire: none. + +## Related + +- [Claim request type](/quest/m1/public-model/claim-request-type.md) - splits `accept` off application requests in the same file; coordinate the order +- [Public routes and answering](/quest/m1/public-model/answer.md) - later makes the forwarding claim public diff --git a/quest/m1/api-audit/auth-access.md b/quest/m1/api-audit/auth-access.md new file mode 100644 index 00000000000..af67fb756b8 --- /dev/null +++ b/quest/m1/api-audit/auth-access.md @@ -0,0 +1,32 @@ +# [M] Auth access is patterns + +## Goal + +moq-auth and `@moq/auth` claims, grants, and permissions carry path patterns +only, as on release, until a quest that enforces bitrate caps adds rates +back. No published token or grant field is one every relay refuses. The +`Key::decode` footgun that skips expiry and claim checks is gone. + +## Plan + +Decided 2026-10-22 (API audit). `rs/moq-auth/src/access.rs` added `Rate` and +`Access { path, rate }` in place of `Patterns` on `Claims`, `Grant`, and +`Permissions` (JS mirrors `Access`, `AccessSchema`), but +`rs/moq-relay/src/auth.rs` `check_rates` refuses any cap and +`doc/bin/relay/auth.md` says so. moq.pro's only use is a test asserting the +refusal. It also regressed ergonomics (`grant.publish` became +`grant.publish.path`) and added a second `Rate` beside +`moq_net::bandwidth::Rate`. + +- Revert to `Patterns`, delete `check_rates`, and drop the doc section. + Re-adding an optional rate later is additive, since no token carries one + today. +- Delete `Key::decode` (Rust `key.rs`, JS `key.ts`): no consumer outside + tests. +- Update [publisher caps](/quest/m2/rate-grant.md), + [QUIC rate](/quest/m2/rate-quic.md), and + [WebSocket rate](/quest/m2/rate-websocket.md): whichever enforces first + re-adds the claim, using `moq_net::bandwidth::Rate`. + +Public API: moq-auth and `@moq/auth` breaking against main, closer to +release. Wire: the token and grant lose the unenforced `rate` field. diff --git a/quest/m1/api-audit/auth-clock-names.md b/quest/m1/api-audit/auth-clock-names.md new file mode 100644 index 00000000000..67761ba24bd --- /dev/null +++ b/quest/m1/api-audit/auth-clock-names.md @@ -0,0 +1,23 @@ +# [S] Auth and clock names + +## Goal + +Refusal and reason types have distinct names across moq-auth and moq-net, +and moq-clock and `@moq/clock` mirror each other's names and shapes. + +## Plan + +Decided 2026-10-22 (API audit): + +- "Refusal" names three things (`moq_auth::Refusal`, the policy enum + `moq_auth::serve::Refusal`, `moq_net::stats::Refusal`) and "Reason" two + (`refusal::Reason`, `lease::Reason`). Rename the policy enum + `serve::Denial` and the stats one `RefusalKind`, or similar. +- Rust `moq_clock::anchor() -> (Instant, Wall)` (ns) versus JS + `origin(): Wall` (ms): name both `origin()` and document the unit split. + Rust `Manual::install` returns a handle while JS returns a closure: match. +- moq-net exposes both `time::now()` and `Instant::now()`; keep one. +- moq-auth's public times (`Claims`, `Grant::expires`) are `SystemTime`; + add them to [wall time](/quest/m1/time/wall.md). + +Public API: moq-auth, moq-net, moq-clock, `@moq/clock` renames. Wire: none. diff --git a/quest/m1/api-audit/binding-state.md b/quest/m1/api-audit/binding-state.md new file mode 100644 index 00000000000..7c5221d14b5 --- /dev/null +++ b/quest/m1/api-audit/binding-state.md @@ -0,0 +1,30 @@ +# [M] Binding connection state + +## Goal + +A binding caller watches one connection state instead of combining a +blocking status watcher, a polling loop, a reconnect counter, and terminal +closure. `MoqSession::state()` returns a snapshot (presence, connect count, +last failure, version) and `state_changed()` waits for the next one, +mirroring moq-tokio's `Monitor::snapshot`. `status()`, `connects()`, and both +`failure()` polls are gone. + +## Plan + +Decided 2026-10-22 (API audit). `rs/moq-ffi/src/session.rs` has +`MoqClient::failure` (#6131) and `MoqSession::failure` (#5723), both new and +polled because successive failures do not change `status()`. OBS combines +all of them (`cpp/obs/src/moq-output.cpp`, `moq-source.cpp`). Kotlin, Dart, +and Go hide the `Client`, so the first-dial failure is unreachable there. + +- `MoqClient::connect` returns the session at once in a connecting presence, + so the pre-session failure is part of the same state and + `MoqClient::failure` goes away. +- Name fields after moq-tokio's `Monitor` (`presence`, not `status`). +- Update every wrapper, OBS, and `doc/lib/*`. + +Public API: moq-ffi, moq-c, every wrapper, OBS breaking. Wire: none. + +## Related + +- [Go first-dial failure](/quest/m2/go-first-dial-failure.md) - becomes unnecessary once the state carries the first failure; delete it when this lands diff --git a/quest/m1/api-audit/binding-trim.md b/quest/m1/api-audit/binding-trim.md new file mode 100644 index 00000000000..e7991fd211e --- /dev/null +++ b/quest/m1/api-audit/binding-trim.md @@ -0,0 +1,32 @@ +# [S] Binding surface trim + +## Goal + +moq-ffi takes route input separately from route observation, uses one watch +verb pattern, and ships no objects without a consumer. + +## Plan + +Decided 2026-10-22 (API audit): + +- `MoqRoute` (`rs/moq-ffi/src/origin.rs`) is both an announce input and an + observation. Its writable `anonymous` is derived from `hops` on read and + ignored on input, and `hops` is writable on announce, so a local publisher + can fabricate a hop chain. Announce takes `MoqAnnounceRoute { cost, epoch }`; + `MoqRoute` stays observation-only with `anonymous` derived. Fix the doc that + pairs a route with `MoqOriginProducer::dynamic`, which takes none since + #5678. +- One watch pattern, `x()` and `x_changed()`: `MoqBandwidthConsumer::peek`/ + `changed` become `rate`/`rate_changed`; `MoqGroupDemand`'s + `is_used`/`used`/`unused` go with it. +- Remove `MoqGroupRequest::demand` and `MoqGroupDemand`; nothing beyond + wrapper pass-throughs uses them. +- `MoqBroadcastConsumer::resolve(reference, epoch)` takes two adjacent + `Option`s; take `MoqRendition`, as the rendition consumers do. +- Document that a dropped `MoqBroadcastFinish` closes the broadcast, which a + garbage-collected language (Kotlin, Go, Dart) does late. +- moq-c: `moq_bandwidth_set_target` has no consumer beyond the README; keep + it only if [native rung disable](/quest/m1/simulcast-rung-disable.md) uses + it. Align `moq_client_defaults` wrapping across languages. + +Public API: moq-ffi, moq-c, wrappers breaking. Wire: none. diff --git a/quest/m1/api-audit/clean-close.md b/quest/m1/api-audit/clean-close.md new file mode 100644 index 00000000000..e694e9aa72a --- /dev/null +++ b/quest/m1/api-audit/clean-close.md @@ -0,0 +1,20 @@ +# [S] One clean close + +## Goal + +A clean session close has one spelling in moq-net, so a caller tells success +from failure with one match arm. Session failures are recorded inside +moq-net, so `stats::Session::fail` is not public. + +## Plan + +Decided 2026-10-22 (API audit). A local close now maps to `Session(Cancel)` +(`rs/moq-net/src/session.rs`), contradicting the doc in `error.rs`, and +`rs/moq-relay/src/connection.rs` needs five arms to mean "not a failure". + +- Collapse the clean spellings into `Error::Cancel`, fixing the docs. +- Record failures where moq-net observes them and make + `stats::Session::fail` `pub(crate)`. +- Mirror in `@moq/net` if it has the same split. + +Public API: moq-net breaking (error mapping). Wire: none. diff --git a/quest/m1/api-audit/cli-flags.md b/quest/m1/api-audit/cli-flags.md new file mode 100644 index 00000000000..2d18e0be3f9 --- /dev/null +++ b/quest/m1/api-audit/cli-flags.md @@ -0,0 +1,39 @@ +# [S] CLI and gst flags + +## Goal + +One flag or property name means one thing across moq-cli subcommands and +the gst elements, and the same knob has the same name everywhere. + +## Plan + +Decided 2026-10-22 (API audit): + +- `export rtmp --max-delay` and `export flv --delay` name the same paced + release; use `--delay` on both (neither spelling was released). Delete the + hidden refusal of `--max-delay` on flv/mkv (`args.rs`): only released + spellings get refusals, and release had `--max-age` there. +- `--passthrough` means CMAF fragments on `import fmp4|hls` (#6250) and the + raw TS multiplex on `import|export ts`. Rename the fmp4/hls one to + `--container cmaf` or another distinct name, consistent with + [container formats](/quest/m1/api-audit/container-format.md). +- `linger`: publishers already linger on a clean end in rtmp, srt, rtc, and + the CLI. Drop moqsink's new boolean `linger` property and ``'s + `linger` attribute so every publisher lingers; NULL and `close` still end + at once. `linger` then means only the subscriber-side wait for a + replacement (`moq export --linger`). +- gst: moqsrc's `versions` (comma list) versus the CLI's repeatable + `--connect-version`; mirror one name, give moqsink the same, and give both + elements the same connection properties (moqsrc lacks + `quic-idle-timeout` and `quic-keep-alive`). moq-tokio has both + `client-version` and `connect-version`; keep one. +- `auth serve --key`/`--key-dir`/`--key-set` conflicts become clap + conflicts, not a runtime check. +- `--backoff-*` and `--goaway-*` take the `connect-` prefix their TOML keys + have; `export hls --listen-tls-*` stops sharing `MOQ_LISTEN_TLS_*` with the + MoQ listener; keep rustdoc links out of `--help`. + +Update `doc/bin/cli.md`, `doc/bin/gstreamer.md`, and every invocation in the +repo and moq.pro. + +Public API: CLI and gst breaking. Wire: none. diff --git a/quest/m1/api-audit/container-format.md b/quest/m1/api-audit/container-format.md new file mode 100644 index 00000000000..763b6226c2b --- /dev/null +++ b/quest/m1/api-audit/container-format.md @@ -0,0 +1,38 @@ +# [M] Container formats name inputs + +## Goal + +`moq_mux::import::ContainerFormat` names only what is parsed. How the import +is packaged (per-sample frames or preserved fragments) is never chosen by an +input-sounding name, and the format strings mean one thing each. +`ContainerStream` and the TS passthrough internals are not public. + +## Plan + +Decided 2026-10-22 (API audit). #6250 made `Fmp4` unwrap to per-sample frames +and added `Cmaf` for fragment passthrough over the same input +(`rs/moq-mux/src/import/format.rs`, `container.rs`). That flip was +deliberate; the defect is the naming axis. `"cmaf"` means passthrough while +`"m2ts"` means demux to TS, though the catalog's `m2ts` section means TS +passthrough, and `ts::Passthrough` is unreachable from `ContainerFormat`. + +- Delete `ContainerFormat::Cmaf` from Rust, moq-ffi, moq-c + (`MOQ_CONTAINER_FORMAT_CMAF`), and every wrapper enum; none has a caller. + Parse `"cmaf"` as `Fmp4`. Passthrough stays Rust-only through + `fmp4::Import::with_passthrough` and `moq_hls::import::Config::passthrough`, + which the CLI already uses. Rewrite the 8 binding MIGRATE entries #6250 + wrote. Chosen over a `ContainerInit::passthrough` flag because nothing + outside Rust asks for passthrough yet. +- Make the `"m2ts"` string agree with the catalog meaning, or rename it so it + does not collide; verify against callers first. +- Delete `ContainerStream` (`import/container.rs`, inherited, a line-for-line + copy of `Container`); `Container::new` with empty `ContainerInit::data` is + equivalent. Keep `Track` and `TrackStream`. Fix `doc/lib/layers.md`. +- TS passthrough (`container/ts/mod.rs`, `passthrough.rs`): make the module + private and export only `Passthrough`; fold its four error structs into + `moq_mux::Error` instead of `anyhow`; consider + `ts::passthrough::{Import, Export}` for the `Passthrough`/`Release` pair. +- Make `Container::cut()` and `fmp4::Import::discontinuity()` return + `Result` like `Track`'s. + +Public API: breaking in moq-mux, moq-ffi, moq-c, and wrappers. Wire: none. diff --git a/quest/m1/api-audit/decode-read.md b/quest/m1/api-audit/decode-read.md new file mode 100644 index 00000000000..bc6ffdae008 --- /dev/null +++ b/quest/m1/api-audit/decode-read.md @@ -0,0 +1,24 @@ +# [M] One decode read + +## Goal + +moq-audio and moq-video decoders yield the same read as moq-mux containers, +`decode::Read { Frame, Gap, End }`, so a player handles loss and the end of +a broadcast the same way for every media type. + +## Plan + +Decided 2026-10-22 (API audit). Today `moq_mux::container::Read` is +`{Frame{group}, Gap, End{group, end}}`, `moq_audio::decode::Read` +(`decode/consumer.rs`) signals loss with a `discontinuity` counter, and +`moq_video::decode::Consumer::read` returns a bare `Frame`, losing gaps and +the end while its docs call it a mirror of audio. + +- One shape modeled on moq-mux's, shared by audio and video decode. +- Callers: moq-c `audio.rs`, `moq play`, moq-ffi media readers. + +Public API: moq-audio, moq-video, moq-c breaking. Wire: none. + +## Related + +- [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - adjacent decode work diff --git a/quest/m1/api-audit/derived-origin-close.md b/quest/m1/api-audit/derived-origin-close.md new file mode 100644 index 00000000000..1483d5a57a1 --- /dev/null +++ b/quest/m1/api-audit/derived-origin-close.md @@ -0,0 +1,22 @@ +# [S] Derived origins borrow + +## Goal + +Closing a `@moq/net` origin handle derived with `scope()` releases only that +handle; only the owner closes the origin. + +## Plan + +Decided 2026-10-22 (API audit). Verified: `origin.scope(...).close()` closes +the owner (`js/net/src/origin.ts`), undercutting the `Table` interface, which +exists so a borrower cannot close the origin. `withPreference` is removed by +[moq-net exports](/quest/m1/api-audit/net-exports.md). + +- A derived handle's `close()` releases what that handle registered. +- moq.pro relies on the old behavior in `e2e/src/relay-stats.ts` and + `dev/smoke.ts`, where the scoped handle is the only one kept; note the + change in `js/net/MIGRATE.md` so the upgrade keeps the owner. + +Check Rust's derived handles for the same behavior and match. + +Public API: `@moq/net` behavior change. Wire: none. diff --git a/quest/m1/api-audit/gateway-api.md b/quest/m1/api-audit/gateway-api.md new file mode 100644 index 00000000000..2ee24a51659 --- /dev/null +++ b/quest/m1/api-audit/gateway-api.md @@ -0,0 +1,29 @@ +# [S] Gateway crate API + +## Goal + +moq-rtmp and moq-srt expose the entry points their consumers use, under the +same builder names for the same knobs, and moq-rtc has one router path. + +## Plan + +Decided 2026-10-22 (API audit): + +- Delete `moq_rtmp::{run, Config, ActivePaths, PathGuard}` and + `moq_srt::{run, Config}` (`listen.rs`). moq-cli drives `Server` directly + and moq.pro uses `Server` and `accept_stream`. This also drops srt + `Config`'s new `linger`/`stitch` fields that only `run` reached, and the + two configs' disagreeing names. Fix the Cargo.toml comments that say to + embed `run`. +- One builder vocabulary: rtmp `Client::with_import_max_age`, + `with_import_bandwidth`, `with_export_max_delay` and srt `with_max_age`, + `with_bandwidth`, `with_latency` become `with_max_age(impl + Into>)`, `with_bandwidth`, `with_max_delay`, documented as + ingest-only or egress-only. `Play::with_max_delay`'s argument stops being + named `latency`. Drop `moq_rtmp::DEFAULT_MAX_DELAY` (2 s, against the CLI's + 500 ms) and keep one default. +- moq-rtc: `Server::publish_router`/`subscribe_router` forward to + `whip::router`/`whep::router`; make the latter private. moq.pro uses + `whip::accept`, which stays. + +Public API: moq-rtmp, moq-srt, moq-rtc breaking. Wire: none. diff --git a/quest/m1/api-audit/js-prepared.md b/quest/m1/api-audit/js-prepared.md new file mode 100644 index 00000000000..84108f75c22 --- /dev/null +++ b/quest/m1/api-audit/js-prepared.md @@ -0,0 +1,36 @@ +# [S] JS prepared answers + +## Goal + +A `Prepared` answer in `@moq/net` owns its request the way Rust's does: +closing it, disposing it, or closing its broadcast before `publish()` refuses +the request, idempotently. A leaked or abandoned `Prepared` never blocks the +path, so the next requester reaches the handler again. + +## Plan + +Decided 2026-10-22 (API audit). Reproduced: after `prepare()` the request is +marked done, so the iterator's drop and `request.reject()` are no-ops. A +leaked `Prepared` stays pending, a second requester for the path joins it, +and the handler is never asked again until every requester or the claim +closes (`js/net/src/origin.ts`, `prepare`, `Prepared`, `ServeState.enqueue`). + +- Replace `Prepared.reject(err)` with an idempotent `close()` plus + `[Symbol.dispose]` (`Bandwidth.Reservation` is the precedent), mirroring + Rust where dropping a `Prepared` refuses with `Unroutable`. +- Closing `prepared.broadcast` before `publish()` abandons the request too. +- Make the `Prepared` constructor private with a static factory, and move + `Request.publisher`, `publishPrepared`, and `rejectPrepared` into module + hooks (the `finishRequest` pattern), so callers cannot bypass the done + state or the "forwarded requests cannot be prepared" check. +- Update `doc/lib/js/net.md`, the `js/net/MIGRATE.md` "A claim answers by + publishing" entry, and `origin-request.test.ts`; examples use `using`. + +Test: a handler that throws after `prepare()` leaves the path answerable by +the next request. moq.pro has no JS claim handlers. + +Public API: `@moq/net` breaking (`Prepared.reject` to `close`). Wire: none. + +## Related + +- [Claim request type](/quest/m1/public-model/claim-request-type.md) - the JS `accept` half lives there diff --git a/quest/m1/api-audit/largest-getter.md b/quest/m1/api-audit/largest-getter.md new file mode 100644 index 00000000000..a1f5a40a678 --- /dev/null +++ b/quest/m1/api-audit/largest-getter.md @@ -0,0 +1,24 @@ +# [S] largest is a getter + +## Goal + +Reading a track producer's largest position is a plain read in Rust and JS. +No caller polls a stream with a no-op waiter to fake a getter, and a second +JS caller can never hang because another consumed a shared cursor's update. + +## Plan + +Decided 2026-10-22 (API audit). Rust `track::Producer::largest(&mut self)` +(`rs/moq-net/src/model/track.rs`) is a stream on the writer; five production +callers use `poll_largest(&Waiter::noop())` as a getter (moq-mux +`catalog/producer.rs`, `ts/programs.rs`, moq-video `encode/producer.rs`). JS +`Track.Producer.largest()` (`js/net/src/track.ts`) keeps the cursor on the +shared handle; reproduced: one caller consumes an update and an independent +second caller waits forever. + +- Rust: `largest(&self) -> Option`, built on the private + `latest_sequence`. A caller that needs to wait uses the consumer side. +- JS: the same getter; if a waiting form has a consumer, it returns a fresh + cursor per call instead of sharing one. + +Public API: breaking in moq-net and `@moq/net`. Wire: none. diff --git a/quest/m1/api-audit/media-trim.md b/quest/m1/api-audit/media-trim.md new file mode 100644 index 00000000000..4e85c7fc329 --- /dev/null +++ b/quest/m1/api-audit/media-trim.md @@ -0,0 +1,49 @@ +# [S] Media surface trim + +## Goal + +Media crate and package items added since release have a consumer or are +private, and Rust and JS media APIs name the same thing the same way. + +## Plan + +Decided 2026-10-22 (API audit). Make `pub(crate)` or delete: + +- `fmp4::Import::dropped_metadata` and the FLV one. +- moq-audio `Applied` and `preset()`; settings mix `with_preset` with `pub` + fields, and moq-ffi's audio config accepts preset plus duration only to + refuse it at runtime. moq-video `Applied`, `Encoder::applied`, + `Sink::applied`. +- moq-video capture `Control`/`Driver` (only `publish_capture` is used), + `DmaBuf::new`, `DmaBufLayout` (until + [OBS Linux GPU](/quest/m3/obs-linux-gpu.md)). +- moq-hls `pub mod master`, range playlists, and `history`: the CLI never + sets history, so `?start=` always answers 416 while `doc/bin/hls.md` + documents it. Remove the docs with it; see + [history floor](/quest/m1/archive/history-floor.md). +- moq-archive `segment::*`, `Key`, and most of `Store`. +- moq-json `window::Checkpoint`, `Encoder::resume`, `Producer::{resume, cut}` + and `moq_mux::timeline::Producer::resume`, reached only by tests, unless + the [archive consumer](/quest/m1/archive/consumer.md) needs them. +- hang `Catalog::from_value`, `Section`/`deserialize_section`. +- The `@moq/loc` `Producer` (test-only, no Rust twin) and the JS + `Container.Consumer` `maxAge` guard. + +Make public for a consumer: moq-hls `Route`/`Resource` out of the `server` +feature, with `segment`/`init` taking the parsed id, so moq.pro's edge stops +copying `Route::parse` without its encoded-`/` refusal. + +Naming: + +- moq-audio `encode::Settings` becomes `Config` like video and decode; the + two `encode::Options` that mean different things get distinct names; audio + `Kind::Named` (a codec) goes, since video's names a backend. +- `hang::catalog::Range` (colour) and `moq_video::color::Range` duplicate + each other; keep one or add `From`. +- moq-json `pop` and `mutate` take arguments in the same order in Rust and + JS. +- JS publishers stamp the catalog `version` by hand; export one encode. +- `playback::Observer::finish(&self)` plus `finished()` forces polling; + return a future. + +Public API: removals and renames across media crates. Wire: none. diff --git a/quest/m1/api-audit/migrate.md b/quest/m1/api-audit/migrate.md new file mode 100644 index 00000000000..a59bc45b586 --- /dev/null +++ b/quest/m1/api-audit/migrate.md @@ -0,0 +1,54 @@ +# [S] MIGRATE matches release + +## Goal + +Every break already on `main` has a `MIGRATE.md` entry under `## Unreleased` +that is correct against `release`, not against an intermediate `main`. +Entries that describe APIs that never shipped are rewritten or deleted, and +packages that were never published carry no migration entries. + +## Plan + +Decided 2026-10-22 (API audit). Known gaps, verify each against +`git show origin/release:`: + +- Bindings: `MoqSession::shutdown` went from sync `()` to async `Result` + (7bbac32721); only `swift/MIGRATE.md` says so. Add it to `rs/moq-ffi`, + `py/moq-rs` (an un-awaited call is now a silent no-op), `go/wrapper` + (`Shutdown(ctx) error`, and `Client.Close()` now blocks while draining), + `kt/moq`, `dart/moq` (`Moq.close()` returns `Future`). +- Bindings: merge the contradictory `finish` entries ("removed (#4152)" and + "the new `finish` lets go (#6157)") into one: `finish()` now returns a + linger handle; call `close()` for the old behavior. +- Bindings: `MoqAudioInit.track` and `MoqVideoInit.track` moved to + `MoqMediaTarget::Named`, with no entry. +- `cpp/moq/MIGRATE.md`: about 130 lines for a package never released; empty + it. The generated-binding MIGRATEs (`go/ffi`, `py/moq-ffi`, `kt/moq-ffi`, + `swift/ffi`, `dart/moq_ffi`) list 4 of about 35 breaks plus checksum noise; + point them at `rs/moq-ffi/MIGRATE.md` instead. +- `rs/moq-net`: `finish_at(Position)`, `final_sequence` renamed `end()`, + `finished()` returning `Position`, and the transport error remapping + (`IdleTimeout`, `StreamError::from(Transport)`) have no entries. +- `rs/hang`: the #5715 entries describe a `timelines` shape that never + shipped; #4034 (`Range` to `Position`, `segment` to `sequence`, + `DEFAULT_NAME` to `SUFFIX`) and JS #5288 (`Container.Consumer.next()` + returns the `Read` union) have none. +- `rs/moq-archive`, `rs/moq-hls`: drop entries for unreleased intermediates + (`Writer`, `Info::epoch`, `Config::timebase`); add `Key::Groups`, + `Error::Bounds` to `Span`, `Rendition::segment(tag, n)`, and the segment URL + change to `seg/{reference}.{n}.m4s`. +- `rs/moq-video`: `frame::macos` to `apple`, `vulkan::Channels` to `Format`, + `Image` accessors becoming fields, `Handles::new` removed. +- `rs/moq-transcode`: `Rung::height` became `Rung::size`, meaning the short + side. Rename the field `short_side` in the same PR so the entry names the + final shape; moq.pro's `rs/transcode/src/ladder.rs` reads `.height`. +- `rs/moq-cli`: `--linger` worked on fmp4, mkv, flv, h264, and h265 on + release and now refuses a nonzero value; iroh left the default features + (#5581). +- `js/publish`: the "`Encoder.cut()` is not rate limited" entry describes an + API added after release (#4184); `cut()` is additive. +- `js/clock`: was private on release, so its rename entries become a + first-release note. + +Docs only, apart from the `short_side` rename. Other children write their own +entries. diff --git a/quest/m1/api-audit/net-exports.md b/quest/m1/api-audit/net-exports.md new file mode 100644 index 00000000000..0e69ac57b7b --- /dev/null +++ b/quest/m1/api-audit/net-exports.md @@ -0,0 +1,55 @@ +# [S] moq-net exports with a consumer + +## Goal + +Every public moq-net and `@moq/net` model item added since release has a +consumer in this repository, moq.pro, moq.dev, or an m1 quest. Items without +one go private or away, items that report wrong answers are deleted, and the +JS names for shared concepts match Rust. + +## Plan + +Decided 2026-10-22 (API audit). Keep the items an m1 quest consumes: +`origin::Preference` and `with_preference` (Rust, +[routes](/quest/m1/cluster-routing/routes.md)), and +`bandwidth::Allocator::set_target` with `transport::Probe` +([native probing](/quest/m1/probe-native.md), +[native rung disable](/quest/m1/simulcast-rung-disable.md)). + +Rust (`rs/moq-net/src/model/`), make `pub(crate)` or delete: + +- `Route::{auth, with_auth}` (benches only; reopen with + [in-band auth](/quest/m1/auth/README.md) if it needs them), + `broadcast::Lister` and `Dynamic::lister` (sessions only, and + `finish(&self)` does not end it), `stats::Handle::wire`, + `cache::Pool::gc` (poll-shaped, not named `poll_*`), + `origin::DEFAULT_UPDATE_HOLD` (external uses are test sleeps). +- `stats::Handle::request` returns a `Session` whose `fail()` does nothing: + fix or hide. +- `Producer::peer()`/`upstream()` set one private `Link`, and `peer()` after + `upstream()` silently does nothing: one builder taking the link. +- `auth::Handle::requests()` can fail `Duplicate`; move it to + `server::Handshake` where it is infallible. +- `moq_net::Role` at the crate root collides with `stats::Role`; rename one. + `Client::with_cost` takes `impl Into`. +- The `async` feature leaves `auth`, `goaway`, and `setup` public but + unobtainable; gate them with it. + +JS (`js/net/src/`): + +- Delete `Requesting.unroutable`: reproduced reading `true` while a local + `dynamic()` claim holds the request, and unused. +- Remove or make internal: `Origin.Preference` and `Producer.withPreference` + (no JS consumer), `Broadcast.Producer.demand()` and `Broadcast.Demand`, + `Auth.None`, `Auth.grantsEqual`, `Auth.Handle.requests()` with `Request`, + `Issued`, `Requests` (P2P is m2), `Epoch.toBytes`/`fromBytes` (wire only), + `Error.NoStreamCredit` (no Rust twin), and the runtime `Track.liteTimescale`. +- `Track.Demand.priority` is the publisher priority while + `Track.Request.priority` is the subscriber's; Rust `Demand` has none. + Remove it from `Demand` and have `Bandwidth.Allocator` read it from `Info`. +- Rename `Track.Location` to `Position`, matching Rust; this cycle already + changed every method that takes it. +- Stale docs: `{@link update}` and `{@link accept}` in `origin.ts`, `dynamic` + serving "tracks", undocumented `Timed`, `SessionCode`, `StreamCode`. + +Public API: removals and renames in moq-net and `@moq/net`. Wire: none. diff --git a/quest/m1/api-audit/qmux-shape.md b/quest/m1/api-audit/qmux-shape.md new file mode 100644 index 00000000000..442388f1b85 --- /dev/null +++ b/quest/m1/api-audit/qmux-shape.md @@ -0,0 +1,34 @@ +# [S] qmux shape + +## Goal + +qmux binds its framing once, at connect or accept, uses moq-tokio's names +for flow control in Rust and JS, has no order-dependent setters, and the JS +package speaks only the wire Rust speaks. + +## Plan + +Decided 2026-10-22 (API audit): + +- `transport::Stream::new(io, version, max_record_size)` + (`rs/qmux/src/transport.rs`) repeats what `Config` holds and breaks framing + silently on a mismatch; both consumers build the config twice. Take + `Stream::new(io)` and bind framing in `connect`/`accept`. +- Flow control has four vocabularies (qmux `max_data`/`max_stream_data`, + `moq_quic::mux` `max_concurrent_bidi_streams`, moq-tokio + `receive_window`/`stream_receive_window`, JS `maxData` plus a bigint + `maxIdleTimeout`). Adopt moq-tokio's names in qmux and `@moq/qmux`; + `max_datagram_frame_size` stops using 0 for off. +- `#[doc(hidden)]` `moq_quic::mux`, public only for qmux. +- `tcp::Config`/`uds::Config` setters must be called in order and + `session_config` drops version and protocol; use + `tcp::{connect, accept}(.., Config)` and the `with_session_config` name + tls/ws use. +- Delete `qmux::ALPNS` (duplicates `Version::ALL`), `Config::negotiated`, + `SendStream::reset_at`, and make `Session::send_group` private. +- `@moq/qmux` still speaks the legacy `webtransport` wire Rust removed in + #6231, falls back to it on accept, and defaults `frame.encode`/`decode` to + it. Delete it. + +Public API: qmux, moq-quic, `@moq/qmux` breaking. Wire: JS drops the +removed legacy framing. diff --git a/quest/m1/api-audit/ranges-wire.md b/quest/m1/api-audit/ranges-wire.md new file mode 100644 index 00000000000..179ed5991e0 --- /dev/null +++ b/quest/m1/api-audit/ranges-wire.md @@ -0,0 +1,27 @@ +# [S] Ranges refuse what the wire drops + +## Goal + +A subscription range with a relative or time anchor fails loud on a hop +whose upstream wire cannot carry it, instead of silently becoming live. +`floor()` honors `set_groups`, and the bindings take max delay as an +optional duration before their shape freezes. + +## Plan + +Decided 2026-10-22 (API audit). Keep the general range API (the +[subscribe ranges](/quest/m1/subscribe-ranges/README.md) line lands lite-07 +before the cut); fix only what the audit found broken: + +- `Anchor::Relative` and `Anchor::Time` are resolved at the serving hop and + otherwise degrade to live on wires that cannot carry them (published lite + versions, moq-transport without a local resolution). Refuse instead, with + a test on each wire. +- `floor()` ignores `set_groups` (`rs/moq-net/src/model/track.rs`); fix and + test. +- Bindings expose `max_delay_us` with zero meaning the live default; take + `max_delay: Option` (or the binding's optional) like Rust's + `Fetch::max_delay`. moq-hls `history.rs` works around the zero default with + a `(1 << 53) - 1` ms budget; remove that once it can say "unset". + +Public API: moq-ffi and wrappers breaking (max delay). Wire: none. diff --git a/quest/m1/api-audit/relay-config.md b/quest/m1/api-audit/relay-config.md new file mode 100644 index 00000000000..08e0072eb52 --- /dev/null +++ b/quest/m1/api-audit/relay-config.md @@ -0,0 +1,44 @@ +# [M] Relay config + +## Goal + +moq-relay and every embedder load configuration through one call that +refuses old spellings, and relay config names do not collide with module +names or each other. + +## Plan + +Decided 2026-10-22 (API audit): + +- One loader: `Config::merge_into(&CliLayer, &EnvLayer, Option)` + takes about 25 lines of setup, so moq.pro's edge bypasses it + (`toml::from_str` plus `update_from`) and `deprecated()` never runs: + `MOQ_SERVER_BIND` or `[server]` are silently ignored there. Provide one + call both binaries use (for example `moq_tokio::cli::load::()`) with + provenance, so an embedder can tell a set value from a default without + comparing against `Default`. +- `[session]` and `[peer]` collide with `moq_relay::session` and + `cluster::Peer`; rename to `[limits.client]` and `[limits.peer]`. +- `acme.dir` (a state path, documented required but typed `Option`) beside + `acme.directory` (the URL): rename `dir` to `acme.cache`; rustls-acme moves + behind an `acme` feature. +- `cluster.connect_api_tls_root` is flat while everything else nests + `*.tls.root`: `[cluster.api] url`, `tls.root`. +- `auth.verifications`/`Auth::with_verifications(usize)` is used only by a + bench and panics on 0: a private constant. +- `[listen|connect.extensions]` is TOML-only and unset everywhere: drop the + config field and `Web::with_extensions`, keep the Rust API. +- `uring::Workers::spawn` then `serve()` is order-dependent (`serve()` alone + no-ops): typestate `spawn(self) -> Spawned`. +- `cluster::with_client_tls` repeats TLS `with_connect` holds: delete. +- mTLS: `serve::Policy::{mtls_peer, mtls_upstream}` and the matching flags + can express "upstream without peer", refused at runtime; take + `Option` and one `--mtls-link` flag, keeping the + `Grant` wire booleans. +- Public only for tests: `Cluster::admit`, `cluster::Admitted`, and + `auth::hold` (move moq.pro onto them, since it keeps copies, or make them + `pub(crate)`); `Incoming`/`Accepted` behind `test-support`. +- Extend the `demo_configs_parse` test to `packaging/` and `test/`. + +Docs: `doc/bin/relay/`. Public API: moq-relay config and Rust API breaking; +old spellings are refused by name. Wire: none. diff --git a/quest/m1/api-audit/resolve.md b/quest/m1/api-audit/resolve.md new file mode 100644 index 00000000000..9bf6fc9f706 --- /dev/null +++ b/quest/m1/api-audit/resolve.md @@ -0,0 +1,77 @@ +# [L] Two broadcast resolutions + +## Goal + +An application resolves a broadcast in one of two ways, named the same in +Rust, JS, and every binding: + +- `request(path, epoch)` resolves one publisher instance. It owns the + discovery interest it needs, so on a watch-driven lite client it finds a + broadcast the peer serves without the caller watching the path first, and + it retries across route churn. It answers `Unroutable` only once discovery + has synced with no covering route. +- `follow(path, epoch)` follows the path across publisher instances (today's + `announced_broadcast`), pinned to `epoch` when given. + +No caller can assemble a racy two-step resolve, and no crate hand-rolls +"resolve once discovery synced". + +## Plan + +Decided 2026-10-22 (API audit, maintainer approved the recommendation). + +Rust `origin::Consumer` today has five overlapping operations +(`rs/moq-net/src/model/origin.rs`): `routed(path) -> Option` (swallows +errors), `follow(path) -> Follow` (route level), `routed_broadcast(path)` (no +epoch), `announced_broadcast(path, epoch)`, and `request_broadcast(path, +epoch)`. Per `rs/moq-net/MIGRATE.md`, `request_broadcast` on a client fails +`Unroutable` for a path no reader watches, even when the peer announces it, +and the bindings promote it as a top-level convenience. + +- Rust: `request(path, epoch) -> Pending` takes + `routed_broadcast`'s semantics plus the epoch pin and the synced + `Unroutable` answer, with no wall clock (relays never block on peers). + `follow(path, epoch)` is today's `announced_broadcast`. Delete `routed`, + `routed_broadcast`, and `Requesting::is_queued`. The immediate table lookup + (today's `request_broadcast`) and the route-level `Follow` become + `pub(crate)` for the sessions; route inspection stays where a consumer + needs it (the `routed()` callers in moq-cli reporting move to whatever + route observation remains public, or drop the report). +- JS (`js/net/src/origin.ts` `Consumer.request(path, {announced, epoch})`): + two methods, `request(path, {epoch})` and `follow(path, {epoch})`. Fix the + mismatch where `{announced: true, epoch}` closes when the instance ends + while Rust's pinned follow hands back the same instance if it returns. Drop + the silent fallback that turns `announced: true` into a blind request when + discovery is unavailable. `Producer.request`/`announced` pass-throughs stay + only if `Table` needs them. moq.pro's five `{announced: true}` sites move + to `follow`. +- Bindings: `request_broadcast(path, epoch)` and `announced_broadcast(path, + epoch)` map onto the two operations under the same names as Rust, and the + Kotlin, Dart, Go, and Python top-level shortcuts follow. +- Callers to fix: `rs/moq-wasm/src/lib.rs` (`routed()` then + `request_broadcast()`, error hidden by `.ok()`), `rs/moq-srt/src/ts.rs` + `Subscriber::new` (production), `rs/moq-cli/src/subscribe.rs` and + `report.rs`, `rs/moq-transcode/examples/transcode.rs`, + `rs/moq-bench/src/connection.rs`, the hand-rolled resolvers in + `rs/moq-mux/src/source.rs`, `rs/moq-hls/src/server/mod.rs` (wall-clock + `RESOLVE_TIMEOUT`) and `rs/moq-stats/src/aggregate.rs`, the + `rs/moq-relay/src/web.rs` fetch deadline, the `rs/moq-e2ee/MIGRATE.md` + advice to read the epoch via `routed()`, and + `demo/carla/sim/moq_carla_sim/publish.py`, which reads the epoch from an + announce and then requests unpinned. + +The prior audit's race claim is narrower than stated: discovery lingers 2 s +after `routed()` drops its follower, so the window is a route retraction or +failover between the two calls. + +Tests: a lite client resolves an announced but unwatched path; a pinned +`follow` hands back the same instance when its route returns, in Rust and JS. + +Public API: breaking in moq-net, `@moq/net`, moq-ffi, and every wrapper. +Wire: none. + +## Related + +- [Readers follow restarts](/quest/m1/sink-restart-follow.md) - moves readers to `follow`; whichever lands second adopts the other's names +- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - `moq_mux::Source::follow` builds on the follow operation +- [Origin fronts park](/quest/m2/origin-front-parks.md) - touches the same retry diff --git a/quest/m1/api-audit/session-limits.md b/quest/m1/api-audit/session-limits.md new file mode 100644 index 00000000000..56a0e39dfbc --- /dev/null +++ b/quest/m1/api-audit/session-limits.md @@ -0,0 +1,30 @@ +# [S] Session limits only where needed + +## Goal + +`moq_net::session::Limits` keeps only the bounds nothing else enforces. A +count that QUIC stream credit or the moq-transport request window already +bounds is not also a runtime refusal cap, and the documented example +compiles. + +## Plan + +Decided 2026-10-22 (API audit). `session.rs` `Limits` with three +`with_limits` builders (client, server, server request) caps subscriptions +and fetches, which AGENTS.md's rule against constants that only refuse at +runtime forbids where flow control already bounds the cost. The +`MIGRATE.md` example does not compile because the struct is +`#[non_exhaustive]`. + +This revisits part of the per-session request caps from #4820 (the m0 DoS +review), so prove each removal first: + +- For each cap, show which existing bound covers it on each version: lite + streams consume QUIC stream credit; drafts 14 to 16 have the request + window; later drafts have MAX_REQUEST_ID. Drop `subscriptions` and + `fetches` where covered, with a test that the peer is still bounded. +- Keep the bounds with no other limit, such as lite announces and the + drafts 14 to 16 request window. +- Fix the example (a constructor or `Default` plus field updates). + +Public API: moq-net `Limits` fields removed. Wire: none. diff --git a/quest/m1/api-audit/stats-naming.md b/quest/m1/api-audit/stats-naming.md new file mode 100644 index 00000000000..094eb5794fd --- /dev/null +++ b/quest/m1/api-audit/stats-naming.md @@ -0,0 +1,41 @@ +# [M] Stats names + +## Goal + +Each moq-stats track and reader has one name that says what it carries, an +encoding is a type rather than a bool, and "stats" means one thing in the +CLI. + +## Plan + +Decided 2026-10-22 (API audit): + +- `PREFIX = "traffic.json"` (`rs/moq-stats/src/lib.rs`), so `prefix_track()` + returns `traffic.json` while `traffic_track()` returns + `publisher.json`/`subscriber.json`. Rename the prefix track to + `/prefix.json`; update `doc/concept/stats.md` and the quests that + cite `traffic.json` ([QoS](/quest/m2/qos/README.md), + [lag dashboard](/quest/m2/qos-lag-dashboard.md), + [lag histogram](/quest/m2/qos/lag-histogram.md)). +- `consume::{Traffic, Totals, Presence, Prefix}` share names with the frame + types while `aggregate::` calls the same readers `*Consumer`; pick one + scheme. Fix the doc's "Sessions" heading versus `Presence` and + `FrameTooLarge` versus `FRAME_TOO_LARGE`. +- Five `*_track(.., compressed: bool)` functions plus `COMPRESSED_SUFFIX`: + take an `Encoding { Plain, Compressed }`, or nothing once + [compressed tracks](/quest/m1/compress/README.md) removes the suffix. +- CLI: `import --stats` adds a media report, `export stats` prints it, and + `--stats-*` publishes relay `.stats/`, which `export stats` cannot read. + Rename the media surfaces `import --report` and `export report` (the code + is `report.rs`), and drop the unused `--stats-*` flags from moq-cli. + `stats.interval` becomes a typed duration and `--stats-linger` gets help. + +moq.pro uses `traffic_track`, `sessions_track`, `COMPRESSED_SUFFIX`, and the +frame types; note each change in MIGRATE. + +Public API: moq-stats and moq-cli breaking. Wire: the prefix track name +changes. + +## Related + +- [Rust stats](/quest/m2/stats/rust.md) - builds on these CLI names diff --git a/quest/m1/api-audit/sync-wait.md b/quest/m1/api-audit/sync-wait.md new file mode 100644 index 00000000000..36322dc73ee --- /dev/null +++ b/quest/m1/api-audit/sync-wait.md @@ -0,0 +1,42 @@ +# [S] Sync.wait says what happened + +## Goal + +`@moq/watch`'s `Sync` stops publishing calls whose correct use depends on +hidden bookkeeping. The decoder-facing calls (`received`, `wait`, `register`) +are `@internal`, and `wait` resolves to whether the frame should be presented +or dropped (reset, skipped, closed, aborted, or unanchored), so no caller +checks `epoch` or `skipped()` around it. The duplicate `out.jitter`, the +dead `probe` input, and the `` compat shims are gone. + +## Plan + +Decided 2026-10-22 (API audit; private over a public result type because no +code outside the built-in decoders calls these, and keeping them private +until a consumer needs them is the rule). + +- `js/watch/src/sync.ts`: `wait(timestamp, signal?)` captures the epoch + itself and returns `Promise` (`true` presents now); it no longer + throws when unanchored. Delete `epoch`/`skipped` as caller-facing checks + and the pre-checks in `js/watch/src/video/decoder.ts`. Reproduced: a wait + resolves for a frame `skipped()` says not to render. +- `Sync.out.jitter` always equals `delay` since #4162, and `SyncInput.probe` + is stored but never read. Delete both, the element `jitter` getter + (`element.ts`), and show one delay readout in + `js/watch/src/ui/components/latency.ts` and `buffer-control.ts`. Point + `demo/web/src/viz.ts` and the audio-quality harness + (`test/audio-quality/clients/js/src/probe.ts`, `schema.ts`, which still + calls it the network portion) at `out.delay`. +- Delete the `` compat attributes `reload`, `latency`, + `latency-min`, `jitter` and the `@internal` `latency`/`latencyMin`/ + `latencyMax` accessors; nothing uses them (a stale comment in moq.pro + `pronto` mentions one). +- Smaller: `Sync.received`'s debug `label` parameter goes, `Sync.now()` + returns `Milli`, and `out.instant` is derived from `in.delay` if it stays. + +This lands before [A/V clock](/quest/m1/av-clock.md), which reshapes +`SyncInput` into per-track handles; that quest's Plan no longer drops +`probe`. + +Public API: `@moq/watch` breaking (`SyncInput.probe`, `out.jitter`, element +attributes, `Sync` methods going internal). Wire: none. diff --git a/quest/m1/api-audit/transport-config.md b/quest/m1/api-audit/transport-config.md new file mode 100644 index 00000000000..6c00cc90a4f --- /dev/null +++ b/quest/m1/api-audit/transport-config.md @@ -0,0 +1,44 @@ +# [M] Transport config + +## Goal + +moq-tokio and moq-quic configuration has one meaning for an unset value, +types modes as enums, has no fields that only one other field reads, and +ships no leftover features. + +## Plan + +Decided 2026-10-22 (API audit): + +- Optional durations: `None` means default in `connect`, `listen`, and + `quic`, yet hand-written `Default` impls fill `Some(DEFAULT_*)`; + `websocket::Options.timeout = None` means forever while `listen.timeout` + uses `Some(ZERO)` for forever. Derive `Default` as all-`None`, keep + defaults in `resolve()`/`Resolved`, and make zero always mean off. +- The `__cli_*` shadow `Duration` fields (about 10 in moq-tokio, plus relay + `config.rs`, `acme.rs`, `stats.rs`, `cache.rs`) let a CLI value silently + override an embedder's assignment; use one humantime newtype field per + duration. +- `quic.keylog: Option` plus `SSLKEYLOGFILE` (failing `KeylogUnset`) + becomes `keylog: Option` like `qlog`. +- `server::Config.tls` and `listen.tls` are exclusive by doc comment only, + and `tls::Listen.resolver` errors with either; `server.tls` overrides + `listen.tls`, and the resolver becomes `tls::Serve::resolver(r)`. +- `Request::ok()` returns `(Session, JoinHandle)` and most callers discard + the handle; return `Session` and surface a driver panic through + `closed()`. +- Delete `quic::Connection` (only wraps `set_limits`), + `worker::Config::with_pin` (unused), and one of `connect.once` or + `Client::with_reconnect(bool)`; the QUIC load balancer gets one config + path (`[listen.lb]`). +- moq-quic: drop the unused features (`rustls-ring`, `tracing-log`, `bloom`, + `platform-verifier`, fips, log) and the "backwards compat" `rustls` alias + in a new crate; gate `pub use rustls` on `any(ring, aws-lc-rs)` so it + exists under `rustls-aws-lc-rs`; point crate docs at + `moq_tokio::quic::driver` instead of quinn. +- Public only for tests: `lease::Producer::{due, failed}` and `Due` go + `pub(crate)` (drop the `tokio` feature), `connect::Config.quic` and + `listen::Config.quic` (read only by `deprecated()`) go `pub(crate)`, and + moq-uring `manual` and kio `sim` are renamed `_manual`/`_sim` or gated. + +Public API: moq-tokio, moq-quic breaking. Wire: none. diff --git a/quest/m1/api-audit/unpublish.md b/quest/m1/api-audit/unpublish.md new file mode 100644 index 00000000000..fed775391ed --- /dev/null +++ b/quest/m1/api-audit/unpublish.md @@ -0,0 +1,38 @@ +# [S] Unpublish what nothing uses + +## Goal + +Packages, crates, features, and listeners with no consumer stop shipping in +this release or stop being on by default, so the release promises nothing +it does not use. + +## Plan + +Decided 2026-10-22 (API audit): + +- `@moq/p2p` (`js/p2p/package.json`, first publish at 0.1.0, only `test/p2p` + consumes it): `"private": true` until [P2P watch](/quest/m2/p2p/watch.md). +- `moq-e2ee`: `publish = false` until [E2EE CLI](/quest/m2/e2ee/cli.md); + `@moq/e2ee` is already private. +- Rust `moq-room`: `publish = false`; no consumer here or in moq.pro (the JS + package has `demo/web`). `@moq/room` stops re-exporting the whole Hang, + Net, Publish, Signals, and Watch namespaces. +- `moq-boy`: `[[bin]] required-features = ["openh264"]`, so `cargo install` + fails at build time instead of building a binary that refuses to start. +- moq-cli: drop `webrtc` from default features + (`rs/moq-cli/Cargo.toml`); the CLI never calls it, yet every build pulls + str0m, moq-ice, mdns-sd, and if-addrs. moq-tokio's `webrtc` module stays + behind its feature, `#[doc(hidden)]` until [P2P CLI](/quest/m2/p2p/cli.md). +- moq-relay's STUN server (`pub mod stun`, `Config.stun`, 537 lines): gate + behind a non-default `stun` feature until + [UDP demux](/quest/m2/p2p/udp-demux.md); nothing sets `stun.bind` and it + forces `stun-types` onto default-features-off embedders. +- moq-rtc: revert `Client::publish`/`subscribe` to `Result<()>` and drop + `pub mod wire` and `Response.wire` until + [wire stats](/quest/m2/wire-stats/README.md) lands its consumer. +- moq-ice stays published (moq-tokio and moq-rtc depend on it); document it + as internal with no stability promise and give `Socket` a constructor that + enforces non-empty `locals`. +- `qmux` 0.7.0 publishes without a README; add one. + +Public API: removes unconsumed surface. Wire: none. diff --git a/quest/m1/api-audit/watch-trim.md b/quest/m1/api-audit/watch-trim.md new file mode 100644 index 00000000000..1ae72b8adac --- /dev/null +++ b/quest/m1/api-audit/watch-trim.md @@ -0,0 +1,34 @@ +# [S] Watch and publish trim + +## Goal + +`@moq/watch`, `@moq/publish`, and `@moq/room` users can name every type +their public signatures take without a new direct dependency, unused watch +outputs are gone, and state a component derives is read-only to callers. + +## Plan + +Decided 2026-10-22 (API audit): + +- Watch, publish, and room types now take `Milli`/`Nano` from `@moq/clock` + and `Net.Time.Milli` is gone, but none re-exports the clock. moq.dev calls + `Net.Time.Milli` through `@moq/watch`. Add `export * as Clock from + "@moq/clock"` to each entrypoint (js/AGENTS.md re-exports dependencies + under namespaces) and MIGRATE entries in watch and publish. +- Delete `Video.Decoder.arrivals()` and its producer plumbing; nothing uses + it. Keep `Audio.Decoder.arrivals()` (moq.dev's voice buffers wait on it) + and document that an open handle must be read or closed, since each + observer queues every event. +- Delete `Player.error` and the element `error` getter (nothing reads them), + and make `out.error` types consistent across sources, decoders, and the + renderer. +- `Audio.Decoder.out.underruns` moves into `Stats.underruns`, as + [JS stats](/quest/m2/stats/js.md) plans. +- `Publish.Broadcast.net` (`js/publish/src/broadcast.ts`) is a writable + `Signal` (inherited); expose a `Getter` backed by private state. +- Small: mark `Watch.Broadcast.relativeBroadcast` `@internal`; make the + `fade` knobs private constants; trim publish `parseBackend` like watch's; + publish support reports `aac` as a `Level` like watch. + +Public API: `@moq/watch`, `@moq/publish`, `@moq/room` (additive re-exports, +removals). Wire: none. diff --git a/quest/m1/api-audit/wrapper-config.md b/quest/m1/api-audit/wrapper-config.md new file mode 100644 index 00000000000..73b6c3c3139 --- /dev/null +++ b/quest/m1/api-audit/wrapper-config.md @@ -0,0 +1,23 @@ +# [M] Wrapper config names + +## Goal + +Python, Go, and Dart client options use the FFI's names and nesting +(`tls.insecure`, `once`, nested `tls`, `quic`, `websocket`, `backoff`), as +Swift, Kotlin, and C++ already do, and Go takes an options struct as +`rs/moq-ffi/AGENTS.md` requires. + +## Plan + +Decided 2026-10-22 (API audit). #4519 renamed the FFI to moq-tokio's names; +Python (`py/moq-rs/.../client.py` `tls_verify`, `reconnect`), Go +(`WithTLSVerify`, `WithReconnect`, now 25 functional options), and Dart +(`tlsVerify`) kept the old ones. + +- Rename to the FFI names and nesting. Keep each language's idiomatic + duration type at the wrapper boundary; + [binding durations](/quest/m2/ffi-durations.md) moves the FFI itself off + `_us` integers later. +- Go: replace functional options with a config struct. + +Public API: Python, Go, Dart wrappers breaking. Wire: none. diff --git a/quest/m1/av-clock.md b/quest/m1/av-clock.md index 6820aeeef11..b21dda4d35d 100644 --- a/quest/m1/av-clock.md +++ b/quest/m1/av-clock.md @@ -28,10 +28,11 @@ and a third track joins without another pair of inputs; `Sync.register` already keeps one jitter entry per track and grows into the handles. The measured target per track comes from the [Audio jitter target](/quest/m1/audio-jitter-target/README.md) line: each decoder registers -its own target through `Sync.register`, and `probe` stays in `SyncInput` unread -so that line lands on `main`. This quest folds the registrations into the -handles and drops `probe`. `SyncInput` is a published `@moq/watch` shape, so -this is a break. +its own target through `Sync.register`. This quest folds the registrations +into the handles. `SyncInput` is a published `@moq/watch` shape, so this is a +break. [Sync.wait says what happened](/quest/m1/api-audit/sync-wait.md) lands +first: it drops `probe` and `out.jitter` and makes the decoder-facing calls +internal, with `wait` reporting present or skip, so the handles build on that. Recommendations for the implementation: diff --git a/quest/m1/nix-cluster-connect.md b/quest/m1/nix-cluster-connect.md new file mode 100644 index 00000000000..9a547a3ce9e --- /dev/null +++ b/quest/m1/nix-cluster-connect.md @@ -0,0 +1,16 @@ +# [XS] NixOS leaf dials its root + +## Goal + +A relay deployed with `nix/modules/moq-relay.nix` and a cluster root URL +joins that root. Today the module sets `MOQ_CLUSTER_ROOT`, which nothing +reads; the relay reads `MOQ_CLUSTER_CONNECT` +(`rs/moq-relay/src/settings.rs`), and unknown `MOQ_*` variables are silently +ignored, so a NixOS leaf runs standalone. + +## Plan + +Found 2026-10-22 by the API audit (inherited from release). Rename the +variable in the module, check the module's other `MOQ_*` names against +`settings.rs`, and add a check (a NixOS VM test or an eval-time assertion) +that every variable the module sets is one the relay reads. diff --git a/quest/m1/wayland-display-id.md b/quest/m1/wayland-display-id.md new file mode 100644 index 00000000000..5ae9a609966 --- /dev/null +++ b/quest/m1/wayland-display-id.md @@ -0,0 +1,23 @@ +# [S] Wayland display id + +## Goal + +Asking moq-video to capture a specific display off X11 either captures that +display or fails loud. It never silently opens the screen portal instead, +and one publication's portal choice never leaks into another's. + +## Plan + +Found 2026-10-22 by the API audit (a regression since release). In +`rs/moq-video/src/capture/mod.rs`, `Source::Display(Some(id))` without X11 +only logs at debug level and opens the portal, and `pipewire.rs` keeps a +process-global `static DISPLAY` portal selection shared across publications. + +- Refuse `Display(Some)` off X11 with a typed error, and have moq-cli pass + `Source::Portal(Selection::new(Kind::Screen))` there, as `--window` already + does. +- Scope the portal selection to its publication. + +## Related + +- [Linux capture](/quest/m2/capture-linux.md) - the broader Linux capture work diff --git a/quest/m2/README.md b/quest/m2/README.md index d5d9f8cc95f..75a4f817739 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -34,6 +34,7 @@ ranked just below deterministic TS legs, which it requires. - [Kotlin calls](/quest/m2/kt-ffi-calls.md) - Kotlin calls into moq-ffi cost about what Python's and Go's do, sync and async, once the fork's Kotlin generator drops JNA's per-call overhead - [Poll-native async](/quest/m2/ffi-poll-migrate.md) - moq-ffi's pure-kio async exports poll their state directly instead of going through `ffi::Task` - [Foreign poll for hot reads](/quest/m2/ffi-poll-protocol.md) - the fork's generators give each wrapper a sync poll plus a registered waker for track and group reads, so a ready read skips the event-loop round trip and a cancel never loses a frame +- [Binding durations](/quest/m2/ffi-durations.md) - moq-ffi takes and returns durations as a typed duration instead of `_us` integers, so wrappers stop converting by hand - [QoS](/quest/m2/qos/README.md) - the relay's egress `lag` histogram and `dropped` counters on the stats totals and prefix tracks - [Plan: watch worker](/quest/m2/plan-watch-worker.md) - prototype an invisible page worker against app-spawned workers, and land the jank harness that decides - [Watch worker](/quest/m2/watch-worker.md) - watch playback runs in a worker onto an OffscreenCanvas, so main-thread jank never stalls video or audio diff --git a/quest/m2/ffi-durations.md b/quest/m2/ffi-durations.md new file mode 100644 index 00000000000..0d386be253a --- /dev/null +++ b/quest/m2/ffi-durations.md @@ -0,0 +1,22 @@ +# [L] Binding durations + +## Goal + +moq-ffi takes and returns durations as a typed duration instead of about 20 +`_us` integer fields, so no wrapper converts microseconds by hand, matching +rs/AGENTS.md's typed-units rule. + +## Plan + +Planned 2026-10-22 from the API audit +([wrapper config names](/quest/m1/api-audit/wrapper-config.md) fixes the +names in m1). Today Kotlin (`Durations.kt`), Dart (`durations.dart`), Go +(`backoffMicros`), and Python (`timedelta`) each convert. First check that +UniFFI's builtin `Duration` maps through the Go, C++, and Dart generator +forks; if not, it waits on [the generator fork](/quest/m2/uniffi-fork.md). + +Public API: moq-ffi, moq-c, every wrapper breaking. Wire: none. + +## Related + +- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - the same move for media timestamps diff --git a/quest/m2/ffi-poll-protocol.md b/quest/m2/ffi-poll-protocol.md index b86869191e1..da52aa362b1 100644 --- a/quest/m2/ffi-poll-protocol.md +++ b/quest/m2/ffi-poll-protocol.md @@ -52,6 +52,16 @@ Things to carry over and check: spike's Python and Go cancel probes are a starting point. - **Concurrent pollers on one handle share one waker.** Pick a semantic and test it: either reject a second concurrent read, or wake every poller. +- **Reader modes are chosen up front** (API audit, 2026-10-22). Today one + `MoqTrackConsumer` offers arrival-order reads, ordered reads, and + `read_frame`; the first read commits a mode and later calls fail + `AlreadyCommitted`, and track-level `read_frame` silently returns only each + group's first frame (`rs/moq-ffi/src/consumer.rs`, inherited from release). + Since this quest reshapes these reads anyway, land the split here so they + break once: `MoqTrackConsumer::ordered() -> MoqOrderedTrackConsumer` takes + over the handle like Rust's `Subscriber::ordered()`, the base consumer keeps + `recv_*`, and `read_frame` moves to the ordered reader returning the group + and frame position like JS. Python's `__aiter__` stops committing silently. - Measure every generated wrapper (Go, Python, Kotlin, Swift, Dart, C++); the spike covered only Go and Python. Sweep publishers as well as subscribers, since the generator's callback-handle map diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index 0686e4b5fb8..e848b45181f 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -17,7 +17,7 @@ re-clamps a live encoder. Decided in the quest audit: this quest owns net's in-band grants, their lite codecs, relay propagation, and publisher clamps. Token and HTTP grant types in -`moq-auth` and `js/auth` already carry [bitrate caps](/doc/bin/relay/auth.md#claims); reuse their admitted caps here. +Token claims carry no bitrate caps since [auth access is patterns](/quest/m1/api-audit/auth-access.md) removed the field nothing enforced; whichever rate quest enforces first re-adds an optional `rate` to the claims using `moq_net::bandwidth::Rate`, and this quest reuses the admitted caps. Update the AUTH grant in `drafts/draft-lcurley-moq-lite.md` and run `just drafts check`. Rates target the next unpublished lite version after finalized lite-07, diff --git a/quest/m2/rate-quic.md b/quest/m2/rate-quic.md index a77910c7897..423df408e8a 100644 --- a/quest/m2/rate-quic.md +++ b/quest/m2/rate-quic.md @@ -9,6 +9,11 @@ refused. ## Plan +The token claim this quest enforces does not exist yet: [auth access is +patterns](/quest/m1/api-audit/auth-access.md) removed the unenforced +`publish.rate`/`subscribe.rate` fields before the release. Whichever rate +quest lands first re-adds them as optional, using `moq_net::bandwidth::Rate`. + Decided in the 2026-10-04 plan: enforce in the QUIC stack, through backpressure the peer cannot ignore, rather than metering and closing. diff --git a/quest/m2/rate-websocket.md b/quest/m2/rate-websocket.md index 6df298227b4..ad47d244a50 100644 --- a/quest/m2/rate-websocket.md +++ b/quest/m2/rate-websocket.md @@ -9,6 +9,11 @@ HTTP `/fetch` and `/announced` keep refusing capped tokens; see ## Plan +The token claim this quest enforces does not exist yet: [auth access is +patterns](/quest/m1/api-audit/auth-access.md) removed the unenforced +`publish.rate`/`subscribe.rate` fields before the release. Whichever rate +quest lands first re-adds them as optional, using `moq_net::bandwidth::Rate`. + TCP carries the backpressure, but only if the kernel cannot absorb the excess: From d4e606af76ed38db3eb3be98625d5ede56c9a40f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 09:24:34 -0700 Subject: [PATCH 2/2] quest: keep moq-auth's rate type off moq-net Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/auth-access.md | 4 +++- quest/m2/rate-grant.md | 2 +- quest/m2/rate-quic.md | 4 +++- quest/m2/rate-websocket.md | 4 +++- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/quest/m1/api-audit/auth-access.md b/quest/m1/api-audit/auth-access.md index af67fb756b8..c25f7943975 100644 --- a/quest/m1/api-audit/auth-access.md +++ b/quest/m1/api-audit/auth-access.md @@ -26,7 +26,9 @@ refusal. It also regressed ergonomics (`grant.publish` became - Update [publisher caps](/quest/m2/rate-grant.md), [QUIC rate](/quest/m2/rate-quic.md), and [WebSocket rate](/quest/m2/rate-websocket.md): whichever enforces first - re-adds the claim, using `moq_net::bandwidth::Rate`. + re-adds the claim with a rate type moq-auth owns (or a lower shared units + crate), converted at the relay boundary, so moq-auth never depends on + moq-net. Public API: moq-auth and `@moq/auth` breaking against main, closer to release. Wire: the token and grant lose the unenforced `rate` field. diff --git a/quest/m2/rate-grant.md b/quest/m2/rate-grant.md index e848b45181f..d85d797b17e 100644 --- a/quest/m2/rate-grant.md +++ b/quest/m2/rate-grant.md @@ -17,7 +17,7 @@ re-clamps a live encoder. Decided in the quest audit: this quest owns net's in-band grants, their lite codecs, relay propagation, and publisher clamps. Token and HTTP grant types in -Token claims carry no bitrate caps since [auth access is patterns](/quest/m1/api-audit/auth-access.md) removed the field nothing enforced; whichever rate quest enforces first re-adds an optional `rate` to the claims using `moq_net::bandwidth::Rate`, and this quest reuses the admitted caps. +Token claims carry no bitrate caps since [auth access is patterns](/quest/m1/api-audit/auth-access.md) removed the field nothing enforced; whichever rate quest enforces first re-adds an optional `rate` to the claims with a rate type moq-auth owns (converted at the relay boundary, so moq-auth never depends on moq-net), and this quest reuses the admitted caps. Update the AUTH grant in `drafts/draft-lcurley-moq-lite.md` and run `just drafts check`. Rates target the next unpublished lite version after finalized lite-07, diff --git a/quest/m2/rate-quic.md b/quest/m2/rate-quic.md index 423df408e8a..256eb569286 100644 --- a/quest/m2/rate-quic.md +++ b/quest/m2/rate-quic.md @@ -12,7 +12,9 @@ refused. The token claim this quest enforces does not exist yet: [auth access is patterns](/quest/m1/api-audit/auth-access.md) removed the unenforced `publish.rate`/`subscribe.rate` fields before the release. Whichever rate -quest lands first re-adds them as optional, using `moq_net::bandwidth::Rate`. +quest lands first re-adds them as optional, with a rate type moq-auth owns +(or a lower shared units crate), converted at the relay boundary so moq-auth +never depends on moq-net. Decided in the 2026-10-04 plan: enforce in the QUIC stack, through backpressure the peer cannot ignore, rather than metering and closing. diff --git a/quest/m2/rate-websocket.md b/quest/m2/rate-websocket.md index ad47d244a50..b863efdeb14 100644 --- a/quest/m2/rate-websocket.md +++ b/quest/m2/rate-websocket.md @@ -12,7 +12,9 @@ HTTP `/fetch` and `/announced` keep refusing capped tokens; see The token claim this quest enforces does not exist yet: [auth access is patterns](/quest/m1/api-audit/auth-access.md) removed the unenforced `publish.rate`/`subscribe.rate` fields before the release. Whichever rate -quest lands first re-adds them as optional, using `moq_net::bandwidth::Rate`. +quest lands first re-adds them as optional, with a rate type moq-auth owns +(or a lower shared units crate), converted at the relay boundary so moq-auth +never depends on moq-net. TCP carries the backpressure, but only if the kernel cannot absorb the excess: