@statewalker/webrun-files-rpc 0.1.0 → 0.1.2

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-//#region src/client.ts
+// 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). */
@@ -55,8 +55,9 @@ var FilesRpcClient = class {
 			streamId: newStreamId$1()
 		});
 		const pending = /* @__PURE__ */ new Map();
+		let fail;
 		const aborted = signal ? new Promise((_, reject) => {
-			const fail = () => reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			fail = () => reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
 			if (signal.aborted) fail();
 			else signal.addEventListener("abort", fail, { once: true });
 		}) : void 0;
@@ -81,6 +82,7 @@ var FilesRpcClient = class {
 				signal?.throwIfAborted();
 			}
 		} finally {
+			if (fail) signal?.removeEventListener("abort", fail);
 			await this.#rpc.closeRead(streamId).catch(() => {});
 		}
 	}
@@ -89,7 +91,20 @@ var FilesRpcClient = class {
 	* then `closeWrite` with their count; any failure aborts the write.
 	*/
 	async write(path, content) {
-		const { streamId } = await this.#rpc.openWrite(path, { streamId: newStreamId$1() });
+		return this.#send(path, content, false);
+	}
+	/**
+	* Adds `content` to the end of `path` (creating it if it does not exist), streamed as `write`
+	* streams. The server appends through the served FilesApi's own `append`, or emulates it.
+	*/
+	async append(path, content) {
+		return this.#send(path, content, true);
+	}
+	async #send(path, content, append) {
+		const { streamId } = await this.#rpc.openWrite(path, {
+			streamId: newStreamId$1(),
+			...append ? { append: true } : {}
+		});
 		const inFlight = /* @__PURE__ */ new Set();
 		let failure;
 		let count = 0;
@@ -114,7 +129,7 @@ var FilesRpcClient = class {
 		}
 	}
 	async mkdir(path) {
-		await this.#rpc.mkdir(path);
+		await this.#rpc.mkdir(path, { requestId: newStreamId$1() });
 	}
 	/** Pages of `pageSize`, each asked after the last path of the one before. */
 	async *list(path, options = {}) {
@@ -137,21 +152,20 @@ var FilesRpcClient = class {
 		return this.#rpc.exists(path);
 	}
 	remove(path) {
-		return this.#rpc.remove(path);
+		return this.#rpc.remove(path, { requestId: newStreamId$1() });
 	}
 	move(source, target) {
-		return this.#rpc.move(source, target);
+		return this.#rpc.move(source, target, { requestId: newStreamId$1() });
 	}
 	copy(source, target) {
-		return this.#rpc.copy(source, target);
+		return this.#rpc.copy(source, target, { requestId: newStreamId$1() });
 	}
 };
 /** A FilesApi over a FilesRpc. */
 function newFilesRpcClient(options) {
 	return new FilesRpcClient(options);
 }
-//#endregion
-//#region src/errors.ts
+// 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:
@@ -168,11 +182,19 @@ var FilesRpcError = class extends Error {
 /** 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];
+	if (typeof code === "string" && CODES.has(code)) return code;
+	return LEADING_CODE.exec(String(e?.message ?? ""))?.[1];
 }
-//#endregion
-//#region src/keyed.ts
+const CODES = /* @__PURE__ */ new Set([
+	"UNKNOWN_STREAM",
+	"CHUNK_RELEASED",
+	"TOO_MANY_STREAMS",
+	"ABORTED",
+	"INVALID"
+]);
+/** A message led by a code, as FilesRpcError writes it (`CODE: …`). */
+const LEADING_CODE = new RegExp(`^(${[...CODES].join("|")}):`);
+// 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.
@@ -235,8 +257,23 @@ var Keyed = class {
 		this.#waiters.clear();
 	}
 };
