From 03a50f484bcac1ea4e47d308c421f6e91a1a6486 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 21 Sep 2026 16:55:03 -0700 Subject: [PATCH 1/2] feat: add web-transport-moq, the WebTransport adapter over the fork Copied from moq-dev/web-transport's web-transport-noq at v0.3.0 and pointed at moq-noq. It shares the workspace version so one tag releases the stack and its adapter together; web-transport-noq stays upstream-facing in its own repo. Co-Authored-By: Claude Opus 5 --- Cargo.lock | 283 ++++- Cargo.toml | 4 +- README.md | 8 +- web-transport-moq/Cargo.toml | 60 + web-transport-moq/README.md | 60 + web-transport-moq/examples/README.md | 12 + .../examples/echo-client-advanced.rs | 83 ++ web-transport-moq/examples/echo-client.rs | 108 ++ .../examples/echo-server-advanced.rs | 145 +++ web-transport-moq/examples/echo-server.rs | 139 +++ web-transport-moq/src/client.rs | 378 ++++++ web-transport-moq/src/connect.rs | 158 +++ web-transport-moq/src/crypto.rs | 67 ++ web-transport-moq/src/error.rs | 297 +++++ web-transport-moq/src/lib.rs | 74 ++ web-transport-moq/src/recv.rs | 159 +++ web-transport-moq/src/send.rs | 194 +++ web-transport-moq/src/server.rs | 200 ++++ web-transport-moq/src/session.rs | 1039 +++++++++++++++++ web-transport-moq/src/settings.rs | 70 ++ web-transport-moq/tests/accept_wakers.rs | 233 ++++ web-transport-moq/tests/qlog.rs | 24 + 22 files changed, 3756 insertions(+), 39 deletions(-) create mode 100644 web-transport-moq/Cargo.toml create mode 100644 web-transport-moq/README.md create mode 100644 web-transport-moq/examples/README.md create mode 100644 web-transport-moq/examples/echo-client-advanced.rs create mode 100644 web-transport-moq/examples/echo-client.rs create mode 100644 web-transport-moq/examples/echo-server-advanced.rs create mode 100644 web-transport-moq/examples/echo-server.rs create mode 100644 web-transport-moq/src/client.rs create mode 100644 web-transport-moq/src/connect.rs create mode 100644 web-transport-moq/src/crypto.rs create mode 100644 web-transport-moq/src/error.rs create mode 100644 web-transport-moq/src/lib.rs create mode 100644 web-transport-moq/src/recv.rs create mode 100644 web-transport-moq/src/send.rs create mode 100644 web-transport-moq/src/server.rs create mode 100644 web-transport-moq/src/session.rs create mode 100644 web-transport-moq/src/settings.rs create mode 100644 web-transport-moq/tests/accept_wakers.rs create mode 100644 web-transport-moq/tests/qlog.rs diff --git a/Cargo.lock b/Cargo.lock index b6f50b8475..db512399fe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -147,7 +147,7 @@ checksum = "3109e49b1e4909e9db6515a30c633684d68cdeaa252f215214cb4fa1a5bfee2c" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", "synstructure", ] @@ -159,7 +159,7 @@ checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -310,7 +310,7 @@ checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -450,7 +450,7 @@ dependencies = [ "regex", "rustc-hash", "shlex 1.3.0", - "syn", + "syn 2.0.119", ] [[package]] @@ -628,7 +628,7 @@ dependencies = [ "heck", "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -871,7 +871,7 @@ dependencies = [ "proc-macro2", "quote", "strsim", - "syn", + "syn 2.0.119", ] [[package]] @@ -882,7 +882,7 @@ checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d" dependencies = [ "darling_core", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -920,7 +920,7 @@ dependencies = [ "proc-macro2", "quote", "structmeta", - "syn", + "syn 2.0.119", ] [[package]] @@ -931,7 +931,7 @@ checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -953,7 +953,7 @@ dependencies = [ "proc-macro2", "quote", "rustc_version", - "syn", + "syn 2.0.119", "unicode-xid", ] @@ -986,7 +986,7 @@ checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -1009,7 +1009,7 @@ checksum = "3ed8956bd5c1f0415200516e78ff07ec9e16415ade83c056c230d7b7ea0d55b7" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -1110,6 +1110,21 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c" +[[package]] +name = "futures" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + [[package]] name = "futures-channel" version = "0.3.33" @@ -1117,6 +1132,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae" dependencies = [ "futures-core", + "futures-sink", ] [[package]] @@ -1125,6 +1141,17 @@ version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" +[[package]] +name = "futures-executor" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + [[package]] name = "futures-io" version = "0.3.33" @@ -1144,6 +1171,17 @@ dependencies = [ "pin-project-lite", ] +[[package]] +name = "futures-macro" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "futures-sink" version = "0.3.33" @@ -1162,8 +1200,13 @@ version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" dependencies = [ + "futures-channel", "futures-core", + "futures-io", + "futures-macro", + "futures-sink", "futures-task", + "memchr", "pin-project-lite", "slab", ] @@ -1183,6 +1226,21 @@ version = "0.3.55" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f5f3913fa0bfe7ee1fd8248b6b9f42a5af4b9d65ec2dd2c3c26132b950ecfc2" +[[package]] +name = "generator" +version = "0.8.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "54ade96dc9003043bce7c035c85a9df5a858bfb2039c5a2e6fdf00f324f6c551" +dependencies = [ + "cc", + "cfg-if", + "libc", + "log", + "rustversion", + "windows-link", + "windows-result", +] + [[package]] name = "generic-array" version = "0.14.7" @@ -1605,7 +1663,7 @@ dependencies = [ "quote", "rustc_version", "simd_cesu8", - "syn", + "syn 2.0.119", ] [[package]] @@ -1624,7 +1682,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" dependencies = [ "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -1648,6 +1706,16 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "kio" +version = "0.5.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3033155c4fffcd86959a9ebdfbcadbed7ec4bfcc2fb545469778f791adf704eb" +dependencies = [ + "loom", + "smallvec", +] + [[package]] name = "lazy_static" version = "1.5.0" @@ -1722,6 +1790,20 @@ version = "0.4.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" +[[package]] +name = "loom" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "419e0dc8046cb947daa77eb95ae174acfbddb7673b4151f56d1eed8e93fbfaca" +dependencies = [ + "cfg-if", + "generator", + "pin-utils", + "scoped-tls", + "tracing", + "tracing-subscriber", +] + [[package]] name = "lru-slab" version = "0.1.2" @@ -2087,7 +2169,7 @@ checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2096,6 +2178,12 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "pin-utils" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184" + [[package]] name = "piper" version = "0.2.5" @@ -2170,7 +2258,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b" dependencies = [ "proc-macro2", - "syn", + "syn 2.0.119", ] [[package]] @@ -2217,7 +2305,7 @@ dependencies = [ "itertools", "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2348,6 +2436,26 @@ dependencies = [ "thiserror 1.0.69", ] +[[package]] +name = "ref-cast" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3" +dependencies = [ + "ref-cast-impl", +] + +[[package]] +name = "ref-cast-impl" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + [[package]] name = "regex" version = "1.13.1" @@ -2456,6 +2564,15 @@ dependencies = [ "security-framework", ] +[[package]] +name = "rustls-pemfile" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dce314e5fee3f39953d46bb63bb8a46d40c2f8fb7cc5a3b6cab2bde9721d6e50" +dependencies = [ + "rustls-pki-types", +] + [[package]] name = "rustls-pki-types" version = "1.15.0" @@ -2529,6 +2646,12 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "scoped-tls" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" + [[package]] name = "scopeguard" version = "1.2.0" @@ -2591,7 +2714,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2627,7 +2750,18 @@ dependencies = [ "darling", "proc-macro2", "quote", - "syn", + "syn 2.0.119", +] + +[[package]] +name = "sfv" +version = "0.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "890ef0e5532daf21fdaa3dbaf991417187f3a87ab69231fe69be942495746480" +dependencies = [ + "base64 0.22.1", + "indexmap", + "ref-cast", ] [[package]] @@ -2755,7 +2889,7 @@ dependencies = [ "proc-macro2", "quote", "structmeta-derive", - "syn", + "syn 2.0.119", ] [[package]] @@ -2766,7 +2900,7 @@ checksum = "152a0b65a590ff6c3da95cabe2353ee04e6167c896b28e3b14478c2636c922fc" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2787,7 +2921,7 @@ dependencies = [ "heck", "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2807,6 +2941,17 @@ dependencies = [ "unicode-ident", ] +[[package]] +name = "syn" +version = "3.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + [[package]] name = "sync_wrapper" version = "1.0.2" @@ -2821,7 +2966,7 @@ checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2834,7 +2979,7 @@ dependencies = [ "proc-macro2", "quote", "structmeta", - "syn", + "syn 2.0.119", ] [[package]] @@ -2869,7 +3014,7 @@ checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2880,7 +3025,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -2968,6 +3113,7 @@ dependencies = [ "bytes", "libc", "mio", + "parking_lot", "pin-project-lite", "signal-hook-registry", "socket2", @@ -2984,7 +3130,7 @@ checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -3103,7 +3249,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -3126,6 +3272,17 @@ dependencies = [ "tracing", ] +[[package]] +name = "tracing-log" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3" +dependencies = [ + "log", + "once_cell", + "tracing-core", +] + [[package]] name = "tracing-subscriber" version = "0.3.23" @@ -3138,10 +3295,12 @@ dependencies = [ "parking_lot", "regex-automata", "sharded-slab", + "smallvec", "thread_local", "time", "tracing", "tracing-core", + "tracing-log", ] [[package]] @@ -3308,7 +3467,7 @@ dependencies = [ "bumpalo", "proc-macro2", "quote", - "syn", + "syn 2.0.119", "wasm-bindgen-shared", ] @@ -3351,7 +3510,7 @@ checksum = "94eb68555b95bcea5e8cf4abe280b529049479fa995bfc23734af96a6aedc120" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -3370,6 +3529,53 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "web-transport-moq" +version = "1.3.0" +dependencies = [ + "anyhow", + "bytes", + "clap", + "futures", + "http", + "kio", + "moq-noq", + "rcgen", + "rustls", + "rustls-native-certs", + "rustls-pemfile", + "thiserror 2.0.18", + "tokio", + "tracing", + "tracing-subscriber", + "url", + "web-transport-proto", + "web-transport-trait", +] + +[[package]] +name = "web-transport-proto" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a81bcc79bf48ad0b819bfa51ec28524ee7c356056d43c316727d6b505dcc71e" +dependencies = [ + "bytes", + "http", + "sfv", + "thiserror 2.0.18", + "tokio", + "url", +] + +[[package]] +name = "web-transport-trait" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a916df726e858e8e6cc21e852129f59e6277d3a01bb2254c0506dcf829fdd5d" +dependencies = [ + "bytes", +] + [[package]] name = "webpki-root-certs" version = "1.0.9" @@ -3416,6 +3622,15 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-sys" version = "0.52.0" @@ -3557,7 +3772,7 @@ checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", "synstructure", ] @@ -3578,7 +3793,7 @@ checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] @@ -3598,7 +3813,7 @@ checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", "synstructure", ] @@ -3638,7 +3853,7 @@ checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.119", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index 1f0f4c0d0f..27fc4ad72f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] -members = ["noq", "noq-proto", "noq-udp", "bench", "perf", "fuzz"] -default-members = ["noq", "noq-proto", "noq-udp", "bench", "perf"] +members = ["noq", "noq-proto", "noq-udp", "web-transport-moq", "bench", "perf", "fuzz"] +default-members = ["noq", "noq-proto", "noq-udp", "web-transport-moq", "bench", "perf"] resolver = "2" [workspace.package] diff --git a/README.md b/README.md index d1039b1940..9d79fed5d4 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,11 @@ This is [moq-dev](https://github.com/moq-dev)'s fork of [n0-computer/noq](https://github.com/n0-computer/noq), published on crates.io as -`moq-noq`, `moq-noq-proto`, and `moq-noq-udp`. It carries the QUIC features -[Media over QUIC](https://github.com/moq-dev/moq) needs before they land -upstream, and it never publishes under the parent's names. `PARENT` names the +`moq-noq`, `moq-noq-proto`, `moq-noq-udp`, and `web-transport-moq`, the +WebTransport adapter over the fork. All four share one version and one release. +It carries the QUIC features [Media over QUIC](https://github.com/moq-dev/moq) +needs before they land upstream, and it never publishes under the parent's +names. `PARENT` names the upstream commit each release includes, and `moq-sync` merges upstream weekly. General changes are offered upstream once their shape settles; the carried set is `git log --no-merges upstream/main..main`. diff --git a/web-transport-moq/Cargo.toml b/web-transport-moq/Cargo.toml new file mode 100644 index 0000000000..d6f28a071e --- /dev/null +++ b/web-transport-moq/Cargo.toml @@ -0,0 +1,60 @@ +[package] +name = "web-transport-moq" +description = "WebTransport library for moq-noq, the MoQ fork of Noq" +authors = ["Luke Curley"] +version.workspace = true +repository.workspace = true +license.workspace = true +rust-version.workspace = true +edition = "2021" +workspace = ".." + +keywords = ["quic", "http3", "webtransport"] +categories = ["network-programming", "web-programming"] + +[package.metadata.docs.rs] +all-features = true + +[features] +default = ["aws-lc-rs"] +aws-lc-rs = ["noq/aws-lc-rs", "rustls/aws-lc-rs"] +ring = ["noq/ring", "rustls/ring"] +# Unlocks `noq::TransportConfig::qlog_*`, which this crate re-exports but cannot +# enable on a caller's behalf. +qlog = ["noq/qlog"] + +[dependencies] +bytes = "1" +futures = "0.3" +http = "1" +kio = "0.5.4" +noq = { package = "moq-noq", path = "../noq", version = "1.3.0", default-features = false, features = [ + "tracing-log", + "platform-verifier", + "runtime-tokio", + "rustls", + "bloom", +] } +rustls = { version = "0.23", default-features = false, features = [ + "logging", + "std", +] } +rustls-native-certs = "0.8" +thiserror = "2" +tokio = { version = "1", default-features = false, features = [ + "io-util", + "macros", + "time", +] } +tracing = "0.1" +url = "2" +web-transport-proto = "0.6" +web-transport-trait = "0.4" + +[dev-dependencies] +anyhow = "1" +clap = { version = "4", features = ["derive"] } +rcgen = "0.14" +rustls-pemfile = "2" +tokio = { version = "1", features = ["full"] } +tracing-subscriber = { version = "0.3", features = ["env-filter"] } diff --git a/web-transport-moq/README.md b/web-transport-moq/README.md new file mode 100644 index 0000000000..6fe2eb1360 --- /dev/null +++ b/web-transport-moq/README.md @@ -0,0 +1,60 @@ +[![crates.io](https://img.shields.io/crates/v/web-transport-moq)](https://crates.io/crates/web-transport-moq) +[![docs.rs](https://img.shields.io/docsrs/web-transport-moq)](https://docs.rs/web-transport-moq) +[![discord](https://img.shields.io/discord/1124083992740761730)](https://discord.gg/FCYF3p99mr) + +# web-transport-moq +A wrapper around the [moq-noq](../README.md) API (the MoQ fork of Noq, a Quinn fork), abstracting away the annoying HTTP/3 internals. The same adapter for upstream noq is [web-transport-noq](https://github.com/moq-dev/web-transport). +Provides a QUIC-like API but with web support! + +## 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. + +WebTransport is layered on top of HTTP/3 which itself is layered on top of QUIC. +This library hides that detail and exposes only the QUIC API, delegating as much as possible to the underlying QUIC implementation (Noq, a Quinn fork). + +QUIC provides two primary APIs: + +## Streams + +QUIC streams are ordered, reliable, flow-controlled, and optionally bidirectional. +Both endpoints can create and close streams (including an error code) with no overhead. +You can think of them as TCP connections, but shared over a single QUIC connection. + +## Datagrams + +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. + +# Usage +To use web-transport-moq, first you need to create a [noq::Endpoint](https://docs.rs/moq-noq/latest/moq_noq/struct.Endpoint.html); see the documentation and examples for more information. +The only requirement is that the ALPN is set to `web_transport_moq::ALPN` (aka `h3`). + +Afterwards, you use [web_transport_moq::accept](https://docs.rs/web-transport-moq/latest/web_transport_moq/fn.accept.html) (as a server) or [web_transport_moq::connect](https://docs.rs/web-transport-moq/latest/web_transport_moq/fn.connect.html) (as a client) to establish a WebTransport session. +This will take over the QUIC connection and perform the boring HTTP/3 handshake for you. + +See the [examples](examples) or [moq-native](https://github.com/moq-dev/moq-rs/blob/main/moq-native/src/quic.rs) for a full setup. + +```rust + // Create a QUIC client. + let mut endpoint = noq::Endpoint::client("[::]:0".parse()?)?; + endpoint.set_default_client_config(/* ... */); + + // Connect to the given URL. + let session = web_transport_moq::connect(&client, Url::parse("https://localhost")?).await?; + + // Create a bidirectional stream. + let (mut send, mut recv) = session.open_bi().await?; + + // Send a message. + send.write(b"hello").await?; +``` + +## API +The `web-transport-moq` API is almost identical to the Noq API, except that [Connection](https://docs.rs/moq-noq/latest/moq_noq/struct.Connection.html) is called [Session](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Session.html). + +When possible, `Deref` is used to expose the underlying Noq API. +However some of the API is wrapped or unavailable due to WebTransport limitations. +- Stream IDs are not available. +- Error codes are not full VarInts (62-bits) and significantly smaller. diff --git a/web-transport-moq/examples/README.md b/web-transport-moq/examples/README.md new file mode 100644 index 0000000000..1526d8c24c --- /dev/null +++ b/web-transport-moq/examples/README.md @@ -0,0 +1,12 @@ +# Example + +## Simple Echo +A simple [server](echo-server.rs) and [client](echo-client.rs). + +There's also advanced examples [server](echo-server-advanced.rs) and [client](echo-client-advanced.rs) that construct the QUIC connection manually. + +QUIC requires TLS, which makes the initial setup a bit more involved. + +- Generate a certificate, for example `rcgen` or `mkcert localhost` +- Run the Rust server: `cargo run --example echo-server -- --tls-cert localhost.crt --tls-key localhost.key` +- Run the Rust client: `cargo run --example echo-client -- --tls-cert localhost.crt` diff --git a/web-transport-moq/examples/echo-client-advanced.rs b/web-transport-moq/examples/echo-client-advanced.rs new file mode 100644 index 0000000000..105b627805 --- /dev/null +++ b/web-transport-moq/examples/echo-client-advanced.rs @@ -0,0 +1,83 @@ +use std::{fs, io, path, sync::Arc}; + +use anyhow::Context; +use clap::Parser; +use rustls::pki_types::CertificateDer; +use url::Url; + +#[derive(Parser, Debug)] +#[command(author, version, about, long_about = None)] +struct Args { + #[arg(short, long, default_value = "https://localhost:4443")] + url: Url, + + /// Accept the certificates at this path, encoded as PEM. + #[arg(long)] + tls_cert: path::PathBuf, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Enable info logging. + tracing_subscriber::fmt() + .with_env_filter( + tracing_subscriber::EnvFilter::try_from_default_env() + .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), + ) + .init(); + + let args = Args::parse(); + + // Read the PEM certificate chain + let chain = fs::File::open(args.tls_cert).context("failed to open cert file")?; + let mut chain = io::BufReader::new(chain); + + let chain: Vec = rustls_pemfile::certs(&mut chain) + .collect::>() + .context("failed to load certs")?; + + anyhow::ensure!(!chain.is_empty(), "could not find certificate"); + + let mut roots = rustls::RootCertStore::empty(); + roots.add_parsable_certificates(chain); + + // Standard noq setup, accepting only the given certificate. + // You should use system roots in production. + let mut config = + rustls::ClientConfig::builder_with_provider(web_transport_moq::crypto::default_provider()) + .with_protocol_versions(&[&rustls::version::TLS13])? + .with_root_certificates(roots) + .with_no_client_auth(); + config.alpn_protocols = vec![web_transport_moq::ALPN.as_bytes().to_vec()]; // this one is important + + let config: noq::crypto::rustls::QuicClientConfig = config.try_into()?; + let config = noq::ClientConfig::new(Arc::new(config)); + + let client = noq::Endpoint::client("[::]:0".parse()?)?; + let client = web_transport_moq::Client::new(client, config); + + // Connect to the given URL. + tracing::info!(url = %args.url, "connecting"); + let session = client.connect(args.url).await?; + + tracing::info!("connected"); + + // Create a bidirectional stream. + let (mut send, mut recv) = session.open_bi().await?; + + tracing::info!("created stream"); + + // Send a message. + let msg = "hello world".to_string(); + send.write_all(msg.as_bytes()).await?; + tracing::info!(%msg, "sent"); + + // Shut down the send stream. + send.finish()?; + + // Read back the message. + let msg = recv.read_to_end(1024).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + Ok(()) +} diff --git a/web-transport-moq/examples/echo-client.rs b/web-transport-moq/examples/echo-client.rs new file mode 100644 index 0000000000..b205c309ff --- /dev/null +++ b/web-transport-moq/examples/echo-client.rs @@ -0,0 +1,108 @@ +use std::{fs, io, path}; + +use anyhow::Context; +use clap::Parser; +use rustls::pki_types::CertificateDer; +use url::Url; +use web_transport_moq::proto::ConnectRequest; + +#[derive(Parser, Debug)] +#[command(author, version, about, long_about = None)] +struct Args { + #[arg(short, long, default_value = "https://localhost:4443")] + url: Url, + + /// Accept the certificates at this path, encoded as PEM. + #[arg(long)] + tls_cert: Option, + + /// Dangerous: Disable TLS certificate verification. + #[arg(long, default_value = "false")] + tls_disable_verify: bool, + + /// Optional WebTransport subprotocol to negotiate. + #[arg(long)] + protocol: Option, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Enable info logging. + tracing_subscriber::fmt() + .with_env_filter( + tracing_subscriber::EnvFilter::try_from_default_env() + .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), + ) + .init(); + + let args = Args::parse(); + + let client = web_transport_moq::ClientBuilder::new(); + + let client = if args.tls_disable_verify { + tracing::warn!("disabling TLS certificate verification; a MITM attack is possible"); + + // Accept any certificate. + client.dangerous().with_no_certificate_verification()? + } else if let Some(path) = &args.tls_cert { + // Read the PEM certificate chain + let chain = fs::File::open(path).context("failed to open cert file")?; + let mut chain = io::BufReader::new(chain); + + let chain: Vec = rustls_pemfile::certs(&mut chain) + .collect::>() + .context("failed to load certs")?; + + anyhow::ensure!(!chain.is_empty(), "could not find certificate"); + + // Only accept these certificates. + // Also available: with_server_certificate_hashes + client.with_server_certificates(chain)? + } else { + // Accept any certificate that matches a system root. + client.with_system_roots()? + }; + + tracing::info!(url = %args.url, "connecting"); + + // Connect to the given URL. + let mut request = ConnectRequest::new(args.url); + if let Some(protocol) = &args.protocol { + request = request.with_protocol(protocol); + } + let session = client.connect(request).await?; + + tracing::info!("connected"); + + match (&args.protocol, session.protocol()) { + (Some(_), Some(protocol)) => { + tracing::info!(%protocol, "negotiated protocol"); + } + (Some(requested), None) => { + tracing::warn!(%requested, "server did not negotiate protocol"); + } + _ => {} + } + + // Create a bidirectional stream. + let (mut send, mut recv) = session.open_bi().await?; + + tracing::info!("created stream"); + + // Send a message. + let msg = "hello world".to_string(); + send.write_all(msg.as_bytes()).await?; + tracing::info!(%msg, "sent"); + + // Shut down the send stream. + send.finish()?; + + // Read back the message. + let msg = recv.read_to_end(1024).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + session.close(42069, b"bye"); + session.closed().await; + + Ok(()) +} diff --git a/web-transport-moq/examples/echo-server-advanced.rs b/web-transport-moq/examples/echo-server-advanced.rs new file mode 100644 index 0000000000..33053255c3 --- /dev/null +++ b/web-transport-moq/examples/echo-server-advanced.rs @@ -0,0 +1,145 @@ +use std::{ + fs, + io::{self, Read}, + path, + sync::Arc, +}; + +use anyhow::Context; + +use clap::Parser; +use rustls::pki_types::CertificateDer; +use web_transport_moq::Session; + +#[derive(Parser, Debug)] +#[command(author, version, about, long_about = None)] +struct Args { + #[arg(short, long, default_value = "[::]:4443")] + addr: std::net::SocketAddr, + + /// Use the certificates at this path, encoded as PEM. + #[arg(long)] + pub tls_cert: path::PathBuf, + + /// Use the private key at this path, encoded as PEM. + #[arg(long)] + pub tls_key: path::PathBuf, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Enable info logging. + tracing_subscriber::fmt() + .with_env_filter( + tracing_subscriber::EnvFilter::try_from_default_env() + .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), + ) + .init(); + + let args = Args::parse(); + + // Read the PEM certificate chain + let chain = fs::File::open(args.tls_cert).context("failed to open cert file")?; + let mut chain = io::BufReader::new(chain); + + let chain: Vec = rustls_pemfile::certs(&mut chain) + .collect::>() + .context("failed to load certs")?; + + anyhow::ensure!(!chain.is_empty(), "could not find certificate"); + + // Read the PEM private key + let mut keys = fs::File::open(args.tls_key).context("failed to open key file")?; + + // Read the keys into a Vec so we can parse it twice. + let mut buf = Vec::new(); + keys.read_to_end(&mut buf)?; + + // Try to parse a PKCS#8 key + // -----BEGIN PRIVATE KEY----- + let key = rustls_pemfile::private_key(&mut io::Cursor::new(&buf)) + .context("failed to load private key")? + .context("missing private key")?; + + // Standard Noq setup + let mut config = + rustls::ServerConfig::builder_with_provider(web_transport_moq::crypto::default_provider()) + .with_protocol_versions(&[&rustls::version::TLS13])? + .with_no_client_auth() + .with_single_cert(chain, key)?; + + config.max_early_data_size = u32::MAX; + config.alpn_protocols = vec![web_transport_moq::ALPN.as_bytes().to_vec()]; // this one is important + + let config: noq::crypto::rustls::QuicServerConfig = config.try_into()?; + let config = noq::ServerConfig::with_crypto(Arc::new(config)); + + tracing::info!(addr = %args.addr, "listening"); + + let server = noq::Endpoint::server(config, args.addr)?; + + // Accept new connections. + while let Some(conn) = server.accept().await { + tokio::spawn(async move { + let err = run_conn(conn).await; + if let Err(err) = err { + tracing::error!(?err, "connection failed") + } + }); + } + + Ok(()) +} + +async fn run_conn(conn: noq::Incoming) -> anyhow::Result<()> { + tracing::info!("received new QUIC connection"); + + // Wait for the QUIC handshake to complete. + let conn = conn.await.context("failed to accept connection")?; + tracing::info!("established QUIC connection"); + + // Perform the WebTransport handshake. + let request = web_transport_moq::Request::accept(conn).await?; + tracing::info!(url = %request.url, "received WebTransport request"); + + // Accept the session. + let session = request.ok().await.context("failed to accept session")?; + + tracing::info!("accepted session"); + + // Run the session + if let Err(err) = run_session(session).await { + tracing::info!(?err, "closing session"); + } + + Ok(()) +} + +async fn run_session(session: Session) -> anyhow::Result<()> { + loop { + // Wait for a bidirectional stream or datagram. + tokio::select! { + res = session.accept_bi() => { + let (mut send, mut recv) = res?; + tracing::info!("accepted stream"); + + // Read the message and echo it back. + let msg = recv.read_to_end(1024).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + send.write_all(&msg).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "send"); + }, + res = session.read_datagram() => { + let msg = res?; + tracing::info!("accepted datagram"); + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + session.send_datagram(msg.clone())?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "send"); + }, + }; + + tracing::info!("echo successful"); + } +} diff --git a/web-transport-moq/examples/echo-server.rs b/web-transport-moq/examples/echo-server.rs new file mode 100644 index 0000000000..2e78f16233 --- /dev/null +++ b/web-transport-moq/examples/echo-server.rs @@ -0,0 +1,139 @@ +use std::{fs, io, path}; + +use anyhow::Context; + +use clap::Parser; +use rustls::pki_types::CertificateDer; +use web_transport_moq::{proto::ConnectResponse, Session}; + +#[derive(Parser, Debug)] +#[command(author, version, about, long_about = None)] +struct Args { + #[arg(short, long, default_value = "[::]:4443")] + addr: std::net::SocketAddr, + + /// Use the certificates at this path, encoded as PEM. + #[arg(long)] + pub tls_cert: path::PathBuf, + + /// Use the private key at this path, encoded as PEM. + #[arg(long)] + pub tls_key: path::PathBuf, + + /// Optional WebTransport subprotocol to support. + #[arg(long)] + pub protocol: Option, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Enable info logging. + tracing_subscriber::fmt() + .with_env_filter( + tracing_subscriber::EnvFilter::try_from_default_env() + .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")), + ) + .init(); + + let args = Args::parse(); + + // Read the PEM certificate chain + let chain = fs::File::open(args.tls_cert).context("failed to open cert file")?; + let mut chain = io::BufReader::new(chain); + + let chain: Vec = rustls_pemfile::certs(&mut chain) + .collect::>() + .context("failed to load certs")?; + + anyhow::ensure!(!chain.is_empty(), "could not find certificate"); + + // Read the PEM private key + let keys = fs::File::open(args.tls_key).context("failed to open key file")?; + + // Try to parse a PKCS#8 key + // -----BEGIN PRIVATE KEY----- + let key = rustls_pemfile::private_key(&mut io::BufReader::new(keys)) + .context("failed to load private key")? + .context("missing private key")?; + + let mut server = web_transport_moq::ServerBuilder::new() + .with_addr(args.addr) + .with_certificate(chain, key)?; + + tracing::info!(addr = %args.addr, "listening"); + + // Accept new connections. + while let Some(conn) = server.accept().await { + let protocol = args.protocol.clone(); + tokio::spawn(async move { + let err = run_conn(conn, protocol).await; + if let Err(err) = err { + tracing::error!(?err, "connection failed") + } + }); + } + + // TODO simple echo server + + Ok(()) +} + +async fn run_conn( + request: web_transport_moq::Request, + protocol: Option, +) -> anyhow::Result<()> { + tracing::info!(url = %request.url, "received WebTransport request"); + + // Negotiate protocol if both client and server support it. + let negotiated = protocol.filter(|p| request.protocols.contains(p)); + if let Some(protocol) = &negotiated { + tracing::info!(%protocol, "negotiated protocol"); + } + + // Accept the session. + let mut response = ConnectResponse::OK; + if let Some(protocol) = negotiated { + response = response.with_protocol(protocol); + } + let session = request + .respond(response) + .await + .context("failed to accept session")?; + tracing::info!("accepted session"); + + // Run the session + if let Err(err) = run_session(session).await { + tracing::info!(?err, "closing session"); + } + + Ok(()) +} + +async fn run_session(session: Session) -> anyhow::Result<()> { + loop { + // Wait for a bidirectional stream or datagram. + tokio::select! { + res = session.accept_bi() => { + let (mut send, mut recv) = res?; + tracing::info!("accepted stream"); + + // Read the message and echo it back. + let msg = recv.read_to_end(1024).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + send.write_all(&msg).await?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "send"); + }, + res = session.read_datagram() => { + let msg = res?; + tracing::info!("accepted datagram"); + tracing::info!(msg = %String::from_utf8_lossy(&msg), "recv"); + + session.send_datagram(msg.clone())?; + tracing::info!(msg = %String::from_utf8_lossy(&msg), "send"); + }, + }; + + tracing::info!("echo successful"); + } +} diff --git a/web-transport-moq/src/client.rs b/web-transport-moq/src/client.rs new file mode 100644 index 0000000000..c3dcee477b --- /dev/null +++ b/web-transport-moq/src/client.rs @@ -0,0 +1,378 @@ +use std::net::{IpAddr, SocketAddr}; +use std::sync::Arc; + +use crate::proto::ConnectRequest; +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +use noq::crypto::rustls::QuicClientConfig; +use rustls::{client::danger::ServerCertVerifier, pki_types::CertificateDer}; +use tokio::net::lookup_host; +use url::Host; + +use crate::crypto; +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +use crate::ALPN; +use crate::{ClientError, Session}; + +/// Congestion control algorithm to use for the connection. +/// +/// Different algorithms make different tradeoffs between throughput and latency. +pub enum CongestionControl { + /// Use the default congestion control algorithm (typically CUBIC). + Default, + /// Optimize for throughput (typically CUBIC). + Throughput, + /// Optimize for low latency (typically BBR). + LowLatency, +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +/// Construct a WebTransport [Client] using sane defaults. +/// +/// This is optional; advanced users may use [Client::new] directly. +#[derive(Clone)] +pub struct ClientBuilder { + provider: crypto::Provider, + congestion_controller: + Option>, +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl ClientBuilder { + /// Create a Client builder, which can be used to establish multiple [Session]s. + pub fn new() -> Self { + Self { + provider: crypto::default_provider(), + congestion_controller: None, + } + } + + /// Enable the specified congestion controller. + pub fn with_congestion_control(mut self, algorithm: CongestionControl) -> Self { + self.congestion_controller = match algorithm { + CongestionControl::LowLatency => Some(Arc::new(noq::congestion::Bbr3Config::default())), + // TODO BBR is also higher throughput in theory. + CongestionControl::Throughput => { + Some(Arc::new(noq::congestion::CubicConfig::default())) + } + CongestionControl::Default => None, + }; + + self + } + + /// Accept any certificate from the server if it uses a known root CA. + pub fn with_system_roots(self) -> Result { + let mut roots = rustls::RootCertStore::empty(); + + let native = rustls_native_certs::load_native_certs(); + + // Log any errors that occurred while loading the native root certificates. + for err in native.errors { + tracing::warn!(?err, "failed to load root cert"); + } + + // Add the platform's native root certificates. + for cert in native.certs { + if let Err(err) = roots.add(cert) { + tracing::warn!(?err, "failed to add root cert"); + } + } + + let crypto = self + .builder() + .with_root_certificates(roots) + .with_no_client_auth(); + + self.build(crypto) + } + + /// Supply certificates for accepted servers instead of using root CAs. + pub fn with_server_certificates( + self, + certs: Vec, + ) -> Result { + let hashes = certs.iter().map({ + let provider = self.provider.clone(); + move |cert| crypto::sha256(&provider, cert).as_ref().to_vec() + }); + + self.with_server_certificate_hashes(hashes.collect()) + } + + /// Supply sha256 hashes for accepted certificates instead of using root CAs. + pub fn with_server_certificate_hashes( + self, + hashes: Vec>, + ) -> Result { + // Use a custom fingerprint verifier. + let fingerprints = Arc::new(ServerFingerprints { + provider: self.provider.clone(), + fingerprints: hashes, + }); + + // Configure the crypto client. + let crypto = self + .builder() + .dangerous() + .with_custom_certificate_verifier(fingerprints.clone()) + .with_no_client_auth(); + + self.build(crypto) + } + + /// Access dangerous configuration options. + /// + /// This method returns a builder that provides access to potentially insecure + /// TLS configurations. These options are opt-in and require explicit acknowledgment + /// through the builder pattern, making the security implications clear at the call site. + pub fn dangerous(self) -> DangerousClientBuilder { + DangerousClientBuilder { inner: self } + } + + fn builder(&self) -> rustls::ConfigBuilder { + rustls::ClientConfig::builder_with_provider(self.provider.clone()) + .with_protocol_versions(&[&rustls::version::TLS13]) + .unwrap() + } + + fn build(self, mut crypto: rustls::ClientConfig) -> Result { + crypto.alpn_protocols = vec![ALPN.as_bytes().to_vec()]; + + let client_config = QuicClientConfig::try_from(crypto).unwrap(); + let mut client_config = noq::ClientConfig::new(Arc::new(client_config)); + + let mut transport = noq::TransportConfig::default(); + if let Some(cc) = &self.congestion_controller { + transport.congestion_controller_factory(cc.clone()); + } + + client_config.transport_config(transport.into()); + + let client = noq::Endpoint::client("[::]:0".parse().unwrap()).unwrap(); + Ok(Client { + endpoint: client, + config: client_config, + }) + } +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl Default for ClientBuilder { + fn default() -> Self { + Self::new() + } +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +/// Builder for dangerous TLS configuration options. +/// +/// This builder provides access to potentially insecure TLS configurations. +/// These options should only be used when you understand the security implications, +/// such as in local development or over a secure VPN connection. +pub struct DangerousClientBuilder { + inner: ClientBuilder, +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl DangerousClientBuilder { + /// Disable certificate verification entirely. + /// + /// This makes the connection vulnerable to man-in-the-middle attacks. + /// Only use this in secure environments, such as in local development or over a VPN connection. + /// + /// This method is safe in the Rust sense (no memory unsafety), but dangerous in the + /// security sense, hence the explicit `dangerous()` builder requirement. + pub fn with_no_certificate_verification(self) -> Result { + let noop = NoCertificateVerification(self.inner.provider.clone()); + + let crypto = self + .inner + .builder() + .dangerous() + .with_custom_certificate_verifier(Arc::new(noop)) + .with_no_client_auth(); + + self.inner.build(crypto) + } +} + +/// A client for connecting to a WebTransport server. +#[derive(Clone, Debug)] +pub struct Client { + endpoint: noq::Endpoint, + config: noq::ClientConfig, +} + +impl Client { + /// Manually create a client via a Noq endpoint and config. + /// + /// The ALPN MUST be set to [ALPN]. + pub fn new(endpoint: noq::Endpoint, config: noq::ClientConfig) -> Self { + Self { endpoint, config } + } + + /// Connect to the server. + pub async fn connect( + &self, + request: impl Into, + ) -> Result { + let request = request.into(); + + let port = request.url.port().unwrap_or(443); + + // TODO error on username:password in host + let (host, remote) = match request + .url + .host() + .ok_or_else(|| ClientError::InvalidDnsName("".to_string()))? + { + Host::Domain(domain) => { + let domain = domain.to_string(); + // Look up the DNS entry. + let mut remotes = match lookup_host((domain.clone(), port)).await { + Ok(remotes) => remotes, + Err(_) => return Err(ClientError::InvalidDnsName(domain)), + }; + + // Return the first entry. + let remote = match remotes.next() { + Some(remote) => remote, + None => return Err(ClientError::InvalidDnsName(domain)), + }; + + (domain, remote) + } + Host::Ipv4(ipv4) => (ipv4.to_string(), SocketAddr::new(IpAddr::V4(ipv4), port)), + Host::Ipv6(ipv6) => (ipv6.to_string(), SocketAddr::new(IpAddr::V6(ipv6), port)), + }; + + // Connect to the server using the addr we just resolved. + let conn = self + .endpoint + .connect_with(self.config.clone(), remote, &host)?; + let conn = conn.await?; + + // Connect with the connection we established. + Session::connect(conn, request).await + } +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl Default for Client { + fn default() -> Self { + ClientBuilder::new().with_system_roots().unwrap() + } +} + +#[cfg_attr(not(any(feature = "aws-lc-rs", feature = "ring")), allow(dead_code))] +#[derive(Debug)] +struct ServerFingerprints { + provider: crypto::Provider, + fingerprints: Vec>, +} + +impl ServerCertVerifier for ServerFingerprints { + fn verify_server_cert( + &self, + end_entity: &rustls::pki_types::CertificateDer<'_>, + _intermediates: &[rustls::pki_types::CertificateDer<'_>], + _server_name: &rustls::pki_types::ServerName<'_>, + _ocsp_response: &[u8], + _now: rustls::pki_types::UnixTime, + ) -> Result { + let cert_hash = crypto::sha256(&self.provider, end_entity); + if self + .fingerprints + .iter() + .any(|fingerprint| fingerprint == cert_hash.as_ref()) + { + return Ok(rustls::client::danger::ServerCertVerified::assertion()); + } + + Err(rustls::Error::InvalidCertificate( + rustls::CertificateError::UnknownIssuer, + )) + } + + fn verify_tls12_signature( + &self, + message: &[u8], + cert: &rustls::pki_types::CertificateDer<'_>, + dss: &rustls::DigitallySignedStruct, + ) -> Result { + rustls::crypto::verify_tls12_signature( + message, + cert, + dss, + &self.provider.signature_verification_algorithms, + ) + } + + fn verify_tls13_signature( + &self, + message: &[u8], + cert: &rustls::pki_types::CertificateDer<'_>, + dss: &rustls::DigitallySignedStruct, + ) -> Result { + rustls::crypto::verify_tls13_signature( + message, + cert, + dss, + &self.provider.signature_verification_algorithms, + ) + } + + fn supported_verify_schemes(&self) -> Vec { + self.provider + .signature_verification_algorithms + .supported_schemes() + } +} + +#[derive(Debug)] +pub struct NoCertificateVerification(Arc); + +impl rustls::client::danger::ServerCertVerifier for NoCertificateVerification { + fn verify_server_cert( + &self, + _end_entity: &CertificateDer<'_>, + _intermediates: &[CertificateDer<'_>], + _server_name: &rustls::pki_types::ServerName<'_>, + _ocsp: &[u8], + _now: rustls::pki_types::UnixTime, + ) -> Result { + Ok(rustls::client::danger::ServerCertVerified::assertion()) + } + + fn verify_tls12_signature( + &self, + message: &[u8], + cert: &CertificateDer<'_>, + dss: &rustls::DigitallySignedStruct, + ) -> Result { + rustls::crypto::verify_tls12_signature( + message, + cert, + dss, + &self.0.signature_verification_algorithms, + ) + } + + fn verify_tls13_signature( + &self, + message: &[u8], + cert: &CertificateDer<'_>, + dss: &rustls::DigitallySignedStruct, + ) -> Result { + rustls::crypto::verify_tls13_signature( + message, + cert, + dss, + &self.0.signature_verification_algorithms, + ) + } + + fn supported_verify_schemes(&self) -> Vec { + self.0.signature_verification_algorithms.supported_schemes() + } +} diff --git a/web-transport-moq/src/connect.rs b/web-transport-moq/src/connect.rs new file mode 100644 index 0000000000..4307355d3f --- /dev/null +++ b/web-transport-moq/src/connect.rs @@ -0,0 +1,158 @@ +use std::ops::Deref; + +use web_transport_proto::{ConnectRequest, ConnectResponse, VarInt}; + +use thiserror::Error; + +#[derive(Error, Debug, Clone)] +pub enum ConnectError { + #[error("quic stream was closed early")] + UnexpectedEnd, + + #[error("protocol error: {0}")] + ProtoError(#[from] web_transport_proto::ConnectError), + + #[error("connection error")] + ConnectionError(#[from] noq::ConnectionError), + + #[error("read error")] + ReadError(#[from] noq::ReadError), + + #[error("write error")] + WriteError(#[from] noq::WriteError), + + #[error("http error status: {0}")] + ErrorStatus(http::StatusCode), + + #[error("server returned protocol not in request: {0}")] + ProtocolMismatch(String), +} + +/// An HTTP/3 CONNECT request/response for establishing a WebTransport session. +pub struct Connecting { + // The request that was sent by the client. + pub request: ConnectRequest, + + // A reference to the send/recv stream, so we don't close it until dropped. + pub(crate) send: noq::SendStream, + pub(crate) recv: noq::RecvStream, +} + +impl Connecting { + pub async fn accept(conn: &noq::Connection) -> Result { + // Accept the stream that will be used to send the HTTP CONNECT request. + // If they try to send any other type of HTTP request, we will error out. + let (send, mut recv) = conn.accept_bi().await?; + + let request = web_transport_proto::ConnectRequest::read(&mut recv).await?; + tracing::debug!(?request, "received CONNECT request"); + + // The request was successfully decoded, so we can send a response. + Ok(Self { + request, + send, + recv, + }) + } + + // Called by the server to send a response to the client and establish the session. + pub async fn respond( + mut self, + response: impl Into, + ) -> Result { + let response = response.into(); + + // Validate that our protocol was in the client's request. + if let Some(protocol) = &response.protocol { + if !self.request.protocols.contains(protocol) { + return Err(ConnectError::ProtocolMismatch(protocol.clone())); + } + } + + tracing::debug!(?response, "sending CONNECT response"); + response.write(&mut self.send).await?; + + Ok(Connected { + request: self.request, + response, + send: self.send, + recv: self.recv, + }) + } + + pub async fn reject(self, status: http::StatusCode) -> Result<(), ConnectError> { + let mut connect = self.respond(status).await?; + connect.send.finish().ok(); + Ok(()) + } +} + +impl Deref for Connecting { + type Target = ConnectRequest; + + fn deref(&self) -> &Self::Target { + &self.request + } +} + +pub struct Connected { + // The request that was sent by the client. + pub request: ConnectRequest, + + // The response sent by the server. + pub response: ConnectResponse, + + // A reference to the send/recv stream, so we don't close it until dropped. + pub(crate) send: noq::SendStream, + pub(crate) recv: noq::RecvStream, +} + +impl Connected { + /// Open a new WebTransport session on the given connection for the given URL. + /// + /// You may add any number of subprotocols allowing the server to select from. + /// If the list is empty the field will be omitted in the request header. + pub async fn open( + conn: &noq::Connection, + request: impl Into, + ) -> Result { + let request = request.into(); + + // Create a new stream that will be used to send the CONNECT frame. + let (mut send, mut recv) = conn.open_bi().await?; + + tracing::debug!(?request, "sending CONNECT request"); + request.write(&mut send).await?; + + let response = web_transport_proto::ConnectResponse::read(&mut recv).await?; + tracing::debug!(?response, "received CONNECT response"); + + // Throw an error if we didn't get a 200 OK. + if response.status != http::StatusCode::OK { + return Err(ConnectError::ErrorStatus(response.status)); + } + + // Validate that the server's protocol was in our request. + if let Some(protocol) = &response.protocol { + if !request.protocols.contains(protocol) { + return Err(ConnectError::ProtocolMismatch(protocol.clone())); + } + } + + Ok(Self { + request, + response, + send, + recv, + }) + } + + // The session ID is the stream ID of the CONNECT request. + pub fn session_id(&self) -> VarInt { + // We gotta convert from the Noq VarInt to the (forked) WebTransport VarInt. + // We don't use the noq::VarInt because that would mean a noq dependency in + // web-transport-proto + let stream_id = noq::VarInt::from(self.send.id()); + VarInt::try_from(stream_id.into_inner()).unwrap() + } +} diff --git a/web-transport-moq/src/crypto.rs b/web-transport-moq/src/crypto.rs new file mode 100644 index 0000000000..1b8bb8ecf1 --- /dev/null +++ b/web-transport-moq/src/crypto.rs @@ -0,0 +1,67 @@ +//! Simple crypto provider utilities for rustls. +//! +//! This module provides helper functions for working with rustls crypto providers, +//! supporting both ring and aws-lc-rs backends. + +use std::sync::Arc; + +use rustls::crypto::hash::{self, HashAlgorithm}; +use rustls::crypto::CryptoProvider; +use rustls::pki_types::CertificateDer; + +/// A shared reference to a crypto provider. +pub type Provider = Arc; + +/// Returns the default crypto provider. +/// +/// This function checks for a process-wide default provider first, +/// then falls back to feature-enabled providers (aws-lc-rs or ring). +/// +/// # Panics +/// +/// Panics if no provider is available. Either call `CryptoProvider::set_default()` +/// or enable exactly one of the `ring` or `aws-lc-rs` features. +pub fn default_provider() -> Provider { + // See + if let Some(provider) = CryptoProvider::get_default().cloned() { + return provider; + } + + #[cfg(all(feature = "aws-lc-rs", not(feature = "ring")))] + { + return Arc::new(rustls::crypto::aws_lc_rs::default_provider()); + } + #[cfg(all(feature = "ring", not(feature = "aws-lc-rs")))] + { + return Arc::new(rustls::crypto::ring::default_provider()); + } + #[allow(unreachable_code)] + { + panic!( + "CryptoProvider::set_default() must be called; or only enable one ring/aws-lc-rs feature." + ); + } +} + +/// Computes the SHA-256 hash of a certificate using the provided crypto provider. +/// +/// # Panics +/// +/// Panics if the provider doesn't expose a SHA-256 hash algorithm. +pub fn sha256(provider: &Provider, cert: &CertificateDer<'_>) -> hash::Output { + let hash_provider = provider.cipher_suites.iter().find_map(|suite| { + let hash_provider = suite.tls13()?.common.hash_provider; + if hash_provider.algorithm() == HashAlgorithm::SHA256 { + Some(hash_provider) + } else { + None + } + }); + if let Some(hash_provider) = hash_provider { + return hash_provider.hash(cert); + } + + panic!( + "No SHA-256 backend available. Ensure your provider exposes SHA-256 or enable the 'ring'/'aws-lc-rs' feature." + ); +} diff --git a/web-transport-moq/src/error.rs b/web-transport-moq/src/error.rs new file mode 100644 index 0000000000..bb1c9ca862 --- /dev/null +++ b/web-transport-moq/src/error.rs @@ -0,0 +1,297 @@ +use std::sync::Arc; + +use thiserror::Error; + +use crate::{ConnectError, SettingsError}; + +/// An error returned when connecting to a WebTransport endpoint. +#[derive(Error, Debug, Clone)] +pub enum ClientError { + #[error("unexpected end of stream")] + UnexpectedEnd, + + #[error("connection error: {0}")] + Connection(#[from] noq::ConnectionError), + + #[error("failed to write: {0}")] + WriteError(#[from] noq::WriteError), + + #[error("failed to read: {0}")] + ReadError(#[from] noq::ReadError), + + #[error("failed to exchange h3 settings: {0}")] + SettingsError(#[from] SettingsError), + + #[error("failed to exchange h3 connect: {0}")] + HttpError(#[from] ConnectError), + + #[error("quic error: {0}")] + NoqError(#[from] noq::ConnectError), + + #[error("invalid DNS name: {0}")] + InvalidDnsName(String), + + #[cfg(any(feature = "aws-lc-rs", feature = "ring"))] + #[error("rustls error: {0}")] + Rustls(#[from] rustls::Error), +} + +/// An errors returned by [`crate::Session`], split based on if they are underlying QUIC errors or +/// WebTransport errors. +#[derive(Clone, Error, Debug)] +pub enum SessionError { + #[error("connection error: {0}")] + ConnectionError(noq::ConnectionError), + + #[error("webtransport error: {0}")] + WebTransportError(#[from] WebTransportError), + + #[error("send datagram error: {0}")] + SendDatagramError(#[from] noq::SendDatagramError), +} + +impl From for SessionError { + fn from(e: noq::ConnectionError) -> Self { + match &e { + noq::ConnectionError::ApplicationClosed(close) => { + match web_transport_proto::error_from_http3(close.error_code.into_inner()) { + Some(code) => WebTransportError::Closed( + code, + String::from_utf8_lossy(&close.reason).into_owned(), + ) + .into(), + None => SessionError::ConnectionError(e), + } + } + _ => SessionError::ConnectionError(e), + } + } +} + +/// An error that can occur when reading/writing the WebTransport stream header. +#[derive(Clone, Error, Debug)] +pub enum WebTransportError { + #[error("closed: code={0} reason={1}")] + Closed(u32, String), + + #[error("unknown session")] + UnknownSession, + + #[error("read error: {0}")] + ReadError(#[from] noq::ReadExactError), + + #[error("write error: {0}")] + WriteError(#[from] noq::WriteError), +} + +/// An error when writing to [`crate::SendStream`]. Similar to [`noq::WriteError`]. +#[derive(Clone, Error, Debug)] +pub enum WriteError { + #[error("STOP_SENDING: {0}")] + Stopped(u32), + + #[error("invalid STOP_SENDING: {0}")] + InvalidStopped(noq::VarInt), + + #[error("session error: {0}")] + SessionError(#[from] SessionError), + + #[error("stream closed")] + ClosedStream, +} + +impl From for WriteError { + fn from(e: noq::WriteError) -> Self { + match e { + noq::WriteError::Stopped(code) => { + match web_transport_proto::error_from_http3(code.into_inner()) { + Some(code) => WriteError::Stopped(code), + None => WriteError::InvalidStopped(code), + } + } + noq::WriteError::ClosedStream => WriteError::ClosedStream, + noq::WriteError::ConnectionLost(e) => WriteError::SessionError(e.into()), + noq::WriteError::ZeroRttRejected => unreachable!("0-RTT not supported"), + } + } +} + +/// An error when reading from [`crate::RecvStream`]. Similar to [`noq::ReadError`]. +#[derive(Clone, Error, Debug)] +pub enum ReadError { + #[error("session error: {0}")] + SessionError(#[from] SessionError), + + #[error("RESET_STREAM: {0}")] + Reset(u32), + + #[error("invalid RESET_STREAM: {0}")] + InvalidReset(noq::VarInt), + + #[error("stream already closed")] + ClosedStream, +} + +impl From for ReadError { + fn from(value: noq::ReadError) -> Self { + match value { + noq::ReadError::Reset(code) => { + match web_transport_proto::error_from_http3(code.into_inner()) { + Some(code) => ReadError::Reset(code), + None => ReadError::InvalidReset(code), + } + } + noq::ReadError::ConnectionLost(e) => ReadError::SessionError(e.into()), + noq::ReadError::ClosedStream => ReadError::ClosedStream, + noq::ReadError::ZeroRttRejected => unreachable!("0-RTT not supported"), + } + } +} + +/// An error returned by [`crate::RecvStream::read_exact`]. Similar to [`noq::ReadExactError`]. +#[derive(Clone, Error, Debug)] +pub enum ReadExactError { + #[error("finished early")] + FinishedEarly(usize), + + #[error("read error: {0}")] + ReadError(#[from] ReadError), +} + +impl From for ReadExactError { + fn from(e: noq::ReadExactError) -> Self { + match e { + noq::ReadExactError::FinishedEarly(size) => ReadExactError::FinishedEarly(size), + noq::ReadExactError::ReadError(e) => ReadExactError::ReadError(e.into()), + } + } +} + +/// An error returned by [`crate::RecvStream::read_to_end`]. Similar to [`noq::ReadToEndError`]. +#[derive(Clone, Error, Debug)] +pub enum ReadToEndError { + #[error("too long")] + TooLong, + + #[error("read error: {0}")] + ReadError(#[from] ReadError), +} + +impl From for ReadToEndError { + fn from(e: noq::ReadToEndError) -> Self { + match e { + noq::ReadToEndError::TooLong => ReadToEndError::TooLong, + noq::ReadToEndError::Read(e) => ReadToEndError::ReadError(e.into()), + } + } +} + +/// An error indicating the stream was already closed. +#[derive(Clone, Error, Debug)] +#[error("stream closed")] +pub struct ClosedStream; + +impl From for ClosedStream { + fn from(_: noq::ClosedStream) -> Self { + ClosedStream + } +} + +/// An error returned when receiving a new WebTransport session. +#[derive(Error, Debug, Clone)] +pub enum ServerError { + #[error("unexpected end of stream")] + UnexpectedEnd, + + #[error("connection error")] + Connection(#[from] noq::ConnectionError), + + #[error("failed to write")] + WriteError(#[from] noq::WriteError), + + #[error("failed to read")] + ReadError(#[from] noq::ReadError), + + #[error("failed to exchange h3 settings")] + SettingsError(#[from] SettingsError), + + #[error("failed to exchange h3 connect")] + ConnectError(#[from] ConnectError), + + #[error("io error: {0}")] + IoError(Arc), + + #[cfg(any(feature = "aws-lc-rs", feature = "ring"))] + #[error("rustls error: {0}")] + Rustls(#[from] rustls::Error), +} + +// #[derive(Clone, Error, Debug)] +// pub enum SendDatagramError { +// #[error("Unsupported peer")] +// UnsupportedPeer, + +// #[error("Datagram support Disabled by peer")] +// DatagramSupportDisabled, + +// #[error("Datagram Too large")] +// TooLarge, + +// #[error("Session errorr: {0}")] +// SessionError(#[from] SessionError), +// } + +// impl From for SendDatagramError { +// fn from(value: noq::SendDatagramError) -> Self { +// match value { +// noq::SendDatagramError::UnsupportedByPeer => SendDatagramError::UnsupportedPeer, +// noq::SendDatagramError::Disabled => SendDatagramError::DatagramSupportDisabled, +// noq::SendDatagramError::TooLarge => SendDatagramError::TooLarge, +// noq::SendDatagramError::ConnectionLost(e) => +// SendDatagramError::SessionError(e.into()), } +// } +// } + +impl web_transport_trait::Error for SessionError { + fn session_error(&self) -> Option<(u32, String)> { + if let SessionError::WebTransportError(WebTransportError::Closed(code, reason)) = self { + return Some((*code, reason.to_string())); + } + + None + } +} + +impl web_transport_trait::Error for WriteError { + fn session_error(&self) -> Option<(u32, String)> { + if let WriteError::SessionError(e) = self { + return e.session_error(); + } + + None + } + + fn stream_error(&self) -> Option { + match self { + WriteError::Stopped(code) => Some(*code), + _ => None, + } + } +} + +impl web_transport_trait::Error for ReadError { + fn session_error(&self) -> Option<(u32, String)> { + if let ReadError::SessionError(e) = self { + return e.session_error(); + } + + None + } + + fn stream_error(&self) -> Option { + match self { + ReadError::Reset(code) => Some(*code), + _ => None, + } + } +} diff --git a/web-transport-moq/src/lib.rs b/web-transport-moq/src/lib.rs new file mode 100644 index 0000000000..576a94b568 --- /dev/null +++ b/web-transport-moq/src/lib.rs @@ -0,0 +1,74 @@ +//! WebTransport is a protocol for client-server communication over QUIC. +//! It's [available in the browser](https://caniuse.com/webtransport) as an alternative to HTTP and WebSockets. +//! +//! WebTransport is layered on top of HTTP/3 which is then layered on top of QUIC. +//! This library hides that detail and tries to expose only the QUIC API, delegating as much as +//! possible to the underlying implementation. See the [Noq documentation](https://docs.rs/moq-noq/latest/moq_noq/) for more documentation. +//! +//! QUIC provides two primary APIs: +//! +//! # Streams +//! QUIC streams are ordered, reliable, flow-controlled, and optionally bidirectional. +//! Both endpoints can create and close streams (including an error code) with no overhead. +//! You can think of them as TCP connections, but shared over a single QUIC connection. +//! +//! # Datagrams +//! 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. +//! +//! # Limitations +//! WebTransport is able to be pooled with HTTP/3 and multiple WebTransport sessions. +//! This crate avoids that complexity, doing the bare minimum to support a single WebTransport +//! session that owns the entire QUIC connection. If you want to support HTTP/3 on the same +//! host/port, you should use another crate (ex. `h3-webtransport`). If you want to support multiple +//! WebTransport sessions over the same QUIC connection... you should just dial a new QUIC +//! connection instead. + +// External +mod client; +mod error; +mod recv; +mod send; +mod server; +mod session; + +pub use client::*; +pub use error::*; +pub use recv::*; +pub use send::*; +pub use server::*; +pub use session::*; + +// Internal +mod connect; +mod settings; + +use connect::*; +use settings::*; + +// Required to access web_transport_moq::proto::ConnectError wrapped in ClientError +pub use connect::ConnectError; + +/// The HTTP/3 ALPN is required when negotiating a QUIC connection. +pub const ALPN: &str = "h3"; + +/// Export our simple crypto provider. +pub mod crypto; + +/// Re-export the underlying QUIC implementation. +pub use noq; + +/// Re-export the http crate because it's in the public API. +pub use http; + +/// Re-export kio, whose [`Waiter`](kio::Waiter) is how a caller of +/// [`SessionAccept`]'s poll methods holds its place in the accept queue. +pub use kio; + +/// Re-export the generic WebTransport implementation. +pub use web_transport_trait as generic; + +/// Re-export the WebTransport protocol implementation. +pub use web_transport_proto as proto; diff --git a/web-transport-moq/src/recv.rs b/web-transport-moq/src/recv.rs new file mode 100644 index 0000000000..fa0da21040 --- /dev/null +++ b/web-transport-moq/src/recv.rs @@ -0,0 +1,159 @@ +use std::{ + io, + pin::Pin, + sync::{Arc, OnceLock}, + task::{Context, Poll}, +}; + +use bytes::Bytes; + +use crate::{ClosedStream, ReadError, ReadExactError, ReadToEndError, SessionError}; + +/// A stream that can be used to receive bytes. See [`noq::RecvStream`]. +#[derive(Debug)] +pub struct RecvStream { + inner: noq::RecvStream, + error: Arc>, +} + +impl RecvStream { + pub(crate) fn new(stream: noq::RecvStream, error: Arc>) -> Self { + Self { + inner: stream, + error, + } + } + + /// Replace connection-level errors with the stored session error if available. + fn map_error(&self, e: impl Into) -> ReadError { + let e = e.into(); + if let Some(err) = self.error.get() { + if matches!(&e, ReadError::SessionError(_)) { + return ReadError::SessionError(err.clone()); + } + } + e + } + + /// Tell the other end to stop sending data with the given error code. See + /// [`noq::RecvStream::stop`]. This is a u32 with WebTransport since it shares the error + /// space with HTTP/3. + pub fn stop(&mut self, code: u32) -> Result<(), noq::ClosedStream> { + let code = web_transport_proto::error_to_http3(code); + let code = noq::VarInt::try_from(code).unwrap(); + self.inner.stop(code) + } + + // Unfortunately, we have to wrap ReadError for a bunch of functions. + + /// Read some data into the buffer and return the amount read. See [`noq::RecvStream::read`]. + pub async fn read(&mut self, buf: &mut [u8]) -> Result, ReadError> { + self.inner.read(buf).await.map_err(|e| self.map_error(e)) + } + + /// Fill the entire buffer with data. See [`noq::RecvStream::read_exact`]. + pub async fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), ReadExactError> { + self.inner.read_exact(buf).await.map_err(|e| match e { + noq::ReadExactError::ReadError(e) => self.map_error(e).into(), + e => e.into(), + }) + } + + /// Read a chunk of data from the stream. See [`noq::RecvStream::read_chunk`]. + pub async fn read_chunk(&mut self, max_length: usize) -> Result, ReadError> { + self.inner + .read_chunk(max_length) + .await + .map_err(|e| self.map_error(e)) + } + + /// Read chunks of data from the stream. See [`noq::RecvStream::read_many_chunks`]. + pub async fn read_many_chunks( + &mut self, + bufs: &mut [Bytes], + ) -> Result, ReadError> { + self.inner + .read_many_chunks(bufs) + .await + .map_err(|e| self.map_error(e)) + } + + /// Read until the end of the stream or the limit is hit. See [`noq::RecvStream::read_to_end`]. + pub async fn read_to_end(&mut self, size_limit: usize) -> Result, ReadToEndError> { + self.inner + .read_to_end(size_limit) + .await + .map_err(|e| match e { + noq::ReadToEndError::Read(e) => self.map_error(e).into(), + e => e.into(), + }) + } + + /// Block until the stream has been reset and return the error code. See + /// [`noq::RecvStream::received_reset`]. + /// + /// Unlike Noq, this returns a SessionError, not a ResetError, because 0-RTT is not supported. + pub async fn received_reset(&mut self) -> Result, SessionError> { + match self.inner.received_reset().await { + Ok(None) => Ok(None), + Ok(Some(code)) => Ok(web_transport_proto::error_from_http3(code.into_inner())), + Err(noq::ResetError::ConnectionLost(conn_err)) => { + Err(self.error.get().cloned().unwrap_or_else(|| conn_err.into())) + } + Err(noq::ResetError::ZeroRttRejected) => unreachable!("0-RTT not supported"), + } + } + + /// Return the underlying QUIC stream ID. + /// + /// > **Warning** + /// > + /// > WebTransport sessions share the QUIC connection with HTTP/3 and potentially other + /// > sessions. + /// > The [noq::StreamId::index] might not increment by 1 like expected when using [noq]. + /// > This is why the Javascript WebTransport API does not expose the Stream ID. + pub fn quic_id(&self) -> noq::StreamId { + self.inner.id() + } + + /// Returns the number of bytes read from this stream. + /// + /// This is the offset of the next byte to be read, i.e. the length of the contiguous + /// prefix of the stream consumed by the application. + pub fn bytes_read(&self) -> Result { + self.inner.bytes_read().map_err(|_| ClosedStream) + } + + // We purposely don't expose the 0RTT because it's not valid with WebTransport +} + +impl tokio::io::AsyncRead for RecvStream { + fn poll_read( + mut self: Pin<&mut Self>, + cx: &mut Context<'_>, + buf: &mut tokio::io::ReadBuf, + ) -> Poll> { + Pin::new(&mut self.inner).poll_read(cx, buf) + } +} + +impl web_transport_trait::RecvStream for RecvStream { + type Error = ReadError; + + fn stop(&mut self, code: u32) { + Self::stop(self, code).ok(); + } + + async fn read(&mut self, dst: &mut [u8]) -> Result, Self::Error> { + self.read(dst).await + } + + async fn read_chunk(&mut self, max: usize) -> Result, Self::Error> { + self.read_chunk(max).await + } + + async fn closed(&mut self) -> Result<(), Self::Error> { + self.received_reset().await?; + Ok(()) + } +} diff --git a/web-transport-moq/src/send.rs b/web-transport-moq/src/send.rs new file mode 100644 index 0000000000..0e67d64cf8 --- /dev/null +++ b/web-transport-moq/src/send.rs @@ -0,0 +1,194 @@ +use std::{ + io, + pin::Pin, + sync::{Arc, OnceLock}, + task::{Context, Poll}, +}; + +use bytes::{Buf, Bytes}; + +use crate::{ClosedStream, SessionError, WriteError}; + +/// A stream that can be used to send bytes. See [`noq::SendStream`]. +/// +/// This wrapper is mainly needed for error codes, which is unfortunate. +/// WebTransport uses u32 error codes and they're mapped in a reserved HTTP/3 error space. +#[derive(Debug)] +pub struct SendStream { + stream: noq::SendStream, + error: Arc>, +} + +impl SendStream { + pub(crate) fn new(stream: noq::SendStream, error: Arc>) -> Self { + Self { stream, error } + } + + /// Replace connection-level errors with the stored session error if available. + fn map_error(&self, e: impl Into) -> WriteError { + let e = e.into(); + if let Some(err) = self.error.get() { + if matches!(&e, WriteError::SessionError(_)) { + return WriteError::SessionError(err.clone()); + } + } + e + } + + /// Abruptly reset the stream with the provided error code. See [`noq::SendStream::reset`]. + /// This is a u32 with WebTransport because we share the error space with HTTP/3. + pub fn reset(&mut self, code: u32) -> Result<(), ClosedStream> { + let code = web_transport_proto::error_to_http3(code); + let code = noq::VarInt::try_from(code).unwrap(); + self.stream.reset(code).map_err(Into::into) + } + + /// Wait until the stream has been stopped and return the error code. See + /// [`noq::SendStream::stopped`]. + /// + /// Unlike Noq, this returns None if the code is not a valid WebTransport error code. + /// Also unlike Noq, this returns a SessionError, not a StoppedError, because 0-RTT is not + /// supported. + pub async fn stopped(&self) -> Result, SessionError> { + match self.stream.stopped().await { + Ok(Some(code)) => Ok(web_transport_proto::error_from_http3(code.into_inner())), + Ok(None) => Ok(None), + Err(noq::StoppedError::ConnectionLost(conn_err)) => { + Err(self.error.get().cloned().unwrap_or_else(|| conn_err.into())) + } + Err(noq::StoppedError::ZeroRttRejected) => unreachable!("0-RTT not supported"), + } + } + + // Unfortunately, we have to wrap WriteError for a bunch of functions. + + /// Write some data to the stream, returning the size written. See [`noq::SendStream::write`]. + pub async fn write(&mut self, buf: &[u8]) -> Result { + self.stream.write(buf).await.map_err(|e| self.map_error(e)) + } + + /// Write all of the data to the stream. See [`noq::SendStream::write_all`]. + pub async fn write_all(&mut self, buf: &[u8]) -> Result<(), WriteError> { + self.stream + .write_all(buf) + .await + .map_err(|e| self.map_error(e)) + } + + /// Write chunks of data to the stream, returning the number of bytes written. + /// + /// See [`noq::SendStream::write_many_chunks`]. + pub async fn write_many_chunks( + &mut self, + bufs: &mut &mut [Bytes], + ) -> Result { + self.stream + .write_many_chunks(bufs) + .await + .map_err(|e| self.map_error(e)) + } + + /// Write a chunk of data to the stream. See [`noq::SendStream::write_chunk`]. + pub async fn write_chunk(&mut self, buf: Bytes) -> Result<(), WriteError> { + self.stream + .write_chunk(buf) + .await + .map_err(|e| self.map_error(e)) + } + + /// Write all of the chunks of data to the stream. See [`noq::SendStream::write_all_chunks`]. + pub async fn write_all_chunks(&mut self, bufs: &mut [Bytes]) -> Result<(), WriteError> { + self.stream + .write_all_chunks(bufs) + .await + .map_err(|e| self.map_error(e)) + } + + /// Mark the stream as finished, such that no more data can be written. See + /// [`noq::SendStream::finish`]. + /// + /// WARNING: This is implicitly called on Drop, but it's a common footgun in Noq. + /// If you cancel futures by dropping them you'll get incomplete writes. + pub fn finish(&mut self) -> Result<(), ClosedStream> { + self.stream.finish().map_err(Into::into) + } + + pub fn set_priority(&self, order: i32) -> Result<(), ClosedStream> { + self.stream.set_priority(order).map_err(Into::into) + } + + pub fn priority(&self) -> Result { + self.stream.priority().map_err(Into::into) + } + + /// Return the underlying QUIC stream ID. + /// + /// > **Warning** + /// > + /// > WebTransport sessions share the QUIC connection with HTTP/3 and potentially other + /// > sessions. + /// > The [noq::StreamId::index] might not increment by 1 like expected when using [noq]. + /// > This is why the Javascript WebTransport API does not expose the Stream ID. + pub fn quic_id(&self) -> noq::StreamId { + self.stream.id() + } +} + +impl tokio::io::AsyncWrite for SendStream { + fn poll_write( + mut self: Pin<&mut Self>, + cx: &mut Context<'_>, + buf: &[u8], + ) -> Poll> { + // We have to use this syntax because noq added its own poll_write method. + tokio::io::AsyncWrite::poll_write(Pin::new(&mut self.stream), cx, buf) + } + + fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll> { + Pin::new(&mut self.stream).poll_flush(cx) + } + + fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll> { + Pin::new(&mut self.stream).poll_shutdown(cx) + } +} + +impl web_transport_trait::SendStream for SendStream { + type Error = WriteError; + + fn set_priority(&mut self, order: u8) { + Self::set_priority(self, order.into()).ok(); + } + + fn reset(&mut self, code: u32) { + Self::reset(self, code).ok(); + } + + fn finish(&mut self) -> Result<(), Self::Error> { + Self::finish(self).map_err(|_| WriteError::ClosedStream) + } + + async fn write(&mut self, buf: &[u8]) -> Result { + Self::write(self, buf).await + } + + async fn write_buf(&mut self, buf: &mut B) -> Result { + // This can avoid making a copy when Buf is Bytes, as Noq will allocate anyway. + let size = buf.chunk().len(); + let chunk = buf.copy_to_bytes(size); + self.write_chunk(chunk).await?; + Ok(size) + } + + async fn write_chunk(&mut self, chunk: Bytes) -> Result<(), Self::Error> { + self.write_chunk(chunk).await + } + + async fn closed(&mut self) -> Result<(), Self::Error> { + // NOTE: This used to require &mut in an older version of Noq. + match self.stopped().await? { + Some(code) => Err(WriteError::Stopped(code)), + None => Ok(()), + } + } +} diff --git a/web-transport-moq/src/server.rs b/web-transport-moq/src/server.rs new file mode 100644 index 0000000000..8af3e81c98 --- /dev/null +++ b/web-transport-moq/src/server.rs @@ -0,0 +1,200 @@ +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +use std::sync::Arc; + +use futures::{future::BoxFuture, stream::FuturesUnordered, StreamExt}; +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +use rustls::pki_types::{CertificateDer, PrivateKeyDer}; + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +use crate::{crypto, CongestionControl}; +use crate::{ + proto::{ConnectRequest, ConnectResponse}, + Connecting, ServerError, Session, Settings, +}; + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +/// Construct a WebTransport [Server] using sane defaults. +/// +/// This is optional; advanced users may use [Server::new] directly. +pub struct ServerBuilder { + provider: crypto::Provider, + addr: std::net::SocketAddr, + congestion_controller: + Option>, +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl Default for ServerBuilder { + fn default() -> Self { + Self::new() + } +} + +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +impl ServerBuilder { + /// Create a server builder with sane defaults. + pub fn new() -> Self { + Self { + provider: crypto::default_provider(), + addr: "[::]:443".parse().unwrap(), + congestion_controller: None, + } + } + + /// Listen on the specified address. + pub fn with_addr(self, addr: std::net::SocketAddr) -> Self { + Self { addr, ..self } + } + + /// Enable the specified congestion controller. + pub fn with_congestion_control(mut self, algorithm: CongestionControl) -> Self { + self.congestion_controller = match algorithm { + CongestionControl::LowLatency => Some(Arc::new(noq::congestion::Bbr3Config::default())), + // TODO BBR is also higher throughput in theory. + CongestionControl::Throughput => { + Some(Arc::new(noq::congestion::CubicConfig::default())) + } + CongestionControl::Default => None, + }; + + self + } + + /// Supply a certificate used for TLS. + // TODO support multiple certs based on...? + pub fn with_certificate( + self, + chain: Vec>, + key: PrivateKeyDer<'static>, + ) -> Result { + // Standard Noq setup + let mut config = rustls::ServerConfig::builder_with_provider(self.provider.clone()) + .with_protocol_versions(&[&rustls::version::TLS13])? + .with_no_client_auth() + .with_single_cert(chain, key)?; + + config.alpn_protocols = vec![crate::ALPN.as_bytes().to_vec()]; // this one is important + + let config: noq::crypto::rustls::QuicServerConfig = config.try_into().unwrap(); + let config = noq::ServerConfig::with_crypto(Arc::new(config)); + + let server = + noq::Endpoint::server(config, self.addr).map_err(|e| ServerError::IoError(e.into()))?; + + Ok(Server::new(server)) + } +} + +/// A WebTransport server that accepts new sessions. +pub struct Server { + endpoint: noq::Endpoint, + accept: FuturesUnordered>>, +} + +impl core::ops::Deref for Server { + type Target = noq::Endpoint; + + fn deref(&self) -> &Self::Target { + &self.endpoint + } +} + +impl Server { + /// Manually create a new server with a manually constructed Endpoint. + /// + /// NOTE: The ALPN must be set to `crate::ALPN` for WebTransport to work. + pub fn new(endpoint: noq::Endpoint) -> Self { + Self { + endpoint, + accept: Default::default(), + } + } + + /// Accept a new WebTransport session Request from a client. + pub async fn accept(&mut self) -> Option { + loop { + tokio::select! { + res = self.endpoint.accept() => { + let conn = res?; + self.accept.push(Box::pin(async move { + let conn = conn.await?; + Request::accept(conn).await + })); + } + Some(res) = self.accept.next() => { + if let Ok(session) = res { + return Some(session) + } + } + } + } + } +} + +/// A mostly complete WebTransport handshake, just awaiting the server's decision on whether to +/// accept or reject the session based on the URL. +pub struct Request { + conn: noq::Connection, + settings: Settings, + connect: Connecting, +} + +impl Request { + /// Accept a new WebTransport session from a client. + pub async fn accept(conn: noq::Connection) -> Result { + // Perform the H3 handshake by sending/reciving SETTINGS frames. + let settings = Settings::connect(&conn).await?; + + // Accept the CONNECT request but don't send a response yet. + let connect = Connecting::accept(&conn).await?; + + // Return the resulting request with a reference to the settings/connect streams. + Ok(Self { + conn, + settings, + connect, + }) + } + + pub async fn ok(self) -> Result { + self.respond(ConnectResponse::OK).await + } + + /// Reply to the session with the given response, usually 200 OK. + /// + /// [ConnectResponse::with_protocol] can be used to select a subprotocol. + pub async fn respond( + self, + response: impl Into, + ) -> Result { + let response = response.into(); + let connect = self.connect.respond(response).await?; + Ok(Session::new(self.conn, self.settings, connect)) + } + + /// Reject the session with the given status code. + pub async fn reject(self, status: http::StatusCode) -> Result<(), ServerError> { + self.connect.reject(status).await?; + Ok(()) + } + + /// Returns the underlying QUIC connection. + pub fn conn(&self) -> &noq::Connection { + &self.conn + } + + /// Returns the CONNECT request that was sent by the client. + /// + /// DEPRECATED: You can access this via the Deref impl. + pub fn connect(&self) -> &ConnectRequest { + &self.connect + } +} + +impl core::ops::Deref for Request { + type Target = ConnectRequest; + + fn deref(&self) -> &Self::Target { + &self.connect + } +} diff --git a/web-transport-moq/src/session.rs b/web-transport-moq/src/session.rs new file mode 100644 index 0000000000..65314070dd --- /dev/null +++ b/web-transport-moq/src/session.rs @@ -0,0 +1,1039 @@ +use std::{ + fmt, + future::Future, + io::Cursor, + ops::Deref, + pin::Pin, + sync::{Arc, Mutex, OnceLock}, + task::{Context, Poll, Waker}, + time::Duration, +}; + +use bytes::{Bytes, BytesMut}; +use futures::stream::{FuturesUnordered, Stream, StreamExt}; +use kio::{Fan, Waiter}; + +use crate::{ + proto::{ConnectRequest, ConnectResponse, Frame, StreamUni, VarInt}, + ClientError, Connected, RecvStream, SendStream, SessionError, Settings, WebTransportError, +}; + +/// The ALPN the QUIC handshake negotiated, or `None` if there was none, the handshake +/// has not completed, or it is not valid UTF-8. +/// +/// Noq only exposes the ALPN via a downcast of the boxed handshake data, so the result +/// is owned rather than borrowed from the connection. +#[cfg(any(feature = "aws-lc-rs", feature = "ring"))] +fn negotiated_alpn(conn: &noq::Connection) -> Option { + let data = conn.handshake_data()?; + let data = data.downcast::().ok()?; + + String::from_utf8(data.protocol?).ok() +} + +/// `noq::crypto::rustls` only exists once a TLS backend is enabled, so there is no +/// handshake data type to name here. +/// +/// This crate's own builders are gated the same way, so normally there is no connection +/// to read an ALPN from either. A caller that enables a provider on `noq` directly and +/// brings its own endpoint can still establish one, and [`Session::protocol`] reports +/// `None` for those raw sessions. Enable this crate's `aws-lc-rs` or `ring` feature to +/// get the ALPN. +#[cfg(not(any(feature = "aws-lc-rs", feature = "ring")))] +fn negotiated_alpn(_conn: &noq::Connection) -> Option { + None +} + +/// An established WebTransport session, acting like a full QUIC connection. See +/// [`noq::Connection`]. +/// +/// It is important to remember that WebTransport is layered on top of QUIC: +/// 1. Each stream starts with a few bytes identifying the stream type and session ID. +/// 2. Errors codes are encoded with the session ID, so they aren't full QUIC error codes. +/// 3. Stream IDs may have gaps in them, used by HTTP/3 transparent to the application. +/// +/// Deref is used to expose non-overloaded methods on [`noq::Connection`]. +/// These should be safe to use with WebTransport, but file a PR if you find one that isn't. +#[derive(Clone)] +pub struct Session { + conn: noq::Connection, + + // The session ID, as determined by the stream ID of the connect request. + session_id: Option, + + // The accept logic is stateful, so use an Arc to share it. + accept: Option>>, + + // Cache the headers in front of each stream we open. + header_uni: Vec, + header_bi: Vec, + header_datagram: Vec, + + // Keep a reference to the settings and connect stream to avoid closing them until dropped. + #[allow(dead_code)] + settings: Option>, + + // The send side of the CONNECT stream, used to write the CloseWebTransportSession capsule. + // Wrapped in Arc>> so close() can take it exactly once. + connect_send: Arc>>, + + // Session error, set once by either local close() or the background task + // when a remote CloseWebTransportSession capsule is received. + // Uses OnceLock for set-once, first-writer-wins semantics with lock-free reads. + error: Arc>, + + // The request sent by the client, or None for a raw QUIC session. + request: Option, + + // The response sent by the server, or None for a raw QUIC session. + response: Option, + + // The ALPN negotiated by the QUIC handshake, for raw QUIC sessions. Noq only + // exposes it behind an allocating downcast, so `protocol()` has nothing in the + // connection to borrow from and needs somewhere to keep the result. + // + // Resolved on first read rather than at construction: `raw()` accepts any + // connection, including one whose handshake has not completed and so has no ALPN + // yet. Only a successful read is latched, so an early call cannot pin `None` for + // the life of the session. Shared across clones. + // + // Unused by HTTP/3 sessions, which read the subprotocol out of the response. + alpn: Arc>, +} + +impl Session { + pub(crate) fn new(conn: noq::Connection, settings: Settings, connect: Connected) -> Self { + // The session ID is the stream ID of the CONNECT request. + let session_id = connect.session_id(); + + // Cache the tiny header we write in front of each stream we open. + let mut header_uni = Vec::new(); + StreamUni::WEBTRANSPORT.encode(&mut header_uni); + session_id.encode(&mut header_uni); + + let mut header_bi = Vec::new(); + Frame::WEBTRANSPORT.encode(&mut header_bi); + session_id.encode(&mut header_bi); + + let mut header_datagram = Vec::new(); + session_id.encode(&mut header_datagram); + + let error: Arc> = Arc::new(OnceLock::new()); + + // Accept logic is stateful, so use an Arc to share it. + let accept = SessionAccept::new(conn.clone(), session_id, error.clone()); + + let this = Self { + conn, + accept: Some(Arc::new(Mutex::new(accept))), + session_id: Some(session_id), + header_uni, + header_bi, + header_datagram, + settings: Some(Arc::new(settings)), + connect_send: Arc::new(Mutex::new(Some(connect.send))), + error: error.clone(), + request: Some(connect.request.clone()), + response: Some(connect.response.clone()), + alpn: Default::default(), + }; + + // Run a background task to read capsules from the CONNECT recv stream. + let conn2 = this.conn.clone(); + tokio::spawn(Self::run_recv(conn2, connect.recv, error)); + + this + } + + // Read capsules from the CONNECT recv stream until it's closed, + // then record the close error and tear down the connection. + async fn run_recv( + conn: noq::Connection, + recv: noq::RecvStream, + error: Arc>, + ) { + let close_info = Self::read_capsules(recv).await; + let code = close_info.as_ref().map_or(0, |(c, _)| *c); + + let http3_code: noq::VarInt = web_transport_proto::error_to_http3(code) + .try_into() + .unwrap(); + + // Try to record the remote close error. If close() already set + // the error, it owns the connection teardown, so we bail out. + match close_info { + Some((code, reason)) => { + let err = WebTransportError::Closed(code, reason.clone()); + if error.set(err.into()).is_err() { + return; + } + conn.close(http3_code, reason.as_bytes()); + } + None => { + let err = noq::ConnectionError::LocallyClosed.into(); + if error.set(err).is_err() { + return; + } + conn.close(http3_code, b""); + } + }; + } + + // Keep reading capsules from the CONNECT recv stream until it's closed. + // Returns Some((code, reason)) if a CloseWebTransportSession capsule was received, + // or None if the stream closed without a capsule. + async fn read_capsules(recv: noq::RecvStream) -> Option<(u32, String)> { + let mut reader = web_transport_proto::Http3CapsuleReader::new(recv); + loop { + match reader.read().await { + Ok(Some(web_transport_proto::Capsule::CloseWebTransportSession { + code, + reason, + })) => return Some((code, reason)), + Ok(Some(web_transport_proto::Capsule::Grease { .. })) => {} + Ok(Some(web_transport_proto::Capsule::Unknown { typ, payload })) => { + tracing::warn!(%typ, size = payload.len(), "unknown capsule"); + } + Ok(None) => return None, + Err(e) => { + tracing::warn!(?e, "failed to read capsule"); + return None; + } + } + } + } + + /// Connect using an established QUIC connection if you want to create the connection yourself. + /// This will only work with a brand new QUIC connection using the HTTP/3 ALPN. + pub async fn connect( + conn: noq::Connection, + request: impl Into, + ) -> Result { + let request = request.into(); + + // Perform the H3 handshake by sending/receiving SETTINGS frames. + let settings = Settings::connect(&conn).await?; + + // Send the HTTP/3 CONNECT request. + let connect = Connected::open(&conn, request).await?; + + // Return the resulting session with a reference to the control/connect streams. + // If either stream is closed, then the session will be closed, so we need to keep them + // around. + let session = Session::new(conn, settings, connect); + + Ok(session) + } + + /// Accept a new unidirectional stream. See [`noq::Connection::accept_uni`]. + pub async fn accept_uni(&self) -> Result { + if let Some(accept) = &self.accept { + // `kio::wait` owns the waiter, so dropping this future — a `timeout` that + // expires, say — also drops its registration in `SessionAccept`. + kio::wait(|waiter| poll_accept_uni_shared(accept, waiter)) + .await + .map_err(|e| self.map_error(e)) + } else { + let recv = self + .conn + .accept_uni() + .await + .map_err(|e| self.map_error(e))?; + Ok(RecvStream::new(recv, self.error.clone())) + } + } + + /// Accept a new bidirectional stream. See [`noq::Connection::accept_bi`]. + pub async fn accept_bi(&self) -> Result<(SendStream, RecvStream), SessionError> { + if let Some(accept) = &self.accept { + kio::wait(|waiter| poll_accept_bi_shared(accept, waiter)) + .await + .map_err(|e| self.map_error(e)) + } else { + let (send, recv) = self.conn.accept_bi().await.map_err(|e| self.map_error(e))?; + Ok(( + SendStream::new(send, self.error.clone()), + RecvStream::new(recv, self.error.clone()), + )) + } + } + + /// Open a new unidirectional stream. See [`noq::Connection::open_uni`]. + pub async fn open_uni(&self) -> Result { + let mut send = self.conn.open_uni().await.map_err(|e| self.map_error(e))?; + + // Set the stream priority to max and then write the stream header. + // Otherwise the application could write data with lower priority than the header, resulting + // in queuing. Also the header is very important for determining the session ID + // without reliable reset. + send.set_priority(i32::MAX).ok(); + Self::write_full(&mut send, &self.header_uni) + .await + .map_err(|e| self.map_error(e))?; + + // Reset the stream priority back to the default of 0. + send.set_priority(0).ok(); + Ok(SendStream::new(send, self.error.clone())) + } + + /// Open a new bidirectional stream. See [`noq::Connection::open_bi`]. + pub async fn open_bi(&self) -> Result<(SendStream, RecvStream), SessionError> { + let (mut send, recv) = self.conn.open_bi().await.map_err(|e| self.map_error(e))?; + + // Set the stream priority to max and then write the stream header. + // Otherwise the application could write data with lower priority than the header, resulting + // in queuing. Also the header is very important for determining the session ID + // without reliable reset. + send.set_priority(i32::MAX).ok(); + Self::write_full(&mut send, &self.header_bi) + .await + .map_err(|e| self.map_error(e))?; + + // Reset the stream priority back to the default of 0. + send.set_priority(0).ok(); + Ok(( + SendStream::new(send, self.error.clone()), + RecvStream::new(recv, self.error.clone()), + )) + } + + /// Asynchronously receives an application datagram from the remote peer. + /// + /// This method is used to receive an application datagram sent by the remote + /// peer over the connection. + /// It waits for a datagram to become available and returns the received bytes. + pub async fn read_datagram(&self) -> Result { + let mut datagram = self + .conn + .read_datagram() + .await + .map_err(|e| self.map_error(e))?; + + let mut cursor = Cursor::new(&datagram); + + if let Some(session_id) = self.session_id { + // We have to check and strip the session ID from the datagram. + let actual_id = + VarInt::decode(&mut cursor).map_err(|_| WebTransportError::UnknownSession)?; + if actual_id != session_id { + return Err(WebTransportError::UnknownSession.into()); + } + } + + // Return the datagram without the session ID. + let datagram = datagram.split_off(cursor.position() as usize); + + Ok(datagram) + } + + /// Sends an application datagram to the remote peer. + /// + /// Datagrams are unreliable and may be dropped or delivered out of order. + /// The data must be smaller than [`max_datagram_size`](Self::max_datagram_size). + pub fn send_datagram(&self, data: Bytes) -> Result<(), SessionError> { + let result = if !self.header_datagram.is_empty() { + // Unfortunately, we need to allocate/copy each datagram because of the Noq API. + // Pls go +1 if you care: https://github.com/quinn-rs/quinn/issues/1724 + let mut buf = BytesMut::with_capacity(self.header_datagram.len() + data.len()); + + // Prepend the datagram with the header indicating the session ID. + buf.extend_from_slice(&self.header_datagram); + buf.extend_from_slice(&data); + + self.conn.send_datagram(buf.into()) + } else { + self.conn.send_datagram(data) + }; + + result.map_err(|e| self.map_error(e))?; + Ok(()) + } + + /// Sends an application datagram to the remote peer, waiting for buffer space if needed. + /// + /// Datagrams are unreliable and may be dropped or delivered out of order. + /// The data must be smaller than [`max_datagram_size`](Self::max_datagram_size). + pub async fn send_datagram_wait(&self, data: Bytes) -> Result<(), SessionError> { + let result = if !self.header_datagram.is_empty() { + // Unfortunately, we need to allocate/copy each datagram because of the Noq API. + // Pls go +1 if you care: https://github.com/quinn-rs/quinn/issues/1724 + let mut buf = BytesMut::with_capacity(self.header_datagram.len() + data.len()); + + // Prepend the datagram with the header indicating the session ID. + buf.extend_from_slice(&self.header_datagram); + buf.extend_from_slice(&data); + + self.conn.send_datagram_wait(buf.into()).await + } else { + self.conn.send_datagram_wait(data).await + }; + + result.map_err(|e| self.map_error(e))?; + Ok(()) + } + + /// Computes the maximum size of datagrams that may be passed to + /// [`send_datagram`](Self::send_datagram). + pub fn max_datagram_size(&self) -> usize { + let mtu = self + .conn + .max_datagram_size() + .expect("datagram support is required"); + mtu.saturating_sub(self.header_datagram.len()) + } + + /// Returns the available buffer space for sending datagrams. + /// + /// This value is adjusted to account for the WebTransport session header. + pub fn datagram_send_buffer_space(&self) -> usize { + self.conn + .datagram_send_buffer_space() + .saturating_sub(self.header_datagram.len()) + } + + /// Close the session with an error code and reason. + /// + /// When there is a session ID (WebTransport over HTTP/3), a `CloseWebTransportSession` + /// capsule is written on the CONNECT stream before the QUIC connection is closed. + /// This allows browser clients to receive the close code and reason via `WebTransport.closed`. + /// + /// The capsule write and connection close happen asynchronously in a spawned task. + /// Callers should `await` [`Session::closed()`] to ensure the capsule has been + /// delivered. Session operations will fail once the QUIC connection is closed. + pub fn close(&self, code: u32, reason: &[u8]) { + // Record the local close error. First writer wins — if the background + // task already set a remote close error, or close() was already called, + // this is a no-op. + let err = SessionError::ConnectionError(noq::ConnectionError::LocallyClosed); + if self.error.set(err).is_err() { + return; + } + + if self.session_id.is_some() { + // Take the send stream for the capsule write. + let send = self.connect_send.lock().unwrap().take(); + + if let Some(send) = send { + let reason = String::from_utf8_lossy(reason).into_owned(); + let conn = self.conn.clone(); + let capsule = + web_transport_proto::Capsule::CloseWebTransportSession { code, reason }; + let rtt = self + .conn + .rtt(noq::PathId::ZERO) + .unwrap_or(Duration::from_millis(100)); + let timeout = (rtt * 3).max(Duration::from_millis(100)); + + tokio::spawn(async move { + Self::close_with_capsule(conn, send, capsule, code, timeout).await; + }); + } + } else { + // Raw QUIC mode: no capsule needed. + self.conn.close(code.into(), reason); + } + } + + /// Write the CloseWebTransportSession capsule, finish the stream, wait for + /// the peer to close the connection (or timeout), then force-close. + async fn close_with_capsule( + conn: noq::Connection, + mut send: noq::SendStream, + capsule: web_transport_proto::Capsule, + code: u32, + timeout: std::time::Duration, + ) { + let http3_code: noq::VarInt = web_transport_proto::error_to_http3(code) + .try_into() + .unwrap(); + + // Encode the capsule, then wrap it in an HTTP/3 DATA frame. + // In HTTP/3, capsule data is carried inside DATA frames on the CONNECT + // stream (RFC 9297 Section 3.2). + let mut capsule_bytes = Vec::new(); + capsule.encode(&mut capsule_bytes); + + let mut frame = Vec::new(); + Frame::DATA.encode(&mut frame); + let Ok(len) = VarInt::try_from(capsule_bytes.len()) else { + tracing::warn!("capsule too large to encode as DATA frame"); + conn.close(http3_code, b""); + return; + }; + len.encode(&mut frame); + frame.extend_from_slice(&capsule_bytes); + + // Write the DATA frame to the CONNECT send stream. + if let Err(e) = send.write_all(&frame).await { + tracing::warn!(?e, "failed to write CloseWebTransportSession capsule"); + conn.close(http3_code, b""); + return; + } + + // FIN the send stream so the peer knows no more capsules are coming. + if let Err(e) = send.finish() { + tracing::warn!(?e, "failed to finish CONNECT send stream"); + conn.close(http3_code, b""); + return; + } + + // Wait for the peer to close the CONNECT stream after receiving the capsule. + if tokio::time::timeout(timeout, conn.closed()).await.is_err() { + tracing::debug!("timeout waiting for peer to close; force-closing connection"); + conn.close(http3_code, b""); + } + } + + /// Wait until the session is closed, returning the error. See [`noq::Connection::closed`]. + /// + /// If the peer sent a `CloseWebTransportSession` capsule, the returned error will be + /// [`WebTransportError::Closed`] with the code and reason from the capsule. + /// + /// Unlike [`noq::Connection::closed`], this does **not** return early when + /// [`close()`](Self::close) has been called. It waits for the underlying QUIC + /// connection to shut down, ensuring the `CloseWebTransportSession` capsule has + /// been delivered. Use [`close_reason()`](Self::close_reason) for a non-blocking check. + pub async fn closed(&self) -> SessionError { + self.map_error(self.conn.closed().await) + } + + /// Return why the session was closed, or None if it's not closed. See + /// [`noq::Connection::close_reason`]. + pub fn close_reason(&self) -> Option { + self.conn.close_reason().map(|e| self.map_error(e)) + } + + /// Replace connection-level errors with the stored session error if available. + fn map_error(&self, e: impl Into) -> SessionError { + let e = e.into(); + if let Some(err) = self.error.get() { + if matches!( + &e, + SessionError::ConnectionError(_) + | SessionError::SendDatagramError(noq::SendDatagramError::ConnectionLost(_)) + ) { + return err.clone(); + } + } + e + } + + async fn write_full(send: &mut noq::SendStream, buf: &[u8]) -> Result<(), SessionError> { + match send.write_all(buf).await { + Ok(_) => Ok(()), + Err(noq::WriteError::ConnectionLost(err)) => Err(err.into()), + Err(err) => Err(WebTransportError::WriteError(err).into()), + } + } + + /// Create a new session from a raw QUIC connection. + /// + /// This is used to pretend like a QUIC connection is a WebTransport session, + /// making it easier to support WebTransport and raw QUIC simultaneously. + /// + /// There is no HTTP/3 exchange, so [`Self::request`] and [`Self::response`] both + /// return `None`. [`Self::protocol`] reports the ALPN negotiated by the QUIC + /// handshake, read from `conn` on demand — a connection that is still handshaking + /// (from `into_0rtt`, say) is fine, it just has no ALPN to report until it is done. + pub fn raw(conn: noq::Connection) -> Self { + Self { + conn, + session_id: None, + header_uni: Default::default(), + header_bi: Default::default(), + header_datagram: Default::default(), + accept: None, + settings: None, + connect_send: Arc::new(Mutex::new(None)), + error: Arc::new(OnceLock::new()), + request: None, + response: None, + alpn: Default::default(), + } + } + + /// Returns the [`ConnectRequest`] if this session was established over HTTP/3, + /// or `None` for a raw QUIC session. + pub fn request(&self) -> Option<&ConnectRequest> { + self.request.as_ref() + } + + /// Returns the [`ConnectResponse`] if this session was established over HTTP/3, + /// or `None` for a raw QUIC session. + pub fn response(&self) -> Option<&ConnectResponse> { + self.response.as_ref() + } + + /// Returns the application protocol negotiated for this session. + /// + /// For an HTTP/3 session this is the subprotocol the server selected via + /// `WT-Available-Protocols`; for a raw QUIC session it is the negotiated ALPN. + /// `None` if neither was negotiated, the ALPN is not valid UTF-8, or the raw + /// connection is still handshaking. + pub fn protocol(&self) -> Option<&str> { + if let Some(response) = &self.response { + return response.protocol.as_deref(); + } + + if let Some(alpn) = self.alpn.get() { + return Some(alpn); + } + + // Latch only a successful read, so a call made while the connection is still + // handshaking cannot pin `None` for the life of the session. + let alpn = negotiated_alpn(&self.conn)?; + Some(self.alpn.get_or_init(|| alpn)) + } + + /// Return connection-level statistics. + pub fn stats(&self) -> SessionStats { + let path = self.conn.path_stats(noq::PathId::ZERO); + let rtt = self + .conn + .rtt(noq::PathId::ZERO) + .or_else(|| path.map(|p| p.rtt)); + SessionStats { + stats: self.conn.stats(), + path, + rtt, + } + } +} + +impl Deref for Session { + type Target = noq::Connection; + + fn deref(&self) -> &Self::Target { + &self.conn + } +} + +impl fmt::Debug for Session { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + self.conn.fmt(f) + } +} + +impl PartialEq for Session { + fn eq(&self, other: &Self) -> bool { + self.conn.stable_id() == other.conn.stable_id() + } +} + +impl Eq for Session {} + +// Poll the shared accept state, then wake the *other* accepters once the lock is +// released. +// +// `SessionAccept` does not wake them itself: a waker is free to resume its task +// inline, and the first thing a resumed accepter does is take this same lock. An +// arrival or a failure is exactly what the others are parked waiting to retry +// after, so `Ready` is the signal. +fn poll_accept_uni_shared( + accept: &Mutex, + waiter: &Waiter, +) -> Poll> { + let (result, waiters, hold) = { + let mut accept = accept.lock().unwrap(); + let waiters = accept.uni_waiters.clone(); + + // The poll below drives the shared accept futures with this list's waker, and one + // of them may wake it inline. `Fan` holds those back while this guard is alive. + let hold = waiters.hold(); + let result = accept.poll_accept_uni(waiter); + + (result, waiters, hold) + }; + + // Dropped after the accept lock, never before: that is where a held-back wake is + // delivered, and delivering it under the lock is the hazard the hold exists for. + drop(hold); + + if result.is_ready() { + waiters.wake(); + } + + result +} + +fn poll_accept_bi_shared( + accept: &Mutex, + waiter: &Waiter, +) -> Poll> { + let (result, waiters, hold) = { + let mut accept = accept.lock().unwrap(); + let waiters = accept.bi_waiters.clone(); + + // The poll below drives the shared accept futures with this list's waker, and one + // of them may wake it inline. `Fan` holds those back while this guard is alive. + let hold = waiters.hold(); + let result = accept.poll_accept_bi(waiter); + + (result, waiters, hold) + }; + + // Dropped after the accept lock, never before: that is where a held-back wake is + // delivered, and delivering it under the lock is the hazard the hold exists for. + drop(hold); + + if result.is_ready() { + waiters.wake(); + } + + result +} + +// Type aliases just so clippy doesn't complain about the complexity. +type AcceptUni = dyn Stream> + Send; +type AcceptBi = + dyn Stream> + Send; +type PendingUni = dyn Future> + Send; +type PendingBi = + dyn Future, SessionError>> + Send; + +// Logic just for accepting streams, which is annoying because of the stream header. +pub struct SessionAccept { + session_id: VarInt, + + // Shared session error for propagation to accepted streams. + error: Arc>, + + // We also need to keep a reference to the qpack streams if the endpoint (incorrectly) creates + // them. Again, this is just so they don't get closed until we drop the session. + qpack_encoder: Option, + qpack_decoder: Option, + + accept_uni: Pin>, + accept_bi: Pin>, + + // Keep track of work being done to read/write the WebTransport stream header. + pending_uni: FuturesUnordered>>, + pending_bi: FuturesUnordered>>, + + // Waiters from concurrent callers of accept_bi / accept_uni. + // Every clone of the session polls this one struct, so an arrival has to be fanned + // out: each caller registers here and all of them are woken when a stream lands — + // by the caller that saw it, once it has released the lock on this struct. + bi_waiters: Fan, + uni_waiters: Fan, + + // `Waker::from(waiters.clone())`, cached so the inner accept futures are polled with + // the same waker every time. That waker outlives every caller, so an accepter that + // drops its future cannot take the wakeup path with it, and the layer below holds + // one registration rather than one per caller. + bi_waker: Waker, + uni_waker: Waker, +} + +impl SessionAccept { + pub(crate) fn new( + conn: noq::Connection, + session_id: VarInt, + error: Arc>, + ) -> Self { + // Create a stream that just outputs new streams, so it's easy to call from poll. + let accept_uni = Box::pin(futures::stream::unfold(conn.clone(), |conn| async { + Some((conn.accept_uni().await, conn)) + })); + + let accept_bi = Box::pin(futures::stream::unfold(conn, |conn| async { + Some((conn.accept_bi().await, conn)) + })); + + let bi_waiters = Fan::new(); + let uni_waiters = Fan::new(); + let bi_waker = bi_waiters.waker(); + let uni_waker = uni_waiters.waker(); + + Self { + session_id, + error, + + qpack_decoder: None, + qpack_encoder: None, + + accept_uni, + accept_bi, + + pending_uni: FuturesUnordered::new(), + pending_bi: FuturesUnordered::new(), + + bi_waiters, + uni_waiters, + bi_waker, + uni_waker, + } + } + + /// Poll for the next unidirectional WebTransport stream. + /// + /// `waiter` is parked until a stream arrives, the accept fails, or the caller drops + /// it. The registration is weak and owned by the caller: keep the [`Waiter`] alive + /// until it is woken, or it will be reclaimed and nothing will wake you. Drive this + /// with [`kio::wait`], which holds the waiter inside the future it builds. + /// + /// A `Ready` here means every *other* parked accepter should be woken so it can + /// retry. This does not do that itself — see `poll_accept_uni_shared`, which wakes + /// them once the lock on this struct is released. + // + // Poll-based because we accept and decode streams in parallel. In async land this + // would be a `tokio::JoinSet`, but that needs a runtime; `FuturesUnordered` is + // runtime-agnostic. + pub fn poll_accept_uni(&mut self, waiter: &Waiter) -> Poll> { + // Register before polling, not on the way out: the shared waker can fire from the + // layer below at any point here, and a wake that lands before the caller is on + // the list would be lost. + self.uni_waiters.register(waiter); + + let waker = self.uni_waker.clone(); + let cx = &mut Context::from_waker(&waker); + + loop { + // Accept any new streams. + if let Poll::Ready(Some(res)) = self.accept_uni.poll_next_unpin(cx) { + // Start decoding the header and add the future to the list of pending streams. + let recv = match res { + Ok(recv) => recv, + Err(e) => { + return Poll::Ready(Err(e.into())); + } + }; + let pending = Self::decode_uni(recv, self.session_id); + self.pending_uni.push(Box::pin(pending)); + + continue; + } + + // Poll the list of pending streams. + let (typ, recv) = match self.pending_uni.poll_next_unpin(cx) { + Poll::Ready(Some(Ok(res))) => res, + Poll::Ready(Some(Err(err))) => { + // Ignore the error, the stream was probably reset early. + tracing::warn!(?err, "failed to decode unidirectional stream"); + continue; + } + Poll::Ready(None) | Poll::Pending => return Poll::Pending, + }; + + // Decide if we keep looping based on the type. + match typ { + StreamUni::WEBTRANSPORT => { + let recv = RecvStream::new(recv, self.error.clone()); + return Poll::Ready(Ok(recv)); + } + StreamUni::QPACK_DECODER => { + self.qpack_decoder = Some(recv); + } + StreamUni::QPACK_ENCODER => { + self.qpack_encoder = Some(recv); + } + _ => { + // ignore unknown streams + tracing::debug!(?typ, "ignoring unknown unidirectional stream"); + } + } + } + } + + // Reads the stream header, returning the stream type. + async fn decode_uni( + mut recv: noq::RecvStream, + expected_session: VarInt, + ) -> Result<(StreamUni, noq::RecvStream), SessionError> { + // Read the VarInt at the start of the stream. + let typ = VarInt::read(&mut recv) + .await + .map_err(|_| WebTransportError::UnknownSession)?; + let typ = StreamUni(typ); + + if typ == StreamUni::WEBTRANSPORT { + // Read the session_id and validate it + let session_id = VarInt::read(&mut recv) + .await + .map_err(|_| WebTransportError::UnknownSession)?; + if session_id != expected_session { + return Err(WebTransportError::UnknownSession.into()); + } + } + + // We need to keep a reference to the qpack streams if the endpoint (incorrectly) creates + // them, so return everything. + Ok((typ, recv)) + } + + /// Poll for the next bidirectional WebTransport stream. + /// + /// The same contract as [`poll_accept_uni`](Self::poll_accept_uni): the `waiter` + /// registration is weak and owned by the caller, and a `Ready` is what the other + /// parked accepters need to be woken for. + pub fn poll_accept_bi( + &mut self, + waiter: &Waiter, + ) -> Poll> { + // Register before polling; see `poll_accept_uni`. + self.bi_waiters.register(waiter); + + let waker = self.bi_waker.clone(); + let cx = &mut Context::from_waker(&waker); + + loop { + // Accept any new streams. + if let Poll::Ready(Some(res)) = self.accept_bi.poll_next_unpin(cx) { + // Start decoding the header and add the future to the list of pending streams. + let (send, recv) = match res { + Ok(pair) => pair, + Err(e) => { + return Poll::Ready(Err(e.into())); + } + }; + let pending = Self::decode_bi(send, recv, self.session_id); + self.pending_bi.push(Box::pin(pending)); + + continue; + } + + // Poll the list of pending streams. + let res = match self.pending_bi.poll_next_unpin(cx) { + Poll::Ready(Some(Ok(res))) => res, + Poll::Ready(Some(Err(err))) => { + // Ignore the error, the stream was probably reset early. + tracing::warn!(?err, "failed to decode bidirectional stream"); + continue; + } + Poll::Ready(None) | Poll::Pending => return Poll::Pending, + }; + + if let Some((send, recv)) = res { + // Wrap the streams in our own types for correct error codes. + let send = SendStream::new(send, self.error.clone()); + let recv = RecvStream::new(recv, self.error.clone()); + return Poll::Ready(Ok((send, recv))); + } + + // Keep looping if it's a stream we want to ignore. + } + } + + // Reads the stream header, returning Some if it's a WebTransport stream. + async fn decode_bi( + send: noq::SendStream, + mut recv: noq::RecvStream, + expected_session: VarInt, + ) -> Result, SessionError> { + let typ = VarInt::read(&mut recv) + .await + .map_err(|_| WebTransportError::UnknownSession)?; + if Frame(typ) != Frame::WEBTRANSPORT { + tracing::debug!(?typ, "ignoring unknown bidirectional stream"); + return Ok(None); + } + + // Read the session ID and validate it. + let session_id = VarInt::read(&mut recv) + .await + .map_err(|_| WebTransportError::UnknownSession)?; + if session_id != expected_session { + return Err(WebTransportError::UnknownSession.into()); + } + + Ok(Some((send, recv))) + } +} + +pub struct SessionStats { + stats: noq::ConnectionStats, + path: Option, + rtt: Option, +} + +impl web_transport_trait::Stats for SessionStats { + fn bytes_sent(&self) -> Option { + Some(self.stats.udp_tx.bytes) + } + + fn bytes_received(&self) -> Option { + Some(self.stats.udp_rx.bytes) + } + + fn bytes_lost(&self) -> Option { + self.path.map(|path| path.lost_bytes) + } + + fn packets_sent(&self) -> Option { + Some(self.stats.udp_tx.datagrams) + } + + fn packets_received(&self) -> Option { + Some(self.stats.udp_rx.datagrams) + } + + fn packets_lost(&self) -> Option { + self.path.map(|path| path.lost_packets) + } + + fn rtt(&self) -> Option { + self.rtt + } + + fn estimated_send_rate(&self) -> Option { + let path = self.path?; + let rtt = self.rtt?; + let rtt_secs = rtt.as_secs_f64(); + if path.cwnd > 0 && rtt_secs > 0.0 { + Some((path.cwnd as f64 * 8.0 / rtt_secs) as u64) + } else { + None + } + } +} + +impl web_transport_trait::Session for Session { + type SendStream = SendStream; + type RecvStream = RecvStream; + type Error = SessionError; + + async fn accept_uni(&self) -> Result { + Self::accept_uni(self).await + } + + async fn accept_bi(&self) -> Result<(Self::SendStream, Self::RecvStream), Self::Error> { + Self::accept_bi(self).await + } + + async fn open_bi(&self) -> Result<(Self::SendStream, Self::RecvStream), Self::Error> { + Self::open_bi(self).await + } + + async fn open_uni(&self) -> Result { + Self::open_uni(self).await + } + + fn close(&self, code: u32, reason: &str) { + Self::close(self, code, reason.as_bytes()); + } + + async fn closed(&self) -> Self::Error { + Self::closed(self).await + } + + fn send_datagram(&self, data: Bytes) -> Result<(), Self::Error> { + Self::send_datagram(self, data) + } + + async fn recv_datagram(&self) -> Result { + Self::read_datagram(self).await + } + + fn max_datagram_size(&self) -> usize { + Self::max_datagram_size(self) + } + + fn protocol(&self) -> Option<&str> { + Self::protocol(self) + } + + #[allow(refining_impl_trait)] + fn stats(&self) -> SessionStats { + Self::stats(self) + } +} diff --git a/web-transport-moq/src/settings.rs b/web-transport-moq/src/settings.rs new file mode 100644 index 0000000000..08ea9a53a1 --- /dev/null +++ b/web-transport-moq/src/settings.rs @@ -0,0 +1,70 @@ +use futures::try_join; + +use thiserror::Error; + +#[derive(Error, Debug, Clone)] +pub enum SettingsError { + #[error("quic stream was closed early")] + UnexpectedEnd, + + #[error("protocol error: {0}")] + ProtoError(#[from] web_transport_proto::SettingsError), + + #[error("WebTransport is not supported")] + WebTransportUnsupported, + + #[error("connection error")] + ConnectionError(#[from] noq::ConnectionError), + + #[error("read error")] + ReadError(#[from] noq::ReadError), + + #[error("write error")] + WriteError(#[from] noq::WriteError), +} + +pub struct Settings { + // A reference to the send/recv stream, so we don't close it until dropped. + #[allow(dead_code)] + send: noq::SendStream, + + #[allow(dead_code)] + recv: noq::RecvStream, +} + +impl Settings { + // Establish the H3 connection. + pub async fn connect(conn: &noq::Connection) -> Result { + let recv = Self::accept(conn); + let send = Self::open(conn); + + // Run both tasks concurrently until one errors or they both complete. + let (send, recv) = try_join!(send, recv)?; + Ok(Self { send, recv }) + } + + async fn accept(conn: &noq::Connection) -> Result { + let mut recv = conn.accept_uni().await?; + let settings = web_transport_proto::Settings::read(&mut recv).await?; + + tracing::debug!(?settings, "received SETTINGS frame"); + + if settings.supports_webtransport() == 0 { + return Err(SettingsError::WebTransportUnsupported); + } + + Ok(recv) + } + + async fn open(conn: &noq::Connection) -> Result { + let mut settings = web_transport_proto::Settings::default(); + settings.enable_webtransport(1); + + tracing::debug!(?settings, "sending SETTINGS frame"); + + let mut send = conn.open_uni().await?; + settings.write(&mut send).await?; + + Ok(send) + } +} diff --git a/web-transport-moq/tests/accept_wakers.rs b/web-transport-moq/tests/accept_wakers.rs new file mode 100644 index 0000000000..0970669b03 --- /dev/null +++ b/web-transport-moq/tests/accept_wakers.rs @@ -0,0 +1,233 @@ +//! Accepters come and go; the accept queue must not leak them or lose them. +//! +//! `SessionAccept` keeps a list of parked accepters so that every one of them is woken +//! when a stream arrives. That list used to be a `Vec` with no way to say "I'm +//! gone", cleared only by a stream arriving or the connection failing, so a caller that +//! started an accept and dropped the future — a `tokio::time::timeout` around +//! `accept_uni()`, say — left its waker there forever. Distinct tasks doing that on a +//! quiet connection grew the list without bound, retaining a task allocation apiece. +//! +//! The wake path had the mirror-image problem: the inner accept future was polled with +//! the caller's waker, so the last caller to poll owned the only path an arrival had +//! back into this crate. When that caller walked away, the accepters still parked here +//! were never woken. + +use std::{ + future::Future, + net::Ipv4Addr, + sync::{ + atomic::{AtomicBool, Ordering}, + Arc, + }, + task::{Context, Wake, Waker}, + time::Duration, +}; + +use anyhow::{Context as _, Result}; +use rcgen::{CertifiedKey, KeyPair}; +use rustls::pki_types::{PrivateKeyDer, PrivatePkcs8KeyDer}; +use tokio::time::timeout; +use web_transport_moq::{ClientBuilder, ServerBuilder}; +use web_transport_proto::ConnectRequest; + +/// How many accepters give up, one after another. Well past any plausible bound on +/// concurrent accepters, so a list that keeps every registration is obvious. +const ABANDONED: usize = 256; + +/// A waker that records whether it was woken. The test also watches its `Arc` count: +/// anything still holding a clone of the waker is retaining this allocation. +#[derive(Default)] +struct FlagWaker { + woken: AtomicBool, +} + +impl FlagWaker { + fn woken(&self) -> bool { + self.woken.load(Ordering::SeqCst) + } +} + +impl Wake for FlagWaker { + fn wake(self: Arc) { + self.woken.store(true, Ordering::SeqCst); + } + + fn wake_by_ref(self: &Arc) { + self.woken.store(true, Ordering::SeqCst); + } +} + +/// With both crypto features enabled — as `--all-features` does — the crate cannot +/// pick a provider for us, so the test installs one. +fn install_crypto_provider() { + #[cfg(all(feature = "aws-lc-rs", feature = "ring"))] + { + let _ = rustls::crypto::aws_lc_rs::default_provider().install_default(); + } +} + +/// A client and server session, already connected. +async fn pair() -> Result<(web_transport_moq::Session, web_transport_moq::Session)> { + install_crypto_provider(); + + let CertifiedKey { cert, signing_key } = + rcgen::generate_simple_self_signed(vec!["localhost".into(), "127.0.0.1".into()])?; + let chain = vec![cert.der().clone()]; + let key = PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(KeyPair::serialize_der( + &signing_key, + ))); + + let mut server = ServerBuilder::new() + .with_addr((Ipv4Addr::LOCALHOST, 0).into()) + .with_certificate(chain.clone(), key)?; + + let addr = server.local_addr()?; + + let server_task = tokio::spawn(async move { + let request = server.accept().await.context("no connection")?; + let session = request.ok().await?; + anyhow::Ok(session) + }); + + let url: url::Url = format!("https://127.0.0.1:{}/", addr.port()).parse()?; + let client = ClientBuilder::new().with_server_certificates(chain)?; + let client = client.connect(ConnectRequest::new(url)).await?; + + let server = server_task.await??; + Ok((client, server)) +} + +/// Register an accepter, abandon it, and repeat — on a connection where no stream ever +/// arrives, which is the case that used to grow forever. Nothing here delivers a +/// stream: an arrival drains the list, which would hide exactly what is under test. +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn abandoned_accepters_release_their_wakers() -> Result<()> { + let (client, server) = pair().await?; + + // Each iteration is a distinct task's worth of waker, registered by a single poll + // and abandoned when the future drops at the end of the scope. + let mut abandoned = Vec::with_capacity(ABANDONED); + for _ in 0..ABANDONED { + let flag = Arc::new(FlagWaker::default()); + let waker = Waker::from(flag.clone()); + + let mut accept = std::pin::pin!(server.accept_uni()); + assert!( + accept + .as_mut() + .poll(&mut Context::from_waker(&waker)) + .is_pending(), + "no stream should be available yet" + ); + + abandoned.push(flag); + } + + // Every abandoned waker should be uniquely owned by the test again: the shared + // accept futures are polled with the accept state's own waker, never the caller's, + // so there is nothing else that could still be holding one. + let retained = abandoned + .iter() + .filter(|flag| Arc::strong_count(flag) > 1) + .count(); + assert_eq!( + retained, 0, + "{retained} of {ABANDONED} abandoned accepters are still parked in the accept list" + ); + + client.close(0, b"bye"); + Ok(()) +} + +/// Reclaiming an abandoned accepter's slot must not cost a live accepter its wakeup. +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn churn_does_not_lose_a_live_accepter() -> Result<()> { + let (client, server) = pair().await?; + + // One accepter that sticks around, registered before the churn. + let parked = Arc::new(FlagWaker::default()); + let parked_waker = Waker::from(parked.clone()); + let mut waiting = std::pin::pin!(server.accept_uni()); + assert!( + waiting + .as_mut() + .poll(&mut Context::from_waker(&parked_waker)) + .is_pending(), + "no stream should be available yet" + ); + + for _ in 0..ABANDONED { + let waker = Waker::from(Arc::new(FlagWaker::default())); + let mut accept = std::pin::pin!(server.accept_uni()); + assert!( + accept + .as_mut() + .poll(&mut Context::from_waker(&waker)) + .is_pending() + ); + } + + let mut send = client.open_uni().await?; + send.write_all(b"hi").await?; + send.finish()?; + + // A second accepter takes the stream; the first should have been woken to retry. + let recv = timeout(Duration::from_secs(10), server.accept_uni()) + .await + .context("the stream never arrived")??; + drop(recv); + + assert!( + parked.woken(), + "the accepter that was still waiting lost its registration to the churn" + ); + + client.close(0, b"bye"); + Ok(()) +} + +/// The last accepter to poll is the one the inner accept future holds a waker for. If it +/// gives up, the arrival has to reach whoever is still waiting. +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn a_departing_accepter_does_not_strand_the_others() -> Result<()> { + let (client, server) = pair().await?; + + // A parks first. + let a = Arc::new(FlagWaker::default()); + let a_waker = Waker::from(a.clone()); + let mut first = std::pin::pin!(server.accept_uni()); + assert!( + first + .as_mut() + .poll(&mut Context::from_waker(&a_waker)) + .is_pending() + ); + + // B polls after A, so B's waker is the one the inner future holds, then gives up. + { + let b = Waker::from(Arc::new(FlagWaker::default())); + let mut second = std::pin::pin!(server.accept_uni()); + assert!( + second + .as_mut() + .poll(&mut Context::from_waker(&b)) + .is_pending() + ); + } + + let mut send = client.open_uni().await?; + send.write_all(b"hi").await?; + send.finish()?; + + // Nothing here polls the accept path again: A has to be woken by the arrival. + for _ in 0..500 { + if a.woken() { + break; + } + tokio::time::sleep(Duration::from_millis(10)).await; + } + assert!(a.woken(), "the remaining accepter was never woken"); + + client.close(0, b"bye"); + Ok(()) +} diff --git a/web-transport-moq/tests/qlog.rs b/web-transport-moq/tests/qlog.rs new file mode 100644 index 0000000000..63c2db2da9 --- /dev/null +++ b/web-transport-moq/tests/qlog.rs @@ -0,0 +1,24 @@ +//! The `qlog` feature must keep `noq`'s qlog knobs reachable through our re-export. + +#![cfg(feature = "qlog")] + +use web_transport_moq::noq; + +/// `TransportConfig`'s Debug reports whether a qlog factory is installed, which is the +/// only observable state noq exposes for it. +fn qlog_enabled(transport: &noq::TransportConfig) -> bool { + format!("{transport:?}").contains("qlog_factory: true") +} + +#[test] +fn transport_config_exposes_qlog() { + let mut transport = noq::TransportConfig::default(); + assert!(!qlog_enabled(&transport), "qlog should start disabled"); + + transport.qlog_from_path(std::env::temp_dir(), "web-transport-moq"); + + assert!( + qlog_enabled(&transport), + "qlog_from_path did not install a factory" + ); +} From d2a7f5e499f7a0c0baa130cda6f7f5775519a814 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 21 Sep 2026 17:11:39 -0700 Subject: [PATCH 2/2] docs(web-transport-moq): show the builder API in the README example Co-Authored-By: Claude Opus 5 --- web-transport-moq/README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/web-transport-moq/README.md b/web-transport-moq/README.md index 6fe2eb1360..3483c43dde 100644 --- a/web-transport-moq/README.md +++ b/web-transport-moq/README.md @@ -28,21 +28,17 @@ Both endpoints can send datagrams below the MTU size (~1.2kb minimum) and they m They are basically UDP packets, except they are encrypted and congestion controlled. # Usage -To use web-transport-moq, first you need to create a [noq::Endpoint](https://docs.rs/moq-noq/latest/moq_noq/struct.Endpoint.html); see the documentation and examples for more information. -The only requirement is that the ALPN is set to `web_transport_moq::ALPN` (aka `h3`). +Build a [Client](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Client.html) or [Server](https://docs.rs/web-transport-moq/latest/web_transport_moq/struct.Server.html) with its builder, or wrap your own [noq::Endpoint](https://docs.rs/moq-noq/latest/moq_noq/struct.Endpoint.html) with `Client::new` / `Server::new`; the only requirement is that the ALPN is set to `web_transport_moq::ALPN` (aka `h3`). +Connecting or accepting takes over the QUIC connection and performs the boring HTTP/3 handshake for you. -Afterwards, you use [web_transport_moq::accept](https://docs.rs/web-transport-moq/latest/web_transport_moq/fn.accept.html) (as a server) or [web_transport_moq::connect](https://docs.rs/web-transport-moq/latest/web_transport_moq/fn.connect.html) (as a client) to establish a WebTransport session. -This will take over the QUIC connection and perform the boring HTTP/3 handshake for you. - -See the [examples](examples) or [moq-native](https://github.com/moq-dev/moq-rs/blob/main/moq-native/src/quic.rs) for a full setup. +See the [examples](examples) or [moq-tokio](https://github.com/moq-dev/moq/blob/main/rs/moq-tokio/src/noq.rs) for a full setup. ```rust - // Create a QUIC client. - let mut endpoint = noq::Endpoint::client("[::]:0".parse()?)?; - endpoint.set_default_client_config(/* ... */); + // Create a QUIC client that trusts the system roots. + let client = web_transport_moq::ClientBuilder::new().with_system_roots()?; // Connect to the given URL. - let session = web_transport_moq::connect(&client, Url::parse("https://localhost")?).await?; + let session = client.connect(Url::parse("https://localhost")?).await?; // Create a bidirectional stream. let (mut send, mut recv) = session.open_bi().await?;