akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/docs
History
Adryan Eka Vandra bb2acf700a
fix(proxy): honor x-headroom-base-url on /v1/messages route (#1763) 
## Description

The Anthropic Messages route (`POST /v1/messages`) ignored the
`x-headroom-base-url` per-request upstream override and unconditionally
forwarded to `api.anthropic.com`. `handle_anthropic_messages` already
accepts `upstream_base_url` (it builds the upstream URL via
`build_copilot_upstream_url`), but the route never passed it. Clients
that speak the Anthropic Messages wire format while authenticating
against a non-Anthropic gateway (e.g. OpenCode Zen's "Go" tier) were
forwarded to the real Anthropic API, which rejected the gateway key with
`401 invalid x-api-key`.

The route now reads and trims `x-headroom-base-url` and passes it
through as `upstream_base_url`, mirroring the OpenAI-compatible routes
and the generic passthrough route (`proxy_routes.py:996`).

Closes #1760

## 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/proxy_routes.py`: the `/v1/messages` route reads
`x-headroom-base-url`; when present it strips whitespace and a trailing
slash and passes the value as `upstream_base_url` to
`handle_anthropic_messages`. Absent or whitespace-only headers keep the
previous default (`api.anthropic.com`).
- `tests/test_proxy/test_anthropic_upstream_header.py`: new test module
pinning the route contract (header present, absent, empty,
whitespace-only, trimming + trailing-slash stripping).
- `docs/content/docs/configuration.mdx`: new "Proxy upstream override
(`x-headroom-base-url`)" subsection under Per-Request Overrides
documenting the header across the OpenAI, Anthropic Messages, and
passthrough routes.
- `CHANGELOG.md`: `Unreleased > Fixed` entry for the `/v1/messages`
override.

## 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
$ python -m pytest tests/test_proxy/ -k "anthropic or passthrough or bedrock"
collected 140 items / 91 deselected / 49 selected
tests/test_proxy/test_anthropic_upstream_header.py ....                  [ 65%]
...
49 passed, 91 deselected, 1 warning in 79.68s

$ ruff check headroom/providers/proxy_routes.py tests/test_proxy/test_anthropic_upstream_header.py
All checks passed!

$ mypy headroom/providers/proxy_routes.py
Success: no issues found in 1 source file
```

## Real Behavior Proof

Ran the actual `headroom proxy` against a local mock upstream (a tiny
HTTP server on `127.0.0.1:9911` that logs the path it receives) to
reproduce the issue's before/after.

- Environment: local, macOS, Python 3.12; ran `headroom proxy --port
8799` against a local mock upstream (a tiny HTTP server on
`127.0.0.1:9911` that logs the path it receives).
- Exact command / steps: started the proxy and the mock upstream, then
sent one `POST /v1/messages` **with** the override header and one
**without** it (negative control), using these two `curl` commands.

  ```bash
# WITH the override header — expect routing to the mock at
127.0.0.1:9911
  curl http://127.0.0.1:8799/v1/messages \
-H "content-type: application/json" -H "anthropic-version: 2023-06-01" \
    -H "x-headroom-base-url: http://127.0.0.1:9911" \
    -H "x-api-key: zen-test-key" \
-d
'{"model":"glm-5.2","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

# WITHOUT the override header — expect routing to the real
api.anthropic.com
  curl http://127.0.0.1:8799/v1/messages \
-H "content-type: application/json" -H "anthropic-version: 2023-06-01" \
    -H "x-api-key: sk-ant-fake" \
-d
'{"model":"claude-3-5-sonnet-20241022","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
  ```

- Observed result: with the header, the mock upstream logged `HIT
path=/v1/messages x-api-key=zen-test-key` and the proxy returned `HTTP
200`, confirming the request was routed to
`<x-headroom-base-url>/v1/messages` carrying the gateway key. Without
the header, the request went to the real `api.anthropic.com` (returned
`HTTP 401` with a genuine `request_id` and
`{"type":"authentication_error","message":"invalid x-api-key"}`) and the
mock received no additional hit — matching the pre-fix behavior in the
issue. Also verified by TDD: the two override unit cases failed before
the route change (`assert None == 'https://opencode.ai/zen/go'`) and
passed after it; all 4 new cases and 49 related proxy tests are green.
- Not tested: a request against the real OpenCode Zen gateway (no
credentials); the gateway path is verified with a local mock upstream
instead.

## 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
- [x] 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 have updated the CHANGELOG.md if applicable

## Additional Notes

- Manual testing against the real OpenCode Zen gateway is N/A (no
credentials); a local mock upstream is used instead to prove the routing
(see Real Behavior Proof).
- Scope is limited to `/v1/messages`. The related
`/v1/messages/count_tokens` route uses a fixed passthrough target and is
out of scope for this issue.
2026-07-09 12:43:40 -05:00
..
app docs: improve discoverability for AI agents and search crawlers 2026-05-13 17:36:06 -07:00
components tokens saved grid 2026-04-12 13:42:20 +06:00
content/docs fix(proxy): honor x-headroom-base-url on /v1/messages route (#1763) 2026-07-09 12:43:40 -05:00
lib docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
overrides fix: repair release and docs pipelines 2026-04-16 12:53:51 -05:00
screenshots Merge pull request #147 from JerrettDavis/feat/anthropic-usage-insights 2026-04-12 10:54:22 -07:00
.gitignore new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
bun.lock fix(deps): remediate dependency CVEs and publish SBOM (#1509) 2026-06-27 15:28:12 -07:00
claude-code-bedrock-headroom.md fix(bedrock): route ARNs via converse, named AWS profiles, and au. re… (#1456) 2026-07-02 22:51:05 -05:00
next.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
observability.md fix(observability): G3 remediation — bound cardinality + wire dead metrics 2026-05-24 10:41:56 -07:00
package-lock.json deps: bump the npm-minor-patch group across 4 directories with 18 updates (#1907) 2026-07-09 09:38:37 -04:00
package.json deps: bump the npm-minor-patch group across 4 directories with 18 updates (#1907) 2026-07-09 09:38:37 -04:00
postcss.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
proxy.ts new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
README.md new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
rtk-architecture.md fix(observability): wire Phase G PR-G3 RTK + proxy metrics (H-blocker) 2026-05-22 13:18:42 -07:00
source.config.ts docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
tsconfig.json new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00

README.md

docs

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Explore

In the project, you can see:

  • lib/source.ts: Code for content source adapter, loader() provides the interface to access your content.
  • lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
Route Description
app/(home) The route group for your landing page and other pages.
app/docs The documentation layout and pages.
app/api/search/route.ts The Route Handler for search.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: