From 7d0e853a2eef018f45317bfb7301be547fe9cd09 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 14:05:22 -0700 Subject: [PATCH 1/3] fix(tokio): document the mdns module instead of linking a gated one `cargo doc -p moq-tokio` with default features fails on the crate-level `[`mdns`]` link: the module is gated behind the non-default `mdns` feature, so rustdoc has no item to resolve. `RUSTDOCFLAGS="-D warnings"` makes it a hard error, and `just check`'s doc pass is diff-scoped, so it fires on any branch whose diff selects moq-tokio. The nightly `features` recipe never saw it because it documents the workspace with `--all-features`, which compiles the module in. Name the module and its feature in prose rather than linking it, so the sentence reads the same in every build. Co-Authored-By: Claude Opus 5 --- rs/moq-tokio/src/lib.rs | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/rs/moq-tokio/src/lib.rs b/rs/moq-tokio/src/lib.rs index 2a60fdf8f0c..d6659b9fb7f 100644 --- a/rs/moq-tokio/src/lib.rs +++ b/rs/moq-tokio/src/lib.rs @@ -9,10 +9,44 @@ //! - Iroh P2P (requires `iroh` feature) //! //! See [`Client`] for connecting to relays and [`Server`] for accepting -//! connections. [`mdns`] finds peers to connect to on the local network. +//! connections. The `mdns` module, behind the feature of the same name, finds +//! peers to connect to on the local network. +//! +//! # Required features +//! +//! A build needs a QUIC backend (`quinn`, `quiche`, or `noq`), and `quinn`/`noq` +//! additionally need a crypto provider (`aws-lc-rs` or `ring`) since their rustls +//! dependency is built with default features off. The `default` feature set covers +//! both; a consumer using `default-features = false` has to pick them itself. #![warn(missing_docs)] +// A backend-less build is not a supported configuration, and without these it fails deep in +// the modules that assume one: `QuicBackend` becomes an empty enum, `RequestKind` an empty +// match, and `worker`/`server` reference items their own gates removed. Say so once here +// instead of letting the caller read eight errors that never name the cause. +// +// Workspace builds never reach these: cargo unifies features per crate, so a member that +// depends on moq-tokio with a backend enables it for everyone. Only `-p moq-tokio` or an +// external consumer with `default-features = false` can select the broken shapes. +#[cfg(not(any(feature = "quinn", feature = "quiche", feature = "noq")))] +compile_error!( + "moq-tokio requires a QUIC backend: enable one of the `quinn`, `quiche`, or `noq` features. \ + A tcp/uds-only build is not supported (see moq-dev/moq#2834)." +); + +// `quinn` is the sharper half: unlike `noq` it still compiles, then has no initial cipher at +// runtime, so the failure lands on a connection attempt rather than the build. `quiche` needs +// neither, since boringssl brings its own. +#[cfg(all( + any(feature = "quinn", feature = "noq"), + not(any(feature = "aws-lc-rs", feature = "ring")) +))] +compile_error!( + "the `quinn` and `noq` backends require a crypto provider: enable `aws-lc-rs` or `ring`. \ + Their rustls dependency is built with default-features off, so there is no cipher without one." +); + pub mod accept; pub use moq_sock::bind; pub mod cli; From a659cd6e2254e51414fdca532a3bbce0b68d3b7c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 14:05:22 -0700 Subject: [PATCH 2/3] feat(tokio): reject an unsupported feature build with one honest error `cargo check -p moq-tokio --no-default-features` failed with 8 errors, none of which named the cause: `QuicBackend` becomes an empty enum, `RequestKind` an empty match, and `worker`/`server` reference `util`/`DEFAULT_BIND` that their own gates removed. The count grows as the crate does; it was 5 when this was filed. Rather than make a backend-less build work, state that it is unsupported. `worker`, `steer`, and `server` all assume a backend exists, so a `compile_error!` matches reality and names the features to enable. Auditing the feature space turned up a second unsupported shape the issue did not cover. `quinn` and `noq` take their crypto provider from the `aws-lc-rs`/`ring` features, since their rustls dependency is built with default features off: - `--features noq` alone fails with 3 unrelated E0599s about missing `EndpointConfig::default` and `ServerConfig::with_crypto`. - `--features quinn` alone *compiles*, then has no initial cipher at runtime, so the failure lands on a connection attempt instead of the build. That one is worth catching precisely because it is silent. `quiche` needs neither, bringing its own through boringssl, and is the only single-feature build that is actually supported. Workspace builds cannot reach either shape: cargo unifies features per crate, so a member depending on moq-tokio with a backend enables one for everyone. That is why nightly's `--workspace --no-default-features` leg never caught this, and it still passes unchanged. Only `-p moq-tokio` or an external consumer with `default-features = false` selects the broken shapes, so `just rs _unsupported-features` asserts each one still fails on its own message rather than on whatever breaks first inside the modules. `compile_error!` does not halt compilation, so the downstream errors still follow it; the change is that the first one names the cause and the fix. Closes #2979 Co-Authored-By: Claude Opus 5 --- doc/lib/rs/crate/moq-tokio.md | 2 ++ rs/justfile | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/doc/lib/rs/crate/moq-tokio.md b/doc/lib/rs/crate/moq-tokio.md index 2276605fa2a..1d1072bae03 100644 --- a/doc/lib/rs/crate/moq-tokio.md +++ b/doc/lib/rs/crate/moq-tokio.md @@ -27,6 +27,8 @@ Tokio-based connection helpers for native Rust applications. Provides TLS config moq-tokio = "0.19" ``` +The default features cover a working build. If you set `default-features = false`, pick a QUIC backend (`quinn`, `quiche`, or `noq`) plus, for `quinn` or `noq`, a crypto provider (`aws-lc-rs` or `ring`); `quiche` brings its own. A build missing either fails with a message naming what to enable. + ## API Reference Full API documentation: [docs.rs/moq-tokio](https://docs.rs/moq-tokio) diff --git a/rs/justfile b/rs/justfile index 2b25ac4a82a..9271fb76c0b 100644 --- a/rs/justfile +++ b/rs/justfile @@ -382,6 +382,32 @@ features: cargo clippy --locked --workspace --all-targets --all-features -- -D warnings RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps cargo nextest run --locked --workspace --all-targets --all-features + just rs _unsupported-features + +# The workspace compiles above can't reach a backend-less moq-tokio: cargo unifies +# features per crate, so a member depending on it with a backend enables one for +# everyone. Only a per-crate invocation selects the shapes an external consumer with +# `default-features = false` can land on, so assert those still fail on their own +# `compile_error!` rather than on whatever breaks first inside the modules. +_unsupported-features: + #!/usr/bin/env bash + set -euo pipefail + + expect() { + local want="$1"; shift + local got + got=$(cargo check --locked -p moq-tokio --no-default-features "$@" 2>&1 || true) + if ! grep -qF "$want" <<< "$got"; then + echo "rs: moq-tokio ${*:-(no features)} should fail on: $want" >&2 + echo "$got" | grep -E '^error' >&2 || true + exit 1 + fi + } + + expect "requires a QUIC backend" + expect "requires a QUIC backend" --features tcp + expect "require a crypto provider" --features quinn + expect "require a crypto provider" --features noq # nextest, not `cargo test`, so a wedged test is killed instead of pinning a core # until someone notices (`.config/nextest.toml` sets the timeout). The trade is From 530014e118e545dca3e9e3ecfc2a29946285ccf0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 28 Aug 2026 14:58:31 -0700 Subject: [PATCH 3/3] fix(tokio): don't refuse a quinn build that installs its own crypto provider The crypto-provider guard covered `quinn` as well as `noq`, which removes a supported configuration. `crypto::provider()` resolves the provider at runtime and takes `CryptoProvider::get_default()` first, so an application that calls `install_default()` works with `quinn` and no provider feature. Its panic names that path as the equal alternative to the features: "no CryptoProvider available; install_default() or enable either the aws-lc-rs or ring feature" Refusing the build made it unreachable, turning a working setup into a compile error for any consumer doing this. `noq` keeps the guard, because it is not a runtime question there: without a provider feature `web-transport-noq` is built without its own, and the constructors this crate calls stop existing, so the build fails regardless of what the application installs later. Found by Codex review (P2) and verified against `crypto.rs`. Co-Authored-By: Claude Opus 5 --- doc/lib/rs/crate/moq-tokio.md | 2 +- rs/justfile | 6 ++++-- rs/moq-tokio/src/lib.rs | 29 ++++++++++++++++------------- 3 files changed, 21 insertions(+), 16 deletions(-) diff --git a/doc/lib/rs/crate/moq-tokio.md b/doc/lib/rs/crate/moq-tokio.md index 1d1072bae03..797ac7ae12a 100644 --- a/doc/lib/rs/crate/moq-tokio.md +++ b/doc/lib/rs/crate/moq-tokio.md @@ -27,7 +27,7 @@ Tokio-based connection helpers for native Rust applications. Provides TLS config moq-tokio = "0.19" ``` -The default features cover a working build. If you set `default-features = false`, pick a QUIC backend (`quinn`, `quiche`, or `noq`) plus, for `quinn` or `noq`, a crypto provider (`aws-lc-rs` or `ring`); `quiche` brings its own. A build missing either fails with a message naming what to enable. +The default features cover a working build. If you set `default-features = false`, pick a QUIC backend (`quinn`, `quiche`, or `noq`); a build without one fails with a message naming them. `noq` also needs a crypto provider (`aws-lc-rs` or `ring`) to compile. `quinn` takes one from either feature or from a provider you install yourself with `CryptoProvider::install_default()`, and `quiche` brings its own. ## API Reference diff --git a/rs/justfile b/rs/justfile index 9271fb76c0b..e6af02ffb5a 100644 --- a/rs/justfile +++ b/rs/justfile @@ -389,6 +389,9 @@ features: # everyone. Only a per-crate invocation selects the shapes an external consumer with # `default-features = false` can land on, so assert those still fail on their own # `compile_error!` rather than on whatever breaks first inside the modules. +# +# `--features quinn` is deliberately absent: it compiles without a provider feature and +# takes one from `CryptoProvider::install_default()` at runtime, which is supported. _unsupported-features: #!/usr/bin/env bash set -euo pipefail @@ -406,8 +409,7 @@ _unsupported-features: expect "requires a QUIC backend" expect "requires a QUIC backend" --features tcp - expect "require a crypto provider" --features quinn - expect "require a crypto provider" --features noq + expect "requires a crypto provider" --features noq # nextest, not `cargo test`, so a wedged test is killed instead of pinning a core # until someone notices (`.config/nextest.toml` sets the timeout). The trade is diff --git a/rs/moq-tokio/src/lib.rs b/rs/moq-tokio/src/lib.rs index d6659b9fb7f..415aed072c5 100644 --- a/rs/moq-tokio/src/lib.rs +++ b/rs/moq-tokio/src/lib.rs @@ -14,10 +14,11 @@ //! //! # Required features //! -//! A build needs a QUIC backend (`quinn`, `quiche`, or `noq`), and `quinn`/`noq` -//! additionally need a crypto provider (`aws-lc-rs` or `ring`) since their rustls -//! dependency is built with default features off. The `default` feature set covers -//! both; a consumer using `default-features = false` has to pick them itself. +//! A build needs a QUIC backend (`quinn`, `quiche`, or `noq`). `noq` additionally +//! needs a crypto provider (`aws-lc-rs` or `ring`) to compile at all. `quinn` takes +//! one from either feature or from a provider the application installed with +//! `CryptoProvider::install_default()`, and `quiche` brings its own. The `default` +//! set covers all of this; `default-features = false` means picking them yourself. #![warn(missing_docs)] @@ -35,16 +36,18 @@ compile_error!( A tcp/uds-only build is not supported (see moq-dev/moq#2834)." ); -// `quinn` is the sharper half: unlike `noq` it still compiles, then has no initial cipher at -// runtime, so the failure lands on a connection attempt rather than the build. `quiche` needs -// neither, since boringssl brings its own. -#[cfg(all( - any(feature = "quinn", feature = "noq"), - not(any(feature = "aws-lc-rs", feature = "ring")) -))] +// Without a provider feature, `web-transport-noq` is built without its own, and the endpoint +// constructors this crate calls stop existing: the build fails with three unrelated E0599s +// about `EndpointConfig::default` and `ServerConfig::with_crypto`. Say which feature is +// missing instead. +// +// Only `noq` gets this. `quinn` compiles either way and resolves its provider at runtime +// through `crypto::provider()`, which accepts one the application installed with +// `CryptoProvider::install_default()`; refusing that build would remove a supported path. +// `quiche` needs neither, since boringssl brings its own. +#[cfg(all(feature = "noq", not(any(feature = "aws-lc-rs", feature = "ring"))))] compile_error!( - "the `quinn` and `noq` backends require a crypto provider: enable `aws-lc-rs` or `ring`. \ - Their rustls dependency is built with default-features off, so there is no cipher without one." + "the `noq` backend requires a crypto provider: enable `aws-lc-rs` or `ring`." ); pub mod accept;