@statewalker/webrun-http-browser 0.6.4 → 0.7.0

package/dist/relay-sw.js

@@ -282,6 +282,34 @@
 			});
 		}
 	}
+	const DEFAULT_CHUNK_SIZE = 16384;
+	/**
+	* Curried `Duplex`-shaped transformer that splits incoming `Uint8Array`s into
+	* chunks no larger than `size` bytes. Empty input chunks are skipped; small
+	* input chunks pass through unchanged (zero-copy `subarray` views are used
+	* when splitting, so no allocation per chunk).
+	*
+	* Use to respect transport MTUs before reaching `channel.send`. Reassembly on
+	* the receive side is not needed — consumers iterate a continuous byte stream.
+	*/
+	function toChunks(size = DEFAULT_CHUNK_SIZE) {
+		if (!(Number.isInteger(size) && size > 0)) throw new RangeError(`toChunks: size must be a positive integer, got ${size}`);
+		return async function* (input) {
+			for await (const block of input) {
+				if (block.byteLength === 0) continue;
+				if (block.byteLength <= size) {
+					yield block;
+					continue;
+				}
+				let offset = 0;
+				while (offset < block.byteLength) {
+					const end = Math.min(offset + size, block.byteLength);
+					yield block.subarray(offset, end);
+					offset = end;
+				}
+			}
+		};
+	}
 	//#endregion
 	//#region ../webrun-http-streams/dist/index.js
 	const CR = 13;
@@ -1033,10 +1061,99 @@
 			}
 		};
 	}
