fix(proxy): route /v1/models to the x-headroom-base-url upstream (#4308)

## Description

Fixes #4302.

`GET /v1/models` and `GET /v1/models/{id}` always queried the default
provider upstream, so a request carrying `x-headroom-base-url` for a
custom OpenAI-compatible gateway got that gateway's key sent to
`api.openai.com` and a 401,. Both routes now resolve the upstream
through one helper that uses the header and applies the same unsafe-URL
rejection (400) as the catch-all.

Closes #4302

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Shared upstream resolver in `proxy_routes.py`, plus a test file.
- 5d7ecd1a5 (review follow-up): the resolver keeps the provider the
request's auth selects and overrides only the destination, so
`x-api-key` requests still get Anthropic model-id sanitization in
`handle_passthrough`. New
`tests/test_proxy/test_model_metadata_passthrough_sanitization.py` runs
the real `create_app` and `handle_passthrough` with an
`httpx.MockTransport` upstream and asserts the outbound URL.

## Testing

- [x] Unit tests pass (`pytest`) - the two metadata test files (7 tests)
- [x] Linting passes (`ruff check .`) - on the changed files
- [x] Type checking passes (`mypy headroom`) - `mypy headroom
--ignore-missing-imports` clean in the verify run
- [x] New tests added for new functionality
- [ ] Manual testing performed - not done

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_proxy/test_model_metadata_passthrough_sanitization.py tests/test_proxy/test_model_metadata_upstream_header.py -q -p no:cacheprovider
platform linux -- Python 3.14.7, pytest-9.2.0, pluggy-1.7.0
collected 7 items

tests/test_proxy/test_model_metadata_passthrough_sanitization.py ..      [ 28%]
tests/test_proxy/test_model_metadata_upstream_header.py .....            [100%]

============================== 7 passed in 6.76s ===============================

$ ruff check headroom/providers/proxy_routes.py tests/test_proxy/test_model_metadata_passthrough_sanitization.py && ruff format --check <same files>
All checks passed!
2 files already formatted

Discrimination: with proxy_routes.py reverted to a62ec010, test_anthropic_auth_with_header_upstream_sanitizes_model_id fails (outbound URL keeps `[1m]`) and the bearer test passes; with the fix, both pass.
Wider run (12 proxy/provider test files, same minimal venv): 282 passed / 17 failed at a62ec010 vs 283 passed / 16 failed at the fix; the 16 are environmental (offline-egress exporters and embedders absent from the minimal install, Gemini tests needing a key) and identical before and after.
```

## Real Behavior Proof

- Environment: FastAPI `TestClient` on the real `create_app`, real
`handle_passthrough`, only the outbound HTTP transport faked with
`httpx.MockTransport`
- Exact command / steps: the pytest command above
- Observed result: header honored on both routes; unsafe URLs get 400;
`GET /v1/models/claude-opus-4-8[1m]` with `x-api-key` and
`x-headroom-base-url: https://gateway.example` sends
`https://gateway.example/v1/models/claude-opus-4-8`; bearer auth sends
the id unchanged
- Not tested: live provider

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: none
- Stable/default behavior changed: no
- Kill switch / disable path: none
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines - ruff check and
format on the changed files
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings - not run
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes - see
Test Output; 16 failures are environmental and identical at base
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

N/A

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4308"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Younes Beriane
2026-11-03 22:47:46 -06:00
committed by GitHub
co-authored by JD Davis
parent b1f340e0b3
commit 6ef52c2047
3 changed files with 171 additions and 9 deletions
+19 -9
View File
@@ -498,8 +498,19 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
VERTEX_STREAM_RAW_PREDICT.name,
)
@app.get("/v1/models")
async def list_models(request: Request):
async def _model_metadata_route(request: Request) -> tuple[str, str]:
# A caller-named upstream wins, as in the catch-all and the chat
# handlers: model discovery must reach the same gateway as inference.
custom_base = request.headers.get("x-headroom-base-url", "").strip()
if custom_base:
if not await is_safe_upstream_url_async(custom_base):
logger.warning("rejecting unsafe x-headroom-base-url: %r", custom_base)
raise HTTPException(status_code=400, detail="Rejected unsafe upstream base URL")
# Only the destination is overridden: keep the provider the request's
# auth selects, so Anthropic-auth requests still get model-id
# sanitization in handle_passthrough.
provider_name = proxy.provider_runtime.model_metadata_provider(dict(request.headers))
return provider_name, custom_base.rstrip("/")
headers = dict(request.headers)
provider_name = proxy.provider_runtime.model_metadata_provider(headers)
base_url = (
@@ -507,6 +518,11 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
if provider_name == "openai"
else _api_target(proxy, provider_name)
)
return provider_name, base_url
@app.get("/v1/models")
async def list_models(request: Request):
provider_name, base_url = await _model_metadata_route(request)
return await handle_model_metadata_endpoint(
proxy,
request,
@@ -517,13 +533,7 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
@app.get("/v1/models/{model_id}")
async def get_model(request: Request, model_id: str):
headers = dict(request.headers)
provider_name = proxy.provider_runtime.model_metadata_provider(headers)
base_url = (
_openai_compatible_base_url(proxy, headers)
if provider_name == "openai"
else _api_target(proxy, provider_name)
)
provider_name, base_url = await _model_metadata_route(request)
return await handle_model_metadata_endpoint(
proxy,
request,
@@ -0,0 +1,63 @@
"""``GET /v1/models/{id}`` with ``x-headroom-base-url`` keeps the selected provider.
The header only overrides the destination. An Anthropic-authenticated request
(``x-api-key``) must still go through ``handle_passthrough``'s Anthropic
model-id sanitization, so Claude Code's ``[1m]`` context-tier suffix never
reaches the named gateway (#4302). These tests run the real
``handle_passthrough`` and fake only the upstream HTTP transport, asserting the
outbound URL.
"""
from __future__ import annotations
import pytest
pytest.importorskip("fastapi")
import httpx # noqa: E402
from fastapi.testclient import TestClient # noqa: E402
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
GATEWAY = "https://gateway.example"
@pytest.fixture
def real_passthrough(monkeypatch: pytest.MonkeyPatch):
monkeypatch.setenv("HEADROOM_REQUIRE_RUST_CORE", "false")
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "gateway.example")
outbound: list[httpx.Request] = []
def handler(request: httpx.Request) -> httpx.Response:
outbound.append(request)
return httpx.Response(200, json={"data": []})
config = ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
)
with TestClient(create_app(config)) as c:
c.app.state.proxy.http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
yield c, outbound
def test_anthropic_auth_with_header_upstream_sanitizes_model_id(real_passthrough) -> None:
client, outbound = real_passthrough
resp = client.get(
"/v1/models/claude-opus-4-8%5B1m%5D",
headers={"x-api-key": "sk-ant-test", "x-headroom-base-url": GATEWAY},
)
assert resp.status_code == 200
assert [str(r.url) for r in outbound] == [f"{GATEWAY}/v1/models/claude-opus-4-8"]
def test_bearer_auth_with_header_upstream_leaves_model_id_untouched(real_passthrough) -> None:
client, outbound = real_passthrough
resp = client.get(
"/v1/models/some-model%5B1m%5D",
headers={"authorization": "Bearer k", "x-headroom-base-url": GATEWAY},
)
assert resp.status_code == 200
assert [str(r.url) for r in outbound] == [f"{GATEWAY}/v1/models/some-model[1m]"]
@@ -0,0 +1,89 @@
"""``GET /v1/models`` and ``/v1/models/{id}`` must honor ``x-headroom-base-url``.
The catch-all passthrough and the chat handlers already route to the
caller-named upstream; model discovery used to ignore the header and hit the
default OpenAI upstream (#4302). An unsafe named upstream is rejected with 400
exactly like the catch-all.
"""
from __future__ import annotations
import pytest
pytest.importorskip("fastapi")
from fastapi import Response # noqa: E402
from fastapi.testclient import TestClient # noqa: E402
from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app # noqa: E402
GATEWAY = "https://gateway.example"
_CALLS: list[tuple[str, str, str]] = []
@pytest.fixture(scope="module")
def client():
# One app for the module: proxy shutdown dominates the runtime otherwise.
mp = pytest.MonkeyPatch()
mp.setenv("HEADROOM_REQUIRE_RUST_CORE", "false")
async def fake_passthrough(self, request, base_url, sub_path=None, *args, **kwargs):
_CALLS.append((base_url, sub_path, request.url.path))
return Response(content=b'{"data": []}', media_type="application/json")
mp.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
config = ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
)
try:
with TestClient(create_app(config)) as c:
yield c
finally:
mp.undo()
@pytest.fixture
def captured(client, monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, str, str]]:
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "gateway.example")
_CALLS.clear()
return _CALLS
def test_list_models_routes_to_header_upstream(client, captured) -> None:
resp = client.get(
"/v1/models",
headers={"authorization": "Bearer k", "x-headroom-base-url": GATEWAY + "/"},
)
assert resp.status_code == 200
assert [c[0] for c in captured] == [GATEWAY]
def test_get_model_routes_to_header_upstream(client, captured) -> None:
resp = client.get(
"/v1/models/some-model",
headers={"authorization": "Bearer k", "x-headroom-base-url": GATEWAY},
)
assert resp.status_code == 200
assert [c[0] for c in captured] == [GATEWAY]
def test_no_header_keeps_default_upstream(client, captured) -> None:
resp = client.get("/v1/models", headers={"authorization": "Bearer k"})
assert resp.status_code == 200
assert captured and captured[0][0] != GATEWAY
@pytest.mark.parametrize("path", ["/v1/models", "/v1/models/some-model"])
def test_unsafe_header_upstream_rejected(client, captured, monkeypatch, path) -> None:
monkeypatch.delenv("HEADROOM_ALLOWED_BASE_URLS", raising=False)
resp = client.get(
path,
headers={"authorization": "Bearer k", "x-headroom-base-url": "http://127.0.0.1:9"},
)
assert resp.status_code == 400
assert captured == []