@statewalker/webrun-files-rpc 0.1.0 → 0.1.1

package/README.md

@@ -7,7 +7,7 @@ A `FilesApi` (from `@statewalker/webrun-files`) over any RPC, with streamed read
 - **Server** (`newFilesRpcServer({ fs })`): serves any `FilesApi` as plain method calls.
 - **Client** (`newFilesRpcClient({ rpc })`): a `FilesApi` whose every call goes through those
   methods: a Durable Object or Workers RPC stub, comlink, `@statewalker/webrun-rpc`, or the server
-  object itself.
+  object itself. It also appends (`append(path, content)`), which `FilesApi` does not.
 
 Content moves as **chunks keyed by `(streamId, chunkId)`**. Both sides keep chunks by their key
 and wait for the ones still on their way:
@@ -37,10 +37,13 @@ Keys make the calls safe on real transports:
   - a chunk read twice is answered twice;
   - an open with the same `streamId` opens one stream;
   - a `closeWrite` delivered again answers as the first did.
-  - Metadata calls carry no key. Delivered twice with no other write in between, `mkdir`,
-    `remove`, `move` and `copy` end in the same state, but each answers for the state it finds: a
-    `remove`, `move` or `copy` delivered twice may report `false` though the first one did it. A
-    `copy` retried after something else wrote to the target copies again.
+  - a metadata call (`mkdir`, `remove`, `move`, `copy`) with a `requestId` runs once: delivered
+    again, concurrently or later, it gets the first answer (or failure). The server keeps answers
+    for `idleTimeout`, at most `maxRequests` of them. The client sends a fresh `requestId` with
+    every such call.
+  - Without a `requestId`, a metadata call delivered twice runs twice: the end state is the same
+    when nothing else writes in between, but the second may report `false` though the first did
+    it, and a late `copy` retry copies again.
 
 ## How to use
 
@@ -58,8 +61,8 @@ Exports:
 - `newFilesRpcServer`, `newFilesRpcClient`, `FilesRpcClient`;
 - `FilesRpcError` and `errorCode`;
 - types `FilesRpc`, `FilesRpcServer`, `FilesRpcServerOptions`, `FilesRpcClientOptions`,
-  `ReadResult`, `ListPage`, `ListPageOptions`, `OpenOptions`, `OpenReadOptions`,
-  `FilesRpcErrorCode`.
+  `AppendableFilesApi`, `ReadResult`, `ListPage`, `ListPageOptions`, `OpenOptions`,
+  `OpenReadOptions`, `OpenWriteOptions`, `RequestOptions`, `FilesRpcErrorCode`.
 
 ### `newFilesRpcServer(options)`
 
@@ -75,6 +78,7 @@ Exports:
 | `idleTimeout` | 2 min | A stream not used for this long is dropped (a read closed, a write aborted). |
 | `maxStreams` | 256 | Open streams at most (`TOO_MANY_STREAMS` beyond). |
 | `maxPageSize` | 256 | Largest listing page. |
+| `maxRequests` | 1024 | Answers of metadata calls kept by `requestId` (oldest dropped beyond). |
 | `sweepInterval` | none | Sweep idle streams every this many ms. Without it, opening a stream sweeps; a server that stops receiving opens needs this (or calls to `sweep()`). |
 | `now` | `Date.now` | The clock (tests). |
 
@@ -94,6 +98,9 @@ The server is a `FilesRpc` plus:
 | `writeAhead` | 4 | `writeChunk` calls not yet answered while writing. |
 | `pageSize` | 256 | Listing page size. |
 
+Besides the `FilesApi` methods, the client has `append(path, content)`: it adds `content` to the
+end of `path` (creating it if it does not exist), streamed exactly as `write` streams.
+
 ### The protocol (`FilesRpc`)
 
 Every argument and result is a plain value: strings, numbers, booleans, plain objects and
@@ -104,12 +111,13 @@ Every argument and result is a plain value: strings, numbers, booleans, plain ob
 | `openRead(path, {start?, length?, streamId?})` | `{streamId}`; a file that does not exist reads as nothing |
 | `readChunk(streamId, chunkId)` | `{data, done}` once chunk `chunkId` exists; past the end `{data: empty, done: true}` |
 | `closeRead(streamId)` | ends the stream (unknown or ended: nothing happens) |
