@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
168 lines (150 loc) • 5.44 kB
text/typescript
/**
* Single-flight gate for CODEX_HOME storage mutations (cleanup, restore, policy).
*
* Manual cleanup, trash restore, and (Phase 3) policy-driven cleanup share one
* in-flight slot per resolved CODEX_HOME. A second caller receives
* `storage_mutation_busy` immediately — no per-operation queues.
*/
import { resolve } from "node:path";
import { resolveCodexHomeDir } from "../codex/home";
import { createAdmissionGate, type AdmissionLease, type AdmissionMetrics } from "../lib/admission";
export type StorageMutationKind = "cleanup" | "restore" | "policy";
export type StorageMutationBusyError = "storage_mutation_busy";
export interface StorageMutationCoordinatorTestHooks {
/** Block after acquiring the slot, before mutation work (race tests). */
blockMs?: number;
/** Test-only cross-thread handshake after one mutation kind acquires its slot. */
pauseAfterAcquire?: {
kind: StorageMutationKind;
readyPath: string;
releasePath: string;
};
}
interface ActiveSlot {
kind: StorageMutationKind;
startedAt: number;
lease: AdmissionLease;
}
export const MAX_ACTIVE_STORAGE_HOME_SLOTS = 32;
const slots = new Map<string, ActiveSlot>();
const slotGate = createAdmissionGate("storage_home_slots", MAX_ACTIVE_STORAGE_HOME_SLOTS);
let releaseMisses = 0;
let mutationEpoch = 0;
let testHooks: StorageMutationCoordinatorTestHooks | null = null;
/**
* Advances whenever a CODEX_HOME storage mutation finishes (coordinated cleanup, restore
* and policy runs on lease release; Log Guard maintenance through
* {@link noteStorageMutationCompleted}). An in-flight storage scan that started under an
* older epoch describes the tree before that mutation and must not answer a later read.
*/
export function storageMutationEpoch(): number {
return mutationEpoch;
}
/** Record a CODEX_HOME mutation that does not go through a coordinator slot. */
export function noteStorageMutationCompleted(): void {
mutationEpoch += 1;
}
function slotKey(codexHome?: string): string {
return resolve(codexHome ?? resolveCodexHomeDir());
}
export function setStorageMutationCoordinatorTestHooks(
hooks: StorageMutationCoordinatorTestHooks | null,
): void {
testHooks = hooks;
}
export function resetStorageMutationCoordinatorForTests(): void {
testHooks = null;
for (const slot of slots.values()) slot.lease.release();
slots.clear();
}
export function storageMutationAdmissionMetrics(): AdmissionMetrics {
const metrics = slotGate.metrics();
return { ...metrics, releaseMisses: metrics.releaseMisses + releaseMisses };
}
export function getActiveStorageMutation(
codexHome?: string,
): { kind: StorageMutationKind; startedAt: number } | null {
const active = slots.get(slotKey(codexHome));
return active ? { kind: active.kind, startedAt: active.startedAt } : null;
}
export function tryBeginStorageMutation(
kind: StorageMutationKind,
codexHome?: string,
): { acquired: true; lease: AdmissionLease } | { acquired: false; error: StorageMutationBusyError } {
const key = slotKey(codexHome);
if (slots.has(key)) {
return { acquired: false, error: "storage_mutation_busy" };
}
const lease = slotGate.tryAcquire();
if (!lease) return { acquired: false, error: "storage_mutation_busy" };
let active = true;
const ownerLease: AdmissionLease = {
release() {
if (!active) return;
active = false;
mutationEpoch += 1;
const owner = slots.get(key);
if (owner?.lease === ownerLease) slots.delete(key);
lease.release();
},
};
slots.set(key, { kind, startedAt: Date.now(), lease: ownerLease });
return { acquired: true, lease: ownerLease };
}
export function endStorageMutation(codexHome?: string): void {
const key = slotKey(codexHome);
const slot = slots.get(key);
if (!slot) {
releaseMisses += 1;
return;
}
slots.delete(key);
slot.lease.release();
}
async function applyCoordinatorBlock(kind: StorageMutationKind): Promise<void> {
const pause = testHooks?.pauseAfterAcquire;
if (pause?.kind === kind) {
await Bun.write(pause.readyPath, "ready\n");
while (!Bun.file(pause.releasePath).size) await Bun.sleep(10);
}
const blockMs = testHooks?.blockMs;
if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
await Bun.sleep(Math.floor(blockMs));
}
}
/**
* Phase 3 policy worker integration — wrap policy-driven cleanup FS/DB work.
* Returns `{ ok: false, error: 'storage_mutation_busy' }` when another mutation
* holds the CODEX_HOME slot.
*/
export async function runPolicyStorageMutation<T>(
codexHome: string | undefined,
work: () => T | Promise<T>,
): Promise<T | { ok: false; error: StorageMutationBusyError }> {
const gate = tryBeginStorageMutation("policy", codexHome);
if (!gate.acquired) {
return { ok: false, error: "storage_mutation_busy" };
}
try {
await applyCoordinatorBlock("policy");
return await work();
} finally {
gate.lease.release();
}
}
export async function withStorageMutationSlot<T>(
kind: StorageMutationKind,
codexHome: string | undefined,
work: () => T | Promise<T>,
): Promise<T | { ok: false; error: StorageMutationBusyError }> {
const gate = tryBeginStorageMutation(kind, codexHome);
if (!gate.acquired) {
return { ok: false, error: "storage_mutation_busy" };
}
try {
await applyCoordinatorBlock(kind);
return await work();
} finally {
gate.lease.release();
}
}