diff --git a/js/web-transport/README.md b/js/web-transport/README.md index a22bc35d..5353f702 100644 --- a/js/web-transport/README.md +++ b/js/web-transport/README.md @@ -62,7 +62,7 @@ const session = new Session("https://example.com:4443/path", { }); ``` -QUIC uses the smaller of both peers' idle timeouts, so disabling one endpoint's timeout leaves the peer's in effect. To keep an otherwise idle session open, set `keepAliveInterval` below the effective idle timeout on either endpoint. +QUIC uses the smaller of both peers' idle timeouts, so disabling one endpoint's timeout leaves the peer's in effect. To keep an otherwise idle session open, set `keepAliveInterval` below the effective idle timeout on either endpoint. An expired idle timeout is a connection failure, so it rejects `session.closed` with a session `WebTransportError`. ### Polyfill @@ -170,10 +170,29 @@ import { WebTransportError } from "@moq/web-transport"; await writer.abort(new WebTransportError("cancelled", { streamErrorCode: 7 })); ``` +### Releasing readers + +Call `reader.cancel()` when you stop reading a receive stream. Cancellation is the +release boundary: it interrupts a pending `read()`, sends STOP_SENDING with the reason's +`streamErrorCode` (0 otherwise), and releases the native stream. + +A pending `read()` keeps its stream alive until data, the stream's end, a session +close, or cancellation settles it. Garbage collection does not cancel an abandoned +reader with a pending read, so an abandoned reader keeps its stream open and the +peer never sees STOP_SENDING. This matches Web Streams, where an awaited `read()` +or `pipeTo()` must not fail because only its promise remains reachable. + ### Closing Always call `session.close()` when finished and await `session.closed`. The Node wrapper retains native Session handles while its close promise and incoming stream operations are pending. Garbage collecting the JavaScript Session does not close those handles, so it does not provide the Rust Session's final-handle cleanup contract. +`session.closed` resolves with the application code and reason after a local or peer close, +including nonzero application codes. An orderly HTTP/3 connection shutdown (H3_NO_ERROR) +without application details resolves with code 0 and an empty reason. A failed connection or an underlying connection +failure rejects it with a `WebTransportError` whose `source` is `"session"` and +`streamErrorCode` is `null`. `session.ready` rejects with the same error if connecting fails. +Backend teardown without an application `session.close()` also rejects `closed`. + ```ts // Close gracefully session.close({ closeCode: 0, reason: "done" }); diff --git a/js/web-transport/napi.d.cts b/js/web-transport/napi.d.cts index 5f9d1b75..d7393bab 100644 --- a/js/web-transport/napi.d.cts +++ b/js/web-transport/napi.d.cts @@ -33,10 +33,10 @@ export declare class NapiClient { export declare class NapiRecvStream { /** * Read up to `max_size` bytes from the stream. Returns null on FIN, or the error if the - * peer reset the stream or the session failed. + * peer reset the stream or the session failed. Local cancellation rejects the read. */ read(maxSize: number): Promise; - /** Tell the peer to stop sending with the given error code. */ + /** Tell the peer to stop sending with the given code; an already terminal stream is a no-op. */ stop(code: number): Promise; } @@ -110,7 +110,7 @@ export declare class NapiSession { maxDatagramSize(): number; /** Close the session with a code and reason. */ close(code: number, reason: string): void; - /** Wait for the session to close, returning close info matching W3C WebTransportCloseInfo. */ + /** Wait for normal closure with its application details, or reject on a connection failure. */ closed(): Promise; } diff --git a/js/web-transport/package.json b/js/web-transport/package.json index e4a57549..3029be3c 100644 --- a/js/web-transport/package.json +++ b/js/web-transport/package.json @@ -32,7 +32,7 @@ "scripts": { "build": "bun run build:native && bun run build:js", "check": "tsc --project tsconfig.tests.json --noEmit", - "test": "bun test tests", + "test": "cargo build -p web-transport-node --example session-peer && bun test tests", "test:runtime": "bun scripts/test-runtime.ts", "release": "bun scripts/release.ts", "build:native": "napi build --platform --release --manifest-path ../../rs/web-transport-node/Cargo.toml --output-dir . --js napi.cjs --dts napi.d.cts && biome check --write napi.cjs napi.d.cts", diff --git a/js/web-transport/src/session.ts b/js/web-transport/src/session.ts index 67f1164f..72c6c1df 100644 --- a/js/web-transport/src/session.ts +++ b/js/web-transport/src/session.ts @@ -6,19 +6,18 @@ import { fromNapi, resetCode, sessionError } from "./error.ts"; const { NapiClient } = napi; function wrapRecvStream(recv: NapiRecvStream): ReadableStream { + let cancelled = false; return new ReadableStream({ async pull(controller) { const chunk = await recv.read(65536); - if (chunk === null) { - controller.close(); - } else if (chunk instanceof Uint8Array) { - controller.enqueue(new Uint8Array(chunk)); - } else { - controller.error(fromNapi(chunk)); - } + if (cancelled) return; + if (chunk === null) controller.close(); + else if (chunk instanceof Uint8Array) controller.enqueue(new Uint8Array(chunk)); + else controller.error(fromNapi(chunk)); }, cancel(reason) { - recv.stop(resetCode(reason)).catch(() => {}); + cancelled = true; + return recv.stop(resetCode(reason)); }, }); } @@ -93,6 +92,13 @@ export default class Session implements WebTransport { const closed = Promise.withResolvers(); this.ready = ready.promise; this.closed = closed.promise; + // The spec marks lifecycle promises handled; callers can still await their rejections. + void this.ready.catch(() => {}); + void this.closed.catch(() => {}); + + const watchSession = (session: NapiSession) => { + void session.closed().then(closed.resolve, (err: unknown) => closed.reject(sessionError(err))); + }; // Check if we got an existing NapiSession (server-side path) if (typeof urlOrSession === "object" && !(urlOrSession instanceof URL)) { @@ -101,9 +107,7 @@ export default class Session implements WebTransport { ready.resolve(); - urlOrSession.closed().then((info) => { - closed.resolve({ closeCode: info.closeCode, reason: info.reason }); - }); + watchSession(urlOrSession); } else { // Client-side: create NapiClient and connect const url = typeof urlOrSession === "string" ? urlOrSession : urlOrSession.toString(); @@ -147,14 +151,13 @@ export default class Session implements WebTransport { (this.datagrams as DeferredDatagrams).bind(session); ready.resolve(); - session.closed().then((info) => { - closed.resolve({ closeCode: info.closeCode, reason: info.reason }); - }); + watchSession(session); }) .catch((err) => { - (this.datagrams as DeferredDatagrams).fail(err instanceof Error ? err : new Error(String(err))); - ready.reject(err instanceof Error ? err : new Error(String(err))); - closed.resolve({ closeCode: 0, reason: String(err) }); + const error = sessionError(err); + (this.datagrams as DeferredDatagrams).fail(error); + ready.reject(error); + closed.reject(error); }); } } diff --git a/js/web-transport/tests/fixtures/active-reader.ts b/js/web-transport/tests/fixtures/active-reader.ts new file mode 100644 index 00000000..a4f9aeaf --- /dev/null +++ b/js/web-transport/tests/fixtures/active-reader.ts @@ -0,0 +1,45 @@ +import assert from "node:assert/strict"; +import { setImmediate } from "node:timers/promises"; +import Session from "../../src/session.ts"; + +const url = process.argv[2]; +if (!url || !globalThis.gc) throw new Error("requires a peer URL and --expose-gc"); +const session = new Session(url, { serverCertificateDisableVerify: true }); +await session.ready; +const incoming = session.incomingUnidirectionalStreams.getReader(); +const trigger = session.datagrams.writable.getWriter(); + +for (const pipe of [false, true]) { + const started = Promise.withResolvers(); + const result = (async () => { + const { value: readable } = await incoming.read(); + if (!readable) throw new Error("no stream"); + if (pipe) { + const observed = readable.pipeThrough( + new TransformStream({ + transform(chunk, controller) { + started.resolve(); + controller.enqueue(chunk); + }, + }), + ); + return new Response(observed).arrayBuffer(); + } + const reader = readable.getReader(); + await reader.read(); + started.resolve(); + return reader.read(); + })(); + // Wait for the first byte, then collect while only the consumer's result is retained. + await started.promise; + await setImmediate(); + globalThis.gc(); + await setImmediate(); + await trigger.write(new Uint8Array([1])); + const value = await result; + if (pipe) assert.deepEqual(new Uint8Array(value as ArrayBuffer), new Uint8Array([1, 2])); + else assert.deepEqual((value as ReadableStreamReadResult).value, new Uint8Array([2])); +} + +session.close(); +await session.closed; diff --git a/js/web-transport/tests/fixtures/idle.ts b/js/web-transport/tests/fixtures/idle.ts index 27154319..5a6e0092 100644 --- a/js/web-transport/tests/fixtures/idle.ts +++ b/js/web-transport/tests/fixtures/idle.ts @@ -2,7 +2,7 @@ import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; import { createSocket } from "node:dgram"; import { setTimeout as sleep } from "node:timers/promises"; -import Session, { Server, type ServerOptions, type SessionOptions } from "../../src/index.ts"; +import Session, { Server, type ServerOptions, type SessionOptions, WebTransportError } from "../../src/index.ts"; const pem = execFileSync("openssl", [ "req", @@ -47,8 +47,10 @@ const EXPIRY_BOUND_MS = 10_000; async function expectExpiry(serverOptions: ServerOptions | undefined, clientOptions: SessionOptions) { const { client, peer } = await connect(serverOptions, clientOptions); const start = performance.now(); - const [info] = await Promise.all([client.closed, peer.closed]); - assert.match(info.reason ?? "", /timed out/); + // An idle timeout is a connection failure, so both sides reject with a session error. + const timedOut = (err: unknown) => + err instanceof WebTransportError && err.source === "session" && /timed out/.test(err.message); + await Promise.all([assert.rejects(client.closed, timedOut), assert.rejects(peer.closed, timedOut)]); assert(performance.now() - start < EXPIRY_BOUND_MS); } diff --git a/js/web-transport/tests/fixtures/server-close.ts b/js/web-transport/tests/fixtures/server-close.ts index 9c753f7f..55db50cc 100644 --- a/js/web-transport/tests/fixtures/server-close.ts +++ b/js/web-transport/tests/fixtures/server-close.ts @@ -78,7 +78,7 @@ holding = false; assert(remoteClient); for (const flight of flights) proxy.send(flight, remoteClient.port, remoteClient.address); await rejected; -await stalled.closed; +await assert.rejects(stalled.closed); await new Promise((resolve) => proxy.close(resolve)); // Stopping the listener must not close sessions it already accepted. diff --git a/js/web-transport/tests/session.test.ts b/js/web-transport/tests/session.test.ts index bae50458..85bb7e09 100644 --- a/js/web-transport/tests/session.test.ts +++ b/js/web-transport/tests/session.test.ts @@ -1,8 +1,12 @@ import { beforeAll, expect, test } from "bun:test"; import { createSocket } from "node:dgram"; +import { join } from "node:path"; +import napi from "../napi.cjs"; import Session, { install, Server, WebTransportError } from "../src/index.ts"; let url: string; +let pem: Buffer; +let peerExecutable: string; // The peer of each client session, in connect order. const accepted: Session[] = []; @@ -10,7 +14,7 @@ const waiters: ((session: Session) => void)[] = []; beforeAll(async () => { // One PEM holding both the certificate and its key; the server reads each block out of it. - const pem = Bun.spawnSync( + const certificate = Bun.spawnSync( [ "openssl", "req", @@ -29,10 +33,19 @@ beforeAll(async () => { ], { stderr: "pipe" }, ); - if (!pem.success) throw new Error(`openssl failed: ${pem.stderr}`); + if (!certificate.success) throw new Error(`openssl failed: ${certificate.stderr}`); + pem = certificate.stdout; + const metadata = Bun.spawnSync(["cargo", "metadata", "--no-deps", "--format-version", "1"]); + if (!metadata.success) throw new Error(`cargo metadata failed: ${metadata.stderr}`); + peerExecutable = join( + JSON.parse(metadata.stdout.toString()).target_directory, + "debug", + "examples", + `session-peer${process.platform === "win32" ? ".exe" : ""}`, + ); const port = await freePort(); - const server = Server.bind(`127.0.0.1:${port}`, pem.stdout, pem.stdout); + const server = Server.bind(`127.0.0.1:${port}`, pem, pem); url = `https://127.0.0.1:${port}`; void (async () => { @@ -87,6 +100,76 @@ test("install() defines WebTransportError alongside WebTransport", () => { } }); +test("a failed TLS connection rejects ready and closed with a session error", async () => { + // The loopback server has a self-signed certificate, which system roots reject. + const client = new Session(url); + const closed = rejection(client.closed); + const ready = await rejection(client.ready); + expect(ready.source).toBe("session"); + expect(ready.streamErrorCode).toBeNull(); + expect(await closed).toBe(ready); +}); + +test("local and peer closes preserve nonzero application codes and reasons", async () => { + const { client, peer } = await connect(); + const info = { closeCode: 42, reason: "done" }; + client.close(info); + client.close({ closeCode: 43, reason: "ignored" }); + expect(await client.closed).toEqual(info); + expect(await peer.closed).toEqual(info); +}); + +for (const side of ["client", "server"] as const) { + for (const mode of ["failure", "orderly", "application"] as const) { + test(`${mode === "failure" ? "an underlying connection failure rejects" : `${mode} capsule-free shutdown resolves`} the ${side} Session.closed`, async () => { + const child = Bun.spawn([peerExecutable, ...(side === "server" ? [url] : [])], { + env: { + ...process.env, + WEB_TRANSPORT_TEST_PEM: pem.toString(), + WEB_TRANSPORT_TEST_ORDERLY_CLOSE: mode === "orderly" ? "1" : undefined, + WEB_TRANSPORT_TEST_WT_CLOSE: mode === "application" ? "1" : undefined, + }, + stdin: "pipe", + stdout: "pipe", + stderr: "pipe", + }); + let session: Session | undefined; + try { + if (side === "client") { + const { value } = await child.stdout.getReader().read(); + if (!value) throw new Error("peer did not print its address"); + session = new Session(new TextDecoder().decode(value).trim(), { + serverCertificateDisableVerify: true, + }); + await session.ready; + } else { + session = accepted.shift() ?? (await new Promise((resolve) => waiters.push(resolve))); + } + const closed = mode === "failure" ? rejection(session.closed) : session.closed; + await session.datagrams.writable.getWriter().write(new Uint8Array([1])); + if (mode === "orderly") expect(await closed).toEqual({ closeCode: 0, reason: "" }); + else if (mode === "application") + expect(await closed).toEqual({ closeCode: 42, reason: "connection shutdown" }); + else { + const err = (await closed) as WebTransportError; + expect(err.source).toBe("session"); + expect(err.streamErrorCode).toBeNull(); + // A late local close must not turn an already observed failure into success. + session.close(); + expect(await rejection(session.closed)).toBe(err); + } + child.stdin.end(); + expect(await child.exited).toBe(0); + expect(await new Response(child.stderr).text()).toBe(""); + } finally { + session?.close(); + child.kill(); + await child.exited; + } + }); + } +} + test("a peer's RESET_STREAM errors the reader with its code", async () => { const { client, peer } = await connect(); @@ -191,3 +274,164 @@ test("an abandoned writer still finishes its stream", async () => { client.close(); }); + +test("cancelling a pending read stops the peer with the requested code", async () => { + const { client, peer } = await connect(); + try { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + await writer.write(new Uint8Array([1])); + const { value: readable } = await client.incomingUnidirectionalStreams.getReader().read(); + if (!readable) throw new Error("no stream"); + const reader = readable.getReader(); + await reader.read(); + const read = reader.read(); + // Let the native call park before cancellation has to wake it. + await new Promise(setImmediate); + await reader.cancel(new WebTransportError("cancel", { streamErrorCode: 17 })); + expect((await read).done).toBe(true); + const err = await rejection(writer.closed); + expect(err.source).toBe("stream"); + expect(err.streamErrorCode).toBe(17); + } finally { + client.close(); + } +}); + +test("concurrent read requests keep pulling through data and FIN", async () => { + const { client, peer } = await connect(); + try { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + await writer.write(new Uint8Array([1])); + const { value: readable } = await client.incomingUnidirectionalStreams.getReader().read(); + if (!readable) throw new Error("no stream"); + const reader = readable.getReader(); + expect((await reader.read()).value).toEqual(new Uint8Array([1])); + const first = reader.read(); + const second = reader.read(); + await writer.write(new Uint8Array([2])); + expect((await first).value).toEqual(new Uint8Array([2])); + await writer.write(new Uint8Array([3])); + expect((await second).value).toEqual(new Uint8Array([3])); + await writer.close(); + expect((await reader.read()).done).toBe(true); + } finally { + client.close(); + } +}); + +test("native cancellation rejects pending and subsequent reads instead of reporting FIN", async () => { + const client = await napi.NapiClient.disableVerify().connect(url); + const peer = accepted.shift() ?? (await new Promise((resolve) => waiters.push(resolve))); + try { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + const closed = rejection(writer.closed); + await writer.write(new Uint8Array([1])); + const recv = await client.acceptUni(); + await recv.read(65536); + const pending = recv.read(65536).then( + () => "unexpected FIN", + (err: Error) => err.message, + ); + await Bun.sleep(0); + await recv.stop(17); + expect(await pending).toBe("stream already closed"); + expect( + await recv.read(65536).then( + () => "unexpected FIN", + (err: Error) => err.message, + ), + ).toBe("stream already closed"); + expect(((await closed) as WebTransportError).streamErrorCode).toBe(17); + } finally { + client.close(0, "done"); + await client.closed(); + } +}); + +test("native cancellation is idempotent after FIN and RESET_STREAM", async () => { + for (const reset of [false, true]) { + const client = await napi.NapiClient.disableVerify().connect(url); + const peer = accepted.shift() ?? (await new Promise((resolve) => waiters.push(resolve))); + try { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + await writer.write(new Uint8Array([1])); + const recv = await client.acceptUni(); + await recv.read(65536); + if (reset) await writer.abort(new WebTransportError("reset", { streamErrorCode: 7 })); + else await writer.close(); + await recv.read(65536); + await recv.stop(17); + await recv.stop(17); + } finally { + client.close(0, "done"); + await client.closed(); + } + } +}); + +test("an awaited read and pipe retain an active receiver through collection", async () => { + for (const pipe of [false, true]) { + const { client, peer } = await connect(); + try { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + await writer.write(new Uint8Array([1])); + const started = Promise.withResolvers(); + const result = (async () => { + const { value: readable } = await client.incomingUnidirectionalStreams.getReader().read(); + if (!readable) throw new Error("no stream"); + if (pipe) { + const observed = readable.pipeThrough( + new TransformStream({ + transform(chunk, controller) { + started.resolve(); + controller.enqueue(chunk); + }, + }), + ); + return new Response(observed).arrayBuffer(); + } + const reader = readable.getReader(); + await reader.read(); + started.resolve(); + return reader.read(); + })(); + // Force collection while only the consumer's pending result is retained. + await started.promise; + await new Promise(setImmediate); + Bun.gc(true); + await new Promise(setImmediate); + await writer.write(new Uint8Array([2])); + await writer.close(); + const value = await result; + if (pipe) expect(new Uint8Array(value as ArrayBuffer)).toEqual(new Uint8Array([1, 2])); + else expect((value as ReadableStreamReadResult).value).toEqual(new Uint8Array([2])); + } finally { + client.close(); + } + } +}); + +test("Node retains an awaited read and pipe through collection", async () => { + const child = Bun.spawn(["node", "--expose-gc", join(import.meta.dir, "fixtures/active-reader.ts"), url], { + stdout: "pipe", + stderr: "pipe", + }); + let peer: Session | undefined; + try { + peer = accepted.shift() ?? (await new Promise((resolve) => waiters.push(resolve))); + const datagrams = peer.datagrams.readable.getReader(); + for (let i = 0; i < 2; i++) { + const writer = (await peer.createUnidirectionalStream()).getWriter(); + await writer.write(new Uint8Array([1])); + await datagrams.read(); + await writer.write(new Uint8Array([2])); + await writer.close(); + } + expect(await child.exited).toBe(0); + expect(await new Response(child.stderr).text()).toBe(""); + } finally { + peer?.close(); + child.kill(); + await child.exited; + } +}); diff --git a/quest/a0/README.md b/quest/a0/README.md index 1013fba3..fea742a0 100644 --- a/quest/a0/README.md +++ b/quest/a0/README.md @@ -13,6 +13,5 @@ The Required list is ordered by priority. Independent children may proceed concu - [Quinn crypto test flake](/quest/a0/quinn-crypto-flake.md) - the handshake/key-update test stops failing the required build - [Dev shell quest](/quest/a0/quest-pin.md) - the quest merge driver auto-resolves link lists again - [Quiche lifecycle](/quest/a0/quiche/README.md) - deterministic harness and retirement handling -- [Node session and reader lifetime](/quest/a0/node-session-lifetime.md) - `closed` rejects on an abnormal end, and an abandoned reader releases its stream - [QMux receive credit](/quest/a0/qmux-recv-credit.md) - stopped or dropped streams return their connection flow-control credit - [TypeScript QMux receive credit](/quest/a0/qmux-recv-credit-js.md) - cancelled streams return their connection flow-control credit diff --git a/quest/a0/node-session-lifetime.md b/quest/a0/node-session-lifetime.md deleted file mode 100644 index c7ceb2ba..00000000 --- a/quest/a0/node-session-lifetime.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Node session and reader lifetime - -## Goal - -In `@moq/web-transport`'s Node polyfill, `Session.closed` rejects with a -`WebTransportError` when a session ends abnormally, as browsers do, and an -abandoned reader's native stream is released even while a `read()` is -pending. - -## Plan - -Found while fixing [#470](https://github.com/moq-dev/web-transport/pull/470): - -- `Session.closed` (`js/web-transport/src/session.ts`) only resolves, so a - failed connect, a lost connection, or a peer's abnormal close never - rejects it. -- A pending `read()` keeps its native stream alive after the reader is - abandoned, because napi-rs keeps an object alive while one of its async - calls is pending. #470 hit the same cause on the writer side, for - STOP_SENDING, and fixed it there. - -Decided 2026-10-28 (maintainer): one quest for both, since they share the -session and stream teardown path. - -Add loopback regressions that fail without the fix: a failed connect and an -abnormal end each reject `closed` with the right `source` and code; dropping -every reference to a reader with a pending read, while the peer keeps the -stream open, makes the peer see the stream terminated, checked without -relying on GC timing where possible. - -Public API: `Session.closed` can now reject, matching the WebTransport spec. diff --git a/rs/web-transport-iroh/README.md b/rs/web-transport-iroh/README.md index a49daf57..d54083be 100644 --- a/rs/web-transport-iroh/README.md +++ b/rs/web-transport-iroh/README.md @@ -13,6 +13,19 @@ The crate was originally derived from [`web-transport-quinn`]. See the [package and backend selection guide](../../PACKAGE-SELECTION.md) for alternatives and integration boundaries. +## Session closure + +A peer close capsule reports `WebTransportError::Closed` with its application code +and reason. A clean CONNECT FIN without a capsule reports code 0 and an empty reason. +Malformed capsule data reports `WebTransportError::CapsuleError(String)` and closes +HTTP/3 with H3_MESSAGE_ERROR (0x10e). An existing connection failure keeps its cause. + +`CapsuleError(String)` is a new public enum variant; downstream exhaustive matches +must handle it when upgrading. + +Dropping a receive stream sends application code 0 in the session's code space: +HTTP/3 maps the code, while raw QUIC sends it unchanged. + ## License Copyright 2025 N0, INC. diff --git a/rs/web-transport-iroh/src/error.rs b/rs/web-transport-iroh/src/error.rs index da2af9e7..53287f13 100644 --- a/rs/web-transport-iroh/src/error.rs +++ b/rs/web-transport-iroh/src/error.rs @@ -72,13 +72,17 @@ pub(crate) fn decode_stream_code(code: endpoint::VarInt, raw: bool) -> Option Self { Self { inner: stream, raw } diff --git a/rs/web-transport-iroh/src/session.rs b/rs/web-transport-iroh/src/session.rs index 0a692141..07eaea3e 100644 --- a/rs/web-transport-iroh/src/session.rs +++ b/rs/web-transport-iroh/src/session.rs @@ -99,10 +99,25 @@ impl Session { } let (code, reason) = match closed { Ok(Some(close)) => close, - Ok(None) => (0, "stream closed".to_string()), + Ok(None) => { + peer_close.send_replace(Some( + WebTransportError::Closed { + code: 0, + reason: String::new(), + } + .into(), + )); + (0, String::new()) + } Err(err) => { tracing::warn!(?err, "failed to read capsule"); - (1, "capsule error".to_string()) + peer_close.send_replace(Some( + WebTransportError::CapsuleError(err.to_string()).into(), + )); + this2 + .conn + .close(0x10eu32.into(), b"invalid CONNECT capsule stream"); + return; } }; // TODO We shouldn't be closing the QUIC connection with the same error. @@ -269,7 +284,9 @@ impl Session { /// Wait until the session is closed, returning the error. See [`iroh::endpoint::Connection::closed`]. /// - /// A peer's `CloseWebTransportSession` capsule is reported as [`WebTransportError::Closed`]. + /// A peer's `CloseWebTransportSession` capsule, or a clean CONNECT FIN without a + /// capsule, is reported as [`WebTransportError::Closed`]. Malformed capsule data + /// returns [`WebTransportError::CapsuleError`]. pub async fn closed(&self) -> SessionError { let err = self.conn.closed().await; if let Some(h3) = &self.h3 { @@ -886,6 +903,76 @@ mod tests { (client_conn, server_conn, [client, server]) } + async fn http3_pair() -> (Session, Connection, Connected, Settings, [Endpoint; 2]) { + let (client, peer, endpoints) = pair().await; + let establish = Session::connect_h3(client, url::Url::parse("https://localhost/").unwrap()); + let accept = async { + let settings = Settings::connect(&peer).await.unwrap(); + let connect = crate::Connecting::accept(&peer) + .await + .unwrap() + .respond(http::StatusCode::OK) + .await + .unwrap(); + (connect, settings) + }; + let (session, (connect, settings)) = tokio::join!(establish, accept); + (session.unwrap(), peer, connect, settings, endpoints) + } + + #[tokio::test] + async fn clean_connect_fin_is_a_default_close() { + let (session, _peer, mut connect, _settings, _endpoints) = http3_pair().await; + connect.send.finish().unwrap(); + let err = session.closed().await; + assert!( + matches!(&err, SessionError::WebTransportError(WebTransportError::Closed { code: 0, reason }) if reason.is_empty()), + "{err:?}" + ); + } + + #[tokio::test] + async fn truncated_connect_data_is_a_protocol_failure() { + let (session, peer, mut connect, _settings, _endpoints) = http3_pair().await; + connect.send.write_all(&[0]).await.unwrap(); + connect.send.finish().unwrap(); + let err = peer.closed().await; + assert!( + matches!(&err, endpoint::ConnectionError::ApplicationClosed(close) if close.error_code.into_inner() == 0x10e), + "{err:?}" + ); + assert!(matches!( + session.closed().await, + SessionError::WebTransportError(WebTransportError::CapsuleError(_)) + )); + } + + #[tokio::test] + async fn failed_connect_stream_preserves_the_connection_failure() { + let (session, peer, _connect, _settings, _endpoints) = http3_pair().await; + peer.close(0u32.into(), b"failure"); + let err = session.closed().await; + assert!( + matches!(&err, SessionError::ConnectionError(endpoint::ConnectionError::ApplicationClosed(close)) if close.error_code.into_inner() == 0 && close.reason == b"failure"[..]), + "{err:?}" + ); + } + + #[tokio::test] + async fn receive_drop_uses_the_session_code_space() { + for raw in [false, true] { + let (client, peer, _endpoints) = pair().await; + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let recv = peer.accept_uni().await.unwrap(); + drop(RecvStream::new(recv, raw)); + assert_eq!( + send.stopped().await.unwrap(), + Some(crate::error::encode_stream_code(0, raw)) + ); + } + } + fn assert_reset(err: SessionError) { assert!( matches!( diff --git a/rs/web-transport-node/Cargo.toml b/rs/web-transport-node/Cargo.toml index ff3f8d09..042e2c58 100644 --- a/rs/web-transport-node/Cargo.toml +++ b/rs/web-transport-node/Cargo.toml @@ -24,4 +24,7 @@ web-transport-quinn = { path = "../web-transport-quinn", version = "0.13" } napi-build = "2" [dev-dependencies] +anyhow = "1" rcgen = "0.14" +tokio = { version = "1", features = ["rt"] } +web-transport-proto = { workspace = true } diff --git a/rs/web-transport-node/examples/session-peer.rs b/rs/web-transport-node/examples/session-peer.rs new file mode 100644 index 00000000..61bf8d96 --- /dev/null +++ b/rs/web-transport-node/examples/session-peer.rs @@ -0,0 +1,64 @@ +//! Loopback peer for the Node lifecycle tests, able to fail the underlying QUIC connection. + +use std::{io::Read, ops::Deref}; + +use anyhow::Context; + +#[tokio::main(flavor = "current_thread")] +async fn main() -> anyhow::Result<()> { + let session = if let Some(url) = std::env::args().nth(1) { + let client = web_transport_quinn::ClientBuilder::new() + .dangerous() + .with_no_certificate_verification() + .context("create client")?; + client + .connect(url::Url::parse(&url).context("parse peer URL")?) + .await + .context("connect to peer")? + } else { + let pem = std::env::var("WEB_TRANSPORT_TEST_PEM").context("read test certificate")?; + let pem = pem.as_bytes(); + let certs = rustls_pemfile::certs(&mut &pem[..]) + .collect::, _>>() + .context("parse certificate")?; + let key = rustls_pemfile::private_key(&mut &pem[..]) + .context("parse private key")? + .context("missing key")?; + let mut server = web_transport_quinn::ServerBuilder::new() + .with_addr("127.0.0.1:0".parse()?) + .with_certificate(certs, key) + .context("bind server")?; + println!("https://{}", server.local_addr().context("server address")?); + server + .accept() + .await + .context("server closed")? + .ok() + .await + .context("accept session")? + }; + + // The JS side sends a datagram after attaching its closed handler, so the failure + // always occurs on an established Session rather than racing its handshake. + session + .read_datagram() + .await + .context("read trigger datagram")?; + // H3_NO_ERROR is orderly shutdown; raw QUIC 0 is outside WebTransport's HTTP/3 space. + let code: u64 = if std::env::var_os("WEB_TRANSPORT_TEST_WT_CLOSE").is_some() { + web_transport_proto::error_to_http3(42) + } else if std::env::var_os("WEB_TRANSPORT_TEST_ORDERLY_CLOSE").is_some() { + 0x100 + } else { + 0 + }; + session + .deref() + .close(code.try_into().unwrap(), b"connection shutdown"); + // Await a second signal on stdin to keep the runtime alive while QUIC sends the close. + tokio::task::spawn_blocking(|| std::io::stdin().read(&mut [0])) + .await + .context("join shutdown signal")? + .context("read shutdown signal")?; + Ok(()) +} diff --git a/rs/web-transport-node/src/lib.rs b/rs/web-transport-node/src/lib.rs index f26c598d..03dce61a 100644 --- a/rs/web-transport-node/src/lib.rs +++ b/rs/web-transport-node/src/lib.rs @@ -21,18 +21,30 @@ use tokio::sync::{watch, Mutex}; // clones back into `self.inner.lock()` across an await -- that reintroduces the // crash. -fn session_error_to_close_info(err: &web_transport_quinn::SessionError) -> NapiCloseInfo { +fn session_error_to_close_info( + err: &web_transport_quinn::SessionError, + local: Option, +) -> Result { match err { web_transport_quinn::SessionError::WebTransportError( web_transport_quinn::WebTransportError::Closed(code, reason), - ) => NapiCloseInfo { + ) => Ok(NapiCloseInfo { close_code: *code, reason: reason.clone(), - }, - other => NapiCloseInfo { - close_code: 0, - reason: other.to_string(), - }, + }), + web_transport_quinn::SessionError::ConnectionError( + web_transport_quinn::quinn::ConnectionError::ApplicationClosed(close), + ) if close.error_code.into_inner() == 0x100 => { + // H3_NO_ERROR is an orderly HTTP/3 shutdown without application close details. + Ok(NapiCloseInfo { + close_code: 0, + reason: String::new(), + }) + } + web_transport_quinn::SessionError::ConnectionError( + web_transport_quinn::quinn::ConnectionError::LocallyClosed, + ) => local.ok_or_else(|| Error::from_reason(err.to_string())), + other => Err(Error::from_reason(other.to_string())), } } @@ -167,7 +179,7 @@ impl NapiClient { .map_err(|e| Error::from_reason(e.to_string()))?; Ok(NapiSession { inner: session.clone(), - closed: Arc::new(Mutex::new(None)), + closed: Arc::new(std::sync::Mutex::new(None)), }) } } @@ -603,7 +615,7 @@ impl NapiRequest { .map_err(|e| Error::from_reason(e.to_string()))?; Ok(NapiSession { inner: session.clone(), - closed: Arc::new(Mutex::new(None)), + closed: Arc::new(std::sync::Mutex::new(None)), }) } @@ -630,8 +642,8 @@ impl NapiRequest { #[napi] pub struct NapiSession { inner: web_transport_quinn::Session, - // Cache the closed future result so multiple callers can await it. - closed: Arc>>, + // The backend reports local closes as LocallyClosed, without their application details. + closed: Arc>>, } /// Info about why a session was closed, matching W3C WebTransportCloseInfo. @@ -685,9 +697,7 @@ impl NapiSession { .accept_uni() .await .map_err(|e| Error::from_reason(e.to_string()))?; - Ok(NapiRecvStream { - inner: Arc::new(Mutex::new(recv)), - }) + Ok(NapiRecvStream::new(recv)) } /// Accept an incoming bidirectional stream. @@ -702,9 +712,7 @@ impl NapiSession { send: Some(NapiSendStream { inner: Arc::new(Mutex::new(send)), }), - recv: Some(NapiRecvStream { - inner: Arc::new(Mutex::new(recv)), - }), + recv: Some(NapiRecvStream::new(recv)), }) } @@ -733,9 +741,7 @@ impl NapiSession { send: Some(NapiSendStream { inner: Arc::new(Mutex::new(send)), }), - recv: Some(NapiRecvStream { - inner: Arc::new(Mutex::new(recv)), - }), + recv: Some(NapiRecvStream::new(recv)), }) } @@ -770,36 +776,28 @@ impl NapiSession { #[napi] pub fn close(&self, code: u32, reason: String) { within_runtime_if_available(|| { + let mut closed = self.closed.lock().unwrap(); + if closed.is_none() && self.inner.close_reason().is_none() { + *closed = Some(NapiCloseInfo { + close_code: code, + reason: reason.clone(), + }); + } self.inner.close(code, reason.as_bytes()); }); } - /// Wait for the session to close, returning close info matching W3C WebTransportCloseInfo. + /// Wait for normal closure with its application details, or reject on a connection failure. #[napi] pub async fn closed(&self) -> Result { - // Own the session handle and the cache for the duration of the future - // (see module note). + // Own both handles for the duration of the future (see module note). let session = self.inner.clone(); let cache = self.closed.clone(); - - // Check if we already have a cached result. - { - let cached = cache.lock().await; - if let Some(info) = cached.as_ref() { - return Ok(info.clone()); - } - } - let err = session.closed().await; - let info = session_error_to_close_info(&err); - - // Cache the result. - { - let mut cached = cache.lock().await; - *cached = Some(info.clone()); - } - - Ok(info) + // Only LocallyClosed uses these details. A peer close or connection failure can + // win the backend's first-close race before the native connection is closed. + let local = cache.lock().unwrap().clone(); + session_error_to_close_info(&err, local) } } @@ -921,20 +919,78 @@ impl NapiSendClosed { #[napi] pub struct NapiRecvStream { inner: Arc>, + // Signal cancellation before stop waits for the receive-stream mutex. + stopped: watch::Sender, +} + +impl NapiRecvStream { + fn new(recv: web_transport_quinn::RecvStream) -> Self { + let (stopped, _) = watch::channel(false); + Self { + inner: Arc::new(Mutex::new(recv)), + stopped, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use web_transport_quinn::{quinn::ConnectionError, SessionError, WebTransportError}; + + #[test] + fn backend_close_wins_over_a_racing_local_request() { + let local = || { + Some(NapiCloseInfo { + close_code: 42, + reason: "local".into(), + }) + }; + let peer = SessionError::WebTransportError(WebTransportError::Closed(7, "peer".into())); + let info = session_error_to_close_info(&peer, local()).unwrap(); + assert_eq!((info.close_code, info.reason.as_str()), (7, "peer")); + assert!(session_error_to_close_info( + &SessionError::ConnectionError(ConnectionError::TimedOut), + local() + ) + .is_err()); + let info = session_error_to_close_info( + &SessionError::ConnectionError(ConnectionError::LocallyClosed), + local(), + ) + .unwrap(); + assert_eq!((info.close_code, info.reason.as_str()), (42, "local")); + // A backend/endpoint teardown without Session.close() is a session failure, + // rather than an application close whose details we can report. + assert!(session_error_to_close_info( + &SessionError::ConnectionError(ConnectionError::LocallyClosed), + None + ) + .is_err()); + } } #[napi] impl NapiRecvStream { /// Read up to `max_size` bytes from the stream. Returns null on FIN, or the error if the - /// peer reset the stream or the session failed. + /// peer reset the stream or the session failed. Local cancellation rejects the read. #[napi] pub async fn read(&self, max_size: u32) -> Result>> { use web_transport_quinn::ReadError; - // Own the shared stream for the duration of the future (see module note). + // Own the shared stream and cancellation receiver for the future (see module note). let inner = self.inner.clone(); + let mut stopped = self.stopped.subscribe(); let mut stream = inner.lock().await; - let err = match stream.read_chunk(max_size as usize, true).await { + if *stopped.borrow() { + return Err(Error::from_reason(ReadError::ClosedStream.to_string())); + } + let result = tokio::select! { + biased; + _ = stopped.changed() => return Err(Error::from_reason(ReadError::ClosedStream.to_string())), + result = stream.read_chunk(max_size as usize, true) => result, + }; + let err = match result { Ok(chunk) => { return Ok(chunk.map(|chunk| Either::A(Buffer::from(chunk.bytes.to_vec())))) } @@ -950,13 +1006,14 @@ impl NapiRecvStream { Ok(Some(Either::B(err))) } - /// Tell the peer to stop sending with the given error code. + /// Tell the peer to stop sending with the given code; an already terminal stream is a no-op. #[napi] pub async fn stop(&self, code: u32) -> Result<()> { let inner = self.inner.clone(); + self.stopped.send_replace(true); let mut stream = inner.lock().await; - stream - .stop(code) - .map_err(|e| Error::from_reason(e.to_string())) + // ClosedStream only means FIN, reset, or an earlier stop already made this terminal. + let _ = stream.stop(code); + Ok(()) } } diff --git a/rs/web-transport-noq/README.md b/rs/web-transport-noq/README.md index e0eeabdd..39320282 100644 --- a/rs/web-transport-noq/README.md +++ b/rs/web-transport-noq/README.md @@ -53,6 +53,14 @@ However some of the API is wrapped or unavailable due to WebTransport limitation - Stream IDs are not available. - Error codes are not full VarInts (62-bits) and significantly smaller. +A clean FIN on the HTTP/3 CONNECT stream without a close capsule reports +`WebTransportError::Closed(0, "")`. Malformed or interrupted capsule data reports +`WebTransportError::CapsuleError`, while an already closed native connection retains +its connection error. Explicit local `close` remains `ConnectionError::LocallyClosed`. +`WebTransportError::CapsuleError(String)` adds a diagnostic variant to the public +enum; exhaustive matches must handle it. Dropping a receive stream sends +application code 0 in the session's code space, preserving raw QUIC code 0 for raw sessions. + Session clones share ownership of the connection. Dropping the final `Session` closes it immediately, including raw QUIC sessions, even if streams or native `noq::Connection` handles remain. Keep a `Session` clone while using those handles. @@ -68,6 +76,9 @@ boundary. Already observed native errors are preserved. Peer delivery, endpoint draining and execution of awakened tasks require a live runtime. Forgotten futures, non-yielding tasks and process abort are outside this guarantee. +Raw QUIC stream reset and stop codes are sent unchanged, matching Quinn and Iroh. +Raw receivers also accept HTTP/3-mapped codes from older peers. HTTP/3 stream codes +continue to use the reserved WebTransport mapping, including code 0 on receive drop. ## CONNECT response metadata diff --git a/rs/web-transport-noq/src/error.rs b/rs/web-transport-noq/src/error.rs index 0f60fe5b..2178d4ea 100644 --- a/rs/web-transport-noq/src/error.rs +++ b/rs/web-transport-noq/src/error.rs @@ -70,7 +70,28 @@ impl From for SessionError { } } -/// An error that can occur when reading/writing the WebTransport stream header. +/// The QUIC code to reset or stop a stream with. Raw QUIC sends the code as is, while +/// HTTP/3 maps it into its own code space. +pub(crate) fn encode_stream_code(code: u32, raw: bool) -> noq::VarInt { + if raw { + return code.into(); + } + noq::VarInt::try_from(web_transport_proto::error_to_http3(code)).unwrap() +} + +/// Decode the peer's QUIC code for a stream reset or stop, or None if it is not one. +pub(crate) fn decode_stream_code(code: noq::VarInt, raw: bool) -> Option { + let code = code.into_inner(); + // An older raw peer maps its codes into the HTTP/3 range too. No u32 reaches that + // range, so the mapped form cannot be mistaken for a raw code. + match web_transport_proto::error_from_http3(code) { + Some(code) => Some(code), + None if raw => u32::try_from(code).ok(), + None => None, + } +} + +/// An error in a WebTransport stream header or session capsule. #[derive(Clone, Error, Debug)] pub enum WebTransportError { #[error("closed: code={0} reason={1}")] @@ -84,6 +105,10 @@ pub enum WebTransportError { #[error("write error: {0}")] WriteError(#[from] noq::WriteError), + + /// The session's HTTP/3 capsule stream was malformed or interrupted, with a diagnostic message. + #[error("capsule error: {0}")] + CapsuleError(String), } /// An error when writing to [`crate::SendStream`]. Similar to [`noq::WriteError`]. diff --git a/rs/web-transport-noq/src/recv.rs b/rs/web-transport-noq/src/recv.rs index dcc5af6f..9724016a 100644 --- a/rs/web-transport-noq/src/recv.rs +++ b/rs/web-transport-noq/src/recv.rs @@ -7,26 +7,48 @@ use std::{ use bytes::Bytes; -use crate::{ClosedStream, ReadError, ReadExactError, ReadToEndError, SessionError}; +use crate::{ + error::{decode_stream_code, encode_stream_code}, + ClosedStream, ReadError, ReadExactError, ReadToEndError, SessionError, +}; -/// A stream that can be used to receive bytes. See [`noq::RecvStream`]. +/// A stream that can receive bytes, stopping with application code 0 on drop. See [`noq::RecvStream`]. #[derive(Debug)] pub struct RecvStream { inner: noq::RecvStream, error: Arc>, + raw: bool, +} + +impl Drop for RecvStream { + fn drop(&mut self) { + // FIN, reset, or an earlier stop can already have made the stream terminal. + let _ = self.stop(0); + } } impl RecvStream { - pub(crate) fn new(stream: noq::RecvStream, error: Arc>) -> Self { + pub(crate) fn new( + stream: noq::RecvStream, + error: Arc>, + raw: bool, + ) -> Self { Self { inner: stream, error, + raw, } } /// Replace connection-level errors with the stored session error if available. - fn map_error(&self, e: impl Into) -> ReadError { - let e = e.into(); + fn map_error(&self, e: noq::ReadError) -> ReadError { + let e = match e { + noq::ReadError::Reset(code) => match decode_stream_code(code, self.raw) { + Some(code) => ReadError::Reset(code), + None => ReadError::InvalidReset(code), + }, + e => e.into(), + }; if let Some(err) = self.error.get() { if matches!(&e, ReadError::SessionError(_)) { return ReadError::SessionError(err.clone()); @@ -37,9 +59,9 @@ impl RecvStream { /// 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. + /// A raw QUIC session sends the code as is. 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(); + let code = encode_stream_code(code, self.raw); self.inner.stop(code) } @@ -94,7 +116,7 @@ impl RecvStream { 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())), + Ok(Some(code)) => Ok(decode_stream_code(code, self.raw)), Err(noq::ResetError::ConnectionLost(conn_err)) => { Err(self.error.get().cloned().unwrap_or_else(|| conn_err.into())) } diff --git a/rs/web-transport-noq/src/send.rs b/rs/web-transport-noq/src/send.rs index a54837a3..8d8309ad 100644 --- a/rs/web-transport-noq/src/send.rs +++ b/rs/web-transport-noq/src/send.rs @@ -7,7 +7,10 @@ use std::{ use bytes::{Buf, Bytes}; -use crate::{ClosedStream, SessionError, WriteError}; +use crate::{ + error::{decode_stream_code, encode_stream_code}, + ClosedStream, SessionError, WriteError, +}; /// A stream that can be used to send bytes. See [`noq::SendStream`]. /// @@ -17,16 +20,27 @@ use crate::{ClosedStream, SessionError, WriteError}; pub struct SendStream { stream: noq::SendStream, error: Arc>, + raw: bool, } impl SendStream { - pub(crate) fn new(stream: noq::SendStream, error: Arc>) -> Self { - Self { stream, error } + pub(crate) fn new( + stream: noq::SendStream, + error: Arc>, + raw: bool, + ) -> Self { + Self { stream, error, raw } } /// Replace connection-level errors with the stored session error if available. - fn map_error(&self, e: impl Into) -> WriteError { - let e = e.into(); + fn map_error(&self, e: noq::WriteError) -> WriteError { + let e = match e { + noq::WriteError::Stopped(code) => match decode_stream_code(code, self.raw) { + Some(code) => WriteError::Stopped(code), + None => WriteError::InvalidStopped(code), + }, + e => e.into(), + }; if let Some(err) = self.error.get() { if matches!(&e, WriteError::SessionError(_)) { return WriteError::SessionError(err.clone()); @@ -37,9 +51,9 @@ impl SendStream { /// 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. + /// A raw QUIC session sends the code as is. 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(); + let code = encode_stream_code(code, self.raw); self.stream.reset(code).map_err(Into::into) } @@ -49,7 +63,7 @@ impl SendStream { /// 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(Some(code)) => Ok(decode_stream_code(code, self.raw)), Ok(None) => Ok(None), Err(noq::StoppedError::ConnectionLost(conn_err)) => { Err(self.error.get().cloned().unwrap_or_else(|| conn_err.into())) diff --git a/rs/web-transport-noq/src/session.rs b/rs/web-transport-noq/src/session.rs index cfe6fb73..776e22be 100644 --- a/rs/web-transport-noq/src/session.rs +++ b/rs/web-transport-noq/src/session.rs @@ -209,52 +209,56 @@ impl Session { 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)) => { + Ok((code, reason)) => { let err = WebTransportError::Closed(code, reason.clone()); if error.set(err.into()).is_err() { return; } - conn.close(http3_code, reason.as_bytes()); + if conn.close_reason().is_none() { + conn.close( + web_transport_proto::error_to_http3(code) + .try_into() + .unwrap(), + reason.as_bytes(), + ); + } } - None => { - let err = noq::ConnectionError::LocallyClosed.into(); + Err(cause) => { + let err = conn.close_reason().map(Into::into).unwrap_or_else(|| { + SessionError::WebTransportError(WebTransportError::CapsuleError( + cause.to_string(), + )) + }); if error.set(err).is_err() { return; } - conn.close(http3_code, b""); + if conn.close_reason().is_none() { + // H3_MESSAGE_ERROR: the CONNECT stream did not contain valid capsules. + conn.close(0x10eu32.into(), b"invalid CONNECT capsule stream"); + } } }; } // 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)> { + // A clean FIN without a close capsule is the default successful close. + async fn read_capsules( + recv: noq::RecvStream, + ) -> Result<(u32, String), web_transport_proto::CapsuleError> { 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)), + })) => return Ok((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; - } + Ok(None) => return Ok((0, String::new())), + Err(e) => return Err(e), } } } @@ -294,7 +298,7 @@ impl Session { .accept_uni() .await .map_err(|e| self.map_error(e))?; - Ok(RecvStream::new(recv, self.error.clone())) + Ok(RecvStream::new(recv, self.error.clone(), true)) } } @@ -307,8 +311,8 @@ impl Session { } 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()), + SendStream::new(send, self.error.clone(), self.session_id.is_none()), + RecvStream::new(recv, self.error.clone(), true), )) } } @@ -327,7 +331,11 @@ impl Session { // Reset the stream priority back to the default of 0. send.set_priority(0).ok(); - Ok(SendStream::new(send, self.error.clone())) + Ok(SendStream::new( + send, + self.error.clone(), + self.session_id.is_none(), + )) } /// Open a new bidirectional stream. See [`noq::Connection::open_bi`]. @@ -345,8 +353,8 @@ impl Session { // 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()), + SendStream::new(send, self.error.clone(), self.session_id.is_none()), + RecvStream::new(recv, self.error.clone(), self.session_id.is_none()), )) } @@ -466,6 +474,11 @@ impl Session { // 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. + if let Some(err) = self.conn.close_reason() { + // A capsule task may not have observed it yet; preserve the first reason. + let _ = self.error.set(self.map_error(err)); + return; + } let err = SessionError::ConnectionError(noq::ConnectionError::LocallyClosed); if self.error.set(err).is_err() { return; @@ -915,7 +928,7 @@ impl SessionAccept { // Decide if we keep looping based on the type. match typ { StreamUni::WEBTRANSPORT => { - let recv = RecvStream::new(recv, self.error.clone()); + let recv = RecvStream::new(recv, self.error.clone(), false); return Poll::Ready(Ok(recv)); } StreamUni::QPACK_DECODER => { @@ -995,8 +1008,8 @@ impl SessionAccept { 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()); + let send = SendStream::new(send, self.error.clone(), false); + let recv = RecvStream::new(recv, self.error.clone(), false); return Poll::Ready(Ok((send, recv))); } @@ -1230,6 +1243,141 @@ mod tests { (client_conn, server_conn) } + #[tokio::test] + async fn clean_connect_fin_is_a_default_close() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let (mut peer_send, _peer_recv) = peer.accept_bi().await.unwrap(); + peer_send.finish().unwrap(); + let error = Arc::new(OnceLock::new()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::WebTransportError(WebTransportError::Closed(0, reason))) + if reason.is_empty() + )); + } + + #[tokio::test] + async fn truncated_connect_data_is_a_capsule_error() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let (mut peer_send, _peer_recv) = peer.accept_bi().await.unwrap(); + // DATA frame type, missing the frame length. + peer_send.write_all(&[0]).await.unwrap(); + peer_send.finish().unwrap(); + let error = Arc::new(OnceLock::new()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::WebTransportError( + WebTransportError::CapsuleError(_) + )) + )); + } + + #[tokio::test] + async fn failed_connect_stream_preserves_the_connection_failure() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let _connect = peer.accept_bi().await.unwrap(); + peer.close(0u32.into(), b"failure"); + client.closed().await; + let error = Arc::new(OnceLock::new()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::ConnectionError(noq::ConnectionError::ApplicationClosed(close))) + if close.error_code.into_inner() == 0 && close.reason == b"failure"[..] + )); + } + + #[tokio::test] + async fn local_close_preserves_a_native_failure_before_the_capsule_reader_runs() { + let (session, peer, _connect, _settings, _endpoints) = http3_pair().await; + session._owner.reader.as_ref().unwrap().abort(); + peer.close(0u32.into(), b"failure"); + session.conn.closed().await; + session.close(7, b"local"); + assert!(matches!( + session.closed().await, + SessionError::ConnectionError(noq::ConnectionError::ApplicationClosed(close)) + if close.error_code.into_inner() == 0 && close.reason == b"failure"[..] + )); + } + + #[tokio::test] + async fn raw_stream_codes_round_trip() { + let (client, peer, _endpoints) = pair().await; + let client = Session::raw(client); + let peer = Session::raw(peer); + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let mut recv = peer.accept_uni().await.unwrap(); + recv.stop(17).unwrap(); + assert_eq!(send.stopped().await.unwrap(), Some(17)); + assert!(matches!( + send.write_all(b"more").await, + Err(crate::WriteError::Stopped(17)) + )); + + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let mut recv = peer.accept_uni().await.unwrap(); + let mut buf = [0; 4]; + recv.read_exact(&mut buf).await.unwrap(); + send.reset(7).unwrap(); + assert!(matches!( + recv.read(&mut buf).await, + Err(crate::ReadError::Reset(7)) + )); + } + + #[tokio::test] + async fn receive_stop_uses_the_session_code_space() { + for raw in [false, true] { + let (client, peer, _endpoints) = pair().await; + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let recv = peer.accept_uni().await.unwrap(); + let mut recv = RecvStream::new(recv, Arc::new(OnceLock::new()), raw); + recv.stop(17).unwrap(); + let code = if raw { + 17 + } else { + web_transport_proto::error_to_http3(17) + }; + assert_eq!( + send.stopped().await.unwrap(), + Some(code.try_into().unwrap()) + ); + } + } + + #[tokio::test] + async fn receive_drop_uses_the_session_code_space() { + for raw in [false, true] { + let (client, peer, _endpoints) = pair().await; + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let recv = peer.accept_uni().await.unwrap(); + let recv = RecvStream::new(recv, Arc::new(OnceLock::new()), raw); + drop(recv); + let code = if raw { + 0 + } else { + web_transport_proto::error_to_http3(0) + }; + assert_eq!( + send.stopped().await.unwrap(), + Some(code.try_into().unwrap()) + ); + } + } + async fn http3_pair() -> ( Session, noq::Connection, diff --git a/rs/web-transport-quiche/README.md b/rs/web-transport-quiche/README.md index e98d613c..e37612b6 100644 --- a/rs/web-transport-quiche/README.md +++ b/rs/web-transport-quiche/README.md @@ -54,6 +54,11 @@ Call `Connection::close` before dropping to choose the close code and reason; final drop preserves an explicit close already in progress. Await `Connection::closed` when the application needs the driver to complete teardown. +The CONNECT reader decodes capsules inside HTTP/3 DATA frames. A clean FIN +without a close capsule closes the session with application code 0 and an empty +reason. Malformed capsules fail with H3_MESSAGE_ERROR, preserving any native +connection failure already observed. + ## Send-rate statistics `Connection::stats()` returns `ez::ConnectionStats`; its `send_rate` field and diff --git a/rs/web-transport-quiche/src/connection.rs b/rs/web-transport-quiche/src/connection.rs index ba537a4d..56ee2a1d 100644 --- a/rs/web-transport-quiche/src/connection.rs +++ b/rs/web-transport-quiche/src/connection.rs @@ -207,8 +207,9 @@ impl Connection { // Keep reading from the control stream until it's closed. async fn run_closed(conn: ez::Connection, mut connect: h3::Connected) { + let mut reader = web_transport_proto::Http3CapsuleReader::new(&mut connect.recv); loop { - match web_transport_proto::Capsule::read(&mut connect.recv).await { + match reader.read().await { Ok(Some(web_transport_proto::Capsule::CloseWebTransportSession { code, reason, @@ -223,11 +224,14 @@ impl Connection { tracing::warn!("unknown capsule: type={typ} size={}", payload.len()); } Ok(None) => { - // Stream closed without capsule + conn.close(web_transport_proto::error_to_http3(0), ""); return; } Err(_) => { - conn.close(web_transport_proto::error_to_http3(500), "capsule error"); + if !conn.is_closed() { + // H3_MESSAGE_ERROR: the CONNECT stream did not contain valid capsules. + conn.close(0x10e, "invalid CONNECT capsule stream"); + } return; } } @@ -1098,6 +1102,53 @@ mod tests { }) } + #[tokio::test] + async fn clean_connect_fin_is_a_default_close() -> Result<()> { + let mut pair = http_pair().await?; + pair._connect.send.finish()?; + let closed = timeout(TIMEOUT, pair.session.closed()).await?; + assert!(matches!(closed, SessionError::Local(0, reason) if reason.is_empty())); + Ok(()) + } + + #[tokio::test] + async fn data_framed_close_capsule_preserves_application_details() -> Result<()> { + let mut pair = http_pair().await?; + let mut capsule = BytesMut::new(); + web_transport_proto::Capsule::CloseWebTransportSession { + code: 7, + reason: "done".into(), + } + .encode(&mut capsule); + let mut frame = BytesMut::new(); + web_transport_proto::Frame::DATA.encode(&mut frame); + VarInt::try_from(capsule.len())?.encode(&mut frame); + frame.extend_from_slice(&capsule); + pair._connect.send.write_all(&frame).await?; + pair._connect.send.finish()?; + let closed = timeout(TIMEOUT, pair.session.closed()).await?; + assert!(matches!(closed, SessionError::Local(7, reason) if reason == "done")); + Ok(()) + } + + #[tokio::test] + async fn truncated_capsule_is_a_protocol_error() -> Result<()> { + let mut pair = http_pair().await?; + // A DATA frame carrying the first byte of a two-byte capsule type, with no second byte. + let mut frame = BytesMut::new(); + web_transport_proto::Frame::DATA.encode(&mut frame); + VarInt::from_u32(1).encode(&mut frame); + frame.extend_from_slice(&[0x68]); + pair._connect.send.write_all(&frame).await?; + pair._connect.send.finish()?; + let closed = timeout(TIMEOUT, pair.session.closed()).await?; + assert!(matches!( + closed, + SessionError::Connection(ez::ConnectionError::Local(0x10e, _)) + )); + Ok(()) + } + #[tokio::test] async fn final_http_frontend_drop_closes_with_connect_held_open() -> Result<()> { let HttpPair { diff --git a/rs/web-transport-quinn/README.md b/rs/web-transport-quinn/README.md index 2db3274f..a59562a5 100644 --- a/rs/web-transport-quinn/README.md +++ b/rs/web-transport-quinn/README.md @@ -137,6 +137,15 @@ An explicit `LowLatency` or `Throughput` congestion choice overrides only the co Quinn's `TransportConfig` is not cloneable, so `ClientBuilder` owns it and does not implement `Clone`. Construct a builder for each configuration, then clone the finished `Client` to share its endpoints and settings across connections. ## API +`Session::closed` preserves the first close reason. A clean CONNECT-stream FIN without +a close capsule reports `WebTransportError::Closed(0, "")`; malformed or interrupted +capsules report `WebTransportError::CapsuleError` unless the underlying connection has +already reported its own error. An explicit local close reports `ConnectionError::LocallyClosed`. + +`WebTransportError::CapsuleError(String)` adds a diagnostic variant to the public +enum; exhaustive matches must handle it. Dropping a receive stream sends +application code 0 in the session's code space, preserving raw QUIC code 0 for raw sessions. + The `web-transport-quinn` API is almost identical to the Quinn API, except that [Connection](https://docs.rs/quinn/latest/quinn/struct.Connection.html) is called [Session](https://docs.rs/web-transport-quinn/latest/web_transport_quinn/struct.Session.html). When possible, `Deref` is used to expose the underlying Quinn API. diff --git a/rs/web-transport-quinn/src/error.rs b/rs/web-transport-quinn/src/error.rs index 39698582..beb4220a 100644 --- a/rs/web-transport-quinn/src/error.rs +++ b/rs/web-transport-quinn/src/error.rs @@ -165,7 +165,7 @@ pub(crate) fn decode_stream_code(code: quinn::VarInt, raw: bool) -> Option } } -/// An error that can occur when reading/writing the WebTransport stream header. +/// An error in a WebTransport stream header or session capsule. #[derive(Clone, Error, Debug)] pub enum WebTransportError { #[error("closed: code={0} reason={1}")] @@ -179,6 +179,10 @@ pub enum WebTransportError { #[error("write error: {0}")] WriteError(#[from] quinn::WriteError), + + /// The session's HTTP/3 capsule stream was malformed or interrupted, with a diagnostic message. + #[error("capsule error: {0}")] + CapsuleError(String), } /// An error when writing to [`crate::SendStream`]. Similar to [`quinn::WriteError`]. diff --git a/rs/web-transport-quinn/src/recv.rs b/rs/web-transport-quinn/src/recv.rs index c7e40c4e..b02093d1 100644 --- a/rs/web-transport-quinn/src/recv.rs +++ b/rs/web-transport-quinn/src/recv.rs @@ -14,7 +14,7 @@ use crate::{ ReadError, ReadExactError, ReadToEndError, SessionError, }; -/// A stream that can be used to recieve bytes. See [`quinn::RecvStream`]. +/// A stream that can receive bytes, stopping with application code 0 on drop. See [`quinn::RecvStream`]. #[derive(Debug)] pub struct RecvStream { inner: quinn::RecvStream, @@ -23,6 +23,14 @@ pub struct RecvStream { raw: bool, } +impl Drop for RecvStream { + fn drop(&mut self) { + // Use the session's code space rather than Quinn's implicit raw QUIC code 0. + // FIN, reset, or an earlier stop can already have made the stream terminal. + let _ = self.stop(0); + } +} + impl RecvStream { pub(crate) fn new(stream: quinn::RecvStream, error: Arc, raw: bool) -> Self { Self { diff --git a/rs/web-transport-quinn/src/session.rs b/rs/web-transport-quinn/src/session.rs index 5af0dba3..e2d46911 100644 --- a/rs/web-transport-quinn/src/session.rs +++ b/rs/web-transport-quinn/src/session.rs @@ -220,59 +220,54 @@ impl Session { // then record the close error and tear down the connection. async fn run_recv(conn: quinn::Connection, recv: quinn::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: quinn::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)) => { + Ok((code, reason)) => { let err = WebTransportError::Closed(code, reason.clone()); if error.set(err.into()).is_err() { return; } if conn.close_reason().is_none() { - conn.close(http3_code, reason.as_bytes()); + conn.close( + crate::error::encode_stream_code(code, false), + reason.as_bytes(), + ); } } - None => { - let err = conn - .close_reason() - .unwrap_or(quinn::ConnectionError::LocallyClosed) - .into(); + Err(cause) => { + let err = conn.close_reason().map(Into::into).unwrap_or_else(|| { + SessionError::WebTransportError(WebTransportError::CapsuleError( + cause.to_string(), + )) + }); if error.set(err).is_err() { return; } if conn.close_reason().is_none() { - conn.close(http3_code, b""); + // H3_MESSAGE_ERROR: the CONNECT stream did not contain valid capsules. + conn.close(0x10eu32.into(), b"invalid CONNECT capsule stream"); } } }; } // 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: quinn::RecvStream) -> Option<(u32, String)> { + // A clean FIN without a close capsule is the default successful close. + async fn read_capsules( + recv: quinn::RecvStream, + ) -> Result<(u32, String), web_transport_proto::CapsuleError> { 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)), + })) => return Ok((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; - } + Ok(None) => return Ok((0, String::new())), + Err(e) => return Err(e), } } } @@ -456,7 +451,7 @@ impl Session { fn close_on(&self, code: u32, reason: &[u8], runtime: Option>) { // 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. A raw peer close that already arrived is latched first. + // this is a no-op. A native failure that already arrived is latched first. if let Some(err) = self.conn.close_reason() { // `map_error` decodes raw codes too, but only raw mapping latches the // result itself. Preserve an observed HTTP/3 peer close before returning. @@ -1965,7 +1960,9 @@ mod tests { session.close(42, b"bye"); drop(session); assert_eq!( - Session::read_capsules(connect.take().unwrap().recv).await, + Session::read_capsules(connect.take().unwrap().recv) + .await + .ok(), Some((42, "bye".into())) ); peer.close(0u32.into(), b"ack"); @@ -1994,6 +1991,91 @@ mod tests { } } + #[tokio::test] + async fn local_close_preserves_a_native_failure_before_the_capsule_reader_runs() { + let (client, peer, _endpoints) = pair().await; + let mut session = Session::raw(client); + // Model an HTTP/3 session whose capsule task has not recorded the failure yet. + session.session_id = Some(SESSION); + session.error = Arc::new(CloseReason::http3()); + peer.close(0u32.into(), b"failure"); + session.conn.closed().await; + session.close(7, b"local"); + assert!(matches!( + session.closed().await, + SessionError::ConnectionError(quinn::ConnectionError::ApplicationClosed(close)) + if close.error_code.into_inner() == 0 && close.reason == b"failure"[..] + )); + } + + #[tokio::test] + async fn receive_drop_uses_the_session_code_space() { + for raw in [false, true] { + let (client, peer, _endpoints) = pair().await; + let mut send = client.open_uni().await.unwrap(); + send.write_all(b"data").await.unwrap(); + let recv = peer.accept_uni().await.unwrap(); + let recv = RecvStream::new(recv, Arc::new(CloseReason::http3()), raw); + drop(recv); + assert_eq!( + send.stopped().await.unwrap(), + Some(crate::error::encode_stream_code(0, raw)) + ); + } + } + + #[tokio::test] + async fn clean_connect_fin_is_a_default_close() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let (mut peer_send, _peer_recv) = peer.accept_bi().await.unwrap(); + peer_send.finish().unwrap(); + let error = Arc::new(CloseReason::http3()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::WebTransportError(WebTransportError::Closed(0, reason))) + if reason.is_empty() + )); + } + + #[tokio::test] + async fn truncated_connect_data_is_a_capsule_error() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let (mut peer_send, _peer_recv) = peer.accept_bi().await.unwrap(); + // DATA frame type, missing the frame length. + peer_send.write_all(&[0]).await.unwrap(); + peer_send.finish().unwrap(); + let error = Arc::new(CloseReason::http3()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::WebTransportError( + WebTransportError::CapsuleError(_) + )) + )); + } + + #[tokio::test] + async fn failed_connect_stream_preserves_the_connection_failure() { + let (client, peer, _endpoints) = pair().await; + let (mut send, recv) = client.open_bi().await.unwrap(); + send.write_all(b"connect").await.unwrap(); + let _connect = peer.accept_bi().await.unwrap(); + peer.close(0u32.into(), b"failure"); + client.closed().await; + let error = Arc::new(CloseReason::http3()); + Session::run_recv(client, recv, error.clone()).await; + assert!(matches!( + error.get(), + Some(SessionError::ConnectionError(quinn::ConnectionError::ApplicationClosed(close))) + if close.error_code.into_inner() == 0 && close.reason == b"failure"[..] + )); + } + fn assert_reset(err: SessionError) { assert!( matches!(