@statewalker/webrun-streams-webrtc 0.1.1 → 0.1.2

package/README.md

@@ -1,16 +1,164 @@
 # @statewalker/webrun-streams-webrtc
 
-WebRTC native multi-stream `Connect` / `Serve` adapter. Each `call(input)` opens a fresh `RTCDataChannel` on the supplied `RTCPeerConnection`; the responder listens on `pc.ondatachannel`.
+WebRTC `Connect` / `Serve` adapter in the `webrun-streams-*` family, with
+**native multi-stream** — one `RTCDataChannel` per logical call.
 
-DataChannels have no native half-close, so the adapter carries a tiny 1-byte frame protocol inside each DC message: `DATA` (0x00, body bytes), `END` (0x01, half-close), `ERROR` (0x02, serialised error). Outbound bytes are chunked at 16 KiB.
+## What this is
+
+A binding between an `RTCPeerConnection` and the
+[`webrun-streams`](../webrun-streams) `Duplex` seam. Your handler is an
+ordinary `Duplex` —
+`(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` — and this
+package carries it directly between two browsers with no server in the data
+path.
+
+Unlike the message-oriented adapters (WebSocket, MessagePort, LiveKit, PeerJS),
+this one does **not** use `emulateMux`. WebRTC can open as many data channels as
+you want, so each `call(input)` opens its own `RTCDataChannel` and the responder
+picks it up via `pc.ondatachannel`. Concurrency is the transport's, not
+emulated.
+
+## Why it exists
+
+`RTCDataChannel` is a good byte pipe with two gaps that every user hits:
+
+1. **No half-close.** A channel is open or closed; there is no way to say
+   "I'm done sending, keep receiving". Request/response needs exactly that.
+2. **No error channel.** If the far end throws, the near end sees a closed
+   channel and no reason.
+
+This adapter closes both gaps with a one-byte frame header inside each data
+channel message:
+
+| Byte | Frame | Payload |
+| --- | --- | --- |
+| `0x00` | `DATA` | body bytes |
+| `0x01` | `END` | — (half-close) |
+| `0x02` | `ERROR` | serialised `Error` (message, stack, custom fields) |
+
+Outbound bytes are chunked at 16 KiB to stay inside the SCTP message limits
+that browsers enforce.
+
+## Install
+
+```sh
+npm install @statewalker/webrun-streams-webrtc
+```
+
+No peer dependencies. In the browser `RTCPeerConnection` is built in; in Node
+tests it is supplied by [`@roamhq/wrtc`](https://www.npmjs.com/package/@roamhq/wrtc).
+
+## Getting started
+
+**Signalling, auth and connection setup are the caller's responsibility.** This
+package takes an already-open `RTCPeerConnection` and does nothing else. If you
+need signalling too, see
+[`@statewalker/webrun-streams-signaling`](../webrun-streams-signaling), which
+produces connected peers for you.
+
+Responder side — register a handler:
+
+```ts
+import { serve } from "@statewalker/webrun-streams-webrtc";
+
+const stop = await serve({ pc }, async function* echo(input) {
+  for await (const chunk of input) yield chunk;
+});
+```
+
+Caller side — open calls over the same peer connection:
+
+```ts
+import { connect } from "@statewalker/webrun-streams-webrtc";
+
+const { call, close } = await connect({ pc });
+
+for await (const chunk of call([new TextEncoder().encode("ping")])) {
+  console.log(new TextDecoder().decode(chunk)); // "ping"
+}
+
+await close();
+```
+
+### Concurrent calls
+
+Every `call(...)` gets its own data channel, so calls are genuinely parallel:
+
+```ts
+import { collectBytes } from "@statewalker/webrun-streams";
+
+const [a, b] = await Promise.all([
+  collectBytes(call(requestA)),
+  collectBytes(call(requestB)),
+]);
+```
+
+### Carrying HTTP over it
+
+Pair with [`webrun-http-streams`](../webrun-http-streams) to exchange real
+`Request` / `Response` objects — including streaming bodies and SSE — directly
+between two browsers:
 
 ```ts
-import { connect, serve } from "@statewalker/webrun-streams-webrtc";
+import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
 
-const { call } = await connect({ pc });          // RTCPeerConnection
-const stop = await serve({ pc }, handler);
+const response = await fetchOverDuplex(call, new Request("http://peer/api/events"));
 ```
 
+See [`apps/p2p-demo`](../../apps/p2p-demo) for this running end to end.
+
+## API
+
+### `connect(params): Promise<{ call, close }>`
+
+Type: `Connect<WebRtcParams>`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `pc` | `RTCPeerConnection` | An already-open peer connection. |
+
+Each `call(input)` opens a fresh `RTCDataChannel`. `close()` tears down the
+adapter's channels; it does not close `pc`, which you own.
+
+### `serve(params, handler): Promise<() => Promise<void>>`
+
+Type: `Serve<WebRtcParams>`. Listens on `pc.ondatachannel` and runs `handler`
+for each inbound channel. Returns an idempotent teardown.
+
+### `duplexOverDataChannel(channel, options?): Duplex`
+
+The lower-level primitive: wraps a single `RTCDataChannel` as one `Duplex`,
+implementing the DATA/END/ERROR framing described above. Use it when you manage
+channel creation yourself.
+
+### `WebRtcParams`
+
+The parameter type shared by `connect` and `serve`.
+
+## Conformance
+
+Runs [`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance)
+against a real `RTCPeerConnection` pair — concurrency, half-close, mid-stream
+cancellation, error propagation and idempotent teardown.
+
+The suite is **browser-gated**: `tests/conformance.test.ts` checks for a
+`window` global and registers the suite only there, so the plain Node run
+reports it as skipped.
+
+```sh
+pnpm --filter @statewalker/webrun-streams-webrtc test:browser   # runs the suite
+pnpm --filter @statewalker/webrun-streams-webrtc test           # reports it skipped
+```
+
+## Dependencies
+
+| Dependency | Kind | Why |
+| --- | --- | --- |
+| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam and error serialisation. |
+| `@roamhq/wrtc` | dev | `RTCPeerConnection` for the Node conformance run. |
+
+No runtime dependencies outside the workspace. ESM only (`"type": "module"`).
+
 ## License
 
-MIT
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/connect-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAG1E,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,YAAY,CAyCzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,YAAY,CAoBrC,CAAC"}
+{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAG1E,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,YAAY,CAyCzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,YAAY,CA4BrC,CAAC"}

package/dist/index.js

@@ -98,12 +98,19 @@ async function* runStream(dc, input) {
 			maybeClose();
 		}
 	})();
+	let inboundDrained = false;
 	try {
 		for await (const chunk of incoming.iterate()) yield chunk;
+		inboundDrained = true;
 	} finally {
 		dc.removeEventListener("message", onMessage);
 		dc.removeEventListener("close", onClose);
-		await outbound.catch(() => {});
+		if (!inboundDrained) {
+			await outbound.catch(() => {});
+			try {
+				dc.close();
+			} catch {}
+		}
 	}
 }
 function makeInboundQueue() {
@@ -201,13 +208,16 @@ const connect = async ({ pc }) => {
 const serve = async ({ pc }, handler) => {
 	const onChannel = (ev) => {
 		const dc = ev.channel;
+		let inputFromPeer = null;
 		(async () => {
 			await waitForOpen(dc);
-			const inputFromPeer = peekInput(dc);
+			inputFromPeer = peekInput(dc);
 			const out = handler(inputFromPeer.input);
 			for await (const chunk of duplexOverDataChannel(dc, out)) inputFromPeer.deliver(chunk);
 			inputFromPeer.done();
-		})();
+		})().catch(() => {
+			inputFromPeer?.done();
+		});
 	};
 	pc.addEventListener("datachannel", onChannel);
 	let torn = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-webrtc",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "WebRTC DataChannel-backed Connect/Serve adapter (native multi-stream) in the webrun-streams-* family",
@@ -15,28 +15,34 @@
     "url": "git@github.com:statewalker/webrun-wire.git"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "0.1.1"
+    "@statewalker/webrun-streams": "0.2.0"
   },
   "devDependencies": {
     "@roamhq/wrtc": "^0.8.0",
     "@types/node": "^26.2.0",
+    "@vitest/browser-playwright": "^4.1.10",
+    "playwright": "^1.62.1",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@statewalker/webrun-streams-conformance": "0.1.1"
+    "@statewalker/webrun-streams-conformance": "0.2.0"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",

package/src/connect-serve.ts

@@ -62,15 +62,23 @@ export const connect: Connect<WebRtcParams> = async ({ pc }) => {
 export const serve: Serve<WebRtcParams> = async ({ pc }, handler: Duplex) => {
   const onChannel = (ev: RTCDataChannelEvent): void => {
     const dc = ev.channel;
+    let inputFromPeer: PeekInput | null = null;
     void (async () => {
       await waitForOpen(dc);
-      const inputFromPeer = peekInput(dc);
+      inputFromPeer = peekInput(dc);
       const out = handler(inputFromPeer.input);
       for await (const chunk of duplexOverDataChannel(dc, out)) {
         inputFromPeer.deliver(chunk);
       }
       inputFromPeer.done();
-    })();
+    })().catch(() => {
+      // A caller that cancels mid-response closes the DataChannel, which
+      // surfaces here as TransportClosedError. That is the cancellation
+      // working, not a fault: this task is fire-and-forget, so without a
+      // catch it becomes an unhandled rejection that fails the page. Closing
+      // the handler's input is what runs the handler's own `finally`.
+      inputFromPeer?.done();
+    });
   };
   pc.addEventListener("datachannel", onChannel);
   let torn = false;

package/src/duplex-over-data-channel.ts

@@ -130,15 +130,46 @@ async function* runStream(
     }
   })();
 
+  let inboundDrained = false;
   try {
     for await (const chunk of incoming.iterate()) {
       yield chunk;
     }
+    inboundDrained = true;
   } finally {
     dc.removeEventListener("message", onMessage);
     dc.removeEventListener("close", onClose);
-    // Wait for outbound to settle so close() doesn't truncate in-flight sends.
-    await outbound.catch(() => {});
+    // Wait for outbound to settle so an early exit doesn't truncate in-flight
+    // sends — but ONLY on an early exit.
+    //
+    // Awaiting it unconditionally deadlocks a responder. `serve` feeds the
+    // handler from the values this generator yields and closes the handler's
+    // input only once this generator completes. So on a normal finish the
+    // cycle is: inbound ends -> we await outbound -> outbound is draining the
+    // handler's output -> the handler is blocked on its input -> its input is
+    // closed only after we return. Nothing moves, and every test that runs a
+    // request to completion hangs.
+    //
+    // When inbound drained on its own the peer has already said it is done, so
+    // there is nothing of theirs left to truncate; outbound keeps running on
+    // its own and `maybeClose` still closes the channel once both halves end.
+    if (!inboundDrained) {
+      await outbound.catch(() => {});
+      // The consumer walked away mid-response (`.return()` on the generator),
+      // or the peer errored. Either way this call is over while the peer may
+      // still be producing, and a DataChannel has no half-close to say so —
+      // `TYPE_END` means "I am done sending", which the outbound pump has
+      // already said and which the peer answers by carrying on. Closing the
+      // channel is the only cancellation signal available: the responder's
+      // `onClose` then ends its inbound queue, which closes the handler's
+      // input and runs the handler's `finally`. Without this, cancellation is
+      // silently local and the handler leaks until the connection drops.
+      try {
+        dc.close();
+      } catch {
+        /* already closing */
+      }
+    }
   }
 }
 

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022-2026 statewalker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.