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
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The API is the most important thing to get right: a bad shape costs a breaking c
- Nest related API, configuration, and output fields under their shared role.
- Mirror API names across Rust, JS, and the bindings.
- Keep package boundaries modular and reusable; prefer a module in an existing package over a one-off package.
- Never mark a special case inside a value: not a huge number like `u64::MAX` (it is the longest varint), and not a reserved prefix or character in a string. Use 0, a separate message or type, a typed field, or a boolean.
- Never mark a special case inside a value: not a huge number like `u64::MAX` (it is the longest varint), and not a reserved prefix or character in a string. Use 0, a separate message or type, a typed field, or a boolean. The one exception is a path segment's leading `.`, which hides the path from announce discovery.
- Enforce a policy where the thing is created, not where it is checked: the signer bounds a token's lifetime, and the verifier accepts what a valid token carries. Don't add `allow-*` opt-out flags; move or generalize the rule.

# Development
Expand All @@ -50,7 +50,7 @@ Review locally with one reviewer, not the pair: `quest review --harness codex`,

# Cross-Package Sync

`moq-ffi` powers every SDK except Rust and JS. Keep all languages and wrappers at the same functionality.
`moq-ffi` powers every SDK except Rust and JS. A feature reaches the bindings when a binding user needs it; every language and wrapper then gets it together.
A Rust change with a JS counterpart updates both in the same PR: `moq-net` and `js/net`, `hang` and `js/hang`, `moq-auth` and `js/auth`.
A wire-format change updates its matching draft in the same PR: framing, fields, enum values, and version negotiation.
Wire, `moq-ffi`, or gateway changes also run `just test interop --all`; plain `interop` is Rust-only.
8 changes: 8 additions & 0 deletions quest/m0/test-flakes-3/py-socket-abort.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,12 @@ ending of a socket endpoint run its cleanup and likely fixes it: run the test
alone in a loop on a base that includes it. If it no longer fails, delete this
quest; if it does, the cause lies elsewhere.

Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): socket
endpoints leave moq for Kixel, and
[their removal](/quest/m2/sockets/remove.md) deletes this test with the
Python wrapper. So do not fix the endpoint here. If the test still flakes
before the removal lands, skip it with the removal quest as its owner and
delete this quest; the removal deletes this quest otherwise. Kixel's port
inherits the race, which goes in that PR's follow-ups for Kixel's tree.

Public API: none. Wire: none.
6 changes: 5 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ because a downstream iGPU transcode trial needs it now.

Decided 2026-11-13 (maintainer, /quest-run): stream-credit stays in m1 and
no longer gates m2, since takeover, its only wire change, moved to m3.
Its YIELDED continuations leave lite-07 again in m2
([yield-defer](/quest/m2/yield-defer.md), 2026-11-16).

Decided 2026-11-12 (maintainer, /quest-audit before the cut):

Expand All @@ -38,7 +40,9 @@ Decided 2026-11-12 (maintainer, /quest-audit before the cut):
a downstream application builds on them from `main` now. Superseded
2026-11-13, below, and 2026-11-14 (maintainer): byte streams moved to Kixel,
which builds its own on moq-net's public API, and sockets dropped their
`tcp` protocol.
`tcp` protocol. Socket endpoints followed on 2026-11-16 (maintainer,
/quest-plan of the pre-cut audit): [they leave moq](/quest/m2/sockets/README.md)
for Kixel before the cut.
- ✅ Also moved here: the two reconnect fixes whose bugs came from PRs that
are on `main` and not on `release`, so the cut would publish them; the Go
module proxy, since the mirror repository nears 1 GB; and the ashpd bump.
Expand Down
86 changes: 82 additions & 4 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,82 @@ complete it before cutting main into release.

## Plan

