@statewalker/webrun-streams-ws 0.1.1 → 0.2.2

package/README.md

@@ -1,24 +1,176 @@
 # @statewalker/webrun-streams-ws
 
-WebSocket-backed `Connect` / `Serve` adapter in the `webrun-streams-*` family. Each `WebSocket` is one byte channel; `emulateMux` provides the multi-stream layer on top.
+WebSocket-backed `Connect` / `Serve` adapter in the `webrun-streams-*` family.
+
+## What this is
+
+A binding between a `WebSocket` and the [`webrun-streams`](../webrun-streams)
+`Duplex` seam. One `WebSocket` becomes one
+[`ByteChannel`](../webrun-streams#the-duplex-seam); `emulateMux` layers many
+concurrent logical calls on top of that single socket.
+
+The point is that your handler never mentions WebSockets. It is an ordinary
+`Duplex` — `(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` —
+so the same function runs unchanged over a `MessagePort`, a WebRTC data
+channel, libp2p, or an in-process pipe. Swapping transports is swapping the
+import.
+
+## Why it exists
+
+A raw `WebSocket` gives you one unordered-in-practice message pipe with no
+notion of a request, no concurrency, no half-close, and no way to propagate an
+error from the far end as an `Error`. Everything above it has to reinvent
+framing, correlation and teardown.
+
+This adapter supplies the missing piece exactly once: it wraps the socket as a
+`ByteChannel`, and `emulateMux` turns that into as many independent
+back-pressured byte streams as you need — each with proper end-of-stream,
+mid-stream cancellation, and error propagation.
+
+## Install
+
+```sh
+npm install @statewalker/webrun-streams-ws
+```
+
+In the browser the global `WebSocket` is used automatically. In Node, supply a
+constructor — the [`ws`](https://www.npmjs.com/package/ws) package works as-is:
+
+```sh
+npm install ws
+```
+
+## Getting started
+
+Serve a handler over an in-process `WebSocketServer` and call it:
 
 ```ts
 import { connect, serve } from "@statewalker/webrun-streams-ws";
 import { WebSocket as NodeWebSocket, WebSocketServer } from "ws";
 
 const wss = new WebSocketServer({ port: 8080 });
+
+// The handler is a plain Duplex: bytes in, bytes out.
 const stop = await serve(
-  { onConnection: (cb) => { wss.on("connection", cb); return () => wss.off("connection", cb); } },
-  async function* (input) { for await (const c of input) yield c; },
+  {
+    onConnection: (cb) => {
+      wss.on("connection", cb);
+      return () => wss.off("connection", cb);
+    },
+  },
+  async function* echo(input) {
+    for await (const chunk of input) yield chunk;
+  },
 );
 
-const { call } = await connect({ url: "ws://localhost:8080", WebSocketCtor: NodeWebSocket });
+const { call, close } = await connect({
+  url: "ws://localhost:8080",
+  WebSocketCtor: NodeWebSocket, // omit in the browser
+});
+
+for await (const chunk of call([new TextEncoder().encode("hello")])) {
+  console.log(new TextDecoder().decode(chunk)); // "hello"
+}
+
+await close();
+await stop();
 ```
 
+In a browser the client side is just:
+
+```ts
+const { call, close } = await connect({ url: "wss://example.com/socket" });
+```
+
+### Concurrent calls
+
+Each `call(...)` is an independent stream over the same socket. They interleave
+without interfering:
+
+```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 move real
+`Request` / `Response` objects across the socket:
+
+```ts
+import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
+
+const response = await fetchOverDuplex(call, new Request("http://x/api/todo"));
+```
+
+## API
+
+### `connect(params): Promise<{ call, close }>`
+
+Opens a `WebSocket` and resolves once it is open. Type: `Connect<ConnectWsParams>`.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `url` | `string` | — | WebSocket URL (`ws://` or `wss://`). |
+| `protocols` | `string \| string[]` | — | Subprotocol(s) passed to the constructor. |
+| `WebSocketCtor` | constructor | global `WebSocket` | Constructor to use. Required where there is no global `WebSocket` (Node). |
+| `mux` | `EmulateMuxOptions` | `emulateMux`'s own | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"initiator"` regardless of `mux.side`. |
+
+Resolves to `{ call: Duplex, close: () => Promise<void> }`. Each `call(input)`
+opens a fresh logical stream; `close()` tears down the socket and every stream
+on it.
+
+### `serve(params, handler): Promise<() => Promise<void>>`
+
+Registers `handler` against a source of inbound sockets. Type: `Serve<ServeWsParams>`.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `onConnection` | `(cb: (ws: WebSocketLike) => void) => () => void` | Subscribes to inbound connections; returns an unsubscribe function. |
+| `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is always `"responder"` regardless of `mux.side`. |
+
+The indirection means this package never depends on a particular server
+library — wire it to `ws`, to a Deno/Bun handler, or to your own accept loop.
+Returns an idempotent teardown.
+
+### `byteChannelFromWebSocket(ws): ByteChannel`
+
+Wraps a single socket as a `ByteChannel` (`send` / `recv` / `closed` / `close`).
+Use this when you want to drive `emulateMux` yourself, or reuse a socket you
+already own.
+
+### `WebSocketLike` / `WS_READY_STATE`
+
+The structural socket interface this package accepts, and the
+`CONNECTING`/`OPEN`/`CLOSING`/`CLOSED` constants. Typing against `WebSocketLike`
+rather than the DOM `WebSocket` is what lets the same code accept Node's `ws`.
+
 ## Conformance
 
-Passes every level of `@statewalker/webrun-streams-conformance` against an in-process `WebSocketServer`.
+Passes every level (L0–L6) of
+[`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance)
+against an in-process `WebSocketServer`: body sizes up to 10 MiB, concurrent
+calls, half-close, mid-stream cancellation, error propagation with stack and
+custom fields preserved, idempotent teardown, and flow control against a slow
+consumer at a small advertised window.
+
+```sh
+pnpm --filter @statewalker/webrun-streams-ws test
+```
+
+## Dependencies
+
+| Dependency | Kind | Why |
+| --- | --- | --- |
+| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `ByteChannel` seam and `emulateMux`. |
+| `ws` | dev / your choice | Only for the Node tests. Consumers pass their own constructor. |
+
+No other runtime dependencies. ESM only (`"type": "module"`).
 
 ## License
 
-MIT
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/connect.d.ts

@@ -1,4 +1,4 @@
-import { type Connect } from "@statewalker/webrun-streams";
+import { type Connect, type EmulateMuxOptions } from "@statewalker/webrun-streams";
 import { type WebSocketLike } from "./websocket-like.js";
 export interface ConnectWsParams {
     /** WebSocket URL (`ws://` or `wss://`). */
@@ -10,6 +10,14 @@ export interface ConnectWsParams {
      * (browser); pass Node's `ws` package's `WebSocket` in Node.
      */
     WebSocketCtor?: new (url: string, protocols?: string | string[]) => WebSocketLike;
+    /**
+     * Flow-control tuning forwarded to `emulateMux` — `mtu` and
+     * `maxStreamBuffer`, which is the credit this side advertises. `side` here
+     * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
+     * suite's L6 uses this to run at a window small enough that a sender
+     * genuinely stalls.
+     */
+    mux?: EmulateMuxOptions;
 }
 /**
  * Open a WebSocket to `params.url`, wrap it as a `ByteChannel`, and run it

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAc,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,KACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAC1B,aAAa,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,eAAe,CAiB5C,CAAC"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,6BAA6B,CAAC;AAE/F,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,KACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAC1B,aAAa,CAAC;IACnB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,eAAe,CAiB5C,CAAC"}

package/dist/index.js

@@ -119,7 +119,10 @@ const connect = async (params) => {
 	const ws = new Ctor(params.url, params.protocols);
 	await waitForOpen(ws);
 	const channel = byteChannelFromWebSocket(ws);
-	const mux = emulateMux(channel, { side: "initiator" });
+	const mux = emulateMux(channel, {
+		...params.mux,
+		side: "initiator"
+	});
 	return {
 		call: mux.call,
 		async close() {
@@ -166,7 +169,10 @@ function waitForOpen(ws) {
 async function serve(params, handler) {
 	const off = params.onConnection((ws) => {
 		const channel = byteChannelFromWebSocket(ws);
-		const mux = emulateMux(channel, { side: "responder" });
+		const mux = emulateMux(channel, {
+			...params.mux,
+			side: "responder"
+		});
 		mux.serve(handler);
 		channel.closed.then(() => mux.close());
 	});

package/dist/serve.d.ts

@@ -1,4 +1,4 @@
-import { type Duplex } from "@statewalker/webrun-streams";
+import { type Duplex, type EmulateMuxOptions } from "@statewalker/webrun-streams";
 import type { WebSocketLike } from "./websocket-like.js";
 export interface ServeWsParams {
     /**
@@ -7,6 +7,14 @@ export interface ServeWsParams {
      * server.
      */
     onConnection: (cb: (ws: WebSocketLike) => void) => () => void;
+    /**
+     * Flow-control tuning forwarded to `emulateMux` — `mtu` and
+     * `maxStreamBuffer`, which is the credit this side advertises. `side` here
+     * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
+     * suite's L6 uses this to run at a window small enough that a sender
+     * genuinely stalls.
+     */
+    mux?: EmulateMuxOptions;
 }
 /**
  * Register a `Duplex` handler against an inbound-WebSocket source. The

package/dist/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAc,MAAM,6BAA6B,CAAC;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAahG"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,iBAAiB,EAAc,MAAM,6BAA6B,CAAC;AAE9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC9D;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAahG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-ws",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "description": "WebSocket-backed Connect/Serve adapter in the webrun-streams-* family",
@@ -15,32 +15,41 @@
     "url": "git@github.com:statewalker/webrun-wire.git"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "source": "./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.1"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "@types/ws": "^8.5.13",
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
+    "@types/ws": "^8.18.2",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
+    "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "ws": "^8.18.0",
-    "@statewalker/webrun-streams-conformance": "0.1.1"
+    "vitest": "^5.0.3",
+    "ws": "^8.22.0",
+    "@statewalker/webrun-streams-conformance": "^0.3.1"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "test:bench": "vitest run --config vitest.bench.config.ts --reporter=verbose",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "lint": "biome check src tests"
   }
 }

package/src/connect.ts

@@ -1,4 +1,4 @@
-import { type Connect, emulateMux } from "@statewalker/webrun-streams";
+import { type Connect, type EmulateMuxOptions, emulateMux } from "@statewalker/webrun-streams";
 import { byteChannelFromWebSocket } from "./byte-channel.js";
 import { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
 
@@ -15,6 +15,14 @@ export interface ConnectWsParams {
     url: string,
     protocols?: string | string[],
   ) => WebSocketLike;
+  /**
+   * Flow-control tuning forwarded to `emulateMux` — `mtu` and
+   * `maxStreamBuffer`, which is the credit this side advertises. `side` here
+   * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
+   * suite's L6 uses this to run at a window small enough that a sender
+   * genuinely stalls.
+   */
+  mux?: EmulateMuxOptions;
 }
 
 /**
@@ -32,7 +40,7 @@ export const connect: Connect<ConnectWsParams> = async (params) => {
   const ws = new Ctor(params.url, params.protocols) as WebSocketLike;
   await waitForOpen(ws);
   const channel = byteChannelFromWebSocket(ws);
-  const mux = emulateMux(channel, { side: "initiator" });
+  const mux = emulateMux(channel, { ...params.mux, side: "initiator" });
   return {
     call: mux.call,
     async close() {

package/src/serve.ts

@@ -1,4 +1,4 @@
-import { type Duplex, emulateMux } from "@statewalker/webrun-streams";
+import { type Duplex, type EmulateMuxOptions, emulateMux } from "@statewalker/webrun-streams";
 import { byteChannelFromWebSocket } from "./byte-channel.js";
 import type { WebSocketLike } from "./websocket-like.js";
 
@@ -9,6 +9,14 @@ export interface ServeWsParams {
    * server.
    */
   onConnection: (cb: (ws: WebSocketLike) => void) => () => void;
+  /**
+   * Flow-control tuning forwarded to `emulateMux` — `mtu` and
+   * `maxStreamBuffer`, which is the credit this side advertises. `side` here
+   * wins over `mux.side`. Defaults are `emulateMux`'s own; the conformance
+   * suite's L6 uses this to run at a window small enough that a sender
+   * genuinely stalls.
+   */
+  mux?: EmulateMuxOptions;
 }
 
 /**
@@ -23,7 +31,7 @@ export interface ServeWsParams {
 export async function serve(params: ServeWsParams, handler: Duplex): Promise<() => Promise<void>> {
   const off = params.onConnection((ws) => {
     const channel = byteChannelFromWebSocket(ws);
-    const mux = emulateMux(channel, { side: "responder" });
+    const mux = emulateMux(channel, { ...params.mux, side: "responder" });
     mux.serve(handler);
     void channel.closed.then(() => mux.close());
   });