Skip to content

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

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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 () => {} })),
};
}