-| `openWrite(path, {streamId?})` | `{streamId}`; the `FilesApi`'s `write` starts consuming chunks in order |
+| `openWrite(path, {streamId?, append?})` | `{streamId}`; the `FilesApi`'s `write` (or, with `append`, the append) starts consuming chunks in order |
 | `writeChunk(streamId, chunkId, data)` | resolves once the chunk is kept (within `writeWindow` of the next to write: at once) |
 | `closeWrite(streamId, chunks)` | resolves once all `chunks` chunks are written |
 | `abortWrite(streamId, reason?)` | cancels the write (unknown or ended: nothing happens) |
 | `list(path, {recursive?, after?, limit?})` | `{entries, more}`; ask again with `after` = the last path |
-| `stats`, `exists`, `mkdir`, `remove`, `move`, `copy` | as the `FilesApi` |
+| `stats`, `exists` | as the `FilesApi` |
+| `mkdir(path, {requestId?})`, `remove(path, {requestId?})`, `move(source, target, {requestId?})`, `copy(source, target, {requestId?})` | as the `FilesApi`; with a `requestId`, once (a call delivered again gets the first answer) |
 
 - **Stream ids:** `streamId` may be chosen by the caller: 16 to 128 characters of `[A-Za-z0-9_-]`,
   random, such as `crypto.randomUUID()` without dashes. Then an open delivered twice opens one
@@ -216,6 +224,27 @@ await server.closeRead(r);
     keeps what it had.
   - `write()` starts at `openWrite`, not at the first chunk. A FilesApi that truncates when a
     write starts has emptied the file already if the write is then aborted.
+- **Appends:** `openWrite(path, { append: true })` streams like a write, and the chunks go to the
+  end of the file.
+  - A served FilesApi with an `append(path, content)` method (`AppendableFilesApi`) appends
+    through it, with whatever atomicity it gives.
+  - Any other FilesApi is appended to with `read`, `write` and `remove` only, in two steps:
+    1. the file's content and the chunks are written to a temporary sibling,
+       `.<name>.append-<id>` (the name cut to 64 characters, the stream id to 16);
+    2. the sibling is written back over the file, then removed.
+  - It never reads and writes one path at once, so a FilesApi that empties a file when a write
+    starts is safe. Only a directory is refused (`INVALID`); `stats` saying the file is missing is
+    not trusted, since reading a missing file yields nothing and the file is created all the same.
+  - A failure or an abort during step 1 leaves the file as it was and removes the sibling. An
+    abort counts until step 2 starts, even after every chunk was sent. A failure during step 2
+    may leave the file incomplete, so the sibling, the only complete copy, is kept and its path
+    is in the error.
+  - Appends to one file (by its normal path) through one server run one after the other. Other
+    writers are not excluded. The emulation copies the file twice and shows the sibling in
+    listings while it runs.
+  - `close()` and expiry leave a write whose outcome is the FilesApi's alone (every chunk handed
+    over, or an emulated append writing back), so a `closeWrite` waiting on it gets the real
+    outcome.
 - **Ended streams:** ids that ended are remembered for `idleTimeout`. Within that time, an open
   delivered after its stream ended does not reopen it, and a `closeWrite` delivered again gets the
   first answer.
@@ -235,8 +264,8 @@ await server.closeRead(r);
 - **The client:**
   - **Read:** it keeps `readAhead` `readChunk` calls in flight and yields the answers in key
     order. Breaking out of the loop, or aborting through `signal`, closes the stream.
-  - **Write:** it cuts any sequence of byte arrays into chunks of exactly `chunkSize` and keeps
-    `writeAhead` unanswered. Any failure (of the source, or of a call) aborts the write.
+  - **Write and append:** it cuts any sequence of byte arrays into chunks of exactly `chunkSize`
+    and keeps `writeAhead` unanswered. Any failure (of the source, or of a call) aborts the write.
   - **List:** it asks page after page with `after`. The server also applies `after` itself, in
     code-point order, so a FilesApi that ignores it cannot make pages repeat.
 - **Not covered:**
