Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
daf5d61
quest: plan the API shape fixes from the release-vs-main audit
kixelated Nov 7, 2026
c0bf001
Merge branch 'base' into pr-8191
Nov 7, 2026
9be112e
fix(quest): keep route session audit additions in Plan
Nov 7, 2026
2e3bf6c
Merge remote-tracking branch 'origin/main' into quest-plan/api-sweep
kixelated Nov 7, 2026
82e6784
quest: plan the API fixes from a sweep of open PRs and remaining quests
kixelated Nov 7, 2026
def9c26
Merge remote-tracking branch 'origin/quest-plan/api-shape-audit' into…
kixelated Nov 7, 2026
9da67d5
Merge remote-tracking branch 'origin/main' into fix/api-plan-review
kixelated Nov 7, 2026
356439f
quest: address review threads on the API sweep plan
kixelated Nov 8, 2026
87a6374
Merge remote-tracking branch 'origin/main' into fix/api-plan-review
kixelated Nov 8, 2026
0a7085b
quest: #8088 has merged
kixelated Nov 8, 2026
9baf17a
Merge remote-tracking branch 'origin/main' into quest-plan/api-sweep
kixelated Nov 8, 2026
cca5848
quest: apply the API sweep's /quest-complete decisions
kixelated Nov 8, 2026
b78644a
Merge remote-tracking branch 'origin/main' into chore/iterate-quest-8214
kixelated Nov 8, 2026
521a9f3
quest: fold finish-self into finished-handle
kixelated Nov 8, 2026
324ded9
quest: apply CodeRabbit's #8232 findings to catalog-finish and video-…
kixelated Nov 8, 2026
d588515
quest: address CodeRabbit's open plan findings on the API sweep
kixelated Nov 8, 2026
0fd27e3
Merge origin/main into quest-plan/api-sweep
kixelated Nov 8, 2026
7eecc2d
quest: address review threads on the API sweep
kixelated Nov 8, 2026
a655a56
Merge remote-tracking branch 'origin/main' into quest-plan/api-sweep
kixelated Nov 8, 2026
ca4bb3d
quest: a peer's iceServers change does not retry a failed pair
kixelated Nov 8, 2026
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
5 changes: 4 additions & 1 deletion quest/m1/explicit-state/publish-capture.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,9 @@ Also sweep:
`AnnounceMode`, and an invalid `announce` attribute suspends announcing
through `#invalid` like every other attribute, instead of the getter
returning `undefined` (added 2026-11-07, maintainer, /quest-plan from the
API shape audit).
API shape audit). An invalid attribute stays detectable the way every
other one already is: its parse error is thrown from
`attributeChangedCallback` and `enabled` turns false. The getter's type
narrows, so TypeScript readers still compile; say so in the PR.
- `js/moq-boy/src/game.ts`: a command sent while disconnected replays on
reconnect.
24 changes: 17 additions & 7 deletions quest/m1/hosted-assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,20 @@ needs the polyfill must also import `@moq/libav` and set its mutable

## Plan

Found by the 2026-11-07 API shape audit (browser media). Move `assets` and
its resolver into `@moq/hang`, the shared dependency whose
`Util.Libav.polyfill()` (`js/hang/src/util/libav.ts`) loads libav, and have
the polyfill take its base from it. `@moq/watch` and `@moq/publish`
re-export it, so their existing `assets()` callers keep working and nothing
breaks. `@moq/libav` stays an implementation dependency. Future hosted files
(the watch worker) join the same call. Test it on the CSP demo pages.
Found by the 2026-11-07 API shape audit (browser media). Move the resolver
into `@moq/hang`, the shared dependency whose `Util.Libav.polyfill()`
(`js/hang/src/util/libav.ts`) loads libav, as a small per-package directory
helper, and have the polyfill take its base from the package that loads it.
`@moq/watch`'s and `@moq/publish`'s `assets()` keep their signatures and
their own directories, so an app that hosts each package's files in a
different directory keeps working and nothing breaks; each also sets the
libav base on the `@moq/hang` instance it imports, so a page that resolves
two `@moq/hang` copies still configures the one each package uses. Each
package's `assets/` ships the libav wasm it needs. `@moq/libav` stays an
implementation dependency. Future hosted files (the watch worker) join the
same call. Test it on the CSP demo pages, including watch and publish
configured with different directories.

