@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
528 lines (491 loc) • 18.2 kB
text/typescript
import type { NativeResponseControl } from "./responses/native-response-control";
import type { ServerWebSocket } from "bun";
import { responsesJsonEventSequence } from "./responses-json-events";
import { FORWARD_HEADERS } from "../adapters/openai-responses";
import type { CodexAuthContext } from "../codex/auth-context";
import { headersForCodexAuthContext } from "../codex/auth-context";
import type { ResponsesTerminalStatus } from "../bridge";
import type { DataPlaneAdmission } from "./auth-cors";
import type { AdmissionLease, AdmissionReservation } from "../lib/admission";
import { BoundedSseFrameBuffer } from "./sse-frame-buffer";
import { safeResponseHeaders } from "./safe-response-headers";
import type { AudioSocketTarget } from "./audio-dictation";
export { safeResponseHeaders } from "./safe-response-headers";
const OPEN = 1;
type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
type ResponsesPayloadObserver = (payload: string) => void;
export interface WsData {
nativeControl?: NativeResponseControl;
/** Content-free per-turn explanation; never a model capability assertion. */
nativeSteeringUnavailable?: string;
headers?: Headers; // base inbound forward headers only; per-turn auth refresh injects current pool tokens
/**
* Resolved once at the handshake. Auth is handshake-time only on this path, so
* the per-frame log contexts have no request headers left to re-resolve from.
* Optional like every other member here: a socket object can exist before the
* handshake fills it, and an unattributed frame is preferable to a fabricated
* attribution.
*/
admission?: DataPlaneAdmission;
authContext?: CodexAuthContext; // last resolved account decision for observability/registry cleanup
cancel?: () => void; // cancels the in-flight stream reader/fetch
turnId?: number; // monotonically increasing per socket; prevents stale frames after replacement turns
/** Fixed-size logical session lane derived at the HTTP upgrade boundary. */
sessionLaneId?: string;
/** Discriminator: Responses reframing vs transparent live/realtime sideband relay. */
kind?: "responses" | "live-sideband" | "remote-workspace-agent";
remoteWorkspaceConnection?: { receive(raw: string | Uint8Array): void };
remoteWorkspaceOpen?: (socket: ServerWebSocket<WsData>) => { receive(raw: string | Uint8Array): void };
remoteWorkspaceClose?: () => void;
liveUpstream?: WebSocket;
liveUpstreamUrl?: string;
liveUpstreamHeaders?: Record<string, string>;
liveUpstreamProtocols?: string[];
liveValidateFrame?: AudioSocketTarget["validateFrame"];
liveFinish?: AudioSocketTarget["finish"];
liveOutcome?: number | "timeout" | "connect_error";
liveMaxSessionMs?: number;
liveConnectTimer?: ReturnType<typeof setTimeout>;
liveSessionTimer?: ReturnType<typeof setTimeout>;
liveAbortSignal?: AbortSignal;
liveAbortListener?: () => void;
livePending?: Array<string | Buffer>;
/** Total encoded bytes retained in livePending while the upstream connects. */
livePendingBytes?: number;
liveOpened?: boolean;
/** Owns captured frames and terminal state until the downstream relay attaches. */
liveUpstreamHandoff?: LiveSidebandUpstreamHandoff;
/** Once teardown starts, ignore new client frames until the upstream closes. */
liveClosing?: boolean;
/** Schedules one bounded close retry without surrendering native-main ownership. */
liveCloseFallback?: ReturnType<typeof setTimeout>;
/** Turn/account ownership retained for the complete sideband socket lifetime. */
liveTurnAdmissionLease?: AdmissionLease;
admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>;
}
export interface LiveSidebandUpstreamFailure {
status: number;
code: string;
message: string;
closeCode?: number;
closeReason?: string;
}
export type LiveSidebandUpstreamTakeover =
| { ok: true; frames: Array<string | Buffer> }
| { ok: false; failure: LiveSidebandUpstreamFailure };
export interface LiveSidebandUpstreamHandoff {
/** Observe failure before the downstream upgrade without ending capture. */
failure(): LiveSidebandUpstreamFailure | undefined;
/** Atomically ends capture and transfers buffered frames or terminal state. */
take(): LiveSidebandUpstreamTakeover;
}
/**
* Build the Responses WebSocket upgrade payload.
*
* Extracted so the handshake's contract is testable: `server.upgrade` hands its
* `data` straight to the socket, and a client has no way to read `ws.data` back.
* A test that only asserts "the socket opened" would still pass if the admission
* were dropped from the payload, so the payload itself is what gets asserted.
*/
export function buildResponsesWsData(
headers: Headers,
admission: DataPlaneAdmission,
admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>,
sessionLaneId?: string,
): WsData {
// Auth is handshake-time only on this path: the per-frame contexts have no
// request headers left to re-resolve from, so the decision rides along here.
return {
headers,
admission,
...(admissionLease ? { admissionLease } : {}),
...(sessionLaneId ? { sessionLaneId } : {}),
};
}
export class WsSendDroppedError extends Error {
constructor() {
super("websocket send dropped the message");
}
}
export function selectForwardHeaders(
headers: Headers,
codexOverride?: { accessToken: string; chatgptAccountId: string },
): Headers {
const selected = new Headers();
for (const name of FORWARD_HEADERS) {
const value = headers.get(name);
if (value) selected.set(name, value);
}
if (codexOverride) {
selected.set("authorization", `Bearer ${codexOverride.accessToken}`);
selected.set("chatgpt-account-id", codexOverride.chatgptAccountId);
}
return selected;
}
export function selectForwardHeadersForAuthContext(headers: Headers, ctx: CodexAuthContext): Headers {
return headersForCodexAuthContext(headers, ctx);
}
export function buildWarmupCompletionFrames(frame: Record<string, unknown>): string[] {
const createdAt = Math.floor(Date.now() / 1000);
const baseResponse: Record<string, unknown> = {
id: "",
object: "response",
created_at: createdAt,
model: typeof frame.model === "string" ? frame.model : undefined,
output: [],
};
return [
JSON.stringify({
type: "response.created",
sequence_number: 0,
response: { ...baseResponse, status: "in_progress" },
}),
JSON.stringify({
type: "response.completed",
sequence_number: 1,
response: { ...baseResponse, status: "completed" },
}),
];
}
export function sendTextFrame(ws: ServerWebSocket<WsData>, payload: string): void {
if (ws.readyState !== OPEN) throw new WsSendDroppedError();
const result = ws.send(payload);
if (result === 0) throw new WsSendDroppedError();
// Bun returns -1 when queued with backpressure. That is accepted; a later 0 is the hard failure.
}
export function sendJsonFrame(ws: ServerWebSocket<WsData>, payload: Record<string, unknown>): void {
sendTextFrame(ws, JSON.stringify(payload));
}
export function buildWsErrorFrame(
status: number,
error: Record<string, unknown>,
headers?: Headers,
): Record<string, unknown> {
return {
type: "error",
status,
error,
headers: headers ? safeResponseHeaders(headers) : {},
};
}
function parseSseBlock(block: string): string | null {
const data: string[] = [];
for (const line of block.split(/\r?\n/)) {
if (line.startsWith("data:")) {
const value = line.slice(5);
data.push(value.startsWith(" ") ? value.slice(1) : value);
}
}
return data.length > 0 ? data.join("\n") : null;
}
function payloadType(payload: string): string | null {
try {
const json = JSON.parse(payload) as { type?: unknown };
return typeof json.type === "string" ? json.type : null;
} catch {
return null;
}
}
function terminalStatusFromType(type: string): ResponsesTerminalStatus | null {
switch (type) {
case "response.completed":
return "completed";
case "response.failed":
return "failed";
case "response.incomplete":
return "incomplete";
default:
return null;
}
}
function protocolError(message: string): Record<string, unknown> {
return {
type: "protocol_error",
code: "websocket_protocol_error",
message,
};
}
function sendProtocolError(ws: ServerWebSocket<WsData>, status: number, message: string): void {
sendJsonFrame(ws, buildWsErrorFrame(status, protocolError(message)));
}
/**
* Report an upstream-pump failure to the client. Errors that carry a structured
* code (for example the undeclared-tool guard's undeclared_tool_call) keep it so
* clients see the same rejection identity as the SSE path; everything else stays
* a generic protocol error.
*/
function sendUpstreamError(ws: ServerWebSocket<WsData>, status: number, err: unknown): void {
const code = err != null && typeof (err as { code?: unknown }).code === "string"
? (err as { code: string }).code
: undefined;
const message = err instanceof Error ? err.message : String(err);
sendJsonFrame(ws, buildWsErrorFrame(status, code
? { type: "upstream_error", code, message }
: protocolError(message)));
}
export async function pumpResponsesSseToWebSocket(
ws: ServerWebSocket<WsData>,
sseStream: ReadableStream<Uint8Array>,
options: {
isCurrent?: () => boolean;
untilEof?: boolean;
onTerminal?: ResponsesTerminalReporter;
onSsePayload?: ResponsesPayloadObserver;
} = {},
): Promise<void> {
const reader = sseStream.getReader();
const isCurrent = options.isCurrent ?? (() => true);
let clientCancelled = false;
let terminalReported = false;
const reportTerminal = (status: ResponsesTerminalStatus) => {
if (terminalReported || clientCancelled || !isCurrent()) return;
terminalReported = true;
options.onTerminal?.(status);
};
const cancel = () => {
clientCancelled = true;
void reader.cancel().catch(() => {});
};
ws.data.cancel = cancel;
const decoder = new TextDecoder();
const framer = new BoundedSseFrameBuffer();
let terminalSeen = false;
let lastTerminal: ResponsesTerminalStatus | undefined;
const handlePayload = (payload: string): boolean => {
if (!isCurrent()) return true;
if (payload === "[DONE]") return false;
try {
options.onSsePayload?.(payload);
} catch {
/* payload observation must not affect WebSocket delivery */
}
const type = payloadType(payload);
if (!type) {
reportTerminal("incomplete");
sendProtocolError(ws, 502, "Invalid JSON payload in upstream SSE frame");
terminalSeen = true;
void reader.cancel().catch(() => {});
return true;
}
if (terminalSeen) return true;
sendTextFrame(ws, payload);
if (options.untilEof && type === "response.created") lastTerminal = undefined;
const terminalStatus = type === "error" && options.untilEof ? "failed" : terminalStatusFromType(type);
if (terminalStatus) {
if (options.untilEof) { lastTerminal = terminalStatus; return false; }
reportTerminal(terminalStatus);
terminalSeen = true;
void reader.cancel().catch(() => {});
return true;
}
return false;
};
try {
while (!terminalSeen) {
const { done, value } = await reader.read();
if (done) break;
for (const frame of framer.feed(value)) {
const payload = parseSseBlock(decoder.decode(frame.block));
if (payload && handlePayload(payload)) break;
}
}
const tail = framer.finish();
if (!terminalSeen && tail.byteLength > 0) {
const payload = parseSseBlock(decoder.decode(tail));
if (payload) handlePayload(payload);
}
if (options.untilEof && lastTerminal && isCurrent() && !clientCancelled) {
reportTerminal(lastTerminal);
terminalSeen = true;
}
if (!terminalSeen && isCurrent() && !clientCancelled) {
reportTerminal("incomplete");
sendProtocolError(ws, 502, "Upstream stream ended before response terminal event");
}
} catch (err) {
framer.dispose();
if (err instanceof WsSendDroppedError) throw err;
if (!terminalSeen
&& isCurrent()
&& ws.readyState === OPEN
&& !(err instanceof WsSendDroppedError)) {
reportTerminal("incomplete");
try {
sendUpstreamError(ws, 502, err);
} catch (sendErr) {
// If delivery is already dropped, there is no useful error frame left
// to send. Swallow only that expected transport signal; other failures
// still surface to the caller after the upstream reader is released.
if (!(sendErr instanceof WsSendDroppedError)) throw sendErr;
}
}
} finally {
framer.dispose();
// Framing errors can occur while the upstream body is still live. Always
// release the reader, even when terminal/send paths already cancelled it.
void reader.cancel().catch(() => {});
if (ws.data.cancel === cancel) ws.data.cancel = undefined;
}
}
export function sendResponsesJsonAsEvents(
ws: ServerWebSocket<WsData>,
response: Record<string, unknown>,
onTerminal?: ResponsesTerminalReporter,
onPayload?: ResponsesPayloadObserver,
): void {
const sendObservedFrame = (payload: Record<string, unknown>) => {
const text = JSON.stringify(payload);
try {
onPayload?.(text);
} catch {
/* payload observation must not affect WebSocket delivery */
}
sendTextFrame(ws, text);
};
const finalStatus = response.status === "failed" || response.status === "incomplete"
? response.status
: "completed";
for (const frame of responsesJsonEventSequence(response)) {
sendObservedFrame(frame);
}
onTerminal?.(finalStatus);
}
function errorPayloadFromText(text: string): Record<string, unknown> {
try {
const json = JSON.parse(text) as { error?: unknown };
if (json.error && typeof json.error === "object" && !Array.isArray(json.error)) {
return json.error as Record<string, unknown>;
}
} catch {
/* fall through */
}
return {
type: "upstream_error",
message: text ? text.slice(0, 500) : "Upstream request failed",
};
}
export async function sendResponseToWebSocket(
ws: ServerWebSocket<WsData>,
response: Response,
isCurrent: () => boolean,
options: {
untilEof?: boolean;
onTerminal?: ResponsesTerminalReporter;
onSsePayload?: ResponsesPayloadObserver;
} = {},
): Promise<void> {
if (!isCurrent()) {
await response.body?.cancel().catch(() => {});
return;
}
if (!response.ok) {
const text = await response.text().catch(() => "");
if (!isCurrent()) return;
sendJsonFrame(ws, buildWsErrorFrame(response.status, errorPayloadFromText(text), response.headers));
return;
}
const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
if (!response.body) {
options.onTerminal?.("incomplete");
sendJsonFrame(ws, buildWsErrorFrame(502, {
type: "protocol_error",
code: "websocket_protocol_error",
message: `Unexpected successful upstream response without a body (${response.status})`,
}, response.headers));
return;
}
if (contentType.includes("text/event-stream")) {
await pumpResponsesSseToWebSocket(ws, response.body, {
isCurrent,
untilEof: options.untilEof,
onTerminal: options.onTerminal,
onSsePayload: options.onSsePayload,
});
return;
}
if (contentType.includes("application/json")) {
const text = await response.text();
if (!isCurrent()) return;
const json = JSON.parse(text) as Record<string, unknown>;
sendResponsesJsonAsEvents(ws, json, options.onTerminal, options.onSsePayload);
return;
}
const { prefix, stream } = await readBoundedPrefix(response.body);
if (!isCurrent()) {
await stream.cancel().catch(() => {});
return;
}
if (looksLikeSse(prefix)) {
await pumpResponsesSseToWebSocket(ws, stream, {
isCurrent,
untilEof: options.untilEof,
onTerminal: options.onTerminal,
onSsePayload: options.onSsePayload,
});
return;
}
const text = await new Response(stream).text();
if (!isCurrent()) return;
const trimmed = text.trim();
if (trimmed.startsWith("{")) {
const json = JSON.parse(trimmed) as Record<string, unknown>;
sendResponsesJsonAsEvents(ws, json, options.onTerminal, options.onSsePayload);
return;
}
options.onTerminal?.("incomplete");
sendJsonFrame(ws, buildWsErrorFrame(502, {
type: "protocol_error",
code: "websocket_protocol_error",
message: `Unexpected successful non-SSE upstream response (${contentType || "missing content-type"})`,
}, response.headers));
}
export async function readBoundedPrefix(
body: ReadableStream<Uint8Array>,
maxBytes = 4096,
): Promise<{ prefix: Uint8Array; stream: ReadableStream<Uint8Array> }> {
const reader = body.getReader();
const chunks: Uint8Array[] = [];
let remainder: Uint8Array | undefined;
let total = 0;
while (total < maxBytes) {
const { done, value } = await reader.read();
if (done) break;
const take = Math.min(value.byteLength, maxBytes - total);
if (take > 0) {
chunks.push(value.slice(0, take));
total += take;
}
if (take < value.byteLength) {
remainder = value.slice(take);
break;
}
}
const prefix = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
prefix.set(chunk, offset);
offset += chunk.byteLength;
}
const stream = new ReadableStream<Uint8Array>({
start(controller) {
if (prefix.byteLength > 0) controller.enqueue(prefix);
if (remainder && remainder.byteLength > 0) controller.enqueue(remainder);
},
async pull(controller) {
const { done, value } = await reader.read();
if (done) {
controller.close();
return;
}
controller.enqueue(value);
},
cancel(reason) {
return reader.cancel(reason);
},
});
return { prefix, stream };
}
export function looksLikeSse(prefix: Uint8Array): boolean {
const text = new TextDecoder().decode(prefix);
return /^\s*(event:|data:)/.test(text);
}