@statewalker/webrun-streams-livekit 0.1.1 → 0.2.2

package/README.md

@@ -1,16 +1,149 @@
 # @statewalker/webrun-streams-livekit
 
-LiveKit-backed `Connect` / `Serve` adapter. Wraps a connected `Room` plus a participant identity into a byte channel; `emulateMux` provides multi-stream. `RELIABLE` publish mode is forced (ordered, retransmitted).
+LiveKit-backed `Connect` / `Serve` adapter in the `webrun-streams-*` family.
+
+## What this is
+
+A binding between a connected LiveKit [`Room`](https://docs.livekit.io/client-sdk-js/classes/Room.html)
+and the [`webrun-streams`](../webrun-streams) `Duplex` seam. A room plus a
+remote participant identity becomes one `ByteChannel`; `emulateMux` layers many
+concurrent logical calls on top.
+
+Your handler is an ordinary `Duplex` —
+`(input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>` — the same
+function you would run over a WebSocket or WebRTC.
+
+## Why it exists
+
+Peer-to-peer links are excellent until they aren't: symmetric NATs, corporate
+firewalls, mobile networks and multi-party sessions all argue for a managed
+SFU. LiveKit provides one, with authentication, room membership and presence
+already solved.
+
+What LiveKit's data channel does *not* provide is request semantics. This
+adapter adds them, so an application written against the `Duplex` seam can move
+from a direct WebRTC link to a LiveKit room by changing one import — the
+handlers, the HTTP layer above them, and the tests all stay put.
+
+Publishes are forced to LiveKit's **`RELIABLE`** mode (ordered, retransmitted),
+because the framing above assumes byte-stream ordering.
+
+## Install
+
+```sh
+npm install @statewalker/webrun-streams-livekit livekit-client
+```
+
+`livekit-client` is a **peer dependency** (`^2.18.3`) — you own the `Room`, its
+token, and its lifecycle.
+
+## Getting started
+
+Both sides take the same parameters: a connected `Room` and the identity of the
+participant at the other end.
+
+Responder:
+
+```ts
+import { Room } from "livekit-client";
+import { serve } from "@statewalker/webrun-streams-livekit";
+
+const room = new Room();
+await room.connect(url, token); // identity: "agent-7"
+
+const stop = await serve({ room, peerIdentity: "client-3" }, async function* echo(input) {
+  for await (const chunk of input) yield chunk;
+});
+```
+
+Caller:
+
+```ts
+import { connect } from "@statewalker/webrun-streams-livekit";
+
+const { call, close } = await connect({ room, peerIdentity: "agent-7" });
+
+for await (const chunk of call([new TextEncoder().encode("ping")])) {
+  console.log(new TextDecoder().decode(chunk)); // "ping"
+}
+
+await close();
+```
+
+### Carrying HTTP over it
 
 ```ts
-import { connect, serve } from "@statewalker/webrun-streams-livekit";
+import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
+
+const response = await fetchOverDuplex(call, new Request("http://peer/api/events"));
+```
+
+[`apps/livekit-demo`](../../apps/livekit-demo) runs this end to end — a dev
+LiveKit server, a token service, and two browser pages exchanging HTTP and SSE
+through a room.
+
+## API
+
+### `connect(params): Promise<{ call, close }>`
+
+Type: `Connect<LiveKitParams>`. Each `call(input)` opens a new logical stream
+addressed to `peerIdentity`; `close()` tears them down. It does not disconnect
+the `Room`, which you own.
+
+### `serve(params, handler): Promise<() => Promise<void>>`
+
+Type: `Serve<LiveKitParams>`. Runs `handler` for inbound streams from
+`peerIdentity`. Returns an idempotent teardown.
+
+### `LiveKitParams`
 
-const { call } = await connect({ room, peerIdentity: "agent-7" });
-const stop = await serve({ room, peerIdentity: "client-3" }, handler);
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `room` | `Room` | An already-connected LiveKit room. |
+| `peerIdentity` | `string` | Identity of the remote participant this side talks to. |
+| `mux` | `EmulateMuxOptions` | Flow-control tuning (`mtu`, `maxStreamBuffer`) forwarded to `emulateMux`. `side` is set by which function you call (`"initiator"` for `connect`, `"responder"` for `serve`) regardless of `mux.side`. **`mtu` defaults to 12 KiB here**, not `emulateMux`'s 64 KiB — see below. |
+
+### `byteChannelFromLiveKit(room, peerIdentity): ByteChannel`
+
+Wraps a room + peer identity as a `ByteChannel` (`send` / `recv` / `closed` /
+`close`) for driving `emulateMux` yourself.
+
+
+### Why the MTU default is lower here
+
+A LiveKit reliable data packet is capped at roughly 15 KiB, and a payload over
+that is dropped rather than fragmented. `emulateMux`'s own 64 KiB default
+therefore does not survive this transport, and it fails silently: a 1 MiB body
+arrives as zero bytes and a 10 MiB body never completes, with no error on
+either side. So `connect` and `serve` default `mtu` to 12 KiB — under the cap
+with room for the frame header (`[varint streamId][1-byte type]`).
+
+An explicit `mux.mtu` still wins, so a deployment that permits larger packets
+can raise it.
+
+## Conformance
+
+Conformance is **browser-gated** — it needs a real LiveKit server rather than a
+Node shim:
+
+```sh
+pnpm --filter @statewalker/webrun-streams-livekit test:browser
 ```
 
-Conformance is browser-gated; run with `pnpm test:browser` plus `WEBRUN_STREAMS_LIVEKIT_*` env vars set against a running LiveKit server.
+with the `WEBRUN_STREAMS_LIVEKIT_*` environment variables pointing at a running
+server. The package's dev dependencies include `testcontainers` and
+`livekit-server-sdk` for standing one up.
+
+## Dependencies
+
+| Dependency | Kind | Why |
+| --- | --- | --- |
+| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `ByteChannel` seam and `emulateMux`. |
+| `livekit-client` | **peer** (`^2.18.3`) | You supply and own the `Room`. |
+| `livekit-server-sdk`, `testcontainers` | dev | Token minting and a containerised server for conformance. |
+
+ESM only (`"type": "module"`).
 
 ## License
 
-MIT
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/connect-serve.d.ts

@@ -1,10 +1,18 @@
-import { type Connect, type Serve } from "@statewalker/webrun-streams";
+import { type Connect, type EmulateMuxOptions, type Serve } from "@statewalker/webrun-streams";
 import type { Room } from "livekit-client";
 export interface LiveKitParams {
     /** Already-connected LiveKit `Room`. */
     room: Room;
     /** Identity of the remote participant the call addresses. */
     peerIdentity: string;
+    /**
+     * 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;
 }
 export declare const connect: Connect<LiveKitParams>;
 export declare const serve: Serve<LiveKitParams>;

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,EAAE,KAAK,OAAO,EAA2B,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAChG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAG3C,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,IAAI,CAAC;IACX,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,aAAa,CAS1C,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,aAAa,CAYtC,CAAC"}
+{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,iBAAiB,EAEtB,KAAK,KAAK,EACX,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAkB3C,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,IAAI,EAAE,IAAI,CAAC;IACX,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,aAAa,CAa1C,CAAC;AAEF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,aAAa,CAmBtC,CAAC"}

package/dist/index.js

@@ -87,9 +87,27 @@ function byteChannelFromLiveKit(room, peerIdentity) {
 }
 //#endregion
 //#region src/connect-serve.ts
-const connect = async ({ room, peerIdentity }) => {
+/**
+* Default `mtu` for this transport.
+*
+* `emulateMux` defaults to 64 KiB, which LiveKit cannot carry: a reliable data
+* packet is capped around 15 KiB, and anything larger is dropped rather than
+* fragmented. The symptom is not an error — a 1 MiB body simply arrives as
+* zero bytes and a 10 MiB body hangs — so the ceiling has to be applied here,
+* where the transport is known, rather than left to every caller.
+*
+* 12 KiB leaves room for the mux frame header (`[varint streamId][1-byte
+* type]`) inside that budget. An explicit `mux.mtu` still wins, so a caller who
+* knows their deployment allows more can raise it.
+*/
+const LIVEKIT_SAFE_MTU = 12288;
+const connect = async ({ room, peerIdentity, mux: muxOpts }) => {
 	const channel = byteChannelFromLiveKit(room, peerIdentity);
-	const mux = emulateMux(channel, { side: "initiator" });
+	const mux = emulateMux(channel, {
+		mtu: LIVEKIT_SAFE_MTU,
+		...muxOpts,
+		side: "initiator"
+	});
 	return {
 		call: mux.call,
 		async close() {
@@ -97,9 +115,13 @@ const connect = async ({ room, peerIdentity }) => {
 		}
 	};
 };
-const serve = async ({ room, peerIdentity }, handler) => {
+const serve = async ({ room, peerIdentity, mux: muxOpts }, handler) => {
 	const channel = byteChannelFromLiveKit(room, peerIdentity);
-	const mux = emulateMux(channel, { side: "responder" });
+	const mux = emulateMux(channel, {
+		mtu: LIVEKIT_SAFE_MTU,
+		...muxOpts,
+		side: "responder"
+	});
 	const off = mux.serve(handler);
 	channel.closed.then(() => mux.close());
 	let torn = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-livekit",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "description": "LiveKit-backed Connect/Serve adapter in the webrun-streams-* family",
@@ -15,33 +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"
   },
   "peerDependencies": {
     "livekit-client": "^2.18.3"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "livekit-client": "^2.18.3",
-    "livekit-server-sdk": "^2.10.0",
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
+    "@vitest/browser-playwright": "^5.0.3",
+    "livekit-client": "^2.22.3",
+    "livekit-server-sdk": "^2.19.1",
+    "playwright": "^1.63.0",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
-    "testcontainers": "^11.0.0",
+    "rolldown": "^1.2.12",
+    "testcontainers": "^12.2.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "@statewalker/webrun-streams-conformance": "0.1.1"
+    "vitest": "^5.0.3",
+    "@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",

package/src/connect-serve.ts

@@ -1,17 +1,50 @@
-import { type Connect, type Duplex, emulateMux, type Serve } from "@statewalker/webrun-streams";
+import {
+  type Connect,
+  type Duplex,
+  type EmulateMuxOptions,
+  emulateMux,
+  type Serve,
+} from "@statewalker/webrun-streams";
 import type { Room } from "livekit-client";
 import { byteChannelFromLiveKit } from "./byte-channel.js";
 
+/**
+ * Default `mtu` for this transport.
+ *
+ * `emulateMux` defaults to 64 KiB, which LiveKit cannot carry: a reliable data
+ * packet is capped around 15 KiB, and anything larger is dropped rather than
+ * fragmented. The symptom is not an error — a 1 MiB body simply arrives as
+ * zero bytes and a 10 MiB body hangs — so the ceiling has to be applied here,
+ * where the transport is known, rather than left to every caller.
+ *
+ * 12 KiB leaves room for the mux frame header (`[varint streamId][1-byte
+ * type]`) inside that budget. An explicit `mux.mtu` still wins, so a caller who
+ * knows their deployment allows more can raise it.
+ */
+const LIVEKIT_SAFE_MTU = 12 * 1024;
+
 export interface LiveKitParams {
   /** Already-connected LiveKit `Room`. */
   room: Room;
   /** Identity of the remote participant the call addresses. */
   peerIdentity: string;
+  /**
+   * 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;
 }
 
-export const connect: Connect<LiveKitParams> = async ({ room, peerIdentity }) => {
+export const connect: Connect<LiveKitParams> = async ({ room, peerIdentity, mux: muxOpts }) => {
   const channel = byteChannelFromLiveKit(room, peerIdentity);
-  const mux = emulateMux(channel, { side: "initiator" });
+  const mux = emulateMux(channel, {
+    mtu: LIVEKIT_SAFE_MTU,
+    ...muxOpts,
+    side: "initiator",
+  });
   return {
     call: mux.call,
     async close() {
@@ -20,9 +53,16 @@ export const connect: Connect<LiveKitParams> = async ({ room, peerIdentity }) =>
   };
 };
 
-export const serve: Serve<LiveKitParams> = async ({ room, peerIdentity }, handler: Duplex) => {
+export const serve: Serve<LiveKitParams> = async (
+  { room, peerIdentity, mux: muxOpts },
+  handler: Duplex,
+) => {
   const channel = byteChannelFromLiveKit(room, peerIdentity);
-  const mux = emulateMux(channel, { side: "responder" });
+  const mux = emulateMux(channel, {
+    mtu: LIVEKIT_SAFE_MTU,
+    ...muxOpts,
+    side: "responder",
+  });
   const off = mux.serve(handler);
   void channel.closed.then(() => mux.close());
   let torn = false;