Files
headroom/tests/test_header_isolation.py
Mansurshakh JaparovandJD Davis 9553d4292f fix(cache): retain prefix trackers for the provider cache lifetime (#4023)
## Description

Session cleanup currently drops prefix trackers after the default
600-second session lifetime even when Anthropic's request selects a
one-hour cache TTL. Losing the tracker also loses the frozen forwarded
prefix and causes the cache-preserving overlay to replay different
bytes.

Closes #4017.

## Type of Change

- [x] Bug fix
- [x] Documentation update

## Changes Made

- Resolve the request's existing Anthropic cache TTL before selecting
the prefix lineage and pass that TTL through tracker selection/creation.
- Retain each lineage for the greater of the configured session floor
and its observed/current provider TTL plus the existing 60-second safety
margin.
- Keep the lifetime per lineage rather than changing global
configuration: a five-minute session does not inherit another session's
one-hour lifetime.
- Preserve normal expiry beyond the provider lifetime and margin.
- Honor configured cache TTL before a confirmed cache write; discard
expired state before accepting a later request's longer TTL.
- Re-register the live lineage family after lookup/cleanup so recreated
sessions cannot share a tracker's frozen state across sibling
conversations or tool profiles.
- Update existing fake callbacks to the changed tracker contract,
preserve all consumer byte-stability assertions, and remove one
handler-to-store wiring-only test rather than re-pinning its internal
identity assertions.
- Document local tracker retention separately from provider cache
availability.

## Testing

- [x] Unit tests pass (`pytest`), including frozen-prefix byte stability
and independent TTL expiry.
- [x] Changed-file lint, configured pre-commit mypy and manual
production timestamp/overlay checks pass.

### Test Output

```text
Review correction: 273 passed, 2 dependency warnings in 83.79s
{"expires_beyond_provider_ttl_and_margin": true, "five_minute_session_evicted": true, "forwarded_prefix_byte_exact": true, "initial_frozen": 1, "one_hour_session_retained": true, "resolved_ttl_seconds": 3600, "resumed_frozen": 1, "same_tracker_after_660s": true}
```

The mandatory pre-push `make ci-precheck` passed: workspace Rust
fmt/clippy/tests, native extension build/import verification, the
complete configured Python gate, and Commitlint. The native gate
explicitly used the installed CPU `libonnxruntime.so.1.26.0` via
`ORT_DYLIB_PATH`, without skipping cached-model assertions.

```text
[build_rust_extension] headroom._core build + install + verify: OK
================== 177 passed, 4 skipped, 1 warning in 12.87s ==================
✅ ci-precheck PASSED — safe to push.
```

```sh
python -m pytest -q tests/test_cache/test_prefix_tracker.py
python -m pytest -q tests/test_proxy_anthropic_cache_stability.py tests/test_cache_prefix_overlay.py tests/test_cache_ttl_preserved.py tests/test_cold_prefix.py
```

**74 passed** in tracker tests; **54 passed** in request/cache tests
(one existing Starlette TestClient deprecation warning). Two new
regressions fail on baseline because the request TTL is not accepted; a
separate production runtime comparison demonstrates the actual pre-fix
loss, not just the missing parameter.

After rebasing onto current main
`1ad92f0cbc3dea27676e253588100f64a2af6994`, ran those suites together
with `tests/test_prefix_tracker_client_rewrote_reply.py`,
`tests/test_cache_mode_delta_marker.py`, and
`tests/test_content_router_mcp_small_result.py`: **150 passed**. The
actual production timestamp/byte-retention smoke was repeated
successfully on the rebased code, covering compatibility with main's
newly merged client-reply normalization.

Review regression and affected HTTP-consumer suite: **273 passed**,
including tracker expiry, Anthropic/OpenAI cache stability,
byte-faithful forwarding, header isolation, buffered timeouts, CCR
injection, and immutable system prompts. All affected two-argument test
callbacks now accept the TTL contract. The obsolete walker-call-order
test was removed; wire-byte assertions remain. The new
configured-TTL/expiry cases fail against the published baseline; the
post-cleanup regression also verifies that an unrelated conversation
gets a different tracker after recreation.

Changed-file Ruff, formatting, installed pre-commit `mypy headroom`, and
Commitlint hooks passed. Full-tree Ruff is locally blocked by executable
filesystem permissions on five unchanged OAuth2 plugin files (tracked
100644). A separate full dev-environment mypy run found an unchanged
optional LangChain `truthy-function` error; the configured isolated
pre-commit hook passed. No unrelated source/permissions changed.

## Real Behavior Proof

- Environment: Linux x86_64, CPython 3.13.14; unchanged
`dea9092e19385f286b7f67a64f4d85de2708d756` and this branch; real
`SessionTrackerStore`, `PrefixCacheTracker`, request TTL parser, token
estimator and `overlay_cached_prefix`, no mocked store or mocked clock.
- Exact command / steps: parse `cache_control: {type: ephemeral, ttl:
1h}` for `claude-sonnet-4-5`; establish one real cache-write-confirmed
frozen message with different original/forwarded prefix bytes; age
`_last_activity` to `time.time()-660` and make periodic cleanup due;
resume the same lineage and compare the tracker, frozen count, and
forwarded-prefix bytes. Also age beyond 3901 seconds and compare
independent 300/3600-second sessions.
- Before: resolved TTL 3600; after 660 seconds, tracker identity
changes, frozen count drops **1→0**, and forwarded-prefix bytes differ.
- Observed result: after the fix, after 660 seconds the same tracker
remains, frozen count stays **1**, and forwarded-prefix bytes are
identical. The one-hour session survives independently, the five-minute
session expires, and the one-hour lineage still expires beyond TTL plus
margin.
- Review runtime proof against published head `e1a107df`: actual stores
and prefix overlays confirm configured TTL retention before the first
cache write, no resurrection of expired state by a later one-hour
request, eventual expiry, and separate trackers after the maintainer's
3901-second cleanup/recreation sequence. On that exact baseline the
unrelated lookup reuses the wrong tracker, although the overlay guard
preserves the particular unrelated input bytes; after the fix both
identity isolation and byte preservation hold. Identical messages under
different tool profiles also receive a cold, separate tracker after the
expired bare-key transition.
- Not tested: Anthropic cloud cache availability, billed savings, or an
actual one-hour wait. The local production state and byte invariants
were exercised by aging actual timestamps, not by a paid upstream
request. Preserving a tracker cannot guarantee that the provider retains
its cache.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; repair of existing TTL-aware
cache-prefix behavior.
- Minimum rollout channel: stable; no rollout-managed feature is
enabled.
- Stable/default behavior changed: eligible local prefix trackers
survive for their provider cache lifetime. Short-TTL/default sessions
remain bounded by their own session floor.
- Kill switch / disable path: the existing prefix-freeze disable path
remains available; no new flag.
- Unsafe override required: no.
- Qualification impact: local Anthropic prefix lineage
selection/retention, not cache pricing or subscription quota policy.
- Rollback path: revert the commit to restore previous retention. No
persistent schema change.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] Existing cache TTL parser and safety margin reused; cache docs
updated.
- [x] Regressions cover frozen-byte retention, expiry, mixed lifetimes,
and existing request byte-stability behavior.
- [x] `CHANGELOG.md` not edited; Conventional Commit title supplied.

