dofs, computer: expose rename on the public filesystem

The store has implemented transactional file, directory, and symbolic
link moves for some time, covering destination replacement, non-empty
directories, read-only mounts, tombstones, revision stamping, and
subtree tracking. None of that reached Workspace.fs, so a caller had
to copy the source and then delete it, and the Worker shell used that
fallback for mv. A failure between the two steps left the entry at
both paths or a directory half copied.

WorkspaceFilesystem now forwards rename, and WorkspaceFilesystemStub
mirrors it with the usual filesystem observation span, so the Workers
RPC surface matches the in-process one. The shell adapter calls it and
keeps copy-then-delete only for a destination rename refuses to
replace, which is what the shell expects when it merges a tree. No new
method crosses the Cap'n Web boundary: the existing synchronisation
protocol already carries the resulting live entries and tombstones.

Closes #120.

Author: agent

.changeset/expose-fs-rename.md

@@ -0,0 +1,6 @@
+---
+"@cloudflare/dofs": minor
+"@cloudflare/computer": minor
+---
+
+`Workspace.fs` gains `rename(oldPath, newPath)`, exposing the store's existing transactional move through the public surface and through `WorkspaceFilesystemStub`. An existing destination is replaced when the two ends agree on kind — a file or symbolic link for a file or symbolic link, an empty directory for a directory — and the operation reports `ENOENT`, `ENOTEMPTY`, `EISDIR`, `ENOTDIR`, `EINVAL`, and `EROFS` as documented in `docs/04_filesystem_interface.md`. The Worker shell's `mv` now calls it, so an interrupted move no longer leaves the entry at both paths or a directory half copied.

docs/12_worker_backend.md

@@ -223,7 +223,9 @@ policy. The backend does not own the external runtime's lifecycle.
 - **No hard links, no `utimes`.** The adapter throws `ENOSYS` on
   `link` (the store has no hard-link model) and no-ops on
   `utimes` (no atime column). `chmod`, `symlink`, `readlink`,
-  and `lstat` all work end-to-end against the DO's store.
+  `lstat`, and `rename` all work end-to-end against the DO's
+  store, so `mv` moves an entry in one operation instead of
+  copying and then deleting it.
 - **No cross-request reattach.** `ShellWorker.getExec` always
   returns ENOENT; `killExec` is a no-op. Each exec is scoped to
   its own call. The previous in-isolate event log shape didn't

packages/computer/src/backends/worker-shell/adapter.test.ts

@@ -275,6 +275,34 @@ describe("WorkspaceFsAdapter — composites", () => {
     expect(await workspace.fs.readFile("/dst", "utf8")).toBe("hello");
     await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
   });
