@statewalker/webrun-streams 0.2.2 → 0.3.0

package/dist/index.js

@@ -31,7 +31,7 @@ async function collectString(input) {
 //#endregion
 //#region src/duplex.ts
 /**
-* Thrown by `emulateMux` and adapters when the underlying transport closes
+* Thrown by adapters when the underlying transport closes
 * while one or more `Duplex` calls are in flight. Consumers can catch by
 * `instanceof TransportClosedError` or by checking `error.name`.
 */
@@ -144,404 +144,6 @@ function newCreditGrantor(window, threshold = .5) {
 	} };
 }
 //#endregion
-//#region src/uint32.ts
-/**
-* Credit payloads are a single big-endian uint32, matching the frame header's
-* byte order.
-*
-* Deliberately **not** re-exported from `index.ts`: this is an internal codec
-* for the `emulateMux` wire format, not a compatibility commitment. Tests
-* import it by path.
-*/
-/** The largest credit a single frame can advertise or grant: 2^32 - 1. */
-const MAX_UINT32 = 4294967295;
-/**
-* Clamps rather than wraps. `n >>> 0` is the obvious spelling and it is wrong
-* here: 2^32 becomes **0**, so a 4 GiB window advertises *zero credit* and the
-* peer stalls forever with no error — the exact silent hang credit exists to
-* remove. 2^32 + 5 becomes 5, which looks like a working window and is worse.
-* Anything above the ceiling is advertised as the ceiling.
-*/
-function encodeUint32(n) {
-	const bytes = /* @__PURE__ */ new Uint8Array(4);
-	const clamped = Number.isFinite(n) ? Math.min(MAX_UINT32, Math.max(0, Math.floor(n))) : 0;
-	new DataView(bytes.buffer).setUint32(0, clamped, false);
-	return bytes;
-}
-/**
-* Returns `undefined` rather than a garbage number when the payload is too
-* short, so a truncated frame — or one from a peer predating credit — is
-* detectable at the call site instead of silently granting nonsense.
-*/
-function decodeUint32(bytes) {
-	if (bytes.byteLength < 4) return void 0;
-	return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, false);
-}
-//#endregion
-//#region src/emulate-mux.ts
-const TYPE_OPEN = 1;
-const TYPE_DATA = 2;
-const TYPE_ACK = 3;
-const TYPE_END = 4;
-const TYPE_ERROR = 5;
-const TYPE_CLOSE = 6;
-const DEFAULT_MAX_STREAMS = 256;
-const DEFAULT_MTU = 65536;
-const DEFAULT_MAX_STREAM_BUFFER = 8388608;
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-function emulateMux(channel, opts = {}) {
-	const maxStreams = opts.maxStreams ?? DEFAULT_MAX_STREAMS;
-	const mtu = opts.mtu ?? DEFAULT_MTU;
-	const maxStreamBuffer = opts.maxStreamBuffer ?? DEFAULT_MAX_STREAM_BUFFER;
-	if (!(maxStreamBuffer >= 1)) throw new RangeError(`emulateMux: maxStreamBuffer must be at least 1, got ${maxStreamBuffer}`);
-	const side = opts.side ?? "initiator";
-	const streams = /* @__PURE__ */ new Map();
-	let nextLocalId = side === "initiator" ? 2 : 1;
-	let handler = null;
-	let muxClosed = false;
-	const sendFrame = (id, type, payload) => {
-		if (muxClosed) return;
-		const idEnc = encodeVarint(id);
-		const total = idEnc.length + 1 + (payload?.byteLength ?? 0);
-		const frame = new Uint8Array(total);
-		frame.set(idEnc, 0);
-		frame[idEnc.length] = type;
-		if (payload && payload.byteLength > 0) frame.set(payload, idEnc.length + 1);
-		try {
-			channel.send(frame);
-		} catch {}
-	};
-	const teardownStream = (s, err) => {
-		if (s.closed) return;
-		s.closed = true;
-		s.outboundCredit.fail(err ?? new TransportClosedError("emulateMux: stream closed"));
-		s.doneIn(err);
-		s.cancelInput?.();
-		streams.delete(s.id);
-	};
-	/**
-	* Graceful counterpart to `teardownStream`. A stream occupies a slot in
-	* `streams` until BOTH directions finish; releasing on inbound END alone
-	* would set `closed` while our own `pumpOutbound` is still sending, and it
-	* checks that flag to decide whether to keep going.
-	*
-	* Without this, only abnormal endings (cancel, ERROR, CLOSE, transport
-	* failure) ever freed a slot, so every normally-completed call leaked one
-	* until `maxStreams` began rejecting new calls.
-	*/
-	const releaseIfComplete = (s) => {
-		if (s.closed || !s.inDone || !s.outDone) return;
-		s.closed = true;
-		streams.delete(s.id);
-	};
-	const failAll = (err) => {
-		if (muxClosed) return;
-		muxClosed = true;
-		for (const s of [...streams.values()]) teardownStream(s, err);
-		streams.clear();
-	};
-	const createStream = (id) => {
-		const queue = makeInboundQueue();
-		const state = {
-			id,
-			inbound: queue.generator(() => {
-				if (!state.closed && !muxClosed) sendFrame(state.id, TYPE_CLOSE);
-				teardownStream(state);
-			}),
-			pushIn: queue.push,
-			doneIn: queue.done,
-			outboundCredit: newCreditLedger(0),
-			grantor: newCreditGrantor(maxStreamBuffer),
-			closed: false,
-			inDone: false,
-			outDone: false,
-			queuedBytes: 0
-		};
-		return state;
-	};
-	const pumpOutbound = async (s, input) => {
-		const iterator = input[Symbol.asyncIterator]?.() ?? input[Symbol.iterator]();
-		s.cancelInput = () => {
-			iterator.return?.(void 0);
-		};
-		try {
-			for (;;) {
-				const next = await iterator.next();
-				if (next.done === true) break;
-				const chunk = next.value;
-				if (s.closed || muxClosed) return;
-				if (chunk.byteLength === 0) continue;
-				let off = 0;
-				while (off < chunk.byteLength) {
-					if (s.closed || muxClosed) return;
-					const take = await s.outboundCredit.reserve(Math.min(mtu, chunk.byteLength - off));
-					if (s.closed || muxClosed) return;
-					const end = off + take;
-					sendFrame(s.id, TYPE_DATA, chunk.subarray(off, end));
-					off = end;
-				}
-			}
-			if (!s.closed && !muxClosed) {
-				sendFrame(s.id, TYPE_END);
-				s.outDone = true;
-				releaseIfComplete(s);
-			}
-		} catch (err) {
-			if (!s.closed && !muxClosed) {
-				const e = err instanceof Error ? err : new Error(String(err));
-				sendFrame(s.id, TYPE_ERROR, encodeError(e));
-				teardownStream(s, e);
-			}
-		}
-	};
-	const runHandler = async (s, h) => {
-		let outbound;
-		try {
-			outbound = h(s.inbound);
-		} catch (err) {
-			const e = err instanceof Error ? err : new Error(String(err));
-			sendFrame(s.id, TYPE_ERROR, encodeError(e));
-			teardownStream(s, e);
-			return;
-		}
-		await pumpOutbound(s, outbound);
-		if (!s.inDone && !s.closed && !muxClosed) {
-			sendFrame(s.id, TYPE_CLOSE);
-			teardownStream(s);
-		}
-	};
-	const handleFrame = (frame) => {
-		if (muxClosed) return;
-		if (frame.byteLength < 2) return;
-		let id;
-		let offset;
-		try {
-			({value: id, offset} = decodeVarint(frame, 0));
-		} catch {
-			return;
-		}
-		if (offset >= frame.byteLength) return;
-		const type = frame[offset];
-		const payload = frame.subarray(offset + 1);
-		if (type === TYPE_OPEN) {
-			if (streams.has(id)) return;
-			if (streams.size >= maxStreams) {
-				sendFrame(id, TYPE_ERROR, encodeError(/* @__PURE__ */ new RangeError(`emulateMux: maxStreams=${maxStreams} exceeded`)));
-				return;
-			}
-			if (!handler) {
-				sendFrame(id, TYPE_ERROR, encodeError(/* @__PURE__ */ new Error("emulateMux: no handler registered")));
-				return;
-			}
-			const s = createStream(id);
-			streams.set(id, s);
-			const advertised = decodeUint32(payload);
-			if (advertised !== void 0) s.outboundCredit.grant(advertised);
-			sendFrame(id, TYPE_ACK, encodeUint32(maxStreamBuffer));
-			runHandler(s, handler);
-			return;
-		}
-		const s = streams.get(id);
-		if (!s) return;
-		switch (type) {
-			case TYPE_DATA: {
-				s.queuedBytes += payload.byteLength;
-				if (s.queuedBytes > maxStreamBuffer) {
-					const err = /* @__PURE__ */ new RangeError(`emulateMux: stream ${id} buffered ${s.queuedBytes} bytes past maxStreamBuffer=${maxStreamBuffer} without being drained`);
-					sendFrame(id, TYPE_ERROR, encodeError(err));
-					teardownStream(s, err);
-					return;
-				}
-				const copy = payload.byteLength === 0 ? payload : new Uint8Array(payload);
-				s.pushIn(copy).then((handled) => {
-					s.queuedBytes -= copy.byteLength;
-					if (!handled || s.closed || muxClosed) return;
-					const grant = s.grantor.consumed(copy.byteLength, s.queuedBytes === 0);
-					if (grant > 0) sendFrame(id, TYPE_ACK, encodeUint32(grant));
-				});
-				return;
-			}
-			case TYPE_ACK: {
-				const granted = decodeUint32(payload);
-				if (granted !== void 0) s.outboundCredit.grant(granted);
-				return;
-			}
-			case TYPE_END:
-				s.inDone = true;
-				s.doneIn();
-				releaseIfComplete(s);
-				return;
-			case TYPE_ERROR:
-				teardownStream(s, decodeError(payload));
-				return;
-			case TYPE_CLOSE:
-				teardownStream(s);
-				return;
-			default: return;
-		}
-	};
-	(async () => {
-		try {
-			for await (const frame of channel.recv) {
-				if (muxClosed) break;
-				handleFrame(frame);
-			}
-		} catch (err) {
-			failAll(err instanceof Error ? err : new Error(String(err)));
-			return;
-		}
-		failAll(new TransportClosedError());
-	})();
-	channel.closed.then(() => failAll(new TransportClosedError())).catch(() => {});
-	const call = (input) => {
-		if (muxClosed) return failedGenerator(new TransportClosedError());
-		if (streams.size >= maxStreams) return failedGenerator(/* @__PURE__ */ new RangeError(`emulateMux: maxStreams=${maxStreams} exceeded`));
-		const id = nextLocalId;
-		nextLocalId += 2;
-		const s = createStream(id);
-		streams.set(id, s);
-		sendFrame(id, TYPE_OPEN, encodeUint32(maxStreamBuffer));
-		pumpOutbound(s, input);
-		return s.inbound;
-	};
-	const serve = (h) => {
-		handler = h;
-		let torn = false;
-		return async () => {
-			if (torn) return;
-			torn = true;
-			if (handler === h) handler = null;
-		};
-	};
-	const close = async () => {
-		if (muxClosed) return;
-		failAll(new TransportClosedError());
-		try {
-			channel.close();
-		} catch {}
-	};
-	return {
-		call,
-		serve,
-		close
-	};
-}
-function failedGenerator(err) {
-	return (async function* () {
-		throw err;
-	})();
-}
-/**
-* Push/pull queue with eager push/done handles. Unlike `newAsyncGenerator`, the
-* push and done functions are usable *before* the consumer begins iterating —
-* `emulateMux` needs to enqueue frames from inbound traffic regardless of when
-* (or whether) the consumer pulls them.
-*
-* `onCancel` fires only when the consumer terminates the generator before
-* `done()` was called — i.e., a unilateral cancellation. If `done()` is
-* called first (peer END/ERROR/CLOSE), the generator ends naturally and
-* `onCancel` does not fire.
-*/
-function makeInboundQueue() {
-	const slots = [];
-	let wake = null;
-	let queueClosed = false;
-	let doneCalled = false;
-	const push = (chunk) => {
-		if (queueClosed) return Promise.resolve(false);
-		return new Promise((resolve) => {
-			slots.push({
-				type: "value",
-				value: chunk,
-				resolve
-			});
-			wake?.();
-		});
-	};
-	const done = (err) => {
-		if (queueClosed || doneCalled) return Promise.resolve(false);
-		doneCalled = true;
-		return new Promise((resolve) => {
-			slots.push({
-				type: "done",
-				err,
-				resolve
-			});
-			wake?.();
-		});
-	};
-	async function* generator(onCancel) {
-		try {
-			while (true) {
-				if (slots.length === 0) {
-					await new Promise((r) => {
-						wake = r;
-					});
-					wake = null;
-					continue;
-				}
-				const slot = slots.shift();
-				if (slot.type === "done") {
-					slot.resolve(true);
-					if (slot.err) throw slot.err;
-					return;
-				}
-				yield slot.value;
-				slot.resolve(true);
-			}
-		} finally {
-			queueClosed = true;
-			for (const s of slots) s.resolve(false);
-			slots.length = 0;
-			if (!doneCalled) onCancel();
-		}
-	}
-	return {
-		generator,
-		push,
-		done
-	};
-}
-function encodeVarint(value) {
-	if (!Number.isInteger(value) || value < 0) throw new RangeError(`encodeVarint: ${value} is not a non-negative integer`);
-	const out = [];
-	let v = value;
-	while (v >= 128) {
-		out.push(v & 127 | 128);
-		v >>>= 7;
-	}
-	out.push(v & 127);
-	return new Uint8Array(out);
-}
-function decodeVarint(buf, start) {
-	let value = 0;
-	let shift = 0;
-	let i = start;
-	while (i < buf.length) {
-		const b = buf[i++];
-		value |= (b & 127) << shift;
-		if ((b & 128) === 0) return {
-			value: value >>> 0,
-			offset: i
-		};
-		shift += 7;
-		if (shift > 28) throw new Error("decodeVarint: too long");
-	}
-	throw new Error("decodeVarint: truncated");
-}
-function encodeError(err) {
-	return textEncoder.encode(JSON.stringify(serializeError(err)));
-}
-function decodeError(buf) {
-	if (buf.byteLength === 0) return /* @__PURE__ */ new Error("unknown stream error");
-	try {
-		return deserializeError(JSON.parse(textDecoder.decode(buf)));
-	} catch {
-		return new Error(textDecoder.decode(buf));
-	}
-}
-//#endregion
 //#region src/lines.ts
 /** Split a stream of string chunks into individual lines (delimited by \n). */
 async function* splitLines(input) {
@@ -736,7 +338,7 @@ async function* newAsyncGenerator(init, skipValues = false) {
 }
 //#endregion
 //#region src/normalize.ts
-const utf8 = new TextEncoder();
+const utf8 = /* @__PURE__ */ new TextEncoder();
 /**
 * Coerce common byte-like inputs into a `Uint8Array`. Strings encode as UTF-8.
 * Blobs return a `Promise<Uint8Array>`; every other input returns synchronously.
@@ -914,4 +516,4 @@ function toChunks(size = DEFAULT_CHUNK_SIZE) {
 	};
 }
 //#endregion
-export { TransportClosedError, collect, collectBytes, collectString, decodeJsonl, decodeText, deserializeError, emulateMux, encodeJsonl, encodeText, fromReadableStream, joinLines, map, newAsyncGenerator, newCreditGrantor, newCreditLedger, normalizeToUint8Array, recieveIterator, sendIterator, serializeError, splitLines, toChunks, toReadableStream };
+export { TransportClosedError, collect, collectBytes, collectString, decodeJsonl, decodeText, deserializeError, encodeJsonl, encodeText, fromReadableStream, joinLines, map, newAsyncGenerator, newCreditGrantor, newCreditLedger, normalizeToUint8Array, recieveIterator, sendIterator, serializeError, splitLines, toChunks, toReadableStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Async-iterator / ReadableStream primitives: collect, text/jsonl codecs, lines, backpressure generators, serialisable errors.",
@@ -35,7 +35,7 @@
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/duplex.ts

@@ -47,7 +47,7 @@ export type Connect<P> = (params: P) => Promise<{
 export type Serve<P> = (params: P, handler: Duplex) => Promise<() => Promise<void>>;
 
 /**
- * Thrown by `emulateMux` and adapters when the underlying transport closes
+ * Thrown by adapters when the underlying transport closes
  * while one or more `Duplex` calls are in flight. Consumers can catch by
  * `instanceof TransportClosedError` or by checking `error.name`.
  */

package/src/flow-control.ts

@@ -11,10 +11,13 @@
  * offer: the receiver's capacity is not knowable to the sender unless the
  * receiver states it.
  *
- * **The unit is opaque.** This module never interprets the numbers it counts.
- * `emulateMux` passes byte counts and advertises `maxStreamBuffer`; the RPC
- * tier passes 1 per value and advertises a maximum in-flight value count.
- * Nothing here depends on which.
+ * **The unit is opaque.** This module never interprets the numbers it counts:
+ * bytes or values, it does not depend on which.
+ *
+ * **Dormant.** Its consumer, `emulateMux`, was removed in Plan C3, and
+ * `webrun-rpc`'s port stack keeps its own window. It stays exported and
+ * tested as the mechanism for per-stream windowing (spec D13) rather than be
+ * rewritten later.
  */
 
 export interface CreditLedger {

package/src/index.ts

@@ -1,6 +1,5 @@
 export * from "./collect.js";
 export * from "./duplex.js";
-export * from "./emulate-mux.js";
 export * from "./errors.js";
 export * from "./flow-control.js";
 export * from "./jsonl.js";

package/src/normalize.ts

@@ -1,4 +1,4 @@
-const utf8 = new TextEncoder();
+const utf8 = /* @__PURE__ */ new TextEncoder();
 
 export type ByteLike = Uint8Array | ArrayBuffer | ArrayBufferView | Blob | string;
 

package/dist/emulate-mux.d.ts

@@ -1,39 +0,0 @@
-import { type Duplex } from "./duplex.js";
-/**
- * The minimum a transport must expose to be wrapped by `emulateMux`. Inbound
- * bytes are surfaced as an async iterable; outbound is imperative `send`. All
- * five message-oriented transports (WebSocket, LiveKit data channel, PeerJS
- * DataConnection, MessagePort, in-process pipe) match this shape after a thin
- * wrapper.
- */
-export type ByteChannel = {
-    send(bytes: Uint8Array): void;
-    recv: AsyncIterable<Uint8Array>;
-    closed: Promise<void>;
-    close(): void;
-};
-export interface EmulateMuxOptions {
-    maxStreams?: number;
-    mtu?: number;
-    /**
-     * Cap on inbound bytes one stream may hold for a consumer that has not
-     * drained them. Exceeding it tears down that stream alone.
-     *
-     * It is also the credit this side advertises to the peer, so it must be at
-     * least 1 — a window of 0 authorises nothing and hangs the peer forever —
-     * and it travels in a uint32, so a value above `MAX_UINT32` (4 GiB - 1) is
-     * advertised as `MAX_UINT32`.
-     */
-    maxStreamBuffer?: number;
-    /**
-     * Stream-id allocation side. Initiator uses even ids (2, 4, …); responder
-     * uses odd ids (1, 3, …). Pick one per peer so allocations don't collide.
-     */
-    side?: "initiator" | "responder";
-}
-export declare function emulateMux(channel: ByteChannel, opts?: EmulateMuxOptions): {
-    call: Duplex;
-    serve: (handler: Duplex) => () => Promise<void>;
-    close: () => Promise<void>;
-};
-//# sourceMappingURL=emulate-mux.d.ts.map

package/dist/emulate-mux.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"emulate-mux.d.ts","sourceRoot":"","sources":["../src/emulate-mux.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAwB,MAAM,aAAa,CAAC;AAUhE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AA4CF,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;CAClC;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE,iBAAsB,GAC3B;IACD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAuVA"}

package/dist/uint32.d.ts

@@ -1,25 +0,0 @@
-/**
- * Credit payloads are a single big-endian uint32, matching the frame header's
- * byte order.
- *
- * Deliberately **not** re-exported from `index.ts`: this is an internal codec
- * for the `emulateMux` wire format, not a compatibility commitment. Tests
- * import it by path.
- */
-/** The largest credit a single frame can advertise or grant: 2^32 - 1. */
-export declare const MAX_UINT32 = 4294967295;
-/**
- * Clamps rather than wraps. `n >>> 0` is the obvious spelling and it is wrong
- * here: 2^32 becomes **0**, so a 4 GiB window advertises *zero credit* and the
- * peer stalls forever with no error — the exact silent hang credit exists to
- * remove. 2^32 + 5 becomes 5, which looks like a working window and is worse.
- * Anything above the ceiling is advertised as the ceiling.
- */
-export declare function encodeUint32(n: number): Uint8Array;
-/**
- * Returns `undefined` rather than a garbage number when the payload is too
- * short, so a truncated frame — or one from a peer predating credit — is
- * detectable at the call site instead of silently granting nonsense.
- */
-export declare function decodeUint32(bytes: Uint8Array): number | undefined;
-//# sourceMappingURL=uint32.d.ts.map

package/dist/uint32.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"uint32.d.ts","sourceRoot":"","sources":["../src/uint32.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,0EAA0E;AAC1E,eAAO,MAAM,UAAU,aAAa,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGlE"}