-	newSniffingCodec({
+	/**
+	* Writes HTTP/1.1; accepts HTTP/1.1 or the legacy JSON envelope. Used whenever
+	* no `codec` option is supplied.
+	*/
+	const defaultCodec = newSniffingCodec({
 		write: httpCodec,
 		accept: [httpCodec, jsonEnvelopeCodec]
 	});
+	/** Carries the serialized JS error between two webrun peers. */
+	const PEER_ERROR_HEADER = "x-webrun-error";
+	/**
+	* `output` is the `Duplex` call's own generator — one logical call, per the
+	* `Duplex` contract in `@statewalker/webrun-streams`: "Consumer `.return()`
+	* on the output → producer's `finally` runs." On a mux transport
+	* (`emulateMux`), that `finally` is what frees the stream-table slot; skip it
+	* and every peer-error response leaks one slot, unboundedly, until the mux
+	* itself is exhausted (`maxStreams` reached, every further call rejected).
+	*
+	* Cancelling `output` here — not inside the codec's own decode logic — is
+	* deliberate. `codec.decodeResponse` already pulled from `output` to read the
+	* head before this function runs, so unlike the body case above there's no
+	* suspended-start no-op to worry about. And it's safe specifically *because*
+	* this is the client's own response-only generator: the request was already
+	* fully sent before we got here, so there is nothing left to write on it.
+	* The equivalent is NOT safe inside `src/http1/decode.ts`'s `ByteReader` —
+	* that code also runs when a caller wires `codec.decodeRequest`/
+	* `decodeResponse` directly onto a raw bidirectional socket (see
+	* `tests/http1-node-interop.test.ts`), where the *same* object is read from
+	* and then written back to (a server reads the request, then replies on the
+	* same socket); cancelling the read side there tears down the whole
+	* connection out from under the pending write. That was tried and reverted —
+	* see the Task 11 report for the "socket hang up" failure it caused.
+	*/
+	async function throwIfPeerError(result, output) {
+		const found = result.envelope.headers.find(([k]) => k.toLowerCase() === PEER_ERROR_HEADER);
+		if (!found) return;
+		await discard(result.body);
+		try {
+			await output.return?.(void 0);
+		} catch {}
+		let payload;
+		try {
+			payload = JSON.parse(found[1]);
+		} catch {
+			payload = { message: found[1] };
+		}
+		throw deserializeError(payload);
+	}
+	/**
+	* Initiate an HTTP call over a `Duplex`. The caller's `call: Duplex` is
+	* obtained from any `webrun-streams-*` adapter's `connect`. Returns the
+	* response envelope and an async iterable over the response body bytes.
+	*
+	* The call is one logical Duplex invocation; multiplexing of concurrent
+	* calls is the adapter's concern (native or `emulateMux`).
+	*/
+	async function httpFetch(call, env, body, options = {}) {
+		const codec = options.codec ?? defaultCodec;
+		const output = call(codec.encodeRequest(env, body));
+		const decoded = await codec.decodeResponse(output, { method: env.method });
+		const release = async () => {
+			try {
+				await output.return?.(void 0);
+			} catch {}
+		};
+		const result = {
+			envelope: decoded.envelope,
+			body: releasingOnExit(decoded.body, release),
+			release
+		};
+		await throwIfPeerError(result, output);
+		return result;
+	}
+	/**
+	* `body`, but leaving it before its end releases the call.
+	*
+	* The body the codec hands back is a generator of its own over a `ByteReader`,
+	* and `.return()` on it never reaches the call's `output` (see
+	* `throwIfPeerError` for why the codec must not do that itself). So a caller
+	* that stopped reading — an aborted `fetch`, a cancelled response stream —
+	* left the peer's producer parked forever, holding its handler open. Safe here
+	* for the same reason it is safe in `throwIfPeerError`: `output` is this
+	* call's own response-only generator, and the request was fully sent.
+	*/
+	async function* releasingOnExit(body, release) {
+		let completed = false;
+		try {
+			yield* body;
+			completed = true;
+		} finally {
+			if (!completed) await release();
+		}
+	}
 	/**
 	* The one place that knows a runtime may not implement request body streams,
 	* and the buffering both fallbacks need. `fetch.ts` and `http-stubs.ts` each
@@ -1142,6 +1259,121 @@
 			return new Response(toReadableStream(result.content[Symbol.asyncIterator]()), responseOptions);
 		};
 	}
+	/**
+	* Connection-scoped headers. The codec surfaces them verbatim (decision 12),
+	* but they are meaningless to a `Request`/`Response`, and re-emitting them
+	* from a relay would corrupt its framing.
+	*/
+	const HOP_BY_HOP = /* @__PURE__ */ new Set([
+		"connection",
+		"host",
+		"keep-alive",
+		"proxy-authenticate",
+		"proxy-authorization",
+		"te",
+		"trailer",
+		"transfer-encoding",
+		"upgrade"
+	]);
+	function forwardableHeaders(headers) {
+		return headers.filter(([name]) => !HOP_BY_HOP.has(name.toLowerCase()));
+	}
+	function headersToArray(headers) {
+		const out = [];
+		headers.forEach((value, key) => {
+			out.push([key, value]);
+		});
+		return out;
+	}
+	async function* readableToAsyncIterable(stream) {
+		if (!stream) return;
+		const reader = stream.getReader();
+		let consumed = false;
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					consumed = true;
+					return;
+				}
+				if (value) yield value;
+			}
+		} finally {
+			if (!consumed) try {
+				await reader.cancel();
+			} catch {}
+			try {
+				reader.releaseLock();
+			} catch {}
+		}
+	}
+	function asyncIterableToReadable(iter) {
+		const it = iter[Symbol.asyncIterator]();
+		return new ReadableStream({
+			async pull(controller) {
+				try {
+					const { done, value } = await it.next();
+					if (done) {
+						controller.close();
+						return;
+					}
+					controller.enqueue(value);
+				} catch (err) {
+					controller.error(err);
+				}
+			},
+			async cancel() {
+				await it.return?.();
+			}
+		});
+	}
+	/**
+	* Run a `Request` through a `Duplex` call and reconstruct the `Response` on
+	* the other side. The request's `signal` is plumbed into the body iteration —
+	* abort terminates the underlying call.
+	*/
+	async function fetchOverDuplex(call, request, options = {}) {
+		if (request.signal?.aborted) throw abortReason$1(request.signal);
+		const env = {
+			url: request.url,
+			method: request.method,
+			headers: headersToArray(request.headers)
+		};
+		let body;
+		if (request.body != null) body = readableToAsyncIterable(request.body);
+		else if (!supportsRequestStreams()) {
+			const buffered = new Uint8Array(await request.arrayBuffer());
+			if (buffered.byteLength > 0) body = [buffered];
+		}
+		const { envelope, body: respBody, release } = await httpFetch(call, env, body, options);
+		const responseInit = {
+			status: envelope.status,
+			statusText: envelope.statusText,
+			headers: forwardableHeaders(envelope.headers)
+		};
+		if (request.method === "HEAD" || request.method === "OPTIONS" || NULL_BODY_STATUSES.has(envelope.status)) {
+			await release?.();
+			return new Response(null, responseInit);
+		}
+		return new Response(asyncIterableToReadable(withAbort(respBody, request.signal)), responseInit);
+	}
+	async function* withAbort(iter, signal) {
+		if (!signal) {
+			yield* iter;
+			return;
+		}
+		for await (const chunk of iter) {
+			if (signal.aborted) throw abortReason$1(signal);
+			yield chunk;
+		}
+	}
+	function abortReason$1(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;
+	}
 	var HttpError = class HttpError extends Error {
 		status;
 		statusText;
@@ -1254,6 +1486,32 @@
 	}
 	//#endregion
 	//#region src/core/data-calls.ts
