Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

refactor(providers): split proxy route adapters (#1934)

JD Davise6243f65c967
diff --git a/headroom/integrations/litellm_callback.py b/headroom/integrations/litellm_callback.py
index 7256d85b8..680805434 100644
--- a/headroom/integrations/litellm_callback.py
+++ b/headroom/integrations/litellm_callback.py
@@ -102,6 +102,7 @@ class HeadroomCallback(_CustomLogger):
"""Called by LiteLLM before each API call. Compresses messages."""
if isinstance(cache, dict) and isinstance(data, str):
data, call_type = cache, data
+
if data is None:
return None
diff --git a/headroom/providers/cloudcode/__init__.py b/headroom/providers/cloudcode/__init__.py
new file mode 100644
index 000000000..4658e6106
--- /dev/null
+++ b/headroom/providers/cloudcode/__init__.py
@@ -0,0 +1,5 @@
+"""Cloud Code provider helpers."""
+
+from .runtime import normalize_cloudcode_passthrough_path
+
+__all__ = ["normalize_cloudcode_passthrough_path"]
diff --git a/headroom/providers/cloudcode/runtime.py b/headroom/providers/cloudcode/runtime.py
new file mode 100644
index 000000000..2e0cf637a
--- /dev/null
+++ b/headroom/providers/cloudcode/runtime.py
@@ -0,0 +1,16 @@
+"""Cloud Code Assist route classification helpers."""
+
+from __future__ import annotations
+
+CLOUDCODE_INTERNAL_PREFIX = "v1internal:"
+CLOUDCODE_VERSIONED_INTERNAL_PREFIX = "v1/v1internal:"
+
+
+def normalize_cloudcode_passthrough_path(path: str) -> str | None:
+ """Return the canonical Cloud Code internal path, or ``None`` when unrelated."""
+ clean_path = path.lstrip("/")
+ if not clean_path.startswith((CLOUDCODE_INTERNAL_PREFIX, CLOUDCODE_VERSIONED_INTERNAL_PREFIX)):
+ return None
+ if clean_path.startswith("v1/"):
+ clean_path = clean_path[3:]
+ return f"/{clean_path}"
diff --git a/headroom/providers/codex/__init__.py b/headroom/providers/codex/__init__.py
index 09dd793b4..1cbc4e9f6 100644
--- a/headroom/providers/codex/__init__.py
+++ b/headroom/providers/codex/__init__.py
@@ -1,5 +1,21 @@
"""Codex-specific provider helpers."""
-from .runtime import DEFAULT_API_URL, build_launch_env, proxy_base_url
+from .runtime import (
+ DEFAULT_API_URL,
+ CodexRoutingDecision,
+ build_launch_env,
+ decode_openai_bearer_payload,
+ proxy_base_url,
+ resolve_codex_routing,
+ resolve_codex_routing_headers,
+)
-__all__ = ["DEFAULT_API_URL", "build_launch_env", "proxy_base_url"]
+__all__ = [
+ "DEFAULT_API_URL",
+ "CodexRoutingDecision",
+ "build_launch_env",
+ "decode_openai_bearer_payload",
+ "proxy_base_url",
+ "resolve_codex_routing",
+ "resolve_codex_routing_headers",
+]
diff --git a/headroom/providers/codex/endpoints.py b/headroom/providers/codex/endpoints.py
new file mode 100644
index 000000000..4671bf71e
--- /dev/null
+++ b/headroom/providers/codex/endpoints.py
@@ -0,0 +1,27 @@
+"""ChatGPT Codex backend endpoint formulas."""
+
+from __future__ import annotations
+
+CHATGPT_BACKEND_API_URL = "https://chatgpt.com"
+CHATGPT_BACKEND_WS_URL = "wss://chatgpt.com"
+CODEX_BACKEND_PREFIX = "/backend-api/codex"
+
+
+def chatgpt_backend_url(path: str, query: str = "") -> str:
+ """Return a ChatGPT HTTPS backend URL for an absolute backend path."""
+ url = f"{CHATGPT_BACKEND_API_URL}{path}"
+ if query:
+ return f"{url}?{query}"
+ return url
+
+
+def codex_backend_url(path: str, query: str = "") -> str:
+ """Return a ChatGPT HTTPS backend URL under `/backend-api/codex`."""
+ path_suffix = path if path.startswith("/") else f"/{path}"
+ return chatgpt_backend_url(f"{CODEX_BACKEND_PREFIX}{path_suffix}", query)
+
+
+def codex_backend_ws_url(path: str = "") -> str:
+ """Return a ChatGPT WebSocket backend URL under `/backend-api/codex`."""
+ path_suffix = path if not path or path.startswith("/") else f"/{path}"
+ return f"{CHATGPT_BACKEND_WS_URL}{CODEX_BACKEND_PREFIX}{path_suffix}"
diff --git a/headroom/providers/codex/headers.py b/headroom/providers/codex/headers.py
new file mode 100644
index 000000000..8a5835f62
--- /dev/null
+++ b/headroom/providers/codex/headers.py
@@ -0,0 +1,21 @@
+"""Case-insensitive header helpers for Codex provider adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+def header_name(headers: Mapping[str, str], name: str) -> str | None:
+ """Return the existing header key matching ``name`` case-insensitively."""
+ lowered = name.lower()
+ for header_name_value in headers:
+ if header_name_value.lower() == lowered:
+ return header_name_value
+ return None
+
+
+def drop_header(headers: dict[str, str], name: str) -> None:
+ """Remove the header matching ``name`` case-insensitively from ``headers``."""
+ existing_name = header_name(headers, name)
+ if existing_name is not None:
+ headers.pop(existing_name, None)
diff --git a/headroom/providers/codex/images.py b/headroom/providers/codex/images.py
new file mode 100644
index 000000000..92b0edd55
--- /dev/null
+++ b/headroom/providers/codex/images.py
@@ -0,0 +1,111 @@
+"""Codex ChatGPT-subscription image forwarding."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from typing import Any, Protocol
+
+from fastapi import Request
+from fastapi.responses import Response
+from starlette.requests import ClientDisconnect
+
+from headroom.proxy.helpers import _strip_internal_headers
+
+from .endpoints import codex_backend_url
+from .headers import drop_header
+from .runtime import resolve_codex_routing
+
+logger = logging.getLogger("headroom.providers.codex.images")
+
+
+class CodexImageForwardResponse(Protocol):
+ """HTTP response surface used by Codex image forwarding."""
+
+ status_code: int
+ content: bytes
+ headers: Mapping[str, str]
+
+
+class CodexImageForwardHttpClient(Protocol):
+ """HTTP client surface needed to forward Codex image requests."""
+
+ async def request(self, method: str, url: str, **kwargs: Any) -> CodexImageForwardResponse:
+ """Issue an HTTP request and return an httpx-like response."""
+ ...
+
+
+def normalize_codex_image_headers(headers: Mapping[str, str]) -> tuple[dict[str, str], bool]:
+ """Prepare inbound headers for ChatGPT Codex image forwarding."""
+ upstream_headers = dict(headers)
+ drop_header(upstream_headers, "host")
+ drop_header(upstream_headers, "accept-encoding")
+ upstream_headers = _strip_internal_headers(upstream_headers)
+ decision = resolve_codex_routing(upstream_headers)
+ return decision.headers, decision.is_chatgpt_auth
+
+
+def codex_image_url(sub_path: str, query: str = "") -> str:
+ """Return the ChatGPT Codex image upstream URL for a route subpath."""
+ return codex_backend_url(f"/images/{sub_path}", query)
+
+
+def sanitize_codex_image_response_headers(headers: Mapping[str, str]) -> dict[str, str]:
+ """Drop stale compression/framing headers after materializing response bytes."""
+ response_headers = dict(headers)
+ drop_header(response_headers, "content-encoding")
+ drop_header(response_headers, "content-length")
+ drop_header(response_headers, "server")
+ return response_headers
+
+
+def codex_image_forward_error_response() -> Response:
+ """Return the stable client-facing error for failed Codex image forwarding."""
+ return Response(
+ content=json.dumps(
+ {
+ "error": {
+ "type": "upstream_error",
+ "message": "Failed to forward Codex image request",
+ }
+ }
+ ),
+ status_code=502,
+ media_type="application/json",
+ )
+
+
+async def handle_chatgpt_codex_images(
+ http_client: CodexImageForwardHttpClient | None,
+ request: Request,
+ sub_path: str,
+) -> Response | None:
+ """Forward Codex OAuth image requests to ChatGPT's Codex image backend."""
+ headers, is_chatgpt_auth = normalize_codex_image_headers(dict(request.headers.items()))
+ if not is_chatgpt_auth:
+ return None
+
+ try:
+ body = await request.body()
+ except ClientDisconnect:
+ logger.debug("Client disconnected during body read for passthrough")
+ return Response(status_code=204)
+ try:
+ if http_client is None:
+ raise RuntimeError("No HTTP client configured for Codex image forwarding")
+ resp = await http_client.request(
+ request.method,
+ codex_image_url(sub_path, request.url.query),
+ headers=headers,
+ content=body,
+ timeout=120.0,
+ )
+ return Response(
+ content=resp.content,
+ status_code=resp.status_code,
+ headers=sanitize_codex_image_response_headers(resp.headers),
+ )
+ except Exception as exc:
+ logger.error("Passthrough /v1/images/%s failed: %s", sub_path, exc)
+ return codex_image_forward_error_response()
diff --git a/headroom/providers/codex/model_metadata.py b/headroom/providers/codex/model_metadata.py
new file mode 100644
index 000000000..f00f46405
--- /dev/null
+++ b/headroom/providers/codex/model_metadata.py
@@ -0,0 +1,386 @@
+"""Codex ChatGPT-subscription model metadata handling."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.parse import quote
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from .endpoints import chatgpt_backend_url, codex_backend_url
+from .headers import drop_header, header_name
+from .runtime import resolve_codex_routing
+
+logger = logging.getLogger("headroom.providers.codex.model_metadata")
+DEFAULT_CODEX_CLIENT_VERSION = "0.130.0"
+
+
+@dataclass(frozen=True, slots=True)
+class CodexModelRegistryOptions:
+ """Configuration for ChatGPT Codex model-registry lookups."""
+
+ default_client_version: str = DEFAULT_CODEX_CLIENT_VERSION
+ timeout_seconds: float = 15.0
+
+
+class CodexModelRegistryResponse(Protocol):
+ """HTTP response surface used by Codex model metadata helpers."""
+
+ status_code: int
+ text: str
+ content: bytes
+ headers: Mapping[str, str]
+
+ def json(self) -> Any:
+ """Parse response JSON."""
+ ...
+
+
+class CodexModelRegistryHttpClient(Protocol):
+ """HTTP client surface needed to fetch the Codex model registry."""
+
+ async def get(self, url: str, **kwargs: Any) -> CodexModelRegistryResponse:
+ """Issue a GET request and return an httpx-like response."""
+ ...
+
+ async def request(self, method: str, url: str, **kwargs: Any) -> CodexModelRegistryResponse:
+ """Issue a generic request and return an httpx-like response."""
+ ...
+
+
+# Codex ChatGPT-subscription auth cannot call `chatgpt.com/backend-api/models`
+# with OAuth bearer tokens. These are known-good Codex model slugs used when
+# the provider registry is unavailable.
+CHATGPT_AUTH_CODEX_MODELS: tuple[str, ...] = (
+ "gpt-5.5",
+ "gpt-5.4",
+ "gpt-5.3",
+ "gpt-5.2",
+ "gpt-5.1",
+ "gpt-5",
+)
+
+
+CODEX_REASONING_LEVELS: tuple[dict[str, str], ...] = (
+ {"effort": "low", "description": "Fast responses with lighter reasoning"},
+ {
+ "effort": "medium",
+ "description": "Balances speed and reasoning depth for everyday tasks",
+ },
+ {"effort": "high", "description": "Greater reasoning depth for complex problems"},
+ {"effort": "xhigh", "description": "Extra high reasoning depth for complex problems"},
+)
+
+
+def codex_client_version(
+ requested_client_version: str | None = None,
+ options: CodexModelRegistryOptions = CodexModelRegistryOptions(),
+) -> str:
+ """Return the Codex client version to use for model-registry requests."""
+ if requested_client_version:
+ return requested_client_version
+ return options.default_client_version
+
+
+def _json_response(payload: dict[str, Any], status_code: int = 200) -> Response:
+ return Response(
+ content=json.dumps(payload),
+ status_code=status_code,
+ headers={"content-type": "application/json"},
+ )
+
+
+def _model_payload(model_id: str) -> dict[str, Any]:
+ return {
+ "id": model_id,
+ "object": "model",
+ "created": 0,
+ "owned_by": "openai",
+ }
+
+
+def display_name_from_model_id(model_id: str) -> str:
+ """Return the Codex display name for a model slug."""
+ return "-".join(
+ part.upper() if part == "gpt" else part.capitalize() for part in model_id.split("-")
+ )
+
+
+def codex_model_registry_entry(
+ model_id: str,
+ upstream_entry: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Return Codex app-server model metadata with required registry fields."""
+ entry = dict(upstream_entry or {})
+ entry["slug"] = model_id
+ entry.setdefault("display_name", display_name_from_model_id(model_id))
+ entry.setdefault("description", "Codex model available through ChatGPT subscription auth.")
+ entry.setdefault("default_reasoning_level", "medium")
+ entry.setdefault("supported_reasoning_levels", list(CODEX_REASONING_LEVELS))
+ entry.setdefault("shell_type", "shell_command")
+ entry.setdefault("visibility", "list")
+ entry.setdefault("supported_in_api", True)
+ entry.setdefault("priority", 50)
+ entry.setdefault("additional_speed_tiers", ["fast"])
+ entry.setdefault(
+ "service_tiers",
+ [{"id": "priority", "name": "Fast", "description": "1.5x speed, increased usage"}],
+ )
+ entry.setdefault("availability_nux", None)
+ entry.setdefault("upgrade", None)
+ entry.setdefault("context_window", 272000)
+ entry.setdefault("max_context_window", 272000)
+ entry.setdefault("effective_context_window_percent", 95)
+ entry.setdefault("experimental_supported_tools", [])
+ entry.setdefault("input_modalities", ["text", "image"])
+ entry.setdefault("supports_search_tool", True)
+ entry.setdefault("use_responses_lite", False)
+ entry.setdefault("support_verbosity", True)
+ entry.setdefault("default_verbosity", "low")
+ entry.setdefault("apply_patch_tool_type", "freeform")
+ entry.setdefault("web_search_tool_type", "text_and_image")
+ entry.setdefault("truncation_policy", {"mode": "tokens", "limit": 10000})
+ entry.setdefault("supports_image_detail_original", True)
+ entry.setdefault("supports_parallel_tool_calls", True)
+ entry.setdefault("supports_reasoning_summaries", True)
+ entry.setdefault("default_reasoning_summary", "none")
+ return entry
+
+
+def _model_not_found_response(model_id: str) -> Response:
+ return _json_response(
+ {
+ "error": {
+ "message": f"Model {model_id!r} not available under ChatGPT auth",
+ "type": "invalid_request_error",
+ "code": "model_not_found",
+ }
+ },
+ status_code=404,
+ )
+
+
+def models_list_response_from_entries(model_entries: tuple[dict[str, Any], ...]) -> Response:
+ """Build an OpenAI-compatible model-list response."""
+ model_ids = tuple(
+ slug
+ for entry in model_entries
+ for slug in (entry.get("slug"),)
+ if isinstance(slug, str) and slug
+ )
+ return _json_response(
+ {
+ "object": "list",
+ "data": [_model_payload(model_id) for model_id in model_ids],
+ "models": list(model_entries),
+ }
+ )
+
+
+def models_list_response(model_ids: tuple[str, ...]) -> Response:
+ """Build a model-list response from model slugs."""
+ return models_list_response_from_entries(
+ tuple(codex_model_registry_entry(model_id) for model_id in model_ids)
+ )
+
+
+def synthetic_models_list_response() -> Response:
+ """OpenAI-compatible `/v1/models` payload for Codex ChatGPT auth."""
+ return models_list_response(CHATGPT_AUTH_CODEX_MODELS)
+
+
+def synthetic_model_get_response(model_id: str) -> Response:
+ """OpenAI-compatible `/v1/models/{id}` payload."""
+ if model_id not in CHATGPT_AUTH_CODEX_MODELS:
+ return _model_not_found_response(model_id)
+ return _json_response(_model_payload(model_id))
+
+
+def normalize_codex_registry_headers(headers: Mapping[str, str]) -> dict[str, str]:
+ """Prepare inbound ChatGPT auth headers for the Codex model registry."""
+ upstream_headers = dict(headers)
+ drop_header(upstream_headers, "host")
+
+ account_header = header_name(upstream_headers, "chatgpt-account-id")
+ account_id = upstream_headers.get(account_header, "") if account_header else ""
+ if account_header is not None and account_id:
+ upstream_headers["chatgpt-account-id"] = account_id
+ if account_header != "chatgpt-account-id":
+ upstream_headers.pop(account_header, None)
+
+ upstream_headers["accept"] = "application/json"
+ for existing_header_name in list(upstream_headers):
+ if existing_header_name.lower() == "accept" and existing_header_name != "accept":
+ upstream_headers.pop(existing_header_name, None)
+ return upstream_headers
+
+
+async def fetch_chatgpt_codex_model_entries(
+ http_client: CodexModelRegistryHttpClient,
+ headers: Mapping[str, str],
+ requested_client_version: str | None,
+ options: CodexModelRegistryOptions = CodexModelRegistryOptions(),
+) -> tuple[dict[str, Any], ...] | None:
+ """Fetch Codex model metadata from ChatGPT, returning None when fallback should apply."""
+ client_version = codex_client_version(requested_client_version, options)
+ upstream_headers = normalize_codex_registry_headers(headers)
+ url = codex_backend_url("models", f"client_version={quote(client_version, safe='')}")
+ try:
+ resp = await http_client.get(
+ url,
+ headers=upstream_headers,
+ timeout=options.timeout_seconds,
+ )
+ if resp.status_code >= 400:
+ logger.warning(
+ "Codex model registry fetch failed: HTTP %s: %s",
+ resp.status_code,
+ resp.text[:300],
+ )
+ return None
+
+ data = resp.json()
+ models_raw = data.get("models") if isinstance(data, dict) else None
+ if not isinstance(models_raw, list):
+ logger.warning("Codex model registry response did not contain models[]")
+ return None
+
+ model_entries = tuple(
+ codex_model_registry_entry(slug, entry)
+ for entry in models_raw
+ if isinstance(entry, dict)
+ for slug in (entry.get("slug"),)
+ if isinstance(slug, str) and slug
+ )
+ if not model_entries:
+ logger.warning("Codex model registry returned no model slugs")
+ return None
+
+ model_ids = [entry["slug"] for entry in model_entries]
+ logger.info("Fetched %d Codex models from upstream model registry", len(model_entries))
+ logger.debug("Fetched Codex model IDs from upstream model registry: %s", model_ids)
+ return model_entries
+ except Exception:
+ logger.exception("Codex model registry fetch failed")
+ return None
+
+
+async def fetch_chatgpt_codex_model_ids(
+ http_client: CodexModelRegistryHttpClient,
+ headers: Mapping[str, str],
+ requested_client_version: str | None,
+ options: CodexModelRegistryOptions = CodexModelRegistryOptions(),
+) -> tuple[str, ...] | None:
+ """Fetch Codex model slugs from ChatGPT, returning None when fallback should apply."""
+ model_entries = await fetch_chatgpt_codex_model_entries(
+ http_client,
+ headers,
+ requested_client_version,
+ options,
+ )
+ if model_entries is None:
+ return None
+ return tuple(
+ slug
+ for entry in model_entries
+ for slug in (entry.get("slug"),)
+ if isinstance(slug, str) and slug
+ )
+
+
+async def fetch_chatgpt_codex_models_response(
+ http_client: CodexModelRegistryHttpClient,
+ headers: Mapping[str, str],
+ requested_client_version: str | None,
+) -> Response | None:
+ """Build a dynamic `/v1/models` response from the Codex registry when available."""
+ model_entries = await fetch_chatgpt_codex_model_entries(
+ http_client, headers, requested_client_version
+ )
+ if model_entries is None:
+ return None
+ return models_list_response_from_entries(model_entries)
+
+
+async def fetch_chatgpt_codex_model_get_response(
+ http_client: CodexModelRegistryHttpClient,
+ headers: Mapping[str, str],
+ model_id: str,
+ requested_client_version: str | None,
+) -> Response | None:
+ """Build a dynamic `/v1/models/{id}` response from the Codex registry when available."""
+ model_entries = await fetch_chatgpt_codex_model_entries(
+ http_client, headers, requested_client_version
+ )
+ if model_entries is None:
+ return None
+ model_ids = tuple(
+ slug
+ for entry in model_entries
+ for slug in (entry.get("slug"),)
+ if isinstance(slug, str) and slug
+ )
+ if model_id in model_ids:
+ return _json_response(_model_payload(model_id))
+ return _model_not_found_response(model_id)
+
+
+async def handle_chatgpt_model_metadata(
+ http_client: CodexModelRegistryHttpClient,
+ request: Request,
+ upstream_path: str,
+) -> Response | None:
+ """Handle Codex ChatGPT-auth model metadata or return None for normal routing."""
+ headers = dict(request.headers.items())
+ drop_header(headers, "host")
+ routing = resolve_codex_routing(headers)
+ if not routing.is_chatgpt_auth:
+ return None
+ headers = routing.headers
+
+ requested_client_version = request.query_params.get("client_version")
+ if upstream_path == "/backend-api/models":
+ upstream_response = await fetch_chatgpt_codex_models_response(
+ http_client,
+ headers,
+ requested_client_version,
+ )
+ if upstream_response is not None:
+ return upstream_response
+ return synthetic_models_list_response()
+ if upstream_path.startswith("/backend-api/models/"):
+ model_id = upstream_path[len("/backend-api/models/") :]
+ upstream_response = await fetch_chatgpt_codex_model_get_response(
+ http_client,
+ headers,
+ model_id,
+ requested_client_version,
+ )
+ if upstream_response is not None:
+ return upstream_response
+ return synthetic_model_get_response(model_id)
+
+ url = chatgpt_backend_url(upstream_path, request.url.query)
+
+ body = await request.body()
+ try:
+ resp = await http_client.request(
+ request.method,
+ url,
+ headers=headers,
+ content=body,
+ timeout=120.0,
+ )
+ return Response(
+ content=resp.content,
+ status_code=resp.status_code,
+ headers=dict(resp.headers),
+ )
+ except Exception:
+ logger.exception("Passthrough %s failed", upstream_path)
+ return Response(content="Upstream request failed.", status_code=502)
diff --git a/headroom/providers/codex/responses.py b/headroom/providers/codex/responses.py
new file mode 100644
index 000000000..34423ac75
--- /dev/null
+++ b/headroom/providers/codex/responses.py
@@ -0,0 +1,94 @@
+"""Codex ChatGPT-subscription Responses passthrough helpers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any, Protocol
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from .endpoints import codex_backend_url, codex_backend_ws_url
+from .headers import drop_header, header_name
+from .runtime import resolve_codex_routing
+
+logger = logging.getLogger("headroom.providers.codex.responses")
+
+
+class CodexResponsesPassthroughResponse(Protocol):
+ """HTTP response surface used by Codex Responses passthrough."""
+
+ status_code: int
+ content: bytes
+ headers: Mapping[str, str]
+
+
+class CodexResponsesPassthroughHttpClient(Protocol):
+ """HTTP client surface needed to forward Codex Responses subpaths."""
+
+ async def request(
+ self,
+ method: str,
+ url: str,
+ **kwargs: Any,
+ ) -> CodexResponsesPassthroughResponse:
+ """Issue an HTTP request and return an httpx-like response."""
+ ...
+
+
+def normalize_codex_responses_headers(headers: Mapping[str, str]) -> tuple[dict[str, str], bool]:
+ """Prepare inbound headers for ChatGPT Codex Responses passthrough."""
+ upstream_headers = dict(headers)
+ drop_header(upstream_headers, "host")
+ decision = resolve_codex_routing(upstream_headers)
+ return decision.headers, decision.is_chatgpt_auth
+
+
+def codex_responses_subpath_url(sub_path: str, query: str = "") -> str:
+ """Return the ChatGPT Codex Responses upstream URL for a route subpath."""
+ return codex_backend_url(f"/responses/{sub_path}", query)
+
+
+def codex_responses_http_url(query: str = "") -> str:
+ """Return the ChatGPT Codex Responses HTTP upstream URL."""
+ return codex_backend_url("/responses", query)
+
+
+def codex_responses_websocket_url() -> str:
+ """Return the ChatGPT Codex Responses WebSocket upstream URL."""
+ return codex_backend_ws_url("/responses")
+
+
+def has_chatgpt_account_header(headers: Mapping[str, str]) -> bool:
+ """Return whether resolved headers contain a ChatGPT account routing hint."""
+ return header_name(headers, "chatgpt-account-id") is not None
+
+
+async def handle_chatgpt_codex_responses_subpath(
+ http_client: CodexResponsesPassthroughHttpClient,
+ request: Request,
+ sub_path: str,
+) -> Response | None:
+ """Forward ChatGPT-auth Codex Responses subpaths or return None for OpenAI fallback."""
+ headers, is_chatgpt_auth = normalize_codex_responses_headers(dict(request.headers.items()))
+ if not is_chatgpt_auth:
+ return None
+
+ body = await request.body()
+ try:
+ resp = await http_client.request(
+ request.method,
+ codex_responses_subpath_url(sub_path, request.url.query),
+ headers=headers,
+ content=body,
+ timeout=120.0,
+ )
+ return Response(
+ content=resp.content,
+ status_code=resp.status_code,
+ headers=dict(resp.headers),
+ )
+ except Exception:
+ logger.exception("Passthrough /v1/responses/%s failed", sub_path)
+ return Response(content="Upstream request failed.", status_code=502)
diff --git a/headroom/providers/codex/runtime.py b/headroom/providers/codex/runtime.py
index c96e5493b..d25ea0e3a 100644
--- a/headroom/providers/codex/runtime.py
+++ b/headroom/providers/codex/runtime.py
@@ -2,12 +2,24 @@
from __future__ import annotations
+import base64
+import json
import os
from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
DEFAULT_API_URL = "https://api.openai.com"
+@dataclass(frozen=True, slots=True)
+class CodexRoutingDecision:
+ """Resolved Codex routing headers and whether they target ChatGPT auth."""
+
+ headers: dict[str, str]
+ is_chatgpt_auth: bool
+
+
def proxy_base_url(port: int) -> str:
"""Return the local proxy base URL used by OpenAI-compatible integrations."""
return f"http://127.0.0.1:{port}/v1"
@@ -21,3 +33,52 @@ def build_launch_env(
base_url = proxy_base_url(port)
env["OPENAI_BASE_URL"] = base_url
return env, [f"OPENAI_BASE_URL={base_url}"]
+
+
+def decode_openai_bearer_payload(headers: Mapping[str, str]) -> dict[str, Any] | None:
+ """Best-effort decode of an OpenAI OAuth bearer token payload.
+
+ This intentionally does not verify the JWT signature. The decoded payload is
+ only a routing hint; upstream still performs the actual authorization.
+ """
+ auth = headers.get("authorization") or headers.get("Authorization")
+ if not auth:
+ return None
+
+ scheme, _, token = auth.partition(" ")
+ if scheme.lower() != "bearer" or token.count(".") < 2:
+ return None
+
+ payload = token.split(".", 2)[1]
+ payload += "=" * (-len(payload) % 4)
+ try:
+ decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
+ data = json.loads(decoded.decode("utf-8"))
+ except (ValueError, UnicodeDecodeError):
+ return None
+
+ return data if isinstance(data, dict) else None
+
+
+def resolve_codex_routing(headers: Mapping[str, str]) -> CodexRoutingDecision:
+ """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""
+ resolved = dict(headers)
+ lower_lookup = {key.lower(): key for key in resolved}
+
+ if "chatgpt-account-id" in lower_lookup:
+ return CodexRoutingDecision(headers=resolved, is_chatgpt_auth=True)
+
+ payload = decode_openai_bearer_payload(resolved)
+ auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None
+ account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None
+ if isinstance(account_id, str) and account_id.strip():
+ resolved["ChatGPT-Account-ID"] = account_id.strip()
+ return CodexRoutingDecision(headers=resolved, is_chatgpt_auth=True)
+
+ return CodexRoutingDecision(headers=resolved, is_chatgpt_auth=False)
+
+
+def resolve_codex_routing_headers(headers: Mapping[str, str]) -> tuple[dict[str, str], bool]:
+ """Resolve Codex routing headers as a legacy tuple."""
+ decision = resolve_codex_routing(headers)
+ return decision.headers, decision.is_chatgpt_auth
diff --git a/headroom/providers/model_metadata.py b/headroom/providers/model_metadata.py
new file mode 100644
index 000000000..f80ab0e7a
--- /dev/null
+++ b/headroom/providers/model_metadata.py
@@ -0,0 +1,60 @@
+"""Provider model metadata route helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from headroom.providers.codex.model_metadata import handle_chatgpt_model_metadata
+
+
+@dataclass(frozen=True, slots=True)
+class ModelMetadataEndpoint:
+ """OpenAI-compatible model metadata endpoint shape."""
+
+ route_path: str
+ upstream_path: str
+ passthrough_sub_path: str = "models"
+
+
+MODEL_METADATA_LIST_ENDPOINT = ModelMetadataEndpoint("/v1/models", "/backend-api/models")
+
+
+def model_metadata_get_endpoint(model_id: str) -> ModelMetadataEndpoint:
+ """Return the single-model metadata endpoint for ``model_id``."""
+ return ModelMetadataEndpoint(
+ "/v1/models/{model_id}",
+ f"/backend-api/models/{model_id}",
+ )
+
+
+async def handle_model_metadata_endpoint(
+ proxy: Any,
+ request: Request,
+ *,
+ endpoint: ModelMetadataEndpoint,
+ provider_api_base_url: str,
+ provider_name: str,
+) -> Response:
+ """Handle OpenAI-compatible model metadata with Codex ChatGPT-auth support."""
+ assert proxy.http_client is not None
+ chatgpt_response = await handle_chatgpt_model_metadata(
+ proxy.http_client,
+ request,
+ endpoint.upstream_path,
+ )
+ if chatgpt_response is not None:
+ return chatgpt_response
+
+ return cast(
+ Response,
+ await proxy.handle_passthrough(
+ request,
+ provider_api_base_url,
+ endpoint.passthrough_sub_path,
+ provider_name,
+ ),
+ )
diff --git a/headroom/providers/openai_images.py b/headroom/providers/openai_images.py
new file mode 100644
index 000000000..ed42fd5ff
--- /dev/null
+++ b/headroom/providers/openai_images.py
@@ -0,0 +1,62 @@
+"""OpenAI image endpoint routing helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from headroom.providers.codex.images import handle_chatgpt_codex_images
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIImageEndpoint:
+ """An OpenAI image endpoint with a possible Codex ChatGPT-auth override."""
+
+ route_path: str
+ sub_path: str
+
+
+OPENAI_IMAGE_ENDPOINTS: tuple[OpenAIImageEndpoint, ...] = (
+ OpenAIImageEndpoint("/v1/images/generations", "images/generations"),
+ OpenAIImageEndpoint("/v1/images/edits", "images/edits"),
+)
+
+
+def codex_image_subpath(openai_image_sub_path: str) -> str:
+ """Return the Codex image backend subpath for an OpenAI image endpoint."""
+ return openai_image_sub_path.removeprefix("images/")
+
+
+def select_codex_image_client(proxy: Any) -> Any:
+ """Return the HTTP client used for ChatGPT-auth image forwarding."""
+ return getattr(proxy, "http_client_h1", None) or getattr(proxy, "http_client", None)
+
+
+async def handle_openai_image_endpoint(
+ proxy: Any,
+ request: Request,
+ *,
+ openai_api_base_url: str,
+ endpoint: OpenAIImageEndpoint,
+) -> Response:
+ """Handle an OpenAI image endpoint, including Codex ChatGPT-auth routing."""
+ chatgpt_response = await handle_chatgpt_codex_images(
+ select_codex_image_client(proxy),
+ request,
+ codex_image_subpath(endpoint.sub_path),
+ )
+ if chatgpt_response is not None:
+ return chatgpt_response
+
+ return cast(
+ Response,
+ await proxy.handle_passthrough(
+ request,
+ openai_api_base_url,
+ endpoint.sub_path,
+ "openai",
+ ),
+ )
diff --git a/headroom/providers/openai_responses.py b/headroom/providers/openai_responses.py
new file mode 100644
index 000000000..e09adc42d
--- /dev/null
+++ b/headroom/providers/openai_responses.py
@@ -0,0 +1,100 @@
+"""OpenAI Responses API passthrough helpers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import Response
+from starlette.requests import ClientDisconnect
+
+logger = logging.getLogger("headroom.providers.openai.responses")
+
+
+def _sanitize_for_log(value: str) -> str:
+ """Return a log-safe single-line representation of untrusted text."""
+ return value.replace("\r", "").replace("\n", "")
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIResponsesSubpathRoute:
+ """Responses API subpath alias exposed by provider route registration."""
+
+ path: str
+ methods: tuple[str, ...]
+
+
+OPENAI_RESPONSES_ROOT_PATHS: tuple[str, ...] = (
+ "/v1/responses",
+ "/v1/codex/responses",
+ "/backend-api/responses",
+ "/backend-api/codex/responses",
+)
+
+OPENAI_RESPONSES_WEBSOCKET_PATHS: tuple[str, ...] = OPENAI_RESPONSES_ROOT_PATHS
+
+OPENAI_RESPONSES_SUBPATH_ROUTES: tuple[OpenAIResponsesSubpathRoute, ...] = (
+ OpenAIResponsesSubpathRoute("/v1/responses/{sub_path:path}", ("GET", "POST", "DELETE")),
+ OpenAIResponsesSubpathRoute("/v1/codex/responses/{sub_path:path}", ("GET", "POST", "DELETE")),
+ OpenAIResponsesSubpathRoute(
+ "/backend-api/responses/{sub_path:path}",
+ ("GET", "POST", "DELETE"),
+ ),
+ OpenAIResponsesSubpathRoute(
+ "/backend-api/codex/responses/{sub_path:path}",
+ ("GET", "POST", "DELETE"),
+ ),
+)
+
+
+def openai_responses_subpath_url(api_base_url: str, sub_path: str, query: str = "") -> str:
+ """Build an OpenAI Responses API subpath URL."""
+ url = f"{api_base_url.rstrip('/')}/v1/responses/{sub_path}"
+ if query:
+ url = f"{url}?{query}"
+ return url
+
+
+def normalize_openai_responses_headers(headers: Mapping[str, str]) -> dict[str, str]:
+ """Return request headers suitable for upstream OpenAI forwarding."""
+ upstream_headers = dict(headers)
+ upstream_headers.pop("host", None)
+ return upstream_headers
+
+
+async def handle_openai_responses_subpath(
+ http_client: Any,
+ request: Request,
+ api_base_url: str,
+ sub_path: str,
+) -> Response:
+ """Forward a Responses API subpath request to the configured OpenAI upstream."""
+ url = openai_responses_subpath_url(api_base_url, sub_path, request.url.query)
+ try:
+ body = await request.body()
+ except ClientDisconnect:
+ logger.debug("Client disconnected during body read for codex responses passthrough")
+ return Response(status_code=204)
+ try:
+ resp = await http_client.request(
+ request.method,
+ url,
+ headers=normalize_openai_responses_headers(dict(request.headers.items())),
+ content=body,
+ timeout=120.0,
+ )
+ return Response(
+ content=resp.content,
+ status_code=resp.status_code,
+ headers=dict(resp.headers),
+ )
+ except Exception as exc:
+ logger.error(
+ "Passthrough /v1/responses/%s failed: %s",
+ _sanitize_for_log(sub_path),
+ exc,
+ )
+ return Response(content="Upstream request failed.", status_code=502)
diff --git a/headroom/providers/proxy_routes.py b/headroom/providers/proxy_routes.py
index ddd3795ea..04a56613c 100644
--- a/headroom/providers/proxy_routes.py
+++ b/headroom/providers/proxy_routes.py
@@ -3,501 +3,205 @@
from __future__ import annotations
-import json
import logging
-from typing import Any, cast
-from urllib.parse import quote
+from typing import Any
from fastapi import FastAPI, Request, WebSocket
-from fastapi.responses import Response
-from headroom.proxy.handlers.openai import (
- _custom_base_passthrough_telemetry,
- _resolve_codex_routing_headers,
- _sanitize_forwarded_response_headers,
+from headroom.providers.cloudcode import normalize_cloudcode_passthrough_path
+from headroom.providers.codex.responses import handle_chatgpt_codex_responses_subpath
+from headroom.providers.model_metadata import (
+ MODEL_METADATA_LIST_ENDPOINT,
+ handle_model_metadata_endpoint,
+ model_metadata_get_endpoint,
)
-
-logger = logging.getLogger("headroom.proxy.routes")
-
-
-def _api_target(proxy: Any, provider_name: str) -> str:
- legacy_attrs = {
- "anthropic": "ANTHROPIC_API_URL",
- "openai": "OPENAI_API_URL",
- "gemini": "GEMINI_API_URL",
- "cloudcode": "CLOUDCODE_API_URL",
- "vertex": "VERTEX_API_URL",
- }
- legacy_attr = legacy_attrs[provider_name]
- return cast(str, getattr(proxy, legacy_attr, proxy.provider_runtime.api_target(provider_name)))
-
-
-def _vertex_target_for_location(proxy: Any, location: str) -> str:
- """Resolve the Vertex upstream host for a request, region-aware.
-
- The Vertex regional host must match the ``locations/{location}`` in the
- request path (e.g. a ``europe-west1`` request cannot go to a
- ``us-central1`` host). The configured target is a single fixed-region host
- (default ``us-central1``), so unless the operator pinned an explicit
- non-default upstream (e.g. a private gateway), derive the host from the
- request's own location. ``global`` maps to the unprefixed host.
- """
- from headroom.providers.registry import DEFAULT_VERTEX_API_URL
-
- configured = _api_target(proxy, "vertex")
- if configured and configured != DEFAULT_VERTEX_API_URL:
- # Operator pinned an explicit upstream (gateway / specific host) — honor it.
- return configured
- if not location or location == "global":
- return "https://aiplatform.googleapis.com"
- return f"https://{location}-aiplatform.googleapis.com"
-
-
-def _select_passthrough_base_url(proxy: Any, headers: dict[str, str]) -> str:
- # Codex CLI subscription mode hits a wide surface under
- # `/backend-api/*` (rate-limit polling, agent identity, JWT
- # refresh, cloud tasks). Without this branch the catchall
- # routes those to api.openai.com which 404s, and Codex
- # interprets the failure as "session invalid" and refuses
- # to use subscription auth at all. The check is a no-op
- # for non-ChatGPT-authed requests.
- _, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
- if is_chatgpt_auth:
- return "https://chatgpt.com"
- if headers.get("x-goog-api-key"):
- return _api_target(proxy, "gemini")
- if headers.get("api-key"):
- azure_base = headers.get("x-headroom-base-url", "")
- if azure_base:
- return azure_base.rstrip("/")
- provider_name = proxy.provider_runtime.model_metadata_provider(headers)
- return _api_target(proxy, provider_name)
-
-
-# Codex ChatGPT-subscription auth doesn't have access to
-# `chatgpt.com/backend-api/models` — that endpoint returns 403 to OAuth
-# bearer tokens (issue #478). Codex polls `/v1/models` every few seconds
-# to populate its model-picker UI, so the 403 storm is noisy and breaks
-# refresh. The fix: when Codex hits `/v1/models` under ChatGPT auth,
-# fetch the Codex-specific registry first and synthesize an
-# OpenAI-compatible response from its slugs. If that registry is
-# unavailable, fall back to the known-supported static set.
-#
-# The list mirrors what Codex itself ships in its built-in model
-# registry (the same models its provider config exposes); it's the
-# safe-by-construction set since these are what `/v1/responses` actually
-# accepts under ChatGPT auth.
-_CHATGPT_AUTH_CODEX_MODELS: tuple[str, ...] = (
- "gpt-5.5",
- "gpt-5.4",
- "gpt-5.3",
- "gpt-5.2",
- "gpt-5.1",
- "gpt-5",
+from headroom.providers.openai_images import (
+ OPENAI_IMAGE_ENDPOINTS,
+ OpenAIImageEndpoint,
+ handle_openai_image_endpoint,
+)
+from headroom.providers.openai_responses import (
+ OPENAI_RESPONSES_ROOT_PATHS,
+ OPENAI_RESPONSES_SUBPATH_ROUTES,
+ OPENAI_RESPONSES_WEBSOCKET_PATHS,
+ OpenAIResponsesSubpathRoute,
+ handle_openai_responses_subpath,
+)
+from headroom.providers.proxy_targets import (
+ api_target as _api_target,
)
+from headroom.providers.proxy_targets import (
+ select_passthrough_base_url as _select_passthrough_base_url,
+)
+from headroom.providers.proxy_targets import (
+ vertex_target_for_location as _vertex_target_for_location,
+)
+from headroom.providers.route_specs import (
+ PROVIDER_HANDLER_ROUTES,
+ PROVIDER_PASSTHROUGH_ROUTES,
+ ProviderHandlerRoute,
+ ProviderPassthroughRoute,
+)
+from headroom.providers.vertex import (
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
+ VERTEX_COUNT_TOKENS,
+ VERTEX_GENERATE_CONTENT,
+ VERTEX_GOOGLE_PROVIDER_NAME,
+ VERTEX_RAW_PREDICT,
+ VERTEX_STREAM_GENERATE_CONTENT,
+ VERTEX_STREAM_RAW_PREDICT,
+ is_vertex_anthropic_publisher,
+ is_vertex_google_publisher,
+ vertex_anthropic_target,
+ vertex_publisher_provider_name,
+)
+from headroom.proxy.passthrough import (
+ custom_base_passthrough_telemetry as _custom_base_passthrough_telemetry,
+)
+from headroom.proxy.request_scope import normalize_request_path
+logger = logging.getLogger("headroom.proxy.routes")
-def _codex_client_version(requested_client_version: str | None = None) -> str:
- """Return the Codex client version to use for model-registry requests."""
- if requested_client_version:
- return requested_client_version
- return "0.130.0"
+def _register_provider_passthrough_route(
+ app: FastAPI,
+ proxy: Any,
+ spec: ProviderPassthroughRoute,
+) -> None:
+ async def provider_passthrough(request: Request):
+ return await proxy.handle_passthrough(
+ request,
+ _api_target(proxy, spec.provider_name),
+ spec.sub_path,
+ spec.provider_name,
+ )
-_CODEX_REASONING_LEVELS: tuple[dict[str, str], ...] = (
- {"effort": "low", "description": "Fast responses with lighter reasoning"},
- {
- "effort": "medium",
- "description": "Balances speed and reasoning depth for everyday tasks",
- },
- {"effort": "high", "description": "Greater reasoning depth for complex problems"},
- {"effort": "xhigh", "description": "Extra high reasoning depth for complex problems"},
-)
+ provider_passthrough.__name__ = (
+ f"{spec.provider_name}_{spec.sub_path.replace('/', '_')}_{spec.method.lower()}_passthrough"
+ )
+ app.api_route(spec.path, methods=[spec.method])(provider_passthrough)
-def _display_name_from_model_id(model_id: str) -> str:
- return "-".join(
- part.upper() if part == "gpt" else part.capitalize() for part in model_id.split("-")
- )
+def _register_provider_passthrough_routes(app: FastAPI, proxy: Any) -> None:
+ for spec in PROVIDER_PASSTHROUGH_ROUTES:
+ _register_provider_passthrough_route(app, proxy, spec)
-def _codex_model_registry_entry(
- model_id: str,
- upstream_entry: dict[str, Any] | None = None,
-) -> dict[str, Any]:
- """Return Codex app-server model metadata with required registry fields."""
- entry = dict(upstream_entry or {})
- entry["slug"] = model_id
- entry.setdefault("display_name", _display_name_from_model_id(model_id))
- entry.setdefault("description", "Codex model available through ChatGPT subscription auth.")
- entry.setdefault("default_reasoning_level", "medium")
- entry.setdefault("supported_reasoning_levels", list(_CODEX_REASONING_LEVELS))
- entry.setdefault("shell_type", "shell_command")
- entry.setdefault("visibility", "list")
- entry.setdefault("supported_in_api", True)
- entry.setdefault("priority", 50)
- entry.setdefault("additional_speed_tiers", ["fast"])
- entry.setdefault(
- "service_tiers",
- [{"id": "priority", "name": "Fast", "description": "1.5x speed, increased usage"}],
+def _register_provider_handler_route(app: FastAPI, proxy: Any, spec: ProviderHandlerRoute) -> None:
+ async def provider_handler(
+ request: Request,
+ batch_id: str = "",
+ batch_name: str = "",
+ model: str = "",
+ ):
+ handler = getattr(proxy, spec.handler_name)
+ if spec.path_param is None:
+ return await handler(request)
+ path_args = {
+ "batch_id": batch_id,
+ "batch_name": batch_name,
+ "model": model,
+ }
+ return await handler(request, path_args[spec.path_param])
+
+ provider_handler.__name__ = (
+ spec.handler_name.replace("handle_", "")
+ + "_"
+ + spec.method.lower()
+ + "_"
+ + spec.path.strip("/").replace("/", "_").replace("-", "_")
)
- entry.setdefault("availability_nux", None)
- entry.setdefault("upgrade", None)
- entry.setdefault("context_window", 272000)
- entry.setdefault("max_context_window", 272000)
- entry.setdefault("effective_context_window_percent", 95)
- entry.setdefault("experimental_supported_tools", [])
- entry.setdefault("input_modalities", ["text", "image"])
- entry.setdefault("supports_search_tool", True)
- entry.setdefault("use_responses_lite", False)
- entry.setdefault("support_verbosity", True)
- entry.setdefault("default_verbosity", "low")
- entry.setdefault("apply_patch_tool_type", "freeform")
- entry.setdefault("web_search_tool_type", "text_and_image")
- entry.setdefault("truncation_policy", {"mode": "tokens", "limit": 10000})
- entry.setdefault("supports_image_detail_original", True)
- entry.setdefault("supports_parallel_tool_calls", True)
- entry.setdefault("supports_reasoning_summaries", True)
- entry.setdefault("default_reasoning_summary", "none")
- return entry
+ app.api_route(spec.path, methods=[spec.method])(provider_handler)
-def _models_list_response_from_entries(model_entries: tuple[dict[str, Any], ...]) -> Response:
- model_ids = tuple(
- slug
- for entry in model_entries
- for slug in (entry.get("slug"),)
- if isinstance(slug, str) and slug
- )
- payload = {
- "object": "list",
- "data": [
- {
- "id": model_id,
- "object": "model",
- "created": 0,
- "owned_by": "openai",
- }
- for model_id in model_ids
- ],
- "models": list(model_entries),
- }
- return Response(
- content=json.dumps(payload),
- status_code=200,
- headers={"content-type": "application/json"},
- )
+def _register_provider_handler_routes(app: FastAPI, proxy: Any) -> None:
+ for spec in PROVIDER_HANDLER_ROUTES:
+ _register_provider_handler_route(app, proxy, spec)
-def _synthetic_models_list_response() -> Response:
- """OpenAI-compatible `/v1/models` payload for Codex ChatGPT auth."""
- return _models_list_response_from_entries(
- tuple(_codex_model_registry_entry(model_id) for model_id in _CHATGPT_AUTH_CODEX_MODELS)
- )
+def _register_openai_responses_root_route(app: FastAPI, proxy: Any, path: str) -> None:
+ async def openai_responses_root(request: Request):
+ return await proxy.handle_openai_responses(request)
+ openai_responses_root.__name__ = path.strip("/").replace("/", "_").replace("-", "_") + "_root"
+ app.post(path)(openai_responses_root)
-def _synthetic_model_get_response(model_id: str) -> Response:
- """OpenAI-compatible `/v1/models/{id}` payload."""
- if model_id not in _CHATGPT_AUTH_CODEX_MODELS:
- return Response(
- content=json.dumps(
- {
- "error": {
- "message": f"Model {model_id!r} not available under ChatGPT auth",
- "type": "invalid_request_error",
- "code": "model_not_found",
- }
- }
- ),
- status_code=404,
- headers={"content-type": "application/json"},
- )
- return Response(
- content=json.dumps(
- {
- "id": model_id,
- "object": "model",
- "created": 0,
- "owned_by": "openai",
- }
- ),
- status_code=200,
- headers={"content-type": "application/json"},
- )
+def _register_openai_responses_websocket_route(app: FastAPI, proxy: Any, path: str) -> None:
+ async def openai_responses_ws(websocket: WebSocket):
+ await proxy.handle_openai_responses_ws(websocket)
-def _normalize_codex_registry_headers(headers: dict[str, str]) -> dict[str, str]:
- """Prepare inbound ChatGPT auth headers for the Codex model registry."""
- upstream_headers = dict(headers)
- upstream_headers.pop("host", None)
- account_id = (
- upstream_headers.get("chatgpt-account-id")
- or upstream_headers.get("ChatGPT-Account-ID")
- or ""
- )
- if account_id:
- upstream_headers["chatgpt-account-id"] = account_id
- upstream_headers.pop("ChatGPT-Account-ID", None)
- upstream_headers["accept"] = "application/json"
- upstream_headers.pop("Accept", None)
- return upstream_headers
+ openai_responses_ws.__name__ = path.strip("/").replace("/", "_").replace("-", "_") + "_ws"
+ app.websocket(path)(openai_responses_ws)
-async def _fetch_chatgpt_codex_model_entries(
+def _register_openai_responses_subpath_route(
+ app: FastAPI,
proxy: Any,
- headers: dict[str, str],
- requested_client_version: str | None,
-) -> tuple[dict[str, Any], ...] | None:
- """Fetch Codex model metadata from ChatGPT, returning None when fallback should apply."""
- client_version = _codex_client_version(requested_client_version)
- upstream_headers = _normalize_codex_registry_headers(headers)
- url = (
- "https://chatgpt.com/backend-api/codex/models"
- f"?client_version={quote(client_version, safe='')}"
- )
- try:
+ spec: OpenAIResponsesSubpathRoute,
+) -> None:
+ async def openai_responses_subpath(request: Request, sub_path: str):
assert proxy.http_client is not None
- resp = await proxy.http_client.get(
- url,
- headers=upstream_headers,
- timeout=15.0,
+ chatgpt_response = await handle_chatgpt_codex_responses_subpath(
+ proxy.http_client,
+ request,
+ sub_path,
)
- if resp.status_code >= 400:
- logger.warning(
- "Codex model registry fetch failed: HTTP %s: %s",
- resp.status_code,
- resp.text[:300],
- )
- return None
-
- data = resp.json()
- models_raw = data.get("models") if isinstance(data, dict) else None
- if not isinstance(models_raw, list):
- logger.warning("Codex model registry response did not contain models[]")
- return None
+ if chatgpt_response is not None:
+ return chatgpt_response
- model_entries = tuple(
- _codex_model_registry_entry(slug, entry)
- for entry in models_raw
- if isinstance(entry, dict)
- for slug in (entry.get("slug"),)
- if isinstance(slug, str) and slug
+ return await handle_openai_responses_subpath(
+ proxy.http_client,
+ request,
+ _api_target(proxy, "openai"),
+ sub_path,
)
- if not model_entries:
- logger.warning("Codex model registry returned no model slugs")
- return None
- model_ids = [entry["slug"] for entry in model_entries]
- logger.info("Fetched %d Codex models from upstream model registry", len(model_entries))
- logger.debug("Fetched Codex model IDs from upstream model registry: %s", model_ids)
- return model_entries
- except Exception:
- logger.exception("Codex model registry fetch failed")
- return None
-
-
-async def _fetch_chatgpt_codex_models_response(
- proxy: Any,
- headers: dict[str, str],
- requested_client_version: str | None,
-) -> Response | None:
- """Build a dynamic `/v1/models` response from the Codex registry when available."""
- model_entries = await _fetch_chatgpt_codex_model_entries(
- proxy, headers, requested_client_version
+ openai_responses_subpath.__name__ = (
+ spec.path.strip("/")
+ .replace("/", "_")
+ .replace("-", "_")
+ .replace("{sub_path:path}", "subpath")
)
- if model_entries is None:
- return None
- return _models_list_response_from_entries(model_entries)
+ app.api_route(spec.path, methods=list(spec.methods))(openai_responses_subpath)
-async def _fetch_chatgpt_codex_model_get_response(
- proxy: Any,
- headers: dict[str, str],
- model_id: str,
- requested_client_version: str | None,
-) -> Response | None:
- """Build a dynamic `/v1/models/{id}` response from the Codex registry when available."""
- model_entries = await _fetch_chatgpt_codex_model_entries(
- proxy, headers, requested_client_version
- )
- if model_entries is None:
- return None
- model_ids = tuple(
- slug
- for entry in model_entries
- for slug in (entry.get("slug"),)
- if isinstance(slug, str) and slug
- )
- if model_id in model_ids:
- return Response(
- content=json.dumps(
- {
- "id": model_id,
- "object": "model",
- "created": 0,
- "owned_by": "openai",
- }
- ),
- status_code=200,
- headers={"content-type": "application/json"},
- )
- return Response(
- content=json.dumps(
- {
- "error": {
- "message": f"Model {model_id!r} not available under ChatGPT auth",
- "type": "invalid_request_error",
- "code": "model_not_found",
- }
- }
- ),
- status_code=404,
- headers={"content-type": "application/json"},
- )
-
+def _register_openai_responses_routes(app: FastAPI, proxy: Any) -> None:
+ for path in OPENAI_RESPONSES_ROOT_PATHS:
+ _register_openai_responses_root_route(app, proxy, path)
+ for path in OPENAI_RESPONSES_WEBSOCKET_PATHS:
+ _register_openai_responses_websocket_route(app, proxy, path)
+ for spec in OPENAI_RESPONSES_SUBPATH_ROUTES:
+ _register_openai_responses_subpath_route(app, proxy, spec)
-async def _handle_chatgpt_model_metadata(
- proxy: Any,
- request: Request,
- upstream_path: str,
-) -> Response | None:
- headers = dict(request.headers.items())
- headers.pop("host", None)
- headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
- if not is_chatgpt_auth:
- return None
- # Avoid generic `/backend-api/models[/{id}]`, which returns 403 for
- # OAuth tokens, but prefer the Codex-specific registry when available.
- requested_client_version = request.query_params.get("client_version")
- if upstream_path == "/backend-api/models":
- upstream_response = await _fetch_chatgpt_codex_models_response(
+def _register_openai_image_route(app: FastAPI, proxy: Any, endpoint: OpenAIImageEndpoint) -> None:
+ async def openai_image_endpoint(request: Request):
+ return await handle_openai_image_endpoint(
proxy,
- headers,
- requested_client_version,
- )
- if upstream_response is not None:
- return upstream_response
- return _synthetic_models_list_response()
- if upstream_path.startswith("/backend-api/models/"):
- model_id = upstream_path[len("/backend-api/models/") :]
- upstream_response = await _fetch_chatgpt_codex_model_get_response(
- proxy,
- headers,
- model_id,
- requested_client_version,
- )
- if upstream_response is not None:
- return upstream_response
- return _synthetic_model_get_response(model_id)
-
- url = f"https://chatgpt.com{upstream_path}"
- if request.url.query:
- url = f"{url}?{request.url.query}"
-
- from starlette.requests import ClientDisconnect
-
- try:
- body = await request.body()
- except ClientDisconnect:
- logger.debug("Client disconnected during body read for passthrough")
- return Response(status_code=204)
- try:
- assert proxy.http_client is not None
- resp = await proxy.http_client.request(
- request.method,
- url,
- headers=headers,
- content=body,
- timeout=120.0,
- )
- return Response(
- content=resp.content,
- status_code=resp.status_code,
- headers=dict(resp.headers),
+ request,
+ openai_api_base_url=_api_target(proxy, "openai"),
+ endpoint=endpoint,
)
- except Exception as exc:
- logger.error("Passthrough %s failed: %s", upstream_path, exc)
- return Response(content=str(exc), status_code=502)
+ openai_image_endpoint.__name__ = endpoint.sub_path.replace("/", "_") + "_post"
+ app.post(endpoint.route_path)(openai_image_endpoint)
-async def _handle_chatgpt_codex_images(
- proxy: Any,
- request: Request,
- sub_path: str,
-) -> Response | None:
- """Forward Codex OAuth image requests to ChatGPT's Codex image backend."""
- from headroom.proxy.helpers import _strip_internal_headers
-
- headers = dict(request.headers.items())
- headers.pop("host", None)
- headers.pop("accept-encoding", None)
- headers = _strip_internal_headers(headers)
- headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
- if not is_chatgpt_auth:
- return None
- url = f"https://chatgpt.com/backend-api/codex/images/{sub_path}"
- if request.url.query:
- url = f"{url}?{request.url.query}"
-
- from starlette.requests import ClientDisconnect
-
- try:
- body = await request.body()
- except ClientDisconnect:
- logger.debug("Client disconnected during body read for passthrough")
- return Response(status_code=204)
- try:
- client = getattr(proxy, "http_client_h1", None) or getattr(proxy, "http_client", None)
- if client is None:
- raise RuntimeError("No HTTP client configured for Codex image forwarding")
- # OAuth image traffic intentionally skips request-outcome telemetry; no token usage is available here.
- resp = await client.request(
- request.method,
- url,
- headers=headers,
- content=body,
- timeout=120.0,
- )
- response_headers = _sanitize_forwarded_response_headers(resp.headers)
- return Response(
- content=resp.content,
- status_code=resp.status_code,
- headers=response_headers,
- )
- except Exception as exc:
- logger.error("Passthrough /v1/images/%s failed: %s", sub_path, exc)
- return Response(
- content=json.dumps(
- {
- "error": {
- "type": "upstream_error",
- "message": "Failed to forward Codex image request",
- }
- }
- ),
- status_code=502,
- media_type="application/json",
- )
+def _register_openai_image_routes(app: FastAPI, proxy: Any) -> None:
+ for endpoint in OPENAI_IMAGE_ENDPOINTS:
+ _register_openai_image_route(app, proxy, endpoint)
def register_provider_routes(app: FastAPI, proxy: Any) -> None:
"""Register provider-specific proxy endpoints."""
- def normalize_request_path(request: Request, path: str) -> None:
- request.scope["path"] = path
- if "raw_path" in request.scope:
- request.scope["raw_path"] = quote(path).encode("ascii")
- if hasattr(request, "_url"):
- delattr(request, "_url")
-
async def vertex_publisher_passthrough(request: Request, publisher: str, action: str):
return await proxy.handle_passthrough(
request,
_api_target(proxy, "vertex"),
action,
- f"vertex:{publisher}",
+ vertex_publisher_provider_name(publisher),
)
@app.post("/v1/messages")
@@ -535,159 +239,9 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
async def bedrock_invoke_stream(request: Request, model_id: str):
return await proxy.handle_bedrock_invoke(request, model_id, stream=True)
- @app.post("/v1/messages/count_tokens")
- async def anthropic_count_tokens(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "anthropic"),
- "count_tokens",
- "anthropic",
- )
-
- @app.post("/v1/messages/batches")
- async def anthropic_batch_create(request: Request):
- return await proxy.handle_anthropic_batch_create(request)
-
- @app.get("/v1/messages/batches")
- async def anthropic_batch_list(request: Request):
- return await proxy.handle_anthropic_batch_passthrough(request)
-
- @app.get("/v1/messages/batches/{batch_id}")
- async def anthropic_batch_get(request: Request, batch_id: str):
- return await proxy.handle_anthropic_batch_passthrough(request, batch_id)
-
- @app.get("/v1/messages/batches/{batch_id}/results")
- async def anthropic_batch_results(request: Request, batch_id: str):
- return await proxy.handle_anthropic_batch_results(request, batch_id)
-
- @app.post("/v1/messages/batches/{batch_id}/cancel")
- async def anthropic_batch_cancel(request: Request, batch_id: str):
- return await proxy.handle_anthropic_batch_passthrough(request, batch_id)
-
- @app.post("/v1/chat/completions")
- async def openai_chat(request: Request):
- return await proxy.handle_openai_chat(request)
-
- @app.post("/v1/responses")
- async def openai_responses(request: Request):
- return await proxy.handle_openai_responses(request)
-
- @app.post("/v1/codex/responses")
- async def openai_v1_codex_responses(request: Request):
- return await proxy.handle_openai_responses(request)
-
- @app.post("/backend-api/responses")
- async def openai_codex_responses(request: Request):
- return await proxy.handle_openai_responses(request)
-
- @app.post("/backend-api/codex/responses")
- async def openai_codex_nested_responses(request: Request):
- return await proxy.handle_openai_responses(request)
-
- @app.websocket("/v1/responses")
- async def openai_responses_ws(websocket: WebSocket):
- await proxy.handle_openai_responses_ws(websocket)
-
- @app.websocket("/v1/codex/responses")
- async def openai_v1_codex_responses_ws(websocket: WebSocket):
- await proxy.handle_openai_responses_ws(websocket)
-
- @app.api_route("/v1/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])
- async def openai_responses_sub(request: Request, sub_path: str):
- headers = dict(request.headers.items())
- headers.pop("host", None)
- headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)
-
- if is_chatgpt_auth:
- url = f"https://chatgpt.com/backend-api/codex/responses/{sub_path}"
- else:
- url = f"{_api_target(proxy, 'openai')}/v1/responses/{sub_path}"
-
- if request.url.query:
- url = f"{url}?{request.url.query}"
-
- from starlette.requests import ClientDisconnect
-
- try:
- body = await request.body()
- except ClientDisconnect:
- logger.debug("Client disconnected during body read for codex responses passthrough")
- return Response(status_code=204)
- try:
- assert proxy.http_client is not None
- resp = await proxy.http_client.request(
- request.method,
- url,
- headers=headers,
- content=body,
- timeout=120.0,
- )
- return Response(
- content=resp.content,
- status_code=resp.status_code,
- headers=dict(resp.headers),
- )
- except Exception as exc:
- logger.error("Passthrough /v1/responses/%s failed: %s", sub_path, exc)
- return Response(content=str(exc), status_code=502)
-
- @app.api_route("/v1/codex/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])
- async def openai_v1_codex_responses_sub(request: Request, sub_path: str):
- return await openai_responses_sub(request, sub_path)
-
- @app.websocket("/backend-api/responses")
- async def openai_codex_responses_ws(websocket: WebSocket):
- await proxy.handle_openai_responses_ws(websocket)
-
- @app.websocket("/backend-api/codex/responses")
- async def openai_codex_nested_responses_ws(websocket: WebSocket):
- await proxy.handle_openai_responses_ws(websocket)
-
- @app.api_route("/backend-api/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"])
- async def openai_codex_responses_sub(request: Request, sub_path: str):
- return await openai_responses_sub(request, sub_path)
-
- @app.api_route(
- "/backend-api/codex/responses/{sub_path:path}", methods=["GET", "POST", "DELETE"]
- )
- async def openai_codex_nested_responses_sub(request: Request, sub_path: str):
- return await openai_responses_sub(request, sub_path)
+ _register_openai_responses_routes(app, proxy)
- @app.post("/v1/batches")
- async def create_batch(request: Request):
- return await proxy.handle_batch_create(request)
-
- @app.get("/v1/batches")
- async def list_batches(request: Request):
- return await proxy.handle_batch_list(request)
-
- @app.get("/v1/batches/{batch_id}")
- async def get_batch(request: Request, batch_id: str):
- return await proxy.handle_batch_get(request, batch_id)
-
- @app.post("/v1/batches/{batch_id}/cancel")
- async def cancel_batch(request: Request, batch_id: str):
- return await proxy.handle_batch_cancel(request, batch_id)
-
- @app.post("/v1beta/models/{model}:generateContent")
- async def gemini_generate_content(request: Request, model: str):
- return await proxy.handle_gemini_generate_content(request, model)
-
- @app.post("/v1beta/models/{model}:streamGenerateContent")
- async def gemini_stream_generate_content(request: Request, model: str):
- return await proxy.handle_gemini_stream_generate_content(request, model)
-
- @app.post("/v1beta/models/{model}:countTokens")
- async def gemini_count_tokens(request: Request, model: str):
- return await proxy.handle_gemini_count_tokens(request, model)
-
- @app.post("/v1internal:streamGenerateContent")
- async def google_cloudcode_stream_generate_content(request: Request):
- return await proxy.handle_google_cloudcode_stream(request)
-
- @app.post("/v1/v1internal:streamGenerateContent")
- async def google_cloudcode_stream_generate_content_v1(request: Request):
- return await proxy.handle_google_cloudcode_stream(request)
+ _register_provider_handler_routes(app, proxy)
@app.post(
"/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:generateContent"
@@ -701,14 +255,14 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
model: str,
):
del api_version, project, location
- if publisher == "google":
+ if is_vertex_google_publisher(publisher):
return await proxy.handle_gemini_generate_content(
request,
model,
_api_target(proxy, "vertex"),
- "vertex:google",
+ VERTEX_GOOGLE_PROVIDER_NAME,
)
- return await vertex_publisher_passthrough(request, publisher, "generateContent")
+ return await vertex_publisher_passthrough(request, publisher, VERTEX_GENERATE_CONTENT.name)
@app.post(
"/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:streamGenerateContent"
@@ -722,14 +276,18 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
model: str,
):
del api_version, project, location
- if publisher == "google":
+ if is_vertex_google_publisher(publisher):
return await proxy.handle_gemini_generate_content(
request,
model,
_api_target(proxy, "vertex"),
- "vertex:google",
+ VERTEX_GOOGLE_PROVIDER_NAME,
)
- return await vertex_publisher_passthrough(request, publisher, "streamGenerateContent")
+ return await vertex_publisher_passthrough(
+ request,
+ publisher,
+ VERTEX_STREAM_GENERATE_CONTENT.name,
+ )
@app.post(
"/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:countTokens"
@@ -743,14 +301,14 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
model: str,
):
del api_version, project, location
- if publisher == "google":
+ if is_vertex_google_publisher(publisher):
return await proxy.handle_gemini_count_tokens(
request,
model,
_api_target(proxy, "vertex"),
- "vertex:google",
+ VERTEX_GOOGLE_PROVIDER_NAME,
)
- return await vertex_publisher_passthrough(request, publisher, "countTokens")
+ return await vertex_publisher_passthrough(request, publisher, VERTEX_COUNT_TOKENS.name)
@app.post(
"/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:rawPredict"
@@ -764,14 +322,14 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
model: str,
):
del api_version, project
- if publisher == "anthropic":
+ if is_vertex_anthropic_publisher(publisher):
return await proxy.handle_anthropic_messages(
request,
_vertex_target_for_location(proxy, location),
- "vertex:anthropic",
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
model,
)
- return await vertex_publisher_passthrough(request, publisher, "rawPredict")
+ return await vertex_publisher_passthrough(request, publisher, VERTEX_RAW_PREDICT.name)
@app.post(
"/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:rawPredict"
@@ -783,16 +341,19 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
publisher: str,
model: str,
):
- if publisher == "anthropic":
+ if is_vertex_anthropic_publisher(publisher):
del project
- target = _vertex_target_for_location(proxy, location).rstrip("/") + "/v1"
+ target = vertex_anthropic_target(
+ _vertex_target_for_location(proxy, location),
+ versionless_route=True,
+ )
return await proxy.handle_anthropic_messages(
request,
target,
- "vertex:anthropic",
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
model,
)
- return await vertex_publisher_passthrough(request, publisher, "rawPredict")
+ return await vertex_publisher_passthrough(request, publisher, VERTEX_RAW_PREDICT.name)
@app.post(
"/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:streamRawPredict"
@@ -806,15 +367,19 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
model: str,
):
del api_version, project
- if publisher == "anthropic":
+ if is_vertex_anthropic_publisher(publisher):
return await proxy.handle_anthropic_messages(
request,
_vertex_target_for_location(proxy, location),
- "vertex:anthropic",
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
model,
- True,
+ VERTEX_STREAM_RAW_PREDICT.force_stream,
)
- return await vertex_publisher_passthrough(request, publisher, "streamRawPredict")
+ return await vertex_publisher_passthrough(
+ request,
+ publisher,
+ VERTEX_STREAM_RAW_PREDICT.name,
+ )
@app.post(
"/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:streamRawPredict"
@@ -826,211 +391,50 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
publisher: str,
model: str,
):
- if publisher == "anthropic":
+ if is_vertex_anthropic_publisher(publisher):
del project
- target = _vertex_target_for_location(proxy, location).rstrip("/") + "/v1"
+ target = vertex_anthropic_target(
+ _vertex_target_for_location(proxy, location),
+ versionless_route=True,
+ )
return await proxy.handle_anthropic_messages(
request,
target,
- "vertex:anthropic",
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
model,
- True,
+ VERTEX_STREAM_RAW_PREDICT.force_stream,
)
- return await vertex_publisher_passthrough(request, publisher, "streamRawPredict")
-
- @app.get("/v1/models")
- async def list_models(request: Request):
- chatgpt_response = await _handle_chatgpt_model_metadata(
- proxy,
+ return await vertex_publisher_passthrough(
request,
- "/backend-api/models",
+ publisher,
+ VERTEX_STREAM_RAW_PREDICT.name,
)
- if chatgpt_response is not None:
- return chatgpt_response
+ @app.get("/v1/models")
+ async def list_models(request: Request):
provider_name = proxy.provider_runtime.model_metadata_provider(dict(request.headers))
- return await proxy.handle_passthrough(
+ return await handle_model_metadata_endpoint(
+ proxy,
request,
- _api_target(proxy, provider_name),
- "models",
- provider_name,
+ endpoint=MODEL_METADATA_LIST_ENDPOINT,
+ provider_api_base_url=_api_target(proxy, provider_name),
+ provider_name=provider_name,
)
@app.get("/v1/models/{model_id}")
async def get_model(request: Request, model_id: str):
- chatgpt_response = await _handle_chatgpt_model_metadata(
- proxy,
- request,
- f"/backend-api/models/{model_id}",
- )
- if chatgpt_response is not None:
- return chatgpt_response
-
provider_name = proxy.provider_runtime.model_metadata_provider(dict(request.headers))
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, provider_name),
- "models",
- provider_name,
- )
-
- @app.post("/v1/embeddings")
- async def openai_embeddings(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "embeddings",
- "openai",
- )
-
- @app.post("/v1/moderations")
- async def openai_moderations(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "moderations",
- "openai",
- )
-
- @app.post("/v1/images/generations")
- async def openai_images_generations(request: Request):
- chatgpt_response = await _handle_chatgpt_codex_images(
- proxy,
- request,
- "generations",
- )
- if chatgpt_response is not None:
- return chatgpt_response
-
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "images/generations",
- "openai",
- )
-
- @app.post("/v1/images/edits")
- async def openai_images_edits(request: Request):
- chatgpt_response = await _handle_chatgpt_codex_images(
+ return await handle_model_metadata_endpoint(
proxy,
request,
- "edits",
- )
- if chatgpt_response is not None:
- return chatgpt_response
-
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "images/edits",
- "openai",
- )
-
- @app.post("/v1/audio/transcriptions")
- async def openai_audio_transcriptions(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "audio/transcriptions",
- "openai",
- )
-
- @app.post("/v1/audio/speech")
- async def openai_audio_speech(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "openai"),
- "audio/speech",
- "openai",
+ endpoint=model_metadata_get_endpoint(model_id),
+ provider_api_base_url=_api_target(proxy, provider_name),
+ provider_name=provider_name,
)
- @app.get("/v1beta/models")
- async def gemini_list_models(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "models",
- "gemini",
- )
+ _register_openai_image_routes(app, proxy)
- @app.get("/v1beta/models/{model_name}")
- async def gemini_get_model(request: Request, model_name: str):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "models",
- "gemini",
- )
-
- @app.post("/v1beta/models/{model}:embedContent")
- async def gemini_embed_content(request: Request, model: str):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "embedContent",
- "gemini",
- )
-
- @app.post("/v1beta/models/{model}:batchEmbedContents")
- async def gemini_batch_embed_contents(request: Request, model: str):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "batchEmbedContents",
- "gemini",
- )
-
- @app.post("/v1beta/models/{model}:batchGenerateContent")
- async def gemini_batch_create(request: Request, model: str):
- return await proxy.handle_google_batch_create(request, model)
-
- @app.get("/v1beta/batches/{batch_name}")
- async def gemini_batch_get(request: Request, batch_name: str):
- return await proxy.handle_google_batch_results(request, batch_name)
-
- @app.post("/v1beta/batches/{batch_name}:cancel")
- async def gemini_batch_cancel(request: Request, batch_name: str):
- return await proxy.handle_google_batch_passthrough(request, batch_name)
-
- @app.delete("/v1beta/batches/{batch_name}")
- async def gemini_batch_delete(request: Request, batch_name: str):
- return await proxy.handle_google_batch_passthrough(request, batch_name)
-
- @app.post("/v1beta/cachedContents")
- async def gemini_create_cached_content(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "cachedContents",
- "gemini",
- )
-
- @app.get("/v1beta/cachedContents")
- async def gemini_list_cached_contents(request: Request):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "cachedContents",
- "gemini",
- )
-
- @app.get("/v1beta/cachedContents/{cache_id}")
- async def gemini_get_cached_content(request: Request, cache_id: str):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "cachedContents",
- "gemini",
- )
-
- @app.delete("/v1beta/cachedContents/{cache_id}")
- async def gemini_delete_cached_content(request: Request, cache_id: str):
- return await proxy.handle_passthrough(
- request,
- _api_target(proxy, "gemini"),
- "cachedContents",
- "gemini",
- )
+ _register_provider_passthrough_routes(app, proxy)
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "HEAD"])
async def passthrough(request: Request, path: str):
@@ -1049,23 +453,9 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
provider_name,
)
- # Intercept Code Assist authentication and onboarding routes
- clean_path = path.lstrip("/")
- if clean_path.startswith(("v1internal:", "v1/v1internal:")):
- # Normalize path (remove v1/ prefix if present to avoid 404 on cloudcode-pa upstream)
- normalized_path = clean_path
- if normalized_path.startswith("v1/"):
- normalized_path = normalized_path[3:]
- normalized_path = f"/{normalized_path}"
-
- # Mutate request scope so handle_passthrough uses the normalized path
- request.scope["path"] = normalized_path
- if "raw_path" in request.scope:
- from urllib.parse import quote
-
- request.scope["raw_path"] = quote(normalized_path).encode("ascii")
- if hasattr(request, "_url"):
- delattr(request, "_url")
+ normalized_cloudcode_path = normalize_cloudcode_passthrough_path(path)
+ if normalized_cloudcode_path is not None:
+ normalize_request_path(request, normalized_cloudcode_path)
return await proxy.handle_passthrough(
request,
diff --git a/headroom/providers/proxy_targets.py b/headroom/providers/proxy_targets.py
new file mode 100644
index 000000000..11dfd596f
--- /dev/null
+++ b/headroom/providers/proxy_targets.py
@@ -0,0 +1,44 @@
+"""Provider upstream target resolution for proxy routes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from headroom.providers.codex import resolve_codex_routing
+from headroom.providers.codex.endpoints import CHATGPT_BACKEND_API_URL
+from headroom.providers.vertex import vertex_target_for_location as _vertex_target_for_location
+
+LEGACY_API_TARGET_ATTRS: dict[str, str] = {
+ "anthropic": "ANTHROPIC_API_URL",
+ "openai": "OPENAI_API_URL",
+ "gemini": "GEMINI_API_URL",
+ "cloudcode": "CLOUDCODE_API_URL",
+ "vertex": "VERTEX_API_URL",
+}
+
+
+def api_target(proxy: Any, provider_name: str) -> str:
+ """Return the proxy target for a provider, honoring legacy proxy attributes."""
+ legacy_attr = LEGACY_API_TARGET_ATTRS[provider_name]
+ return cast(str, getattr(proxy, legacy_attr, proxy.provider_runtime.api_target(provider_name)))
+
+
+def vertex_target_for_location(proxy: Any, location: str) -> str:
+ """Resolve the Vertex upstream host for a request, region-aware."""
+ return _vertex_target_for_location(api_target(proxy, "vertex"), location)
+
+
+def select_passthrough_base_url(proxy: Any, headers: Mapping[str, str]) -> str:
+ """Resolve the upstream base URL for catch-all proxy passthrough requests."""
+ routing = resolve_codex_routing(headers)
+ if routing.is_chatgpt_auth:
+ return CHATGPT_BACKEND_API_URL
+ if headers.get("x-goog-api-key"):
+ return api_target(proxy, "gemini")
+ if headers.get("api-key"):
+ azure_base = headers.get("x-headroom-base-url", "")
+ if azure_base:
+ return azure_base.rstrip("/")
+ provider_name = proxy.provider_runtime.model_metadata_provider(headers)
+ return api_target(proxy, provider_name)
diff --git a/headroom/providers/route_specs.py b/headroom/providers/route_specs.py
new file mode 100644
index 000000000..2aaabc9a4
--- /dev/null
+++ b/headroom/providers/route_specs.py
@@ -0,0 +1,196 @@
+"""Declarative route specifications for provider passthrough endpoints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderPassthroughRoute:
+ """A direct provider passthrough route handled by ``HeadroomProxy.handle_passthrough``."""
+
+ method: str
+ path: str
+ provider_name: str
+ sub_path: str
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderHandlerRoute:
+ """A route that delegates directly to a named proxy handler."""
+
+ method: str
+ path: str
+ handler_name: str
+ path_param: str | None = None
+
+
+ANTHROPIC_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
+ ProviderPassthroughRoute("POST", "/v1/messages/count_tokens", "anthropic", "count_tokens"),
+)
+
+
+OPENAI_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
+ ProviderPassthroughRoute("POST", "/v1/embeddings", "openai", "embeddings"),
+ ProviderPassthroughRoute("POST", "/v1/moderations", "openai", "moderations"),
+ ProviderPassthroughRoute("POST", "/v1/audio/transcriptions", "openai", "audio/transcriptions"),
+ ProviderPassthroughRoute("POST", "/v1/audio/speech", "openai", "audio/speech"),
+)
+
+
+GEMINI_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
+ ProviderPassthroughRoute("GET", "/v1beta/models", "gemini", "models"),
+ ProviderPassthroughRoute("GET", "/v1beta/models/{model_name}", "gemini", "models"),
+ ProviderPassthroughRoute(
+ "POST", "/v1beta/models/{model}:embedContent", "gemini", "embedContent"
+ ),
+ ProviderPassthroughRoute(
+ "POST",
+ "/v1beta/models/{model}:batchEmbedContents",
+ "gemini",
+ "batchEmbedContents",
+ ),
+ ProviderPassthroughRoute("POST", "/v1beta/cachedContents", "gemini", "cachedContents"),
+ ProviderPassthroughRoute("GET", "/v1beta/cachedContents", "gemini", "cachedContents"),
+ ProviderPassthroughRoute(
+ "GET",
+ "/v1beta/cachedContents/{cache_id}",
+ "gemini",
+ "cachedContents",
+ ),
+ ProviderPassthroughRoute(
+ "DELETE",
+ "/v1beta/cachedContents/{cache_id}",
+ "gemini",
+ "cachedContents",
+ ),
+)
+
+
+PROVIDER_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
+ *ANTHROPIC_PASSTHROUGH_ROUTES,
+ *OPENAI_PASSTHROUGH_ROUTES,
+ *GEMINI_PASSTHROUGH_ROUTES,
+)
+
+
+ANTHROPIC_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute("POST", "/v1/messages", "handle_anthropic_messages"),
+)
+
+
+ANTHROPIC_BATCH_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute("POST", "/v1/messages/batches", "handle_anthropic_batch_create"),
+ ProviderHandlerRoute("GET", "/v1/messages/batches", "handle_anthropic_batch_passthrough"),
+ ProviderHandlerRoute(
+ "GET",
+ "/v1/messages/batches/{batch_id}",
+ "handle_anthropic_batch_passthrough",
+ "batch_id",
+ ),
+ ProviderHandlerRoute(
+ "GET",
+ "/v1/messages/batches/{batch_id}/results",
+ "handle_anthropic_batch_results",
+ "batch_id",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1/messages/batches/{batch_id}/cancel",
+ "handle_anthropic_batch_passthrough",
+ "batch_id",
+ ),
+)
+
+
+OPENAI_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute("POST", "/v1/chat/completions", "handle_openai_chat"),
+)
+
+
+OPENAI_BATCH_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute("POST", "/v1/batches", "handle_batch_create"),
+ ProviderHandlerRoute("GET", "/v1/batches", "handle_batch_list"),
+ ProviderHandlerRoute("GET", "/v1/batches/{batch_id}", "handle_batch_get", "batch_id"),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1/batches/{batch_id}/cancel",
+ "handle_batch_cancel",
+ "batch_id",
+ ),
+)
+
+
+GEMINI_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:generateContent",
+ "handle_gemini_generate_content",
+ "model",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:streamGenerateContent",
+ "handle_gemini_stream_generate_content",
+ "model",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:countTokens",
+ "handle_gemini_count_tokens",
+ "model",
+ ),
+)
+
+
+GEMINI_BATCH_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:batchGenerateContent",
+ "handle_google_batch_create",
+ "model",
+ ),
+ ProviderHandlerRoute(
+ "GET",
+ "/v1beta/batches/{batch_name}",
+ "handle_google_batch_results",
+ "batch_name",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/batches/{batch_name}:cancel",
+ "handle_google_batch_passthrough",
+ "batch_name",
+ ),
+ ProviderHandlerRoute(
+ "DELETE",
+ "/v1beta/batches/{batch_name}",
+ "handle_google_batch_passthrough",
+ "batch_name",
+ ),
+)
+
+
+CLOUDCODE_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1internal:streamGenerateContent",
+ "handle_google_cloudcode_stream",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1/v1internal:streamGenerateContent",
+ "handle_google_cloudcode_stream",
+ ),
+)
+
+
+PROVIDER_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
+ *ANTHROPIC_HANDLER_ROUTES,
+ *ANTHROPIC_BATCH_ROUTES,
+ *OPENAI_HANDLER_ROUTES,
+ *OPENAI_BATCH_ROUTES,
+ *GEMINI_HANDLER_ROUTES,
+ *GEMINI_BATCH_ROUTES,
+ *CLOUDCODE_HANDLER_ROUTES,
+)
diff --git a/headroom/providers/vertex/__init__.py b/headroom/providers/vertex/__init__.py
new file mode 100644
index 000000000..18e6b48e1
--- /dev/null
+++ b/headroom/providers/vertex/__init__.py
@@ -0,0 +1,33 @@
+"""Google Vertex provider helpers."""
+
+from .runtime import (
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
+ VERTEX_COUNT_TOKENS,
+ VERTEX_GENERATE_CONTENT,
+ VERTEX_GOOGLE_PROVIDER_NAME,
+ VERTEX_RAW_PREDICT,
+ VERTEX_STREAM_GENERATE_CONTENT,
+ VERTEX_STREAM_RAW_PREDICT,
+ VertexPublisherAction,
+ is_vertex_anthropic_publisher,
+ is_vertex_google_publisher,
+ vertex_anthropic_target,
+ vertex_publisher_provider_name,
+ vertex_target_for_location,
+)
+
+__all__ = [
+ "VERTEX_ANTHROPIC_PROVIDER_NAME",
+ "VERTEX_COUNT_TOKENS",
+ "VERTEX_GENERATE_CONTENT",
+ "VERTEX_GOOGLE_PROVIDER_NAME",
+ "VERTEX_RAW_PREDICT",
+ "VERTEX_STREAM_GENERATE_CONTENT",
+ "VERTEX_STREAM_RAW_PREDICT",
+ "VertexPublisherAction",
+ "is_vertex_anthropic_publisher",
+ "is_vertex_google_publisher",
+ "vertex_anthropic_target",
+ "vertex_publisher_provider_name",
+ "vertex_target_for_location",
+]
diff --git a/headroom/providers/vertex/runtime.py b/headroom/providers/vertex/runtime.py
new file mode 100644
index 000000000..5a1931ff7
--- /dev/null
+++ b/headroom/providers/vertex/runtime.py
@@ -0,0 +1,58 @@
+"""Pure Vertex provider routing formulas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from headroom.providers.registry import DEFAULT_VERTEX_API_URL
+
+VERTEX_GOOGLE_PUBLISHER = "google"
+VERTEX_ANTHROPIC_PUBLISHER = "anthropic"
+VERTEX_GOOGLE_PROVIDER_NAME = "vertex:google"
+VERTEX_ANTHROPIC_PROVIDER_NAME = "vertex:anthropic"
+
+
+@dataclass(frozen=True, slots=True)
+class VertexPublisherAction:
+ """A Vertex publisher action exposed by route registration."""
+
+ name: str
+ force_stream: bool = False
+
+
+VERTEX_GENERATE_CONTENT = VertexPublisherAction("generateContent")
+VERTEX_STREAM_GENERATE_CONTENT = VertexPublisherAction("streamGenerateContent")
+VERTEX_COUNT_TOKENS = VertexPublisherAction("countTokens")
+VERTEX_RAW_PREDICT = VertexPublisherAction("rawPredict")
+VERTEX_STREAM_RAW_PREDICT = VertexPublisherAction("streamRawPredict", force_stream=True)
+
+
+def is_vertex_google_publisher(publisher: str) -> bool:
+ """Return whether a Vertex publisher should use Gemini-style handlers."""
+ return publisher == VERTEX_GOOGLE_PUBLISHER
+
+
+def is_vertex_anthropic_publisher(publisher: str) -> bool:
+ """Return whether a Vertex publisher should use Anthropic-style handlers."""
+ return publisher == VERTEX_ANTHROPIC_PUBLISHER
+
+
+def vertex_publisher_provider_name(publisher: str) -> str:
+ """Return the provider label used for Vertex publisher passthrough telemetry."""
+ return f"vertex:{publisher}"
+
+
+def vertex_anthropic_target(base_url: str, *, versionless_route: bool = False) -> str:
+ """Return the Anthropic-on-Vertex upstream target for a route shape."""
+ if versionless_route:
+ return base_url.rstrip("/") + "/v1"
+ return base_url
+
+
+def vertex_target_for_location(configured_target: str, location: str) -> str:
+ """Return the Vertex upstream target for a request location."""
+ if configured_target and configured_target != DEFAULT_VERTEX_API_URL:
+ return configured_target
+ if not location or location == "global":
+ return "https://aiplatform.googleapis.com"
+ return f"https://{location}-aiplatform.googleapis.com"
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 7fce06409..e111dccdd 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -6,7 +6,6 @@ Contains all OpenAI Chat Completions, Responses API, and passthrough handlers.
from __future__ import annotations
import asyncio
-import base64
import contextlib
import copy
import hashlib
@@ -50,6 +49,17 @@ from headroom.copilot_auth import (
is_copilot_api_url,
)
from headroom.pipeline import PipelineStage, summarize_routing_markers
+from headroom.providers.codex.responses import (
+ codex_responses_http_url,
+ codex_responses_websocket_url,
+ has_chatgpt_account_header,
+)
+from headroom.providers.codex.runtime import (
+ decode_openai_bearer_payload,
+)
+from headroom.providers.codex.runtime import (
+ resolve_codex_routing_headers as _resolve_codex_routing_headers,
+)
from headroom.providers.copilot import model_prefers_responses_api
from headroom.proxy.auth_mode import (
classify_auth_mode,
@@ -60,6 +70,9 @@ from headroom.proxy.compression_decision import CompressionDecision
from headroom.proxy.cost import _summarize_transforms, header_safe_transforms
from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value
from headroom.proxy.outcome import RequestOutcome
+from headroom.proxy.passthrough import (
+ custom_base_passthrough_telemetry as _custom_base_passthrough_telemetry,
+)
from headroom.proxy.project_context import classify_project, set_current_project
logger = logging.getLogger("headroom.proxy")
@@ -86,7 +99,7 @@ _OPENAI_CHAT_COMPLETIONS_PATH = "/chat/completions"
_OPENAI_RESPONSES_PATH = "/responses"
_OPENAI_ORIGINAL_PATH_HEADER = "x-headroom-original-path"
_OPENAI_BASE_URL_HEADER = "x-headroom-base-url"
-_OPENCODE_ZEN_HOSTS = {"opencode.ai", "www.opencode.ai"}
+_decode_openai_bearer_payload = decode_openai_bearer_payload
def _normalize_openai_max_tokens(body: dict[str, Any]) -> None:
@@ -126,25 +139,6 @@ def _sanitize_forwarded_response_headers(
return cleaned
-def _custom_base_passthrough_telemetry(method: str, path: str, base_url: str) -> tuple[str, str]:
- """Return passthrough telemetry metadata for narrow custom-base exceptions."""
- # OpenCode Zen sends provider-prefixed OpenAI-compatible traffic through
- # custom-base routing. Keep this exact to avoid labeling arbitrary
- # custom-base tool traffic as LLM provider telemetry.
- if method.upper() != "POST":
- return "", ""
- try:
- host = (urlparse(base_url.strip()).hostname or "").lower()
- except ValueError:
- return "", ""
- if host not in _OPENCODE_ZEN_HOSTS:
- return "", ""
- normalized_path = path[1:] if path.startswith("/") else path
- if normalized_path == "zen/v1/chat/completions":
- return "chat/completions", "zen"
- return "", ""
-
-
def _resolve_openai_handler_path(
request_headers: dict[str, str],
*,
@@ -1020,53 +1014,6 @@ def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int,
return input_tokens, output_tokens, cached_tokens, cache_write_tokens, uncached_tokens
-def _decode_openai_bearer_payload(headers: dict[str, str]) -> dict[str, Any] | None:
- """Best-effort decode of an OpenAI OAuth bearer token payload.
-
- OpenClaw's Codex OAuth flow may forward only the bearer token after the
- provider base URL is overridden. In that case the explicit
- ``ChatGPT-Account-ID`` header can be missing even though the JWT still
- carries the account id we need to route to the ChatGPT Codex backend.
- """
- auth = headers.get("authorization") or headers.get("Authorization")
- if not auth:
- return None
-
- scheme, _, token = auth.partition(" ")
- if scheme.lower() != "bearer" or token.count(".") < 2:
- return None
-
- payload = token.split(".", 2)[1]
- payload += "=" * (-len(payload) % 4)
- # Intentionally no signature verification here: this is only a best-effort
- # routing hint extractor. Upstream still performs the actual auth/authz checks.
- try:
- decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
- data = json.loads(decoded.decode("utf-8"))
- except (ValueError, UnicodeDecodeError):
- return None
-
- return data if isinstance(data, dict) else None
-
-
-def _resolve_codex_routing_headers(headers: dict[str, str]) -> tuple[dict[str, str], bool]:
- """Resolve ChatGPT Codex routing hints from explicit headers or OAuth JWT."""
- resolved = dict(headers)
- lower_lookup = {k.lower(): k for k in resolved}
-
- if "chatgpt-account-id" in lower_lookup:
- return resolved, True
-
- payload = _decode_openai_bearer_payload(resolved)
- auth_claims = payload.get("https://api.openai.com/auth") if isinstance(payload, dict) else None
- account_id = auth_claims.get("chatgpt_account_id") if isinstance(auth_claims, dict) else None
- if isinstance(account_id, str) and account_id.strip():
- resolved["ChatGPT-Account-ID"] = account_id.strip()
- return resolved, True
-
- return resolved, False
-
-
def _prefers_http1_passthrough(base_url: str) -> bool:
"""Whether passthrough to this host must use HTTP/1.1.
@@ -4044,7 +3991,7 @@ class OpenAIHandlerMixin:
# Route to correct endpoint based on auth mode.
# ChatGPT session auth (codex login) uses chatgpt.com, not api.openai.com.
if is_chatgpt_auth:
- url = "https://chatgpt.com/backend-api/codex/responses"
+ url = codex_responses_http_url()
else:
upstream_base_url = _resolve_openai_upstream_base(request.headers)
handler_path = (
@@ -4811,7 +4758,7 @@ class OpenAIHandlerMixin:
# Build upstream WebSocket URL based on auth mode
if is_chatgpt_auth:
# ChatGPT session auth → route to chatgpt.com backend
- upstream_url = "wss://chatgpt.com/backend-api/codex/responses"
+ upstream_url = codex_responses_websocket_url()
logger.debug(
f"[{request_id}] WS: ChatGPT session auth detected, routing to chatgpt.com"
)
@@ -6995,9 +6942,8 @@ class OpenAIHandlerMixin:
Codex work immediately instead of exhausting its WS retry budget.
"""
# Route to correct endpoint based on auth mode
- _lower = {k.lower() for k in upstream_headers}
- if "chatgpt-account-id" in _lower:
- http_url = "https://chatgpt.com/backend-api/codex/responses"
+ if has_chatgpt_account_header(upstream_headers):
+ http_url = codex_responses_http_url()
else:
http_url = build_copilot_upstream_url(self.OPENAI_API_URL, "/v1/responses")
diff --git a/headroom/proxy/passthrough.py b/headroom/proxy/passthrough.py
new file mode 100644
index 000000000..720710bc2
--- /dev/null
+++ b/headroom/proxy/passthrough.py
@@ -0,0 +1,26 @@
+"""Shared passthrough routing and telemetry helpers."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+OPENCODE_ZEN_HOSTS = {"opencode.ai", "www.opencode.ai"}
+
+
+def custom_base_passthrough_telemetry(method: str, path: str, base_url: str) -> tuple[str, str]:
+ """Return passthrough telemetry metadata for narrow custom-base exceptions."""
+ # OpenCode Zen sends provider-prefixed OpenAI-compatible traffic through
+ # custom-base routing. Keep this exact to avoid labeling arbitrary
+ # custom-base tool traffic as LLM provider telemetry.
+ if method.upper() != "POST":
+ return "", ""
+ try:
+ host = (urlparse(base_url.strip()).hostname or "").lower()
+ except ValueError:
+ return "", ""
+ if host not in OPENCODE_ZEN_HOSTS:
+ return "", ""
+ normalized_path = path[1:] if path.startswith("/") else path
+ if normalized_path == "zen/v1/chat/completions":
+ return "chat/completions", "zen"
+ return "", ""
diff --git a/headroom/proxy/project_context.py b/headroom/proxy/project_context.py
index e0cd3bf9b..d6a446c68 100644
--- a/headroom/proxy/project_context.py
+++ b/headroom/proxy/project_context.py
@@ -18,7 +18,6 @@ from __future__ import annotations
from collections.abc import MutableMapping
from contextvars import ContextVar
from typing import Any
-from urllib.parse import quote
from headroom.proxy.project_policy import (
PROJECT_HEADER,
@@ -27,6 +26,7 @@ from headroom.proxy.project_policy import (
split_project_path,
with_project_prefix,
)
+from headroom.proxy.request_scope import normalize_scope_path
from headroom.proxy.savings_tracker import sanitize_project_name
_current_project: ContextVar[str | None] = ContextVar("headroom_current_project", default=None)
@@ -50,9 +50,7 @@ def strip_project_path_prefix(scope: MutableMapping[str, Any]) -> str | None:
"""
project, stripped = split_project_path(scope.get("path", ""))
if project is not None:
- scope["path"] = stripped
- if "raw_path" in scope:
- scope["raw_path"] = quote(stripped).encode("ascii")
+ normalize_scope_path(scope, stripped)
return project
diff --git a/headroom/proxy/request_scope.py b/headroom/proxy/request_scope.py
new file mode 100644
index 000000000..4a7e14dc9
--- /dev/null
+++ b/headroom/proxy/request_scope.py
@@ -0,0 +1,23 @@
+"""ASGI request-scope mutation helpers."""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import Request
+
+
+def normalize_scope_path(scope: MutableMapping[str, Any], path: str) -> None:
+ """Set an ASGI scope path and keep ``raw_path`` aligned when present."""
+ scope["path"] = path
+ if "raw_path" in scope:
+ scope["raw_path"] = quote(path).encode("ascii")
+
+
+def normalize_request_path(request: Request, path: str) -> None:
+ """Set a FastAPI request path and clear its cached URL, if any."""
+ normalize_scope_path(request.scope, path)
+ if hasattr(request, "_url"):
+ delattr(request, "_url")
diff --git a/tests/test_package_init_lazy.py b/tests/test_package_init_lazy.py
index be97b9463..7a320137e 100644
--- a/tests/test_package_init_lazy.py
+++ b/tests/test_package_init_lazy.py
@@ -161,6 +161,37 @@ def test_proxy_package_import_does_not_eagerly_load_server() -> None:
assert data["server_loaded"] is False
+def test_codex_package_import_stays_runtime_only() -> None:
+ script = textwrap.dedent(
+ """
+ import json
+ import sys
+
+ import headroom.providers.codex
+
+ print(json.dumps({
+ "images_loaded": "headroom.providers.codex.images" in sys.modules,
+ "model_metadata_loaded": "headroom.providers.codex.model_metadata" in sys.modules,
+ "responses_loaded": "headroom.providers.codex.responses" in sys.modules,
+ }))
+ """
+ )
+
+ result = subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ data = json.loads(result.stdout.strip())
+ assert data == {
+ "images_loaded": False,
+ "model_metadata_loaded": False,
+ "responses_loaded": False,
+ }
+
+
def test_proxy_server_import_skips_litellm_backend() -> None:
script = textwrap.dedent(
"""
diff --git a/tests/test_provider_cloudcode_runtime.py b/tests/test_provider_cloudcode_runtime.py
new file mode 100644
index 000000000..8f6a89b6a
--- /dev/null
+++ b/tests/test_provider_cloudcode_runtime.py
@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from headroom.providers.cloudcode import normalize_cloudcode_passthrough_path
+
+
+def test_normalize_cloudcode_passthrough_path_accepts_internal_routes() -> None:
+ assert normalize_cloudcode_passthrough_path("v1internal:loadCodeAssist") == (
+ "/v1internal:loadCodeAssist"
+ )
+ assert normalize_cloudcode_passthrough_path("/v1internal:loadCodeAssist") == (
+ "/v1internal:loadCodeAssist"
+ )
+
+
+def test_normalize_cloudcode_passthrough_path_strips_version_prefix() -> None:
+ assert normalize_cloudcode_passthrough_path("/v1/v1internal:fetchAvailableModels") == (
+ "/v1internal:fetchAvailableModels"
+ )
+
+
+def test_normalize_cloudcode_passthrough_path_ignores_unrelated_paths() -> None:
+ assert normalize_cloudcode_passthrough_path("/unrelated/v1internal:loadCodeAssist") is None
+ assert normalize_cloudcode_passthrough_path("/v1beta/models") is None
diff --git a/tests/test_provider_codex_endpoints.py b/tests/test_provider_codex_endpoints.py
new file mode 100644
index 000000000..d02827655
--- /dev/null
+++ b/tests/test_provider_codex_endpoints.py
@@ -0,0 +1,27 @@
+from headroom.providers.codex.endpoints import (
+ chatgpt_backend_url,
+ codex_backend_url,
+ codex_backend_ws_url,
+)
+
+
+def test_chatgpt_backend_url_appends_optional_query() -> None:
+ assert chatgpt_backend_url("/backend-api/me") == "https://chatgpt.com/backend-api/me"
+ assert (
+ chatgpt_backend_url("/backend-api/me", "client_version=1")
+ == "https://chatgpt.com/backend-api/me?client_version=1"
+ )
+
+
+def test_codex_backend_url_normalizes_path_prefix() -> None:
+ assert codex_backend_url("models") == "https://chatgpt.com/backend-api/codex/models"
+ assert (
+ codex_backend_url("/responses/compact", "trace=1")
+ == "https://chatgpt.com/backend-api/codex/responses/compact?trace=1"
+ )
+
+
+def test_codex_backend_ws_url_normalizes_path_prefix() -> None:
+ assert codex_backend_ws_url() == "wss://chatgpt.com/backend-api/codex"
+ assert codex_backend_ws_url("responses") == "wss://chatgpt.com/backend-api/codex/responses"
+ assert codex_backend_ws_url("/responses") == "wss://chatgpt.com/backend-api/codex/responses"
diff --git a/tests/test_provider_codex_headers.py b/tests/test_provider_codex_headers.py
new file mode 100644
index 000000000..6abfe3305
--- /dev/null
+++ b/tests/test_provider_codex_headers.py
@@ -0,0 +1,26 @@
+from headroom.providers.codex.headers import drop_header, header_name
+
+
+def test_header_name_matches_case_insensitively() -> None:
+ headers = {
+ "Authorization": "Bearer token",
+ "ChatGPT-Account-ID": "acct",
+ }
+
+ assert header_name(headers, "authorization") == "Authorization"
+ assert header_name(headers, "chatgpt-account-id") == "ChatGPT-Account-ID"
+ assert header_name(headers, "missing") is None
+
+
+def test_drop_header_removes_case_insensitive_match() -> None:
+ headers = {
+ "Host": "localhost:8787",
+ "Accept-Encoding": "gzip",
+ "authorization": "Bearer token",
+ }
+
+ drop_header(headers, "host")
+ drop_header(headers, "accept-encoding")
+ drop_header(headers, "missing")
+
+ assert headers == {"authorization": "Bearer token"}
diff --git a/tests/test_provider_codex_images.py b/tests/test_provider_codex_images.py
new file mode 100644
index 000000000..075aafe41
--- /dev/null
+++ b/tests/test_provider_codex_images.py
@@ -0,0 +1,62 @@
+import json
+
+from headroom.providers.codex.images import (
+ codex_image_forward_error_response,
+ codex_image_url,
+ normalize_codex_image_headers,
+ sanitize_codex_image_response_headers,
+)
+
+
+def test_codex_image_url_includes_optional_query() -> None:
+ assert (
+ codex_image_url("generations", "client_version=0.142.0")
+ == "https://chatgpt.com/backend-api/codex/images/generations?client_version=0.142.0"
+ )
+ assert codex_image_url("edits") == "https://chatgpt.com/backend-api/codex/images/edits"
+
+
+def test_codex_image_headers_drop_proxy_only_headers_and_resolve_auth() -> None:
+ headers, is_chatgpt_auth = normalize_codex_image_headers(
+ {
+ "Host": "localhost:8787",
+ "Authorization": "Bearer token",
+ "Accept-Encoding": "gzip",
+ "X-Headroom-Bypass": "1",
+ "ChatGPT-Account-ID": "acct",
+ "Content-Type": "application/json",
+ }
+ )
+
+ assert is_chatgpt_auth is True
+ assert headers == {
+ "Authorization": "Bearer token",
+ "ChatGPT-Account-ID": "acct",
+ "Content-Type": "application/json",
+ }
+
+
+def test_codex_image_response_headers_drop_stale_framing_case_insensitive() -> None:
+ assert sanitize_codex_image_response_headers(
+ {
+ "Content-Encoding": "gzip",
+ "Content-Length": "9999",
+ "Content-Type": "application/json",
+ "x-upstream": "kept",
+ }
+ ) == {
+ "Content-Type": "application/json",
+ "x-upstream": "kept",
+ }
+
+
+def test_codex_image_forward_error_response_shape() -> None:
+ response = codex_image_forward_error_response()
+
+ assert response.status_code == 502
+ assert json.loads(response.body) == {
+ "error": {
+ "type": "upstream_error",
+ "message": "Failed to forward Codex image request",
+ }
+ }
diff --git a/tests/test_provider_codex_model_metadata.py b/tests/test_provider_codex_model_metadata.py
new file mode 100644
index 000000000..26f50c25e
--- /dev/null
+++ b/tests/test_provider_codex_model_metadata.py
@@ -0,0 +1,162 @@
+import base64
+import json
+
+import httpx
+import pytest
+
+from headroom.providers.codex import (
+ CodexRoutingDecision as ExportedCodexRoutingDecision,
+)
+from headroom.providers.codex import (
+ resolve_codex_routing as exported_resolve_codex_routing,
+)
+from headroom.providers.codex.model_metadata import (
+ codex_model_registry_entry,
+ fetch_chatgpt_codex_model_ids,
+ normalize_codex_registry_headers,
+ synthetic_model_get_response,
+ synthetic_models_list_response,
+)
+from headroom.providers.codex.runtime import (
+ decode_openai_bearer_payload,
+ resolve_codex_routing,
+ resolve_codex_routing_headers,
+)
+
+
+def _jwt(payload: dict) -> str:
+ header = {"alg": "none", "typ": "JWT"}
+
+ def encode(part: dict) -> str:
+ raw = json.dumps(part, separators=(",", ":")).encode("utf-8")
+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+ return f"{encode(header)}.{encode(payload)}."
+
+
+def test_codex_runtime_resolves_chatgpt_account_from_openai_oauth_jwt() -> None:
+ token = _jwt(
+ {
+ "https://api.openai.com/auth": {
+ "chatgpt_account_id": "acct-from-jwt",
+ }
+ }
+ )
+
+ payload = decode_openai_bearer_payload({"authorization": f"Bearer {token}"})
+ headers, is_chatgpt_auth = resolve_codex_routing_headers({"authorization": f"Bearer {token}"})
+
+ assert payload == {
+ "https://api.openai.com/auth": {
+ "chatgpt_account_id": "acct-from-jwt",
+ }
+ }
+ assert is_chatgpt_auth is True
+ assert headers["ChatGPT-Account-ID"] == "acct-from-jwt"
+
+
+def test_codex_runtime_exposes_named_routing_decision() -> None:
+ decision = resolve_codex_routing({"ChatGPT-Account-ID": "acct-explicit"})
+
+ assert decision.is_chatgpt_auth is True
+ assert decision.headers == {"ChatGPT-Account-ID": "acct-explicit"}
+
+
+def test_codex_package_exports_routing_decision() -> None:
+ decision = exported_resolve_codex_routing({"ChatGPT-Account-ID": "acct-root"})
+
+ assert isinstance(decision, ExportedCodexRoutingDecision)
+ assert decision.is_chatgpt_auth is True
+ assert decision.headers == {"ChatGPT-Account-ID": "acct-root"}
+
+
+def test_codex_runtime_ignores_malformed_oauth_jwt() -> None:
+ assert decode_openai_bearer_payload({"authorization": "Bearer header.***.sig"}) is None
+
+ headers, is_chatgpt_auth = resolve_codex_routing_headers(
+ {"authorization": "Bearer header.***.sig"}
+ )
+
+ assert is_chatgpt_auth is False
+ assert headers == {"authorization": "Bearer header.***.sig"}
+
+
+def test_codex_registry_headers_normalize_account_and_accept_headers() -> None:
+ headers = normalize_codex_registry_headers(
+ {
+ "Host": "localhost:8787",
+ "authorization": "Bearer token",
+ "ChatGPT-Account-ID": "acct",
+ "Accept": "text/event-stream",
+ }
+ )
+
+ assert headers == {
+ "authorization": "Bearer token",
+ "chatgpt-account-id": "acct",
+ "accept": "application/json",
+ }
+
+
+async def test_codex_model_registry_fetch_returns_slugs() -> None:
+ class FakeClient:
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, dict[str, str]]] = []
+
+ async def get(self, url, **kwargs): # type: ignore[no-untyped-def]
+ self.calls.append((url, dict(kwargs.get("headers", {}))))
+ return httpx.Response(
+ 200,
+ json={"models": [{"slug": "gpt-5.5"}, {"slug": ""}, {"slug": "gpt-5.4"}]},
+ )
+
+ client = FakeClient()
+
+ model_ids = await fetch_chatgpt_codex_model_ids(
+ client,
+ {"authorization": "Bearer token", "chatgpt-account-id": "acct"},
+ "0.135.0",
+ )
+
+ assert model_ids == ("gpt-5.5", "gpt-5.4")
+ assert client.calls == [
+ (
+ "https://chatgpt.com/backend-api/codex/models?client_version=0.135.0",
+ {
+ "authorization": "Bearer token",
+ "chatgpt-account-id": "acct",
+ "accept": "application/json",
+ },
+ )
+ ]
+
+
+def test_codex_synthetic_model_metadata_responses() -> None:
+ list_payload = json.loads(synthetic_models_list_response().body)
+ known_payload = json.loads(synthetic_model_get_response("gpt-5.5").body)
+ unknown = synthetic_model_get_response("gpt-99-future")
+
+ assert list_payload["object"] == "list"
+ assert "gpt-5.5" in {entry["id"] for entry in list_payload["data"]}
+ assert known_payload == {
+ "id": "gpt-5.5",
+ "object": "model",
+ "created": 0,
+ "owned_by": "openai",
+ }
+ assert unknown.status_code == 404
+
+
+def test_codex_model_registry_entry_preserves_upstream_fields_and_defaults() -> None:
+ entry = codex_model_registry_entry(
+ "gpt-5.3-codex-spark",
+ {"display_name": "Spark", "context_window": 12345},
+ )
+
+ assert entry["slug"] == "gpt-5.3-codex-spark"
+ assert entry["display_name"] == "Spark"
+ assert entry["context_window"] == 12345
+ assert entry["default_reasoning_level"] == "medium"
+ assert entry["supports_parallel_tool_calls"] is True
+ assert entry["supported_in_api"] is True
diff --git a/tests/test_provider_codex_responses.py b/tests/test_provider_codex_responses.py
new file mode 100644
index 000000000..5e67fb5a0
--- /dev/null
+++ b/tests/test_provider_codex_responses.py
@@ -0,0 +1,59 @@
+from headroom.providers.codex.responses import (
+ codex_responses_http_url,
+ codex_responses_subpath_url,
+ codex_responses_websocket_url,
+ has_chatgpt_account_header,
+ normalize_codex_responses_headers,
+)
+
+
+def test_codex_responses_subpath_url_includes_optional_query() -> None:
+ assert (
+ codex_responses_subpath_url("items/resp_1", "trace=2")
+ == "https://chatgpt.com/backend-api/codex/responses/items/resp_1?trace=2"
+ )
+ assert (
+ codex_responses_subpath_url("compact")
+ == "https://chatgpt.com/backend-api/codex/responses/compact"
+ )
+
+
+def test_codex_responses_endpoint_urls_are_provider_owned() -> None:
+ assert codex_responses_http_url() == "https://chatgpt.com/backend-api/codex/responses"
+ assert (
+ codex_responses_http_url("stream=true")
+ == "https://chatgpt.com/backend-api/codex/responses?stream=true"
+ )
+ assert codex_responses_websocket_url() == "wss://chatgpt.com/backend-api/codex/responses"
+
+
+def test_codex_responses_headers_drop_host_and_resolve_explicit_chatgpt_auth() -> None:
+ headers, is_chatgpt_auth = normalize_codex_responses_headers(
+ {
+ "Host": "localhost:8787",
+ "authorization": "Bearer token",
+ "chatgpt-account-id": "acct",
+ "originator": "Codex Desktop",
+ }
+ )
+
+ assert is_chatgpt_auth is True
+ assert headers == {
+ "authorization": "Bearer token",
+ "chatgpt-account-id": "acct",
+ "originator": "Codex Desktop",
+ }
+ assert has_chatgpt_account_header(headers) is True
+
+
+def test_codex_responses_headers_return_false_for_regular_openai_auth() -> None:
+ headers, is_chatgpt_auth = normalize_codex_responses_headers(
+ {
+ "Host": "localhost:8787",
+ "authorization": "Bearer sk-proj-test",
+ }
+ )
+
+ assert is_chatgpt_auth is False
+ assert headers == {"authorization": "Bearer sk-proj-test"}
+ assert has_chatgpt_account_header(headers) is False
diff --git a/tests/test_provider_model_metadata.py b/tests/test_provider_model_metadata.py
new file mode 100644
index 000000000..5a6a92f07
--- /dev/null
+++ b/tests/test_provider_model_metadata.py
@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, Response
+from fastapi.testclient import TestClient
+
+from headroom.providers.model_metadata import (
+ MODEL_METADATA_LIST_ENDPOINT,
+ ModelMetadataEndpoint,
+ handle_model_metadata_endpoint,
+ model_metadata_get_endpoint,
+)
+
+
+def test_model_metadata_endpoints_are_explicit() -> None:
+ assert MODEL_METADATA_LIST_ENDPOINT == ModelMetadataEndpoint(
+ "/v1/models",
+ "/backend-api/models",
+ )
+ assert model_metadata_get_endpoint("gpt-5") == ModelMetadataEndpoint(
+ "/v1/models/{model_id}",
+ "/backend-api/models/gpt-5",
+ )
+
+
+def test_handle_model_metadata_endpoint_returns_chatgpt_response_when_present(monkeypatch) -> None:
+ async def fake_chatgpt_metadata(
+ http_client,
+ request: Request,
+ upstream_path: str,
+ ) -> Response:
+ return JSONResponse({"client": http_client, "upstream_path": upstream_path})
+
+ monkeypatch.setattr(
+ "headroom.providers.model_metadata.handle_chatgpt_model_metadata",
+ fake_chatgpt_metadata,
+ )
+ proxy = type("Proxy", (), {"http_client": "h2"})()
+ app = FastAPI()
+
+ @app.get("/probe")
+ async def probe(request: Request):
+ return await handle_model_metadata_endpoint(
+ proxy,
+ request,
+ endpoint=MODEL_METADATA_LIST_ENDPOINT,
+ provider_api_base_url="https://api.openai.test",
+ provider_name="openai",
+ )
+
+ with TestClient(app) as client:
+ response = client.get("/probe")
+
+ assert response.json() == {"client": "h2", "upstream_path": "/backend-api/models"}
+
+
+def test_handle_model_metadata_endpoint_falls_back_to_selected_provider(monkeypatch) -> None:
+ async def fake_chatgpt_metadata(http_client, request: Request, upstream_path: str) -> None:
+ return None
+
+ calls: list[tuple[str, str, str]] = []
+
+ class Proxy:
+ http_client = "h2"
+
+ async def handle_passthrough(
+ self,
+ request: Request,
+ base_url: str,
+ sub_path: str = "",
+ provider_name: str = "",
+ ) -> Response:
+ calls.append((base_url, sub_path, provider_name))
+ return JSONResponse({"provider": provider_name, "sub_path": sub_path})
+
+ monkeypatch.setattr(
+ "headroom.providers.model_metadata.handle_chatgpt_model_metadata",
+ fake_chatgpt_metadata,
+ )
+ app = FastAPI()
+
+ @app.get("/probe")
+ async def probe(request: Request):
+ return await handle_model_metadata_endpoint(
+ Proxy(),
+ request,
+ endpoint=model_metadata_get_endpoint("claude-opus"),
+ provider_api_base_url="https://api.anthropic.test",
+ provider_name="anthropic",
+ )
+
+ with TestClient(app) as client:
+ response = client.get("/probe")
+
+ assert response.json() == {"provider": "anthropic", "sub_path": "models"}
+ assert calls == [("https://api.anthropic.test", "models", "anthropic")]
diff --git a/tests/test_provider_openai_images.py b/tests/test_provider_openai_images.py
new file mode 100644
index 000000000..5b68b8277
--- /dev/null
+++ b/tests/test_provider_openai_images.py
@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, Response
+from fastapi.testclient import TestClient
+
+from headroom.providers.openai_images import (
+ OPENAI_IMAGE_ENDPOINTS,
+ OpenAIImageEndpoint,
+ codex_image_subpath,
+ handle_openai_image_endpoint,
+ select_codex_image_client,
+)
+
+
+def test_openai_image_endpoints_are_explicit() -> None:
+ assert OPENAI_IMAGE_ENDPOINTS == (
+ OpenAIImageEndpoint("/v1/images/generations", "images/generations"),
+ OpenAIImageEndpoint("/v1/images/edits", "images/edits"),
+ )
+
+
+def test_codex_image_subpath_drops_openai_images_prefix() -> None:
+ assert codex_image_subpath("images/generations") == "generations"
+ assert codex_image_subpath("images/edits") == "edits"
+
+
+def test_select_codex_image_client_prefers_h1_client() -> None:
+ proxy = type("Proxy", (), {"http_client_h1": "h1", "http_client": "h2"})()
+ fallback_proxy = type("Proxy", (), {"http_client": "h2"})()
+
+ assert select_codex_image_client(proxy) == "h1"
+ assert select_codex_image_client(fallback_proxy) == "h2"
+
+
+def test_handle_openai_image_endpoint_returns_codex_response_when_present(monkeypatch) -> None:
+ async def fake_codex_images(client: Any, request: Request, sub_path: str) -> Response:
+ return JSONResponse({"client": client, "sub_path": sub_path})
+
+ monkeypatch.setattr(
+ "headroom.providers.openai_images.handle_chatgpt_codex_images",
+ fake_codex_images,
+ )
+ proxy = type("Proxy", (), {"http_client_h1": "h1", "http_client": "h2"})()
+ app = FastAPI()
+
+ @app.post("/probe")
+ async def probe(request: Request):
+ return await handle_openai_image_endpoint(
+ proxy,
+ request,
+ openai_api_base_url="https://api.openai.test",
+ endpoint=OpenAIImageEndpoint("/probe", "images/generations"),
+ )
+
+ with TestClient(app) as client:
+ response = client.post("/probe", json={"prompt": "test"})
+
+ assert response.json() == {"client": "h1", "sub_path": "generations"}
+
+
+def test_handle_openai_image_endpoint_falls_back_to_openai_passthrough(monkeypatch) -> None:
+ async def fake_codex_images(client: Any, request: Request, sub_path: str) -> None:
+ return None
+
+ calls: list[tuple[str, str, str]] = []
+
+ class Proxy:
+ http_client = "h2"
+
+ async def handle_passthrough(
+ self,
+ request: Request,
+ base_url: str,
+ sub_path: str = "",
+ provider_name: str = "",
+ ) -> Response:
+ calls.append((base_url, sub_path, provider_name))
+ return JSONResponse({"provider": provider_name, "sub_path": sub_path})
+
+ monkeypatch.setattr(
+ "headroom.providers.openai_images.handle_chatgpt_codex_images",
+ fake_codex_images,
+ )
+ app = FastAPI()
+
+ @app.post("/probe")
+ async def probe(request: Request):
+ return await handle_openai_image_endpoint(
+ Proxy(),
+ request,
+ openai_api_base_url="https://api.openai.test",
+ endpoint=OpenAIImageEndpoint("/probe", "images/edits"),
+ )
+
+ with TestClient(app) as client:
+ response = client.post("/probe", json={"prompt": "test"})
+
+ assert response.json() == {"provider": "openai", "sub_path": "images/edits"}
+ assert calls == [("https://api.openai.test", "images/edits", "openai")]
diff --git a/tests/test_provider_openai_responses.py b/tests/test_provider_openai_responses.py
new file mode 100644
index 000000000..439166ae9
--- /dev/null
+++ b/tests/test_provider_openai_responses.py
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.testclient import TestClient
+
+from headroom.providers.openai_responses import (
+ OPENAI_RESPONSES_ROOT_PATHS,
+ OPENAI_RESPONSES_SUBPATH_ROUTES,
+ OPENAI_RESPONSES_WEBSOCKET_PATHS,
+ OpenAIResponsesSubpathRoute,
+ handle_openai_responses_subpath,
+ normalize_openai_responses_headers,
+ openai_responses_subpath_url,
+)
+
+
+def test_openai_responses_route_aliases_are_explicit() -> None:
+ assert OPENAI_RESPONSES_ROOT_PATHS == (
+ "/v1/responses",
+ "/v1/codex/responses",
+ "/backend-api/responses",
+ "/backend-api/codex/responses",
+ )
+ assert OPENAI_RESPONSES_WEBSOCKET_PATHS == OPENAI_RESPONSES_ROOT_PATHS
+ assert OPENAI_RESPONSES_SUBPATH_ROUTES == (
+ OpenAIResponsesSubpathRoute("/v1/responses/{sub_path:path}", ("GET", "POST", "DELETE")),
+ OpenAIResponsesSubpathRoute(
+ "/v1/codex/responses/{sub_path:path}",
+ ("GET", "POST", "DELETE"),
+ ),
+ OpenAIResponsesSubpathRoute(
+ "/backend-api/responses/{sub_path:path}",
+ ("GET", "POST", "DELETE"),
+ ),
+ OpenAIResponsesSubpathRoute(
+ "/backend-api/codex/responses/{sub_path:path}",
+ ("GET", "POST", "DELETE"),
+ ),
+ )
+
+
+def test_openai_responses_route_aliases_are_unique() -> None:
+ root_keys = {("POST", path) for path in OPENAI_RESPONSES_ROOT_PATHS}
+ websocket_keys = {("WS", path) for path in OPENAI_RESPONSES_WEBSOCKET_PATHS}
+ subpath_keys = {
+ (method, spec.path) for spec in OPENAI_RESPONSES_SUBPATH_ROUTES for method in spec.methods
+ }
+
+ assert len(root_keys) == len(OPENAI_RESPONSES_ROOT_PATHS)
+ assert len(websocket_keys) == len(OPENAI_RESPONSES_WEBSOCKET_PATHS)
+ assert len(subpath_keys) == sum(len(spec.methods) for spec in OPENAI_RESPONSES_SUBPATH_ROUTES)
+
+
+def test_openai_responses_subpath_url_includes_optional_query() -> None:
+ assert (
+ openai_responses_subpath_url(
+ "https://api.openai.example/",
+ "items/resp_1",
+ "trace=2",
+ )
+ == "https://api.openai.example/v1/responses/items/resp_1?trace=2"
+ )
+ assert (
+ openai_responses_subpath_url("https://api.openai.example", "compact")
+ == "https://api.openai.example/v1/responses/compact"
+ )
+
+
+def test_normalize_openai_responses_headers_drops_host() -> None:
+ assert normalize_openai_responses_headers(
+ {"host": "localhost:8000", "authorization": "Bearer test"}
+ ) == {"authorization": "Bearer test"}
+
+
+def test_handle_openai_responses_subpath_forwards_body_headers_and_query() -> None:
+ class FakeAsyncClient:
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, str, dict[str, object]]] = []
+
+ async def request(self, method: str, url: str, **kwargs: object) -> httpx.Response:
+ self.calls.append((method, url, kwargs))
+ return httpx.Response(202, json={"ok": True}, headers={"x-upstream": "yes"})
+
+ fake = FakeAsyncClient()
+ app = FastAPI()
+
+ @app.post("/probe/{sub_path:path}")
+ async def probe(request: Request, sub_path: str):
+ return await handle_openai_responses_subpath(
+ fake,
+ request,
+ "https://api.openai.example",
+ sub_path,
+ )
+
+ with TestClient(app) as client:
+ response = client.post(
+ "/probe/items/resp_1?trace=1",
+ headers={"Authorization": "Bearer test"},
+ json={"model": "gpt-4o"},
+ )
+
+ assert response.status_code == 202
+ assert response.headers["x-upstream"] == "yes"
+ assert len(fake.calls) == 1
+ method, url, kwargs = fake.calls[0]
+ assert method == "POST"
+ assert url == "https://api.openai.example/v1/responses/items/resp_1?trace=1"
+ assert kwargs["headers"]["authorization"] == "Bearer test" # type: ignore[index]
+ assert kwargs["content"] == b'{"model":"gpt-4o"}'
+ assert kwargs["timeout"] == 120.0
+
+
+def test_handle_openai_responses_subpath_returns_502_on_failure() -> None:
+ class FailingAsyncClient:
+ async def request(self, method: str, url: str, **kwargs: object) -> httpx.Response:
+ raise RuntimeError(f"boom: {method} {url}")
+
+ app = FastAPI()
+
+ @app.delete("/probe/{sub_path:path}")
+ async def probe(request: Request, sub_path: str):
+ return await handle_openai_responses_subpath(
+ FailingAsyncClient(),
+ request,
+ "https://api.openai.example",
+ sub_path,
+ )
+
+ with TestClient(app) as client:
+ with patch("headroom.providers.openai_responses.logger") as logger:
+ response = client.delete("/probe/items/resp_1?trace=1")
+
+ assert response.status_code == 502
+ assert response.text == "Upstream request failed."
+ logger.error.assert_called_once()
+ assert "boom: DELETE https://api.openai.example/v1/responses/items/resp_1?trace=1" in str(
+ logger.error.call_args
+ )
diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.py
index 0c10124a9..7a6ebb599 100644
--- a/tests/test_provider_proxy_routes.py
+++ b/tests/test_provider_proxy_routes.py
@@ -9,6 +9,7 @@ import httpx
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
+from headroom.providers.codex.runtime import CodexRoutingDecision
from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app
@@ -307,6 +308,10 @@ def test_proxy_route_helpers_prefer_legacy_targets_and_gemini_passthrough() -> N
assert proxy_routes._select_passthrough_base_url(proxy, {"api-key": "azure"}) == (
"https://legacy.anthropic.test"
)
+ assert (
+ proxy_routes._select_passthrough_base_url(proxy, {"chatgpt-account-id": "acct"})
+ == "https://chatgpt.com"
+ )
assert proxy_routes._select_passthrough_base_url(proxy, {}) == "https://legacy.anthropic.test"
@@ -486,12 +491,15 @@ def test_openai_response_subpath_passthrough_returns_502_on_http_failure() -> No
with TestClient(_app()) as client:
client.app.state.proxy.http_client = FailingAsyncClient()
- with patch("headroom.providers.proxy_routes.logger") as logger:
+ with patch("headroom.providers.openai_responses.logger") as logger:
response = client.post("/v1/responses/compact?trace=1", json={"model": "gpt-4o"})
assert response.status_code == 502
- assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in response.text
+ assert response.text == "Upstream request failed."
logger.error.assert_called_once()
+ assert "boom: POST https://api.openai.test/v1/responses/compact?trace=1" in str(
+ logger.error.call_args
+ )
def test_openai_response_subpath_passthrough_uses_openai_target() -> None:
@@ -524,8 +532,8 @@ def test_openai_response_subpath_passthrough_uses_openai_target() -> None:
def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(monkeypatch) -> None:
monkeypatch.setattr(
- "headroom.providers.proxy_routes._resolve_codex_routing_headers",
- lambda headers: (headers, True),
+ "headroom.providers.codex.responses.resolve_codex_routing",
+ lambda headers: CodexRoutingDecision(headers=dict(headers), is_chatgpt_auth=True),
)
class FakeAsyncClient:
@@ -555,8 +563,11 @@ def test_openai_response_subpath_aliases_and_chatgpt_auth_use_expected_targets(m
def test_openai_image_routes_use_codex_backend_under_chatgpt_auth(monkeypatch) -> None:
monkeypatch.setattr(
- "headroom.providers.proxy_routes._resolve_codex_routing_headers",
- lambda headers: ({**headers, "ChatGPT-Account-ID": "acct_123"}, True),
+ "headroom.providers.codex.images.resolve_codex_routing",
+ lambda headers: CodexRoutingDecision(
+ headers={**headers, "ChatGPT-Account-ID": "acct_123"},
+ is_chatgpt_auth=True,
+ ),
)
class FakeAsyncClient:
@@ -627,8 +638,11 @@ def test_openai_image_codex_response_strips_stale_compression_headers(monkeypatc
upstream_body = b'{"ok":true}'
stale_content_length = "9999"
monkeypatch.setattr(
- "headroom.providers.proxy_routes._resolve_codex_routing_headers",
- lambda headers: ({**headers, "ChatGPT-Account-ID": "acct_123"}, True),
+ "headroom.providers.codex.images.resolve_codex_routing",
+ lambda headers: CodexRoutingDecision(
+ headers={**headers, "ChatGPT-Account-ID": "acct_123"},
+ is_chatgpt_auth=True,
+ ),
)
class FakeAsyncClient:
@@ -728,8 +742,11 @@ def test_openai_image_edits_api_key_auth_falls_through_to_openai_passthrough(
def test_openai_image_edits_preserves_multipart_body_under_chatgpt_auth(monkeypatch) -> None:
monkeypatch.setattr(
- "headroom.providers.proxy_routes._resolve_codex_routing_headers",
- lambda headers: ({**headers, "ChatGPT-Account-ID": "acct_123"}, True),
+ "headroom.providers.codex.images.resolve_codex_routing",
+ lambda headers: CodexRoutingDecision(
+ headers={**headers, "ChatGPT-Account-ID": "acct_123"},
+ is_chatgpt_auth=True,
+ ),
)
boundary = "----headroom-boundary"
body = (
@@ -817,10 +834,10 @@ def test_gemini_batch_embed_contents_passthrough_uses_gemini_target(monkeypatch)
def test_v1_models_fetches_codex_registry_under_chatgpt_auth(monkeypatch) -> None:
- proxy_routes = importlib.import_module("headroom.providers.proxy_routes")
+ model_metadata = importlib.import_module("headroom.providers.codex.model_metadata")
debug_messages: list[tuple[str, tuple[object, ...]]] = []
monkeypatch.setattr(
- proxy_routes.logger,
+ model_metadata.logger,
"debug",
lambda message, *args: debug_messages.append((message, args)),
)
diff --git a/tests/test_provider_proxy_targets.py b/tests/test_provider_proxy_targets.py
new file mode 100644
index 000000000..b8f4412c5
--- /dev/null
+++ b/tests/test_provider_proxy_targets.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from headroom.providers.proxy_targets import (
+ api_target,
+ select_passthrough_base_url,
+ vertex_target_for_location,
+)
+from headroom.providers.registry import DEFAULT_VERTEX_API_URL
+
+
+def _proxy(**legacy_targets: str):
+ class Runtime:
+ @staticmethod
+ def api_target(provider: str) -> str:
+ return f"https://runtime.{provider}.test"
+
+ @staticmethod
+ def model_metadata_provider(headers) -> str: # type: ignore[no-untyped-def]
+ return "anthropic" if headers.get("x-api-key") else "openai"
+
+ return type("Proxy", (), {**legacy_targets, "provider_runtime": Runtime()})()
+
+
+def test_api_target_prefers_legacy_proxy_attrs() -> None:
+ proxy = _proxy(ANTHROPIC_API_URL="https://legacy.anthropic.test")
+
+ assert api_target(proxy, "anthropic") == "https://legacy.anthropic.test"
+ assert api_target(proxy, "openai") == "https://runtime.openai.test"
+
+
+def test_vertex_target_for_location_derives_region_when_default_configured() -> None:
+ proxy = _proxy(VERTEX_API_URL=DEFAULT_VERTEX_API_URL)
+
+ assert vertex_target_for_location(proxy, "europe-west1") == (
+ "https://europe-west1-aiplatform.googleapis.com"
+ )
+ assert vertex_target_for_location(proxy, "global") == "https://aiplatform.googleapis.com"
+
+
+def test_vertex_target_for_location_honors_explicit_gateway() -> None:
+ proxy = _proxy(VERTEX_API_URL="https://vertex-gateway.example")
+
+ assert vertex_target_for_location(proxy, "europe-west1") == "https://vertex-gateway.example"
+
+
+def test_select_passthrough_base_url_handles_special_auth_modes() -> None:
+ proxy = _proxy(
+ ANTHROPIC_API_URL="https://legacy.anthropic.test",
+ OPENAI_API_URL="https://legacy.openai.test",
+ GEMINI_API_URL="https://legacy.gemini.test",
+ )
+
+ assert select_passthrough_base_url(proxy, {"chatgpt-account-id": "acct"}) == (
+ "https://chatgpt.com"
+ )
+ assert select_passthrough_base_url(proxy, {"x-goog-api-key": "test"}) == (
+ "https://legacy.gemini.test"
+ )
+ assert (
+ select_passthrough_base_url(
+ proxy,
+ {"api-key": "azure", "x-headroom-base-url": "https://azure.example/base/"},
+ )
+ == "https://azure.example/base"
+ )
+ assert select_passthrough_base_url(proxy, {"x-api-key": "anthropic"}) == (
+ "https://legacy.anthropic.test"
+ )
+ assert select_passthrough_base_url(proxy, {}) == "https://legacy.openai.test"
diff --git a/tests/test_provider_route_specs.py b/tests/test_provider_route_specs.py
new file mode 100644
index 000000000..52aa8e988
--- /dev/null
+++ b/tests/test_provider_route_specs.py
@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from headroom.providers.route_specs import (
+ ANTHROPIC_BATCH_ROUTES,
+ ANTHROPIC_HANDLER_ROUTES,
+ ANTHROPIC_PASSTHROUGH_ROUTES,
+ CLOUDCODE_HANDLER_ROUTES,
+ GEMINI_BATCH_ROUTES,
+ GEMINI_HANDLER_ROUTES,
+ GEMINI_PASSTHROUGH_ROUTES,
+ OPENAI_BATCH_ROUTES,
+ OPENAI_HANDLER_ROUTES,
+ OPENAI_PASSTHROUGH_ROUTES,
+ PROVIDER_HANDLER_ROUTES,
+ PROVIDER_PASSTHROUGH_ROUTES,
+ ProviderHandlerRoute,
+ ProviderPassthroughRoute,
+)
+
+
+def test_provider_passthrough_route_specs_are_unique() -> None:
+ route_keys = {(spec.method, spec.path) for spec in PROVIDER_PASSTHROUGH_ROUTES}
+
+ assert len(route_keys) == len(PROVIDER_PASSTHROUGH_ROUTES)
+
+
+def test_provider_handler_route_specs_are_unique() -> None:
+ route_keys = {(spec.method, spec.path) for spec in PROVIDER_HANDLER_ROUTES}
+
+ assert len(route_keys) == len(PROVIDER_HANDLER_ROUTES)
+
+
+def test_openai_passthrough_routes_model_endpoint_intent() -> None:
+ assert OPENAI_PASSTHROUGH_ROUTES == (
+ ProviderPassthroughRoute("POST", "/v1/embeddings", "openai", "embeddings"),
+ ProviderPassthroughRoute("POST", "/v1/moderations", "openai", "moderations"),
+ ProviderPassthroughRoute(
+ "POST",
+ "/v1/audio/transcriptions",
+ "openai",
+ "audio/transcriptions",
+ ),
+ ProviderPassthroughRoute("POST", "/v1/audio/speech", "openai", "audio/speech"),
+ )
+
+
+def test_anthropic_passthrough_routes_model_endpoint_intent() -> None:
+ assert ANTHROPIC_PASSTHROUGH_ROUTES == (
+ ProviderPassthroughRoute(
+ "POST",
+ "/v1/messages/count_tokens",
+ "anthropic",
+ "count_tokens",
+ ),
+ )
+
+
+def test_gemini_passthrough_routes_model_endpoint_intent() -> None:
+ assert (
+ ProviderPassthroughRoute(
+ "POST",
+ "/v1beta/models/{model}:batchEmbedContents",
+ "gemini",
+ "batchEmbedContents",
+ )
+ in GEMINI_PASSTHROUGH_ROUTES
+ )
+ assert (
+ ProviderPassthroughRoute(
+ "DELETE",
+ "/v1beta/cachedContents/{cache_id}",
+ "gemini",
+ "cachedContents",
+ )
+ in GEMINI_PASSTHROUGH_ROUTES
+ )
+
+
+def test_direct_handler_routes_model_endpoint_intent() -> None:
+ assert ANTHROPIC_HANDLER_ROUTES == (
+ ProviderHandlerRoute("POST", "/v1/messages", "handle_anthropic_messages"),
+ )
+ assert OPENAI_HANDLER_ROUTES == (
+ ProviderHandlerRoute("POST", "/v1/chat/completions", "handle_openai_chat"),
+ )
+ assert GEMINI_HANDLER_ROUTES == (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:generateContent",
+ "handle_gemini_generate_content",
+ "model",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:streamGenerateContent",
+ "handle_gemini_stream_generate_content",
+ "model",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:countTokens",
+ "handle_gemini_count_tokens",
+ "model",
+ ),
+ )
+ assert CLOUDCODE_HANDLER_ROUTES == (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1internal:streamGenerateContent",
+ "handle_google_cloudcode_stream",
+ ),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1/v1internal:streamGenerateContent",
+ "handle_google_cloudcode_stream",
+ ),
+ )
+
+
+def test_batch_handler_routes_model_endpoint_intent() -> None:
+ assert ANTHROPIC_BATCH_ROUTES[0] == ProviderHandlerRoute(
+ "POST",
+ "/v1/messages/batches",
+ "handle_anthropic_batch_create",
+ )
+ assert (
+ ProviderHandlerRoute(
+ "GET",
+ "/v1/messages/batches/{batch_id}/results",
+ "handle_anthropic_batch_results",
+ "batch_id",
+ )
+ in ANTHROPIC_BATCH_ROUTES
+ )
+ assert OPENAI_BATCH_ROUTES == (
+ ProviderHandlerRoute("POST", "/v1/batches", "handle_batch_create"),
+ ProviderHandlerRoute("GET", "/v1/batches", "handle_batch_list"),
+ ProviderHandlerRoute("GET", "/v1/batches/{batch_id}", "handle_batch_get", "batch_id"),
+ ProviderHandlerRoute(
+ "POST",
+ "/v1/batches/{batch_id}/cancel",
+ "handle_batch_cancel",
+ "batch_id",
+ ),
+ )
+ assert (
+ ProviderHandlerRoute(
+ "POST",
+ "/v1beta/models/{model}:batchGenerateContent",
+ "handle_google_batch_create",
+ "model",
+ )
+ in GEMINI_BATCH_ROUTES
+ )
+ assert (
+ ProviderHandlerRoute(
+ "DELETE",
+ "/v1beta/batches/{batch_name}",
+ "handle_google_batch_passthrough",
+ "batch_name",
+ )
+ in GEMINI_BATCH_ROUTES
+ )
diff --git a/tests/test_provider_vertex_runtime.py b/tests/test_provider_vertex_runtime.py
new file mode 100644
index 000000000..cf0bad667
--- /dev/null
+++ b/tests/test_provider_vertex_runtime.py
@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from headroom.providers.registry import DEFAULT_VERTEX_API_URL
+from headroom.providers.vertex import (
+ VERTEX_ANTHROPIC_PROVIDER_NAME,
+ VERTEX_COUNT_TOKENS,
+ VERTEX_GENERATE_CONTENT,
+ VERTEX_GOOGLE_PROVIDER_NAME,
+ VERTEX_RAW_PREDICT,
+ VERTEX_STREAM_GENERATE_CONTENT,
+ VERTEX_STREAM_RAW_PREDICT,
+ VertexPublisherAction,
+ is_vertex_anthropic_publisher,
+ is_vertex_google_publisher,
+ vertex_anthropic_target,
+ vertex_publisher_provider_name,
+ vertex_target_for_location,
+)
+
+
+def test_vertex_publisher_classification_is_explicit() -> None:
+ assert is_vertex_google_publisher("google") is True
+ assert is_vertex_google_publisher("anthropic") is False
+ assert is_vertex_anthropic_publisher("anthropic") is True
+ assert is_vertex_anthropic_publisher("google") is False
+
+
+def test_vertex_provider_names_are_provider_owned() -> None:
+ assert VERTEX_GOOGLE_PROVIDER_NAME == "vertex:google"
+ assert VERTEX_ANTHROPIC_PROVIDER_NAME == "vertex:anthropic"
+ assert vertex_publisher_provider_name("mistral") == "vertex:mistral"
+
+
+def test_vertex_publisher_actions_are_named_values() -> None:
+ assert VERTEX_GENERATE_CONTENT == VertexPublisherAction("generateContent")
+ assert VERTEX_STREAM_GENERATE_CONTENT == VertexPublisherAction("streamGenerateContent")
+ assert VERTEX_COUNT_TOKENS == VertexPublisherAction("countTokens")
+ assert VERTEX_RAW_PREDICT == VertexPublisherAction("rawPredict")
+ assert VERTEX_STREAM_RAW_PREDICT == VertexPublisherAction(
+ "streamRawPredict",
+ force_stream=True,
+ )
+
+
+def test_vertex_anthropic_target_adds_v1_only_for_versionless_routes() -> None:
+ assert vertex_anthropic_target("https://europe-west1-aiplatform.googleapis.com") == (
+ "https://europe-west1-aiplatform.googleapis.com"
+ )
+ assert (
+ vertex_anthropic_target(
+ "https://europe-west1-aiplatform.googleapis.com/",
+ versionless_route=True,
+ )
+ == "https://europe-west1-aiplatform.googleapis.com/v1"
+ )
+
+
+def test_vertex_target_for_location_derives_regional_hosts_from_default_target() -> None:
+ assert vertex_target_for_location(DEFAULT_VERTEX_API_URL, "europe-west1") == (
+ "https://europe-west1-aiplatform.googleapis.com"
+ )
+ assert vertex_target_for_location(DEFAULT_VERTEX_API_URL, "global") == (
+ "https://aiplatform.googleapis.com"
+ )
+ assert vertex_target_for_location(DEFAULT_VERTEX_API_URL, "") == (
+ "https://aiplatform.googleapis.com"
+ )
+
+
+def test_vertex_target_for_location_honors_explicit_gateway() -> None:
+ assert vertex_target_for_location("https://vertex-gateway.internal", "europe-west1") == (
+ "https://vertex-gateway.internal"
+ )
diff --git a/tests/test_proxy_passthrough.py b/tests/test_proxy_passthrough.py
new file mode 100644
index 000000000..c7e7f1572
--- /dev/null
+++ b/tests/test_proxy_passthrough.py
@@ -0,0 +1,37 @@
+from headroom.proxy.passthrough import custom_base_passthrough_telemetry
+
+
+def test_custom_base_passthrough_telemetry_recognizes_opencode_zen_chat() -> None:
+ assert custom_base_passthrough_telemetry(
+ "POST",
+ "/zen/v1/chat/completions",
+ "https://opencode.ai/",
+ ) == ("chat/completions", "zen")
+ assert custom_base_passthrough_telemetry(
+ "POST",
+ "zen/v1/chat/completions",
+ "https://www.opencode.ai",
+ ) == ("chat/completions", "zen")
+
+
+def test_custom_base_passthrough_telemetry_ignores_non_matching_traffic() -> None:
+ assert custom_base_passthrough_telemetry(
+ "GET",
+ "/zen/v1/chat/completions",
+ "https://opencode.ai/",
+ ) == ("", "")
+ assert custom_base_passthrough_telemetry(
+ "POST",
+ "/v1/chat/completions",
+ "https://opencode.ai/",
+ ) == ("", "")
+ assert custom_base_passthrough_telemetry(
+ "POST",
+ "/zen/v1/chat/completions",
+ "https://custom.example/",
+ ) == ("", "")
+ assert custom_base_passthrough_telemetry(
+ "POST",
+ "/zen/v1/chat/completions",
+ "://bad-url",
+ ) == ("", "")
diff --git a/tests/test_proxy_request_scope.py b/tests/test_proxy_request_scope.py
new file mode 100644
index 000000000..4bd482c07
--- /dev/null
+++ b/tests/test_proxy_request_scope.py
@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from fastapi import Request
+
+from headroom.proxy.request_scope import normalize_request_path, normalize_scope_path
+
+
+def test_normalize_scope_path_updates_path_and_raw_path() -> None:
+ scope = {"path": "/old", "raw_path": b"/old"}
+
+ normalize_scope_path(scope, "/v1/messages")
+
+ assert scope == {"path": "/v1/messages", "raw_path": b"/v1/messages"}
+
+
+def test_normalize_scope_path_quotes_raw_path_when_needed() -> None:
+ scope = {"path": "/old", "raw_path": b"/old"}
+
+ normalize_scope_path(scope, "/v1/models/claude opus")
+
+ assert scope["path"] == "/v1/models/claude opus"
+ assert scope["raw_path"] == b"/v1/models/claude%20opus"
+
+
+def test_normalize_scope_path_leaves_missing_raw_path_absent() -> None:
+ scope = {"path": "/old"}
+
+ normalize_scope_path(scope, "/new")
+
+ assert scope == {"path": "/new"}
+
+
+def test_normalize_request_path_clears_cached_url() -> None:
+ request = Request(
+ {
+ "type": "http",
+ "method": "GET",
+ "path": "/old",
+ "raw_path": b"/old",
+ "headers": [],
+ "query_string": b"",
+ "server": ("testserver", 80),
+ "scheme": "http",
+ "client": ("testclient", 50000),
+ }
+ )
+ assert str(request.url).endswith("/old")
+
+ normalize_request_path(request, "/new path")
+
+ assert request.scope["path"] == "/new path"
+ assert request.scope["raw_path"] == b"/new%20path"
+ assert request.url.path == "/new path"