Remote CI results are not inferred from local verification.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-07 17:46:21 -05:00

681 lines
24 KiB
Python

"""Header-isolation tests for PR-A5 (P5-49 fix).
`x-headroom-*` request headers are internal control flags consumed by the
proxy itself (bypass gating, mode selection, user-id, stack/base-url
fingerprints). Forwarding them upstream:
1. Fingerprints the proxy to subscription-revocation enforcers.
2. Leaks user-id / stack / base-url internals to whichever vendor
terminates the request.
PR-A5 wraps every handler-entry capture of the request headers with
`_strip_internal_headers`. Inbound read paths (`request.headers.get(...)`
for bypass gating, `_extract_tags` reading `x-headroom-*`) keep working
because they never depended on the local outbound-bound dict.
Operator opt-in `HEADROOM_STRIP_INTERNAL_HEADERS=disabled` keeps the
internal headers in the upstream-bound dict for diagnostic shadow tracing.
That mode is loud and explicit per realignment build constraint #4 — NOT
a silent fallback.
"""
from __future__ import annotations
from types import SimpleNamespace
from unittest.mock import AsyncMock
import httpx
import pytest
pytest.importorskip("fastapi")
from fastapi.testclient import TestClient
from headroom.proxy.helpers import (
_strip_internal_headers,
get_strip_internal_headers_mode,
merge_extra_headers,
)
from headroom.proxy.server import ProxyConfig, create_app
@pytest.fixture(autouse=True)
def _allow_reserved_test_upstream(monkeypatch: pytest.MonkeyPatch) -> None:
"""Permit the reserved override used by the end-to-end isolation test."""
monkeypatch.setenv("HEADROOM_ALLOWED_BASE_URLS", "override.example")
# ---------------------------------------------------------------------------
# Pure helper unit tests
# ---------------------------------------------------------------------------
def test_strip_returns_new_dict_does_not_mutate_caller() -> None:
"""`_strip_internal_headers` is pure — caller's dict is untouched."""
original = {
"authorization": "Bearer x",
"x-headroom-bypass": "true",
}
out = _strip_internal_headers(original)
assert out is not original
assert "x-headroom-bypass" in original
assert "x-headroom-bypass" not in out
assert out["authorization"] == "Bearer x"
def test_strip_x_headroom_bypass_removed() -> None:
out = _strip_internal_headers({"x-headroom-bypass": "true", "k": "v"})
assert "x-headroom-bypass" not in out
assert out["k"] == "v"
def test_strip_x_headroom_mode_removed() -> None:
out = _strip_internal_headers({"x-headroom-mode": "passthrough", "k": "v"})
assert "x-headroom-mode" not in out
assert out["k"] == "v"
def test_strip_x_headroom_user_id_removed() -> None:
out = _strip_internal_headers({"x-headroom-user-id": "u1", "k": "v"})
assert "x-headroom-user-id" not in out
assert out["k"] == "v"
def test_strip_x_headroom_stack_removed() -> None:
out = _strip_internal_headers({"x-headroom-stack": "engineer", "k": "v"})
assert "x-headroom-stack" not in out
assert out["k"] == "v"
def test_strip_x_headroom_base_url_removed() -> None:
out = _strip_internal_headers({"x-headroom-base-url": "http://x", "k": "v"})
assert "x-headroom-base-url" not in out
assert out["k"] == "v"
def test_strip_case_insensitive_prefix_match() -> None:
"""Mixed-case `X-Headroom-Foo`, `x-Headroom-Bar`, `X-HEADROOM-BAZ` all stripped."""
out = _strip_internal_headers(
{
"X-Headroom-Foo": "1",
"x-Headroom-Bar": "2",
"X-HEADROOM-BAZ": "3",
"Authorization": "Bearer x",
}
)
assert "X-Headroom-Foo" not in out
assert "x-Headroom-Bar" not in out
assert "X-HEADROOM-BAZ" not in out
assert out["Authorization"] == "Bearer x"
def test_strip_legitimate_headers_passthrough() -> None:
"""Headers without the internal prefix must NOT be stripped."""
out = _strip_internal_headers(
{
"Authorization": "Bearer x",
"x-api-key": "k",
"x-request-id": "rid-1",
"x-trace-id": "tid-1",
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"User-Agent": "claude-code/1.0",
}
)
assert out["Authorization"] == "Bearer x"
assert out["x-api-key"] == "k"
assert out["x-request-id"] == "rid-1"
assert out["x-trace-id"] == "tid-1"
assert out["Content-Type"] == "application/json"
assert out["anthropic-version"] == "2023-06-01"
assert out["User-Agent"] == "claude-code/1.0"
def test_strip_disabled_mode_passes_internal_headers_through(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""`HEADROOM_STRIP_INTERNAL_HEADERS=disabled` is operator opt-in for diag."""
monkeypatch.setenv("HEADROOM_STRIP_INTERNAL_HEADERS", "disabled")
out = _strip_internal_headers({"x-headroom-bypass": "true", "authorization": "Bearer x"})
assert out["x-headroom-bypass"] == "true"
assert out["authorization"] == "Bearer x"
def test_strip_disabled_mode_returns_copy_not_alias(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Even in disabled mode the helper returns a NEW dict, never an alias."""
monkeypatch.setenv("HEADROOM_STRIP_INTERNAL_HEADERS", "disabled")
src = {"x-headroom-bypass": "true"}
out = _strip_internal_headers(src)
assert out is not src
def test_strip_mode_default_is_enabled(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("HEADROOM_STRIP_INTERNAL_HEADERS", raising=False)
assert get_strip_internal_headers_mode() == "enabled"
def test_strip_mode_invalid_raises(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("HEADROOM_STRIP_INTERNAL_HEADERS", "garbage")
with pytest.raises(ValueError, match="HEADROOM_STRIP_INTERNAL_HEADERS"):
get_strip_internal_headers_mode()
def test_strip_empty_dict_returns_empty_dict() -> None:
assert _strip_internal_headers({}) == {}
def test_strip_preserves_value_semantics() -> None:
"""Values are forwarded unchanged for kept headers."""
out = _strip_internal_headers(
{
"Authorization": "Bearer sk-ant-...",
"anthropic-version": "2023-06-01",
}
)
assert out["Authorization"] == "Bearer sk-ant-..."
assert out["anthropic-version"] == "2023-06-01"
def test_strip_default_tenant_header_removed() -> None:
"""Tenant header is ingress-only and must not reach providers."""
out = _strip_internal_headers(
{
"Authorization": "Bearer sk-ant-...",
"X-Headroom-Tenant-ID": "tenant_a",
}
)
assert "X-Headroom-Tenant-ID" not in out
assert out["Authorization"] == "Bearer sk-ant-..."
def test_strip_custom_tenant_header_removed(monkeypatch: pytest.MonkeyPatch) -> None:
"""Configured tenant header is also stripped, even outside x-headroom-*."""
monkeypatch.setenv("HEADROOM_TENANT_KEY_HEADER", "X-Tenant-ID")
out = _strip_internal_headers(
{
"Authorization": "Bearer sk-ant-...",
"X-Tenant-ID": "tenant_a",
"x-request-id": "rid-1",
}
)
assert "X-Tenant-ID" not in out
assert out["x-request-id"] == "rid-1"
# ---------------------------------------------------------------------------
# End-to-end: x-headroom-* never reaches the upstream
# ---------------------------------------------------------------------------
class _CapturingTransport(httpx.AsyncBaseTransport):
def __init__(self) -> None:
self.captured_headers: dict[str, str] | None = None
self.captured_body: bytes | None = None
async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
body = b""
async for chunk in request.stream:
body += chunk
self.captured_body = body
self.captured_headers = dict(request.headers.items())
return httpx.Response(
200,
json={
"id": "msg_1",
"type": "message",
"role": "assistant",
"content": [{"type": "text", "text": "ok"}],
"usage": {
"input_tokens": 10,
"output_tokens": 3,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
},
},
)
class _FakePrefixTracker:
def __init__(self, frozen_count: int = 0):
self._frozen_count = frozen_count
self._cached_token_count = 0
self._last_original_messages: list = []
self._last_forwarded_messages: list = []
def get_frozen_message_count(self) -> int:
return self._frozen_count
def get_last_original_messages(self): # noqa: ANN201
return list(self._last_original_messages)
def get_last_forwarded_messages(self): # noqa: ANN201
return list(self._last_forwarded_messages)
def update_from_response(self, **kwargs): # noqa: ANN003
self._last_original_messages = kwargs.get("original_messages", kwargs.get("messages", []))
self._last_forwarded_messages = kwargs.get("messages", [])
return None
def _make_anthropic_app(**config_overrides) -> tuple[TestClient, _CapturingTransport]:
config = ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_inject_tool=False,
ccr_handle_responses=False,
ccr_context_tracking=False,
image_optimize=False,
**config_overrides,
)
app = create_app(config)
proxy = app.state.proxy
transport = _CapturingTransport()
proxy.http_client = httpx.AsyncClient(transport=transport)
fake_tracker = _FakePrefixTracker(frozen_count=0)
proxy.session_tracker_store.compute_session_id = lambda request, model, messages: "s1"
proxy.session_tracker_store.get_or_create = (
lambda session_id, provider, cache_ttl_seconds=None: fake_tracker
)
return TestClient(app), transport
def test_x_headroom_bypass_not_forwarded() -> None:
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-bypass": "true",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-bypass" not in upstream
# Legitimate headers must reach upstream.
assert upstream.get("x-api-key") == "test-key"
assert upstream.get("anthropic-version") == "2023-06-01"
def test_x_headroom_mode_not_forwarded() -> None:
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-mode": "passthrough",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-mode" not in upstream
def test_x_headroom_user_id_not_forwarded() -> None:
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-user-id": "alice",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-user-id" not in upstream
def test_x_headroom_stack_not_forwarded() -> None:
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-stack": "engineer",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-stack" not in upstream
def test_x_headroom_base_url_not_forwarded() -> None:
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-base-url": "https://override.example",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-base-url" not in upstream
def test_case_insensitive_prefix_match_e2e() -> None:
"""Mixed-case headers are stripped end-to-end."""
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"X-Headroom-Foo": "1",
"x-Headroom-Bar": "2",
"X-HEADROOM-BAZ": "3",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream_lower = {k.lower(): v for k, v in transport.captured_headers.items()}
assert "x-headroom-foo" not in upstream_lower
assert "x-headroom-bar" not in upstream_lower
assert "x-headroom-baz" not in upstream_lower
def test_legitimate_headers_passthrough_e2e() -> None:
"""Authorization / x-api-key / x-request-id / Content-Type all preserved."""
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"Authorization": "Bearer sk-ant-test",
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-request-id": "rid-abc",
"User-Agent": "claude-code/1.2.3",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert upstream.get("x-api-key") == "test-key"
assert upstream.get("anthropic-version") == "2023-06-01"
assert upstream.get("user-agent") == "claude-code/1.2.3"
# Authorization is delivered uppercased; httpx normalizes to lowercase
# when reading via dict()-of-Headers, so check via lowercase key.
assert upstream.get("authorization") == "Bearer sk-ant-test"
def test_inbound_read_path_still_reads_x_headroom_bypass() -> None:
"""Bypass header still gates compression even though it's stripped from upstream.
The handler reads `request.headers.get('x-headroom-bypass')` directly.
Stripping the local outbound-bound `headers` dict does NOT affect that
inbound read path.
"""
config = ProxyConfig(
# Compression is the only thing bypass affects observably; turn it on.
optimize=True,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_inject_tool=False,
ccr_handle_responses=False,
ccr_context_tracking=False,
image_optimize=False,
)
app = create_app(config)
proxy = app.state.proxy
transport = _CapturingTransport()
proxy.http_client = httpx.AsyncClient(transport=transport)
fake_tracker = _FakePrefixTracker(frozen_count=0)
proxy.session_tracker_store.compute_session_id = lambda request, model, messages: "s_bypass"
proxy.session_tracker_store.get_or_create = (
lambda session_id, provider, cache_ttl_seconds=None: fake_tracker
)
client = TestClient(app)
# Force a bypass via header. The handler logs "Bypass: skipping compression"
# if the inbound read worked; we can't easily intercept the log, so we
# primarily assert that:
# 1. The request still succeeds.
# 2. The upstream did NOT receive the `x-headroom-bypass` header.
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-bypass": "true",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200
upstream = {k.lower(): v for k, v in (transport.captured_headers or {}).items()}
assert "x-headroom-bypass" not in upstream
def test_disabled_mode_passes_through_e2e(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""`HEADROOM_STRIP_INTERNAL_HEADERS=disabled` lets internal headers through."""
monkeypatch.setenv("HEADROOM_STRIP_INTERNAL_HEADERS", "disabled")
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "test-key",
"anthropic-version": "2023-06-01",
"content-type": "application/json",
"x-headroom-mode": "passthrough",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
# Operator opt-in: internal header IS forwarded (diagnostic mode).
assert upstream.get("x-headroom-mode") == "passthrough"
# ---------------------------------------------------------------------------
# OpenAI Chat Completions parity check
# ---------------------------------------------------------------------------
def test_openai_chat_x_headroom_bypass_not_forwarded() -> None:
"""OpenAI handler also strips x-headroom-* before upstream call."""
config = ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_inject_tool=False,
ccr_handle_responses=False,
ccr_context_tracking=False,
image_optimize=False,
)
app = create_app(config)
proxy = app.state.proxy
captured: dict[str, object] = {}
async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
captured["headers"] = dict(headers)
return httpx.Response(
200,
json={
"id": "chatcmpl_1",
"object": "chat.completion",
"model": "gpt-4o",
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "ok"},
"finish_reason": "stop",
}
],
"usage": {"prompt_tokens": 10, "completion_tokens": 1, "total_tokens": 11},
},
)
proxy._retry_request = _fake_retry # type: ignore[attr-defined]
proxy.memory_handler = SimpleNamespace(
config=SimpleNamespace(inject_context=False, inject_tools=False),
search_and_format_context=AsyncMock(return_value=""),
has_memory_tool_calls=lambda resp, provider: False,
)
client = TestClient(app)
resp = client.post(
"/v1/chat/completions",
headers={
"authorization": "Bearer sk-test",
"x-headroom-bypass": "true",
"x-headroom-user-id": "u1",
},
json={
"model": "gpt-4o",
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
sent_headers_raw = captured.get("headers")
assert isinstance(sent_headers_raw, dict)
sent_headers = {k.lower(): v for k, v in sent_headers_raw.items()}
assert "x-headroom-bypass" not in sent_headers
assert "x-headroom-user-id" not in sent_headers
assert sent_headers.get("authorization") == "Bearer sk-test"
# ---------------------------------------------------------------------------
# Configured extra headers (anthropic_extra_headers / openai_extra_headers)
# ---------------------------------------------------------------------------
def test_anthropic_extra_headers_merged_and_override_client_header() -> None:
"""Configured extra headers reach upstream and override same-named client headers."""
client, transport = _make_anthropic_app(
anthropic_extra_headers={"x-api-key": "gateway-key", "x-gateway-id": "gw-1"}
)
resp = client.post(
"/v1/messages",
headers={
"x-api-key": "client-key",
"anthropic-version": "2023-06-01",
},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
assert transport.captured_headers is not None
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
# Configured header wins over the client-sent value for the same key.
assert upstream.get("x-api-key") == "gateway-key"
# A configured header not sent by the client is still added.
assert upstream.get("x-gateway-id") == "gw-1"
def test_anthropic_no_extra_headers_configured_is_unchanged() -> None:
"""With no extra headers configured, forwarding behavior is unchanged."""
client, transport = _make_anthropic_app()
resp = client.post(
"/v1/messages",
headers={"x-api-key": "client-key", "anthropic-version": "2023-06-01"},
json={
"model": "claude-sonnet-4-6",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hi"}],
},
)
assert resp.status_code == 200, resp.text
upstream = {k.lower(): v for k, v in transport.captured_headers.items()}
assert upstream.get("x-api-key") == "client-key"
assert "x-gateway-id" not in upstream
def test_merge_extra_headers_overrides_case_insensitively() -> None:
"""A configured extra header wins even when the client used different casing."""
out = merge_extra_headers(
{"Authorization": "client", "keep": "v"},
{"authorization": "gateway"},
upstream_url=None,
)
assert out == {"authorization": "gateway", "keep": "v"}
# Exactly one authorization header survives (no duplicate casings upstream).
assert [k for k in out if k.lower() == "authorization"] == ["authorization"]
def test_merge_extra_headers_none_returns_same_object() -> None:
"""No configured extras -> caller's dict is returned unchanged (no copy)."""
headers = {"a": "b"}
assert merge_extra_headers(headers, None, upstream_url=None) is headers