diff --git a/docs/platform-feature-matrix.json b/docs/platform-feature-matrix.json new file mode 100644 index 000000000..42fc432fa --- /dev/null +++ b/docs/platform-feature-matrix.json @@ -0,0 +1,329 @@ +{ + "schema_version": 1, + "updated": "2026-07-06", + "source_issues": [ + "https://github.com/headroomlabs-ai/headroom/issues/1843" + ], + "status_values": [ + "covered", + "partial", + "gap", + "blocked" + ], + "platforms": [ + "linux", + "macos", + "windows" + ], + "features": [ + { + "id": "install_apply_python", + "name": "Persistent Python install applies and starts", + "risk": "install", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_cli/test_install_cli.py", + "tests/test_install/test_supervisors.py", + ".github/workflows/install-native-e2e.yml" + ] + }, + "macos": { + "status": "covered", + "tests": [ + "tests/test_install/test_supervisors.py", + ".github/workflows/install-native-e2e.yml" + ] + }, + "windows": { + "status": "partial", + "tests": [ + "tests/test_install/test_supervisors.py", + "tests/test_install/test_runtime.py", + ".github/workflows/ci.yml#windows-native-wrapper" + ], + "gap": "Native install smoke workflow is source-level until Windows wheel CRT conflicts are resolved." + } + } + }, + { + "id": "install_windows_service", + "name": "Windows service install uses sc.exe safely", + "risk": "install", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_install/test_supervisors.py" + ] + }, + "macos": { + "status": "covered", + "tests": [ + "tests/test_install/test_supervisors.py" + ] + }, + "windows": { + "status": "covered", + "tests": [ + "tests/test_install/test_supervisors.py" + ] + } + } + }, + { + "id": "single_instance_start", + "name": "Persistent runtime start is single-instance by default", + "risk": "runtime", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_cli/test_install_cli.py", + "tests/test_install/test_runtime.py" + ] + }, + "macos": { + "status": "covered", + "tests": [ + "tests/test_cli/test_install_cli.py", + "tests/test_install/test_runtime.py" + ] + }, + "windows": { + "status": "covered", + "tests": [ + "tests/test_cli/test_install_cli.py", + "tests/test_install/test_runtime.py" + ] + } + } + }, + { + "id": "compression_fail_open", + "name": "Slow or saturated compression fails open", + "risk": "performance", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_kompress_request_nonblocking.py", + "tests/test_proxy_compression_executor.py", + "tests/test_openai_codex_ws_lifecycle.py" + ] + }, + "macos": { + "status": "partial", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_kompress_request_nonblocking.py", + "tests/test_proxy_compression_executor.py" + ], + "gap": "Native workflow coverage should add focused performance-gate tests without full model downloads." + }, + "windows": { + "status": "partial", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_kompress_request_nonblocking.py", + "tests/test_proxy_compression_executor.py" + ], + "gap": "Source-level tests validate fail-open semantics; full native proxy e2e waits on Windows wheel availability." + } + } + }, + { + "id": "proxy_functional_smoke", + "name": "Proxy health and /v1/compress work through the app surface", + "risk": "proxy", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_ccr_row_drop_store_bridge.py" + ] + }, + "macos": { + "status": "partial", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_ccr_row_drop_store_bridge.py" + ], + "gap": "FastAPI route coverage exists; native persistent proxy process smoke should be added." + }, + "windows": { + "status": "partial", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_ccr_row_drop_store_bridge.py" + ], + "gap": "FastAPI route coverage exists; native persistent proxy process smoke waits on Windows wheel availability." + } + } + }, + { + "id": "ccr_persistence", + "name": "CCR survives restart when persistent storage is enabled", + "risk": "cache", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "crates/headroom-core/tests/ccr_backends.rs", + "tests/test_storage_backends.py" + ] + }, + "macos": { + "status": "partial", + "tests": [ + "crates/headroom-core/tests/ccr_backends.rs", + "tests/test_storage_backends.py" + ], + "gap": "Rust backend tests run in the Rust workflow; native macOS restart e2e is not yet present." + }, + "windows": { + "status": "partial", + "tests": [ + "crates/headroom-core/tests/ccr_backends.rs", + "tests/test_storage_backends.py" + ], + "gap": "Windows restart e2e is blocked by the native wheel CRT conflict." + } + } + }, + { + "id": "init_cli", + "name": "headroom init configures supported agents", + "risk": "install", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + ".github/workflows/init-native-e2e.yml" + ] + }, + "macos": { + "status": "covered", + "tests": [ + ".github/workflows/init-native-e2e.yml" + ] + }, + "windows": { + "status": "blocked", + "tests": [ + ".github/workflows/init-native-e2e.yml" + ], + "gap": "Matrix entry is intentionally excluded until Windows wheel CRT conflicts are resolved." + } + } + }, + { + "id": "wrap_prepare_only", + "name": "headroom wrap prepare-only mutates config safely", + "risk": "install", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + ".github/workflows/wrap-native-e2e.yml" + ] + }, + "macos": { + "status": "covered", + "tests": [ + ".github/workflows/wrap-native-e2e.yml" + ] + }, + "windows": { + "status": "blocked", + "tests": [ + ".github/workflows/wrap-native-e2e.yml" + ], + "gap": "Matrix entry is intentionally excluded until Windows wheel CRT conflicts are resolved." + } + } + }, + { + "id": "toin_skip_recommendations", + "name": "TOIN skip-compression recommendations are exposed", + "risk": "cache", + "platforms": { + "linux": { + "status": "covered", + "tests": [ + "tests/test_toin.py", + "tests/test_proxy_ccr.py", + "tests/test_compression_policy_toin_gate.py" + ] + }, + "macos": { + "status": "partial", + "tests": [ + "tests/test_toin.py", + "tests/test_compression_policy_toin_gate.py" + ], + "gap": "Native end-to-end verification of served recommendations is still needed." + }, + "windows": { + "status": "partial", + "tests": [ + "tests/test_toin.py", + "tests/test_compression_policy_toin_gate.py" + ], + "gap": "Native end-to-end verification is blocked by Windows wheel availability." + } + } + } + ], + "sanity_tests": [ + { + "id": "cli_help", + "description": "Every public CLI command renders help without importing optional heavy runtimes.", + "tests": [ + "tests/test_cli" + ] + }, + { + "id": "install_paths", + "description": "Install paths resolve under the active user profile and never require administrator paths for user scope.", + "tests": [ + "tests/test_install/test_paths.py" + ] + }, + { + "id": "runtime_selection", + "description": "Python, Docker, service, and task runtime commands are generated deterministically for each platform.", + "tests": [ + "tests/test_install/test_runtime.py", + "tests/test_install/test_supervisors.py" + ] + }, + { + "id": "health_startup", + "description": "Persistent starts wait for /readyz and surface startup failure instead of silently succeeding.", + "tests": [ + "tests/test_cli/test_install_cli.py", + "tests/test_install/test_health.py" + ] + }, + { + "id": "compression_backpressure", + "description": "Compression queue saturation and model cold-start fail open without hanging request paths.", + "tests": [ + "tests/test_platform_stabilization_functional.py", + "tests/test_kompress_request_nonblocking.py", + "tests/test_proxy_compression_executor.py" + ] + }, + { + "id": "proxy_route_smoke", + "description": "Health and /v1/compress routes return functional metrics and fail open on timeout.", + "tests": [ + "tests/test_platform_stabilization_functional.py" + ] + } + ] +} diff --git a/docs/platform-stabilization.md b/docs/platform-stabilization.md new file mode 100644 index 000000000..bb3c63f42 --- /dev/null +++ b/docs/platform-stabilization.md @@ -0,0 +1,28 @@ +# Platform Stabilization Matrix + +This matrix is the hardening source of truth for install, startup, runtime, cache, and compression behavior across Linux, macOS, and Windows. The machine-readable matrix lives in `docs/platform-feature-matrix.json`; CI tests validate its shape so every feature has explicit platform status and test evidence. + +## Status Values + +- `covered`: unit, integration, or native e2e coverage exists for the platform. +- `partial`: coverage exists, but a named gap remains. +- `gap`: no meaningful coverage exists yet. +- `blocked`: coverage is intentionally excluded by a known external blocker. + +## Current Priorities + +1. Keep install/setup/run idempotent. Persistent starts must not create duplicate proxy instances unless a future explicit opt-in exists. +2. Keep compression fail-open. Cold model downloads, saturated executors, or timeout paths must pass through unchanged traffic instead of hanging agents. +3. Keep cache behavior visible. CCR persistence and TOIN skip recommendations must have restart and served-recommendation coverage. +4. Keep Windows honest. Windows-specific tests should run locally and in CI whenever they do not require the currently blocked native wheel build. + +## Issue 1843 Coverage Map + +- Windows service quoting: `install_windows_service` +- Duplicate startup processes: `single_instance_start` +- Slow compression and hangs: `compression_fail_open` +- CCR restart persistence: `ccr_persistence` +- TOIN recommendation wiring: `toin_skip_recommendations` +- Install/setup/run sanity: `install_apply_python`, `init_cli`, `wrap_prepare_only` + +When adding or closing a hardening item, update `docs/platform-feature-matrix.json` in the same PR as the implementation or test change. diff --git a/headroom/cli/install.py b/headroom/cli/install.py index 66221fd36..249550d27 100644 --- a/headroom/cli/install.py +++ b/headroom/cli/install.py @@ -59,11 +59,26 @@ def _require_manifest(profile: str) -> DeploymentManifest: return manifest -def _start_deployment(manifest: DeploymentManifest) -> None: +def _start_deployment(manifest: DeploymentManifest, *, assume_start_lock: bool = False) -> None: + if not assume_start_lock: + with acquire_runtime_start_lock(manifest.profile) as acquired: + if not acquired: + click.echo(f"Deployment '{manifest.profile}' start is already in progress.") + return + _start_deployment(manifest, assume_start_lock=True) + return + + if probe_ready(manifest.health_url): + return if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value and shutil.which("docker") is None: raise click.ClickException( "Docker is required for this deployment but 'docker' was not found on PATH." ) + if runtime_status(manifest) == "running": + if wait_ready(manifest, timeout_seconds=_STARTUP_READY_TIMEOUT_SECONDS): + return + stop_runtime(manifest) + try: if manifest.preset == InstallPreset.PERSISTENT_DOCKER.value: start_persistent_docker(manifest) @@ -77,7 +92,7 @@ def _start_deployment(manifest: DeploymentManifest) -> None: except subprocess.CalledProcessError as e: raise click.ClickException( f"Cannot start deployment '{manifest.profile}': command failed " - f"({' '.join(map(str, e.cmd)) if isinstance(e.cmd, (list, tuple)) else e.cmd})" + f"({' '.join(map(str, e.cmd)) if isinstance(e.cmd, list | tuple) else e.cmd})" ) from None if not wait_ready(manifest, timeout_seconds=45): @@ -276,7 +291,7 @@ def install_apply( _restore_deployment(existing) # Surface non-Click errors (OSError, CalledProcessError, …) as a clean # message rather than a raw traceback; Click errors pass through as-is. - if isinstance(exc, (click.ClickException, click.Abort)): + if isinstance(exc, click.ClickException | click.Abort): raise raise click.ClickException(f"Failed to install deployment '{profile}': {exc}") from exc @@ -409,5 +424,5 @@ def install_agent_ensure(profile: str) -> None: click.echo(f"Deployment '{profile}' is healthy.") return stop_runtime(manifest) - _start_deployment(manifest) + _start_deployment(manifest, assume_start_lock=True) click.echo(f"Deployment '{profile}' is healthy.") diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index dbff4e627..9ec52bf79 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -7218,19 +7218,21 @@ class OpenAIHandlerMixin: ) except TimeoutError: logger.warning( - "Compression timed out after %.0fs (payload too large)", + "Compression timed out after %.0fs; failing open with original messages", COMPRESSION_TIMEOUT_SECONDS, ) return JSONResponse( - status_code=503, content={ - "error": { - "type": "compression_timeout", - "message": ( - "Compression exceeded " - f"{COMPRESSION_TIMEOUT_SECONDS:.0f}s; payload too large." - ), - } + "messages": messages, + "tokens_before": 0, + "tokens_after": 0, + "tokens_saved": 0, + "compression_ratio": 1.0, + "transforms_applied": [], + "transforms_summary": {}, + "ccr_hashes": [], + "compression_skipped": True, + "skip_reason": "compression_timeout", }, ) except Exception as e: diff --git a/tests/test_cli/test_install_cli.py b/tests/test_cli/test_install_cli.py index 2ba8b5577..6cccaeb92 100644 --- a/tests/test_cli/test_install_cli.py +++ b/tests/test_cli/test_install_cli.py @@ -43,6 +43,8 @@ def test_install_apply_starts_service_supervisor(monkeypatch) -> None: monkeypatch.setattr( "headroom.cli.install.wait_ready", lambda deployment, timeout_seconds=45: True ) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: False) + monkeypatch.setattr("headroom.cli.install.runtime_status", lambda manifest: "stopped") result = runner.invoke(main, ["install", "apply"]) @@ -153,6 +155,8 @@ def test_install_restart_uses_internal_helpers(monkeypatch) -> None: monkeypatch.setattr( "headroom.cli.install.wait_ready", lambda manifest, timeout_seconds=45: True ) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: False) + monkeypatch.setattr("headroom.cli.install.runtime_status", lambda manifest: "stopped") result = runner.invoke(main, ["install", "restart"]) @@ -161,6 +165,114 @@ def test_install_restart_uses_internal_helpers(monkeypatch) -> None: assert calls == ["stop_supervisor", "stop_runtime", "start_supervisor"] +def test_install_start_noops_when_already_healthy(monkeypatch) -> None: + runner = CliRunner() + calls: list[str] = [] + + class Manifest: + profile = "default" + preset = "persistent-service" + runtime_kind = "python" + supervisor_kind = "service" + scope = "user" + health_url = "http://127.0.0.1:8787/readyz" + + monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: Manifest()) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: True) + monkeypatch.setattr( + "headroom.cli.install.start_supervisor", lambda manifest: calls.append("start_supervisor") + ) + + result = runner.invoke(main, ["install", "start"]) + + assert result.exit_code == 0, result.output + assert "Started deployment 'default'." in result.output + assert calls == [] + + +def test_install_start_noops_for_healthy_docker_without_docker_on_path(monkeypatch) -> None: + runner = CliRunner() + + class Manifest: + profile = "default" + preset = "persistent-docker" + runtime_kind = "docker" + supervisor_kind = "none" + scope = "user" + health_url = "http://127.0.0.1:8787/readyz" + + monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: Manifest()) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: True) + monkeypatch.setattr("headroom.cli.install.shutil.which", lambda name, *args, **kwargs: None) + + result = runner.invoke(main, ["install", "start"]) + + assert result.exit_code == 0, result.output + assert "Started deployment 'default'." in result.output + + +def test_install_start_does_not_spawn_when_start_lock_is_contended(monkeypatch) -> None: + runner = CliRunner() + calls: list[str] = [] + + class Manifest: + profile = "default" + preset = "persistent-service" + runtime_kind = "python" + supervisor_kind = "service" + scope = "user" + health_url = "http://127.0.0.1:8787/readyz" + + monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: Manifest()) + + import contextlib + + @contextlib.contextmanager + def fake_lock(profile): + yield False + + monkeypatch.setattr("headroom.cli.install.acquire_runtime_start_lock", fake_lock) + monkeypatch.setattr( + "headroom.cli.install.start_supervisor", lambda manifest: calls.append("start_supervisor") + ) + + result = runner.invoke(main, ["install", "start"]) + + assert result.exit_code == 0, result.output + assert "start is already in progress" in result.output + assert calls == [] + + +def test_install_start_restarts_wedged_runtime_under_single_lock(monkeypatch) -> None: + runner = CliRunner() + calls: list[str] = [] + + class Manifest: + profile = "default" + preset = "persistent-service" + runtime_kind = "python" + supervisor_kind = "service" + scope = "user" + health_url = "http://127.0.0.1:8787/readyz" + + monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: Manifest()) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: False) + monkeypatch.setattr("headroom.cli.install.runtime_status", lambda manifest: "running") + wait_results = iter([False, True]) + monkeypatch.setattr( + "headroom.cli.install.wait_ready", lambda manifest, timeout_seconds: next(wait_results) + ) + monkeypatch.setattr("headroom.cli.install.stop_runtime", lambda manifest: calls.append("stop")) + monkeypatch.setattr( + "headroom.cli.install.start_supervisor", lambda manifest: calls.append("start_supervisor") + ) + + result = runner.invoke(main, ["install", "start"]) + + assert result.exit_code == 0, result.output + assert calls == ["stop", "start_supervisor"] + + def test_install_apply_rejects_invalid_profile() -> None: runner = CliRunner() @@ -350,6 +462,7 @@ def test_install_apply_uses_docker_runtime_for_persistent_docker(monkeypatch) -> supervisor_kind = "none" scope = "user" health_url = "http://127.0.0.1:8787/readyz" + container_name = "headroom-default" targets: list[str] = [] mutations = [] artifacts = [] @@ -366,6 +479,8 @@ def test_install_apply_uses_docker_runtime_for_persistent_docker(monkeypatch) -> monkeypatch.setattr( "headroom.cli.install.wait_ready", lambda deployment, timeout_seconds=45: True ) + monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: False) + monkeypatch.setattr("headroom.cli.install.runtime_status", lambda deployment: "stopped") # _start_deployment guards the persistent-docker preset with # `shutil.which("docker")`. Fake docker as present so the test exercises the # runtime-selection path itself rather than the host's docker install — @@ -517,7 +632,8 @@ def test_install_agent_ensure_stops_wedged_runtime_before_restart(monkeypatch) - monkeypatch.setattr("headroom.cli.install.acquire_runtime_start_lock", fake_lock) monkeypatch.setattr( - "headroom.cli.install._start_deployment", lambda manifest: calls.append("start_deployment") + "headroom.cli.install._start_deployment", + lambda manifest, **kwargs: calls.append("start_deployment"), ) result = runner.invoke(main, ["install", "agent", "ensure"]) @@ -626,7 +742,7 @@ def test_install_agent_ensure_propagates_start_deployment_failure(monkeypatch) - monkeypatch.setattr("headroom.cli.install.acquire_runtime_start_lock", fake_lock) - def boom(manifest): + def boom(manifest, **kwargs): raise click.ClickException("simulated start failure") monkeypatch.setattr("headroom.cli.install._start_deployment", boom) diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.py index c9f144fc4..f15cda93b 100644 --- a/tests/test_install/test_runtime.py +++ b/tests/test_install/test_runtime.py @@ -272,7 +272,12 @@ def test_runtime_start_lock_blocks_another_process(monkeypatch, tmp_path: Path) "with acquire_runtime_start_lock('default') as acquired:\n" " print(acquired)\n" ) - env = {**os.environ, "HOME": str(tmp_path), "PYTHONPATH": str(Path.cwd())} + env = { + **os.environ, + "HOME": str(tmp_path), + "USERPROFILE": str(tmp_path), + "PYTHONPATH": str(Path.cwd()), + } with acquire_runtime_start_lock("default") as acquired: assert acquired is True diff --git a/tests/test_platform_feature_matrix.py b/tests/test_platform_feature_matrix.py new file mode 100644 index 000000000..9cf2511fb --- /dev/null +++ b/tests/test_platform_feature_matrix.py @@ -0,0 +1,70 @@ +from __future__ import annotations + +import json +from pathlib import Path + +MATRIX_PATH = Path("docs/platform-feature-matrix.json") +VALID_STATUSES = {"covered", "partial", "gap", "blocked"} +PLATFORMS = {"linux", "macos", "windows"} + + +def test_platform_feature_matrix_is_complete() -> None: + matrix = json.loads(MATRIX_PATH.read_text(encoding="utf-8")) + + assert matrix["schema_version"] == 1 + assert set(matrix["platforms"]) == PLATFORMS + assert set(matrix["status_values"]) == VALID_STATUSES + assert matrix["features"], "matrix must list hardening features" + + feature_ids: set[str] = set() + for feature in matrix["features"]: + feature_id = feature["id"] + assert feature_id not in feature_ids, f"duplicate feature id: {feature_id}" + feature_ids.add(feature_id) + assert feature["name"] + assert feature["risk"] in {"install", "runtime", "performance", "cache", "proxy"} + assert set(feature["platforms"]) == PLATFORMS + + for platform, coverage in feature["platforms"].items(): + status = coverage["status"] + assert status in VALID_STATUSES, f"{feature_id}/{platform} has invalid status" + assert coverage["tests"], f"{feature_id}/{platform} must cite tests or workflows" + for test_ref in coverage["tests"]: + path = Path(test_ref.split("#", 1)[0]) + assert path.exists(), f"{feature_id}/{platform} cites missing path {test_ref}" + if status in {"partial", "gap", "blocked"}: + assert coverage.get("gap"), f"{feature_id}/{platform} must explain {status}" + + +def test_platform_feature_matrix_covers_issue_1843_regression_areas() -> None: + matrix = json.loads(MATRIX_PATH.read_text(encoding="utf-8")) + feature_ids = {feature["id"] for feature in matrix["features"]} + + assert { + "install_windows_service", + "single_instance_start", + "compression_fail_open", + "proxy_functional_smoke", + "ccr_persistence", + "toin_skip_recommendations", + } <= feature_ids + + +def test_platform_feature_matrix_sanity_tests_are_enumerated() -> None: + matrix = json.loads(MATRIX_PATH.read_text(encoding="utf-8")) + sanity_ids = {item["id"] for item in matrix["sanity_tests"]} + + assert { + "cli_help", + "install_paths", + "runtime_selection", + "health_startup", + "compression_backpressure", + "proxy_route_smoke", + } <= sanity_ids + for item in matrix["sanity_tests"]: + assert item["description"] + assert item["tests"] + for test_ref in item["tests"]: + path = Path(test_ref.split("#", 1)[0]) + assert path.exists(), f"{item['id']} cites missing path {test_ref}" diff --git a/tests/test_platform_stabilization_functional.py b/tests/test_platform_stabilization_functional.py new file mode 100644 index 000000000..f89b1a296 --- /dev/null +++ b/tests/test_platform_stabilization_functional.py @@ -0,0 +1,166 @@ +from __future__ import annotations + +import json +import time +from typing import Any + +import pytest + +pytest.importorskip("fastapi") +pytest.importorskip("headroom._core") + +from fastapi.testclient import TestClient + +from headroom.config import TransformResult +from headroom.proxy.server import ProxyConfig, create_app + + +def _proxy_config(**overrides: Any) -> ProxyConfig: + defaults: dict[str, Any] = { + "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, + "disable_kompress": True, + "compression_max_workers": 1, + } + defaults.update(overrides) + return ProxyConfig(**defaults) + + +def test_proxy_health_surfaces_compression_runtime_metrics(monkeypatch) -> None: + monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1") + app = create_app(_proxy_config(optimize=False)) + + with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client: + live = client.get("/livez") + health = client.get("/health") + + assert live.status_code == 200 + assert live.json()["alive"] is True + assert health.status_code == 200 + runtime = health.json()["runtime"] + assert runtime["compression_executor"]["max_workers"] == 1 + assert runtime["compression_executor"]["queued"] == 0 + assert runtime["compression_executor"]["queue_timeouts_total"] == 0 + + +def test_v1_compress_success_reports_actual_metrics(monkeypatch) -> None: + monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1") + app = create_app(_proxy_config()) + proxy = app.state.proxy + request_messages = [{"role": "user", "content": "summarize this repeated payload"}] + compressed_messages = [{"role": "user", "content": "summary payload"}] + + def fake_apply(**kwargs): + assert kwargs["messages"] == request_messages + assert kwargs["model"] == "gpt-4o" + return TransformResult( + messages=compressed_messages, + tokens_before=100, + tokens_after=40, + transforms_applied=["test:compress"], + markers_inserted=["marker-1"], + ) + + monkeypatch.setattr(proxy.openai_pipeline, "apply", fake_apply) + + with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client: + response = client.post( + "/v1/compress", + json={"model": "gpt-4o", "messages": request_messages}, + ) + + body = response.json() + assert response.status_code == 200 + assert body["messages"] == compressed_messages + assert body["tokens_before"] == 100 + assert body["tokens_after"] == 40 + assert body["tokens_saved"] == 60 + assert body["compression_ratio"] == 0.4 + assert body["transforms_applied"] == ["test:compress"] + assert body["transforms_summary"] == {"test:compress": 1} + assert body["ccr_hashes"] == ["marker-1"] + + +def test_v1_compress_timeout_fails_open_quickly(monkeypatch) -> None: + monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1") + app = create_app(_proxy_config()) + proxy = app.state.proxy + request_messages = [{"role": "user", "content": "do not mutate me"}] + + async def timeout_executor(fn, *, timeout): # noqa: ANN001 + raise TimeoutError("compression deadline exceeded") + + monkeypatch.setattr(proxy, "_run_compression_in_executor", timeout_executor) + + with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client: + started = time.perf_counter() + response = client.post( + "/v1/compress", + json={"model": "gpt-4o", "messages": request_messages}, + ) + elapsed = time.perf_counter() - started + + body = response.json() + assert response.status_code == 200 + assert elapsed < 0.5 + assert body["messages"] == request_messages + assert body["tokens_saved"] == 0 + assert body["compression_ratio"] == 1.0 + assert body["transforms_applied"] == [] + assert body["compression_skipped"] is True + assert body["skip_reason"] == "compression_timeout" + + +def test_v1_compress_real_json_tool_payload_reduces_tokens(monkeypatch) -> None: + monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1") + app = create_app( + _proxy_config( + ccr_inject_marker=False, + min_tokens_to_crush=20, + max_items_after_crush=10, + ) + ) + items = [ + { + "id": i, + "status": "ok", + "score": i % 5, + "message": "same repeated value " * 20, + } + for i in range(80) + ] + request = { + "model": "gpt-4o", + "messages": [ + {"role": "user", "content": "summarize rows"}, + { + "role": "assistant", + "content": None, + "tool_calls": [ + { + "id": "call-1", + "type": "function", + "function": {"name": "list_rows", "arguments": "{}"}, + } + ], + }, + {"role": "tool", "tool_call_id": "call-1", "content": json.dumps(items)}, + ], + } + + with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client: + response = client.post("/v1/compress", json=request) + + body = response.json() + assert response.status_code == 200, response.text + assert body["tokens_before"] > body["tokens_after"], body + assert body["tokens_saved"] > 0 + assert body["compression_ratio"] < 1.0 + assert body["transforms_applied"], body