diff --git a/doc/lib/rs/crate/moq-tokio.md b/doc/lib/rs/crate/moq-tokio.md index 2276605fa2a..797ac7ae12a 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`); 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 Full API documentation: [docs.rs/moq-tokio](https://docs.rs/moq-tokio) diff --git a/rs/justfile b/rs/justfile index 2b25ac4a82a..e6af02ffb5a 100644 --- a/rs/justfile +++ b/rs/justfile @@ -382,6 +382,34 @@ 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. +# +# `--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 + + 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 "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 2a60fdf8f0c..415aed072c5 100644 --- a/rs/moq-tokio/src/lib.rs +++ b/rs/moq-tokio/src/lib.rs @@ -9,10 +9,47 @@ //! - 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`). `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)] +// 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)." +); + +// 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 `noq` backend requires a crypto provider: enable `aws-lc-rs` or `ring`." +); + pub mod accept; pub use moq_sock::bind; pub mod cli;