fix(zcode): skip providers that point at the Headroom proxy itself (#4413)

## Description

`detect_upstream` returned the first enabled ZCode provider with a
`baseURL`, even when that URL is the Headroom proxy (the URL the setup
lines tell the user to configure), so `headroom wrap zcode` started the
proxy with itself as upstream. A provider with `"baseURL": null` also
raised `AttributeError` instead of falling back. `wrap zcode` now
resolves the port the proxy will bind (the requested port, or the next
free one when a non-Headroom service holds it) and passes it to
`detect_upstream`, which skips URLs whose host is the proxy's advertised
host (`127.0.0.1`, or `localhost` treated as the same host) on that
port. `[::1]` is not treated as the proxy: it is a different socket, so
an IPv6 provider on the same port stays selectable. Non-string `baseURL`
values are skipped.

Fixes #4409

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

- `detect_upstream(config_path=None, proxy_port=None)`: new optional
`proxy_port`; skip providers whose `baseURL` host is `127.0.0.1` or
`localhost` on that port (not `[::1]`, review round 2); skip non-string
`baseURL`.
- `wrap zcode` resolves the port first (`_find_available_port` when the
requested port is free or held by a non-Headroom listener; unchanged
when a Headroom proxy already runs there or with `--no-proxy`) and
passes it as `proxy_port`. Without this, `_ensure_proxy` could move the
proxy after the upstream was chosen: a backend on the occupied port was
skipped, and a provider on the replacement port (the proxy itself) could
be picked.
- Seven new tests in `tests/test_cli/test_wrap_zcode.py` (four for
`detect_upstream`, three for the port fallback). The new one,
`test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4`, drives
`detect_upstream` with an enabled provider at `http://[::1]:8787` and
`proxy_port=8787` and asserts that provider is selected.

## Testing

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

### Test Output

```text
# new tests, source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_skips_provider_pointing_at_proxy
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_only_proxy_provider_falls_back
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[null]
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[int]
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[list]
5 failed, 20 passed

# port-fallback tests (second commit), source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_keeps_backend_on_busy_port
FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_skips_provider_on_replacement_port
2 failed, 26 passed

# review round 2 ([::1] regression), source change reverted
FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4
1 failed, 28 passed

# with the fix
tests/test_cli/test_wrap_zcode.py: 29 passed
tests/test_cli/test_wrap_zcode.py test_wrap_antigravity.py test_wrap_bob.py: 108 passed

ruff check: All checks passed!
ruff format --check: 2 files already formatted (the two files touched in round 2)
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2), Python 3.12.15, upstream main e995eb9f (PR
head 98ff36c7). The Rust core `_core.abi3.so` was copied (not committed)
from the official `headroom-ai` 0.41.0 wheel. `HOME` pointed at a
scratch directory holding `~/.zcode/v2/config.json`. Real provider = a
local stub on 127.0.0.1:18831 that answers `POST /v1/messages` with a
200 message.
- Exact command / steps: with a config listing a Headroom provider
(`baseURL` http://127.0.0.1:18830) before the stub provider
(http://127.0.0.1:18831), run `HOME=<scratch> python -c "from
headroom.cli.main import main; main()" wrap zcode --port 18830`, wait
for "Proxy ready", then send one `POST /v1/messages` to 127.0.0.1:18830
and read the stub's log. Repeat with the first provider's `baseURL` set
to `null`. "Before" = the source change reverted with `git apply -R`.
- Observed result: see below.
- Not tested: a real ZCode app or the real Z.ai API; Windows/macOS; a
proxy listening on `::1` (`build_proxy_targets` always advertises
`127.0.0.1`, so the code cannot express it, and the inverse case has no
test); the `[::1]` change (review round 2) is unit-level only, no real
proxy run and no real sockets, the earlier runs above were not repeated;
non-loopback aliases of the proxy (a hostname or LAN address that
resolves to the proxy is not detected; the check is by design limited to
the loopback names ZCode's setup lines print); a port that changes after
the check, such as a stale Headroom proxy being replaced on another
port, or another process taking the free port between the check and the
proxy start; the OpenAI-compatible `kind`; mypy.

Before (change reverted), proxy-on-itself config:

```
  Detected provider: Headroom
  Upstream: http://127.0.0.1:18830
proxy process: python -m headroom.cli proxy --port 18830 --workers 1 --anthropic-api-url http://127.0.0.1:18830
client: no response within 40 s
stub upstream received: (nothing)
```

Before, `"baseURL": null` first:

```
  File ".../headroom/providers/zcode/runtime.py", line 86, in detect_upstream
    base_url = opts.get("baseURL", "").strip()
AttributeError: 'NoneType' object has no attribute 'strip'
```

After (this change), both configs:

```
  Detected provider: Z.ai local stub
  Upstream: http://127.0.0.1:18831
proxy process: python -m headroom.cli proxy --port 18830 --workers 1 --anthropic-api-url http://127.0.0.1:18831
client: HTTP 200 {"id": "msg_first", "type": "message", "role": "assistant", ...}
stub upstream received: STUB-UPSTREAM call #1 POST /v1/messages -> 200
```

Port fallback (`wrap zcode --port 18840`, a non-Headroom stub holds
18840 and is the ZCode provider; the proxy moves to 18841). Before
(second commit's source change reverted):

```
  Port 18840 is in use, using port 18841 instead.
  Detected provider: Z.ai (default)
  Upstream: https://api.z.ai/api/anthropic
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url https://api.z.ai/api/anthropic
```

The backend on the occupied port was skipped. With the provider's
`baseURL` set to the replacement port 18841 instead, the proxy is its
own upstream:

```
  Detected provider: Local backend
  Upstream: http://127.0.0.1:18841
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url http://127.0.0.1:18841
```

After (this change), backend on the occupied port:

```
  Starting Headroom proxy on port 18841...
  Detected provider: Local backend
  Upstream: http://127.0.0.1:18840
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url http://127.0.0.1:18840
client (POST /v1/messages to 127.0.0.1:18841): HTTP 200 {"stub": "ok"}
stub upstream received: STUB-UPSTREAM POST /v1/messages body_bytes=89
```

After, provider on the replacement port 18841 (skipped as the proxy
itself):

```
  Detected provider: Z.ai (default)
  Upstream: https://api.z.ai/api/anthropic
proxy process: python -m headroom.cli proxy --port 18841 --workers 1 --anthropic-api-url https://api.z.ai/api/anthropic
```

In the runs where the upstream fell back to api.z.ai no request was
sent, so nothing reached the real API.

Note: to start the proxy through the CLI in the scratch venv, the
packages that `headroom proxy` checks for (mcp, zstandard, websockets,
orjson, transformers, magika, onnxruntime) were installed into a
separate directory on `PYTHONPATH`.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only for ZCode configs that list a
provider pointing at the proxy's own port (now skipped) or a non-string
`baseURL` (now skipped instead of raising)
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none known
- Rollback path: revert the 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
- [ ] 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)

## Additional Notes

Only the three listed test files were run, not the whole suite.
`detect_upstream`'s new parameter is optional, so other callers are
unaffected (the only caller is `wrap zcode`). The change is three
commits: the first adds the loopback check and the `baseURL` guard, the
second resolves the port before detection (review feedback on the
first), the third stops treating `[::1]` as the proxy (maintainer
review). Policy: a provider counts as the proxy only if its host is the
advertised `127.0.0.1` (or `localhost`, treated as that host) and the
port matches; no DNS is done. The sibling PR #4405 (cc-switch loop
guard) applies the same rule (`[::1]` is the proxy only when the proxy
itself is bound to `::1`). Produced with AI assistance (Claude Code)
operated by me (HetCreep); the reproduction was run on my machine on a
clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
HetCreep
2026-10-24 08:45:28 -07:00
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent 023dd1bc54
commit 9ac1b52c27
3 changed files with 282 additions and 5 deletions
+9 -1
View File
@@ -8110,7 +8110,15 @@ def zcode(
if prepare_only:
return
upstream = _detect_zcode_upstream()
# _ensure_proxy moves to another port when the requested one is held by a
# non-Headroom service. Resolve that port first so the upstream is chosen
# against the port the proxy will actually bind.
if not no_proxy and not (_check_proxy(port) and not _foreign_listener(port)):
try:
port = _find_available_port(port)
except (OSError, RuntimeError):
pass # _ensure_proxy reports the same error
upstream = _detect_zcode_upstream(proxy_port=port)
anthropic_url, openai_url = _zcode_upstream_to_urls(upstream)
def _print_zcode_setup(actual_port: int = port) -> None:
+31 -4
View File
@@ -6,6 +6,7 @@ import json
import logging
from dataclasses import dataclass
from pathlib import Path
from urllib.parse import urlsplit
from headroom.install.paths import zcode_config_dir
from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url
@@ -40,11 +41,30 @@ def build_proxy_targets(port: int) -> ZCodeProxyTargets:
)
def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
def _points_at_proxy(base_url: str, proxy_port: int | None) -> bool:
"""True when *base_url* names the Headroom proxy: its advertised host and port.
Policy: the proxy is advertised on ``127.0.0.1`` (see ``build_proxy_targets``)
and ``localhost`` is treated as that same host. ``[::1]`` is a different
socket, so an IPv6 provider on the same port is a real upstream, not the proxy.
"""
if proxy_port is None:
return False
try:
parts = urlsplit(base_url)
return parts.hostname in ("127.0.0.1", "localhost") and parts.port == proxy_port
except ValueError:
return False
def detect_upstream(
config_path: Path | None = None, proxy_port: int | None = None
) -> ZCodeUpstream:
"""Read ZCode config.json and find the enabled provider's upstream URL.
Resolution order:
1. First provider with ``enabled=True`` and a non-empty ``baseURL``.
1. First provider with ``enabled=True`` and a non-empty ``baseURL`` that
does not point at the Headroom proxy itself (``proxy_port``).
2. Fallback: Z.ai Anthropic endpoint.
Parameters
@@ -52,6 +72,10 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
config_path:
Override for the config file path. When *None* the default
``~/.zcode/v2/config.json`` is used.
proxy_port:
Port of the local Headroom proxy. A provider whose ``baseURL`` is a
loopback URL on this port is skipped, because ZCode users are told to
point a provider at the proxy and using it as the upstream would loop.
"""
if config_path is None:
config_path = zcode_config_dir() / "v2" / "config.json"
@@ -83,8 +107,11 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
opts = provider.get("options", {})
if not isinstance(opts, dict):
continue
base_url = opts.get("baseURL", "").strip()
if not base_url:
base_url = opts.get("baseURL")
if not isinstance(base_url, str):
continue
base_url = base_url.strip()
if not base_url or _points_at_proxy(base_url, proxy_port):
continue
kind = provider.get("kind", "anthropic")
name = provider.get("name", "ZCode provider")
+242
View File
@@ -8,6 +8,7 @@ settings UI.
from __future__ import annotations
import json
from pathlib import Path
from unittest.mock import patch
@@ -151,6 +152,113 @@ def test_detect_upstream_no_baseurl_skips(tmp_path: Path) -> None:
assert upstream.base_url == "https://api.z.ai/api/anthropic"
def test_detect_upstream_skips_provider_pointing_at_proxy(tmp_path: Path) -> None:
"""A provider set to the Headroom proxy itself must not become the upstream."""
import json as _json
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
_json.dumps(
{
"provider": {
"headroom": {
"name": "Headroom",
"kind": "anthropic",
"enabled": True,
"options": {"baseURL": "http://127.0.0.1:8787"},
},
"local": {
"name": "Local",
"kind": "openai",
"enabled": True,
"options": {"baseURL": "http://localhost:8787/v1"},
},
"other-port": {
"name": "Other",
"kind": "openai",
"enabled": True,
"options": {"baseURL": "http://127.0.0.1:9999/v1"},
},
}
}
),
encoding="utf-8",
)
upstream = detect_upstream(config, proxy_port=8787)
assert upstream.provider_name == "Other"
assert upstream.base_url == "http://127.0.0.1:9999/v1"
def test_detect_upstream_only_proxy_provider_falls_back(tmp_path: Path) -> None:
"""With only a proxy-pointing provider the Z.ai default is used."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"headroom": {"name": "Headroom", "kind": "anthropic", '
'"enabled": true, "options": {"baseURL": "http://127.0.0.1:8787"}}}}',
encoding="utf-8",
)
upstream = detect_upstream(config, proxy_port=8787)
assert upstream.provider_name == "Z.ai (default)"
def test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4(tmp_path: Path) -> None:
"""[::1] is a different socket from the 127.0.0.1 proxy, so it stays selectable."""
import json as _json
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
_json.dumps(
{
"provider": {
"v6": {
"name": "Local v6",
"kind": "anthropic",
"enabled": True,
"options": {"baseURL": "http://[::1]:8787"},
}
}
}
),
encoding="utf-8",
)
upstream = detect_upstream(config, proxy_port=8787)
assert upstream.provider_name == "Local v6"
assert upstream.base_url == "http://[::1]:8787"
@pytest.mark.parametrize("base_url", [None, 42, ["x"]], ids=["null", "int", "list"])
def test_detect_upstream_non_string_baseurl_skips(tmp_path: Path, base_url: object) -> None:
"""detect_upstream falls back instead of raising when baseURL is not a string."""
import json as _json
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
_json.dumps(
{
"provider": {
"zai": {
"name": "Z.ai",
"kind": "anthropic",
"enabled": True,
"options": {"baseURL": base_url},
}
}
}
),
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
@pytest.mark.parametrize(
"bad_options",
[
@@ -313,6 +421,74 @@ def test_wrap_zcode_passes_upstream_to_watcher(
assert captured.get("port") == 9000
def _zcode_config_with(tmp_path: Path, base_url: str) -> Path:
home = tmp_path / "zhome"
(home / "v2").mkdir(parents=True)
(home / "v2" / "config.json").write_text(
json.dumps(
{
"provider": {
"p": {
"name": "P",
"kind": "anthropic",
"enabled": True,
"options": {"baseURL": base_url},
}
}
}
),
encoding="utf-8",
)
return home
def _run_zcode_with_port_busy(
runner: CliRunner, tmp_path: Path, base_url: str, *, busy: bool
) -> dict[str, object]:
"""Run ``wrap zcode --port 8787``; port 8787 is held by a foreign service when *busy*."""
captured: dict[str, object] = {}
home = _zcode_config_with(tmp_path, base_url)
with (
patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),
patch.object(wrap_mod, "_check_proxy", return_value=busy),
patch.object(wrap_mod, "_foreign_listener", return_value=busy),
patch.object(wrap_mod, "_find_available_port", return_value=8788 if busy else 8787),
patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),
):
runner.invoke(main, ["wrap", "zcode", "--port", "8787"])
return captured
def test_wrap_zcode_port_fallback_keeps_backend_on_busy_port(
runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A backend on the occupied port stays a valid upstream; the proxy moves to 8788."""
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8787", busy=True)
assert captured["port"] == 8788
assert captured["anthropic_api_url"] == "http://127.0.0.1:8787"
def test_wrap_zcode_port_fallback_skips_provider_on_replacement_port(
runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A provider pointing at the replacement port is the proxy itself, not an upstream."""
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8788", busy=True)
assert captured["port"] == 8788
assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"
def test_wrap_zcode_free_port_unchanged(
runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""With the requested port free, a provider on it is still skipped as the proxy."""
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8787", busy=False)
assert captured["port"] == 8787
assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"
def test_wrap_zcode_passes_openai_upstream(
runner: CliRunner,
tmp_path: Path,
@@ -339,3 +515,69 @@ def test_wrap_zcode_passes_openai_upstream(
assert captured.get("anthropic_api_url") is None
assert captured.get("openai_api_url") == "https://my-api.example.com/v1"
@pytest.mark.parametrize("base_url", ["http://127.0.0.1:99999", "http://127.0.0.1:abc"])
def test_detect_upstream_keeps_provider_with_unparseable_port(
tmp_path: Path, base_url: str
) -> None:
"""A port urlsplit cannot read is not the proxy's port, so the provider stays selectable."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
json.dumps(
{
"provider": {
"odd": {
"name": "Odd port",
"kind": "anthropic",
"enabled": True,
"options": {"baseURL": base_url},
}
}
}
),
encoding="utf-8",
)
upstream = detect_upstream(config, proxy_port=8787)
assert upstream.provider_name == "Odd port"
def test_wrap_zcode_keeps_requested_port_when_no_free_port_is_found(
runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""If the free-port search fails, the upstream is chosen against the requested port."""
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, object] = {}
home = _zcode_config_with(tmp_path, "http://127.0.0.1:8787")
with (
patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),
patch.object(wrap_mod, "_check_proxy", return_value=False),
patch.object(wrap_mod, "_foreign_listener", return_value=False),
patch.object(wrap_mod, "_find_available_port", side_effect=RuntimeError("no port")),
patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),
):
runner.invoke(main, ["wrap", "zcode", "--port", "8787"])
assert captured["port"] == 8787
assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"
def test_wrap_zcode_reuses_running_headroom_proxy_port(
runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A Headroom proxy already on the port is reused; no other port is searched for."""
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
captured: dict[str, object] = {}
home = _zcode_config_with(tmp_path, "http://127.0.0.1:8787")
with (
patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),
patch.object(wrap_mod, "_check_proxy", return_value=True),
patch.object(wrap_mod, "_foreign_listener", return_value=False),
patch.object(wrap_mod, "_find_available_port") as find_port,
patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),
):
runner.invoke(main, ["wrap", "zcode", "--port", "8787"])
find_port.assert_not_called()
assert captured["port"] == 8787
assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"