@statewalker/webrun-rpc 0.5.1 → 0.7.0

package/src/port-credit.ts

@@ -0,0 +1,61 @@
+import type { MessageTarget } from "./message-target.js";
+
+/**
+ * The send side of a port with flow control (`PortMuxOptions.window`): what
+ * waits in its queue, and when it has drained.
+ */
+export interface PortSendState {
+  /** Bytes queued on this port, waiting for the peer's credit. */
+  bufferedAmount(): number;
+  /** Resolves once at most `below` bytes are queued (default 0). */
+  ready(below?: number): Promise<void>;
+}
+
+/**
+ * Runs `fn` on a later task, never a microtask: a producer looping on
+ * `whenPortReady` must let the transport's own events run. `setImmediate`
+ * where it exists; elsewhere a `MessageChannel`, because nested `setTimeout`s
+ * are clamped to 4 ms in browsers.
+ */
+const setImmediateFn = (globalThis as { setImmediate?: (fn: () => void) => unknown }).setImmediate;
+/** @internal */
+export const nextTask: (fn: () => void) => void = setImmediateFn
+  ? (fn) => {
+      setImmediateFn(fn);
+    }
+  : (() => {
+      let channel: MessageChannel | undefined;
+      const queue: Array<() => void> = [];
+      return (fn) => {
+        if (!channel) {
+          channel = new MessageChannel();
+          channel.port1.onmessage = () => queue.shift()?.();
+        }
+        queue.push(fn);
+        channel.port2.postMessage(0);
+      };
+    })();
+
+const states = new WeakMap<MessageTarget, PortSendState>();
+
+/** @internal Registered by the multiplexer for each port with a window. */
+export function setPortSendState(port: MessageTarget, state: PortSendState): void {
+  states.set(port, state);
+}
+
+/**
+ * Bytes queued on `port` because its window is spent (0 for a port without
+ * flow control). A sender that should not queue without bound waits for
+ * `whenPortReady` before posting more.
+ */
+export function portBufferedAmount(port: MessageTarget): number {
+  return states.get(port)?.bufferedAmount() ?? 0;
+}
+
+/**
+ * Resolves once at most `below` bytes are queued on `port`, always on a later
+ * task (for a port without flow control, on the next one).
+ */
+export function whenPortReady(port: MessageTarget, below = 0): Promise<void> {
+  return states.get(port)?.ready(below) ?? new Promise<void>((resolve) => nextTask(resolve));
+}

package/src/port-types.ts

@@ -3,14 +3,22 @@ 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.
+ * `open`, `message` and `close`, plus `credit` (a port's window) and `frame`
+ * (a piece of a large message, with `frameSize`). There is no DATA/ACK split
+ * 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: "open"; id: number; meta?: unknown; window?: number; exact?: boolean }
   | { type: "message"; id: number; payload: unknown }
