@statewalker/webrun-rpc 0.5.1 → 0.8.0

package/dist/listen-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listen-port.d.ts","sourceRoot":"","sources":["../src/listen-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,WAAW,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAC9D,MAAM,EAAE,OAAO,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC7D,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,EAAE,WAAgB,EAAE,GAAc,EAAE,GAAE,iBAAsB,GAC3D,MAAM,IAAI,CAsBZ"}
+{"version":3,"file":"listen-port.d.ts","sourceRoot":"","sources":["../src/listen-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,WAAW,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAC9D,MAAM,EAAE,OAAO,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC7D,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,EAAE,WAAgB,EAAE,GAAc,EAAE,GAAE,iBAAsB,GAC3D,MAAM,IAAI,CA6BZ"}

package/dist/message-target.d.ts

@@ -8,9 +8,22 @@ export interface MessageSource {
 /** An object we can post messages to (with optional transferable list). */
 export interface MessageSink {
     postMessage(message: unknown, transfer?: Transferable[]): void;
+    /**
+     * Optional: bytes posted and not yet written out, as a WebSocket's or an
+     * `RTCDataChannel`'s `bufferedAmount`. Informational.
+     */
+    readonly bufferedAmount?: number;
+    /**
+     * Optional: resolves once the pipe can take more, at once when it can now.
+     * A multiplexer with `frameSize` waits on it between frames, which is what
+     * lets frames of different ports take turns instead of piling up in the
+     * pipe's own buffer.
+     */
+    whenDrained?(): Promise<void>;
 }
 /** Full-duplex message target: both sends and receives. */
 export interface MessageTarget extends MessageSource, MessageSink {
-    close?(): void | Promise<void>;
+    /** `reason`, where the target keeps one, becomes its close signal's reason. */
+    close?(reason?: unknown): void | Promise<void>;
 }
 //# sourceMappingURL=message-target.d.ts.map

package/dist/message-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACnE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;CAChE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAc,SAAQ,aAAa,EAAE,WAAW;IAC/D,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}
+{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACnE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/D;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAc,SAAQ,aAAa,EAAE,WAAW;IAC/D,+EAA+E;IAC/E,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}

package/dist/multiplex-port.d.ts

@@ -1,5 +1,5 @@
 import type { MessageTarget } from "./message-target.js";
-import type { PortMux, PortMuxOptions } from "./port-types.js";
+import type { PortInfo, PortMux, PortMuxOptions } from "./port-types.js";
 /**
  * The message of the error that fails the calls still in flight on a
  * multiplexer when it is closed (`PortMux.close()`).
@@ -7,11 +7,22 @@ import type { PortMux, PortMuxOptions } from "./port-types.js";
 export declare const MUX_CLOSED_MESSAGE = "webrun-rpc: the multiplexer was closed";
 /** Ceiling on concurrently open virtual ports. Bounds the id table only. */
 export declare const DEFAULT_MAX_PORTS = 1024;
+/** Default ceiling on one message reassembled from frames (`maxReassembledBytes`). */
+export declare const DEFAULT_MAX_REASSEMBLED_BYTES: number;
+/**
+ * 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
+ * to 4 levels deep (at most 256 values), and at least 64. Both ends compute it
+ * from the same structured value, so they agree.
+ */
+export declare function estimateMessageSize(payload: unknown): number;
 /**
  * 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 declare function multiplexPort(port: MessageTarget, options: PortMuxOptions): PortMux;
+export declare function multiplexPort(port: MessageTarget, options: PortMuxOptions): PortMux & {
+    ports(): PortInfo[];
+};
 //# sourceMappingURL=multiplex-port.d.ts.map

package/dist/multiplex-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multiplex-port.d.ts","sourceRoot":"","sources":["../src/multiplex-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7E;;;GAGG;AACH,eAAO,MAAM,kBAAkB,2CAA2C,CAAC;AAE3E,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAwHnF"}
+{"version":3,"file":"multiplex-port.d.ts","sourceRoot":"","sources":["../src/multiplex-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAGV,QAAQ,EACR,OAAO,EACP,cAAc,EACf,MAAM,iBAAiB,CAAC;AAGzB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,2CAA2C,CAAC;AAY3E,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,sFAAsF;AACtF,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAc5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,GAAG;IAAE,KAAK,IAAI,QAAQ,EAAE,CAAA;CAAE,CA0rBnC"}

package/dist/port-credit.d.ts

@@ -0,0 +1,27 @@
+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>;
+}
+/** @internal */
+export declare const nextTask: (fn: () => void) => void;
+/** @internal Registered by the multiplexer for each port with a window. */
+export declare function setPortSendState(port: MessageTarget, state: PortSendState): void;
+/**
+ * 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 declare function portBufferedAmount(port: MessageTarget): number;
+/**
+ * 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 declare function whenPortReady(port: MessageTarget, below?: number): Promise<void>;
+//# sourceMappingURL=port-credit.d.ts.map

package/dist/port-credit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-credit.d.ts","sourceRoot":"","sources":["../src/port-credit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,cAAc,IAAI,MAAM,CAAC;IACzB,kEAAkE;IAClE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AASD,gBAAgB;AAChB,eAAO,MAAM,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAenC,CAAC;AAIT,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3E"}

package/dist/port-types.d.ts

@@ -2,14 +2,17 @@ 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;
+    window?: number;
+    exact?: boolean;
 } | {
     type: "message";
     id: number;
@@ -18,6 +21,28 @@ export type PortEnvelope = {
     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.
@@ -32,6 +57,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 {
     /** How envelopes are placed on the underlying port. */
@@ -73,13 +107,126 @@ 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;
+    /**
+     * 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`
+     * 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/dist/port-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port-types.d.ts","sourceRoot":"","sources":["../src/port-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IACnF,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;IACtE;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,OAAO;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}
+{"version":3,"file":"port-types.d.ts","sourceRoot":"","sources":["../src/port-types.ts"],"names":[],"mappings":"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"}

package/dist/structured-codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structured-codec.d.ts","sourceRoot":"","sources":["../src/structured-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAU/D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,SAU7B,CAAC"}
+{"version":3,"file":"structured-codec.d.ts","sourceRoot":"","sources":["../src/structured-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAkB/D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,SAU7B,CAAC"}

package/dist/transfer-port-mux.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-port-mux.d.ts","sourceRoot":"","sources":["../src/transfer-port-mux.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;IACtE,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CA8DT"}
+{"version":3,"file":"transfer-port-mux.d.ts","sourceRoot":"","sources":["../src/transfer-port-mux.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAmB,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEhE,8EAA8E;AAC9E,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;IACtE,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAsFT"}

package/dist/virtual-port.d.ts

@@ -2,8 +2,12 @@ import type { 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
@@ -11,6 +15,8 @@ export interface VirtualPortHandle {
      */
     markClosed(reason?: unknown): void;
     isClosed(): boolean;
+    /** Multiplexer-only: the consumer still listens, so the port is in use. */
+    hasListeners(): boolean;
 }
 /**
  * One virtual port.

package/dist/virtual-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-port.d.ts","sourceRoot":"","sources":["../src/virtual-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,IAAI,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,KAAK,IAAI,EAC3D,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,GACvC,iBAAiB,CA6DnB"}
+{"version":3,"file":"virtual-port.d.ts","sourceRoot":"","sources":["../src/virtual-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,IAAI,EAAE,aAAa,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IACvE;;;;OAIG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,IAAI,OAAO,CAAC;IACpB,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,KAAK,IAAI,EAC3D,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,GACvC,iBAAiB,CAqFnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-rpc",
-  "version": "0.5.1",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "description": "Ports and RPC over them: a port multiplexer, and typed request/response and streaming primitives over any MessageTarget.",

package/src/connect-serve.ts

@@ -6,7 +6,7 @@ import {
 } from "./duplex-over-port.js";
 import type { MessageTarget } from "./message-target.js";
 import { multiplexPort } from "./multiplex-port.js";
-import type { PortCodec, PortMux } from "./port-types.js";
+import type { PortCodec, PortMux, PortMuxOptions } from "./port-types.js";
 import { returningAtOnce } from "./return-at-once.js";
 
 /**
@@ -139,15 +139,24 @@ export const serve: Serve<PortParams> = async ({ mux: factory, timeout }, handle
     // reaches it as `return()` through `throughAbort`, so the `finally` runs
     // on every ending — normal exhaustion, handler throw, peer abort, local
     // teardown. `serveDuplexOverPort` reports no completion of its own.
-    const tracked: Duplex = (input) =>
-      (async function* () {
-        try {
-          yield* handler(input);
-        } finally {
-          finished = true;
-          if (off) live.delete(off);
-        }
-      })();
+    const tracked: Duplex = (input) => {
+      const output = handler(input);
+      // `return()` on this wrapper is queued behind its pending `next()`, as on
+      // any async generator, so the abandonment would reach the handler only
+      // once it answers. Forwarded at once, a handler still waiting (an HTTP
+      // long poll) learns now that its caller left.
+      return returningAtOnce(
+        (async function* () {
+          try {
+            yield* output;
+          } finally {
+            finished = true;
+            if (off) live.delete(off);
+          }
+        })(),
+        () => void output.return(undefined).catch(() => {}),
+      );
+    };
     off = serveDuplexOverPort(port, tracked, streamOptions);
     // `serveDuplexOverPort` invokes the handler synchronously. The generator
     // body above is lazy, so today it cannot have finished by the time `off`
@@ -195,6 +204,18 @@ export interface OverPipeOptions {
    * transport's real ceiling — see `PortMuxOptions.maxMessageSize`.
    */
   maxMessageSize?: number;