+
+  it("mv moves through the store's rename rather than copy and delete", async () => {
+    await workspace.fs.writeFile("/src", "hello");
+    const rename = vi.spyOn(stub, "rename");
+    const writeFile = vi.spyOn(stub, "writeFile");
+    await adapter.mv("/src", "/dst");
+    expect(rename).toHaveBeenCalledWith("/src", "/dst");
+    expect(writeFile).not.toHaveBeenCalled();
+  });
+
+  it("mv moves a directory tree in one operation", async () => {
+    await workspace.fs.mkdir("/src/inner", { recursive: true });
+    await workspace.fs.writeFile("/src/inner/b", "b");
+    await adapter.mv("/src", "/dst");
+    expect(await workspace.fs.readFile("/dst/inner/b", "utf8")).toBe("b");
+    await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("mv falls back to copy and delete when rename cannot replace the destination", async () => {
+    await workspace.fs.mkdir("/src", { recursive: true });
+    await workspace.fs.writeFile("/src/a", "a");
+    await workspace.fs.mkdir("/dst", { recursive: true });
+    await workspace.fs.writeFile("/dst/keep", "keep");
+    await adapter.mv("/src", "/dst");
+    expect(await workspace.fs.readFile("/dst/a", "utf8")).toBe("a");
+    expect(await workspace.fs.readFile("/dst/keep", "utf8")).toBe("keep");
+    await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
+  });
 });
 
 describe("WorkspaceFsAdapter — pure utilities", () => {

packages/computer/src/backends/worker-shell/adapter.ts

@@ -3,8 +3,8 @@
 //
 // The adapter is a thin façade. Operations that map one-for-one
 // (writeFile, readdir, mkdir, rm, chmod, symlink, readlink, stat,
-// lstat) forward directly. Operations the stub doesn't expose —
-// appendFile, cp, mv, exists — synthesize from the available
+// lstat, rename) forward directly. Operations the stub doesn't
+// expose — appendFile, cp — synthesize from the available
 // primitives. Hard links and utimes aren't supported: link throws
 // ENOSYS so a script that depends on them fails loudly; utimes
 // is a documented no-op because the store has no atime column.
@@ -50,6 +50,7 @@ export interface WorkspaceFs {
   rm(path: string, options?: RmOptions): Promise<void>;
   chmod(path: string, mode: number): Promise<void>;
   symlink(target: string, path: string): Promise<void>;
+  rename(oldPath: string, newPath: string): Promise<void>;
 }
 
 // Matches the subset of just-bash's IFileSystem the adapter
@@ -213,10 +214,19 @@ export class WorkspaceFsAdapter {
   }
 
   async mv(src: string, dest: string): Promise<void> {
-    // The store doesn't have a native rename today, so model mv as
-    // copy+delete. POSIX mv is atomic when src and dest live on
-    // the same filesystem; this approach isn't, but it matches
-    // what just-bash's other adapters do.
+    // The store renames in one transaction, so an interrupted move can
+    // no longer leave the bytes at both paths or a directory half
+    // copied. A destination that rename refuses to replace — a
+    // non-empty directory, or a directory and a non-directory in
+    // either order — still falls back to copy-then-delete, which is
+    // what the shell's own `mv` expects when it merges a tree.
+    try {
+      await this.#fs.rename(src, dest);
+      return;
+    } catch (err) {
+      const code = (err as { code?: string }).code;
+      if (code !== "ENOTEMPTY" && code !== "EISDIR" && code !== "ENOTDIR") throw err;
+    }
     await this.cp(src, dest, { recursive: true });
     await this.#fs.rm(src, { recursive: true });
   }

packages/computer/src/stub.test.ts

@@ -259,6 +259,50 @@ describe("WorkspaceStub", () => {
     });
   });
 