-  | { type: "close"; id: number; reason?: unknown };
+  | { type: "close"; id: number; reason?: unknown }
+  /** Per-port flow control (`window`): the receiver has consumed `bytes` more. */
+  | { type: "credit"; id: number; bytes: number; exact?: boolean }
+  /** Fair framing (`frameSize`): one piece of an encoded `message` envelope. */
+  | { type: "frame"; id: number; data: Uint8Array; last?: boolean }
+  /** Keepalive (`keepalive`): the mux's own liveness probe and its answer, on an id no port takes. */
+  | { type: "ping"; id: number }
+  | { type: "pong"; id: number };
 
 /**
  * How an envelope reaches the wire.
@@ -25,6 +33,15 @@ export interface PortCodec {
   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;
+  /**
+   * Optional, for codecs whose wire form is bytes, with `decode`: the bytes
+   * `post` would place on the port. A port with a window then counts real
+   * bytes instead of an estimate, posts them as they are (encoding once), and
+   * can split them into frames (`frameSize`).
+   */
+  encode?(envelope: PortEnvelope): Uint8Array;
+  /** Optional, with `encode`: an envelope back from its bytes, or `undefined`. */
+  decode?(data: unknown): PortEnvelope | undefined;
 }
 
 export interface PortMuxOptions {
@@ -67,14 +84,113 @@ export interface PortMuxOptions {
    * delivered a body as zero bytes with no error on either side.
    */
   maxMessageSize?: number;
+  /**
+   * The transport's life. When it aborts, the mux closes with
+   * `signal.reason`: every port's close signal aborts and the calls in flight
+   * on them reject at once. Wire it to whatever reports the pipe's death — a
+   * worker's `exit`, a libp2p stream's `close`, a liveness lock — because a
+   * pipe that dies silently otherwise leaves every port open, forever.
+   */
+  signal?: AbortSignal;
+  /**
+   * Per-port flow control, in bytes (off when unset). A port this mux opens
+   * asks for it in its `open`; the peer's mux then applies it to that port in
+   * both directions. Each side may have at most `window` bytes of a port's
+   * messages delivered but not yet consumed by the other side; what exceeds
+   * it waits in the port's send queue (`portBufferedAmount`,
+   * `whenPortReady`). A message counts as consumed once every listener has
+   * returned, or, for a listener that returns a promise, once it settles: a
+   * slow consumer holds its own port's budget, and no other port's.
+   *
+   * A message's size is its byte length (`ArrayBuffer`, typed arrays), a
+   * string's length, or for an object the sizes of its values (4 levels deep,
+   * at most 256 values), and at least 64 — or, when both ends' codecs
+   * implement `encode` / `decode`, the encoded bytes. A message larger than
+   * the window is sent when nothing else is outstanding.
+   *
+   * Safe against an older peer: neither end holds back until the other has
+   * shown it reads credit (the responder's zero-byte ack, then the opener's
+   * answer to it), so a peer that never sends credit runs unwindowed.
+   */
+  window?: number;
+  /**
+   * Fair framing, in bytes (off when unset). Every port's messages leave in
+   * turn, one item per port, whenever the pipe has room (its `whenDrained`),
+   * and a message whose encoding is larger than `frameSize` goes as frames of
+   * that size, reassembled by the peer. A small message then waits for one
+   * frame of another port's large message, not for all of it. It needs
+   * `window` and codecs with `encode` / `decode` on both ends, agreed in the
+   * window's `open` and acknowledgement (`exact`); otherwise messages go
+   * whole. 16-64 KiB is a reasonable range.
+   */
+  frameSize?: number;
+  /**
+   * Liveness of the peer (off when unset). Every `intervalMs` the mux pings
+   * and the peer answers; anything from it counts as an answer. After `misses`
+   * pings in a row (default 3) with nothing back from a peer that has answered
+   * before, the mux closes with `webrun-rpc: the peer did not answer …`: the
+   * peer died or froze. A tick taken while this end's own pipe reports a
+   * backlog (`bufferedAmount`) is not counted. Every current mux answers pings,
+   * with or without this option; an older one never does and is never closed
+   * for it — nor is a peer that dies before its first answer, so wire
+   * `signal` too where the transport can report death.
+   */
+  keepalive?: { intervalMs: number; misses?: number };
+  /**
+   * Leak detection, for development (off when unset). A port its consumer
+   * dropped without `close()` is reported here once the garbage collector
+   * reclaims it. If it has no listener left it is freed on both ends, as a
+   * close would free it; one that still has a listener is still receiving, so
+   * it is reported and left open. A listener that closes over its own port
+   * keeps it reachable from the mux, so such a port is never collected, and
+   * never reported. Each port costs a `FinalizationRegistry` entry, and when
+   * the collector runs is up to the runtime.
+   */
+  onLeak?: (info: PortInfo) => void;
+}
+
+/** What `PortMux.ports()` reports for one open port. */
+export interface PortInfo {
+  id: number;
+  meta?: unknown;
+  /** `Date.now()` when the port was opened. */
+  openedAt: number;
+  /** `Date.now()` of the last message in either direction. */
+  lastActivity: number;
+  /**
+   * The window in force, once the peer acknowledged it. Absent on a port that
+   * asked for one from a peer that never answers credit (an older version).
+   */
+  window?: number;
+  /** With a window: bytes waiting in this port's send queue. */
+  queued?: number;
+  /** With a window: bytes sent and not yet granted back by the peer. */
+  outstanding?: number;
+  /**
+   * With a window: bytes delivered to this side's listeners and not yet
+   * consumed. A value that stays up names a listener whose promise never
+   * settles, which holds the port's window spent.
+   */
+  unconsumed?: number;
+}
+
+export interface OpenPortOptions {
+  /** Closes the port when it aborts, so the port lives no longer than its user. */
+  signal?: AbortSignal;
 }
 
 /** 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>;
+  openPort(meta?: unknown, options?: OpenPortOptions): Promise<MessageTarget>;
+  /**
+   * Close every port, then release the underlying port. With
+   * `multiplexPort`, `reason` becomes the reason of every port's close signal
+   * (`getPortCloseSignal`); `transferPortMux`'s real ports have none.
+   */
+  close(reason?: unknown): Promise<void>;
+  /** The ports open now, to find who holds a full table. */
+  ports?(): PortInfo[];
   /** See {@link PortMuxOptions.maxMessageSize}. */
   readonly maxMessageSize?: number;
 }

package/src/structured-codec.ts