@@ -257,9 +286,10 @@ encoding come from `webrun-files-tests`.
 | `server-read.test.ts` | numbered chunks with `done`, out-of-order and concurrent requests, ranges, missing files, retries, release, bounded read-ahead, closing, failing sources |
 | `server-write.test.ts` | in-order and out-of-order chunks, duplicates, backpressure, `closeWrite` waiting for a gap or refusing a wrong count, empty files, abort, failing writes, byte types |
 | `server-lifecycle.test.ts` | idle expiry, the stream limit, `close()`, unguessable ids, paged listing, metadata |
-| `protocol.test.ts` | caller-chosen keys (opens and `closeWrite` delivered twice, after the end), what is refused, waiting requests failed by a close, error codes across a structured clone, many streams at once, release never dropping an undelivered chunk, metadata calls delivered twice |
+| `protocol.test.ts` | caller-chosen keys (opens and `closeWrite` delivered twice, after the end), what is refused, waiting requests failed by a close, error codes across a structured clone, many streams at once, release never dropping an undelivered chunk, metadata calls delivered twice (with a `requestId`: once, the same answer, failures too, kept for `idleTimeout` and `maxRequests`; without: the same end state) |
 | `robustness.test.ts` | the window (huge chunk ids refused at once, bounded pulls), busy streams not swept, writes too far ahead refused, writes waiting for the holder swept, the sweep timer, a failing write's error reaching the client, a late abort not undoing a commit, a source yielding non-bytes, waiters past the count, aborting a hanging read, `close()` not hanging, listing with a FilesApi that ignores `after` |
 | `client.test.ts` | the `FilesApi` round trip, iterables, ranges, pipelining depth, early stop and abort, failing sources, write depth, listing; delayed, reordered and duplicated calls (five seeds) |
-| `conformance.test.ts` | the repository's `FilesApi` suite (`webrun-files-tests`) on the client over the server: directly, and through the transport simulator (cloned, reordered, every call but `remove`/`move`/`copy` delivered twice at random) |
+| `append.test.ts` | appends through the FilesApi's own `append` and through the emulation, also on a FilesApi that writes as it goes: existing and missing files, large files, aborts (also after every chunk was sent) and failing sources leaving the file unchanged and no temporary file, a failed write-back keeping the temporary copy, `close()` during the write-back, two appends at once, `stats` not trusted, odd paths and long names, directories refused; over the transport simulator; an open delivered twice |
+| `conformance.test.ts` | the repository's `FilesApi` suite (`webrun-files-tests`) on the client over the server: directly, and through the transport simulator (cloned, reordered, every call delivered twice at random) |
 | `big-files.test.ts` | the repository's big-file suite (64 MiB) on the client over the server, every call structured-cloned |
 | `readme.test.ts` | the examples above |

package/dist/cjs/index.cjs

@@ -56,8 +56,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;
@@ -82,6 +83,7 @@ var FilesRpcClient = class {
 				signal?.throwIfAborted();
 			}
 		} finally {
+			if (fail) signal?.removeEventListener("abort", fail);
 			await this.#rpc.closeRead(streamId).catch(() => {});
 		}
 	}
@@ -90,7 +92,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;
@@ -115,7 +130,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 = {}) {
@@ -138,13 +153,13 @@ 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. */
@@ -169,9 +184,18 @@ 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];
 }
