@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
175 lines (156 loc) • 7.63 kB
text/typescript
/**
* prompt-lock.ts — advisory cross-process lock for prompt-layer mutations.
*
* An in-process mutex only serialises browser tabs behind one service. A CLI
* invocation, a second service, or a stale process can all reach the same
* files, so the lock lives on disk.
*
* STALE TAKEOVER IS A RENAME, NOT AN UNLINK. Naive breaking is racy: A judges
* the lock stale, B removes it and acquires its own, then A unlinks *B's live
* lock* and both proceed. Unlinking a path you did not verify is the bug. Here
* the contender renames the observed stale lock to a token-quarantined name —
* a serialized operation under a short, unique per-process reservation. The
* reservation covers observation through creation: rename alone cannot stop
* an old observation from moving a successor's live lock.
*
* RELEASE ONLY DELETES A LOCK WHOSE TOKEN IS STILL OURS. A mismatch means we
* were superseded, and deleting it would hand the critical section to two
* writers at once.
*
* This does NOT cover Codex, which knows nothing about our lock. That residual
* is handled by the per-target byte checks in the write path, and the rename
* window itself is documented as irreducible from user space.
*/
import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { checkEntry, guarded, type Entry } from "./prompt-lock-evidence";
import { randomBytes } from "node:crypto";
import { UnsafeLockNamespace, withLockClaim } from "./prompt-lock-claim";
import { ownerDefaults, ownEvidence, ownerState, safeNamespace, type OwnerDeps, type OwnerEvidence } from "./prompt-lock-owner";
import { LockFileBusy, lockFileOperation } from "./prompt-lock-io";
const FILE_MODE = 0o600;
/** A lock younger than this is respected even if its pid looks gone. */
export const STALE_AFTER_MS = 10_000;
export interface LockRecord extends OwnerEvidence {
token: string;
pid: number;
acquiredAt: number;
}
export interface LockHandle {
path: string;
token: string;
}
export type AcquireResult =
| { ok: true; handle: LockHandle }
| { ok: false; error: "locked" }
| { ok: false; error: "unsafe"; detail: string };
export interface LockDeps extends Partial<OwnerDeps> {
isProcessAlive: (pid: number) => boolean | undefined;
now: () => number;
onClaimInitialized?: () => void;
}
const defaultDeps: LockDeps = { ...ownerDefaults, now: () => Date.now() };
function readRecord(path: string, platform: NodeJS.Platform): LockRecord | null {
try {
const parsed = JSON.parse(lockFileOperation(() => readFileSync(path, "utf8"), platform)) as LockRecord;
if (typeof parsed?.token !== "string" || typeof parsed?.pid !== "number") return null;
return parsed;
} catch (error) {
if (error instanceof LockFileBusy) throw error;
return null;
}
}
/** One attempt, including namespace validation and serialized stale observation. */
export function tryAcquire(path: string, deps: LockDeps = defaultDeps): AcquireResult {
const resolved = { ...ownerDefaults, ...deps };
const token = randomBytes(8).toString("hex");
try {
if (!safeNamespace(path, "file", resolved, true)) throw new UnsafeLockNamespace(path);
const reserved = withLockClaim(path, token, resolved,
() => acquireReserved(path, token, resolved), deps.onClaimInitialized);
return reserved.ok ? reserved.value : { ok: false, error: "locked" };
} catch (error) {
if (error instanceof LockFileBusy) return { ok: false, error: "locked" };
if (error instanceof UnsafeLockNamespace) return { ok: false, error: "unsafe", detail: error.path };
throw error;
}
}
function acquireReserved(path: string, token: string, deps: OwnerDeps & LockDeps): AcquireResult {
const parentPath = dirname(path);
if (!safeNamespace(parentPath, "directory", deps)) throw new UnsafeLockNamespace(parentPath);
const parents = [{ path: parentPath, stat: lockFileOperation(() => deps.lstat(parentPath), deps.platform) }];
const io = <R>(operation: () => R): R => guarded(parents, [], deps, operation);
const record: LockRecord = { token, ...ownEvidence(deps), acquiredAt: deps.now() };
const body = JSON.stringify(record);
try {
io(() => writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" }));
return { ok: true, handle: { path, token } };
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
}
const observed = io(() => {
const entry: Entry = { path, stat: deps.lstat(path), body: readFileSync(path, "utf8") };
checkEntry(entry, deps);
return entry;
});
let previous: LockRecord | null;
// Same shape gate as readRecord: a malformed record is evidence, never a takeover target.
try {
const parsed = JSON.parse(observed.body) as LockRecord;
previous = typeof parsed?.token === "string" && typeof parsed?.pid === "number" ? parsed : null;
} catch { previous = null; }
const state = ownerState(previous, deps);
if (state === "unsafe") return { ok: false, error: "unsafe", detail: path };
if (state !== "dead" || !previous || !Number.isFinite(previous.acquiredAt)
|| deps.now() - previous.acquiredAt <= STALE_AFTER_MS) return { ok: false, error: "locked" };
// The reservation excludes cooperating writers; fence external replacements
// and parent retargets again on every sharing-error retry.
const quarantine = `${path}.stale-${token}`;
try {
guarded(parents, [observed], deps, () => renameSync(path, quarantine));
} catch {
// Someone else won the rename, or the owner released between our checks.
// Either way we do NOT touch the path — retry from the top.
return { ok: false, error: "locked" };
}
const moved = { ...observed, path: quarantine };
const cleanup = () => {
try { guarded(parents, [moved], deps, () => unlinkSync(quarantine)); } catch { /* Preserve changed or busy debris. */ }
};
try {
io(() => writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" }));
} catch (error) {
// A successor acquired the real lock between our rename and this create.
// Its lock is live and is not ours to remove.
cleanup();
if ((error as NodeJS.ErrnoException).code === "EEXIST") return { ok: false, error: "locked" };
throw error;
}
cleanup();
return { ok: true, handle: { path, token } };
}
/**
* Release. Deletes nothing unless the on-disk token is still ours; returns false
* when we were superseded, which the caller surfaces as `write_superseded`.
*/
export function release(handle: LockHandle): boolean {
try {
const deps = ownerDefaults;
if (!safeNamespace(handle.path, "file", deps) || !safeNamespace(dirname(handle.path), "directory", deps)) return false;
const parents = [{ path: dirname(handle.path), stat: lockFileOperation(() => deps.lstat(dirname(handle.path)), deps.platform) }];
const entry = guarded(parents, [], deps, () => {
const saved = { path: handle.path, stat: deps.lstat(handle.path), body: readFileSync(handle.path, "utf8") };
checkEntry(saved, deps);
return saved;
});
if (JSON.parse(entry.body)?.token !== handle.token) return false;
return guarded(parents, [entry], deps, () => { unlinkSync(handle.path); return true; });
} catch { return false; }
}
/** True when the on-disk lock is still the one this handle acquired. */
export function stillHeld(handle: LockHandle): boolean {
try {
return safeNamespace(handle.path, "file", ownerDefaults)
&& readRecord(handle.path, ownerDefaults.platform)?.token === handle.token;
} catch { return false; }
}