@statewalker/webrun-streams-webrtc 0.1.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-webrtc",
-  "version": "0.1.6",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "WebRTC DataChannel-backed Connect/Serve adapter (native multi-stream) in the webrun-streams-* family",
@@ -30,19 +30,21 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "^0.2.3"
+    "@statewalker/webrun-streams": "^0.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
     "@roamhq/wrtc": "^0.10.0",
     "@types/node": "^26.6.4",
-    "@vitest/browser-playwright": "^5.0.3",
+    "@vitest/browser-playwright": "^5.0.5",
     "playwright": "^1.63.0",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3",
-    "@statewalker/webrun-streams-conformance": "^0.3.3"
+    "vitest": "^5.0.5",
+    "@statewalker/webrun-msgpack": "^0.11.0",
+    "@statewalker/webrun-rpc": "^0.12.0",
+    "@statewalker/webrun-streams-conformance": "^0.5.0"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -53,6 +55,8 @@
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
     "test:browser": "vitest run --config vitest.browser.config.ts",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "lint": "biome check src tests"
   }
 }

package/src/connect-serve.ts

@@ -1,5 +1,11 @@
 import type { Connect, Duplex, Serve } from "@statewalker/webrun-streams";
-import { duplexOverDataChannel } from "./duplex-over-data-channel.js";
+import {
+  duplexOverDataChannel,
+  holdEvents,
+  markAnswering,
+  runStream,
+} from "./duplex-over-data-channel.js";
+import { PORT_LABEL_PREFIX } from "./port-mux.js";
 
 export interface WebRtcParams {
   /** Open `RTCPeerConnection`. Signalling, auth, and connection setup are the caller's responsibility. */
@@ -15,12 +21,10 @@ export const connect: Connect<WebRtcParams> = async ({ pc }) => {
   let counter = 0;
   let closed = false;
   const open = new Set<RTCDataChannel>();
-  const onConnectionClose = (): void => {
-    closed = true;
+  const onStateChange = (): void => {
+    if (pc.connectionState === "closed" || pc.connectionState === "failed") closed = true;
   };
-  pc.addEventListener("connectionstatechange", () => {
-    if (pc.connectionState === "closed" || pc.connectionState === "failed") onConnectionClose();
-  });
+  pc.addEventListener("connectionstatechange", onStateChange);
 
   const call: Duplex = (input) => {
     if (closed) {
@@ -31,6 +35,7 @@ export const connect: Connect<WebRtcParams> = async ({ pc }) => {
     }
     const label = `webrun/${Date.now().toString(36)}/${(counter++).toString(36)}`;
     const dc = pc.createDataChannel(label);
+    holdEvents(dc); // the responder may answer before our stream starts listening
     open.add(dc);
     dc.addEventListener("close", () => open.delete(dc));
     return (async function* () {
@@ -43,6 +48,7 @@ export const connect: Connect<WebRtcParams> = async ({ pc }) => {
     call,
     async close() {
       closed = true;
+      pc.removeEventListener("connectionstatechange", onStateChange);
       for (const dc of open) {
         try {
           dc.close();
@@ -62,22 +68,41 @@ 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;
+    if (dc.label.startsWith(PORT_LABEL_PREFIX)) return; // a port's channel: `webrtcPortMux`'s
+    holdEvents(dc);
+    markAnswering(dc); // the caller closes the channel once the call is over
     let inputFromPeer: PeekInput | null = null;
     void (async () => {
       await waitForOpen(dc);
-      inputFromPeer = peekInput(dc);
-      const out = handler(inputFromPeer.input);
-      for await (const chunk of duplexOverDataChannel(dc, out)) {
-        inputFromPeer.deliver(chunk);
+      const peek = peekInput(dc);
+      inputFromPeer = peek;
+      // Once the handler's output ends (or throws) the handler is done with its input: what the
+      // peer still sends is dropped, so its upload finishes instead of waiting for credit.
+      const handlerOutput = handler(peek.input);
+      const out = (async function* () {
+        try {
+          yield* handlerOutput;
+        } finally {
+          peek.release();
+        }
+      })();
+      // The next chunk is pulled (and its credit returned) only once the handler took this one.
+      // When the inbound side fails (the caller cancelled and closed the channel, or its input
+      // threw), the handler's input ends with that error before the stream waits for its outbound
+      // pump: the pump may be waiting for the handler's output, the handler for its input.
+      const inbound = runStream(dc, out, { onInboundFailed: (err) => peek.done(err) });
+      for await (const chunk of inbound) {
+        await peek.deliver(chunk);
       }
-      inputFromPeer.done();
-    })().catch(() => {
+      peek.done();
+    })().catch((err: unknown) => {
       // 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();
+      // catch it becomes an unhandled rejection that fails the page. Ending
+      // the handler's input (with the error, so a handler does not take a
+      // truncated upload for a complete one) is what runs its own `finally`.
+      inputFromPeer?.done(err instanceof Error ? err : new Error(String(err)));
     });
   };
   pc.addEventListener("datachannel", onChannel);
@@ -137,8 +162,12 @@ function toAsyncIterable(
 
 interface PeekInput {
   input: AsyncGenerator<Uint8Array>;
-  deliver(chunk: Uint8Array): void;
-  done(): void;
+  /** resolves once the handler has taken the chunk (or stopped reading) */
+  deliver(chunk: Uint8Array): Promise<void>;
+  /** ends the input after the chunks already delivered; with `err`, the handler's read throws it */
+  done(err?: Error): void;
+  /** the handler is finished: pending and later chunks are dropped */
+  release(): void;
 }
 
 /**
@@ -152,9 +181,12 @@ interface PeekInput {
  * the handler's input queue.
  */
 function peekInput(_dc: RTCDataChannel): PeekInput {
-  const slots: Array<{ type: "value"; value: Uint8Array } | { type: "done" }> = [];
+  const slots: Array<
+    { type: "value"; value: Uint8Array; taken: () => void } | { type: "done"; err?: Error }
+  > = [];
   let wake: (() => void) | null = null;
   let closed = false;
+  let ended = false;
   const input = (async function* () {
     try {
       while (true) {
@@ -167,24 +199,37 @@ function peekInput(_dc: RTCDataChannel): PeekInput {
         }
         const slot = slots.shift();
         if (!slot) continue;
-        if (slot.type === "done") return;
+        if (slot.type === "done") {
+          if (slot.err) throw slot.err;
+          return;
+        }
+        slot.taken();
         yield slot.value;
       }
     } finally {
-      closed = true;
+      release();
     }
   })();
+  function release(): void {
+    closed = true;
+    for (const s of slots.splice(0)) if (s.type === "value") s.taken();
+    wake?.();
+  }
   return {
     input,
-    deliver(chunk: Uint8Array): void {
-      if (closed) return;
-      slots.push({ type: "value", value: chunk });
-      wake?.();
+    deliver(chunk: Uint8Array): Promise<void> {
+      if (closed) return Promise.resolve();
+      return new Promise<void>((taken) => {
+        slots.push({ type: "value", value: chunk, taken });
+        wake?.();
+      });
     },
-    done(): void {
-      if (closed) return;
-      slots.push({ type: "done" });
+    done(err?: Error): void {
+      if (closed || ended) return;
+      ended = true;
+      slots.push({ type: "done", err });
       wake?.();
     },
+    release,
   };
 }

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

@@ -8,13 +8,74 @@ import {
 const TYPE_DATA = 0x00;
 const TYPE_END = 0x01;
 const TYPE_ERROR = 0x02;
+const TYPE_CREDIT = 0x03;
 
 const DC_MTU = 16 * 1024; // conservative across browsers
+
+/**
+ * Send-side backpressure: a sender waits while the DataChannel holds more than this many bytes
+ * unsent (`bufferedAmount`), until it drains to {@link LOW_WATER_MARK} (`bufferedamountlow`).
+ * Without it a fast producer fills the browser's send queue (Chrome fails `send` past 16 MiB).
+ */
+export const HIGH_WATER_MARK = 1024 * 1024;
+export const LOW_WATER_MARK = 256 * 1024;
+/**
+ * Receive-side backpressure: a sender may have at most this many payload bytes outstanding that
+ * the receiving consumer has not yet pulled. The receiver returns credit (`CREDIT` frames) as its
+ * consumer pulls, half a window at a time. A DataChannel delivers every message as it arrives,
+ * whether or not anyone reads, so without credit a slow reader's queue grows without bound. The
+ * window is larger than the send buffer's high-water mark so a long round trip does not throttle a
+ * fast link: the buffer limit is what bounds the sender's memory.
+ *
+ * The receiver enforces it: a peer that sends more than the window plus the credit returned fails
+ * the call (the queued payload is dropped, the stream throws, the channel is closed).
+ */
+export const RECEIVE_WINDOW = 4 * 1024 * 1024;
 const FRAME_OVERHEAD = 1; // 1-byte type tag
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 
+/**
+ * Messages (and a close) that arrive on a channel before its stream starts listening. A generator
+ * runs only on its first `next()`, so without this a peer that answers at once (a handler that
+ * throws, a reply with no input to wait for) can be faster than our listener: its frames are
+ * dropped and the call hangs or reports a bare close.
+ */
+const held = new WeakMap<RTCDataChannel, { events: Event[]; listener: (ev: Event) => void }>();
+
+/**
+ * Channels this side answers (from `datachannel`). A finished call is closed by its caller only,
+ * once it has the responder's `END` or `ERROR`: a responder that closed right after sending them
+ * could lose them in flight (Chrome delivers the close first), turning an error into a bare close.
+ */
+const answering = new WeakSet<RTCDataChannel>();
+export function markAnswering(dc: RTCDataChannel): void {
+  answering.add(dc);
+}
+
+/** starts holding a channel's events until {@link duplexOverDataChannel} takes them */
+export function holdEvents(dc: RTCDataChannel): void {
+  if (held.has(dc)) return;
+  dc.binaryType = "arraybuffer";
+  const events: Event[] = [];
+  const listener = (ev: Event): void => {
+    events.push(ev);
+  };
+  dc.addEventListener("message", listener);
+  dc.addEventListener("close", listener);
+  held.set(dc, { events, listener });
+}
+
+function takeHeld(dc: RTCDataChannel): Event[] {
+  const h = held.get(dc);
+  if (!h) return [];
+  held.delete(dc);
+  dc.removeEventListener("message", h.listener);
+  dc.removeEventListener("close", h.listener);
+  return h.events;
+}
+
 /**
  * Drive one `Duplex` over one `RTCDataChannel`. The DataChannel hosts a tiny
  * in-band framing protocol:
@@ -23,7 +84,9 @@ const textDecoder = new TextDecoder();
  *
  * Types are `DATA` (0x00, body bytes), `END` (0x01, signals half-close — the
  * sender is done emitting; the channel stays open for the other direction),
- * and `ERROR` (0x02, followed by a serialised `Error`).
+ * `ERROR` (0x02, followed by a serialised `Error`) and `CREDIT` (0x03, a
+ * big-endian u32: payload bytes the receiver's consumer has pulled, which the
+ * sender may now send again; see {@link RECEIVE_WINDOW}).
  *
  * `RTCDataChannel` has no native half-close, so `END` is emitted by the
  * sender once its input iterator exhausts; the channel is only physically
@@ -36,9 +99,21 @@ export function duplexOverDataChannel(
   return runStream(dc, input);
 }
 
-async function* runStream(
+export interface RunStreamHooks {
+  /**
+   * Called once when the inbound side fails (the peer's `ERROR`, the channel closing, a peer
+   * past the receive window), before the stream waits for its outbound pump to settle. A
+   * responder ends its handler's input here: the pump may be waiting for the handler's next
+   * output while the handler waits for its next input.
+   */
+  onInboundFailed?(err: Error): void;
+}
+
+/** {@link duplexOverDataChannel}, with hooks for `serve` */
+export async function* runStream(
   dc: RTCDataChannel,
   input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  hooks: RunStreamHooks = {},
 ): AsyncGenerator<Uint8Array> {
   dc.binaryType = "arraybuffer";
 
@@ -46,8 +121,56 @@ async function* runStream(
   let peerEnded = false;
   let localEnded = false;
 
+  // flow control: what the peer still lets us send, and what our consumer has pulled
+  let credit = RECEIVE_WINDOW;
+  let pulled = 0;
+  /** what the peer may still send us: the window plus the credit we returned, less what came */
+  let allowance = RECEIVE_WINDOW;
+  let overrun = false;
+  let wakeSender: (() => void) | null = null;
+  const nudge = (): void => {
+    const w = wakeSender;
+    wakeSender = null;
+    w?.();
+  };
+  const stalled = (): Promise<void> =>
+    new Promise<void>((r) => {
+      wakeSender = r;
+    });
+  dc.bufferedAmountLowThreshold = LOW_WATER_MARK;
+  const sendRaw = (bytes: Uint8Array): void => {
+    (dc as unknown as { send: (data: Uint8Array) => void }).send(bytes);
+  };
+  /** set when this call is abandoned (cancelled, or the peer failed): the sender stops waiting */
+  let aborted = false;
+  /** waits for credit for `n` bytes and room in the send buffer; false once the call is over */
+  const room = async (n: number): Promise<boolean> => {
+    while (
+      !aborted &&
+      dc.readyState === "open" &&
+      (credit < n || dc.bufferedAmount > HIGH_WATER_MARK)
+    )
+      await stalled();
+    return !aborted && dc.readyState === "open";
+  };
+  /** returns credit for what our consumer pulled, half a window at a time */
+  const consumed = (n: number): void => {
+    pulled += n;
+    if (pulled < RECEIVE_WINDOW / 2 || dc.readyState !== "open") return;
+    const frame = new Uint8Array(5);
+    frame[0] = TYPE_CREDIT;
+    new DataView(frame.buffer).setUint32(1, pulled);
+    try {
+      sendRaw(frame);
+      allowance += pulled;
+    } catch {
+      /* closing */
+    }
+    pulled = 0;
+  };
+
   const maybeClose = (): void => {
-    if (peerEnded && localEnded) {
+    if (peerEnded && localEnded && !answering.has(dc)) {
       try {
         dc.close();
       } catch {
@@ -69,11 +192,35 @@ async function* runStream(
     const type = bytes[0];
     const payload = bytes.subarray(1);
     if (type === TYPE_DATA) {
+      if (overrun) return;
+      allowance -= payload.byteLength;
+      if (allowance < 0) {
+        // the peer ignores credit: fail the call rather than queue without bound
+        overrun = true;
+        peerEnded = true;
+        incoming.fail(
+          new Error(
+            `webrun-streams-webrtc: the peer sent past the receive window (${RECEIVE_WINDOW} bytes) without credit`,
+          ),
+        );
+        // and tell the peer now, not once our consumer reaches the error
+        aborted = true;
+        nudge();
+        try {
+          dc.close();
+        } catch {
+          /* already closing */
+        }
+        return;
+      }
       incoming.push(new Uint8Array(payload));
     } else if (type === TYPE_END) {
       peerEnded = true;
       incoming.done();
       maybeClose();
+    } else if (type === TYPE_CREDIT && payload.byteLength >= 4) {
+      credit += new DataView(payload.buffer, payload.byteOffset, 4).getUint32(0);
+      nudge();
     } else if (type === TYPE_ERROR) {
       let err: Error;
       try {
@@ -88,6 +235,7 @@ async function* runStream(
   };
 
   const onClose = (): void => {
+    nudge();
     if (!peerEnded) {
       incoming.done(new TransportClosedError());
       peerEnded = true;
@@ -96,16 +244,33 @@ async function* runStream(
 
   dc.addEventListener("message", onMessage);
   dc.addEventListener("close", onClose);
+  dc.addEventListener("bufferedamountlow", nudge);
+  // what arrived before we listened, in order
+  for (const ev of takeHeld(dc)) {
+    if (ev.type === "message") onMessage(ev as MessageEvent);
+    else onClose();
+  }
+  if (dc.readyState === "closed") onClose();
+  // The listeners stay until both halves are done: after the peer's END our own sending may still
+  // wait for the peer's CREDIT frames (a reply larger than the window, sent after the input ended).
+  let inboundFinished = false;
+  const detach = (): void => {
+    if (!inboundFinished || !localEnded) return;
+    dc.removeEventListener("message", onMessage);
+    dc.removeEventListener("close", onClose);
+    dc.removeEventListener("bufferedamountlow", nudge);
+  };
 
   // Outbound pump runs in parallel with inbound iteration.
   const outbound = (async () => {
     try {
       for await (const chunk of toChunks(DC_MTU - FRAME_OVERHEAD)(input)) {
-        if (dc.readyState !== "open") return;
+        if (!(await room(chunk.byteLength))) return;
+        credit -= chunk.byteLength;
         const framed = new Uint8Array(chunk.byteLength + 1);
         framed[0] = TYPE_DATA;
         framed.set(chunk, 1);
-        (dc as unknown as { send: (data: Uint8Array) => void }).send(framed);
+        sendRaw(framed);
       }
       if (dc.readyState === "open") {
         const end = new Uint8Array([TYPE_END]);
@@ -127,20 +292,27 @@ async function* runStream(
     } finally {
       localEnded = true;
       maybeClose();
+      detach();
     }
   })();
 
   let inboundDrained = false;
+  let inboundError: Error | undefined;
   try {
     for await (const chunk of incoming.iterate()) {
       yield chunk;
+      consumed(chunk.byteLength); // pulled: the peer may send that much again
     }
     inboundDrained = true;
+  } catch (err) {
+    inboundError = err instanceof Error ? err : new Error(String(err));
+    throw err;
   } finally {
-    dc.removeEventListener("message", onMessage);
-    dc.removeEventListener("close", onClose);
-    // Wait for outbound to settle so an early exit doesn't truncate in-flight
-    // sends — but ONLY on an early exit.
+    inboundFinished = true;
+    detach();
+    // On an early exit, stop the outbound pump (it may be waiting for credit
+    // the peer will never send now), close the channel, then let the pump
+    // settle — 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
@@ -154,7 +326,8 @@ async function* runStream(
     // 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(() => {});
+      aborted = true;
+      nudge();
       // 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 —
@@ -164,11 +337,17 @@ async function* runStream(
       // `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.
+      // The close comes before waiting on the pump: a pump stalled on credit
+      // would otherwise hold the cancellation back.
       try {
         dc.close();
       } catch {
         /* already closing */
       }
+      // A responder's pump may be waiting for the handler's next output while the handler waits
+      // for its next input: end that input (with the error) before waiting on the pump.
+      if (inboundError) hooks.onInboundFailed?.(inboundError);
+      await outbound.catch(() => {});
     }
   }
 }
@@ -176,6 +355,8 @@ async function* runStream(
 interface InboundQueue {
   push(chunk: Uint8Array): void;
   done(err?: Error): void;
+  /** drops what is queued and ends with `err` */
+  fail(err: Error): void;
   iterate(): AsyncGenerator<Uint8Array>;
 }
 
@@ -196,6 +377,12 @@ function makeInboundQueue(): InboundQueue {
       slots.push({ type: "done", err });
       wake?.();
     },
+    fail(err: Error): void {
+      if (closed) return;
+      slots.length = 0;
+      slots.push({ type: "done", err });
+      wake?.();
+    },
     iterate(): AsyncGenerator<Uint8Array> {
       return (async function* () {
         try {

package/src/index.ts

@@ -1,2 +1,13 @@
 export { connect, serve, type WebRtcParams } from "./connect-serve.js";
 export { duplexOverDataChannel } from "./duplex-over-data-channel.js";
+export {
+  type DataChannelPort,
+  DEFAULT_PORT_MAX_FRAME_BYTES,
+  DEFAULT_PORT_MAX_MESSAGE_SIZE,
+  PORT_DRAIN_LOW_WATER,
+  PORT_LABEL_PREFIX,
+  type ValueCodec,
+  type WebRtcPortMux,
+  type WebRtcPortMuxOptions,
+  webrtcPortMux,
+} from "./port-mux.js";