@moq/web-transport 0.0.4 → 0.1.1

package/README.md

@@ -0,0 +1,141 @@
+# @moq/web-transport
+
+WebTransport for Node.js, powered by native QUIC/HTTP3 via NAPI-RS.
+
+Provides a custom client and server API for setup, then exposes the standard [W3C WebTransport API](https://www.w3.org/TR/webtransport/) for streams, datagrams, and session lifecycle.
+
+## Installation
+
+```bash
+bun add @moq/web-transport
+```
+
+## Client
+
+Connect to a WebTransport server using the `Session` class, which implements the W3C `WebTransport` interface:
+
+```ts
+import Session from "@moq/web-transport";
+
+const session = new Session("https://example.com:4443/path");
+await session.ready;
+
+// Use the standard W3C WebTransport API from here on
+```
+
+### Certificate options
+
+```ts
+// Skip certificate verification (testing only!)
+const session = new Session("https://localhost:4443", {
+	serverCertificateDisableVerify: true,
+});
+
+// Pin to specific certificate hashes
+const session = new Session("https://localhost:4443", {
+	serverCertificateHashes: [
+		{ algorithm: "sha-256", value: certHash },
+	],
+});
+```
+
+### Polyfill
+
+Install `Session` as the global `WebTransport` for libraries that expect the browser API:
+
+```ts
+import { install } from "@moq/web-transport";
+
+install(); // globalThis.WebTransport = Session (no-op if already defined)
+```
+
+## Server
+
+Use `Server` to accept incoming connections. Each `Request` can be accepted (returning a W3C `Session`) or rejected:
+
+```ts
+import { Server } from "@moq/web-transport";
+import fs from "node:fs";
+
+const cert = fs.readFileSync("cert.pem");
+const key = fs.readFileSync("key.pem");
+
+const server = Server.bind("[::]:4443", cert, key);
+
+while (true) {
+	const request = await server.accept();
+	if (!request) break;
+
+	const url = await request.url;
+	console.log("incoming session:", url);
+
+	const session = await request.ok(); // or request.reject(404)
+
+	// Use the standard W3C WebTransport API from here on
+	handleSession(session);
+}
+
+// Stop accepting new connections
+server.close();
+```
+
+## W3C WebTransport API
+
+Once you have a `Session` (client or server-side), the API follows the [W3C WebTransport spec](https://www.w3.org/TR/webtransport/):
+
+### Bidirectional streams
+
+```ts
+// Open a bidirectional stream
+const stream = await session.createBidirectionalStream();
+const writer = stream.writable.getWriter();
+await writer.write(new Uint8Array([1, 2, 3]));
+await writer.close();
+
+// Accept incoming bidirectional streams
+const reader = session.incomingBidirectionalStreams.getReader();
+const { value: incoming } = await reader.read();
+const data = await new Response(incoming.readable).arrayBuffer();
+```
+
+### Unidirectional streams
+
+```ts
+// Open a unidirectional stream
+const writable = await session.createUnidirectionalStream();
+const writer = writable.getWriter();
+await writer.write(new TextEncoder().encode("hello"));
+await writer.close();
+
+// Accept incoming unidirectional streams
+const reader = session.incomingUnidirectionalStreams.getReader();
+const { value: readable } = await reader.read();
+const text = await new Response(readable).text();
+```
+
+### Datagrams
+
+```ts
+// Send datagrams
+const writer = session.datagrams.writable.getWriter();
+await writer.write(new Uint8Array([0x01, 0x02]));
+
+// Receive datagrams
+const reader = session.datagrams.readable.getReader();
+const { value: datagram } = await reader.read();
+```
+
+### Closing
+
+```ts
+// Close gracefully
+session.close({ closeCode: 0, reason: "done" });
+
+// Wait for the session to close
+const info = await session.closed;
+console.log(info.closeCode, info.reason);
+```
+
+## License
+
+MIT OR Apache-2.0

package/{index.d.ts → napi.d.ts}

@@ -59,6 +59,8 @@ export declare class NapiServer {
 	static bind(addr: string, certPem: Buffer, keyPem: Buffer): NapiServer;
 	/** Accept the next incoming WebTransport session request. */
 	accept(): Promise<NapiRequest | null>;
+	/** Close the server, stopping it from accepting new connections. */
+	close(): void;
 }
 
 /** An established WebTransport session. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@moq/web-transport",
-	"version": "0.0.4",
+	"version": "0.1.1",
 	"description": "WebTransport polyfill for Node.js via QUIC/HTTP3",
 	"type": "module",
 	"license": "(MIT OR Apache-2.0)",
@@ -21,12 +21,12 @@
 	"types": "./src/index.ts",
 	"files": [
 		"./src",
-		"index.js",
-		"index.d.ts",
+		"napi.js",
+		"napi.d.ts",
 		"*.node"
 	],
 	"scripts": {
-		"build": "napi build --platform --release --manifest-path ../../rs/web-transport-node/Cargo.toml --output-dir .",
+		"build": "napi build --platform --release --manifest-path ../../rs/web-transport-node/Cargo.toml --output-dir . --js napi.js --dts napi.d.ts",
 		"check": "tsc --noEmit",
 		"release": "bun scripts/release.ts"
 	},
@@ -36,11 +36,11 @@
 		"@types/node": "^24.3.0"
 	},
 	"optionalDependencies": {
-		"@moq/web-transport-darwin-x64": "0.0.4",
-		"@moq/web-transport-darwin-arm64": "0.0.4",
-		"@moq/web-transport-win32-x64-msvc": "0.0.4",
-		"@moq/web-transport-linux-x64-gnu": "0.0.4",
-		"@moq/web-transport-linux-arm64-gnu": "0.0.4"
+		"@moq/web-transport-darwin-x64": "0.1.1",
+		"@moq/web-transport-darwin-arm64": "0.1.1",
+		"@moq/web-transport-win32-x64-msvc": "0.1.1",
+		"@moq/web-transport-linux-x64-gnu": "0.1.1",
+		"@moq/web-transport-linux-arm64-gnu": "0.1.1"
 	},
 	"keywords": [
 		"webtransport",

package/src/datagrams.ts

@@ -1,4 +1,4 @@
-import type { NapiSession } from "../index.js";
+import type { NapiSession } from "../napi.js";
 
 export class Datagrams implements WebTransportDatagramDuplexStream {
 	readonly readable: ReadableStream<Uint8Array>;

package/src/index.ts

@@ -9,4 +9,6 @@ export function install(): boolean {
 }
 
 export default Session;
-export { NapiRequest, NapiServer } from "../index.js";
+export { Request } from "./request.ts";
+export { Server } from "./server.ts";
+export type { SessionOptions } from "./session.ts";

package/src/request.ts

@@ -0,0 +1,24 @@
+import type { NapiRequest } from "../napi.js";
+import Session from "./session.ts";
+
+export class Request {
+	#inner: NapiRequest;
+
+	/** @internal */
+	constructor(inner: NapiRequest) {
+		this.#inner = inner;
+	}
+
+	get url(): Promise<string> {
+		return this.#inner.url;
+	}
+
+	async ok(): Promise<Session> {
+		const session = await this.#inner.ok();
+		return new Session(session);
+	}
+
+	reject(status: number): Promise<void> {
+		return this.#inner.reject(status);
+	}
+}

package/src/server.ts

@@ -0,0 +1,24 @@
+import { NapiServer } from "../napi.js";
+import { Request } from "./request.ts";
+
+export class Server {
+	#inner: NapiServer;
+
+	private constructor(inner: NapiServer) {
+		this.#inner = inner;
+	}
+
+	static bind(addr: string, certPem: Buffer, keyPem: Buffer): Server {
+		return new Server(NapiServer.bind(addr, certPem, keyPem));
+	}
+
+	async accept(): Promise<Request | null> {
+		const inner = await this.#inner.accept();
+		if (!inner) return null;
+		return new Request(inner);
+	}
+
+	close(): void {
+		this.#inner.close();
+	}
+}

package/src/session.ts

@@ -1,4 +1,4 @@
-import { NapiClient, type NapiRecvStream, type NapiSendStream, type NapiSession } from "../index.js";
+import { NapiClient, type NapiRecvStream, type NapiSendStream, type NapiSession } from "../napi.js";
 import { Datagrams } from "./datagrams.ts";
 
 function wrapRecvStream(recv: NapiRecvStream): ReadableStream<Uint8Array> {