@statewalker/webrun-http-browser 0.9.0 → 0.12.1

package/dist/worker.js

@@ -1207,7 +1207,11 @@ async function drain(output) {
 */
 function httpServe(handler, options = {}) {
 	const codec = options.codec ?? defaultCodec;
-	return async function* httpHandlerDuplex(input) {
+	return (input) => {
+		const abandoned = new AbortController();
+		return abortingOnReturn(exchange(input, { signal: abandoned.signal }), (reason) => abandoned.abort(reason ?? /* @__PURE__ */ new Error("webrun-http-streams: the exchange was abandoned before it was over")));
+	};
+	async function* exchange(input, context) {
 		let decoded;
 		try {
 			decoded = await codec.decodeRequest(input);
@@ -1219,7 +1223,7 @@ function httpServe(handler, options = {}) {
 		const replyCodec = decoded.codec ?? codec;
 		let result;
 		try {
-			result = await handler(decoded.envelope, decoded.body);
+			result = await handler(decoded.envelope, decoded.body, context);
 		} catch (error) {
 			yield* encodeErrorResponse(replyCodec, error, decoded.envelope.method);
 			return;
@@ -1234,7 +1238,36 @@ function httpServe(handler, options = {}) {
 				await result.release?.();
 			} catch {}
 		}
+	}
+}
+/**
+* `gen`, except that `return()` and `throw()` from its consumer call `abandon`
+* at once — before they are queued behind a `next()` still parked inside the
+* generator (the handler's `await`) — unless the generator already finished.
+*/
+function abortingOnReturn(gen, abandon) {
+	let finished = false;
+	const settle = (r) => {
+		if (r.done) finished = true;
+		return r;
+	};
+	const wrapped = {
+		next: (...args) => gen.next(...args).then(settle),
+		return(value) {
+			if (!finished) abandon();
+			finished = true;
+			return gen.return(value);
+		},
+		throw(error) {
+			if (!finished) abandon(error);
+			finished = true;
+			return gen.throw(error);
+		},
+		[Symbol.asyncIterator]() {
+			return wrapped;
+		}
 	};
+	return asyncDisposable$2(wrapped, () => wrapped.return(void 0));
 }
 /**
 * The one place that knows a runtime may not implement request body streams,
@@ -1418,10 +1451,11 @@ async function fetchOverDuplex(call, request, options = {}) {
 * registered with any `webrun-streams-*` adapter's `serve`.
 */
 function serveFetchOverDuplex(handler, options = {}) {
-	return httpServe(async (env, body) => {
+	return httpServe(async (env, body, exchange) => {
 		const reqInit = {
 			method: env.method,
-			headers: forwardableHeaders(env.headers)
+			headers: forwardableHeaders(env.headers),
+			signal: exchange?.signal
 		};
 		let upload;
 		if (env.method !== "GET" && env.method !== "HEAD") {
@@ -1772,6 +1806,99 @@ async function* throughAbort(input, signal) {
 	}
 }
 /**
+* Runs `fn` on a later task, never a microtask: a producer looping on
+* `whenPortReady` must let the transport's own events run. `setImmediate`
+* where it exists; elsewhere a `MessageChannel`, because nested `setTimeout`s
+* are clamped to 4 ms in browsers.
+*/
+const setImmediateFn = globalThis.setImmediate;
+/** @internal */
+const nextTask = setImmediateFn ? (fn) => {
+	setImmediateFn(fn);
+} : (() => {
+	let channel;
+	const queue = [];
+	return (fn) => {
+		if (!channel) {
+			channel = new MessageChannel();
+			channel.port1.onmessage = () => queue.shift()?.();
+		}
+		queue.push(fn);
+		channel.port2.postMessage(0);
+	};
+})();
+const states = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortSendState(port, state) {
+	states.set(port, state);
+}
+/**
+* Bytes queued on `port` because its window is spent (0 for a port without
+* flow control). A sender that should not queue without bound waits for
+* `whenPortReady` before posting more.
+*/
+function portBufferedAmount(port) {
+	return states.get(port)?.bufferedAmount() ?? 0;
+}
+/**
+* Resolves once at most `below` bytes are queued on `port`, always on a later
+* task (for a port without flow control, on the next one).
+*/
+function whenPortReady(port, below = 0) {
+	return states.get(port)?.ready(below) ?? new Promise((resolve) => nextTask(resolve));
+}
+const agreements = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortAgreement(port, agreement) {
+	agreements.set(port, agreement);
+}
+/**
+* @internal What has been agreed with the peer on `port` so far; `undefined`
+* on a port without a window. Not exported from the package.
+*/
+function portAgreement(port) {
+	return agreements.get(port)?.();
+}
+const ends = /* @__PURE__ */ new WeakMap();
+/** @internal Registered by the multiplexer for each port with a window. */
+function setPortEndState(port, state) {
+	ends.set(port, state);
+}
+/**
+* @internal End this side's direction of `port`: an `end` is queued behind
+* everything already posted on it, and anything posted afterwards is dropped.
+* `false`, and nothing changes, when `end` was not agreed (no window, the
+* handshake not answered yet, or a peer that does not speak it): the caller
+* then closes the port. Never waits on the peer. Not exported from the package.
+*/
+function endPort(port) {
+	return ends.get(port)?.end() ?? false;
+}
+/**
+* @internal Resolves once the peer has ended its direction of `port`. It never
+* settles otherwise: not on a port where `end` is not agreed when it is asked
+* (no window, the handshake not answered yet, a peer or codec without it), and
+* not when the port closes first, so a caller races it against the port's
+* close signal. Not exported from the package.
+*/
+function whenPortEnded(port) {
+	let waiting = peerEnds.get(port);
+	if (!waiting) {
+		let resolve = () => {};
+		const promise = new Promise((r) => {
+			resolve = r;
+		});
+		if (!ends.get(port)?.watchPeerEnd(resolve)) return promise;
+		waiting = {
+			promise,
+			resolve
+		};
+		peerEnds.set(port, waiting);
+	}
+	return waiting.promise;
+}
+const peerEnds = /* @__PURE__ */ new WeakMap();
+/**
 * Makes `target` disposable with `await using`: installs `dispose` as its
 * `[Symbol.asyncDispose]`, where the runtime defines the symbol. Hand-written
 * iterators lose what a native generator gets from `AsyncIteratorPrototype`;
@@ -1843,6 +1970,61 @@ function returningAtOnce(gen, abandon) {
 * tests and adapters assert on it.
 */
 const STREAM_ABORT = "webrun-rpc:stream-abort";
+/**
+* The `type` of a pipelined chunk: a plain port message, not a `callPort`
+* request, sent only on a port where both ends agreed `pipeline`. The window's
+* credit is its confirmation.
+*/
+const CHUNK = "webrun-rpc:chunk";
+/**
+* What a pipelined chunk counts beyond its bytes, against the window, on the
+* receiving side. Both codecs' windows count more for the chunk's envelope
+* (the estimate at least 64, msgpack's keys alone more than this), so an honest
+* sender never makes the receiver count past the window; a sender of empty
+* chunks still cannot have it hold an unbounded number of them.
+*/
+const CHUNK_OVERHEAD = 32;
+/**
+* The bytes of `view` as a plain `Uint8Array` that owns its whole buffer:
+* `view` itself when it already is one, else a copy. Structured clone carries
+* and keeps a view's whole `ArrayBuffer`, and a byte codec may decode into
+* views of the frame, while the window and the receiver's count see only the
+* view: a 4 KiB `subarray` of a 4 MiB buffer would cost 4 MiB per chunk.
+* Copied with the `Uint8Array` constructor, not `slice()`: a Node `Buffer`'s
+* `slice()` is another view on the same memory.
+*/
+function ownBytes(view) {
+	if (view instanceof Uint8Array && view.constructor === Uint8Array && view.byteOffset === 0 && view.byteLength === view.buffer.byteLength) return view;
+	return new Uint8Array(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+}
+/**
+* A producer's chunk as bytes this end may send, in either mode: any view or
+* `ArrayBuffer`, normalised by `ownBytes`. Anything else fails the stream here,
+* as the producer's own error, rather than reaching a peer that would refuse it.
+*/
+/**
+* A received confirmed chunk's value, as its own bytes, put back in place of
+* the original in `chunk`: `listenPort` keeps the request until the handler
+* returns, and the original would keep its whole buffer that long. A function
+* of its own, so that no temporary of the suspended handler holds the
+* original either.
+*/
+function adoptValue(chunk) {
+	const original = chunk.value;
+	if (ArrayBuffer.isView(original)) chunk.value = ownBytes(original);
+	return chunk.value;
+}
+function chunkBytes(value) {
+	if (ArrayBuffer.isView(value)) return ownBytes(value);
+	if (value instanceof ArrayBuffer || Object.prototype.toString.call(value) === "[object ArrayBuffer]") return new Uint8Array(value);
+	throw new TypeError(`webrun-rpc: a stream chunk must be bytes (a typed array, a DataView or an ArrayBuffer), got ${value === null ? "null" : typeof value}`);
+}
+const MIXED_MESSAGE = "webrun-rpc: peer mixed confirmed and pipelined chunks; the stream port is closed";
+/** This end may pipeline its own chunks: agreed, and the window holds them. */
+const mayPipeline = (port) => {
+	const agreement = portAgreement(port);
+	return !!agreement?.enforced && agreement.caps.has("pipeline");
+};
 /** 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. */
@@ -1855,7 +2037,9 @@ const CHANNEL_OUT = "out";
 * 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.
+* `listenPort` withholds it until then. On a port whose window both ends
+* speak and that agreed `pipeline`, chunks go as plain messages instead, and
+* the window's credit is the confirmation: up to a window is in flight.
 *
 * A stream port carries exactly one invocation. To make several calls, open
 * several ports: `mux.openPort({ kind: "stream" })` per call.
@@ -1872,22 +2056,49 @@ function serveDuplexOverPort(port, handler, options = {}) {
 	const notice = installAbortNotice(port, controller);
 	abortOnPortClose(port, controller);
 	const clock = installStreamTimeout(controller, options.timeout);
-	const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch);
+	const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch, notice);
 	let output;
 	try {
 		output = handler(inbound.stream);
 	} catch (err) {
-		const pump = sendChunks(port, CHANNEL_OUT, failing(err), options, controller.signal, clock.touch);
+		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);
+	let onSent = () => {};
+	const sent = new Promise((resolve) => {
+		onSent = resolve;
+	});
+	const pump = sendChunks(port, CHANNEL_OUT, output, options, controller.signal, clock.touch, onSent);
 	pump.catch(() => {});
 	disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+	endServedStream(port, sent, inbound.over);
 	return teardownOnce(controller, notice, clock, inbound, output);
 }
 /**
+* The serving side's normal finish. Once the handler's last chunk has gone
+* without an error, and no more input is coming (`over`: the caller's last
+* chunk arrived without an error and was read, or the caller ended its
+* direction behind it, for a handler that did not read all its input), this
+* side ends its direction too, where `end` was agreed. Without `end` nothing
+* happens here: the caller closes the port. A stream that never gets that far
+* was abandoned, and the caller's notice and `close` free the port; this then
+* never resumes. It needs no race against the port's close signal: nothing
+* awaits it, and what keeps it waiting is the input's watcher, a listener of
+* the port that a close drops, after which the wait is collected.
+*
+* Nothing this side still posts is lost behind its `end`. The caller ends only
+* once its own last chunk was confirmed, so no confirmation is owed to it
+* here, and what the freed port's close signal aborts has settled: the last
+* chunk has left, and input nobody reads is dropped, as on a close.
+*/
+async function endServedStream(port, sent, over) {
+	await sent;
+	await over;
+	endPort(port);
+}
+/**
 * 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
@@ -1927,22 +2138,31 @@ function runCallerSide(port, input, options) {
 	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);
+	const inbound = receiveChunks(port, CHANNEL_OUT, controller, clock.touch, notice);
+	let sent = false;
+	const pump = sendChunks(port, CHANNEL_IN, input, options, controller.signal, clock.touch, () => {
+		sent = true;
+	});
 	pump.catch(() => {});
 	return returningAtOnce((async function* () {
+		let received = false;
 		try {
 			yield* inbound.stream;
+			received = true;
 		} finally {
+			const ended = received && sent;
 			if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the caller abandoned the stream"));
-			notice.post();
+			if (!ended) notice.post();
 			notice.stop();
 			clock.stop();
 			inbound.stop();
 			await pump.catch(() => {});
-			try {
-				await port.close?.();
-			} catch {}
+			if (!(ended && endPort(port))) {
+				notice.post();
+				try {
+					await port.close?.();
+				} catch {}
+			}
 		}
 	})(), () => {
 		if (!controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("webrun-rpc: the caller abandoned the stream"));
@@ -2036,7 +2256,7 @@ function installStreamTimeout(controller, timeout) {
 * 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) {
+function receiveChunks(port, channelName, controller, touch, notice) {
 	let deliver;
 	const waiting = [];
 	let finished = false;
@@ -2046,25 +2266,64 @@ function receiveChunks(port, channelName, controller, touch) {
 	const ended = new Promise((resolve) => {
 		resolveEnded = resolve;
 	});
+	let resolveOver = () => {};
+	const over = new Promise((resolve) => {
+		resolveOver = 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 }) => {
+	const violate = (message) => {
+		poison = new Error(message);
+		controller.abort(poison);
+		setTimeout(() => {
+			try {
+				port.close?.();
+			} catch {}
+		}, 0);
+		return poison;
+	};
+	let lastChunkArrived = false;
+	let watching = false;
+	const watchPeerEnd = () => {
+		if (watching) return true;
+		if (!portAgreement(port)?.caps.has("end")) return false;
+		watching = true;
+		whenPortEnded(port).then(() => {
+			port.removeEventListener("message", watcher);
+			if (lastChunkArrived) {
+				resolveOver();
+				return;
+			}
+			notice.post();
+			violate("webrun-rpc: the peer ended its direction without finishing it; the stream port is closed");
+		});
+		return true;
+	};
+	const watcher = (event) => {
+		const data = event.data;
+		if (data?.channelName !== channelName) return;
+		const chunk = data.type === CHUNK ? data.chunk : data.type === "request" ? data.params : void 0;
+		if (!chunk) return;
+		if (!watchPeerEnd()) {
+			port.removeEventListener("message", watcher);
+			return;
+		}
+		if (chunk.done && !chunk.error) lastChunkArrived = true;
+	};
+	port.addEventListener("message", watcher);
+	watchPeerEnd();
+	let held = 0;
+	const off = listenPort(port, async (params) => {
+		const { done, error } = params;
+		const value = adoptValue(params);
 		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;
-		}
+		if (held > 0) throw violate(MIXED_MESSAGE);
+		if (outstanding) throw violate("webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed");
 		outstanding = true;
 		try {
 			await ready();
@@ -2074,15 +2333,60 @@ function receiveChunks(port, channelName, controller, touch) {
 				value,
 				error: error ? deserializeError(error) : void 0
 			});
+			if (done && !error) resolveOver();
 		} finally {
 			outstanding = false;
 		}
 		if (done) resolveEnded();
 	}, { channelName });
+	const onChunk = (event) => {
+		const data = event.data;
+		if (data?.type !== CHUNK || data.channelName !== channelName || !data.chunk) return;
+		if (poison) return;
+		const agreement = portAgreement(port);
+		if (!agreement?.caps.has("pipeline")) {
+			violate("webrun-rpc: peer sent a pipelined chunk where pipelining was not agreed");
+			return;
+		}
+		if (outstanding) {
+			violate(MIXED_MESSAGE);
+			return;
+		}
+		if (data.chunk.value !== void 0 && !ArrayBuffer.isView(data.chunk.value)) {
+			violate("webrun-rpc: peer sent a pipelined chunk whose value is not bytes");
+			return;
+		}
+		if (held > agreement.window) {
+			violate(`webrun-rpc: peer sent past the window (${agreement.window} bytes) without waiting for credit; the stream port is closed`);
+			return;
+		}
+		touch();
+		const { done, error } = data.chunk;
+		const value = data.chunk.value && ownBytes(data.chunk.value);
+		const size = (value?.byteLength ?? 0) + CHUNK_OVERHEAD;
+		held += size;
+		return (async () => {
+			try {
+				await ready();
+				if (finished) return;
+				await deliver?.({
+					done,
+					value,
+					error: error ? deserializeError(error) : void 0
+				});
+				if (done && !error) resolveOver();
+				if (done) resolveEnded();
+			} finally {
+				held -= size;
+			}
+		})();
+	};
+	port.addEventListener("message", onChunk);
 	const detach = () => {
 		finished = true;
 		wake();
 		off();
+		port.removeEventListener("message", onChunk);
 		controller.signal.removeEventListener("abort", onAbort);
 		resolveEnded();
 	};
@@ -2112,21 +2416,35 @@ function receiveChunks(port, channelName, controller, touch) {
 			return detach;
 		}),
 		stop: detach,
-		ended
+		ended,
+		over
 	};
 }
 /**
 * 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).
+* outstanding at a time (spec D11/D12), with no per-chunk deadline (spec D8) —
+* or, once pipelining is agreed, plain chunk messages held back by the window.
+* `onSent` runs once the end of the output has left without an error: posted
+* when pipelined, confirmed when not.
 */
-async function sendChunks(port, channelName, output, { maxMessageSize, log }, signal, touch) {
-	const stream = throughAbort(maxMessageSize ? toChunks(maxMessageSize)(output) : output, signal);
+async function sendChunks(port, channelName, output, { maxMessageSize, log }, signal, touch, onSent) {
+	const framed = maxMessageSize ? toChunks(maxMessageSize)(output) : output;
+	const stream = throughAbort(framed, signal);
+	const producer = output;
+	const returnProducer = () => void Promise.resolve(producer.return?.()).catch(() => {});
+	if (framed !== output) signal.addEventListener("abort", returnProducer, { once: true });
+	let onAborted = () => {};
+	const aborted = new Promise((resolve) => {
+		onAborted = () => resolve();
+	});
+	if (signal.aborted) onAborted();
+	else signal.addEventListener("abort", onAborted, { once: true });
 	try {
 		await sendIterator(async ({ done, value, error }) => {
 			if (signal.aborted) return;
 			const chunk = {
 				done,
-				value,
+				value: done ? value : chunkBytes(value),
 				error: error === void 0 ? void 0 : serializeError(error)
 			};
 			log?.("[duplexOverPort] send", {
@@ -2134,46 +2452,34 @@ async function sendChunks(port, channelName, output, { maxMessageSize, log }, si
 				done,
 				size: value?.byteLength
 			});
+			if (mayPipeline(port)) {
+				port.postMessage({
+					type: CHUNK,
+					channelName,
+					chunk
+				});
+				touch();
+				if (done && !error) onSent();
+				if (portBufferedAmount(port) > 0) await Promise.race([whenPortReady(port), aborted]);
+				return;
+			}
 			await callPort(port, chunk, {
 				channelName,
 				timeout: NO_TIMEOUT,
 				signal
 			});
 			touch();
+			if (done && !error) onSent();
 		}, stream);
 	} catch (err) {
 		if (signal.aborted) return;
 		throw err;
+	} finally {
+		signal.removeEventListener("abort", returnProducer);
+		signal.removeEventListener("abort", onAborted);
 	}
 }
 /**
-* Runs `fn` on a later task, never a microtask: a producer looping on
-* `whenPortReady` must let the transport's own events run. `setImmediate`
-* where it exists; elsewhere a `MessageChannel`, because nested `setTimeout`s
-* are clamped to 4 ms in browsers.
-*/
-const setImmediateFn = globalThis.setImmediate;
-/** @internal */
-const nextTask = setImmediateFn ? (fn) => {
-	setImmediateFn(fn);
-} : (() => {
-	let channel;
-	const queue = [];
-	return (fn) => {
-		if (!channel) {
-			channel = new MessageChannel();
-			channel.port1.onmessage = () => queue.shift()?.();
-		}
-		queue.push(fn);
-		channel.port2.postMessage(0);
-	};
-})();
-const states = /* @__PURE__ */ new WeakMap();
-/** @internal Registered by the multiplexer for each port with a window. */
-function setPortSendState(port, state) {
-	states.set(port, state);
-}
-/**
 * One virtual port.
 *
 * `deliver` and `markClosed` are deliberately not on `port`: the consumer holds
@@ -2251,6 +2557,21 @@ function newVirtualPort(send, requestClose) {
 const KEEPALIVE_ID = Number.MAX_SAFE_INTEGER;
 /** The longest delay a timer holds; past it `setInterval` fires at once. */
 const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+* What a windowed port offers in its `open`: every capability this end
+* speaks. `end` only over a codec that reads it (`PortCodec.halfClose`).
+*/
+function ownCaps(codec) {
+	return codec.halfClose ? ["pipeline", "end"] : ["pipeline"];
+}
+/**
+* The capabilities in a peer's `caps` that this end speaks too, or
+* `undefined` when the peer listed none (it is then treated as an older peer).
+*/
+function sharedCaps(own, listed) {
+	if (!Array.isArray(listed)) return void 0;
+	return new Set(own.filter((cap) => listed.includes(cap)));
+}
 /** Ceiling on concurrently open virtual ports. Bounds the id table only. */
 const DEFAULT_MAX_PORTS = 1024;
 /**
@@ -2282,10 +2603,18 @@ function estimateMessageSize(payload) {
 */
 function multiplexPort(port, options) {
 	const { codec, onPort, side = "initiator", maxPorts = DEFAULT_MAX_PORTS, maxMessageSize, signal, window, frameSize, keepalive, onLeak } = options;
+	const maxReassembledBytes = options.maxReassembledBytes ?? 67108864;
 	const misses = keepalive?.misses ?? 3;
 	if (keepalive && !(Number.isFinite(keepalive.intervalMs) && keepalive.intervalMs > 0 && keepalive.intervalMs <= MAX_TIMER_MS && Number.isSafeInteger(misses) && misses > 0)) throw new RangeError(`webrun-rpc: keepalive needs an intervalMs in (0, ${MAX_TIMER_MS}] and a positive integer misses`);
 	if (frameSize != null && !(Number.isSafeInteger(frameSize) && frameSize > 0)) throw new RangeError(`webrun-rpc: frameSize must be a positive integer, got ${frameSize}`);
+	if (!(Number.isSafeInteger(maxReassembledBytes) && maxReassembledBytes > 0)) throw new RangeError(`webrun-rpc: maxReassembledBytes must be a positive integer, got ${maxReassembledBytes}`);
 	const open = /* @__PURE__ */ new Map();
+	let reassembling = 0;
+	const freePartial = (entry) => {
+		if (!entry?.partial) return;
+		reassembling -= entry.partial.charged;
+		entry.partial = void 0;
+	};
 	const leaks = onLeak ? new FinalizationRegistry(({ id, record, release }) => {
 		const entry = open.get(id);
 		if (entry?.handle !== record) return;
@@ -2306,6 +2635,8 @@ function multiplexPort(port, options) {
 	let muxClosed = false;
 	/** This end counts encoded bytes and reassembles frames. */
 	const exactCodec = codec.encode != null && codec.decode != null;
+	/** What this end offers on a windowed port. */
+	const caps = ownCaps(codec);
 	const post = (envelope, transfer) => {
 		if (muxClosed) return;
 		codecPost(envelope, transfer);
@@ -2363,13 +2694,39 @@ function multiplexPort(port, options) {
 			port.postMessage(bytes);
 		} catch {}
 	};
+	/**
+	* Both directions have ended: free the id as a close would, with no `close`
+	* on the wire (each end frees it on its own once it has seen both ends).
+	* Aborting the close signal is how the port's consumer learns it is gone.
+	*/
+	const freeIfEnded = (id, c) => {
+		const entry = open.get(id);
+		if (!c.endSent || !c.peerEnded || entry?.credit !== c) return;
+		freePartial(entry);
+		open.delete(id);
+		leaks?.unregister(entry.handle);
+		entry.handle.markClosed(/* @__PURE__ */ new Error("webrun-rpc: the port ended in both directions"));
+	};
+	/** A peer that broke the port's protocol: hold none of its traffic, and close. */
+	const failPort = (id, entry, error, reason) => {
+		freePartial(entry);
+		dropOutgoing(id);
+		open.delete(id);
+		releaseWaiters(entry.credit);
+		entry.handle.markClosed(error);
+		post({
+			type: "close",
+			id,
+			reason
+		});
+	};
 	const releaseWaiters = (c) => {
 		for (const w of c?.waiters.splice(0) ?? []) w.resolve();
 	};
 	const flush = (c) => {
 		while (c.queue.length) {
 			const next = c.queue[0];
-			if (c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window) break;
+			if (next.size > 0 && c.enforced && c.outstanding > 0 && c.outstanding + next.size > c.window) break;
 			c.queue.shift();
 			c.queued -= next.size;
 			c.outstanding += next.size;
@@ -2407,15 +2764,20 @@ function multiplexPort(port, options) {
 			enforced: false,
 			opener,
 			exact,
+			caps: /* @__PURE__ */ new Set(),
 			outstanding: 0,
 			queue: [],
 			queued: 0,
 			unconsumed: 0,
 			waiters: [],
 			toGrant: 0,
-			grantScheduled: false
+			grantScheduled: false,
+			ending: false,
+			endSent: false,
+			peerEnded: false
 		} : void 0;
 		const self = newVirtualPort((payload, transfer) => {
+			if (c?.ending) return;
 			touch(id);
 			const envelope = {
 				type: "message",
@@ -2433,12 +2795,12 @@ function multiplexPort(port, options) {
 				...envelope,
 				payload: structuredClone(payload, { transfer })
 			} : void 0;
-			const send = () => {
+			const send = (whole = false) => {
 				if (!bytes) {
 					sendOnPort(id, held ? () => post(held) : () => post(envelope, transfer));
 					return;
 				}
-				if (frameSize != null && c.enforced && c.exact && bytes.byteLength > frameSize) {
+				if (!whole && frameSize != null && c.enforced && c.exact && bytes.byteLength > frameSize) {
 					for (let at = 0; at < bytes.byteLength; at += frameSize) {
 						const data = bytes.subarray(at, at + frameSize);
 						const frame = at + frameSize >= bytes.byteLength ? {
@@ -2468,10 +2830,11 @@ function multiplexPort(port, options) {
 			record.markClosed(reason);
 		});
 		function release(reason) {
+			freePartial(open.get(id));
 			open.delete(id);
 			leaks?.unregister(record);
 			if (c?.queue.length) {
-				for (const item of c.queue.splice(0)) item.send();
+				for (const item of c.queue.splice(0)) item.send(true);
 				c.queued = 0;
 			}
 			sendOnPort(id, () => post({
@@ -2501,6 +2864,38 @@ function multiplexPort(port, options) {
 					});
 				})
 			});
+			setPortEndState(self.port, {
+				end: () => {
+					if (isClosed() || !c.caps.has("end")) return false;
+					if (c.ending) return true;
+					c.ending = true;
+					c.queue.push({
+						size: 0,
+						send: () => sendOnPort(id, () => {
+							if (open.get(id)?.credit !== c) return;
+							post({
+								type: "end",
+								id
+							});
+							c.endSent = true;
+							freeIfEnded(id, c);
+						})
+					});
+					flush(c);
+					return true;
+				},
+				watchPeerEnd: (resolve) => {
+					if (!c.caps.has("end")) return false;
+					if (c.peerEnded) resolve();
+					else c.onPeerEnd = new WeakRef(resolve);
+					return true;
+				}
+			});
+			setPortAgreement(self.port, () => ({
+				window: c.window,
+				caps: c.caps,
+				enforced: c.enforced
+			}));
 		}
 		const record = {
 			deliver: self.deliver,
@@ -2552,16 +2947,24 @@ function multiplexPort(port, options) {
 			}
 			const handle = attach(envelope.id, envelope.meta, envelope.window, false, envelope.exact === true && exactCodec);
 			const credit = open.get(envelope.id)?.credit;
-			if (credit) post(credit.exact ? {
-				type: "credit",
-				id: envelope.id,
-				bytes: 0,
-				exact: true
-			} : {
-				type: "credit",
-				id: envelope.id,
-				bytes: 0
-			});
+			const listed = sharedCaps(caps, envelope.caps);
+			if (credit) {
+				const ack = credit.exact ? {
+					type: "credit",
+					id: envelope.id,
+					bytes: 0,
+					exact: true
+				} : {
+					type: "credit",
+					id: envelope.id,
+					bytes: 0
+				};
+				if (listed) credit.caps = listed;
+				post(listed ? {
+					...ack,
+					caps: [...listed]
+				} : ack);
+			}
 			let accepted = false;
 			if (onPort) try {
 				accepted = onPort(handle.port, envelope.meta) !== false;
@@ -2589,6 +2992,7 @@ function multiplexPort(port, options) {
 					c.exact = false;
 					c.outstanding = 0;
 				}
+				c.caps = sharedCaps(caps, envelope.caps) ?? /* @__PURE__ */ new Set();
 				post({
 					type: "credit",
 					id: envelope.id,
@@ -2600,6 +3004,10 @@ function multiplexPort(port, options) {
 			flush(c);
 			return;
 		}
+		if ((envelope.type === "message" || envelope.type === "frame") && entry?.credit?.peerEnded) {
+			failPort(envelope.id, entry, /* @__PURE__ */ new Error("webrun-rpc: the peer sent on a port after its end"), "protocol");
+			return;
+		}
 		if (envelope.type === "message") {
 			const sizeOf = (c) => (c.exact ? byteLengthOf(event.data) : void 0) ?? estimateMessageSize(envelope.payload);
 			if (!entry) return;
@@ -2610,15 +3018,29 @@ function multiplexPort(port, options) {
 		if (envelope.type === "frame") {
 			if (!entry?.credit?.exact || !codec.decode || !(envelope.data instanceof Uint8Array)) return;
 			touch(envelope.id);
+			const c = entry.credit;
+			const owed = c.unconsumed + c.toGrant;
 			const partial = entry.partial ?? {
 				chunks: [],
-				bytes: 0
+				bytes: 0,
+				owed,
+				charged: 0,
+				...owed > 0 ? { room: c.window - owed } : {}
 			};
 			entry.partial = partial;
+			const size = envelope.data.byteLength;
+			const charged = partial.room == null ? Math.max(0, partial.bytes + size - c.window) : 0;
+			const overrun = partial.room != null && partial.bytes + size > partial.room ? `what the window left (${partial.room} of ${c.window} bytes, ${partial.owed} still owed)` : reassembling - partial.charged + charged > maxReassembledBytes ? `maxReassembledBytes (${maxReassembledBytes} bytes past the window, across all ports)` : void 0;
+			if (overrun) {
+				failPort(envelope.id, entry, /* @__PURE__ */ new RangeError(`webrun-rpc: a framed message passed ${overrun}`), "max-reassembled-bytes");
+				return;
+			}
+			partial.bytes += size;
+			reassembling += charged - partial.charged;
+			partial.charged = charged;
 			partial.chunks.push(envelope.data);
-			partial.bytes += envelope.data.byteLength;
 			if (!envelope.last) return;
-			entry.partial = void 0;
+			freePartial(entry);
 			const whole = new Uint8Array(partial.bytes);
 			let at = 0;
 			for (const chunk of partial.chunks) {
@@ -2630,8 +3052,22 @@ function multiplexPort(port, options) {
 			entry.handle.deliver(inner.payload, whole.byteLength);
 			return;
 		}
+		if (envelope.type === "end") {
+			if (!entry) return;
+			const c = entry.credit;
+			if (!c?.caps.has("end")) {
+				failPort(envelope.id, entry, /* @__PURE__ */ new Error("webrun-rpc: the peer ended a port where end was not agreed"), "protocol");
+				return;
+			}
+			touch(envelope.id);
+			c.peerEnded = true;
+			c.onPeerEnd?.deref()?.();
+			freeIfEnded(envelope.id, c);
+			return;
+		}
 		dropOutgoing(envelope.id);
 		if (!entry) return;
+		freePartial(entry);
 		open.delete(envelope.id);
 		releaseWaiters(entry.credit);
 		entry.handle.markClosed(/* @__PURE__ */ new Error("webrun-rpc: the peer closed the port"));
@@ -2710,12 +3146,14 @@ function multiplexPort(port, options) {
 				id,
 				meta,
 				window,
-				exact: true
+				exact: true,
+				caps: [...caps]
 			} : {
 				type: "open",
 				id,
 				meta,
-				window
+				window,
+				caps: [...caps]
 			} : {
 				type: "open",
 				id,
@@ -2822,14 +3260,17 @@ const serve = async ({ mux: factory, timeout }, handler) => {
 	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);
-			}
-		})();
+		const tracked = (input) => {
+			const output = handler(input);
+			return returningAtOnce((async function* () {
+				try {
+					yield* output;
+				} finally {
+					finished = true;
+					if (off) live.delete(off);
+				}
+			})(), () => void output.return(void 0).catch(() => {}));
+		};
 		off = serveDuplexOverPort(port, tracked, streamOptions);
 		if (!finished) live.add(off);
 	});
@@ -2867,7 +3308,7 @@ function isEnvelope(value) {
 	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" || candidate.type === "credit" || candidate.type === "frame" || candidate.type === "ping" || candidate.type === "pong";
+	return candidate.type === "open" || candidate.type === "message" || candidate.type === "close" || candidate.type === "credit" || candidate.type === "frame" || candidate.type === "ping" || candidate.type === "pong" || candidate.type === "end";
 }
 /**
 * For ports whose messages are structured values — a real `MessagePort`, a
@@ -2879,6 +3320,7 @@ function isEnvelope(value) {
 * not send anything a byte codec could not also carry.
 */
 const structuredCodec = {
+	halfClose: true,
 	post(port, envelope, transfer) {
 		if (transfer && transfer.length > 0) port.postMessage(envelope, transfer);
 		else port.postMessage(envelope);
@@ -2916,10 +3358,15 @@ function asyncDisposable(target, dispose) {
 * 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.
+* multiplexed on it, each call a stream with backpressure in both
+* directions, and cancellation that reaches the handler. A call's port with a
+* window (`HttpLinkOptions.window`) pipelines its chunks where both ends speak
+* it, and goes one confirmed chunk at a time otherwise, so the window needs
+* no new version.
 */
 const HTTP_LINK_PROTOCOL = "webrun-http-link/2";
+/** The calling end's default `HttpLinkOptions.window`: 256 KiB. */
+const DEFAULT_HTTP_LINK_WINDOW = 262144;
 /**
 * 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
@@ -2938,12 +3385,13 @@ var LinkLostError = class extends Error {
 */
 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, maxPorts } = {}) {
+async function connectHttpLink(port, { streamTimeout, maxPorts, window = DEFAULT_HTTP_LINK_WINDOW } = {}) {
 	const { call, close } = await connect({
 		mux: overPipe(port, {
 			codec: structuredCodec,
 			side: "initiator",
-			maxPorts
+			maxPorts,
+			window
 		}),
 		timeout: streamTimeout
 	});
@@ -3399,6 +3847,7 @@ var PortSocketCore = class extends EventTarget {
 			code,
 			reason
 		});
+		if (!Number.isFinite(this._closeTimeoutMs)) return;
 		this._closeTimer = this._timers.setTimeout(() => this._finish(1006, "", false), this._closeTimeoutMs);
 	}
 	_onCloseFrame(code, reason) {
@@ -3764,7 +4213,8 @@ var PortRendezvous = class {
 *   `whenDrained(limit)` waits for it to fall: the backpressure a producer
 *   applies.
 * - When the client's pings stop for three heartbeat periods (a closed tab, a
-*   terminated worker), the socket closes with 1006.
+*   terminated worker), the socket closes with 1006. With `watch: "first-ping"`
+*   the watch starts only once the client pings.
 */
 var ServerWebSocket = class extends PortSocketCore {
 	static CONNECTING = 0;
@@ -3773,55 +4223,150 @@ var ServerWebSocket = class extends PortSocketCore {
 	static CLOSED = 3;
 	url;
 	protocol;
+	_binaryType = "arraybuffer";
+	_options;
 	_accepted = false;
+	_detached = false;
 	_queue = [];
 	_heartbeatMs = DEFAULT_HEARTBEAT_MS;
 	_lastPing = Date.now();
+	/** Whether a ping (with a period a timer takes) arrived already. */
+	_pinged = false;
 	_watch;
 	constructor(port, options = {}) {
 		super({
 			timers: options.timers,
 			closeTimeoutMs: options.closeTimeoutMs
 		});
+		this._options = options;
 		this.url = options.url ?? "";
 		this.protocol = options.protocol ?? "";
 		this._attach(port);
 		this._state = 1;
-		this._watchHeartbeat();
+		if (options.watch !== "first-ping") this._watchHeartbeat();
 	}
 	/** Whether `accept()` was called. */
 	get accepted() {
 		return this._accepted;
 	}
+	/** How binary messages arrive: `ArrayBuffer`s (the default) or `Blob`s. Other values are ignored. */
+	get binaryType() {
+		return this._binaryType;
+	}
+	set binaryType(value) {
+		if (value === "blob" || value === "arraybuffer") this._binaryType = value;
+	}
+	/**
+	* Hands this end's transport to another holder before it was accepted: the port to give the
+	* client (a pair's end returned in a 101, say), with the frames that reached this end first
+	* delivered ahead of the rest. This end is closed then, with no event, and answers nothing.
+	*/
+	detach() {
+		const port = this._port;
+		if (!port || this._accepted || this._state !== 1) throw new DOMException("Only an open end that was not accepted can be detached.", "InvalidStateError");
+		this._detached = true;
+		this._port = void 0;
+		port.onmessage = null;
+		let owed = this.bufferedAmount;
+		this._state = 3;
+		this._onClosed();
+		this._wakeDrainWaiters();
+		const queued = this._queue.splice(0);
+		if (queued.length === 0 && owed === 0) return port;
+		const relay = new MessageChannel();
+		const holder = relay.port2;
+		const closing = /* @__PURE__ */ new Set();
+		const end = () => {
+			port.onmessage = null;
+			holder.onmessage = null;
+			port.close();
+			holder.close();
+		};
+		const sawClose = (way) => {
+			closing.add(way);
+			if (closing.size === 2) end();
+		};
+		for (const frame of queued) {
+			postFrame(holder, frame);
+			if (frame.t === "c") closing.add("in");
+		}
+		holder.onmessage = (event) => {
+			port.postMessage(event.data, transferables(event.data));
+			if (event.data?.t === "c") sawClose("out");
+		};
+		port.onmessage = (event) => {
+			const data = event.data;
+			if (data?.t === "a" && typeof data.n === "number" && owed > 0) {
+				const absorbed = Math.min(owed, data.n);
+				owed -= absorbed;
+				if (data.n > absorbed) holder.postMessage({
+					t: "a",
+					n: data.n - absorbed
+				});
+				return;
+			}
+			holder.postMessage(event.data, transferables(event.data));
+			if (data?.t === "c") sawClose("in");
+		};
+		port.addEventListener?.("close", end);
+		holder.addEventListener?.("close", end);
+		return relay.port1;
+	}
 	/** Starts delivering events, the queued ones first. */
 	accept() {
+		if (this._detached) throw new DOMException("This end was detached; it cannot be accepted.", "InvalidStateError");
 		if (this._accepted) return;
 		this._accepted = true;
-		for (const frame of this._queue.splice(0)) super._deliver(frame);
+		for (const frame of this._queue.splice(0)) this._deliver(frame);
 	}
 	send(data) {
-		if (!this._accepted) throw new DOMException("accept() the socket before sending on it.", "InvalidStateError");
+		if (this._detached) throw new DOMException("This end was detached; it cannot send.", "InvalidStateError");
+		if (!this._accepted && !this._options.sendBeforeAccept) throw new DOMException("accept() the socket before sending on it.", "InvalidStateError");
 		this._sendData(isBinary(data) ? toArrayBuffer(data) : String(data));
 	}
-	close(code = 1e3, reason = "") {
-		if (!isSendableCloseCode(code)) throw new DOMException(`${code} is not a close code an endpoint may send.`, "InvalidAccessError");
+	close(code, reason = "") {
+		this.checkClose(code, reason);
+		this._startClose(code ?? this._options.defaultCloseCode ?? 1e3, reason);
+	}
+	/**
+	* Refuses a `close()` the endpoint may not make: by default a code outside RFC 6455 §7.4's
+	* sendable ones, or a reason over 123 bytes. A subclass with another platform's rules
+	* overrides it.
+	*/
+	checkClose(code, reason) {
+		if (code !== void 0 && !isSendableCloseCode(code)) throw new DOMException(`${code} is not a close code an endpoint may send.`, "InvalidAccessError");
 		if (utf8Length(reason) > 123) throw new DOMException("The close reason is longer than 123 bytes.", "SyntaxError");
-		this._startClose(code, reason);
 	}
 	_deliver(frame) {
 		if (!this._accepted) {
 			this._queue.push(frame);
 			return;
 		}
+		if (frame.t === "m" && this._state === 2 && this._options.deliverWhileClosing) {
+			this._dispatchMessage(frame.d);
+			this._consumed(messageSize(frame.d));
+			return;
+		}
 		super._deliver(frame);
 	}
 	_dispatchMessage(data) {
-		this.dispatchEvent(new MessageEvent("message", { data }));
+		const delivered = typeof data !== "string" && this._binaryType === "blob" ? new Blob([data]) : data;
+		this.dispatchEvent(new MessageEvent("message", { data: delivered }));
 	}
 	_onPing(hb) {
 		this._post({ t: "q" });
 		this._lastPing = Date.now();
-		if (hb !== this._heartbeatMs) {
+		if (this._state === 3) return;
+		const keep = this._options.heartbeatPeriod === "first" && this._pinged;
+		if (!(hb > 0 && hb < 2 ** 31 - 1)) {
+			if (!keep && this._watch !== void 0) {
+				this._timers.clearInterval(this._watch);
+				this._watch = void 0;
+			}
+			return;
+		}
+		this._pinged = true;
+		if (!keep && (this._watch === void 0 || hb !== this._heartbeatMs)) {
 			this._heartbeatMs = hb;
 			this._watchHeartbeat();
 		}
@@ -3843,6 +4388,11 @@ function isSendableCloseCode(code) {
 	if (code >= 3e3 && code <= 4999) return true;
 	return code >= 1e3 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006;
 }
+/** The buffers a relayed frame carries, to transfer rather than copy. */
+function transferables(data) {
+	const d = data?.d;
+	return d instanceof ArrayBuffer ? [d] : [];
+}
 //#endregion
 //#region src/ws/upgrade.ts
 /**
@@ -3874,6 +4424,7 @@ function newWebSocketUpgradeRequest(url, { protocols = [], headers } = {}) {
 	all.set("connection", "Upgrade");
 	all.set("sec-websocket-version", "13");
 	if (!all.has("sec-websocket-key")) all.set("sec-websocket-key", randomKey());
+	all.delete("sec-websocket-protocol");
 	if (protocols.length > 0) all.set("sec-websocket-protocol", protocols.join(", "));
 	if (!all.has("x-webrun-ws-version")) all.set(WS_VERSION_HEADER, `2`);
 	return withHeaders(new Request(httpUrl, {
@@ -3933,6 +4484,23 @@ function upgradeWebSocket(request, options = {}) {
 		url: request.url,
 		protocol
 	});
+	const response = webSocketUpgradeResponse(channel.port2, protocol);
+	Object.defineProperty(response, "webSocket", {
+		value: socket,
+		configurable: true
+	});
+	return {
+		socket,
+		response
+	};
+}
+/**
+* A 101 for a socket whose server end the handler runs itself, on the other end of `port`
+* (a server of its own over this package's frames, say): what `upgradeWebSocket` returns, minus
+* the `ServerWebSocket`. The host hands `port` to the caller as it would for `upgradeWebSocket`
+* (`takePort`), and `protocol` (`""` for none) is the subprotocol picked.
+*/
+function webSocketUpgradeResponse(port, protocol = "") {
 	const response = new Response(null, {
 		status: 200,
 		headers: protocol ? { "sec-websocket-protocol": protocol } : {}
@@ -3946,23 +4514,16 @@ function upgradeWebSocket(request, options = {}) {
 			value: "Switching Protocols",
 			configurable: true
 		},
-		webSocket: {
-			value: socket,
-			configurable: true
-		},
 		[UPGRADE]: {
 			value: {
-				port: channel.port2,
+				port,
 				protocol
 			},
 			configurable: true,
 			writable: true
 		}
 	});
-	return {
-		socket,
-		response
-	};
+	return response;
 }
 /**
 * The port to hand to the caller, for a response from `upgradeWebSocket`.
@@ -4029,6 +4590,15 @@ function randomKey() {
 	crypto.getRandomValues(bytes);
 	return btoa(String.fromCharCode(...bytes));
 }
+/** `headers` as pairs a `postMessage` can carry (a `Headers` object cannot be cloned). */
+function headerPairs(headers) {
+	if (headers === void 0) return void 0;
+	const pairs = [];
+	new Headers(headers).forEach((value, name) => {
+		pairs.push([name, value]);
+	});
+	return pairs;
+}
 //#endregion
 //#region src/sw/handler-endpoint.ts
 /** The message calls through a lost ServiceWorker fail with. */
@@ -4113,8 +4683,11 @@ var HandlerEndpoint = class {
 		this._startKeepAlive();
 		return await link.up.send(request);
 	}
-	/** Opens a socket to the handler `url` routes to, through the ServiceWorker. */
-	async connectWebSocket(url, protocols = []) {
+	/**
+	* Opens a socket to the handler `url` routes to, through the ServiceWorker. The handler sees
+	* `headers` on the upgrade request, and so does a `route` function choosing it.
+	*/
+	async connectWebSocket(url, protocols = [], headers) {
 		const link = await this._linkWith("ctl");
 		const id = this._sockets.newId();
 		const answer = this._sockets.wait(id, this.options.wsConnectTimeoutMs ?? 15e3, `the socket request for ${url}`);
@@ -4122,7 +4695,8 @@ var HandlerEndpoint = class {
 			t: "ws-open",
 			id,
 			url,
-			protocols
+			protocols,
+			headers: headerPairs(headers)
 		});
 		return await answer;
 	}
@@ -4292,11 +4866,11 @@ function serveHttpInWorker(handler, options = {}) {
 	};
 	scope.addEventListener("message", onMessage);
 	const baseUrl = () => globalThis.location?.href;
-	const connectWebSocket = (url, protocols = []) => {
+	const connectWebSocket = (url, protocols = [], headers) => {
 		const httpUrl = new URL(`${url}`, baseUrl());
 		if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
 		else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
-		return endpoint.connectWebSocket(`${httpUrl}`, protocols);
+		return endpoint.connectWebSocket(`${httpUrl}`, protocols, headers);
 	};
 	let WebSocketClass;
 	return {
@@ -4323,4 +4897,4 @@ function serveHttpInWorker(handler, options = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_HEARTBEAT_MS, HTTP_LINK_PROTOCOL, LinkLostError, ServerWebSocket, WS_PORT_PROTOCOL_VERSION, WS_VERSION_HEADER, WsCloseEvent, connectHttpLink, createWebSocketClass, isWebSocketUpgrade, newWebSocketUpgradeRequest, requestedProtocols, serveHttpInWorker, serveHttpLink, serveWebSocketUpgrade, takePort, takeUpgrade, trackedLink, upgradeWebSocket, withHeaders };
+export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_HEARTBEAT_MS, HTTP_LINK_PROTOCOL, LinkLostError, ServerWebSocket, WS_PORT_PROTOCOL_VERSION, WS_VERSION_HEADER, WsCloseEvent, connectHttpLink, createWebSocketClass, isWebSocketUpgrade, newWebSocketUpgradeRequest, requestedProtocols, serveHttpInWorker, serveHttpLink, serveWebSocketUpgrade, takePort, takeUpgrade, trackedLink, upgradeWebSocket, webSocketUpgradeResponse, withHeaders };