@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
404 lines (371 loc) • 16.7 kB
text/typescript
export interface TrayProxyLive { port: number }
export interface TrayProxyServiceState {
installed: boolean;
startable: boolean;
summary: string;
}
export interface TrayProxyStartIo {
findLive: () => Promise<TrayProxyLive | null>;
/** Normal Start is idempotent; restart fallback refuses a target that reappeared. */
existingIsSuccess?: boolean;
diagnoseService: () => TrayProxyServiceState;
startService: () => void | Promise<void>;
startDirect: () => void | Promise<void>;
waitForProxy: () => Promise<TrayProxyLive | null>;
info: (message: string) => void;
error: (message: string) => void;
}
export interface ProxyRestartLive {
pid: number | null;
port: number;
hostname?: string;
source: "runtime" | "config";
}
export type ProxyRestartRequestOutcome =
| { accepted: true }
| { accepted: false; uncertain: boolean; error?: unknown };
export type ProxyRestartResult =
| { ok: true; mode: "started" }
| { ok: true; mode: "skipped" }
| { ok: true; mode: "restarted"; live: ProxyRestartLive }
| { ok: false; phase: "start" | "identity" | "request" | "replacement"; error?: unknown };
export type ProxyRestartDiscovery =
| { status: "live"; live: ProxyRestartLive }
| { status: "absent" }
| { status: "uncertain"; error?: unknown };
export type ProxyRestartStartOutcome =
| { status: "started" }
| { status: "skipped" }
| { status: "failed"; launch: "never" | "exited" | "unknown"; error?: unknown };
/** Only the launched child's observed exit (or no launch) permits another attempt. */
export function restartStartOutcome(
started: boolean,
child: { exitCode: number | null; signalCode: string | null } | null,
error?: unknown,
): ProxyRestartStartOutcome {
if (started) return { status: "started" };
return {
status: "failed",
launch: child === null ? "never" : child.exitCode !== null || child.signalCode !== null ? "exited" : "unknown",
error,
};
}
export interface ProxyRestartDiscoveryIo {
findLive: () => Promise<ProxyRestartLive | null>;
waitBetweenChecks?: () => Promise<void>;
expired?: () => boolean;
}
export interface ProxyRestartIo {
findLive: () => Promise<ProxyRestartDiscovery>;
startWhenStopped: (recoveringLiveRestart: boolean) => ProxyRestartStartOutcome | Promise<ProxyRestartStartOutcome>;
requestInPlaceRestart: (
previous: ProxyRestartLive,
) => ProxyRestartRequestOutcome | Promise<ProxyRestartRequestOutcome>;
waitForReplacement: (previous: ProxyRestartLive) => Promise<ProxyRestartLive | null>;
/** Pause between start attempts; defaults to a short sleep. Tests pass a recorder. */
waitBetweenAttempts?: () => Promise<void>;
/**
* Strong re-observation after a missed replacement. Defaults to `findLive`, but the
* production wiring passes a fresh bounded window: by the time the replacement wait
* expires, the shared observe deadline has expired too, so reusing it would answer
* `uncertain` forever and the crash-recovery path could never run.
*/
reobserveAfterReplacement?: (previous: ProxyRestartLive) => Promise<ProxyRestartDiscovery>;
/** A failed recovery start must recheck under a fresh window after the shared deadline. */
recheckAfterFailedStart?: () => Promise<ProxyRestartDiscovery>;
}
/**
* Poll for a departed predecessor inside a bounded confirmation window. Each round is
* already a strong observation (the caller supplies it); this only decides whether
* another round still fits: absent and valid-replacement verdicts return immediately,
* while the still-live old PID (or another uncertain round) keeps polling until the
* budget check refuses. A replacement that lands late in the window is still attested
* instead of being cut off by the wait that reserved the window.
*/
export async function pollReplacementDeparture(
observe: () => Promise<ProxyRestartDiscovery>,
previous: ProxyRestartLive,
shouldContinue: () => boolean,
wait: () => Promise<void>,
): Promise<ProxyRestartDiscovery> {
for (;;) {
const round = await observe();
if (round.status === "absent") return round;
if (round.status === "live" && isProxyReplacement(previous, round.live)) return round;
if (!shouldContinue()) return round;
await wait();
}
}
export async function waitForProxyReplacement(
previous: ProxyRestartLive,
deadlineAt: number,
observe: (deadlineAt: number) => Promise<ProxyRestartLive | null>,
): Promise<ProxyRestartLive | null> {
while (Date.now() < deadlineAt) {
const live = await observe(deadlineAt);
if (Date.now() >= deadlineAt) return null;
if (isProxyReplacement(previous, live)) return live;
const remainingMs = deadlineAt - Date.now();
if (remainingMs > 0) await Bun.sleep(Math.min(250, remainingMs));
}
return null;
}
export function reobserveRestartReplacement(
previous: ProxyRestartLive,
deadlineAt: number,
observe: (end: number) => Promise<ProxyRestartDiscovery>,
): Promise<ProxyRestartDiscovery> {
const now = Date.now();
const windowMs = Math.min(5_000, deadlineAt - now);
if (windowMs < 1_500) return Promise.resolve({
status: "uncertain", error: new Error("restart_reobserve_window_exhausted"),
});
const end = now + windowMs;
return pollReplacementDeparture(() => observe(end), previous, () => Date.now() + 750 < end, () => Bun.sleep(250));
}
/** Production recovery recheck: the original restart deadline may already be spent. */
export function recheckRestartFailedStart(
observe: (end: number) => Promise<ProxyRestartDiscovery>,
): Promise<ProxyRestartDiscovery> {
const end = Date.now() + 5_000;
return observe(end);
}
/**
* Confirm absence twice before restart is allowed to select a start-only path.
* A live target appearing during confirmation is uncertainty, not success: the
* caller must not claim it restarted a process it never asked to restart.
*/
export async function discoverStableProxyForRestart(
io: ProxyRestartDiscoveryIo,
): Promise<ProxyRestartDiscovery> {
let first: ProxyRestartLive | null;
try {
first = await io.findLive();
} catch (error) {
return { status: "uncertain", error };
}
if (first) return { status: "live", live: first };
if (io.expired?.()) {
return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
}
await (io.waitBetweenChecks ?? (() => Bun.sleep(100)))();
let second: ProxyRestartLive | null;
try {
second = await io.findLive();
} catch (error) {
return { status: "uncertain", error };
}
if (second) {
return {
status: "uncertain",
error: new Error("restart_target_appeared_during_absence_confirmation"),
};
}
if (io.expired?.()) {
return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
}
return { status: "absent" };
}
export function isProxyReplacement(
previous: ProxyRestartLive,
candidate: ProxyRestartLive | null,
): candidate is ProxyRestartLive & { pid: number } {
return previous.pid !== null
&& candidate?.pid !== null
&& candidate?.pid !== undefined
&& candidate.source === "runtime"
&& candidate.port === previous.port
&& candidate.pid !== previous.pid;
}
/** Side-effect coordinator for the tray's fixed proxy-start action. */
export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean> {
const live = await io.findLive();
if (live) {
if (io.existingIsSuccess === false) {
io.error("Proxy appeared while restart was confirming absence; no start was attempted.");
return false;
}
io.info(`Proxy already running on port ${live.port}.`);
return true;
}
const service = io.diagnoseService();
if (service.installed && !service.startable) {
io.error(`Cannot start from the tray because the installed service is not viable: ${service.summary}`);
io.error("Repair or remove the service before starting a direct proxy.");
return false;
}
if (service.startable) await io.startService();
else await io.startDirect();
const started = await io.waitForProxy();
if (!started) {
io.error("Proxy did not become healthy after the tray start action.");
return false;
}
io.info(`Proxy running on port ${started.port}.`);
return true;
}
/**
* Shared restart transaction for both `ocx restart` and the Windows tray.
*
* A live proxy restarts itself through POST /api/system/restart. That lifecycle owns
* drain, supervisor handoff, exact replacement identity, and managed-routing
* preservation. Re-implementing restart as `stop` + `start` here races a late service
* child and lets ordinary /api/stop restore native routing between the two halves.
* When no proxy is live there is nothing to recycle, so restart degrades to the
* caller's normal start path.
*
* An uncertain discovery round is re-observed. A failed start is retried only after
* proof that it never launched or its child exited; a health miss is insufficient.
* A missed replacement gets a bounded re-observation. A live target is never stopped
* to make room, and absence is confirmed twice before any fresh start.
*/
/**
* A proven pre-launch refusal or observed child exit can be retried within this bound.
* A deliberate operator refusal (`"skipped"`) never retries.
*/
const RESTART_START_ATTEMPTS = 3;
/** Discovery rounds per restart transaction; an uncertain round is a transient race. */
const RESTART_DISCOVERY_ATTEMPTS = 3;
/**
* Start leg with phase evidence. A bare boolean cannot tell a pre-launch refusal from
* a child that was launched but is not healthy yet, or from post-health steps that
* threw on an already-live proxy — and blindly respawning on any of those risks a
* second proxy racing the first for the port. So every failed attempt is followed by a
* beat and a strong re-observation: a live proxy attests success (no second start),
* and only confirmed absence plus launch proof earns another attempt.
*/
async function startRestartedProxy(
io: ProxyRestartIo,
waitBetweenAttempts: () => Promise<void>,
recoveringLiveRestart: boolean,
/** The restarted proxy's identity; recovery success must be a different process. */
previous?: ProxyRestartLive,
): Promise<ProxyRestartResult> {
let originalError: unknown;
for (let attempt = 0; attempt < RESTART_START_ATTEMPTS; attempt++) {
let outcome: ProxyRestartStartOutcome;
try {
outcome = await io.startWhenStopped(recoveringLiveRestart);
} catch (error) {
// An unstructured exception can have happened after launch.
outcome = { status: "failed", launch: "unknown", error };
}
if (outcome.status === "skipped") return recoveringLiveRestart
? { ok: false, phase: "replacement" } : { ok: true, mode: "skipped" };
if (outcome.status === "started") {
if (!previous) return { ok: true, mode: "started" };
// Recovery after a live restart: the start path counts any healthy proxy it finds as
// started, and the ORIGINAL process reappearing would satisfy it. Success needs an
// identity-verified replacement — a different runtime PID on the original port —
// observed in a fresh window; anything else fails closed as a missed replacement.
let confirm: ProxyRestartDiscovery;
try {
confirm = await (io.recheckAfterFailedStart?.() ?? io.findLive());
} catch (error) {
return { ok: false, phase: "replacement", error };
}
return confirm.status === "live" && isProxyReplacement(previous, confirm.live)
? { ok: true, mode: "started" }
: { ok: false, phase: "replacement" };
}
if (attempt === 0) originalError = outcome.error;
// Beat first: a child that was just launched may still be binding, and post-health
// steps may have thrown on an already-live proxy. Re-observe before deciding: live
// attests success (never a second start), only confirmed absence earns a retry.
await waitBetweenAttempts();
let recheck: ProxyRestartDiscovery;
try {
recheck = await (io.recheckAfterFailedStart?.() ?? io.findLive());
} catch {
return { ok: false, phase: "start", error: originalError };
}
// Runtime-attested only: a config-sourced observation is not proof a proxy serves,
// so it keeps the start failure instead of reporting a success nobody earned.
// A throw on an attested-live proxy is different from a clean refusal: post-health
// work failed on a serving process, so the error propagates instead of converting
// to success — still without spawning again.
const attested = recheck.status === "live"
&& recheck.live.pid !== null
&& recheck.live.source === "runtime";
// Recovery after a live restart: the old PID coming back is not a replacement this
// command started. It is serving, so never start another over it, and never call it
// success either.
if (attested && previous && recheck.status === "live" && !isProxyReplacement(previous, recheck.live)) {
return { ok: false, phase: "replacement" };
}
if (attested && outcome.error !== undefined) return { ok: false, phase: "start", error: originalError };
if (attested) return { ok: true, mode: "started" };
if (outcome.launch === "unknown" || recheck.status !== "absent") {
return { ok: false, phase: "start", error: originalError };
}
}
return { ok: false, phase: "start", error: originalError };
}
export async function runProxyRestart(io: ProxyRestartIo): Promise<ProxyRestartResult> {
const waitBetweenAttempts = io.waitBetweenAttempts ?? (() => Bun.sleep(500));
// An uncertain round is a transient appear/vanish race, not a verdict: re-observe a
// few times before failing, so one invocation survives a supervisor mid-handoff.
let discovery: ProxyRestartDiscovery = { status: "uncertain", error: new Error("restart_discovery_no_attempt") };
for (let attempt = 0; attempt < RESTART_DISCOVERY_ATTEMPTS; attempt++) {
if (attempt > 0) await waitBetweenAttempts();
try {
discovery = await io.findLive();
} catch (error) {
discovery = { status: "uncertain", error };
}
if (discovery.status !== "uncertain") break;
}
if (discovery.status === "uncertain") {
return { ok: false, phase: "request", error: discovery.error };
}
if (discovery.status === "absent") {
return startRestartedProxy(io, waitBetweenAttempts, false);
}
const previous = discovery.live;
if (previous.pid === null || previous.source !== "runtime") {
return { ok: false, phase: "identity" };
}
let request: ProxyRestartRequestOutcome;
try {
request = await io.requestInPlaceRestart(previous);
} catch (error) {
// The request may have reached the proxy before the response connection failed.
// Keep observing the original identity; never replay or fall back to stop/start.
request = { accepted: false, uncertain: true, error };
}
if (!request.accepted && !request.uncertain) {
return { ok: false, phase: "request", error: request.error };
}
let replacement: ProxyRestartLive | null;
try {
replacement = await io.waitForReplacement(previous);
} catch (error) {
return { ok: false, phase: "replacement", error };
}
if (replacement) return { ok: true, mode: "restarted", live: replacement };
// The replacement never arrived: re-observe once instead of failing blind. A proxy
// that crashed mid-restart reads absent (safe to start fresh — nothing live can race
// the bind); a replacement that landed just past the deadline still proves success;
// the same PID or another uncertain round fails closed exactly as before. A live
// target is never stopped to make room: the no-stop/start-fallback invariant holds.
const reobserveHook = io.reobserveAfterReplacement;
const reobserve = reobserveHook ? () => reobserveHook(previous) : io.findLive;
let again: ProxyRestartDiscovery;
try {
again = await reobserve();
} catch (error) {
return { ok: false, phase: "replacement", error };
}
if (again.status === "absent") {
// Only an ACCEPTED restart earns a recovery start. After an uncertain request the old
// proxy may merely be mid-restart and reappear; starting one here could race it.
if (!request.accepted) return { ok: false, phase: "request", error: request.error };
return startRestartedProxy(io, waitBetweenAttempts, true, previous);
}
if (again.status === "live" && isProxyReplacement(previous, again.live)) {
return { ok: true, mode: "restarted", live: again.live };
}
return request.accepted
? { ok: false, phase: "replacement" }
: { ok: false, phase: "request", error: request.error };
}