UNPKG

@bitkyc08/opencodex

Version:

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

137 lines (122 loc) • 6.83 kB
/** * Home and Child compatibility over a Remote Link. * * `LINK_PROTOCOL_RELEASES` is the published record of which release first spoke each part of the * link protocol. It is history, so it cannot be derived at run time; `tests/clients/link-peer- * compatibility.test.ts` holds every id to the live feature registry and every release to the * package version. The verdict uses only what the link carries: the relay-auth version of a * verified challenge and, from 2.91.0, the Child's own version and feature report * (`src/link/peer-report.ts`). */ import { LINK_RELAY_AUTH_VERSION } from "./relay-auth"; import { LINK_PEER_REPORT_VERSION, type LinkPeerEntry } from "./peer-report"; import { LINK_REQUEST_ZSTD_FEATURE } from "./request-compression"; export interface LinkProtocolRelease { /** The peer feature id, as `GET /readyz` lists it. */ readonly id: string; /** First release that speaks it on both sides of a link. */ readonly since: string; readonly summary: string; } export const LINK_PEER_REPORT_FEATURE = `link-peer-report/${LINK_PEER_REPORT_VERSION}`; export const LINK_PROTOCOL_RELEASES: readonly LinkProtocolRelease[] = [ { id: "relay-auth/2", since: "2.69.0", summary: "Connection-bound relay authentication before every relayed request." }, { id: "link-management-relay", since: "2.84.0", summary: "Read-only Home management and Home Codex settings for the Child." }, { id: LINK_PEER_REPORT_FEATURE, since: "2.91.0", summary: "The Child reports its version and features on the relay challenge." }, // The dev line's version when this landed; 2.100.x was already tagged, so the release that first // ships it moves this to its own number (the test holds `since` at or below the package version). { id: LINK_REQUEST_ZSTD_FEATURE, since: "2.100.0", summary: "The Home decodes per-body zstd request bodies and the Child sends them." }, ]; /** * Features a Child uses only when its Home names them on the link, and otherwise works without: * per-body zstd falls back to identity bodies. A Child leaves them out of its peer report, because * a Home that predates one counts every feature it does not serve as used and would tell the owner * to upgrade it, and a Home never counts one against itself. */ export const LINK_OPTIONAL_CHILD_FEATURES: ReadonlySet<string> = new Set([LINK_REQUEST_ZSTD_FEATURE]); /** The feature ids a Child reports on the relay challenge. */ export function linkChildReportFeatures(features: readonly string[]): string[] { return features.filter(id => !LINK_OPTIONAL_CHILD_FEATURES.has(id)); } export type LinkCompatibilityVerdict = "compatible" | "degraded" | "incompatible" | "unknown"; export interface LinkLocalPeer { version: string; relayAuth: string; features: string[]; } export interface LinkPeerStatus { observedAt: string | null; /** The Child's reported release, or null when it predates the report. */ version: string | null; /** For an unreported version: the oldest release the observed protocol implies, and the first that would report. */ versionRange: { min: string | null; below: string } | null; relayAuth: string | null; features: string[] | null; compatibility: LinkCompatibilityVerdict; reasons: string[]; } function releaseParts(version: string): number[] { return version.split(/[-+]/, 1)[0]!.split(".").map(part => Number(part)); } export function compareReleases(a: string, b: string): number { const left = releaseParts(a), right = releaseParts(b); for (let i = 0; i < 3; i++) { const diff = (left[i] ?? 0) - (right[i] ?? 0); if (diff !== 0) return Math.sign(diff); } return 0; } function sinceOf(id: string): string | null { return LINK_PROTOCOL_RELEASES.find(release => release.id === id)?.since ?? null; } function relayAuthNumber(value: string): number { return /^\d{1,4}$/.test(value) ? Number(value) : Number.NaN; } export function linkPeerStatus(local: LinkLocalPeer, entry: LinkPeerEntry): LinkPeerStatus { const { observed, refused } = entry; if (refused && (!observed || observed.observedAt <= refused.refusedAt)) { const newerChild = relayAuthNumber(refused.relayAuth) > relayAuthNumber(local.relayAuth); return { observedAt: refused.refusedAt, version: null, versionRange: null, relayAuth: refused.relayAuth, features: null, compatibility: "incompatible", reasons: [`The Child speaks relay-auth/${refused.relayAuth} and this Home speaks relay-auth/${local.relayAuth}, so relayed requests are refused. Upgrade the ${newerChild ? "Home" : "Child"}.`], }; } if (!observed) { return { observedAt: null, version: null, versionRange: null, relayAuth: null, features: null, compatibility: "unknown", reasons: ["No relayed request from this Child since the Home started."], }; } const base = { observedAt: observed.observedAt, relayAuth: observed.relayAuth, features: observed.features }; if (!observed.reported) { return { ...base, version: null, versionRange: { min: sinceOf(`relay-auth/${observed.relayAuth}`), below: sinceOf(LINK_PEER_REPORT_FEATURE)! }, compatibility: "compatible", reasons: [`relay-auth/${observed.relayAuth} matches. The Child does not report its version; it predates ${LINK_PEER_REPORT_FEATURE}.`], }; } if (observed.version === null || observed.features === null) { // A reporting Child whose version or feature list was missing or rejected: the Home cannot tell what it uses. return { ...base, version: observed.version, versionRange: null, compatibility: "unknown", reasons: [`relay-auth/${observed.relayAuth} matches, but the Child's ${observed.version === null && observed.features === null ? "version and feature list were" : observed.version === null ? "version was" : "feature list was"} missing or invalid, so its features cannot be checked.`], }; } const childOnly = observed.features.filter(id => !local.features.includes(id) && !LINK_OPTIONAL_CHILD_FEATURES.has(id)); if (childOnly.length > 0) { return { ...base, version: observed.version, versionRange: null, compatibility: "degraded", reasons: [`The Child (${observed.version}) uses ${childOnly.join(", ")}, which this Home (${local.version}) does not serve. Upgrade the Home.`], }; } return { ...base, version: observed.version, versionRange: null, compatibility: "compatible", reasons: [compareReleases(observed.version, local.version) === 0 ? "Same release as this Home." : `relay-auth/${observed.relayAuth} matches and this Home (${local.version}) serves every feature the Child (${observed.version}) uses.`], }; } export function localLinkPeer(version: string, features: readonly string[]): LinkLocalPeer { return { version, relayAuth: LINK_RELAY_AUTH_VERSION, features: [...features] }; }