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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion bench/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ also run during timing. Every timed round reads and checks all payload bytes,
returns lease credit, and fills each stream again. Throughput counts delivered
payload once. Nightly's supplemental Rust benchmark leg records the series and
keeps the memory output with its raw results. The broader MoQ session transport
and version sweep remains in [its quest](/quest/m4/bench-transport-sweep.md).
and version sweep remains in [its quest](/quest/m5/bench-transport-sweep.md).

Compare one multi-threaded Tokio runtime with the same number of independent
Tokio/epoll and io\_uring workers:
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/socket.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ every hop, so a slow reader slows the writer, as TCP backpressure does, and
nothing is lost. A writer that doesn't wait sheds the front of its half, and a
reader that falls behind it fails with an eviction error instead of skipping
data. Pacing reaches across native QUIC and qmux hops; see
[unbounded groups](https://github.com/moq-dev/moq/tree/main/quest/m2/unbounded-groups)
[unbounded groups](https://github.com/moq-dev/moq/tree/main/quest/m3/unbounded-groups)
for what remains, such as browsers, which read without pacing.

Use `tcp` for a byte stream or a log of records that must all arrive in order,
Expand Down
3 changes: 2 additions & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ The [`moq`](https://pub.dev/packages/moq) package on pub.dev wraps the
generated [`moq_ffi`](https://pub.dev/packages/moq_ffi) bindings in Dart
futures and streams. A Native Assets hook supplies the Rust core for Android
(API 24+), iOS (16+), Linux, macOS, and Windows. Flutter web is not supported,
since it can't load a native library.
since it can't load a native library. The iOS library ships but has not yet
been run in an iOS app, so treat iOS as untested.

Import `package:moq/media.dart` with a prefix for catalogs, encoded-media imports, and
container consumers. `TrackProducer.audio` / `.video` take a broadcast, an init record,
Expand Down
2 changes: 1 addition & 1 deletion infra/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -385,7 +385,7 @@ paths, with their old signatures, indefinitely. The next Cache push refills it.
## Bootstrapping the video corpus

The nightly video-quality job, which [the harness
quest](../quest/m3/video-quality/harness.md) adds, reads its clips from two
quest](../quest/m9/video-quality/harness.md) adds, reads its clips from two
buckets.
`corpus-moq-dev` holds open clips and is public at `corpus.moq.dev`.
`corpus-private-moq-dev` holds clips that cannot be redistributed. It has no
Expand Down
18 changes: 18 additions & 0 deletions quest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,24 @@ release execution, and bug fixes in shipped code; m4 holds tests, tooling,
benchmarks, optimizations, and features nobody waits on yet. m5 holds work
gated on the outside world, or speculative work with no named consumer.

[m9](/quest/m9/README.md) is the lab (decided 2026-11-12, maintainer,
/quest-audit; renamed from `lab` 2026-11-13): experiments and measurements
that touch no published API, wire format, or CLI surface. They start any
time, merge whenever, never gate a cut, and stay in place when the
milestones shift. `quest` orders milestones by name, so `lab` ranked ahead
of m0; as m9 it ranks last.

Until the cut, [m4](/quest/m4/README.md) and [m5](/quest/m5/README.md)
require the [release cut](/quest/m3/release/cut.md) (decided 2026-11-13,
maintainer), so spare capacity goes to m0 to m3 and then to m9's lab work
instead of to later features. m3 stays open, since it holds the cut and its
reviews. The cut's PR deletes the cut quest, which lifts the gate.

No quest requires one in a later milestone (decided 2026-11-13, maintainer):
a blocker ranks by its own milestone, so the earlier quest would stall behind
the later milestone's work. Additive work that builds on m2 joins m3, which
ranks right after m2, rather than m1.

A change is breaking when a published consumer or a deployed peer must adapt
to it: the public Rust, JS, or bindings API, a frozen wire version, the hang
catalog JSON, a stored or exported container format, or CLI flags, config
Expand Down
33 changes: 33 additions & 0 deletions quest/m0/cut-placement.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# [M] Place each cycle's cuts so no milestone waits on a later one

## Goal

The [release cut](/quest/m3/release/cut.md)'s steps re-create each later cut
in a place where no quest requires one in a later milestone, and re-create
the gate that holds later work until that cut while the lab,
[m9](/quest/m9/README.md), stays open. The current cut follows them when it
re-creates its successor.

## Plan

Planned 2026-11-13 (maintainer, /quest-plan, on
[moq-dev/moq#8637](https://github.com/moq-dev/moq/pull/8637)): the same day
settled that no quest requires one in a later milestone, and that
[m4](/quest/m4/README.md) and [m5](/quest/m5/README.md) require this cut
until it lands. The cut's steps predate both: they re-create later cuts in
m0's release epic, and the wire cut that ends a cycle requires m2 and m3.

The constraints a placement must meet, all enforced by `quest check` once
moq-dev/quest's rule ships:

- A cut lives in or after the last milestone it waits on.
- A cut can't require the milestone that holds it, or any epic above it.
- A milestone gated on a cut can't hold that cut, or the gate is a cycle.

Settle with the maintainer where each phase's cut lives and which milestones
its gate covers, then rewrite the cut's steps and the root
[questline](/quest/README.md)'s cycle description to match.

## Related

- [Release cut](/quest/m3/release/cut.md) - holds the steps this rewrites
2 changes: 1 addition & 1 deletion quest/m0/nightly/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ This README's own work, after the children:
fixtures were repaired in [moq-dev/moq#7940](https://github.com/moq-dev/moq/pull/7940).
The receive-windows benchmark's overcommitted cells, skipped since
[moq-dev/moq#7838](https://github.com/moq-dev/moq/pull/7838), moved to
[m1](/quest/m1/receive-windows-evicted.md) on 2026-11-04 (maintainer).
[m1](/quest/m3/receive-windows-evicted.md) on 2026-11-04 (maintainer).

Decided 2026-11-05 (maintainer, /quest-plan): catch the next moq-net bench
break in Nightly's measured coverage only. Do not add a test-mode bench run
Expand Down
25 changes: 25 additions & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,31 @@ 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.

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

- ✅ Additive and docs-only work that sat in m2 moved here, so the cut stops
waiting on it: the time-addressing guide, the JS fills that carry a time,
and outbound federation (rejected: leaving each in m2 beside the breaking
work it follows). Each still lists the m2 quest it builds on under
`Required`. Superseded 2026-11-13, below.
- ✅ The mesh libraries and byte streams moved here from m3 (rejected:
staying first in m3). The 2026-11-03 reason to keep them out of m1 was that
the cut would wait on them; since 2026-11-05 the cut waits on m2 alone, and
a downstream application builds on them from `main` now. Superseded
2026-11-13, below.
- ✅ 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.

Decided 2026-11-13 (maintainer, /quest-plan): no quest requires one in a later
milestone, so the 14 m1 quests that waited on m2 work moved to
[m3](/quest/m3/README.md): buffered-ascending, export-order,
receive-windows-evicted, route-trace-validation, routing-guide,
subscribe-fills-js, time-addressing-guide, and the cluster-routing and mesh
epics whole. ✅ m3 (rejected: m2, where the cut would wait on them; pulling
their 12 breaking m2 blockers into m1). m3 is not gated, and they rank right
after m2, which is when they can start.

Decided 2026-11-13 (maintainer, /quest-plan on what testing to add): tests
that guard what production traffic reaches join m1 ahead of the questline's
m4 default, so changes are proven before they ship: the
Expand Down
2 changes: 2 additions & 0 deletions quest/m4/ashpd-maintained.md → quest/m1/ashpd-maintained.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ adapt the portal capture client to any 0.14 API changes, drop the three
exceptions, then run `just rs audit` and, on Linux,
`cargo check --locked -p moq-video --no-default-features --features pipewire`
so the portal capture client compiles against the new API.
Confirmed 2026-11-12 (/quest-audit): `cargo info ashpd` lists 0.14.0 on
crates.io; the lock still holds 0.13.13.

## Related

Expand Down
5 changes: 3 additions & 2 deletions quest/m3/go-module-proxy.md → quest/m1/go-module-proxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ published version, old and new, verifies against sum.golang.org. The
`moq-dev/moq-go-ffi` mirror stops receiving releases and is archived.

Today each release commits about 61 MiB of compressed staticlibs to that
mirror. It reached 610 MB after 35 releases in 12 weeks, so it passes
GitHub's 1 GB guidance within weeks.
mirror. It reached 610 MB after 35 releases in 12 weeks, and about 819 MiB
with 44 tags on 2026-11-12 (`gh api repos/moq-dev/moq-go-ffi --jq .size`,
in KiB), so it passes GitHub's 1 GB guidance in about three more releases.

## Plan

Expand Down
2 changes: 1 addition & 1 deletion quest/m1/obs-js.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,5 +87,5 @@ Recommended:

- [OBS simulcast check](/quest/m3/obs-multitrack-check.md) - keeps the dock's
Go Live layers; this quest runs the obs-websocket recipe
- [MoQ in obs-studio](/quest/m3/obs-studio/README.md) - a native output keeps
- [MoQ in obs-studio](/quest/m5/obs-studio/README.md) - a native output keeps
the same obs-websocket surface
17 changes: 10 additions & 7 deletions quest/m1/quic-sim.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,13 @@ What remains:
(`crate::bind::udp`), so a sim test cannot reach them yet. Pick how a
caller hands either one a `driver::endpoint::Socket`, such as a
documented `sim`-only hook (`just check` bans `#[doc(hidden)]`). That API
choice belongs to the maintainer.
- Route the session-level spawns that `server.rs`, `connection.rs`, and
`origin.rs` still send through `crate::runtime::spawn` through
choice belongs to the maintainer (see Waiting). `Client::with_network`
(`rs/moq-tokio/src/sim.rs`) already gives a client an in-memory network
under the `sim` feature, and the relay's integration tests run hops and
reconnects over it (`rs/moq-relay/tests/integration/memory.rs`), though
not over QUIC.
- Route the session-level spawns that `server.rs` and `origin.rs` still
send through `crate::runtime::spawn` through
`runtime::Spawner`, as `transport.rs` and the WebTransport session already
do.
- Then run `moq_relay` between a publisher and a subscriber, and between two
Expand All @@ -42,7 +46,6 @@ queue is not evidence about congestion loss.
Decided 2026-11-13 (maintainer, /quest-plan on what testing to add): ✅ m1
(rejected: staying in m4). It is the base for [fault schedules](/quest/m4/cluster-fault-schedules.md).

Check first: `moq_tokio::Client::with_network` and the relay's
`cluster::Config::network` already exist under `sim`, so say which of "What
remains" has landed, and whether that `Network` carries QUIC or the in-memory
transport, before picking the server's hook.
## Waiting

- Maintainer: how moq-tokio's `Client` and `Server` take a simulated QUIC socket. Options: (a) extend the `sim`-feature `Client::with_network` path, already documented as tracking internals that can change in any release, to carry `quic::driver::sim::Network`, with a matching hook on `Server`; (b) a new `sim`-only `with_socket(driver::endpoint::Socket)` on each; (c) drop this quest, since the memory network already covers relay hops and reconnects. Recommended: (a) if a failure only real QUIC would show is named, otherwise (c).
File renamed without changes.
2 changes: 1 addition & 1 deletion quest/m3/stream/rust.md → quest/m1/stream/rust.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ unmodified client and server talk through a relay.

## Plan

See the [epic](/quest/m3/stream/README.md) for the mapping: a socket endpoint
See the [epic](/quest/m1/stream/README.md) for the mapping: a socket endpoint
per forwarded service, a session per connection with one group each way, a
frame per TCP read, no fill handler.

Expand Down
28 changes: 28 additions & 0 deletions quest/m1/token-count-signing-input.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# [S] A malleated signature does not double a token's session cap

## Goal

The auth server counts sessions per token by the token's signing input
(header and payload), not by the whole compact JWS. Today the per-token count
hashes the full string (`Sessions::connect` in `rs/moq-auth/src/serve.rs`),
and an ECDSA signature can be malleated into a second valid string for the
same claims, so an ES256 or ES384 holder gets twice `--limit-token`.

## Plan

Found by the 2026-11-07 invariant audit (auth-6). Split 2026-11-12
(maintainer, /quest-audit before the cut) from
[the O(1) session index](/quest/m4/auth-session-index.md): ✅ this is a fix
to shipped behavior, since token caps are in `release`, so it joins m1 and
can be backported; the index stays an optimization in m4 (rejected: leaving
the fix inside the optimization).

- Key the count on the signing input or the decoded claims; pick whichever
the verifier already has in hand, and say which in the PR.
- Reproduce first: a test that connects with a token and its malleated twin
and exceeds the cap on `main`.
- Check the other places a token is used as a map key (attachment leases,
shared request-token grants) for the same assumption, and fix each in this
PR.

Public API: none. Wire: none.
10 changes: 3 additions & 7 deletions quest/m1/wire-fuzz-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## Goal

The hand-written unsafe that peer input reaches in `moq-c`, `moq-uring`, and `moq-sock` runs under Miri or a fuzz target of its own, asserting more than "it did not panic". Other peer-facing decoders, such as the media importers and RTMP's AMF0, are outside this quest.
The hand-written unsafe that peer input reaches in `moq-uring` and `moq-sock` runs under Miri or a fuzz target of its own, asserting more than "it did not panic". Other peer-facing decoders, such as the media importers and RTMP's AMF0, are outside this quest.

The moq-net half is done: the `ingest` and `request` targets cover the incremental group ingest and request-stream framing, and the seeds include prefixes at and past every cap. What remains: `rs/moq-c`, `rs/moq-uring`, and `rs/moq-sock` have no fuzz target and no Miri run. Their cmsg walks bound every length by the buffer, with unit tests, but nothing searches for the next mistake.
The moq-net half is done: the `ingest` and `request` targets cover the incremental group ingest and request-stream framing, and the seeds include prefixes at and past every cap. What remains: `rs/moq-uring` and `rs/moq-sock` have no fuzz target and no Miri run. `moq-c`'s unsafe is the C ABI, reached by its C caller rather than by a peer, so it is not part of this quest. Their cmsg walks bound every length by the buffer, with unit tests, but nothing searches for the next mistake.

## Plan

Expand All @@ -18,10 +18,7 @@ The point is the invariant, not the coverage number: a target that only checks f

Each crate follows moq-net's shape (`rs/moq-net/fuzz/README.md`): the target body in a `fuzz` module, documented as test support behind the `fuzz` feature, so the crate's own tests replay `fuzz/regressions/` on stable, a one-line shim per target, an `--exclude` in the `no_fuzz` list of `rs/justfile`, and a row in `nightly.yml`'s fuzz matrix. Target names must stay unique across crates.

Ordering:

- `moq-sock`'s `CMsg::decode` still reads `size_of::<T>()` past a short message (only a `debug_assert_eq!` checks it), which [Bound cmsg payload reads](https://github.com/moq-dev/moq/pull/7394) fixes. A moq-sock target landing first would fail nightly on that known overread, so land it after, or with, that fix. The moq-uring target has no such dependency.
- `just rs miri` and its nightly job already exist ([moq-dev/moq#7315](https://github.com/moq-dev/moq/pull/7315)); this quest adds its crates to them.
`moq-sock`'s known overread is fixed: [moq-dev/moq#7394](https://github.com/moq-dev/moq/pull/7394) (merged 2026-11-01) bounds `CMsg::decode` (`rs/moq-sock/src/udp/cmsg/mod.rs`), which now returns `None` for a short message, so neither target waits on anything. `just rs miri` and its nightly job already exist ([moq-dev/moq#7315](https://github.com/moq-dev/moq/pull/7315)); this quest adds its crates to them.

Decided 2026-11-13 (maintainer, /quest-plan on what testing to add): ✅ m1
(rejected: staying in m4). This unsafe is reachable by any peer.
Expand All @@ -31,4 +28,3 @@ Public API: none. Wire: none.
## Related

- [CI cost and latency](/quest/m0/ci/README.md) - where the nightly budget lives
- [Bound cmsg payload reads](https://github.com/moq-dev/moq/pull/7394) - fixes the moq-sock overread a cmsg target would hit
30 changes: 25 additions & 5 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,30 @@ fixes, and moq-c parity) live under the recurring
cut gate, decided the same day; the [release cut](/quest/m3/release/cut.md)
holds its template.

Held by open claims: the [probe epic](/quest/m2/probe/README.md)
stays here while its open claims last, so the cut waits on it until the
[re-cut follow-up](/quest/m2/recut-held.md) moves it to m3. Its padding and JS
rung disable quests already moved to m3 on 2026-11-06.
Decided 2026-11-12 (maintainer, /quest-audit before the cut):

- ✅ Left m2, so the cut stops waiting on them: the
[probe epic](/quest/m3/probe/README.md) to m3 and the routes
[browser proof](/quest/m5/routes-browser-proof.md) to m5 (each waits on a
browser release and breaks nothing); the docs-only and additive quests and
outbound federation to [m1](/quest/m1/README.md); and
[unbounded groups](/quest/m3/unbounded-groups/README.md) to m3, whose byte
offset goes on the wire version after lite-07 (rejected for each: staying
in m2). The padding and JS rung disable quests are parked in m5.
- ✅ Joined m2, each a small break the cut would otherwise freeze: the mesh
[grant shape](/quest/m2/mesh-grant-shape.md) and
[key budget](/quest/m2/mesh-device-bounds.md), since `moq_auth::mesh`
publishes for the first time at this cut;
[auth key validation](/quest/m2/auth-key-validation.md); the
[RTMPS connect](/quest/m2/rtmp-rtmps-tcurl.md) signature;
[usage's derived settings](/quest/m2/usage-derive-settings.md);
[first-publish versions](/quest/m2/first-publish-versions.md); and three
API fences: [mesh enrollment](/quest/m2/api-mesh-enrollment.md),
[the capture selections](/quest/m2/api-capture-fences.md), and
[the acknowledgment hook's trait](/quest/m2/api-ack-hook-trait.md). None
is on the routes chain, which stays the critical path.
- ✅ Under the path rule a route keeps one sticky down-only flag beside its
path; see the [routes epic](/quest/m2/cluster-routes/README.md).

Carried from m1's Plan before the re-cut, where "m1" means the whole pre-cut
milestone, now m1 and m2:
Expand Down Expand Up @@ -85,7 +105,7 @@ warmup rule for the shipping dual decoder, the binding migration guide fixes,
and the API-diff tooling. Public routes now wait on cluster routing.

Added 2026-10-20 (maintainer): the probe target, native probing, and the
native rung disable moved up from the [m2 probe epic](/quest/m2/probe/README.md),
native rung disable moved up from the [m2 probe epic](/quest/m3/probe/README.md),
so Rust, FFI, and OBS publishers recover a stopped rendition in this release;
padding and the browser's rung disable stayed in m2, with only padding's
lite-07 stream type here. Both moved to m3 on 2026-11-06 (maintainer,
Expand Down
Loading