mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## 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:
@@ -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 (
|
||||
|
||||
@@ -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"):
|
||||
|
||||
@@ -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"),
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -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"
|
||||
@@ -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"
|
||||
)
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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"),
|
||||
)
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user