✅ Decided 2026-11-07 (maintainer, /quest-complete): each package keeps its
own directory and points libav at its files, as above (rejected: one shared
directory for every package).
13 changes: 13 additions & 0 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,13 @@ and instants become objects; native playout sync decouples its tracks like
the browser's; sentinels, moq-video's environment reads, and per-gateway
ingest setters go; and an epic batches the small fixes per area.

Added 2026-11-07 (maintainer, /quest-plan from an API sweep of the open PRs
and the remaining quests): the shapes later quests would otherwise break
after the cut. Public spawning constructors, moq-audio's codec seam,
consuming `finish`, the new `bus` signatures, the moq-auth iroh variant, and
the `warmup` contract settle here; growing structs are fenced with
`#[non_exhaustive]` through the api-shape epic.

Decided 2026-11-05 (maintainer, /quest-audit): blockers rank above the
quests that require them.

Expand Down Expand Up @@ -197,6 +204,12 @@ quests that require them.
- [Native playout sync keeps tracks decoupled](/quest/m2/mux-sync.md) - `moq_mux::timeline` becomes `moq_mux::sync`, and one slow track no longer stalls or moves another
- [JS time values are types, not numbers](/quest/m2/js-time-types.md) - every public JS duration and instant is a `Clock.Duration` or `Clock.Instant` object, so a unit mistake fails to compile
- [Small API fixes before the cut](/quest/m2/api-shape/README.md) - one path and one spelling per item, names by role, and no dead or wrong-role public surface across net, transport, media, native, apps, JS, and bindings
- [Public constructors spawn nothing, or say why](/quest/m2/spawn-constructors.md) - each public library entry point that spawns returns a driver its caller polls, or is listed as kept
- [moq-audio codecs return zero or more outputs](/quest/m2/audio-codec-seam.md) - `encode` and `decode` return any number of outputs and gain `flush`, as moq-video's do
- [Bus writes land at a bus position](/quest/m2/bus-positioned-write.md) - callers sync audio to video without copying the bus's private latency, before the cut first publishes `bus`
- [A mix-minus removes several sources](/quest/m2/bus-minus-several.md) - a guest's return feed drops every copy of their own sound
- [Drop moq-auth's iroh transport](/quest/m2/auth-drop-iroh.md) - this breaking moq-auth release drops `Transport::Iroh` and the JS `"iroh"` value
- [Plan: recovery boundaries](/quest/m2/intra-refresh-boundary.md) - the catalog's new `warmup` contract is settled before the cut publishes it
- [MoQ on rind](/quest/m1/rind/README.md) - every MoQ crate takes its crypto from rind, a pure-Rust graviola fork, so no build compiles C crypto (held in m1 by an open claim)
- [moq auth serve bounds what a leaked token or public caller can do](/quest/m2/auth-serve-policy.md) - tokens need an `exp` unless the operator opts out, and a public listener authenticates relays
- [Finishing a producer returns a Finished handle](/quest/m2/finished-handle.md) - `finish(self)` consumes moq-net's and the media crates' producers, so appending after finish doesn't compile
Expand Down
20 changes: 15 additions & 5 deletions quest/m2/api-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,23 @@ became their own m1, m2, m3, and m4 quests; this epic holds the rest.

This audit ran while [moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088),
the previous API audit's final pass, was open, and none of its children
repeats an item #8088 changes. A child that starts after #8088 merges
rechecks each item against `main` and drops what is already done.
repeats an item #8088 changes. #8088 has since merged, so a child rechecks
each item against `main` and drops what is already done.

Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): fences for
what later quests grow (`#[non_exhaustive]` on structs and enums m3 to m5
add to), shapes those quests would otherwise break, and this epic's own
work: before the cut, run a "public item used only by its definition"
search over the published crates and remove each hit, starting with
`moq_tokio::Server::serve_both`, `hang::Catalog::to_json_pretty`, and
`moq_audio::Format::{is_planar, is_float}`, the shortlist of
[the dead code audit](/quest/m3/audit-dead-code.md). The audit itself stays
in m3 for private code.

Rules every child follows:

- Removal beats addition. A public item with no caller in this repository,
a known downstream application goes private, unless an m1 or m2 quest plans a
- Removal beats addition. A public item with no caller in this repository
or a known downstream application goes private, unless an m1 or m2 quest plans a
caller.
- No serde aliases, refusals, or shims for a spelling `release` never
shipped.
Expand All @@ -44,7 +54,7 @@ Rejected in planning:

## Required

- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, and priority surface, and no public wire codes
- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, proxy, and priority surface, and no public wire codes
- [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals
- [Crates re-export no whole crate](/quest/m2/api-shape/reexports.md) - no moq crate re-exports a whole crate, moq's own included, so a dependency bump is no moq break, and moq-mux's container `Guard` gets a name
- [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name
Expand Down
6 changes: 6 additions & 0 deletions quest/m2/api-shape/apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@
environment, with named refusals for the old flags, which shipped.
- moq-boy's Rust crate stops exporting its internals (the JS half is in
[the JS child](/quest/m2/api-shape/js.md)).
- moq-relay's `cluster::Options.network`, a `moq_tokio::sim::Network` test
hook added by [moq-dev/moq#8139](https://github.com/moq-dev/moq/pull/8139),
is `#[doc(hidden)]` test support, so the published config names no
simulator type. If an embedder needs injected dials, the shape is a
take-once `Cluster::dials()` handle, not a config field (added
2026-11-07, maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests).

## Plan

Expand Down
16 changes: 16 additions & 0 deletions quest/m2/api-shape/bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,25 @@
a free constructor that the caller must then register.
- Python: `moq.testing` leaves the published wheel; tests import it from the
source tree.
- moq-ffi's `MoqVideoSurface` gets `#[non_exhaustive]`: it has one variant,
and Android HardwareBuffer, D3D11, and DMA-BUF surfaces are planned in m3.
Check any other output-only UniFFI enum an m3 quest plans to grow.
Comment thread
kixelated marked this conversation as resolved.
Resolved
`#[non_exhaustive]` fences Rust and C only: UniFFI's Kotlin, Swift, Python,
Dart, and C++ enums stay exhaustive, so a new variant breaks a foreign `when` or
`switch`. Open, for whoever starts this, with the maintainer: fence it in
the bindings too (recommended: the wrappers add an unknown arm that a new
variant maps to until the wrapper learns it), or record a new variant as
breaking for those bindings.
- Go's `*DecoderOutput` aliases go (from
[the OBS adapter](/quest/m3/obs-moq-video/adapter.md)).
- Dart's wrapper names the route instance accessor `instance()`, as the
other bindings do, so [the exporter](/quest/m3/ffi-exporter.md) changes no
Dart call site.

## Plan

Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the video surface fence, the Go aliases, and Dart's `instance()`.

Found by the 2026-11-07 API shape audit (bindings); see the
[epic](/quest/m2/api-shape/README.md). The generated check that each
hand-written wrapper exports every FFI item is
Expand Down
11 changes: 9 additions & 2 deletions quest/m2/api-shape/js.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,13 @@
`with_instance(instance, epoch)`.
- `@moq/qmux` exports `Session` by name instead of an anonymous default.
- `@moq/watch`: the decoder and source plumbing outputs are `@internal`, the
renderer's output is a named `Video.RendererOutput`, and `<moq-watch>`'s
`player` property goes private, so each component has one path.
renderer's output is a named `Video.RendererOutput` with no `frame` (a
`VideoFrame` signal cannot cross a worker, so
[the watch worker](/quest/m3/watch-worker.md) would break it; the paused
poster reads an internal painted flag), and `<moq-watch>`'s `player`
property goes private, so each component has one path.
- `@moq/room` exposes timestamps and stats instead of `Video.Renderer` and
`Video.Decoder`, so the worker's break lands in one package.
- `@moq/publish`: `Rendition.onDemand` becomes an enum, `Broadcast.join`
becomes a `Getter`, and the five internal source helpers are unexported.
- `@moq/ui` and `@moq/video` mark their helpers `@internal`; only `Support`,
Expand All @@ -27,6 +32,8 @@

## Plan

Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the worker-safe renderer output and room's narrower surface.

Found by the 2026-11-07 API shape audit (JS core and browser media); see
the [epic](/quest/m2/api-shape/README.md). Durations are
[js-time-types](/quest/m2/js-time-types.md); hosted assets and the
Expand Down
23 changes: 21 additions & 2 deletions quest/m2/api-shape/media.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,25 @@ Each item below has one path and one name:

