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
54 changes: 54 additions & 0 deletions quest/m2/features-leaf-trims.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# [S] Drop the compile-trim features from the media and gateway crates

## Goal

These features, each gating pure-Rust code or logic only, go away and
their code always compiles:

- moq-audio: `aac` and `bus` (pure Rust, on by default, and every consumer
that builds moq-audio enables `aac`), and `aec`, which adds no dependency and
gates only the echo-canceller wiring between `capture` and `playback`;
compile that on `all(feature = "capture", feature = "playback")`.
- moq-ffi: `audio` and `video`, which are defaults no build turns off (the C++
wrapper refuses a prebuilt moq-ffi without them).
- moq-rtmp: `tls`, whose rustls and tokio-rustls every consumer already has
through moq-tokio.
- moq-webrtc: `p2p`, whose if-addrs, mdns-sd, and qmux are already in moq-cli's
tree through LAN discovery and the qmux transports.
- moq-quic: `mux`, which gates the sans-IO QMux connection and no dependency.
- moq-video: `dmabuf`, a private helper module the `vaapi`, `render`, and
`pipewire` features turn on; compile it on Linux.

And moq-video's `v4l2`, which costs the build nothing (moq-v4l checks its
bindings in), joins the defaults beside `vaapi` and `nvidia` in moq-video,
moq-transcode, and moq-cli.

## Plan

Found by the [Cargo feature review](/quest/m3/release/feature-flags.md) (first
pass, 2026-11-14), against the `# Features` rules in `rs/AGENTS.md`: none of
these is a vendor integration or a system dependency, so each only trims
compile time or gates logic out of the default test run.

Decided 2026-11-14 (maintainer, /quest-complete): ✅ keep this quest in m2
(rejected: drop it).

moq-video's `v4l2` stays a feature rather than always compiling, like `vaapi`
and `nvidia`: each is one vendor's hardware path, and a consumer such as
demo/carla's bridge builds one vendor alone. As a default, the moq-cli
release workflow's `linux-features: v4l2` becomes redundant;
[Ship capture and playback](/quest/m3/cli-packaging.md) replaces that line
with `full` anyway, so leave it to that quest.

Breaking for anyone who names a removed feature: the PR's Impact section says
to delete it, except `aec`, which a manifest replaces with `capture,playback`
to keep both device APIs. Update `doc/lib/rs` pages and crate READMEs that
mention these features, and `rs/justfile`: the `audio-devices` recipe's
`--features aec,pulseaudio` becomes `capture,playback,pulseaudio`, and the
CodSpeed bench recipe drops `moq-audio/bus`. moq-audio's `bus` bench drops its
`required-features = ["bus"]`.

## Related

- [Always compile the network stack](/quest/m2/features-network.md) - the same
rule applied to the transport crates
68 changes: 68 additions & 0 deletions quest/m2/features-network.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# [L] Always compile the network stack

## Goal

The transports, LAN discovery, STUN, and the io_uring runtime compile into
every build of the crates that offer them, picked at runtime by URL scheme,
flag, or config instead of by Cargo feature. These features go away:

- moq-tokio: `net`, `driver`, `quic`, `websocket`, `tcp`, `uds`, `qmux`,
`watch`, `mdns`, and the private `_transport` and `_certs`. It keeps
`jemalloc` (a C build) and `sim` (test-only), and `qlog` until
[Always compile qlog](/quest/m2/features-qlog.md) decides it.
- moq-relay: `quic`, `_quic`, `websocket`, `uds`, `cluster-lan`, `stun`,
`io-uring`, and `_uring`.
- moq-cli: `quic`, `websocket`, and `cluster-lan`.
- moq-bench and moq-boy: `quic`, `websocket`, and `tcp`.
- qmux: `tcp`, `tls`, `uds`, `ws`, and `wss`.

Unix sockets compile on `cfg(unix)` and io_uring on `cfg(target_os =
"linux")`, as platform gates rather than features.

## Plan

Found by the [Cargo feature review](/quest/m3/release/feature-flags.md) (first
pass, 2026-11-14). The `# Features` rules in `rs/AGENTS.md` keep a feature only
for a vendor integration or a system dependency. None of these is either: every
crate they gate is pure Rust. Measured with `cargo tree -e normal`, moq-relay's
default `quic`, `websocket`, `uds`, and `cluster-lan` add 10 of its 278
crates (mdns-sd, if-addrs, flume, socket-pktinfo, web-transport-proto, sfv, and
four small helpers); moq-tokio's `websocket`, `tcp`, and `uds` add 12 over
`quic` alone. Against that, `quic`, `websocket`, `tcp`, and `uds` hold about
660 `cfg` sites in moq-tokio and 160 in moq-relay, plus the "every subset
compiles" matrix in `just rs features` (`rs/justfile`) and private markers
(`_quic`, which only `quic` enables, and `_transport`) that exist only to make
those subsets compile. No shipped consumer turns them off: the release binaries,
Nix, moq-ffi, moq-gst, and moq-c all build every transport.

