@serfab/cadre-core 1.13.0 → 1.15.0

package/src/fs-atomic.ts

@@ -1,117 +1,92 @@
-/**
- * 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 — and every uppercase letter, because Windows
- * (NTFS) and macOS (APFS/HFS+ by default) ignore case in file names. Reversed by
- * `decodeURIComponent`.
- *
- * The result contains only `a-z0-9-_` and `%XX` escapes (uppercase hex). Since a
- * literal `%` is itself escaped, every `%` starts an escape, so ignoring case
- * can change only escape hex digits — which decode case-insensitively — and two
- * different inputs never yield names equal ignoring case. The escapes keep
- * `encodeURIComponent`'s uppercase hex so a name built from an id with no
- * capital letters (the identity slot `cadre%2Fidentity.key`, a lowercase party
- * id) is the same as before uppercase letters were escaped.
- */
-export function encodeFileSafeComponent(component: string): string {
-	// NOTE: a file left from before uppercase letters were escaped (`trusted-owners.Alice.json`) has, ignoring case, the new name of the all-lowercase id (`alice`), so on Windows/macOS a lookup for that id opens it; the per-party records' envelope party-id check rejects it (cold start), and `FileKeyStore` needs two parties in one key directory whose ids fold to the same lowercase string. The release note says to delete old files; if a store ever reads another id's old file in practice, rename or remove old-format files when the store opens.
-	return encodeURIComponent(component).replace(
-		/(%[0-9A-F]{2})|[!'()*~.A-Z]/g,
-		(c, escape: string | undefined) => escape ?? `%${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(() => {});
-	}
-}
+/**
+ * Node-only filesystem helpers: atomic file write and the ENOENT check, shared
+ * by `key-store-file.ts` and `file-durable-slot.ts`. The filename-safe encoding
+ * they also use is cross-platform and lives in `file-safe-name.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;
+
+/** 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(() => {});
+	}
+}