UNPKG

@bitkyc08/opencodex

Version:

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

397 lines (375 loc) • 18.7 kB
/** * Default-on periodic catalog refresh so newly released models appear without a * manual `ocx sync` (issue #3630). * * This is load-bearing, not a convenience. The served model set is otherwise * only rewritten by an explicit sync, a management mutation, or startup * convergence, so an overnight provider release stays invisible until someone * happens to run one of those. The overnight case is the whole reason the * scheduler exists. * * Shape follows src/quota/reset-poller.ts: a module-singleton unref'd interval * whose config gate lives in the callee, so toggling `enabled` or changing the * cadence takes effect on the next tick without a restart (the rationale * spelled out at src/oauth/token-guardian.ts:276). Importing this module at * startup must cost nothing — src/server/background-lifecycle.ts loads it * statically — so the config barrel, the admission snapshot, and the * convergence funnel are all dynamic import()s inside the tick. */ /** * Keep these numeric literals aligned with CATALOG_AUTO_REFRESH_* in src/config.ts. * They cannot be imported from there: this module is a static edge from * background-lifecycle, and the config barrel is a heavy import reserved for the tick. */ const DEFAULT_INTERVAL_MS = 60 * 60_000; const MIN_INTERVAL_MS = 15 * 60_000; const INITIAL_DELAY_MS = 3 * 60_000; /** * Commit-lock wait only. Gather already has per-provider timeouts, and automatic * callers fail fast and defer (ConvergeRequest.mode) rather than holding the * write lock across a slow tick. */ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs"; import type { OcxConfig } from "../types"; const TICK_DEADLINE_MS = 1_000; const MAX_JOURNAL_BYTES = 1024 * 1024; const MAX_CATALOG_BYTES = 64 * 1024 * 1024; let timer: ReturnType<typeof setInterval> | null = null; let initialTimer: ReturnType<typeof setTimeout> | null = null; let detachShutdownHook: (() => void) | null = null; /** The bounded cadence the live timer was created with, so a tick can notice config drift. */ let liveIntervalMs: number | null = null; /** * Bumped by every start and stop. A tick captures it on entry and re-checks before publishing, * so a converge still in flight when the timer stops cannot publish into the next generation. */ let generation = 0; /** Keys the last drift heal found missing, and whether this process already warned about one. */ let lastHealMissingKeys: readonly string[] = []; let healReported = false; /** setInterval does not skip a firing while the previous callback is still awaiting. */ let inFlight = false; /** Refreshes already-connected clients after a changed catalog; owned by the server lifecycle. */ export type CatalogChangedClientFanout = (isCurrent: () => boolean) => Promise<ReadonlyArray<{ readonly ok: boolean }>>; let clientFanout: CatalogChangedClientFanout | null = null; export function setCatalogAutoRefreshClientFanout(fanout: CatalogChangedClientFanout | null): void { clientFanout = fanout; } /** * Notified after a tick committed a changed catalog. Owned by the link Child-ops scheduler, which registers only while * this Home has links, so a Home without links pays one null check. Synchronous and fire-and-forget: the scheduler * debounces and does its own work later. */ export type CatalogChangedLinkFanout = () => void; let linkFanout: CatalogChangedLinkFanout | null = null; export function setCatalogAutoRefreshLinkFanout(fanout: CatalogChangedLinkFanout | null): void { linkFanout = fanout; } /** Read only a regular file, with a byte limit even if it grows after the stat. */ function readBoundedRegularFile(path: string, maxBytes: number): string | null { let fd: number | undefined; try { const entry = lstatSync(path); if (!entry.isFile() || entry.size > maxBytes) return null; fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); const opened = fstatSync(fd); if (!opened.isFile() || opened.size > maxBytes) return null; const bytes = Buffer.alloc(opened.size + 1); let length = 0; while (length < bytes.length) { const read = readSync(fd, bytes, length, bytes.length - length, null); if (read === 0) break; length += read; } return length > maxBytes ? null : bytes.subarray(0, length).toString("utf8"); } catch { return null; } finally { if (fd !== undefined) closeSync(fd); } } /** A background observation must not use journaledInjectedCatalogPath(), which cleans invalid journals. */ function readJournaledCatalogPath(journalPath: string): string | null { const bytes = readBoundedRegularFile(journalPath, MAX_JOURNAL_BYTES); if (bytes === null) return null; try { const journal: unknown = JSON.parse(bytes); if (!journal || typeof journal !== "object" || Array.isArray(journal)) return null; const record = journal as Record<string, unknown>; return record.version === 1 && typeof record.injectedCatalogPath === "string" && record.injectedCatalogPath.trim() ? record.injectedCatalogPath : null; } catch { return null; } } function usableCatalogPath(path: string | null): string | null { if (!path) return null; const bytes = readBoundedRegularFile(path, MAX_CATALOG_BYTES); if (bytes === null) return null; try { const catalog: unknown = JSON.parse(bytes); return catalog && typeof catalog === "object" && Array.isArray((catalog as { models?: unknown }).models) ? path : null; } catch { return null; } } /** Testable path decision with no journal mutation or catalog write. */ export function selectDriftHealCatalogPath( journalPath: string, defaultCatalogPath: string, resolvePath: (path: string) => string, ): string | null { const recorded = readJournaledCatalogPath(journalPath); return usableCatalogPath(recorded ? resolvePath(recorded) : null) ?? usableCatalogPath(defaultCatalogPath); } /** Repair only the missing config roots; catalog convergence remains the later tick step. */ async function healCodexConfigDrift(config: OcxConfig, entryGeneration: number): Promise<"none" | "healed" | "not-healed"> { const [{ codexConfigDrift }, { JOURNAL_PATH, journaledInjectedCatalogPath, journaledInjectedOpenaiBaseUrl, journaledInjectedRealtimeWsBaseUrl, journaledInjectedRootValues }, { shouldSyncCodexOnStart }, { injectCodexConfig }, { CODEX_CONFIG_PATH, DEFAULT_CATALOG_PATH, resolveCodexCatalogPath }, { loadConfig }, { inspectNativeCodexOwnership }] = await Promise.all([ import("./config-drift-heal"), import("./journal"), import("./desired-state"), import("./inject"), import("./paths"), import("../config"), import("../integrations/native/ownership-preflight"), ]); const capturedSettings = JSON.stringify(config); const current = () => entryGeneration === generation && JSON.stringify(loadConfig()) === capturedSettings; if (!current()) return "none"; if (!shouldSyncCodexOnStart(config)) return "none"; const journaled = { injectedOpenaiBaseUrl: journaledInjectedOpenaiBaseUrl({ readOnly: true }), injectedRealtimeWsBaseUrl: journaledInjectedRealtimeWsBaseUrl({ readOnly: true }), injectedCatalogPath: journaledInjectedCatalogPath(), injectedRootValues: { openai_base_url: journaledInjectedRootValues("openai_base_url", { readOnly: true }), experimental_realtime_ws_base_url: journaledInjectedRootValues("experimental_realtime_ws_base_url", { readOnly: true }), }, }; const drift = codexConfigDrift(() => journaled); if (!drift.drifted) return "none"; lastHealMissingKeys = drift.missingKeys; const { readRuntimePort } = await import("../config/process-state"); if (!current()) return "none"; const runtime = readRuntimePort(process.pid); if (!runtime) return "not-healed"; const catalogPath = selectDriftHealCatalogPath( JOURNAL_PATH, DEFAULT_CATALOG_PATH, path => resolveCodexCatalogPath(CODEX_CONFIG_PATH, path), ); if (!current()) return "none"; // Keep the missing routing roots visible to the next tick. Catalog-only convergence below // may recreate the file now, but it does not re-inject config.toml in this tick. if (catalogPath === null) return "not-healed"; // Ownership is probed directly, not through admission: admission can refuse on the // config or generation authority before it ever inspects native ownership, and a // veto that rides that result would let those refusals pass on a foreign home. const serviceHomeOwned = () => inspectNativeCodexOwnership().ownership === "owned"; if (!serviceHomeOwned()) return "not-healed"; await injectCodexConfig(runtime.port, config, { catalogPath, lockTimeoutMs: TICK_DEADLINE_MS, beforeClientWrite: () => { if (!current()) throw new Error("Catalog drift heal tick is stale"); if (!serviceHomeOwned()) throw new Error("Catalog drift heal lost service-home ownership"); }, }).catch(() => null); if (!current()) return "none"; return codexConfigDrift(() => journaled).drifted ? "not-healed" : "healed"; } /** Number of ticks that have run. Test-only observability; carries no catalog data. */ let tickCount = 0; function boundedInterval(value: number): number { return Math.max(MIN_INTERVAL_MS, Math.floor(value)); } /** Re-arm the timer when the operator changed the cadence since it was created. */ function restartIfCadenceChanged(configured: number): void { if (timer === null || boundedInterval(configured) === liveIntervalMs) return; clearInterval(timer); liveIntervalMs = boundedInterval(configured); timer = setInterval(() => void tick(), liveIntervalMs); timer.unref?.(); } async function tick(): Promise<void> { // An interval firing while the previous converge is still awaiting would stack // provider fetches precisely when a slow /models call is already in flight. if (inFlight) return; inFlight = true; const entryGeneration = generation; try { const { armDetachedConfigBaseline, loadConfig, isCatalogAutoRefreshEnabled, resolveCatalogAutoRefreshIntervalMs, } = await import("../config"); const config = loadConfig(); // Convergence can persist model-discovery fields after awaiting provider /models. // Arm this independently loaded snapshot as detached so the save rebases every // field — listener binding and disk-only keys included — against what is on disk // by then, and concurrent hand edits survive the tick. armDetachedConfigBaseline(config); if (!isCatalogAutoRefreshEnabled(config)) return; const configured = resolveCatalogAutoRefreshIntervalMs(config); // 0 is dormant: the section stays configured but this tick must not converge, // and the unref'd timer is left running so flipping the minutes back on is // picked up without a process restart. if (configured === 0) return; // The default-on case belongs to installs whose local Codex client this proxy manages. With // the integration off (or on a hub or sibling), an absent section keeps the old opt-in // meaning: no background converge may write the native Codex home unasked. An explicit // `enabled: true` still refreshes, as it did before the default flipped. const { shouldSyncCodexOnStart } = await import("./desired-state"); const codexManaged = shouldSyncCodexOnStart(config); if (!codexManaged && config.catalogAutoRefresh?.enabled !== true) return; // A stop or restart landed while the config resolved: this tick no longer owns the timer, // so it must neither count as a refresh nor adopt a cadence for a generation that is gone. if (entryGeneration !== generation) return; // Adopt a changed cadence without a restart, which is why the config gate lives in the // callee at all. Only while this tick still owns the timer. restartIfCadenceChanged(configured); tickCount += 1; // Config-surface healing precedes catalog work: a desktop app rewrite that stripped the // injected routing keys leaves the catalog file untouched, so the converge below would // report "no change" while Codex serves its native model picker. Re-injecting through the // standard sync rewrites the keys, re-journals the baseline, and only runs when the // integration is on and this install is allowed to manage its local client. const heal = await healCodexConfigDrift(config, entryGeneration); if (entryGeneration !== generation) return; if (heal === "healed") { const { codexConfigHealNotice } = await import("./config-drift-heal"); console.info(codexConfigHealNotice(lastHealMissingKeys, !healReported)); healReported = true; } else if (heal === "not-healed") { console.info("[catalog-auto-refresh] injected Codex config keys were rewritten externally; not re-injected this tick"); } const { refreshCatalogAutoRefreshSources, catalogAutoRefreshReloadRequired } = await import("./catalog-auto-refresh-sources"); if (entryGeneration !== generation) return; // Codex sources read Codex credentials and probe its binary; only a managed client needs them. if (codexManaged) await refreshCatalogAutoRefreshSources(config, () => entryGeneration === generation); if (entryGeneration !== generation) return; const [{ createManagementConvergeCodex }, { createCatalogConvergeRequest }] = await Promise.all([ import("./management-convergence"), import("./catalog-admission"), ]); // A stop or restart landed while the funnel was loading: the result belongs to a // generation that no longer owns the timer, so it must not publish. if (entryGeneration !== generation) return; const converge = createManagementConvergeCodex(config); const outcome = await converge(createCatalogConvergeRequest({ deadlineMs: TICK_DEADLINE_MS })); if (entryGeneration !== generation) return; // createManagementConvergeCodex always projects catalog-only. Any other kind is a // funnel contract break, not something this scheduler should re-classify. if (outcome.kind !== "catalog-only") return; const { recordCatalogAutoRefreshOutcome, lastCatalogAutoRefreshOutcome } = await import("./catalog-refresh-status"); const reloadRequired = (outcome.changed || lastCatalogAutoRefreshOutcome()?.reloadRequired === true) ? await catalogAutoRefreshReloadRequired(outcome.changed) : false; if (entryGeneration !== generation) return; recordCatalogAutoRefreshOutcome(outcome.catalogRefresh, outcome.changed, reloadRequired); if (outcome.changed) { try { linkFanout?.(); } catch { /* the scheduler's 5-minute poll catches the change */ } // Privacy scan: no provider names, model ids, paths, or account identifiers. console.info(reloadRequired ? "[catalog-auto-refresh] served model set changed; running Codex sessions keep the old list until restarted (ocx sync --restart-codex)" : "[catalog-auto-refresh] served model set changed"); } const fanout = clientFanout; if (outcome.changed && fanout) { const current = () => entryGeneration === generation; try { const failed = (await fanout(current)).filter(result => !result.ok).length; // Outcomes can contain private paths and reasons; only the failure count leaves this hook. if (current() && failed > 0) console.warn(`[catalog-auto-refresh] ${failed} client integration(s) were not refreshed; ocx sync retries them`); } catch { if (current()) console.warn("[catalog-auto-refresh] client integrations were not refreshed; ocx sync retries them"); } } } catch { // A failed refresh is not an error worth surfacing: the next tick tries again. } finally { inFlight = false; } } /** Idempotent. A second call while running is a no-op, matching startQuotaResetPoller. */ export function startCatalogAutoRefresh(intervalMs = DEFAULT_INTERVAL_MS): void { if (timer) return; const bounded = boundedInterval(intervalMs); generation += 1; liveIntervalMs = bounded; timer = setInterval(() => void tick(), bounded); // Never keep the process alive for a catalog refresh. timer.unref?.(); const startedGeneration = generation; initialTimer = setTimeout(() => { if (startedGeneration !== generation) return; initialTimer = null; return tick(); }, INITIAL_DELAY_MS); initialTimer.unref?.(); void import("../lib/optional-shutdown-hooks") .then(hooks => { if (startedGeneration !== generation) return; detachShutdownHook = hooks.registerOptionalShutdownHook( "catalog-auto-refresh", stopCatalogAutoRefresh, ); }) .catch(() => { // Without the hook the unref'd timer still cannot delay exit. }); } export function stopCatalogAutoRefresh(): void { if (initialTimer) { clearTimeout(initialTimer); initialTimer = null; } if (timer) { clearInterval(timer); timer = null; } liveIntervalMs = null; generation += 1; detachShutdownHook?.(); detachShutdownHook = null; } export function isCatalogAutoRefreshRunning(): boolean { return timer !== null; } /** * Adopt the operator's configured cadence at startup. * * The caller starts the scheduler synchronously with the default interval, because * resolving the config here would mean a static edge to ../config from a module * background-lifecycle imports at load time. Resolving it through import() keeps * that edge dynamic, at the cost of the timer running at the default for the few * microtasks before this settles. */ export async function syncCatalogAutoRefreshCadence(): Promise<void> { const entryGeneration = generation; const { loadConfig, resolveCatalogAutoRefreshIntervalMs } = await import("../config"); if (entryGeneration !== generation) return; const configured = resolveCatalogAutoRefreshIntervalMs(loadConfig()); // 0 is dormant: tick() already returns before converging, and the timer stays unref'd. if (configured === 0) return; restartIfCadenceChanged(configured); } /** Test-only: run one tick synchronously rather than waiting out the interval. */ export async function runCatalogAutoRefreshTickForTests(): Promise<void> { await tick(); } export function catalogAutoRefreshTickCountForTests(): number { return tickCount; } /** Test-only: the bounded cadence the live timer is running at, or null when stopped. */ export function catalogAutoRefreshIntervalForTests(): number | null { return liveIntervalMs; } export function resetCatalogAutoRefreshForTests(): void { stopCatalogAutoRefresh(); tickCount = 0; }