Files
headroom/tests/test_provider_proxy_targets.py
Luis Araya 931e5b9666 fix(anthropic): route /api/hello connectivity probes to Anthropic (#3336) (#4059)
## Description

Claude Code (and other Anthropic SDK clients) uses `HEAD /api/hello` or
`GET /api/hello` as an unauthenticated connectivity probe to verify
upstream reachability. Because this probe carries no Anthropic
authentication headers, the unrouted passthrough in
`select_passthrough_base_url` fell through to the default OpenAI target,
opening an unexpected outbound connection to `api.openai.com` (which
returns 404) on an Anthropic-only setup.

This mirrors the Copilot completion routing fix (#3076): `/api/hello` is
an Anthropic-specific endpoint and is now explicitly routed to the
Anthropic target even when no authentication headers are present.

Closes #3336

## 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

- `headroom/providers/route_specs.py`: add `GET` and `HEAD` `/api/hello`
to `ANTHROPIC_PASSTHROUGH_ROUTES`.
- `headroom/providers/proxy_targets.py`: add `is_anthropic_hello_path()`
and route `/api/hello` to `api_target(proxy, "anthropic")` in
`select_passthrough_base_url()`.
- `headroom/providers/registry.py`: accept optional `path` in
`select_passthrough_base_url()` to route `/api/hello` to Anthropic
target.
- `tests/test_provider_route_specs.py`,
`tests/test_provider_proxy_targets.py`,
`tests/test_provider_proxy_routes.py`,
`tests/test_provider_registry.py`: update existing route and target
assertions.
- `tests/test_anthropic_hello_probe_routing.py`: new targeted regression
tests for path normalization, base URL resolution, and unauthenticated
end-to-end `HEAD` and `GET` routing.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_provider_route_specs.py tests/test_provider_proxy_targets.py tests/test_provider_proxy_routes.py tests/test_provider_registry.py tests/test_anthropic_hello_probe_routing.py -q
..................................................................       [100%]
66 passed, 1 warning in 56.04s

$ ruff check headroom/providers/route_specs.py headroom/providers/proxy_targets.py headroom/providers/registry.py tests/test_anthropic_hello_probe_routing.py
All checks passed!

$ ruff format --check headroom/providers/route_specs.py headroom/providers/proxy_targets.py headroom/providers/registry.py tests/test_anthropic_hello_probe_routing.py
4 files already formatted

$ mypy headroom/providers/route_specs.py headroom/providers/proxy_targets.py headroom/providers/registry.py tests/test_anthropic_hello_probe_routing.py --follow-imports=silent --ignore-missing-imports
Success: no issues found in 4 source files
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.14.6, local test server with
Anthropic and OpenAI target stubs.
- Exact command / steps: Sent unauthenticated `HEAD /api/hello`
(carrying `User-Agent: Bun/1.1.20`) and `GET /api/hello` requests to the
proxy using `fastapi.testclient.TestClient`.
- Observed result: Both requests routed directly to
`https://api.anthropic.test` with HTTP 200; `fake_passthrough` recorded
`base_url == "https://api.anthropic.test"` and `provider ==
"anthropic"`. Other unauthenticated endpoints continue falling through
to `https://api.openai.test`.
- Not tested: Live Anthropic egress against production Claude API.

### Maintainer live qualification (2026-10-08)

- Environment: actual Windows 11, Python 3.12.13, uvicorn proxy over
loopback TCP. Provider API-key environment variables were empty; the
client sent no authentication headers.
- Exact steps: start the unchanged proxy from this head with
`anthropic_api_url=https://api.anthropic.com` and the OpenAI target
deliberately set to unreachable `http://127.0.0.1:1`; send keyless `HEAD
/api/hello` and `GET /api/hello` through the proxy with httpx.
- Observed: public Anthropic returned **HEAD 200 with zero body bytes**
and **GET 200 with `{"message": "hello"}`**. No handler or provider call
was mocked. A second real TCP probe against a loopback Anthropic test
server captured exactly HEAD and GET `/api/hello`, both 200, while the
OpenAI target remained unreachable. **66 focused provider-routing tests
passed**.
- Scope: connectivity canaries only; no inference request or
credentialed API action was made. Hosted CI was held by GitHub's fork
workflow-approval gate, which the maintainer approved after reviewing
this exact head; CI is now running and PR approval remains pending until
it qualifies.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: `/api/hello` probes now forward to
Anthropic rather than OpenAI. Other unauthenticated routes remain
unchanged.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## 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
- [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
- [x] My changes generate no new warnings
- [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
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

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

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4059"
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 -->
2026-10-08 22:30:20 -05:00

159 lines
6.3 KiB
Python

from __future__ import annotations
from unittest.mock import patch
from headroom.providers.proxy_targets import (
api_target,
is_anthropic_hello_path,
openai_compatible_base_url,
select_passthrough_base_url,
vertex_target_for_location,
)
from headroom.providers.registry import DEFAULT_VERTEX_API_URL
from headroom.proxy import upstream_guard
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"
)
# The Azure branch honours the override only after the SSRF guard clears
# the destination (CVE-2026-77775), and `azure.example` does not resolve.
# Pin a public answer so this stays a test of target *precedence*.
with patch.object(
upstream_guard.socket,
"getaddrinfo",
return_value=[(None, None, None, None, ("20.10.10.10", 443))],
):
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"
assert select_passthrough_base_url(proxy, {}, "/api/hello") == "https://legacy.anthropic.test"
assert select_passthrough_base_url(proxy, {}, "/api/hello/") == "https://legacy.anthropic.test"
# Non-probe unauthenticated paths still fall through to OpenAI.
assert select_passthrough_base_url(proxy, {}, "/other/endpoint") == "https://legacy.openai.test"
# A configured OpenAI target outranks Grok wire signals (see
# ``test_openai_compatible_base_url_respects_configured_openai_target``).
assert (
select_passthrough_base_url(
proxy,
{
"x-xai-token-auth": "xai-grok-cli",
"user-agent": "grok-shell/0.2.117",
},
)
== "https://legacy.openai.test"
)
def test_openai_compatible_base_url_routes_grok_to_xai_on_default_target() -> None:
"""The shared-proxy case this routing exists for: OpenAI target untouched."""
proxy = _proxy(OPENAI_API_URL="https://api.openai.com")
grok_headers = {"user-agent": "grok-pager/0.2.117 grok-shell/0.2.117"}
assert openai_compatible_base_url(proxy, grok_headers) == "https://api.x.ai"
assert openai_compatible_base_url(proxy, {}) == "https://api.openai.com"
# Also via passthrough, which is the catch-all entry point Grok CLI hits.
assert select_passthrough_base_url(proxy, grok_headers) == "https://api.x.ai"
def test_openai_compatible_base_url_routes_grok_build_to_xai_on_default_target() -> None:
"""Grok Build + Antigravity manifest case: the OpenAI target stays default.
Antigravity needs api.openai.com, so the manifest cannot point the whole
proxy at xAI; Grok Build's ``grok/`` user agent must still route there per
request — for direct inference and for model-list/passthrough alike.
"""
proxy = _proxy(OPENAI_API_URL="https://api.openai.com")
grok_build_headers = {"user-agent": "grok/1.2.3"}
assert openai_compatible_base_url(proxy, grok_build_headers) == "https://api.x.ai"
assert select_passthrough_base_url(proxy, grok_build_headers) == "https://api.x.ai"
# Antigravity traffic keeps the default OpenAI target.
assert (
openai_compatible_base_url(proxy, {"user-agent": "antigravity/1.0.0"})
== "https://api.openai.com"
)
def test_openai_compatible_base_url_respects_configured_openai_target() -> None:
"""An operator gateway is chosen for every OpenAI-compatible client.
A client User-Agent must not silently bypass it, nor carry the gateway's
``OPENAI_TARGET_API_HEADERS`` to a different vendor.
"""
proxy = _proxy(OPENAI_API_URL="https://legacy.openai.test")
assert (
openai_compatible_base_url(
proxy,
{"user-agent": "grok-pager/0.2.117 grok-shell/0.2.117"},
)
== "https://legacy.openai.test"
)
assert openai_compatible_base_url(proxy, {}) == "https://legacy.openai.test"
def test_is_anthropic_hello_path() -> None:
assert is_anthropic_hello_path("/api/hello")
assert is_anthropic_hello_path("api/hello")
assert is_anthropic_hello_path("/api/hello/")
assert is_anthropic_hello_path("api/hello/")
assert not is_anthropic_hello_path(None)
assert not is_anthropic_hello_path("")
assert not is_anthropic_hello_path("/api/hello/extra")
assert not is_anthropic_hello_path("/v1/messages")
assert not is_anthropic_hello_path("/hello")