+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("|")}):`);
 //#endregion
 //#region src/keyed.ts
 /**
@@ -238,6 +262,22 @@ var Keyed = class {
 };
 //#endregion
 //#region 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() {
@@ -300,6 +340,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, {
@@ -442,6 +516,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);
@@ -454,17 +574,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);
@@ -557,7 +677,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);
@@ -621,7 +741,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);
@@ -640,6 +760,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() {
@@ -649,6 +770,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));

package/dist/client.d.ts

@@ -26,6 +26,11 @@ export declare class FilesRpcClient implements FilesApi {
      * then `closeWrite` with their count; any failure aborts the write.
      */
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * 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.
+     */
+    append(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
     mkdir(path: string): Promise<void>;
     /** Pages of `pageSize`, each asked after the last path of the one before. */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;

package/dist/client.d.ts.map

@@ -1 +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"}
+{"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,CA4C9E;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,CAEf;IAED;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAEf;IAsCK,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.map

@@ -1 +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"}
+{"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,CAMnE"}

package/dist/esm/index.js

@@ -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,13 +152,13 @@ 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. */
@@ -168,9 +183,18 @@ 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];
 }
+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("|")}):`);
 //#endregion
 //#region src/keyed.ts
 /**
@@ -237,6 +261,22 @@ var Keyed = class {
 };
 //#endregion
 //#region 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 +339,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 +515,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 +573,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 +676,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 +740,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 +759,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 +769,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));

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":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE/E,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,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;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,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,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;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnF;;;;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-rpc",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "FilesApi over any RPC: streamed reads and writes as chunks kept and awaited by (streamId, chunkId)",

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";

package/src/server.ts

@@ -1,7 +1,16 @@
 import type { FileInfo, FilesApi } from "@statewalker/webrun-files";
 import { FilesRpcError } from "./errors.js";
 import { Keyed } from "./keyed.js";
-import type { FilesRpc, ListPage, OpenOptions, OpenReadOptions, ReadResult } from "./types.js";
+import type {
+  AppendableFilesApi,
+  FilesRpc,
+  ListPage,
+  OpenOptions,
+  OpenReadOptions,
+  OpenWriteOptions,
+  ReadResult,
+  RequestOptions,
+} from "./types.js";
 
 export interface FilesRpcServerOptions {
   /** The file system served. */
