@statewalker/webrun-rpc 0.4.0

package/src/message-target.ts

@@ -0,0 +1,18 @@
+export type MessageListener = (event: MessageEvent) => void | Promise<void>;
+
+/** An object we can listen for `"message"` events on. */
+export interface MessageSource {
+  addEventListener(type: "message", listener: MessageListener): void;
+  removeEventListener(type: "message", listener: MessageListener): void;
+  start?(): void | Promise<void>;
+}
+
+/** An object we can post messages to (with optional transferable list). */
+export interface MessageSink {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+
+/** Full-duplex message target: both sends and receives. */
+export interface MessageTarget extends MessageSource, MessageSink {
+  close?(): void | Promise<void>;
+}

package/src/multiplex-port.ts

@@ -0,0 +1,134 @@
+import type { MessageTarget } from "./message-target.js";
+import type { PortEnvelope, PortMux, PortMuxOptions } from "./port-types.js";
+import { newVirtualPort, type VirtualPortHandle } from "./virtual-port.js";
+
+/** Ceiling on concurrently open virtual ports. Bounds the id table only. */
+export const DEFAULT_MAX_PORTS = 1024;
+
+/**
+ * The default `PortMux`: emulates multiplexing over a single port.
+ *
+ * A transport that already multiplexes natively supplies its own `PortMux`
+ * instead — this implementation is for transports that offer one pipe.
+ */
+export function multiplexPort(port: MessageTarget, options: PortMuxOptions): PortMux {
+  const {
+    codec,
+    onPort,
+    side = "initiator",
+    maxPorts = DEFAULT_MAX_PORTS,
+    maxMessageSize,
+  } = options;
+
+  const open = new Map<number, VirtualPortHandle>();
+  let nextId = side === "initiator" ? 0 : 1;
+  let muxClosed = false;
+
+  const post = (envelope: PortEnvelope, transfer?: Transferable[]): void => {
+    if (muxClosed) return;
+    try {
+      codec.post(port, envelope, transfer);
+    } catch {
+      // The underlying port is gone. There is nothing useful to do here and
+      // no flow control to unwind — layer 1 holds no state on its behalf.
+    }
+  };
+
+  const attach = (id: number): VirtualPortHandle => {
+    let self!: VirtualPortHandle;
+    self = newVirtualPort(
+      (payload, transfer) => post({ type: "message", id, payload }, transfer),
+      (reason) => {
+        post({ type: "close", id, reason });
+        open.delete(id);
+        self.markClosed();
+      },
+    );
+    open.set(id, self);
+    return self;
+  };
+
+  const handleEnvelope = (envelope: PortEnvelope): void => {
+    if (muxClosed) return;
+
+    if (envelope.type === "open") {
+      // A duplicate id is a peer bug; ignoring it is safer than replacing a
+      // live port out from under its consumer.
+      if (open.has(envelope.id)) return;
+      if (open.size >= maxPorts) {
+        post({ type: "close", id: envelope.id, reason: "max-ports" });
+        return;
+      }
+      const handle = attach(envelope.id);
+      let accepted = false;
+      if (onPort) {
+        try {
+          accepted = onPort(handle.port, envelope.meta) !== false;
+        } catch {
+          accepted = false;
+        }
+      }
+      if (!accepted) {
+        open.delete(envelope.id);
+        handle.markClosed();
+        post({ type: "close", id: envelope.id, reason: "rejected" });
+      }
+      return;
+    }
+
+    const handle = open.get(envelope.id);
+
+    if (envelope.type === "message") {
+      // Drop, never queue. An id that was rejected, never opened, or already
+      // closed has no consumer, and holding its traffic would be exactly the
+      // buffering layer 1 refuses to do.
+      if (!handle) return;
+      handle.deliver(envelope.payload);
+      return;
+    }
+
+    if (!handle) return;
+    open.delete(envelope.id);
+    handle.markClosed();
+  };
+
+  const listener = (event: MessageEvent): void => {
+    const envelope = codec.read(event);
+    if (envelope) handleEnvelope(envelope);
+  };
+
+  port.addEventListener("message", listener);
+  void port.start?.();
+
+  return {
+    maxMessageSize,
+
+    async openPort(meta?: unknown): Promise<MessageTarget> {
+      if (muxClosed) throw new Error("webrun-rpc: the multiplexer is closed");
+      if (open.size >= maxPorts) {
+        throw new RangeError(`webrun-rpc: maxPorts (${maxPorts}) reached`);
+      }
+      // A hostile or misconfigured peer may have opened using our own
+      // parity. Skipping a claimed id costs one line and keeps a local open
+      // from silently taking over a handle the peer is already using.
+      while (open.has(nextId)) nextId += 2;
+      const id = nextId;
+      nextId += 2;
+      const handle = attach(id);
+      post({ type: "open", id, meta });
+      return handle.port;
+    },
+
+    async close(): Promise<void> {
+      if (muxClosed) return;
+      for (const [id, handle] of [...open]) {
+        post({ type: "close", id });
+        open.delete(id);
+        handle.markClosed();
+      }
+      muxClosed = true;
+      port.removeEventListener("message", listener);
+      await port.close?.();
+    },
+  };
+}

package/src/port-types.ts

@@ -0,0 +1,80 @@
+import type { MessageTarget } from "./message-target.js";
+
+/**
+ * What a multiplexer exchanges over the underlying port.
+ *
+ * Three types and nothing more. There is no DATA/ACK split, no credit and no
+ * error type: `close` carries an opaque `reason` that layer 1 never inspects,
+ * because stream semantics belong above this layer.
+ */
+export type PortEnvelope =
+  | { type: "open"; id: number; meta?: unknown }
+  | { type: "message"; id: number; payload: unknown }
+  | { type: "close"; id: number; reason?: unknown };
+
+/**
+ * How an envelope reaches the wire.
+ *
+ * This is the only place that knows the wire format. A port whose messages are
+ * structured values passes envelopes through untouched; a port whose messages
+ * are bytes encodes them. A transport with different constraints adds a codec,
+ * not a multiplexer.
+ */
+export interface PortCodec {
+  /** Place one envelope on the underlying port. */
+  post(port: MessageTarget, envelope: PortEnvelope, transfer?: Transferable[]): void;
+  /** Recover an envelope from a message event, or `undefined` to ignore it. */
+  read(event: MessageEvent): PortEnvelope | undefined;
+}
+
+export interface PortMuxOptions {
+  /** How envelopes are placed on the underlying port. */
+  codec: PortCodec;
+  /**
+   * Called when the peer opens a port. Return `false` to reject it: a `close`
+   * goes back and every later message for that id is dropped. Any other return
+   * value — including `undefined` — accepts.
+   *
+   * With no `onPort` at all, inbound ports are rejected. A port nobody holds
+   * has no consumer, and accepting one would mean dropping its traffic
+   * silently rather than telling the peer.
+   */
+  onPort?: (port: MessageTarget, meta?: unknown) => boolean | undefined;
+  /**
+   * Id parity. The initiator allocates even ids, the responder odd, so both
+   * ends may open concurrently with no negotiation. Defaults to `"initiator"`.
+   */
+  side?: "initiator" | "responder";
+  /**
+   * Ceiling on concurrently open virtual ports. Bounds the id table only — it
+   * never inspects, counts or delays a payload.
+   */
+  maxPorts?: number;
+  /**
+   * Largest **payload** a port on this mux can carry, if the transport imposes
+   * a limit. Layer 1 does not enforce it; it reports it so layer 2 can chunk.
+   *
+   * It bounds the payload, **not the frame**. `duplexOverPort` applies
+   * `toChunks(maxMessageSize)` and the envelope framing — the chunk wrapper,
+   * `callPort`'s request, this mux's own envelope, then the codec — is added on
+   * top afterwards. Measured over `msgpackCodec` that framing is 123-128 bytes
+   * (modelled ceiling 134), and it is not constant: the call id's length varies
+   * per chunk, the port id's integer width adds up to 4, and the payload's
+   * length header widens at 64 KiB.
+   *
+   * So set this **at least 256 bytes below** the transport's real limit. Set to
+   * the limit exactly, a full-size chunk overruns it — which on LiveKit
+   * delivered a body as zero bytes with no error on either side.
+   */
+  maxMessageSize?: number;
+}
+
+/** One port in, many ports out. */
+export interface PortMux {
+  /** Allocate a port, announce it, and return the local end. */
+  openPort(meta?: unknown): Promise<MessageTarget>;
+  /** Close every virtual port, then release the underlying port. */
+  close(): Promise<void>;
+  /** See {@link PortMuxOptions.maxMessageSize}. */
+  readonly maxMessageSize?: number;
+}

package/src/recieve.ts

@@ -0,0 +1,89 @@
+import { type IteratorChunk, recieveIterator } from "@statewalker/webrun-streams";
+import { type ListenPortOptions, listenPort } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+
+export interface RecieveOptions extends ListenPortOptions {
+  /**
+   * Optional cancel signal. When fired, the currently-active
+   * `recieveIterator` is force-closed (its producer is signalled `done`
+   * with an `AbortError`) so any pending `.next()` resolves immediately
+   * and the consumer's iteration loop can unwind. Required to make
+   * consumer-side `iter.return()` propagate through `callBidi`/`yield*`
+   * without waiting on `callPort` timeouts.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Async generator over async generators. Each outer yield is one inbound
+ * stream reconstructed from chunk-envelopes delivered by the peer's
+ * {@link send}.
+ *
+ * The outer generator itself never ends: break out of the outer loop when
+ * you've handled the streams you care about.
+ *
+ * When the outer for-await is interrupted (`break`, `return`, throw), the
+ * `finally` here both removes the underlying `listenPort` and closes the
+ * most recently yielded `recieveIterator`. The latter is required because
+ * a `listenPort` handler invocation that's already in flight (awaiting
+ * `deliver(chunk)`) would otherwise hang forever — `iterator.return()`
+ * triggers `drainQueue` which resolves all pending producer Promises.
+ *
+ * If `options.signal` is provided and fires while the consumer is awaiting
+ * a chunk, the active `recieveIterator` is force-delivered an end-of-stream
+ * marker so the consumer wakes up immediately rather than waiting for the
+ * next inbound chunk (or `callPort` timeout).
+ */
+export async function* recieve<T>(
+  port: MessageTarget,
+  options: RecieveOptions = {},
+): AsyncGenerator<AsyncGenerator<T>> {
+  const { signal, ...listenOptions } = options;
+  let onMessage: ((chunk: IteratorChunk<T>) => Promise<boolean>) | undefined;
+  let currentIter: AsyncGenerator<T> | undefined;
+  let forceClose: (() => void) | undefined;
+
+  const close = listenPort<IteratorChunk<T>, void>(
+    port,
+    async ({ done, value, error }) => {
+      await onMessage?.({ done, value, error });
+    },
+    listenOptions,
+  );
+
+  const onAbort = () => {
+    forceClose?.();
+  };
+  if (signal) {
+    if (signal.aborted) {
+      // Bail out immediately — close listener and yield nothing.
+      close();
+      return;
+    }
+    signal.addEventListener("abort", onAbort);
+  }
+
+  try {
+    while (true) {
+      currentIter = recieveIterator<T>((deliver) => {
+        onMessage = deliver;
+        forceClose = () => {
+          void deliver({ done: true });
+        };
+      });
+      yield currentIter;
+    }
+  } finally {
+    close();
+    signal?.removeEventListener("abort", onAbort);
+    onMessage = undefined;
+    forceClose = undefined;
+    if (currentIter) {
+      try {
+        await currentIter.return?.(undefined as never);
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}

package/src/send.ts

@@ -0,0 +1,60 @@
+import { sendIterator } from "@statewalker/webrun-streams";
+import { type CallPortOptions, callPort } from "./call-port.js";
+import type { MessageTarget } from "./message-target.js";
+import { throughAbort } from "./through-abort.js";
+
+export interface SendOptions extends CallPortOptions {
+  /**
+   * Optional cancellation signal. When fired, `send` aborts cleanly:
+   *   - the current iteration is interrupted (by calling `return()` on the
+   *     underlying iterator, releasing any pending work in the producer);
+   *   - no further `callPort` round-trips are issued;
+   *   - the final `{done: true}` marker is **not** sent (the peer told us
+   *     it's gone — there's no one to receive it).
+   *
+   * `send` resolves normally on abort; the caller can distinguish abort
+   * from normal completion by checking `options.signal.aborted` after.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Send every value produced by `output` to `port`, one `callPort` round-trip
+ * per chunk. Resolves once the peer has acknowledged the final `{ done: true }`
+ * envelope, or once `options.signal` aborts (whichever comes first).
+ */
+export async function send<T>(
+  port: MessageTarget,
+  output: AsyncIterable<T> | Iterable<T>,
+  options: SendOptions = {},
+): Promise<void> {
+  const { signal, ...callOptions } = options;
+  if (!signal) {
+    await sendIterator<T>(async ({ done, value, error }) => {
+      await callPort(port, { done, value, error }, callOptions);
+    }, output);
+    return;
+  }
+
+  const stream = throughAbort(output, signal);
+  let abortedBeforeDone = false;
+  try {
+    await sendIterator<T>(async ({ done, value, error }) => {
+      if (signal.aborted) {
+        // Skip everything — including the final {done:true}. The peer
+        // initiated the cancel and isn't listening anymore.
+        abortedBeforeDone = true;
+        return;
+      }
+      // Pass the signal so an in-flight callPort short-circuits when abort
+      // fires — otherwise it would hang on the per-chunk timeout.
+      await callPort(port, { done, value, error }, { ...callOptions, signal });
+    }, stream);
+  } catch (err) {
+    // If we aborted, the chunkSender may have surfaced a callPort error from
+    // the very last in-flight round-trip. Swallow it — abort is the expected
+    // outcome here.
+    if (signal.aborted || abortedBeforeDone) return;
+    throw err;
+  }
+}

package/src/structured-codec.ts

@@ -0,0 +1,30 @@
+import type { PortCodec, PortEnvelope } from "./port-types.js";
+
+function isEnvelope(value: unknown): value is PortEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { type?: unknown; id?: unknown };
+  if (typeof candidate.id !== "number") return false;
+  if (!Number.isInteger(candidate.id) || candidate.id < 0) return false;
+  return candidate.type === "open" || candidate.type === "message" || candidate.type === "close";
+}
+
+/**
+ * For ports whose messages are structured values — a real `MessagePort`, a
+ * worker, an iframe.
+ *
+ * Envelopes are posted as-is, so nothing is encoded, `ArrayBuffer`s move
+ * zero-copy through the transfer list, and structured clone does the work the
+ * platform already does well. This is a performance choice only: layer 2 may
+ * not send anything a byte codec could not also carry.
+ */
+export const structuredCodec: PortCodec = {
+  post(port, envelope, transfer) {
+    // An empty transfer list is not the same as no transfer list — some
+    // implementations reject the former.
+    if (transfer && transfer.length > 0) port.postMessage(envelope, transfer);
+    else port.postMessage(envelope);
+  },
+  read(event) {
+    return isEnvelope(event.data) ? event.data : undefined;
+  },
+};

package/src/through-abort.ts

@@ -0,0 +1,32 @@
+/**
+ * Wraps an async iterable so that an `AbortSignal` firing causes the wrapper
+ * to return cleanly, forwarding `return()` to the underlying iterator so the
+ * producer (e.g., a user-supplied generator) sees its own `finally` blocks
+ * run immediately rather than waiting for the next yield.
+ */
+export async function* throughAbort<T>(
+  input: AsyncIterable<T> | Iterable<T>,
+  signal: AbortSignal,
+): AsyncGenerator<T> {
+  const iter = (input as AsyncIterable<T>)[Symbol.asyncIterator]
+    ? (input as AsyncIterable<T>)[Symbol.asyncIterator]()
+    : ((input as Iterable<T>)[Symbol.iterator]() as unknown as AsyncIterator<T>);
+  const onAbort = () => {
+    void iter.return?.(undefined as never);
+  };
+  if (signal.aborted) {
+    void iter.return?.(undefined as never);
+    return;
+  }
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    while (true) {
+      const r = await iter.next();
+      if (r.done) return;
+      if (signal.aborted) return;
+      yield r.value;
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}

package/src/transfer-port-mux.ts

@@ -0,0 +1,106 @@
+import type { MessageTarget } from "./message-target.js";
+import type { PortMux } from "./port-types.js";
+
+/** The `type` of the envelope that carries a transferred port to the peer. */
+export const PORT_TRANSFER = "webrun-rpc:port-transfer";
+
+export interface TransferPortMuxOptions {
+  /**
+   * Called when the peer transfers a port in. Return `false` to reject it: the
+   * port is closed and nothing further arrives on it. Any other return value —
+   * including `undefined` — accepts.
+   *
+   * With no `onPort` at all, inbound ports are rejected, matching
+   * `multiplexPort`: a port nobody holds has no consumer.
+   */
+  onPort?: (port: MessageTarget, meta?: unknown) => boolean | undefined;
+  /** Reported to layer 2, never enforced. A `MessagePort` normally has none. */
+  maxMessageSize?: number;
+}
+
+/**
+ * A `PortMux` whose ports are real, transferred `MessagePort`s (spec D23).
+ *
+ * `openPort` creates a `MessageChannel`, transfers one end to the peer over
+ * `target`, and returns the other. There is no id table, no `maxPorts` and no
+ * envelope overhead per message, because the platform does the multiplexing.
+ *
+ * **It needs structured clone with transferables**, so it exists in browsers,
+ * workers and iframes and nowhere else that lacks them. A caller selects it
+ * explicitly rather than by capability sniffing (spec D21): use
+ * `multiplexPort` where the transport is one pipe of bytes.
+ *
+ * What it buys over emulation: a transferred port can cross an origin or a
+ * worker boundary and be handed to code that never saw `target`, where an
+ * emulated port id is meaningless outside its own mux.
+ *
+ * `target` must be a full `MessageTarget`. Reaching a send-only `MessageSink`
+ * — a `ServiceWorkerClient`, say — is a real use of port transfer but needs a
+ * different entry point, and is not part of this interface.
+ */
+export function transferPortMux(
+  target: MessageTarget,
+  options: TransferPortMuxOptions = {},
+): PortMux {
+  const { onPort, maxMessageSize } = options;
+  const issued = new Set<MessagePort>();
+  let closed = false;
+
+  const listener = (event: MessageEvent): void => {
+    if (closed) return;
+    const data = event.data as { type?: unknown; meta?: unknown } | undefined;
+    if (!data || typeof data !== "object" || data.type !== PORT_TRANSFER) return;
+    const port = event.ports?.[0];
+    // The right `type` with no port attached is a malformed message, not a
+    // transfer. Dropping it keeps a shared parent port uncorrupted.
+    if (!port) return;
+    port.start();
+    let accepted = false;
+    if (onPort) {
+      try {
+        accepted = onPort(port, data.meta) !== false;
+      } catch {
+        accepted = false;
+      }
+    }
+    if (!accepted) {
+      port.close();
+      return;
+    }
+    issued.add(port);
+  };
+
+  target.addEventListener("message", listener);
+  void target.start?.();
+
+  return {
+    maxMessageSize,
+
+    async openPort(meta?: unknown): Promise<MessageTarget> {
+      if (closed) throw new Error("webrun-rpc: the multiplexer is closed");
+      const channel = new MessageChannel();
+      channel.port1.start();
+      // The transferred end is not referenced from the message itself, so it
+      // arrives in `event.ports` on the peer — the platform's own hand-off,
+      // identical in Node and in browsers.
+      target.postMessage({ type: PORT_TRANSFER, meta }, [channel.port2]);
+      issued.add(channel.port1);
+      return channel.port1;
+    },
+
+    async close(): Promise<void> {
+      if (closed) return;
+      closed = true;
+      target.removeEventListener("message", listener);
+      for (const port of issued) {
+        try {
+          port.close();
+        } catch {
+          /* already gone */
+        }
+      }
+      issued.clear();
+      await target.close?.();
+    },
+  };
+}

package/src/virtual-port.ts

@@ -0,0 +1,71 @@
+import type { MessageListener, MessageTarget } from "./message-target.js";
+
+export interface VirtualPortHandle {
+  /** The consumer-facing end. Indistinguishable from a real `MessagePort`. */
+  port: MessageTarget;
+  /** Multiplexer-only: hand an inbound payload to the consumer's listeners. */
+  deliver(payload: unknown): void;
+  /** Multiplexer-only: the port is finished; drop listeners and go inert. */
+  markClosed(): void;
+  isClosed(): boolean;
+}
+
+/**
+ * One virtual port.
+ *
+ * `deliver` and `markClosed` are deliberately not on `port`: the consumer holds
+ * only a `MessageTarget`, so it cannot forge inbound traffic or close the port
+ * out from under the multiplexer's bookkeeping.
+ */
+export function newVirtualPort(
+  send: (payload: unknown, transfer?: Transferable[]) => void,
+  requestClose: (reason?: unknown) => void,
+): VirtualPortHandle {
+  const listeners = new Set<MessageListener>();
+  let closed = false;
+
+  const port: MessageTarget = {
+    addEventListener(_type, listener) {
+      listeners.add(listener);
+    },
+    removeEventListener(_type, listener) {
+      listeners.delete(listener);
+    },
+    postMessage(message, transfer) {
+      if (closed) return;
+      send(message, transfer);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      const notify = requestClose;
+      listeners.clear();
+      notify();
+    },
+  };
+
+  return {
+    port,
+    deliver(payload) {
+      if (closed) return;
+      const event = new MessageEvent("message", { data: payload });
+      // Copy first: a listener may add or remove listeners while running.
+      for (const listener of [...listeners]) {
+        try {
+          void listener(event);
+        } catch {
+          // One consumer's fault is not the multiplexer's. Swallowing here
+          // keeps a thrown listener from killing the inbound loop and every
+          // other port with it.
+        }
+      }
+    },
+    markClosed() {
+      closed = true;
+      listeners.clear();
+    },
+    isClosed() {
+      return closed;
+    },
+  };
+}