-//#endregion
-//#region src/server.ts
+// src/server.ts
+/**
+* Whether a write's outcome is the FilesApi's alone: every chunk was handed to it (an emulated
+* append, until its write-back starts, can still be cancelled).
+*/
+const committed = (s) => s.total !== void 0 && s.next >= s.total && (!s.emulated || s.committing === true);
+/** `path` in normal form: one leading slash, no empty, "." or ".." segments, no trailing slash. */
+function normalPath(path) {
+	const out = [];
+	for (const seg of String(path).split("/")) {
+		if (!seg || seg === ".") continue;
+		if (seg === "..") out.pop();
+		else out.push(seg);
+	}
+	return `/${out.join("/")}`;
+}
+const messageOf = (e) => String(e?.message ?? e);
 const EMPTY = /* @__PURE__ */ new Uint8Array();
 const STREAM_ID = /^[A-Za-z0-9_-]{16,128}$/;
 function newStreamId() {
@@ -299,6 +336,40 @@ function newFilesRpcServer(options) {
 	* open it anew, and a closeWrite delivered again answers as the first one did.
 	*/
 	const ended = /* @__PURE__ */ new Map();
+	/** Answers of metadata calls, by method and requestId, oldest first. */
+	const requests = /* @__PURE__ */ new Map();
+	const maxRequests = Math.max(1, options.maxRequests ?? 1024);
+	/** Runs `call` once per requestId (within idleTimeout): a call delivered again gets its answer. */
+	const once = (method, opts, call) => {
+		const id = opts?.requestId;
+		if (id === void 0) return call();
+		if (typeof id !== "string" || !STREAM_ID.test(id)) return Promise.reject(new FilesRpcError("INVALID", "a requestId is 16 to 128 characters of [A-Za-z0-9_-]"));
+		const key = `${method} ${id}`;
+		const kept = requests.get(key);
+		if (kept) return kept.answer;
+		const answer = call();
+		answer.catch(() => {});
+		const entry = {
+			at: now(),
+			settled: false,
+			answer
+		};
+		requests.set(key, entry);
+		const settle = () => {
+			entry.at = now();
+			entry.settled = true;
+		};
+		answer.then(settle, settle);
+		while (requests.size > maxRequests) {
+			let victim;
+			for (const [k, r] of requests) if (r.settled) {
+				victim = k;
+				break;
+			}
+			requests.delete(victim ?? requests.keys().next().value);
+		}
+		return answer;
+	};
 	const finish = (id, failure) => {
 		streams.delete(id);
 		ended.set(id, {
@@ -441,6 +512,52 @@ function newFilesRpcServer(options) {
 			s.wake = void 0;
 		}
 	}
+	/** Emulated appends in progress, by normal path: one at a time per file. */
+	const appending = /* @__PURE__ */ new Map();
+	/**
+	* Appends `content` to `path`: through the FilesApi's own `append`, or with read, write and
+	* remove only. The emulation never reads and writes one path at once (a FilesApi may empty a
+	* file when a write starts):
+	*  1. the file's content and the chunks go to a temporary sibling;
+	*  2. that sibling is written back over the file, then removed.
+	* A failure or an abort in step 1 leaves the file as it was and removes the sibling. A failure
+	* in step 2 keeps the sibling (the only complete copy) and names it in the error. Appends to
+	* one file through this server run one after the other; other writers are not excluded.
+	*/
+	const append = async (path, content, id, s) => {
+		const own = fs.append;
+		if (typeof own === "function") return own.call(fs, path, content);
+		s.emulated = true;
+		const file = normalPath(path);
+		const run = (appending.get(file) ?? Promise.resolve()).then(async () => {
+			if ((await fs.stats(file))?.kind === "directory") throw new FilesRpcError("INVALID", `cannot append to a directory: ${file}`);
+			const slash = file.lastIndexOf("/");
+			const temp = `${file.slice(0, slash + 1)}.${file.slice(slash + 1, slash + 65)}.append-${id.slice(0, 16)}`;
+			try {
+				await fs.write(temp, (async function* () {
+					yield* fs.read(file);
+					yield* content;
+				})());
+				if (s.failure !== void 0) throw s.failure;
+			} catch (e) {
+				await fs.remove(temp).catch(() => {});
+				throw e;
+			}
+			s.committing = true;
+			try {
+				await fs.write(file, fs.read(temp));
+			} catch (e) {
+				throw Object.assign(/* @__PURE__ */ new Error(`${messageOf(e)} (the append failed while writing ${file} back: it may be incomplete; its content and the appended chunks are kept in ${temp})`), { cause: e });
+			}
+			await fs.remove(temp).catch(() => {});
+		});
+		const settled = run.catch(() => {});
+		appending.set(file, settled);
+		settled.then(() => {
+			if (appending.get(file) === settled) appending.delete(file);
+		});
+		return run;
+	};
 	const failWrite = (s, failure) => {
 		s.failure ??= failure;
 		for (const r of s.room.splice(0)) r.reject(s.failure);
@@ -453,17 +570,17 @@ function newFilesRpcServer(options) {
 		async exists(path) {
 			return fs.exists(path);
 		},
-		async mkdir(path) {
-			await fs.mkdir(path);
+		async mkdir(path, opts) {
+			await once("mkdir", opts, () => fs.mkdir(path));
 		},
-		async remove(path) {
-			return fs.remove(path);
+		async remove(path, opts) {
+			return once("remove", opts, () => fs.remove(path));
 		},
-		async move(source, target) {
-			return fs.move(source, target);
+		async move(source, target, opts) {
+			return once("move", opts, () => fs.move(source, target));
 		},
-		async copy(source, target) {
-			return fs.copy(source, target);
+		async copy(source, target, opts) {
+			return once("copy", opts, () => fs.copy(source, target));
 		},
 		async list(path, opts = {}) {
 			const limit = Math.min(Math.max(1, Math.floor(Number(opts.limit) || maxPageSize)), maxPageSize);
@@ -556,7 +673,7 @@ function newFilesRpcServer(options) {
 				room: [],
 				done: Promise.resolve()
 			};
-			s.done = fs.write(path, ordered(s)).then(() => {
+			s.done = (opts.append ? append(path, ordered(s), id, s) : fs.write(path, ordered(s))).then(() => {
 				if (s.failure !== void 0) throw s.failure;
 			}, (e) => {
 				failWrite(s, e);
@@ -620,7 +737,7 @@ function newFilesRpcServer(options) {
 			const id = String(streamId);
 			const s = streams.get(id);
 			if (s?.kind !== "write") return;
-			if (s.total !== void 0 && s.next >= s.total) return;
+			if (committed(s)) return;
 			const error = new FilesRpcError("ABORTED", reason ? String(reason) : "the write was aborted");
 			finish(id, error);
 			failWrite(s, error);
@@ -639,6 +756,7 @@ function newFilesRpcServer(options) {
 				else failWrite(s, error);
 			}
 			for (const [id, e] of [...ended]) if (t - e.at > idleTimeout) ended.delete(id);
+			for (const [key, r] of [...requests]) if (r.settled && t - r.at > idleTimeout) requests.delete(key);
 			return dropped;
 		},
 		openStreams() {
@@ -648,6 +766,10 @@ function newFilesRpcServer(options) {
 			if (timer) clearInterval(timer);
 			const sources = [];
 			for (const [id, s] of [...streams]) {
+				if (s.kind === "write" && committed(s)) {
+					streams.delete(id);
+					continue;
+				}
 				const error = new FilesRpcError("ABORTED", "the server closed");
 				finish(id, error);
 				if (s.kind === "read") sources.push(closeSource(s));
@@ -662,5 +784,4 @@ function newFilesRpcServer(options) {
 	timer?.unref?.();
 	return server;
 }
-//#endregion
 export { FilesRpcClient, FilesRpcError, errorCode, newFilesRpcClient, newFilesRpcServer };

package/dist/index.d.ts

@@ -7,5 +7,5 @@
 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";
+export type { AppendableFilesApi, FilesRpc, FilesRpcErrorCode, ListPage, ListPageOptions, OpenOptions, OpenReadOptions, OpenWriteOptions, ReadResult, RequestOptions, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/server.d.ts

@@ -27,6 +27,8 @@ export interface FilesRpcServerOptions {
     maxStreams?: number;
     /** Largest listing page. Default 256. */
     maxPageSize?: number;
+    /** Answers of metadata calls kept by their `requestId` at most (default 1024). */
+    maxRequests?: number;
     /** Sweeps idle streams every this many ms (default: only when a stream is opened). */
     sweepInterval?: number;
     /** The clock (tests). Default `Date.now`. */

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,KAAK,EAAE,QAAQ,EAAsD,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAe,SAAQ,QAAQ;IAC9C,0EAA0E;IAC1E,KAAK,IAAI,MAAM,CAAC;IAChB,wBAAwB;IACxB,WAAW,IAAI,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiGD,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA2bhF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,KAAK,EAEV,QAAQ,EAOT,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAe,SAAQ,QAAQ;IAC9C,0EAA0E;IAC1E,KAAK,IAAI,MAAM,CAAC;IAChB,wBAAwB;IACxB,WAAW,IAAI,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAwHD,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA0iBhF"}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { FileInfo, FileStats } from "@statewalker/webrun-files";
+import type { FileInfo, FileStats, FilesApi } from "@statewalker/webrun-files";
 /** One chunk of a read stream: its bytes, and whether it is the last. */
 export interface ReadResult {
     data: Uint8Array;
@@ -24,6 +24,31 @@ export interface OpenOptions {
      */
     streamId?: string;
 }
+/** Options of the calls that change metadata (`mkdir`, `remove`, `move`, `copy`). */
+export interface RequestOptions {
+    /**
+     * The call's id, chosen by the caller (the same form as a stream id). The server keeps each
+     * id's answer for `idleTimeout` (at most `maxRequests` of them): the same call delivered again
+     * gets that answer and does not run again.
+     */
+    requestId?: string;
+}
+export interface OpenWriteOptions extends OpenOptions {
+    /**
+     * Add the stream's chunks to the end of the file instead of replacing it (a file that does not
+     * exist is created). See `AppendableFilesApi` for how the server appends.
+     */
+    append?: boolean;
+}
+/**
+ * A FilesApi that can append itself. `FilesApi` has no append; a served FilesApi with this method
+ * gets appends through it. Any other is appended to with read, write and remove only: the old
+ * content and the new chunks go to a temporary sibling (`.<name>.append-<streamId>`), which is
+ * then written back over the file and removed.
+ */
+export interface AppendableFilesApi extends FilesApi {
+    append(path: string, content: AsyncIterable<Uint8Array>): Promise<void>;
+}
 export interface OpenReadOptions extends OpenOptions {
     /** First byte (default 0). */
     start?: number;
@@ -44,10 +69,10 @@ export interface OpenReadOptions extends OpenOptions {
 export interface FilesRpc {
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
-    mkdir(path: string): Promise<void>;
-    remove(path: string): Promise<boolean>;
-    move(source: string, target: string): Promise<boolean>;
-    copy(source: string, target: string): Promise<boolean>;
+    mkdir(path: string, options?: RequestOptions): Promise<void>;
+    remove(path: string, options?: RequestOptions): Promise<boolean>;
+    move(source: string, target: string, options?: RequestOptions): Promise<boolean>;
+    copy(source: string, target: string, options?: RequestOptions): Promise<boolean>;
     list(path: string, options?: ListPageOptions): Promise<ListPage>;
     /** Opens `path` for reading. A file that does not exist reads as nothing. */
     openRead(path: string, options?: OpenReadOptions): Promise<{
@@ -60,8 +85,11 @@ export interface FilesRpc {
     readChunk(streamId: string, chunkId: number): Promise<ReadResult>;
     /** Ends the stream (unknown or closed: nothing happens). */
     closeRead(streamId: string): Promise<void>;
-    /** Opens `path` for writing; the FilesApi's `write` consumes the chunks in order. */
-    openWrite(path: string, options?: OpenOptions): Promise<{
+    /**
+     * Opens `path` for writing (or, with `append`, for appending); the FilesApi consumes the chunks
+     * in order.
+     */
+    openWrite(path: string, options?: OpenWriteOptions): Promise<{
         streamId: string;
     }>;
     /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAErE,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,0FAA0F;AAC1F,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACpD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEjE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjF;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClE,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C,qFAAqF;IACrF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,6EAA6E;IAC7E,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,oCAAoC;AACpC,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,SAAS,GACT,SAAS,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-rpc",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "FilesApi over any RPC: streamed reads and writes as chunks kept and awaited by (streamId, chunkId)",
@@ -34,7 +34,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.4"
+    "@statewalker/webrun-files": "^0.10.5"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
@@ -42,8 +42,8 @@
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.4 || ^5.0.3",
-    "@statewalker/webrun-files-mem": "^0.10.4",
-    "@statewalker/webrun-files-tests": "^3.0.0"
+    "@statewalker/webrun-files-tests": "^3.0.0",
+    "@statewalker/webrun-files-mem": "^0.10.5"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/client.ts

@@ -90,9 +90,10 @@ export class FilesRpcClient implements FilesApi {
     });
     const pending = new Map<number, Promise<ReadResult>>();
     // An abort interrupts the wait for an answer, not only the loop between answers.
+    let fail: (() => void) | undefined;
     const aborted = signal
       ? new Promise<never>((_, reject) => {
-          const fail = () => reject(signal.reason ?? new Error("aborted"));
+          fail = () => reject(signal.reason ?? new Error("aborted"));
           if (signal.aborted) fail();
           else signal.addEventListener("abort", fail, { once: true });
         })
@@ -118,6 +119,8 @@ export class FilesRpcClient implements FilesApi {
         signal?.throwIfAborted();
       }
     } finally {
+      // A signal may outlive many reads: each takes its listener away.
+      if (fail) signal?.removeEventListener("abort", fail);
       await this.#rpc.closeRead(streamId).catch(() => {});
     }
   }
@@ -130,7 +133,29 @@ export class FilesRpcClient implements FilesApi {
     path: string,
     content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
   ): Promise<void> {
-    const { streamId } = await this.#rpc.openWrite(path, { streamId: newStreamId() });
+    return this.#send(path, content, false);
+  }
+
+  /**
+   * Adds `content` to the end of `path` (creating it if it does not exist), streamed as `write`
+   * streams. The server appends through the served FilesApi's own `append`, or emulates it.
+   */
+  async append(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    return this.#send(path, content, true);
+  }
+
+  async #send(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+    append: boolean,
+  ): Promise<void> {
+    const { streamId } = await this.#rpc.openWrite(path, {
+      streamId: newStreamId(),
+      ...(append ? { append: true } : {}),
+    });
     const inFlight = new Set<Promise<void>>();
     let failure: { error: unknown } | undefined;
     let count = 0;
@@ -159,7 +184,7 @@ export class FilesRpcClient implements FilesApi {
   }
 
   async mkdir(path: string): Promise<void> {
-    await this.#rpc.mkdir(path);
+    await this.#rpc.mkdir(path, { requestId: newStreamId() });
   }
 
   /** Pages of `pageSize`, each asked after the last path of the one before. */
@@ -184,13 +209,13 @@ export class FilesRpcClient implements FilesApi {
     return this.#rpc.exists(path);
   }
   remove(path: string): Promise<boolean> {
-    return this.#rpc.remove(path);
+    return this.#rpc.remove(path, { requestId: newStreamId() });
   }
   move(source: string, target: string): Promise<boolean> {
-    return this.#rpc.move(source, target);
+    return this.#rpc.move(source, target, { requestId: newStreamId() });
   }
   copy(source: string, target: string): Promise<boolean> {
-    return this.#rpc.copy(source, target);
+    return this.#rpc.copy(source, target, { requestId: newStreamId() });
   }
 }
 

package/src/errors.ts

@@ -16,10 +16,19 @@ export class FilesRpcError extends Error {
 
 /** The FilesRpcError code of an error, also after it crossed a transport; undefined otherwise. */
 export function errorCode(e: unknown): FilesRpcErrorCode | undefined {
+  // Only a protocol code: other errors carry codes of their own (a file system's `ENOENT`).
   const code = (e as { code?: unknown })?.code;
-  if (typeof code === "string") return code as FilesRpcErrorCode;
-  const m = /^(UNKNOWN_STREAM|CHUNK_RELEASED|TOO_MANY_STREAMS|ABORTED|INVALID):/.exec(
-    String((e as Error)?.message ?? ""),
-  );
+  if (typeof code === "string" && CODES.has(code)) return code as FilesRpcErrorCode;
+  const m = LEADING_CODE.exec(String((e as Error)?.message ?? ""));
   return m?.[1] as FilesRpcErrorCode | undefined;
 }
+
+const CODES: ReadonlySet<string> = new Set<FilesRpcErrorCode>([
+  "UNKNOWN_STREAM",
+  "CHUNK_RELEASED",
+  "TOO_MANY_STREAMS",
+  "ABORTED",
+  "INVALID",
+]);
+/** A message led by a code, as FilesRpcError writes it (`CODE: …`). */
+const LEADING_CODE = new RegExp(`^(${[...CODES].join("|")}):`);

package/src/index.ts

@@ -8,11 +8,14 @@ export { FilesRpcClient, type FilesRpcClientOptions, newFilesRpcClient } from ".
 export { errorCode, FilesRpcError } from "./errors.js";
 export { type FilesRpcServer, type FilesRpcServerOptions, newFilesRpcServer } from "./server.js";
 export type {
+  AppendableFilesApi,
   FilesRpc,
   FilesRpcErrorCode,
   ListPage,
   ListPageOptions,
   OpenOptions,
   OpenReadOptions,
+  OpenWriteOptions,
   ReadResult,
+  RequestOptions,
 } from "./types.js";