@statewalker/webrun-rpc 0.7.0 → 0.10.0

package/dist/index.js

@@ -471,6 +471,101 @@ async function* callBidi(port, input, { options = {}, ...params } = {}) {
 	if (outerError !== void 0) throw outerError;
 }
 //#endregion
+//#region src/port-credit.ts
+/**
+* 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();
+//#endregion
 //#region src/async-dispose.ts
 /**
 * Makes `target` disposable with `await using`: installs `dispose` as its
@@ -548,6 +643,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. */
@@ -560,7 +710,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.
@@ -577,22 +729,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
@@ -632,22 +811,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"));
@@ -741,7 +929,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;
@@ -751,25 +939,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();
@@ -779,15 +1006,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();
 	};
@@ -817,21 +1089,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", {
@@ -839,63 +1125,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);
 	}
 }
 //#endregion
-//#region src/port-credit.ts
-/**
-* 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));
-}
-//#endregion
 //#region src/virtual-port.ts
 /**
 * One virtual port.
@@ -982,8 +1239,25 @@ const MUX_CLOSED_MESSAGE = "webrun-rpc: the multiplexer was closed";
 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;
+/** Default ceiling on one message reassembled from frames (`maxReassembledBytes`). */
+const DEFAULT_MAX_REASSEMBLED_BYTES = 67108864;
 /**
 * What a message costs a port's window when the codec cannot say
 * (`PortCodec.encode`): its bytes and string lengths, found in its values up
@@ -1013,10 +1287,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;
@@ -1037,6 +1319,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);
@@ -1094,13 +1378,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;
@@ -1138,15 +1448,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",
@@ -1164,12 +1479,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 ? {
@@ -1199,10 +1514,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({
@@ -1232,6 +1548,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,
@@ -1283,16 +1631,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;
@@ -1320,6 +1676,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,
@@ -1331,6 +1688,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;
@@ -1341,15 +1702,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) {
@@ -1361,8 +1736,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"));
@@ -1441,12 +1830,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,
@@ -1555,14 +1946,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);
 	});
@@ -1666,7 +2060,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
@@ -1678,6 +2072,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);
@@ -1780,4 +2175,4 @@ function transferPortMux(target, options = {}) {
 	};
 }
 //#endregion
-export { CANCEL_CHANNEL_TYPE, DEFAULT_MAX_PORTS, MUX_CLOSED_MESSAGE, NO_TIMEOUT, PORT_TRANSFER, STREAM_ABORT, byteChannelFromMessagePort, callBidi, callPort, connect, duplexOverPort, getPortCloseSignal, ioHandle, ioSend, listenBidi, listenCancelChannel, listenPort, multiplexPort, overPipe, overPorts, portBufferedAmount, postCancelChannel, recieve, send, serve, serveDuplexOverPort, setPortCloseSignal, structuredCodec, transferPortMux, whenPortReady };
+export { CANCEL_CHANNEL_TYPE, DEFAULT_MAX_PORTS, DEFAULT_MAX_REASSEMBLED_BYTES, MUX_CLOSED_MESSAGE, NO_TIMEOUT, PORT_TRANSFER, STREAM_ABORT, byteChannelFromMessagePort, callBidi, callPort, connect, duplexOverPort, getPortCloseSignal, ioHandle, ioSend, listenBidi, listenCancelChannel, listenPort, multiplexPort, overPipe, overPorts, portBufferedAmount, postCancelChannel, recieve, send, serve, serveDuplexOverPort, setPortCloseSignal, structuredCodec, transferPortMux, whenPortReady };