@statewalker/webrun-rpc 0.4.0

package/dist/index.js

@@ -0,0 +1,1180 @@
+import { deserializeError, recieveIterator, sendIterator, serializeError, toChunks } from "@statewalker/webrun-streams";
+//#region src/byte-channel.ts
+/**
+* Wrap any `MessageTarget` — a real `MessagePort`, a worker, or a virtual
+* port over some other transport — as a `ByteChannel`. Outbound bytes are emitted via
+* `port.postMessage(uint8Array)` (the structured-clone path); inbound bytes
+* are taken from `message` events whose `data` is a `Uint8Array` (or
+* coerceable byte-like value).
+*
+* The port must already be started (`port.start()` if manually constructed).
+* This adapter assumes the port carries only byte payloads — non-byte messages
+* are ignored.
+*/
+function byteChannelFromMessagePort(port) {
+	let closedResolve;
+	const closed = new Promise((r) => {
+		closedResolve = r;
+	});
+	let isClosed = false;
+	const queue = [];
+	let pending = null;
+	const deliver = (bytes) => {
+		if (isClosed) return;
+		if (pending) {
+			const r = pending;
+			pending = null;
+			r({
+				value: bytes,
+				done: false
+			});
+		} else queue.push(bytes);
+	};
+	const onMessage = (ev) => {
+		const data = ev.data;
+		if (data instanceof Uint8Array) {
+			deliver(new Uint8Array(data));
+			return;
+		}
+		if (data instanceof ArrayBuffer) {
+			deliver(new Uint8Array(data));
+			return;
+		}
+		if (ArrayBuffer.isView(data)) {
+			const view = data;
+			deliver(new Uint8Array(view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength)));
+		}
+	};
+	port.addEventListener("message", onMessage);
+	port.start?.();
+	return {
+		send(bytes) {
+			if (isClosed) return;
+			try {
+				port.postMessage(bytes);
+			} catch {}
+		},
+		recv: { [Symbol.asyncIterator]() {
+			return { next() {
+				if (queue.length > 0) return Promise.resolve({
+					value: queue.shift(),
+					done: false
+				});
+				if (isClosed) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				return new Promise((resolve) => {
+					pending = resolve;
+				});
+			} };
+		} },
+		closed,
+		close() {
+			if (isClosed) return;
+			isClosed = true;
+			port.removeEventListener("message", onMessage);
+			try {
+				port.close?.();
+			} catch {}
+			if (pending) {
+				const r = pending;
+				pending = null;
+				r({
+					value: void 0,
+					done: true
+				});
+			}
+			closedResolve();
+		}
+	};
+}
+//#endregion
+//#region src/close-signal.ts
+const closeSignals = /* @__PURE__ */ new WeakMap();
+/**
+* Internal: register a port's close signal. Called once by `bindBytesToPort`.
+*
+* @internal
+*/
+function setPortCloseSignal(port, signal) {
+	closeSignals.set(port, signal);
+}
+/**
+* Return the AbortSignal that fires when `port`'s transport closes, or
+* `undefined` if `port` is not transport-backed (e.g., a raw
+* `MessageChannel().port1`).
+*/
+function getPortCloseSignal(port) {
+	return closeSignals.get(port);
+}
+//#endregion
+//#region src/call-port.ts
+/**
+* Pass as `timeout` to install no deadline at all. Used by the stream tier,
+* where the deadline belongs to the stream rather than to one chunk (spec D8):
+* a slow consumer is throttled, never failed.
+*/
+const NO_TIMEOUT = Number.POSITIVE_INFINITY;
+/**
+* Asynchronous request/response over any `MessageTarget`.
+*
+* Sends `params` to the peer listening with `listenPort`, waits up to
+* `timeout` ms for a matching reply, and either resolves with the result or
+* rejects with the deserialised error.
+*/
+function callPort(port, params, { timeout = 1e3, channelName = "", log = () => {}, newCallId = () => `call-${Date.now()}-${String(Math.random()).substring(2)}`, signal } = {}) {
+	const callId = newCallId();
+	log("[callPort]", {
+		channelName,
+		callId,
+		params
+	});
+	const combinedSignal = combineSignals(signal, getPortCloseSignal(port));
+	let timerId;
+	let onMessage;
+	let onAbort;
+	const promise = new Promise((resolve, reject) => {
+		if (combinedSignal?.aborted) {
+			reject(abortReason(combinedSignal));
+			return;
+		}
+		if (Number.isFinite(timeout) && timeout > 0) timerId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Call timeout. CallId: "${callId}".`)), timeout);
+		onMessage = (event) => {
+			const data = event.data;
+			if (!data) return;
+			if (data.channelName !== channelName) return;
+			if (data.callId !== callId) return;
+			if (data.type === "response:error") reject(deserializeError(data.error));
+			else if (data.type === "response:result") resolve(data.result);
+		};
+		port.addEventListener("message", onMessage);
+		if (combinedSignal) {
+			onAbort = () => reject(abortReason(combinedSignal));
+			combinedSignal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+	promise.catch(() => {}).finally(() => {
+		if (timerId !== void 0) clearTimeout(timerId);
+		if (onMessage) port.removeEventListener("message", onMessage);
+		if (onAbort && combinedSignal) combinedSignal.removeEventListener("abort", onAbort);
+	});
+	port.postMessage({
+		type: "request",
+		channelName,
+		callId,
+		params
+	});
+	return promise;
+}
+function abortReason(signal) {
+	const reason = signal.reason;
+	if (reason instanceof Error) return reason;
+	const err = new Error(reason === void 0 ? "Aborted" : String(reason));
+	err.name = "AbortError";
+	return err;
+}
+function combineSignals(...signals) {
+	const live = signals.filter((s) => s !== void 0);
+	if (live.length === 0) return void 0;
+	if (live.length === 1) return live[0];
+	return AbortSignal.any(live);
+}
+//#endregion
+//#region src/cancel-channel.ts
+const CANCEL_CHANNEL_TYPE = "cancel-channel";
+function postCancelChannel(port, channelName) {
+	if (!channelName) return;
+	try {
+		port.postMessage({
+			type: CANCEL_CHANNEL_TYPE,
+			channelName
+		});
+	} catch {}
+}
+function listenCancelChannel(port, channelName, onCancel) {
+	const handler = (event) => {
+		const data = event.data;
+		if (!data || data.type !== "cancel-channel") return;
+		if (data.channelName !== channelName) return;
+		onCancel();
+	};
+	port.addEventListener("message", handler);
+	return () => port.removeEventListener("message", handler);
+}
+//#endregion
+//#region src/listen-port.ts
+/**
+* Installs `handler` as the server side of a `callPort` / `listenPort`
+* request/response pair on `port`.
+*
+* Returns a cleanup function that removes the listener.
+*/
+function listenPort(port, handler, { channelName = "", log = () => {} } = {}) {
+	const onMessage = async (event) => {
+		const data = event.data;
+		if (!data || data.channelName !== channelName || data.type !== "request") return;
+		const { callId, params } = data;
+		log("[listenPort]", {
+			channelName,
+			callId,
+			params
+		});
+		let result;
+		let error;
+		let type;
+		try {
+			result = await handler(params);
+			type = "response:result";
+		} catch (e) {
+			error = serializeError(e);
+			type = "response:error";
+		}
+		port.postMessage({
+			callId,
+			channelName,
+			type,
+			result,
+			error
+		});
+	};
+	port.addEventListener("message", onMessage);
+	return () => port.removeEventListener("message", onMessage);
+}
+//#endregion
+//#region src/recieve.ts
+/**
+* Async generator over async generators. Each outer yield is one inbound
+* stream reconstructed from chunk-envelopes delivered by the peer's
+* {@link send}.
+*
+* The outer generator itself never ends: break out of the outer loop when
+* you've handled the streams you care about.
+*
+* When the outer for-await is interrupted (`break`, `return`, throw), the
+* `finally` here both removes the underlying `listenPort` and closes the
+* most recently yielded `recieveIterator`. The latter is required because
+* a `listenPort` handler invocation that's already in flight (awaiting
+* `deliver(chunk)`) would otherwise hang forever — `iterator.return()`
+* triggers `drainQueue` which resolves all pending producer Promises.
+*
+* If `options.signal` is provided and fires while the consumer is awaiting
+* a chunk, the active `recieveIterator` is force-delivered an end-of-stream
+* marker so the consumer wakes up immediately rather than waiting for the
+* next inbound chunk (or `callPort` timeout).
+*/
+async function* recieve(port, options = {}) {
+	const { signal, ...listenOptions } = options;
+	let onMessage;
+	let currentIter;
+	let forceClose;
+	const close = listenPort(port, async ({ done, value, error }) => {
+		await onMessage?.({
+			done,
+			value,
+			error
+		});
+	}, listenOptions);
+	const onAbort = () => {
+		forceClose?.();
+	};
+	if (signal) {
+		if (signal.aborted) {
+			close();
+			return;
+		}
+		signal.addEventListener("abort", onAbort);
+	}
+	try {
+		while (true) {
+			currentIter = recieveIterator((deliver) => {
+				onMessage = deliver;
+				forceClose = () => {
+					deliver({ done: true });
+				};
+			});
+			yield currentIter;
+		}
+	} finally {
+		close();
+		signal?.removeEventListener("abort", onAbort);
+		onMessage = void 0;
+		forceClose = void 0;
+		if (currentIter) try {
+			await currentIter.return?.(void 0);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/through-abort.ts
+/**
+* Wraps an async iterable so that an `AbortSignal` firing causes the wrapper
+* to return cleanly, forwarding `return()` to the underlying iterator so the
+* producer (e.g., a user-supplied generator) sees its own `finally` blocks
+* run immediately rather than waiting for the next yield.
+*/
+async function* throughAbort(input, signal) {
+	const iter = input[Symbol.asyncIterator] ? input[Symbol.asyncIterator]() : input[Symbol.iterator]();
+	const onAbort = () => {
+		iter.return?.(void 0);
+	};
+	if (signal.aborted) {
+		iter.return?.(void 0);
+		return;
+	}
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		while (true) {
+			const r = await iter.next();
+			if (r.done) return;
+			if (signal.aborted) return;
+			yield r.value;
+		}
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+//#region src/send.ts
+/**
+* Send every value produced by `output` to `port`, one `callPort` round-trip
+* per chunk. Resolves once the peer has acknowledged the final `{ done: true }`
+* envelope, or once `options.signal` aborts (whichever comes first).
+*/
+async function send(port, output, options = {}) {
+	const { signal, ...callOptions } = options;
+	if (!signal) {
+		await sendIterator(async ({ done, value, error }) => {
+			await callPort(port, {
+				done,
+				value,
+				error
+			}, callOptions);
+		}, output);
+		return;
+	}
+	const stream = throughAbort(output, signal);
+	let abortedBeforeDone = false;
+	try {
+		await sendIterator(async ({ done, value, error }) => {
+			if (signal.aborted) {
+				abortedBeforeDone = true;
+				return;
+			}
+			await callPort(port, {
+				done,
+				value,
+				error
+			}, {
+				...callOptions,
+				signal
+			});
+		}, stream);
+	} catch (err) {
+		if (signal.aborted || abortedBeforeDone) return;
+		throw err;
+	}
+}
+//#endregion
+//#region src/io-send.ts
+/**
+* Client half of a full-duplex exchange over any `MessageTarget`.
+*
+* Concurrently reads one inbound stream from the peer and writes `output`
+* to it. Yields each value received from the peer. Completes once both
+* directions finish. Pairs with {@link ioHandle}.
+*
+* If the consumer breaks out of the `for await` (via `iter.return()` or
+* loop `break`), `ioSend` posts a `cancel-channel` message on the same
+* sub-channel so the peer can abort its `send` immediately rather than
+* waiting for `callPort` timeouts to fire.
+*/
+async function* ioSend(port, output, options = {}) {
+	const { cancelSignal, ...recieveOptions } = options;
+	const channelName = recieveOptions.channelName ?? "";
+	let inputEndedNormally = false;
+	const sendAbort = new AbortController();
+	if (cancelSignal) {
+		if (cancelSignal.aborted) sendAbort.abort();
+		else cancelSignal.addEventListener("abort", () => sendAbort.abort(), { once: true });
+	}
+	const recieveOpts = {
+		...recieveOptions,
+		signal: cancelSignal
+	};
+	for await (const input of recieve(port, recieveOpts)) {
+		const sendPromise = send(port, output, {
+			...recieveOptions,
+			signal: sendAbort.signal
+		});
+		try {
+			yield* input;
+			inputEndedNormally = true;
+		} finally {
+			if (!inputEndedNormally) {
+				postCancelChannel(port, channelName);
+				sendAbort.abort();
+			}
+			try {
+				await sendPromise;
+			} catch {}
+		}
+		break;
+	}
+}
+//#endregion
+//#region src/call-bidi.ts
+/**
+* Initiates a full-duplex stream call: ships `input` values to the peer and
+* yields the values returned by `listenBidi`'s handler.
+*
+* Internally allocates a fresh sub-channel name, announces it to the peer
+* via `callPort`, and then runs {@link ioSend} on that sub-channel.
+*
+* If the outer `callPort` rejects (e.g., the peer's handler threw and
+* `listenPort` surfaced the error as `response:error`), the inner `ioSend`'s
+* recieveIterator is force-closed via an internal cancel signal so the
+* consumer doesn't hang waiting for chunks that will never come. The outer
+* error is then re-thrown to the caller.
+*/
+async function* callBidi(port, input, { options = {}, ...params } = {}) {
+	const channelName = `${+String(Math.random()).substring(2)}`;
+	const { bidiTimeout = 2147483647 } = options;
+	const promise = callPort(port, {
+		...params,
+		channelName
+	}, {
+		...options,
+		timeout: bidiTimeout
+	});
+	const cancelInner = new AbortController();
+	const sendIter = ioSend(port, input, {
+		...options,
+		channelName,
+		cancelSignal: cancelInner.signal
+	});
+	let outerError;
+	promise.catch((err) => {
+		outerError = err;
+		cancelInner.abort();
+	});
+	try {
+		yield* sendIter;
+	} finally {
+		try {
+			await promise;
+		} catch {}
+	}
+	if (outerError !== void 0) throw outerError;
+}
+//#endregion
+//#region src/duplex-over-port.ts
+/**
+* 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.
+*/
+const STREAM_ABORT = "webrun-rpc:stream-abort";
+/** Caller's input travels on this channel; the handler listens on it. */
+const CHANNEL_IN = "in";
+/** The handler's output travels on this channel; the caller listens on it. */
+const CHANNEL_OUT = "out";
+/**
+* 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.
+*/
+function duplexOverPort(port, options = {}) {
+	return (input) => runCallerSide(port, input, options);
+}
+/**
+* Installs `handler` as the serving side of one stream on `port`. Returns an
+* idempotent teardown that abandons the stream and notifies the peer.
+*/
+function serveDuplexOverPort(port, handler, options = {}) {
+	const controller = new AbortController();
+	const notice = installAbortNotice(port, controller);
+	const clock = installStreamTimeout(controller, options.timeout);
+	const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch);
+	let output;
+	try {
+		output = handler(inbound.stream);
+	} catch (err) {
+		const pump = sendChunks(port, CHANNEL_OUT, failing(err), options, controller.signal, clock.touch);
+		pump.catch(() => {});
+		disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+		return teardownOnce(controller, notice, clock, inbound, void 0);
+	}
+	const pump = sendChunks(port, CHANNEL_OUT, output, options, controller.signal, clock.touch);
+	pump.catch(() => {});
+	disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+	return teardownOnce(controller, notice, clock, inbound, output);
+}
+/**
+* A stream that completes normally has nobody left to call the returned
+* teardown — the caller only knows the stream ended, not that it must also
+* dispose the serve-side handle. Without this, the last `touch()`'s timer
+* stays armed for up to `timeout` ms after real completion, doing nothing
+* but holding the event loop open.
+*
+* Only disarms once BOTH `pump` (our output) and `inboundEnded` (the peer's
+* declared end of input, or an abort) have settled. Disarming on `pump`
+* alone is not safe: under half-close the handler can finish producing
+* output while the caller is still sending input, and a clock stopped then
+* would leave that still-open half with no deadline at all — worse than the
+* leak this fixes.
+*/
+function disarmClockWhenBothSidesSettle(clock, pump, inboundEnded) {
+	Promise.allSettled([pump, inboundEnded]).then(() => {
+		clock.stop();
+	});
+}
+async function* failing(err) {
+	throw err;
+}
+function teardownOnce(controller, notice, clock, inbound, output) {
+	let torn = false;
+	return () => {
+		if (torn) return;
+		torn = true;
+		if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: stream torn down"));
+		notice.post();
+		notice.stop();
+		clock.stop();
+		inbound.stop();
+		output?.return(void 0).catch(() => {});
+	};
+}
+function runCallerSide(port, input, options) {
+	const controller = new AbortController();
+	const notice = installAbortNotice(port, controller);
+	const clock = installStreamTimeout(controller, options.timeout);
+	const inbound = receiveChunks(port, CHANNEL_OUT, controller, clock.touch);
+	const pump = sendChunks(port, CHANNEL_IN, input, options, controller.signal, clock.touch);
+	pump.catch(() => {});
+	return (async function* () {
+		try {
+			yield* inbound.stream;
+		} finally {
+			if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the caller abandoned the stream"));
+			notice.post();
+			notice.stop();
+			clock.stop();
+			inbound.stop();
+			await pump.catch(() => {});
+			try {
+				await port.close?.();
+			} catch {}
+		}
+	})();
+}
+/**
+* Listens for the peer's abort notice, and can post our own. The notice is a
+* plain message with no `channelName` and a `type` that is not `"request"`,
+* so neither `callPort` nor `listenPort` reacts to it, and it carries no
+* numeric `id`, so `structuredCodec` never mistakes it for a layer 1 envelope.
+*/
+function installAbortNotice(port, controller) {
+	const onMessage = (event) => {
+		const data = event.data;
+		if (!data || data.type !== "webrun-rpc:stream-abort") return;
+		if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the peer abandoned the stream"));
+	};
+	port.addEventListener("message", onMessage);
+	let posted = false;
+	return {
+		post() {
+			if (posted) return;
+			posted = true;
+			try {
+				port.postMessage({ type: STREAM_ABORT });
+			} catch {}
+		},
+		stop() {
+			port.removeEventListener("message", onMessage);
+		}
+	};
+}
+/**
+* The per-stream inactivity timeout (spec D8). Reset by any chunk in either
+* direction; elapsing aborts the stream. Unset, zero or non-finite installs no
+* timer at all, which is the default: a slow consumer is throttled, not failed.
+*/
+function installStreamTimeout(controller, timeout) {
+	if (timeout === void 0 || !Number.isFinite(timeout) || timeout <= 0) return {
+		touch() {},
+		stop() {}
+	};
+	let timer;
+	let stopped = false;
+	const arm = () => {
+		timer = setTimeout(() => {
+			if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error(`webrun-rpc: stream idle for ${timeout} ms`));
+		}, timeout);
+	};
+	arm();
+	return {
+		touch() {
+			if (stopped) return;
+			if (timer !== void 0) clearTimeout(timer);
+			arm();
+		},
+		stop() {
+			stopped = true;
+			if (timer !== void 0) clearTimeout(timer);
+			timer = void 0;
+		}
+	};
+}
+/**
+* The receiving half of one direction.
+*
+* The `listenPort` listener is installed **eagerly**, not lazily inside
+* `recieveIterator`'s installer, because a handler that never drains its input
+* would otherwise leave the peer's chunk calls with nobody to answer them. If
+* the local consumer has not started iterating, an inbound chunk waits for it —
+* which is the correct backpressure, and different from having no listener.
+*/
+function receiveChunks(port, channelName, controller, touch) {
+	let deliver;
+	const waiting = [];
+	let finished = false;
+	let outstanding = false;
+	let poison;
+	let resolveEnded = () => {};
+	const ended = new Promise((resolve) => {
+		resolveEnded = resolve;
+	});
+	let aborted = false;
+	let abortReason;
+	const ready = () => deliver || finished ? Promise.resolve() : new Promise((r) => waiting.push(r));
+	const wake = () => {
+		for (const r of waiting.splice(0)) r();
+	};
+	const off = listenPort(port, async ({ done, value, error }) => {
+		touch();
+		if (poison) throw poison;
+		if (outstanding) {
+			poison = /* @__PURE__ */ new Error("webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed");
+			controller.abort(poison);
+			setTimeout(() => {
+				try {
+					port.close?.();
+				} catch {}
+			}, 0);
+			throw poison;
+		}
+		outstanding = true;
+		try {
+			await ready();
+			if (finished) throw poison ?? /* @__PURE__ */ new Error("webrun-rpc: the stream is closed");
+			await deliver?.({
+				done,
+				value,
+				error: error ? deserializeError(error) : void 0
+			});
+		} finally {
+			outstanding = false;
+		}
+		if (done) resolveEnded();
+	}, { channelName });
+	const detach = () => {
+		finished = true;
+		wake();
+		off();
+		controller.signal.removeEventListener("abort", onAbort);
+		resolveEnded();
+	};
+	const onAbort = () => {
+		aborted = true;
+		abortReason = controller.signal.reason;
+		finished = true;
+		wake();
+		deliver?.({
+			done: true,
+			error: abortReason
+		});
+		resolveEnded();
+	};
+	controller.signal.addEventListener("abort", onAbort, { once: true });
+	return {
+		stream: recieveIterator((d) => {
+			if (aborted) {
+				d({
+					done: true,
+					error: abortReason
+				});
+				return detach;
+			}
+			deliver = d;
+			wake();
+			return detach;
+		}),
+		stop: detach,
+		ended
+	};
+}
+/**
+* The sending half of one direction: one `callPort` per chunk, one call
+* outstanding at a time (spec D11/D12), with no per-chunk deadline (spec D8).
+*/
+async function sendChunks(port, channelName, output, { maxMessageSize, log }, signal, touch) {
+	const stream = throughAbort(maxMessageSize ? toChunks(maxMessageSize)(output) : output, signal);
+	try {
+		await sendIterator(async ({ done, value, error }) => {
+			if (signal.aborted) return;
+			const chunk = {
+				done,
+				value,
+				error: error === void 0 ? void 0 : serializeError(error)
+			};
+			log?.("[duplexOverPort] send", {
+				channelName,
+				done,
+				size: value?.byteLength
+			});
+			await callPort(port, chunk, {
+				channelName,
+				timeout: NO_TIMEOUT,
+				signal
+			});
+			touch();
+		}, stream);
+	} catch (err) {
+		if (signal.aborted) return;
+		throw err;
+	}
+}
+//#endregion
+//#region src/virtual-port.ts
+/**
+* One virtual port.
+*
+* `deliver` and `markClosed` are deliberately not on `port`: the consumer holds
+* only a `MessageTarget`, so it cannot forge inbound traffic or close the port
+* out from under the multiplexer's bookkeeping.
+*/
+function newVirtualPort(send, requestClose) {
+	const listeners = /* @__PURE__ */ new Set();
+	let closed = false;
+	return {
+		port: {
+			addEventListener(_type, listener) {
+				listeners.add(listener);
+			},
+			removeEventListener(_type, listener) {
+				listeners.delete(listener);
+			},
+			postMessage(message, transfer) {
+				if (closed) return;
+				send(message, transfer);
+			},
+			close() {
+				if (closed) return;
+				closed = true;
+				const notify = requestClose;
+				listeners.clear();
+				notify();
+			}
+		},
+		deliver(payload) {
+			if (closed) return;
+			const event = new MessageEvent("message", { data: payload });
+			for (const listener of [...listeners]) try {
+				listener(event);
+			} catch {}
+		},
+		markClosed() {
+			closed = true;
+			listeners.clear();
+		},
+		isClosed() {
+			return closed;
+		}
+	};
+}
+//#endregion
+//#region src/multiplex-port.ts
+/** Ceiling on concurrently open virtual ports. Bounds the id table only. */
+const DEFAULT_MAX_PORTS = 1024;
+/**
+* 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.
+*/
+function multiplexPort(port, options) {
+	const { codec, onPort, side = "initiator", maxPorts = DEFAULT_MAX_PORTS, maxMessageSize } = options;
+	const open = /* @__PURE__ */ new Map();
+	let nextId = side === "initiator" ? 0 : 1;
+	let muxClosed = false;
+	const post = (envelope, transfer) => {
+		if (muxClosed) return;
+		try {
+			codec.post(port, envelope, transfer);
+		} catch {}
+	};
+	const attach = (id) => {
+		let self;
+		self = newVirtualPort((payload, transfer) => post({
+			type: "message",
+			id,
+			payload
+		}, transfer), (reason) => {
+			post({
+				type: "close",
+				id,
+				reason
+			});
+			open.delete(id);
+			self.markClosed();
+		});
+		open.set(id, self);
+		return self;
+	};
+	const handleEnvelope = (envelope) => {
+		if (muxClosed) return;
+		if (envelope.type === "open") {
+			if (open.has(envelope.id)) return;
+			if (open.size >= maxPorts) {
+				post({
+					type: "close",
+					id: envelope.id,
+					reason: "max-ports"
+				});
+				return;
+			}
+			const handle = attach(envelope.id);
+			let accepted = false;
+			if (onPort) try {
+				accepted = onPort(handle.port, envelope.meta) !== false;
+			} catch {
+				accepted = false;
+			}
+			if (!accepted) {
+				open.delete(envelope.id);
+				handle.markClosed();
+				post({
+					type: "close",
+					id: envelope.id,
+					reason: "rejected"
+				});
+			}
+			return;
+		}
+		const handle = open.get(envelope.id);
+		if (envelope.type === "message") {
+			if (!handle) return;
+			handle.deliver(envelope.payload);
+			return;
+		}
+		if (!handle) return;
+		open.delete(envelope.id);
+		handle.markClosed();
+	};
+	const listener = (event) => {
+		const envelope = codec.read(event);
+		if (envelope) handleEnvelope(envelope);
+	};
+	port.addEventListener("message", listener);
+	port.start?.();
+	return {
+		maxMessageSize,
+		async openPort(meta) {
+			if (muxClosed) throw new Error("webrun-rpc: the multiplexer is closed");
+			if (open.size >= maxPorts) throw new RangeError(`webrun-rpc: maxPorts (${maxPorts}) reached`);
+			while (open.has(nextId)) nextId += 2;
+			const id = nextId;
+			nextId += 2;
+			const handle = attach(id);
+			post({
+				type: "open",
+				id,
+				meta
+			});
+			return handle.port;
+		},
+		async close() {
+			if (muxClosed) return;
+			for (const [id, handle] of [...open]) {
+				post({
+					type: "close",
+					id
+				});
+				open.delete(id);
+				handle.markClosed();
+			}
+			muxClosed = true;
+			port.removeEventListener("message", listener);
+			await port.close?.();
+		}
+	};
+}
+//#endregion
+//#region src/connect-serve.ts
+/**
+* Announced with every port this pair opens. Layer 1 never reads `meta` — it is
+* here so a peer running something else over the same multiplexer can tell a
+* stream port from whatever else it hands out, and so a packet capture says
+* what the port is for.
+*/
+const STREAM_META = { kind: "stream" };
+/**
+* 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.
+*/
+const connect = async ({ mux: factory, timeout }) => {
+	const mux = await factory();
+	const streamOptions = {
+		maxMessageSize: mux.maxMessageSize,
+		timeout
+	};
+	const call = (input) => (async function* () {
+		yield* duplexOverPort(await mux.openPort(STREAM_META), streamOptions)(input);
+	})();
+	return {
+		call,
+		async close() {
+			await mux.close();
+		}
+	};
+};
+/**
+* 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.
+*/
+const serve = async ({ mux: factory, timeout }, handler) => {
+	const live = /* @__PURE__ */ new Set();
+	let streamOptions = { timeout };
+	const mux = await factory((port) => {
+		let off;
+		let finished = false;
+		const tracked = (input) => (async function* () {
+			try {
+				yield* handler(input);
+			} finally {
+				finished = true;
+				if (off) live.delete(off);
+			}
+		})();
+		off = serveDuplexOverPort(port, tracked, streamOptions);
+		if (!finished) live.add(off);
+	});
+	streamOptions = {
+		maxMessageSize: mux.maxMessageSize,
+		timeout
+	};
+	let torn = false;
+	return async () => {
+		if (torn) return;
+		torn = true;
+		for (const off of [...live]) {
+			live.delete(off);
+			try {
+				off();
+			} catch {}
+		}
+		await mux.close();
+	};
+};
+/**
+* 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.
+*/
+function overPipe(pipe, options) {
+	return (onPort) => multiplexPort(pipe, {
+		...options,
+		onPort
+	});
+}
+/**
+* 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);
+* ```
+*/
+function overPorts(factory) {
+	return factory;
+}
+//#endregion
+//#region src/io-handle.ts
+/**
+* Server half of a full-duplex exchange over any `MessageTarget`.
+*
+* For each inbound stream, invokes `handler` with the stream, sends the
+* handler's output back, and yields a counter. The generator never ends
+* on its own — consumers break when they want to stop. Pairs with
+* {@link ioSend}.
+*
+* If the peer (the consumer of our outbound send) posts a `cancel-channel`
+* message on the same sub-channel, we abort `send` immediately. This makes
+* `ioSend`'s `iter.return()` propagate cleanly without waiting for
+* `callPort` timeouts.
+*/
+async function* ioHandle(port, handler, options = {}) {
+	let counter = 0;
+	const channelName = options.channelName ?? "";
+	for await (const input of recieve(port, options)) {
+		const sendAbort = new AbortController();
+		const unsubscribeCancel = channelName ? listenCancelChannel(port, channelName, () => sendAbort.abort()) : () => {};
+		try {
+			await send(port, await handler(input), {
+				...options,
+				signal: sendAbort.signal
+			});
+		} finally {
+			unsubscribeCancel();
+		}
+		yield counter++;
+	}
+}
+//#endregion
+//#region src/listen-bidi.ts
+/**
+* Server half of {@link callBidi}: listens for stream-call requests on `port`
+* and dispatches each accepted one to `action`.
+*
+* The optional `accept` predicate can inspect the incoming params and reject
+* unwanted calls. Returns a cleanup function that removes the listener.
+*/
+function listenBidi(port, action, accept = () => true) {
+	return listenPort(port, async (params) => {
+		if (!params || typeof params.channelName !== "string") return;
+		if (!accept(params)) return;
+		const handler = async (input) => action(input, params);
+		for await (const _idx of ioHandle(port, handler, params)) break;
+	});
+}
+//#endregion
+//#region src/structured-codec.ts
+function isEnvelope(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	if (typeof candidate.id !== "number") return false;
+	if (!Number.isInteger(candidate.id) || candidate.id < 0) return false;
+	return candidate.type === "open" || candidate.type === "message" || candidate.type === "close";
+}
+/**
+* For ports whose messages are structured values — a real `MessagePort`, a
+* worker, an iframe.
+*
+* Envelopes are posted as-is, so nothing is encoded, `ArrayBuffer`s move
+* zero-copy through the transfer list, and structured clone does the work the
+* platform already does well. This is a performance choice only: layer 2 may
+* not send anything a byte codec could not also carry.
+*/
+const structuredCodec = {
+	post(port, envelope, transfer) {
+		if (transfer && transfer.length > 0) port.postMessage(envelope, transfer);
+		else port.postMessage(envelope);
+	},
+	read(event) {
+		return isEnvelope(event.data) ? event.data : void 0;
+	}
+};
+//#endregion
+//#region src/transfer-port-mux.ts
+/** The `type` of the envelope that carries a transferred port to the peer. */
+const PORT_TRANSFER = "webrun-rpc:port-transfer";
+/**
+* A `PortMux` whose ports are real, transferred `MessagePort`s (spec D23).
+*
+* `openPort` creates a `MessageChannel`, transfers one end to the peer over
+* `target`, and returns the other. There is no id table, no `maxPorts` and no
+* envelope overhead per message, because the platform does the multiplexing.
+*
+* **It needs structured clone with transferables**, so it exists in browsers,
+* workers and iframes and nowhere else that lacks them. A caller selects it
+* explicitly rather than by capability sniffing (spec D21): use
+* `multiplexPort` where the transport is one pipe of bytes.
+*
+* What it buys over emulation: a transferred port can cross an origin or a
+* worker boundary and be handed to code that never saw `target`, where an
+* emulated port id is meaningless outside its own mux.
+*
+* `target` must be a full `MessageTarget`. Reaching a send-only `MessageSink`
+* — a `ServiceWorkerClient`, say — is a real use of port transfer but needs a
+* different entry point, and is not part of this interface.
+*/
+function transferPortMux(target, options = {}) {
+	const { onPort, maxMessageSize } = options;
+	const issued = /* @__PURE__ */ new Set();
+	let closed = false;
+	const listener = (event) => {
+		if (closed) return;
+		const data = event.data;
+		if (!data || typeof data !== "object" || data.type !== "webrun-rpc:port-transfer") return;
+		const port = event.ports?.[0];
+		if (!port) return;
+		port.start();
+		let accepted = false;
+		if (onPort) try {
+			accepted = onPort(port, data.meta) !== false;
+		} catch {
+			accepted = false;
+		}
+		if (!accepted) {
+			port.close();
+			return;
+		}
+		issued.add(port);
+	};
+	target.addEventListener("message", listener);
+	target.start?.();
+	return {
+		maxMessageSize,
+		async openPort(meta) {
+			if (closed) throw new Error("webrun-rpc: the multiplexer is closed");
+			const channel = new MessageChannel();
+			channel.port1.start();
+			target.postMessage({
+				type: PORT_TRANSFER,
+				meta
+			}, [channel.port2]);
+			issued.add(channel.port1);
+			return channel.port1;
+		},
+		async close() {
+			if (closed) return;
+			closed = true;
+			target.removeEventListener("message", listener);
+			for (const port of issued) try {
+				port.close();
+			} catch {}
+			issued.clear();
+			await target.close?.();
+		}
+	};
+}
+//#endregion
+export { CANCEL_CHANNEL_TYPE, DEFAULT_MAX_PORTS, NO_TIMEOUT, PORT_TRANSFER, STREAM_ABORT, byteChannelFromMessagePort, callBidi, callPort, connect, duplexOverPort, getPortCloseSignal, ioHandle, ioSend, listenBidi, listenCancelChannel, listenPort, multiplexPort, overPipe, overPorts, postCancelChannel, recieve, send, serve, serveDuplexOverPort, setPortCloseSignal, structuredCodec, transferPortMux };