fix(server): add per-provider upstreamHttpVersion to pin Bun fetch HTTP version

docs-site/src/content/docs/reference/configuration/providers.md

@@ -67,6 +67,7 @@ differing backup and rewrites known legacy namespaced selected ids to bare ids.
 | `adapter` | `string` | One of `openai-chat`, `openai-responses`, `anthropic`, `google`, `kiro`, `cursor`, `azure-openai` (or alias `azure`). |
 | `baseUrl` | `string` | Upstream API base URL. Most built-in fixed endpoints ignore a mismatch; collision-safe key presets preserve an older same-named custom destination. |
 | `requestPacing?` | `{ enabled, requestsPerMinute?, minIntervalMs?, models? }` | Optional client-side outbound request-start pacing, separate from upstream usage, billing, and rate-limit indicators. RPM is converted to an even interval; `minIntervalMs` may impose a longer interval. Provider limits apply across all models, while `models` entries use exact upstream model IDs (for example `nvidia/llama-3.1-nemotron-ultra-253b-v1`) and can only add delay. Queue waits do not consume the upstream response-header timeout. HTTP, Responses WebSocket, and explicit adapter `fetchResponse`/`runTurn` dispatches are covered. |
+| `upstreamHttpVersion?` | `"auto" \| "http1.1" \| "h1" \| "http2" \| "h2"` | Pin the HTTP version used for upstream requests to this provider. Defaults to `auto`, which lets Bun negotiate. Set `http1.1` when a provider's HTTP/2 SSE stream stalls instead of delivering events — the symptom is a long-running streaming request that produces nothing and eventually times out. Management `POST`/`PATCH` accept `null` to clear it back to `auto`. |
 | `responsesPath?` | `string` | Relative resource path for key-auth `openai-responses` requests. It must start with `/` and contain no scheme, query, or fragment. |
 | `supportsServiceTier?` | `boolean` | Tri-state `service_tier` capability fallback. `true`: fast mode may inject and caller values are preserved. `false`: the field is stripped and never injected, and exact model declarations cannot reopen it. Absent: the provider is unclassified — caller-supplied values are preserved untouched and fast mode never injects unless an exact model is enabled. The registry classifies canonical OpenAI (`true`), DeepSeek, and Volcengine Ark (`false`); set it explicitly only for custom gateways that genuinely support tiers. Chat routes additionally need provider-wide or exact-model Chat authorization. |
 | `modelSupportsServiceTier?` | `Record<string, boolean>` | Exact upstream model capability overrides. Exact `true` authorizes that Chat model even without `chatServiceTier`; exact `false` narrows provider defaults and Chat authorization. An explicit provider-level `supportsServiceTier: false` remains fail-closed and cannot be reopened. Undeclared models fall back to provider-wide behavior. Management `PATCH /api/providers` merges entries and accepts `null` to clear one. |

src/config.ts