- moq-mux exporters (fmp4, mkv, flv, mp4): the fmp4 and catalog internals
no caller uses become private, flv returns a typed error instead of a
string, and every exporter names its wait the same way (the name moq-mux's
TS exporter uses since [moq-dev/moq#7981](https://github.com/moq-dev/moq/pull/7981)).
string, and fMP4, MP4, MKV, and FLV take a `moq_net::Delay { min, max }`
(`min` the start behind the live edge, `max` today's skip budget), the
pair [export-live-start](/quest/m3/export-live-start.md) needs, instead of
one `Duration` under three spellings. TS keeps its jitter `delay`, a
different role ([moq-dev/moq#7981](https://github.com/moq-dev/moq/pull/7981)).
- moq-mux stops re-exporting `mp4_atom` (`container::fmp4`), and
`fmp4::Wire::{new, trak}` become `pub(crate)` or give way to the one
accessor moq-hls needs, so an mp4-atom bump (two are planned in m3) is not
a moq-mux break. The errors leak it too: `moq_mux::Error::Mp4` and
`fmp4::Error::Mp4` wrap `mp4_atom::Error`, `fmp4::Error::{UnknownCodec,
UnsupportedCodec}` carry `mp4_atom::FourCC` and `mp4_atom::Codec`, and
both have `From<mp4_atom::Error>`. Those variants carry an opaque source
and moq-mux's own codec name, and the public `From` impls go.
- hang's echo drops `latency` in Rust, JS, and the draft: nothing produces
it, and [latency-ledger](/quest/m5/latency-ledger.md) adds its measurement
additively.
- `moq_json::{diff, Diff}` become `pub(crate)`.
- `moq_mux::codec::aac::Config` gets `#[non_exhaustive]`, since
[aac-sbr-config](/quest/m4/aac-sbr-config.md) adds a field.
- The container `Consumer` has one constructor, through
`container::Playout`; `with_delay` goes.
- hang's `catalog::Range` becomes `ColorRange`, and the MoQ epoch constant
Expand All @@ -20,6 +37,8 @@ Each item below has one path and one name:

## Plan

Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): exporter delays, mp4-atom, echo latency, the JSON diff, and the AAC config.

Found by the 2026-11-07 API shape audit (media formats); see the
[epic](/quest/m2/api-shape/README.md). The playout clock is
[mux-sync](/quest/m2/mux-sync.md), and rendition stats are
Expand Down
8 changes: 6 additions & 2 deletions quest/m2/api-shape/native.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,12 @@

## Goal

- moq-audio's `encode::{Control, State, Status}` become private, and
`publish_capture` stays the public path.
- `publish_capture` returns a handle plus a driver in both moq-audio and
moq-video, mirroring each other, and moq-audio's `encode::{Control, State,
Status}` stop being separate public names. The handle may start with only
the state accessors audio has today, so
[video-publish-grant](/quest/m3/video-publish-grant.md) adds `grant()`
without a break (added 2026-11-07, maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests).
- `on_demand` means one thing across crates. moq-video's closes the camera
between viewers and defaults to `false`; moq-audio's keeps the device open,
defers encoding, and replays retained PCM, and defaults to `true`. Audio's
Expand Down
38 changes: 36 additions & 2 deletions quest/m2/api-shape/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,46 @@ its JS and binding mirrors:
`RouteEvent::Takeover`, un-hide `origin::Consumer::routes`, `Routes`, and
`RouteEvent`, documented as the relay-level stream that moq-relay and
downstream relays already consume, and fix `request`'s doc to say what #8063 made it
do.
do. `RouteEvent` becomes `pub struct RouteEvent { pub kind: RouteKind, pub
announce: Announce }` with `pub enum RouteKind { Start, Update, Restart, End }`,
mirroring JS's `{ kind } & Routed`, so callers need no or-pattern and no
accessors.
- `stats::Registry::report` takes an explicit `now`, and
`stats::Handle::{refuse, session}` take `#[non_exhaustive]` argument
structs with a `new(label, ..)` constructor (named by role, not clashing
with `server::Admission`), so [lag-histogram](/quest/m3/qos/lag-histogram.md)
and [session-outcome-records](/quest/m3/session-outcome-records.md) add
fields instead of breaking moq-net again.
- `group::MAX_CACHE_BYTES` becomes `pub(crate)`: byte-holes turns it from a
size cap into a tail budget, and moq-json's `max_group_bytes` keeps its own
32 MiB default. Each outside use takes a limit of its own: moq-json's
encoder defaults and clamp, moq-mux's jitter, container-consumer, and
fMP4 bounds, the moq-stats `producer_tick` benchmark, and the oversize
tests in moq-json, moq-mux, and moq-gst.
- Remove `origin::Consumer::with_proxy` (from
[moq-dev/moq#8023](https://github.com/moq-dev/moq/pull/8023)) in favor of
`origin::Producer::with_proxy`, which already reaches every consumer taken
from that producer. Only tests call the consumer override: the moq-net
integration harness (`rs/moq-net/tests/integration/support/harness.rs`, two
sites), `mount.rs`, and moq-mux's `container/test_util.rs` (two sites);
each sets proxy on the producer it consumes from instead.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- `auth::Grant` gets `#[non_exhaustive]`, since
[rate-grant](/quest/m5/rate-grant.md) adds rates to it; callers outside
moq-net build it from `Grant::default()`.

## Plan

Found by the 2026-11-07 API shape audit (net model and net session); see
the [epic](/quest/m2/api-shape/README.md). Each item is XS except
`Attempt::client` and `Compression` (S each). `RefusalKind` is a stats-wire
`Attempt::client`, `Compression`, and the `with_proxy` removal (S each). `RefusalKind` is a stats-wire
field, so say in the PR which deployed dashboards read it. If #8063 has not
merged when this starts, leave the un-hide for a follow-up and say so.

Added 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): the `RouteEvent`
struct, the stats arguments, the cache cap, and `Grant`. The `RouteEvent`
reshape replaces [moq-dev/moq#7862](https://github.com/moq-dev/moq/pull/7862)'s
accessors. #7862 closed without taking it, so the reshape lands here.

Decided 2026-11-07 (maintainer, /quest-complete, from
[moq-dev/moq#8088](https://github.com/moq-dev/moq/pull/8088)'s follow-ups):
✅ remove `origin::Consumer::with_proxy` in favor of the producer's.
33 changes: 29 additions & 4 deletions quest/m2/api-shape/transport.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,38 @@
configs take a `moq_congestion` factory (BBR3 by default, matching
moq-tokio; today `moq_uring::quic::Congestion` defaults to `Loss`) and an
`Arc<rustls::ClientConfig>` or `Arc<rustls::ServerConfig>`, as moq-tokio's
do. `moq_uring::quic::Congestion`, `Identity`, `ClientAuth`, and the client
TLS fields are gone.
- moq-tokio's `server::Request::quic()` is removed; nothing outside the
crate calls it, and it exposes the QUIC backend through the session API.
do. `Identity`, `ClientAuth`, and the client TLS fields are gone.
`moq_uring::quic::Congestion` stays as a convenience that converts into a
factory, so the built-in families keep their names while the config holds
only a factory. The relay's io_uring runtime installs the controller a
`moq_tokio::quic::Config::controller` carries instead of refusing it
(`rs/moq-tokio/src/quic.rs`), so an embedder gets the same controller on
either runtime.
- qmux names no tungstenite type: TLS is qmux's own `tls::Client` config,
`WebSocketConfig` folds into qmux's record-size limits, `Upgraded::new`
takes the raw upgraded IO plus a role, `Error::WebSocket` is opaque, and
`pub use tokio_tungstenite` goes (`rs/qmux/src/ws.rs`), so a tungstenite
major is not a qmux break.
- moq-tokio's `server::Request::quic()` is removed, since it exposes the QUIC
backend's connection through the session API. Its one outside caller, the
relay's `pacer()` (`rs/moq-relay/src/incoming.rs`), clones it to apply
changed bitrate caps after acceptance, which `with_quic_limits` cannot do.
It gets a narrow replacement: a cloneable live-limits handle (for example
`Request::quic_limits() -> Option<QuicLimits>` with `set(moq_quic::Limits)`),
`None` on qmux streams as today, so the relay keeps updating caps on a
running session without naming the connection.

## Plan

Decided 2026-11-07 (maintainer, /quest-plan from the 2026-11-07 API sweep of open PRs and remaining quests): ✅ the
`Congestion` enum converts to a factory, and the config takes only a factory
(rejected: delete the enum; keep the enum with a factory variant). This
reconciles the 2026-11-01 decision that the enum keeps its built-in families
with one factory both runtimes install, and absorbs the deleted m3
uring-controller quest. qmux's tungstenite exposure is from
[the stream codec bench](/quest/m4/perf/stream/codec.md), which stays
perf-only.

Found by the 2026-11-07 API shape audit (transport); see the
[epic](/quest/m2/api-shape/README.md). The relay's io_uring path builds its
configs the way the tokio path does, so it loses its conversion code. The
Expand Down
Loading