UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

431 lines (422 loc) • 23 kB
/** * config-write-lock.ts — one advisory lock for every opencodex-originated * `config.toml` write. * * Why a second lock next to the existing two: the injector's SQLite lock N * serializes injection against injection, and the prompt-layers lock serializes * prompt edits against prompt edits. Neither covers the writers BETWEEN them — * the feature scalars in `features.ts`, the `ocx restore`/`removeCodexConfig` * transforms, and the journal replay each did their own unlocked read → edit → * `atomicWriteFile`. Each write is individually atomic, but a foreign rewrite * landing between any writer's read and its rename was silently discarded: * a features edit could drop an injection's freshly-written routing keys, a * remove could drop a prompt projection committed a millisecond earlier. * * This lock closes that class at its source rather than per call site: every * opencodex writer reads `config.toml` and renames over it while holding * `<config>.ocx-write.lock`, so no cooperating writer can be computed against * stale bytes and none can land mid-section. * * What it deliberately does NOT cover: * - Codex itself knows nothing about the file; upstream's own rewrites cannot * be serialized from here. That residual is why the injector's witness and * the drift healer still exist. * - Lock ordering: prompt-layers commit() takes the prompt store lock first, * then this one; the injector takes this one first, then N, then C — and the * coordinated restore path follows that same file-first order * (`restoreNativeCodexAsyncImpl` acquires this lock before its `withCodexWriteLock` * journal replay), so no cross-lock inversion remains. Synchronous * acquisition fails fast; asynchronous acquisition has a bounded wait. * - The injector's held section contains awaits (`withCodexWriteLock` is * async), so the lock must NOT be implicitly reentrant — a same-process * writer that slipped inside on a process-global check would interleave * mid-section. Reentrancy is explicit instead: a caller that already holds * the file passes its handle (`heldConfigWriteLock`) to the writer it * calls. * - Acquisition is a single attempt for synchronous writers: the section under * this lock is a handful of file operations, so a busy result means the * caller reports "locked" and the operator retries — the same contract the * prompt store lock already exposes. Async callers (the injector) use the * bounded wait in `acquireConfigWriteLock`. */ import { atomicWriteFileStreamed, type AtomicWriteHooks } from "../config/atomic-write"; import { lstatSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs"; import { createHash, randomUUID } from "node:crypto"; import { basename, dirname, join, resolve } from "node:path"; import { release, stillHeld, tryAcquire, type AcquireResult, type LockHandle } from "./prompt-lock"; interface Destination { canonical: string; inode: string | null } const destinations = new WeakMap<LockHandle, Destination>(); interface ConfigWriteRecovery { canonical: string; preimage: Buffer | null; identity: string | null; refreshBeforeSpawn: boolean; } const recoveries = new WeakMap<LockHandle, ConfigWriteRecovery>(); export class ConfigWriteParentMissing extends Error { constructor(readonly path: string) { super(`Codex configuration parent is missing or unresolved at ${path}`); } } type ConfigWriteAcquireResult = AcquireResult | { ok: false; error: "missing-parent"; detail: string }; function destination(path: string): Destination { const absolute = resolve(path); let canonical: string; try { canonical = realpathSync.native(absolute); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; try { canonical = join(realpathSync.native(dirname(absolute)), basename(absolute)); } catch (parentError) { if ((parentError as NodeJS.ErrnoException).code === "ENOENT") throw new ConfigWriteParentMissing(dirname(absolute)); throw parentError; } } try { const stat = statSync(canonical, { bigint: true }); return { canonical, inode: `${stat.dev}:${stat.ino}` }; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return { canonical, inode: null }; } } /** Symlink aliases share the lock beside their canonical write destination. */ export function configWriteLockPath(configPath: string): string { return `${destination(configPath).canonical}.ocx-write.lock`; } export const CONFIG_WRITE_LOCKED_MESSAGE = "another opencodex process is writing Codex configuration — retry shortly"; export type ConfigWriteLockOutcome<T> = | { ok: true; value: T } | Exclude<ConfigWriteAcquireResult, { ok: true }>; function acquire(configPath: string): ConfigWriteAcquireResult { let target: Destination; try { target = destination(configPath); } catch (error) { if (error instanceof ConfigWriteParentMissing) return { ok: false, error: "missing-parent", detail: error.path }; throw error; } const acquired = tryAcquire(`${target.canonical}.ocx-write.lock`); if (!acquired.ok) return acquired; try { // A preceding writer may atomically replace the file before releasing the lock. // Capture the inode only after acquisition, while retaining the canonical-path gate. const current = destination(configPath); if (current.canonical !== target.canonical || !stillHeld(acquired.handle)) { release(acquired.handle); return { ok: false, error: "unsafe", detail: acquired.handle.path }; } // Preserve caller-owned unreadable/non-regular errors, but do not mistake a // dangling link (realpath's fallback) or a fresh replacement for proven absence. try { const entry = lstatSync(current.canonical, { bigint: true }); if (entry.isSymbolicLink() || `${entry.dev}:${entry.ino}` !== current.inode) throw new ConfigWriteDestinationChanged(); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT" || current.inode !== null) throw error; } destinations.set(acquired.handle, current); return acquired; } catch (error) { release(acquired.handle); throw error; } } export function withConfigWriteLock<T>(configPath: string, run: (handle: LockHandle) => T): ConfigWriteLockOutcome<T> { const acquired = acquire(configPath); if (!acquired.ok) return acquired; try { return { ok: true, value: run(acquired.handle) }; } finally { release(acquired.handle); } } export function configWriteLockHeld(handle: LockHandle): boolean { return stillHeld(handle); } export function releaseConfigWriteLock(handle: LockHandle): void { release(handle); } export type { LockHandle }; export function assertConfigWriteDestination(configPath: string, held: LockHandle): string { const current = destination(configPath); const expected = destinations.get(held); if (!stillHeld(held) || held.path !== `${current.canonical}.ocx-write.lock` || (expected && (current.canonical !== expected.canonical || current.inode !== expected.inode))) { throw new Error("Codex configuration destination changed; files and recovery evidence were preserved."); } if (!expected) destinations.set(held, current); return current.canonical; } /** A writer advances the witness only through its confirmed publication hook. */ export function publishConfigWrite<T>(configPath: string, held: LockHandle, run: (destination: string, hooks: AtomicWriteHooks) => T): T { const canonical = assertConfigWriteDestination(configPath, held); return run(canonical, { validateBeforeRename: () => { assertConfigWriteDestination(configPath, held); }, afterRename: () => { const payloadKnown = payloadDigestPending.delete(held); const recovery = recoveries.get(held); if (recovery?.canonical === canonical) recovery.identity = canonicalFileIdentity(canonical); const after = destination(configPath); if (!stillHeld(held) || after.canonical !== canonical) throw new Error("Codex configuration destination changed; recovery evidence was preserved."); destinations.set(held, after); // A payload-aware publisher records the digest of what it wrote; this re-read only // covers writers whose bytes this process never sees (a native child, the empty file). // Known limit for a native child: the `codex` CLI renames its own file and exits, and this // re-read runs after it exits, so a write by a non-OpenCodex process (the Codex app, an // editor) landing between the child's rename and this line is recorded as OpenCodex's and a // later compensation in the same section could revert it. The child cannot report its bytes. if (!payloadKnown) publishedConfigDigests.set(held, fileDigest(canonical)); const watched = targets.get(held); if (watched) for (const [path, expected] of watched) if (expected.canonical === canonical) watched.set(path, after); }, }); } /** config.toml no longer holds the bytes a writer decided from; nothing was written. */ export class ConfigWriteContentChanged extends Error { readonly retryable = true; constructor() { super("Codex config.toml changed while OpenCodex was writing it; nothing was overwritten. Retry the command."); } } /** * The digest of the config.toml bytes this lock section last published, `null` for a removal, * `undefined` when it published none. Compensation reverts only a file still holding them. */ const publishedConfigDigests = new WeakMap<LockHandle, string | null>(); const payloadDigestPending = new WeakSet<LockHandle>(); export function publishedConfigDigest(held: LockHandle): string | null | undefined { return publishedConfigDigests.get(held); } /** Called by a publisher that knows its payload, before the rename's afterRename hook runs. */ export function recordPublishedConfigDigest(held: LockHandle, digest: string | null): void { publishedConfigDigests.set(held, digest); payloadDigestPending.add(held); } export function configDigest(bytes: string | null): string | null { return bytes === null ? null : createHash("sha256").update(bytes).digest("hex"); } function fileDigest(path: string): string | null { try { return createHash("sha256").update(readFileSync(path)).digest("hex"); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; } } /** Native children use the acquisition witness, never a fresh home resolution. */ export class ConfigWriteDestinationChanged extends Error { readonly retryable = false; constructor(message = "Codex configuration destination changed; files and recovery evidence were preserved.") { super(message); } } /** Refuse before transition staging: native Codex always writes home/config.toml. */ export function assertNativeConfigWriteDestination(configPath: string, held: LockHandle): string { let canonical: string; try { canonical = assertConfigWriteDestination(configPath, held); } catch { throw new ConfigWriteDestinationChanged(); } const home = realpathSync.native(dirname(canonical)); if (basename(canonical) !== "config.toml" || canonical !== join(home, "config.toml")) { throw new ConfigWriteDestinationChanged("Native feature changes are unavailable when config.toml is a symlink to a differently named file."); } return canonical; } function canonicalFileIdentity(canonical: string): string | null { const current = destination(canonical); if (current.canonical !== canonical) throw new Error("canonical configuration target was redirected"); let stat; try { stat = lstatSync(canonical, { bigint: true }); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" && current.inode === null) return null; throw error; } if (!stat.isFile() || `${stat.dev}:${stat.ino}` !== current.inode) throw new Error("canonical configuration target is not the observed regular file"); return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`; } /** Capture before the first write; nested native children share the same recovery scope. */ export function withConfigWriteRecovery<T>( configPath: string, held: LockHandle, run: () => T, options: { refreshBeforeSpawn?: boolean; preimage?: Buffer; requireMatchingPreimage?: boolean } = {}, ): T { const nested = recoveries.get(held); if (nested && !options.requireMatchingPreimage) return run(); let canonical: string; try { canonical = assertConfigWriteDestination(configPath, held); } catch { throw new ConfigWriteDestinationChanged(); } const identity = canonicalFileIdentity(canonical); const preimage = identity === null ? null : readFileSync(canonical); if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged(); if (options.requireMatchingPreimage && (!options.preimage || !preimage?.equals(options.preimage))) { throw new ConfigWriteDestinationChanged(); } if (nested && (nested.canonical !== canonical || nested.identity !== identity)) throw new ConfigWriteDestinationChanged(); if (nested) return run(); const recovery: ConfigWriteRecovery = { canonical, identity, preimage: options.preimage ?? preimage, refreshBeforeSpawn: options.refreshBeforeSpawn === true && options.preimage === undefined, }; recoveries.set(held, recovery); try { const value = run(); assertConfigWriteDestination(configPath, held); return value; } catch (error) { // Refused before this scope published anything: there is nothing to recover. if (error instanceof ConfigWriteContentChanged && recovery.identity === identity) throw error; let changed = error instanceof ConfigWriteDestinationChanged; try { assertConfigWriteDestination(configPath, held); } catch { changed = true; } try { const validateRecovery = (targetPath = canonical) => { if (targetPath !== canonical || !stillHeld(held) || held.path !== `${canonical}.ocx-write.lock` || canonicalFileIdentity(canonical) !== recovery.identity) { throw new Error("canonical configuration target changed before recovery"); } }; validateRecovery(); // A pre-write refusal leaves the original entry intact, including its inode. const unchanged = recovery.identity === identity && (recovery.preimage === preimage || (recovery.preimage !== null && preimage !== null && recovery.preimage.equals(preimage))); if (!unchanged) { if (recovery.preimage === null) { validateRecovery(); if (recovery.identity !== null) unlinkSync(canonical); } else atomicWriteFileStreamed(canonical, fd => writeFileSync(fd, recovery.preimage!), { validateBeforeRename: validateRecovery }); } destinations.set(held, destination(canonical)); } catch (recoveryError) { let evidence = "recovery evidence could not be persisted"; try { const recoveryPath = `${canonical}.ocx-native-preimage.${randomUUID()}`; atomicWriteFileStreamed(recoveryPath, fd => writeFileSync(fd, recovery.preimage ?? Buffer.from('{"preimage":"absent"}\n'))); evidence = `recovery evidence retained at ${recoveryPath}`; } catch { /* Preserve the refusal and diagnostic even when evidence storage fails. */ } throw new ConfigWriteDestinationChanged(`Codex configuration destination changed; canonical preimage recovery refused: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}; ${evidence}.`); } if (changed) throw new ConfigWriteDestinationChanged(`${error instanceof Error ? error.message : String(error)}; canonical preimage restored and recovery evidence preserved.`); throw error; } finally { recoveries.delete(held); } } export function runConfigWriteChild( configPath: string, held: LockHandle, run: (env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void) => void, transitionPreimage?: Buffer, ): void { withConfigWriteRecovery(configPath, held, () => { const canonical = assertNativeConfigWriteDestination(configPath, held); const recovery = recoveries.get(held)!; let readyToSpawn = false; const validateBeforeSpawn = () => { readyToSpawn = false; assertNativeConfigWriteDestination(configPath, held); const identity = canonicalFileIdentity(canonical); const bytes = identity === null ? null : readFileSync(canonical); if (canonicalFileIdentity(canonical) !== identity) throw new ConfigWriteDestinationChanged(); if (recovery.refreshBeforeSpawn) { recovery.preimage = bytes; recovery.identity = identity; } readyToSpawn = true; }; publishConfigWrite(configPath, held, (_canonical, hooks) => { const env = { ...process.env }; // Windows env names are case-insensitive; wrappers may honor Orca's override. for (const key of Object.keys(env)) { if (["CODEX_HOME", "ORCA_CODEX_HOME"].includes(key.toUpperCase())) delete env[key]; } env.CODEX_HOME = realpathSync.native(dirname(canonical)); validateBeforeSpawn(); try { run(env, validateBeforeSpawn); } // Even a failed child can replace config.toml. Observe only after it entered. finally { try { if (readyToSpawn) hooks.afterRename?.(canonical); } catch { throw new ConfigWriteDestinationChanged(); } } }); }, { refreshBeforeSpawn: true, preimage: transitionPreimage }); } export function withConfigWriteLockHeld<T>( configPath: string, held: LockHandle | undefined, run: (handle: LockHandle) => T, ): ConfigWriteLockOutcome<T> { if (held !== undefined) { try { assertConfigWriteDestination(configPath, held); } catch { return { ok: false, error: "unsafe", detail: held.path }; } return { ok: true, value: run(held) }; } return withConfigWriteLock(configPath, run); } const RETRY_MIN_MS = 25; const RETRY_MAX_MS = 75; export const CONFIG_WRITE_LOCK_WAIT_MS = 2_000; export async function acquireConfigWriteLock( configPath: string, options: { timeoutMs?: number; nowMs?: () => number; sleep?: (ms: number) => Promise<void> } = {}, ): Promise<ConfigWriteAcquireResult> { const timeoutMs = options.timeoutMs ?? CONFIG_WRITE_LOCK_WAIT_MS; if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 10_000) throw new RangeError("Invalid config lock timeout"); const now = options.nowMs ?? (() => performance.now()); const sleep = options.sleep ?? (ms => new Promise(done => setTimeout(done, ms))); const deadline = now() + timeoutMs; for (;;) { const acquired = acquire(configPath); if (acquired.ok || acquired.error !== "locked") return acquired; const remaining = deadline - now(); if (timeoutMs === 0 || remaining <= 0) return { ok: false, error: "locked" }; await sleep(Math.max(1, Math.min(remaining, RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS + 1))))); } } const targets = new WeakMap<LockHandle, Map<string, Destination>>(); export function watchConfigWriteTargets(held: LockHandle, paths: readonly string[]): void { let watched = targets.get(held); if (!watched) { watched = new Map(); targets.set(held, watched); } for (const path of paths) if (!watched.has(path)) watched.set(path, destination(path)); } export function publishConfigWriteTarget<T>( configPath: string, held: LockHandle, path: string, run: (destination: string, hooks: AtomicWriteHooks) => T, ): T { assertConfigWriteDestination(configPath, held); watchConfigWriteTargets(held, [path]); const watched = targets.get(held)!, expected = watched.get(path)!, current = destination(path); if (expected.canonical !== current.canonical || expected.inode !== current.inode) { throw new Error("Codex artifact destination changed; files and recovery evidence were preserved."); } if (path === configPath) { const value = publishConfigWrite(configPath, held, run); return value; } return run(current.canonical, { validateBeforeRename: () => { assertConfigWriteDestination(configPath, held); const now = destination(path); if (expected.canonical !== now.canonical || expected.inode !== now.inode) throw new Error("Codex artifact destination changed; files and recovery evidence were preserved."); }, afterRename: () => { assertConfigWriteDestination(configPath, held); const after = destination(path); if (after.canonical !== current.canonical) throw new Error("Codex artifact destination changed; recovery evidence was preserved."); watched.set(path, after); }, }); } export function removeConfigWriteEntry(configPath: string, held: LockHandle, path: string): void { assertConfigWriteDestination(configPath, held); watchConfigWriteTargets(held, [path]); const watched = targets.get(held)!; const expected = watched.get(path)!; const current = destination(path); if (expected.canonical !== current.canonical || expected.inode !== current.inode || current.canonical !== join(realpathSync.native(dirname(resolve(path))), basename(resolve(path)))) { throw new Error("Codex artifact destination changed; files and recovery evidence were preserved."); } if (expected.inode === null) return; const entry = join(realpathSync.native(dirname(resolve(path))), basename(resolve(path))); const identity = (file: { dev: bigint; ino: bigint }) => `${file.dev}:${file.ino}`; const before = lstatSync(entry, { bigint: true }); if (before.isSymbolicLink() || !before.isFile() || identity(before) !== expected.inode) { throw new Error("Codex artifact destination changed; files and recovery evidence were preserved."); } assertConfigWriteDestination(configPath, held); const now = lstatSync(entry, { bigint: true }); if (now.isSymbolicLink() || !now.isFile() || identity(now) !== expected.inode) { throw new Error("Codex artifact destination changed; files and recovery evidence were preserved."); } unlinkSync(entry); assertConfigWriteDestination(configPath, held); const after = destination(path); if (after.inode !== null || after.canonical !== expected.canonical) { throw new Error("Codex artifact destination changed; recovery evidence was preserved."); } watched.set(path, after); } export function configWriteLockFailureMessage(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>): string { if (failure.error === "missing-parent") return `Codex configuration parent is missing or unresolved at ${failure.detail}; no files were changed.`; return failure.error === "unsafe" ? `Unsafe Codex configuration lock at ${failure.detail}; deliberate removal is required. Files and recovery evidence were preserved.` : CONFIG_WRITE_LOCKED_MESSAGE; } export class ConfigWriteLockRefusal extends Error { readonly retryable: boolean; constructor(failure: Exclude<ConfigWriteAcquireResult, { ok: true }>) { super(configWriteLockFailureMessage(failure)); this.retryable = failure.error === "locked"; } }