@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
text/typescript
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;
}