@@ -30,6 +39,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`. */
@@ -89,10 +100,33 @@ interface WriteStream {
   room: { chunkId: number; resolve: () => void; reject: (e: unknown) => void }[];
   failure?: unknown;
   done: Promise<void>;
+  /** An append the server emulates; `committing` once it writes the file back. */
+  emulated?: boolean;
+  committing?: boolean;
 }
 
 type Stream = ReadStream | WriteStream;
 
+/**
+ * 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: WriteStream): boolean =>
+  s.total !== undefined && 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: string): string {
+  const out: string[] = [];
+  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: unknown) => String((e as Error)?.message ?? e);
+
 const EMPTY = new Uint8Array();
 const STREAM_ID = /^[A-Za-z0-9_-]{16,128}$/;
 
@@ -165,6 +199,44 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
    */
   const ended = new Map<string, { at: number; failure?: unknown }>();
 
+  /** Answers of metadata calls, by method and requestId, oldest first. */
+  const requests = new Map<string, { at: number; settled: boolean; answer: Promise<unknown> }>();
+  const maxRequests = Math.max(1, options.maxRequests ?? 1024);
+  /** Runs `call` once per requestId (within idleTimeout): a call delivered again gets its answer. */
+  const once = <T>(method: string, opts: RequestOptions | undefined, call: () => Promise<T>) => {
+    const id = opts?.requestId;
+    if (id === undefined) 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 as Promise<T>;
+    const answer = call();
+    answer.catch(() => {});
+    const entry = { at: now(), settled: false, answer };
+    requests.set(key, entry);
+    // Kept for idleTimeout after it settled (a call still running is not forgotten).
+    const settle = () => {
+      entry.at = now();
+      entry.settled = true;
+    };
+    void answer.then(settle, settle);
+    // Past the cap, the oldest settled answer goes: forgetting a call still running would let a
+    // retry run it again. Only when every call is running does the oldest of them go.
+    while (requests.size > maxRequests) {
+      let victim: string | undefined;
+      for (const [k, r] of requests)
+        if (r.settled) {
+          victim = k;
+          break;
+        }
+      requests.delete(victim ?? (requests.keys().next().value as string));
+    }
+    return answer;
+  };
+
   const finish = (id: string, failure?: unknown) => {
     streams.delete(id);
     ended.set(id, { at: now(), failure });
@@ -311,6 +383,71 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
     }
   }
 
+  /** Emulated appends in progress, by normal path: one at a time per file. */
+  const appending = new Map<string, Promise<void>>();
+
+  /**
+   * 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: string,
+    content: AsyncIterable<Uint8Array>,
+    id: string,
+    s: WriteStream,
+  ): Promise<void> => {
+    const own = (fs as Partial<AppendableFilesApi>).append;
+    if (typeof own === "function") return own.call(fs, path, content);
+    s.emulated = true;
+    const file = normalPath(path);
+    const previous = appending.get(file) ?? Promise.resolve();
+    const run = previous.then(async () => {
+      // Only a directory is refused: whether the file exists is not trusted (reading a missing
+      // file yields nothing, so a missing file is created all the same).
+      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 !== undefined) throw s.failure; // aborted before the write-back
+      } 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(
+          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);
+    void settled.then(() => {
+      if (appending.get(file) === settled) appending.delete(file);
+    });
+    return run;
+  };
+
   const failWrite = (s: WriteStream, failure: unknown) => {
     s.failure ??= failure;
     for (const r of s.room.splice(0)) r.reject(s.failure);
@@ -324,17 +461,17 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
     async exists(path) {
       return fs.exists(path);
     },
-    async mkdir(path) {
-      await fs.mkdir(path);
+    async mkdir(path, opts?: RequestOptions) {
+      await once("mkdir", opts, () => fs.mkdir(path));
     },
-    async remove(path) {
-      return fs.remove(path);
+    async remove(path, opts?: RequestOptions) {
+      return once("remove", opts, () => fs.remove(path));
     },
-    async move(source, target) {
-      return fs.move(source, target);
+    async move(source, target, opts?: RequestOptions) {
+      return once("move", opts, () => fs.move(source, target));
     },
-    async copy(source, target) {
-      return fs.copy(source, target);
+    async copy(source, target, opts?: RequestOptions) {
+      return once("copy", opts, () => fs.copy(source, target));
     },
     async list(path, opts = {}): Promise<ListPage> {
       const limit = Math.min(
@@ -429,7 +566,7 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
       await closeSource(s);
     },
 
-    async openWrite(path, opts: OpenOptions = {}) {
+    async openWrite(path, opts: OpenWriteOptions = {}) {
       const { id, existing } = claim(opts, "write");
       if (existing) return { streamId: id };
       const s: WriteStream = {
@@ -441,7 +578,7 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
         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 !== undefined) throw s.failure;
         },
@@ -530,8 +667,9 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
       const id = String(streamId);
       const s = streams.get(id);
       if (s?.kind !== "write") return;
-      // Every chunk was handed to the FilesApi: the commit is under way; an abort is too late.
-      if (s.total !== undefined && s.next >= s.total) return;
+      // The outcome is the FilesApi's now (every chunk handed over; an emulated append already
+      // writing back): an abort is too late.
+      if (committed(s)) return;
       const error = new FilesRpcError("ABORTED", reason ? String(reason) : "the write was aborted");
       finish(id, error);
       failWrite(s, error);
@@ -557,6 +695,8 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
         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;
     },
 
@@ -568,6 +708,11 @@ export function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServe
       if (timer) clearInterval(timer);
       const sources: Promise<unknown>[] = [];
       for (const [id, s] of [...streams]) {
+        // A write whose outcome is the FilesApi's keeps it: a closeWrite waiting on it gets that.
+        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));

package/src/types.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 {
@@ -29,6 +29,34 @@ 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;
@@ -50,10 +78,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. */
@@ -66,8 +94,11 @@ export interface FilesRpc {
   /** 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<{ streamId: string }>;
+  /**
+   * Opens `path` for writing (or, with `append`, for appending); the FilesApi consumes the chunks
+   * in order.
+   */
+  openWrite(path: string, options?: OpenWriteOptions): Promise<{ streamId: string }>;
   /**
    * Hands over chunk `chunkId`. Resolves once it is kept (not yet written): at once if it is
    * within `writeWindow` chunks of the next to write, else when it is. A chunk already received