@statewalker/webrun-rpc 0.5.0 → 0.7.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,20 @@ 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;
+/**
+ * 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;;;;;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,CAqnBnC"}

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,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/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/return-at-once.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `gen`, except that `return()` and `throw()` take effect at once.
+ *
+ * On an async generator both are queued behind a `next()` that is still
+ * pending: a consumer that gives up on a stream while it waits for the peer's
+ * next chunk — an aborted fetch whose response head has not come, say — cannot
+ * end it until that chunk arrives, which for a peer that never answers is
+ * never. The stream's `finally` (which closes its port and tells the peer)
+ * then never runs, and on a multiplexer the port is kept for good.
+ *
+ * So `abandon` runs first, synchronously: it must make the pending `next()`
+ * settle (abort the stream), which then resolves done, after which the
+ * generator's own `return()` / `throw()` proceeds as usual. On a generator
+ * suspended at a `yield` it is the same ending, a step earlier. `abandon` runs once, whichever comes first.
+ */
+export declare function returningAtOnce<T>(gen: AsyncGenerator<T>, abandon: (reason?: unknown) => void): AsyncGenerator<T>;
+//# sourceMappingURL=return-at-once.d.ts.map

package/dist/return-at-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-at-once.d.ts","sourceRoot":"","sources":["../src/return-at-once.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC,EACtB,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,GAClC,cAAc,CAAC,CAAC,CAAC,CA8BnB"}

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.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Ports and RPC over them: a port multiplexer, and typed request/response and streaming primitives over any MessageTarget.",
@@ -30,7 +30,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "^0.2.2"
+    "@statewalker/webrun-streams": "^0.2.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
@@ -39,7 +39,7 @@
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3",
-    "@statewalker/webrun-streams-conformance": "^0.3.2"
+    "@statewalker/webrun-streams-conformance": "^0.3.3"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/async-dispose.ts

@@ -0,0 +1,22 @@
+/**
+ * Makes `target` disposable with `await using`: installs `dispose` as its
+ * `[Symbol.asyncDispose]`, where the runtime defines the symbol. Hand-written
+ * iterators lose what a native generator gets from `AsyncIteratorPrototype`;
+ * this gives it back. A no-op where the symbol is missing. Kept off the
+ * declared types, which would require consumers to compile with the
+ * `esnext.disposable` lib.
+ */
+export function asyncDisposable<T extends object>(target: T, dispose: () => Promise<unknown>): T {
+  // Read here, not at module level: a top-level read is code a bundler keeps.
+  const asyncDispose = (Symbol as { asyncDispose?: symbol }).asyncDispose;
+  if (asyncDispose && !(asyncDispose in target)) {
+    Object.defineProperty(target, asyncDispose, {
+      value: async () => {
+        await dispose();
+      },
+      configurable: true,
+      writable: true,
+    });
+  }
+  return target;
+}

package/src/close-signal.ts

@@ -22,7 +22,7 @@
  */
 import type { MessageTarget } from "./message-target.js";
 
-const closeSignals = new WeakMap<MessageTarget, AbortSignal>();
+const closeSignals = /* @__PURE__ */ new WeakMap<MessageTarget, AbortSignal>();
 
 /**
  * Internal: register a port's close signal. Called once by `bindBytesToPort`.

package/src/connect-serve.ts

@@ -6,7 +6,8 @@ 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";
 
 /**
  * Announced with every port this pair opens. Layer 1 never reads `meta` — it is
@@ -74,19 +75,34 @@ export const connect: Connect<PortParams> = async ({ mux: factory, timeout }) =>
   const mux = await factory();
   const streamOptions: DuplexOverPortOptions = { maxMessageSize: mux.maxMessageSize, timeout };
 
-  const call: Duplex = (input) =>
+  const call: Duplex = (input) => {
+    let stream: AsyncGenerator<Uint8Array> | undefined;
+    let abandoned = false;
     // The port is opened on the consumer's first pull, not when `call` is
     // invoked. A caller that builds a stream and then drops it without
     // iterating therefore costs the peer nothing — under eager opening it
     // would burn a port (and over libp2p, a whole stream) for a call that
     // never arrives.
-    (async function* () {
+    const outer = (async function* () {
       const port = await mux.openPort(STREAM_META);
+      if (abandoned) {
+        // Given up while the port was being opened.
+        await port.close?.();
+        return;
+      }
+      stream = duplexOverPort(port, streamOptions)(input);
       // `yield*` and not a hand-rolled pump: delegation already forwards
       // `return()` and `throw()` into `duplexOverPort`'s generator, which is
       // exactly the cancellation path `Duplex` specifies.
-      yield* duplexOverPort(port, streamOptions)(input);
+      yield* stream;
     })();
+    // Delegation forwards them only once the pending `next()` settles, though:
+    // giving up while the peer has not answered must reach the stream now.
+    return returningAtOnce(outer, () => {
+      abandoned = true;
+      void stream?.return(undefined).catch(() => {});
+    });
+  };
 
   return {
     call,
@@ -179,6 +195,16 @@ 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;
+  /** 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

@@ -12,6 +12,7 @@ import { callPort, NO_TIMEOUT } from "./call-port.js";
 import { getPortCloseSignal } from "./close-signal.js";
 import { listenPort } from "./listen-port.js";
 import type { MessageTarget } from "./message-target.js";
+import { returningAtOnce } from "./return-at-once.js";
 import { throughAbort } from "./through-abort.js";
 
 /**
@@ -177,7 +178,7 @@ function runCallerSide(
     // the consumer's contract is the inbound half.
   });
 
-  return (async function* () {
+  const stream = (async function* () {
     try {
       yield* inbound.stream;
     } finally {
@@ -200,6 +201,13 @@ function runCallerSide(
       }
     }
   })();
+  // A caller that gives up while it waits for the peer's next chunk ends the
+  // stream now: the abort settles that wait, and the `finally` above runs.
+  return returningAtOnce(stream, () => {
+    if (!controller.signal.aborted) {
+      controller.abort(new Error("webrun-rpc: the caller abandoned the stream"));
+    }
+  });
 }
 
 /**

package/src/index.ts

@@ -22,7 +22,15 @@ 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 { 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>;
 }