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.

fix(anthropic): route /api/hello connectivity probes to Anthropic (#3336) (#4059)

Luis Araya931e5b9666f4
diff --git a/headroom/providers/proxy_targets.py b/headroom/providers/proxy_targets.py
index 24b1cba74..eaec63622 100644
--- a/headroom/providers/proxy_targets.py
+++ b/headroom/providers/proxy_targets.py
@@ -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 (
diff --git a/headroom/providers/registry.py b/headroom/providers/registry.py
index a8b816f3b..96c19d025 100644
--- a/headroom/providers/registry.py
+++ b/headroom/providers/registry.py
@@ -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"):
diff --git a/headroom/providers/route_specs.py b/headroom/providers/route_specs.py
index 2b03c33ba..510bb60d5 100644
--- a/headroom/providers/route_specs.py
+++ b/headroom/providers/route_specs.py
@@ -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"),
)
diff --git a/tests/test_anthropic_hello_probe_routing.py b/tests/test_anthropic_hello_probe_routing.py
new file mode 100644
index 000000000..bfffa1f12
--- /dev/null
+++ b/tests/test_anthropic_hello_probe_routing.py
@@ -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"
diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.py
index 39ea4171e..b8287f8d8 100644
--- a/tests/test_provider_proxy_routes.py
+++ b/tests/test_provider_proxy_routes.py
@@ -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"
)
diff --git a/tests/test_provider_proxy_targets.py b/tests/test_provider_proxy_targets.py
index 6b3aa2193..02e9a9b26 100644
--- a/tests/test_provider_proxy_targets.py
+++ b/tests/test_provider_proxy_targets.py
@@ -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")
diff --git a/tests/test_provider_registry.py b/tests/test_provider_registry.py
index 07310cd41..89be444d1 100644
--- a/tests/test_provider_registry.py
+++ b/tests/test_provider_registry.py
@@ -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:
diff --git a/tests/test_provider_route_specs.py b/tests/test_provider_route_specs.py
index bf860c5fb..bcd2caf29 100644
--- a/tests/test_provider_route_specs.py
+++ b/tests/test_provider_route_specs.py
@@ -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"),
)