@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
140 lines (126 loc) • 6.87 kB
text/typescript
/**
* The process-local "sibling instance" mark.
*
* A sibling is what `decideStartWithLiveOwner` calls `"sibling"`: `ocx start --port <other>` while a
* live proxy already serves the configured port. Only an independent `OPENCODEX_HOME` gets past the
* state-directory spend-ledger lease, and that independence ends at its own directory: the sibling
* still shares `CODEX_HOME`, `~/.claude`, `~/.grok`, the shell rc hook and the launchd domain with
* the live owner. A sibling that ran the ordinary startup sync therefore re-pointed Codex at its own
* port, and every thread broke with "Connection refused" once the sibling exited or was killed. The
* owner's client routing is the owner's, for this process's whole lifetime.
*
* So `handleStart` sets this mark the moment it takes the sibling path, before the server binds and
* before any client write, and the local-client gate (`localClientSyncAllowed` in
* `desired-state.ts`), the restore entry points, the catalog convergence funnel, the owned-catalog
* refresh, the Claude writers, the stop teardown and the management route guard all consult it. The
* sibling still serves direct requests on its own port.
*
* One-way and process-local on purpose. A mark that could be cleared would let a later code path
* resume writing mid-lifetime, and a persisted one would outlive the process it describes. Worker
* threads do not see it; that is acceptable because history jobs start only from inject and
* restore, and both return before spawning one.
*
* A sibling runs the no-op native-main lifecycle (the gate is closed), so it never contends for the
* native-main owner lease and cannot take ownership from the live proxy across that proxy's
* restarts. Its data-plane native-main admission is the same as a Codex-OFF proxy's: an `auth.json`
* refresh still runs under the machine-wide exclusive claim. The native-main mutation routes are
* refused by the management guard instead.
*
* The one hand-off is to this process's own replacement. A sibling's dashboard drain-and-restart and
* its standalone recycle spawn a fresh `ocx start` that re-probes; if the owner is down for that
* moment, the replacement used to start as an unmarked owner, re-point Codex at itself and persist
* `config.port`. Those spawns carry a port plus a one-use record nonce from `sibling-handoff.ts`.
* `handleStart` consumes the record before any probe; an env port alone grants nothing.
*
* Deliberately import-free: the gate, the server and the CLI all read it, and a leaf cannot form a
* cycle.
*/
let livePort: number | null = null;
/** Mark this process as a sibling of the proxy serving `port`. Idempotent; never unset. */
export function markSiblingStart(port: number): void {
livePort = port;
}
/** The live owner's port when this process is a sibling, otherwise `null`. */
export function siblingOfLivePort(): number | null {
return livePort;
}
/** Test seam only: production never clears the mark. */
export function resetSiblingStartForTests(): void {
livePort = null;
}
/**
* The one line a sibling prints wherever it declines a shared client write.
*
* With the sibling's own port it describes the split; without one (a skip deep inside a writer
* that does not know the port) it names what was left alone.
*/
export function siblingSkipMessage(ownPort?: number): string {
const live = livePort ?? "unknown";
return ownPort === undefined
? `Client routing stays on the proxy at port ${live}; this instance does not rewrite Codex, Grok or Claude configs.`
: `Client routing stays on the proxy at port ${live}; this instance serves direct requests on port ${ownPort} only.`;
}
/**
* The optional runtime-record field that tells a later `ocx stop` it is stopping a sibling.
* Empty when unmarked, so a non-sibling record stays byte-identical.
*/
export function siblingRuntimeField(): { siblingOfPort?: number } {
return livePort === null ? {} : { siblingOfPort: livePort };
}
/** The env var a sibling hands its own replacement `ocx start`: the live owner's port. */
export const SIBLING_OF_PORT_ENV = "OCX_SIBLING_OF_PORT";
export const SIBLING_HANDOFF_NONCE_ENV = "OCX_SIBLING_HANDOFF_NONCE";
type Env = Record<string, string | undefined>;
/** The owner port an inherited marker names, or `null` when absent or not a TCP port. */
export function parseSiblingMarker(raw: string | undefined): number | null {
const trimmed = raw?.trim() ?? "";
if (!/^[0-9]{1,5}$/.test(trimmed)) return null;
const port = Number(trimmed);
return port >= 1 && port <= 65535 ? port : null;
}
/**
* Honor a port only when its one-use handoff record was consumed. Both env fields are stripped
* before any probe, including on refusal, so a later detached child cannot inherit them.
*/
export function honorSiblingMarker(env: Env, consumeHandoff: (port: number, nonce: string | undefined) => boolean): number | null {
const port = parseSiblingMarker(env[SIBLING_OF_PORT_ENV]);
const nonce = env[SIBLING_HANDOFF_NONCE_ENV];
delete env[SIBLING_OF_PORT_ENV];
delete env[SIBLING_HANDOFF_NONCE_ENV];
if (port === null || !consumeHandoff(port, nonce)) return null;
markSiblingStart(port);
return port;
}
/** A copy of `env` for this process's own replacement, with a one-use handoff when marked. */
export function withSiblingMarker<T extends Env>(env: T, issueHandoff?: (port: number) => string): T {
const next: Env = withoutSiblingMarker(env);
if (livePort !== null) {
if (!issueHandoff) throw new Error("Sibling replacement requires a one-use handoff issuer.");
next[SIBLING_OF_PORT_ENV] = String(livePort);
next[SIBLING_HANDOFF_NONCE_ENV] = issueHandoff(livePort);
}
return next as T;
}
/** A copy of `env` for a child that must start as an ordinary owner (`ocx ensure`, the tray). */
export function withoutSiblingMarker<T extends Env>(env: T): T {
const next: Env = { ...env };
delete next[SIBLING_OF_PORT_ENV];
delete next[SIBLING_HANDOFF_NONCE_ENV];
return next as T;
}
/**
* Whether `ocx stop` of a sibling runtime found the live owner instead of the sibling.
*
* A hard-killed sibling leaves its record behind with a dead pid, so the stop falls through to
* discovery, and discovery ends on the configured port, where the live owner answers. Stopping that
* proxy is the outage the sibling design exists to prevent. The found proxy is the owner when it
* answers on `siblingOfPort`, or when only the configured-port fallback reached it (the sibling's
* own record did not answer). `live` is `findLiveProxy`'s result.
*/
export function siblingStopFoundOwner(
siblingOfPort: number | undefined,
live: { port: number; source: "runtime" | "config" } | null,
): boolean {
if (siblingOfPort === undefined || live === null) return false;
return live.port === siblingOfPort || live.source === "config";
}