+  it("fs.rename moves a file in one call", async () => {
+    await withStub(async (ws) => {
+      const stub = ws.stub();
+      await ws.fs.writeFile("/old.txt", "payload");
+      await stub.fs.rename("/old.txt", "/new.txt");
+      expect(await ws.fs.readFile("/new.txt", "utf8")).toBe("payload");
+      await expect(ws.fs.stat("/old.txt")).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("fs.rename moves a directory subtree", async () => {
+    await withStub(async (ws) => {
+      const stub = ws.stub();
+      await ws.fs.mkdir("/src/nested", { recursive: true });
+      await ws.fs.writeFile("/src/nested/a.txt", "a");
+      await stub.fs.rename("/src", "/dst");
+      expect(await ws.fs.readFile("/dst/nested/a.txt", "utf8")).toBe("a");
+      await expect(ws.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("fs.rename replaces an existing file and reports POSIX errors", async () => {
+    await withStub(async (ws) => {
+      const stub = ws.stub();
+      await ws.fs.writeFile("/a.txt", "a");
+      await ws.fs.writeFile("/b.txt", "b");
+      await stub.fs.rename("/a.txt", "/b.txt");
+      expect(await ws.fs.readFile("/b.txt", "utf8")).toBe("a");
+
+      await expect(stub.fs.rename("/missing", "/somewhere")).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+
+      await ws.fs.mkdir("/dir");
+      await ws.fs.writeFile("/dir/child.txt", "c");
+      await ws.fs.writeFile("/file.txt", "f");
+      await expect(stub.fs.rename("/file.txt", "/dir")).rejects.toMatchObject({ code: "EISDIR" });
+      await ws.fs.mkdir("/other");
+      await expect(stub.fs.rename("/other", "/dir")).rejects.toMatchObject({ code: "ENOTEMPTY" });
+      await expect(stub.fs.rename("/dir", "/file.txt")).rejects.toMatchObject({ code: "ENOTDIR" });
+      await expect(stub.fs.rename("/file.txt", "/")).rejects.toMatchObject({ code: "EINVAL" });
+    });
+  });
+
   it("fs.stat propagates ENOENT for missing paths", async () => {
     await withStub(async (ws) => {
       const stub = ws.stub();

packages/computer/src/stub.ts

@@ -268,6 +268,19 @@ export class WorkspaceFilesystemStub extends RpcTarget {
     );
   }
 
+  // Move a path in one store operation. Replaces the copy-then-delete
+  // dance callers used to write, so a failure can no longer leave both
+  // ends behind. Overwrite and error behavior is documented in
+  // docs/04_filesystem_interface.md.
+  rename(oldPath: string, newPath: string): Promise<void> {
+    return withSpan(
+      this.#ws.observer,
+      "workspace.fs.rename",
+      { "workspace.fs.path": oldPath, "workspace.fs.destination": newPath },
+      () => this.#ws.fs.rename(oldPath, newPath),
+    );
+  }
+
   chmod(path: string, mode: number): Promise<void> {
     return withSpan(
       this.#ws.observer,

packages/computer/tests/worker-backend.test.ts

@@ -111,6 +111,17 @@ describe("WorkerShellBackend end-to-end", () => {
     expect(text).toBe("from inside the shell\n");
   });
 
+  it("moves a file with mv through the host's rename over Workers RPC", async () => {
+    const id = freshId();
+    await write(id, "/workspace/old.txt", "payload");
+    // `test -e` on the source proves the adapter renamed rather than
+    // copying and leaving both ends behind.
+    const result = await exec(id, "mv old.txt new.txt && cat new.txt && test -e old.txt");
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stdout).toBe("payload");
+    expect(await read(id, "/workspace/new.txt")).toBe("payload");
+  });
+
   it("reports a non-zero exit code with stderr captured", async () => {
     const id = freshId();
     const result = await exec(id, "ls /nope 2>&1; echo done");

packages/dofs/README.md

@@ -15,7 +15,7 @@ Durable Object SQLite-backed virtual filesystem for Cloudflare Computer.
 This package exposes a JavaScript module, not a CLI. It bundles three layers that can be used independently:
 
 - A `Database` wrapper around Durable Object SQL storage plus `initializeSchema` for the `vfs_*` tables.
-- Filesystem primitives under `src/fs/*` (`mkdir`, `writeFile`, `readFile`, `rm`, `readdir`, `stat`, `lstat`, `chmod`, `find`, `ls`, `grep`, `symlink`, `readlink`, `gc`, `watch`) operating on a `Database`.
+- Filesystem primitives under `src/fs/*` (`mkdir`, `writeFile`, `readFile`, `rm`, `rename`, `readdir`, `stat`, `lstat`, `chmod`, `find`, `ls`, `grep`, `symlink`, `readlink`, `gc`, `watch`) operating on a `Database`.
 - `SQLiteWorkspaceProvider`, a `@platformatic/vfs` adapter that composes those primitives into a node-shaped filesystem (fd table, positional `readSync`/`writeSync`, `watchSync`, symlinks). This is what `computerd` mounts via FUSE.
 - Sync protocol building blocks operating on the same `Database`: `applyChanges`, `stageBlob`, `materialiseChange`, `coalesceChanges`, `fetchChanges`, `fetchObjects`, `hasObjects`, `pushObjects`, `buildManifest`, `currentRev`, `compareChangeCursors`, `readWatermark`/`writeWatermark`, `assertAppliedPushCursor`, and the opt-in ignore matcher `isIgnored` (the default ignore list is empty). The wire wiring lives in `@cloudflare/computer-rpc`.
 

packages/dofs/src/fs/filesystem.test.ts

@@ -115,6 +115,47 @@ describe("WorkspaceFilesystem", () => {
     });
   });
 
+  it("rename moves a file, a directory tree and a symbolic link", async () => {
+    await withFs(async (fs) => {
+      await fs.writeFile("/old.txt", "payload");
+      await fs.rename("/old.txt", "/new.txt");
+      expect(await fs.readFile("/new.txt", "utf8")).toBe("payload");
+      await expect(fs.stat("/old.txt")).rejects.toMatchObject({ code: "ENOENT" });
+
+      await fs.mkdir("/tree/inner", { recursive: true });
+      await fs.writeFile("/tree/inner/a.txt", "a");
+      await fs.rename("/tree", "/moved");
+      expect(await fs.readFile("/moved/inner/a.txt", "utf8")).toBe("a");
+      await expect(fs.stat("/tree")).rejects.toMatchObject({ code: "ENOENT" });
+
+      await fs.symlink("/new.txt", "/link");
+      await fs.rename("/link", "/link2");
+      expect(await fs.readlink("/link2")).toBe("/new.txt");
+    });
+  });
+
+  it("rename replaces a file and reports the documented errors", async () => {
+    await withFs(async (fs) => {
+      await fs.writeFile("/a.txt", "a");
+      await fs.writeFile("/b.txt", "b");
+      await fs.rename("/a.txt", "/b.txt");
+      expect(await fs.readFile("/b.txt", "utf8")).toBe("a");
+
+      await expect(fs.rename("/missing", "/elsewhere")).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(fs.rename("/b.txt", "/no/such/dir/b.txt")).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+
+      await fs.mkdir("/full");
+      await fs.writeFile("/full/child", "c");
+      await fs.mkdir("/empty");
+      await expect(fs.rename("/empty", "/full")).rejects.toMatchObject({ code: "ENOTEMPTY" });
+      await expect(fs.rename("/b.txt", "/full")).rejects.toMatchObject({ code: "EISDIR" });
+      await expect(fs.rename("/full", "/b.txt")).rejects.toMatchObject({ code: "ENOTDIR" });
+      await expect(fs.rename("/b.txt", "/")).rejects.toMatchObject({ code: "EINVAL" });
+    });
+  });
+
   it("chmod updates the stored mode", async () => {
     await withFs(async (fs) => {
       await fs.writeFile("/a", "hi");

packages/dofs/src/fs/filesystem.ts

@@ -22,6 +22,7 @@ import { type MkdirOptions, mkdir } from "./mkdir.js";
 import { type ReaddirOptions, readdir, type WorkspaceDirentResult } from "./readdir.js";
 import { type ReadFileOptions, readFile } from "./readFile.js";
 import { readlink } from "./readlink.js";
+import { rename } from "./rename.js";
 import { type RmOptions, rm } from "./rm.js";
 import { lstat, stat, type WorkspaceStatResult } from "./stat.js";
 import { symlink } from "./symlink.js";
@@ -121,6 +122,21 @@ export class WorkspaceFilesystem {
     rm(this.db, path, options);
   }
 
+  // Move a file, directory or symbolic link in one transaction. An
+  // existing destination is replaced when the two ends agree on kind:
+  // a file or symbolic link replaces a file or symbolic link, and a
+  // directory replaces an empty directory.
+  //
+  // Errors: ENOENT when the source is missing or the destination's
+  // parent does not exist, ENOTEMPTY when the destination is a
+  // non-empty directory, EISDIR when a non-directory would replace a
+  // directory, ENOTDIR when a directory would replace a
+  // non-directory, EINVAL for the root at either end or a directory
+  // moved into itself, and EROFS under a read-only mount.
+  async rename(oldPath: string, newPath: string): Promise<void> {
+    rename(this.db, oldPath, newPath);
+  }
+
   // Change the permission bits on a path. Follows symlinks like
   // POSIX chmod — the change lands on the target, not the link.
   // The supplied mode is masked to twelve bits.