@statewalker/webrun-rpc 0.7.0 → 0.10.0

package/src/multiplex-port.ts

@@ -1,8 +1,15 @@
 import { getPortCloseSignal } from "./close-signal.js";
 import type { MessageTarget } from "./message-target.js";
-import { nextTask, setPortSendState } from "./port-credit.js";
+import {
+  nextTask,
+  type PortCap,
+  setPortAgreement,
+  setPortEndState,
+  setPortSendState,
+} from "./port-credit.js";
 import type {
   OpenPortOptions,
+  PortCodec,
   PortEnvelope,
   PortInfo,
   PortMux,
@@ -26,9 +33,29 @@ const KEEPALIVE_ID = Number.MAX_SAFE_INTEGER;
 /** The longest delay a timer holds; past it `setInterval` fires at once. */
 const MAX_TIMER_MS = 2 ** 31 - 1;
 
+/**
+ * What a windowed port offers in its `open`: every capability this end
+ * speaks. `end` only over a codec that reads it (`PortCodec.halfClose`).
+ */
+function ownCaps(codec: PortCodec): readonly PortCap[] {
+  return codec.halfClose ? ["pipeline", "end"] : ["pipeline"];
+}
+
+/**
+ * The capabilities in a peer's `caps` that this end speaks too, or
+ * `undefined` when the peer listed none (it is then treated as an older peer).
+ */
+function sharedCaps(own: readonly PortCap[], listed: unknown): Set<PortCap> | undefined {
+  if (!Array.isArray(listed)) return undefined;
+  return new Set(own.filter((cap) => listed.includes(cap)));
+}
+
 /** Ceiling on concurrently open virtual ports. Bounds the id table only. */
 export const DEFAULT_MAX_PORTS = 1024;
 
+/** Default ceiling on one message reassembled from frames (`maxReassembledBytes`). */
+export const DEFAULT_MAX_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+
 /**
  * What a message costs a port's window when the codec cannot say
  * (`PortCodec.encode`): its bytes and string lengths, found in its values up
@@ -73,6 +100,7 @@ export function multiplexPort(
     keepalive,
     onLeak,
   } = options;
+  const maxReassembledBytes = options.maxReassembledBytes ?? DEFAULT_MAX_REASSEMBLED_BYTES;
   const misses = keepalive?.misses ?? 3;
   if (
     keepalive &&
@@ -92,6 +120,11 @@ export function multiplexPort(
   if (frameSize != null && !(Number.isSafeInteger(frameSize) && frameSize > 0)) {
     throw new RangeError(`webrun-rpc: frameSize must be a positive integer, got ${frameSize}`);
   }
+  if (!(Number.isSafeInteger(maxReassembledBytes) && maxReassembledBytes > 0)) {
+    throw new RangeError(
+      `webrun-rpc: maxReassembledBytes must be a positive integer, got ${maxReassembledBytes}`,
+    );
+  }
 
   /**
    * Flow control of one port (`PortMuxOptions.window`): the send side's queue
@@ -116,13 +149,27 @@ export function multiplexPort(
      * port wedged.
      */
     exact: boolean;
+    /** What both ends speak on this port; empty until the handshake says otherwise. */
+    caps: Set<PortCap>;
     outstanding: number;
-    queue: { send: () => void; size: number }[];
+    queue: { send: (whole?: boolean) => void; size: number }[];
     queued: number;
     unconsumed: number;
     waiters: { below: number; resolve: () => void }[];
     toGrant: number;
     grantScheduled: boolean;
+    /** This side's `end` is queued: anything posted afterwards is dropped. */
+    ending: boolean;
+    /** This side's `end` has left, behind the port's frames. */
+    endSent: boolean;
+    /** The peer's `end` has arrived. */
+    peerEnded: boolean;
+    /**
+     * Resolves `whenPortEnded`, once someone waits for it. Held weakly: the
+     * waiter's continuations would otherwise keep a dropped port reachable
+     * from the mux, and `onLeak` would never see it.
+     */
+    onPeerEnd?: WeakRef<() => void>;
   }
   /**
    * What the mux keeps of a port: never the consumer's `port` object itself,
@@ -138,10 +185,28 @@ export function multiplexPort(
   interface Entry extends PortInfo {
     handle: PortRecord;
     credit?: Credit;
-    /** The frames of a message still arriving. */
-    partial?: { chunks: Uint8Array[]; bytes: number };
+    /**
+     * The frames of a message still arriving. `room`: what the window left
+     * when the first came, if anything was still owed back then. `charged`:
+     * its bytes past the window, counted in `reassembling`.
+     */
+    partial?: {
+      chunks: Uint8Array[];
+      bytes: number;
+      room?: number;
+      owed: number;
+      charged: number;
+    };
   }
   const open = new Map<number, Entry>();
