fix(providers): drop the shadowed POST /v1/messages route spec (#4075)

## Description

`register_provider_routes` registers `POST /v1/messages` twice:

1. Explicitly, at `headroom/providers/proxy_routes.py:292`. This handler
honours `x-headroom-base-url`.
2. Again later, from `ANTHROPIC_HANDLER_ROUTES` in
`headroom/providers/route_specs.py`.

Starlette dispatches to the first matching route, so the spec route
never ran. If someone edited that spec, for example to set
`supports_custom_base_url`, nothing would change. This PR removes the
dead spec and adds a test that the registered app has no duplicate
(method, path) pairs.

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

- Remove `ANTHROPIC_HANDLER_ROUTES` and its entry in
`PROVIDER_HANDLER_ROUTES`. The explicit `/v1/messages` route in
`proxy_routes.py` is unchanged and is still the one that serves traffic.
- Add `test_registered_provider_routes_are_unique`. It builds the
FastAPI app through `register_provider_routes` and asserts that no
(method, path) pair is registered twice.
- Drop the test assertion that pinned the removed spec.

## Testing

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

### Test Output

```text
# before the fix (new test only)
FAILED tests/test_provider_route_specs.py::test_registered_provider_routes_are_unique
E   assert 2 == 1
1 failed, 9 passed

# after the fix
$ pytest -q tests/test_provider_route_specs.py tests/test_provider_proxy_routes.py tests/test_custom_base_passthrough_telemetry.py tests/test_proxy/test_anthropic_upstream_header.py tests/test_cli/test_wrap_bob.py
116 passed in 10.87s
$ ruff check headroom/providers/route_specs.py tests/test_provider_route_specs.py
All checks passed!
```

## Real Behavior Proof

- Environment: macOS, repo venv, branch checkout at 024a37a6 compared
with main a9815bbb, temp HOME / HEADROOM_WORKSPACE_DIR, offline.
- Exact command / steps: (1) shared smoke harness: start a real proxy
from this checkout against a local fake upstream and send one Anthropic
`POST /v1/messages` and one OpenAI request with a compressible tool
result; (2) build the app with `register_provider_routes` and list
duplicate (method, path) routes and the published OpenAPI operationId
for `POST /v1/messages`, on main and on this branch.
- Observed result: `POST /v1/messages` returns HTTP 200 through the
proxy with savings; main registers it twice (routes 4 and 21) and this
branch once. OpenAPI on main described the shadowed route that never
ran; it now describes the live handler.
- Not tested: a real Anthropic upstream; the fake upstream answers every
request.

```text
$ bash smoke.sh <worktree>
branch: cleanup/providers-evals-shadowed-messages-route @ 024a37a6
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.

$ python -c "<FastAPI(); register_provider_routes(app, proxy); count (method, path); app.openapi()['paths']['/v1/messages']['post']['operationId']>"
main:   DUP ('POST', '/v1/messages') [(4, 'anthropic_messages'), (21, 'anthropic_messages_post_v1_messages')]
main:   total routes 79
main:   operationId: anthropic_messages_post_v1_messages_v1_messages_post
branch: total routes 78
branch: operationId: anthropic_messages_v1_messages_post
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A, no runtime behaviour change.
- Stable/default behavior changed: No. The removed route was
unreachable.
- 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)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

OpenAPI: FastAPI's `/openapi.json` used to describe the shadowed spec
route (operationId
`anthropic_messages_post_v1_messages_v1_messages_post`); it now
describes the handler that actually serves the path
(`anthropic_messages_v1_messages_post`). Nothing in the repo, its SDKs,
docs or tests reads `/openapi.json` or operation ids, and FastAPI
already warns about other duplicate operation ids on main, so they are
not a stable contract. Documentation is N/A: the route spec was
internal. Mypy was not run, because there are no type changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Tejas Chopra
2026-10-10 08:56:41 -07:00
committed by GitHub
parent e5cbec5f1a
commit 69a16cb59c
2 changed files with 21 additions and 10 deletions
-6
View File
@@ -77,11 +77,6 @@ PROVIDER_PASSTHROUGH_ROUTES: tuple[ProviderPassthroughRoute, ...] = (
)
ANTHROPIC_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
ProviderHandlerRoute("POST", "/v1/messages", "handle_anthropic_messages"),
)
ANTHROPIC_BATCH_ROUTES: tuple[ProviderHandlerRoute, ...] = (
ProviderHandlerRoute("POST", "/v1/messages/batches", "handle_anthropic_batch_create"),
ProviderHandlerRoute("GET", "/v1/messages/batches", "handle_anthropic_batch_passthrough"),
@@ -206,7 +201,6 @@ CLOUDCODE_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
PROVIDER_HANDLER_ROUTES: tuple[ProviderHandlerRoute, ...] = (
*ANTHROPIC_HANDLER_ROUTES,
*ANTHROPIC_BATCH_ROUTES,
*OPENAI_HANDLER_ROUTES,
*OPENAI_BATCH_ROUTES,
+21 -4
View File
@@ -1,8 +1,13 @@
from __future__ import annotations
from collections import Counter
from types import SimpleNamespace
from fastapi import FastAPI
from headroom.providers.proxy_routes import register_provider_routes
from headroom.providers.route_specs import (
ANTHROPIC_BATCH_ROUTES,
ANTHROPIC_HANDLER_ROUTES,
ANTHROPIC_PASSTHROUGH_ROUTES,
CLOUDCODE_HANDLER_ROUTES,
GEMINI_BATCH_ROUTES,
@@ -30,6 +35,21 @@ def test_provider_handler_route_specs_are_unique() -> None:
assert len(route_keys) == len(PROVIDER_HANDLER_ROUTES)
def test_registered_provider_routes_are_unique() -> None:
"""A second route for the same method and path is shadowed by the first and never runs."""
app = FastAPI()
proxy = SimpleNamespace(config=SimpleNamespace(bedrock_api_url="https://bedrock.example.test"))
register_provider_routes(app, proxy)
seen: Counter[tuple[str, str]] = Counter()
for route in app.router.routes:
for method in getattr(route, "methods", None) or {"WEBSOCKET"}:
seen[(method, route.path)] += 1
assert seen[("POST", "/v1/messages")] == 1
assert [key for key, count in seen.items() if count > 1] == []
def test_openai_passthrough_routes_model_endpoint_intent() -> None:
assert OPENAI_PASSTHROUGH_ROUTES == (
ProviderPassthroughRoute("POST", "/v1/embeddings", "openai", "embeddings"),
@@ -79,9 +99,6 @@ def test_gemini_passthrough_routes_model_endpoint_intent() -> None:
def test_direct_handler_routes_model_endpoint_intent() -> None:
assert ANTHROPIC_HANDLER_ROUTES == (
ProviderHandlerRoute("POST", "/v1/messages", "handle_anthropic_messages"),
)
assert OPENAI_HANDLER_ROUTES == (
ProviderHandlerRoute("POST", "/v1/chat/completions", "handle_openai_chat"),
ProviderHandlerRoute("POST", "/chat/completions", "handle_openai_chat"),