fix(wrap): preserve pre-set ANTHROPIC_BASE_URL as proxy upstream (#1358)

## Description

Issue #1353: when the user already has `ANTHROPIC_BASE_URL` pointing at
a LiteLLM (or any custom Anthropic-compatible) gateway, `headroom wrap
claude` overwrote it with the local proxy URL and silently forwarded to
`api.anthropic.com`. `wrap claude` now treats a pre-existing
non-self-pointing `ANTHROPIC_BASE_URL` as the proxy's upstream (passed
as `ANTHROPIC_TARGET_API_URL`) so compression layers on top of the
user's gateway instead of replacing it. Explicit
`ANTHROPIC_TARGET_API_URL`, Foundry and Vertex paths still win.

Closes #1353

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

- Add `_detect_inbound_anthropic_upstream(proxy_port)` to
`headroom/cli/wrap.py`: returns a pre-set `ANTHROPIC_BASE_URL` as the
proxy upstream, ignoring unset/blank values and self-pointing localhost
URLs on the proxy port.
- Wire it into `wrap claude` so a user's custom gateway is preserved as
`ANTHROPIC_TARGET_API_URL` instead of being overwritten.
- Precedence unchanged: explicit `ANTHROPIC_TARGET_API_URL`, Foundry,
and Vertex still take priority.
- Add `tests/test_cli/test_wrap_claude_inbound_upstream.py` (8 cases)
covering detection, blank/unset, self-pointing URLs, and a
different-port upstream.

## Testing

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

### Test Output

```text
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_detects_custom_litellm_upstream PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_unset PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_blank PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://localhost:8787] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787/] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://LOCALHOST:8787/v1] PASSED
tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_localhost_on_different_port PASSED

============================== 8 passed in 0.25s ===============================
```

## Real Behavior Proof

- Observed result: eight focused detection cases fail without the helper
and pass with it; custom non-self-pointing gateways are preserved while
blank or self-pointing values fall through safely.

- Environment: Python 3.13, local checkout, pytest 9.0.3
- Exact command / steps: `pytest
tests/test_cli/test_wrap_claude_inbound_upstream.py -v` on the patched
branch, then with the production fix reverted.
- Observed result (RED → GREEN):
- **RED** — with the fix reverted, all 8 tests fail: `AttributeError:
module 'headroom.cli.wrap' has no attribute
'_detect_inbound_anthropic_upstream'` (`8 failed in 0.37s`).
  - **GREEN** — with the fix applied, all 8 pass (`8 passed in 0.25s`).
- Not tested: end-to-end live LiteLLM gateway round-trip (covered
indirectly by the upstream-URL detection unit tests).

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

## Additional Notes

Docs/CHANGELOG checklist items left unchecked as N/A: this is a
behavioral bug fix to existing `wrap claude` upstream handling with no
new public surface to document.


## Real Behavior Proof

- Environment: headroom 0.28.0 dev checkout (branch `fix/issue-1353`),
`.venv`, proxy port 8787.
- Exact command / steps: invoked the real detection path used by `wrap
claude` (`_detect_inbound_anthropic_upstream`) across representative
`ANTHROPIC_BASE_URL` values:
  ```
python -c "from headroom.cli.wrap import
_detect_inbound_anthropic_upstream as d; ..."
  ```
- Observed result:
  ```
  custom LiteLLM gateway        -> 'https://litellm.mycorp.internal/v1'
  unset                         -> None
  blank                         -> None
  self-pointing localhost:8787  -> None
  self-pointing LOCALHOST/v1    -> None
  different port (real upstream)-> 'http://10.0.0.5:4000'
  ```
