@ericsanchezok/synergy-util 3.0.20 → 3.0.22

package/dist/fs-lock.js

@@ -1,9 +1,11 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { processStartIdentity } from "./process-identity";
 const DEFAULT_RETRY_MS = 25;
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_STALE_METADATA_MS = 5_000;
+const VERIFIED_LIVE_TTL_MS = 1_000;
 export const HOLOS_ACCOUNTS_WRITE_LOCK_KEY = "holos-accounts:write";
 export const LEGACY_API_KEY_WRITE_LOCK_KEY = "legacy-api-key:write";
 export function authLockDirectory(synergyRoot) {
@@ -30,57 +32,148 @@ async function acquireFileLock(options) {
     await fs.chmod(options.directory, 0o700);
     const filename = fileLockPath(options.directory, options.key);
     const startedAt = Date.now();
+    const startIdentity = await processStartIdentity(process.pid);
+    const ownerToken = randomUUID();
+    const verifiedLiveUntil = new Map();
     while (true) {
+        if (Date.now() - startedAt >= timeoutMs) {
+            throw new Error(options.timeoutMessage ?? `Timed out acquiring file lock for ${options.key}`);
+        }
+        let handle;
         try {
-            const handle = await fs.open(filename, "wx", 0o600);
-            try {
-                await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: Date.now() }));
-            }
-            catch (error) {
-                await fs.unlink(filename).catch(() => { });
-                throw error;
-            }
-            finally {
-                await handle.close();
-            }
-            return {
-                async release() {
-                    await fs.unlink(filename).catch((error) => {
-                        if (error.code !== "ENOENT")
-                            throw error;
-                    });
-                },
-            };
+            handle = await fs.open(filename, "wx", 0o600);
         }
         catch (error) {
-            if (error.code !== "EEXIST")
+            const code = error.code;
+            // Provenance: DeleteFileW delete-pending semantics — an open on a
+            // delete-pending entry fails with access-denied until the last handle
+            // closes ( https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-deletefilew ).
+            // Local adaptation: libuv maps that failure to EPERM, so an exclusive
+            // create can see EPERM instead of EEXIST right after a release — treat
+            // it as contention and retry. Only the create itself qualifies:
+            // EPERM from payload writes or close stays a caller-visible failure,
+            // bounded here by the top-of-loop timeout check.
+            if (code !== "EEXIST" && code !== "EPERM")
                 throw error;
-            const owner = await readLockOwner(filename);
-            if (owner?.pid && !processExists(owner.pid)) {
-                await fs.unlink(filename).catch(() => { });
-                continue;
-            }
-            if (!owner?.pid) {
-                const stat = await fs.stat(filename).catch(() => undefined);
-                if (stat && Date.now() - stat.mtimeMs > staleMetadataMs) {
-                    await fs.unlink(filename).catch(() => { });
+            const snapshot = await readOwnerSnapshot(filename);
+            if (snapshot && (await isStaleOwner(filename, snapshot, staleMetadataMs, verifiedLiveUntil))) {
+                if (await removeStaleLock(filename, snapshot.contents))
                     continue;
-                }
-            }
-            if (Date.now() - startedAt >= timeoutMs) {
-                throw new Error(options.timeoutMessage ?? `Timed out acquiring file lock for ${options.key}`);
             }
             await sleep(retryMs);
+            continue;
+        }
+        try {
+            await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: Date.now(), startIdentity, ownerToken }));
         }
