@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
369 lines (350 loc) • 15.2 kB
text/typescript
import type { ResponsesTerminalStatus } from "../../bridge";
import { responsesCompletionError } from "../../lib/errors";
import { ResponseBodyInactivityError } from "../../lib/response-body-inactivity";
import {
createSseInspector,
createSseTerminalOutputBoundary,
createTerminalStatusTracker,
SseAggregateLimitError,
type CodexSafetyBufferingFilterOptions,
type SseInspector,
} from "../relay";
import { SseFrameCountLimitError, SseFrameTooLargeError } from "../sse-frame-buffer";
import {
MAX_UPSTREAM_JSON_BODY_BYTES,
UPSTREAM_JSON_BODY_INACTIVITY_TIMEOUT_MS,
UPSTREAM_JSON_BODY_TOTAL_TIMEOUT_MS,
} from "./core-lifetime";
/** Larger than persistence inspection because this path must return the whole bounded response. */
export const MAX_BUFFERED_RESPONSES_OUTPUT_ITEMS = 10_000;
export const MAX_BUFFERED_RESPONSES_RECONSTRUCTION_BYTES = MAX_UPSTREAM_JSON_BODY_BYTES;
export const MAX_BUFFERED_RESPONSES_SSE_FRAMES = 100_000;
/**
* A buffered caller cannot consume partial output, so keep one independent lifetime ceiling even
* when the operator disables the ordinary silence clock. Fifteen minutes is intentionally much
* larger than the public default stall budget while still releasing an abandoned body eventually.
*/
export const BUFFERED_RESPONSES_TOTAL_TIMEOUT_MS = 15 * 60_000;
const BUFFERED_SSE_PROCESSING_SLICE_BYTES = 64 * 1024;
export type BufferedFailedCompletion = {
payload: unknown;
error: NonNullable<ReturnType<typeof responsesCompletionError>>;
};
export type BufferedResponsesTerminal = {
status: ResponsesTerminalStatus;
response: Record<string, unknown>;
failedCompletion?: undefined;
} | {
status: "failed";
failedCompletion: BufferedFailedCompletion;
};
export type BufferedResponsesSseFailure = {
ok: false;
kind: "aborted" | "malformed" | "missing_terminal" | "oversized" | "read_error" | "timeout";
error?: unknown;
/** Bounded diagnostic captured from a bare upstream `error` event. */
upstreamError?: string;
/** Fatal provider refusal verdict that must not be flattened into a retryable transport error. */
upstreamRefusalCode?: string;
/** Bounded structured class from the same bare error envelope as `upstreamError`. */
upstreamErrorType?: string;
/** Bounded structured code; unknown codes remain transport failures instead of message guesses. */
upstreamErrorCode?: string;
};
export type BufferedResponsesSseResult = {
ok: true;
/** Present only when the caller needs to replay the bounded transcript through rewrites. */
bytes?: Uint8Array;
terminal: BufferedResponsesTerminal;
} | BufferedResponsesSseFailure;
type BufferedReadOptions = {
maxBytes?: number;
maxFrames?: number;
totalTimeoutMs?: number;
/** Absolute whole-turn deadline shared by every validation pass. */
deadlineAt?: number;
inactivityTimeoutMs?: number;
firstByteTimeoutMs?: number;
};
export type BufferedResponsesReadOptions = BufferedReadOptions & { deadlineAt: number };
/**
* Resolve the read clocks for canonical SSE that must be folded into client JSON.
*
* A positive stall budget owns both time-to-first-byte and inter-chunk silence. A disabled budget
* must not become an immediate timeout, so both clocks fall back to the independent total ceiling.
* The ceiling remains separate because a JSON caller has no partial body to keep alive forever.
*/
export function bufferedResponsesReadOptions(
stallTimeoutMs: number,
totalTimeoutMs = BUFFERED_RESPONSES_TOTAL_TIMEOUT_MS,
startedAt = Date.now(),
): BufferedResponsesReadOptions {
if (!Number.isFinite(stallTimeoutMs)) throw new RangeError("stallTimeoutMs must be finite");
if (!Number.isSafeInteger(totalTimeoutMs) || totalTimeoutMs <= 0) {
throw new RangeError("totalTimeoutMs must be a positive safe integer");
}
if (!Number.isSafeInteger(startedAt) || startedAt < 0 || startedAt > Number.MAX_SAFE_INTEGER - totalTimeoutMs) {
throw new RangeError("startedAt must produce a safe deadline");
}
const silenceTimeoutMs = stallTimeoutMs > 0 ? Math.ceil(stallTimeoutMs) : totalTimeoutMs;
return {
totalTimeoutMs,
deadlineAt: startedAt + totalTimeoutMs,
firstByteTimeoutMs: silenceTimeoutMs,
inactivityTimeoutMs: silenceTimeoutMs,
};
}
type Uint8ReadResult = Awaited<ReturnType<ReadableStreamDefaultReader<Uint8Array>["read"]>>;
class BufferedSseTimeoutError extends Error {
constructor(deadline: "total" | "inactivity") {
super(`buffered Responses SSE ${deadline} timeout`);
this.name = "BufferedSseTimeoutError";
}
}
function createBufferedTerminalInspector(maxSourceBytes: number): {
inspector: SseInspector;
result: () => { ok: true; terminal: BufferedResponsesTerminal } | BufferedResponsesSseFailure;
} {
let malformed = false;
let terminalCount = 0;
let status: ResponsesTerminalStatus | undefined;
let terminalResponse: Record<string, unknown> | undefined;
let failedCompletion: BufferedFailedCompletion | undefined;
const classifyTerminal = createTerminalStatusTracker();
const inspector = createSseInspector({
terminalReconstruction: {
maxItems: MAX_BUFFERED_RESPONSES_OUTPUT_ITEMS,
maxSourceBytes,
requireCompleteOutputIndices: true,
mergeSparseTerminalOutput: true,
},
onParsedPayload(payload) {
const candidateStatus = classifyTerminal(payload);
if (!candidateStatus) return;
terminalCount += 1;
status ??= candidateStatus;
if (terminalCount === 1 && candidateStatus === "failed") {
const error = responsesCompletionError(payload);
if (error) failedCompletion = { payload, error };
}
},
onOpaquePayload(payload) {
if (payload !== "[DONE]") malformed = true;
},
onTerminalResponse(candidateStatus, response) {
if (!failedCompletion && candidateStatus === status && terminalResponse === undefined) {
if (response.status !== undefined && response.status !== candidateStatus) {
malformed = true;
return;
}
if (response.output !== undefined && !Array.isArray(response.output)) {
malformed = true;
return;
}
terminalResponse = {
...response,
status: candidateStatus,
output: response.output ?? [],
} as Record<string, unknown>;
}
},
});
return {
inspector,
result: () => {
if (malformed) return { ok: false, kind: "malformed" };
if (terminalCount !== 1 || status === undefined) return { ok: false, kind: "missing_terminal" };
// A provider error on response.completed is authoritative even when the snapshot claims success.
if (failedCompletion) return { ok: true, terminal: { status: "failed", failedCompletion } };
if (!terminalResponse || terminalResponse.status !== status || !Array.isArray(terminalResponse.output)) {
return { ok: false, kind: "malformed" };
}
return { ok: true, terminal: { status, response: terminalResponse } };
},
};
}
/** Strict synchronous seam for terminal/reconstruction tests; production feeds bytes incrementally. */
export function inspectBufferedResponsesTerminal(text: string):
| { ok: true; terminal: BufferedResponsesTerminal }
| BufferedResponsesSseFailure {
const state = createBufferedTerminalInspector(MAX_BUFFERED_RESPONSES_RECONSTRUCTION_BYTES);
try {
state.inspector.feed(new TextEncoder().encode(text));
state.inspector.finish();
return state.result();
} finally {
state.inspector.dispose();
}
}
function cancelReader(reader: ReadableStreamDefaultReader<Uint8Array>, reason?: unknown): void {
try { void reader.cancel(reason).catch(() => undefined); } catch { /* non-conforming stream */ }
}
async function deadlineRead(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal | undefined,
deadlineAt: number,
deadline: "total" | "inactivity",
): Promise<Uint8ReadResult> {
if (signal?.aborted) throw signal.reason;
return await new Promise<Uint8ReadResult>((resolve, reject) => {
let settled = false;
let timer: ReturnType<typeof setTimeout> | undefined;
const finish = (callback: () => void): void => {
if (settled) return;
settled = true;
if (timer !== undefined) clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
callback();
};
const onAbort = () => finish(() => reject(signal?.reason));
timer = setTimeout(
() => finish(() => reject(new BufferedSseTimeoutError(deadline))),
Math.max(0, deadlineAt - Date.now()),
);
signal?.addEventListener("abort", onAbort, { once: true });
if (signal?.aborted) onAbort();
void reader.read().then(
value => finish(() => resolve(value)),
error => finish(() => reject(error)),
);
});
}
/**
* Consume through the first terminal, which must validate, with bounded framing and deadlines.
* `retainTranscript:false` feeds the strict assembler directly and never materializes the second,
* client-facing SSE transcript. Side effects remain the delivery owner's responsibility.
*/
export async function collectBufferedResponsesSse(
body: ReadableStream<Uint8Array>,
upstream: AbortController,
options: {
signal?: AbortSignal;
terminalBoundary?: CodexSafetyBufferingFilterOptions;
read?: BufferedReadOptions;
retainTranscript?: boolean;
/** Per-request outbound mask, applied to upstream copy before the boundary bounds it. */
maskCredential?: (text: string) => string;
} = {},
): Promise<BufferedResponsesSseResult> {
const maxBytes = options.read?.maxBytes ?? MAX_UPSTREAM_JSON_BODY_BYTES;
if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
throw new RangeError("maxBytes must be a positive safe integer");
}
const maxFrames = options.read?.maxFrames ?? MAX_BUFFERED_RESPONSES_SSE_FRAMES;
const totalTimeoutMs = options.read?.totalTimeoutMs ?? UPSTREAM_JSON_BODY_TOTAL_TIMEOUT_MS;
const inactivityTimeoutMs = options.read?.inactivityTimeoutMs ?? UPSTREAM_JSON_BODY_INACTIVITY_TIMEOUT_MS;
const firstByteTimeoutMs = options.read?.firstByteTimeoutMs ?? totalTimeoutMs;
const absoluteDeadlineAt = options.read?.deadlineAt;
if (absoluteDeadlineAt !== undefined && (!Number.isSafeInteger(absoluteDeadlineAt) || absoluteDeadlineAt < 0)) {
throw new RangeError("deadlineAt must be a non-negative safe integer");
}
const retainTranscript = options.retainTranscript === true;
const reader = body.getReader();
const boundary = createSseTerminalOutputBoundary({
...options.terminalBoundary,
maskCredential: options.maskCredential,
maxInputBytes: maxBytes,
maxOutputBytes: maxBytes,
maxFrames,
});
const state = createBufferedTerminalInspector(Math.min(
maxBytes,
MAX_BUFFERED_RESPONSES_RECONSTRUCTION_BYTES,
));
const utf8 = new TextDecoder("utf-8", { fatal: true });
let retained = retainTranscript ? new Uint8Array(Math.min(maxBytes, 64 * 1024)) : undefined;
let retainedBytes = 0;
const startedAt = Date.now();
const totalDeadlineAt = absoluteDeadlineAt ?? startedAt + totalTimeoutMs;
let inactivityDeadlineAt = startedAt + firstByteTimeoutMs;
const withBoundaryError = <T extends BufferedResponsesSseFailure>(failure: T): T => {
const upstreamError = boundary.upstreamError();
const upstreamRefusalCode = boundary.upstreamRefusalCode();
const upstreamErrorType = boundary.upstreamErrorType();
const upstreamErrorCode = boundary.upstreamErrorCode();
return {
...failure,
...(upstreamError === undefined ? {} : { upstreamError }),
...(upstreamRefusalCode === undefined ? {} : { upstreamRefusalCode }),
...(upstreamErrorType === undefined ? {} : { upstreamErrorType }),
...(upstreamErrorCode === undefined ? {} : { upstreamErrorCode }),
};
};
const inspect = (chunk: Uint8Array): void => {
if (chunk.byteLength === 0) return;
// Validate incrementally without retaining a second decoded transcript. The shared inspector
// independently owns SSE framing and JSON reconstruction over the same bytes.
utf8.decode(chunk, { stream: true });
state.inspector.feed(chunk);
if (!retained) return;
if (chunk.byteLength > maxBytes - retainedBytes) throw new SseAggregateLimitError(maxBytes);
const required = retainedBytes + chunk.byteLength;
if (required > retained.byteLength) {
const grown = new Uint8Array(Math.min(maxBytes, Math.max(required, retained.byteLength * 2)));
grown.set(retained.subarray(0, retainedBytes));
retained = grown;
}
retained.set(chunk, retainedBytes);
retainedBytes = required;
};
try {
for (;;) {
const deadlineAt = Math.min(totalDeadlineAt, inactivityDeadlineAt);
const deadline = totalDeadlineAt <= inactivityDeadlineAt ? "total" : "inactivity";
const { done, value } = await deadlineRead(reader, options.signal, deadlineAt, deadline);
if (options.signal?.aborted) throw options.signal.reason;
if (done) {
inspect(boundary.finish());
break;
}
if (!value || value.byteLength === 0) continue;
inactivityDeadlineAt = Date.now() + inactivityTimeoutMs;
// Slice the reader's chunk before framing. This keeps one oversized network read from
// producing a transcript-sized array of frames/output buffers and gives the total deadline
// and aggregate frame cap a checkpoint between bounded pieces of synchronous work.
for (let offset = 0; offset < value.byteLength && !boundary.terminalSeen();) {
if (Date.now() >= totalDeadlineAt) throw new BufferedSseTimeoutError("total");
const end = Math.min(value.byteLength, offset + BUFFERED_SSE_PROCESSING_SLICE_BYTES);
inspect(boundary.feed(value.subarray(offset, end)));
offset = end;
}
if (boundary.terminalSeen()) {
cancelReader(reader, "Responses terminal event received");
break;
}
}
utf8.decode();
state.inspector.finish();
if (options.signal?.aborted) throw options.signal.reason;
const terminal = state.result();
if (!terminal.ok) {
upstream.abort(new Error(`buffered Responses SSE ${terminal.kind}`));
return withBoundaryError(terminal);
}
return {
...terminal,
...(retained ? { bytes: retained.subarray(0, retainedBytes) } : {}),
};
} catch (error) {
upstream.abort(error);
cancelReader(reader, error);
return withBoundaryError({
ok: false,
kind: options.signal?.aborted
? "aborted"
// A source guarded at its upstream reads reports its stall through the body it feeds us.
: error instanceof BufferedSseTimeoutError || error instanceof ResponseBodyInactivityError
? "timeout"
: error instanceof SseAggregateLimitError
|| error instanceof SseFrameTooLargeError
|| error instanceof SseFrameCountLimitError
? "oversized"
: "read_error",
error,
});
} finally {
boundary.dispose();
state.inspector.dispose();
try { reader.releaseLock(); } catch { /* a cancelled pending read may still own it briefly */ }
}
}