moq-tokio's `driver` without `net` (the QUIC driver without moq-net) has no
consumer: every enabler also turns on a transport, which turns on `net`. moq-net
becomes an unconditional dependency.

Keep each runtime refusal that names a missing feature only where a platform can
still lack it (io_uring off Linux, Unix sockets off Unix), and reword it to name
the platform. `config.rs`'s "needs moq-relay built with the `quic` feature"
checks go away, with the tests that assert them, such as
`workers_require_a_quic_backend` in `rs/moq-relay/src/relay.rs`.

Breaking for anyone who names a removed feature in a manifest: Cargo errors on
an unknown feature. The PR's Impact section says to delete those names from
`features = [...]` and `--features`; nothing replaces them.

Decided 2026-11-14 (maintainer, /quest-complete): ✅ keep this quest in m2
(rejected: drop it), and ✅ compile moq-relay's io_uring runtime into every
Linux build (rejected: keep `io-uring` as an opt-in feature). It is pure Rust
(the `io-uring` crate, no liburing), already selected at runtime by
`--runtime-io-uring`, and moq-relay already carries most of what `_uring`
adds.

Update `doc/bin/relay` and `doc/bin/cli.md` wherever they tell a source
builder to pass one of these features, `bench/run.sh`'s and
`.oss-scanner/Dockerfile`'s `--features moq-relay/io-uring`, and the
`rs/justfile` recipes that name a removed feature: `features` (moq-cli's
`websocket`), `uring`, and `uring-check` (moq-relay's `io-uring`).

## Related

- [Cost audit](/quest/m3/audit-cost.md) - owns per-crate build cost, which this
trades a little of for a smaller test matrix
43 changes: 43 additions & 0 deletions quest/m2/features-qlog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# [S] Always compile qlog

## Goal

qlog trace capture compiles into every build that has QUIC, and the existing
runtime switches (`--quic-qlog <DIR>`, `--client-quic-qlog <DIR>`,
`quic::Transport::qlog`, moq-ffi's and the C++ wrapper's qlog option) are the
only way to turn it on. The `qlog` features of moq-quic, moq-tokio, moq-uring,
moq-relay, moq-cli, and moq-ffi, and the C++ `MOQ_FFI_QLOG` CMake option, go
away.

## Plan

Found by the [Cargo feature review](/quest/m3/release/feature-flags.md) (first
pass, 2026-11-14). Decided 2026-11-14 (maintainer, /quest-complete): ✅ keep
this quest in m2 (rejected: drop it).

The features exist so "production builds do not pull in the
qlog crate and its serde_json encoder". Measured with `cargo tree -e normal`,
`qlog` adds one crate to moq-relay (`qlog` itself; serde, serde_json, and
serde_with are already there) and 16 to moq-quic alone. It costs about 30 `cfg`
sites in moq-quic and 10 in moq-uring, and it means an operator who hits a
congestion bug on a shipped relay has to rebuild before they can trace it.

Confirm that a connection with qlog off pays nothing on the hot path (the
writer is `None` and no event is built) before removing the gate; if it does
pay, fix that in the same PR rather than keep the feature.

Breaking for anyone who names `qlog` in a manifest or passes
`-DMOQ_FFI_QLOG=ON`: the PR's Impact section says to delete it. A prebuilt
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
moq-ffi then carries qlog, so `cpp/moq/cmake/moq-ffi.cmake` drops its check
that a prebuilt input lacks it, and moq-ffi's `moq_qlog_supported` (always
true then) is deleted from every binding with its "fails unless supported"
doc on `MoqQuicConfig::qlog`. `doc/bin/relay/config.md` drops "Needs the
`qlog` build feature", `doc/bin/obs.md` drops its `-DMOQ_FFI_QLOG=ON` source
build for traces, and the `rs/justfile` uring recipes drop `moq-relay/qlog`
from their clippy run and `--features qlog` from moq-uring's nextest run.

## Related

- [Always compile the network stack](/quest/m2/features-network.md) - removes
the other moq-tokio and moq-relay features; expect conflicts in the same
manifests
2 changes: 1 addition & 1 deletion quest/m3/cli-packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ encoder (congestion control retunes through it) and 1080p, which codes as
1088 rows and relies on the compose rectangle to crop back.

`moq-cli.yml` already passes `linux-features: v4l2` to `release-binary.yml`,
a no-op until `capture` is on; `release` replaces it there.
a no-op until `capture` is on; `full` replaces it there.