+        catch (error) {
+            await fs.unlink(filename).catch(() => { });
+            throw error;
+        }
+        finally {
+            await handle.close();
+        }
+        return {
+            release: () => releaseOwnedLock(filename, ownerToken),
+        };
+    }
+}
+async function readOwnerSnapshot(filename) {
+    const contents = await fs.readFile(filename, "utf8").catch(() => undefined);
+    if (contents === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(contents);
+        if (!value || typeof value !== "object")
+            return { contents };
+        const pid = value.pid;
+        const startIdentity = value.startIdentity;
+        return {
+            contents,
+            owner: {
+                pid: typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? pid : undefined,
+                startIdentity: typeof startIdentity === "string" ? startIdentity : undefined,
+            },
+        };
+    }
+    catch {
+        return { contents };
+    }
+}
+/**
+ * A live pid proves nothing: pids recycle on every platform, and on Windows a
+ * recycled pid makes a dead owner look alive forever. The recorded start
+ * identity settles whether the pid still belongs to the process that took the
+ * lock — deterministically, without ever displacing a live owner by age.
+ */
+async function isStaleOwner(filename, snapshot, staleMetadataMs, verifiedLiveUntil) {
+    const owner = snapshot.owner;
+    if (owner?.pid === undefined) {
+        const stat = await fs.stat(filename).catch(() => undefined);
+        return !!stat && Date.now() - stat.mtimeMs > staleMetadataMs;
+    }
+    if (!processExists(owner.pid))
+        return true;
+    if (owner.startIdentity === undefined)
+        return false;
+    const key = `${owner.pid}:${owner.startIdentity}`;
+    const verifiedUntil = verifiedLiveUntil.get(key);
+    if (verifiedUntil !== undefined && verifiedUntil > Date.now())
+        return false;
+    const current = await processStartIdentity(owner.pid);
+    if (current === undefined || current === owner.startIdentity) {
+        // The owner was verified live. Cache the verdict briefly so the identity
+        // query (a subprocess on Windows) is not spawned on every retry, but
+        // recheck once it expires: the owner may exit and its pid be recycled
+        // while this acquisition attempt is still waiting.
+        verifiedLiveUntil.set(key, Date.now() + VERIFIED_LIVE_TTL_MS);
+        return false;
     }
+    return true;
 }
