fix(wrap): reject saved bob gateway URLs the proxy would not route (#3975)

## Description

Follow-up to #3801, promised on its Devin threads ([path
shape](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286291),
[invalid
port](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286403)).
Both findings landed after that PR was approved, so they ship here
rather than resetting its review.

`bob_preflight` guards against a saved `~/.bob/settings/settings.json`
`gatewayUrl`, which bobshell resolves over `BOB_GATEWAY_URL` at startup.
It compared only scheme/host/port, so two classes of saved URL got
through or crashed it:

- A proxy URL with an extra path segment, query or fragment
(`http://127.0.0.1:8787/p/work/v1`, `…/p/work?team=a`) passed. Bob then
appended `/inference/v1/...` to it; `split_project_path` strips only one
`/p/<project>` segment, so the request arrived as `/v1/inference/v1/...`
and matched nothing. The wrap launched and Bob failed.
- A non-numeric port (`http://127.0.0.1:not-a-port`) made
`urlsplit(...).port` raise outside the parse `try`, so the user got a
traceback instead of the guidance.

Two helpers now answer the two questions separately: `_origin` gives
(scheme, host, port) or None for an unparsable value;
`_routable_proxy_path` is true only for a bare origin or exactly one
`/p/<project>` prefix (reusing `split_project_path`, the router's own
grammar), checked on the **decoded** path the ASGI server hands the
router (so `%2F` in the project segment counts as the extra segment it
becomes, while the `%20` that `with_project_prefix` itself emits is
fine) and with no `?`/`#` anywhere, even bare, since Bob appends to the
string. The abort message names the real problem: "could not be parsed"
/ "is not a URL the proxy can route" when it points at the proxy with a
bad shape / "would bypass the Headroom proxy" for any foreign host,
regardless of its path. A trailing slash remains accepted: bobshell's
`AJ()` collapses repeated slashes and strips a trailing one before
appending paths (verified in 2.0.5).

Closes # (no issue; follow-up to #3801)

## 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/wrap_registry.py`: `_origin_key` → `_origin` +
`_routable_proxy_path`; `bob_preflight` passes only when the saved
origin equals the proxy's and the path is routable, and picks the
message by cause. `split_project_path` is imported from
`headroom.proxy.project_context` alongside the existing
`with_project_prefix`.
- `tests/test_cli/test_wrap_bob.py`:
`TestBobPreflight::test_fails_on_non_proxy_shapes` (12 rejected shapes,
each asserting its reason: bypass / unroutable / unparsable) and
`test_unparsable_env_url_never_matches` (two `None` identities must not
compare equal). Passing cases now also cover `/p/my%20proj` and
`HTTP://LOCALHOST:8787/`.

## 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
$ PYTHONPATH=$PWD python -m pytest -q -p no:cacheprovider tests/test_cli/
981 passed, 1 skipped, 17 warnings in 19.79s

$ git stash push headroom/   # previous head's wrap_registry, new tests
$ pytest tests/test_cli/test_wrap_bob.py -k "non_proxy_shapes or unparsable_env"
5 failed, 3 passed   # the two cases already rejected by #3801 plus one message-only case pass; all new shapes fail

