mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description `headroom proxy --uds PATH` binds an AF_UNIX socket instead of a TCP port. Request handling is untouched; this is the transport only. Reasons to prefer it over a loopback port: there's no port to collide with, nothing listens on the network, and filesystem permissions govern access. Containers and systemd units can share a socket through a bind mount or a runtime directory without publishing a port. Path handling refuses more than it deletes: - It clears a stale socket left by a crashed proxy. - It refuses to start when something is still listening on the path, since two proxies would split traffic. - It refuses a path that exists as a non-socket, which is far more likely a mistyped argument pointing at real data than a leftover. - It refuses a path longer than `sun_path` (108 bytes on Linux, 104 on macOS/BSD). Otherwise that fails inside `bind()` with an error that names nothing. - Missing parent directories are created `0700`. An existing parent's mode is never changed, and a world-writable, non-sticky parent is refused. - On Windows `--uds` is rejected with a clear error. This PR started as a route to Claude Code Remote Control through Headroom (#1779). That route was field-tested on Linux and does not work. `ANTHROPIC_UNIX_SOCKET` passes Remote Control's host check, but Claude Code then classifies the session as API-key auth, which fails Remote Control's separate subscription-auth requirement. The troubleshooting docs record that negative result, and this PR no longer claims to fix #1779. Devin's review of this head found two real defects and a few smaller points; they're listed under "Not tested" below. @Mearman's #3959 fixes all of them on top of this branch: it is stacked here and carries these three commits unchanged. #3960 is their standalone alternative. Maintainers can merge this and then #3959's nine commits, or take #3959 directly. Refs #1779 ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `headroom/proxy/uds.py` (new): - `prepare_uds_path()`: stale-socket cleanup; refusal of a live listener, a non-socket path or an over-long path; `0700` for directories it creates; refusal of an unsafe existing parent - `remove_uds_path()` - the `sun_path` limits and the Windows guard - `socket_usage_lines()`, used by both banners - `headroom/cli/proxy.py`: the `--uds PATH` option (env `HEADROOM_UDS`) and the socket banner. - `headroom/proxy/server.py`: `run_server` prepares the path, passes it to uvicorn, and removes the socket when it exits. The legacy `python -m headroom.proxy.server` banner uses the same usage lines. - `headroom/proxy/models.py`: the `uds` setting on `ProxyConfig`. - `headroom/settings_store.py`: registers `HEADROOM_UDS`. - `docs/content/docs/proxy.mdx`: a "Serving on a Unix socket" section. `docs/content/docs/troubleshooting.mdx` gets the Remote Control finding. - `tests/test_proxy_uds.py`: 24 tests covering path preparation, parent-mode handling, `sun_path` limits, the Windows guard, the banners, and the stale-socket and live-listener cases against real AF_UNIX sockets. ## 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 # This head (73f77da2) in a python:3.11-slim container, with the Rust core from the # headroom-ai 0.36.0 Linux wheel (the branch's version): == PR #3151 head73f77da2, Python 3.11.17, Linux $ pytest tests/test_proxy_uds.py tests/test_proxy_settings_endpoints.py -q ======================== 52 passed, 1 warning in 5.17s ========================= # Same head, the files this PR touches: $ ruff check <files> && ruff format --check <files> # ruff 0.16.8 All checks passed! 6 files already formatted $ mypy headroom/proxy/uds.py headroom/cli/proxy.py headroom/proxy/server.py headroom/proxy/models.py headroom/settings_store.py --ignore-missing-imports --follow-imports=silent --platform linux # mypy 1.19.1 Success: no issues found in 5 source files ``` ## Real Behavior Proof - Environment: Linux (Docker `python:3.11-slim` on a WSL2 kernel), Python 3.11.17, this PR's head `73f77da2`, isolated `HEADROOM_WORKSPACE_DIR`, no provider credentials. - Exact command / steps: `headroom proxy --uds /tmp/hr-uds/run/proxy.sock` with neither parent directory existing. I queried it over the socket with httpx's UDS transport, checked the listening TCP ports in `/proc/net/tcp*`, started a second proxy on the same path, then stopped the first with Ctrl+C. Finally I started it again and stopped it with SIGTERM. - Observed result: the proxy serves over the socket, creates owner-only parents, binds no TCP port, refuses a second proxy, and cleans up on Ctrl+C. SIGTERM leaves the socket file behind (see "Not tested"): ```text GET /health over the socket -> {'service': 'headroom-proxy', 'status': 'healthy', 'ready': True} socket is a unix socket: True | run/ mode: 0o700 | hr-uds/ mode: 0o700 TCP ports in LISTEN inside the container: none second proxy on the same path -> exit 1 | ['headroom.proxy.uds.UdsError: Another process is already listening on /tmp/hr-uds/run/proxy.sock. Stop it, or choose a different --uds path.'] after Ctrl+C (SIGINT): exit 0 | socket file still present: False after SIGTERM (systemd/docker stop): exit -15 | socket file still present: True ``` - Not tested: macOS live, Windows live (`--uds` is refused there; covered by a unit test), real provider traffic over the socket, and `--workers` greater than 1. Known limitations at this head, all fixed in #3959: - SIGTERM leaves the socket file, because uvicorn re-raises the signal before `run_server`'s cleanup runs. A restart clears the stale socket. - A stored `HEADROOM_UDS` overrides `--port`, and `headroom wrap` passes it to the TCP proxy it starts. - uvicorn creates the socket `0666`. That's harmless under a `0700` parent, but reachable by every local user if placed directly in `/tmp`. ## Runtime Rollout Safety - Rollout-managed feature(s): none; `--uds` is an opt-in CLI flag - Minimum rollout channel: n/a - Stable/default behavior changed: no. Without `--uds` (or `HEADROOM_UDS`) the proxy binds TCP exactly as before. - Kill switch / disable path: don't pass `--uds` and don't set `HEADROOM_UDS` - Unsafe override required: no - Qualification impact: none for the default TCP path - Rollback path: revert this PR; no stored state or format changes ## 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 did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes - This replaces the earlier description, which had been saved with literal backslash-n sequences instead of newlines and was cut off mid-sentence, so the template check could not read it. - The "Not tested" limitations are deliberate disclosure rather than open questions: #3959 has the fixes and tests for each. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3151" 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 -->
398 lines
13 KiB
Python
398 lines
13 KiB
Python
"""Tests for serving the proxy on a Unix domain socket (`headroom proxy --uds`).
|
|
|
|
The socket transport is a plain alternative to a TCP port — see
|
|
`headroom/proxy/uds.py` for the rationale and for why it does not restore
|
|
Claude Code's Remote Control (GH #1779).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import socket
|
|
import stat
|
|
from pathlib import Path
|
|
from unittest.mock import patch
|
|
|
|
import pytest
|
|
from click.testing import CliRunner
|
|
|
|
from headroom.cli.proxy import proxy as proxy_cmd
|
|
from headroom.proxy.uds import (
|
|
UDS_SUPPORTED,
|
|
UdsError,
|
|
_missing_ancestors,
|
|
_require_safe_existing_parent,
|
|
max_uds_path_length,
|
|
prepare_uds_path,
|
|
remove_uds_path,
|
|
require_uds_support,
|
|
socket_usage_lines,
|
|
)
|
|
|
|
requires_uds = pytest.mark.skipif(
|
|
not UDS_SUPPORTED, reason="platform has no socket.AF_UNIX (Windows)"
|
|
)
|
|
|
|
try: # `headroom.proxy.server` pulls in the compiled Rust core.
|
|
import headroom._core # noqa: F401
|
|
|
|
_CORE_BUILT = True
|
|
except ImportError: # pragma: no cover - depends on the local build
|
|
_CORE_BUILT = False
|
|
|
|
requires_core = pytest.mark.skipif(
|
|
not _CORE_BUILT, reason="headroom._core is not built in this environment"
|
|
)
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# Platform capability — runs everywhere, since the platform is a parameter.
|
|
# --------------------------------------------------------------------------
|
|
|
|
|
|
def test_require_uds_support_rejects_windows() -> None:
|
|
"""Windows has neither socket.AF_UNIX nor an asyncio UDS transport."""
|
|
with pytest.raises(UdsError, match="unavailable on this platform"):
|
|
require_uds_support(platform="win32")
|
|
|
|
|
|
def test_require_uds_support_accepts_posix() -> None:
|
|
if not UDS_SUPPORTED:
|
|
pytest.skip("AF_UNIX missing; the platform argument cannot override that")
|
|
require_uds_support(platform="linux")
|
|
|
|
|
|
def test_sun_path_limit_is_platform_specific() -> None:
|
|
"""Linux allows 108 bytes, the BSDs and macOS 104. Guessing high truncates."""
|
|
assert max_uds_path_length("linux") == 108
|
|
assert max_uds_path_length("darwin") == 104
|
|
|
|
|
|
def test_cli_rejects_uds_on_windows() -> None:
|
|
"""The CLI fails fast with a readable error, not a bind-time OSError."""
|
|
with patch("headroom.proxy.uds.UDS_SUPPORTED", False):
|
|
result = CliRunner().invoke(proxy_cmd, ["--uds", "/tmp/headroom-test.sock"])
|
|
|
|
assert result.exit_code != 0
|
|
assert "Unix domain sockets" in result.output
|
|
assert "--port instead" in result.output
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# Parent-directory policy — pure logic, so it runs on every platform.
|
|
# --------------------------------------------------------------------------
|
|
|
|
|
|
def test_missing_ancestors_lists_only_absent_levels(tmp_path: Path) -> None:
|
|
"""Only these get chmod 0700; anything already on disk is left alone."""
|
|
existing = tmp_path / "existing"
|
|
existing.mkdir()
|
|
|
|
missing = _missing_ancestors(existing / "a" / "b")
|
|
|
|
assert missing == [existing / "a", existing / "a" / "b"]
|
|
|
|
|
|
def test_missing_ancestors_is_empty_for_an_existing_dir(tmp_path: Path) -> None:
|
|
assert _missing_ancestors(tmp_path) == []
|
|
|
|
|
|
class _FakeStat:
|
|
def __init__(self, mode: int) -> None:
|
|
self.st_mode = mode
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
("mode", "accepted"),
|
|
[
|
|
(0o700, True), # owner only
|
|
(0o750, True), # group may read/traverse, not write
|
|
(0o755, True), # the common shared-parent case
|
|
(0o770, False), # any group member could swap the socket
|
|
(0o777, False), # any local user could
|
|
(0o1777, True), # /tmp: sticky, so others cannot unlink ours
|
|
(0o1770, True), # sticky group-writable
|
|
],
|
|
)
|
|
def test_existing_parent_accepted_only_when_others_cannot_swap_the_socket(
|
|
tmp_path: Path, mode: int, accepted: bool
|
|
) -> None:
|
|
"""Windows chmod is a no-op, so the mode is injected rather than applied."""
|
|
with patch.object(Path, "stat", return_value=_FakeStat(stat.S_IFDIR | mode)):
|
|
if accepted:
|
|
_require_safe_existing_parent(tmp_path)
|
|
else:
|
|
with pytest.raises(UdsError, match="writable by other users"):
|
|
_require_safe_existing_parent(tmp_path)
|
|
|
|
|
|
def test_unreadable_existing_parent_defers_to_bind(tmp_path: Path) -> None:
|
|
"""A stat we cannot perform is not evidence of a problem; let bind() rule."""
|
|
with patch.object(Path, "stat", side_effect=PermissionError):
|
|
_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.
|
|
# --------------------------------------------------------------------------
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_creates_parent_owner_only(tmp_path: Path) -> None:
|
|
"""The directory mode is the access-control boundary for the socket."""
|
|
target = tmp_path / "run" / "headroom.sock"
|
|
|
|
resolved = prepare_uds_path(target)
|
|
|
|
assert resolved == target
|
|
assert target.parent.is_dir()
|
|
assert stat.S_IMODE(target.parent.stat().st_mode) == 0o700
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_preserves_an_existing_parents_mode(tmp_path: Path) -> None:
|
|
"""A caller-owned directory must not be silently tightened to 0700.
|
|
|
|
Regression test: `--uds /run/shared/hr.sock` where `/run/shared` is a
|
|
directory someone else set up at 0755 would have locked out every other
|
|
user of that directory.
|
|
"""
|
|
parent = tmp_path / "shared"
|
|
parent.mkdir()
|
|
parent.chmod(0o755)
|
|
bystander = parent / "someone-elses.txt"
|
|
bystander.write_text("theirs", encoding="utf-8")
|
|
|
|
prepare_uds_path(parent / "headroom.sock")
|
|
|
|
assert stat.S_IMODE(parent.stat().st_mode) == 0o755
|
|
assert bystander.read_text(encoding="utf-8") == "theirs"
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_only_chmods_directories_it_creates(tmp_path: Path) -> None:
|
|
"""The 0700 applies to the new levels, not to the existing root above them."""
|
|
root = tmp_path / "existing"
|
|
root.mkdir()
|
|
root.chmod(0o755)
|
|
|
|
prepare_uds_path(root / "a" / "b" / "headroom.sock")
|
|
|
|
assert stat.S_IMODE(root.stat().st_mode) == 0o755
|
|
assert stat.S_IMODE((root / "a").stat().st_mode) == 0o700
|
|
assert stat.S_IMODE((root / "a" / "b").stat().st_mode) == 0o700
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_refuses_a_world_writable_existing_parent(tmp_path: Path) -> None:
|
|
"""Without the sticky bit, any local user could swap the socket out."""
|
|
parent = tmp_path / "open"
|
|
parent.mkdir()
|
|
parent.chmod(0o777)
|
|
|
|
with pytest.raises(UdsError, match="writable by other users"):
|
|
prepare_uds_path(parent / "headroom.sock")
|
|
|
|
assert stat.S_IMODE(parent.stat().st_mode) == 0o777, "the refusal must not mutate"
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_accepts_a_sticky_world_writable_parent(tmp_path: Path) -> None:
|
|
"""`/tmp` is 1777: others can add entries but cannot unlink ours."""
|
|
parent = tmp_path / "sticky"
|
|
parent.mkdir()
|
|
parent.chmod(0o1777)
|
|
|
|
resolved = prepare_uds_path(parent / "headroom.sock")
|
|
|
|
assert resolved.parent == parent
|
|
assert stat.S_IMODE(parent.stat().st_mode) == 0o1777
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_clears_a_stale_socket(tmp_path: Path) -> None:
|
|
"""A crashed proxy leaves an inode behind; a restart must not trip on it."""
|
|
target = tmp_path / "stale.sock"
|
|
dead = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
dead.bind(str(target))
|
|
dead.close() # closing without unlinking is exactly the crash case
|
|
assert target.exists()
|
|
|
|
prepare_uds_path(target)
|
|
|
|
assert not target.exists()
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_refuses_a_live_socket(tmp_path: Path) -> None:
|
|
"""Two proxies on one socket would silently steal each other's traffic."""
|
|
target = tmp_path / "live.sock"
|
|
live = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
live.bind(str(target))
|
|
live.listen(1)
|
|
try:
|
|
with pytest.raises(UdsError, match="already listening"):
|
|
prepare_uds_path(target)
|
|
assert target.exists(), "the live socket must survive the refusal"
|
|
finally:
|
|
live.close()
|
|
target.unlink(missing_ok=True)
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_never_deletes_a_regular_file(tmp_path: Path) -> None:
|
|
"""A typo'd --uds pointing at real data must not destroy it."""
|
|
target = tmp_path / "notes.txt"
|
|
target.write_text("important", encoding="utf-8")
|
|
|
|
with pytest.raises(UdsError, match="is not a socket"):
|
|
prepare_uds_path(target)
|
|
|
|
assert target.read_text(encoding="utf-8") == "important"
|
|
|
|
|
|
@requires_uds
|
|
def test_prepare_rejects_an_oversized_path(tmp_path: Path) -> None:
|
|
"""Past sun_path, bind() fails with an ENAMETOOLONG that names nothing."""
|
|
target = tmp_path / ("d" * 120) / "headroom.sock"
|
|
|
|
with pytest.raises(UdsError, match="sun_path limit"):
|
|
prepare_uds_path(target)
|
|
|
|
|
|
@requires_uds
|
|
def test_remove_uds_path_is_socket_only(tmp_path: Path) -> None:
|
|
"""Cleanup runs in a finally block, so it must be narrow and never raise."""
|
|
sock_path = tmp_path / "gone.sock"
|
|
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
sock.bind(str(sock_path))
|
|
sock.close()
|
|
regular = tmp_path / "keep.txt"
|
|
regular.write_text("keep", encoding="utf-8")
|
|
|
|
remove_uds_path(sock_path)
|
|
remove_uds_path(regular)
|
|
remove_uds_path(tmp_path / "does-not-exist.sock")
|
|
|
|
assert not sock_path.exists()
|
|
assert regular.exists()
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# Server wiring — uvicorn is mocked, so this runs on every platform.
|
|
# --------------------------------------------------------------------------
|
|
|
|
|
|
def _bind_kwargs_for(**config_kwargs: object) -> dict[str, object]:
|
|
"""Run run_server far enough to capture what it would bind to."""
|
|
from headroom.proxy.server import ProxyConfig, run_server
|
|
|
|
captured: dict[str, object] = {}
|
|
|
|
def fake_run_uvicorn( # noqa: ANN202
|
|
app_target, # noqa: ANN001
|
|
bind_kwargs, # noqa: ANN001
|
|
workers, # noqa: ANN001
|
|
limit_concurrency, # noqa: ANN001
|
|
log_level, # noqa: ANN001
|
|
uvicorn_kwargs, # noqa: ANN001
|
|
):
|
|
captured.update(bind_kwargs)
|
|
|
|
with (
|
|
patch("headroom.proxy.server._run_uvicorn", side_effect=fake_run_uvicorn),
|
|
patch("headroom.proxy.server.create_app"),
|
|
):
|
|
run_server(ProxyConfig(**config_kwargs), print_banner=False) # type: ignore[arg-type]
|
|
|
|
return captured
|
|
|
|
|
|
@requires_core
|
|
def test_run_server_binds_host_and_port_by_default() -> None:
|
|
bind = _bind_kwargs_for(host="127.0.0.1", port=9123)
|
|
|
|
assert bind == {"host": "127.0.0.1", "port": 9123}
|
|
|
|
|
|
@requires_uds
|
|
@requires_core
|
|
def test_run_server_binds_the_socket_instead_of_a_port(tmp_path: Path) -> None:
|
|
"""uvicorn treats uds and host/port as alternatives; passing both is an error."""
|
|
target = tmp_path / "headroom.sock"
|
|
|
|
bind = _bind_kwargs_for(host="127.0.0.1", port=9123, uds=str(target))
|
|
|
|
assert bind == {"uds": str(target)}
|
|
assert "host" not in bind and "port" not in bind
|
|
|
|
|
|
@requires_uds
|
|
@requires_core
|
|
def test_run_server_removes_the_socket_on_exit(tmp_path: Path) -> None:
|
|
"""A crash inside uvicorn must not leave an inode that blocks the restart."""
|
|
from headroom.proxy.server import ProxyConfig, run_server
|
|
|
|
target = tmp_path / "headroom.sock"
|
|
|
|
def bind_then_fail( # noqa: ANN202
|
|
app_target, # noqa: ANN001
|
|
bind_kwargs, # noqa: ANN001
|
|
workers, # noqa: ANN001
|
|
limit_concurrency, # noqa: ANN001
|
|
log_level, # noqa: ANN001
|
|
uvicorn_kwargs, # noqa: ANN001
|
|
):
|
|
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
sock.bind(bind_kwargs["uds"])
|
|
sock.close()
|
|
raise KeyboardInterrupt
|
|
|
|
with (
|
|
patch("headroom.proxy.server._run_uvicorn", side_effect=bind_then_fail),
|
|
patch("headroom.proxy.server.create_app"),
|
|
pytest.raises(KeyboardInterrupt),
|
|
):
|
|
run_server(ProxyConfig(uds=str(target)), print_banner=False)
|
|
|
|
assert not target.exists()
|