+	const TRANSFER = Symbol.for("webrun-http-browser:transfer");
+	/**
+	* A channel call's result that carries transferables, a `MessagePort` say:
+	* return `withTransfer({ port }, [port])` from a `handleChannelCalls` handler
+	* and `callChannel` resolves with `{ port }`.
+	*/
+	function withTransfer(value, transfer) {
+		return {
+			[TRANSFER]: true,
+			value,
+			transfer
+		};
+	}
+	function isTransferResult(value) {
+		return typeof value === "object" && value !== null && TRANSFER in value;
+	}
+	/** Splits a handler's result into the value to post and its transfer list. */
+	function unwrapTransfer(result) {
+		return isTransferResult(result) ? {
+			value: result.value,
+			transfer: result.transfer
+		} : {
+			value: result,
+			transfer: []
+		};
+	}
 	function callChannel(target, callType, params, ...transfers) {
 		return new Promise((resolve, reject) => {
 			const channel = new MessageChannel();
@@ -1273,12 +1531,14 @@
 			if (!event.data || event.data.type !== callType) return;
 			const [port, ...transfers] = event.ports ?? [];
 			const response = {};
+			let transfer = [];
 			try {
-				response.result = await handler(event, event.data.params, ...transfers);
+				const result = await handler(event, event.data.params, ...transfers);
+				({value: response.result, transfer} = unwrapTransfer(result));
 			} catch (error) {
 				response.error = serializeError(error);
 			}
-			port?.postMessage(response);
+			port?.postMessage(response, transfer);
 		};
 		target.addEventListener("message", listener);
 		target.start?.();
@@ -1335,6 +1595,798 @@
 		});
 	}
 	//#endregion
