@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
347 lines (329 loc) • 17.2 kB
text/typescript
import { nonBlankStringArrayConfigError, normalizeNonBlankStringArray } from "../../config/provider-validation";
import {
retryOn429PolicyConfigError,
retryOnResetPolicyConfigError,
transientRetryOn5xxPolicyConfigError,
} from "../../config/load-degrade";
import { providerTimeoutOverrideConfigError } from "../../config/schema/leaf-validators";
import type { OcxProviderConfig } from "../../types";
import { providerModelDiscoveryConfigError } from "../../providers/model-discovery-config";
const TIMEOUT_OVERRIDE_FIELDS = ["connectTimeoutMs", "stallTimeoutSec"] as const;
/**
* The retry policies. They are the one carried group the PATCH field mask did not know, and they
* are `"editor"` fields, so before this a save that dropped one left no API path to put it back.
* Each validator is the same strict check the loader's schema applies, so the mask cannot store a
* block that a later load would reject.
*/
const RETRY_POLICY_FIELDS = ["retryOn429", "transientRetryOn5xx", "retryOnReset"] as const satisfies
readonly (keyof OcxProviderConfig)[];
const RETRY_POLICY_VALIDATORS = {
retryOn429: retryOn429PolicyConfigError,
transientRetryOn5xx: transientRetryOn5xxPolicyConfigError,
retryOnReset: retryOnResetPolicyConfigError,
} as const satisfies Record<typeof RETRY_POLICY_FIELDS[number], (policy: unknown) => string | null>;
/**
* What a provider save keeps (#5563).
*
* `POST /api/providers` with an existing name replaces the stored row with a candidate built from
* the request. The dashboard form cannot send the fields below, so a save that omits them used
* to drop them from a custom provider, or reset them to the registry seed through
* `enrichProviderFromCatalog` for a registry provider. The live-config reconcile cannot restore
* them afterwards: the disk row equals its baseline, so the three-way merge keeps the value the
* save wrote.
*
* `hideRawReasoning` is an operator display policy, so every overwrite of the same provider name
* carries it when omitted, even when the destination changes. The compatibility settings below
* record how one upstream behaves. An overwrite that keeps the destination
* carries each one the request omits, including an explicit `[]` or `false`. An overwrite that
* moves the provider to another destination carries none of them: they describe the previous
* upstream, and registry enrichment already fills what is known about the new one. The same
* destination rule gates the stored `apiKeyPool`, whose keys were issued for the previous
* destination. A value the request sends always wins, and the rest of the old row is never merged
* into the candidate.
*
* The three retry policies join them on the same terms, and for a sharper reason: they are
* `"editor"` fields that had no branch in the PATCH field mask, so a save that dropped one left no
* API path to put it back. The mask branch below restores that path, and validates each policy
* against the loader's own schema — PATCH never runs the schema, and a malformed block would not
* degrade to "absent": the load would fail and the default config would take the whole provider
* table.
*/
export const PROVIDER_COMPAT_CARRY_FIELDS = [
"preserveReasoningContentModels",
"preserveResponsesReasoningContent",
"promoteAdditionalTools",
"requiresReasoningPlaceholderModels",
"foldDeveloperRoleToSystem",
"singleLeadingSystemMessage",
"reasoningWireFormat",
"omitReasoningEffortWithToolsModels",
// Hosted-tool denials describe the same upstream, and the form sends neither. They travel
// together: carrying only the conditional list (#8204) would let a hosted-only request
// forward a tool the dropped unconditional list had denied.
"unsupportedHostedTools",
"unsupportedHostedToolsWithClientTools",
// Whether this gateway runs Claude Code's Advisor server tool (#8448): a fact about the upstream,
// so a move to another gateway must not keep forwarding it there.
"forwardAdvisorTool",
...RETRY_POLICY_FIELDS,
] as const satisfies readonly (keyof OcxProviderConfig)[];
export const PROVIDER_DISPLAY_CARRY_FIELDS = [
"hideRawReasoning",
"rawReasoningAsSummary",
// The Anthropic thinking display policy (#8363) is operator configuration the dashboard form
// cannot send either, so an unrelated save must not silently return the model to the default.
"thinkingDisplay",
"modelThinkingDisplay",
// The experimental Anthropic per-message effort switch (#6895) is operator configuration the form
// cannot send; an unrelated save must not silently turn it off.
"perMessageEffort",
// The dashboard form omits these operator-configured transport budgets.
...TIMEOUT_OVERRIDE_FIELDS,
] as const satisfies readonly (keyof OcxProviderConfig)[];
/** Display policies that are plain booleans and can share one validation/patch branch. */
const PROVIDER_BOOLEAN_DISPLAY_FIELDS = ["hideRawReasoning", "rawReasoningAsSummary"] as const satisfies readonly (keyof OcxProviderConfig)[];
export type ProviderCompatCarryField = typeof PROVIDER_COMPAT_CARRY_FIELDS[number];
type ProviderDisplayCarryField = typeof PROVIDER_DISPLAY_CARRY_FIELDS[number];
/**
* Discovery compatibility (#7910). `modelDiscovery.skipInvalidRows` records that one gateway
* publishes invalid `/models` rows, so it follows the compatibility settings' destination rule:
* kept on a same-destination overwrite that omits it, dropped when the provider moves. It is a
* separate group because it changes discovery, not the request the compatibility cases probe.
*/
export const PROVIDER_DISCOVERY_CARRY_FIELDS = ["modelDiscovery"] as const satisfies readonly (keyof OcxProviderConfig)[];
type ProviderDiscoveryCarryField = typeof PROVIDER_DISCOVERY_CARRY_FIELDS[number];
/** The only `reasoningWireFormat` value the adapters understand. */
export const PROVIDER_REASONING_WIRE_FORMATS: readonly NonNullable<OcxProviderConfig["reasoningWireFormat"]>[] = [
"gateway-object",
];
/**
* Request ownership, sampled before `enrichProviderFromCatalog`. After enrichment "the client
* omitted this" and "the registry supplied it" look the same.
*/
export interface ProviderOverwriteSample {
readonly submitted: ReadonlySet<ProviderCompatCarryField | ProviderDisplayCarryField | ProviderDiscoveryCarryField>;
readonly namesAuthMode: boolean;
}
export function sampleProviderOverwrite(provider: object): ProviderOverwriteSample {
return {
submitted: new Set([...PROVIDER_COMPAT_CARRY_FIELDS, ...PROVIDER_DISPLAY_CARRY_FIELDS, ...PROVIDER_DISCOVERY_CARRY_FIELDS]
.filter(field => Object.hasOwn(provider, field))),
namesAuthMode: Object.hasOwn(provider, "authMode"),
};
}
function normalizedDestinationUrl(value: unknown): string {
if (typeof value !== "string") return "";
const trimmed = value.trim();
try {
const url = new URL(trimmed);
return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}${url.search}`;
} catch {
return trimmed.replace(/\/+$/, "");
}
}
/**
* Whether an overwrite keeps the provider on the same upstream: same adapter, same base URL
* (scheme and host compared case-insensitively, trailing slashes ignored) and, when the request
* names one, the same auth mode. The dashboard form sends `authMode` only for key and forward
* auth, so an omitted value is not evidence of a move; a stored row without `authMode` is a
* key-auth row.
*/
export function providerOverwriteKeepsDestination(
candidate: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode">,
stored: Pick<OcxProviderConfig, "adapter" | "baseUrl" | "authMode"> | undefined,
sample: ProviderOverwriteSample,
): boolean {
if (!stored) return false;
if ((candidate.adapter ?? "").trim() !== (stored.adapter ?? "").trim()) return false;
if (normalizedDestinationUrl(candidate.baseUrl) !== normalizedDestinationUrl(stored.baseUrl)) return false;
if (sample.namesAuthMode && (candidate.authMode ?? "key") !== (stored.authMode ?? "key")) return false;
return true;
}
/**
* Carry omitted operator settings on every overwrite, then the omitted compatibility settings
* only when the destination is unchanged. `live` must be the row read after
* the route's DNS await, so a PATCH that saved one of them during the wait is kept.
*/
export function carryProviderCompatFields(
candidate: OcxProviderConfig,
live: OcxProviderConfig | undefined,
sample: ProviderOverwriteSample,
): void {
if (!live) return;
const target = candidate as unknown as Record<string, unknown>;
for (const field of PROVIDER_DISPLAY_CARRY_FIELDS) {
if (sample.submitted.has(field)) continue;
const stored = live[field];
// Copy maps rather than alias them, like the compatibility settings below.
if (stored !== undefined) target[field] = stored !== null && typeof stored === "object" ? structuredClone(stored) : stored;
}
if (!providerOverwriteKeepsDestination(candidate, live, sample)) return;
for (const field of [...PROVIDER_COMPAT_CARRY_FIELDS, ...PROVIDER_DISCOVERY_CARRY_FIELDS]) {
if (sample.submitted.has(field)) continue;
const stored = live[field];
if (stored === undefined) continue;
// Arrays and the retry-policy objects are copied rather than aliased, like `requestPacing`
// in the route: a later edit of one row must not reach the other through a shared value.
target[field] = Array.isArray(stored)
? [...stored]
: stored !== null && typeof stored === "object"
? structuredClone(stored)
: stored;
}
}
const REASONING_LIST_FIELDS = ["preserveReasoningContentModels", "requiresReasoningPlaceholderModels"] as const;
/**
* Type checks for a POST that does send one of the settings. `omitReasoningEffortWithToolsModels`
* is already checked by `providerManagementConfigError`.
*/
export function providerCompatFieldConfigError(provider: Record<string, unknown>): string | null {
for (const field of REASONING_LIST_FIELDS) {
const error = nonBlankStringArrayConfigError(provider[field], field);
if (error) return error;
}
const fold = provider.foldDeveloperRoleToSystem;
if (fold !== undefined && typeof fold !== "boolean") return "foldDeveloperRoleToSystem must be a boolean";
if (provider.singleLeadingSystemMessage !== undefined && typeof provider.singleLeadingSystemMessage !== "boolean") {
return "singleLeadingSystemMessage must be a boolean";
}
for (const field of PROVIDER_BOOLEAN_DISPLAY_FIELDS) {
const value = provider[field];
if (value !== undefined && typeof value !== "boolean") return `${field} must be a boolean`;
}
const preserveResponses = provider.preserveResponsesReasoningContent;
if (preserveResponses !== undefined && typeof preserveResponses !== "boolean") return "preserveResponsesReasoningContent must be a boolean";
const promoteAdditionalTools = provider.promoteAdditionalTools;
if (promoteAdditionalTools !== undefined && typeof promoteAdditionalTools !== "boolean") return "promoteAdditionalTools must be a boolean";
if (provider.forwardAdvisorTool !== undefined && typeof provider.forwardAdvisorTool !== "boolean") return "forwardAdvisorTool must be a boolean";
const wire = provider.reasoningWireFormat;
if (wire !== undefined && !PROVIDER_REASONING_WIRE_FORMATS.includes(wire as never)) {
return `reasoningWireFormat must be one of: ${PROVIDER_REASONING_WIRE_FORMATS.join(", ")}`;
}
return null;
}
/**
* PATCH branches for the settings the field mask did not know. `null` clears a field. For the two
* reasoning lists an empty array is kept rather than deleted: it is the explicit opt-out that stops
* the registry seed from filling the field back in (see the note under OAUTH_RECONCILE_FIELDS in
* src/oauth/index.ts).
*/
export function applyProviderCompatPatchFields(
rawBody: Record<string, unknown>,
next: OcxProviderConfig,
): { touched: boolean } | { error: string } {
let touched = false;
for (const field of REASONING_LIST_FIELDS) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (value === null) {
delete next[field];
} else {
const error = nonBlankStringArrayConfigError(value, field);
if (error) return { error };
next[field] = normalizeNonBlankStringArray(value as string[]);
}
touched = true;
}
if (Object.hasOwn(rawBody, "foldDeveloperRoleToSystem")) {
const value = rawBody.foldDeveloperRoleToSystem;
if (value === null) delete next.foldDeveloperRoleToSystem;
else if (typeof value === "boolean") next.foldDeveloperRoleToSystem = value;
else return { error: "foldDeveloperRoleToSystem must be a boolean" };
touched = true;
}
if (Object.hasOwn(rawBody, "singleLeadingSystemMessage")) {
const value = rawBody.singleLeadingSystemMessage;
if (value === null) delete next.singleLeadingSystemMessage;
else if (typeof value === "boolean") next.singleLeadingSystemMessage = value;
else return { error: "singleLeadingSystemMessage must be a boolean" };
touched = true;
}
for (const field of PROVIDER_BOOLEAN_DISPLAY_FIELDS) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (value === null) delete next[field];
else if (typeof value === "boolean") next[field] = value;
else return { error: `${field} must be a boolean` };
touched = true;
}
if (Object.hasOwn(rawBody, "preserveResponsesReasoningContent")) {
const value = rawBody.preserveResponsesReasoningContent;
if (value === null) delete next.preserveResponsesReasoningContent;
else if (typeof value === "boolean") next.preserveResponsesReasoningContent = value;
else return { error: "preserveResponsesReasoningContent must be a boolean" };
touched = true;
}
if (Object.hasOwn(rawBody, "promoteAdditionalTools")) {
const value = rawBody.promoteAdditionalTools;
if (value === null) delete next.promoteAdditionalTools;
else if (typeof value === "boolean") next.promoteAdditionalTools = value;
else return { error: "promoteAdditionalTools must be a boolean" };
touched = true;
}
if (Object.hasOwn(rawBody, "forwardAdvisorTool")) {
const value = rawBody.forwardAdvisorTool;
if (value === null) delete next.forwardAdvisorTool;
else if (typeof value === "boolean") next.forwardAdvisorTool = value;
else return { error: "forwardAdvisorTool must be a boolean" };
touched = true;
}
if (Object.hasOwn(rawBody, "inferContextWindow")) {
const value = rawBody.inferContextWindow;
if (value === null) delete next.inferContextWindow;
else if (typeof value === "boolean") next.inferContextWindow = value;
else return { error: "inferContextWindow must be a boolean or null" };
touched = true;
}
if (Object.hasOwn(rawBody, "reasoningWireFormat")) {
const value = rawBody.reasoningWireFormat;
if (value === null) {
delete next.reasoningWireFormat;
} else {
const format = PROVIDER_REASONING_WIRE_FORMATS.find(candidate => candidate === value);
if (!format) return { error: `reasoningWireFormat must be one of: ${PROVIDER_REASONING_WIRE_FORMATS.join(", ")}` };
next.reasoningWireFormat = format;
}
touched = true;
}
// The retry policies. They are validated here, like `requestPacing` and `upstreamHttpVersion`,
// because PATCH does not run the config schema: only POST does, through
// `validateConfigCandidate`. A malformed block that reached disk would fail the load and take
// the whole provider table to the default config with it, so the mask refuses it rather than
// storing something the loader will reject. `null` leaves the row entirely: the schema reads an
// absent block as "off", so deleting the key is what disables one, not storing `{enabled:false}`.
for (const field of RETRY_POLICY_FIELDS) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (value === null) {
delete next[field];
} else {
const error = RETRY_POLICY_VALIDATORS[field](value);
if (error) return { error };
next[field] = structuredClone(value) as OcxProviderConfig[typeof field];
}
touched = true;
}
for (const field of TIMEOUT_OVERRIDE_FIELDS) {
if (!Object.hasOwn(rawBody, field)) continue;
const value = rawBody[field];
if (value === null) {
delete next[field];
} else {
const error = providerTimeoutOverrideConfigError({ [field]: value });
if (error) return { error };
// A named, non-null JSON field can only pass validation with an integer.
next[field] = value as number;
}
touched = true;
}
// `null` or `{}` clears the block; anything else must pass the same check POST applies.
if (Object.hasOwn(rawBody, "modelDiscovery")) {
const value = rawBody.modelDiscovery;
const error = value === null ? null : providerModelDiscoveryConfigError(value);
if (error) return { error };
if (value === null || Object.keys(value as object).length === 0) delete next.modelDiscovery;
else next.modelDiscovery = structuredClone(value) as NonNullable<OcxProviderConfig["modelDiscovery"]>;
touched = true;
}
return { touched };
}