diff --git a/PACKAGE-SELECTION.md b/PACKAGE-SELECTION.md new file mode 100644 index 00000000..706572cb --- /dev/null +++ b/PACKAGE-SELECTION.md @@ -0,0 +1,134 @@ +# Choosing a package and backend + +Start with the API boundary your application needs, then choose a transport. +The `web-transport` crate selects Quinn on native targets and the browser API on +non-WASI `wasm32` targets. Other native backends and QMux are separate packages; selecting them means +using their APIs directly or writing against `web-transport-trait`. + +This guide describes the code in this checkout. The external comparison was +checked on 2026-11-07 against [wtransport 0.7.2][wt-manifest] and its public +reference documentation. Recheck the linked sources when changing versions. +The browser WASM paths below exclude WASI: the [router source][router-code] also +selects Quinn for WASI, whose build support is unverified here. +**Unsupported** means the cited API excludes a capability. **Unverified** means +these sources do not establish support; it does not mean the capability is +impossible or absent from every related project. + +## Choose the Rust API boundary + +| Package | Use it when | Boundary | +| --- | --- | --- | +| [`web-transport`](rs/web-transport) | You want one concrete client/session API for native Rust and browser WASM. | The [platform router][router-code] fixes the implementation at compile time. Configured native clients and servers come from Quinn, with conversions into the router's types. There is no browser server API. | +| [`web-transport-trait`](rs/web-transport-trait) | Your application should accept different session implementations. | The [async session/stream traits][traits-code] cover streams, datagrams, closure and metadata. They do not create endpoints or choose a backend. The [conditional bounds][trait-bounds] require `Send`/`Sync` outside `target_family = "wasm"` and relax them within that family, including WASI. | +| A native backend below | You need backend configuration or access to its connection and stream types. | Endpoint, TLS and runtime integration remain backend-specific. A shared trait does not make their builders interchangeable. | +| [`qmux`](rs/qmux) | You need the session abstraction over an ordered byte transport such as TCP, TLS or WebSocket. | Implements the async traits using QMux framing, with its own setup and wire protocol. Being retired; see [When to use QMux](#when-to-use-qmux). | +| [`web-transport-proto`](rs/web-transport-proto) | You are implementing protocol integration inside a backend. | Shared HTTP/3/WebTransport framing; it is not an application client or server. | + +The async traits are implemented by Quinn, Noq, Quiche, iroh and QMux, and by +[the WASM adapter on WASM targets][wasm-traits]. The separate +[`poll` traits][poll-traits] serve callers that drive operations explicitly; +check each backend's implementations before depending on that surface. + +## Choose a native backend + +All four native backends expose client/server setup, bidirectional and +unidirectional streams, and datagram send/receive APIs. Choose based on the +networking stack you need to integrate, rather than assuming one is faster. + +| Package | Integration surface | Where to start | +| --- | --- | --- | +| [`web-transport-quinn`](rs/web-transport-quinn) | Quinn endpoints, connections and streams. `Client::new`/`Server::new` accept configured Quinn objects; `Session::connect` and `Request::accept` work with an established connection. | [Client](rs/web-transport-quinn/src/client.rs), [server](rs/web-transport-quinn/src/server.rs), [session](rs/web-transport-quinn/src/session.rs), [examples](rs/web-transport-quinn/examples). The package README describes runtime selection and the hostname-resolution caveat outside Tokio. | +| [`web-transport-noq`](rs/web-transport-noq) | The corresponding Noq endpoint/connection API, using the Noq fork of Quinn. Choose it for an application already integrating Noq. | [Client](rs/web-transport-noq/src/client.rs), [server](rs/web-transport-noq/src/server.rs), [session](rs/web-transport-noq/src/session.rs), [examples](rs/web-transport-noq/examples). | +| [`web-transport-quiche`](rs/web-transport-quiche) | Quiche through `tokio-quiche` and the crate's `ez` layer. Builders accept sockets/settings; server integration also accepts a `tokio_quiche` listener and certificate resolver. | [Client](rs/web-transport-quiche/src/client.rs), [server](rs/web-transport-quiche/src/server.rs), [connection](rs/web-transport-quiche/src/connection.rs), [examples](rs/web-transport-quiche/examples). This is a Tokio integration, not a direct sans-I/O Quiche adapter. | +| [`web-transport-iroh`](rs/web-transport-iroh) | iroh connections in two modes: WebTransport over HTTP/3 (`Client::connect_h3`, `H3Request::accept`), or raw QUIC (`Client::connect_quic`, `QuicRequest::accept`, `Session::raw`) with the same session API but no HTTP/3 handshake. Raw sessions are not WebTransport-over-HTTP/3, so pick the mode your peer speaks. | [Client](rs/web-transport-iroh/src/client.rs), [server](rs/web-transport-iroh/src/server.rs), [session](rs/web-transport-iroh/src/session.rs). Verify browser reachability separately for an iroh deployment. | + +The native HTTP/3 implementations use one WebTransport session per QUIC +connection. General HTTP/3 serving and multiple WebTransport sessions pooled on +one connection are unsupported by this design; see the +[Quinn](rs/web-transport-quinn/src/lib.rs), +[Noq](rs/web-transport-noq/src/lib.rs), +[Quiche](rs/web-transport-quiche/src/lib.rs) and +[iroh](rs/web-transport-iroh/src/lib.rs) limitations. Use a stack with HTTP/3 +request routing if your application needs to share that connection with other +HTTP traffic. + +### When to use QMux + +[QMux](rs/qmux/README.md) provides multiplexed streams and datagrams over TCP, +Unix domain sockets, TLS and WebSockets, with feature-specific entry points. +It also accepts an application-provided transport. Use it when the peer speaks +QMux, including a WebSocket path for networks that block UDP. Your application +chooses that path; the Rust router does not automatically fall back to QMux. + +QMux is a separate wire protocol from WebTransport over HTTP/3. Both ends must +agree on the QMux version and application protocol. Datagrams carried over a +reliable ordered connection still share its retransmission and head-of-line +blocking behavior; they do not acquire QUIC's independent packet delivery. +See the [QMux draft][qmux-draft] and the package's negotiation documentation. + +The QMux packages here, [`qmux`](rs/qmux) and [`@moq/qmux`](js/qmux), receive +bug fixes only and will be retired in favour of the copy in +[moq-dev/moq][moq-qmux]. That copy implements moq-net's traits rather than +`web-transport-trait`; read its [migration guide][moq-qmux-migrate] before +starting a new QMux integration. + +## Browser and language packages + +| Environment | Package | Integration surface | +| --- | --- | --- | +| Rust in a browser | [`web-transport-wasm`](rs/web-transport-wasm), or the router | Wraps the browser's WebTransport API through `web-sys`; client only. The browser owns networking and TLS policy. Build with the [required unstable web-sys flags](rs/web-transport-wasm/README.md#requirements). | +| JavaScript in a browser | The browser's [WebTransport API][browser-api] | A browser client can connect to a native HTTP/3 WebTransport server. Browser interoperability does not require compiling the native server library to WASM. Check the target browser's support for the APIs you use. | +| Node.js | [`@moq/web-transport`](js/web-transport) | Custom client/server setup, followed by a WebTransport-shaped Web Streams/datagram/session API. Uses the [Quinn-backed NAPI-RS bridge](rs/web-transport-node/Cargo.toml), not the browser's network stack. | +| JavaScript over WebSocket | [`@moq/qmux`](js/qmux) | A browser polyfill plus server-side sessions over an accepted WebSocket. The host performs the HTTP upgrade and negotiates the subprotocol. Requires a QMux-compatible peer. Being retired; see [When to use QMux](#when-to-use-qmux). | +| Python | [`web-transport-rs`](py/web-transport) | Typed `asyncio` wrapper over UniFFI, with native client/server, streams and datagrams. | +| Kotlin / Android | [`dev.moq:web-transport`](kt) | UniFFI bindings packaged for JVM and Android. See its README for artifact and target requirements. | +| Swift | [`WebTransport`](swift) | Swift wrapper and generated UniFFI bindings, distributed through release archives. See its README for the supported installation path. | + +Python, Kotlin and Swift share the [Quinn-backed `web-transport-ffi` core](rs/web-transport-ffi). +These packages do not select among the Rust backends or use QMux. Follow each +language's owning README for its available wrapper API, installation and examples; +a Rust method is not automatically available through every wrapper. + +[`@moq/web-socket-stream`](js/web-socket-stream) is a lower-level WebSocket-to-Web +Streams adapter used by the JavaScript QMux package. It does not add multiplexed +streams or implement WebTransport by itself. + +## Compared with wtransport + +[wtransport][wt-readme] is another Rust WebTransport implementation. Its native +client and server use Quinn with Tokio, as shown by its [manifest][wt-manifest]. +For a native Quinn application, both projects offer streams and datagrams; +compare the setup and ownership APIs your application will actually use. + +| Capability | This workspace | wtransport 0.7.2 | +| --- | --- | --- | +| Native backend choice | Quinn, Noq, Quiche/Tokio and iroh packages, as linked above. The router uses Quinn. | Quinn/Tokio is verified. An alternative backend is unverified in the cited manifest and docs. | +| Browser interoperability | Native HTTP/3 servers plus the browser API; a dedicated Rust/WASM adapter is also provided. | The [browser integration guide][wt-browser] demonstrates JavaScript's native WebTransport connecting to a Rust server. A Rust adapter wrapping the browser API is unverified. | +| Streams | Native session APIs and the shared traits open/accept uni- and bidirectional streams, with read/write, finish, reset/stop and priority operations. The router offers a smaller concrete surface. | [`Connection`][wt-connection] opens/accepts both directions. [`SendStream`][wt-send] and [`RecvStream`][wt-recv] provide read/write, finish, reset/stop and Tokio I/O traits; send priority is exposed. | +| Datagrams | The native backends, router, WASM adapter and language wrappers expose send/receive operations; payload limits and async signatures depend on the surface. | [`Connection`][wt-connection] exposes `send_datagram`, `receive_datagram` and `max_datagram_size`. | +| Native configuration and underlying QUIC access | Use a backend directly for its endpoint/configuration and connection access; the router and bindings expose narrower APIs. | [Configuration builders][wt-config] expose TLS and transport settings. The [`quinn` feature][wt-manifest] exposes underlying Quinn configuration, connection and stream access. | +| Language bindings | Node.js through NAPI-RS; Python, Kotlin and Swift through UniFFI. | The [README][wt-readme] links external Elixir bindings. Support for the four languages listed here is unverified from those sources. | +| QMux / WebSocket transport | Separate Rust and JavaScript QMux packages, with explicit peer negotiation. | QMux integration is unverified in the cited README and manifest. | + +The APIs are not drop-in replacements. For example, wtransport's stream-opening +operations return an opening future after the first await; its +[connection reference][wt-connection] explains both stages. Use each package's +own reference and examples for cancellation, ownership, errors and configuration. +No performance, reliability or production-readiness ranking is established here. + +[router-code]: rs/web-transport/src/lib.rs +[traits-code]: rs/web-transport-trait/src/lib.rs +[trait-bounds]: rs/web-transport-trait/src/util.rs +[poll-traits]: rs/web-transport-trait/src/poll.rs +[wasm-traits]: rs/web-transport-wasm/src/traits.rs +[qmux-draft]: https://www.ietf.org/archive/id/draft-ietf-quic-qmux-02.html +[moq-qmux]: https://github.com/moq-dev/moq/tree/main/rs/qmux +[moq-qmux-migrate]: https://github.com/moq-dev/moq/blob/main/rs/qmux/MIGRATE.md +[browser-api]: https://www.w3.org/TR/webtransport/ +[wt-manifest]: https://github.com/BiagioFesta/wtransport/blob/0.7.2/wtransport/Cargo.toml +[wt-readme]: https://github.com/BiagioFesta/wtransport/blob/0.7.2/README.md +[wt-browser]: https://github.com/BiagioFesta/wtransport/blob/0.7.2/README.md#browser-integration +[wt-connection]: https://docs.rs/wtransport/0.7.2/wtransport/connection/struct.Connection.html +[wt-config]: https://docs.rs/wtransport/0.7.2/wtransport/config/index.html +[wt-send]: https://docs.rs/wtransport/0.7.2/wtransport/stream/struct.SendStream.html +[wt-recv]: https://docs.rs/wtransport/0.7.2/wtransport/stream/struct.RecvStream.html diff --git a/README.md b/README.md index d975ad93..238a78b5 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ QUIC datagrams are unordered, unreliable, and not flow-controlled. Both endpoints can send datagrams below the MTU size (~1.2kb minimum) and they might arrive out of order or not at all. They are basically UDP packets, except they are encrypted and congestion controlled. +For package and backend choices, including a comparison with wtransport, see the +[selection guide](PACKAGE-SELECTION.md). + # Crates The Rust workspace contains these crates under [`rs/`](rs/): diff --git a/js/qmux/README.md b/js/qmux/README.md index 32b409df..777dfedb 100644 --- a/js/qmux/README.md +++ b/js/qmux/README.md @@ -4,6 +4,8 @@ A [WebTransport](https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_A QMux brings QUIC's multiplexed streams and flow control to reliable, ordered byte-stream transports like WebSockets. This allows WebTransport applications to seamlessly fall back when QUIC/UDP is blocked by network middleboxes. +See the [package and backend selection guide](https://github.com/moq-dev/web-transport/blob/main/PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Install ```bash diff --git a/js/web-transport/README.md b/js/web-transport/README.md index 61a5b1df..a22bc35d 100644 --- a/js/web-transport/README.md +++ b/js/web-transport/README.md @@ -4,6 +4,8 @@ WebTransport for Node.js, powered by native QUIC/HTTP3 via NAPI-RS. Provides a custom client and server API for setup, then exposes the standard [W3C WebTransport API](https://www.w3.org/TR/webtransport/) for streams, datagrams, and session lifecycle. +See the [package and backend selection guide](https://github.com/moq-dev/web-transport/blob/main/PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Installation ```bash diff --git a/kt/README.md b/kt/README.md index d6bab805..a524942e 100644 --- a/kt/README.md +++ b/kt/README.md @@ -4,6 +4,8 @@ Kotlin/Android bindings for [web-transport-ffi](../rs/web-transport-ffi) via [Un Single Kotlin Multiplatform module that publishes `dev.moq:web-transport` with both JVM and Android variants under one coordinate. Consumers add `dev.moq:web-transport:VERSION` and Gradle metadata resolution picks the right artifact for their target. +See the [package and backend selection guide](../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Install ```kotlin diff --git a/py/web-transport/README.md b/py/web-transport/README.md index 7907ebe4..19848ef7 100644 --- a/py/web-transport/README.md +++ b/py/web-transport/README.md @@ -5,6 +5,8 @@ Python bindings for [web-transport-quinn](https://docs.rs/web-transport-quinn/) — a pure-Rust WebTransport library built on QUIC. +See the [package and backend selection guide](https://github.com/moq-dev/web-transport/blob/main/PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Features - **Server and client** — one session per connection, no HTTP/3 pooling complexity diff --git a/quest/README.md b/quest/README.md index 4b87840b..c1c37dfa 100644 --- a/quest/README.md +++ b/quest/README.md @@ -10,7 +10,7 @@ Keep living development plans under `quest/`, ordered by priority horizon. Each The initial backlog prioritizes safety and regression foundations, then binding coverage/configuration/documentation, then optional metrics and measured optimization. External conditions remain visible as ready quests rather than hidden blockers. Existing PRs retain ownership of their implementation work. -Use `quest guide` for the format and workflow, `quest ready` for actionable work, and `quest check` after editing the tree. Plan with `$quest-plan` or `/quest-plan`; import issues with `$quest-import` or `/quest-import`. Feature changes carry their own API reference and examples; the package-selection guide is separate. +Use `quest guide` for the format and workflow, `quest ready` for actionable work, and `quest check` after editing the tree. Plan with `$quest-plan` or `/quest-plan`; import issues with `$quest-import` or `/quest-import`. Feature changes carry their own API reference and examples; package and backend selection lives in the [selection guide](/PACKAGE-SELECTION.md). ## Required diff --git a/quest/a1/README.md b/quest/a1/README.md index 4e5b078b..43643ee0 100644 --- a/quest/a1/README.md +++ b/quest/a1/README.md @@ -15,4 +15,3 @@ The Required list is ordered by priority. Independent children may proceed concu - [Response headers](/quest/a1/response-headers.md) - preserve success and rejection metadata - [Rust platform verifier](/quest/a1/platform-verifier.md) - `with_system_roots()` verifies with the OS trust store - [FFI platform verifier](/quest/a1/ffi-platform-verifier.md) - bindings verify on iOS and Android -- [Package selection](/quest/a1/package-selection.md) - verified comparison and selection guide diff --git a/quest/a1/package-selection.md b/quest/a1/package-selection.md deleted file mode 100644 index 297c0951..00000000 --- a/quest/a1/package-selection.md +++ /dev/null @@ -1,15 +0,0 @@ -# [M] Document package and backend selection - -## Goal - -A dedicated guide helps users select a package/backend and understand verified differences from wtransport without unsupported rankings. - -## Plan - -Compare current public capabilities: native backend choice, browser/WASM support, language bindings, stream/datagram APIs and integration surfaces. Use current primary documentation for wtransport and link to it; distinguish unsupported capabilities from unverified ones. Explain when to use the router, traits, a native backend or QMux. - -Create a standalone guide linked from the root and relevant package READMEs. This was approved as a separate documentation quest; API reference and examples remain with their feature changes. Avoid a comprehensive cross-language tutorial or performance claims without measurements. - -## Closes - -- [#117](https://github.com/moq-dev/web-transport/issues/117) - the implementation completes this report diff --git a/rs/qmux/README.md b/rs/qmux/README.md index 26f9c050..aca56896 100644 --- a/rs/qmux/README.md +++ b/rs/qmux/README.md @@ -6,6 +6,8 @@ QMux brings QUIC's multiplexed streams and flow control to reliable, ordered byt The protocol reuses QUIC frame types and semantics while adapting them for stream-based transports, providing multiplexed streams with flow control and optional unreliable datagrams. +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Install ```toml diff --git a/rs/web-transport-ffi/README.md b/rs/web-transport-ffi/README.md index 6bc43457..2e705a49 100644 --- a/rs/web-transport-ffi/README.md +++ b/rs/web-transport-ffi/README.md @@ -4,6 +4,8 @@ Low-level UniFFI bindings for WebTransport over HTTP/3 (QUIC). Generates Python, For an ergonomic Python API (async context managers, legacy exception hierarchy), see [`web-transport-rs`](https://pypi.org/project/web-transport-rs/) which wraps this package. +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + Clients lazily share one socket per destination address family: IPv4 uses `0.0.0.0:0`, IPv6 uses IPv6-only `[::]:0`, and IPv4-mapped IPv6 uses IPv4. Socket setup errors are returned by `connect`. `close` and final client drop diff --git a/rs/web-transport-iroh/README.md b/rs/web-transport-iroh/README.md index 564d2603..dc501d4e 100644 --- a/rs/web-transport-iroh/README.md +++ b/rs/web-transport-iroh/README.md @@ -11,6 +11,8 @@ It implements the [`web-transport-trait`] traits for iroh connections and stream The crate was originally derived from [`web-transport-quinn`]. +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## License Copyright 2025 N0, INC. diff --git a/rs/web-transport-noq/README.md b/rs/web-transport-noq/README.md index a4a6c149..28532798 100644 --- a/rs/web-transport-noq/README.md +++ b/rs/web-transport-noq/README.md @@ -6,6 +6,8 @@ A wrapper around the Noq API (a Quinn fork), abstracting away the annoying HTTP/3 internals. Provides a QUIC-like API but with web support! +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## WebTransport [WebTransport](https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API) is a new web API that allows for low-level, bidirectional communication between a client and a server. It's [available in the browser](https://caniuse.com/webtransport) as an alternative to HTTP and WebSockets. diff --git a/rs/web-transport-quiche/README.md b/rs/web-transport-quiche/README.md index b78e6db5..bb71da5d 100644 --- a/rs/web-transport-quiche/README.md +++ b/rs/web-transport-quiche/README.md @@ -6,6 +6,8 @@ A wrapper around the Quiche, abstracting away the annoying API and HTTP/3 internals. Provides a QUIC-like API but with web support! +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Limitations This library builds on top of [tokio-quiche](https://docs.rs/tokio-quiche/latest/tokio_quiche/); the "official" Tokio runtime for [quiche](https://github.com/cloudflare/quiche). diff --git a/rs/web-transport-quinn/README.md b/rs/web-transport-quinn/README.md index b51f794c..41ba2b1c 100644 --- a/rs/web-transport-quinn/README.md +++ b/rs/web-transport-quinn/README.md @@ -6,6 +6,8 @@ A wrapper around the Quinn API, abstracting away the annoying HTTP/3 internals. Provides a QUIC-like API but with web support! +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## WebTransport [WebTransport](https://developer.mozilla.org/en-US/docs/Web/API/WebTransport_API) is a new web API that allows for low-level, bidirectional communication between a client and a server. It's [available in the browser](https://caniuse.com/webtransport) as an alternative to HTTP and WebSockets. diff --git a/rs/web-transport-trait/README.md b/rs/web-transport-trait/README.md index cfe7f005..5a20e4a1 100644 --- a/rs/web-transport-trait/README.md +++ b/rs/web-transport-trait/README.md @@ -29,6 +29,8 @@ still owns its networking and runtime integration. The [web-transport](../web-transport) crate provides a concrete API that selects Quinn or the browser backend at compile time. +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Receive defaults The default async and poll receive helpers initialize at most 8 KiB of destination diff --git a/rs/web-transport-wasm/README.md b/rs/web-transport-wasm/README.md index b36d6cc0..4590cc2f 100644 --- a/rs/web-transport-wasm/README.md +++ b/rs/web-transport-wasm/README.md @@ -5,6 +5,8 @@ # web-transport-wasm A wrapper around the WebTransport browser API. +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Poll and async The browser API is a set of promises, but the surface here is a state machine. Every operation is a diff --git a/rs/web-transport/README.md b/rs/web-transport/README.md index 41262c9c..0490e624 100644 --- a/rs/web-transport/README.md +++ b/rs/web-transport/README.md @@ -15,6 +15,8 @@ This crate provides a generic WebTransport implementation depending on the platf WASM builds additionally require `--cfg=web_sys_unstable_apis`; see [web-transport-wasm](../web-transport-wasm/README.md#requirements). +See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Platform API and traits This crate exposes concrete types selected at compile time for the target platform. diff --git a/swift/README.md b/swift/README.md index 0d7dec41..6545d61a 100644 --- a/swift/README.md +++ b/swift/README.md @@ -2,6 +2,8 @@ A Swift wrapper around the [web-transport-ffi](../rs/web-transport-ffi) UniFFI bindings for [WebTransport over HTTP/3](https://datatracker.ietf.org/doc/draft-ietf-webtrans-http3/). +See the [package and backend selection guide](../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Install The package is distributed as a GitHub Release asset on the [moq-dev/web-transport](https://github.com/moq-dev/web-transport) repo. There is **no SPM mirror yet**, so SPM cannot resolve a `https://github.com/...` URL directly until one is set up.