@statewalker/webrun-http-browser 0.10.0 → 0.12.2

package/dist/sw-worker.js

@@ -428,8 +428,9 @@
 	* Returns a function that stops answering.
 	*/
 	function handleClaimRequests(self) {
-		return handleChannelCalls(self, CLAIM_CALL, (event) => {
-			const claimed = self.clients.claim().then(() => true);
+		const sw = self;
+		return handleChannelCalls(sw, CLAIM_CALL, (event) => {
+			const claimed = sw.clients.claim().then(() => true);
 			event.waitUntil?.(claimed);
 			return claimed;
 		});
@@ -2251,6 +2252,99 @@
 		}
 	}
 	/**
+	* 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`;
@@ -2322,6 +2416,61 @@
 	* 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. */
@@ -2334,7 +2483,9 @@
 	* 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.
@@ -2351,22 +2502,49 @@
 		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
@@ -2406,22 +2584,31 @@
 		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"));
@@ -2515,7 +2702,7 @@
 	* 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;
@@ -2525,25 +2712,64 @@
 		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();
@@ -2553,15 +2779,60 @@
 					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();
 		};
@@ -2591,25 +2862,35 @@
 				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) {
+	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", {
@@ -2617,48 +2898,34 @@
 					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
@@ -2736,6 +3003,21 @@
 	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;
 	/**
@@ -2799,6 +3081,8 @@
 		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);
@@ -2856,13 +3140,39 @@
 				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;
@@ -2900,15 +3210,20 @@
 				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",
@@ -2995,6 +3310,38 @@
 						});
 					})
 				});
+				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,
@@ -3046,16 +3393,24 @@
 				}
 				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;
@@ -3083,6 +3438,7 @@
 						c.exact = false;
 						c.outstanding = 0;
 					}
+					c.caps = sharedCaps(caps, envelope.caps) ?? /* @__PURE__ */ new Set();
 					post({
 						type: "credit",
 						id: envelope.id,
@@ -3094,6 +3450,10 @@
 				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;
@@ -3118,16 +3478,7 @@
 				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) {
-					freePartial(entry);
-					dropOutgoing(envelope.id);
-					open.delete(envelope.id);
-					releaseWaiters(c);
-					entry.handle.markClosed(/* @__PURE__ */ new RangeError(`webrun-rpc: a framed message passed ${overrun}`));
-					post({
-						type: "close",
-						id: envelope.id,
-						reason: "max-reassembled-bytes"
-					});
+					failPort(envelope.id, entry, /* @__PURE__ */ new RangeError(`webrun-rpc: a framed message passed ${overrun}`), "max-reassembled-bytes");
 					return;
 				}
 				partial.bytes += size;
@@ -3147,6 +3498,19 @@
 				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);
@@ -3228,12 +3592,14 @@
 					id,
 					meta,
 					window,
-					exact: true
+					exact: true,
+					caps: [...caps]
 				} : {
 					type: "open",
 					id,
 					meta,
-					window
+					window,
+					caps: [...caps]
 				} : {
 					type: "open",
 					id,
@@ -3388,7 +3754,7 @@
 		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
@@ -3400,6 +3766,7 @@
 	* 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);
@@ -3437,10 +3804,15 @@
 	* 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
@@ -3459,12 +3831,13 @@
 	*/
 	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
 		});
