@statewalker/webrun-rpc 0.8.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,6 +33,23 @@ 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;
 
@@ -125,6 +149,8 @@ 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: (whole?: boolean) => void; size: number }[];
     queued: number;
@@ -132,6 +158,18 @@ export function multiplexPort(
     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,
@@ -202,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;
@@ -277,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();
   };
@@ -285,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;
@@ -339,6 +404,7 @@ export function multiplexPort(
             enforced: false,
             opener,
             exact,
+            caps: new Set(),
             outstanding: 0,
             queue: [],
             queued: 0,
@@ -346,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
@@ -447,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,
@@ -494,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) {
@@ -533,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 });
       }
@@ -542,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
@@ -587,12 +711,12 @@ export function multiplexPort(
             : undefined;
       if (overrun) {
         // A peer that frames past what it may send: hold none of it.
-        freePartial(entry);
-        dropOutgoing(envelope.id);
-        open.delete(envelope.id);
-        releaseWaiters(c);
-        entry.handle.markClosed(new RangeError(`webrun-rpc: a framed message passed ${overrun}`));
-        post({ type: "close", id: envelope.id, reason: "max-reassembled-bytes" });
+        failPort(
+          envelope.id,
+          entry,
+          new RangeError(`webrun-rpc: a framed message passed ${overrun}`),
+          "max-reassembled-bytes",
+        );
         return;
       }
       partial.bytes += size;
@@ -613,6 +737,27 @@ 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;
@@ -724,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 {

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.