@serfab/cadre-core 0.9.0 → 0.11.0

package/src/fs-atomic.ts

@@ -0,0 +1,107 @@
+/**
+ * Node-only filesystem helpers: atomic file write, filename-safe encoding, and
+ * the ENOENT check, shared by `key-store-file.ts` and `file-durable-slot.ts`.
+ *
+ * This module imports `node:fs/promises`, so — like its consumers — it is kept
+ * OUT of the package's cross-platform default entry and is not itself an
+ * exported subpath; it is only reachable through the Node-only store modules.
+ */
+import debug from 'debug';
+import { mkdir, rm, rename, open } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+
+const log = debug('sereus:cadre:fs-atomic');
+
+/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
+export const DIR_MODE = 0o700;
+export const FILE_MODE = 0o600;
+
+/**
+ * Percent-encode a string into a filesystem-safe filename component. Beyond
+ * `encodeURIComponent` (which already escapes `/`, spaces, and unicode), this
+ * also escapes the unreserved characters `encodeURIComponent` leaves intact but
+ * that are unsafe in filenames on some platforms (notably `*` on Windows) — and
+ * `.`, so a file suffix appended by the caller is the only literal dot, making
+ * suffix-stripping unambiguous. Reversed by `decodeURIComponent`. The result
+ * contains only `A-Za-z0-9-_` and `%XX`.
+ */
+export function encodeFileSafeComponent(component: string): string {
+	return encodeURIComponent(component).replace(
+		/[!'()*~.]/g,
+		(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+	);
+}
+
+/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
+export function isNotFound(error: unknown): boolean {
+	return typeof error === 'object' && error !== null
+		&& (error as { code?: unknown }).code === 'ENOENT';
+}
+
+/**
+ * Crash-atomic file write: a concurrent reader sees either the complete
+ * previous bytes or the complete new bytes, never a torn file. `dir` is created
+ * (0700) if absent; the data is written to `tmpPath` (created exclusively,
+ * 0600), fsync'd, then atomically renamed onto `finalPath`. A failure at any
+ * point removes the temp file and leaves the previous file untouched.
+ *
+ * `tmpPath` must be a sibling of `finalPath` (same directory) so the rename
+ * stays within one filesystem and is therefore atomic, and should carry a
+ * random component so concurrent writers (and crash-orphaned leftovers) are
+ * collide-free.
+ *
+ * Durability bar: the temp file is fsync'd before the rename so a power loss
+ * cannot surface a file whose bytes never reached the platter, and `dir` is
+ * fsync'd afterwards (best-effort — see {@link syncDirBestEffort}) so the
+ * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+ * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+ * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+ * holds the destination open. That cross-process case is out of scope for the
+ * single-flight in-process callers here; such a failure surfaces to the caller
+ * with the previous file left intact.
+ */
+export async function writeFileAtomically(
+	dir: string,
+	tmpPath: string,
+	finalPath: string,
+	data: Uint8Array
+): Promise<void> {
+	await mkdir(dir, { recursive: true, mode: DIR_MODE });
+	// 'wx' creates the temp file exclusively; a name collision (astronomically
+	// unlikely given the caller's random component) fails here before we own anything.
+	const handle = await open(tmpPath, 'wx', FILE_MODE);
+	try {
+		try {
+			await handle.writeFile(data);
+			await handle.sync(); // land bytes on disk before the rename exposes them
+		} finally {
+			await handle.close().catch(() => {});
+		}
+		await rename(tmpPath, finalPath);
+	} catch (error) {
+		// Any failure after creation (write, sync, or rename): drop the temp
+		// file so a retry leaves no `.tmp` debris. The destination is only ever
+		// swapped by the atomic rename, so the previous bytes stay intact.
+		await rm(tmpPath, { force: true }).catch(() => {});
+		throw error;
+	}
+	await syncDirBestEffort(dir);
+}
+
+/**
+ * Best-effort fsync of a directory so a fresh file's directory entry is
+ * durable across power loss. Opening a directory for fsync is not portable
+ * (unsupported on Windows and some filesystems), and rename atomicity does not
+ * depend on it — so a failure here is logged and swallowed, never surfaced.
+ */
+async function syncDirBestEffort(dir: string): Promise<void> {
+	let dirHandle: FileHandle | undefined;
+	try {
+		dirHandle = await open(dir, 'r');
+		await dirHandle.sync();
+	} catch (error) {
+		log('directory fsync skipped for %s: %o', dir, error);
+	} finally {
+		await dirHandle?.close().catch(() => {});
+	}
+}