+  /** The pipe's life: aborting it closes the mux. See `PortMuxOptions.signal`. */
+  signal?: AbortSignal;
+  /** Experimental per-port flow control in bytes — see `PortMuxOptions.window`. */
+  window?: number;
+  /** Fair framing in bytes — see `PortMuxOptions.frameSize`. */
+  frameSize?: number;
+  /** Ceiling on a message reassembled from frames — see `PortMuxOptions.maxReassembledBytes`. */
+  maxReassembledBytes?: number;
+  /** Liveness of the peer by ping/pong — see `PortMuxOptions.keepalive`. */
+  keepalive?: { intervalMs: number; misses?: number };
+  /** Development aid: report ports dropped without `close()` — see `PortMuxOptions.onLeak`. */
+  onLeak?: PortMuxOptions["onLeak"];
 }
 
 /**

package/src/duplex-over-port.ts

@@ -481,6 +481,12 @@ async function sendChunks(
 ): Promise<void> {
   const framed = maxMessageSize ? toChunks(maxMessageSize)(output) : output;
   const stream = throughAbort(framed, signal);
+  // `throughAbort` returns `framed`; when chunking wraps the output, that
+  // `return()` is queued behind the chunker's pending `next()`, so the abort
+  // would reach the producer only once it yields. Return the producer itself.
+  const producer = output as Partial<AsyncIterator<Uint8Array>>;
+  const returnProducer = () => void Promise.resolve(producer.return?.()).catch(() => {});
+  if (framed !== output) signal.addEventListener("abort", returnProducer, { once: true });
   try {
     await sendIterator<Uint8Array>(async ({ done, value, error }) => {
       if (signal.aborted) return;
@@ -502,5 +508,7 @@ async function sendChunks(
     // anything else is a genuine transport failure worth surfacing.
     if (signal.aborted) return;
     throw err;
+  } finally {
+    signal.removeEventListener("abort", returnProducer);
   }
 }

package/src/index.ts

@@ -21,8 +21,21 @@ export * from "./io-send.js";
 export * from "./listen-bidi.js";
 export * from "./listen-port.js";
 export * from "./message-target.js";
-export { DEFAULT_MAX_PORTS, MUX_CLOSED_MESSAGE, multiplexPort } from "./multiplex-port.js";
-export type { PortCodec, PortEnvelope, PortMux, PortMuxOptions } from "./port-types.js";
+export {
+  DEFAULT_MAX_PORTS,
+  DEFAULT_MAX_REASSEMBLED_BYTES,
+  MUX_CLOSED_MESSAGE,
+  multiplexPort,
+} from "./multiplex-port.js";
+export { type PortSendState, portBufferedAmount, whenPortReady } from "./port-credit.js";
+export type {
+  OpenPortOptions,
+  PortCodec,
+  PortEnvelope,
+  PortInfo,
+  PortMux,
+  PortMuxOptions,
+} from "./port-types.js";
 export * from "./recieve.js";
 export * from "./send.js";
 export { structuredCodec } from "./structured-codec.js";

package/src/listen-port.ts

@@ -42,6 +42,13 @@ export function listenPort<TParams = unknown, TResult = unknown>(
     }
     port.postMessage({ callId, channelName, type, result, error });
   };
-  port.addEventListener("message", onMessage);
-  return () => port.removeEventListener("message", onMessage);
+  // A request counts as consumed (for a port's window) once it is handed to its
+  // handler, not when the handler finishes: a handler that waits for a later
+  // call on the same port (long polls, subscriptions) must not hold the window
+  // that later call needs.
+  const listener = (event: MessageEvent): void => {
+    void onMessage(event);
+  };
+  port.addEventListener("message", listener);
+  return () => port.removeEventListener("message", listener);
 }

package/src/message-target.ts

@@ -10,9 +10,22 @@ export interface MessageSource {
 /** An object we can post messages to (with optional transferable list). */
 export interface MessageSink {
   postMessage(message: unknown, transfer?: Transferable[]): void;
+  /**
+   * Optional: bytes posted and not yet written out, as a WebSocket's or an
+   * `RTCDataChannel`'s `bufferedAmount`. Informational.
+   */
+  readonly bufferedAmount?: number;
+  /**
+   * Optional: resolves once the pipe can take more, at once when it can now.
+   * A multiplexer with `frameSize` waits on it between frames, which is what
+   * lets frames of different ports take turns instead of piling up in the
+   * pipe's own buffer.
+   */
+  whenDrained?(): Promise<void>;
 }
 
 /** Full-duplex message target: both sends and receives. */
 export interface MessageTarget extends MessageSource, MessageSink {
-  close?(): void | Promise<void>;
+  /** `reason`, where the target keeps one, becomes its close signal's reason. */
+  close?(reason?: unknown): void | Promise<void>;
 }