@@ -3775,6 +4148,7 @@
 		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, {
@@ -3907,6 +4281,21 @@
 	const NEED_LINKS_CALL = "webrun-http:need-links";
 	//#endregion
 	//#region src/sw/http-sw-dispatcher.ts
+	/**
+	* The default key: the url's first path segment under `scope`, decoded; none outside it, at the
+	* scope itself, or for a segment that does not decode.
+	*/
+	function scopeKey(url, scope) {
+		const href = `${url}`;
+		if (!href.startsWith(scope)) return void 0;
+		const key = href.substring(scope.length).replace(/[?#].*$/, "").split("/")[0];
+		if (!key) return void 0;
+		try {
+			return decodeURIComponent(key);
+		} catch {
+			return;
+		}
+	}
 	/** One attached handler link, as the ServiceWorker holds it. */
 	var HandlerEntry = class {
 		key;
@@ -3946,7 +4335,8 @@
 	* (`SwHttpAdapter.register`) or in Dedicated Workers
 	* (`SwHttpAdapter.attachWorker` + `serveHttpInWorker`).
 	*
-	* A url `<scope>/<key>/...` belongs to the handlers of `key`. Of those, the
+	* A url `<scope>/<key>/...` belongs to the handlers of `key` (the `key`
+	* option maps urls to keys some other way). Of those, the
 	* `route` option picks one per request. Requests and responses stream with
 	* backpressure in both directions, and an aborted fetch reaches the handler
 	* as a cancellation (webrun-rpc + webrun-http-streams).
@@ -3965,6 +4355,8 @@
 	*/
 	var SwHttpDispatcher = class {
 		self;
+		/** `self`, with the WebWorker lib's types this module compiles with. */
+		_sw;
 		log;
 		options;
 		table = new HandlerTable();
@@ -3987,19 +4379,22 @@
 		constructor(options) {
 			this.options = options;
 			this.self = options.self;
+			this._sw = options.self;
 			this.log = options.log ?? (() => {});
 			if (locksAvailable()) this.routerLock = newLockName("webrun-http-router");
 		}
 		get scope() {
-			return `${new URL("./", this.self.location.href)}`;
+			return this._sw.registration?.scope ?? `${new URL("./", this._sw.location.href)}`;
 		}
-		/** The key `url` belongs to: its first path segment under the scope. */
+		/** The key `url` belongs to (the `key` option; by default its first path segment under the scope). */
 		keyOf(url) {
-			const href = `${url}`;
-			const scope = this.scope;
-			if (!href.startsWith(scope)) return void 0;
-			const key = href.substring(scope.length).replace(/[?#].*$/, "").split("/")[0];
-			return key ? decodeURIComponent(key) : void 0;
+			let parsed;
+			try {
+				parsed = new URL(`${url}`);
+			} catch {
+				return;
+			}
+			return (this.options.key ?? scopeKey)(parsed, this.scope);
 		}
 		/** Whether `key` has ever been served on this worker. */
 		isClaimedKey(key) {
@@ -4010,7 +4405,7 @@
 			return this.claimedKeys.has(key) || this.table.all(key).length > 0;
 		}
 		start() {
-			const self = this.self;
+			const self = this._sw;
 			if (this.routerLock) this._routerHeld = holdLock(this.routerLock).then(() => {});
 			this._restored = this._restoreClaimedKeys();
 			const latch = () => {
@@ -4030,8 +4425,8 @@
 				return true;
 			}), handleChannelCalls(self, WS_CONNECT_CALL, async (event, params) => {
 				if (!this._isOwnClient(event)) throw new Error("Only this origin's pages may open sockets");
-				const { url, protocols } = params;
-				const connection = await this.connectWebSocket(url, protocols ?? []);
+				const { url, protocols, headers } = params;
+				const connection = await this.connectWebSocket(url, protocols ?? [], this._socketHeaders(headers, "page"));
 				return withTransfer(connection, [connection.port]);
 			}));
 			const onMessage = (event) => {
@@ -4049,10 +4444,10 @@
 				this.log("Claim control over all clients.");
 				event.waitUntil(self.clients.claim());
 			};
-			const onFetch = (event) => this._onFetch(event);
+			const onFetch = (event) => void this.handleFetch(event);
 			self.addEventListener("install", onInstall);
 			self.addEventListener("activate", onActivate);
-			self.addEventListener("fetch", onFetch);
+			if (this.options.handleFetch !== false) self.addEventListener("fetch", onFetch);
 			this._cleanup.push(() => {
 				self.removeEventListener("install", onInstall);
 				self.removeEventListener("activate", onActivate);
@@ -4067,37 +4462,60 @@
 		}
 		/**
 		* Answers `request` as a fetch under the scope would be: through the
-		* handler its key routes to. A url outside the scope, or of a key this
-		* worker never served, goes to the network.
+		* handler its key routes to. A url with no key (by default, one outside the
+		* scope), or of a key this worker never served, goes to the network.
 		*/
 		async dispatch(request) {
 			const key = this.keyOf(request.url);
 			if (key === void 0) return await fetch(request);
 			await this._restored.catch(() => {});
 			const entry = await this._acquire(request, key);
-			if (entry === TIMED_OUT) return new Response(null, {
-				status: 503,
-				statusText: "Service Unavailable (no handler attached in time)"
-			});
+			if (entry === TIMED_OUT) return await this._failed(request, { kind: "timeout" });
 			if (!entry) {
 				if (!this.serves(key)) return await fetch(request);
-				return new Response(null, {
-					status: 404,
-					statusText: "Not Found (no active handler)"
-				});
+				return await this._failed(request, { kind: "gone" });
 			}
 			try {
 				return await entry.link.send(request);
 			} catch (error) {
 				this.log("[dispatch] failed", key, error);
-				return new Response(errorMessage(error), {
-					status: 502,
-					statusText: "Bad Gateway",
-					headers: { "content-type": "text/plain; charset=utf-8" }
+				return await this._failed(request, {
+					kind: "lost",
+					error
 				});
 			}
 		}
 		/**
+		* After `start()`: settles once the keys this worker served before a restart are read back
+		* (whatever the outcome). Until then `serves()` may answer `false` for a key it will serve.
+		*/
+		get ready() {
+			return this._restored.then(() => {}, () => {});
+		}
+		_socketHeaders(headers, from) {
+			return this.options.socketHeaders ? this.options.socketHeaders(headers, from) : headers;
+		}
+		async _failed(request, failure) {
+			if (this.options.failure) try {
+				return await this.options.failure(request, failure);
+			} catch (error) {
+				this.log("[dispatch] the failure option threw; answering by default", error);
+			}
+			if (failure.kind === "timeout") return new Response(null, {
+				status: 503,
+				statusText: "Service Unavailable (no handler attached in time)"
+			});
+			if (failure.kind === "gone") return new Response(null, {
+				status: 404,
+				statusText: "Not Found (no active handler)"
+			});
+			return new Response(errorMessage(failure.error), {
+				status: 502,
+				statusText: "Bad Gateway",
+				headers: { "content-type": "text/plain; charset=utf-8" }
+			});
+		}
+		/**
 		* Opens a socket to the handler `url` routes to: the handler accepts or
 		* refuses it like an HTTP upgrade, and the socket's port comes back. After
 		* that the socket runs between the caller and the handler directly; this
@@ -4109,7 +4527,7 @@
 				headers
 			});
 			const key = this.keyOf(request.url);
-			if (key === void 0) throw new Error(`${url} is outside this ServiceWorker's scope`);
+			if (key === void 0) throw new Error(`${url} belongs to no key of this ServiceWorker`);
 			await this._restored.catch(() => {});
 			const entry = await this._acquire(request, key);
 			if (!entry || entry === TIMED_OUT) throw new Error(`No handler serves ${url}`);
@@ -4125,20 +4543,47 @@
 			});
 			return await answer;
 		}
-		_onFetch(event) {
-			const request = event.request;
+		/**
+		* Answers `event` if it is the dispatcher's, with `request` (default `event.request`; a host
+		* may pass a rewritten one, with headers it adds). Returns whether it called `respondWith`;
+		* when it did not, the event is the caller's to answer or to leave to the network. For a host
+		* that listens to `fetch` itself (`handleFetch: false`); call it synchronously in the event's
+		* listener, as `respondWith` must be.
+		*
+		* It takes a same-origin request whose key (the `key` option) a handler serves, and also:
+		* - a navigation under the scope whose key nobody serves (answered by `unserved`);
+		* - before the stored keys are read (the first requests after a restart), every request with
+		*   a key, since only then is it known whose it is: one nobody serves gets what it would have
+		*   got after, `unserved` for a navigation and the network for anything else.
+		* So a host with a page of its own for urls nobody serves gives it as `unserved`, rather than
+		* deciding before calling this.
+		*/
+		handleFetch(event, request = event.request) {
+			const navigation = event.request.mode === "navigate";
+			if (new URL(request.url).origin !== this._sw.location.origin) return false;
 			const key = this.keyOf(request.url);
-			if (key === void 0) return;
+			if (key === void 0) return false;
 			if (this._restoreSettled) {
-				if (this.serves(key)) event.respondWith(this.dispatch(request));
-				else if (request.mode === "navigate") event.respondWith(fetch(request));
-				return;
+				if (this.serves(key)) {
+					event.respondWith(this.dispatch(request));
+					return true;
+				}
+				if (navigation) {
+					event.respondWith(this._unserved(request));
+					return true;
+				}
+				return false;
 			}
 			event.respondWith((async () => {
 				await this._restored.catch(() => {});
-				if (!this.serves(key)) return await fetch(request);
-				return await this.dispatch(request);
+				if (this.serves(key)) return await this.dispatch(request);
+				return navigation ? await this._unserved(request) : await fetch(request);
 			})());
+			return true;
+		}
+		/** What a request the dispatcher took, and no handler serves, gets: `unserved`, or the network. */
+		async _unserved(request) {
+			return await (this.options.unserved ?? fetch)(request);
 		}
 		async _attach(event, params, ports) {
 			const clientId = event.source?.id;
@@ -4157,8 +4602,11 @@
 			}
 			const ctl = params.ctl ? rest.shift() : void 0;
 			const up = params.up ? rest.shift() : void 0;
-			const streamTimeout = this.options.streamTimeout;
-			const link = await connectHttpLink(down, { streamTimeout });
+			const { streamTimeout, window } = this.options;
+			const link = await connectHttpLink(down, {
+				streamTimeout,
+				window
+			});
 			const entry = new HandlerEntry(params.key, params.id ?? clientId ?? crypto.randomUUID(), params.owner ?? crypto.randomUUID(), params.meta, link, ctl, clientId, params.ownerLock);
 			if (up) entry.closeUp = await serveHttpLink(up, (request) => this.dispatch(request), { streamTimeout });
 			if (ctl) ctl.onmessage = (message) => this._onControl(entry, message.data);
@@ -4237,20 +4685,35 @@
 		* its key, waiting for one when there is none.
 		*/
 		async _acquire(request, key) {
+			const deadline = Date.now() + (this.options.attachTimeoutMs ?? 15e3);
 			const picked = await this._pick(request, key);
 			if (picked) return picked;
-			if (this.table.all(key).length > 0) return await this.table.waitFor(key, this.options.attachTimeoutMs ?? 15e3, this.table.live(key).length > 0) ? await this._pick(request, key) ?? TIMED_OUT : TIMED_OUT;
-			const vacantUntil = this._vacant.get(key) ?? 0;
-			if (vacantUntil > Date.now()) return await this.table.waitFor(key, vacantUntil - Date.now()) ? await this._pick(request, key) ?? TIMED_OUT : TIMED_OUT;
-			if (!this.serves(key)) return void 0;
-			await this._askForLinks(key);
-			return await this._pick(request, key);
+			if (this.table.all(key).length === 0) {
+				const vacantUntil = this._vacant.get(key) ?? 0;
+				if (vacantUntil > Date.now()) return await this._waitToPick(request, key, vacantUntil);
+				if (!this.serves(key)) return void 0;
+				await this._askForLinks(key);
+				const relinked = await this._pick(request, key);
+				if (relinked) return relinked;
+				if (this.table.all(key).length === 0) return void 0;
+			}
+			return await this._waitToPick(request, key, deadline);
+		}
+		/** Waits for attaches until `route` accepts a handler, or `until` passes. */
+		async _waitToPick(request, key, until) {
+			for (;;) {
+				const left = until - Date.now();
+				if (left <= 0) return TIMED_OUT;
+				await this.table.waitFor(key, Math.min(left, 1e3), this.table.live(key).length > 0);
+				const picked = await this._pick(request, key);
+				if (picked) return picked;
+			}
 		}
 		async _pick(request, key) {
 			let live = this.table.live(key);
 			for (const entry of live) {
 				if (entry.ownerLock || !entry.clientId) continue;
-				if (!await this.self.clients.get(entry.clientId)) this._close(entry, new LinkLostError(HANDLER_LOST_MESSAGE));
+				if (!await this._sw.clients.get(entry.clientId)) this._close(entry, new LinkLostError(HANDLER_LOST_MESSAGE));
 			}
 			live = this.table.live(key);
 			if (live.length === 0) return void 0;
@@ -4274,7 +4737,7 @@
 		}
 		async _linkRound(key) {
 			const timeout = this.options.relinkTimeoutMs ?? 3e3;
-			const windows = await this.self.clients.matchAll({
+			const windows = await this._sw.clients.matchAll({
 				type: "window",
 				includeUncontrolled: true
 			});
@@ -4312,7 +4775,7 @@
 					entry.sockets.fail(message.id, new Error(message.message));
 					return;
 				case "ws-open":
-					this.connectWebSocket(message.url, message.protocols).then(({ port, protocol }) => entry.ctl?.postMessage({
+					this.connectWebSocket(message.url, message.protocols, this._socketHeaders(message.headers, "handler")).then(({ port, protocol }) => entry.ctl?.postMessage({
 						t: "ws-opened",
 						id: message.id,
 						protocol,
@@ -4329,7 +4792,7 @@
 			const source = event.source;
 			if (!source?.url) return false;
 			try {
-				return new URL(source.url).origin === this.self.location.origin;
+				return new URL(source.url).origin === this._sw.location.origin;
 			} catch {
 				return false;
 			}
@@ -4353,6 +4816,7 @@
 	* that stops it.
 	*/
 	function startHttpDispatcher(options) {
+		if (options.handleFetch === false) throw new Error("startHttpDispatcher: handleFetch: false needs a dispatcher to call handleFetch on; construct it instead: new SwHttpDispatcher({ self, handleFetch: false }).start()");
 		const dispatcher = new SwHttpDispatcher(options);
 		dispatcher.start();
 		return () => {