@jinn-network/core 0.1.0

package/dist/evidence-store-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withEvidenceStoreLockSync<T>(episodesDir: string, operation: () => T): T;
+export declare function withEvidenceStoreLock<T>(episodesDir: string, operation: () => Promise<T>, afterUnlock?: (result: T) => Promise<void>): Promise<T>;

package/dist/evidence-store-lock.js

@@ -0,0 +1,208 @@
+import { constants, closeSync, fchmodSync, fsyncSync, openSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import Database from 'better-sqlite3';
+import { inspectRegularPath, nodeErrorCode, prepareEvidenceDirectory, recoverWriterPublicationAliases, secureRegularPath, } from './evidence-filesystem.js';
+const LOCK_FILE = '.jinn-evidence-store-lock.sqlite';
+const LOCK_APPLICATION_ID = 0x4a4c4f43;
+const LOCK_SCHEMA_VERSION = '1';
+const LOCK_BUSY_TIMEOUT_MS = 30_000;
+const asyncTails = new Map();
+const activeAsyncKeys = new Set();
+function prepareLockFile(episodesDir) {
+    const directory = resolve(episodesDir);
+    prepareEvidenceDirectory(directory, 'evidence store', true);
+    const path = join(directory, LOCK_FILE);
+    let identity = inspectRegularPath(path, 'evidence store lock');
+    if (!identity) {
+        let fd;
+        try {
+            fd = openSync(path, constants.O_RDWR
+                | constants.O_CREAT
+                | constants.O_EXCL
+                | (constants.O_NOFOLLOW ?? 0), 0o600);
+            if (process.platform !== 'win32')
+                fchmodSync(fd, 0o600);
+            fsyncSync(fd);
+        }
+        catch (error) {
+            if (nodeErrorCode(error) !== 'EEXIST')
+                throw error;
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+        identity = inspectRegularPath(path, 'evidence store lock');
+    }
+    if (!identity)
+        throw new Error(`evidence store lock disappeared: ${path}`);
+    return { path, identity };
+}
+function openStoreLock(episodesDir) {
+    const prepared = prepareLockFile(episodesDir);
+    const db = new Database(prepared.path);
+    try {
+        // Fail before even a writable pragma or schema transaction if the prepared
+        // pathname changed between creation/inspection and SQLite open.
+        secureRegularPath(prepared.path, 'evidence store lock', prepared.identity);
+        db.pragma(`busy_timeout = ${LOCK_BUSY_TIMEOUT_MS}`);
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const applicationId = Number(db.pragma('application_id', { simple: true }));
+            const tables = db.prepare(`
+        SELECT name FROM sqlite_master
+        WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+        ORDER BY name ASC
+      `).all();
+            if (applicationId === 0 && tables.length === 0) {
+                db.pragma(`application_id = ${LOCK_APPLICATION_ID}`);
+                db.exec(`
+          CREATE TABLE evidence_store_lock_meta (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          );
+          INSERT INTO evidence_store_lock_meta(key, value)
+          VALUES ('schema_version', '${LOCK_SCHEMA_VERSION}');
+        `);
+            }
+            else {
+                if (applicationId !== LOCK_APPLICATION_ID) {
+                    throw new Error(`refusing file that is not a Jinn evidence store lock: ${prepared.path}`);
+                }
+                if (JSON.stringify(tables.map((row) => row.name)) !== JSON.stringify([
+                    'evidence_store_lock_meta',
+                ])) {
+                    throw new Error(`refusing evidence store lock with an unexpected schema: ${prepared.path}`);
+                }
+                const version = db.prepare("SELECT value FROM evidence_store_lock_meta WHERE key = 'schema_version'").get();
+                if (version?.value !== LOCK_SCHEMA_VERSION) {
+                    throw new Error(`unsupported Jinn evidence store lock schema: ${String(version?.value)}`);
+                }
+            }
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            if (db.inTransaction)
+                db.exec('ROLLBACK');
+            throw error;
+        }
+        secureRegularPath(prepared.path, 'evidence store lock', prepared.identity);
+        return { db, path: prepared.path, identity: prepared.identity };
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+function closeStoreLock(lock) {
+    let failure;
+    try {
+        lock.db.close();
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        secureRegularPath(lock.path, 'evidence store lock', lock.identity);
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    if (failure !== undefined)
+        throw failure;
+}
+function beginStoreLock(lock) {
+    secureRegularPath(lock.path, 'evidence store lock', lock.identity);
+    lock.db.exec('BEGIN IMMEDIATE');
+}
+function finishStoreLock(lock, commit) {
+    if (lock.db.inTransaction)
+        lock.db.exec(commit ? 'COMMIT' : 'ROLLBACK');
+}
+export function withEvidenceStoreLockSync(episodesDir, operation) {
+    const key = resolve(episodesDir);
+    if (activeAsyncKeys.has(key)) {
+        throw new Error(`cannot synchronously acquire an evidence store lock while an async `
+            + `operation is active in this process: ${key}`);
+    }
+    const lock = openStoreLock(episodesDir);
+    try {
+        beginStoreLock(lock);
+        try {
+            recoverWriterPublicationAliases(resolve(episodesDir));
+            const result = operation();
+            finishStoreLock(lock, true);
+            return result;
+        }
+        catch (error) {
+            finishStoreLock(lock, false);
+            throw error;
+        }
+    }
+    finally {
+        closeStoreLock(lock);
+    }
+}
+export async function withEvidenceStoreLock(episodesDir, operation, afterUnlock) {
+    const key = resolve(episodesDir);
+    const previous = asyncTails.get(key) ?? Promise.resolve();
+    let release;
+    const turn = new Promise((resolveTurn) => {
+        release = resolveTurn;
+    });
+    const tail = previous.catch(() => undefined).then(() => turn);
+    asyncTails.set(key, tail);
+    await previous.catch(() => undefined);
+    let released = false;
+    const releaseTurn = () => {
+        if (released)
+            return;
+        released = true;
+        release();
+        if (asyncTails.get(key) === tail)
+            asyncTails.delete(key);
+    };
+    let ownsActiveMarker = false;
+    const clearActiveMarker = () => {
+        if (!ownsActiveMarker)
+            return;
+        ownsActiveMarker = false;
+        activeAsyncKeys.delete(key);
+    };
+    try {
+        let result;
+        activeAsyncKeys.add(key);
+        ownsActiveMarker = true;
+        const lock = openStoreLock(episodesDir);
+        try {
+            beginStoreLock(lock);
+            try {
+                recoverWriterPublicationAliases(resolve(episodesDir));
+                result = await operation();
+                finishStoreLock(lock, true);
+            }
+            catch (error) {
+                finishStoreLock(lock, false);
+                throw error;
+            }
+        }
+        finally {
+            try {
+                closeStoreLock(lock);
+            }
+            finally {
+                clearActiveMarker();
+            }
+        }
+        // The cross-process SQLite lock now orders both writes and rebuilds. Let a
+        // refresh callback re-enter the same store without waiting on its own
+        // process-local queue turn.
+        releaseTurn();
+        await afterUnlock?.(result);
+        return result;
+    }
+    finally {
+        clearActiveMarker();
+        releaseTurn();
+    }
+}