Decided 2026-11-16 (maintainer, /quest-plan of an audit of everything on
`main` since `release`, and of the lite-07 draft): the cut also waits on what
that audit found. Fifteen reviewers judged about 480 work lines for a
long-term purpose and a caller, against moq.pro's and Kixel's roadmaps; the
maintainer decided each finding in a 15-round interview, and each quest's
Plan records its decision with what was rejected. The audit reopened the 50
work lines the 2026-11-14 [feature review](/quest/m3/release/feature-review.md)
judged "ship as is". Everything below is breaking by this milestone's rule: a
removal, a rename, or a wire, catalog, or format change that is free until
0.22 publishes it.

- **lite-07 wire.** [YIELDED continuations](/quest/m2/yield-defer.md) leave
for lite-08; [the ietf extension](/quest/m2/ietf-records-per-track.md)
costs nothing on a moq-lite track; [the path escape](/quest/m2/path-escape.md)
is finished; [Subscriber Min Age](/quest/m2/min-age-join.md) stays and
gains its reader, reversing 2026-11-14; and
[lite-07 by start](/quest/m2/time-addressing/lite07.md) carries the
smaller wire fixes. [Refresh](/quest/m2/refresh-interval.md) and
[group drops](/quest/m2/group-drops.md) took simpler contracts.
[moq-transport time addressing](/quest/m2/ietf-time-addressing.md)
returned from m4, and the two moq-transport interop quests in m3 were
deleted. Kept as they are: datagram tracks with their lite-05/06 bridge,
all seven lite versions, the hidden `.` path prefix, and the route plan
of [cache-aware multicast](/quest/m2/multicast/README.md), whose
[switch](/quest/m2/multicast/switch.md) also settles the public route API
and retires the moq-cluster draft.
- **moq-net API.** [Groups](/quest/m2/group-api.md),
[reconnect](/quest/m2/reconnect-off.md), [names](/quest/m2/net-renames.md),
and [session codes](/quest/m2/session-codes.md).
[Socket endpoints](/quest/m2/sockets/README.md) leave for Kixel, and the
demos return to their earlier format.
- **Unused API.** [One sweep per area](/quest/m2/unused-api/README.md), each
item re-checked for a downstream caller first.
- **Relay and transports.** [Memory](/quest/m2/relay-memory.md), which the
cut waits on by name; [congestion names](/quest/m2/congestion-names.md);
[config names](/quest/m2/relay-config-names.md),
[the two dial keys](/quest/m2/relay-connect-keys.md), and
[the 0.14 leftovers](/quest/m2/relay-014-leftovers.md);
[transport names](/quest/m2/transport-names.md); and
[stats names](/quest/m2/stats-old-names.md).
- **Auth and crypto.** [Grants](/quest/m2/auth-grants.md),
[claims](/quest/m2/auth-claims.md), and
[the attached token](/quest/m2/auth-attach-token.md). End-to-end encryption
[is its own unpublished crate again](/quest/m2/e2ee-crate.md); its
[finished format](/quest/m3/e2ee-format.md) follows in m3.
- **Catalog, drafts, and formats.** [hang-04](/quest/m2/hang04/README.md)
(the `sync` section, a version per entry, no video `warmup`, `m2ts` under
`mpegts`, one strict rule); [dead drafts](/quest/m2/drafts-retire.md);
[the archive as version 2](/quest/m2/archive-v2.md);
[declared ends](/quest/m2/time-addressing/consumers.md), back from m3;
[finish](/quest/m2/finish-sweep.md), [TS outcomes](/quest/m2/ts-typed-outcomes.md),
and [moq-json writes](/quest/m2/json-write-at.md).
- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md),
[the hole wait](/quest/m2/delay-hole-wait.md),
[device and cursor](/quest/m2/native-media-config.md),
[sink names](/quest/m2/audio-sink-names.md),
[moq-vaapi's exports](/quest/m2/vaapi-exports.md),
[the WebRTC bind](/quest/m2/webrtc-bind.md),
[gateway admission](/quest/m2/gateway-align.md), and
[upstream str0m](/quest/m2/str0m-upstream.md), which reverses the
2026-10-30 vendoring.
- **JS and browser.** [`@moq/net`](/quest/m2/js-net-api.md),
[signals](/quest/m2/signals-semantics.md), [`@moq/ui`](/quest/m2/ui-private.md),
and [room, publish, and OBS names](/quest/m2/browser-packages.md).
- **Bindings.** [Open selectors](/quest/m2/ffi-open-selectors.md),
[Dart as experimental](/quest/m2/dart-experimental.md), and
[the C API as `libmoq`](/quest/m2/libmoq-name.md), reversing 2026-10-25.
The bindings break twice by decision: at 0.22, and again at
[the exporter switch](/quest/m3/ffi-exporter.md).

Two rules changed with it (AGENTS.md): a feature reaches the bindings when a
binding user needs it, and a path segment's leading `.` is the one marker
allowed inside a value. Not reopened: AUTH_ERROR's retry codes (2026-11-14)
and AUTH_OK's rate fields, which wait for lite-08
([rate grant](/quest/m5/rate-grant.md)).

Decided 2026-11-15 (maintainer, /quest-plan on the whole route layer): ✅ the
cut waits on [cache-aware multicast](/quest/m2/multicast/README.md), which
replaces lite-07's route layer before it freezes (rejected: lite-08). The
Expand Down Expand Up @@ -232,10 +308,12 @@ what would need a breaking release had it landed right after the cut:
returned to m2 on 2026-11-15 (maintainer, on
[moq-dev/moq#8832](https://github.com/moq-dev/moq/pull/8832)) and became
the request quest of [cache-aware multicast](/quest/m2/multicast/README.md);
[media consumers](/quest/m3/time-addressing-consumers.md) to m3 (its API
breaks ride the model; dropping hang's markers is tolerated by readers);
[moq-transport time addressing](/quest/m4/ietf-time-addressing.md) to m4
(low-priority compatibility, no named consumer); and the
[media consumers](/quest/m2/time-addressing/consumers.md) to m3 (its API
breaks ride the model; dropping hang's markers is tolerated by readers),
until it returned to m2 on 2026-11-16;
[moq-transport time addressing](/quest/m2/ietf-time-addressing.md) to m4
(low-priority compatibility, no named consumer), until it returned to m2
on 2026-11-16; and the
[Playwright bump](/quest/m1/playwright-pin.md) to m1, which the release
cut requires in place of lite07-finalize (its strict interop lane needs
Chromium 158), with lite07-finalize checking Chromium 158 once by hand. The E2EE nonce
Expand Down
84 changes: 84 additions & 0 deletions quest/m2/archive-v2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# [M] The archive format ships as version 2, and readers accept only it

## Goal

The stored format `moq-archive` writes at the cut is version 2, the
successor to the version 1 that `release` ships, and it is one format: the
reader accepts exactly version 2 and names the version it refused. The code
for the layouts main called 2, 3, and 4, none of which was ever published,
is gone, and `rs/moq-archive/src/lib.rs`'s format description matches what
the reader uses.

## Plan

Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit):

- ✅ Ship as version 2, and the reader accepts exactly it (rejected:
bumping to 5 as the one version at the cut; keeping 4 and deleting only
the legacy paths; freezing as is). The number counts published formats:
2, 3, and 4 only ever existed on main.

Facts found by the audit:

- `rs/moq-archive/src/lib.rs` has `VERSION = 4` and `VERSION_MIN = 2`;
`origin/release` has `VERSION = 1`, a different layout that main already
cannot read.
- The reader still carries the unpublished layouts:
`rs/moq-archive/src/layout.rs` (`LEGACY_GROUP`, `legacy = version < 4`,
the three-field entry) and `rs/moq-archive/src/info.rs` (the version 2
priority byte, and the `VERSION_MIN..=VERSION` range checks in both
files).
- [moq-dev/moq#8638](https://github.com/moq-dev/moq/pull/8638) changed
what version 4 means without bumping it: the entry sequence and the
key's group field became the group's start
(`rs/moq-archive/src/producer/track.rs`, `let sequence = group.start`).
A version 4 archive written before it and one written after disagree.
- The object key is `<group>-<frame>-<pts>`. Since #8638 the consumer
drops the third field: `rs/moq-archive/src/consumer/index.rs` keeps
`(start.group, start.frame)` and says "a group's sequence is its start,
so these sort by time too", while `lib.rs` still says the listing
"answers group and time lookups". The producer reads `pts` back to
resume (`producer/track.rs`).
- `.info` and the layout structs use `deny_unknown_fields`
(`info.rs`, `layout.rs` twice), so no field can be added without a
version bump.

Recommendations for the PR (not decided):

- The key's `<pts>`: use it or remove it. A field every implementer must
write and validate, and no reader uses, is what a freeze makes
permanent. Removing it needs the producer's resume to recover the
timestamp another way (the object's first frame); if that costs a GET
per resume, keeping the field and making the consumer's time lookup use
it is the better end. Say which in the PR.
- Tolerate unknown fields in `.info` and the layout records, so version 2
can gain an optional field without becoming version 3. Keep
`deny_unknown_fields` only where an ignored field would change what the
bytes mean.
- Decide on purpose whether per-frame timestamps stay absolute while
sequences are delta coded; the audit had low confidence it matters.

For the PR:

- First check moq.pro for stores written by a main build (its staging
recorder): those archives say 2, 3, or 4 and mean something else. The
format is unpublished, so they are rewritten or discarded, not read;
the Impact section says so. A deployed store that must stay readable is
the one thing that reopens the decision.
- A version 1 archive stays unreadable, as on main today; the error names
the version found and the one supported, so nobody mistakes a release
archive for a corrupt one.
- Update `doc/concept/archives.md` and the crate docs to the one format.

Tests: a version 2 archive round-trips through producer and consumer; an
`.info` or layout that says 1, 3, or 4 is refused with the typed version
error; resume after a restart finds the last object; if unknown fields are
tolerated, a record with an extra field reads.

Public API: none expected beyond the version constants. Wire: the stored
archive format; archives written by any main build before this are not
read.

## Related

- [Media consumers address groups by start](/quest/m2/time-addressing/consumers.md) - the model that made the key's group field a start
48 changes: 48 additions & 0 deletions quest/m2/audio-sink-names.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# [XS] The audio sink's silence markers say what they declare

## Goal

`moq_audio::playback::Sink` declares a publisher's announced silence and the
start of the next utterance under names that say so (recommended:
`silence()` and `resume()`), not `end()` and `next()`. `end()` no longer sits
beside `finish()` on a type it does not end.

## Plan

Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit):

- ✅ Rename the two methods before the cut (rejected: keep; hide the sink's
placement methods until the playout library lands). A name is free to
change only until moq-audio publishes with it.

Facts found by the audit:

- `Sink::end()` (`rs/moq-audio/src/playback/sink.rs:228`) declares silence
the publisher announced; it does not end the sink, which `finish(self)`
does (`:150`). `Sink::next()` (`:238`) starts the next utterance.
- The publisher calls the same marker `discontinuity`
(`rs/moq-audio/src/encode/producer.rs:668`), and the decoder reports it as
`Read::End`.
- One caller: `moq play`, four call sites in `rs/moq-cli/src/play/media.rs`
(`:889`, `:900`, `:912`, `:1029`) through the output trait at
`rs/moq-cli/src/play/output.rs:59`, `:62`. No binding, GStreamer element,
or OBS source calls them.

For the PR: settle the names against the publisher's `discontinuity` and the
decoder's `Read::End`, so the three read as one idea, and rename the trait
methods in `rs/moq-cli/src/play/output.rs` to match. The sink's placement
methods (`output_latency`, `set_latency`, `due`) stay as they are:
[the playout library](/quest/m3/audio-playout-library.md) decides their
future after the cut (2026-11-14).

Recommended in the same PR, not decided by the maintainer:
`encode::Producer::reanchor()` (`rs/moq-audio/src/encode/producer.rs:366`)
and `discontinuity()` (`:668`) are a lazy and an immediate marker for one
idea, and moq-ffi exposes only `reanchor`. Keep one public method, or say in
the docs why a caller needs both.

Public API: moq-audio breaks (two method names). Wire: none.

## Related

- [Native audio playout is a library](/quest/m3/audio-playout-library.md) - builds on the sink after the cut
68 changes: 68 additions & 0 deletions quest/m2/auth-attach-token.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# [S] An attached token arrives as a token, not in the query

## Goal

When a client attaches a credential in band, the relay's `attach` request
to the auth server carries it in `Request.token` and leaves `query` exactly
as the client dialed it. The relay no longer knows the name `jwt`, and an
in-band token need not be UTF-8. `moq auth serve` and the docs read the
attached credential from `token`.

## Plan

Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): ✅ the
in-band token rides `Request.token` and the query stays as dialed (rejected:
keeping the rewrite and documenting it; a third field for the attached
credential). The contract says nothing is parsed on the relay's behalf, and
the rewrite is the one place the relay breaks that.

Facts found by the audit:

- The contract: "Nothing is parsed on the relay's behalf" and `query` is
"The raw query string" (`rs/moq-auth/src/request.rs:13,60`).
- For an in-band token the relay clones the connection's request, replaces
or appends a `jwt=` pair in `query`, and clears `token`
(`rs/moq-relay/src/auth/refresh.rs:259-265`, `with_jwt` at `:497-523`).
So an `attach` request carries a query the client never dialed, and a
server whose credential is not called `jwt` reads its own parameter at
`connect` and `jwt` at `attach`.
- The lite draft's token is opaque bytes, but the relay refuses one that is
not UTF-8 (`refresh.rs:259-262`), only because it must fit a query string.
A binary token works in SETUP (`token.value` is base64url) and fails in
band.
- `jwt` is also fixed in `presents_token`
(`rs/moq-relay/src/auth.rs:878-885`) and in the clients
(`rs/moq-net/src/auth/tokens.rs:456-532`,
`js/net/src/connection/tokens.ts:25-50`).
- `token`'s docs still say "a moq-transport client"
(`request.rs:63`, `js/auth/src/contract.ts:123`), though lite-07's Token
Setup Parameter lands there with `kind` 0.

For the PR:

- Relay: on `attach`, set `token` to `{kind: 0, value}` and leave `query`
alone. Delete `with_jwt` and the UTF-8 refusal. `presents_token` is the
relay's only other reader of `jwt`; replace it with a fact the request
already has, or move the question to the server, so the relay holds no
parameter name.
- `moq auth serve` verifies `token` when `event` is `attach`. Today it
counts a query `jwt` and a SETUP token once when equal and refuses when
they differ (`rs/moq-auth/src/serve.rs:195-197`); on `attach` the dialed
query still holds the first credential, so that rule must not fire there.
- The clients keep `?jwt=` only as the fallback for versions before
lite-07. Don't change them here.
- Both downstream auth servers read `attach` requests. This is a contract
break for them: record it in the Impact section, and check moq.pro's and
Kixel's handlers before merging.
- Update `request.rs`, `contract.ts`, and `doc/bin/relay/auth.md` (the
`token` field's description and the `attach` event).
- Tests: an attached binary token reaches the server unchanged; an `attach`
request's `query` equals the dialed one; `moq auth serve` renews a session
whose dialed query holds an expired `jwt`.

Public API: none in Rust or JS beyond doc comments. HTTP contract: breaking
for `attach` (the credential moves from `query` to `token`). Wire: none.

## Related

- [A relay refuses a grant it does not fully understand](/quest/m2/auth-grants.md) - the other change to the same request and its docs
Loading