@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
226 lines (207 loc) • 12.7 kB
text/typescript
/**
* Error detail kept on request-log rows (live ring, /api/logs, usage.jsonl and hydration).
*
* Rows carry only proxy-owned error facts: a code from a closed vocabulary, a classified upstream
* condition, and, for one provider, a numeric quota reset time. Upstream-authored error text and
* tokens are read here once to derive those facts and are never retained.
*/
import { classifyUpstreamCondition, isUpstreamCondition, type UpstreamCondition } from "../lib/upstream-condition";
import { boundedFailureDetail, type FailureDetail, type FailureDetailCode } from "../lib/failure-detail";
import { boundedServiceTier } from "../lib/response-service-tier";
export { boundedServiceTier };
/**
* Every error code a row may carry. Codes outside this set (an upstream-supplied code that reached a
* writer, a future writer's typo) collapse to the status fallback below. http_NNN codes are formatted
* by the proxy from a numeric status and stay valid.
*/
export const LOG_ERROR_CODES: ReadonlySet<string> = new Set([
// classifyError and requestLogErrorCode outputs
"spend_ledger_storage_unavailable", "previous_response_not_found", "client_cancelled", "client_closed_request",
"cyber_policy", "input_admission_refused", "inbound_body_too_large", "context_length_exceeded",
"tool_catalog_too_large", "rate_limit_exceeded", "insufficient_quota", "request_send_budget_exhausted",
"origin_rejected", "upstream_server_error", "invalid_api_key", "permission_denied", "location_not_supported",
"subscription_required", "server_is_overloaded", "invalid_request_error", "upstream_error",
// local refusals and proxy decisions
"server_busy", "unsupported_feature", "usage_limit_reached", "undeclared_tool_call", "outbound_body_too_large",
"codex_no_account", "upstream_reset_replay_refused", "memory_model_target_unavailable",
"intercept_target_unavailable", "observation_barrier_timeout", "claude_thread_unsupported",
"claude_compatibility_configuration", "claude_compatibility_unsupported",
"unsupported_credential_domain", "unsupported_synthetic_selector", "unsupported_shadow_rewrite",
// workflow budget refusals
"workflow_sends_exhausted", "workflow_children_exhausted", "workflow_concurrency_exhausted",
"workflow_spend_exhausted", "workflow_tracking_exhausted", "workflow_send_replayed",
"workflow_pool_history_unresolved", "workflow_spend_undurable",
]);
const HTTP_CODE = /^http_[1-5][0-9]{2}$/;
function statusFallbackCode(status: number | undefined): string | undefined {
if (status === undefined || !Number.isInteger(status) || status < 400) return undefined;
if (status === 499) return "client_closed_request";
if (status === 400 || status === 409) return "invalid_request_error";
if (status === 401) return "invalid_api_key";
if (status === 403) return "permission_denied";
if (status === 429) return "rate_limit_exceeded";
if (status === 503) return "server_is_overloaded";
if (status >= 500) return "upstream_server_error";
return `http_${status}`;
}
/** A code from the closed vocabulary, or the proxy's own code for the status, or nothing. */
export function normalizeLogErrorCode(code: unknown, status?: number): string | undefined {
if (typeof code === "string" && (LOG_ERROR_CODES.has(code) || HTTP_CODE.test(code))) return code;
return typeof code === "string" && code ? statusFallbackCode(status) ?? "upstream_error" : undefined;
}
// Meta Muse states its quota window in one fixed sentence. The reset time is kept as a number so
// the dashboard needs no message text.
const MUSE_PROVIDER = "meta-muse";
const MUSE_RESET_SENTENCE = /^Subscription quota exhausted\. Your usage window resets at (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)\.$/;
export const RATE_LIMIT_RESET_MAX_MS = 8 * 24 * 60 * 60 * 1000;
/** A reset time is kept only when it is a finite epoch-ms value after the request and within 8 days. */
export function boundedRateLimitResetAt(value: unknown, timestamp: unknown): number | undefined {
if (typeof value !== "number" || !Number.isSafeInteger(value)) return undefined;
if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) return undefined;
return value > timestamp && value - timestamp <= RATE_LIMIT_RESET_MAX_MS ? value : undefined;
}
export function deriveRateLimitResetAt(entry: {
provider?: unknown; status?: unknown; errorCode?: unknown; upstreamError?: unknown; timestamp?: unknown;
}): number | undefined {
if (entry.provider !== MUSE_PROVIDER || entry.status !== 429 || entry.errorCode !== "rate_limit_exceeded") return undefined;
if (typeof entry.upstreamError !== "string") return undefined;
const match = MUSE_RESET_SENTENCE.exec(entry.upstreamError);
if (!match) return undefined;
const parsed = Date.parse(match[1]!);
return boundedRateLimitResetAt(Number.isFinite(parsed) ? parsed : undefined, entry.timestamp);
}
/** The fields an error-detail projection reads; all optional so legacy rows qualify. */
export interface ErrorDetailSource {
status?: unknown;
timestamp?: unknown;
provider?: unknown;
errorCode?: unknown;
terminalStatus?: unknown;
upstreamError?: unknown;
upstreamErrorCode?: unknown;
upstreamErrorType?: unknown;
upstreamCondition?: unknown;
rateLimitResetAt?: unknown;
failureDetail?: unknown;
}
export interface ErrorDetail {
errorCode?: string;
upstreamCondition?: UpstreamCondition;
rateLimitResetAt?: number;
failureDetail?: FailureDetail;
}
const str = (value: unknown): string | undefined => typeof value === "string" ? value : undefined;
// Sentences this proxy writes into a relayed error body (web-search and image-bridge loops, body
// inactivity guard). The request log only sees them as captured error text, so a match becomes a
// closed code with the parsed number; the number is bounded so no credential-length value can fit.
const PROXY_SENTENCES: ReadonlyArray<readonly [RegExp, FailureDetailCode]> = [
[/^Provider response-header timeout after (\d{1,7})ms during (?:web-search|image-bridge)$/, "header_timeout"],
[/^Upstream response body stalled for (\d{1,7})ms$/, "body_stall"],
[/^Routed model generation timeout after (\d{1,7})ms without response bytes during web-search$/, "generation_timeout"],
[/^runTurn inactivity timeout after (\d{1,7})ms during image-bridge$/, "turn_inactivity"],
[/^Provider connect timeout after (\d{1,7})ms$/, "connect_timeout"],
[/^client closed request during web-search$/, "client_closed"],
];
function proxySentenceDetail(text: string | undefined): FailureDetail | undefined {
if (text === undefined) return undefined;
for (const [pattern, code] of PROXY_SENTENCES) {
const match = pattern.exec(text);
if (match) return match[1] === undefined ? { code } : { code, value: Number(match[1]) };
}
return undefined;
}
/**
* Derive the proxy-owned error facts for one row. An existing condition or reset time is kept only
* when valid; otherwise both are derived from upstream evidence, which the caller then drops.
* A condition is derived only when the row carries upstream evidence, so local refusals get none.
*/
export function errorDetailFor(entry: ErrorDetailSource): ErrorDetail {
const status = typeof entry.status === "number" ? entry.status : undefined;
const errorCode = normalizeLogErrorCode(entry.errorCode, status);
// The HTTP status decides when present: a 200 that stopped at the requested output limit is an
// incomplete terminal but a successful request, not an upstream failure.
const failed = status !== undefined ? status >= 400 : typeof entry.terminalStatus === "string" && entry.terminalStatus !== "completed";
// A client that closed the request is not an upstream condition.
const clientClosed = status === 499 || errorCode === "client_closed_request" || errorCode === "client_cancelled";
// A recorded condition is kept under the same rules that derive one: failed and not a client close.
let upstreamCondition: UpstreamCondition | undefined = failed && !clientClosed && isUpstreamCondition(entry.upstreamCondition)
? entry.upstreamCondition : undefined;
const evidence = str(entry.upstreamError) ?? str(entry.upstreamErrorCode) ?? str(entry.upstreamErrorType);
if (!upstreamCondition && failed && !clientClosed && evidence !== undefined && status !== undefined) {
upstreamCondition = classifyUpstreamCondition({
status,
code: str(entry.upstreamErrorCode),
type: str(entry.upstreamErrorType),
message: str(entry.upstreamError),
});
}
const rateLimitResetAt = boundedRateLimitResetAt(entry.rateLimitResetAt, entry.timestamp)
?? deriveRateLimitResetAt({ provider: entry.provider, status: entry.status, timestamp: entry.timestamp, upstreamError: entry.upstreamError, errorCode });
// A closed code with bounded parameters; free text (a legacy or edited row) is dropped.
const failureDetail = boundedFailureDetail(entry.failureDetail) ?? proxySentenceDetail(str(entry.upstreamError));
return {
...(errorCode ? { errorCode } : {}),
...(upstreamCondition ? { upstreamCondition } : {}),
...(rateLimitResetAt !== undefined ? { rateLimitResetAt } : {}),
...(failureDetail ? { failureDetail } : {}),
};
}
/** Upstream-authored fields that never leave the request context. */
export const UPSTREAM_TEXT_FIELDS = ["upstreamError", "upstreamErrorCode", "upstreamErrorType", "upstreamRequestId"] as const;
type ProjectableEntry = ErrorDetailSource & {
attempts?: unknown; attemptNormalizationDropped?: unknown; responseServiceTier?: unknown; tierOutcome?: unknown;
};
/** A tier outcome whose recorded response tier is a closed member (or absent); same object when unchanged. */
function boundedTierOutcome(outcome: unknown): unknown {
if (!outcome || typeof outcome !== "object" || !("responseServiceTier" in outcome)) return outcome;
const record = outcome as Record<string, unknown>;
const tier = boundedServiceTier(record.responseServiceTier);
if (tier === record.responseServiceTier) return outcome;
const { responseServiceTier: _dropped, ...rest } = record;
return tier === undefined ? rest : { ...rest, responseServiceTier: tier };
}
/**
* The live-row form of {@link errorDetailFor}: attach the proxy-owned facts and remove upstream text.
* Returns the same object when nothing changes, so callers that rely on identity keep it. Attempt
* codes outside the vocabulary are corrected, and upstream text fields removed, in place (attempts
* keep their identity too).
*/
export function projectErrorDetail<T extends ProjectableEntry>(entry: T): T {
if (Array.isArray(entry.attempts)) {
for (const attempt of entry.attempts as unknown[]) {
if (!attempt || typeof attempt !== "object") continue;
const record = attempt as Record<string, unknown>;
for (const field of UPSTREAM_TEXT_FIELDS) if (field in record) delete record[field];
if ("tierOutcome" in record) record.tierOutcome = boundedTierOutcome(record.tierOutcome);
if (typeof record.errorCode !== "string") continue;
const code = normalizeLogErrorCode(record.errorCode, typeof record.status === "number" ? record.status : undefined);
if (code !== record.errorCode) {
if (code === undefined) delete record.errorCode;
else record.errorCode = code;
}
}
}
const detail = errorDetailFor(entry);
const responseServiceTier = boundedServiceTier(entry.responseServiceTier);
const tierOutcome = boundedTierOutcome(entry.tierOutcome);
const unchanged = UPSTREAM_TEXT_FIELDS.every(field => entry[field as keyof ErrorDetailSource] === undefined)
&& entry.responseServiceTier === responseServiceTier && entry.tierOutcome === tierOutcome
&& entry.errorCode === detail.errorCode
&& entry.upstreamCondition === detail.upstreamCondition
&& entry.rateLimitResetAt === detail.rateLimitResetAt
&& entry.failureDetail === detail.failureDetail;
if (unchanged) return entry;
const out = { ...entry } as Record<string, unknown>;
// A non-enumerable marker does not survive a spread; carry it explicitly.
if (entry.attemptNormalizationDropped === true) out.attemptNormalizationDropped = true;
for (const field of UPSTREAM_TEXT_FIELDS) delete out[field];
if (responseServiceTier === undefined) delete out.responseServiceTier;
else out.responseServiceTier = responseServiceTier;
if (tierOutcome === undefined) delete out.tierOutcome;
else out.tierOutcome = tierOutcome;
for (const field of ["errorCode", "upstreamCondition", "rateLimitResetAt", "failureDetail"] as const) {
if (detail[field] === undefined) delete out[field];
else out[field] = detail[field];
}
return out as T;
}