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

package/dist/keyed.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export declare class Keyed<T> {
+    #private;
+    get size(): number;
+    has(key: number): boolean;
+    get(key: number): T | undefined;
+    keys(): IterableIterator<number>;
+    /** Keeps `value` under `key` and wakes whoever waits for it. */
+    put(key: number, value: T): void;
+    delete(key: number): void;
+    /** The value of `key`: now if kept, else when it is put (or the whole set fails). */
+    wait(key: number): Promise<T>;
+    /** Answers every waiter for a key at or above `from` with `value` (the end of a stream). */
+    settleFrom(from: number, value: (key: number) => T): void;
+    /** Fails every waiter, now and later. */
+    fail(error: unknown): void;
+}
+//# sourceMappingURL=keyed.d.ts.map

package/dist/keyed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../src/keyed.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,KAAK,CAAC,CAAC;;IAKlB,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;IACD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAE9B;IACD,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAE/B;IACD,gEAAgE;IAChE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAM/B;IACD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAExB;IACD,qFAAqF;IACrF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ5B;IACD,4FAA4F;IAC5F,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,IAAI,CAMxD;IACD,yCAAyC;IACzC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAIzB;CACF"}

package/dist/server.d.ts

@@ -0,0 +1,49 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { FilesRpc } from "./types.js";
+export interface FilesRpcServerOptions {
+    /** The file system served. */
+    fs: FilesApi;
+    /** Largest chunk a read stream answers. Default 256 KiB. */
+    chunkSize?: number;
+    /** Chunks produced ahead, counting from the highest one asked. Default 4. */
+    readAhead?: number;
+    /** A chunk is released once the reader asked for one `retain` chunks past it. Default 16. */
+    retain?: number;
+    /**
+     * A read request may name a chunk at most this many past the lowest chunk not yet delivered
+     * (INVALID beyond). Bounds what one stream makes the server pull and hold. Default 64.
+     */
+    window?: number;
+    /**
+     * Chunks of a write kept ahead of the next one to write. Default 16. One window more may wait
+     * for room; a chunk beyond is refused (INVALID).
+     */
+    writeWindow?: number;
+    /** Largest chunk a write takes. Default 4 MiB. */
+    maxChunkSize?: number;
+    /** A stream not used for this long is dropped (reads closed, writes aborted). Default 2 min. */
+    idleTimeout?: number;
+    /** Open streams at most. Default 256. */
+    maxStreams?: number;
+    /** Largest listing page. Default 256. */
+    maxPageSize?: number;
+    /** Sweeps idle streams every this many ms (default: only when a stream is opened). */
+    sweepInterval?: number;
+    /** The clock (tests). Default `Date.now`. */
+    now?: () => number;
+}
+/** The server: the RPC methods, plus maintenance. */
+export interface FilesRpcServer extends FilesRpc {
+    /** Drops idle streams; returns how many. Opening a stream does it too. */
+    sweep(): number;
+    /** Streams open now. */
+    openStreams(): number;
+    /**
+     * Ends every stream (reads closed, writes aborted) and stops the sweep timer. It does not wait
+     * for the FilesApi's writes to settle, and waits at most a second for sources to end.
+     */
+    close(): Promise<void>;
+}
+/** Serves a FilesApi as the FilesRpc methods. */
+export declare function newFilesRpcServer(options: FilesRpcServerOptions): FilesRpcServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +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"}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+import type { FileInfo, FileStats } from "@statewalker/webrun-files";
+/** One chunk of a read stream: its bytes, and whether it is the last. */
+export interface ReadResult {
+    data: Uint8Array;
+    done: boolean;
+}
+/** One page of a listing. `more`: ask again with `after` = the last path of this page. */
+export interface ListPage {
+    entries: FileInfo[];
+    more: boolean;
+}
+/** One page of `list`: `after` the given path (exclusive), at most `limit` entries. */
+export interface ListPageOptions {
+    recursive?: boolean;
+    after?: string;
+    limit?: number;
+}
+/** Open options shared by reads and writes. */
+export interface OpenOptions {
+    /**
+     * The stream's id, chosen by the caller (16 to 128 characters of `[A-Za-z0-9_-]`, random:
+     * `crypto.randomUUID()`), so that an open delivered twice opens one stream. Without it the
+     * server chooses one.
+     */
+    streamId?: string;
+}
+export interface OpenReadOptions extends OpenOptions {
+    /** First byte (default 0). */
+    start?: number;
+    /** Bytes to read (default: to the end). */
+    length?: number;
+}
+/**
+ * What the server exposes and the client calls: a FilesApi cut into calls an RPC can carry.
+ * Every argument and result is a plain value (strings, numbers, booleans, plain objects,
+ * Uint8Array), so any transport that passes structured-clonable values carries it: Durable
+ * Object and Workers RPC, postMessage, comlink, or a direct call.
+ *
+ * Content moves as chunks keyed by (streamId, chunkId). chunkId counts from 0 in each stream.
+ * Both sides keep chunks by their key and wait for the ones that have not arrived: the server
+ * answers `readChunk(id, k)` once chunk k exists, and writes chunk k once chunks 0..k-1 are
+ * written, whatever order they came in. Calls delivered twice are harmless.
+ */
+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>;
+    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<{
+        streamId: string;
+    }>;
+    /**
+     * Chunk `chunkId` of the stream, once it exists. Past the end: empty and done. A chunk can be
+     * asked again (a retry) until the reader has moved `retain` chunks past it.
+     */
+    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<{
+        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
+     * is ignored.
+     */
+    writeChunk(streamId: string, chunkId: number, data: Uint8Array | ArrayBuffer): Promise<void>;
+    /** The stream had `chunks` chunks: resolves when all of them are written. */
+    closeWrite(streamId: string, chunks: number): Promise<void>;
+    /** Cancels the write (unknown or closed: nothing happens). */
+    abortWrite(streamId: string, reason?: string): Promise<void>;
+}
+/** Error codes of FilesRpcError. */
+export type FilesRpcErrorCode = "UNKNOWN_STREAM" | "CHUNK_RELEASED" | "TOO_MANY_STREAMS" | "ABORTED" | "INVALID";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@statewalker/webrun-files-rpc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "FilesApi over any RPC: streamed reads and writes as chunks kept and awaited by (streamId, chunkId)",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-files/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-files/tree/main/packages/webrun-files-rpc#readme",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statewalker/webrun-files.git",
+    "directory": "packages/webrun-files-rpc"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "^0.10.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "rimraf": "^6.1.3",
+    "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"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
+  }
 }

