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 -->
This commit is contained in:
Luis Araya
2026-10-08 22:30:20 -05:00
committed by GitHub
parent f8212a39dc
commit 931e5b9666
8 changed files with 153 additions and 1 deletions
+17
View File
@@ -79,6 +79,21 @@ def openai_compatible_base_url(proxy: Any, headers: Mapping[str, str]) -> str:
return target
def is_anthropic_hello_path(path: str | None) -> bool:
"""Return True for Anthropic's connectivity canary endpoint (/api/hello).
Claude Code (and other Anthropic SDK clients) sends unauthenticated
``HEAD /api/hello`` or ``GET /api/hello`` requests to test upstream
connectivity. Because the probe carries no authorization headers,
unrouted passthrough would otherwise fall through to the default OpenAI
target and fail with 404 (#3336).
"""
if not path:
return False
normalized = (path if path.startswith("/") else f"/{path}").rstrip("/")
return normalized == "/api/hello"
def select_passthrough_base_url(
proxy: Any, headers: Mapping[str, str], path: str | None = None
) -> str:
@@ -99,6 +114,8 @@ def select_passthrough_base_url(
if is_safe_upstream_url(azure_base):
return azure_base.rstrip("/")
logger.warning("ignoring unsafe x-headroom-base-url override: %r", azure_base)
if is_anthropic_hello_path(path):
return api_target(proxy, "anthropic")
provider_name = proxy.provider_runtime.model_metadata_provider(headers)
target = api_target(proxy, provider_name)
if (
+8 -1
View File
@@ -72,8 +72,15 @@ class ProxyProviderRuntime:
"""Resolve the upstream provider that should serve OpenAI-style model metadata."""
return "anthropic" if _is_anthropic_auth(headers) else "openai"
def select_passthrough_base_url(self, headers: Mapping[str, str]) -> str:
def select_passthrough_base_url(
self, headers: Mapping[str, str], path: str | None = None
) -> str:
"""Resolve the upstream base URL for catch-all passthrough requests."""
if path is not None:
from headroom.providers.proxy_targets import is_anthropic_hello_path
if is_anthropic_hello_path(path):
return self.api_targets.anthropic
if _is_anthropic_auth(headers):
return self.api_targets.anthropic
if headers.get("x-goog-api-key"):
+2
View File
@@ -28,6 +28,8 @@ class ProviderHandlerRoute:
ANTHROPIC_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
ProviderPassthroughRoute("POST", "/v1/messages/count_tokens", "anthropic", "count_tokens"),
ProviderPassthroughRoute("GET", "/api/hello", "anthropic", "api/hello"),
ProviderPassthroughRoute("HEAD", "/api/hello", "anthropic", "api/hello"),
)
+102
View File
@@ -0,0 +1,102 @@
"""Regression tests for Anthropic connectivity probe routing (#3336).
Claude Code (and other Anthropic SDK clients) sends unauthenticated
``HEAD /api/hello`` or ``GET /api/hello`` requests to test upstream
connectivity. Because the probe carries no authorization headers,
it must not fall through to the default OpenAI target.
"""
from __future__ import annotations
from typing import Any
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from headroom.providers.proxy_targets import (
is_anthropic_hello_path,
select_passthrough_base_url,
)
from headroom.proxy.server import HeadroomProxy, ProxyConfig, create_app
def _mock_proxy(**legacy_targets: str) -> Any:
class Runtime:
@staticmethod
def api_target(provider: str) -> str:
return f"https://runtime.{provider}.test"
@staticmethod
def model_metadata_provider(headers: Any) -> str:
return "anthropic" if headers.get("x-api-key") else "openai"
return type("Proxy", (), {**legacy_targets, "provider_runtime": Runtime()})()
def test_is_anthropic_hello_path_matches_expected_patterns() -> 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/subpath")
assert not is_anthropic_hello_path("/v1/messages")
assert not is_anthropic_hello_path("/api/other")
def test_select_passthrough_base_url_routes_hello_to_anthropic() -> None:
proxy = _mock_proxy(
ANTHROPIC_API_URL="https://anthropic.custom.test",
OPENAI_API_URL="https://openai.custom.test",
)
# Keyless probe on /api/hello routes to Anthropic target.
assert select_passthrough_base_url(proxy, {}, "/api/hello") == "https://anthropic.custom.test"
assert select_passthrough_base_url(proxy, {}, "api/hello/") == "https://anthropic.custom.test"
# Other keyless paths still fall through to OpenAI.
assert select_passthrough_base_url(proxy, {}, "/other/endpoint") == "https://openai.custom.test"
def test_hello_probe_end_to_end_routing(monkeypatch: Any) -> None:
calls: list[tuple[str, str, str, str]] = []
async def fake_passthrough(
self: Any, request: Any, base_url: str, sub_path: str = "", provider_name: str = ""
) -> JSONResponse:
calls.append((request.method, request.url.path, base_url, provider_name))
return JSONResponse(
{
"method": request.method,
"path": request.url.path,
"base_url": base_url,
"sub_path": sub_path,
"provider": provider_name,
}
)
monkeypatch.setattr(HeadroomProxy, "handle_passthrough", fake_passthrough)
app = create_app(
ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
anthropic_api_url="https://api.anthropic.test",
openai_api_url="https://api.openai.test",
)
)
with TestClient(app) as client:
# Keyless HEAD request as sent by Claude Code's Bun connectivity probe.
head_resp = client.head("/api/hello", headers={"user-agent": "Bun/1.1.20"})
assert head_resp.status_code == 200
assert calls[-1] == ("HEAD", "/api/hello", "https://api.anthropic.test", "anthropic")
# Keyless GET request.
get_resp = client.get("/api/hello")
assert get_resp.status_code == 200
assert calls[-1] == ("GET", "/api/hello", "https://api.anthropic.test", "anthropic")
assert get_resp.json()["base_url"] == "https://api.anthropic.test"
+3
View File
@@ -118,6 +118,9 @@ def test_provider_passthrough_routes_forward_expected_targets(monkeypatch) -> No
assert client.post("/v1/messages/count_tokens").json()["base_url"] == (
"https://api.anthropic.test"
)
assert client.get("/api/hello").json()["base_url"] == ("https://api.anthropic.test")
assert client.head("/api/hello").status_code == 200
assert calls[-1] == ("HEAD", "/api/hello", "https://api.anthropic.test", "anthropic")
assert client.get("/v1/models", headers={"x-goog-api-key": "test"}).json()["base_url"] == (
"https://api.openai.test"
)
+17
View File
@@ -4,6 +4,7 @@ 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,
@@ -79,6 +80,10 @@ def test_select_passthrough_base_url_handles_special_auth_modes() -> None:
"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 (
@@ -139,3 +144,15 @@ def test_openai_compatible_base_url_respects_configured_openai_target() -> None:
== "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")
+2
View File
@@ -160,6 +160,8 @@ def test_proxy_provider_runtime_routes_model_metadata_and_passthrough() -> None:
assert runtime.select_passthrough_base_url({"api-key": "azure", "x-headroom-base-url": ""}) == (
runtime.api_targets.openai
)
assert runtime.select_passthrough_base_url({}, "/api/hello") == runtime.api_targets.anthropic
assert runtime.select_passthrough_base_url({}, "/other/path") == runtime.api_targets.openai
def test_create_proxy_backend_handles_missing_litellm_backend(caplog) -> None:
+2
View File
@@ -52,6 +52,8 @@ def test_anthropic_passthrough_routes_model_endpoint_intent() -> None:
"anthropic",
"count_tokens",
),
ProviderPassthroughRoute("GET", "/api/hello", "anthropic", "api/hello"),
ProviderPassthroughRoute("HEAD", "/api/hello", "anthropic", "api/hello"),
)