Skip to content

Write HTML. Render video. Built for agents.

fix: readers never see an empty or half-written project file (#4777)

Miguel Ángel567525a8c2e4
diff --git a/packages/cli/src/cloud/download.test.ts b/packages/cli/src/cloud/download.test.ts
index 4c5b4908e8..a4ba1abc6f 100644
--- a/packages/cli/src/cloud/download.test.ts
+++ b/packages/cli/src/cloud/download.test.ts
@@ -1,6 +1,7 @@
import {
chmodSync,
lstatSync,
+ mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
@@ -203,4 +204,21 @@ describe("cloud/download", () => {
expect(readdirSync(dir).sort()).toEqual(["alias.mp4", "target.mp4"]);
},
);
+
+ it.skipIf(process.platform === "win32")(
+ "follows a relative output link inside a linked folder to the real target",
+ async () => {
+ mkdirSync(join(dir, "real/deep/sub"), { recursive: true });
+ mkdirSync(join(dir, "root"));
+ symlinkSync(join(dir, "real/deep/sub"), join(dir, "root/sub"));
+ symlinkSync("../target.mp4", join(dir, "real/deep/sub/alias.mp4"));
+
+ await downloadToFile("https://example/x", join(dir, "root/sub/alias.mp4"), {
+ fetchImpl: makeBytesFetch(new Uint8Array([7])),
+ });
+
+ expect(readFileSync(join(dir, "real/deep/target.mp4"))).toEqual(Buffer.from([7]));
+ expect(readdirSync(join(dir, "root")).sort()).toEqual(["sub"]);
+ },
+ );
});
diff --git a/packages/cli/src/cloud/download.ts b/packages/cli/src/cloud/download.ts
index 6bf3a5e646..63980a234f 100644
--- a/packages/cli/src/cloud/download.ts
+++ b/packages/cli/src/cloud/download.ts
@@ -16,15 +16,14 @@
import {
chmodSync,
createWriteStream,
- lstatSync,
mkdirSync,
mkdtempSync,
- readlinkSync,
renameSync,
rmSync,
statSync,
} from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
+import { resolveWritePath } from "@hyperframes/core/atomic-file";
import { pipeline } from "node:stream/promises";
export interface DownloadOptions {
@@ -69,7 +68,8 @@ export async function downloadToFile(
const total = totalHeader ? Number.parseInt(totalHeader, 10) : undefined;
const totalOpt = total !== undefined && Number.isFinite(total) ? total : undefined;
- const destination = resolveDownloadDestination(destPath);
+ // Writes through a caller-selected symlink, as before.
+ const destination = resolveWritePath(destPath);
const previous = statSync(destination, { throwIfNoEntry: false });
const stage = mkdtempSync(join(dirname(destination), ".hf-download-"));
const stagedFile = join(stage, "download");
@@ -104,13 +104,3 @@ export async function downloadToFile(
}
return { path: destPath, bytes };
}
-
-/** Preserve the existing behavior of writing through a caller-selected symlink. */
-function resolveDownloadDestination(destPath: string): string {
- let destination = resolve(destPath);
- for (let hops = 0; hops < 40; hops++) {
- if (!lstatSync(destination, { throwIfNoEntry: false })?.isSymbolicLink()) return destination;
- destination = resolve(dirname(destination), readlinkSync(destination));
- }
- throw new Error(`Too many symbolic links in download destination: ${destPath}`);
-}
diff --git a/packages/cli/src/server/studioServer.registryInstall.test.ts b/packages/cli/src/server/studioServer.registryInstall.test.ts
index bd21b74bbd..067d94867b 100644
--- a/packages/cli/src/server/studioServer.registryInstall.test.ts
+++ b/packages/cli/src/server/studioServer.registryInstall.test.ts
@@ -15,6 +15,10 @@ import { trackRegistryItemAdded } from "../telemetry/events.js";
import { createStudioServer, type StudioServer } from "./studioServer.js";
vi.mock("../telemetry/events.js", () => ({ trackRegistryItemAdded: vi.fn() }));
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ return { ...actual, writeFileSync: vi.fn(actual.writeFileSync) };
+});
const SCHEMA = "https://hyperframes.heygen.com/schema/registry-item.json";
// Names no other test uses: the registry cache is shared by every test in a run.
@@ -196,6 +200,20 @@ describe("Studio catalog install", () => {
expect(readFileSync(file, "utf-8")).toBe("my own edit");
});
+ it("fits a block to the project by replacing its file whole, never rewriting it in place", async () => {
+ const { link, real } = projectWithRegistry();
+ vi.mocked(writeFileSync).mockClear();
+
+ await installer(link)("studio-drop-block");
+
+ const block = join("scenes", "studio-drop-block.html");
+ expect(readFileSync(join(real, block), "utf-8")).toContain('content="width=1920, height=1080"');
+ const inPlace = vi
+ .mocked(writeFileSync)
+ .mock.calls.filter(([path]) => String(path).endsWith(block));
+ expect(inPlace).toEqual([]);
+ });
+
it("keeps an edit to one block when another block is installed", async () => {
const { link, real } = projectWithRegistry();
const install = installer(link);
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 90c7060b60..4463450418 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -8,7 +8,8 @@
import { Hono, type Context } from "hono";
import { streamSSE } from "hono/streaming";
import { realpath } from "@hyperframes/core";
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from "node:fs";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { createHash } from "node:crypto";
import { fileURLToPath } from "node:url";
import { resolve, join, basename, relative, sep } from "node:path";
@@ -402,7 +403,7 @@ function rewriteWrittenToHostViewport(projectDir: string, written: string[]): vo
return match;
},
);
- writeFileSync(absPath, content, "utf-8");
+ replaceFileAtomically(absPath, content, statSync(absPath).mode);
}
}
diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index ef25941cd6..75c95a1ba2 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -44,6 +44,12 @@
"types": "./dist/safePath.d.ts",
"environments": ["bun", "node"]
},
+ "./atomic-file": {
+ "source": "./src/atomicFile.ts",
+ "runtime": "./dist/atomicFile.js",
+ "types": "./dist/atomicFile.d.ts",
+ "environments": ["bun", "node"]
+ },
"./asset-paths": {
"source": "./src/compiler/rewriteSubCompPaths.ts",
"runtime": "./dist/compiler/rewriteSubCompPaths.js",
diff --git a/packages/core/package.json b/packages/core/package.json
index ad8945b6e4..c2e405e5a6 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -58,6 +58,12 @@
"import": "./src/safePath.ts",
"types": "./src/safePath.ts"
},
+ "./atomic-file": {
+ "bun": "./src/atomicFile.ts",
+ "node": "./dist/atomicFile.js",
+ "import": "./src/atomicFile.ts",
+ "types": "./src/atomicFile.ts"
+ },
"./asset-paths": {
"bun": "./src/compiler/rewriteSubCompPaths.ts",
"node": "./dist/compiler/rewriteSubCompPaths.js",
@@ -492,6 +498,10 @@
"import": "./dist/safePath.js",
"types": "./dist/safePath.d.ts"
},
+ "./atomic-file": {
+ "import": "./dist/atomicFile.js",
+ "types": "./dist/atomicFile.d.ts"
+ },
"./asset-paths": {
"import": "./dist/compiler/rewriteSubCompPaths.js",
"types": "./dist/compiler/rewriteSubCompPaths.d.ts"
diff --git a/packages/core/src/atomicFile.test.ts b/packages/core/src/atomicFile.test.ts
new file mode 100644
index 0000000000..6b65d9b34e
--- /dev/null
+++ b/packages/core/src/atomicFile.test.ts
@@ -0,0 +1,434 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import { lstatSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createFileAtomically, replaceFileAtomically, resolveWritePath } from "./atomicFile.js";
+
+vi.mock("node:crypto", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:crypto")>();
+ return { ...actual, randomBytes: vi.fn(actual.randomBytes) };
+});
+
+/** `<file>.<8 hex>.tmp`, checked without building a regex from a path (Windows paths hold backslashes). */
+function expectTempSiblingOf(tempPath: string, file: string): void {
+ expect(tempPath.startsWith(`${file}.`)).toBe(true);
+ expect(tempPath.slice(file.length)).toMatch(/^\.[0-9a-f]{8}\.tmp$/);
+}
+
+describe("replaceFileAtomically", () => {
+ const dirs: string[] = [];
+
+ afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.length = 0;
+ });
+
+ // Windows needs a privilege to create symlinks.
+ it.skipIf(process.platform === "win32")(
+ "replaces a link at the path, never writing its target",
+ () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-test-"));
+ dirs.push(dir);
+ const target = join(dir, "target.html");
+ const link = join(dir, "link.html");
+ writeFileSync(target, "old");
+ symlinkSync(target, link);
+
+ replaceFileAtomically(link, "new", 0o644);
+
+ expect(readFileSync(target, "utf-8")).toBe("old");
+ expect(lstatSync(link).isSymbolicLink()).toBe(false);
+ },
+ );
+
+ it("writes the sibling completely before replacing the project file", () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-test-"));
+ dirs.push(dir);
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old", { mode: 0o640 });
+ const events: string[] = [];
+ const operations = {
+ writeFileSync: (path: fs.PathLike, ...args: any[]) => {
+ events.push(`write:${String(path)}`);
+ return fs.writeFileSync(path, ...args);
+ },
+ chmodSync: fs.chmodSync,
+ renameSync: (from: fs.PathLike, to: fs.PathLike) => {
+ events.push(`rename:${String(from)}:${String(to)}`);
+ expect(readFileSync(from, "utf-8")).toBe("new complete html");
+ return fs.renameSync(from, to);
+ },
+ unlinkSync: fs.unlinkSync,
+ };
+
+ replaceFileAtomically(file, "new complete html", 0o640, operations);
+
+ expect(events).toHaveLength(2);
+ expect(events[0]!.startsWith("write:")).toBe(true);
+ const tempPath = events[0]!.slice("write:".length);
+ expectTempSiblingOf(tempPath, file);
+ expect(events[1]).toBe(`rename:${tempPath}:${file}`);
+ expect(readFileSync(file, "utf-8")).toBe("new complete html");
+ // Windows keeps only a read-only bit, no group or other permissions.
+ if (process.platform !== "win32") expect(fs.statSync(file).mode & 0o777).toBe(0o640);
+ });
+
+ it("replaces an existing destination", () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-replace-test-"));
+ dirs.push(dir);
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old destination");
+
+ replaceFileAtomically(file, "new destination", 0o640);
+
+ expect(readFileSync(file, "utf-8")).toBe("new destination");
+ });
+
+ it("allocates a distinct temporary sibling for each writer", () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-unique-test-"));
+ dirs.push(dir);
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old");
+ const tempPaths: string[] = [];
+ const operations = {
+ writeFileSync: (path: fs.PathLike, ...args: any[]) => {
+ tempPaths.push(String(path));
+ return fs.writeFileSync(path, ...args);
+ },
+ chmodSync: fs.chmodSync,
+ renameSync: fs.renameSync,
+ unlinkSync: fs.unlinkSync,
+ };
+
+ replaceFileAtomically(file, "first", 0o640, operations);
+ replaceFileAtomically(file, "second", 0o640, operations);
+
+ expect(tempPaths).toHaveLength(2);
+ expect(tempPaths[0]).not.toBe(tempPaths[1]);
+ });
+
+ it("uses a unique temporary sibling and removes it when publication fails", () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-failure-test-"));
+ dirs.push(dir);
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old");
+ const tempPaths: string[] = [];
+ const removed: string[] = [];
+ const operations = {
+ writeFileSync: (path: fs.PathLike, ...args: any[]) => {
+ tempPaths.push(String(path));
+ return fs.writeFileSync(path, ...args);
+ },
+ chmodSync: fs.chmodSync,
+ renameSync: () => {
+ throw new Error("publish failed");
+ },
+ unlinkSync: (path: fs.PathLike) => {
+ removed.push(String(path));
+ return fs.unlinkSync(path);
+ },
+ };
+
+ expect(() => replaceFileAtomically(file, "new", 0o640, operations)).toThrow("publish failed");
+ expect(tempPaths).toHaveLength(1);
+ expectTempSiblingOf(tempPaths[0]!, file);
+ expect(removed).toEqual(tempPaths);
+ });
+
+ it("keeps the default mode when none is given", () => {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-file-mode-test-"));
+ dirs.push(dir);
+ writeFileSync(join(dir, "plain.html"), "x");
+
+ replaceFileAtomically(join(dir, "new.html"), "new");
+
+ expect(fs.statSync(join(dir, "new.html")).mode).toBe(fs.statSync(join(dir, "plain.html")).mode);
+ });
+});
+
+describe("createFileAtomically", () => {
+ const dirs: string[] = [];
+
+ afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.length = 0;
+ });
+
+ function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-create-test-"));
+ dirs.push(dir);
+ return dir;
+ }
+
+ it("publishes a complete file and leaves no temporary sibling", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+ const operations = {
+ writeFileSync: (path: fs.PathLike, ...args: any[]) => {
+ expect(String(path)).not.toBe(file);
+ return fs.writeFileSync(path, ...args);
+ },
+ chmodSync: fs.chmodSync,
+ linkSync: (from: fs.PathLike, to: fs.PathLike) => {
+ expect(readFileSync(from, "utf-8")).toBe("complete html");
+ return fs.linkSync(from, to);
+ },
+ unlinkSync: fs.unlinkSync,
+ };
+
+ createFileAtomically(file, "complete html", operations);
+
+ expect(readFileSync(file, "utf-8")).toBe("complete html");
+ expect(fs.readdirSync(dir)).toEqual(["index.html"]);
+ });
+
+ it("refuses an existing file, keeping it and removing the temporary sibling", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old");
+
+ expect(() => createFileAtomically(file, "new")).toThrow(
+ expect.objectContaining({ code: "EEXIST" }),
+ );
+ expect(readFileSync(file, "utf-8")).toBe("old");
+ expect(fs.readdirSync(dir)).toEqual(["index.html"]);
+ });
+
+ // Windows needs a privilege to create symlinks.
+ it.skipIf(process.platform === "win32")(
+ "refuses a dangling link without creating its target",
+ () => {
+ const dir = tempDir();
+ symlinkSync(join(dir, "target.html"), join(dir, "link.html"));
+
+ expect(() => createFileAtomically(join(dir, "link.html"), "new")).toThrow(
+ expect.objectContaining({ code: "EEXIST" }),
+ );
+ expect(fs.existsSync(join(dir, "target.html"))).toBe(false);
+ },
+ );
+
+ function failingLink(code: string) {
+ return {
+ writeFileSync: fs.writeFileSync,
+ chmodSync: fs.chmodSync,
+ linkSync: () => {
+ throw Object.assign(new Error(code), { code });
+ },
+ unlinkSync: fs.unlinkSync,
+ };
+ }
+
+ it.each(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV", "EISDIR"])(
+ "writes directly on a volume without hard links (%s)",
+ (code) => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+
+ createFileAtomically(file, "html", failingLink(code));
+
+ expect(readFileSync(file, "utf-8")).toBe("html");
+ expect(fs.readdirSync(dir)).toEqual(["index.html"]);
+ },
+ );
+
+ it("propagates any other link failure without writing the destination", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+
+ expect(() => createFileAtomically(file, "html", failingLink("EIO"))).toThrow("EIO");
+ expect(fs.readdirSync(dir)).toEqual([]);
+ });
+
+ it("reports success when only the temporary file's cleanup fails", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const operations = {
+ writeFileSync: fs.writeFileSync,
+ chmodSync: fs.chmodSync,
+ linkSync: fs.linkSync,
+ unlinkSync: () => {
+ throw Object.assign(new Error("EBUSY"), { code: "EBUSY" });
+ },
+ };
+
+ createFileAtomically(file, "html", operations);
+
+ expect(readFileSync(file, "utf-8")).toBe("html");
+ expect(warn).toHaveBeenCalledOnce();
+ warn.mockRestore();
+ });
+
+ function nextTempNames(...hex: string[]) {
+ for (const name of hex)
+ vi.mocked(crypto.randomBytes).mockImplementationOnce(() => Buffer.from(name, "hex") as never);
+ }
+
+ it("takes a fresh temporary name when another writer holds one, leaving theirs alone", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+ writeFileSync(`${file}.deadbeef.tmp`, "theirs");
+ nextTempNames("deadbeef");
+
+ createFileAtomically(file, "html");
+
+ expect(readFileSync(file, "utf-8")).toBe("html");
+ expect(readFileSync(`${file}.deadbeef.tmp`, "utf-8")).toBe("theirs");
+ });
+
+ it("gives up after three taken temporary names without touching them", () => {
+ const dir = tempDir();
+ const file = join(dir, "index.html");
+ for (const name of ["00000001", "00000002", "00000003"])
+ writeFileSync(`${file}.${name}.tmp`, "theirs");
+ nextTempNames("00000001", "00000002", "00000003");
+
+ expect(() => createFileAtomically(file, "html")).toThrow(
+ expect.objectContaining({ code: "EEXIST" }),
+ );
+ expect(fs.readdirSync(dir)).toHaveLength(3);
+ expect(fs.existsSync(file)).toBe(false);
+ });
+
+ it("creates and replaces a name close to the filesystem's 255-byte limit", () => {
+ const dir = tempDir();
+ const file = join(dir, `${"n".repeat(237)}.html`);
+
+ createFileAtomically(file, "first");
+ replaceFileAtomically(file, "second");
+
+ expect(readFileSync(file, "utf-8")).toBe("second");
+ });
+});
+
+describe("replaceFileAtomically on a busy target", () => {
+ const dirs: string[] = [];
+ afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ });
+
+ function renamingAfter(failures: number, code: string) {
+ const dir = mkdtempSync(join(tmpdir(), "atomic-busy-test-"));
+ dirs.push(dir);
+ const file = join(dir, "index.html");
+ writeFileSync(file, "old");
+ let attempts = 0;
+ const operations = {
+ writeFileSync: fs.writeFileSync,
+ chmodSync: fs.chmodSync,
+ unlinkSync: fs.unlinkSync,
+ renameSync: (from: fs.PathLike, to: fs.PathLike) => {
+ if (++attempts <= failures) throw Object.assign(new Error(code), { code });
+ fs.renameSync(from, to);
+ },
+ };
+ return { dir, file, operations, attempts: () => attempts };
+ }
+
+ it.each(["EPERM", "EBUSY", "EACCES"])("retries a rename refused with %s", (code) => {
+ const { file, operations, attempts } = renamingAfter(2, code);
+
+ replaceFileAtomically(file, "new", 0o644, operations);
+
+ expect(readFileSync(file, "utf-8")).toBe("new");
+ expect(attempts()).toBe(3);
+ });
+
+ it("gives up after five attempts and keeps the old file", () => {
+ const { dir, file, operations, attempts } = renamingAfter(Infinity, "EBUSY");
+
+ expect(() => replaceFileAtomically(file, "new", 0o644, operations)).toThrow("EBUSY");
+ expect(attempts()).toBe(5);
+ expect(readFileSync(file, "utf-8")).toBe("old");
+ expect(fs.readdirSync(dir)).toEqual(["index.html"]);
+ });
+
+ it("does not retry other rename errors", () => {
+ const { file, operations, attempts } = renamingAfter(Infinity, "ENOSPC");
+
+ expect(() => replaceFileAtomically(file, "new", 0o644, operations)).toThrow("ENOSPC");
+ expect(attempts()).toBe(1);
+ });
+});
+
+// Windows needs a privilege to create symlinks.
+describe.skipIf(process.platform === "win32")("resolveWritePath", () => {
+ const dirs: string[] = [];
+ afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ });
+
+ /** root/sub links to real/deep/sub, as when a project is opened through a linked folder. */
+ function linkedFolder() {
+ const base = fs.realpathSync(mkdtempSync(join(tmpdir(), "atomic-resolve-test-")));
+ dirs.push(base);
+ fs.mkdirSync(join(base, "real/deep/sub"), { recursive: true });
+ fs.mkdirSync(join(base, "root"));
+ symlinkSync(join(base, "real/deep/sub"), join(base, "root/sub"));
+ return base;
+ }
+
+ it("resolves a relative link against the folder a linked folder points at", () => {
+ const base = linkedFolder();
+ writeFileSync(join(base, "real/deep/target.html"), "old");
+ symlinkSync("../target.html", join(base, "real/deep/sub/comp.html"));
+
+ expect(resolveWritePath(join(base, "root/sub/comp.html"))).toBe(
+ join(base, "real/deep/target.html"),
+ );
+ });
+
+ it("resolves a dangling link to the file a write through it creates", () => {
+ const base = linkedFolder();
+ symlinkSync("../missing.html", join(base, "real/deep/sub/comp.html"));
+
+ expect(resolveWritePath(join(base, "root/sub/comp.html"))).toBe(
+ join(base, "real/deep/missing.html"),
+ );
+ });
+
+ it("returns a plain file's real path and a new file's path unchanged", () => {
+ const base = linkedFolder();
+ writeFileSync(join(base, "real/deep/sub/plain.html"), "x");
+
+ expect(resolveWritePath(join(base, "root/sub/plain.html"))).toBe(
+ join(base, "real/deep/sub/plain.html"),
+ );
+ expect(resolveWritePath(join(base, "root/sub/new.html"))).toBe(
+ join(base, "real/deep/sub/new.html"),
+ );
+ });
+
+ it("reads a link through a linked folder and .. the way the system does", () => {
+ const base = linkedFolder();
+ fs.mkdirSync(join(base, "real/a/b"), { recursive: true });
+ symlinkSync(join(base, "real/a/b"), join(base, "root/x"));
+ writeFileSync(join(base, "real/a/t.html"), "old");
+ symlinkSync("x/../t.html", join(base, "root/comp.html"));
+
+ expect(resolveWritePath(join(base, "root/comp.html"))).toBe(join(base, "real/a/t.html"));
+ });
+
+ it("follows a dangling link through a linked folder and .. the way the system does", () => {
+ const base = linkedFolder();
+ fs.mkdirSync(join(base, "real/a/b"), { recursive: true });
+ symlinkSync(join(base, "real/a/b"), join(base, "root/x"));
+ symlinkSync("x/../t.html", join(base, "root/comp.html"));
+
+ expect(resolveWritePath(join(base, "root/comp.html"))).toBe(join(base, "real/a/t.html"));
+ });
+
+ it("stops a link loop with ELOOP", () => {
+ const base = linkedFolder();
+ symlinkSync("b.html", join(base, "root/a.html"));
+ symlinkSync("a.html", join(base, "root/b.html"));
+
+ expect(() => resolveWritePath(join(base, "root/a.html"))).toThrow(
+ expect.objectContaining({ code: "ELOOP" }),
+ );
+ });
+});
diff --git a/packages/core/src/atomicFile.ts b/packages/core/src/atomicFile.ts
new file mode 100644
index 0000000000..d33210e51b
--- /dev/null
+++ b/packages/core/src/atomicFile.ts
@@ -0,0 +1,142 @@
+import * as fs from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { realpath } from "./safePath.js";
+
+type SiblingFileSystem = Pick<typeof fs, "writeFileSync" | "chmodSync" | "unlinkSync">;
+
+// Codes a volume without hard links (FAT, exFAT, some network shares) answers link() with.
+// EISDIR: libuv maps Windows ERROR_INVALID_FUNCTION (FAT/exFAT refusing a link) to it; nodejs/node#65817.
+const NO_HARD_LINKS = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV", "EISDIR"]);
+// Windows refuses a rename while another process briefly holds the target open.
+const BUSY_RENAME = new Set(["EPERM", "EBUSY", "EACCES"]);
+const RENAME_RETRY_DELAYS_MS = [10, 20, 30, 40];
+const MAX_LINK_HOPS = 40;
+const TEMP_NAME_TRIES = 3;
+
+/** Replace a file only after the complete sibling temp file is written. No mode: the default one. */
+export function replaceFileAtomically(
+ filePath: string,
+ content: string | Uint8Array,
+ mode?: number,
+ operations: SiblingFileSystem & Pick<typeof fs, "renameSync"> = fs,
+): void {
+ // Node fs.rename uses libuv uv_fs_rename; win32 calls MoveFileExW with MOVEFILE_REPLACE_EXISTING.
+ publishSibling(filePath, content, mode, operations, (tempPath) =>
+ renameWithRetry(operations, tempPath, filePath),
+ );
+}
+
+/** Create a file that must not exist yet (EEXIST otherwise); readers never see it empty or partial. */
+export function createFileAtomically(
+ filePath: string,
+ content: string | Uint8Array,
+ operations: SiblingFileSystem & Pick<typeof fs, "linkSync"> = fs,
+): void {
+ publishSibling(filePath, content, undefined, operations, (tempPath) => {
+ try {
+ operations.linkSync(tempPath, filePath);
+ } catch (error) {
+ if (!NO_HARD_LINKS.has(errorCode(error))) throw error;
+ // Without hard links, keep today's direct exclusive write.
+ operations.writeFileSync(filePath, content, { flag: "wx" });
+ }
+ try {
+ operations.unlinkSync(tempPath);
+ } catch (error) {
+ console.warn(`[hyperframes] created ${filePath} but could not remove ${tempPath}: ${error}`);
+ }
+ });
+}
+
+/** The file a write to `filePath` lands on: folder links and file links followed as the system does. */
+export function resolveWritePath(filePath: string): string {
+ let path = resolve(filePath);
+ for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+ try {
+ return realpath(path);
+ } catch (error) {
+ if (errorCode(error) !== "ENOENT") throw error;
+ }
+ // Missing: a new file, or a dangling link to the file a write through it creates.
+ const parent = realpath(dirname(path));
+ const leaf = join(parent, basename(path));
+ if (!fs.lstatSync(leaf, { throwIfNoEntry: false })?.isSymbolicLink()) return leaf;
+ // Not normalized: `x/..` must climb out of where link `x` points, as the system reads it.
+ const target = fs.readlinkSync(leaf);
+ path = isAbsolute(target) ? target : `${parent}${sep}${target}`;
+ }
+ throw Object.assign(new Error(`ELOOP: too many symbolic links, '${filePath}'`), {
+ code: "ELOOP",
+ });
+}
+
+function publishSibling(
+ filePath: string,
+ content: string | Uint8Array,
+ mode: number | undefined,
+ operations: SiblingFileSystem,
+ publish: (tempPath: string) => void,
+): void {
+ const tempPath = writeTempSibling(filePath, content, mode, operations);
+ try {
+ if (mode !== undefined) operations.chmodSync(tempPath, mode);
+ publish(tempPath);
+ } catch (error) {
+ try {
+ operations.unlinkSync(tempPath);
+ } catch {
+ // Preserve the write error; cleanup is best effort.
+ }
+ throw error;
+ }
+}
+
+/** A new temp file beside `filePath`; a name another writer already holds is never touched. */
+function writeTempSibling(
+ filePath: string,
+ content: string | Uint8Array,
+ mode: number | undefined,
+ operations: SiblingFileSystem,
+): string {
+ for (let attempt = 1; ; attempt++) {
+ // Short, so a name near the filesystem's limit still fits.
+ const tempPath = `${filePath}.${randomBytes(4).toString("hex")}.tmp`;
+ try {
+ operations.writeFileSync(tempPath, content, { encoding: "utf-8", mode, flag: "wx" });
+ return tempPath;
+ } catch (error) {
+ if (errorCode(error) === "EEXIST") {
+ if (attempt < TEMP_NAME_TRIES) continue;
+ throw error;
+ }
+ try {
+ operations.unlinkSync(tempPath);
+ } catch {
+ // Preserve the write error; cleanup is best effort.
+ }
+ throw error;
+ }
+ }
+}
+
+function renameWithRetry(
+ operations: Pick<typeof fs, "renameSync">,
+ from: string,
+ to: string,
+): void {
+ for (let attempt = 0; ; attempt++) {
+ try {
+ operations.renameSync(from, to);
+ return;
+ } catch (error) {
+ const delay = RENAME_RETRY_DELAYS_MS[attempt];
+ if (delay === undefined || !BUSY_RENAME.has(errorCode(error))) throw error;
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+ }
+ }
+}
+
+function errorCode(error: unknown): string {
+ return String((error as NodeJS.ErrnoException)?.code);
+}
diff --git a/packages/sdk/src/adapters/fs.test.ts b/packages/sdk/src/adapters/fs.test.ts
new file mode 100644
index 0000000000..75987ddc96
--- /dev/null
+++ b/packages/sdk/src/adapters/fs.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ chmodSync,
+ existsSync,
+ linkSync,
+ lstatSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createFsAdapter } from "./fs.js";
+
+describe("fs adapter writes", () => {
+ const dirs: string[] = [];
+ afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ });
+ function root(): string {
+ const dir = mkdtempSync(join(tmpdir(), "hf-fs-adapter-"));
+ dirs.push(dir);
+ return dir;
+ }
+
+ it("replaces the file whole, so a reader holding the old one never sees a partial write", async () => {
+ const dir = root();
+ writeFileSync(join(dir, "comp.html"), "old");
+ linkSync(join(dir, "comp.html"), join(dir, "reader.html"));
+
+ await createFsAdapter({ root: dir }).write("comp.html", "new");
+
+ expect(readFileSync(join(dir, "reader.html"), "utf-8")).toBe("old");
+ expect(readFileSync(join(dir, "comp.html"), "utf-8")).toBe("new");
+ expect(readdirSync(dir).filter((name) => name.endsWith(".tmp"))).toEqual([]);
+ });
+
+ // Windows keeps only a read-only bit, no group or other permissions.
+ it.skipIf(process.platform === "win32")("keeps the file's mode", async () => {
+ const dir = root();
+ writeFileSync(join(dir, "comp.html"), "old");
+ chmodSync(join(dir, "comp.html"), 0o640);
+
+ await createFsAdapter({ root: dir }).write("comp.html", "new");
+
+ expect(statSync(join(dir, "comp.html")).mode & 0o777).toBe(0o640);
+ });
+
+ // Windows needs a privilege to create symlinks.
+ it.skipIf(process.platform === "win32")("writes through a link to its target", async () => {
+ const dir = root();
+ writeFileSync(join(dir, "target.html"), "old");
+ symlinkSync(join(dir, "target.html"), join(dir, "comp.html"));
+
+ await createFsAdapter({ root: dir }).write("comp.html", "new");
+
+ expect(lstatSync(join(dir, "comp.html")).isSymbolicLink()).toBe(true);
+ expect(readFileSync(join(dir, "target.html"), "utf-8")).toBe("new");
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "creates the target of a link that points at no file yet",
+ async () => {
+ const dir = root();
+ symlinkSync(join(dir, "target.html"), join(dir, "comp.html"));
+
+ await createFsAdapter({ root: dir }).write("comp.html", "new");
+
+ expect(lstatSync(join(dir, "comp.html")).isSymbolicLink()).toBe(true);
+ expect(readFileSync(join(dir, "target.html"), "utf-8")).toBe("new");
+ },
+ );
+
+ it.skipIf(process.platform === "win32")("follows a chain of relative links", async () => {
+ const dir = root();
+ writeFileSync(join(dir, "target.html"), "old");
+ symlinkSync("target.html", join(dir, "middle.html"));
+ symlinkSync("middle.html", join(dir, "comp.html"));
+
+ await createFsAdapter({ root: dir }).write("comp.html", "new");
+
+ expect(lstatSync(join(dir, "comp.html")).isSymbolicLink()).toBe(true);
+ expect(lstatSync(join(dir, "middle.html")).isSymbolicLink()).toBe(true);
+ expect(readFileSync(join(dir, "target.html"), "utf-8")).toBe("new");
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "follows a relative link inside a linked project folder to the real target",
+ async () => {
+ const base = root();
+ mkdirSync(join(base, "real/deep/sub"), { recursive: true });
+ mkdirSync(join(base, "root"));
+ symlinkSync(join(base, "real/deep/sub"), join(base, "root/sub"));
+ writeFileSync(join(base, "real/deep/target.html"), "old");
+ symlinkSync("../target.html", join(base, "real/deep/sub/comp.html"));
+
+ await createFsAdapter({ root: join(base, "root") }).write("sub/comp.html", "new");
+
+ expect(readFileSync(join(base, "real/deep/target.html"), "utf-8")).toBe("new");
+ expect(existsSync(join(base, "root/target.html"))).toBe(false);
+ },
+ );
+
+ it("creates a new file in a new folder", async () => {
+ const dir = root();
+
+ await createFsAdapter({ root: dir }).write("scenes/intro.html", "intro");
+
+ expect(readFileSync(join(dir, "scenes/intro.html"), "utf-8")).toBe("intro");
+ });
+});
diff --git a/packages/sdk/src/adapters/fs.ts b/packages/sdk/src/adapters/fs.ts
index 615015a7f7..7614810999 100644
--- a/packages/sdk/src/adapters/fs.ts
+++ b/packages/sdk/src/adapters/fs.ts
@@ -1,6 +1,7 @@
import type { PersistAdapter, PersistVersionEntry } from "./types.js";
import type { PersistErrorEvent } from "../types.js";
-import { readFile, writeFile, mkdir, readdir, unlink } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, unlink, stat } from "node:fs/promises";
+import { replaceFileAtomically, resolveWritePath } from "@hyperframes/core/atomic-file";
import { join, dirname } from "node:path";
export interface FsAdapterOptions {
@@ -49,7 +50,15 @@ class FsAdapter implements PersistAdapter {
try {
const abs = this.abs(path);
await mkdir(dirname(abs), { recursive: true });
- await writeFile(abs, content, "utf8");
+ const target = resolveWritePath(abs);
+ const mode = await stat(target).then(
+ (s) => s.mode,
+ (err: unknown) => {
+ if (isNotFound(err)) return undefined;
+ throw err;
+ },
+ );
+ replaceFileAtomically(target, content, mode);
await this.appendVersion(path, content);
} catch (err) {
for (const h of this.errorHandlers) h({ error: { message: String(err), cause: err } });
diff --git a/packages/studio-server/src/helpers/applyFileMutations.ts b/packages/studio-server/src/helpers/applyFileMutations.ts
index 17c5ff80d0..26f77447ea 100644
--- a/packages/studio-server/src/helpers/applyFileMutations.ts
+++ b/packages/studio-server/src/helpers/applyFileMutations.ts
@@ -1,5 +1,5 @@
import { readFileSync, statSync } from "node:fs";
-import { replaceFileAtomically } from "./atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { backupPathForResponse, snapshotBeforeWrite } from "./backupJournal.js";
import {
clearFileWriteReceipt,
diff --git a/packages/studio-server/src/helpers/atomicFile.test.ts b/packages/studio-server/src/helpers/atomicFile.test.ts
deleted file mode 100644
index fe8aae462d..0000000000
--- a/packages/studio-server/src/helpers/atomicFile.test.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import * as fs from "node:fs";
-import { lstatSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { replaceFileAtomically } from "./atomicFile.js";
-
-describe("replaceFileAtomically", () => {
- const dirs: string[] = [];
-
- afterEach(() => {
- for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
- dirs.length = 0;
- });
-
- // Windows needs a privilege to create symlinks.
- it.skipIf(process.platform === "win32")(
- "replaces a link at the path, never writing its target",
- () => {
- const dir = mkdtempSync(join(tmpdir(), "atomic-file-test-"));
- dirs.push(dir);
- const target = join(dir, "target.html");
- const link = join(dir, "link.html");
- writeFileSync(target, "old");
- symlinkSync(target, link);
-
- replaceFileAtomically(link, "new", 0o644);
-
- expect(readFileSync(target, "utf-8")).toBe("old");
- expect(lstatSync(link).isSymbolicLink()).toBe(false);
- },
- );
-
- it("writes the sibling completely before replacing the project file", () => {
- const dir = mkdtempSync(join(tmpdir(), "atomic-file-test-"));
- dirs.push(dir);
- const file = join(dir, "index.html");
- writeFileSync(file, "old", { mode: 0o640 });
- const events: string[] = [];
- const operations = {
- writeFileSync: (path: fs.PathLike, ...args: any[]) => {
- events.push(`write:${String(path)}`);
- return fs.writeFileSync(path, ...args);
- },
- chmodSync: fs.chmodSync,
- renameSync: (from: fs.PathLike, to: fs.PathLike) => {
- events.push(`rename:${String(from)}:${String(to)}`);
- expect(readFileSync(from, "utf-8")).toBe("new complete html");
- return fs.renameSync(from, to);
- },
- unlinkSync: fs.unlinkSync,
- };
-
- replaceFileAtomically(file, "new complete html", 0o640, operations);
-
- expect(events).toHaveLength(2);
- expect(events[0]).toMatch(new RegExp(`^write:${file}\\.\\d+\\.[0-9a-f-]+\\.tmp$`));
- const tempPath = events[0]!.slice("write:".length);
- expect(events[1]).toBe(`rename:${tempPath}:${file}`);
- expect(readFileSync(file, "utf-8")).toBe("new complete html");
- expect(fs.statSync(file).mode & 0o777).toBe(0o640);
- });
-
- it("replaces an existing destination", () => {
- const dir = mkdtempSync(join(tmpdir(), "atomic-file-replace-test-"));
- dirs.push(dir);
- const file = join(dir, "index.html");
- writeFileSync(file, "old destination");
-
- replaceFileAtomically(file, "new destination", 0o640);
-
- expect(readFileSync(file, "utf-8")).toBe("new destination");
- });
-
- it("allocates a distinct temporary sibling for each writer", () => {
- const dir = mkdtempSync(join(tmpdir(), "atomic-file-unique-test-"));
- dirs.push(dir);
- const file = join(dir, "index.html");
- writeFileSync(file, "old");
- const tempPaths: string[] = [];
- const operations = {
- writeFileSync: (path: fs.PathLike, ...args: any[]) => {
- tempPaths.push(String(path));
- return fs.writeFileSync(path, ...args);
- },
- chmodSync: fs.chmodSync,
- renameSync: fs.renameSync,
- unlinkSync: fs.unlinkSync,
- };
-
- replaceFileAtomically(file, "first", 0o640, operations);
- replaceFileAtomically(file, "second", 0o640, operations);
-
- expect(tempPaths).toHaveLength(2);
- expect(tempPaths[0]).not.toBe(tempPaths[1]);
- });
-
- it("uses a unique temporary sibling and removes it when publication fails", () => {
- const dir = mkdtempSync(join(tmpdir(), "atomic-file-failure-test-"));
- dirs.push(dir);
- const file = join(dir, "index.html");
- writeFileSync(file, "old");
- const tempPaths: string[] = [];
- const removed: string[] = [];
- const operations = {
- writeFileSync: (path: fs.PathLike, ...args: any[]) => {
- tempPaths.push(String(path));
- return fs.writeFileSync(path, ...args);
- },
- chmodSync: fs.chmodSync,
- renameSync: () => {
- throw new Error("publish failed");
- },
- unlinkSync: (path: fs.PathLike) => {
- removed.push(String(path));
- return fs.unlinkSync(path);
- },
- };
-
- expect(() => replaceFileAtomically(file, "new", 0o640, operations)).toThrow("publish failed");
- expect(tempPaths).toHaveLength(1);
- expect(tempPaths[0]).toMatch(new RegExp(`^${file}\\.\\d+\\.[0-9a-f-]+\\.tmp$`));
- expect(removed).toEqual(tempPaths);
- });
-});
diff --git a/packages/studio-server/src/helpers/atomicFile.ts b/packages/studio-server/src/helpers/atomicFile.ts
deleted file mode 100644
index 8526c05b55..0000000000
--- a/packages/studio-server/src/helpers/atomicFile.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import * as fs from "node:fs";
-import { randomUUID } from "node:crypto";
-
-type AtomicFileSystem = Pick<
- typeof fs,
- "writeFileSync" | "chmodSync" | "renameSync" | "unlinkSync"
->;
-
-/** Replace a file only after the complete sibling temp file is written. */
-export function replaceFileAtomically(
- filePath: string,
- content: string | Uint8Array,
- mode: number,
- operations: AtomicFileSystem = fs,
-): void {
- const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
- try {
- operations.writeFileSync(tempPath, content, { encoding: "utf-8", mode });
- operations.chmodSync(tempPath, mode);
- // Node fs.rename uses libuv uv_fs_rename; win32 calls MoveFileExW with MOVEFILE_REPLACE_EXISTING.
- operations.renameSync(tempPath, filePath);
- } catch (error) {
- try {
- operations.unlinkSync(tempPath);
- } catch {
- // Preserve the write error; cleanup is best effort.
- }
- throw error;
- }
-}
diff --git a/packages/studio-server/src/helpers/hfIdPersist.noFollow.test.ts b/packages/studio-server/src/helpers/hfIdPersist.noFollow.test.ts
index 15a6062a46..196bc4a7e1 100644
--- a/packages/studio-server/src/helpers/hfIdPersist.noFollow.test.ts
+++ b/packages/studio-server/src/helpers/hfIdPersist.noFollow.test.ts
@@ -4,8 +4,8 @@ import { join } from "node:path";
import { afterEach, expect, it, vi } from "vitest";
const swap = vi.hoisted(() => ({ to: "" }));
-vi.mock("./atomicFile.js", async (importOriginal) => {
- const actual = await importOriginal<typeof import("./atomicFile.js")>();
+vi.mock("@hyperframes/core/atomic-file", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("@hyperframes/core/atomic-file")>();
const fs = await import("node:fs");
return {
...actual,
diff --git a/packages/studio-server/src/helpers/hfIdPersist.ts b/packages/studio-server/src/helpers/hfIdPersist.ts
index bc11e81353..4535a72fc9 100644
--- a/packages/studio-server/src/helpers/hfIdPersist.ts
+++ b/packages/studio-server/src/helpers/hfIdPersist.ts
@@ -2,7 +2,7 @@ import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { createHash } from "node:crypto";
import { closeSync, constants, fstatSync, openSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
-import { replaceFileAtomically } from "./atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { isInHiddenOrVendorDir, mkdirWithinProject, walkDir } from "./safePath.js";
export const isCompositionSource = (html: string): boolean => /data-composition-id\s*=/.test(html);
diff --git a/packages/studio-server/src/helpers/previewDocumentStore.ts b/packages/studio-server/src/helpers/previewDocumentStore.ts
index 3c86fdbd47..036821f9a1 100644
--- a/packages/studio-server/src/helpers/previewDocumentStore.ts
+++ b/packages/studio-server/src/helpers/previewDocumentStore.ts
@@ -1,7 +1,7 @@
import { createHash } from "node:crypto";
import { readFileSync, readdirSync, rmSync } from "node:fs";
import { join } from "node:path";
-import { replaceFileAtomically } from "./atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { mkdirWithinProject } from "./safePath.js";
import type { PreviewDocumentStore } from "./mediaProxyPreview.js";
diff --git a/packages/studio-server/src/history/historyId.ts b/packages/studio-server/src/history/historyId.ts
index 228d8abbc2..6aa24b56b2 100644
--- a/packages/studio-server/src/history/historyId.ts
+++ b/packages/studio-server/src/history/historyId.ts
@@ -1,7 +1,7 @@
import { randomUUID } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { replaceFileAtomically } from "../helpers/atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { mkdirWithinProject } from "../helpers/safePath.js";
export const ID_PATH = join(".hyperframes", "history-id");
diff --git a/packages/studio-server/src/history/historyLog.ts b/packages/studio-server/src/history/historyLog.ts
index 7b4599250f..bdce41b647 100644
--- a/packages/studio-server/src/history/historyLog.ts
+++ b/packages/studio-server/src/history/historyLog.ts
@@ -1,6 +1,6 @@
import { closeSync, constants, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
import { dirname } from "node:path";
-import { replaceFileAtomically } from "../helpers/atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
export interface HistoryWho {
kind: "person" | "agent" | "outside";
diff --git a/packages/studio-server/src/history/projectHistory.ts b/packages/studio-server/src/history/projectHistory.ts
index 1c160d3d64..d8cbafab47 100644
--- a/packages/studio-server/src/history/projectHistory.ts
+++ b/packages/studio-server/src/history/projectHistory.ts
@@ -14,7 +14,7 @@ import {
} from "node:fs";
import { homedir } from "node:os";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { replaceFileAtomically } from "../helpers/atomicFile.js";
+import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
import {
DELETED_VERSION,
fileContentVersion,
diff --git a/packages/studio-server/src/routes/files.atomicCreate.test.ts b/packages/studio-server/src/routes/files.atomicCreate.test.ts
new file mode 100644
index 0000000000..daebb25339
--- /dev/null
+++ b/packages/studio-server/src/routes/files.atomicCreate.test.ts
@@ -0,0 +1,95 @@
+// @vitest-environment node
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Hono } from "hono";
+import { registerFileRoutes } from "./files";
+import type { StudioApiAdapter } from "../types";
+
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ return {
+ ...actual,
+ openSync: vi.fn(actual.openSync),
+ writeFileSync: vi.fn(actual.writeFileSync),
+ };
+});
+
+let project: string;
+beforeEach(() => {
+ project = fs.mkdtempSync(join(tmpdir(), "hf-atomic-create-"));
+ fs.writeFileSync(join(project, "index.html"), "<html>index</html>");
+ vi.clearAllMocks();
+});
+afterEach(() => fs.rmSync(project, { recursive: true, force: true }));
+
+function app(): Hono {
+ const api = new Hono();
+ registerFileRoutes(api, {
+ resolveProject: async (id: string) => ({ id, dir: project }),
+ } as unknown as StudioApiAdapter);
+ return api;
+}
+
+// A write opened on the destination itself exposes an empty file until it finishes.
+function writesOpenedOn(name: string): unknown[][] {
+ const dests = [join(project, name), join(fs.realpathSync(project), name)];
+ const onDest = ([path]: unknown[]) => dests.includes(String(path));
+ return [
+ ...vi.mocked(fs.writeFileSync).mock.calls.filter(onDest),
+ ...vi.mocked(fs.openSync).mock.calls.filter((call) => onDest(call) && call[1] !== "r"),
+ ];
+}
+
+it.each([
+ [
+ "create",
+ "new.html",
+ () =>
+ app().request("http://localhost/projects/demo/files/new.html", {
+ method: "POST",
+ body: "<html>new</html>",
+ }),
+ "<html>new</html>",
+ ],
+ [
+ "create-only save",
+ "saved.html",
+ () =>
+ app().request("http://localhost/projects/demo/files/saved.html", {
+ method: "PUT",
+ headers: { "If-None-Match": "*" },
+ body: "<html>saved</html>",
+ }),
+ "<html>saved</html>",
+ ],
+ [
+ "duplicate",
+ "index (copy).html",
+ () =>
+ app().request("http://localhost/projects/demo/duplicate-file", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ path: "index.html" }),
+ }),
+ "<html>index</html>",
+ ],
+ [
+ "upload",
+ "clip.txt",
+ () => {
+ const form = new FormData();
+ form.append("files", new File(["upload bytes"], "clip.txt"));
+ return app().request("http://localhost/projects/demo/upload", { method: "POST", body: form });
+ },
+ "upload bytes",
+ ],
+])("%s publishes the file only once it is complete", async (_route, name, send, content) => {
+ const response = await send();
+
+ expect(response.status).toBeLessThan(300);
+ expect(fs.readFileSync(join(project, name), "utf-8")).toBe(content);
+ expect(writesOpenedOn(name)).toEqual([]);
+ expect(fs.readdirSync(project).filter((entry) => entry.endsWith(".tmp"))).toEqual([]);
+});
diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts
index 06c5947ada..90f63ed379 100644
--- a/packages/studio-server/src/routes/files.ts
+++ b/packages/studio-server/src/routes/files.ts
@@ -11,8 +11,6 @@ import {
openSync,
readFileSync,
readlinkSync,
- writeFileSync,
- writeSync,
unlinkSync,
rmSync,
statSync,
@@ -23,7 +21,7 @@ import {
import { resolve, dirname, join } from "node:path";
import type { StudioApiAdapter } from "../types.js";
import { isAudioFile } from "../helpers/mime.js";
-import { replaceFileAtomically } from "../helpers/atomicFile.js";
+import { createFileAtomically, replaceFileAtomically } from "@hyperframes/core/atomic-file";
import { generateWaveformCache } from "../helpers/waveform.js";
import { validateUploadedMediaBuffer } from "../helpers/mediaValidation.js";
import {
@@ -2308,12 +2306,7 @@ async function processUploadedFiles(
let written = false;
while (n < MAX_COPY_INDEX && isSafePath(projectDir, finalPath)) {
try {
- const fd = openSync(finalPath, "wx");
- try {
- writeFileSync(fd, buffer);
- } finally {
- closeSync(fd);
- }
+ createFileAtomically(finalPath, buffer);
written = true;
break;
} catch (error) {
@@ -2441,9 +2434,8 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
let overwrote: Buffer | undefined;
if (createOnly) {
ensureDir(res.project.dir, res.absPath);
- let fd: number;
try {
- fd = openSync(res.absPath, "wx");
+ createFileAtomically(res.absPath, body);
} catch (error) {
if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
throw error;
@@ -2459,11 +2451,6 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
409,
);
}
- try {
- writeSync(fd, body, 0, body.length, 0);
- } finally {
- closeSync(fd);
- }
} else {
let fd: number | null;
try {
@@ -2530,7 +2517,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
ensureDir(res.project.dir, res.absPath);
const body = Buffer.from(await c.req.arrayBuffer());
try {
- writeFileSync(res.absPath, body, { flag: "wx" });
+ createFileAtomically(res.absPath, body);
} catch (error) {
if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
throw error;
@@ -3239,7 +3226,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
ensureDir(project.dir, destAbs);
try {
- writeFileSync(destAbs, readFileSync(srcAbs), { flag: "wx" });
+ createFileAtomically(destAbs, readFileSync(srcAbs));
} catch (error) {
if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
throw error;
diff --git a/scripts/check-no-main-deletions.mjs b/scripts/check-no-main-deletions.mjs
index 815441ce6f..f9b3c3a2e7 100644
--- a/scripts/check-no-main-deletions.mjs
+++ b/scripts/check-no-main-deletions.mjs
@@ -1099,6 +1099,14 @@ export const ALLOWED_DELETIONS = new Map([
],
["docs/images/preview-reload-evidence/after.webm", "evidence video no page referenced"],
["docs/images/preview-reload-evidence/before.webm", "evidence video no page referenced"],
+ [
+ "packages/studio-server/src/helpers/atomicFile.ts",
+ "moved to @hyperframes/core/atomic-file (packages/core/src/atomicFile.ts) as the single atomic writer for core, sdk, cli and studio-server",
+ ],
+ [
+ "packages/studio-server/src/helpers/atomicFile.test.ts",
+ "its tests moved with it to packages/core/src/atomicFile.test.ts",
+ ],
]);
export function parseBase(argv, fallback = "origin/main") {