@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.10

package/dist/core/repl/store/lockfile.js

@@ -0,0 +1,155 @@
+/**
+ * PID lockfile — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * Prevents two REPL processes in the same project directory from
+ * writing to the same `session.db` concurrently. SQLite's WAL handles
+ * that case correctly at the page level, but the JSONL event log lives
+ * outside the SQL transaction — concurrent appends from two processes
+ * would interleave events. The lockfile is the higher-level mutex.
+ *
+ * Algorithm:
+ *
+ *   1. Try `O_CREAT | O_EXCL` open of `<dir>/session.lock`. Write the
+ *      caller's PID + process start time as the body. If the open
+ *      succeeds, we hold the lock; return.
+ *   2. If `EEXIST`, read the existing PID. Probe with `kill(pid, 0)`
+ *      (signal 0 = "check liveness, do not deliver"). If the probe
+ *      returns ESRCH, the holder is dead — unlink the stale lock and
+ *      retry the exclusive create.
+ *   3. If the probe says the PID is alive, throw `SessionLockBusyError`
+ *      so the caller surfaces a clean message to the operator.
+ *
+ * Why not `proper-lockfile`: pulling a 14kB dependency for a 60-line
+ * PID file is poor cost/benefit. The stale-detection loop is the only
+ * tricky part and we test it explicitly. The dependency would also
+ * pull `signal-exit` + `retry` transitively, raising the install
+ * footprint of the CLI bundle.
+ *
+ * Brand voice / privacy: the lockfile body is `{"pid":N,"createdAt":"…"}`
+ * — operator-readable if they `cat` the file, no secrets. Mode 0600 so
+ * other users on the box cannot read which PID is editing the store.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeSync, } from 'node:fs';
+import { SessionLockBusyError } from './types.js';
+/**
+ * Take an exclusive lock on `lockPath`. Throws `SessionLockBusyError`
+ * if a live process already holds the lock. `kill` is injectable for
+ * tests so the stale-detection branch is exercisable without spawning
+ * a real child process.
+ */
+export function takeLock(lockPath, options) {
+    const kill = options?.kill ?? ((pid, signal) => process.kill(pid, signal));
+    const now = options?.now ?? (() => new Date());
+    const body = { pid: process.pid, createdAt: now().toISOString() };
+    const serialized = JSON.stringify(body);
+    // First attempt: exclusive create. Retry once if the existing lock
+    // turns out to be stale (dead PID).
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeSync(fd, serialized);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { path: lockPath, release: () => releaseLock(lockPath, process.pid) };
+        }
+        catch (error) {
+            // EEXIST is the only branch that triggers stale-detection. Any
+            // other error (EACCES, ENOENT on parent, ENOSPC) propagates so
+            // the caller sees the real failure.
+            if (!isEexist(error)) {
+                throw error;
+            }
+            const holder = readLockBody(lockPath);
+            if (!holder) {
+                // Corrupt body — treat as stale and unlink.
+                tryUnlink(lockPath);
+                continue;
+            }
+            if (holder.pid === process.pid) {
+                // We already hold the lock (reentrant open from same process).
+                // Return a handle that is a no-op on release; the original
+                // owner's release will unlink.
+                return { path: lockPath, release: () => undefined };
+            }
+            if (isAlive(holder.pid, kill)) {
+                throw new SessionLockBusyError(holder.pid, lockPath);
+            }
+            // Stale lock — unlink and retry the exclusive create.
+            tryUnlink(lockPath);
+        }
+    }
+    // Two retries failed — the lock is contested by another process
+    // racing us. Surface as busy rather than spinning.
+    const holder = readLockBody(lockPath);
+    throw new SessionLockBusyError(holder?.pid ?? 0, lockPath);
+}
+/**
+ * Read a lockfile body. Returns null when the file is missing,
+ * unreadable, or malformed. The store never throws from this path —
+ * the caller treats null as "stale, unlink and retry".
+ */
+export function readLockBody(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object'
+            && parsed !== null
+            && typeof parsed.pid === 'number'
+            && typeof parsed.createdAt === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return null;
+}
+function isAlive(pid, kill) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH = no such process. Any other error (EPERM = process exists
+        // but we lack permission) means the process IS alive.
+        const code = error?.code;
+        if (code === 'ESRCH')
+            return false;
+        return true;
+    }
+}
+function releaseLock(lockPath, expectedPid) {
+    const holder = readLockBody(lockPath);
+    if (!holder)
+        return;
+    // Defence-in-depth: only unlink if we still own the lock. A future
+    // session may have taken over after our process died and was
+    // replaced — better to leave the new owner's file in place than to
+    // race-condition delete it.
+    if (holder.pid !== expectedPid)
+        return;
+    tryUnlink(lockPath);
+}
+function tryUnlink(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* ignore — file may be gone already */
+    }
+}
+function isEexist(error) {
+    return error?.code === 'EEXIST';
+}
+//# sourceMappingURL=lockfile.js.map