@statewalker/webrun-rpc 0.4.0

package/dist/close-signal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-port AbortSignal that fires when the underlying transport adapter
+ * (libp2p stream, LiveKit participant, WebSocket, …) detects closure.
+ *
+ * Native `MessagePort` does NOT surface close events to either entangled
+ * half — neither a `close` event, nor a `messageerror`, nor any signal at
+ * all. Closing one half just silently stops message delivery on the other.
+ * A WHATWG proposal exists (https://github.com/whatwg/html/issues/1766) but
+ * no browser ships it.
+ *
+ * This module is the work-around: `bindBytesToPort` creates an
+ * `AbortController` per port and aborts it when `transport.onClose` fires.
+ * Consumers (`callPort`, `recieve`, `send`, application code) look up the
+ * signal via `getPortCloseSignal(port)` and combine it into their own
+ * abort plumbing — typically with `AbortSignal.any([userSignal, closeSignal])`
+ * — so pending awaits reject cleanly instead of hanging until a per-call
+ * timeout fires.
+ *
+ * Ports created via raw `new MessageChannel()` (i.e., without going through
+ * `bindBytesToPort`) return `undefined` from `getPortCloseSignal` — there's
+ * no underlying transport so there's nothing to track.
+ */
+import type { MessageTarget } from "./message-target.js";
+/**
+ * Internal: register a port's close signal. Called once by `bindBytesToPort`.
+ *
+ * @internal
+ */
+export declare function setPortCloseSignal(port: MessageTarget, signal: AbortSignal): void;
+/**
+ * Return the AbortSignal that fires when `port`'s transport closes, or
+ * `undefined` if `port` is not transport-backed (e.g., a raw
+ * `MessageChannel().port1`).
+ */
+export declare function getPortCloseSignal(port: MessageTarget): AbortSignal | undefined;
+//# sourceMappingURL=close-signal.d.ts.map

package/dist/close-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-signal.d.ts","sourceRoot":"","sources":["../src/close-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,WAAW,GAAG,SAAS,CAE/E"}

package/dist/connect-serve.d.ts

@@ -0,0 +1,104 @@
+import type { Connect, Serve } from "@statewalker/webrun-streams";
+import type { MessageTarget } from "./message-target.js";
+import type { PortCodec, PortMux } from "./port-types.js";
+/** What a mux calls when the peer opens a port. `false` rejects it. */
+export type OnPort = (port: MessageTarget, meta?: unknown) => boolean | undefined;
+/**
+ * A source of ports, built around the handler that will answer them.
+ *
+ * WHY A FACTORY AND NOT A `PortMux`. Every mux decides accept-or-reject
+ * **synchronously**, inside the `open` envelope, and tells the peer on the
+ * spot — `multiplexPort` posts `{type:"close", reason:"rejected"}` before
+ * returning. There is no "decide later", and layer 1 refuses to queue what it
+ * cannot deliver ("Drop, never queue").
+ *
+ * So a mux handed over already built has a window between its construction and
+ * its handler being attached, and a port arriving in that window is rejected
+ * outright — measured: zero messages delivered, and the peer told `rejected`
+ * for a call that was merely early. A factory closes the window by
+ * construction: the mux cannot exist before the thing that answers it.
+ *
+ * `connect` passes no handler, which is how a caller declines inbound ports.
+ * The same factory therefore serves both sides, and whichever of them called
+ * it owns the mux and closes it.
+ */
+export type PortMuxFactory = (onPort?: OnPort) => PortMux | Promise<PortMux>;
+export interface PortParams {
+    /**
+     * Where ports come from. See {@link PortMuxFactory}, and `overPipe` /
+     * `overPorts` for the two this package ships.
+     *
+     * This used to be a `MessageTarget` plus `side` and a credit window, which
+     * forced one strategy — an id table — on every transport. A libp2p
+     * connection multiplexes already, so that stacked two multiplexers with no
+     * way to tell which one stalled; a transferable boundary moves real ports
+     * and needs no table at all. The strategy belongs to whoever knows the
+     * transport, which is never this file.
+     */
+    mux: PortMuxFactory;
+    /** Per-stream inactivity timeout in ms, reset by any chunk in either direction.
+     *
+     * Unset — the default — means no timeout at all: a slow consumer is
+     * throttled, never failed. Set it on the side that must not hang. */
+    timeout?: number;
+}
+/**
+ * One port source in, one caller `Duplex` out.
+ *
+ * A call is a port: the mux allocates one, `duplexOverPort` runs the single
+ * invocation on it, and closing the stream closes the port. No stream ids, no
+ * framing and no credit accounting live here — the mux owns the first, and
+ * `duplexOverPort` owns the one-chunk window that makes memory bounded.
+ */
+export declare const connect: Connect<PortParams>;
+/**
+ * One port source in, `handler` serving every call that arrives on it.
+ *
+ * Each inbound port is one invocation, so the factory's `onPort` is the accept
+ * loop: it installs `handler` on the new port and nothing else. The returned
+ * teardown abandons the streams still running *before* dropping the mux, so
+ * the peer's callers reject with "the peer abandoned the stream" instead of
+ * parking forever on a port that has silently gone inert — layer 1's close is
+ * not observable to layer 2, which is why the notice has to be posted
+ * deliberately.
+ */
+export declare const serve: Serve<PortParams>;
+export interface OverPipeOptions {
+    /** How envelopes are placed on the pipe. `structuredCodec` for a `MessagePort`. */
+    codec: PortCodec;
+    /**
+     * Id parity. The initiator allocates even ids, the responder odd, so both
+     * ends may open concurrently with no negotiation. The two ends of one pair
+     * must disagree, or their ids collide.
+     */
+    side?: "initiator" | "responder";
+    /** Ceiling on concurrently open ports. Bounds the id table only. */
+    maxPorts?: number;
+    /**
+     * Largest payload one message may carry, if the pipe imposes a limit.
+     * Bodies are split to fit. Leave at least 256 bytes of margin below the
+     * transport's real ceiling — see `PortMuxOptions.maxMessageSize`.
+     */
+    maxMessageSize?: number;
+}
+/**
+ * Ports over ONE PIPE OF BYTES — a `MessagePort`, a worker, a WebSocket.
+ *
+ * There is no second port to be had, so `multiplexPort`'s id table invents
+ * them. Use this when the transport gives you exactly one channel.
+ */
+export declare function overPipe(pipe: MessageTarget, options: OverPipeOptions): PortMuxFactory;
+/**
+ * Ports from a source that already has them — a transferable boundary, or a
+ * transport that multiplexes on its own (libp2p's yamux, say).
+ *
+ * A pass-through, so an adapter that builds its own `PortMux` plugs in without
+ * this package learning what that transport is. It exists to make the
+ * three-way choice legible at the call site rather than to do work:
+ *
+ * ```ts
+ * await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, onPort })) }, handler);
+ * ```
+ */
+export declare function overPorts(factory: PortMuxFactory): PortMuxFactory;
+//# sourceMappingURL=connect-serve.d.ts.map

package/dist/connect-serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAM1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAU1D,uEAAuE;AACvE,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;OAUG;IACH,GAAG,EAAE,cAAc,CAAC;IACpB;;;yEAGqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,UAAU,CA0BvC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,UAAU,CAqDnC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAEtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAEjE"}

package/dist/duplex-over-port.d.ts

@@ -0,0 +1,49 @@
+import { type Duplex } from "@statewalker/webrun-streams";
+import type { MessageTarget } from "./message-target.js";
+/**
+ * The `type` of the out-of-band notice a side posts when it abandons a stream.
+ *
+ * Layer 1's `close` is not observable to layer 2 — a closed virtual port drops
+ * its listeners silently and is indistinguishable from a working port nobody
+ * is answering — so the peer would otherwise wait forever. Exported because
+ * tests and adapters assert on it.
+ */
+export declare const STREAM_ABORT = "webrun-rpc:stream-abort";
+export interface DuplexOverPortOptions {
+    /**
+     * Largest payload one chunk may carry, from `PortMux.maxMessageSize` (spec
+     * D10). Bodies are split to fit with `toChunks`. Unset means no limit and no
+     * splitting.
+     */
+    maxMessageSize?: number;
+    /**
+     * Inactivity timeout for the whole stream, in ms: the clock is reset by any
+     * chunk in either direction, and elapsing aborts the stream. Unset — the
+     * default — means no timeout at all (spec D8): a slow consumer is throttled,
+     * never failed. Any finite default would reintroduce F5 at a different
+     * threshold.
+     */
+    timeout?: number;
+    /** Logging function; defaults to a no-op. */
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * One port in, one `Duplex` out (spec D9).
+ *
+ * The returned `Duplex` runs a single stream on `port`: the caller's `input`
+ * is sent chunk by chunk with `callPort`, and the handler's output arrives the
+ * same way on the other channel. Within each direction the next chunk is never
+ * sent until the previous one has been delivered *and* pulled past by the
+ * consumer (spec D11) — the reply to a chunk call *is* the confirmation, and
+ * `listenPort` withholds it until then.
+ *
+ * A stream port carries exactly one invocation. To make several calls, open
+ * several ports: `mux.openPort({ kind: "stream" })` per call.
+ */
+export declare function duplexOverPort(port: MessageTarget, options?: DuplexOverPortOptions): Duplex;
+/**
+ * Installs `handler` as the serving side of one stream on `port`. Returns an
+ * idempotent teardown that abandons the stream and notifies the peer.
+ */
+export declare function serveDuplexOverPort(port: MessageTarget, handler: Duplex, options?: DuplexOverPortOptions): () => void;
+//# sourceMappingURL=duplex-over-port.d.ts.map

package/dist/duplex-over-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplex-over-port.d.ts","sourceRoot":"","sources":["../src/duplex-over-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,MAAM,EAOZ,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AActD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAE/F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,qBAA0B,GAClC,MAAM,IAAI,CA6BZ"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { byteChannelFromMessagePort } from "./byte-channel.js";
+export * from "./call-bidi.js";
+export * from "./call-port.js";
+export * from "./cancel-channel.js";
+export { getPortCloseSignal, setPortCloseSignal } from "./close-signal.js";
+export { connect, type OnPort, type OverPipeOptions, overPipe, overPorts, type PortMuxFactory, type PortParams, serve, } from "./connect-serve.js";
+export * from "./duplex-over-port.js";
+export * from "./io-handle.js";
+export * from "./io-send.js";
+export * from "./listen-bidi.js";
+export * from "./listen-port.js";
+export * from "./message-target.js";
+export { DEFAULT_MAX_PORTS, multiplexPort } from "./multiplex-port.js";
+export type { PortCodec, PortEnvelope, PortMux, PortMuxOptions } from "./port-types.js";
+export * from "./recieve.js";
+export * from "./send.js";
+export { structuredCodec } from "./structured-codec.js";
+export * from "./transfer-port-mux.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,OAAO,EACP,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,QAAQ,EACR,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,GACN,MAAM,oBAAoB,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxF,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,cAAc,wBAAwB,CAAC"}