package/src/client.ts

@@ -0,0 +1,200 @@
+import type {
+  FileInfo,
+  FileStats,
+  FilesApi,
+  ListOptions,
+  ReadOptions,
+} from "@statewalker/webrun-files";
+import type { FilesRpc, ReadResult } from "./types.js";
+
+export interface FilesRpcClientOptions {
+  /** The server's methods, through any transport (a stub, a proxy, the server itself). */
+  rpc: FilesRpc;
+  /** Bytes per chunk written. Default 256 KiB (keep it at most the server's `maxChunkSize`). */
+  chunkSize?: number;
+  /** Chunk requests kept in flight while reading. Default 4 (below the server's `window`). */
+  readAhead?: number;
+  /** Chunks sent and not yet acknowledged while writing. Default 4. */
+  writeAhead?: number;
+  /** Listing page size. Default 256. */
+  pageSize?: number;
+}
+
+const toBytes = (v: unknown): Uint8Array =>
+  v instanceof Uint8Array
+    ? v
+    : ArrayBuffer.isView(v)
+      ? new Uint8Array(v.buffer, v.byteOffset, v.byteLength)
+      : new Uint8Array(v as ArrayBuffer);
+
+const newStreamId = () => crypto.randomUUID().replace(/-/g, "");
+
+/** Cuts any sequence of byte arrays into chunks of exactly `size` bytes (the last may be shorter). */
+async function* rechunk(
+  content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  size: number,
+): AsyncGenerator<Uint8Array> {
+  let carry: Uint8Array | undefined;
+  let carried = 0;
+  for await (const piece of content as AsyncIterable<Uint8Array>) {
+    let part = toBytes(piece);
+    while (part.length) {
+      if (!carry && part.length >= size) {
+        yield part.slice(0, size);
+        part = part.subarray(size);
+        continue;
+      }
+      carry ??= new Uint8Array(size);
+      const n = Math.min(size - carried, part.length);
+      carry.set(part.subarray(0, n), carried);
+      carried += n;
+      part = part.subarray(n);
+      if (carried === size) {
+        yield carry;
+        carry = undefined;
+        carried = 0;
+      }
+    }
+  }
+  if (carry && carried) yield carry.slice(0, carried);
+}
+
+/** A FilesApi whose every call goes through a FilesRpc; content moves in keyed chunks. */
+export class FilesRpcClient implements FilesApi {
+  #rpc: FilesRpc;
+  #chunkSize: number;
+  #readAhead: number;
+  #writeAhead: number;
+  #pageSize: number;
+
+  constructor(options: FilesRpcClientOptions) {
+    this.#rpc = options.rpc;
+    this.#chunkSize = Math.max(1, options.chunkSize ?? 256 * 1024);
+    this.#readAhead = Math.max(1, options.readAhead ?? 4);
+    this.#writeAhead = Math.max(1, options.writeAhead ?? 4);
+    this.#pageSize = Math.max(1, options.pageSize ?? 256);
+  }
+
+  /**
+   * Asks for chunks 0, 1, 2, … keeping `readAhead` requests in flight, and yields them in key
+   * order whatever order the answers come in.
+   */
+  async *read(path: string, options: ReadOptions = {}): AsyncIterable<Uint8Array> {
+    const { start, length, signal } = options;
+    if (length === 0) return;
+    signal?.throwIfAborted();
+    const { streamId } = await this.#rpc.openRead(path, {
+      start,
+      length,
+      streamId: newStreamId(),
+    });
+    const pending = new Map<number, Promise<ReadResult>>();
+    // An abort interrupts the wait for an answer, not only the loop between answers.
+    const aborted = signal
+      ? new Promise<never>((_, reject) => {
+          const fail = () => reject(signal.reason ?? new Error("aborted"));
+          if (signal.aborted) fail();
+          else signal.addEventListener("abort", fail, { once: true });
+        })
+      : undefined;
+    aborted?.catch(() => {});
+    let asked = 0;
+    let finished = false;
+    try {
+      for (let next = 0; ; next++) {
+        while (!finished && asked < next + this.#readAhead) {
+          const request = this.#rpc.readChunk(streamId, asked);
+          request.catch(() => {}); // awaited below, in order
+          pending.set(asked++, request);
+        }
+        const answer = pending.get(next) as Promise<ReadResult>;
+        pending.delete(next);
+        const { data, done } = await (aborted ? Promise.race([answer, aborted]) : answer);
+        signal?.throwIfAborted();
+        if (done) finished = true;
+        const bytes = toBytes(data);
+        if (bytes.length) yield bytes;
+        if (done) return;
+        signal?.throwIfAborted();
+      }
+    } finally {
+      await this.#rpc.closeRead(streamId).catch(() => {});
+    }
+  }
+
+  /**
+   * Sends chunks of `chunkSize` bytes keyed 0, 1, 2, … with up to `writeAhead` unacknowledged,
+   * then `closeWrite` with their count; any failure aborts the write.
+   */
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    const { streamId } = await this.#rpc.openWrite(path, { streamId: newStreamId() });
+    const inFlight = new Set<Promise<void>>();
+    let failure: { error: unknown } | undefined;
+    let count = 0;
+    try {
+      for await (const chunk of rechunk(content, this.#chunkSize)) {
+        if (failure) throw failure.error;
+        const sent: Promise<void> = this.#rpc.writeChunk(streamId, count++, chunk).then(
+          () => {
+            inFlight.delete(sent);
+          },
+          (error) => {
+            inFlight.delete(sent);
+            failure ??= { error };
+          },
+        );
+        inFlight.add(sent);
+        while (inFlight.size >= this.#writeAhead) await Promise.race(inFlight);
+      }
+      await Promise.all(inFlight);
+      if (failure) throw failure.error;
+      await this.#rpc.closeWrite(streamId, count);
+    } catch (e) {
+      await this.#rpc.abortWrite(streamId, String((e as Error)?.message ?? e)).catch(() => {});
+      throw e;
+    }
+  }
+
+  async mkdir(path: string): Promise<void> {
+    await this.#rpc.mkdir(path);
+  }
+
+  /** Pages of `pageSize`, each asked after the last path of the one before. */
+  async *list(path: string, options: ListOptions = {}): AsyncIterable<FileInfo> {
+    let after = options.after;
+    for (;;) {
+      const page = await this.#rpc.list(path, {
+        recursive: options.recursive,
+        after,
+        limit: this.#pageSize,
+      });
+      yield* page.entries;
+      if (!page.more || page.entries.length === 0) return;
+      after = page.entries[page.entries.length - 1]?.path;
+    }
+  }
+
+  stats(path: string): Promise<FileStats | undefined> {
+    return this.#rpc.stats(path);
+  }
+  exists(path: string): Promise<boolean> {
+    return this.#rpc.exists(path);
+  }
+  remove(path: string): Promise<boolean> {
+    return this.#rpc.remove(path);
+  }
+  move(source: string, target: string): Promise<boolean> {
+    return this.#rpc.move(source, target);
+  }
+  copy(source: string, target: string): Promise<boolean> {
+    return this.#rpc.copy(source, target);
+  }
+}
+
+/** A FilesApi over a FilesRpc. */
+export function newFilesRpcClient(options: FilesRpcClientOptions): FilesRpcClient {
+  return new FilesRpcClient(options);
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import type { FilesRpcErrorCode } from "./types.js";
+
+/**
+ * An error of the protocol itself. The code also leads the message (`UNKNOWN_STREAM: …`), since
+ * a structured clone keeps an error's name and message but not its other properties:
+ * `errorCode(e)` reads it back on the other side of a transport.
+ */
+export class FilesRpcError extends Error {
+  readonly code: FilesRpcErrorCode;
+  constructor(code: FilesRpcErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = "FilesRpcError";
+    this.code = code;
+  }
+}
+
+/** The FilesRpcError code of an error, also after it crossed a transport; undefined otherwise. */
+export function errorCode(e: unknown): FilesRpcErrorCode | undefined {
+  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 ?? ""),
+  );
+  return m?.[1] as FilesRpcErrorCode | undefined;
+}