-async function readLockOwner(filename) {
+/**
+ * Remove the lock file only while its contents still match the snapshot the
+ * stale decision was based on. Read-compare-unlink, never rename-vacate: a
+ * rename briefly removes the canonical path, and when several waiters observe
+ * the same stale payload a delayed rename can displace a successor's fresh
+ * lock and then discard it on a failed restore — overlapping critical
+ * sections. The residual read-to-unlink window is far narrower and only
+ * deletes a lock that was replaced in that instant, not a lock we moved.
+ */
+async function removeStaleLock(filename, expectedContents) {
+    const current = await fs.readFile(filename, "utf8").catch(() => undefined);
+    if (current !== expectedContents)
+        return false;
+    try {
+        await fs.unlink(filename);
+        return true;
+    }
+    catch (error) {
+        // ENOENT: another waiter already reclaimed it — treat as removed.
+        return error.code === "ENOENT";
+    }
+}
+async function releaseOwnedLock(filename, ownerToken) {
+    const contents = await fs.readFile(filename, "utf8").catch(() => undefined);
+    if (contents === undefined || readOwnerToken(contents) !== ownerToken)
+        return;
+    try {
+        await fs.unlink(filename);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function readOwnerToken(contents) {
+    if (contents === undefined)
+        return undefined;
     try {
-        const owner = JSON.parse(await fs.readFile(filename, "utf8"));
-        if (!owner || typeof owner !== "object")
+        const value = JSON.parse(contents);
+        if (!value || typeof value !== "object")
             return undefined;
-        const pid = owner.pid;
-        return typeof pid === "number" ? { pid } : undefined;
+        const ownerToken = value.ownerToken;
+        return typeof ownerToken === "string" ? ownerToken : undefined;
     }
     catch {
         return undefined;

package/dist/process-identity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Identity of a pid beyond the number itself: the moment the occupying process
+ * started. Pids recycle on every platform, so a recorded pid matching a live
+ * process does not prove that process is the recorded one — the same pid held
+ * by a process with a different start time does. Returns `undefined` when the
+ * start time cannot be determined; callers must treat that as "unknown", never
+ * as "recycled".
+ *
+ * Every platform has one canonical encoding, so a recorded identity is always
+ * comparable with a later query on the same machine. Linux identities include
+ * the boot id because start ticks reset on reboot while lock files survive it.
+ */
+export declare function processStartIdentity(pid: number): Promise<string | undefined>;
+/**
+ * WMIC reports the creation time as local wall clock plus a UTC offset in
+ * minutes (`YYYYMMDDHHMMSS.microseconds±UUU`). Convert to UTC epoch
+ * milliseconds so the value stays comparable with the PowerShell fallback,
+ * which reports .NET ticks — the two sources must share one encoding or a
+ * live owner looks like a recycled pid when a later query takes the other
+ * path.
+ */
+export declare function wmicCreationDateToEpochMs(value: string): number | undefined;
+/** .NET ticks (100 ns since 0001-01-01) → UTC epoch milliseconds. */
+export declare function ticksToEpochMs(value: string): number | undefined;

package/dist/process-identity.js

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+let ownIdentityPromise;
+let linuxBootIdPromise;
+/**
+ * Identity of a pid beyond the number itself: the moment the occupying process
+ * started. Pids recycle on every platform, so a recorded pid matching a live
+ * process does not prove that process is the recorded one — the same pid held
+ * by a process with a different start time does. Returns `undefined` when the
+ * start time cannot be determined; callers must treat that as "unknown", never
+ * as "recycled".
+ *
+ * Every platform has one canonical encoding, so a recorded identity is always
+ * comparable with a later query on the same machine. Linux identities include
+ * the boot id because start ticks reset on reboot while lock files survive it.
+ */
+export async function processStartIdentity(pid) {
+    if (pid === process.pid) {
+        // Cache the promise, not the value: concurrent first acquisitions must
+        // share a single query instead of spawning one subprocess each.
+        ownIdentityPromise ??= queryProcessStartIdentity(pid);
+        return ownIdentityPromise;
+    }
+    return queryProcessStartIdentity(pid);
+}
+async function queryProcessStartIdentity(pid) {
+    if (process.platform === "linux") {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, "utf8").catch(() => "");
+        const closingParen = stat.lastIndexOf(")");
+        const fields = closingParen < 0
+            ? []
+            : stat
+                .slice(closingParen + 1)
+                .trim()
+                .split(/\s+/);
+        const startTicks = fields[19];
+        if (!startTicks)
+            return undefined;
+        const bootId = await linuxBootId();
+        return bootId ? `linux:${bootId}:${startTicks}` : `linux:${startTicks}`;
+    }
+    if (process.platform === "win32") {
+        const wmic = await execFileAsync("wmic.exe", [
+            "process",
+            "where",
+            `(ProcessId=${pid})`,
+            "get",
+            "CreationDate",
+            "/value",
+        ]).catch(() => ({ stdout: "" }));
+        const creationDate = wmic.stdout.match(/CreationDate=(\d{14}\.\d{6}[+-]\d{3})/)?.[1];
+        if (creationDate !== undefined) {
+            const epochMs = wmicCreationDateToEpochMs(creationDate);
+            if (epochMs !== undefined)
+                return `windows:${epochMs}`;
+        }
+        const result = await execFileAsync("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+        ]).catch(() => ({ stdout: "" }));
+        const epochMs = ticksToEpochMs(result.stdout);
+        if (epochMs !== undefined)
+            return `windows:${epochMs}`;
+        return undefined;
+    }
+    // `ps -o lstart=` resolves to whole seconds on macOS and BSD, so two
+    // processes started within the same second share an identity and a pid
+    // recycled within that second is not detected. That failure is fail-safe:
+    // the stale lock waits out the acquire timeout instead of a live owner
+    // being displaced.
+    const result = await execFileAsync("ps", ["-p", String(pid), "-o", "lstart="]).catch(() => ({ stdout: "" }));
+    const startedAt = Date.parse(result.stdout.trim());
+    return Number.isNaN(startedAt) ? undefined : `unix:${startedAt}`;
+}
+async function linuxBootId() {
+    linuxBootIdPromise ??= fs
+        .readFile("/proc/sys/kernel/random/boot_id", "utf8")
+        .then((value) => value.trim() || undefined)
+        .catch(() => undefined);
+    return linuxBootIdPromise;
+}
+/**
+ * WMIC reports the creation time as local wall clock plus a UTC offset in
+ * minutes (`YYYYMMDDHHMMSS.microseconds±UUU`). Convert to UTC epoch
+ * milliseconds so the value stays comparable with the PowerShell fallback,
+ * which reports .NET ticks — the two sources must share one encoding or a
+ * live owner looks like a recycled pid when a later query takes the other
+ * path.
+ */
+export function wmicCreationDateToEpochMs(value) {
+    const match = value.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-]\d{3})$/);
+    if (!match)
+        return undefined;
+    const [, year, month, day, hour, minute, second, micros, offset] = match;
+    const offsetMinutes = Number(offset);
+    return (Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second), Number(micros.slice(0, 3))) -
+        offsetMinutes * 60_000);
+}
+/** .NET ticks (100 ns since 0001-01-01) → UTC epoch milliseconds. */
+export function ticksToEpochMs(value) {
+    const match = value.trim().match(/^\d+$/);
+    if (!match)
+        return undefined;
+    return Number((BigInt(match[0]) - 621355968000000000n) / 10000n);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericsanchezok/synergy-util",
-  "version": "3.0.20",
+  "version": "3.0.22",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -11,7 +11,8 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "bun test test/*.test.ts"
   },
   "files": [
     "dist"