+	//#region ../webrun-rpc/dist/index.js
+	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);
+	}
+	/**
+	* 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);
+	}
+	/**
+	* 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);
+	}
+	/**
+	* 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);
+		}
+	}
+	/**
+	* 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);
+	}
+	function runCallerSide(port, input, options) {
+		const controller = new AbortController();
+		const notice = installAbortNotice(port, controller);
+		abortOnPortClose(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);
+			}
+		};
+	}
+	/**
+	* Aborts the stream when its port closes underneath it — the multiplexer was
+	* closed, or the peer closed the port — for ports that report it (see
+	* `getPortCloseSignal`). Without this a stream waiting for the peer's next
+	* chunk would wait forever on a port that can no longer deliver one: the
+	* outbound half's `callPort` already fails on the close signal, but nothing
+	* failed the inbound half.
+	*/
+	function abortOnPortClose(port, controller) {
+		const closed = getPortCloseSignal(port);
+		if (!closed) return;
+		const onClose = () => {
+			if (!controller.signal.aborted) controller.abort(closed.reason);
+		};
+		if (closed.aborted) {
+			onClose();
+			return;
+		}
+		closed.addEventListener("abort", onClose, { once: true });
+		controller.signal.addEventListener("abort", () => closed.removeEventListener("abort", onClose), { once: true });
+	}
+	/**
+	* 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;
+		}
+	}
+	/**
+	* 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;
+		const closing = new AbortController();
+		const abort = (reason) => {
+			if (closing.signal.aborted) return;
+			closing.abort(reason ?? /* @__PURE__ */ new Error("webrun-rpc: the port was closed"));
+		};
+		const 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();
+				abort();
+			}
+		};
+		setPortCloseSignal(port, closing.signal);
+		return {
+			port,
+			deliver(payload) {
+				if (closed) return;
+				const event = new MessageEvent("message", { data: payload });
+				for (const listener of [...listeners]) try {
+					listener(event);
+				} catch {}
+			},
+			markClosed(reason) {
+				closed = true;
+				listeners.clear();
+				abort(reason);
+			},
+			isClosed() {
+				return closed;
+			}
+		};
+	}
+	/**
+	* The message of the error that fails the calls still in flight on a
+	* multiplexer when it is closed (`PortMux.close()`).
+	*/
+	const MUX_CLOSED_MESSAGE = "webrun-rpc: the multiplexer was closed";
+	/** 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(/* @__PURE__ */ new Error("webrun-rpc: the port was rejected"));
+					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(/* @__PURE__ */ new Error("webrun-rpc: the peer closed the port"));
+		};
+		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(/* @__PURE__ */ new Error(MUX_CLOSED_MESSAGE));
+				}
+				muxClosed = true;
+				port.removeEventListener("message", listener);
+				await port.close?.();
+			}
+		};
+	}
+	/**
+	* 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();
+			}
+		};
+	};
+	/**
+	* 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
+		});
+	}
+	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/link/http-link.ts
+	/**
+	* The version of the HTTP-over-`MessagePort` protocol this package speaks,
+	* sent in every hand-shake that sets up a link. Version 1 was this package's
+	* own `handleStreams` / `sendStream` (no backpressure); version 2 is
+	* webrun-rpc's `connect` / `serve` over `overPipe` with webrun-http-streams'
+	* `fetchOverDuplex` / `serveFetchOverDuplex`: one port per link, calls
+	* multiplexed on it, each call a stream with a one-chunk window in both
+	* directions, and cancellation that reaches the handler.
+	*/
+	const HTTP_LINK_PROTOCOL = "webrun-http-link/2";
+	/**
+	* Why a request failed when its link went away under it: the far side (the
+	* handler, or the ServiceWorker) was lost. The request may or may not have
+	* been applied.
+	*/
+	var LinkLostError = class extends Error {
+		constructor(message = "The link was lost while this request was in flight") {
+			super(`${message}; it may or may not have been applied.`);
+			this.name = "LinkLostError";
+		}
+	};
+	/**
+	* Posted on a link's port by the calling end when it closes the link, so the
+	* answering end can release it: a `MessagePort` never reports that its other
+	* end is gone.
+	*/
+	const LINK_CLOSE = "webrun-http:link-close";
+	/** Opens the calling end of a link on `port` (one port per link). */
+	async function connectHttpLink(port, { streamTimeout } = {}) {
+		const { call, close } = await connect({
+			mux: overPipe(port, {
+				codec: structuredCodec,
+				side: "initiator"
+			}),
+			timeout: streamTimeout
+		});
+		return trackedLink((request) => fetchOverDuplex(call, request), async () => {
+			try {
+				port.postMessage({ type: LINK_CLOSE });
+			} catch {}
+			await close();
+		});
+	}
+	/**
+	* Wraps a `send` so the link knows its requests in flight (for draining and
+	* load-based routing) and can fail them all at once when it is closed.
+	*/
+	function trackedLink(send, release) {
+		let inflight = 0;
+		let closed = false;
+		let lostReason;
+		const failers = /* @__PURE__ */ new Set();
+		const idleWaiters = [];
+		const done = () => {
+			inflight--;
+			if (inflight === 0) for (const resolve of idleWaiters.splice(0)) resolve();
+		};
+		return {
+			get inflight() {
+				return inflight;
+			},
+			get closed() {
+				return closed;
+			},
+			whenIdle() {
+				return inflight === 0 ? Promise.resolve() : new Promise((r) => idleWaiters.push(r));
+			},
+			async send(request) {
+				if (closed) throw lostReason ?? new LinkLostError("The link is closed");
+				inflight++;
+				let finished = false;
+				const finish = () => {
+					if (finished) return;
+					finished = true;
+					failers.delete(fail);
+					done();
+				};
+				let fail = () => {};
+				const lost = new Promise((_, reject) => {
+					fail = reject;
+				});
+				failers.add(fail);
+				lost.catch(() => {});
+				let response;
+				try {
+					response = await Promise.race([send(request), lost]);
+				} catch (error) {
+					finish();
+					throw lostReason ?? error;
+				}
+				if (!response.body) {
+					finish();
+					return response;
+				}
+				return new Response(guardBody(response.body, lost, () => lostReason, finish), {
+					status: response.status,
+					statusText: response.statusText,
+					headers: response.headers
+				});
+			},
+			async close(reason) {
+				if (closed) return;
+				closed = true;
+				lostReason = reason ?? new LinkLostError("The link was closed");
+				for (const fail of [...failers]) fail(lostReason);
+				try {
+					await release();
+				} catch {}
+			}
+		};
+	}
+	/**
+	* A response body that reports its end (done, cancelled or failed) and fails
+	* with the link's reason when the link is lost mid-stream.
+	*/
+	function guardBody(body, lost, reason, finish) {
+		const reader = body.getReader();
+		return new ReadableStream({
+			async pull(controller) {
+				try {
+					const { done, value } = await Promise.race([reader.read(), lost]);
+					if (done) {
+						finish();
+						controller.close();
+						return;
+					}
+					controller.enqueue(value);
+				} catch (error) {
+					finish();
+					reader.cancel().catch(() => {});
+					controller.error(reason() ?? error);
+				}
+			},
+			async cancel(why) {
+				finish();
+				await reader.cancel(why).catch(() => {});
+			}
+		});
+	}
+	//#endregion
+	//#region src/sw/protocol.ts
+	/** Page → ServiceWorker: open a WebSocket to a handler. */
+	const WS_CONNECT_CALL = "webrun-http:ws-connect";
+	//#endregion
 	//#region src/core/data-channels.ts
 	const MESSAGE_TYPE_REQUEST = "REQUEST";
 	const MESSAGE_TYPE_RESPONSE = "RESPONSE";
