Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Make atomicWrite crash-durable: fsync the temp file and its directory
[._.]/ Adam Eivy7f180a406ea9
diff --git a/server/lib/aiToolkit/internal/atomicWrite.js b/server/lib/aiToolkit/internal/atomicWrite.jsindex bb1b24c2c9..a66ce8fcfc 100644--- a/server/lib/aiToolkit/internal/atomicWrite.js+++ b/server/lib/aiToolkit/internal/atomicWrite.js@@ -14,9 +14,11 @@** Writes data to a temp file, then renames atomically so readers never see* a partial write. Accepts a string, a Buffer, or any JSON-serializable value.+ * The temp file is fsynced before the rename and the directory after it+ * (#12025), so a crash cannot leave the rename durable without its bytes.*/-import { chmod, mkdir, stat, writeFile, rename, unlink } from 'fs/promises';+import { chmod, mkdir, open, stat, writeFile, rename, unlink } from 'fs/promises';import { randomUUID } from 'crypto';import { dirname } from 'path';@@ -44,6 +46,31 @@ export async function ensureDir(dir) {await mkdir(dir, { recursive: true });}+// Directories whose fsync already failed once this process, so a filesystem+// that rejects directory fsync (EINVAL on some network mounts) warns once+// instead of on every write.+const unsyncableDirs = new Set();++/**+ * fsync a directory so a just-completed rename inside it survives a crash.+ * Best-effort once the rename is visible: the bytes are already in place, so a+ * filesystem that cannot sync its directory degrades to the pre-#12025+ * guarantee with one warning rather than failing a write that succeeded.+ * Windows cannot open a directory for fsync, so it is skipped there.+ */+async function syncDirectory(dir) {+ if (isWindows()) return;+ try {+ const handle = await open(dir, 'r');+ try { await handle.sync(); } finally { await handle.close(); }+ } catch (err) {+ if (!err?.code) throw err;+ if (unsyncableDirs.has(dir)) return;+ unsyncableDirs.add(dir);+ console.warn(`⚠️ Directory fsync unavailable for ${dir} (${err.code}); renames there are not crash-durable`);+ }+}+export async function atomicWrite(filePath, data) {// Buffer must pass through unchanged — JSON.stringify on a Buffer produces// `{"type":"Buffer","data":[...]}` which corrupts binary writes (PNG, etc.).@@ -59,7 +86,8 @@ export async function atomicWrite(filePath, data) {try {// A failed write may already have produced partial bytes; cleanup owns the// entire preparation, including restoring mode bits tightened by umask.- await writeFile(tmp, payload, existingMode !== null ? { mode: existingMode } : undefined);+ // `flush` fsyncs the temp file's bytes before the handle closes.+ await writeFile(tmp, payload, { ...(existingMode !== null ? { mode: existingMode } : {}), flush: true });if (existingMode !== null) await chmod(tmp, existingMode);// Persistent Windows lock: fail without moving the destination aside.const err = await renameWithWindowsRetries(tmp, filePath);@@ -68,4 +96,5 @@ export async function atomicWrite(filePath, data) {await unlink(tmp).catch(() => {});throw err;}+ await syncDirectory(dirname(filePath));}diff --git a/server/lib/aiToolkit/internal/atomicWrite.test.js b/server/lib/aiToolkit/internal/atomicWrite.test.jsindex ca6db158b0..399d6c4bb5 100644--- a/server/lib/aiToolkit/internal/atomicWrite.test.js+++ b/server/lib/aiToolkit/internal/atomicWrite.test.js@@ -13,6 +13,7 @@ vi.mock('fs/promises', async (importOriginal) => {writeFile: vi.fn((...args) => actual.writeFile(...args)),stat: vi.fn((...args) => actual.stat(...args)),chmod: vi.fn((...args) => actual.chmod(...args)),+ open: vi.fn((...args) => actual.open(...args)),};});@@ -34,7 +35,7 @@ beforeEach(() => {afterEach(() => {restorePlatform();restorePlatform = () => {};- for (const name of ['rename', 'writeFile', 'stat', 'chmod']) {+ for (const name of ['rename', 'writeFile', 'stat', 'chmod', 'open']) {fsPromises[name].mockReset();fsPromises[name].mockImplementation((...args) => realFsPromises[name](...args));}@@ -67,6 +68,43 @@ describe('AI Toolkit atomicWrite Windows lock retries', () => {});});+describe('AI Toolkit atomicWrite crash durability (#12025, mirrors fileCore)', () => {+ it('fsyncs the temp file before the rename and the parent directory after it', async () => {+ const target = join(tmpRoot, 'durable.json');+ const calls = [];+ fsPromises.writeFile.mockImplementationOnce(async (path, data, options) => {+ calls.push(['writeFile', options?.flush]);+ return realFsPromises.writeFile(path, data, options);+ });+ fsPromises.rename.mockImplementationOnce(async (...args) => {+ calls.push(['rename']);+ return realFsPromises.rename(...args);+ });+ fsPromises.open.mockImplementationOnce(async (path, flags) => {+ const handle = await realFsPromises.open(path, flags);+ const sync = handle.sync.bind(handle);+ handle.sync = async () => { calls.push(['dirSync', path]); return sync(); };+ return handle;+ });++ await atomicWrite(target, { durable: true });++ expect(calls).toEqual([['writeFile', true], ['rename'], ['dirSync', tmpRoot]]);+ expect(JSON.parse(readFileSync(target, 'utf8'))).toEqual({ durable: true });+ });++ it('skips the directory sync on Windows', async () => {+ restorePlatform = pinPlatform('win32');+ const target = join(tmpRoot, 'state.json');+ fsPromises.open.mockClear();++ await atomicWrite(target, { v: 1 });++ expect(fsPromises.open).not.toHaveBeenCalled();+ expect(JSON.parse(readFileSync(target, 'utf8'))).toEqual({ v: 1 });+ });+});+describe('AI Toolkit atomicWrite preparation failures', () => {it('removes a partially written temp file and can retry without changing the original on failure', async () => {const target = join(tmpRoot, 'state.json');diff --git a/server/lib/fileCore.js b/server/lib/fileCore.jsindex 46419f5b65..41cd3e4c4a 100644--- a/server/lib/fileCore.js+++ b/server/lib/fileCore.js@@ -1,5 +1,5 @@/** Cross-cutting filesystem, time, formatting, and hashing helpers. */-import { access, appendFile, chmod, copyFile, mkdir, readFile, readdir, stat, writeFile, rename, unlink, rm } from 'fs/promises';+import { access, appendFile, chmod, copyFile, mkdir, open, readFile, readdir, stat, writeFile, rename, unlink, rm } from 'fs/promises';import { createReadStream, createWriteStream, existsSync, statSync, watch as watchFileSystem } from 'fs';import { createHash, randomUUID } from 'crypto';import { basename, dirname, extname, join } from 'path';@@ -41,6 +41,31 @@ const WIN_RETRY_DELAY_MS = 10;const WIN_RENAME_LOCK_CODES = ['EPERM', 'EACCES', 'EEXIST', 'EBUSY'];const FILE_WATCH_FALLBACK_POLL_MS = 5000;+// Directories whose fsync already failed once this process, so a filesystem+// that rejects directory fsync (EINVAL on some network mounts) warns once+// instead of on every write.+const unsyncableDirs = new Set();++/**+ * fsync a directory so a just-completed rename inside it survives a crash.+ * Best-effort once the rename is visible: the bytes are already in place, so a+ * filesystem that cannot sync its directory degrades to the pre-#12025+ * guarantee with one warning rather than failing a write that succeeded.+ * Windows cannot open a directory for fsync, so it is skipped there.+ */+async function syncDirectory(dir) {+ if (isWindows()) return;+ try {+ const handle = await open(dir, 'r');+ try { await handle.sync(); } finally { await handle.close(); }+ } catch (err) {+ if (!err?.code) throw err;+ if (unsyncableDirs.has(dir)) return;+ unsyncableDirs.add(dir);+ console.warn(`⚠️ Directory fsync unavailable for ${dir} (${err.code}); renames there are not crash-durable`);+ }+}+/** Normalize Node statfs block counts into byte totals and compatibility aliases. */export function parseFilesystemStats(stats) {if (!stats) return null;@@ -224,6 +249,13 @@ export async function ensureDirs(dirs) {* to be followed. Callers that genuinely need follow-the-link semantics must* resolve `realpath(filePath)` themselves before calling.*+ * Crash durability (#12025): the temp file is fsynced before the rename and+ * the parent directory after it, so a power loss or OS crash cannot make the+ * rename durable while the bytes are not — the zero-length or stale store that+ * strict readers (settings, auth sessions, the media-jobs persist latch) treat+ * as permanent corruption. The rename alone only protects concurrent readers.+ * Windows gets the file sync only; see `syncDirectory`.+ ** @param {string} filePath - Destination file path* @param {string|object} data - String or JSON-serializable value* @returns {Promise<void>}@@ -293,13 +325,16 @@ export async function atomicWrite(filePath, data) {try {// writeFile can create a partial temp file before rejecting (e.g. ENOSPC).// Own cleanup from that first write, and publish only once its mode is set.- await writeFile(tmp, payload, existingMode !== null ? { mode: existingMode } : undefined);+ // `flush` fsyncs the temp file's bytes before the handle closes, so the+ // rename below never publishes an inode the disk has not yet received.+ await writeFile(tmp, payload, { ...(existingMode !== null ? { mode: existingMode } : {}), flush: true });if (existingMode !== null) await chmod(tmp, existingMode);await replace();} catch (err) {await unlink(tmp).catch(() => {});throw err;}+ await syncDirectory(dirname(filePath));}/**diff --git a/server/lib/fileUtils.test.js b/server/lib/fileUtils.test.jsindex 8daa62a3b7..9e4c34004c 100644--- a/server/lib/fileUtils.test.js+++ b/server/lib/fileUtils.test.js@@ -20,6 +20,7 @@ vi.mock('fs/promises', async (importOriginal) => {return {...actual,mkdir: vi.fn((...args) => actual.mkdir(...args)),+ open: vi.fn((...args) => actual.open(...args)),readFile: vi.fn((...args) => actual.readFile(...args)),rename: vi.fn((...args) => actual.rename(...args)),writeFile: vi.fn((...args) => actual.writeFile(...args)),@@ -102,7 +103,7 @@ describe('importFileToDir', () => {});const restoreFsMocks = () => {- for (const name of ['readFile', 'rename', 'readdir', 'mkdir', 'stat', 'writeFile', 'chmod']) {+ for (const name of ['readFile', 'rename', 'readdir', 'mkdir', 'stat', 'writeFile', 'chmod', 'open']) {fsPromises[name].mockReset();fsPromises[name].mockImplementation((...args) => realFsPromises[name](...args));}@@ -1356,6 +1357,52 @@ describe('fileUtils', () => {expect(await readFile(target, 'utf8')).toBe('{"x":1}\n');});+ // Crash durability (#12025): the bytes reach the disk before the rename+ // publishes them, and the directory entry reaches the disk after. The+ // ordering is observed through the fs seam because a real power loss+ // cannot be staged in a unit test.+ it('fsyncs the temp file before the rename and the parent directory after it', async () => {+ const target = join(tmpRoot, 'durable.json');+ const calls = [];+ fsPromises.writeFile.mockImplementationOnce(async (path, data, options) => {+ calls.push(['writeFile', options?.flush]);+ return realFsPromises.writeFile(path, data, options);+ });+ fsPromises.rename.mockImplementationOnce(async (...args) => {+ calls.push(['rename']);+ return realFsPromises.rename(...args);+ });+ fsPromises.open.mockImplementationOnce(async (path, flags) => {+ const handle = await realFsPromises.open(path, flags);+ const sync = handle.sync.bind(handle);+ handle.sync = async () => { calls.push(['dirSync', path]); return sync(); };+ return handle;+ });++ await atomicWrite(target, { durable: true });++ expect(calls).toEqual([['writeFile', true], ['rename'], ['dirSync', tmpRoot]]);+ expect(JSON.parse(readFileSync(target, 'utf8'))).toEqual({ durable: true });+ });++ it('keeps a published write when the directory cannot be fsynced, warning once per directory', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ try {+ const target = join(tmpRoot, 'netfs.json');+ const failure = Object.assign(new Error('synthetic directory fsync failure'), { code: 'EINVAL' });+ fsPromises.open.mockRejectedValueOnce(failure).mockRejectedValueOnce(failure);++ await atomicWrite(target, { v: 1 });+ await atomicWrite(target, { v: 2 });++ expect(JSON.parse(readFileSync(target, 'utf8'))).toEqual({ v: 2 });+ expect(warn).toHaveBeenCalledTimes(1);+ expect(warn.mock.calls[0][0]).toContain('EINVAL');+ } finally {+ warn.mockRestore();+ }+ });+it('removes a partially written temp file after ENOSPC and allows a later retry', async () => {const target = join(tmpRoot, 'state.json');writeFileSync(target, 'original');@@ -1511,6 +1558,18 @@ describe('Windows swap-window retries (#4095)', () => {});describe('atomicWrite', () => {+ it('fsyncs the temp file but skips the directory sync, which Windows cannot open a handle for (#12025)', async () => {+ const target = join(tmpRoot, 'state.json');+ fakePlatform('win32');+ fsPromises.open.mockClear();++ await atomicWrite(target, { v: 1 });++ expect(fsPromises.writeFile).toHaveBeenLastCalledWith(expect.any(String), expect.any(String), expect.objectContaining({ flush: true }));+ expect(fsPromises.open).not.toHaveBeenCalled();+ expect(JSON.parse(readFileSync(target, 'utf8'))).toEqual({ v: 1 });+ });+it('retries the atomic rename on a transient lock instead of opening the destination-missing window', async () => {const target = join(tmpRoot, 'state.json');writeFileSync(target, JSON.stringify({ v: 1 }));diff --git a/server/services/identity.test.js b/server/services/identity.test.jsindex 2c64139195..b9870c62fb 100644--- a/server/services/identity.test.js+++ b/server/services/identity.test.js@@ -66,6 +66,9 @@ function makeFsPromisesStore() {return { mode: 0o644 };}),chmod: vi.fn(async () => {}),+ // atomicWrite fsyncs the parent directory after the rename (#12025); the+ // in-memory store has nothing to flush, so hand back an inert handle.+ open: vi.fn(async () => ({ sync: async () => {}, close: async () => {} })),};}