Repository navigation
quest: Cargo feature review, first pass #8765
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
1d68907
chore(quest): claim quest/m3/release/feature-flags.md
kixelated 7eca84e
quest: Cargo feature review, first pass, files three m2 trims
kixelated ffaf826
quest: record the maintainer's picks for the feature-review follow-ups
kixelated 81ce292
quest: name the recipes, tests, and docs the feature removals touch
kixelated File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
|
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 | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.