@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
404 lines (369 loc) • 16 kB
text/typescript
/** Process-lifetime single-writer ownership for the shared spend journal. */
import { Database } from "bun:sqlite";
import { chmodSync, lstatSync, mkdirSync, realpathSync } from "node:fs";
import { join, resolve } from "node:path";
import { getConfigDir } from "../config/paths";
import { recordOwnedConfigPath } from "./config-ownership";
import { assertPrivateSqliteSidecars, preparePrivateSqliteDatabase } from "./private-sqlite-path";
import { assertNotRealHomeUnderTest } from "./test-home-guard";
import { hardenSecretDir, hardenSecretPath } from "./windows-secret-acl";
export const SPEND_LEDGER_OWNER_FILENAME = "spend-ledger-owner.sqlite";
export const SPEND_LEDGER_RESTART_PARENT_ENV = "OCX_SPEND_LEDGER_RESTART_PARENT_PID";
export const SPEND_LEDGER_RESTART_WAIT_MS = 5_000;
const OWNER_SIDECARS = ["-journal", "-wal", "-shm"] as const;
export type SpendLedgerOwnerErrorCode =
| "SPEND_LEDGER_OWNER_BUSY"
| "SPEND_LEDGER_OWNER_UNAVAILABLE"
| "SPEND_LEDGER_OWNER_HOME_CONFLICT"
| "SPEND_LEDGER_OWNER_NOT_HELD";
export class SpendLedgerOwnerError extends Error {
constructor(readonly code: SpendLedgerOwnerErrorCode, message: string, options?: ErrorOptions) {
super(message, options);
this.name = "SpendLedgerOwnerError";
}
}
export interface SpendLedgerOwnerLease {
release(): void;
}
interface ActiveOwner {
readonly home: string;
readonly database: Database;
references: number;
}
let activeOwner: ActiveOwner | null = null;
let boundLedgerHome: string | null = null;
/**
* Identity of the current ownership, not just of the home it covers.
*
* A home name alone cannot tell "still the lease I was built under" from "the same directory,
* owned again since". A ledger that only checked the home therefore came back to life across a
* release and a reacquire, writing totals it had accumulated before another writer owned the
* journal. Every acquisition that actually takes the lock mints a new value.
*/
let ownerGeneration = 0;
const releaseHooks: Array<() => void> = [];
const acquiredHooks: Array<(home: string) => void> = [];
/** Run once after each new ownership generation is acquired. */
export function onSpendLedgerOwnerAcquired(hook: (home: string) => void): void {
acquiredHooks.push(hook);
}
const releasingHooks: Array<() => void> = [];
let releasing = false;
/** Run before the final lease is released, while existing storage tokens remain valid. */
export function onSpendLedgerOwnerReleasing(hook: () => void): void {
releasingHooks.push(hook);
}
function assertNotReleasing(): void {
if (releasing) throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
);
}
/**
* Run when the last lease on a state directory goes away.
*
* The ledger singleton is bound to the home it was built for, so it has to go when ownership
* does; otherwise a process that starts a second server against a different state directory
* either writes the old home's journal or is refused for a conflict it no longer has. The
* journal on disk is the durable record and construction replays it, so nothing is lost.
*/
export function onSpendLedgerOwnerReleased(hook: () => void): void {
releaseHooks.push(hook);
}
function errorCode(error: unknown): unknown {
return error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
}
function assertPrivateFile(path: string): void {
const stat = lstatSync(path);
if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger ownership could not be established safely.",
);
}
if (process.platform !== "win32" && stat.uid !== process.getuid!()) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger ownership could not be established safely.",
);
}
}
function prepareOwnerPath(configDir: string): { home: string; path: string } {
const requested = resolve(configDir);
// First statement before mutation: tests must never acquire against the real user home.
assertNotRealHomeUnderTest(requested);
mkdirSync(requested, { recursive: true, mode: 0o700 });
const home = realpathSync.native(requested);
if (process.platform !== "win32") chmodSync(home, 0o700);
hardenSecretDir(home, { required: true });
const path = join(home, SPEND_LEDGER_OWNER_FILENAME);
// Registered while the directory is still EMPTY. Config ownership refuses to claim a
// directory that already has contents, so creating the database first meant a fresh home
// never got an ownership marker at all: the manifest was never written, and the database and
// its sidecars were left behind by a later uninstall because nothing recorded them.
recordOwnedConfigPath(home, path);
for (const suffix of OWNER_SIDECARS) recordOwnedConfigPath(home, `${path}${suffix}`);
// Refuses a link or reparse point at the database or a sidecar before anything is created:
// Windows creates a new file through a link at its name.
preparePrivateSqliteDatabase(path);
assertPrivateFile(path);
if (process.platform !== "win32") chmodSync(path, 0o600);
hardenSecretPath(path, { required: true });
assertPrivateFile(path);
return { home: process.platform === "win32" ? home.toLowerCase() : home, path };
}
function isBusy(error: unknown): boolean {
const code = errorCode(error);
const message = error instanceof Error ? error.message : "";
return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
|| /database (?:is|table is) locked/i.test(message);
}
function stateDirectoryIdentity(configDir: string): string {
const requested = resolve(configDir);
assertNotRealHomeUnderTest(requested);
let canonical = requested;
try { canonical = realpathSync.native(requested); } catch { /* acquisition owns creation */ }
return process.platform === "win32" ? canonical.toLowerCase() : canonical;
}
function restartHandoffWaitMs(): number {
const markedParent = process.env[SPEND_LEDGER_RESTART_PARENT_ENV];
delete process.env[SPEND_LEDGER_RESTART_PARENT_ENV];
return markedParent === String(process.ppid) ? SPEND_LEDGER_RESTART_WAIT_MS : 0;
}
/** Mark only a parent-exit restart child for bounded lease acquisition. */
export function spendLedgerRestartEnvironment(
source: NodeJS.ProcessEnv,
parentPid?: number,
): NodeJS.ProcessEnv {
const env = { ...source };
if (parentPid === undefined) delete env[SPEND_LEDGER_RESTART_PARENT_ENV];
else env[SPEND_LEDGER_RESTART_PARENT_ENV] = String(parentPid);
return env;
}
/**
* Hold one SQLite write transaction until the final in-process reference releases it.
* SQLite and the OS release a crashed process; no PID, timestamp, TTL or lock-file unlink
* can evict a live owner or mistake a reused process identity for this lease.
*/
export function acquireSpendLedgerOwner(configDir = getConfigDir()): SpendLedgerOwnerLease {
assertNotReleasing();
const requestedHome = stateDirectoryIdentity(configDir);
const busyTimeout = restartHandoffWaitMs();
if (boundLedgerHome !== null && boundLedgerHome !== requestedHome) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_HOME_CONFLICT",
"This process already owns the spend ledger for a different state directory.",
);
}
if (activeOwner) {
if (activeOwner.home !== requestedHome) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_HOME_CONFLICT",
"This process already owns the spend ledger for a different state directory.",
);
}
activeOwner.references += 1;
return leaseFor(activeOwner);
}
let prepared: { home: string; path: string };
try {
prepared = prepareOwnerPath(configDir);
} catch (cause) {
if (cause instanceof SpendLedgerOwnerError) throw cause;
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger ownership could not be established safely.",
{ cause },
);
}
let database: Database | undefined;
try {
assertPrivateSqliteSidecars(prepared.path);
database = new Database(prepared.path, { create: true });
database.exec(`PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = ${busyTimeout}; BEGIN IMMEDIATE`);
} catch (cause) {
try { database?.close(); } catch { /* preserve acquisition failure */ }
if (isBusy(cause)) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_BUSY",
"Another OpenCodex process already owns this spend ledger. Use a separate OPENCODEX_HOME for an independent instance.",
);
}
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger ownership could not be established safely.",
{ cause },
);
}
activeOwner = { home: prepared.home, database, references: 1 };
ownerGeneration += 1;
const owner = activeOwner;
for (const hook of acquiredHooks) {
try { hook(owner.home); } catch { /* one hook must not prevent acquisition */ }
}
return leaseFor(owner);
}
function leaseFor(owner: ActiveOwner): SpendLedgerOwnerLease {
let released = false;
return Object.freeze({
release(): void {
if (released) return;
released = true;
if (activeOwner !== owner || owner.references < 1) return;
if (owner.references === 1) {
releasing = true;
try {
for (const hook of releasingHooks) {
try { hook(); } catch { /* a flush hook must not prevent release */ }
}
} finally {
releasing = false;
}
}
owner.references -= 1;
if (owner.references > 0) return;
activeOwner = null;
boundLedgerHome = null;
for (const hook of releaseHooks) {
try { hook(); } catch { /* a discard hook must not mask a release failure */ }
}
let failure: unknown;
try { owner.database.exec("ROLLBACK"); } catch (error) { failure = error; }
try { owner.database.close(); } catch (error) { failure ??= error; }
if (failure !== undefined) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger ownership could not be released cleanly.",
{ cause: failure },
);
}
},
});
}
/** The ownership a ledger was built under, to be handed back on every later use. */
export function currentSpendLedgerOwnerGeneration(): number {
return ownerGeneration;
}
/**
* Permission to touch one file under the owned state directory, for as long as this exact
* ownership lasts.
*
* A callback supplied by the caller cannot be this proof: the caller can pass one that does
* nothing, which is how a "required guard" still allowed an unowned write. A marker carried ON
* the object is not proof either, because an object spread copies it: `{ ...minted, path:
* elsewhere, assert() {} }` would look minted while pointing somewhere else. So the token
* carries nothing. The path and the ownership it was minted under live in a table only this
* module can read, keyed by the token's identity, and a copy is simply not that key.
*/
export interface SpendLedgerStorage {
readonly __spendLedgerStorage: unique symbol;
}
const mintedStorage = new WeakMap<object, { readonly path: string; readonly generation: number; readonly home: string }>();
function trustedStorage(storage: SpendLedgerStorage): { readonly path: string; readonly generation: number; readonly home: string } {
const entry = typeof storage === "object" && storage !== null ? mintedStorage.get(storage) : undefined;
if (!entry) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
);
}
return entry;
}
/**
* Mint storage permission for one file name directly under the owned state directory.
*
* The name is a file name, never a path: joining a caller-supplied path would let the caller
* choose the destination, which is the thing ownership is supposed to decide.
*/
export function mintSpendLedgerStorage(fileName: string): SpendLedgerStorage {
assertNotReleasing();
if (fileName.includes("/") || fileName.includes("\\") || fileName === "." || fileName === "..") {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_UNAVAILABLE",
"Spend-ledger storage could not be established safely.",
);
}
assertSpendLedgerOwnerHeld();
const owner = activeOwner;
if (!owner) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
);
}
const generation = ownerGeneration;
const home = owner.home;
// The token is deliberately empty: everything trustworthy about it is held here, under its
// identity, where a spread cannot reach.
const token = Object.freeze({}) as unknown as SpendLedgerStorage;
mintedStorage.set(token, { path: join(home, fileName), generation, home });
return token;
}
/** The file this token stands for, as this module recorded it at mint time. */
export function spendLedgerStoragePath(storage: SpendLedgerStorage): string {
return trustedStorage(storage).path;
}
/**
* Refuse unless this exact token was minted here and its ownership is still current.
*
* Both halves matter: identity rules out a copy or a look-alike, and the generation rules out a
* token minted before the lock was dropped and taken again.
*/
export function assertStorageOwned(storage: SpendLedgerStorage): void {
const entry = trustedStorage(storage);
assertSpendLedgerOwnerGeneration(entry.generation, entry.home);
}
/**
* Refuse a handle built under an ownership that has since ended.
*
* The state directory may be the same one; what matters is that the lock was dropped and taken
* again in between, because another process could have written the journal while it was free.
*/
export function assertSpendLedgerOwnerGeneration(generation: number, configDir = getConfigDir()): void {
assertSpendLedgerOwnerHeld(configDir);
if (generation !== ownerGeneration) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
);
}
}
/** The singleton journal may be touched only while its matching state directory is owned. */
export function assertSpendLedgerOwnerHeld(configDir = getConfigDir()): void {
let home: string;
try {
const canonical = realpathSync.native(resolve(configDir));
home = process.platform === "win32" ? canonical.toLowerCase() : canonical;
} catch (cause) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
{ cause },
);
}
if (!activeOwner || activeOwner.home !== home || activeOwner.references < 1) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_NOT_HELD",
"Spend-ledger ownership is required before the shared ledger can be used.",
);
}
}
/** Permanently bind the live process-wide singleton to its first constructed home. */
export function bindSpendLedgerOwnerHome(configDir = getConfigDir()): void {
assertSpendLedgerOwnerHeld(configDir);
const home = stateDirectoryIdentity(configDir);
if (boundLedgerHome !== null && boundLedgerHome !== home) {
throw new SpendLedgerOwnerError(
"SPEND_LEDGER_OWNER_HOME_CONFLICT",
"This process already owns the spend ledger for a different state directory.",
);
}
boundLedgerHome = home;
}
export function spendLedgerOwnerSnapshot(): { readonly ownership: "held" | "unheld" } {
return { ownership: activeOwner ? "held" : "unheld" };
}
/** Test seam paired with discarding the process-wide ledger singleton. */
export function resetSpendLedgerOwnerBindingForTest(): void {
boundLedgerHome = null;
}