@statewalker/webrun-files-rpc 0.0.0-stage → 0.1.0

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,GAAG,EAAE,QAAQ,CAAC;IACd,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyCD,0FAA0F;AAC1F,qBAAa,cAAe,YAAW,QAAQ;;IAO7C,YAAY,OAAO,EAAE,qBAAqB,EAMzC;IAED;;;OAGG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC9E;IAED;;;OAGG;IACG,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CA2Bf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAY5E;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAElD;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErD;IACD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErD;CACF;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAEhF"}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+import type { FilesRpcErrorCode } from "./types.js";
+/**
+ * An error of the protocol itself. The code also leads the message (`UNKNOWN_STREAM: …`), since
+ * a structured clone keeps an error's name and message but not its other properties:
+ * `errorCode(e)` reads it back on the other side of a transport.
+ */
+export declare class FilesRpcError extends Error {
+    readonly code: FilesRpcErrorCode;
+    constructor(code: FilesRpcErrorCode, message: string);
+}
+/** The FilesRpcError code of an error, also after it crossed a transport; undefined otherwise. */
+export declare function errorCode(e: unknown): FilesRpcErrorCode | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,YAAY,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAInD;CACF;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAOnE"}

package/dist/esm/index.js

@@ -0,0 +1,666 @@
+//#region src/client.ts
+const toBytes$1 = (v) => v instanceof Uint8Array ? v : ArrayBuffer.isView(v) ? new Uint8Array(v.buffer, v.byteOffset, v.byteLength) : new Uint8Array(v);
+const newStreamId$1 = () => crypto.randomUUID().replace(/-/g, "");
+/** Cuts any sequence of byte arrays into chunks of exactly `size` bytes (the last may be shorter). */
+async function* rechunk(content, size) {
+	let carry;
+	let carried = 0;
+	for await (const piece of content) {
+		let part = toBytes$1(piece);
+		while (part.length) {
+			if (!carry && part.length >= size) {
+				yield part.slice(0, size);
+				part = part.subarray(size);
+				continue;
+			}
+			carry ??= new Uint8Array(size);
+			const n = Math.min(size - carried, part.length);
+			carry.set(part.subarray(0, n), carried);
+			carried += n;
+			part = part.subarray(n);
+			if (carried === size) {
+				yield carry;
+				carry = void 0;
+				carried = 0;
+			}
+		}
+	}
+	if (carry && carried) yield carry.slice(0, carried);
+}
+/** A FilesApi whose every call goes through a FilesRpc; content moves in keyed chunks. */
+var FilesRpcClient = class {
+	#rpc;
+	#chunkSize;
+	#readAhead;
+	#writeAhead;
+	#pageSize;
+	constructor(options) {
+		this.#rpc = options.rpc;
+		this.#chunkSize = Math.max(1, options.chunkSize ?? 262144);
+		this.#readAhead = Math.max(1, options.readAhead ?? 4);
+		this.#writeAhead = Math.max(1, options.writeAhead ?? 4);
+		this.#pageSize = Math.max(1, options.pageSize ?? 256);
+	}
+	/**
+	* Asks for chunks 0, 1, 2, … keeping `readAhead` requests in flight, and yields them in key
+	* order whatever order the answers come in.
+	*/
+	async *read(path, options = {}) {
+		const { start, length, signal } = options;
+		if (length === 0) return;
+		signal?.throwIfAborted();
+		const { streamId } = await this.#rpc.openRead(path, {
+			start,
+			length,
+			streamId: newStreamId$1()
+		});
+		const pending = /* @__PURE__ */ new Map();
+		const aborted = signal ? new Promise((_, reject) => {
+			const fail = () => reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			if (signal.aborted) fail();
+			else signal.addEventListener("abort", fail, { once: true });
+		}) : void 0;
+		aborted?.catch(() => {});
+		let asked = 0;
+		let finished = false;
+		try {
+			for (let next = 0;; next++) {
+				while (!finished && asked < next + this.#readAhead) {
+					const request = this.#rpc.readChunk(streamId, asked);
+					request.catch(() => {});
+					pending.set(asked++, request);
+				}
+				const answer = pending.get(next);
+				pending.delete(next);
+				const { data, done } = await (aborted ? Promise.race([answer, aborted]) : answer);
+				signal?.throwIfAborted();
+				if (done) finished = true;
+				const bytes = toBytes$1(data);
+				if (bytes.length) yield bytes;
+				if (done) return;
+				signal?.throwIfAborted();
+			}
+		} finally {
+			await this.#rpc.closeRead(streamId).catch(() => {});
+		}
+	}
+	/**
+	* Sends chunks of `chunkSize` bytes keyed 0, 1, 2, … with up to `writeAhead` unacknowledged,
+	* then `closeWrite` with their count; any failure aborts the write.
+	*/
+	async write(path, content) {
+		const { streamId } = await this.#rpc.openWrite(path, { streamId: newStreamId$1() });
+		const inFlight = /* @__PURE__ */ new Set();
+		let failure;
+		let count = 0;
+		try {
+			for await (const chunk of rechunk(content, this.#chunkSize)) {
+				if (failure) throw failure.error;
+				const sent = this.#rpc.writeChunk(streamId, count++, chunk).then(() => {
+					inFlight.delete(sent);
+				}, (error) => {
+					inFlight.delete(sent);
+					failure ??= { error };
+				});
+				inFlight.add(sent);
+				while (inFlight.size >= this.#writeAhead) await Promise.race(inFlight);
+			}
+			await Promise.all(inFlight);
+			if (failure) throw failure.error;
+			await this.#rpc.closeWrite(streamId, count);
+		} catch (e) {
+			await this.#rpc.abortWrite(streamId, String(e?.message ?? e)).catch(() => {});
+			throw e;
+		}
+	}
+	async mkdir(path) {
+		await this.#rpc.mkdir(path);
+	}
+	/** Pages of `pageSize`, each asked after the last path of the one before. */
+	async *list(path, options = {}) {
+		let after = options.after;
+		for (;;) {
+			const page = await this.#rpc.list(path, {
+				recursive: options.recursive,
+				after,
+				limit: this.#pageSize
+			});
+			yield* page.entries;
+			if (!page.more || page.entries.length === 0) return;
+			after = page.entries[page.entries.length - 1]?.path;
+		}
+	}
+	stats(path) {
+		return this.#rpc.stats(path);
+	}
+	exists(path) {
+		return this.#rpc.exists(path);
+	}
+	remove(path) {
+		return this.#rpc.remove(path);
+	}
+	move(source, target) {
+		return this.#rpc.move(source, target);
+	}
+	copy(source, target) {
+		return this.#rpc.copy(source, target);
+	}
+};
+/** A FilesApi over a FilesRpc. */
+function newFilesRpcClient(options) {
+	return new FilesRpcClient(options);
+}
+//#endregion
+//#region src/errors.ts
+/**
+* An error of the protocol itself. The code also leads the message (`UNKNOWN_STREAM: …`), since
+* a structured clone keeps an error's name and message but not its other properties:
+* `errorCode(e)` reads it back on the other side of a transport.
+*/
+var FilesRpcError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(`${code}: ${message}`);
+		this.name = "FilesRpcError";
+		this.code = code;
+	}
+};
+/** The FilesRpcError code of an error, also after it crossed a transport; undefined otherwise. */
+function errorCode(e) {
+	const code = e?.code;
+	if (typeof code === "string") return code;
+	return /^(UNKNOWN_STREAM|CHUNK_RELEASED|TOO_MANY_STREAMS|ABORTED|INVALID):/.exec(String(e?.message ?? ""))?.[1];
+}
+//#endregion
+//#region src/keyed.ts
+/**
+* Values kept by key, and waiters for keys that have no value yet: what both ends of a stream
+* use to keep chunks by chunkId and wait for the ones still on their way.
+*/
+var Keyed = class {
+	#values = /* @__PURE__ */ new Map();
+	#waiters = /* @__PURE__ */ new Map();
+	#failure;
+	get size() {
+		return this.#values.size;
+	}
+	has(key) {
+		return this.#values.has(key);
+	}
+	get(key) {
+		return this.#values.get(key);
+	}
+	keys() {
+		return this.#values.keys();
+	}
+	/** Keeps `value` under `key` and wakes whoever waits for it. */
+	put(key, value) {
+		this.#values.set(key, value);
+		const waiting = this.#waiters.get(key);
+		if (!waiting) return;
+		this.#waiters.delete(key);
+		for (const w of waiting) w.resolve(value);
+	}
+	delete(key) {
+		this.#values.delete(key);
+	}
+	/** The value of `key`: now if kept, else when it is put (or the whole set fails). */
+	wait(key) {
+		if (this.#values.has(key)) return Promise.resolve(this.#values.get(key));
+		if (this.#failure) return Promise.reject(this.#failure.error);
+		return new Promise((resolve, reject) => {
+			const list = this.#waiters.get(key);
+			if (list) list.push({
+				resolve,
+				reject
+			});
+			else this.#waiters.set(key, [{
+				resolve,
+				reject
+			}]);
+		});
+	}
+	/** Answers every waiter for a key at or above `from` with `value` (the end of a stream). */
+	settleFrom(from, value) {
+		for (const [key, waiting] of [...this.#waiters]) {
+			if (key < from) continue;
+			this.#waiters.delete(key);
+			for (const w of waiting) w.resolve(value(key));
+		}
+	}
+	/** Fails every waiter, now and later. */
+	fail(error) {
+		this.#failure ??= { error };
+		for (const waiting of this.#waiters.values()) for (const w of waiting) w.reject(error);
+		this.#waiters.clear();
+	}
+};
+//#endregion
+//#region src/server.ts
+const EMPTY = /* @__PURE__ */ new Uint8Array();
+const STREAM_ID = /^[A-Za-z0-9_-]{16,128}$/;
+function newStreamId() {
+	return crypto.randomUUID().replace(/-/g, "");
+}
+function toBytes(data) {
+	if (data instanceof Uint8Array) return data;
+	if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	throw new FilesRpcError("INVALID", "a chunk is a Uint8Array or an ArrayBuffer");
+}
+function chunkIdOf(v) {
+	const n = Number(v);
+	if (!Number.isSafeInteger(n) || n < 0) throw new FilesRpcError("INVALID", `a chunk id is an integer from 0 (got ${String(v)})`);
+	return n;
+}
+/** Orders paths by Unicode code point, as `FilesApi.list()` does (webrun-files' comparePaths). */
+function comparePaths(a, b) {
+	const x = a[Symbol.iterator]();
+	const y = b[Symbol.iterator]();
+	for (;;) {
+		const p = x.next();
+		const q = y.next();
+		if (p.done || q.done) return p.done && q.done ? 0 : p.done ? -1 : 1;
+		const d = p.value.codePointAt(0) - q.value.codePointAt(0);
+		if (d !== 0) return d;
+	}
+}
+/** Joins the first `n` buffered bytes into one chunk. */
+function take(s, n) {
+	const out = new Uint8Array(n);
+	let at = 0;
+	while (at < n) {
+		const head = s.buffer[0];
+		const part = head.subarray(0, n - at);
+		out.set(part, at);
+		at += part.length;
+		if (part.length === head.length) s.buffer.shift();
+		else s.buffer[0] = head.subarray(part.length);
+	}
+	s.buffered -= n;
+	return out;
+}
+/** Serves a FilesApi as the FilesRpc methods. */
+function newFilesRpcServer(options) {
+	const fs = options.fs;
+	const chunkSize = Math.max(1, options.chunkSize ?? 262144);
+	const readAhead = Math.max(1, options.readAhead ?? 4);
+	const retain = Math.max(1, options.retain ?? 16);
+	const window = Math.max(1, options.window ?? 64);
+	const writeWindow = Math.max(1, options.writeWindow ?? 16);
+	const maxChunkSize = Math.max(1, options.maxChunkSize ?? 4194304);
+	const idleTimeout = options.idleTimeout ?? 12e4;
+	const maxStreams = options.maxStreams ?? 256;
+	const maxPageSize = Math.max(1, options.maxPageSize ?? 256);
+	const now = options.now ?? Date.now;
+	const streams = /* @__PURE__ */ new Map();
+	/**
+	* Streams that ended recently, by id: an open delivered again after its stream ended must not
+	* open it anew, and a closeWrite delivered again answers as the first one did.
+	*/
+	const ended = /* @__PURE__ */ new Map();
+	const finish = (id, failure) => {
+		streams.delete(id);
+		ended.set(id, {
+			at: now(),
+			failure
+		});
+	};
+	const stream = (id, kind) => {
+		const s = streams.get(String(id));
+		if (!s || s.kind !== kind) throw new FilesRpcError("UNKNOWN_STREAM", `no open ${kind} stream '${String(id)}'`);
+		s.touched = now();
+		return s;
+	};
+	/** Runs `work` as a call in progress on `s`: the stream is not idle meanwhile. */
+	const busy = async (s, work) => {
+		s.busy++;
+		try {
+			return await work();
+		} finally {
+			s.busy--;
+			s.touched = now();
+		}
+	};
+	/** An id for a new stream, or the stream an open delivered twice already opened. */
+	const claim = (opts, kind) => {
+		const wanted = opts?.streamId;
+		if (wanted !== void 0) {
+			if (typeof wanted !== "string" || !STREAM_ID.test(wanted)) throw new FilesRpcError("INVALID", "a stream id is 16 to 128 characters of [A-Za-z0-9_-]");
+			const existing = streams.get(wanted);
+			if (existing) {
+				if (existing.kind !== kind) throw new FilesRpcError("INVALID", `stream '${wanted}' is a ${existing.kind} stream`);
+				return {
+					id: wanted,
+					existing
+				};
+			}
+			if (ended.has(wanted)) throw new FilesRpcError("INVALID", `stream '${wanted}' has ended`);
+		}
+		server.sweep();
+		if (streams.size >= maxStreams) throw new FilesRpcError("TOO_MANY_STREAMS", `at most ${maxStreams} open streams`);
+		return { id: wanted ?? newStreamId() };
+	};
+	/** Pulls the source until `readAhead` chunks from the highest asked exist, or it ends. */
+	const wanted = (s) => !s.ended && !s.closed && s.error === void 0 && s.produced < s.asked + readAhead;
+	const pump = (s) => {
+		if (s.pumping) return s.pumping;
+		const run = (async () => {
+			await void 0;
+			while (wanted(s)) {
+				if (s.buffered > chunkSize) {
+					const id = s.produced++;
+					s.chunks.put(id, {
+						data: take(s, chunkSize),
+						done: false
+					});
+					continue;
+				}
+				let next;
+				try {
+					next = await s.source.next();
+				} catch (e) {
+					while (s.buffered > 0) {
+						const id = s.produced++;
+						s.chunks.put(id, {
+							data: take(s, Math.min(chunkSize, s.buffered)),
+							done: false
+						});
+					}
+					s.error = e;
+					s.chunks.fail(e);
+					return;
+				}
+				if (next.done) {
+					while (s.buffered > chunkSize) {
+						const id = s.produced++;
+						s.chunks.put(id, {
+							data: take(s, chunkSize),
+							done: false
+						});
+					}
+					const id = s.produced++;
+					s.chunks.put(id, {
+						data: s.buffered ? take(s, s.buffered) : EMPTY,
+						done: true
+					});
+					s.ended = true;
+					s.chunks.settleFrom(s.produced, () => ({
+						data: EMPTY,
+						done: true
+					}));
+					return;
+				}
+				let part;
+				try {
+					part = toBytes(next.value);
+				} catch {
+					s.error = new FilesRpcError("INVALID", "the source yielded something that is not bytes");
+					s.chunks.fail(s.error);
+					return;
+				}
+				if (part.length) {
+					s.buffer.push(part);
+					s.buffered += part.length;
+				}
+			}
+		})();
+		s.pumping = run;
+		run.finally(() => {
+			s.pumping = void 0;
+			if (wanted(s)) pump(s);
+		});
+		return run;
+	};
+	const closeSource = async (s) => {
+		s.closed = true;
+		s.chunks.fail(new FilesRpcError("UNKNOWN_STREAM", "the stream was closed"));
+		await s.pumping?.catch(() => {});
+		await Promise.resolve(s.source.return?.()).catch(() => {});
+	};
+	/** The chunks of a write stream in order, as they arrive: what the FilesApi's write consumes. */
+	async function* ordered(s) {
+		for (;;) {
+			s.touched = now();
+			if (s.failure !== void 0) throw s.failure;
+			const chunk = s.chunks.get(s.next);
+			if (chunk) {
+				s.chunks.delete(s.next);
+				s.next++;
+				for (const r of s.room.filter((r) => r.chunkId < s.next + writeWindow)) {
+					s.room.splice(s.room.indexOf(r), 1);
+					r.resolve();
+				}
+				yield chunk;
+				continue;
+			}
+			if (s.total !== void 0 && s.next >= s.total) return;
+			await new Promise((resolve) => {
+				s.wake = resolve;
+			});
+			s.wake = void 0;
+		}
+	}
+	const failWrite = (s, failure) => {
+		s.failure ??= failure;
+		for (const r of s.room.splice(0)) r.reject(s.failure);
+		s.wake?.();
+	};
+	const server = {
+		async stats(path) {
+			return fs.stats(path);
+		},
+		async exists(path) {
+			return fs.exists(path);
+		},
+		async mkdir(path) {
+			await fs.mkdir(path);
+		},
+		async remove(path) {
+			return fs.remove(path);
+		},
+		async move(source, target) {
+			return fs.move(source, target);
+		},
+		async copy(source, target) {
+			return fs.copy(source, target);
+		},
+		async list(path, opts = {}) {
+			const limit = Math.min(Math.max(1, Math.floor(Number(opts.limit) || maxPageSize)), maxPageSize);
+			const entries = [];
+			let more = false;
+			const after = opts.after;
+			for await (const entry of fs.list(path, {
+				recursive: !!opts.recursive,
+				after
+			})) {
+				if (after !== void 0 && comparePaths(entry.path, after) <= 0) continue;
+				if (entries.length === limit) {
+					more = true;
+					break;
+				}
+				entries.push({ ...entry });
+			}
+			return {
+				entries,
+				more
+			};
+		},
+		async openRead(path, opts = {}) {
+			const { id, existing } = claim(opts, "read");
+			if (existing) return { streamId: id };
+			const length = opts.length;
+			const source = length === 0 ? (async function* () {})() : fs.read(path, {
+				start: opts.start,
+				length
+			})[Symbol.asyncIterator]();
+			streams.set(id, {
+				kind: "read",
+				touched: now(),
+				busy: 0,
+				source,
+				chunks: new Keyed(),
+				buffer: [],
+				buffered: 0,
+				produced: 0,
+				low: 0,
+				delivered: /* @__PURE__ */ new Set(),
+				asked: 0,
+				released: 0,
+				ended: false,
+				closed: false
+			});
+			return { streamId: id };
+		},
+		async readChunk(streamId, chunkIdArg) {
+			const s = stream(streamId, "read");
+			const chunkId = chunkIdOf(chunkIdArg);
+			if (chunkId >= s.low + window) throw new FilesRpcError("INVALID", `chunk ${chunkId} is more than ${window} chunks past the lowest undelivered (${s.low})`);
+			if (chunkId < s.released && chunkId < s.produced && !s.chunks.has(chunkId)) throw new FilesRpcError("CHUNK_RELEASED", `chunk ${chunkId} of '${streamId}' was released (the reader moved past it)`);
+			if (chunkId > s.asked) {
+				s.asked = chunkId;
+				const keepFrom = s.asked - retain + 1;
+				for (; s.released < keepFrom; s.released++) if (s.released < s.low || s.delivered.has(s.released)) s.chunks.delete(s.released);
+			}
+			if (s.ended && chunkId >= s.produced) return {
+				data: EMPTY,
+				done: true
+			};
+			return busy(s, async () => {
+				const answer = s.chunks.wait(chunkId);
+				pump(s);
+				const result = await answer;
+				if (chunkId === s.low) {
+					s.low++;
+					while (s.delivered.delete(s.low)) s.low++;
+				} else if (chunkId > s.low) s.delivered.add(chunkId);
+				if (chunkId < s.released) s.chunks.delete(chunkId);
+				return result;
+			});
+		},
+		async closeRead(streamId) {
+			const s = streams.get(String(streamId));
+			if (s?.kind !== "read") return;
+			finish(String(streamId));
+			await closeSource(s);
+		},
+		async openWrite(path, opts = {}) {
+			const { id, existing } = claim(opts, "write");
+			if (existing) return { streamId: id };
+			const s = {
+				kind: "write",
+				touched: now(),
+				busy: 0,
+				chunks: /* @__PURE__ */ new Map(),
+				next: 0,
+				room: [],
+				done: Promise.resolve()
+			};
+			s.done = fs.write(path, ordered(s)).then(() => {
+				if (s.failure !== void 0) throw s.failure;
+			}, (e) => {
+				failWrite(s, e);
+				throw s.failure;
+			});
+			s.done.catch(() => {});
+			streams.set(id, s);
+			return { streamId: id };
+		},
+		async writeChunk(streamId, chunkIdArg, data) {
+			const s = stream(streamId, "write");
+			const chunkId = chunkIdOf(chunkIdArg);
+			const bytes = toBytes(data);
+			if (bytes.length > maxChunkSize) throw new FilesRpcError("INVALID", `a chunk is at most ${maxChunkSize} bytes`);
+			if (s.failure !== void 0) throw s.failure;
+			if (s.total !== void 0 && chunkId >= s.total) throw new FilesRpcError("INVALID", `chunk ${chunkId} is past the stream's ${s.total} chunks`);
+			if (chunkId < s.next || s.chunks.has(chunkId)) return;
+			if (chunkId >= s.next + 2 * writeWindow) throw new FilesRpcError("INVALID", `chunk ${chunkId} is more than ${2 * writeWindow} chunks past the next to write (${s.next})`);
+			if (chunkId >= s.next + writeWindow) {
+				await busy(s, () => new Promise((resolve, reject) => s.room.push({
+					chunkId,
+					resolve,
+					reject
+				})));
+				if (chunkId < s.next || s.chunks.has(chunkId)) return;
+			}
+			s.chunks.set(chunkId, bytes.slice());
+			if (chunkId === s.next) s.wake?.();
+		},
+		async closeWrite(streamId, chunksArg) {
+			const id = String(streamId);
+			const done = ended.get(id);
+			if (done && !streams.has(id)) {
+				if (done.failure !== void 0) throw done.failure;
+				return;
+			}
+			const s = stream(id, "write");
+			const total = chunkIdOf(chunksArg);
+			const highest = Math.max(s.next - 1, ...s.chunks.keys());
+			if (highest >= total) {
+				const error = new FilesRpcError("INVALID", `the stream has chunk ${highest}, so more than ${total} chunks`);
+				failWrite(s, error);
+				finish(id, error);
+				throw error;
+			}
+			s.total = total;
+			for (const r of s.room.filter((r) => r.chunkId >= total)) {
+				s.room.splice(s.room.indexOf(r), 1);
+				r.reject(new FilesRpcError("INVALID", `chunk ${r.chunkId} is past the stream's ${total} chunks`));
+			}
+			s.wake?.();
+			try {
+				await busy(s, () => s.done);
+				if (streams.get(id) === s) finish(id);
+			} catch (e) {
+				if (streams.get(id) === s) finish(id, e);
+				throw e;
+			}
+		},
+		async abortWrite(streamId, reason) {
+			const id = String(streamId);
+			const s = streams.get(id);
+			if (s?.kind !== "write") return;
+			if (s.total !== void 0 && s.next >= s.total) return;
+			const error = new FilesRpcError("ABORTED", reason ? String(reason) : "the write was aborted");
+			finish(id, error);
+			failWrite(s, error);
+		},
+		sweep() {
+			const t = now();
+			let dropped = 0;
+			for (const [id, s] of [...streams]) {
+				if (t - s.touched <= idleTimeout) continue;
+				if (s.kind === "read" && s.busy > 0) continue;
+				if (s.kind === "write" && (s.chunks.has(s.next) || s.total !== void 0 && s.next >= s.total)) continue;
+				dropped++;
+				const error = new FilesRpcError("ABORTED", "the stream was idle too long");
+				finish(id, error);
+				if (s.kind === "read") closeSource(s);
+				else failWrite(s, error);
+			}
+			for (const [id, e] of [...ended]) if (t - e.at > idleTimeout) ended.delete(id);
+			return dropped;
+		},
+		openStreams() {
+			return streams.size;
+		},
+		async close() {
+			if (timer) clearInterval(timer);
+			const sources = [];
+			for (const [id, s] of [...streams]) {
+				const error = new FilesRpcError("ABORTED", "the server closed");
+				finish(id, error);
+				if (s.kind === "read") sources.push(closeSource(s));
+				else failWrite(s, error);
+			}
+			await Promise.race([Promise.all(sources), new Promise((r) => {
+				setTimeout(r, 1e3).unref?.();
+			})]);
+		}
+	};
+	const timer = options.sweepInterval && options.sweepInterval > 0 ? setInterval(() => server.sweep(), options.sweepInterval) : void 0;
+	timer?.unref?.();
+	return server;
+}
+//#endregion
+export { FilesRpcClient, FilesRpcError, errorCode, newFilesRpcClient, newFilesRpcServer };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * webrun-files-rpc: a FilesApi over any RPC. The server serves a FilesApi as plain calls; the
+ * client is a FilesApi over them. Content is streamed as chunks keyed by (streamId, chunkId):
+ * both sides keep chunks by their key and wait for those still on their way, so calls may arrive
+ * out of order, concurrently, or twice.
+ */
+export { FilesRpcClient, type FilesRpcClientOptions, newFilesRpcClient } from "./client.js";
+export { errorCode, FilesRpcError } from "./errors.js";
+export { type FilesRpcServer, type FilesRpcServerOptions, newFilesRpcServer } from "./server.js";
+export type { FilesRpc, FilesRpcErrorCode, ListPage, ListPageOptions, OpenOptions, OpenReadOptions, ReadResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjG,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,WAAW,EACX,eAAe,EACf,UAAU,GACX,MAAM,YAAY,CAAC"}