mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
feat(wrap): add headroom wrap droid for Factory Droid (#4143)
## Description Add `headroom wrap droid` so Factory subscription traffic, including Droid Core, can be compressed on the existing Factory plan. Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper points that at the local proxy and gives the proxy a Factory upstream (`--factory-api-url` / `FACTORY_TARGET_API_URL`, default `https://api.factory.ai`). With a Factory upstream configured the proxy registers: - `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are stripped. Operator Anthropic extra headers are withheld from the untrusted Factory host. - Every other `/api/*` path — forwarded verbatim to Factory, except Hermes Studio's scoped prefixes and requests that name their own `x-headroom-base-url`. Nothing outside `/api/` is sent to Factory. `select_passthrough_base_url` and `upstream_trust` are untouched, so a leftover Codex, Claude, or Copilot config pointed at a Factory-mode proxy keeps its own upstream and credentials. That is the deliberate difference from https://github.com/headroomlabs-ai/headroom/pull/2352, which is still open and which this does not close. #2352 sends every unrouted request on a Factory-mode proxy to Factory. `wrap droid` writes no Droid config. It threads `factory_api_url` through the existing proxy-reuse logic. With `--no-proxy` it refuses unless `/health` shows a Headroom proxy serving the same Factory upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded uncompressed. Those routes are deferred. This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The only conflicts were `docs/content/docs/meta.json` (kept both the new `hermes` page and `droid`) and the `--no-proxy` branch in `headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the Factory check). Refs #2351 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [x] 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 wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy and resolves the Factory upstream from `--factory-api-url`, then `FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback, credential, query, and fragment URLs are rejected. - Factory inference and `/api/*` passthrough routes are registered only when a Factory upstream is configured. The default proxy is unchanged. - `/health` reports `factory_api_url`. - Docs: `docs/content/docs/droid.mdx`. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`, importing that tree via `PYTHONPATH` and the existing venv at `/home/hermes/workspace/headroom/.venv` (Python 3.11.16). ```text tests/test_cli/test_wrap_droid.py ............................ [ 31%] tests/test_provider_droid_runtime.py ................................ [ 66%] ``` 60 passed. Those are the wrap launch-env tests and the Factory runtime tests. `tests/test_proxy/test_factory_decoy_proof.py` did not complete in this worktree. The proxy refuses to start because `headroom._core` is not built here (`ModuleNotFoundError`, exit 78). Setting `HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The decoy proof (decoy upstream stays silent, Factory stand-in receives the inference request, spoofed `x-headroom-*` headers, REST passthrough, `--no-proxy` refusals) was written for this change and passed in the pre-rebase review session. It was not re-run to a green result after this rebase. `ruff` and `mypy` were not re-run after the rebase. ## Real Behavior Proof - Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top of `upstream/main` `8c1beb20`. No Factory token. No call to `api.factory.ai`. - Exact command / steps: `PYTHONPATH=/home/hermes/workspace/headroom-rebase /home/hermes/workspace/headroom/.venv/bin/python -m pytest tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py` - Observed result: 60 passed. - Not tested: a live Factory subscription, `droid` itself, the socket decoy proof on this rebased commit (blocked locally by the missing Rust extension), `ruff`, `mypy`, and CI on GitHub. ## Runtime Rollout Safety - Rollout-managed feature(s): none. Factory routes register only when `factory_api_url` / `--factory-api-url` is set. - Minimum rollout channel: stable. Default proxy behavior is unchanged. - Stable/default behavior changed: no, unless a Factory upstream is configured. - Kill switch / disable path: do not pass `--factory-api-url` and do not set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in. - Unsafe override required: no. - Qualification impact: none on the default proxy. - Rollback path: revert this commit. No config is written into Droid. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5 high review with an empty blocking list. This commit is that change rebased onto current main. The two conflict resolutions are described above and have not had a second Opus pass. ## 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 - [ ] 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 Does not close #2352. That PR is the prior attempt. This one is a current-main rebuild with the catch-all leak removed: only `/api/*` is forwarded to Factory. akbarkanso is not a Headroom maintainer. Please do not expect this account to merge. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143" 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 --> ### Maintainer current-main requalification Exact head `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. Updated against upstream/maine4a60ed7. Resolved the OpenAI passthrough overlap by retaining main's prepared-request/model/timing parameters and soft-passthrough guard alongside the contributor's verbatim flag; generic compression requires both guards to permit it. Re-reviewed Factory direct-routing/verbatim semantics and existing discussion. All 93 wrapper/runtime/Factory passthrough/socket-decoy tests pass with existing native extension; changed-file Ruff lint/format and whitespace checks pass. No contributor routing policy was rewritten. Independently reran the official Droid1.3.0 CLI with isolated home, dummy API key, actual Headroom/Uvicorn proxy and controlled LAN HTTP upstream on this exact combined head. The CLI consumed the controlled Anthropic SSE reply and exited zero with HEADROOM_QUALIFICATION_OK. The message request preserved dummy Authorization and forwarded no x-headroom headers. This is controlled transport/runtime qualification, not a live Factory subscription or savings benchmark, and not a fresh native build. Applied shared test-only Gemini fixture repair for independently established main failures; all ten cases pass. Formal approval awaits exact-head hosted qualification. Exact-head hosted checks are being handled by maintainers. No new finding in the reviewed scope; formal approval awaits exact-head hosted qualification; nothing merged. ### Maintainer current-main requalification Exact head `7dd0725a9ac4dd8103dedf78552ceca886fc3620`, upstream main `c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`. Clean mechanical merge with upstream mainc01cf07d94. Re-reviewed current Factory/Droid routing and author/Devin discussion. Factory inference retains force_direct to bypass translating backends; Factory passthrough retains verbatim alongside main's soft-passthrough/prepared-request guards. Hermes scoped proxy prefixes remain excluded from Factory dispatch; the existing standalone environment precedence is intentionally consistent with sibling targets, while Click/wrap retain flag precedence. No contributor routing policy rewritten. Fresh wrapper/runtime/Factory passthrough/socket-decoy/Hermes verification: 100 passed, with test-client/runpy warnings only. All 14 changed Python files pass Ruff lint/format; main-relative whitespace clean and owned tree clean. Tests use the current-main native DLL for local startup. Earlier official Droid 1.3.0 controlled-upstream runtime proof remains scoped to its original run; no fresh official CLI replay, Factory subscription inference, savings benchmark or branch-native build is claimed. No new blocker found; approval awaits exact-head hosted checks. Nothing merged. Exact-head hosted checks are being handled by maintainers. No new finding in the reviewed scope; formal approval awaits exact-head hosted qualification; nothing merged. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
JerrettDavis
parent
602ca65126
commit
bb8d18a56a
@@ -87,7 +87,7 @@ Zero code changes. [Agent compatibility](#agent-compatibility) ·
|
||||
|
||||
- **Library** — `compress(messages)` in Python or TypeScript, inline in any app.
|
||||
- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language.
|
||||
- **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode` in one command; undo with `headroom unwrap <tool>`.
|
||||
- **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|droid|zcode` in one command; undo with `headroom unwrap <tool>`.
|
||||
- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client.
|
||||
- **Cross-agent memory** — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
|
||||
- **`headroom learn`** — mines failed sessions and writes corrections to `CLAUDE.local.md` (default, gitignored), `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `GROK.md`.
|
||||
@@ -292,6 +292,7 @@ Saved** card then reads `measured` rather than `estimated`, with the band.
|
||||
| OpenHands | ✅ | starts proxy + launches |
|
||||
| Mistral Vibe | ✅ | starts proxy + launches |
|
||||
| Oh My Pi | ✅ | Anthropic + OpenAI/Codex · injects config · starts proxy + launches |
|
||||
| Factory Droid | ✅ | routes via `FACTORY_API_BASE_URL`; Anthropic-model turns compressed, other Factory traffic passed through |
|
||||
| Cortex Code | Library only | 60–65% savings in library mode; no `wrap` |
|
||||
| Kimi CLI | ✅ | OAuth bearer forwarded — log in once |
|
||||
| ZCode | ✅ | starts the proxy and prints base URLs for ZCode settings |
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Factory Droid
|
||||
description: Route Factory Droid through Headroom so Anthropic-model turns are compressed on your existing Factory subscription.
|
||||
---
|
||||
|
||||
Use `headroom wrap droid` to run [Factory Droid](https://docs.factory.ai) through the local Headroom proxy. Droid keeps talking to Factory with its own login; Headroom sits in between and compresses the Anthropic-shaped inference requests.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
headroom wrap droid
|
||||
```
|
||||
|
||||
Pass Droid arguments after `--`:
|
||||
|
||||
```bash
|
||||
headroom wrap droid -- exec "fix the failing test"
|
||||
```
|
||||
|
||||
There is nothing to undo. The wrapper writes no Droid config and no `customModels`; it only sets an environment variable on the `droid` process it launches.
|
||||
|
||||
## What `wrap droid` Does
|
||||
|
||||
| Step | What happens |
|
||||
|---|---|
|
||||
| Upstream | Resolves the real Factory upstream (see [Upstream precedence](#upstream-precedence)) |
|
||||
| Proxy | Starts or reuses a Headroom proxy started with `--factory-api-url <upstream>` |
|
||||
| Launch | Runs `droid` with `FACTORY_API_BASE_URL=http://127.0.0.1:<port>` |
|
||||
|
||||
If the requested port is busy, or a proxy with different routing is running there, the wrapper picks a free port and points `FACTORY_API_BASE_URL` at it. You do not need to pass `--port` yourself.
|
||||
|
||||
## What Is Compressed
|
||||
|
||||
| Path | Behaviour |
|
||||
|---|---|
|
||||
| `POST /api/llm/a/v1/messages` | Compressed with the same pipeline as `/v1/messages`, then forwarded to `<upstream>/api/llm/a/v1/messages` |
|
||||
| Any other `/api/*` path | Forwarded verbatim to the upstream (method, query string, headers and body unchanged) |
|
||||
| Anything outside `/api/` | Never sent to Factory; keeps the proxy's normal routing |
|
||||
|
||||
OpenAI-shaped traffic under `/api/llm/o/` is **not compressed yet**. It still reaches Factory, but is forwarded verbatim and buffered rather than streamed incrementally. Models Droid serves over that route see no savings.
|
||||
|
||||
A few `/api/*` requests keep the proxy's normal behaviour instead of going to Factory: requests that set `x-headroom-base-url`, and Hermes Studio's `/api/codex-proxy/` and `/api/claude-code-proxy/` paths.
|
||||
|
||||
On the compressed route, Headroom ignores a client-sent `x-headroom-base-url` and strips every `x-headroom-*` header before forwarding. Your Factory `Authorization` header is forwarded unchanged. Operator-configured Anthropic extra headers (`ANTHROPIC_TARGET_API_HEADERS`) are **not** sent to Factory.
|
||||
|
||||
## Upstream Precedence
|
||||
|
||||
1. `--factory-api-url <url>`
|
||||
2. An existing `FACTORY_API_BASE_URL` in your shell (for example an enterprise or regional gateway)
|
||||
3. `https://api.factory.ai`
|
||||
|
||||
The upstream must be an `http(s)` URL with no credentials, query string or fragment. Loopback hosts (`localhost`, `127.x`, `[::1]`) are rejected, which stops a leftover `FACTORY_API_BASE_URL` from an earlier wrapped session from pointing the proxy at itself. If you see that error, unset `FACTORY_API_BASE_URL` and run the command again.
|
||||
|
||||
## Using an Existing Proxy
|
||||
|
||||
With `--no-proxy`, the wrapper does not start a proxy. It refuses to launch Droid unless the port answers `/health` as a Headroom proxy that serves the same Factory upstream:
|
||||
|
||||
```bash
|
||||
headroom proxy --port 8787 --factory-api-url https://api.factory.ai
|
||||
headroom wrap droid --no-proxy --port 8787
|
||||
```
|
||||
|
||||
A non-Headroom listener, a proxy without Factory routing, or a proxy for a different Factory upstream is an error, so Droid's credentials never go to a listener that was not set up for them.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
|---|---|
|
||||
| `--port`, `-p` | Proxy port (default: `$HEADROOM_PORT`, else 8787) |
|
||||
| `--factory-api-url` | Real Factory upstream (default: `$FACTORY_API_BASE_URL`, else `https://api.factory.ai`) |
|
||||
| `--no-proxy` | Use an existing Factory-mode proxy instead of starting one |
|
||||
| `--learn` | Enable live traffic learning |
|
||||
| `--memory` | Enable persistent cross-session memory |
|
||||
@@ -47,6 +47,7 @@
|
||||
"opencode-deepseek",
|
||||
"grok-build",
|
||||
"hermes",
|
||||
"droid",
|
||||
"oauth2-upstream",
|
||||
"agent-hooks",
|
||||
"openclaw",
|
||||
|
||||
@@ -65,6 +65,7 @@ Disable it with `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off` (or `--no-teleme
|
||||
| `--gemini-api-url` | Gemini default | Custom Gemini API URL |
|
||||
| `--backend` | `anthropic` | Backend: `anthropic`, `bedrock`, `openrouter`, `anyllm`, or `litellm-<provider>` |
|
||||
| `--bedrock-api-url` | None | Bedrock InvokeModel upstream for the `/model/{id}/invoke` passthrough routes (see [Bedrock via a local gateway](#bedrock-via-a-local-gateway)) |
|
||||
| `--factory-api-url` | None | Factory Droid upstream (env: `FACTORY_TARGET_API_URL`). Registers `/api/*` routes: `/api/llm/a/v1/messages` is compressed, other `/api/*` paths pass through verbatim. Paths outside `/api/` are never sent to Factory. Set automatically by `headroom wrap droid` (see [Factory Droid](/docs/droid)) |
|
||||
| `--telemetry` | `false` | Enable local, in-process usage stats (for your own `/stats` and dashboard; nothing leaves the machine) |
|
||||
| `--no-telemetry` | `false` | Force local telemetry off (already the default) |
|
||||
| `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |
|
||||
|
||||
+18
-1
@@ -1157,6 +1157,15 @@ def dashboard(port: int | None, no_open: bool) -> None:
|
||||
"(env: BEDROCK_TARGET_API_URL)"
|
||||
),
|
||||
)
|
||||
@click.option(
|
||||
"--factory-api-url",
|
||||
default=None,
|
||||
help=(
|
||||
"Factory Droid upstream for /api/* (used by `headroom wrap droid`). "
|
||||
"/api/llm/a/v1/messages is compressed; other /api/* paths pass "
|
||||
"through verbatim. (env: FACTORY_TARGET_API_URL)"
|
||||
),
|
||||
)
|
||||
@click.option(
|
||||
"--telemetry",
|
||||
is_flag=True,
|
||||
@@ -1296,6 +1305,7 @@ def proxy(
|
||||
bedrock_region: str | None,
|
||||
bedrock_profile: str | None,
|
||||
bedrock_api_url: str | None,
|
||||
factory_api_url: str | None,
|
||||
telemetry: bool,
|
||||
no_telemetry: bool,
|
||||
stateless: bool,
|
||||
@@ -1677,6 +1687,7 @@ def proxy(
|
||||
# CLI flag > env > unset. Matches the BEDROCK_TARGET_API_URL naming of
|
||||
# the sibling *_TARGET_API_URL passthrough overrides.
|
||||
bedrock_api_url=bedrock_api_url or os.environ.get("BEDROCK_TARGET_API_URL"),
|
||||
factory_api_url=factory_api_url or os.environ.get("FACTORY_TARGET_API_URL"),
|
||||
anyllm_provider=effective_anyllm_provider,
|
||||
# License / Usage Reporting (managed/enterprise)
|
||||
license_key=license_key,
|
||||
@@ -1722,6 +1733,12 @@ def proxy(
|
||||
openai_url = provider_api_targets.openai
|
||||
cloudcode_url = provider_api_targets.cloudcode
|
||||
vertex_url = provider_api_targets.vertex
|
||||
factory_route_line = (
|
||||
f"\n /api/* → {config.factory_api_url} "
|
||||
"(Factory Droid; /api/llm/a/v1/messages compressed)"
|
||||
if config.factory_api_url
|
||||
else ""
|
||||
)
|
||||
backend_section = ""
|
||||
|
||||
if config.backend == "anyllm" or config.backend.startswith("anyllm-"):
|
||||
@@ -1927,7 +1944,7 @@ Routing:
|
||||
/v1/chat/completions → {openai_url}
|
||||
/v1/responses → {openai_url} (HTTP + WebSocket)
|
||||
/v1internal:streamGenerateContent → {cloudcode_url}
|
||||
/v1/projects/.../publishers/... → {vertex_url}
|
||||
/v1/projects/.../publishers/... → {vertex_url}{factory_route_line}
|
||||
|
||||
Usage:
|
||||
{usage_section}
|
||||
|
||||
+130
-4
@@ -166,6 +166,12 @@ from headroom.providers.copilot import (
|
||||
validate_configuration as _validate_copilot_configuration,
|
||||
)
|
||||
from headroom.providers.cursor import render_setup_lines as _render_cursor_setup_lines
|
||||
from headroom.providers.droid import (
|
||||
DEFAULT_FACTORY_API_URL,
|
||||
canonical_factory_api_url,
|
||||
resolve_factory_upstream,
|
||||
)
|
||||
from headroom.providers.droid import proxy_base_url as droid_proxy_base_url
|
||||
from headroom.providers.grok import (
|
||||
DEFAULT_API_URL as _GROK_DEFAULT_API_URL,
|
||||
)
|
||||
@@ -768,6 +774,7 @@ def _start_proxy(
|
||||
copilot_api_token: str | None = None,
|
||||
copilot_refresh_oauth_token: str | None = None,
|
||||
copilot_api_token_expires_at: float | None = None,
|
||||
factory_api_url: str | None = None,
|
||||
proxy_extensions: list[str] | None = None,
|
||||
) -> subprocess.Popen:
|
||||
"""Start Headroom proxy as a background subprocess.
|
||||
@@ -830,6 +837,8 @@ def _start_proxy(
|
||||
if vertex_api_url:
|
||||
cmd.extend(["--vertex-api-url", vertex_api_url])
|
||||
|
||||
if factory_api_url:
|
||||
cmd.extend(["--factory-api-url", factory_api_url])
|
||||
# Extensions carried over from the proxy this one replaces (see
|
||||
# ``_dedicated_proxy_extensions``). The flag outranks the envvar in click,
|
||||
# so callers must not pass this when HEADROOM_PROXY_EXTENSIONS is set;
|
||||
@@ -890,6 +899,8 @@ def _start_proxy(
|
||||
proxy_env.pop("VERTEX_TARGET_API_URL", None)
|
||||
if vertex_api_url:
|
||||
proxy_env["VERTEX_TARGET_API_URL"] = vertex_api_url
|
||||
if factory_api_url:
|
||||
proxy_env["FACTORY_TARGET_API_URL"] = factory_api_url
|
||||
# Pin the wrapper-validated Copilot token for this proxy instance only.
|
||||
# Injected into the subprocess env here (not the parent's os.environ) so it
|
||||
# never leaks into shared state. The proxy's CopilotTokenProvider honours
|
||||
@@ -4271,9 +4282,9 @@ def _proxy_needs_version_restart(payload: dict[str, Any] | None) -> bool:
|
||||
|
||||
# Upstream-URL config keys that decide where a running proxy forwards
|
||||
# traffic. A running proxy is only reusable when every key matches the
|
||||
# requested value. This build's /health config payload only serializes the
|
||||
# first five keys; the augment/factory entries catch proxies built from
|
||||
# feature branches or other versions that DO expose them (exactly the
|
||||
# requested value. This build's /health config payload serializes the first
|
||||
# five keys plus factory_api_url; the augment entry catches proxies built from
|
||||
# feature branches or other versions that DO expose it (exactly the
|
||||
# mixed-fleet shape of the 2026-08-22 incident, where a 0.34-era proxy
|
||||
# reported augment_api_url). Keys absent from the running config simply
|
||||
# compare equal to an unrequested (None) value, so they are inert, never
|
||||
@@ -4333,6 +4344,7 @@ def _effective_requested_proxy_routing(
|
||||
anthropic_api_url: str | None,
|
||||
vertex_api_url: str | None,
|
||||
clear_vertex_api_url: bool,
|
||||
factory_api_url: str | None = None,
|
||||
) -> tuple[str, dict[str, str | None]]:
|
||||
"""Resolve the routing a newly started proxy would inherit."""
|
||||
from headroom.providers.registry import resolve_api_overrides
|
||||
@@ -4353,7 +4365,7 @@ def _effective_requested_proxy_routing(
|
||||
"cloudcode_api_url": overrides.cloudcode,
|
||||
"vertex_api_url": None if clear_vertex_api_url else overrides.vertex,
|
||||
"augment_api_url": os.environ.get("AUGMENT_TARGET_API_URL"),
|
||||
"factory_api_url": os.environ.get("FACTORY_TARGET_API_URL"),
|
||||
"factory_api_url": factory_api_url or os.environ.get("FACTORY_TARGET_API_URL"),
|
||||
},
|
||||
)
|
||||
|
||||
@@ -4877,6 +4889,7 @@ def _ensure_proxy_unlocked(
|
||||
copilot_api_token: str | None = None,
|
||||
copilot_refresh_oauth_token: str | None = None,
|
||||
copilot_api_token_expires_at: float | None = None,
|
||||
factory_api_url: str | None = None,
|
||||
) -> tuple[subprocess.Popen | None, int]:
|
||||
"""Start or verify proxy. Returns (process_handle, actual_port).
|
||||
|
||||
@@ -4897,6 +4910,7 @@ def _ensure_proxy_unlocked(
|
||||
anthropic_api_url=anthropic_api_url,
|
||||
vertex_api_url=vertex_api_url,
|
||||
clear_vertex_api_url=clear_vertex_api_url,
|
||||
factory_api_url=factory_api_url,
|
||||
)
|
||||
# Set True when the proxy on the requested port belongs to a persistent
|
||||
# deployment whose routing config does not match this wrap: the deployment
|
||||
@@ -5351,6 +5365,7 @@ def _ensure_proxy_unlocked(
|
||||
copilot_api_token=copilot_api_token,
|
||||
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
|
||||
copilot_api_token_expires_at=copilot_api_token_expires_at,
|
||||
factory_api_url=factory_api_url,
|
||||
proxy_extensions=proxy_extensions,
|
||||
),
|
||||
)
|
||||
@@ -5366,6 +5381,26 @@ def _ensure_proxy_unlocked(
|
||||
running_config = _require_no_proxy_openai_upstream(port, openai_api_url)
|
||||
click.echo(f" Proxy on port {port} already targets {openai_api_url}")
|
||||
_warn_proxy_mode_mismatch(running_config)
|
||||
if factory_api_url is not None:
|
||||
# Droid is pointed at this port unconditionally, so an unverified
|
||||
# listener would receive its Factory credentials. Require a
|
||||
# Headroom proxy that serves exactly the requested Factory upstream.
|
||||
payload = helpers._query_proxy_health(port) if helpers._check_proxy(port) else None
|
||||
running_config = helpers._proxy_health_config(payload)
|
||||
if not (
|
||||
isinstance(payload, dict)
|
||||
and payload.get("service") == "headroom-proxy"
|
||||
and running_config is not None
|
||||
and _normalize_proxy_api_url(
|
||||
running_config.get("factory_api_url"), strip_provider_v1=False
|
||||
)
|
||||
== _normalize_proxy_api_url(factory_api_url, strip_provider_v1=False)
|
||||
):
|
||||
raise click.ClickException(
|
||||
f"--no-proxy requires a Headroom proxy on port {port} serving Factory "
|
||||
f"upstream {factory_api_url}; start one with headroom proxy "
|
||||
f"--factory-api-url {factory_api_url} or omit --no-proxy."
|
||||
)
|
||||
elif not helpers._check_proxy(port):
|
||||
click.echo(f" Warning: No proxy detected on port {port}")
|
||||
elif (
|
||||
@@ -5622,6 +5657,7 @@ def _launch_tool(
|
||||
copilot_api_token: str | None = None,
|
||||
copilot_refresh_oauth_token: str | None = None,
|
||||
copilot_api_token_expires_at: float | None = None,
|
||||
factory_api_url: str | None = None,
|
||||
configure_launch: Callable[
|
||||
[int, tuple, dict[str, str], list[str]],
|
||||
tuple[tuple, dict[str, str], list[str]],
|
||||
@@ -5665,6 +5701,7 @@ def _launch_tool(
|
||||
copilot_api_token=copilot_api_token,
|
||||
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
|
||||
copilot_api_token_expires_at=copilot_api_token_expires_at,
|
||||
factory_api_url=factory_api_url,
|
||||
)
|
||||
if actual_port != port:
|
||||
_unregister_proxy_client(port)
|
||||
@@ -9248,6 +9285,95 @@ def unwrap_omp(port: int, no_stop_proxy: bool) -> None:
|
||||
click.echo()
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Factory Droid
|
||||
# =============================================================================
|
||||
|
||||
|
||||
@wrap.command(context_settings={"ignore_unknown_options": True})
|
||||
@_retired_context_tool_option
|
||||
@proxy_port_option()
|
||||
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
|
||||
@click.option("--learn", is_flag=True, help="Enable live traffic learning")
|
||||
@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
|
||||
@click.option(
|
||||
"--factory-api-url",
|
||||
default=None,
|
||||
help=(
|
||||
"Real Factory upstream the proxy forwards to (default: $FACTORY_API_BASE_URL, "
|
||||
f"else {DEFAULT_FACTORY_API_URL})"
|
||||
),
|
||||
)
|
||||
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
|
||||
@click.option("--prepare-only", is_flag=True, hidden=True)
|
||||
@click.argument("droid_args", nargs=-1, type=click.UNPROCESSED)
|
||||
def droid(
|
||||
port: int,
|
||||
no_proxy: bool,
|
||||
learn: bool,
|
||||
memory: bool,
|
||||
factory_api_url: str | None,
|
||||
verbose: bool,
|
||||
prepare_only: bool,
|
||||
droid_args: tuple,
|
||||
) -> None:
|
||||
"""Launch Factory Droid through Headroom proxy.
|
||||
|
||||
\b
|
||||
Sets FACTORY_API_BASE_URL for the droid process only, pointing it at the
|
||||
proxy, which forwards to the real Factory upstream. The Anthropic-shaped
|
||||
/api/llm/a/v1/messages route is compressed; every other /api/* path is
|
||||
forwarded verbatim (OpenAI-shaped /api/llm/o/* traffic is not compressed
|
||||
yet). Nothing durable is written: no Droid config, no customModels.
|
||||
|
||||
\b
|
||||
Examples:
|
||||
headroom wrap droid # Start proxy + droid
|
||||
headroom wrap droid -- exec "fix the bug" # Non-interactive run
|
||||
headroom wrap droid --factory-api-url https://factory.example.com
|
||||
"""
|
||||
upstream = canonical_factory_api_url(resolve_factory_upstream(factory_api_url))
|
||||
if upstream is None:
|
||||
raise click.ClickException(
|
||||
"Factory upstream must be an http(s) URL with a non-loopback host and no "
|
||||
"credentials, query or fragment (from --factory-api-url, else "
|
||||
"FACTORY_API_BASE_URL). If FACTORY_API_BASE_URL still points at a local "
|
||||
"proxy from an earlier session, unset it."
|
||||
)
|
||||
|
||||
if prepare_only:
|
||||
click.echo(f"FACTORY_API_BASE_URL={droid_proxy_base_url(port)}")
|
||||
click.echo(f"upstream={upstream}")
|
||||
return
|
||||
|
||||
droid_bin = shutil.which("droid")
|
||||
if not droid_bin:
|
||||
click.echo("Error: 'droid' not found in PATH.")
|
||||
click.echo("Install Factory Droid: see https://docs.factory.ai")
|
||||
raise SystemExit(1)
|
||||
|
||||
env = os.environ.copy()
|
||||
env["FACTORY_API_BASE_URL"] = droid_proxy_base_url(port)
|
||||
env_vars_display = [
|
||||
f"FACTORY_API_BASE_URL={env['FACTORY_API_BASE_URL']}",
|
||||
f"Factory upstream: {upstream}",
|
||||
]
|
||||
|
||||
_launch_tool(
|
||||
binary=droid_bin,
|
||||
args=droid_args,
|
||||
env=env,
|
||||
port=port,
|
||||
no_proxy=no_proxy,
|
||||
tool_label="DROID",
|
||||
env_vars_display=env_vars_display,
|
||||
learn=learn,
|
||||
memory=memory,
|
||||
agent_type="droid",
|
||||
factory_api_url=upstream,
|
||||
)
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Grok CLI (unwrap)
|
||||
# =============================================================================
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
"""Factory Droid provider integration for `headroom wrap droid`."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from .runtime import (
|
||||
DEFAULT_FACTORY_API_URL,
|
||||
canonical_factory_api_url,
|
||||
proxy_base_url,
|
||||
resolve_factory_upstream,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"DEFAULT_FACTORY_API_URL",
|
||||
"canonical_factory_api_url",
|
||||
"proxy_base_url",
|
||||
"resolve_factory_upstream",
|
||||
]
|
||||
@@ -0,0 +1,104 @@
|
||||
"""Runtime helpers for Factory Droid integration.
|
||||
|
||||
``headroom wrap droid`` routes Droid through Headroom by pointing Droid's
|
||||
Factory gateway at the local proxy via the ``FACTORY_API_BASE_URL`` environment
|
||||
variable. The proxy compresses the Anthropic-shaped ``/api/llm/a/v1/messages``
|
||||
inference route and forwards every other Factory ``/api/*`` path verbatim to
|
||||
the real upstream resolved here. OpenAI-shaped ``/api/llm/o/*`` traffic is
|
||||
forwarded uncompressed for now.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import ipaddress
|
||||
import os
|
||||
import re
|
||||
import socket
|
||||
from urllib.parse import urlsplit, urlunsplit
|
||||
|
||||
DEFAULT_FACTORY_API_URL = "https://api.factory.ai"
|
||||
_DNS_HOST_RE = re.compile(
|
||||
r"(?=.{1,253}\.?$)"
|
||||
r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*"
|
||||
r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.?"
|
||||
)
|
||||
|
||||
|
||||
def _is_valid_host(host: str) -> bool:
|
||||
"""Return whether `host` is an IP literal or a syntactically valid DNS name."""
|
||||
try:
|
||||
ipaddress.ip_address(host.rstrip("."))
|
||||
except ValueError:
|
||||
return _DNS_HOST_RE.fullmatch(host) is not None
|
||||
return True
|
||||
|
||||
|
||||
def _is_self_host(host: str) -> bool:
|
||||
"""Return whether `host` names this machine (loopback or the unspecified address).
|
||||
|
||||
Forwarding there would loop the proxy back to itself when a leftover proxy
|
||||
address sits in ``FACTORY_API_BASE_URL``.
|
||||
"""
|
||||
normalized = host.rstrip(".").lower()
|
||||
if normalized == "localhost" or normalized.endswith(".localhost"):
|
||||
return True
|
||||
try:
|
||||
address = ipaddress.ip_address(normalized)
|
||||
except ValueError:
|
||||
try:
|
||||
address = ipaddress.ip_address(socket.inet_aton(normalized))
|
||||
except OSError:
|
||||
return False
|
||||
return address.is_loopback or address.is_unspecified
|
||||
|
||||
|
||||
def canonical_factory_api_url(value: object) -> str | None:
|
||||
"""Return a strict Factory upstream URL, or None when unsafe or malformed.
|
||||
|
||||
Only for resolving and validating the upstream; running-vs-requested proxy
|
||||
comparisons use the wrap module's shared URL normaliser.
|
||||
"""
|
||||
if not isinstance(value, str):
|
||||
return None
|
||||
try:
|
||||
parsed = urlsplit(value.strip())
|
||||
port = parsed.port
|
||||
except ValueError:
|
||||
return None
|
||||
scheme = parsed.scheme.lower()
|
||||
host = parsed.hostname
|
||||
if (
|
||||
scheme not in {"http", "https"}
|
||||
or not host
|
||||
or not _is_valid_host(host)
|
||||
or parsed.username is not None
|
||||
or parsed.password is not None
|
||||
or parsed.query
|
||||
or parsed.fragment
|
||||
or _is_self_host(host)
|
||||
):
|
||||
return None
|
||||
|
||||
host = host.lower()
|
||||
rendered_host = f"[{host}]" if ":" in host else host
|
||||
if port is not None and not (
|
||||
(scheme == "http" and port == 80) or (scheme == "https" and port == 443)
|
||||
):
|
||||
rendered_host = f"{rendered_host}:{port}"
|
||||
return urlunsplit((scheme, rendered_host, parsed.path.rstrip("/"), "", ""))
|
||||
|
||||
|
||||
def proxy_base_url(port: int) -> str:
|
||||
"""Return the local Headroom base URL Droid targets via FACTORY_API_BASE_URL."""
|
||||
return f"http://127.0.0.1:{port}"
|
||||
|
||||
|
||||
def resolve_factory_upstream(explicit: str | None = None) -> str:
|
||||
"""Resolve the real Factory upstream the proxy forwards to.
|
||||
|
||||
Precedence: an explicit ``--factory-api-url``, then the caller's existing
|
||||
``FACTORY_API_BASE_URL`` (an enterprise or EU gateway they already use),
|
||||
then the public default.
|
||||
"""
|
||||
candidate = explicit or os.environ.get("FACTORY_API_BASE_URL") or DEFAULT_FACTORY_API_URL
|
||||
return candidate.strip().rstrip("/")
|
||||
@@ -25,6 +25,11 @@ _CLAUDE_TEXT_PART_TYPES = frozenset({"text"})
|
||||
_RESPONSES_TEXT_PART_TYPES = frozenset({"text", "input_text", "output_text"})
|
||||
_CODEX_RESPONSES_SUFFIX = "/v1/responses"
|
||||
_CLAUDE_MESSAGES_SUFFIX = "/v1/messages"
|
||||
# Hermes Studio's scoped proxy prefixes. They live under `/api/`, so a
|
||||
# Factory-mode proxy must keep every path below them on the normal catch-all.
|
||||
CODEX_PROXY_PREFIX = "/api/codex-proxy/"
|
||||
CLAUDE_CODE_PROXY_PREFIX = "/api/claude-code-proxy/"
|
||||
SCOPED_PATH_PREFIXES = (CODEX_PROXY_PREFIX, CLAUDE_CODE_PROXY_PREFIX)
|
||||
|
||||
|
||||
def build_launch_env(
|
||||
@@ -76,8 +81,8 @@ def unsupported_provider_error(hermes_args: tuple[str, ...] | list[str]) -> str
|
||||
|
||||
def is_scoped_coding_agent_path(path: str) -> bool:
|
||||
"""Return whether *path* is a Hermes scoped coding-agent endpoint."""
|
||||
return (path.startswith("/api/codex-proxy/") and path.endswith(_CODEX_RESPONSES_SUFFIX)) or (
|
||||
path.startswith("/api/claude-code-proxy/") and path.endswith(_CLAUDE_MESSAGES_SUFFIX)
|
||||
return (path.startswith(CODEX_PROXY_PREFIX) and path.endswith(_CODEX_RESPONSES_SUFFIX)) or (
|
||||
path.startswith(CLAUDE_CODE_PROXY_PREFIX) and path.endswith(_CLAUDE_MESSAGES_SUFFIX)
|
||||
)
|
||||
|
||||
|
||||
@@ -105,7 +110,7 @@ def compress_scoped_passthrough_body(
|
||||
if not model:
|
||||
return body
|
||||
|
||||
if path.startswith("/api/claude-code-proxy/"):
|
||||
if path.startswith(CLAUDE_CODE_PROXY_PREFIX):
|
||||
field_name = "messages"
|
||||
route_name = "claude-code"
|
||||
else:
|
||||
|
||||
@@ -21,6 +21,7 @@ from headroom.providers.codex.live import (
|
||||
)
|
||||
from headroom.providers.codex.responses import handle_chatgpt_codex_responses_subpath
|
||||
from headroom.providers.codex.runtime import resolve_codex_routing
|
||||
from headroom.providers.hermes import SCOPED_PATH_PREFIXES as HERMES_SCOPED_PATH_PREFIXES
|
||||
from headroom.providers.model_metadata import (
|
||||
MODEL_METADATA_LIST_ENDPOINT,
|
||||
handle_model_metadata_endpoint,
|
||||
@@ -308,6 +309,46 @@ def _register_openai_image_routes(app: FastAPI, proxy: Any) -> None:
|
||||
def register_provider_routes(app: FastAPI, proxy: Any) -> None:
|
||||
"""Register provider-specific proxy endpoints."""
|
||||
|
||||
async def _default_passthrough(request: Request, path: str):
|
||||
"""Catch-all forwarding for paths no provider route claims.
|
||||
|
||||
``path`` is the request path without its leading slash, as the
|
||||
``/{path:path}`` catch-all captures it.
|
||||
"""
|
||||
custom_base = request.headers.get("x-headroom-base-url")
|
||||
if custom_base:
|
||||
if not await is_safe_upstream_url_async(custom_base):
|
||||
logger.warning("rejecting unsafe x-headroom-base-url: %r", custom_base)
|
||||
raise HTTPException(status_code=400, detail="Rejected unsafe upstream base URL")
|
||||
base_url = custom_base.rstrip("/")
|
||||
endpoint_name, provider_name = _custom_base_passthrough_telemetry(
|
||||
request.method,
|
||||
path,
|
||||
base_url,
|
||||
)
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
base_url,
|
||||
endpoint_name,
|
||||
provider_name,
|
||||
)
|
||||
|
||||
normalized_cloudcode_path = normalize_cloudcode_passthrough_path(path)
|
||||
if normalized_cloudcode_path is not None:
|
||||
normalize_request_path(request, normalized_cloudcode_path)
|
||||
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
_api_target(proxy, "cloudcode"),
|
||||
)
|
||||
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
# The path matters here: this is where unrouted paths land, and
|
||||
# Copilot's inline completions are one of them (#3076).
|
||||
_select_passthrough_base_url(proxy, dict(request.headers), request.url.path),
|
||||
)
|
||||
|
||||
async def vertex_publisher_passthrough(request: Request, publisher: str, action: str):
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
@@ -367,6 +408,48 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
|
||||
async def bedrock_invoke_stream(request: Request, model_id: str):
|
||||
return await proxy.handle_bedrock_invoke(request, model_id, stream=True)
|
||||
|
||||
# Factory Droid. Registered ONLY when an upstream is configured
|
||||
# (`--factory-api-url` / FACTORY_TARGET_API_URL, set by `headroom wrap
|
||||
# droid`). Droid sends everything under `/api/`; nothing outside `/api/`
|
||||
# ever goes to Factory, so another tool still pointed at this port (a
|
||||
# leftover Codex/Claude config) keeps its usual upstream and its
|
||||
# credentials never reach Factory.
|
||||
factory_api_url = getattr(proxy.config, "factory_api_url", None)
|
||||
if factory_api_url:
|
||||
factory_base = factory_api_url.rstrip("/")
|
||||
|
||||
@app.post("/api/llm/a/v1/messages")
|
||||
async def factory_anthropic_messages(request: Request):
|
||||
# Anthropic-shaped inference: compressed, then forwarded to
|
||||
# `{factory}/api/llm/a/v1/messages`. A client-sent
|
||||
# `x-headroom-base-url` is deliberately ignored (the handler strips
|
||||
# `x-headroom-*`), and Factory is not a trusted host, so operator
|
||||
# Anthropic extra headers are withheld. `force_direct` keeps a
|
||||
# configured translating backend or route advice from taking it.
|
||||
return await proxy.handle_anthropic_messages(
|
||||
request,
|
||||
upstream_base_url=factory_base,
|
||||
provider_name="factory",
|
||||
force_direct=True,
|
||||
)
|
||||
|
||||
@app.api_route(
|
||||
"/api/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
|
||||
)
|
||||
async def factory_passthrough(request: Request, path: str):
|
||||
# Hermes Studio's scoped proxies and callers that name their own
|
||||
# upstream are not Droid traffic: keep the catch-all behaviour.
|
||||
if request.headers.get(
|
||||
"x-headroom-base-url", ""
|
||||
).strip() or request.url.path.startswith(HERMES_SCOPED_PATH_PREFIXES):
|
||||
return await _default_passthrough(request, request.url.path[1:])
|
||||
# Factory REST (and, for now, OpenAI-shaped `/api/llm/o/*`):
|
||||
# verbatim and buffered, even with `compress_passthrough` on. No
|
||||
# endpoint name, so no LLM telemetry.
|
||||
return await proxy.handle_passthrough(
|
||||
request, factory_base, None, "factory", verbatim=True
|
||||
)
|
||||
|
||||
_register_openai_responses_routes(app, proxy)
|
||||
|
||||
_register_provider_handler_routes(app, proxy)
|
||||
@@ -615,36 +698,4 @@ def register_provider_routes(app: FastAPI, proxy: Any) -> None:
|
||||
|
||||
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "HEAD"])
|
||||
async def passthrough(request: Request, path: str):
|
||||
custom_base = request.headers.get("x-headroom-base-url")
|
||||
if custom_base:
|
||||
if not await is_safe_upstream_url_async(custom_base):
|
||||
logger.warning("rejecting unsafe x-headroom-base-url: %r", custom_base)
|
||||
raise HTTPException(status_code=400, detail="Rejected unsafe upstream base URL")
|
||||
base_url = custom_base.rstrip("/")
|
||||
endpoint_name, provider_name = _custom_base_passthrough_telemetry(
|
||||
request.method,
|
||||
path,
|
||||
base_url,
|
||||
)
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
base_url,
|
||||
endpoint_name,
|
||||
provider_name,
|
||||
)
|
||||
|
||||
normalized_cloudcode_path = normalize_cloudcode_passthrough_path(path)
|
||||
if normalized_cloudcode_path is not None:
|
||||
normalize_request_path(request, normalized_cloudcode_path)
|
||||
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
_api_target(proxy, "cloudcode"),
|
||||
)
|
||||
|
||||
return await proxy.handle_passthrough(
|
||||
request,
|
||||
# The path matters here: this is where unrouted paths land, and
|
||||
# Copilot's inline completions are one of them (#3076).
|
||||
_select_passthrough_base_url(proxy, dict(request.headers), request.url.path),
|
||||
)
|
||||
return await _default_passthrough(request, path)
|
||||
|
||||
@@ -1313,8 +1313,15 @@ class AnthropicHandlerMixin:
|
||||
provider_name: str = "anthropic",
|
||||
model_override: str | None = None,
|
||||
force_stream: bool = False,
|
||||
force_direct: bool = False,
|
||||
) -> Response | StreamingResponse:
|
||||
"""Handle Anthropic /v1/messages endpoint."""
|
||||
"""Handle Anthropic /v1/messages endpoint.
|
||||
|
||||
``force_direct`` forwards over HTTP to ``upstream_base_url`` without
|
||||
consulting the backend resolver: neither ``self.anthropic_backend``
|
||||
nor route advice can take the request (or rewrite ``body["model"]``).
|
||||
Used by routes whose upstream is fixed, such as Factory.
|
||||
"""
|
||||
if not hasattr(self, "pipeline_extensions"):
|
||||
from headroom.pipeline import PipelineExtensionManager
|
||||
|
||||
@@ -4175,7 +4182,10 @@ class AnthropicHandlerMixin:
|
||||
str(model)
|
||||
if (
|
||||
not upstream_base_url
|
||||
or getattr(self, "anthropic_backend", None) is not None
|
||||
or (
|
||||
getattr(self, "anthropic_backend", None) is not None
|
||||
and not force_direct
|
||||
)
|
||||
or _is_googleapis_endpoint(upstream_base_url)
|
||||
)
|
||||
else None
|
||||
@@ -4250,10 +4260,13 @@ class AnthropicHandlerMixin:
|
||||
# it names a provider we do not already speak, serve this ONE
|
||||
# request from a translating backend for it. Absent, unresolvable,
|
||||
# or same-protocol -> `self.anthropic_backend`, i.e. exactly the
|
||||
# behaviour this line had before.
|
||||
# behaviour this line had before. `force_direct` skips the
|
||||
# resolver entirely: the caller's upstream is the only target.
|
||||
from headroom.proxy.route_advice import resolver_for
|
||||
|
||||
request_backend = resolver_for(self).for_request(request, body=body)
|
||||
request_backend = (
|
||||
None if force_direct else resolver_for(self).for_request(request, body=body)
|
||||
)
|
||||
if request_backend is not None:
|
||||
# Route through Bedrock backend
|
||||
try:
|
||||
|
||||
@@ -12227,6 +12227,7 @@ class OpenAIHandlerMixin:
|
||||
endpoint_name: str | None = None,
|
||||
provider: str | None = None,
|
||||
*,
|
||||
verbatim: bool = False,
|
||||
_upstream_request: httpx.Request | None = None,
|
||||
_model: str | None = None,
|
||||
_start_time: float | None = None,
|
||||
@@ -12238,6 +12239,8 @@ class OpenAIHandlerMixin:
|
||||
base_url: The upstream API base URL
|
||||
endpoint_name: Optional name for stats tracking (e.g., "models", "embeddings")
|
||||
provider: Optional provider name for stats (e.g., "openai", "anthropic", "gemini")
|
||||
verbatim: Skip the opt-in ``compress_passthrough`` Responses
|
||||
compressor, so the body reaches the upstream unchanged.
|
||||
"""
|
||||
from fastapi.responses import Response
|
||||
|
||||
@@ -12339,7 +12342,8 @@ class OpenAIHandlerMixin:
|
||||
# the exact same ContentRouter/Kompress path the native handler runs.
|
||||
_pt_config = getattr(self, "config", None)
|
||||
if (
|
||||
not soft_passthrough
|
||||
not verbatim
|
||||
and not soft_passthrough
|
||||
and getattr(_pt_config, "compress_passthrough", False)
|
||||
and getattr(_pt_config, "optimize", False)
|
||||
and request.method == "POST"
|
||||
|
||||
@@ -192,6 +192,12 @@ class ProxyConfig:
|
||||
# SigV4 signature. Leave unset (default) to keep `--backend bedrock`'s
|
||||
# direct-to-AWS, re-signing behavior unchanged.
|
||||
bedrock_api_url: str | None = None
|
||||
# Factory Droid upstream (`--factory-api-url` / FACTORY_TARGET_API_URL).
|
||||
# When set, `/api/llm/a/v1/messages` is compressed and forwarded here and
|
||||
# every other `/api/*` path is passed through verbatim; it serves `/api/*`
|
||||
# only and never becomes the catch-all upstream. Leave unset (default) to
|
||||
# keep `/api/*` on the normal catch-all.
|
||||
factory_api_url: str | None = None
|
||||
anyllm_provider: str = "openai"
|
||||
|
||||
# Optimization mode: "token" (rewrite for max compression) or
|
||||
|
||||
@@ -4062,6 +4062,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
|
||||
"gemini_api_url": config.gemini_api_url,
|
||||
"cloudcode_api_url": config.cloudcode_api_url,
|
||||
"vertex_api_url": config.vertex_api_url,
|
||||
"factory_api_url": config.factory_api_url,
|
||||
"savings_profile": config.savings_profile,
|
||||
# Enabled extension names only (no plugin state): `headroom
|
||||
# wrap` carries them over when it has to start a dedicated
|
||||
@@ -6667,6 +6668,7 @@ def _proxy_config_from_env() -> ProxyConfig:
|
||||
bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", "us-west-2"),
|
||||
bedrock_profile=os.environ.get("AWS_PROFILE"),
|
||||
bedrock_api_url=os.environ.get("BEDROCK_TARGET_API_URL"),
|
||||
factory_api_url=os.environ.get("FACTORY_TARGET_API_URL"),
|
||||
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", "openai"),
|
||||
disable_kompress=_get_env_bool("HEADROOM_DISABLE_KOMPRESS", False),
|
||||
disable_kompress_fallback=_get_env_bool("HEADROOM_DISABLE_KOMPRESS_FALLBACK", False),
|
||||
@@ -7199,6 +7201,14 @@ if __name__ == "__main__":
|
||||
"(env: BEDROCK_TARGET_API_URL)"
|
||||
),
|
||||
)
|
||||
parser.add_argument(
|
||||
"--factory-api-url",
|
||||
help=(
|
||||
"Factory Droid upstream for /api/* — /api/llm/a/v1/messages is "
|
||||
"compressed, other /api/* paths pass through "
|
||||
"(env: FACTORY_TARGET_API_URL)"
|
||||
),
|
||||
)
|
||||
parser.add_argument(
|
||||
"--openrouter-api-key",
|
||||
help="OpenRouter API key (or set OPENROUTER_API_KEY env var)",
|
||||
@@ -7501,6 +7511,7 @@ if __name__ == "__main__":
|
||||
bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", args.bedrock_region),
|
||||
bedrock_profile=args.bedrock_profile or os.environ.get("AWS_PROFILE"),
|
||||
bedrock_api_url=_get_env_str("BEDROCK_TARGET_API_URL", args.bedrock_api_url),
|
||||
factory_api_url=_get_env_str("FACTORY_TARGET_API_URL", args.factory_api_url),
|
||||
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", args.anyllm_provider),
|
||||
optimize=optimize,
|
||||
min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens),
|
||||
|
||||
@@ -21,7 +21,7 @@ The canonical, always-current documentation index lives at the docs site below.
|
||||
- TypeScript / Node: `npm install headroom-ai` (or `pnpm add headroom-ai`, `bun add headroom-ai`)
|
||||
- Docker local: `docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom:latest --host 0.0.0.0`
|
||||
- Run the proxy: `headroom proxy --port 8787` then point any client at `http://127.0.0.1:8787`
|
||||
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `grok`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`, `zcode`)
|
||||
- Wrap an agent in one command: `headroom wrap claude` (also: `codex`, `grok`, `copilot`, `cursor`, `aider`, `opencode`, `cline`, `continue`, `goose`, `openhands`, `openclaw`, `vibe`, `omp`, `zcode`, `droid`)
|
||||
- Zero-network check, no provider key: `HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"` (prints roughly `20000 -> 95 FATAL kept: True`)
|
||||
|
||||
## By task (plain-language jobs this package does)
|
||||
|
||||
@@ -0,0 +1,331 @@
|
||||
"""Tests for ``headroom wrap droid`` (Factory Droid).
|
||||
|
||||
The command points Droid's ``FACTORY_API_BASE_URL`` at the local proxy and
|
||||
starts (or reuses) a proxy whose ``factory_api_url`` is the real Factory
|
||||
upstream. Nothing durable is written. Every proxy/launch seam is patched, so
|
||||
no proxy starts and no Droid binary runs.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import subprocess
|
||||
from typing import Any
|
||||
|
||||
import click
|
||||
import pytest
|
||||
from click.testing import CliRunner
|
||||
|
||||
import headroom.cli.wrap as wrap_cli
|
||||
from headroom.cli.main import main
|
||||
|
||||
FACTORY = "https://api.factory.ai"
|
||||
OTHER_FACTORY = "https://eu.factory.example"
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _hermetic(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
|
||||
monkeypatch.chdir(tmp_path)
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
for name in (
|
||||
"FACTORY_API_BASE_URL",
|
||||
"FACTORY_TARGET_API_URL",
|
||||
"ANTHROPIC_TARGET_API_URL",
|
||||
"OPENAI_TARGET_API_URL",
|
||||
"GEMINI_TARGET_API_URL",
|
||||
"CLOUDCODE_TARGET_API_URL",
|
||||
"VERTEX_TARGET_API_URL",
|
||||
"AUGMENT_TARGET_API_URL",
|
||||
"HEADROOM_BACKEND",
|
||||
):
|
||||
monkeypatch.delenv(name, raising=False)
|
||||
monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [])
|
||||
monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
|
||||
|
||||
|
||||
def _boom(message: str):
|
||||
def _raise(*args: Any, **kwargs: Any):
|
||||
raise AssertionError(message)
|
||||
|
||||
return _raise
|
||||
|
||||
|
||||
def _invoke(args: list[str], env: dict[str, str] | None = None):
|
||||
return CliRunner().invoke(main, ["wrap", "droid", *args], env=env)
|
||||
|
||||
|
||||
# ── command: env, precedence, rejection, missing binary ───────────────
|
||||
|
||||
|
||||
def test_launch_env_points_droid_at_proxy(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
captured: dict[str, Any] = {}
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
|
||||
monkeypatch.setattr(wrap_cli, "_launch_tool", lambda **kw: captured.update(kw))
|
||||
|
||||
result = _invoke(["--port", "8787", "--", "exec", "hi"])
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert captured["binary"] == "/usr/bin/droid"
|
||||
assert captured["args"] == ("exec", "hi")
|
||||
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8787"
|
||||
assert captured["factory_api_url"] == FACTORY
|
||||
assert captured["agent_type"] == "droid"
|
||||
assert captured["tool_label"] == "DROID"
|
||||
|
||||
|
||||
def test_fallback_port_rewrites_child_env(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
captured: dict[str, Any] = {}
|
||||
ensure_kwargs: dict[str, Any] = {}
|
||||
|
||||
def _ensure(port: int, no_proxy: bool, **kwargs: Any):
|
||||
ensure_kwargs.update(kwargs)
|
||||
return None, 8799
|
||||
|
||||
def _run(cmd: list[str], env: dict[str, str]):
|
||||
captured["cmd"] = cmd
|
||||
captured["env"] = env
|
||||
return subprocess.CompletedProcess(cmd, 0)
|
||||
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
|
||||
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _ensure)
|
||||
monkeypatch.setattr(wrap_cli, "_push_runtime_env", lambda *a, **kw: None)
|
||||
monkeypatch.setattr(wrap_cli.subprocess, "run", _run)
|
||||
|
||||
result = _invoke(["--port", "8787"])
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8799"
|
||||
assert ensure_kwargs["factory_api_url"] == FACTORY
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("args", "env", "expected"),
|
||||
[
|
||||
([], {}, FACTORY),
|
||||
([], {"FACTORY_API_BASE_URL": "https://EU.factory.example/"}, OTHER_FACTORY),
|
||||
(
|
||||
["--factory-api-url", "https://flag.factory.example"],
|
||||
{"FACTORY_API_BASE_URL": OTHER_FACTORY},
|
||||
"https://flag.factory.example",
|
||||
),
|
||||
],
|
||||
)
|
||||
def test_upstream_precedence(args: list[str], env: dict[str, str], expected: str) -> None:
|
||||
result = _invoke([*args, "--port", "8787", "--prepare-only"], env=env)
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert "FACTORY_API_BASE_URL=http://127.0.0.1:8787" in result.output
|
||||
assert f"upstream={expected}" in result.output
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("args", "env"),
|
||||
[
|
||||
(["--factory-api-url", "http://127.0.0.1:8787"], {}),
|
||||
([], {"FACTORY_API_BASE_URL": "http://127.0.0.1:8787"}),
|
||||
(["--factory-api-url", "http://localhost:9000"], {}),
|
||||
(["--factory-api-url", "https://user:pw@api.factory.ai"], {}),
|
||||
(["--factory-api-url", "https://api.factory.ai?x=1"], {}),
|
||||
(["--factory-api-url", "https://api.factory.ai#frag"], {}),
|
||||
],
|
||||
)
|
||||
def test_rejected_upstreams_never_launch(
|
||||
monkeypatch: pytest.MonkeyPatch, args: list[str], env: dict[str, str]
|
||||
) -> None:
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
|
||||
monkeypatch.setattr(wrap_cli, "_launch_tool", _boom("must not launch"))
|
||||
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _boom("must not start a proxy"))
|
||||
|
||||
result = _invoke([*args, "--port", "8787"], env=env)
|
||||
|
||||
assert result.exit_code != 0
|
||||
assert "FACTORY_API_BASE_URL" in result.output
|
||||
|
||||
|
||||
def test_missing_binary_exits_before_proxy_work(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: None)
|
||||
monkeypatch.setattr(wrap_cli, "_ensure_proxy", _boom("must not ensure a proxy"))
|
||||
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("must not start a proxy"))
|
||||
|
||||
result = _invoke(["--port", "8787"])
|
||||
|
||||
assert result.exit_code == 1
|
||||
assert "'droid' not found" in result.output
|
||||
|
||||
|
||||
# ── proxy routing plumbing ────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_requested_routing_uses_explicit_factory(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
kwargs = {
|
||||
"backend": None,
|
||||
"openai_api_url": None,
|
||||
"anthropic_api_url": None,
|
||||
"vertex_api_url": None,
|
||||
"clear_vertex_api_url": False,
|
||||
}
|
||||
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs, factory_api_url=FACTORY)
|
||||
assert urls["factory_api_url"] == FACTORY
|
||||
|
||||
monkeypatch.setenv("FACTORY_TARGET_API_URL", OTHER_FACTORY)
|
||||
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs)
|
||||
assert urls["factory_api_url"] == OTHER_FACTORY
|
||||
_, urls = wrap_cli._effective_requested_proxy_routing(**kwargs, factory_api_url=FACTORY)
|
||||
assert urls["factory_api_url"] == FACTORY
|
||||
|
||||
|
||||
def test_start_proxy_forwards_factory_flag_and_env(monkeypatch: pytest.MonkeyPatch, tmp_path):
|
||||
captured: dict[str, Any] = {}
|
||||
|
||||
class _Proc:
|
||||
returncode = None
|
||||
|
||||
def poll(self):
|
||||
return None
|
||||
|
||||
def _popen(cmd, **kwargs):
|
||||
captured["cmd"] = cmd
|
||||
captured["env"] = kwargs["env"]
|
||||
return _Proc()
|
||||
|
||||
monkeypatch.setattr(wrap_cli, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
|
||||
monkeypatch.setattr(
|
||||
wrap_cli, "_get_proxy_stdio_log_path", lambda port=None: tmp_path / "stdio.log"
|
||||
)
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
|
||||
monkeypatch.setattr(wrap_cli.subprocess, "Popen", _popen)
|
||||
|
||||
wrap_cli._start_proxy(8787, agent_type="droid", factory_api_url=FACTORY)
|
||||
|
||||
cmd = captured["cmd"]
|
||||
assert cmd[cmd.index("--factory-api-url") + 1] == FACTORY
|
||||
assert captured["env"]["FACTORY_TARGET_API_URL"] == FACTORY
|
||||
|
||||
|
||||
def _health(config: dict[str, Any], *, sessions: int = 0) -> dict[str, Any]:
|
||||
return {
|
||||
"service": "headroom-proxy",
|
||||
"version": wrap_cli._HEADROOM_VERSION,
|
||||
"runtime": {"websocket_sessions": {"active_sessions": sessions, "active_relay_tasks": 0}},
|
||||
"config": {"pid": 4242, "backend": "anthropic", **config},
|
||||
}
|
||||
|
||||
|
||||
def test_idle_non_factory_proxy_is_restarted_in_factory_mode(
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
calls: list[Any] = []
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: _health({}))
|
||||
monkeypatch.setattr(
|
||||
wrap_cli, "_kill_proxy_by_pid", lambda pid, port: calls.append(("kill", pid)) or True
|
||||
)
|
||||
monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start, **kw: start)
|
||||
monkeypatch.setattr(
|
||||
wrap_cli, "_start_proxy", lambda port, **kw: calls.append(("start", port, kw))
|
||||
)
|
||||
|
||||
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8787)
|
||||
assert calls[0] == ("kill", 4242)
|
||||
assert calls[1][0] == "start"
|
||||
assert calls[1][1] == 8787
|
||||
assert calls[1][2]["factory_api_url"] == FACTORY
|
||||
|
||||
|
||||
def test_attached_non_factory_proxy_pushes_droid_to_dedicated_port(
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
calls: list[Any] = []
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: _health({}))
|
||||
monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [{"pid": 1}])
|
||||
monkeypatch.setattr(wrap_cli, "_kill_proxy_by_pid", _boom("attached proxy must survive"))
|
||||
monkeypatch.setattr(
|
||||
wrap_cli,
|
||||
"_find_available_port",
|
||||
lambda start, **kw: calls.append(("find", start)) or 8799,
|
||||
)
|
||||
monkeypatch.setattr(
|
||||
wrap_cli, "_start_proxy", lambda port, **kw: calls.append(("start", port, kw))
|
||||
)
|
||||
|
||||
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8799)
|
||||
assert calls[0] == ("find", 8787)
|
||||
assert calls[1][1] == 8799
|
||||
assert calls[1][2]["factory_api_url"] == FACTORY
|
||||
|
||||
|
||||
def test_matching_factory_proxy_is_reused(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
|
||||
monkeypatch.setattr(
|
||||
wrap_cli,
|
||||
"_query_proxy_health",
|
||||
lambda port: _health({"factory_api_url": f"{FACTORY}/"}),
|
||||
)
|
||||
monkeypatch.setattr(wrap_cli, "_kill_proxy_by_pid", _boom("must reuse"))
|
||||
monkeypatch.setattr(wrap_cli, "_find_available_port", _boom("must reuse"))
|
||||
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("must reuse"))
|
||||
|
||||
assert wrap_cli._ensure_proxy(8787, False, factory_api_url=FACTORY) == (None, 8787)
|
||||
|
||||
|
||||
# ── --no-proxy ────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
_NO_PROXY_REFUSALS = {
|
||||
"no-listener": (False, None),
|
||||
"foreign-service": (
|
||||
True,
|
||||
{"service": "something-else", "config": {"factory_api_url": FACTORY}},
|
||||
),
|
||||
"config-less": (True, {"service": "headroom-proxy"}),
|
||||
"non-factory": (True, _health({})),
|
||||
"other-factory": (True, _health({"factory_api_url": OTHER_FACTORY})),
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("case", sorted(_NO_PROXY_REFUSALS))
|
||||
def test_no_proxy_refuses_unverified_listener(monkeypatch: pytest.MonkeyPatch, case: str) -> None:
|
||||
listening, payload = _NO_PROXY_REFUSALS[case]
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: listening)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: payload)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_config", lambda port: None)
|
||||
|
||||
with pytest.raises(click.ClickException, match="--no-proxy requires a Headroom proxy"):
|
||||
wrap_cli._ensure_proxy(8787, True, factory_api_url=FACTORY)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("case", sorted(_NO_PROXY_REFUSALS))
|
||||
def test_no_proxy_refusal_never_launches_droid(monkeypatch: pytest.MonkeyPatch, case: str) -> None:
|
||||
listening, payload = _NO_PROXY_REFUSALS[case]
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: listening)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: payload)
|
||||
monkeypatch.setattr(wrap_cli, "_query_proxy_config", lambda port: None)
|
||||
monkeypatch.setattr(wrap_cli.subprocess, "run", _boom("droid must not launch"))
|
||||
|
||||
result = _invoke(["--port", "8787", "--no-proxy"])
|
||||
|
||||
assert result.exit_code != 0
|
||||
assert "--no-proxy requires a Headroom proxy" in result.output
|
||||
|
||||
|
||||
def test_no_proxy_matching_factory_launches(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
captured: dict[str, Any] = {}
|
||||
|
||||
def _run(cmd: list[str], env: dict[str, str]):
|
||||
captured["env"] = env
|
||||
return subprocess.CompletedProcess(cmd, 0)
|
||||
|
||||
monkeypatch.setattr(wrap_cli.shutil, "which", lambda name: "/usr/bin/droid")
|
||||
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: True)
|
||||
monkeypatch.setattr(
|
||||
wrap_cli, "_query_proxy_health", lambda port: _health({"factory_api_url": FACTORY})
|
||||
)
|
||||
monkeypatch.setattr(wrap_cli, "_push_runtime_env", lambda *a, **kw: None)
|
||||
monkeypatch.setattr(wrap_cli, "_start_proxy", _boom("--no-proxy must not start a proxy"))
|
||||
monkeypatch.setattr(wrap_cli.subprocess, "run", _run)
|
||||
|
||||
result = _invoke(["--port", "8787", "--no-proxy"])
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert captured["env"]["FACTORY_API_BASE_URL"] == "http://127.0.0.1:8787"
|
||||
@@ -0,0 +1,87 @@
|
||||
"""Tests for the Factory Droid runtime helpers behind ``headroom wrap droid``."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
from headroom.providers.droid import (
|
||||
DEFAULT_FACTORY_API_URL,
|
||||
canonical_factory_api_url,
|
||||
proxy_base_url,
|
||||
resolve_factory_upstream,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _no_inherited_factory_env(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.delenv("FACTORY_API_BASE_URL", raising=False)
|
||||
|
||||
|
||||
def test_default_upstream_is_public_factory() -> None:
|
||||
assert DEFAULT_FACTORY_API_URL == "https://api.factory.ai"
|
||||
assert resolve_factory_upstream(None) == DEFAULT_FACTORY_API_URL
|
||||
|
||||
|
||||
def test_env_beats_default(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setenv("FACTORY_API_BASE_URL", "https://eu.factory.example/")
|
||||
assert resolve_factory_upstream(None) == "https://eu.factory.example"
|
||||
|
||||
|
||||
def test_explicit_flag_beats_env(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setenv("FACTORY_API_BASE_URL", "https://eu.factory.example")
|
||||
assert resolve_factory_upstream("https://flag.factory.example") == (
|
||||
"https://flag.factory.example"
|
||||
)
|
||||
|
||||
|
||||
def test_proxy_base_url_is_loopback_without_v1() -> None:
|
||||
assert proxy_base_url(8799) == "http://127.0.0.1:8799"
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("raw", "expected"),
|
||||
[
|
||||
("https://API.Factory.AI", "https://api.factory.ai"),
|
||||
("https://api.factory.ai/", "https://api.factory.ai"),
|
||||
("https://api.factory.ai:443", "https://api.factory.ai"),
|
||||
("http://gw.example:80/", "http://gw.example"),
|
||||
("https://gw.example:8443/factory/", "https://gw.example:8443/factory"),
|
||||
(" https://api.factory.ai ", "https://api.factory.ai"),
|
||||
("https://[2001:db8::1]:8443", "https://[2001:db8::1]:8443"),
|
||||
],
|
||||
)
|
||||
def test_canonicalisation(raw: str, expected: str) -> None:
|
||||
assert canonical_factory_api_url(raw) == expected
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"raw",
|
||||
[
|
||||
# loopback, in every spelling that reaches this host
|
||||
"http://127.0.0.1:8787",
|
||||
"http://localhost:8787",
|
||||
"http://LOCALHOST",
|
||||
"http://x.localhost",
|
||||
"http://[::1]:8787",
|
||||
"http://127.1:8787",
|
||||
"http://0.0.0.0:8787",
|
||||
# credentials, query, fragment
|
||||
"https://user:pw@api.factory.ai",
|
||||
"https://user@api.factory.ai",
|
||||
"https://api.factory.ai?x=1",
|
||||
"https://api.factory.ai#frag",
|
||||
# schemes and malformed values
|
||||
"ftp://api.factory.ai",
|
||||
"file:///etc/passwd",
|
||||
"api.factory.ai",
|
||||
"https://",
|
||||
"https://api.factory.ai:99999",
|
||||
"https://api.factory.ai:notaport",
|
||||
"https://bad_host!.example",
|
||||
"",
|
||||
None,
|
||||
42,
|
||||
],
|
||||
)
|
||||
def test_rejections(raw: object) -> None:
|
||||
assert canonical_factory_api_url(raw) is None
|
||||
@@ -0,0 +1,346 @@
|
||||
"""Local decoy proof for Factory Droid routing, over real sockets.
|
||||
|
||||
Two local HTTP servers stand in for the outside world:
|
||||
|
||||
* a **decoy**, configured as the proxy's Anthropic and OpenAI upstream (and
|
||||
allowlisted as a client-named base), which must stay silent for every
|
||||
Factory-bound request, and
|
||||
* a **Factory stand-in**, configured as ``factory_api_url``, which must
|
||||
receive Droid's inference request and its non-inference REST calls.
|
||||
|
||||
The proxy runs under a real uvicorn server. ``headroom wrap droid --no-proxy``
|
||||
then probes real listeners and either refuses or launches a fake ``droid``
|
||||
executable. Nothing here contacts Factory or needs a Factory token.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import signal
|
||||
import socket
|
||||
import stat
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
from collections.abc import Iterator
|
||||
from dataclasses import dataclass, field
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
pytest.importorskip("fastapi")
|
||||
httpx = pytest.importorskip("httpx")
|
||||
uvicorn = pytest.importorskip("uvicorn")
|
||||
|
||||
from click.testing import CliRunner # noqa: E402
|
||||
|
||||
from headroom.cli.main import main # noqa: E402
|
||||
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
|
||||
|
||||
MESSAGES = "/api/llm/a/v1/messages"
|
||||
UNCONTACTED_FACTORY = "https://factory.invalid"
|
||||
|
||||
|
||||
def _free_port() -> int:
|
||||
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
|
||||
sock.bind(("127.0.0.1", 0))
|
||||
return int(sock.getsockname()[1])
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Seen:
|
||||
method: str
|
||||
path: str
|
||||
headers: dict[str, str]
|
||||
body: bytes
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Upstream:
|
||||
name: str
|
||||
server: ThreadingHTTPServer
|
||||
seen: list[_Seen] = field(default_factory=list)
|
||||
|
||||
@property
|
||||
def url(self) -> str:
|
||||
return f"http://127.0.0.1:{self.server.server_address[1]}"
|
||||
|
||||
|
||||
def _start_upstream(name: str) -> _Upstream:
|
||||
upstream: _Upstream
|
||||
|
||||
class _Handler(BaseHTTPRequestHandler):
|
||||
def _serve(self) -> None:
|
||||
length = int(self.headers.get("content-length") or 0)
|
||||
body = self.rfile.read(length) if length else b""
|
||||
upstream.seen.append(
|
||||
_Seen(
|
||||
self.command,
|
||||
self.path,
|
||||
{k.lower(): v for k, v in self.headers.items()},
|
||||
body,
|
||||
)
|
||||
)
|
||||
if self.path.split("?")[0].endswith("/v1/messages"):
|
||||
reply: dict[str, Any] = {
|
||||
"id": "msg_1",
|
||||
"type": "message",
|
||||
"role": "assistant",
|
||||
"model": "claude-sonnet-4-5",
|
||||
"content": [{"type": "text", "text": f"from {name}"}],
|
||||
"stop_reason": "end_turn",
|
||||
"usage": {"input_tokens": 10, "output_tokens": 3},
|
||||
}
|
||||
else:
|
||||
reply = {"served_by": name, "path": self.path}
|
||||
payload = json.dumps(reply).encode()
|
||||
self.send_response(200)
|
||||
self.send_header("content-type", "application/json")
|
||||
self.send_header("content-length", str(len(payload)))
|
||||
self.end_headers()
|
||||
self.wfile.write(payload)
|
||||
|
||||
do_GET = do_POST = do_PATCH = do_PUT = do_DELETE = _serve
|
||||
|
||||
def log_message(self, *args: Any) -> None:
|
||||
pass
|
||||
|
||||
server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
|
||||
server.daemon_threads = True
|
||||
upstream = _Upstream(name, server)
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
return upstream
|
||||
|
||||
|
||||
class _ProxyThread:
|
||||
def __init__(self, config: ProxyConfig) -> None:
|
||||
self.port = _free_port()
|
||||
config.port = self.port
|
||||
self.server = uvicorn.Server(
|
||||
uvicorn.Config(
|
||||
create_app(config),
|
||||
host="127.0.0.1",
|
||||
port=self.port,
|
||||
log_level="warning",
|
||||
loop="asyncio",
|
||||
lifespan="on",
|
||||
ws="none",
|
||||
)
|
||||
)
|
||||
self.thread = threading.Thread(target=self.server.run, daemon=True)
|
||||
|
||||
@property
|
||||
def url(self) -> str:
|
||||
return f"http://127.0.0.1:{self.port}"
|
||||
|
||||
def start(self) -> None:
|
||||
self.thread.start()
|
||||
deadline = time.perf_counter() + 30.0
|
||||
while time.perf_counter() < deadline:
|
||||
if self.server.started:
|
||||
return
|
||||
time.sleep(0.05)
|
||||
raise RuntimeError("proxy failed to start within 30s")
|
||||
|
||||
def stop(self) -> None:
|
||||
self.server.should_exit = True
|
||||
self.thread.join(timeout=10.0)
|
||||
|
||||
|
||||
def _config(**overrides: Any) -> ProxyConfig:
|
||||
base: dict[str, Any] = {
|
||||
"optimize": True,
|
||||
"cache_enabled": False,
|
||||
"rate_limit_enabled": False,
|
||||
"cost_tracking_enabled": False,
|
||||
"log_requests": False,
|
||||
}
|
||||
base.update(overrides)
|
||||
return ProxyConfig(**base)
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Stack:
|
||||
decoy: _Upstream
|
||||
factory: _Upstream
|
||||
factory_proxy: _ProxyThread
|
||||
plain_proxy: _ProxyThread
|
||||
uncontacted_factory_proxy: _ProxyThread
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def stack(monkeypatch: pytest.MonkeyPatch, tmp_path) -> Iterator[_Stack]:
|
||||
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
|
||||
# Allowlist the loopback decoy as a client-named base, so a spoofed
|
||||
# x-headroom-base-url pointing at it would pass the SSRF guard if it were
|
||||
# honoured. The decoy staying silent then proves the route ignores it.
|
||||
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "127.0.0.1")
|
||||
for name in ("FACTORY_API_BASE_URL", "FACTORY_TARGET_API_URL"):
|
||||
monkeypatch.delenv(name, raising=False)
|
||||
saved_signals = {
|
||||
sig: signal.getsignal(sig)
|
||||
for sig in (signal.SIGINT, signal.SIGTERM, getattr(signal, "SIGHUP", None))
|
||||
if sig is not None
|
||||
}
|
||||
|
||||
decoy = _start_upstream("decoy")
|
||||
factory = _start_upstream("factory")
|
||||
# Provider targets are process-wide, so every in-process proxy gets the
|
||||
# decoy; otherwise the last one created would reset them to the public
|
||||
# defaults and stray traffic would leave the machine.
|
||||
decoy_targets = {"anthropic_api_url": decoy.url, "openai_api_url": decoy.url}
|
||||
proxies = [
|
||||
_ProxyThread(_config(factory_api_url=factory.url, **decoy_targets)),
|
||||
_ProxyThread(_config(**decoy_targets)),
|
||||
_ProxyThread(_config(factory_api_url=UNCONTACTED_FACTORY, **decoy_targets)),
|
||||
]
|
||||
try:
|
||||
for proxy in proxies:
|
||||
proxy.start()
|
||||
yield _Stack(decoy, factory, *proxies)
|
||||
finally:
|
||||
for proxy in proxies:
|
||||
proxy.stop()
|
||||
decoy.server.shutdown()
|
||||
factory.server.shutdown()
|
||||
for sig, handler in saved_signals.items():
|
||||
signal.signal(sig, handler)
|
||||
|
||||
|
||||
def test_inference_reaches_factory_stand_in_and_decoy_stays_silent(stack: _Stack) -> None:
|
||||
body = {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"max_tokens": 16,
|
||||
"messages": [{"role": "user", "content": "lorem ipsum dolor " * 400}],
|
||||
}
|
||||
response = httpx.post(
|
||||
f"{stack.factory_proxy.url}{MESSAGES}",
|
||||
headers={
|
||||
"authorization": "Bearer fk-local-dummy",
|
||||
"anthropic-version": "2023-06-01",
|
||||
# Spoofed Headroom control headers: none may redirect the request.
|
||||
"x-headroom-base-url": stack.decoy.url,
|
||||
"x-headroom-provider": "openai",
|
||||
"x-headroom-target": stack.decoy.url,
|
||||
},
|
||||
json=body,
|
||||
timeout=60,
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
assert response.json()["content"][0]["text"] == "from factory"
|
||||
assert stack.decoy.seen == []
|
||||
[seen] = stack.factory.seen
|
||||
assert (seen.method, seen.path) == ("POST", MESSAGES)
|
||||
assert seen.headers["authorization"] == "Bearer fk-local-dummy"
|
||||
assert not [k for k in seen.headers if k.startswith("x-headroom-")]
|
||||
|
||||
|
||||
def test_non_inference_factory_paths_pass_through(stack: _Stack) -> None:
|
||||
get = httpx.get(
|
||||
f"{stack.factory_proxy.url}/api/sessions?limit=5",
|
||||
headers={"authorization": "Bearer fk-local-dummy"},
|
||||
timeout=30,
|
||||
)
|
||||
patch = httpx.patch(
|
||||
f"{stack.factory_proxy.url}/api/sessions/s1",
|
||||
headers={"authorization": "Bearer fk-local-dummy"},
|
||||
content=b'{"title":"x"}',
|
||||
timeout=30,
|
||||
)
|
||||
|
||||
assert get.json() == {"served_by": "factory", "path": "/api/sessions?limit=5"}
|
||||
assert patch.json()["served_by"] == "factory"
|
||||
assert [(s.method, s.path) for s in stack.factory.seen] == [
|
||||
("GET", "/api/sessions?limit=5"),
|
||||
("PATCH", "/api/sessions/s1"),
|
||||
]
|
||||
assert stack.factory.seen[1].body == b'{"title":"x"}'
|
||||
assert stack.decoy.seen == []
|
||||
|
||||
|
||||
def test_unmatched_traffic_never_reaches_factory(stack: _Stack) -> None:
|
||||
unrouted = httpx.get(
|
||||
f"{stack.factory_proxy.url}/totally/unrouted",
|
||||
headers={"authorization": "Bearer sk-other-tool"},
|
||||
timeout=30,
|
||||
)
|
||||
hermes = httpx.post(
|
||||
f"{stack.factory_proxy.url}/api/codex-proxy/s1/v1/responses",
|
||||
headers={"authorization": "Bearer sk-hermes"},
|
||||
json={"model": "gpt-4o-mini", "input": "hi"},
|
||||
timeout=30,
|
||||
)
|
||||
|
||||
assert unrouted.json()["served_by"] == "decoy"
|
||||
assert hermes.json()["served_by"] == "decoy"
|
||||
assert stack.factory.seen == []
|
||||
assert [s.path for s in stack.decoy.seen] == [
|
||||
"/totally/unrouted",
|
||||
"/api/codex-proxy/s1/v1/responses",
|
||||
]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def fake_droid(tmp_path, monkeypatch: pytest.MonkeyPatch):
|
||||
record = tmp_path / "droid-env.txt"
|
||||
bin_dir = tmp_path / "bin"
|
||||
bin_dir.mkdir()
|
||||
script = bin_dir / "droid"
|
||||
script.write_text(f'#!/bin/sh\nprintf "%s" "$FACTORY_API_BASE_URL" > "{record}"\n')
|
||||
script.chmod(script.stat().st_mode | stat.S_IXUSR)
|
||||
if sys.platform == "win32":
|
||||
# `shutil.which("droid")` ignores the extensionless script on Windows
|
||||
# but finds `droid.cmd` via PATHEXT. Python does the write so the
|
||||
# record has no trailing newline, matching `printf "%s"`.
|
||||
write = (
|
||||
"import os, pathlib, sys; "
|
||||
"pathlib.Path(sys.argv[1]).write_text(os.environ.get('FACTORY_API_BASE_URL', ''))"
|
||||
)
|
||||
(bin_dir / "droid.cmd").write_bytes(
|
||||
f'@echo off\r\n"{sys.executable}" -c "{write}" "{record}"\r\n'.encode()
|
||||
)
|
||||
monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ.get('PATH', '')}")
|
||||
return record
|
||||
|
||||
|
||||
def _wrap_droid_no_proxy(port: int, upstream: str):
|
||||
return CliRunner().invoke(
|
||||
main,
|
||||
["wrap", "droid", "--no-proxy", "--port", str(port), "--factory-api-url", upstream],
|
||||
)
|
||||
|
||||
|
||||
def test_no_proxy_refuses_non_factory_listener(stack: _Stack, fake_droid) -> None:
|
||||
result = _wrap_droid_no_proxy(stack.plain_proxy.port, UNCONTACTED_FACTORY)
|
||||
|
||||
assert result.exit_code != 0
|
||||
assert "--no-proxy requires a Headroom proxy" in result.output
|
||||
assert not fake_droid.exists()
|
||||
|
||||
|
||||
def test_no_proxy_refuses_mismatched_factory_listener(stack: _Stack, fake_droid) -> None:
|
||||
result = _wrap_droid_no_proxy(
|
||||
stack.uncontacted_factory_proxy.port, "https://eu.factory.example"
|
||||
)
|
||||
|
||||
assert result.exit_code != 0
|
||||
assert "--no-proxy requires a Headroom proxy" in result.output
|
||||
assert not fake_droid.exists()
|
||||
|
||||
|
||||
def test_no_proxy_refuses_absent_listener(stack: _Stack, fake_droid) -> None:
|
||||
result = _wrap_droid_no_proxy(_free_port(), UNCONTACTED_FACTORY)
|
||||
|
||||
assert result.exit_code != 0
|
||||
assert not fake_droid.exists()
|
||||
|
||||
|
||||
def test_no_proxy_launches_against_matching_listener(stack: _Stack, fake_droid) -> None:
|
||||
port = stack.uncontacted_factory_proxy.port
|
||||
result = _wrap_droid_no_proxy(port, f"{UNCONTACTED_FACTORY}/")
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert fake_droid.read_text() == f"http://127.0.0.1:{port}"
|
||||
@@ -0,0 +1,531 @@
|
||||
"""Tests for the Factory Droid routes registered when ``factory_api_url`` is set.
|
||||
|
||||
``headroom wrap droid`` points Droid's ``FACTORY_API_BASE_URL`` at the proxy.
|
||||
With a Factory upstream configured, the proxy:
|
||||
|
||||
1. compresses ``POST /api/llm/a/v1/messages`` and forwards it to
|
||||
``{factory}/api/llm/a/v1/messages`` (never to a client-named base);
|
||||
2. forwards every other ``/api/*`` request verbatim to the Factory upstream,
|
||||
except Hermes Studio's scoped prefixes and requests that name their own
|
||||
``x-headroom-base-url``, which keep the normal catch-all behaviour;
|
||||
3. never sends traffic outside ``/api/*`` to Factory (the leak guard).
|
||||
|
||||
Forwarding is intercepted with ``respx`` so no real upstream is contacted.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import runpy
|
||||
import sys
|
||||
from typing import Any
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
from urllib.parse import urlsplit
|
||||
|
||||
import pytest
|
||||
|
||||
fastapi = pytest.importorskip("fastapi")
|
||||
httpx = pytest.importorskip("httpx")
|
||||
respx = pytest.importorskip("respx")
|
||||
|
||||
from fastapi.testclient import TestClient # noqa: E402
|
||||
|
||||
from headroom.proxy.loopback_guard import require_loopback # noqa: E402
|
||||
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
|
||||
|
||||
UPSTREAM = "https://factory.example"
|
||||
UPSTREAM_HOST = "factory.example"
|
||||
GATEWAY = "https://gateway.example"
|
||||
MESSAGES = "/api/llm/a/v1/messages"
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def _allow_reserved_test_upstream(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
"""Admit the reserved, intentionally unresolvable client-named gateway."""
|
||||
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "gateway.example")
|
||||
monkeypatch.delenv("FACTORY_TARGET_API_URL", raising=False)
|
||||
|
||||
|
||||
class _FakeResult:
|
||||
"""Stand-in for TransformPipeline.apply's TransformResult."""
|
||||
|
||||
def __init__(self, messages: list[dict], tokens_before: int, tokens_after: int) -> None:
|
||||
self.messages = messages
|
||||
self.tokens_before = tokens_before
|
||||
self.tokens_after = tokens_after
|
||||
self.transforms_applied = ["smartcrush"]
|
||||
self.timing = {"total": 1.0}
|
||||
|
||||
|
||||
def _make_config(**overrides: Any) -> ProxyConfig:
|
||||
base: dict[str, Any] = {
|
||||
"factory_api_url": UPSTREAM,
|
||||
"optimize": True,
|
||||
"cache_enabled": False,
|
||||
"rate_limit_enabled": False,
|
||||
"cost_tracking_enabled": False,
|
||||
"log_requests": False,
|
||||
"mode": "token",
|
||||
}
|
||||
base.update(overrides)
|
||||
return ProxyConfig(**base)
|
||||
|
||||
|
||||
def _make_app(**overrides: Any):
|
||||
app = create_app(_make_config(**overrides))
|
||||
app.dependency_overrides[require_loopback] = lambda: None
|
||||
return app
|
||||
|
||||
|
||||
def _anthropic_reply() -> dict[str, Any]:
|
||||
return {
|
||||
"id": "msg_1",
|
||||
"type": "message",
|
||||
"role": "assistant",
|
||||
"model": "claude-sonnet-4-5",
|
||||
"content": [{"type": "text", "text": "ok"}],
|
||||
"stop_reason": "end_turn",
|
||||
"usage": {"input_tokens": 10, "output_tokens": 1},
|
||||
}
|
||||
|
||||
|
||||
# Hosts the proxy contacts on its own at startup (pricing table fetch,
|
||||
# subscription usage poll with the machine's own credentials); unrelated to
|
||||
# the request under test.
|
||||
_BACKGROUND_HOSTS = frozenset({"raw.githubusercontent.com", "api.anthropic.com"})
|
||||
|
||||
|
||||
class _Recorder:
|
||||
"""Capture every upstream request the proxy makes, on any host."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.requests: list[httpx.Request] = []
|
||||
|
||||
def __call__(self, request: httpx.Request) -> httpx.Response:
|
||||
self.requests.append(request)
|
||||
if request.url.path.endswith("/v1/messages"):
|
||||
return httpx.Response(200, json=_anthropic_reply())
|
||||
return httpx.Response(200, json={"ok": True, "path": request.url.path})
|
||||
|
||||
def to_host(self, host: str) -> list[httpx.Request]:
|
||||
return [r for r in self.requests if r.url.host == host]
|
||||
|
||||
def proxied(self) -> list[httpx.Request]:
|
||||
"""Requests forwarded on a client's behalf, minus proxy startup polls."""
|
||||
return [r for r in self.requests if r.url.host not in _BACKGROUND_HOSTS]
|
||||
|
||||
def only(self, path: str) -> httpx.Request:
|
||||
hits = [r for r in self.requests if r.url.path == path]
|
||||
assert len(hits) == 1, [str(r.url) for r in self.requests]
|
||||
return hits[0]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def recorder():
|
||||
rec = _Recorder()
|
||||
with respx.mock(assert_all_called=False) as router:
|
||||
router.route().mock(side_effect=rec)
|
||||
yield rec
|
||||
|
||||
|
||||
def _big_messages_body() -> dict[str, Any]:
|
||||
return {
|
||||
"model": "claude-sonnet-4-5",
|
||||
"max_tokens": 16,
|
||||
"messages": [{"role": "user", "content": "lorem ipsum " * 600}],
|
||||
}
|
||||
|
||||
|
||||
# ── route gating ──────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _paths(cfg: ProxyConfig) -> list[str]:
|
||||
return [r.path for r in create_app(cfg).routes if hasattr(r, "path")]
|
||||
|
||||
|
||||
def test_routes_absent_when_factory_api_url_unset():
|
||||
paths = _paths(ProxyConfig())
|
||||
assert MESSAGES not in paths
|
||||
assert "/api/{path:path}" not in paths
|
||||
|
||||
|
||||
def test_routes_present_and_ordered_before_catch_all():
|
||||
paths = _paths(_make_config())
|
||||
assert MESSAGES in paths
|
||||
assert "/api/{path:path}" in paths
|
||||
assert paths.index(MESSAGES) < paths.index("/api/{path:path}")
|
||||
assert paths.index("/api/{path:path}") < paths.index("/{path:path}")
|
||||
|
||||
|
||||
# ── inference route ───────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_messages_route_compresses_and_reaches_factory(recorder):
|
||||
app = _make_app()
|
||||
with TestClient(app) as client:
|
||||
proxy = client.app.state.proxy
|
||||
proxy._record_request_outcome = AsyncMock()
|
||||
compressed = [{"role": "user", "content": "compressed"}]
|
||||
proxy.anthropic_pipeline.apply = MagicMock(return_value=_FakeResult(compressed, 900, 100))
|
||||
response = client.post(
|
||||
MESSAGES,
|
||||
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
|
||||
json=_big_messages_body(),
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
sent = recorder.only(MESSAGES)
|
||||
assert str(sent.url) == f"{UPSTREAM}{MESSAGES}"
|
||||
assert sent.headers["authorization"] == "Bearer fk-test"
|
||||
assert json.loads(sent.content)["messages"] == compressed
|
||||
assert proxy.anthropic_pipeline.apply.called
|
||||
outcome = proxy._record_request_outcome.await_args.args[0]
|
||||
assert outcome.provider == "factory"
|
||||
|
||||
|
||||
def test_messages_route_bypasses_configured_backend_and_route_advice(recorder):
|
||||
"""A translating backend (HEADROOM_BACKEND=bedrock, route advice) must not
|
||||
swallow Factory inference: the route never consults the resolver."""
|
||||
from headroom.backends.base import BackendResponse
|
||||
from headroom.proxy.route_advice import BackendResolver
|
||||
|
||||
backend_calls: list[Any] = []
|
||||
|
||||
class _SentinelBackend:
|
||||
name = "sentinel"
|
||||
|
||||
async def send_message(self, body: dict, headers: dict) -> BackendResponse:
|
||||
backend_calls.append(body)
|
||||
return BackendResponse(body={"error": "teapot"}, status_code=418)
|
||||
|
||||
resolver_calls: list[Any] = []
|
||||
|
||||
def _no_resolver(self: Any, request: Any, **kwargs: Any) -> Any:
|
||||
resolver_calls.append(request)
|
||||
raise AssertionError("Factory route consulted the backend resolver")
|
||||
|
||||
app = _make_app()
|
||||
with (
|
||||
TestClient(app) as client,
|
||||
patch.object(BackendResolver, "for_request", _no_resolver),
|
||||
):
|
||||
proxy = client.app.state.proxy
|
||||
proxy.anthropic_backend = _SentinelBackend()
|
||||
compressed = [{"role": "user", "content": "compressed"}]
|
||||
proxy.anthropic_pipeline.apply = MagicMock(return_value=_FakeResult(compressed, 900, 100))
|
||||
response = client.post(
|
||||
MESSAGES,
|
||||
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
|
||||
json=_big_messages_body(),
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
assert backend_calls == []
|
||||
assert resolver_calls == []
|
||||
sent = recorder.only(MESSAGES)
|
||||
assert sent.url.host == UPSTREAM_HOST
|
||||
assert json.loads(sent.content)["messages"] == compressed
|
||||
assert proxy.anthropic_pipeline.apply.called
|
||||
|
||||
|
||||
def test_spoofed_headroom_headers_do_not_redirect_inference(recorder):
|
||||
app = _make_app()
|
||||
with TestClient(app) as client:
|
||||
response = client.post(
|
||||
MESSAGES,
|
||||
headers={
|
||||
"authorization": "Bearer fk-test",
|
||||
"anthropic-version": "2023-06-01",
|
||||
"x-headroom-base-url": "http://evil.example",
|
||||
"x-headroom-provider": "openai",
|
||||
"x-headroom-bypass": "true",
|
||||
},
|
||||
json=_big_messages_body(),
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
assert [r.url.host for r in recorder.proxied()] == [UPSTREAM_HOST]
|
||||
assert not recorder.to_host("evil.example")
|
||||
sent = recorder.only(MESSAGES)
|
||||
assert not [k for k in sent.headers if k.lower().startswith("x-headroom-")]
|
||||
assert sent.headers["authorization"] == "Bearer fk-test"
|
||||
|
||||
|
||||
def test_operator_extra_headers_withheld_from_factory(recorder):
|
||||
app = _make_app(anthropic_extra_headers={"x-gateway-secret": "s3cret"})
|
||||
with TestClient(app) as client:
|
||||
response = client.post(
|
||||
MESSAGES,
|
||||
headers={"authorization": "Bearer fk-test", "anthropic-version": "2023-06-01"},
|
||||
json=_big_messages_body(),
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
sent = recorder.only(MESSAGES)
|
||||
assert "x-gateway-secret" not in {k.lower() for k in sent.headers}
|
||||
|
||||
|
||||
# ── REST passthrough ──────────────────────────────────────────────────
|
||||
|
||||
|
||||
def test_rest_get_passes_through_with_query_and_auth(recorder):
|
||||
app = _make_app()
|
||||
with TestClient(app) as client:
|
||||
response = client.get(
|
||||
"/api/sessions?limit=5",
|
||||
headers={"authorization": "Bearer fk-test"},
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
sent = recorder.only("/api/sessions")
|
||||
assert str(sent.url) == f"{UPSTREAM}/api/sessions?limit=5"
|
||||
assert sent.headers["authorization"] == "Bearer fk-test"
|
||||
|
||||
|
||||
def test_rest_patch_passes_through_byte_identical(recorder):
|
||||
app = _make_app()
|
||||
payload = b'{"title":"renamed"}'
|
||||
with TestClient(app) as client:
|
||||
response = client.patch(
|
||||
"/api/sessions/s1",
|
||||
headers={"authorization": "Bearer fk-test", "content-type": "application/json"},
|
||||
content=payload,
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
sent = recorder.only("/api/sessions/s1")
|
||||
assert sent.method == "PATCH"
|
||||
assert sent.url.host == UPSTREAM_HOST
|
||||
assert sent.content == payload
|
||||
|
||||
|
||||
def test_responses_passthrough_stays_verbatim_with_compress_passthrough(recorder):
|
||||
"""`compress_passthrough` must not rewrite Droid's OpenAI-shaped traffic."""
|
||||
app = _make_app(compress_passthrough=True)
|
||||
payload = b'{"model":"gpt-5","input":"' + b"lorem ipsum " * 600 + b'"}'
|
||||
with TestClient(app) as client:
|
||||
proxy = client.app.state.proxy
|
||||
proxy._maybe_compress_passthrough_responses = AsyncMock(return_value=b'{"rewritten":1}')
|
||||
response = client.post(
|
||||
"/api/llm/o/v1/responses",
|
||||
headers={"authorization": "Bearer fk-test", "content-type": "application/json"},
|
||||
content=payload,
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
proxy._maybe_compress_passthrough_responses.assert_not_called()
|
||||
sent = recorder.only("/api/llm/o/v1/responses")
|
||||
assert sent.url.host == UPSTREAM_HOST
|
||||
assert sent.content == payload
|
||||
|
||||
|
||||
def test_compress_passthrough_still_applies_to_unrelated_catch_all(recorder):
|
||||
"""Control: without Factory, the generic catch-all still compresses."""
|
||||
app = create_app(
|
||||
ProxyConfig(
|
||||
optimize=True,
|
||||
compress_passthrough=True,
|
||||
cache_enabled=False,
|
||||
rate_limit_enabled=False,
|
||||
log_requests=False,
|
||||
)
|
||||
)
|
||||
app.dependency_overrides[require_loopback] = lambda: None
|
||||
path = "/api/llm/o/v1/responses"
|
||||
with TestClient(app) as client:
|
||||
proxy = client.app.state.proxy
|
||||
proxy._maybe_compress_passthrough_responses = AsyncMock(return_value=b'{"rewritten":1}')
|
||||
response = client.post(
|
||||
path,
|
||||
headers={"authorization": "Bearer sk-x", "content-type": "application/json"},
|
||||
content=b'{"model":"gpt-5","input":"hi"}',
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
proxy._maybe_compress_passthrough_responses.assert_awaited_once()
|
||||
sent = recorder.only(path)
|
||||
assert sent.url.host != UPSTREAM_HOST
|
||||
assert sent.content == b'{"rewritten":1}'
|
||||
|
||||
|
||||
# ── leak guard: unmatched traffic must never go to Factory ────────────
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("method", "path", "headers", "expected_host"),
|
||||
[
|
||||
("GET", "/backend-api/me", {"chatgpt-account-id": "acct"}, "chatgpt.com"),
|
||||
("POST", "/v1/engines/x/completions", {"authorization": "Bearer tid_fake_copilot"}, None),
|
||||
(
|
||||
"POST",
|
||||
"/v1beta/models/m:generateContent",
|
||||
{"x-goog-api-key": "g-key"},
|
||||
"generativelanguage.googleapis.com",
|
||||
),
|
||||
(
|
||||
"POST",
|
||||
"/api/codex-proxy/s1/v1/responses",
|
||||
{"authorization": "Bearer sk-hermes"},
|
||||
"api.openai.com",
|
||||
),
|
||||
(
|
||||
"POST",
|
||||
"/api/codex-proxy/s1/other",
|
||||
{"authorization": "Bearer sk-hermes"},
|
||||
"api.openai.com",
|
||||
),
|
||||
(
|
||||
"POST",
|
||||
"/api/claude-code-proxy/s1/v1/messages",
|
||||
{"authorization": "Bearer sk-hermes", "x-headroom-base-url": GATEWAY},
|
||||
"gateway.example",
|
||||
),
|
||||
(
|
||||
"GET",
|
||||
"/api/anything",
|
||||
{"authorization": "Bearer other", "x-headroom-base-url": GATEWAY},
|
||||
"gateway.example",
|
||||
),
|
||||
("GET", "/totally/unrouted", {"authorization": "Bearer sk-x"}, "api.openai.com"),
|
||||
],
|
||||
)
|
||||
def test_non_factory_traffic_never_reaches_factory(
|
||||
recorder, method: str, path: str, headers: dict[str, str], expected_host: str | None
|
||||
):
|
||||
app = _make_app()
|
||||
with TestClient(app) as client:
|
||||
body = {"model": "m", "input": "hi"} if method == "POST" else None
|
||||
client.request(method, path, headers=headers, json=body)
|
||||
|
||||
forwarded = [r for r in recorder.requests if urlsplit(str(r.url)).path.endswith(path)]
|
||||
assert forwarded, [str(r.url) for r in recorder.requests]
|
||||
assert not recorder.to_host(UPSTREAM_HOST), [str(r.url) for r in recorder.requests]
|
||||
if expected_host is not None:
|
||||
assert forwarded[0].url.host == expected_host
|
||||
|
||||
|
||||
def test_unsafe_client_base_on_api_path_is_still_rejected(recorder):
|
||||
app = _make_app()
|
||||
with TestClient(app) as client:
|
||||
response = client.get(
|
||||
"/api/anything",
|
||||
headers={"x-headroom-base-url": "http://169.254.169.254"},
|
||||
)
|
||||
|
||||
assert response.status_code == 400
|
||||
assert recorder.proxied() == []
|
||||
|
||||
|
||||
# ── guard: unchanged behaviour without Factory configured ─────────────
|
||||
|
||||
|
||||
def test_without_factory_messages_path_falls_through_to_catch_all(recorder):
|
||||
app = create_app(
|
||||
ProxyConfig(
|
||||
optimize=True, cache_enabled=False, rate_limit_enabled=False, log_requests=False
|
||||
)
|
||||
)
|
||||
app.dependency_overrides[require_loopback] = lambda: None
|
||||
with TestClient(app) as client:
|
||||
response = client.post(
|
||||
MESSAGES,
|
||||
headers={"authorization": "Bearer fk-test"},
|
||||
json=_big_messages_body(),
|
||||
)
|
||||
|
||||
assert response.status_code == 200, response.text
|
||||
sent = recorder.only(MESSAGES)
|
||||
assert sent.url.host != UPSTREAM_HOST
|
||||
assert sent.url.host == "api.openai.com"
|
||||
|
||||
|
||||
# ── config plumbing ───────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _loopback_client(app) -> TestClient:
|
||||
return TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
|
||||
|
||||
|
||||
def test_health_reports_factory_api_url():
|
||||
app = _make_app()
|
||||
with _loopback_client(app) as client:
|
||||
payload = client.get("/health").json()
|
||||
assert payload["config"]["factory_api_url"] == UPSTREAM
|
||||
|
||||
|
||||
def test_health_reports_none_without_factory():
|
||||
app = create_app(ProxyConfig())
|
||||
with _loopback_client(app) as client:
|
||||
payload = client.get("/health").json()
|
||||
assert payload["config"]["factory_api_url"] is None
|
||||
|
||||
|
||||
def test_env_var_feeds_config(monkeypatch):
|
||||
from headroom.proxy.server import _proxy_config_from_env
|
||||
|
||||
monkeypatch.delenv("HEADROOM_PROXY_CONFIG_JSON", raising=False)
|
||||
monkeypatch.setenv("FACTORY_TARGET_API_URL", UPSTREAM)
|
||||
assert _proxy_config_from_env().factory_api_url == UPSTREAM
|
||||
|
||||
|
||||
class _Captured(Exception):
|
||||
pass
|
||||
|
||||
|
||||
def test_standalone_argparse_flag_feeds_config(monkeypatch):
|
||||
"""``python -m headroom.proxy.server --factory-api-url`` populates ProxyConfig."""
|
||||
from headroom.proxy import models
|
||||
|
||||
real = models.ProxyConfig
|
||||
seen: dict[str, Any] = {}
|
||||
|
||||
def _capture(*args: Any, **kwargs: Any):
|
||||
if "factory_api_url" in kwargs:
|
||||
seen.update(kwargs)
|
||||
raise _Captured
|
||||
return real(*args, **kwargs)
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["server", "--factory-api-url", UPSTREAM])
|
||||
monkeypatch.setattr(models, "ProxyConfig", _capture)
|
||||
with pytest.raises(_Captured):
|
||||
runpy.run_module("headroom.proxy.server", run_name="__main__")
|
||||
assert seen["factory_api_url"] == UPSTREAM
|
||||
|
||||
|
||||
def test_cli_proxy_flag_feeds_config():
|
||||
from click.testing import CliRunner
|
||||
|
||||
from headroom.cli.main import main
|
||||
|
||||
captured: dict[str, Any] = {}
|
||||
|
||||
def _run_server(config, **kwargs):
|
||||
captured["config"] = config
|
||||
|
||||
with patch("headroom.proxy.server.run_server", _run_server):
|
||||
result = CliRunner().invoke(
|
||||
main, ["proxy", "--factory-api-url", UPSTREAM], catch_exceptions=False
|
||||
)
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert captured["config"].factory_api_url == UPSTREAM
|
||||
assert "Factory Droid" in result.output
|
||||
|
||||
|
||||
def test_cli_proxy_env_feeds_config():
|
||||
from click.testing import CliRunner
|
||||
|
||||
from headroom.cli.main import main
|
||||
|
||||
captured: dict[str, Any] = {}
|
||||
|
||||
def _run_server(config, **kwargs):
|
||||
captured["config"] = config
|
||||
|
||||
with patch("headroom.proxy.server.run_server", _run_server):
|
||||
result = CliRunner().invoke(
|
||||
main, ["proxy"], env={"FACTORY_TARGET_API_URL": UPSTREAM}, catch_exceptions=False
|
||||
)
|
||||
|
||||
assert result.exit_code == 0, result.output
|
||||
assert captured["config"].factory_api_url == UPSTREAM
|
||||
Reference in New Issue
Block a user