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

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,7 @@ const providerConfigSchema = z.object({
   modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
   preserveResponsesReasoningContent: z.boolean().optional(),
   allowPrivateNetwork: z.boolean().optional(),
+  upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES).optional(),
   noStructuredOutputModels: z.array(z.string().min(1))
     .transform(normalizeNonBlankStringArray)
     .optional(),
@@ -906,6 +908,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,

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",

tests/management-provider-validation.test.ts

@@ -3170,3 +3170,165 @@ describe("provider management validation", () => {
     }
   });
 });
+
+describe("provider upstreamHttpVersion management contract (#1668)", () => {
+  function makeConfig(): OcxConfig {
+    return {
+      port: 0,
+      hostname: "127.0.0.1",
+      defaultProvider: "nvidia",
+      providers: {
+        nvidia: {
+          adapter: "openai-chat",
+          baseUrl: "https://integrate.api.nvidia.com/v1",
+          apiKey: "sk-nvidia",
+        },
+      },
+    };
+  }
+
+  // Direct handleManagementAPI calls (no startServer) keep the whole contract in one
+  // synchronous authority, matching the request-pacing PATCH tests above.
+  async function withRequest(liveConfig: OcxConfig, run: (request: (path: string, init?: RequestInit) => Promise<Response | null>) => Promise<void>): Promise<void> {
+    const resolvedError = spyOn(destinationPolicy, "providerDestinationResolvedError")
+      .mockResolvedValue(null);
+    try {
+      const request = async (path: string, init?: RequestInit) => {
+        const req = new Request(`http://127.0.0.1${path}`, init);
+        return handleManagementAPI(req, new URL(req.url), liveConfig, {
+          createManagementConvergeCodex: catalogConvergenceFactory(),
+        });
+      };
+      await run(request);
+    } finally {
+      resolvedError.mockRestore();
+    }
+  }
+
+  test("POST accepts a valid upstreamHttpVersion and persists it; GET exposes it", async () => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    const liveConfig = makeConfig();
+    saveConfig(liveConfig);
+    await withRequest(liveConfig, async (request) => {
+      const created = await request("/api/providers", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          name: "h1-provider",
+          provider: {
+            adapter: "openai-chat",
+            baseUrl: "https://api.example.test/v1",
+            upstreamHttpVersion: "http1.1",
+          },
+        }),
+      });
+      expect(created?.status).toBe(200);
+      // Live config, disk reload, and the public GET row must all carry the pin.
+      expect(liveConfig.providers["h1-provider"]?.upstreamHttpVersion).toBe("http1.1");
+      expect(loadConfig().providers["h1-provider"]?.upstreamHttpVersion).toBe("http1.1");
+      const list = await request("/api/providers");
+      expect(await list?.json()).toContainEqual(expect.objectContaining({
+        name: "h1-provider",
+        upstreamHttpVersion: "http1.1",
+      }));
+    });
+  });
+
+  test("POST rejects an invalid upstreamHttpVersion at the write boundary without persisting", async () => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    const liveConfig = makeConfig();
+    saveConfig(liveConfig);
+    await withRequest(liveConfig, async (request) => {
+      const rejected = await request("/api/providers", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          name: "bad-version",
+          provider: {
+            adapter: "openai-chat",
+            baseUrl: "https://api.example.test/v1",
+            upstreamHttpVersion: "http3",
+          },
+        }),
+      });
+      expect(rejected?.status).toBe(400);
+      expect(await rejected?.json()).toMatchObject({
+        error: expect.stringContaining("upstreamHttpVersion"),
+      });
+      expect(loadConfig().providers["bad-version"]).toBeUndefined();
+    });
+  });
+
+  test("PATCH sets, then clears upstreamHttpVersion with live + disk persistence", async () => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    const liveConfig = makeConfig();
+    saveConfig(liveConfig);
+    await withRequest(liveConfig, async (request) => {
+      const set = await request("/api/providers?name=nvidia", {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ upstreamHttpVersion: "http1.1" }),
+      });
+      expect(set?.status).toBe(200);
+      expect(liveConfig.providers.nvidia?.upstreamHttpVersion).toBe("http1.1");
+      expect(loadConfig().providers.nvidia?.upstreamHttpVersion).toBe("http1.1");
+
+      const invalid = await request("/api/providers?name=nvidia", {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ upstreamHttpVersion: "h3" }),
+      });
+      expect(invalid?.status).toBe(400);
+      expect(liveConfig.providers.nvidia?.upstreamHttpVersion).toBe("http1.1");
+
+      const clear = await request("/api/providers?name=nvidia", {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ upstreamHttpVersion: null }),
+      });
+      expect(clear?.status).toBe(200);
+      expect(liveConfig.providers.nvidia?.upstreamHttpVersion).toBeUndefined();
+      expect(loadConfig().providers.nvidia?.upstreamHttpVersion).toBeUndefined();
+    });
+  });
+
+  test("safeConfigDTO exposes upstreamHttpVersion without leaking it into the live row", async () => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(TEST_DIR, { recursive: true });
+    process.env.OPENCODEX_HOME = TEST_DIR;
+    const liveConfig = makeConfig();
+    liveConfig.providers.nvidia = {
+      ...liveConfig.providers.nvidia!,
+      upstreamHttpVersion: "http1.1",
+    };
+    saveConfig(liveConfig);
+    const dto = safeConfigDTO(loadConfig()) as {
+      providers?: Record<string, Record<string, unknown>>;
+    };
+    expect(dto.providers?.nvidia?.upstreamHttpVersion).toBe("http1.1");
+  });
+
+  test("providerManagementConfigError rejects invalid upstreamHttpVersion values", () => {
+    expect(providerManagementConfigError("x", {
+      adapter: "openai-chat",
+      baseUrl: "https://api.example.test/v1",
+      upstreamHttpVersion: "http3",
+    })).toContain("upstreamHttpVersion");
+    expect(providerManagementConfigError("x", {
+      adapter: "openai-chat",
+      baseUrl: "https://api.example.test/v1",
+      upstreamHttpVersion: "http1.1",
+    })).toBeNull();
+    expect(providerManagementConfigError("x", {
+      adapter: "openai-chat",
+      baseUrl: "https://api.example.test/v1",
+      upstreamHttpVersion: 42,
+    })).toContain("upstreamHttpVersion");
+  });
+});