@@ -60,6 +60,7 @@ import {
   OPENAI_PROVIDER_TIER_VERSION,
   pinnedWireAdapter,
   REASONING_SUMMARY_DELIVERY_VALUES,
+  UPSTREAM_HTTP_VERSION_VALUES,
   type OcxClaudeCodeConfig,
   type OcxConfig,
   type OcxApiKeyEntry,
@@ -734,6 +735,12 @@ const providerConfigSchema = z.object({
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
   preserveResponsesReasoningContent: z.boolean().optional(),
   allowPrivateNetwork: z.boolean().optional(),
+  // The management API accepts `null` as "clear this", so a config written before the POST
+  // canonicalization below can hold one on disk. Rejecting it here would send the operator
+  // through invalid-config recovery for a value the API told them was fine.
+  upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES)
+    .nullish()
+    .transform(value => value ?? undefined),
   noStructuredOutputModels: z.array(z.string().min(1))
     .transform(normalizeNonBlankStringArray)
     .optional(),
@@ -906,6 +913,20 @@ export function apiKeyTransportConfigError(
   return null;
 }
 
+/**
+ * Shared runtime boundary for the per-provider upstream HTTP-version pin (#1668). Used by
+ * the management write path (providerManagementConfigError / PATCH) so it can never disagree
+ * with the strict zod load schema: a value that survives POST/PATCH is always loadable, and
+ * a value the loader rejects is rejected at write time too.
+ */
+export function upstreamHttpVersionConfigError(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || !(UPSTREAM_HTTP_VERSION_VALUES as readonly string[]).includes(value)) {
+    return 'upstreamHttpVersion must be one of "auto", "http1.1", "h1", "http2", "h2", or null to clear';
+  }
+  return null;
+}
+
 export function positiveIntegerRecordConfigError(value: unknown, field: string): string | null {
   if (value === undefined) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;

src/server/auth-cors.ts

@@ -16,6 +16,7 @@ import {
   retryOn429PolicyConfigError,
   requestPacingConfigError,
   sanitizeModelCostsForDisplay,
+  upstreamHttpVersionConfigError,
 } from "../config";
 import { providerDestinationConfigError } from "../lib/destination-policy";
 import { redactSecretString } from "../lib/redact";
@@ -520,6 +521,10 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
   if (requestPacingError) {
     return `provider ${JSON.stringify(redactSecretString(name))} ${requestPacingError}`;
   }
+  const upstreamHttpVersionError = upstreamHttpVersionConfigError(raw.upstreamHttpVersion);
+  if (upstreamHttpVersionError) {
+    return `provider ${JSON.stringify(redactSecretString(name))} ${upstreamHttpVersionError}`;
+  }
   const modelCostsError = providerModelCostsConfigError(raw.modelCosts);
   if (modelCostsError) {
     // The provider name is caller-controlled and can be token-shaped; redact and JSON-escape
@@ -640,6 +645,7 @@ export function safeConfigDTO(config: OcxConfig): unknown {
       "noTopPModels",
       "noPenaltyModels",
       "noStructuredOutputModels",
+      "upstreamHttpVersion",
       "autoToolChoiceOnlyModels",
       "preserveReasoningContentModels",
       "requiresReasoningPlaceholderModels",

src/server/management/provider-routes.ts

@@ -17,6 +17,7 @@ import {
   requestPacingConfigError,
   readConfigAdmissionSnapshot,
   saveConfigPreservingClaudeCode,
+  upstreamHttpVersionConfigError,
   withConfigMutationLockSync,
 } from "../../config";
 import {
@@ -194,6 +195,19 @@ function applyProviderPatchFields(
     }
     touched = true;
   }
+  if (Object.hasOwn(rawBody, "upstreamHttpVersion")) {
+    const value = rawBody.upstreamHttpVersion;
+    if (value === null || value === "") {
+      delete next.upstreamHttpVersion;
+    } else {
+      const versionError = upstreamHttpVersionConfigError(value);
+      if (versionError) return { error: versionError };
+      // `upstreamHttpVersionConfigError` is the shared write boundary; the assertion is
+      // explicit because the incoming value is an unknown JSON scalar.
+      next.upstreamHttpVersion = value as OcxProviderConfig["upstreamHttpVersion"];
+    }
+    touched = true;
+  }
   // The Models page edits the catalog hints in place; keep them on the existing
   // provider mutation path so validation, cache invalidation, and convergence stay unified (#1073).
   if (Object.hasOwn(rawBody, "contextWindow")) {
@@ -374,6 +388,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       modelContextWindows: p.modelContextWindows,
       modelSupportsServiceTier: p.modelSupportsServiceTier,
       noStructuredOutputModels: p.noStructuredOutputModels,
+      upstreamHttpVersion: p.upstreamHttpVersion,
       authMode: p.authMode,
       apiKeyTransport: p.apiKeyTransport,
       disabled: p.disabled === true,
@@ -466,6 +481,10 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     const serviceTierError = providerServiceTierConfigError(name, body.provider);
     if (serviceTierError) return jsonResponse({ error: serviceTierError }, 400);
     const prov = body.provider ? stripCodexRuntimeProviderFields(body.provider as OcxProviderConfig) : undefined;
+    // PATCH already clears on null; POST persisted the body as submitted, so a `null` here
+    // reached disk and the next loadConfig() refused it. Canonicalize to absent, which is what
+    // "clear" means everywhere else.
+    if (prov && prov.upstreamHttpVersion === null) delete prov.upstreamHttpVersion;
     if (!name || !prov?.adapter || !prov?.baseUrl) {
       return jsonResponse({ error: "name, provider.adapter and provider.baseUrl are required" }, 400);
     }

src/server/responses/fetch-helpers.ts

@@ -33,7 +33,7 @@ import {
 import { isInjectionDebugEnabled } from "../../lib/debug-settings";
 import { injectionDebugLog } from "../../lib/injection-debug-log";
 import { modelInList, namespacedToolName } from "../../types";
-import type { AdapterEvent, OcxConfig, OcxParsedRequest, OcxProviderConfig, OcxProviderContinuationState, OcxUsage } from "../../types";
+import type { AdapterEvent, OcxConfig, OcxParsedRequest, OcxProviderConfig, OcxProviderContinuationState, OcxUsage, UpstreamHttpVersion } from "../../types";
 import {
   forceRefreshOAuthAccessSnapshot,
   getOAuthCredentialApiBaseUrl,
@@ -149,6 +149,38 @@ export interface ProviderFetchOptions {
   modelId?: string;
 }
 
+/**
+ * Bun's fetch accepts a non-standard `protocol` init to pin the HTTP version
+ * (BunFetchRequestInit.protocol). The DOM lib types do not include it, so the
+ * value is carried on an intersection and stripped before non-Bun callers.
+ * The accepted values are the shared UPSTREAM_HTTP_VERSION_VALUES enum from types.
+ */
+const UPSTREAM_HTTP_VERSION_PROTOCOL: Record<Exclude<UpstreamHttpVersion, "auto">, string> = {
+  "http1.1": "http1.1",
+  h1: "h1",
+  http2: "http2",
+  h2: "h2",
+};
+
+/** Attach Bun's `protocol` pin when the provider opted into a fixed HTTP version. */
+export function withUpstreamHttpVersion(
+  input: Parameters<typeof globalThis.fetch>[0],
+  init: RequestInit | undefined,
+  provider: OcxProviderConfig,
+): RequestInit | undefined {
+  const version = provider.upstreamHttpVersion;
+  if (!version || version === "auto") return init;
+  // Bun's protocol pin requires an https: target; local/plaintext upstreams keep
+  // their existing transport untouched.
+  const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  try {
+    if (new URL(target).protocol !== "https:") return init;
+  } catch {
+    return init;
+  }
+  return { ...(init ?? {}), protocol: UPSTREAM_HTTP_VERSION_PROTOCOL[version] } as RequestInit;
+}
+
 export function providerFetch(
   provider: OcxProviderConfig,
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
@@ -162,7 +194,7 @@ export function providerFetch(
     if (typeof input === "string" && init && shouldUseCodexWsUpstream(input, init, runtime)) {
       return codexWsUpstreamFetch(input, init, base, runtime);
     }
-    return base(input, init);
+    return base(input, withUpstreamHttpVersion(input, init, provider));
   };
   const waitForPacing = (signal?: AbortSignal) => options.providerName
     ? waitForProviderRequestSlot(options.providerName, provider, options.modelId, signal)

src/types.ts

@@ -1375,6 +1375,14 @@ export interface OcxProviderConfig {
    * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
    */
   allowPrivateNetwork?: boolean;
+  /**
+   * Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
+   * HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
+   * HTTP/2 streaming responses (issue #1668). "http1.1" / "h1" forces HTTP/1.1,
+   * "http2" / "h2" forces HTTP/2. Absent or "auto" keeps Bun's default negotiation
+   * (current behavior unchanged). Only meaningful for https: base URLs.
+   */
+  upstreamHttpVersion?: UpstreamHttpVersion;
   /** Keep provider settings on disk but exclude it from routing and model/catalog listings. */
   disabled?: boolean;
   /**
@@ -1668,6 +1676,21 @@ export interface OcxProviderConfig {
   nativeLocalExec?: "off" | "codex-sandbox" | "on";
 }
 
+/**
+ * Accepted values for the per-provider upstream HTTP-version pin (#1668). Shared by the
+ * zod load schema, the management write boundary (POST/PATCH), and the fetch runtime, so
+ * a value that one boundary accepts can never be rejected by another.
+ */
+export const UPSTREAM_HTTP_VERSION_VALUES = [
+  "auto",
+  "http1.1",
+  "h1",
+  "http2",
+  "h2",
+] as const;
+
+export type UpstreamHttpVersion = (typeof UPSTREAM_HTTP_VERSION_VALUES)[number];
+
 export const REASONING_SUMMARY_DELIVERY_VALUES = [
   "sequential",
   "sequential_cutoff",