From 00a0d1b18d166a89b182f6cd3c0f4a271d9c1455 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 04:33:53 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/a1/package-selection.md Quest-Claim: eebaf5d124bfa28e From 6b882fee5de0fc5c471fb6c6d8b8926ce3d7aab0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 04:40:19 -0800 Subject: [PATCH 2/4] docs: add package and backend selection guide (Written by GPT-6.1 Sol with xhigh) --- PACKAGE-SELECTION.md | 122 ++++++++++++++++++++++++++++++ README.md | 3 + js/qmux/README.md | 2 + js/web-transport/README.md | 2 + kt/README.md | 2 + py/web-transport/README.md | 2 + quest/a1/README.md | 1 - quest/a1/docs-current.md | 1 - quest/a1/package-selection.md | 19 ----- rs/qmux/README.md | 2 + rs/web-transport-ffi/README.md | 2 + rs/web-transport-iroh/README.md | 2 + rs/web-transport-noq/README.md | 2 + rs/web-transport-quiche/README.md | 2 + rs/web-transport-quinn/README.md | 2 + rs/web-transport-trait/README.md | 2 + rs/web-transport-wasm/README.md | 2 + rs/web-transport/README.md | 1 + swift/README.md | 2 + 19 files changed, 152 insertions(+), 21 deletions(-) create mode 100644 PACKAGE-SELECTION.md delete mode 100644 quest/a1/package-selection.md diff --git a/PACKAGE-SELECTION.md b/PACKAGE-SELECTION.md new file mode 100644 index 00000000..50877d03 --- /dev/null +++ b/PACKAGE-SELECTION.md @@ -0,0 +1,122 @@ +# 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 +WASM. 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. +**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. Native server setup comes 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 native `Send`/`Sync` and relax those bounds on WASM. | +| 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. | +| [`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) | HTTP/3/WebTransport semantics over existing iroh connections, with an iroh endpoint on the client side. | [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) and +[Quiche](rs/web-transport-quiche/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. + +## 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. | +| 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 +[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 d88a8f2b..2cfcb58f 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 This project is broken up into quite a few different crates: diff --git a/js/qmux/README.md b/js/qmux/README.md index b61c70d0..632273d2 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](../../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 eddd00cc..91885758 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](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. + ## Installation ```bash diff --git a/kt/README.md b/kt/README.md index f4dfb7df..eba33b1c 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 30e1f1d8..888c52bb 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](../../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/a1/README.md b/quest/a1/README.md index 951db889..1b2de085 100644 --- a/quest/a1/README.md +++ b/quest/a1/README.md @@ -21,4 +21,3 @@ The Required list is ordered by priority. Independent children may proceed concu - [WebSocket record size](/quest/a1/qmux-ws-record-size.md) - advertise only what the socket accepts - [Response headers](/quest/a1/response-headers.md) - preserve success and rejection metadata - [Current architecture docs](/quest/a1/docs-current.md) - repair stale workspace descriptions -- [Package selection](/quest/a1/package-selection.md) - verified comparison and selection guide diff --git a/quest/a1/docs-current.md b/quest/a1/docs-current.md index d1c15290..042d9d1e 100644 --- a/quest/a1/docs-current.md +++ b/quest/a1/docs-current.md @@ -12,5 +12,4 @@ Binding-specific installation/build instructions are owned by the corresponding ## Related -- [Package-selection guide](/quest/a1/package-selection.md) - new comparative guidance - [Binding runtime coverage](/quest/a1/bindings/README.md) - owns binding-local command corrections diff --git a/quest/a1/package-selection.md b/quest/a1/package-selection.md deleted file mode 100644 index f8b75c92..00000000 --- a/quest/a1/package-selection.md +++ /dev/null @@ -1,19 +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 - -## Related - -- [Current architecture documentation](/quest/a1/docs-current.md) - repairs existing stale descriptions independently diff --git a/rs/qmux/README.md b/rs/qmux/README.md index 57baf91f..c43d6ea7 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 8c20901e..d95ba476 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. + ## Building ```bash 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 a6d7dc15..00550ac6 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 871922ce..ef449d56 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 e17180b3..eff6547f 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 695e47c4..e6b496cb 100644 --- a/rs/web-transport-trait/README.md +++ b/rs/web-transport-trait/README.md @@ -16,6 +16,8 @@ This crate provides a WebTransport trait for Send runtimes. If you don't care about the underyling runtime, use the [web-transport](../web-transport) crate. +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 0720376f..5a6e385a 100644 --- a/rs/web-transport/README.md +++ b/rs/web-transport/README.md @@ -15,6 +15,7 @@ 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. ## Why no trait? diff --git a/swift/README.md b/swift/README.md index 6b9a0dc4..4e5ade9a 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. From e8e177befd79fe7cf74a6d12fd2931ce53684ada Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 04:47:32 -0800 Subject: [PATCH 3/4] docs: address package selection review findings (Written by GPT-6.1 Sol with xhigh) --- PACKAGE-SELECTION.md | 12 ++++++++---- quest/README.md | 2 +- quest/a1/docs-current.md | 2 +- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/PACKAGE-SELECTION.md b/PACKAGE-SELECTION.md index 50877d03..5d470ba4 100644 --- a/PACKAGE-SELECTION.md +++ b/PACKAGE-SELECTION.md @@ -2,12 +2,14 @@ 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 -WASM. Other native backends and QMux are separate packages; selecting them means +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. @@ -17,7 +19,7 @@ impossible or absent from every related project. | 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. Native server setup comes 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 native `Send`/`Sync` and relax those bounds on WASM. | +| [`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. | | [`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. | @@ -43,8 +45,10 @@ networking stack you need to integrate, rather than assuming one is faster. 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) and -[Quiche](rs/web-transport-quiche/src/lib.rs) limitations. Use a stack with HTTP/3 +[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. 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/docs-current.md b/quest/a1/docs-current.md index 042d9d1e..a56c2738 100644 --- a/quest/a1/docs-current.md +++ b/quest/a1/docs-current.md @@ -8,7 +8,7 @@ The root and Rust package documentation correctly link the workspace and describ Repair root crate links that omit `rs/`, the router README claim that WASM cannot implement the trait, and the trait README's obsolete Quiche/sans-I/O TODO descriptions. Check remaining package maps against Cargo workspace membership and actual exports. Preserve package-local detail rather than growing AGENTS.md. -Binding-specific installation/build instructions are owned by the corresponding binding CI quests to avoid competing edits. Validate local links and examples against the source. This cleanup is independently shippable from the new package-selection guide. +Binding-specific installation/build instructions are owned by the corresponding binding CI quests to avoid competing edits. Validate local links and examples against the source. Keep the [package-selection guide](/PACKAGE-SELECTION.md) separate from these architecture-map repairs. ## Related From 0a0f3389ad25fe644d6cd2602f2541171454b71f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 11 Nov 2026 00:45:59 -0800 Subject: [PATCH 4/4] docs: distinguish iroh raw QUIC and use absolute guide links in registry READMEs Co-Authored-By: Claude Opus 5.5 --- PACKAGE-SELECTION.md | 2 +- js/qmux/README.md | 2 +- js/web-transport/README.md | 2 +- py/web-transport/README.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/PACKAGE-SELECTION.md b/PACKAGE-SELECTION.md index a75f910e..706572cb 100644 --- a/PACKAGE-SELECTION.md +++ b/PACKAGE-SELECTION.md @@ -40,7 +40,7 @@ networking stack you need to integrate, rather than assuming one is faster. | [`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) | HTTP/3/WebTransport semantics over existing iroh connections, with an iroh endpoint on the client side. | [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. | +| [`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 diff --git a/js/qmux/README.md b/js/qmux/README.md index 64de23a0..777dfedb 100644 --- a/js/qmux/README.md +++ b/js/qmux/README.md @@ -4,7 +4,7 @@ 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](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. +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 diff --git a/js/web-transport/README.md b/js/web-transport/README.md index f7cc5dc1..a22bc35d 100644 --- a/js/web-transport/README.md +++ b/js/web-transport/README.md @@ -4,7 +4,7 @@ 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](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. +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 diff --git a/py/web-transport/README.md b/py/web-transport/README.md index a2f14fb9..19848ef7 100644 --- a/py/web-transport/README.md +++ b/py/web-transport/README.md @@ -5,7 +5,7 @@ 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](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. +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