Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: A0 — fail-loud rust core deployment smoke test
chopratejas00ab1ea74dd9
diff --git a/Dockerfile b/Dockerfileindex 5ed9da360..ddddb00c4 100644--- a/Dockerfile+++ b/Dockerfile@@ -12,14 +12,32 @@ FROM python:${PYTHON_VERSION}-slim@${PYTHON_DIGEST} AS builderARG UV_VERSION+# build-essential / g++ for any C extension wheels uv may need to build+# from source. curl + ca-certificates are required by the rustup+# bootstrap below. Hotfix-A0 (Finding #2) added the rust toolchain so the+# image actually carries `headroom._core`; previously the runtime image+# shipped without the Rust extension and every compressed request fell+# back to a Python-only path or no-op.RUN apt-get update && \apt-get install -y --no-install-recommends \build-essential \g++ \+ curl \+ ca-certificates \&& rm -rf /var/lib/apt/lists/*RUN python -m pip install --no-cache-dir uv==${UV_VERSION}+# Rust toolchain for the headroom._core extension build. Pinned via+# rust-toolchain.toml at the repo root so this matches what local devs+# build with. Installed as root before WORKDIR change so the env+# additions stick for every subsequent RUN.+ENV CARGO_HOME=/usr/local/cargo \+ RUSTUP_HOME=/usr/local/rustup \+ PATH=/usr/local/cargo/bin:${PATH}+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \+ | sh -s -- -y --no-modify-path --profile minimal --default-toolchain stable+WORKDIR /build# Layer 1: install deps only (cached unless pyproject.toml/uv.lock change)@@ -35,6 +53,28 @@ COPY headroom/ headroom/RUN --mount=type=cache,target=/root/.cache/uv \uv pip install --system --no-deps --reinstall-package headroom-ai .+# Layer 3 (Hotfix-A0): build and install the Rust extension wheel. uv+# already installed `maturin` as a transitive of the [proxy]/[code]+# extras; if it didn't, install it explicitly here so the build never+# silently skips.+COPY crates/ crates/+COPY Cargo.toml Cargo.lock rust-toolchain.toml ./+RUN --mount=type=cache,target=/root/.cache/uv \+ --mount=type=cache,target=/root/.cargo/registry \+ --mount=type=cache,target=/build/target \+ uv pip install --system maturin \+ && maturin build --release -m crates/headroom-py/Cargo.toml --out /build/wheels \+ && uv pip install --system --force-reinstall --no-deps /build/wheels/headroom_core_py-*.whl++# Layer 4 (Hotfix-A0): verify the extension actually loads end-to-end+# inside the build image. If this fails, the runtime image would fail+# its lifespan smoke test on every restart — better to break the build+# loudly here than ship a broken image.+RUN python -c "from headroom._core import hello; \+ marker = hello(); \+ assert marker == 'headroom-core', f'expected headroom-core, got {marker!r}'; \+ print(f'build-stage rust core verify OK: {marker}')"+# ---- Runtime stage (python-slim): supports root/nonroot via build arg ----FROM python:${PYTHON_VERSION}-slim@${PYTHON_DIGEST} AS runtime-slim-basediff --git a/Makefile b/Makefileindex cc02bc05d..ed43fb836 100644--- a/Makefile+++ b/Makefile@@ -7,7 +7,7 @@ MATURIN ?= maturinPYTHON ?= python3FIXTURES ?= tests/parity/fixtures-.PHONY: help test test-parity bench build-proxy build-wheel fmt fmt-check lint clippy clean ci-precheck ci-precheck-rust ci-precheck-python ci-precheck-commitlint install-git-hooks+.PHONY: help test test-parity bench build-proxy build-wheel fmt fmt-check lint clippy clean ci-precheck ci-precheck-rust ci-precheck-python ci-precheck-commitlint install-git-hooks verify-rust-corehelp:@echo "Headroom Rust targets:"@@ -16,6 +16,7 @@ help:@echo " make bench - cargo bench --workspace"@echo " make build-proxy - release build + strip headroom-proxy, print size"@echo " make build-wheel - release wheel for headroom-py"+ @echo " make verify-rust-core - build + install + import-verify headroom._core"@echo " make fmt - cargo fmt --all"@echo " make fmt-check - cargo fmt --all -- --check"@echo " make lint - cargo clippy --workspace -- -D warnings"@@ -52,6 +53,18 @@ build-proxy:build-wheel:$(MATURIN) build --release -m crates/headroom-py/Cargo.toml+# Hotfix-A0: maturin-develop + symlink + import-verify in one shot. Run this+# any time you suspect the proxy is silently falling back to Python-only+# mode (Finding #2 in HEADROOM_PROXY_LOG_FINDINGS_2026_05_03.md). The+# proxy itself runs the same check at lifespan startup; this target+# exposes it as a developer-facing one-liner.+verify-rust-core:+ @if [ -z "$$VIRTUAL_ENV" ]; then \+ echo "error: activate a venv first (e.g. source .venv/bin/activate)"; \+ exit 1; \+ fi+ bash scripts/build_rust_extension.sh+fmt:$(CARGO) fmt --alldiff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 3f29f6fe5..4f66d0f0a 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -186,6 +186,93 @@ logger = logging.getLogger("headroom.proxy")_MULTI_WORKER_CONFIG_ENV = "HEADROOM_PROXY_CONFIG_JSON"+# Env var that opts out of the Rust core deployment smoke test (Hotfix-A0).+# Default behavior: hard-fail at startup if `headroom._core` is unimportable+# (Finding #2 in HEADROOM_PROXY_LOG_FINDINGS_2026_05_03.md — production+# deployment was silently running without the Rust extension and degrading+# every compressed request to a Python-only path or a no-op).+#+# Set to the literal string "false" to start the proxy in degraded+# Python-only mode. Any other value (including unset) keeps the+# fail-loud behavior.+_RUST_CORE_REQUIRED_ENV = "HEADROOM_REQUIRE_RUST_CORE"++# sysexits.h(3) — EX_CONFIG. Process supervisors (systemd, k8s, docker)+# treat this as a deliberate configuration failure rather than a crash, so+# they won't restart-loop on a broken deployment.+_EXIT_CONFIG = 78+++def _check_rust_core() -> tuple[str, str | None]:+ """Verify the Rust extension `headroom._core` is loadable at startup.++ Returns a `(status, error)` tuple:+ - ``("loaded", None)`` — `headroom._core.hello()` returned the+ expected sentinel.+ - ``("disabled", reason)`` — opt-out env var was set; proxy starts+ in Python-only degraded mode. `reason` carries the underlying+ import error (or ``None`` if the import actually succeeded).+ - ``("missing", reason)`` — never returned: this branch calls+ ``sys.exit(78)`` so the proxy refuses to start. The branch exists+ only as a typed sentinel for callers that want to reason about+ all three states (e.g. health endpoints).++ Behavior is gated by the ``HEADROOM_REQUIRE_RUST_CORE`` env var:+ any value other than ``"false"`` (case-insensitive) keeps the+ fail-loud default.+ """+ require = os.environ.get(_RUST_CORE_REQUIRED_ENV, "true").strip().lower() != "false"+ try:+ from headroom._core import hello as _rust_hello++ marker = _rust_hello()+ except Exception as exc: # ImportError, but also any init-time PyO3 failure+ reason = f"{type(exc).__name__}: {exc}"+ if not require:+ logger.warning(+ "event=rust_core_disabled reason=%r opt_out_env=%s=false mode=python_only_degraded",+ reason,+ _RUST_CORE_REQUIRED_ENV,+ )+ return ("disabled", reason)+ # Fail loud. Print to stderr in addition to logging so operators+ # see it even if the logging handler is mis-configured.+ msg = (+ f"FATAL: Rust extension `headroom._core` not loadable.\n"+ f" error: {reason}\n"+ f" fix: `make build-wheel && pip install --force-reinstall "+ f"target/wheels/headroom_*.whl`\n"+ f" opt-out: set {_RUST_CORE_REQUIRED_ENV}=false to start in "+ f"degraded Python-only mode\n"+ )+ logger.error("event=rust_core_missing reason=%r action=exit_78", reason)+ print(msg, file=sys.stderr, flush=True)+ sys.exit(_EXIT_CONFIG)++ # Import succeeded; sanity-check the marker so we catch a stale or+ # mis-linked .so where the symbol name resolves but returns garbage.+ if marker != "headroom-core":+ reason = f"unexpected marker {marker!r}"+ if not require:+ logger.warning(+ "event=rust_core_disabled reason=%r opt_out_env=%s=false",+ reason,+ _RUST_CORE_REQUIRED_ENV,+ )+ return ("disabled", reason)+ msg = (+ f"FATAL: Rust extension `headroom._core` is loaded but the "+ f"marker function returned {marker!r}; expected 'headroom-core'.\n"+ f" fix: rebuild: `make build-wheel && pip install "+ f"--force-reinstall target/wheels/headroom_*.whl`\n"+ )+ logger.error("event=rust_core_marker_mismatch marker=%r action=exit_78", marker)+ print(msg, file=sys.stderr, flush=True)+ sys.exit(_EXIT_CONFIG)++ logger.info("event=rust_core_loaded marker=%r", marker)+ return ("loaded", None)+# Compression pipeline timeout in seconds@@ -1258,6 +1345,17 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:@asynccontextmanagerasync def lifespan(app: FastAPI): # type: ignore[no-untyped-def]+ # Hotfix-A0: Rust core deployment smoke test. Refuse to accept+ # traffic if the Rust extension is missing unless the operator+ # explicitly opted out with HEADROOM_REQUIRE_RUST_CORE=false. See+ # Finding #2 in HEADROOM_PROXY_LOG_FINDINGS_2026_05_03.md.+ # `_check_rust_core` either returns ("loaded"|"disabled", _) or+ # calls `sys.exit(78)` — execution past this line implies the+ # rust_core_status is recorded.+ _rust_core_status, _rust_core_error = _check_rust_core()+ app.state.rust_core_status = _rust_core_status+ app.state.rust_core_error = _rust_core_error+configure_otel_metrics(OTelMetricsConfig.from_env(default_service_name="headroom-proxy"))configure_langfuse_tracing(LangfuseTracingConfig.from_env(default_service_name="headroom-proxy")@@ -1315,6 +1413,12 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:app.state.started_at = Noneapp.state.ready = Falseapp.state.startup_error = None+ # Set by the lifespan startup smoke test (`_check_rust_core`). Default+ # "missing" means lifespan hasn't run yet — anything reading /health+ # before startup completes (rare; lifespan runs before the first+ # request) sees an honest "missing" rather than a stale "loaded".+ app.state.rust_core_status = "missing"+ app.state.rust_core_error = Nonedef _iso_utc_now() -> str:return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")@@ -1432,7 +1536,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"uptime_seconds": _uptime_seconds(),"checks": checks,"runtime": _runtime_payload(),+ # Hotfix-A0: surface rust core load state so operators can alert+ # on `rust_core != "loaded"` (Finding #2).+ "rust_core": getattr(app.state, "rust_core_status", "missing"),}+ rust_core_error = getattr(app.state, "rust_core_error", None)+ if rust_core_error:+ payload["rust_core_error"] = rust_core_errordeployment_profile = os.environ.get("HEADROOM_DEPLOYMENT_PROFILE")if deployment_profile:payload["deployment"] = {diff --git a/scripts/build_rust_extension.sh b/scripts/build_rust_extension.shindex 0e678540c..68c0fa30f 100755--- a/scripts/build_rust_extension.sh+++ b/scripts/build_rust_extension.sh@@ -9,37 +9,82 @@# the maturin overlay, so `import headroom._core` fails. Symlinking the# built `.so` into `headroom/` fixes the lookup with zero copies.#+# Hotfix-A0 (2026-05-02): the script now also runs an end-to-end import+# verification with the `hello()` marker so a partial / stale build is+# caught before the proxy is started. This mirrors the lifespan smoke+# test in `headroom.proxy.server._check_rust_core` so dev-time and+# deploy-time both catch the same class of failure.+## Idempotent. Safe to run repeatedly. Requires `maturin` in PATH (i.e.# inside the project venv).set -euo pipefail+# Move to repo root so all relative paths below are stable.cd "$(dirname "$0")/.."-if ! command -v maturin >/dev/null 2>&1; then- echo "error: maturin not found. Activate the venv first:" >&2- echo " source .venv/bin/activate" >&2+log() {+ printf '[build_rust_extension] %s\n' "$*" >&2+}++fail() {+ printf '[build_rust_extension] error: %s\n' "$*" >&2exit 1+}++# Step 1: pre-flight. Maturin must be on PATH and a venv must be active —+# `maturin develop` writes into site-packages, and we want that write to+# land in the same env the proxy will run in.+if ! command -v maturin >/dev/null 2>&1; then+ fail "maturin not found on PATH. Activate the venv first: source .venv/bin/activate"fi-# Build the wheel + install into the venv site-packages.-maturin develop -m crates/headroom-py/Cargo.toml+if [[ -z "${VIRTUAL_ENV:-}" ]]; then+ log "warning: VIRTUAL_ENV is unset; maturin will install into the system Python."+ log " If that is not what you want, abort and 'source .venv/bin/activate' first."+fi++# Step 2: build + install via `maturin develop` (in-place editable install+# with C extensions). This produces a `.so` under+# crates/headroom-py/python/headroom/.+log "step 1/3: maturin develop"+maturin develop -m crates/headroom-py/Cargo.toml \+ || fail "maturin develop failed (see output above)"-# Locate the built `.so`. `maturin develop` writes it under-# `crates/headroom-py/python/headroom/_core.cpython-<ver>-<platform>.so`.+# Step 3: locate the built artifact. `maturin develop` writes+# `_core.cpython-<ver>-<platform>.{so,dylib,pyd}` into the package dir.SO_FILE=$(find crates/headroom-py/python/headroom -maxdepth 1 \- -name "_core.cpython-*.so" -o -name "_core.cpython-*.dylib" -o -name "_core.pyd" \- 2>/dev/null | head -1)+ \( -name "_core.cpython-*.so" -o -name "_core.cpython-*.dylib" -o -name "_core.pyd" \) \+ 2>/dev/null | head -1 || true)-if [[ -z "$SO_FILE" ]]; then- echo "error: maturin develop succeeded but produced no _core.* binary." >&2- exit 1+if [[ -z "${SO_FILE}" ]]; then+ fail "maturin develop succeeded but produced no _core.* binary in crates/headroom-py/python/headroom/"fi-# Symlink into the in-tree package dir.-LINK_NAME="headroom/$(basename "$SO_FILE")"-ln -sf "$(pwd)/$SO_FILE" "$LINK_NAME"-echo "linked: $LINK_NAME -> $SO_FILE"+# Step 4: symlink into the in-tree package dir so the in-tree+# `headroom/__init__.py` resolves the `_core` submodule. Only the symlink+# style is supported; copy semantics drift on every rebuild.+LINK_NAME="headroom/$(basename "${SO_FILE}")"+ln -sf "$(pwd)/${SO_FILE}" "${LINK_NAME}" \+ || fail "failed to symlink ${SO_FILE} into ${LINK_NAME}"+log "step 2/3: linked ${LINK_NAME} -> ${SO_FILE}"++# Step 5: end-to-end import verification. This is the same check the+# proxy lifespan runs at startup. Failing here means the build produced+# something that can't be loaded — fix the build, don't fix the proxy.+log "step 3/3: verifying \`from headroom._core import hello\`"+python -c '+import sys+try:+ from headroom._core import hello, DiffCompressor+except Exception as exc:+ print(f"verify FAILED: {type(exc).__name__}: {exc}", file=sys.stderr)+ sys.exit(1)+marker = hello()+if marker != "headroom-core":+ print(f"verify FAILED: hello() returned {marker!r}, expected \"headroom-core\"", file=sys.stderr)+ sys.exit(1)+print(f"verify OK: hello()={marker!r}, DiffCompressor={DiffCompressor!r}")+' || fail "import verification failed (see above)"-# Smoke-test the import to fail loudly if anything is misconfigured.-python -c "from headroom._core import DiffCompressor; print('headroom._core OK:', DiffCompressor)"+log "headroom._core build + install + verify: OK"diff --git a/tests/test_rust_core_smoke.py b/tests/test_rust_core_smoke.pynew file mode 100644index 000000000..e45d5461c--- /dev/null+++ b/tests/test_rust_core_smoke.py@@ -0,0 +1,179 @@+"""Hotfix-A0 smoke tests: deployment-stage Rust core verification.++Background — Finding #2 of HEADROOM_PROXY_LOG_FINDINGS_2026_05_03.md.+A customer's production proxy was silently running without the+`headroom._core` PyO3 extension because the Docker image never built it+into the runtime layer. Diff compression failed 54 times in one day;+optimization failed 379 times. Once the failure rate hit ~100%, every+Rust port we'd shipped was providing zero customer value.++These tests pin the contract for the fix:++1. The PyO3 module exposes a `hello()` marker function returning+ ``"headroom-core"`` so the deployment smoke test has something stable+ to latch onto. Reusing an existing function instead of inventing a+ new one means we don't drift the Rust API surface for diagnostic+ purposes.++2. The proxy lifespan refuses to start when ``headroom._core`` is+ unimportable, exiting with `sysexits.h` ``EX_CONFIG`` (78) so process+ supervisors recognize this as a deliberate configuration failure+ rather than a crash they should retry forever.++3. An explicit opt-out — ``HEADROOM_REQUIRE_RUST_CORE=false`` — keeps+ the dev-time `pip install -e .` workflow alive without forcing every+ contributor to run maturin.++The opt-out test also verifies that `/health` surfaces the rust core+state so operators can alert on `rust_core != "loaded"` in production.+"""++from __future__ import annotations++import pytest+++# ──────────────────────────────────────────────────────────────────────────+# 1. The Rust extension's `hello()` marker is stable and importable.+# ──────────────────────────────────────────────────────────────────────────+def test_rust_core_imports() -> None:+ """`headroom._core.hello()` returns the documented sentinel.++ The deployment smoke test (`headroom.proxy.server._check_rust_core`)+ asserts on the exact return value so a stale or mis-linked .so is+ caught — not just a complete `ImportError`. If you change the marker+ string, you also need to update the lifespan check to match.+ """+ from headroom._core import hello++ assert hello() == "headroom-core"+++# ──────────────────────────────────────────────────────────────────────────+# 2. Default behavior: missing extension blocks startup with exit 78.+# ──────────────────────────────────────────────────────────────────────────+def test_proxy_refuses_to_start_when_rust_core_missing(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """When `headroom._core` raises ImportError on import and the opt-out+ env var is not set, the lifespan smoke test must call `sys.exit(78)`.++ We invoke the helper directly (rather than spinning up FastAPI)+ because the helper is the single source of truth for the policy and+ `sys.exit` propagates through the lifespan context manager+ transparently. Hitting it directly keeps the test tight and avoids+ the lifespan's 30+ side effects (OTel, Langfuse, beacon, ...).+ """+ from headroom.proxy import server++ # Ensure the env var is absent so the default fail-loud path runs.+ monkeypatch.delenv("HEADROOM_REQUIRE_RUST_CORE", raising=False)++ # Force the import to raise. Patching the symbol on the module is+ # not enough because `_check_rust_core` runs `from headroom._core+ # import hello` inside its body — we need the import machinery to+ # raise. `sys.modules` is the cleanest hook for that.+ import sys++ # Pre-purge any cached binding so the import statement re-runs.+ sys.modules.pop("headroom._core", None)+ # Sentinel that pretends to be the module but raises on attribute+ # access. `from X import Y` first looks up `X` in sys.modules; if+ # present it skips re-import and uses it directly. Setting+ # sys.modules["headroom._core"] to None forces a real ImportError.+ sys.modules["headroom._core"] = None # type: ignore[assignment]++ try:+ with pytest.raises(SystemExit) as exc_info:+ server._check_rust_core()+ assert exc_info.value.code == 78, (+ f"expected exit code 78 (EX_CONFIG), got {exc_info.value.code!r}"+ )+ finally:+ # Restore the real module so subsequent tests can import it.+ sys.modules.pop("headroom._core", None)+++# ──────────────────────────────────────────────────────────────────────────+# 3. Opt-out path: HEADROOM_REQUIRE_RUST_CORE=false → degraded mode + /health.+# ──────────────────────────────────────────────────────────────────────────+def test_proxy_starts_in_degraded_mode_when_opt_out_set(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """With the opt-out env var set, the lifespan must start successfully+ even when `headroom._core` is missing, and `/health` must surface+ `rust_core: "disabled"` so operators can detect the degraded mode.++ We spin up a real FastAPI app via `TestClient` because the spec+ requires the health endpoint to reflect the lifespan state — the+ helper alone doesn't tell us the wiring is right.+ """+ from fastapi.testclient import TestClient++ from headroom.proxy.server import ProxyConfig, create_app++ monkeypatch.setenv("HEADROOM_REQUIRE_RUST_CORE", "false")++ # Force the import to fail at lifespan time. Same trick as above:+ # sys.modules["headroom._core"] = None makes Python treat the module+ # as known-unimportable, raising ImportError on the next `from ...+ # import` without re-trying the loader.+ import sys++ sys.modules.pop("headroom._core", None)+ sys.modules["headroom._core"] = None # type: ignore[assignment]++ config = ProxyConfig(+ optimize=False,+ image_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,+ )+ app = create_app(config)++ try:+ with TestClient(app) as client:+ response = client.get("/health")+ assert response.status_code == 200+ payload = response.json()+ assert payload["rust_core"] == "disabled", (+ f"expected rust_core=disabled, got {payload.get('rust_core')!r}; "+ f"full payload keys: {sorted(payload.keys())}"+ )+ # The error reason should be carried through so operators can+ # see *why* the extension isn't loaded.+ assert "rust_core_error" in payload+ assert (+ "ModuleNotFoundError" in payload["rust_core_error"]+ or "ImportError" in payload["rust_core_error"]+ )+ finally:+ sys.modules.pop("headroom._core", None)+++# ──────────────────────────────────────────────────────────────────────────+# 4. Happy path through the helper: real extension present → status=loaded.+# ──────────────────────────────────────────────────────────────────────────+def test_check_rust_core_returns_loaded_when_extension_present(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """When `headroom._core` is loadable and `hello()` returns the+ expected sentinel, `_check_rust_core` returns ``("loaded", None)``.++ This covers the production-happy path so a future change that+ breaks the marker check (e.g. tightening to require a JSON dict+ return) will fail this test rather than degrading silently.+ """+ from headroom.proxy import server++ # Make sure the env var doesn't tip us into the disabled branch.+ monkeypatch.delenv("HEADROOM_REQUIRE_RUST_CORE", raising=False)++ status, error = server._check_rust_core()+ assert status == "loaded"+ assert error is None