UNPKG

@bitkyc08/opencodex

Version:

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

506 lines (500 loc) • 24.4 kB
import { nativeSteeringUnavailableReason, nativeResponseControlMode, type NativeResponseControl } from "../responses/native-response-control"; import { NativeInjectionChannel } from "../responses/native-injection"; import { NativeSteeringChannel, NativeSteeringError } from "../responses/native-steering"; import { createNativeSteeringLogObserver } from "../responses/native-steering-log"; import { reasoningArchiveErrorResponse } from "../responses/reasoning-archive-error"; import { captureAdmissionPolicy } from "../capture-admission-policy"; import type { Server, ServerWebSocket } from "bun"; import { LIVE_SIDEBAND_UPSTREAM_OPEN_TIMEOUT_MS, MAX_WS_FRAME_BYTES, WEBSOCKET_IDLE_TIMEOUT_SECONDS, attachLiveSidebandUpstream, beginAudioFinalization, clientCloseForUpstream, closeLiveSideband, closeLiveSidebandBeforeUpgrade, enqueueLiveSidebandPendingFrame, exceedsLiveSidebandFrameByteLimit, openLiveSidebandUpstream, sendUpstreamFrame, webSocketFrameBytes, } from "./live-sideband"; import { markActivity } from "../../lib/sidecar-tracker"; import { isReplayRefusalResponse } from "../../lib/upstream-retry"; import { buildWarmupCompletionFrames, buildWsErrorFrame, selectForwardHeaders, sendJsonFrame, buildResponsesWsData, sendResponseToWebSocket, sendTextFrame, type WsData, } from "../ws-bridge"; import { CodexAccountCooldownError, CodexMainAccountHardLockError, cooldownErrorMessage, cooldownErrorResponse, } from "../../codex/auth-context"; import { codexAccountNamespaceForModel } from "../../codex/account-namespace-match"; import { registerCodexWebSocket, tryReserveCodexWebSocket, unregisterCodexWebSocket, updateCodexWebSocketAuthContext, } from "../../codex/websocket-registry"; import { formatErrorResponse, type ResponsesTerminalStatus, } from "../../bridge"; import { isDraining, registerTurn, tryAdmitTurn, unregisterTurn, type ActiveTurnLease, } from "../lifecycle"; import { addFinalRequestLog, httpStatusForRequestLogTerminal, inspectResponseLogSsePayload, nextRequestLogId, recordFirstOutput, type RequestLogContext, type RequestLogEntry, } from "../request-log"; import { corsHeaders, managementCorsHeaders, isAllowedRequestOrigin, isAllowedManagementOrigin, isApiAuthRequired, jsonResponse, admissionFields, resolveApiAuth, resolveResponsesApiAuth, isContextPrincipalCurrent, type RequestPolicyView, withCors, withManagementCors, } from "../auth-cors"; import { connectionReplayScopeLive, releaseConnectionReplayScope } from "../../responses/state/connection-scope"; import { disableResponsesRequestTimeout, handleResponses, handleResponsesCompact, } from "../responses"; import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade, } from "../live"; import type { ServeOptionsContext } from "./serve-options"; import type { RequestMetricsRecorder } from "../request-metrics"; import { attachParsedRequestBody, resolveInboundBodyLimitBytes } from "../request-decompress"; import { responseToolOwnership } from "../responses/response-tool-ownership"; import { runTurnStateCallerScope } from "../turn-state-handles"; import { runWithRequestPeer } from "../../lib/request-peer-scope"; /** The socket recorded a local peer at its upgrade; any other socket has no local snapshot. */ const LOCAL_PEER = Object.freeze({ local: true }); import { admitHttpWorkflowTurn, workflowDecisionRefusalResponse } from "../workflow-refusal"; /** * The WebSocket half of the Bun.serve options, split out of serve-options.ts to keep that file * under the 2,000-line ratchet threshold. The body is the original handler verbatim; it reads the * same startServer context the HTTP half does, so it takes the same context object. */ export function createWebsocketHandler( ctx: ServeOptionsContext, requestMetricsRecorder?: RequestMetricsRecorder, ) { const { config, deps } = ctx; return { maxPayloadLength: MAX_WS_FRAME_BYTES, idleTimeout: WEBSOCKET_IDLE_TIMEOUT_SECONDS, // Responses WebSocket data plane (phase 120.2). Re-frames the same SSE pipeline onto the // socket: parse response.create → run handleResponses unchanged → pump its SSE body as WS // Text frames. response.processed is a no-op ack. close() aborts the upstream (RC2 parity). // Live sideband sockets (kind=live-sideband) are a transparent bidirectional relay instead. open(ws: ServerWebSocket<WsData>) { if (ws.data.kind === "remote-workspace-agent") { const open = ws.data.remoteWorkspaceOpen; if (!open) { ws.close(1011, "remote workspace connection unavailable"); return; } try { ws.data.remoteWorkspaceConnection = open(ws); } catch { ws.close(1011, "remote workspace connection failed"); } return; } if (ws.data.kind === "live-sideband") { if (!ws.data.liveTurnAdmissionLease) { closeLiveSideband(ws, 1013, "server busy"); return; } attachLiveSidebandUpstream(ws, deps.liveSidebandWebSocketFactory); return; } if (!ws.data.admissionLease) { ws.close(1013, "server busy"); return; } ws.data.admissionLease.bind(ws); registerCodexWebSocket(ws); }, message(ws: ServerWebSocket<WsData>, raw: string | Buffer) { if (ws.data.kind === "remote-workspace-agent") { try { ws.data.remoteWorkspaceConnection?.receive(raw); } catch { ws.close(1008, "remote workspace protocol error"); } return; } if (ws.data.kind === "live-sideband") { if (ws.data.liveClosing) return; if (ws.data.liveValidateFrame && !ws.data.liveValidateFrame(raw)) { closeLiveSideband(ws, 1008, "invalid audio event"); return; } beginAudioFinalization(ws, raw); const rawBytes = webSocketFrameBytes(raw); if (exceedsLiveSidebandFrameByteLimit(rawBytes)) { closeLiveSideband(ws, 1009, "message too large"); return; } logLiveSidebandFrame("c2u", raw); const upstream = ws.data.liveUpstream; if (!upstream || upstream.readyState === WebSocket.CONNECTING || !ws.data.liveOpened) { const enqueueResult = enqueueLiveSidebandPendingFrame(ws.data, raw, rawBytes); if (enqueueResult === "too-many-frames") { closeLiveSideband(ws, 1009, "too many pending frames"); return; } if (enqueueResult === "too-many-bytes") { closeLiveSideband(ws, 1009, "too many pending bytes"); return; } return; } if (upstream.readyState !== WebSocket.OPEN) { closeLiveSideband(ws, 1011, "upstream not open"); return; } try { sendUpstreamFrame(upstream, raw, ws.data.authContext); if (ws.data.liveMaxSessionMs !== undefined && upstream.bufferedAmount > MAX_WS_FRAME_BYTES) { closeLiveSideband(ws, 1013, "audio upstream backpressure"); } } catch { closeLiveSideband(ws, 1011, "upstream send failed"); } return; } if (ws.data.responsesActivity?.closing) return; ws.data.responsesActivity?.touch(); const rawBytes = typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength; if (rawBytes > MAX_WS_FRAME_BYTES) { sendJsonFrame(ws, buildWsErrorFrame(413, { type: "invalid_request_error", message: "WebSocket response.create frame is too large", })); ws.close(1009, "message too large"); return; } // An established control connection only ever carries control frames, so the // inbound body limit applies to raw bytes before the parse materializes them. if (ws.data.nativeControl && rawBytes > resolveInboundBodyLimitBytes(config.maxInboundBodyBytes)) { sendJsonFrame(ws, buildWsErrorFrame(413, { type: "invalid_request_error", code: "inbound_body_too_large", message: "Native response control frame exceeds the configured inbound body limit.", })); return; } let frame: Record<string, unknown>; try { frame = JSON.parse(typeof raw === "string" ? raw : raw.toString()) as Record<string, unknown>; } catch { return; // text-only contract; ignore unparseable frames } if ((frame.type === "response.inject" || frame.type === "response.steer") && rawBytes > resolveInboundBodyLimitBytes(config.maxInboundBodyBytes)) { sendJsonFrame(ws, buildWsErrorFrame(413, { type: "invalid_request_error", code: "inbound_body_too_large", message: "Native response control frame exceeds the configured inbound body limit.", })); return; } if (frame.type === "response.inject" || frame.type === "response.steer" || (frame.type === "response.create" && ws.data.nativeControl)) { try { // Remote Link sockets never carry native control (design T4 1.1); the link wrapper has // already re-checked this frame's authorization before it reached the shared handler. if (ws.data.nativeControlDisabled && frame.type !== "response.create") throw new NativeSteeringError("native_control_unavailable_on_link", "Native response control is unavailable on a Remote Link WebSocket."); if (frame.type === "response.inject") { if (!ws.data.nativeControl?.inject) throw new NativeSteeringError("injection_not_supported", "Native injection is disabled or unavailable on this route."); ws.data.nativeControl.inject(frame); ws.data.responsesActivity?.acceptResults(frame.input); return; } if (frame.type === "response.steer") { if (!ws.data.nativeControl) throw new NativeSteeringError("steering_not_supported", ws.data.nativeSteeringUnavailable ?? "Native steering transport is unavailable; the route may be unsupported or using HTTP fallback."); ws.data.nativeControl.steer(frame); return; } if (ws.data.nativeControl?.continue(frame)) { ws.data.responsesActivity?.acceptResults(frame.input); return; } } catch (error) { sendJsonFrame(ws, buildWsErrorFrame(400, { type: "invalid_request_error", code: error instanceof NativeSteeringError ? error.code : "native_steering_error", message: error instanceof NativeSteeringError ? error.message : "Native steering transport failed; delivery may be unknown. Do not automatically replay input.", })); return; } } if (frame.type === "response.processed") return; // ack — no-op if (frame.type !== "response.create") return; markActivity("ws response.create"); let nativeControl: NativeResponseControl | undefined; try { const idleMs = typeof config.stallTimeoutSec === "number" && Number.isFinite(config.stallTimeoutSec) ? Math.max(1, config.stallTimeoutSec) * 1000 : 300_000; const mode = ws.data.nativeControlDisabled ? undefined : nativeResponseControlMode(frame, config); nativeControl = mode === "injection" ? new NativeInjectionChannel(frame, idleMs, config.maxUpstreamBodyBytes) : mode === "steering" ? new NativeSteeringChannel(frame, idleMs, config.maxUpstreamBodyBytes) : undefined; } catch { sendJsonFrame(ws, buildWsErrorFrame(400, { type: "invalid_request_error", message: "Invalid native steering request settings" })); return; } ws.data.cancel?.(); // A superseded turn must not keep ownership during warmup or refusal. ws.data.nativeControl = undefined; ws.data.nativeSteeringUnavailable = nativeSteeringUnavailableReason(frame, config.codexNativeSteering); const turnId = (ws.data.turnId ?? 0) + 1; ws.data.turnId = turnId; const isCurrent = () => ws.data.turnId === turnId; const turnAbort = new AbortController(); const cancelTurn = () => { turnAbort.abort("websocket turn superseded or closed"); }; ws.data.cancel = cancelTurn; // A socket may carry several response.create frames. Clear the previous // account before resolving this frame so a failed Multi resolution cannot // leave stale invalidation ownership behind. updateCodexWebSocketAuthContext(ws, undefined); if (frame.generate === false) { for (const payload of buildWarmupCompletionFrames(frame)) { if (!isCurrent()) return; sendTextFrame(ws, payload); } if (ws.data.cancel === cancelTurn) ws.data.cancel = undefined; return; } const turnAdmissionLease = tryAdmitTurn(ws.data.sessionLaneId); if (!turnAdmissionLease) { sendJsonFrame(ws, buildWsErrorFrame(503, { type: "server_error", code: "server_busy", message: "active turns capacity reached", retryable: true, }, new Headers({ "Retry-After": "1" }))); if (ws.data.cancel === cancelTurn) ws.data.cancel = undefined; return; } // Only a genuinely admitted turn may receive steering or continuations. const advisorAdmissionPolicy = captureAdmissionPolicy(config, ws.data.admission); const finishActivity = ws.data.responsesActivity?.beginTurn(frame.input); const payload: Record<string, unknown> = { ...frame }; delete payload.type; turnAdmissionLease.bindAbortController(turnAbort); // The frame runs with its own caller slot, which admission fills for turn-state handle binding. void runWithRequestPeer(ws.data.peerLocal === true ? LOCAL_PEER : undefined, () => runTurnStateCallerScope(async () => { const start = Date.now(); const requestId = nextRequestLogId(start); // Resolved once at the handshake — a frame has no request headers left // to re-resolve from. Optional on WsData like every other member, so // narrow rather than assume: an unattributed frame is preferable to a // fabricated attribution. const wsAdmission = ws.data.admission; const logCtx: RequestLogContext = { model: "unknown", provider: "unknown", ...(requestMetricsRecorder ? { requestMetricsRecorder } : {}), ...(wsAdmission ? admissionFields(wsAdmission) : {}), client: ws.data.client ?? "unknown", inboundProtocol: "responses", }; let logged = false; const finalizeLog = ( status: number, meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">, ) => { if (logged) return; logged = true; addFinalRequestLog(requestId, start, logCtx, status, meta); }; const baseHeaders = ws.data.headers ?? new Headers(); const fwd = new Headers({ "content-type": "application/json" }); baseHeaders.forEach((value, key) => fwd.set(key, value)); // A Remote Link socket hands the pipeline the create it parsed (#8600): serializing it into the request and // parsing it back would hold two more request-sized copies for the turn. Local sockets keep the request body. // turnBody is a shallow copy: preparation's in-place edits to nested input reach frame.input too, which the // socket's activity book reads again later, for the array's identity and each result's type and ids only. const turnBody = { ...payload, stream: true }; const linkSocket = ws.data.link !== undefined; const req = new Request("http://localhost/v1/responses", { method: "POST", headers: fwd, ...(linkSocket ? {} : { body: JSON.stringify(turnBody) }), }); if (linkSocket) attachParsedRequestBody(req, turnBody); try { // A socket can be the first ingress for a root. Admit every inference frame, // then keep its workflow lease with the turn until terminal output or cancellation. const workflow = admitHttpWorkflowTurn(req.headers); if (workflow && !workflow.admitted) { const refusal = workflowDecisionRefusalResponse(workflow, logCtx); await sendResponseToWebSocket(ws, refusal, isCurrent); finalizeLog(refusal.status); return; } if (workflow?.admitted) turnAdmissionLease.attach(workflow.lease); ws.data.nativeControl = nativeControl; let terminalRecorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined; const retainedPrincipal = ws.data.replayPrincipal; const replayPrincipal = retainedPrincipal && (isContextPrincipalCurrent(retainedPrincipal.clientPrincipalId, config) ? retainedPrincipal : { clientPrincipalId: undefined }); // The connection scope is a live-socket capability, not a retained credential: // once closed or expired it stops backfilling the replay owner entirely. const retainedScope = ws.data.replayScope; const replayScope = retainedScope && connectionReplayScopeLive(retainedScope) ? retainedScope : undefined; const response = await handleResponses(req, config, logCtx, { advisorAdmissionPolicy, ...(wsAdmission ? { admission: wsAdmission } : {}), // Keep an empty holder after revocation: a different forwarded bearer // must not become this connection's retained replay owner. ...(replayPrincipal ? { replayPrincipal } : {}), ...(replayScope ? { replayScope } : {}), forceEmptyResponseId: true, inboundTransport: "websocket", nativeControl, ...(ws.data.linkTurnObserver ? { linkTurn: ws.data.linkTurnObserver(turnId) } : {}), abortSignal: turnAbort.signal, turnAdmissionLease, onFirstOutput: () => recordFirstOutput(logCtx, start), onCodexAuthContextResolved: context => updateCodexWebSocketAuthContext(ws, context), recordTerminalOutcomes: false, setTerminalOutcomeRecorder: recorder => { terminalRecorder = recorder; }, }); // This ingress finalizes directly, without the HTTP deferred logger. // Preserve recorder provenance before framing a synthetic 429 as a WS error. if (isReplayRefusalResponse(response)) { logCtx.causeHint = "transport-ambiguous"; logCtx.terminalSource = "synthetic"; } // Remote Link holds release only for a turn every admission accepted (link-websocket.ts). if (response.ok) ws.data.responsesActivity?.notifyAccepted(frame.input); const observeLog = nativeControl?.relayActive ? createNativeSteeringLogObserver(logCtx, () => recordFirstOutput(logCtx, start)) : (payload: string) => inspectResponseLogSsePayload(logCtx, payload); const providerExecuted = responseToolOwnership(response); await sendResponseToWebSocket(ws, response, isCurrent, { // A native-control body is the upstream itself, with no relay tail behind it. untilEof: nativeControl?.relayActive === true, rawUpstream: nativeControl?.relayActive === true, onSsePayload: payload => { ws.data.responsesActivity?.observePayload(payload, providerExecuted); observeLog(payload); }, onTerminal: status => { terminalRecorder?.(status, logCtx.terminalHttpStatus); finalizeLog(httpStatusForRequestLogTerminal(status, logCtx), { terminalStatus: status, closeReason: "terminal", }); }, }); if (!logged) finalizeLog(turnAbort.signal.aborted ? 499 : response.status); } catch (err) { if (!isCurrent()) return; try { if (err instanceof CodexAccountCooldownError) { finalizeLog(429); // Codex Desktop rides this WS transport, so it must carry the same // actionable text as HTTP; a frame has no headers, hence message-only. const accountSelector = typeof payload.model === "string" ? codexAccountNamespaceForModel(config.codexAccountNamespaces, payload.model) : undefined; if (err instanceof CodexMainAccountHardLockError) { // Same terminal usage-limit body and Retry-After as HTTP (#7046). const refusal = cooldownErrorResponse(err, Date.now(), accountSelector); const body = await refusal.json() as { error: Record<string, unknown> }; sendJsonFrame(ws, buildWsErrorFrame(429, body.error, refusal.headers)); return; } sendJsonFrame(ws, buildWsErrorFrame(429, { type: "rate_limit_error", message: cooldownErrorMessage(err, accountSelector), })); return; } // A local archive refusal happens before any send. Carry the same sanitized 503 // body and stable code as HTTP so no filesystem path reaches the client frame. const archiveError = reasoningArchiveErrorResponse(err); if (archiveError) { finalizeLog(archiveError.status); const body = await archiveError.json() as { error: Record<string, unknown> }; sendJsonFrame(ws, buildWsErrorFrame(archiveError.status, body.error)); return; } finalizeLog(502); sendJsonFrame(ws, buildWsErrorFrame(502, { type: "proxy_error", message: err instanceof Error ? err.message : String(err), })); } catch { /* socket already gone or send dropped */ } } finally { finishActivity?.(); turnAdmissionLease.release(); if (ws.data.nativeControl === nativeControl) ws.data.nativeControl = undefined; if (!logged && turnAbort.signal.aborted) finalizeLog(499); ws.data.linkTurnEnded?.(turnId); if (ws.data.cancel === cancelTurn) ws.data.cancel = undefined; } })); }, close(ws: ServerWebSocket<WsData>, code: number, reason: string) { if (ws.data.kind === "remote-workspace-agent") { ws.data.remoteWorkspaceClose?.(); return; } if (ws.data.kind === "live-sideband") { // Carry the client's own close through to the upstream instead of reporting every // hang-up as a plain 1000. const forwarded = clientCloseForUpstream(code, reason); closeLiveSideband(ws, forwarded.code, forwarded.reason); return; } unregisterCodexWebSocket(ws); ws.data.admissionLease?.release(); ws.data.admissionLease = undefined; // Close the connection scope before cancelling the turn so a late completion // write is refused; then drop every entry this socket still owns. releaseConnectionReplayScope(ws.data.replayScope); ws.data.replayScope = undefined; ws.data.cancel?.(); // RC2: abort the upstream when the client disconnects }, } as const; }