UNPKG

@bitkyc08/opencodex

Version:

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

234 lines (220 loc) • 10.5 kB
/** * A connected client's view of its hub's provider, login and roster state (#4236). * * The rule this module exists to enforce: on a connected client, the hub is the authority, and * when the hub cannot be read the answer is "unavailable" — never the client's own local * credential store. That store is empty by design, and reporting it as the truth is what made an * agent on a connected machine conclude the hub could not serve grok while the hub was serving * grok. Every failure path here therefore lands on `stateSource: "unavailable"` with a reason a * human can act on, and none of them reaches back into local config. * * The last good response is cached at `<OPENCODEX_HOME>/hub-state.json`, 0600, stamped with the * connection that produced it. The owner stamp is not decoration: after `ocx disconnect` and a * reconnect to a different hub (or a key rotation that changes `apiKeyId`), a stale file would * otherwise be presented as this hub's state. `sameClientConnectionOwner` is the same triple * (`serverUrl`, `apiKeyId`, `connectedAt`) the rest of the client lifecycle compares on. */ import { existsSync, lstatSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { getConfigDir } from "../config"; import { atomicWriteFile } from "../config/atomic-write"; import { parseHubStateBody, type HubStateDTO } from "../remote/hub-state"; import type { OcxClientConnectionConfig } from "../types"; import { fetchHubState, HubClientError } from "./hub-client"; import { sameClientConnectionOwner } from "./state"; /** Bound the status path: `ocx status` must answer even when the hub is gone. */ const DEFAULT_HUB_STATE_TIMEOUT_MS = 3_000; /** The cache document plus its stamp; the DTO itself is already capped by its own contract. */ const MAX_CACHE_BYTES = 128 * 1024; export type HubStateOwner = Pick<OcxClientConnectionConfig, "serverUrl" | "apiKeyId" | "connectedAt">; /** Where the state came from. "unavailable" is a reportable outcome, not a fallback to local. */ export type HubStateSource = "hub" | "cache" | "unavailable"; export interface HubStateResolution { stateSource: HubStateSource; state: HubStateDTO | null; /** Present whenever the live read did not succeed. Short, operator-facing. */ reason?: string; /** ISO timestamp of the response this state came from. */ fetchedAt?: string; ageSeconds?: number; } export function hubStateCachePath(): string { return join(getConfigDir(), "hub-state.json"); } interface CacheDocument { version: 1; owner: HubStateOwner; fetchedAt: string; state: HubStateDTO; } function readCacheDocument(): CacheDocument | null { const path = hubStateCachePath(); if (!existsSync(path)) return null; try { const stat = lstatSync(path); // A symlink or an oversized file is refused rather than followed: this file is written // 0600 by us, and anything else about it is someone else's doing. if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_CACHE_BYTES) return null; const raw = JSON.parse(readFileSync(path, "utf8")) as unknown; if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null; const doc = raw as Record<string, unknown>; if (doc.version !== 1) return null; const owner = doc.owner; if (!owner || typeof owner !== "object" || Array.isArray(owner)) return null; const ownerRow = owner as Record<string, unknown>; if (typeof ownerRow.serverUrl !== "string" || typeof ownerRow.apiKeyId !== "string" || typeof ownerRow.connectedAt !== "string") return null; if (typeof doc.fetchedAt !== "string" || Number.isNaN(Date.parse(doc.fetchedAt))) return null; const state = parseHubStateBody(doc.state); if (!state) return null; return { version: 1, owner: { serverUrl: ownerRow.serverUrl, apiKeyId: ownerRow.apiKeyId, connectedAt: ownerRow.connectedAt, }, fetchedAt: doc.fetchedAt, state, }; } catch { return null; } } /** The cached state for THIS connection, or null when absent, malformed, or another hub's. */ export function readCachedHubState(owner: HubStateOwner): { state: HubStateDTO; fetchedAt: string } | null { const doc = readCacheDocument(); if (!doc) return null; if (!sameClientConnectionOwner(doc.owner, owner)) return null; return { state: doc.state, fetchedAt: doc.fetchedAt }; } /** Best-effort: a cache that cannot be written must never fail the command that asked. */ export function writeCachedHubState(owner: HubStateOwner, state: HubStateDTO, fetchedAt: string): boolean { try { const document: CacheDocument = { version: 1, owner: { serverUrl: owner.serverUrl, apiKeyId: owner.apiKeyId, connectedAt: owner.connectedAt }, fetchedAt, state, }; atomicWriteFile(hubStateCachePath(), `${JSON.stringify(document, null, 2)}\n`); return true; } catch { return false; } } /** * Why the live read did not land, in words an operator can act on. * * `hub_state_unsupported` is the version-skew case and gets an explicit upgrade instruction: * left as a bare code it reads like a bug in the client. * * Every code `fetchHubState` can throw has a sentence here, including the open-ended * `hub_state_http_<status>` family. This reason is printed in the `ocx status` banner, and a * banner reading `state unavailable (hub_state_http_507)` sends the reader looking for a client * bug when the hub has in fact answered and said something. */ export function hubStateFailureReason(error: unknown, peer: "hub" | "Home" = "hub"): string { // A Remote Link Child reads the same route from its Home (#6957); the sentences name the peer // the operator actually configured. const holder = peer === "Home" ? "this Child's link key" : "this client's data key"; if (error instanceof HubClientError) { switch (error.code) { case "hub_state_not_a_hub": return "the remote host does not publish hub state"; case "hub_state_unsupported": return `this ${peer} is too old to report its state; upgrade the ${peer}`; case "hub_state_unauthorized": return `the ${peer} rejected ${holder}`; case "hub_state_schema_invalid": case "hub_state_invalid": return `the ${peer} returned an unreadable hub-state document`; case "hub_state_content_type_invalid": // Usually a captive portal, a TLS-terminating proxy or an error page in front of the // hub: the request reached SOMETHING, and that something is not the hub's API. return `the ${peer}'s state response was not JSON`; case "body_too_large": return `the ${peer}'s state response exceeded the allowed size`; case "unreachable": return `the ${peer} is unreachable`; case "redirect_refused": return `the ${peer} redirected the state request`; default: { const status = error.code.startsWith("hub_state_http_") ? error.code.slice("hub_state_http_".length) : null; return status && /^\d+$/.test(status) ? `the ${peer} answered HTTP ${status} to the state request` : error.code; } } } if (error instanceof Error && error.name === "LinkRelayAuthenticationError") return error.message; return `the ${peer} state could not be read`; } export interface ResolveHubStateOptions { owner: HubStateOwner; /** The per-client data key. Null when the token file is missing or unsafe. */ token: string | null; /** * Why the caller withheld the token, when it withheld one it holds. A null token reads the * same here whether the file is missing or the caller declined to send a perfectly good * token for a different connection, and the operator acts on that difference. */ withheldTokenReason?: string; /** Identity-checked local Child transport that strips credentials and owns Home admission. */ localRelayFetchImpl?: typeof fetch; timeoutMs?: number; fetchImpl?: typeof fetch; now?: number; /** False reads only the cache — for paths that must not make a network call. */ allowNetwork?: boolean; /** False skips the cache write, for read-only callers. */ persist?: boolean; /** Which peer the sentences name: a hub, or a Remote Link Child's Home. */ peer?: "hub" | "Home"; } function withAge( source: HubStateSource, state: HubStateDTO | null, fetchedAt: string | undefined, now: number, reason?: string, ): HubStateResolution { const ageSeconds = fetchedAt ? Math.max(0, Math.floor((now - Date.parse(fetchedAt)) / 1000)) : undefined; return { stateSource: source, state, ...(reason ? { reason } : {}), ...(fetchedAt ? { fetchedAt } : {}), ...(ageSeconds === undefined || Number.isNaN(ageSeconds) ? {} : { ageSeconds }), }; } export async function resolveHubState(options: ResolveHubStateOptions): Promise<HubStateResolution> { const now = options.now ?? Date.now(); const fromCache = (reason: string): HubStateResolution => { const cached = readCachedHubState(options.owner); return cached ? withAge("cache", cached.state, cached.fetchedAt, now, reason) : withAge("unavailable", null, undefined, now, reason); }; if (!options.token && !options.localRelayFetchImpl) { return fromCache(options.withheldTokenReason ?? "this client has no usable data-plane token"); } if (options.allowNetwork === false) return fromCache("a live hub read was not attempted"); let state: HubStateDTO; try { state = await fetchHubState(options.owner.serverUrl, options.localRelayFetchImpl ? null : options.token, { timeoutMs: options.timeoutMs ?? DEFAULT_HUB_STATE_TIMEOUT_MS, ...((options.localRelayFetchImpl ?? options.fetchImpl) ? { fetchImpl: options.localRelayFetchImpl ?? options.fetchImpl } : {}), }); } catch (error) { // Deliberately no local-state fallback here. A stale cache is still the HUB's state; the // client's own providers and logins are not, at any age. if (error instanceof HubClientError && error.code === "hub_state_not_a_hub") return withAge("unavailable", null, undefined, now, hubStateFailureReason(error, options.peer)); return fromCache(hubStateFailureReason(error, options.peer)); } const fetchedAt = new Date(now).toISOString(); if (options.persist !== false) writeCachedHubState(options.owner, state, fetchedAt); return withAge("hub", state, fetchedAt, now); }