@@ -1533,51 +2585,6 @@
 		})(request);
 	}
 	//#endregion
-	//#region src/relay/mount-table.ts
-	/** `/` stays `/`; `/peers` and `/peers/` both become `/peers/`. */
-	function normalise(path) {
-		if (path === "" || path === "/") return "/";
-		const withSlash = path.startsWith("/") ? path : `/${path}`;
-		return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
-	}
-	/** Does `prefix` own `pathname`? `/peers/` owns `/peers/`, `/peers` and `/peers/x`. */
-	function owns(prefix, pathname) {
-		if (prefix === "/") return true;
-		if (pathname.startsWith(prefix)) return true;
-		return `${pathname}/` === prefix;
-	}
-	function newMountTable(options = {}) {
-		const entries = /* @__PURE__ */ new Map();
-		let seq = 0;
-		return {
-			set(key, spec) {
-				entries.set(key, {
-					key,
-					prefix: spec.path == null ? "" : normalise(spec.path),
-					match: spec.match,
-					seq: seq++
-				});
-			},
-			remove(key) {
-				entries.delete(key);
-			},
-			excludes(url) {
-				return options.exclude?.(url) === true;
-			},
-			find(url) {
-				if (options.exclude?.(url) === true) return void 0;
-				let best;
-				for (const entry of entries.values()) {
-					if (entry.prefix === "" || !owns(entry.prefix, url.pathname)) continue;
-					if (best == null || entry.prefix.length > best.prefix.length) best = entry;
-				}
-				if (best != null) return best.key;
-				const predicates = [...entries.values()].filter((entry) => entry.match != null).sort((a, b) => a.seq - b.seq);
-				for (const entry of predicates) if (entry.match?.(url) === true) return entry.key;
-			}
-		};
-	}
-	//#endregion
 	//#region src/relay/split-service-url.ts
 	/**
 	* Splits a URL of the form `<base>/<separator><key>/<path>` into parts.
@@ -1635,6 +2642,69 @@
 			path: slash < 0 ? "" : rest.slice(slash + 1)
 		};
 	}
+	self.location.href;
+	/**
+	* Sends `request` on a port a service accepted with `reply`: over an HTTP link
+	* when the service speaks `HTTP_LINK_PROTOCOL`, over version 1's transport
+	* when it answered `true`. The link is closed once the response is done.
+	*/
+	async function sendOverConnection(port, reply, request, options = {}) {
+		if (reply === true) return await sendHttpRequest(port, request);
+		const link = await connectHttpLink(port, options);
+		try {
+			const response = await link.send(request);
+			link.whenIdle().then(() => link.close());
+			return response;
+		} catch (error) {
+			await link.close();
+			throw error;
+		}
+	}
+	//#endregion
+	//#region src/relay/mount-table.ts
+	/** `/` stays `/`; `/peers` and `/peers/` both become `/peers/`. */
+	function normalise(path) {
+		if (path === "" || path === "/") return "/";
+		const withSlash = path.startsWith("/") ? path : `/${path}`;
+		return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
+	}
+	/** Does `prefix` own `pathname`? `/peers/` owns `/peers/`, `/peers` and `/peers/x`. */
+	function owns(prefix, pathname) {
+		if (prefix === "/") return true;
+		if (pathname.startsWith(prefix)) return true;
+		return `${pathname}/` === prefix;
+	}
+	function newMountTable(options = {}) {
+		const entries = /* @__PURE__ */ new Map();
+		let seq = 0;
+		return {
+			set(key, spec) {
+				entries.set(key, {
+					key,
+					prefix: spec.path == null ? "" : normalise(spec.path),
+					match: spec.match,
+					seq: seq++
+				});
+			},
+			remove(key) {
+				entries.delete(key);
+			},
+			excludes(url) {
+				return options.exclude?.(url) === true;
+			},
+			find(url) {
+				if (options.exclude?.(url) === true) return void 0;
+				let best;
+				for (const entry of entries.values()) {
+					if (entry.prefix === "" || !owns(entry.prefix, url.pathname)) continue;
+					if (best == null || entry.prefix.length > best.prefix.length) best = entry;
+				}
+				if (best != null) return best.key;
+				const predicates = [...entries.values()].filter((entry) => entry.match != null).sort((a, b) => a.seq - b.seq);
+				for (const entry of predicates) if (entry.match?.(url) === true) return entry.key;
+			}
+		};
+	}
 	//#endregion
 	//#region src/relay/index-sw.ts
 	/**
@@ -1762,7 +2832,7 @@
 			const source = event.source;
 			if (!source) return false;
 			const { key, path } = data;
-			if (options.canRegister != null && !await options.canRegister(source, key)) throw new Error(`this client may not register "${key}"`);
+			if (options.canRegister != null && !await options.canRegister(source, key, path)) throw new Error(path == null ? `this client may not register "${key}"` : `this client may not register "${key}" at "${path}"`);
 			if (takeover === "first-wins") {
 				const current = await clientsRegistry.getMount(key);
 				const isCurrentLive = current != null && await clientsRegistry.getClient(key) != null;
@@ -1777,8 +2847,14 @@
 			applyRegisteredMount(mounts, key, path, hostKeys);
 			return added;
 		}));
-		register(handleChannelCalls(self, "UNREGISTER", async (_event, data) => {
+		register(handleChannelCalls(self, "UNREGISTER", async (event, data) => {
+			const source = event.source;
+			if (!source) return false;
 			const { key } = data;
+			const current = await clientsRegistry.getMount(key);
+			if (current == null) return false;
+			if (await clientsRegistry.getClient(key) != null && current.clientId !== source.id) throw new Error(`"${key}" is served by another client`);
+			if (options.canRegister != null && !await options.canRegister(source, key, current.path)) throw new Error(`this client may not unregister "${key}"`);
 			removeRegisteredMount(mounts, key, hostKeys);
 			return await clientsRegistry.removeClient(key);
 		}));
@@ -1786,7 +2862,34 @@
 			const { key } = data;
 			const client = await clientsRegistry.getClient(key);
 			if (!client) throw new Error(`Target client was not found. Target key: "${key}".`);
-			return await callChannel(client, "CONNECT", data, port);
+			const reply = await callChannel(client, "CONNECT", data, port);
+			const socketPort = reply?.port;
+			return socketPort ? withTransfer(reply, [socketPort]) : reply;
+		}));
+		register(handleChannelCalls(self, WS_CONNECT_CALL, async (event, data) => {
+			const source = event.source;
+			if (!source?.url || new URL(source.url).origin !== self.location.origin) throw new Error("Only this origin's pages may open sockets");
+			const { url, protocols = [] } = data;
+			const httpUrl = new URL(url);
+			if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
+			else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
+			await restored.catch(() => {});
+			const key = resolveServiceKey(httpUrl, mounts, self.location.origin);
+			if (key == null) throw new Error(`No service serves ${url}`);
+			const client = await clientsRegistry.getClient(key);
+			if (!client) throw new Error(`No service serves ${url}`);
+			const channel = new MessageChannel();
+			try {
+				const connection = await callChannel(client, "CONNECT", {
+					type: "ws",
+					key,
+					url: `${httpUrl}`,
+					protocols
+				}, channel.port2);
+				return withTransfer(connection, [connection.port]);
+			} finally {
+				channel.port1.close();
+			}
 		}));
 		/** Answers `request` as the service registered under `key`. */
 		async function serve(key, request, url) {
@@ -1795,11 +2898,13 @@
 				const channel = new MessageChannel();
 				const client = await clientsRegistry.getClient(key);
 				if (!client) throw HttpError.errorResourceGone(params);
-				if (!await callChannel(client, "CONNECT", {
+				const reply = await callChannel(client, "CONNECT", {
 					type: "http",
-					key
-				}, channel.port2)) throw HttpError.errorForbidden(params);
-				const response = await sendHttpRequest(channel.port1, request);
+					key,
+					wire: HTTP_LINK_PROTOCOL
+				}, channel.port2);
+				if (!reply) throw HttpError.errorForbidden(params);
+				const response = await sendOverConnection(channel.port1, reply, request, { streamTimeout: options.streamTimeout });
 				return options.decorateResponse?.(response, request) ?? response;
 			} catch (error) {
 				const httpError = HttpError.fromError(error);