package/src/index.ts

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

package/src/keyed.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+export class Keyed<T> {
+  #values = new Map<number, T>();
+  #waiters = new Map<number, { resolve: (v: T) => void; reject: (e: unknown) => void }[]>();
+  #failure: { error: unknown } | undefined;
+
+  get size(): number {
+    return this.#values.size;
+  }
+  has(key: number): boolean {
+    return this.#values.has(key);
+  }
+  get(key: number): T | undefined {
+    return this.#values.get(key);
+  }
+  keys(): IterableIterator<number> {
+    return this.#values.keys();
+  }
+  /** Keeps `value` under `key` and wakes whoever waits for it. */
+  put(key: number, value: T): void {
+    this.#values.set(key, value);
+    const waiting = this.#waiters.get(key);
+    if (!waiting) return;
+    this.#waiters.delete(key);
+    for (const w of waiting) w.resolve(value);
+  }
+  delete(key: number): void {
+    this.#values.delete(key);
+  }
+  /** The value of `key`: now if kept, else when it is put (or the whole set fails). */
+  wait(key: number): Promise<T> {
+    if (this.#values.has(key)) return Promise.resolve(this.#values.get(key) as T);
+    if (this.#failure) return Promise.reject(this.#failure.error);
+    return new Promise<T>((resolve, reject) => {
+      const list = this.#waiters.get(key);
+      if (list) list.push({ resolve, reject });
+      else this.#waiters.set(key, [{ resolve, reject }]);
+    });
+  }
+  /** Answers every waiter for a key at or above `from` with `value` (the end of a stream). */
+  settleFrom(from: number, value: (key: number) => T): void {
+    for (const [key, waiting] of [...this.#waiters]) {
+      if (key < from) continue;
+      this.#waiters.delete(key);
+      for (const w of waiting) w.resolve(value(key));
+    }
+  }
+  /** Fails every waiter, now and later. */
+  fail(error: unknown): void {
+    this.#failure ??= { error };
+    for (const waiting of this.#waiters.values()) for (const w of waiting) w.reject(error);
+    this.#waiters.clear();
+  }
+}