@@ -5,7 +5,15 @@ function isEnvelope(value: unknown): value is PortEnvelope {
   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";
+  return (
+    candidate.type === "open" ||
+    candidate.type === "message" ||
+    candidate.type === "close" ||
+    candidate.type === "credit" ||
+    candidate.type === "frame" ||
+    candidate.type === "ping" ||
+    candidate.type === "pong"
+  );
 }
 
 /**

package/src/transfer-port-mux.ts

@@ -1,5 +1,5 @@
 import type { MessageTarget } from "./message-target.js";
-import type { PortMux } from "./port-types.js";
+import type { OpenPortOptions, 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";
@@ -43,7 +43,8 @@ export function transferPortMux(
   options: TransferPortMuxOptions = {},
 ): PortMux {
   const { onPort, maxMessageSize } = options;
-  const issued = new Set<MessagePort>();
+  // Each port this side issued, with the function that detaches it from its `openPort` signal.
+  const issued = new Map<MessagePort, () => void>();
   let closed = false;
 
   const listener = (event: MessageEvent): void => {
@@ -67,7 +68,14 @@ export function transferPortMux(
       port.close();
       return;
     }
-    issued.add(port);
+    // A port its user closes is forgotten, as on the opening side.
+    const forget = () => issued.delete(port);
+    issued.set(port, forget);
+    const close = port.close.bind(port);
+    port.close = () => {
+      forget();
+      close();
+    };
   };
 
   target.addEventListener("message", listener);
@@ -76,25 +84,41 @@ export function transferPortMux(
   return {
     maxMessageSize,
 
-    async openPort(meta?: unknown): Promise<MessageTarget> {
+    async openPort(meta?: unknown, { signal }: OpenPortOptions = {}): Promise<MessageTarget> {
       if (closed) throw new Error("webrun-rpc: the multiplexer is closed");
+      if (signal?.aborted) throw signal.reason;
       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;
+      const port = channel.port1;
+      const onAbort = () => port.close();
+      signal?.addEventListener("abort", onAbort, { once: true });
+      // The port is done when its user closes it, the signal aborts, or the mux closes: each
+      // forgets it and removes the signal's listener, so a long-lived signal reused for many
+      // ports holds none of them.
+      const forget = () => {
+        signal?.removeEventListener("abort", onAbort);
+        issued.delete(port);
+      };
+      issued.set(port, forget);
+      const close = port.close.bind(port);
+      port.close = () => {
+        forget();
+        close();
+      };
+      return port;
     },
 
     async close(): Promise<void> {
       if (closed) return;
       closed = true;
       target.removeEventListener("message", listener);
-      for (const port of issued) {
+      for (const port of [...issued.keys()]) {
         try {
-          port.close();
+          port.close(); // forgets it too
         } catch {
           /* already gone */
         }

package/src/virtual-port.ts

@@ -4,8 +4,12 @@ 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: hand an inbound payload to the consumer's listeners.
+   * Returns a promise when a listener returned one (settled once they all
+   * have), so flow control can count the message as consumed only then.
+   */
+  deliver(payload: unknown, size?: number): Promise<unknown> | undefined;
   /**
    * Multiplexer-only: the port is finished; drop listeners and go inert.
    * `reason` becomes the reason of the port's close signal (see
@@ -13,6 +17,8 @@ export interface VirtualPortHandle {
    */
   markClosed(reason?: unknown): void;
   isClosed(): boolean;
+  /** Multiplexer-only: the consumer still listens, so the port is in use. */
+  hasListeners(): boolean;
 }
 
 /**
@@ -39,6 +45,21 @@ export function newVirtualPort(
     closing.abort(reason ?? new Error("webrun-rpc: the port was closed"));
   };
 
+  // A standalone function, not a method using `port`: closures here share one
+  // scope, and one that captured `port` would make `deliver` and `markClosed`
+  // — which the mux keeps — hold the consumer's port too (see `onLeak`). It
+  // also works detached, as `Symbol.dispose` may be called.
+  const close = (reason?: unknown): void => {
+    if (closed) return;
+    closed = true;
+    const notify = requestClose;
+    listeners.clear();
+    // The mux frees the port first (its slot and its entry in `ports()`), then the close
+    // signal fires with the caller's reason: a listener that reopens (reconnect logic) finds
+    // the slot free. `notify` passes the reason on to `markClosed`, which aborts with it.
+    notify(reason);
+    abort(reason);
+  };
   const port: MessageTarget = {
     addEventListener(_type, listener) {
       listeners.add(listener);
@@ -50,32 +71,38 @@ export function newVirtualPort(
       if (closed) return;
       send(message, transfer);
     },
-    close() {
-      if (closed) return;
-      closed = true;
-      const notify = requestClose;
-      listeners.clear();
-      notify();
-      abort();
-    },
+    close,
   };
   setPortCloseSignal(port, closing.signal);
+  // `using port = await mux.openPort()` closes it on scope exit. Installed
+  // only where the runtime has the symbol, and kept off the declared type,
+  // which would require consumers to compile with `esnext.disposable`.
+  const dispose = (Symbol as { dispose?: symbol }).dispose;
+  if (dispose) {
+    Object.defineProperty(port, dispose, { value: () => close(), configurable: true });
+  }
 
   return {
     port,
     deliver(payload) {
       if (closed) return;
       const event = new MessageEvent("message", { data: payload });
+      let pending: PromiseLike<unknown>[] | undefined;
       // Copy first: a listener may add or remove listeners while running.
       for (const listener of [...listeners]) {
         try {
-          void listener(event);
+          const result = listener(event) as unknown;
+          if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+            pending ??= [];
+            pending.push(result as PromiseLike<unknown>);
+          }
         } 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.
         }
       }
+      return pending ? Promise.allSettled(pending) : undefined;
     },
     markClosed(reason) {
       closed = true;
@@ -85,5 +112,8 @@ export function newVirtualPort(
     isClosed() {
       return closed;
     },
+    hasListeners() {
+      return listeners.size > 0;
+    },
   };
 }