@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
110 lines (99 loc) • 5.61 kB
text/typescript
/**
* Whether a Remote Link Child can serve relayed requests right now, for its `GET /readyz`.
*
* `/healthz` keeps meaning "this process answers". A Child whose tunnel is down still answers it,
* yet every relayed turn fails with 503, so readiness is where that shows: not ready, with one
* fixed reason word. Nothing here carries ssh output, host names, ports or keys.
*
* - A Child-initiated link reads its own tunnel supervisor; no network traffic.
* - A Home-initiated link has no local tunnel to inspect (the Home runs `ssh -R`), so it runs
* the credential-free relay preflight through the tunnel port. One preflight runs at a time, a
* verdict is reused for `LINK_READINESS_TTL_MS`, and a request waits at most
* `LINK_READINESS_WAIT_MS` for a running preflight before it answers `link_unverified`. An
* unauthenticated caller can therefore cause at most one preflight per TTL.
*/
import { LINK_RELAY_AUTH_TIMEOUT_MS } from "../link/relay-auth";
import { isLinkPort } from "../link/ports";
import { probeLinkRelayPreflight, type BoundLinkRelayTarget, type LinkRelayPreflightResult } from "./link-relay-transport";
import type { ClientLinkSupervisorStatus } from "./link-tunnel";
/**
* Every reason word /readyz may report. `client_state_changed`: the Child's durable connection no
* longer matches the one this runtime started with. A reader of /readyz (`ocx connect status`)
* accepts only these words, so nothing else a listener sends is echoed to a terminal.
*/
export const LINK_READINESS_REASONS = [
"tunnel_idle", "tunnel_connecting", "tunnel_failed", "tunnel_unavailable", "sidecar_invalid",
"home_unreachable", "home_unauthorized", "link_auth_failed", "link_credential_unavailable",
"link_unverified", "client_state_changed",
] as const;
export type LinkReadinessReason = typeof LINK_READINESS_REASONS[number];
export function isLinkReadinessReason(value: unknown): value is LinkReadinessReason {
return typeof value === "string" && (LINK_READINESS_REASONS as readonly string[]).includes(value);
}
export type LinkReadiness = { ready: true } | { ready: false; reason: LinkReadinessReason };
export const LINK_READINESS_TTL_MS = 5_000;
export const LINK_READINESS_WAIT_MS = 500;
const READY: LinkReadiness = { ready: true };
const notReady = (reason: LinkReadinessReason): LinkReadiness => ({ ready: false, reason });
/**
* A Child-initiated link from its supervisor. The keyed probe the supervisor runs every 30 seconds
* while connected is display-only for the tunnel, but a Home that stopped answering or refuses the
* key cannot serve a turn, so readiness follows it. A Home whose own startup readiness is pending
* still serves relayed requests (the probe's `home_not_ready`), so that reads ready.
*/
export function clientInitiatedLinkReadiness(status: ClientLinkSupervisorStatus): LinkReadiness {
if (status.kind === "failed") return notReady("sidecar_invalid");
if (status.kind === "stopped") return notReady("tunnel_idle");
const { state, probe } = status;
if (state.kind === "connected") {
if (probe === "home_unreachable") return notReady("home_unreachable");
if (probe === "unauthorized") return notReady("home_unauthorized");
return READY;
}
if (state.kind === "connecting" || state.kind === "reconnecting") return notReady("tunnel_connecting");
if (state.kind === "failed") return notReady(state.inFlight ? "tunnel_connecting" : "tunnel_failed");
return notReady("tunnel_idle");
}
function fromPreflight(result: LinkRelayPreflightResult): LinkReadiness {
if (result === "ok") return READY;
return notReady(result === "unreachable" ? "home_unreachable" : "link_auth_failed");
}
export interface HomeInitiatedLinkReadinessDeps {
target: Omit<BoundLinkRelayTarget, "admissionKey">;
linkKey: () => string | null;
probe?: (target: BoundLinkRelayTarget, options: { timeoutMs: number }) => Promise<LinkRelayPreflightResult>;
now?: () => number;
/** Resolves after `ms`; the wait for a running preflight. */
delay?: (ms: number) => Promise<void>;
}
/** The readiness of a Home-initiated link, from a shared, rate-limited relay preflight. */
export function createHomeInitiatedLinkReadiness(deps: HomeInitiatedLinkReadinessDeps): () => Promise<LinkReadiness> {
const probe = deps.probe ?? probeLinkRelayPreflight;
const now = deps.now ?? Date.now;
const delay = deps.delay ?? (ms => new Promise<void>(resolve => {
const timer = setTimeout(resolve, ms);
(timer as { unref?: () => void }).unref?.();
}));
let last: { at: number; verdict: LinkReadiness } | undefined;
let flight: Promise<LinkReadiness> | undefined;
const run = (admissionKey: string): Promise<LinkReadiness> => {
flight ??= probe({ ...deps.target, admissionKey }, { timeoutMs: LINK_RELAY_AUTH_TIMEOUT_MS })
.then(fromPreflight, () => notReady("home_unreachable"))
.then(verdict => {
last = { at: now(), verdict };
return verdict;
})
.finally(() => { flight = undefined; });
return flight;
};
return async () => {
if (!isLinkPort(deps.target.tunnelPort)) return notReady("tunnel_unavailable");
let admissionKey: string | null;
try { admissionKey = deps.linkKey(); } catch { admissionKey = null; }
if (!admissionKey) return notReady("link_credential_unavailable");
const at = now();
if (last && at >= last.at && at - last.at < LINK_READINESS_TTL_MS) return last.verdict;
const unverified = notReady("link_unverified");
return await Promise.race([run(admissionKey), delay(LINK_READINESS_WAIT_MS).then(() => unverified)]);
};
}