Add a board hardware note to `doc/bin/cli.md` next to the capture build
instructions: Raspberry Pi 5 has no video encoder and Jetson Orin Nano ships
Expand Down
4 changes: 2 additions & 2 deletions quest/m3/nixpkgs-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ encoders), kept current by nixpkgs-update from our `moq-cli-v*` tags.

Decided 2026-11-05 (maintainer, /quest-plan):

- Should the nixpkgs moq-cli wait for cli-packaging's `release` feature?
- Should the nixpkgs moq-cli wait for cli-packaging's `full` feature?
- Don't wait
- ✅ Wait for cli-packaging
- The maintainer added "moq-cli only when we're happy with the feature set"
Expand All @@ -34,5 +34,5 @@ their driver libraries, so make them findable at runtime (for example

## Required

- [Ship capture and playback](/quest/m3/cli-packaging.md) - the `release` feature set that the nixpkgs package builds
- [Ship capture and playback](/quest/m3/cli-packaging.md) - the `full` feature set that the nixpkgs package builds
- [moq-relay in nixpkgs](/quest/m3/nixpkgs-relay.md) - kixelated's maintainer entry and the package conventions
129 changes: 80 additions & 49 deletions quest/m3/release/feature-flags.md
Original file line number Diff line number Diff line change
@@ -1,64 +1,95 @@
# [M] Cargo feature review before the cut
# [S] Cargo feature review before the cut: delta pass

## Goal

Every Cargo feature in the workspace has been judged before the release
ships. Defaults build nothing expensive or system-dependent. Each feature that
remains lives in the crate that owns its integration (`s3` in moq-archive,
forwarded by the binaries that ship it). A feature that only trims compile
time is removed in favor of always-compiled code. The scope covers the
defaults and `release` sets of shipped binaries, and the feature lists the
bindings and packaging builds pass. Each change the maintainer approves is a
quest that lands before the cut.
Every Cargo feature m2 added or changed since the first pass (2026-11-14) has
been judged before the release ships, by the same rules: defaults build
nothing expensive or system-dependent; each feature that remains is a vendor
integration or a system dependency and lives in the crate that owns that
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
integration, forwarded by dependents under the same name; a feature that only
trims compile time is removed in favor of always-compiled code. The scope
covers the defaults and `full` sets of shipped binaries, and the feature lists
the bindings and packaging builds pass. Each change the maintainer approves is
a quest that lands before the cut. A feature that matches a reason the Plan's
Kept list records (the poll-first `async` design, a test or harness hook, an
optional `serde`, or a layering split) also stays.

## Plan

Recurs once per API or wire cut (decided 2026-10-26; per breaking cut
2026-11-09). The [release cut](/quest/m3/release/cut.md) re-creates this quest
when the maintainer names the next API or wire cut, so the PR finishing this
run adds no successor.
Record what this run learned (inventory method, findings, what to check
first) in the cut's PR notes or a follow-up quest, so the next run starts from
it. Only `/quest-delete` ends the recurrence.
run adds no successor. Record what this run learned in the cut's PR notes or a
follow-up quest. Only `/quest-delete` ends the recurrence.

Decided 2026-11-12 (maintainer, /quest-audit before the cut): ✅ this run
starts now, on the features `main` has today, with a delta pass after m2
(rejected: one pass after m2 lands, which puts every approved change behind
the routes chain instead of beside it). The first pass's PR rewrites this
quest to the delta pass: features m2 added or changed since, with
[m2](/quest/m2/README.md) under `Required`. The cut waits for the delta pass. Feature changes break downstream builds, which is why this
runs before the cut rather than with the post-release audits. Like the [API
shape review](/quest/m3/release/api-review.md), this run changes no code
(decided 2026-10-26): it proposes each change with a recommendation, asks the
maintainer, and files each approved change as a quest in m2, which holds the
cut until it lands.
Decided 2026-11-12 (maintainer, /quest-audit): a first pass on `main` as it
stood, then this delta pass after m2. Like the [API shape
review](/quest/m3/release/api-review.md), it changes no code: it proposes
each change with a recommendation and files each approved change as a quest
in m2.

Judge every feature against the `# Features` rules in `rs/AGENTS.md`, and
challenge each one's premise: fewer features are better. A feature trims a
build for a few power users but fragments the code and its test matrix, so
keep one only for a vendor integration or a system dependency. For each crate,
inventory the `[features]` table, which crates forward each feature, and what
it gates. Then check:
What the first pass ([moq-dev/moq#8765](https://github.com/moq-dev/moq/pull/8765))
judged, so this pass reads only the difference:

- Defaults: nothing that needs libclang, a system library at build or load
time, or a large dependency tree. A shipped binary's `release` set holds
every backend its platform loads without a system library.
- Scope: a vendor feature sits in the crate that integrates the vendor, and
dependents forward it under the same name instead of enabling their
dependencies' features directly.
- Fragmentation: features no consumer turns off, or that gate logic rather
than a dependency, are candidates to delete.
- Method: list every `[features]` table (`git ls-files '*Cargo.toml'`), every
internal dependency's `features =` and `default-features`, every
`--features` in `.github/`, `nix/`, `.cargo/config.toml`, `bench/run.sh`,
`rs/justfile`, the binding build hooks (`dart/`, `py/`, `pyproject.toml`,
`cpp/`), and count `cfg(feature = ...)` sites per crate. Measure a
feature's cost with `cargo tree -e normal --prefix none` with and without
it, inside the shipped binary rather than the crate alone: most features
that look heavy on their crate add one or two crates to moq-relay or moq-cli.
Diff this pass's inventory against the first pass's to find what m2 added.
- Filed: [network stack](/quest/m2/features-network.md),
[qlog](/quest/m2/features-qlog.md), and [media and gateway
trims](/quest/m2/features-leaf-trims.md). Check each landed or was dropped.
- Kept, with the reason a new feature has to match:
- `async` in kio, moq-net, hang, moq-json, moq-mux, moq-stats, moq-hls,
moq-crypto, and moq-auth: the poll-first design (decided 2026-11-05 in
[moq-dev/moq#7607](https://github.com/moq-dev/moq/pull/7607)), checked
by `just rs coroutines`. kio's `runtime`, `macros`, `sim`, and `manual`
follow it.
- Vendor or system: moq-video's `nvidia`, `vaapi`, `mediacodec`, `v4l2`,
`openh264` (a vendored C++ build), `vpx` (system libvpx), `pipewire`
(libpipewire), and `render` (wgpu); moq-audio's `capture`, `playback`,
`pipewire`, and `pulseaudio` (libasound through cpal); `jemalloc` (a C
build); moq-cli's `s3`, `gcs`, and `azure`.
- Large HTTP stacks a library embedder owns: moq-auth's `client`
(reqwest) and `serve` (axum), moq-hls's and moq-webrtc's `server` (axum).
- moq-crypto's `sign`, `e2ee`, `cpu`, and `provider`: they keep moq-net out
of moq-quic's graph, a layering need rather than a trim.
- `serde` in kio, moq-pattern, and moq-crypto: an optional dependency, by
ecosystem convention.
- moq-video's `capture`: device I/O the bindings deliberately leave to the
language wrappers, and its platform frameworks would bloat mobile builds.
- moq-cli's `capture`, `play`, and `transcode`: [Ship capture and
playback](/quest/m3/cli-packaging.md) owns them and the `full` set.
- Test and harness hooks, off by default and never in a shipped build:
`fuzz` (moq-net, moq-mux, moq-quic, moq-rtmp, moq-sock, moq-uring),
`sim` (moq-quic, moq-tokio), `test-support` (moq-relay, moq-rtsp),
`testing` (moq-ffi), `test` (moq-shaper), `bench` (moq-json, moq-stats),
`_manual` and `_probe` (moq-uring), and uniffi-bindgen's `cli`. Cross-crate
tests and fuzz crates are separate packages, so a dev-dependency cannot
replace them.
- Corrected premise: storage features belong in moq-cli, not moq-archive.
moq-archive is generic over any `ObjectStore`; moq-cli's `open_store` is the
code that integrates S3, GCS, and Azure.

What to check first (seeded 2026-10-26):
What to check first in this pass:

- moq-cli's `s3`, `gcs`, and `azure` enable `object_store/aws`, `gcp`, and
`azure` directly; moq-archive, which owns storage, has no features. Also
check moq-cli's other defaults (`cluster-lan`, `quic`, `websocket`, `nvidia`)
against the rules. Distributions building with `release` is
[Ship capture and playback](/quest/m3/cli-packaging.md)'s work, not this
review's.
- The crates with the most features at seeding: moq-cli (21), moq-tokio (17),
moq-relay (14), and moq-video (11).
- New `[features]` entries and new `default-features = false` consumers since
the first pass, especially in crates m2's routes and cluster work touched
(moq-net, moq-relay, moq-tokio).
- Whether [ALSA without a load-time
link](/quest/m3/capture-alsa-link.md) landed: if libasound loads at run time,
moq-audio's `capture` and `playback` no longer need a system library to
build, and their premise needs re-judging.

Related: the [cost audit](/quest/m3/audit-cost.md) owns per-crate build
cost and which dependencies exist.
## Required

- [m2](/quest/m2/README.md) - the delta pass judges what m2 added

## Related

- [Cost audit](/quest/m3/audit-cost.md) - owns per-crate build cost and which
dependencies exist