@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
236 lines (221 loc) • 11.4 kB
text/typescript
import { OPENAI_API_RESPONSES_URL } from "./native-response-control";
import { isInjectionRequest } from "./native-injection-protocol";
import type { NativeResponseControl } from "./native-response-control";
// Upstream WebSocket transport for the ChatGPT Codex backend.
//
// Why this exists: the Codex backend serves the responses_websockets path from
// a measurably faster queue than the plain SSE POST path. Measured 2026-08-12
// KST (same account, same payload, strictly sequential): gpt-5.6-luna TTFT p50
// ~1.0s over WS vs ~3.9s over SSE. Codex CLI itself defaults to the WS
// transport; opencodex previously always POSTed SSE, which is where its extra
// 2-3s of TTFT came from.
//
// The wrapper only swaps the transport. It dials wss:// with the same headers,
// sends the JSON body as a single `response.create` frame, and re-encodes the
// returned event frames as an SSE byte stream, so every downstream consumer
// (passthrough relay, adapter parsers, usage sniffing) is unchanged.
import { compareBunVersions } from "../../lib/bun-stream-caps";
import { resolveProxyRoute, socks5ProxyFromEnv } from "../../lib/proxy-env";
import type { CodexWsQuotaObserver } from "./codex-ws-metadata";
import { CODEX_RESPONSES_HTTP_URL, CODEX_RESPONSES_WS_URL, CODEX_WS_FRAME_HEADERS, prepareCodexHttpInit, prepareCodexWsRequest } from "./codex-ws-request";
import { codexWsExchange } from "./codex-ws-exchange";
import { CodexWsSession } from "./codex-ws-session";
import { codexWsPool, codexWsReuseIdentity } from "./codex-ws-pool";
import { codexWsCreateFrameExceedsLimit } from "./codex-ws-wire";
import { isLoopbackUrl, rewriteWebSocketDial } from "../../plugins/upstream-hooks";
export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES,
MAX_CODEX_WS_CREATE_FRAME_BYTES, CODEX_WS_CREATE_FRAME_LIMIT_BYTES, codexWsCreateFrameExceedsLimit,
isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./codex-ws-wire";
export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
/**
* Dial URL for a first-party Responses endpoint. The canonical ChatGPT backend
* keeps its constant; the api.openai.com Responses endpoint swaps https for wss
* on the same path. No other upstream may enter the WebSocket lane.
*/
function wsUpstreamUrlFor(httpUrl: string): string {
if (httpUrl === CODEX_RESPONSES_HTTP_URL) return CODEX_RESPONSES_WS_URL;
if (httpUrl === OPENAI_API_RESPONSES_URL) return httpUrl.replace(/^http(s?):/, "ws$1:");
throw new Error("unsupported Codex WebSocket upstream");
}
export type BunRuntimeIdentity = {
version: string;
versionWithSha: string;
};
export type BunRuntimeGateInput = string | BunRuntimeIdentity;
export function currentBunRuntimeIdentity(): BunRuntimeIdentity {
return {
version: Bun.version,
versionWithSha: Bun.version_with_sha,
};
}
function boundedRelayVersion(input: BunRuntimeGateInput): string | null {
if (typeof input === "string") return input.trim() || null;
const numericVersion = input.version.trim();
const numericMatch = /^(\d+\.\d+\.\d+)$/.exec(numericVersion);
const detailedMatch = /^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\s+\([0-9a-fA-F]+\)$/.exec(
input.versionWithSha.trim(),
);
if (!numericMatch || !detailedMatch) return null;
const detailedNumeric = /^(\d+\.\d+\.\d+)/.exec(detailedMatch[1])?.[1];
return detailedNumeric === numericMatch[1] ? detailedMatch[1] : null;
}
/**
* Bun 1.3.14 does not propagate a stalled HTTP response socket back to a JS
* ReadableStream producer on Windows. A real raw-TCP slow-client probe drained
* the entire upstream despite the eager relay queue; Bun 1.4.0-canary.1 stopped
* below one MiB. Prereleases still fail closed; release builds before 1.4.0
* fall back to HTTP SSE.
*/
export function bunSupportsBoundedCodexWsRelay(
runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
): boolean {
const version = boundedRelayVersion(runtime);
if (!version) return false;
if (/^\d+\.\d+\.\d+-/.test(version.trim())) return false;
const comparison = compareBunVersions(version, MIN_BOUNDED_CODEX_WS_BUN_VERSION);
return comparison !== null && comparison >= 0;
}
/**
* Apply plugin rewrites to one Codex WebSocket dial and settle its proxy. `proxy` was resolved
* for the canonical `wsUrl`. A loopback rewrite dials directly; any other rewrite gets its own
* route (scheme and `NO_PROXY` may differ). Null means the rewritten destination needs the SSE
* fallback, exactly as an unusable route for the canonical URL does.
*/
export function planCodexWsDial(
wsUrl: string,
headers: Record<string, string>,
proxy: string | undefined,
env: Parameters<typeof resolveProxyRoute>[1] = process.env,
): { url: string; headers: Record<string, string>; proxy: string | undefined } | null {
const rewritten = rewriteWebSocketDial(wsUrl, headers, proxy);
// Per-turn headers ride in each frame's client_metadata, which was prepared before the rewrite
// and is authoritative; a pooled socket's upgrade copy is intentionally ignored. A rewriter
// therefore cannot change them here, and the upgrade keeps the values the frame carries.
const dialHeaders = { ...rewritten.headers };
for (const name of CODEX_WS_FRAME_HEADERS) {
if (Object.hasOwn(headers, name)) dialHeaders[name] = headers[name]!;
else delete dialHeaders[name];
}
const dial = { ...rewritten, headers: dialHeaders };
if (dial.url === wsUrl || isLoopbackUrl(dial.url)) return dial;
let destination: URL;
try {
destination = new URL(dial.url);
} catch {
return null;
}
const route = resolveProxyRoute(destination, env);
if (route.kind === "fallback") return null;
return { ...dial, proxy: route.kind === "proxy" ? route.proxy : undefined };
}
export function shouldUseCodexWsUpstream(
url: string,
init?: RequestInit,
runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
upstreamWebsocketConfigured?: boolean,
): boolean {
if (!bunSupportsBoundedCodexWsRelay(runtime)) return false;
if (socks5ProxyFromEnv()) return false;
if (url === CODEX_RESPONSES_HTTP_URL && upstreamWebsocketConfigured === false) return false;
// Bun's client WebSocket API delivers only fully assembled messages and has
// no enforceable inbound payload limit. Keep arbitrary provider endpoints on
// bounded HTTP/SSE until the client can reject fragmented text and binary
// messages during ingestion rather than after allocation. The first-party
// api.openai.com lane still requires the operator opt-in.
if (url !== CODEX_RESPONSES_HTTP_URL
&& !(upstreamWebsocketConfigured && url === OPENAI_API_RESPONSES_URL)) return false;
if ((init?.method ?? "GET").toUpperCase() !== "POST") return false;
const body = init?.body;
if (typeof body !== "string") return false;
// Only root-level stream:true selects WS: JSON-mode calls keep the HTTP path
// because the WS path only speaks the event protocol, and a nested
// {"metadata":{"stream":true}} must not flip the transport. Parsing (not
// substring matching) also keeps whitespace-formatted bodies routable.
try {
const parsed = JSON.parse(body) as unknown;
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
&& (parsed as Record<string, unknown>).stream === true;
} catch {
return false;
}
}
export function codexWsUpstreamFetch(
url: string,
init: RequestInit,
sseFallback: typeof globalThis.fetch,
runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
onQuota?: CodexWsQuotaObserver,
beforeDispatch?: (headers: Headers) => void,
nativeControl?: NativeResponseControl,
beforeContinuation?: () => Promise<void>,
): Promise<Response> {
const prepared = prepareCodexWsRequest(url, init);
if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
init = prepared.httpInit;
if ((url !== CODEX_RESPONSES_HTTP_URL && url !== OPENAI_API_RESPONSES_URL)
|| !bunSupportsBoundedCodexWsRelay(runtime)) {
return sseFallback(url, init);
}
const signal = init.signal ?? undefined;
if (signal?.aborted) {
return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
}
const { frameText, headers } = prepared;
// Never infer backend support from a model name or enable controls on a gateway.
const control = nativeControl?.kind === "injection"
? ((prepared.canonical || url === OPENAI_API_RESPONSES_URL) && isInjectionRequest(JSON.parse(frameText)) ? nativeControl : undefined)
: prepared.canonical ? nativeControl : undefined;
if (control?.kind === "injection" && url === OPENAI_API_RESPONSES_URL) {
const beta = headers["openai-beta"];
if (!beta?.split(",").some(value => value.trim() === "responses_multi_agent=v1")) {
headers["openai-beta"] = beta ? `${beta}, responses_multi_agent=v1` : "responses_multi_agent=v1";
}
}
// Decide before dialing. Once the socket is open the caller already holds a
// streaming Response, so the oversized close can only be surfaced as a stream
// error — and a resend at that point could double-generate. Measuring the
// frame we are about to send keeps the whole failure mode unreachable.
if (codexWsCreateFrameExceedsLimit(frameText)) {
return sseFallback(url, init);
}
const wsUrl = wsUpstreamUrlFor(url);
const proxyRoute = resolveProxyRoute(new URL(wsUrl));
if (proxyRoute.kind === "fallback") return sseFallback(url, init);
const proxy = proxyRoute.kind === "proxy" ? proxyRoute.proxy : undefined;
// A genuine caller `originator` is already in these headers via the forward
// set. Never fabricate one here: pool/forward traffic must not impersonate
// Codex CLI, per the metadata-integrity contract. (The backend's fast lane
// keys on WS + originator, so callers without the tag simply keep their own
// provenance and scheduling.)
// A local refusal is not a failed upgrade and must never enter the SSE fallback path.
try {
beforeDispatch?.(new Headers(headers));
} catch (error) {
return Promise.reject(error);
}
let session: CodexWsSession;
try {
// Steering keeps a private physical connection across successor responses; it
// must never enter the idle-socket pool or move to a different credential.
// Plugin rewrite runs per exchange, before the pool lookup. The dialled destination, its
// headers and its proxy are all part of the reuse identity, so a pooled socket is never
// reused for a different destination or with stale plugin headers.
const dial = planCodexWsDial(wsUrl, headers, proxy);
if (!dial) return sseFallback(url, init);
const identity = control ? null : codexWsReuseIdentity(url, dial.headers, frameText, dial.proxy, dial.url);
session = (identity ? codexWsPool.acquire(identity, dial.url, dial.headers, dial.proxy) : null)
?? new CodexWsSession(dial.url, dial.headers, false, undefined, dial.proxy);
if (!session.busy && !session.reserve()) {
session.dispose();
return sseFallback(url, init);
}
} catch {
return sseFallback(url, init);
}
return codexWsExchange({
session, url, init, prepared, sseFallback, onQuota, beforeDispatch,
nativeControl: control,
beforeContinuation,
bunVersion: typeof runtime === "string" ? runtime : runtime.version,
});
}