mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:07:29 +08:00
## Description Adds a gateway turn contract to `POST /v1/compress`, allowing an API gateway to submit a complete provider request and later report the provider response. Requests without a top-level `gateway` object remain unchanged. ## Type of Change - [x] 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Adds the request half to `/v1/compress` and the response half at `/v1/compress/response`, including bounded pending turns, idempotent rounds, usage relay, and redrive obligations. - Adds a reusable six-stage compress-turn extension seam and turn-hook priority/provider-header support. - Keeps native tool-schema deferral in the licensed extension while sharing protocol-shape helpers with core. - Accepts Anthropic, OpenAI chat, OpenAI Responses, and Kong-shaped usage payloads. - Documents the gateway contract in `docs/content/docs/proxy.mdx` and `wiki/proxy.md`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text tests/gateway + gateway unit + turn-hook seam + test_issue_746_tool_search: 358 passed ruff 0.16.3 lint/format and mypy on touched modules: clean Kong 3.9 Docker e2e (HEADROOM_KONG_E2E=1): 4 passed ``` ## Real Behavior Proof - Environment: Kong 3.9 Docker e2e and real-provider Claude Code through Kong on SWE-bench-mini. - Exact command / steps: `HEADROOM_KONG_E2E=1` gateway e2e; real-provider traffic through the gateway contract with usage relay and licensed native deferral. - Observed result: four Kong e2e tests passed; prefix cache remained intact with zero busts; relayed usage matched Anthropic token-for-token; licensed tool-search deferral reduced cache-read tokens per turn by 27–30%. - Not tested: production rollout at scale. ## Runtime Rollout Safety - Rollout-managed feature(s): gateway contract and in-process pending-turn registry. - Minimum rollout channel: controlled gateway deployment before broader enablement. - Stable/default behavior changed: only requests containing a top-level `gateway` object enter the new contract; ordinary `/v1/compress` bodies are unchanged. - Kill switch / disable path: set `HEADROOM_GATEWAY_CONTRACT=0`. - Unsafe override required: no. - Qualification impact: gateway callers must redeem advertised `redrive` and `relay_usage` obligations. - Rollback path: disable the contract with `HEADROOM_GATEWAY_CONTRACT=0` or revert the feature commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) Not applicable; this is an API contract change. ## Additional Notes Pending turns are process-local and bounded by `HEADROOM_GATEWAY_TURN_TTL_SECONDS`, `HEADROOM_GATEWAY_MAX_PENDING_TURNS`, and `HEADROOM_GATEWAY_MAX_REDRIVES`. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
163 lines
5.4 KiB
Python
163 lines
5.4 KiB
Python
"""Fixtures for the gateway turn contract tests.
|
|
|
|
* ``make_headroom_client`` / ``headroom_client`` - the proxy app built like
|
|
``tests/test_compress_session_mode.py::_make_client`` and served through a
|
|
loopback ``TestClient`` (``/v1/compress`` and ``/v1/compress/response`` are
|
|
loopback-gated).
|
|
* ``fake_provider`` / ``provider_client`` - a :class:`FakeProvider` and a
|
|
``TestClient`` mounted on its ASGI app.
|
|
* ``make_gateway`` - a :class:`FakeGateway` factory bound to the two clients.
|
|
* ``outcome_spy`` - captures every ``RequestOutcome`` the proxy records.
|
|
* Autouse: turn hooks cleared before/after each test; ``HEADROOM_GATEWAY_*``
|
|
scrubbed (the repo conftest already scrubs every ``HEADROOM_*`` var, this one
|
|
makes the dependency explicit for the knobs these tests set).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
import os
|
|
from collections.abc import Callable, Iterator
|
|
from typing import Any
|
|
|
|
import pytest
|
|
|
|
pytest.importorskip("fastapi")
|
|
|
|
from fastapi.testclient import TestClient # noqa: E402
|
|
|
|
from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
|
|
from headroom.proxy.turn_hooks import clear_turn_hooks # noqa: E402
|
|
from tests.gateway.fake_gateway import FakeGateway # noqa: E402
|
|
from tests.gateway.fake_provider import FakeProvider # noqa: E402
|
|
|
|
LOOPBACK = ("127.0.0.1", 12345)
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _clear_hooks() -> Iterator[None]:
|
|
clear_turn_hooks()
|
|
yield
|
|
clear_turn_hooks()
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _scrub_gateway_env(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
for key in list(os.environ):
|
|
if key.startswith("HEADROOM_GATEWAY_") or key.startswith("HEADROOM_TEST_REDRIVE_"):
|
|
monkeypatch.delenv(key, raising=False)
|
|
|
|
|
|
def proxy_config(**overrides: Any) -> ProxyConfig:
|
|
"""The same posture as the session-mode tests: optimize on, everything that
|
|
would reach the network or add per-request noise off."""
|
|
kwargs: dict[str, Any] = {
|
|
"optimize": True,
|
|
"cache_enabled": False,
|
|
"rate_limit_enabled": False,
|
|
"cost_tracking_enabled": False,
|
|
"log_requests": False,
|
|
"image_optimize": False,
|
|
}
|
|
kwargs.update(overrides)
|
|
return ProxyConfig(**kwargs)
|
|
|
|
|
|
@pytest.fixture
|
|
def make_headroom_client() -> Iterator[Callable[..., TestClient]]:
|
|
"""Factory: ``make_headroom_client(**ProxyConfig overrides) -> TestClient``.
|
|
|
|
Each client is entered (lifespan started) and closed at teardown. Use the
|
|
factory when a test must set env vars BEFORE the app is created."""
|
|
opened: list[TestClient] = []
|
|
|
|
def _make(**overrides: Any) -> TestClient:
|
|
app = create_app(proxy_config(**overrides))
|
|
client = TestClient(app, base_url="http://127.0.0.1", client=LOOPBACK)
|
|
client.__enter__()
|
|
opened.append(client)
|
|
return client
|
|
|
|
yield _make
|
|
for client in reversed(opened):
|
|
client.__exit__(None, None, None)
|
|
|
|
|
|
@pytest.fixture
|
|
def headroom_client(make_headroom_client: Callable[..., TestClient]) -> TestClient:
|
|
return make_headroom_client()
|
|
|
|
|
|
@pytest.fixture
|
|
def fake_provider() -> FakeProvider:
|
|
return FakeProvider()
|
|
|
|
|
|
@pytest.fixture
|
|
def provider_client(fake_provider: FakeProvider) -> Iterator[TestClient]:
|
|
with TestClient(fake_provider.app) as client:
|
|
yield client
|
|
|
|
|
|
@pytest.fixture
|
|
def make_gateway(
|
|
headroom_client: TestClient, provider_client: TestClient
|
|
) -> Callable[..., FakeGateway]:
|
|
def _make(**kwargs: Any) -> FakeGateway:
|
|
kwargs.setdefault("can_redrive", True)
|
|
kwargs.setdefault("can_relay_response", True)
|
|
return FakeGateway(headroom_client, provider_client, **kwargs)
|
|
|
|
return _make
|
|
|
|
|
|
@pytest.fixture
|
|
def outcome_spy(monkeypatch: pytest.MonkeyPatch) -> Callable[[Any], list[Any]]:
|
|
"""``outcome_spy(client_or_app_or_proxy) -> list`` that fills with every
|
|
``RequestOutcome`` recorded by that proxy instance (patched on the instance,
|
|
so two apps in one test get separate lists)."""
|
|
|
|
def _attach(target: Any) -> list[Any]:
|
|
proxy = target
|
|
if hasattr(target, "app"):
|
|
proxy = target.app.state.proxy
|
|
elif hasattr(target, "state"):
|
|
proxy = target.state.proxy
|
|
outcomes: list[Any] = []
|
|
|
|
async def _spy(outcome: Any, *args: Any, **kwargs: Any) -> None:
|
|
outcomes.append(outcome)
|
|
|
|
monkeypatch.setattr(proxy, "_record_request_outcome", _spy)
|
|
return outcomes
|
|
|
|
return _attach
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Helpers (plain functions, importable from the tests) #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
|
|
def compress(
|
|
client: TestClient, body: dict[str, Any], *, headers: dict[str, str] | None = None
|
|
) -> Any:
|
|
return client.post("/v1/compress", json=body, headers=headers)
|
|
|
|
|
|
def gateway_block(**flags: Any) -> dict[str, Any]:
|
|
return dict(flags)
|
|
|
|
|
|
def count_loop_tasks(client: TestClient) -> int:
|
|
"""Number of asyncio tasks alive on the app's event loop (the TestClient
|
|
portal thread). Used to prove the response half leaks no suspended hook
|
|
tasks."""
|
|
assert client.portal is not None, "client must be entered"
|
|
return client.portal.call(lambda: len(asyncio.all_tasks()))
|
|
|
|
|
|
def registry_of(client: TestClient) -> Any:
|
|
"""The proxy's ``PendingTurnRegistry`` (``None`` until the core lands)."""
|
|
return getattr(client.app.state.proxy, "gateway_turns", None)
|