$ uvx ruff@0.16.8 check headroom/providers/wrap_registry.py tests/test_cli/test_wrap_bob.py
All checks passed!
$ uvx ruff@0.16.8 format --check ...
2 files already formatted
$ uvx mypy==1.20.2 headroom --ignore-missing-imports
Success: no issues found in 556 source files
```

## Real Behavior Proof

- Environment: macOS, bobshell 2.0.5, isolated `HOME` whose
`.bob/settings/settings.json` holds
`{"gatewayUrl":"http://127.0.0.1:8788/p/work/v1"}`; proxy code from each
head via `PYTHONPATH`.
- Exact command / steps: `HOME=<fakehome> PYTHONPATH=<checkout> python
-m headroom.cli wrap bob --port 8788 -- --version`, once on
`upstream/main` (`befdb52f`, contains #3801) and once on this branch.
- Observed result: main launched Bob; this branch aborted before the
spawn. Details:
- main: `Launching BOB (API routed through Headroom)...
BOB_GATEWAY_URL=http://127.0.0.1:8788/p/scratchpad` then Bob prints
`2.0.5` — the guard passed and Bob would have used the saved
`/p/work/v1` URL.
- this branch: `Error: Bob's saved gatewayUrl
(http://127.0.0.1:8788/p/work/v1) is not a URL the proxy can route (use
the bare proxy origin, optionally with one /p/<project> prefix). Remove
the gatewayUrl entry from <fakehome>/.bob/settings/settings.json ...` —
Bob never spawned.
- Not tested: a full Bob inference round trip (this change only alters
the pre-launch guard; the account's IBM plan is suspended, see #3801).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only `headroom wrap bob` on a machine
whose saved Bob `gatewayUrl` points at the proxy with an extra
path/query/fragment, or is unparsable. Those launches used to proceed
(and then fail inside Bob) or crash with a traceback; they now abort
with guidance.
- Kill switch / disable path: remove `gatewayUrl` from Bob's settings
(the message says so); no other wrap target has a preflight.
- Unsafe override required: no
- Qualification impact: none
- 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
- [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

- Documentation: n/a, the guard's behavior is explained by its own error
message.
- Self-review found and fixed, beyond the two Devin findings:
query/fragment acceptance, scheme-less/host-less URLs comparing equal to
an unparsable env URL, and the "bypass" wording being wrong for
proxy-pointing URLs.
- Deliberately unchanged: `localhost`→`127.0.0.1` normalization does not
cover `[::1]`/`0.0.0.0` (pre-existing; `with_project_prefix` only ever
emits `127.0.0.1`).

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3975"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
trs-80
2026-10-07 20:56:28 -05:00
committed by GitHub
co-authored by Claude Fable 5.1 JD Davis
parent d8294a4ed1
commit 944eafc6d4
2 changed files with 88 additions and 18 deletions
+55 -15
View File
@@ -20,11 +20,11 @@ from collections.abc import Callable, Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Literal
from urllib.parse import urlsplit
from urllib.parse import unquote, urlsplit
from headroom.providers.claude import proxy_base_url as claude_proxy_base_url
from headroom.providers.codex import proxy_base_url as codex_proxy_base_url
from headroom.proxy.project_context import with_project_prefix
from headroom.proxy.project_context import split_project_path, with_project_prefix
# How an EnvVar's URL is shaped: ``openai_v1`` ends in ``/v1`` (OpenAI-style
# clients append ``/chat/completions``); ``anthropic`` is a bare origin
@@ -114,10 +114,39 @@ def build_launch_env(
return env, display
def _origin_key(url: str) -> tuple[str, str, int | None]:
parts = urlsplit(url.strip())
host = (parts.hostname or "").lower()
return parts.scheme, "127.0.0.1" if host == "localhost" else host, parts.port
def _origin(url: str) -> tuple[str, str, int | None] | None:
"""(scheme, host, port) of ``url``; None when it cannot be an HTTP origin.
None for an unparsable URL (a non-numeric port makes ``urlsplit(...).port``
raise) or a missing scheme or host.
"""
try:
parts = urlsplit(url)
port = parts.port
except ValueError:
return None
if not parts.scheme or not parts.hostname:
return None
host = parts.hostname # urlsplit lowercases it
return parts.scheme, "127.0.0.1" if host == "localhost" else host, port
def _routable_proxy_path(url: str) -> bool:
"""True when Bob's gateway paths appended to ``url`` reach the proxy router.
Only a bare origin or one ``/p/<project>`` prefix qualifies; anything else
leaves Bob's paths under a prefix the router never sees. A ``?`` or ``#``
anywhere fails, even bare: Bob appends to the string, so the paths would
land in the query or fragment. The path is checked decoded, as the ASGI
server hands it to the router, so an encoded slash in the project segment
is the extra segment it becomes, while the ``%20`` that
``with_project_prefix`` itself emits is fine. A trailing slash is fine too:
bobshell's ``AJ()`` (verified in 2.0.5) collapses repeated slashes and
strips a trailing one before appending.
"""
if "?" in url or "#" in url:
return False
return split_project_path(unquote(urlsplit(url).path))[1] in ("", "/")
def bob_preflight(env: Mapping[str, str], settings_path: Path | None = None) -> str | None:
@@ -136,16 +165,27 @@ def bob_preflight(env: Mapping[str, str], settings_path: Path | None = None) ->
return None
if not isinstance(saved, str) or not saved.strip():
return None
# Same proxy if scheme, host and port agree; a different /p/<project>
# prefix only changes attribution, and the error below tells users to
# point gatewayUrl at the proxy, so that must not then be rejected.
if _origin_key(saved) == _origin_key(env.get("BOB_GATEWAY_URL", "")):
return None
saved = saved.strip()
saved_origin = _origin(saved)
proxy_origin = _origin(env.get("BOB_GATEWAY_URL", ""))
if saved_origin is None:
reason = "could not be parsed as an HTTP origin"
elif proxy_origin is not None and saved_origin == proxy_origin:
# Same proxy. A different /p/<project> prefix only changes attribution,
# and the message below tells users to point gatewayUrl at the proxy,
# so that must not then be rejected; an extra path segment must be.
if _routable_proxy_path(saved):
return None
reason = (
"is not a URL the proxy can route (use the bare proxy origin, optionally "
"with one /p/<project> prefix, and no query or fragment)"
)
else:
reason = "overrides BOB_GATEWAY_URL, so Bob would bypass the Headroom proxy"
return (
f"Bob's saved gatewayUrl ({saved.strip()}) overrides BOB_GATEWAY_URL, so Bob "
f"would bypass the Headroom proxy. Remove the gatewayUrl entry from {path} "
"(or set it to the proxy URL shown by this wrap) and retry. If your "
"organisation enforces a GatewayUrl policy, Bob cannot be wrapped."
f"Bob's saved gatewayUrl ({saved}) {reason}. Remove the gatewayUrl "
f"entry from {path} (or set it to the proxy URL shown by this wrap) and retry. "
"If your organisation enforces a GatewayUrl policy, Bob cannot be wrapped."
)
+33 -3
View File
@@ -162,6 +162,8 @@ class TestBobPreflight:
{"gatewayUrl": "http://127.0.0.1:8787/p/myproj/"}, # already the proxy
{"gatewayUrl": "http://127.0.0.1:8787/p/another-project"}, # attribution only
{"gatewayUrl": "http://localhost:8787"}, # same proxy, spelled differently
{"gatewayUrl": "HTTP://LOCALHOST:8787/"}, # case and trailing slash
{"gatewayUrl": "http://127.0.0.1:8787/p/my%20proj"}, # as with_project_prefix prints it
"not json",
],
)
@@ -171,9 +173,37 @@ class TestBobPreflight:
def test_passes_when_no_settings_file(self, tmp_path):
assert bob_preflight(self.ENV, tmp_path / "missing.json") is None
def test_fails_on_same_host_other_port(self, tmp_path):
path = self._settings(tmp_path, {"gatewayUrl": "http://127.0.0.1:9999"})
assert bob_preflight(self.ENV, path) is not None
BYPASS = "would bypass the Headroom proxy"
UNROUTABLE = "not a URL the proxy can route"
UNPARSABLE = "could not be parsed"
@pytest.mark.parametrize(
("gateway_url", "reason"),
[
("http://127.0.0.1:9999", BYPASS), # same host, other port
("https://api.eu-de.bob.ibm.com/inference", BYPASS), # foreign host with a path
("https://api.eu-de.bob.ibm.com/?r=1", BYPASS),
("http://127.0.0.1:8787/p/myproj/v1", UNROUTABLE), # extra segment
("http://127.0.0.1:8787/inference", UNROUTABLE), # path without the /p/ prefix
("http://127.0.0.1:8787/p/team%2Fwork", UNROUTABLE), # ASGI decodes into 2 segments
("http://127.0.0.1:8787/p/myproj?team=a", UNROUTABLE), # Bob appends after the query
("http://127.0.0.1:8787#frag", UNROUTABLE),
("http://127.0.0.1:8787/p/myproj?", UNROUTABLE), # bare delimiters parse as empty
("http://127.0.0.1:8787#", UNROUTABLE),
("http://127.0.0.1:not-a-port", UNPARSABLE), # urlsplit(...).port raises
("/", UNPARSABLE), # no scheme or host
],
)
def test_fails_on_non_proxy_shapes(self, tmp_path, gateway_url, reason):
path = self._settings(tmp_path, {"gatewayUrl": gateway_url})
message = bob_preflight(self.ENV, path)
assert message is not None and str(path) in message and reason in message
def test_unparsable_env_url_never_matches(self, tmp_path):
# Two None identities must not compare equal.
path = self._settings(tmp_path, {"gatewayUrl": "/"})
assert bob_preflight({"BOB_GATEWAY_URL": "http://127.0.0.1:bad"}, path) is not None
assert bob_preflight({}, path) is not None
def test_fails_on_foreign_gateway(self, tmp_path):
path = self._settings(tmp_path, {"gatewayUrl": "https://api.eu-de.bob.ibm.com"})