fix(project): make project saves atomic

2026-09-24 14:55:37 +00:00 · 2026-07-10 19:00:09 +07:00
parent e69074e5fa
commit 3d9212f349
3 changed files with 259 additions and 3 deletions
@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { getProjectBackupPath, writeProjectFileAtomically } from "./atomicSave";
+
+describe("writeProjectFileAtomically", () => {
+	let tempDir: string;
+	let projectPath: string;
+
+	beforeEach(async () => {
+		tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-atomic-project-"));
+		projectPath = path.join(tempDir, "demo.recordly");
+	});
+
+	afterEach(async () => {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	});
+
+	async function expectNoTemporaryArtifacts() {
+		const entries = await fs.readdir(tempDir);
+		expect(entries.filter((entry) => entry.endsWith(".tmp"))).toEqual([]);
+	}
+
+	it("commits a complete new project without creating a backup", async () => {
+		await writeProjectFileAtomically(projectPath, '{"version":1}');
+
+		await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1}');
+		await expect(fs.access(getProjectBackupPath(projectPath))).rejects.toMatchObject({
+			code: "ENOENT",
+		});
+		await expectNoTemporaryArtifacts();
+	});
+
+	it("removes a stale backup when the target has no previous generation", async () => {
+		await fs.writeFile(getProjectBackupPath(projectPath), "stale-project");
+
+		await writeProjectFileAtomically(projectPath, '{"version":1}');
+
+		await expect(fs.access(getProjectBackupPath(projectPath))).rejects.toMatchObject({
+			code: "ENOENT",
+		});
+	});
+
+	it("preserves the previous complete generation before replacement", async () => {
+		await writeProjectFileAtomically(projectPath, '{"version":1,"name":"old"}');
+		await writeProjectFileAtomically(projectPath, '{"version":1,"name":"new"}');
+
+		await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1,"name":"new"}');
+		await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+			'{"version":1,"name":"old"}',
+		);
+		await expectNoTemporaryArtifacts();
+	});
+
+	it("keeps the active generation unchanged when backup commit fails", async () => {
+		await writeProjectFileAtomically(projectPath, '{"version":1,"name":"old"}');
+		await fs.mkdir(getProjectBackupPath(projectPath));
+
+		await expect(
+			writeProjectFileAtomically(projectPath, '{"version":1,"name":"new"}'),
+		).rejects.toBeDefined();
+
+		await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1,"name":"old"}');
+
+		await fs.rm(getProjectBackupPath(projectPath), { recursive: true });
+		await writeProjectFileAtomically(projectPath, '{"version":1,"name":"retry"}');
+		await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe(
+			'{"version":1,"name":"retry"}',
+		);
+		await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+			'{"version":1,"name":"old"}',
+		);
+		await expectNoTemporaryArtifacts();
+	});
+
+	it("serializes overlapping writes to the same project", async () => {
+		await writeProjectFileAtomically(projectPath, '{"revision":1}');
+
+		await Promise.all([
+			writeProjectFileAtomically(projectPath, '{"revision":2}'),
+			writeProjectFileAtomically(projectPath, '{"revision":3}'),
+		]);
+
+		await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"revision":3}');
+		await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+			'{"revision":2}',
+		);
+		await expectNoTemporaryArtifacts();
+	});
+
+	it.skipIf(process.platform === "win32")(
+		"preserves existing project permission bits on replacement",
+		async () => {
+			await fs.writeFile(projectPath, '{"revision":1}', { mode: 0o600 });
+
+			await writeProjectFileAtomically(projectPath, '{"revision":2}');
+
+			expect((await fs.stat(projectPath)).mode & 0o777).toBe(0o600);
+		},
+	);
+});
@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const pendingWrites = new Map<string, Promise<void>>();
+
+const unsupportedDirectorySyncErrors = new Set([
+	"EACCES",
+	"EINVAL",
+	"EISDIR",
+	"ENOSYS",
+	"ENOTSUP",
+	"EOPNOTSUPP",
+	"EPERM",
+]);
+
+export function getProjectBackupPath(projectPath: string): string {
+	return `${projectPath}.bak`;
+}
+
+function getQueueKey(projectPath: string): string {
+	const resolvedPath = path.resolve(projectPath);
+	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function createTemporaryPath(parentDir: string, label: string): string {
+	return path.join(parentDir, `.recordly-${label}-${process.pid}-${randomUUID()}.tmp`);
+}
+
+async function getExistingFileMode(filePath: string): Promise<number | undefined> {
+	try {
+		return (await fs.stat(filePath)).mode & 0o777;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return undefined;
+		}
+		throw error;
+	}
+}
+
+async function writeSyncedTemporaryFile(
+	filePath: string,
+	contents: string,
+	mode?: number,
+): Promise<void> {
+	const handle = await fs.open(filePath, "wx", mode);
+	try {
+		await handle.writeFile(contents, "utf-8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function syncExistingFile(filePath: string): Promise<void> {
+	const handle = await fs.open(filePath, "r+");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function syncParentDirectory(parentDir: string): Promise<void> {
+	if (process.platform === "win32") {
+		return;
+	}
+
+	try {
+		const handle = await fs.open(parentDir, "r");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (!code || !unsupportedDirectorySyncErrors.has(code)) {
+			throw error;
+		}
+	}
+}
+
+async function preservePreviousGeneration(
+	targetPath: string,
+	backupPath: string,
+	backupTemporaryPath: string,
+): Promise<void> {
+	try {
+		await fs.copyFile(targetPath, backupTemporaryPath, fsConstants.COPYFILE_EXCL);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			await fs.rm(backupPath, { force: true });
+			return;
+		}
+		throw error;
+	}
+
+	await syncExistingFile(backupTemporaryPath);
+	await fs.rename(backupTemporaryPath, backupPath);
+}
+
+async function commitProjectFile(projectPath: string, contents: string): Promise<void> {
+	const targetPath = path.resolve(projectPath);
+	const parentDir = path.dirname(targetPath);
+	const backupPath = getProjectBackupPath(targetPath);
+	const temporaryPath = createTemporaryPath(parentDir, "project");
+	const backupTemporaryPath = createTemporaryPath(parentDir, "backup");
+	const existingMode = await getExistingFileMode(targetPath);
+
+	try {
+		await writeSyncedTemporaryFile(temporaryPath, contents, existingMode);
+		await preservePreviousGeneration(targetPath, backupPath, backupTemporaryPath);
+		await fs.rename(temporaryPath, targetPath);
+		await syncParentDirectory(parentDir);
+	} finally {
+		await Promise.all([
+			fs.rm(temporaryPath, { force: true }).catch(() => undefined),
+			fs.rm(backupTemporaryPath, { force: true }).catch(() => undefined),
+		]);
+	}
+}
+
+export async function writeProjectFileAtomically(
+	projectPath: string,
+	contents: string,
+): Promise<void> {
+	const queueKey = getQueueKey(projectPath);
+	const previousWrite = pendingWrites.get(queueKey) ?? Promise.resolve();
+	const currentWrite = previousWrite
+		.catch(() => undefined)
+		.then(() => commitProjectFile(projectPath, contents));
+	pendingWrites.set(queueKey, currentWrite);
+
+	try {
+		await currentWrite;
+	} finally {
+		if (pendingWrites.get(queueKey) === currentWrite) {
+			pendingWrites.delete(queueKey);
+		}
+	}
+}
@@ -9,6 +9,7 @@ import {
 	LEGACY_PROJECT_FILE_EXTENSIONS,
 	PROJECT_FILE_EXTENSION,
 } from "../constants";
+import { writeProjectFileAtomically } from "../project/atomicSave";
 import {
 	getProjectsDir,
  getProjectThumbnailPath,
@@ -305,7 +306,10 @@ export function registerProjectHandlers() {
        : null

      if (trustedExistingProjectPath) {
-        await fs.writeFile(trustedExistingProjectPath, JSON.stringify(preparedProject.projectData, null, 2), 'utf-8')
+        await writeProjectFileAtomically(
+          trustedExistingProjectPath,
+          JSON.stringify(preparedProject.projectData, null, 2),
+        )
        setCurrentProjectPath(trustedExistingProjectPath)
        await saveProjectThumbnail(trustedExistingProjectPath, thumbnailDataUrl)
        await rememberRecentProject(trustedExistingProjectPath)
@@ -345,7 +349,10 @@ export function registerProjectHandlers() {
        }
      }

-      await fs.writeFile(result.filePath, JSON.stringify(preparedProject.projectData, null, 2), 'utf-8')
+      await writeProjectFileAtomically(
+        result.filePath,
+        JSON.stringify(preparedProject.projectData, null, 2),
+      )
      setCurrentProjectPath(result.filePath)
      await saveProjectThumbnail(result.filePath, thumbnailDataUrl)
      await rememberRecentProject(result.filePath)
@@ -411,7 +418,10 @@ export function registerProjectHandlers() {
          return overwriteCheck
        }

-        await fs.writeFile(targetProjectPath, JSON.stringify(preparedProject.projectData, null, 2), 'utf-8')
+        await writeProjectFileAtomically(
+          targetProjectPath,
+          JSON.stringify(preparedProject.projectData, null, 2),
+        )
        await saveProjectThumbnail(targetProjectPath, thumbnailDataUrl)
        await rememberRecentProject(targetProjectPath)