A pre-set, non-self-pointing `ANTHROPIC_BASE_URL` is returned as the
proxy upstream (wired to `ANTHROPIC_TARGET_API_URL`), so compression
layers on top of the user's gateway. Unset / blank / self-pointing
values fall through to `None`, so the proxy default applies and no
self-forwarding loop is created.
- Not tested: full `wrap claude` launch end-to-end against a live
LiteLLM gateway (needs the external gateway + Claude Code); the wiring
from `custom_upstream` to `ANTHROPIC_TARGET_API_URL` is covered by the
unit suite.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Ben Younes
2026-10-01 22:32:38 -05:00
committed by GitHub
co-authored by Claude Opus 4.8 JerrettDavis
parent f19bc9a9c3
commit bb1ab6afd3
2 changed files with 109 additions and 1 deletions
+53 -1
View File
@@ -5625,6 +5625,42 @@ def wrap_selfheal(marker: str | None) -> None:
# Claude Code
# =============================================================================
# Hostnames that mean "this machine" — used to avoid feeding the proxy its own
# URL back as the upstream when the user already had ANTHROPIC_BASE_URL pointed
# at a previous Headroom instance.
_LOCAL_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "::1"})
def _detect_inbound_anthropic_upstream(port: int) -> str | None:
"""Return a pre-set ANTHROPIC_BASE_URL that is NOT this proxy, else None.
Issue #1353: users who already route Claude Code at a LiteLLM (or any
custom Anthropic-compatible) gateway via ``ANTHROPIC_BASE_URL`` lose that
routing when they run ``headroom wrap claude`` — wrap overwrites
ANTHROPIC_BASE_URL with the local proxy URL and silently forwards to
api.anthropic.com instead of the LiteLLM URL the user configured. Treat
the pre-existing value as the proxy's upstream so compression layers on
top of the user's gateway instead of replacing it. URLs pointing at this
proxy instance are ignored to avoid a self-referential forwarding loop.
"""
base_url = (os.environ.get("ANTHROPIC_BASE_URL") or "").strip()
if not base_url:
return None
try:
parsed = urllib.parse.urlsplit(base_url)
except ValueError:
return None
hostname = (parsed.hostname or "").lower()
if hostname in _LOCAL_HOSTNAMES:
try:
parsed_port = parsed.port
except ValueError:
return None
if parsed_port == port:
return None
return base_url
@wrap.command(context_settings={"ignore_unknown_options": True})
@_retired_context_tool_option
@@ -5851,6 +5887,20 @@ def claude(
proxy_url = _claude_proxy_base_url(port)
vertex_upstream = _vertex_target_api_url_from_claude_env(proxy_url) if use_vertex else None
# Issue #1353: when none of the explicit override channels (Foundry,
# Vertex, ANTHROPIC_TARGET_API_URL) apply, inherit a pre-existing
# ANTHROPIC_BASE_URL as the upstream so wrap doesn't silently revert
# the user's LiteLLM/custom-gateway routing back to api.anthropic.com.
custom_upstream: str | None = None
if (
not foundry_upstream
and not use_vertex
and not os.environ.get("ANTHROPIC_TARGET_API_URL")
):
custom_upstream = _detect_inbound_anthropic_upstream(port)
upstream_for_proxy = foundry_upstream or custom_upstream
_register_proxy_client(port)
proxy_holder[0], actual_port = _ensure_proxy(
port,
@@ -5861,7 +5911,7 @@ def claude(
code_graph=code_graph,
backend=backend,
region=region,
anthropic_api_url=foundry_upstream,
anthropic_api_url=upstream_for_proxy,
vertex_api_url=vertex_upstream,
clear_vertex_api_url=use_vertex and vertex_upstream is None,
)
@@ -5907,6 +5957,8 @@ def claude(
click.echo(
f" Foundry mode: ANTHROPIC_FOUNDRY_BASE_URL={_foundry_proxy_url(proxy_url)} → upstream {foundry_upstream}"
)
elif custom_upstream:
click.echo(f" ANTHROPIC_BASE_URL={proxy_url} → upstream {custom_upstream}")
else:
click.echo(f" ANTHROPIC_BASE_URL={proxy_url}")
# Issue #1779: Claude Code 2.1.196+ deterministically disables
@@ -0,0 +1,56 @@
"""Tests for inbound ANTHROPIC_BASE_URL → upstream forwarding (issue #1353).
Verifies that `headroom wrap claude` preserves a pre-existing custom
ANTHROPIC_BASE_URL (e.g. a LiteLLM gateway) as the proxy's Anthropic upstream
instead of silently reverting routing to api.anthropic.com.
"""
from __future__ import annotations
import pytest
from headroom.cli import wrap as wrap_cli
_PROXY_PORT = 8787
_LITELLM_URL = "https://litellm.example.internal/anthropic"
_MALFORMED_LOCAL_PORT_URL = "http://localhost:notaport"
def test_detects_custom_litellm_upstream(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("ANTHROPIC_BASE_URL", _LITELLM_URL)
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) == _LITELLM_URL
def test_returns_none_when_unset(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("ANTHROPIC_BASE_URL", raising=False)
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) is None
def test_returns_none_when_blank(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("ANTHROPIC_BASE_URL", " ")
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) is None
@pytest.mark.parametrize(
"url",
[
f"http://127.0.0.1:{_PROXY_PORT}",
f"http://localhost:{_PROXY_PORT}",
f"http://127.0.0.1:{_PROXY_PORT}/",
f"http://LOCALHOST:{_PROXY_PORT}/v1",
],
)
def test_returns_none_for_self_pointing_url(monkeypatch: pytest.MonkeyPatch, url: str) -> None:
monkeypatch.setenv("ANTHROPIC_BASE_URL", url)
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) is None
def test_returns_localhost_on_different_port(monkeypatch: pytest.MonkeyPatch) -> None:
other_port_url = f"http://127.0.0.1:{_PROXY_PORT + 1}"
monkeypatch.setenv("ANTHROPIC_BASE_URL", other_port_url)
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) == other_port_url
def test_returns_none_for_malformed_local_port(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("ANTHROPIC_BASE_URL", _MALFORMED_LOCAL_PORT_URL)
assert wrap_cli._detect_inbound_anthropic_upstream(_PROXY_PORT) is None