diff --git a/doc/lib/rs/index.md b/doc/lib/rs/index.md index 08059e24cea..a92eb3acbd7 100644 --- a/doc/lib/rs/index.md +++ b/doc/lib/rs/index.md @@ -15,7 +15,7 @@ links cover crates awaiting their first release. | --- | --- | | [moq-net](/lib/rs/moq-net) | The pub/sub layer: sessions, origins, broadcasts, tracks, groups, frames. Transport-agnostic. | | [moq-pattern](https://docs.rs/moq-pattern) | Path patterns such as `room/**`. Re-exported by moq-net and moq-auth. | -| [moq-tokio](https://docs.rs/moq-tokio) | Connects and listens over QUIC, WebSocket, or iroh, from config or CLI flags. | +| [moq-tokio](https://docs.rs/moq-tokio) | Connects and listens over QUIC, WebSocket, or iroh, from config or CLI flags. Its `driver` feature alone is a tokio QUIC stack without MoQ. | | [moq-sock](https://docs.rs/moq-sock) | Socket binding and CPU pinning for thread-per-core listeners. | | [moq-ice](https://github.com/moq-dev/moq/tree/main/rs/moq-ice) | The ICE agent behind native WebRTC: drives a str0m connection over UDP, with a STUN client. | | [moq-uring](https://docs.rs/moq-uring) | Experimental Linux io\_uring server for moq-lite. | diff --git a/quest/m1/README.md b/quest/m1/README.md index 87e43e90c9c..563031d3bd3 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -67,7 +67,6 @@ lands before the cut. - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone -- [An async QUIC driver without moq-net](/quest/m1/quic-driver.md) - `moq_tokio::quic::driver` is supported API that builds without moq-net, so other applications can embed moq-quic on tokio - [Lazy discovery](/quest/m1/lazy-discovery/README.md) - a `consume` session requests announcements only for prefixes the origin is watching, in JS then Rust; `follow`, `broadcasts`, and the `discovery` option go away - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [JSON window timestamps](/quest/m1/json-window-timestamps.md) - Rust and JS window consumers return each event's frame timestamp like the snapshot and stream consumers diff --git a/quest/m1/quic-driver.md b/quest/m1/quic-driver.md deleted file mode 100644 index 77a60ab3bf9..00000000000 --- a/quest/m1/quic-driver.md +++ /dev/null @@ -1,90 +0,0 @@ -# [M] An async QUIC driver without moq-net - -## Goal - -An application runs `moq-quic` on tokio without depending on moq-net: -`moq_tokio::quic::driver`'s endpoint, connection, and stream futures, with -send groups, `reset_at`, receive leases, and live `Limits`, become documented -public API that builds without moq-net. Any Rust MoQ implementation, or any -QUIC application, can embed the stack moq-dev ships, instead of forking -quinn's async layer again. - -`cargo tree -e normal` on a driver-only build of moq-tokio -(`--no-default-features`, the driver feature, and a crypto provider) shows no -moq-net, kio, reqwest, or notify, and no crate from quinn, noq, or -moq-dev/web-transport. CI builds that feature set, and the driver's tests stay -in the merge gate. - -## Plan - -Where it stands: - -- The driver is quinn's async layer on moq-quic, kept as moq-tokio modules, - tokio-only (decided 2026-10-06 in the fork epic, over `moq-quic-udp` and - `moq-quic-tokio` crates). The udp half is now `moq_sock::udp`. -- Its only moq-net type is `moq_net::transport::Wire`, a pair of byte - counters (`quic/driver/connection.rs`). `quic/backend.rs` also takes - `moq_net::Versions` for ALPN lists, but sits above the driver. -- moq-net is a required dependency of moq-tokio, even without the `quic` - feature that gates the driver, so a consumer cannot take the driver alone. -- The driver is public but `#[doc(hidden)]`, and is not on `release`. - -Decided 2026-10-20 (maintainer): `moq-quic` powers qmux and WebTransport, -and moq takes no new work in, or dependency on, moq-dev/web-transport, noq -or quinn. The driver is that stack's tokio runtime, beside moq-uring's -driver and the planned in-tree qmux, so this quest moves no code out of the -tree. quinn stays the upstream the fork cherry-picks from, not a dependency. - -Decided 2026-10-20 (maintainer): the driver stays in moq-tokio, at -`moq_tokio::quic::driver`, and moq-net becomes optional there. No new crate -and no feature on moq-quic: the driver keeps its home and its tests, and the -sans-IO core that moq-uring and qmux share gets no runtime. It stays a -`driver` submodule, since `quic::Connection` and `quic::Error` already name -the MoQ backend's types. - -Rejected: a `moq-quic-tokio` crate (a new published crate and a reversal of -the 2026-10-06 decision) and a `tokio` feature on moq-quic (a runtime in the -sans-IO core, and the driver's tests behind a non-default gate). - -The work: - -- The first commit replaces `Wire` with counters owned by the driver. - moq-tokio converts at its boundary, and moq-net's wire stats do not change. -- moq-net moves behind a default feature, which every transport feature also - enables, since none works without it. `web-transport-trait` moves with it: - every user (`transport`, `server`, `tcp`, `quic::web`) is on the moq-net - side. Every moq-net use in moq-tokio, including the `moq_net` re-export, - gets the gate. -- A driver-only feature turns on `quic::driver` alone, and `quic` enables it - plus `quic::backend` and `quic::web`. `quic`'s other dependencies (reqwest, - notify through `watch`, kio, http, web-transport-proto, - rustls-native-certs, dns-lookup) stay on `quic`, so a driver-only build - drops them. Name both features in the implementing PR. -- Out of scope: moq-tokio's unconditional dependencies, which a driver-only - build still pulls through its `cli`, `tls`, and `settings` modules: tokio - `full`, rustls and rustls-platform-verifier, x509-parser, serde, toml, - tracing-subscriber, and usage-rs, plus rcgen and rustls-webpki from the - crypto-provider feature. None is MoQ code; splitting them is its own quest - if an embedder needs it. -- Drop the driver's `#[doc(hidden)]` and its "not a stable API" comment, and - document every exported item. The driver keeps quinn's rustfmt config. -- In-tree consumers with `default-features = false` and no transport feature - that use moq-net-backed modules (moq-room, moq-boy, moq-bench) enable the - new moq-net feature. -- `quic::web` and `quic::backend` keep their features and dependencies here. - [Drop web-transport-trait](/quest/m2/drop-web-transport-trait.md) owns their - API changes, such as `quic::web::Session` dropping its `Deref`, and proceeds - on top. Driver API changes that quest makes, such as aligning the stream - setters with moq-uring's, land in the driver here; neither quest waits on - the other. -- moq-uring's driver is out of scope. It is `!Send`, and coupled to moq-net - through `server::Activity` as well as `Wire`. - -Decided 2026-10-20: m1, because making moq-net optional is a breaking change. -A build with `default-features = false` and no transport feature loses -`client`, `connect`, `connection`, `listen`, `origin`, `transport`, the root -re-exports built on them (`Client`, `Connection`, `Error`, ...), and the -`moq_net` re-export, so it lands before the cut. Add an entry under -`## Unreleased` in `rs/moq-tokio/MIGRATE.md`: enable the new moq-net feature -or a transport feature to keep them. Public API: the two new features, and -`quic::driver` becomes supported. Wire: none. diff --git a/quest/m2/drop-web-transport-trait.md b/quest/m2/drop-web-transport-trait.md index 536cc787fef..210c36ba718 100644 --- a/quest/m2/drop-web-transport-trait.md +++ b/quest/m2/drop-web-transport-trait.md @@ -46,9 +46,8 @@ each gets its own impl: adapters. A native impl can pass them to the open, as moq-tokio's driver `open_uni`/`open_bi` already accept. - moq-tokio's `quic::web` module is public but `#[doc(hidden)]`. Decide - whether it is API or should be private. `quic::driver` stays public: - [An async QUIC driver without moq-net](/quest/m1/quic-driver.md) makes it - supported API. + whether it is API or should be private. `quic::driver` is supported API + and stays public. Notes from related quests: - [qmux on moq-quic](/quest/m1/quic-qmux.md) planned to port qmux's diff --git a/rs/moq-bench/Cargo.toml b/rs/moq-bench/Cargo.toml index 7239d2ddcb2..c5db0c8f8ab 100644 --- a/rs/moq-bench/Cargo.toml +++ b/rs/moq-bench/Cargo.toml @@ -45,7 +45,7 @@ websocket = ["moq-tokio/websocket"] anyhow = { workspace = true, features = ["backtrace"] } humantime = { workspace = true } moq-net = { workspace = true } -moq-tokio = { workspace = true, default-features = false, features = ["aws-lc-rs"] } +moq-tokio = { workspace = true, default-features = false, features = ["aws-lc-rs", "net"] } rand = { workspace = true } serde = { workspace = true } serde_json = { workspace = true } diff --git a/rs/moq-boy/Cargo.toml b/rs/moq-boy/Cargo.toml index 3ae442fc20f..905680aee84 100644 --- a/rs/moq-boy/Cargo.toml +++ b/rs/moq-boy/Cargo.toml @@ -32,7 +32,7 @@ moq-audio = { workspace = true } moq-json = { workspace = true } moq-mux = { workspace = true } moq-net = { workspace = true } -moq-tokio = { workspace = true, default-features = false, features = ["aws-lc-rs"] } +moq-tokio = { workspace = true, default-features = false, features = ["aws-lc-rs", "net"] } # Select the Linux NVIDIA and VAAPI codecs explicitly; software H.264 is the # `openh264` feature. moq-video = { workspace = true, features = ["nvidia", "vaapi"] } diff --git a/rs/moq-room/Cargo.toml b/rs/moq-room/Cargo.toml index 0bcd19bd096..96f1f8bec74 100644 --- a/rs/moq-room/Cargo.toml +++ b/rs/moq-room/Cargo.toml @@ -21,5 +21,5 @@ moq-net = { workspace = true } thiserror = { workspace = true } [dev-dependencies] -moq-tokio = { path = "../moq-tokio", default-features = false } +moq-tokio = { path = "../moq-tokio", default-features = false, features = ["net"] } tokio = { workspace = true, features = ["macros", "rt", "test-util"] } diff --git a/rs/moq-rtc/Cargo.toml b/rs/moq-rtc/Cargo.toml index cd79d6ef3cf..1781b59523c 100644 --- a/rs/moq-rtc/Cargo.toml +++ b/rs/moq-rtc/Cargo.toml @@ -44,5 +44,7 @@ uuid = { version = "1", features = ["v4"] } # Signs the MESSAGE-INTEGRITY on a forged STUN binding request: str0m rejects a # request without one, and its own SHA1 provider is private. aws-lc-rs = { workspace = true } +# The tests host their broadcasts on `origin::spawn`. +moq-tokio = { workspace = true, features = ["net"] } tokio = { workspace = true, features = ["test-util"] } tracing-test = { workspace = true } diff --git a/rs/moq-rtmp/Cargo.toml b/rs/moq-rtmp/Cargo.toml index 21b1416b9ff..7833507e4c3 100644 --- a/rs/moq-rtmp/Cargo.toml +++ b/rs/moq-rtmp/Cargo.toml @@ -60,7 +60,7 @@ moq-clock = { path = "../moq-clock", features = ["sim"] } # `rustls::ServerConfig`. No transport feature: a QUIC backend here would be # unified into every other crate a `--workspace` build selects, which is exactly # what hid moq-tokio's backend-less build from the nightly feature matrix. -moq-tokio = { path = "../moq-tokio", default-features = false, features = ["aws-lc-rs"] } +moq-tokio = { path = "../moq-tokio", default-features = false, features = ["aws-lc-rs", "net"] } tokio = { workspace = true, features = ["test-util"] } tracing-test = { workspace = true, features = ["no-env-filter"] } diff --git a/rs/moq-tokio/Cargo.toml b/rs/moq-tokio/Cargo.toml index 8da1476538e..add6f0610a2 100644 --- a/rs/moq-tokio/Cargo.toml +++ b/rs/moq-tokio/Cargo.toml @@ -13,18 +13,21 @@ keywords = ["quic", "http3", "webtransport", "media", "live"] categories = ["multimedia", "network-programming", "web-programming"] [features] -default = ["quic", "aws-lc-rs", "websocket", "tcp", "uds"] +default = ["net", "quic", "aws-lc-rs", "websocket", "tcp", "uds"] +# MoQ sessions over moq-net: `Client`, `Server`, `origin`, and the `connect`, `listen`, +# and `transport` modules. Every transport feature turns it on, since none works without it. +net = ["dep:moq-net", "dep:web-transport-trait"] +# The async QUIC driver alone (`quic::driver`): moq-quic on tokio, without moq-net or +# the MoQ backend. Needs a crypto-provider feature. +driver = ["dep:moq-quic", "dep:pin-project-lite", "dep:rustc-hash", "dep:socket2"] # QUIC and WebTransport over moq-quic, for `https://`, `moqt://`, and `moql://`. quic = [ "_transport", "_certs", - "dep:moq-quic", + "driver", "dep:http", "dep:kio", - "dep:pin-project-lite", - "dep:rustc-hash", "dep:rustls-native-certs", - "dep:socket2", "dep:web-transport-proto", "dep:reqwest", "watch", @@ -38,7 +41,7 @@ quic = [ _certs = ["dep:rcgen", "dep:rustls-webpki"] # Private "any transport is compiled" marker. Not one to enable on its own: every # backend that can move bytes turns it on, and `uds` reaches it through `tcp`. -_transport = [] +_transport = ["net"] # Filesystem watcher for hot-reloading on-disk TLS certs, keys, and root CAs. watch = ["dep:notify"] # Capture qlog traces (`--*-quic-qlog `). Off by default so production @@ -80,8 +83,8 @@ mdns-sd = { workspace = true, optional = true } moq-clock = { workspace = true } # The ICE agent behind the `webrtc` module. Private, like str0m: neither appears in this crate's API. moq-ice = { workspace = true, optional = true } -moq-net = { workspace = true } -# The QUIC state machine the `quic` module drives; the crypto-provider features pick its provider. +moq-net = { workspace = true, optional = true } +# The QUIC state machine `quic::driver` drives; the crypto-provider features pick its provider. moq-quic = { workspace = true, features = ["bloom"], optional = true } moq-sock = { workspace = true } # iroh runs on upstream noq rather than moq-quic, and re-exports only the @@ -119,7 +122,7 @@ url = { version = "2", features = ["serde"] } usage-rs = { workspace = true, features = ["config"] } web-transport-iroh = { workspace = true, optional = true } web-transport-proto = { workspace = true, optional = true } -web-transport-trait = { workspace = true } +web-transport-trait = { workspace = true, optional = true } x509-parser = { workspace = true } [target.'cfg(target_os = "android")'.dependencies] @@ -159,3 +162,17 @@ tokio = { workspace = true, features = ["test-util"] } tokio-rustls = { workspace = true } toml = "1.1" tracing-test = { workspace = true, features = ["no-env-filter"] } + +# The examples and integration tests run MoQ sessions, which a driver-only build lacks. +[[example]] +name = "chat" +required-features = ["net"] + +[[example]] +name = "clock" +required-features = ["net"] + +[[test]] +name = "integration" +path = "tests/integration/main.rs" +required-features = ["net"] diff --git a/rs/moq-tokio/MIGRATE.md b/rs/moq-tokio/MIGRATE.md index 6e82bd99cd4..27b42b1ce42 100644 --- a/rs/moq-tokio/MIGRATE.md +++ b/rs/moq-tokio/MIGRATE.md @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first. ## Unreleased +### MoQ sessions need the `net` feature (#6132) + +moq-net is optional, behind the default `net` feature that every transport feature (`quic`, `websocket`, `tcp`, `uds`, `iroh`, `webrtc`) turns on. +A build with `default-features = false` and no transport feature loses `client`, `connect`, `connection`, `listen`, `origin`, `transport`, their root re-exports (`Client`, `Connection`, `ConnectError`, `Transport`, ...), `Error::MoqNet`, `Error::Connect`, `Error::connect_error`, `Error::is_auth`, and the `moq_net` re-export. +Enable `net`, or a transport feature, to keep them. + ### `mdns::Secret` is `secret::Secret`, read from a file (#5910) The 32-byte secret type moved out of `mdns` so `listen.reset.secret` shares it, and it no longer parses inline hex. diff --git a/rs/moq-tokio/src/error.rs b/rs/moq-tokio/src/error.rs index feb4ef8c3d1..ae2a5003690 100644 --- a/rs/moq-tokio/src/error.rs +++ b/rs/moq-tokio/src/error.rs @@ -42,6 +42,7 @@ pub(crate) use from_message; /// A response that arrived is the server's answer, and only this narrow set invites another /// attempt: request timeout, rate limit, and the gateway/overload statuses. Every other status, /// `404` and `403` included, is settled. +#[cfg(feature = "net")] pub(crate) fn status_retryable(status: u16) -> bool { matches!(status, 408 | 429 | 502 | 503 | 504) } @@ -68,6 +69,7 @@ pub enum Error { Io(Arc), /// The MoQ session itself failed, after the transport was established. + #[cfg(feature = "net")] #[error(transparent)] MoqNet(#[from] moq_net::Error), @@ -128,6 +130,7 @@ pub enum Error { ConnectTimeout(std::time::Duration), /// The server rejected the connection with an auth status. See [`crate::ConnectError`]. + #[cfg(feature = "net")] #[error(transparent)] Connect(#[from] crate::ConnectError), @@ -247,6 +250,7 @@ pub enum Error { impl Error { /// A fixed local error or settled rejection that another dial cannot repair. + #[cfg(feature = "net")] pub(crate) fn is_terminal(&self) -> bool { match self { #[cfg(feature = "websocket")] @@ -295,6 +299,7 @@ impl Error { } /// The auth rejection behind this error, digging through backend and race variants. + #[cfg(feature = "net")] pub fn connect_error(&self) -> Option { match self { Self::Connect(err) => Some(*err), @@ -312,6 +317,7 @@ impl Error { } /// True if the server rejected us for auth reasons, so retrying won't help without new credentials. + #[cfg(feature = "net")] pub fn is_auth(&self) -> bool { // Expiry has no HTTP status, so it has no `ConnectError` to report. matches!(self, Self::MoqNet(err) if moq_net::SessionError::from(err) == moq_net::SessionError::Expired) diff --git a/rs/moq-tokio/src/lib.rs b/rs/moq-tokio/src/lib.rs index 2910e76dc83..e85c43c01b5 100644 --- a/rs/moq-tokio/src/lib.rs +++ b/rs/moq-tokio/src/lib.rs @@ -18,20 +18,28 @@ //! anything, though a crypto provider on its own is still enough to configure TLS //! and to build a plain-TLS listener's `rustls::ServerConfig` from //! [`tls::Listen::server_config`]. +//! +//! MoQ sessions need the `net` feature, which every transport turns on. Without +//! it, `driver` and a crypto provider build [`quic::driver`] alone: an async +//! QUIC stack for any application, MoQ or not. #![warn(missing_docs)] // The protocol crates need a compiled provider for reset and retry-token keys. A rustls provider // installed at runtime cannot supply constructors removed by their compile-time feature gates. -#[cfg(all(feature = "quic", not(any(feature = "aws-lc-rs", feature = "ring"))))] +#[cfg(all(feature = "driver", not(any(feature = "aws-lc-rs", feature = "ring"))))] compile_error!("a rustls QUIC backend requires a crypto provider: enable either the `aws-lc-rs` or `ring` feature"); +#[cfg(any(feature = "net", all(feature = "watch", feature = "_certs")))] mod abort; pub mod accept; pub use moq_sock::bind; pub mod cli; +#[cfg(feature = "net")] pub mod client; +#[cfg(feature = "net")] pub mod connect; +#[cfg(feature = "net")] pub mod connection; pub mod crypto; mod error; @@ -39,8 +47,10 @@ mod error; pub mod failover; #[cfg(feature = "jemalloc")] pub mod jemalloc; +#[cfg(feature = "net")] pub mod listen; mod log; +#[cfg(feature = "net")] pub mod origin; pub mod panic; pub mod quic; @@ -54,6 +64,7 @@ pub mod settings; #[cfg(feature = "tcp")] pub mod tcp; pub mod tls; +#[cfg(feature = "net")] pub mod transport; #[cfg(all(feature = "uds", unix))] pub mod unix; @@ -84,16 +95,21 @@ fn qmux_config() -> qmux::Config { // Enumerated rather than globbed, so the root surface is a deliberate list and a // new `pub` item in these modules doesn't silently join it. +#[cfg(feature = "net")] pub use client::Client; +#[cfg(feature = "net")] pub use connect::{Addrs, ConnectError}; +#[cfg(feature = "net")] pub use connection::{Backoff, Connection, Redirect, Status}; pub use error::{Error, Result}; pub use log::{Log, RedactedUrl}; #[cfg(feature = "_transport")] pub use server::{Listener, Server}; +#[cfg(feature = "net")] pub use transport::Transport; // Re-export these crates. +#[cfg(feature = "net")] pub use moq_net; pub use rustls; diff --git a/rs/moq-tokio/src/quic.rs b/rs/moq-tokio/src/quic.rs index f774b7845fd..f31ebdeb1a9 100644 --- a/rs/moq-tokio/src/quic.rs +++ b/rs/moq-tokio/src/quic.rs @@ -20,16 +20,13 @@ mod backend; pub(crate) use backend::{Client, Closer, Options, Server, accept}; #[cfg(feature = "quic")] pub use backend::{Connection, Error}; -/// The flow-control limits a live QUIC connection can change; see [`Connection::set_limits`]. -#[cfg(feature = "quic")] +/// The flow-control limits a live QUIC connection can change; see [`driver::Connection::set_limits`]. +#[cfg(feature = "driver")] pub use moq_quic::{Limits, LimitsError}; -// The async QUIC layer driving `moq-quic` on tokio, forked from quinn (see its module docs). -// Public only so the workspace's tests can dial a bare endpoint; not a stable API. // cargo fmt formats submodules with the crate root's config, so `just rs fix` // formats this one separately with its own (quinn's). -#[cfg(feature = "quic")] -#[doc(hidden)] +#[cfg(feature = "driver")] #[rustfmt::skip] pub mod driver; diff --git a/rs/moq-tokio/src/quic/driver/connection.rs b/rs/moq-tokio/src/quic/driver/connection.rs index 6913eb8382e..5ceccbb4d35 100644 --- a/rs/moq-tokio/src/quic/driver/connection.rs +++ b/rs/moq-tokio/src/quic/driver/connection.rs @@ -193,8 +193,8 @@ impl Connecting { /// the endpoint is bound to a wildcard address like `0.0.0.0` or `::`. /// /// This will return `None` for clients, or when the platform does not expose this - /// information. See [`quinn_udp::RecvMeta::dst_ip`](moq_sock::udp::RecvMeta::dst_ip) for a list of - /// supported platforms when using [`quinn_udp`](udp) for I/O, which is the default. + /// information. See [`moq_sock::udp::RecvMeta::dst_ip`] for a list of + /// supported platforms when using [`moq_sock::udp`] for I/O, which is the default. /// /// Will panic if called after `poll` has returned `Ready`. pub fn local_ip(&self) -> Option { @@ -284,9 +284,12 @@ impl Future for ConnectionDriver { conn.forward_app_events(&self.conn.shared); // Every datagram sent or received passes through this poll. - let stats = conn.inner.stats(); - self.conn.shared.wire.set_sent_bytes(stats.udp_tx.bytes); - self.conn.shared.wire.set_received_bytes(stats.udp_rx.bytes); + #[cfg(feature = "net")] + { + let stats = conn.inner.stats(); + self.conn.shared.wire.set_sent_bytes(stats.udp_tx.bytes); + self.conn.shared.wire.set_received_bytes(stats.udp_rx.bytes); + } if !conn.inner.is_drained() { if keep_going { @@ -618,8 +621,8 @@ impl Connection { /// the endpoint is bound to a wildcard address like `0.0.0.0` or `::`. /// /// This will return `None` for clients, or when the platform does not expose this - /// information. See [`quinn_udp::RecvMeta::dst_ip`](moq_sock::udp::RecvMeta::dst_ip) for a list of - /// supported platforms when using [`quinn_udp`](udp) for I/O, which is the default. + /// information. See [`moq_sock::udp::RecvMeta::dst_ip`] for a list of + /// supported platforms when using [`moq_sock::udp`] for I/O, which is the default. pub fn local_ip(&self) -> Option { self.0.state.lock("local_ip").inner.local_ip() } @@ -640,6 +643,7 @@ impl Connection { } /// The wire counters the driver updates as it sends and receives. + #[cfg(feature = "net")] pub(crate) fn wire(&self) -> moq_net::transport::Wire { self.0.shared.wire.clone() } @@ -1069,6 +1073,9 @@ pub(crate) struct Shared { /// Number of live handles that can used to initiate or handle I/O; excludes the driver ref_count: AtomicUsize, /// Refreshed by every driver poll, so readers never wake the driver to sample. + /// + /// Only moq-net reads them, so a driver-only build skips the per-poll stats. + #[cfg(feature = "net")] wire: moq_net::transport::Wire, } diff --git a/rs/moq-tokio/src/quic/driver/mod.rs b/rs/moq-tokio/src/quic/driver/mod.rs index 5acc2455104..a0fb8d6781c 100644 --- a/rs/moq-tokio/src/quic/driver/mod.rs +++ b/rs/moq-tokio/src/quic/driver/mod.rs @@ -1,12 +1,16 @@ -//! QUIC transport protocol implementation +//! An async QUIC driver: [`moq_quic`]'s state machine on tokio sockets and timers. +//! +//! Its API mirrors quinn's, plus what moq-quic adds: +//! [`SendGroup`]s that schedule streams and datagrams together, [`SendStream::reset_at`] to +//! keep a prefix reliable, [`RecvStream::read_held`] to hold receive credit until a message is +//! complete, and [`Connection::set_limits`] to change flow control on a live connection. +//! +//! It needs no MoQ session: enable the `driver` feature (with `aws-lc-rs` or `ring`) and +//! `default-features = false` to build it without moq-net. The entry point is the [`Endpoint`]. //! //! [QUIC](https://en.wikipedia.org/wiki/QUIC) is a modern transport protocol addressing //! shortcomings of TCP, such as head-of-line blocking, poor security, slow handshakes, and -//! inefficient congestion control. This crate provides a portable userspace implementation. It -//! builds on top of quinn-proto, which implements protocol logic independent of any particular -//! runtime. -//! -//! The entry point of this crate is the [`Endpoint`]. +//! inefficient congestion control. //! //! # About QUIC //! @@ -29,7 +33,7 @@ //! multiple TCP connections between the same two hosts, while providing more useful behavior than //! raw UDP sockets. //! -//! Quinn also exposes unreliable datagrams, which are a low-level primitive preferred when +//! The driver also exposes unreliable datagrams, which are a low-level primitive preferred when //! automatic fragmentation and retransmission of certain data is not desired. //! //! QUIC uses encryption and identity verification built directly on TLS 1.3. Just as with a TLS @@ -76,8 +80,9 @@ pub use crate::quic::driver::incoming::{Incoming, IncomingFuture, RetryError}; pub use crate::quic::driver::recv_stream::{ Credit, ReadError, ReadExactError, ReadToEndError, RecvStream, ResetError, }; +#[cfg(feature = "quic")] pub(crate) use crate::quic::driver::runtime::send_failed; -#[cfg(test)] +#[cfg(all(test, feature = "quic"))] pub(crate) use crate::quic::driver::runtime::wrap_udp_socket; pub use crate::quic::driver::runtime::{AsyncUdpSocket, UdpSender}; pub use crate::quic::driver::send_group::{SendGroup, SendOptions}; diff --git a/rs/moq-tokio/src/quic/driver/send_stream.rs b/rs/moq-tokio/src/quic/driver/send_stream.rs index 7e09c65b47e..9fb64e16a19 100644 --- a/rs/moq-tokio/src/quic/driver/send_stream.rs +++ b/rs/moq-tokio/src/quic/driver/send_stream.rs @@ -320,6 +320,7 @@ impl SendStream { } /// Reset at `offset` with `code`, instead of at 0 with code 0, if dropped before `finish` + #[cfg(feature = "quic")] pub(crate) fn set_drop_reset(&mut self, offset: u64, code: VarInt) { self.drop_reset = (offset, code); } diff --git a/rs/moq-tokio/src/tls.rs b/rs/moq-tokio/src/tls.rs index f896dcf0486..976b53b58e8 100644 --- a/rs/moq-tokio/src/tls.rs +++ b/rs/moq-tokio/src/tls.rs @@ -172,6 +172,7 @@ pub enum Error { impl Error { /// A configuration no retry can fix, unlike a certificate file read mid-rotation. + #[cfg(feature = "net")] pub(crate) fn is_terminal(&self) -> bool { !matches!( self, diff --git a/sh/rs/tokio-features.sh b/sh/rs/tokio-features.sh index 9bbb5cc363e..44c60af47c7 100755 --- a/sh/rs/tokio-features.sh +++ b/sh/rs/tokio-features.sh @@ -1,7 +1,8 @@ #!/usr/bin/env bash -# Compile moq-tokio by itself at the feature extremes; --all also isolates each -# crypto and transport permutation. The default-feature build is already in the -# ordinary gate, which can hide missing feature gates through unification. +# Compile moq-tokio by itself at the feature extremes and as a bare QUIC driver; +# --all also isolates each crypto and transport permutation. The default-feature +# build is already in the ordinary gate, which can hide missing feature gates +# through unification. set -euo pipefail all=0 @@ -16,13 +17,24 @@ cd "$(git rev-parse --show-toplevel)" cargo clippy --locked -p moq-tokio --no-default-features -- -D warnings cargo clippy --locked -p moq-tokio --all-features -- -D warnings + +# The QUIC driver is public API for applications without a MoQ session, so its +# build must not reach moq-net, the MoQ backend's dependencies, or another QUIC stack. +driver=(--no-default-features --features "driver,aws-lc-rs") +cargo clippy --locked -p moq-tokio --all-targets "${driver[@]}" -- -D warnings +graph=$(cargo tree --locked -p moq-tokio -e normal --prefix none "${driver[@]}") +if leaked=$(grep -E '^(moq-net|reqwest|notify|quinn[a-z-]*|noq[a-z-]*|web-transport[a-z-]*) ' <<<"$graph"); then + echo "rs: moq-tokio's driver build must not depend on:" >&2 + sort -u <<<"$leaked" >&2 + exit 1 +fi # Only a feature-owner edit needs every isolated permutation on a PR. Shared # dependencies still compile at both extremes; Nightly runs every permutation. if ((all)); then cargo clippy --locked -p moq-tokio --no-default-features --features quic,aws-lc-rs -- -D warnings cargo clippy --locked -p moq-tokio --no-default-features --features quic,ring -- -D warnings - for feature in aws-lc-rs ring tcp uds websocket webrtc; do + for feature in net aws-lc-rs ring tcp uds websocket webrtc; do cargo clippy --locked -p moq-tokio --no-default-features --features "$feature" -- -D warnings done fi