@optimystic/db-p2p-storage-fs 1.15.0 → 1.17.0

package/src/index.ts

@@ -1,2 +1,5 @@
 export * from './file-storage.js';
+export * from './file-batch-backend.js';
+export * from './file-write-log.js';
+export * from './store-lock.js';
 export * from './file-kv-store.js';

package/src/store-lock.ts

@@ -0,0 +1,123 @@
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createLogger } from './logger.js';
+
+const log = createLogger('store-lock');
+
+export const STORE_LOCK_FILENAME = 'store.lock';
+
+/** What the lock file records about the process that took it. */
+export interface StoreLockHolder {
+	readonly pid: number;
+	readonly hostname: string;
+}
+
+/**
+ * Thrown by every operation of a store whose directory another live process on this machine has
+ * open. Invariant 5 in `packages/db-p2p/docs/storage.md`: a store is owned by exactly one process,
+ * and the write-ahead log makes two writers in one file a corruption rather than a stale cache.
+ */
+export class StoreLockedError extends Error {
+	constructor(readonly lockPath: string, readonly holder: StoreLockHolder) {
+		super(`store at ${path.dirname(lockPath)} is open in process ${holder.pid} on ${holder.hostname}; a store is owned by one process at a time`);
+		this.name = 'StoreLockedError';
+	}
+}
+
+export interface StoreLock {
+	readonly path: string;
+	/** Remove the lock file. Idempotent. */
+	release(): Promise<void>;
+}
+
+/** How many stale locks one open will replace before giving up on a directory whose lock keeps reappearing. */
+const REPLACE_ATTEMPTS = 3;
+
+/**
+ * Take `<basePath>/store.lock` for this process. The file is created exclusively (`wx`) and holds
+ * `{ pid, hostname }`. An existing lock naming this machine and a live pid refuses the open with
+ * {@link StoreLockedError}; any other existing lock — another machine's, a dead pid's, or one whose
+ * content cannot be read — is stale and replaced. The liveness test is `process.kill(pid, 0)`, so
+ * only one machine is protected, which is the one case ever supported (two machines over one
+ * network share never were; Invariant 5).
+ *
+ * NOTE: the content is written in the same call that creates the file, but a second process that
+ * opens the directory in the microseconds between the create and the write reads an empty file,
+ * judges the lock stale and replaces it. Two processes starting over one directory at the same
+ * instant is already the violation the lock exists to refuse; if that race is ever seen, judge an
+ * unreadable lock by its age instead of replacing it at once.
+ * NOTE: the holder is identified by pid and hostname alone. A dead holder's pid reused by an
+ * unrelated process reads as live, and the open is refused until the lock file is removed by hand;
+ * a machine whose hostname changed between two starts reads its own live lock as another
+ * machine's and replaces it. Both need a start-time stamp in the lock to tell apart; add one if
+ * either is seen.
+ */
+export async function acquireStoreLock(basePath: string): Promise<StoreLock> {
+	const lockPath = path.join(basePath, STORE_LOCK_FILENAME);
+	const self: StoreLockHolder = { pid: process.pid, hostname: os.hostname() };
+	for (let attempt = 0; attempt < REPLACE_ATTEMPTS; attempt++) {
+		if (await tryCreate(lockPath, self)) {
+			return { path: lockPath, release: () => removeLock(lockPath) };
+		}
+		const holder = await readHolder(lockPath);
+		if (holder && holder.hostname === self.hostname && processExists(holder.pid)) {
+			throw new StoreLockedError(lockPath, holder);
+		}
+		log('replacing stale lock %s held by %o', lockPath, holder);
+		await removeLock(lockPath);
+	}
+	throw new Error(`could not take ${lockPath}: it was replaced ${REPLACE_ATTEMPTS} times by another opener`);
+}
+
+async function tryCreate(lockPath: string, holder: StoreLockHolder): Promise<boolean> {
+	try {
+		await fs.writeFile(lockPath, JSON.stringify(holder), { flag: 'wx' });
+		return true;
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === 'EEXIST') return false;
+		throw err;
+	}
+}
+
+/** The holder a lock file names, or `undefined` for a missing, unreadable or malformed one. */
+async function readHolder(lockPath: string): Promise<StoreLockHolder | undefined> {
+	let text: string;
+	try {
+		text = await fs.readFile(lockPath, 'utf8');
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+		throw err;
+	}
+	try {
+		const parsed: unknown = JSON.parse(text);
+		return isHolder(parsed) ? parsed : undefined;
+	} catch (err) {
+		if (err instanceof SyntaxError) return undefined;
+		throw err;
+	}
+}
+
+function isHolder(value: unknown): value is StoreLockHolder {
+	if (typeof value !== 'object' || value === null) return false;
+	const { pid, hostname } = value as Record<string, unknown>;
+	return Number.isInteger(pid) && (pid as number) > 0 && typeof hostname === 'string';
+}
+
+/** Signal 0 tests for existence without sending anything; EPERM means the process exists but is not ours. */
+function processExists(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return (err as NodeJS.ErrnoException).code === 'EPERM';
+	}
+}
+
+async function removeLock(lockPath: string): Promise<void> {
+	try {
+		await fs.unlink(lockPath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+	}
+}

package/dist/src/atomic-write.d.ts

@@ -1,22 +0,0 @@
-/**
- * Atomically write `content` to `filePath`.
- *
- * Writes to a unique `*.tmp` sibling, fsyncs the data, then renames it into
- * place. `rename` over an existing file is atomic on POSIX and NTFS, so a
- * concurrent reader only ever sees the complete old file or the complete new
- * file — never a torn/half-written one. After the rename we best-effort fsync
- * the containing directory so the rename itself survives power loss on POSIX;
- * that directory fsync is unsupported on win32 and is skipped there.
- *
- * On any failure the temp file is removed (best-effort) so a crashed write does
- * not leave the canonical path damaged. A crash *between* the temp write and the
- * rename leaves only an inert `*.tmp` sibling — never read (reads target
- * canonical paths) and skipped by `.json` directory scans.
- *
- * `content` is `string | Uint8Array`: `FileKVStore` writes strings, while the
- * `KvRawStorage`-backed `FileStoreDriver` writes the kernel's raw value bytes.
- * `FileHandle.writeFile` writes either losslessly — a `Uint8Array` is written
- * byte-for-byte, so non-ASCII JSON round-trips exactly.
- */
-export declare function atomicWriteFile(filePath: string, content: string | Uint8Array): Promise<void>;
-//# sourceMappingURL=atomic-write.d.ts.map

package/dist/src/atomic-write.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../../src/atomic-write.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCnG"}

package/dist/src/atomic-write.js

@@ -1,90 +0,0 @@
-import { promises as fs } from 'fs';
-import * as path from 'path';
-// Per-process monotonic counter for unique temp names. Combined with the pid it
-// makes each temp path unique across concurrent writers to the same logical
-// target — even two FileRawStorage/FileKVStore instances in one process, which
-// do not lock (see the proper-lockfile TODO in file-storage.ts). Deterministic
-// and collision-safe, unlike Math.random()/Date.now().
-let tempCounter = 0;
-/**
- * Atomically write `content` to `filePath`.
- *
- * Writes to a unique `*.tmp` sibling, fsyncs the data, then renames it into
- * place. `rename` over an existing file is atomic on POSIX and NTFS, so a
- * concurrent reader only ever sees the complete old file or the complete new
- * file — never a torn/half-written one. After the rename we best-effort fsync
- * the containing directory so the rename itself survives power loss on POSIX;
- * that directory fsync is unsupported on win32 and is skipped there.
- *
- * On any failure the temp file is removed (best-effort) so a crashed write does
- * not leave the canonical path damaged. A crash *between* the temp write and the
- * rename leaves only an inert `*.tmp` sibling — never read (reads target
- * canonical paths) and skipped by `.json` directory scans.
- *
- * `content` is `string | Uint8Array`: `FileKVStore` writes strings, while the
- * `KvRawStorage`-backed `FileStoreDriver` writes the kernel's raw value bytes.
- * `FileHandle.writeFile` writes either losslessly — a `Uint8Array` is written
- * byte-for-byte, so non-ASCII JSON round-trips exactly.
- */
-export async function atomicWriteFile(filePath, content) {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
-    // Suffix ends in `.tmp` (not `.json`) so listPendingTransactions / FileKVStore.list,
-    // which filter on `.json`, never surface an in-flight temp file.
-    // NOTE: a crash between open and rename leaves an inert `*.tmp` orphan (never read,
-    // skipped by `.json` scans). No cleanup sweep exists; if a crash-looping writer ever
-    // accumulates many, add a startup sweep of stale `*.tmp` siblings.
-    const tmpPath = path.join(dir, `${path.basename(filePath)}.${process.pid}.${tempCounter++}.tmp`);
-    let handle;
-    try {
-        handle = await fs.open(tmpPath, 'w');
-        await handle.writeFile(content);
-        await handle.sync();
-        await handle.close();
-        handle = undefined;
-        // NOTE: on win32, rename-over-existing can throw EPERM/EACCES/EBUSY if a
-        // concurrent reader holds the target open without FILE_SHARE_DELETE (Node
-        // readIfExists/get open→read→close in a tiny window, so it's rare). Modern
-        // libuv retries some cases; if this ever surfaces as spurious write failures
-        // under concurrent read+write on Windows, add a bounded retry loop here (the
-        // write-file-atomic package does exactly this). Conditional — the adapter is
-        // already last-writer-wins with no cross-process lock (proper-lockfile TODO
-        // in file-storage.ts), so it is not reachable under current single-writer use.
-        await fs.rename(tmpPath, filePath);
-    }
-    catch (err) {
-        if (handle)
-            await handle.close().catch(() => { });
-        await fs.unlink(tmpPath).catch(() => { });
-        throw err;
-    }
-    await fsyncDir(dir);
-}
-/**
- * Best-effort fsync of a directory so a completed rename is durable. POSIX needs
- * this; platforms that reject opening a directory for fsync throw, and we ignore
- * that rather than failing the write.
- *
- * Skipped outright on win32: there `fs.open(dir, 'r')` SUCCEEDS and only the
- * following `handle.sync()` fails with EPERM (swallowed), so the open/close pair
- * was guaranteed wasted work — exactly half of all `fs.open` calls a write
- * workload makes. Durability is unchanged on win32 (the sync never succeeded
- * there); the on-disk layout is untouched.
- */
-async function fsyncDir(dir) {
-    if (process.platform === 'win32')
-        return;
-    let handle;
-    try {
-        handle = await fs.open(dir, 'r');
-        await handle.sync();
-    }
-    catch {
-        // Directory fsync unsupported here — nothing to do.
-    }
-    finally {
-        if (handle)
-            await handle.close().catch(() => { });
-    }
-}
-//# sourceMappingURL=atomic-write.js.map

package/dist/src/atomic-write.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,gFAAgF;AAChF,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,uDAAuD;AACvD,IAAI,WAAW,GAAG,CAAC,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB,EAAE,OAA4B;IACnF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,qFAAqF;IACrF,iEAAiE;IACjE,oFAAoF;IACpF,qFAAqF;IACrF,mEAAmE;IACnE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,WAAW,EAAE,MAAM,CAAC,CAAC;IAEjG,IAAI,MAAiC,CAAC;IACtC,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACrC,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,GAAG,SAAS,CAAC;QACnB,yEAAyE;QACzE,0EAA0E;QAC1E,2EAA2E;QAC3E,6EAA6E;QAC7E,6EAA6E;QAC7E,6EAA6E;QAC7E,4EAA4E;QAC5E,+EAA+E;QAC/E,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,MAAM;YAAE,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAqB,CAAC,CAAC,CAAC;QACpE,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAyC,CAAC,CAAC,CAAC;QAChF,MAAM,GAAG,CAAC;IACX,CAAC;IAED,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IACzC,IAAI,MAAiC,CAAC;IACtC,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACR,oDAAoD;IACrD,CAAC;YAAS,CAAC;QACV,IAAI,MAAM;YAAE,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAqB,CAAC,CAAC,CAAC;IACrE,CAAC;AACF,CAAC"}

package/src/atomic-write.ts

@@ -1,89 +0,0 @@
-import { promises as fs } from 'fs';
-import * as path from 'path';
-
-// Per-process monotonic counter for unique temp names. Combined with the pid it
-// makes each temp path unique across concurrent writers to the same logical
-// target — even two FileRawStorage/FileKVStore instances in one process, which
-// do not lock (see the proper-lockfile TODO in file-storage.ts). Deterministic
-// and collision-safe, unlike Math.random()/Date.now().
-let tempCounter = 0;
-
-/**
- * Atomically write `content` to `filePath`.
- *
- * Writes to a unique `*.tmp` sibling, fsyncs the data, then renames it into
- * place. `rename` over an existing file is atomic on POSIX and NTFS, so a
- * concurrent reader only ever sees the complete old file or the complete new
- * file — never a torn/half-written one. After the rename we best-effort fsync
- * the containing directory so the rename itself survives power loss on POSIX;
- * that directory fsync is unsupported on win32 and is skipped there.
- *
- * On any failure the temp file is removed (best-effort) so a crashed write does
- * not leave the canonical path damaged. A crash *between* the temp write and the
- * rename leaves only an inert `*.tmp` sibling — never read (reads target
- * canonical paths) and skipped by `.json` directory scans.
- *
- * `content` is `string | Uint8Array`: `FileKVStore` writes strings, while the
- * `KvRawStorage`-backed `FileStoreDriver` writes the kernel's raw value bytes.
- * `FileHandle.writeFile` writes either losslessly — a `Uint8Array` is written
- * byte-for-byte, so non-ASCII JSON round-trips exactly.
- */
-export async function atomicWriteFile(filePath: string, content: string | Uint8Array): Promise<void> {
-	const dir = path.dirname(filePath);
-	await fs.mkdir(dir, { recursive: true });
-
-	// Suffix ends in `.tmp` (not `.json`) so listPendingTransactions / FileKVStore.list,
-	// which filter on `.json`, never surface an in-flight temp file.
-	// NOTE: a crash between open and rename leaves an inert `*.tmp` orphan (never read,
-	// skipped by `.json` scans). No cleanup sweep exists; if a crash-looping writer ever
-	// accumulates many, add a startup sweep of stale `*.tmp` siblings.
-	const tmpPath = path.join(dir, `${path.basename(filePath)}.${process.pid}.${tempCounter++}.tmp`);
-
-	let handle: fs.FileHandle | undefined;
-	try {
-		handle = await fs.open(tmpPath, 'w');
-		await handle.writeFile(content);
-		await handle.sync();
-		await handle.close();
-		handle = undefined;
-		// NOTE: on win32, rename-over-existing can throw EPERM/EACCES/EBUSY if a
-		// concurrent reader holds the target open without FILE_SHARE_DELETE (Node
-		// readIfExists/get open→read→close in a tiny window, so it's rare). Modern
-		// libuv retries some cases; if this ever surfaces as spurious write failures
-		// under concurrent read+write on Windows, add a bounded retry loop here (the
-		// write-file-atomic package does exactly this). Conditional — the adapter is
-		// already last-writer-wins with no cross-process lock (proper-lockfile TODO
-		// in file-storage.ts), so it is not reachable under current single-writer use.
-		await fs.rename(tmpPath, filePath);
-	} catch (err) {
-		if (handle) await handle.close().catch(() => { /* best-effort */ });
-		await fs.unlink(tmpPath).catch(() => { /* best-effort: temp may not exist */ });
-		throw err;
-	}
-
-	await fsyncDir(dir);
-}
-
-/**
- * Best-effort fsync of a directory so a completed rename is durable. POSIX needs
- * this; platforms that reject opening a directory for fsync throw, and we ignore
- * that rather than failing the write.
- *
- * Skipped outright on win32: there `fs.open(dir, 'r')` SUCCEEDS and only the
- * following `handle.sync()` fails with EPERM (swallowed), so the open/close pair
- * was guaranteed wasted work — exactly half of all `fs.open` calls a write
- * workload makes. Durability is unchanged on win32 (the sync never succeeded
- * there); the on-disk layout is untouched.
- */
-async function fsyncDir(dir: string): Promise<void> {
-	if (process.platform === 'win32') return;
-	let handle: fs.FileHandle | undefined;
-	try {
-		handle = await fs.open(dir, 'r');
-		await handle.sync();
-	} catch {
-		// Directory fsync unsupported here — nothing to do.
-	} finally {
-		if (handle) await handle.close().catch(() => { /* best-effort */ });
-	}
-}