fix(proxy): stop the --uds banner advertising a recipe that cannot work

Both startup banners printed an ANTHROPIC_UNIX_SOCKET=... claude line on a
socket bind. That configuration is the one this branch's own docs document as
broken: it satisfies Claude Code's api.anthropic.com host check but
reclassifies the session as API-key auth, so the session then fails to
authenticate. Runtime output was contradicting the docs and walking users into
the failure. Review feedback on #3151.

The socket branch of both banners now comes from uds.socket_usage_lines(), a
single agent-neutral block: the socket path, the transport requirement (the
client must speak HTTP over a Unix socket natively), a curl example, and a
link to the docs page that carries the per-client detail. The legacy banner's
hardcoded "Claude Code:" label is now computed alongside it, so the socket
bind no longer addresses one agent by name; both branches still render to the
same 70-column inner width.

Per-client wiring stays in the docs, where it can be qualified. Three tests
pin the contract: the unsupported recipe is absent, the replacement states the
requirement and links the docs, and no agent is named at all. They are pure
string assertions, so they run on every platform rather than only where
AF_UNIX exists.
This commit is contained in:
Ayushraj06-bit
2026-08-21 06:26:26 +05:30
parent a63919d83a
commit 73f77da262
4 changed files with 76 additions and 10 deletions
+5 -8
View File
@@ -1636,16 +1636,13 @@ Memory (Multi-Provider):
else:
tuning_section = ""
# A socket has no URL, and the client-side wiring for it is a different pair
# of env vars, so the banner's URL and Usage blocks both switch shape.
# A socket has no URL, and no per-agent recipe belongs here — see
# uds.socket_usage_lines() for why the banner stays transport-neutral.
if config.uds:
from headroom.proxy.uds import socket_usage_lines
listen_display = f"unix:{config.uds}"
usage_section = "\n".join(
(
f" Claude Code: ANTHROPIC_UNIX_SOCKET={config.uds} \\",
" ANTHROPIC_BASE_URL=http://api.anthropic.com claude",
)
)
usage_section = "\n".join(socket_usage_lines(config.uds))
else:
listen_display = f"http://{config.host}:{config.port}"
usage_section = "\n".join(
+5 -2
View File
@@ -5386,10 +5386,13 @@ def run_server(
api_targets = resolve_api_targets(config.provider_api_overrides)
if config.uds:
# No per-agent recipe on a socket bind; see uds.socket_usage_lines().
listen_display = f"unix:{config.uds}"
usage_display = f"ANTHROPIC_UNIX_SOCKET={config.uds} claude"
usage_label = "Client: "
usage_display = "must support HTTP over a Unix socket natively"
else:
listen_display = f"http://{config.host}:{config.port}"
usage_label = "Claude Code:"
usage_display = f"ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude"
if print_banner:
@@ -5420,7 +5423,7 @@ def run_server(
║ Conn Pool: {pool_info:<52}║
╠══════════════════════════════════════════════════════════════════════╣
║ USAGE: ║
║ Claude Code: {usage_display:<51}║
║ {usage_label} {usage_display:<51}║
║ Cursor: Set base URL in settings ║
╠══════════════════════════════════════════════════════════════════════╣
║ ENDPOINTS: ║
+25
View File
@@ -36,6 +36,7 @@ from pathlib import Path
__all__ = [
"UDS_SUPPORTED",
"UdsError",
"socket_usage_lines",
"max_uds_path_length",
"prepare_uds_path",
"remove_uds_path",
@@ -105,6 +106,30 @@ def _is_live_socket(path: Path) -> bool:
sock.close()
# Docs page carrying the client-compatibility detail the banner has no room for.
UDS_DOCS_URL = "https://headroom-docs.vercel.app/docs/proxy#serving-on-a-unix-socket"
def socket_usage_lines(path: str | os.PathLike[str]) -> tuple[str, ...]:
"""How the startup banner describes a socket bind, for every banner.
Deliberately names no agent and hands out no environment variables. An
earlier revision printed an ``ANTHROPIC_UNIX_SOCKET=... claude`` recipe here,
which is a configuration that does not work: it satisfies Claude Code's
``api.anthropic.com`` host check but reclassifies the session as API-key
auth, and the session then fails to authenticate. Printing it at startup
turned a known-negative result into first-party guidance. The rule this
encodes is that the banner states a transport requirement and points at the
docs; per-client wiring belongs in the docs, where it can be qualified.
"""
return (
f" Socket: {path}",
" Client: must support HTTP over a Unix socket natively",
f" Example: curl --unix-socket {path} http://localhost/health",
f" Details: {UDS_DOCS_URL}",
)
def _missing_ancestors(target: Path) -> list[Path]:
"""Directories along *target* that do not exist yet, shallowest first."""
missing: list[Path] = []
+41
View File
@@ -25,6 +25,7 @@ from headroom.proxy.uds import (
prepare_uds_path,
remove_uds_path,
require_uds_support,
socket_usage_lines,
)
requires_uds = pytest.mark.skipif(
@@ -130,6 +131,46 @@ def test_unreadable_existing_parent_defers_to_bind(tmp_path: Path) -> None:
_require_safe_existing_parent(tmp_path)
# --------------------------------------------------------------------------
# Startup banner — a socket bind must not advertise a broken recipe.
# --------------------------------------------------------------------------
def test_socket_usage_lines_omit_the_unsupported_claude_code_recipe() -> None:
"""Regression: the banner once printed a configuration that cannot work.
`ANTHROPIC_UNIX_SOCKET=... claude` passes Claude Code's api.anthropic.com
host check but reclassifies the session as API-key auth, and the session
then fails to authenticate. Printing it at startup turned a known-negative
field result into first-party runtime guidance.
"""
rendered = "\n".join(socket_usage_lines("/run/headroom/proxy.sock"))
assert "ANTHROPIC_UNIX_SOCKET" not in rendered
assert "ANTHROPIC_BASE_URL" not in rendered
assert "claude" not in rendered.lower()
def test_socket_usage_lines_state_the_transport_requirement() -> None:
"""What replaces the recipe has to be useful, not merely absent."""
path = "/run/headroom/proxy.sock"
rendered = "\n".join(socket_usage_lines(path))
assert path in rendered
assert "HTTP over a Unix socket" in rendered
assert "curl --unix-socket" in rendered
assert "serving-on-a-unix-socket" in rendered
def test_socket_usage_lines_name_no_agent() -> None:
"""Transport-neutral: the banner singles out no client."""
rendered = "\n".join(socket_usage_lines("/run/headroom/proxy.sock")).lower()
for agent in ("claude", "codex", "opencode", "cursor", "aider", "copilot"):
assert agent not in rendered, f"banner should not name {agent}"
# --------------------------------------------------------------------------
# Path preparation — needs a real AF_UNIX platform.
# --------------------------------------------------------------------------