+  // Bytes of partial messages held past their port's window, across every
+  // port (`maxReassembledBytes`). What fits a window is bounded by it already.
+  let reassembling = 0;
+  const freePartial = (entry: Entry | undefined): void => {
+    if (!entry?.partial) return;
+    reassembling -= entry.partial.charged;
+    entry.partial = undefined;
+  };
   // A port collected while still open: report it, then free its slot on both
   // ends as its close would. Only with `onLeak` — a registry costs per port.
   const leaks = onLeak
@@ -175,6 +240,8 @@ export function multiplexPort(
   let muxClosed = false;
   /** This end counts encoded bytes and reassembles frames. */
   const exactCodec = codec.encode != null && codec.decode != null;
+  /** What this end offers on a windowed port. */
+  const caps = ownCaps(codec);
 
   const post = (envelope: PortEnvelope, transfer?: Transferable[]): void => {
     if (muxClosed) return;
@@ -250,6 +317,29 @@ export function multiplexPort(
     }
   };
 
+  /**
+   * Both directions have ended: free the id as a close would, with no `close`
+   * on the wire (each end frees it on its own once it has seen both ends).
+   * Aborting the close signal is how the port's consumer learns it is gone.
+   */
+  const freeIfEnded = (id: number, c: Credit): void => {
+    const entry = open.get(id);
+    if (!c.endSent || !c.peerEnded || entry?.credit !== c) return;
+    freePartial(entry);
+    open.delete(id);
+    leaks?.unregister(entry.handle);
+    entry.handle.markClosed(new Error("webrun-rpc: the port ended in both directions"));
+  };
+  /** A peer that broke the port's protocol: hold none of its traffic, and close. */
+  const failPort = (id: number, entry: Entry, error: Error, reason: string): void => {
+    freePartial(entry);
+    dropOutgoing(id);
+    open.delete(id);
+    releaseWaiters(entry.credit);
+    entry.handle.markClosed(error);
+    post({ type: "close", id, reason });
+  };
+
   const releaseWaiters = (c: Credit | undefined): void => {
     for (const w of c?.waiters.splice(0) ?? []) w.resolve();
   };
@@ -258,8 +348,10 @@ export function multiplexPort(
     while (c.queue.length) {
       // biome-ignore lint/style/noNonNullAssertion: the loop condition checks the queue is not empty.
       const next = c.queue[0]!;
-      // A message larger than the window goes out once nothing else is outstanding.
-      if (c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window) break;
+      // A message larger than the window goes out once nothing else is
+      // outstanding. An `end` (size 0) costs no window and never waits for credit.
+      if (next.size > 0 && c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window)
+        break;
       c.queue.shift();
       c.queued -= next.size;
       c.outstanding += next.size;
@@ -312,6 +404,7 @@ export function multiplexPort(
             enforced: false,
             opener,
             exact,
+            caps: new Set(),
             outstanding: 0,
             queue: [],
             queued: 0,
@@ -319,10 +412,15 @@ export function multiplexPort(
             waiters: [],
             toGrant: 0,
             grantScheduled: false,
+            ending: false,
+            endSent: false,
+            peerEnded: false,
           }
         : undefined;
     const self = newVirtualPort(
       (payload, transfer) => {
+        // This side's direction has ended: nothing more goes out on it.
+        if (c?.ending) return;
         touch(id);
         const envelope: PortEnvelope = { type: "message", id, payload };
         // Without a window nothing frames or waits: post at once, so the
@@ -346,14 +444,22 @@ export function multiplexPort(
           !bytes && waits
             ? { ...envelope, payload: structuredClone(payload, { transfer }) }
             : undefined;
-        const send = (): void => {
+        // `whole`: at close, what is still queued leaves past the window, and
+        // a frame past the window is what the peer refuses (`maxReassembledBytes`).
+        const send = (whole = false): void => {
           if (!bytes) {
             sendOnPort(id, held ? () => post(held) : () => post(envelope, transfer));
             return;
           }
           // Frames only once the peer has acknowledged exact sizing: before
           // that, it may be a peer that cannot reassemble them.
-          if (frameSize != null && c.enforced && c.exact && bytes.byteLength > frameSize) {
+          if (
+            !whole &&
+            frameSize != null &&
+            c.enforced &&
+            c.exact &&
+            bytes.byteLength > frameSize
+          ) {
             for (let at = 0; at < bytes.byteLength; at += frameSize) {
               const data = bytes.subarray(at, at + frameSize);
               const frame: PortEnvelope =
@@ -376,6 +482,7 @@ export function multiplexPort(
       },
     );
     function release(reason: unknown): void {
+      freePartial(open.get(id));
       open.delete(id);
       leaks?.unregister(record);
       // What is queued goes out now, before the close and regardless of the
@@ -384,7 +491,7 @@ export function multiplexPort(
       // kept for a port nobody holds. Without a window it would all have
       // gone out at once anyway.
       if (c?.queue.length) {
-        for (const item of c.queue.splice(0)) item.send();
+        for (const item of c.queue.splice(0)) item.send(true);
         c.queued = 0;
       }
       // Behind this port's frames, so the peer gets the whole message first.
@@ -411,6 +518,40 @@ export function multiplexPort(
             else c.waiters.push({ below, resolve: () => nextTask(resolve) });
           }),
       });
+      setPortEndState(self.port, {
+        end: () => {
+          if (isClosed() || !c.caps.has("end")) return false;
+          if (c.ending) return true;
+          c.ending = true;
+          // Behind what this side already posted: first in the window queue
+          // (a size-0 item), then in the fair-framing ring behind its frames.
+          c.queue.push({
+            size: 0,
+            send: () =>
+              sendOnPort(id, () => {
+                // A port closed meanwhile was abandoned, not ended: its peer
+                // hears the close alone, never an end that looks like a normal finish.
+                if (open.get(id)?.credit !== c) return;
+                post({ type: "end", id });
+                c.endSent = true;
+                freeIfEnded(id, c);
+              }),
+          });
+          flush(c);
+          return true;
+        },
+        watchPeerEnd: (resolve) => {
+          if (!c.caps.has("end")) return false;
+          if (c.peerEnded) resolve();
+          else c.onPeerEnd = new WeakRef(resolve);
+          return true;
+        },
+      });
+      setPortAgreement(self.port, () => ({
+        window: c.window,
+        caps: c.caps,
+        enforced: c.enforced,
+      }));
     }
     const record: PortRecord = {
       deliver: self.deliver,
@@ -458,13 +599,18 @@ export function multiplexPort(
       // Acknowledge the window before `onPort` runs: what `onPort` posts then
       // reaches the opener after the ack, so both ends count it the same way
       // (exact bytes or the estimate). A rejection's close follows the ack.
+      // Only an opener that listed capabilities hears them answered; they
+      // hold from here for what it sends. This end's own sends still wait for
+      // the opener's answer to the ack before the window holds them: that
+      // answer is what shows this end's codec reads credit at all.
       const credit = open.get(envelope.id)?.credit;
+      const listed = sharedCaps(caps, envelope.caps);
       if (credit) {
-        post(
-          credit.exact
-            ? { type: "credit", id: envelope.id, bytes: 0, exact: true }
-            : { type: "credit", id: envelope.id, bytes: 0 },
-        );
+        const ack: PortEnvelope = credit.exact
+          ? { type: "credit", id: envelope.id, bytes: 0, exact: true }
+          : { type: "credit", id: envelope.id, bytes: 0 };
+        if (listed) credit.caps = listed;
+        post(listed ? { ...ack, caps: [...listed] } : ack);
       }
       let accepted = false;
       if (onPort) {
@@ -497,6 +643,7 @@ export function multiplexPort(
           c.exact = false;
           c.outstanding = 0;
         }
+        c.caps = sharedCaps(caps, envelope.caps) ?? new Set();
         // Show the responder its codec reads credit, so it may hold back too.
         post({ type: "credit", id: envelope.id, bytes: 0 });
       }
@@ -506,6 +653,19 @@ export function multiplexPort(
       return;
     }
 
+    // Nothing follows a peer's `end` on its direction but credit: an honest
+    // sender drops what is posted after it. Delivering more would hand the
+    // consumer data after it was told the input is over.
+    if ((envelope.type === "message" || envelope.type === "frame") && entry?.credit?.peerEnded) {
+      failPort(
+        envelope.id,
+        entry,
+        new Error("webrun-rpc: the peer sent on a port after its end"),
+        "protocol",
+      );
+      return;
+    }
+
     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
@@ -520,16 +680,51 @@ export function multiplexPort(
 
     if (envelope.type === "frame") {
       // Only where this end advertised exact sizing — the one place a peer may
-      // frame. A frame sequence buffers no more than the same message sent
-      // whole, which a byte transport would also have to hold entire.
+      // frame. What a partial message may hold is bounded below, so frames
+      // that never end cannot make this side buffer without limit.
       if (!entry?.credit?.exact || !codec.decode || !(envelope.data instanceof Uint8Array)) return;
       touch(envelope.id);
-      const partial = entry.partial ?? { chunks: [], bytes: 0 };
+      const c = entry.credit;
+      // What this side still owes back (delivered and unconsumed, or consumed
+      // and not yet granted) is never more than what the sender counted as
+      // outstanding. So an honest sender starts a message only when owed plus
+      // the message fits the window, or when nothing is owed at all: a message
+      // larger than the window, bounded by `maxReassembledBytes` alone.
+      const owed = c.unconsumed + c.toGrant;
+      const partial = entry.partial ?? {
+        chunks: [],
+        bytes: 0,
+        owed,
+        charged: 0,
+        ...(owed > 0 ? { room: c.window - owed } : {}),
+      };
       entry.partial = partial;
+      const size = envelope.data.byteLength;
+      // Only a message begun with nothing owed may pass the window; what it
+      // holds past it is what the cap, shared by all ports, bounds.
+      const charged = partial.room == null ? Math.max(0, partial.bytes + size - c.window) : 0;
+      const overrun =
+        partial.room != null && partial.bytes + size > partial.room
+          ? `what the window left (${partial.room} of ${c.window} bytes, ${partial.owed} still owed)`
+          : reassembling - partial.charged + charged > maxReassembledBytes
+            ? `maxReassembledBytes (${maxReassembledBytes} bytes past the window, across all ports)`
+            : undefined;
+      if (overrun) {
+        // A peer that frames past what it may send: hold none of it.
+        failPort(
+          envelope.id,
+          entry,
+          new RangeError(`webrun-rpc: a framed message passed ${overrun}`),
+          "max-reassembled-bytes",
+        );
+        return;
+      }
+      partial.bytes += size;
+      reassembling += charged - partial.charged;
+      partial.charged = charged;
       partial.chunks.push(envelope.data);
-      partial.bytes += envelope.data.byteLength;
       if (!envelope.last) return;
-      entry.partial = undefined;
+      freePartial(entry);
       const whole = new Uint8Array(partial.bytes);
       let at = 0;
       for (const chunk of partial.chunks) {
@@ -542,9 +737,31 @@ export function multiplexPort(
       return;
     }
 
+    if (envelope.type === "end") {
+      if (!entry) return;
+      const c = entry.credit;
+      // Only where `end` was agreed. Anywhere else the peer broke the protocol,
+      // as with a pipelined chunk where pipelining was not agreed.
+      if (!c?.caps.has("end")) {
+        failPort(
+          envelope.id,
+          entry,
+          new Error("webrun-rpc: the peer ended a port where end was not agreed"),
+          "protocol",
+        );
+        return;
+      }
+      touch(envelope.id);
+      c.peerEnded = true;
+      c.onPeerEnd?.deref()?.();
+      freeIfEnded(envelope.id, c);
+      return;
+    }
+
     // The peer closed the port: whatever it still had to receive is moot.
     dropOutgoing(envelope.id);
     if (!entry) return;
+    freePartial(entry);
     open.delete(envelope.id);
     releaseWaiters(entry.credit);
     entry.handle.markClosed(new Error("webrun-rpc: the peer closed the port"));
@@ -652,8 +869,8 @@ export function multiplexPort(
       post(
         window
           ? exactCodec
-            ? { type: "open", id, meta, window, exact: true }
-            : { type: "open", id, meta, window }
+            ? { type: "open", id, meta, window, exact: true, caps: [...caps] }
+            : { type: "open", id, meta, window, caps: [...caps] }
           : { type: "open", id, meta },
       );
       if (portSignal) {

package/src/port-credit.ts

@@ -59,3 +59,89 @@ export function portBufferedAmount(port: MessageTarget): number {
 export function whenPortReady(port: MessageTarget, below = 0): Promise<void> {
   return states.get(port)?.ready(below) ?? new Promise<void>((resolve) => nextTask(resolve));
 }
+
+/** A capability two ends agree on for one windowed port, in its `open` and the ack. */
+export type PortCap = "pipeline" | "end";
+
+/**
+ * What two ends have agreed for one windowed port so far. `caps`: what both
+ * speak, and so what the peer may send; empty until the handshake settles it
+ * (the opener learns it from the ack, the responder from the `open`).
+ * `enforced`: the window holds this end's own sends — what this end needs
+ * before it relies on the window instead of a confirmation per message.
+ */
+export interface PortAgreement {
+  window: number;
+  caps: ReadonlySet<PortCap>;
+  enforced: boolean;
+}
+
+const agreements = new WeakMap<MessageTarget, () => PortAgreement | undefined>();
+
+/** @internal Registered by the multiplexer for each port with a window. */
+export function setPortAgreement(port: MessageTarget, agreement: () => PortAgreement | undefined) {
+  agreements.set(port, agreement);
+}
+
+/**
+ * @internal What has been agreed with the peer on `port` so far; `undefined`
+ * on a port without a window. Not exported from the package.
+ */
+export function portAgreement(port: MessageTarget): PortAgreement | undefined {
+  return agreements.get(port)?.();
+}
+
+/** @internal The half-close of one windowed port (capability `"end"`). */
+export interface PortEndState {
+  /** Queue this side's `end`; `false` when `end` was not agreed. */
+  end(): boolean;
+  /**
+   * Calls `resolve` once the peer has ended its direction (at once if it has
+   * already); `false`, and `resolve` is never called, when `end` was not
+   * agreed. The mux holds `resolve` weakly, so a port dropped while someone
+   * waits on it can still be collected (`onLeak`).
+   */
+  watchPeerEnd(resolve: () => void): boolean;
+}
+
+const ends = new WeakMap<MessageTarget, PortEndState>();
+
+/** @internal Registered by the multiplexer for each port with a window. */
+export function setPortEndState(port: MessageTarget, state: PortEndState): void {
+  ends.set(port, state);
+}
+
+/**
+ * @internal End this side's direction of `port`: an `end` is queued behind
+ * everything already posted on it, and anything posted afterwards is dropped.
+ * `false`, and nothing changes, when `end` was not agreed (no window, the
+ * handshake not answered yet, or a peer that does not speak it): the caller
+ * then closes the port. Never waits on the peer. Not exported from the package.
+ */
+export function endPort(port: MessageTarget): boolean {
+  return ends.get(port)?.end() ?? false;
+}
+
+/**
+ * @internal Resolves once the peer has ended its direction of `port`. It never
+ * settles otherwise: not on a port where `end` is not agreed when it is asked
+ * (no window, the handshake not answered yet, a peer or codec without it), and
+ * not when the port closes first, so a caller races it against the port's
+ * close signal. Not exported from the package.
+ */
+export function whenPortEnded(port: MessageTarget): Promise<void> {
+  let waiting = peerEnds.get(port);
+  if (!waiting) {
+    let resolve: () => void = () => {};
+    const promise = new Promise<void>((r) => {
+      resolve = r;
+    });
+    if (!ends.get(port)?.watchPeerEnd(resolve)) return promise;
+    // Held from the port only: what waits on it lives as long as the port.
+    waiting = { promise, resolve };
+    peerEnds.set(port, waiting);
+  }
+  return waiting.promise;
+}
+
+const peerEnds = new WeakMap<MessageTarget, { promise: Promise<void>; resolve: () => void }>();

package/src/port-types.ts

@@ -9,11 +9,18 @@ import type { MessageTarget } from "./message-target.js";
  * inspects, because stream semantics belong above this layer.
  */
 export type PortEnvelope =
-  | { type: "open"; id: number; meta?: unknown; window?: number; exact?: boolean }
+  /** `caps` (with a window): the capabilities the opener speaks on this port. */
+  | { type: "open"; id: number; meta?: unknown; window?: number; exact?: boolean; caps?: string[] }
   | { type: "message"; id: number; payload: 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 }
+  /**
+   * Per-port flow control (`window`): the receiver has consumed `bytes` more.
+   * The responder's zero-byte ack carries `caps`, the shared subset, when the
+   * opener listed some.
+   */
+  | { type: "credit"; id: number; bytes: number; exact?: boolean; caps?: string[] }
+  /** Half-close (capability `"end"`): the sender's direction of the port has ended. */
+  | { type: "end"; id: number }
   /** 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. */
@@ -42,6 +49,15 @@ export interface PortCodec {
   encode?(envelope: PortEnvelope): Uint8Array;
   /** Optional, with `encode`: an envelope back from its bytes, or `undefined`. */
   decode?(data: unknown): PortEnvelope | undefined;
+  /**
+   * Optional: this codec's `read` (and `decode`) accept the `end` envelope.
+   * Only then does a windowed port offer the `end` capability. A codec that
+   * dropped `end` would leave a port that ended normally in the peer's table
+   * (`ports()`) until the mux closes, with no error anywhere. A codec spread
+   * from a built-in (`{ ...structuredCodec, read }`) inherits the flag: its
+   * own `read` must then accept `end` too, or it must drop the flag.
+   */
+  halfClose?: true;
 }
 
 export interface PortMuxOptions {
@@ -124,6 +140,19 @@ export interface PortMuxOptions {
    * whole. 16-64 KiB is a reasonable range.
    */
   frameSize?: number;
+  /**
+   * Ceiling, in bytes, on what this side holds of a peer's framed messages
+   * past their ports' windows, summed over all ports (default 64 MiB).
+   * A partial message counts against its port's window as it arrives: one
+   * begun while this side still owed credit must fit what the window left,
+   * and one begun with nothing owed may pass the window, its excess charged
+   * to this cap. A frame past either limit makes the mux drop that port's
+   * partial message, close the port with a `RangeError` and send the peer a
+   * close with reason `"max-reassembled-bytes"`. A framed message more than
+   * this cap past the window never arrives, though the same message sent
+   * whole would.
+   */
+  maxReassembledBytes?: 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`

package/src/structured-codec.ts

@@ -12,7 +12,8 @@ function isEnvelope(value: unknown): value is PortEnvelope {
     candidate.type === "credit" ||
     candidate.type === "frame" ||
     candidate.type === "ping" ||
-    candidate.type === "pong"
+    candidate.type === "pong" ||
+    candidate.type === "end"
   );
 }
 
@@ -26,6 +27,9 @@ function isEnvelope(value: unknown): value is PortEnvelope {
  * not send anything a byte codec could not also carry.
  */
 export const structuredCodec: PortCodec = {
+  // `read` accepts `end`, so windowed ports over this codec offer it.
+  halfClose: true,
+
   post(port, envelope, transfer) {
     // An empty transfer list is not the same as no transfer list — some
     // implementations reject the former.