Files
headroom/tests/test_proxy_uds.py
Ayush Kumar Jha e7b3baf236 feat(proxy): serve on a Unix domain socket (--uds) (#3151)
## 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 head 73f77da2, 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 -->
2026-10-05 15:28:41 -05:00

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()