Commit Graph
1 Commits
Author SHA1 Message Date
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