Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
104 changes: 104 additions & 0 deletions quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
@@ -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 `<moq-watch>` 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
32 changes: 32 additions & 0 deletions quest/m1/api-audit/announce-owner.md
Original file line number Diff line number Diff line change
@@ -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
34 changes: 34 additions & 0 deletions quest/m1/api-audit/auth-access.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# [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 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.
23 changes: 23 additions & 0 deletions quest/m1/api-audit/auth-clock-names.md
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 30 additions & 0 deletions quest/m1/api-audit/binding-state.md
Original file line number Diff line number Diff line change
@@ -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
32 changes: 32 additions & 0 deletions quest/m1/api-audit/binding-trim.md
Original file line number Diff line number Diff line change
@@ -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<String>`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.
20 changes: 20 additions & 0 deletions quest/m1/api-audit/clean-close.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading