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(transforms): bound native content detection with a Windows watchdog (#575) (#1563)
Parideboy95abca3abd69
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex d9ce37096..163881895 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -42,6 +42,7 @@ import mathimport osimport reimport sys+import threadingimport timefrom concurrent.futures import ThreadPoolExecutorfrom dataclasses import dataclass, field@@ -66,6 +67,7 @@ logger = logging.getLogger(__name__)_detect_backend_warned = False_detect_panic_warned = False+_detect_native_unhealthy = False # circuit breaker: native detect hung once (#575)def _router_debug_dumps(value: Any) -> str:@@ -129,6 +131,60 @@ def _resolve_detect_backend() -> str:return "python" if sys.platform == "win32" else "rust"+_DETECT_TIMEOUT_ENV = "HEADROOM_DETECT_TIMEOUT_SECS"+_DEFAULT_DETECT_TIMEOUT_SECS = 5.0+++def _detect_timeout_secs() -> float:+ """Watchdog budget (seconds) for one native detect call.++ Override with ``HEADROOM_DETECT_TIMEOUT_SECS``; blank, non-numeric, or+ non-positive values fall back to the default.+ """+ raw = os.environ.get(_DETECT_TIMEOUT_ENV, "").strip()+ if not raw:+ return _DEFAULT_DETECT_TIMEOUT_SECS+ try:+ secs = float(raw)+ except ValueError:+ return _DEFAULT_DETECT_TIMEOUT_SECS+ return secs if secs > 0 else _DEFAULT_DETECT_TIMEOUT_SECS+++def _rust_detect_watchdogged(rust_detect: Any, content: str, timeout: float) -> Any:+ """Run the native detector under a watchdog thread, bounding the caller's wait.++ On Windows the first native ``detect_content_type`` can park forever in an+ ort/``Once`` init (``WaitOnAddress``) at 0% CPU, and a wedged native call+ cannot be cancelled from Python (#575). The native call releases the GIL+ while parked, so a watchdog thread runs it and the caller waits at most+ ``timeout`` seconds before raising ``TimeoutError`` — letting+ ``_detect_content`` degrade to the pure-Python detector instead of+ deadlocking (and, in the proxy, instead of permanently consuming a+ compression-executor worker — see #575's executor-saturation report).++ # ponytail: can't kill a GIL-released native call; the watchdog frees the+ # caller and the stuck daemon thread is left to die with the process. The+ # upgrade path is the Rust-side fix that makes first-call init non-blocking.+ """+ box: dict[str, Any] = {}++ def _run() -> None:+ try:+ box["result"] = rust_detect(content)+ except BaseException as exc: # noqa: BLE001 — relayed to the caller's degrade path+ box["error"] = exc++ worker = threading.Thread(target=_run, name="headroom-detect-watchdog", daemon=True)+ worker.start()+ worker.join(timeout)+ if worker.is_alive():+ raise TimeoutError(f"native detect_content_type exceeded {timeout:.1f}s watchdog")+ if "error" in box:+ raise box["error"]+ return box["result"]++def _detect_content(content: str) -> DetectionResult:"""Detect content type via the native chain, with a safe Windows default.@@ -144,7 +200,7 @@ def _detect_content(content: str) -> DetectionResult:only consumed `.content_type` from it; the strategy mapping in`_strategy_from_detection` keys off that field alone."""- global _detect_backend_warned+ global _detect_backend_warned, _detect_panic_warned, _detect_native_unhealthybackend = _resolve_detect_backend()if backend == "python":@@ -157,11 +213,23 @@ def _detect_content(content: str) -> DetectionResult:)return _regex_detect_content_type(content)+ if _detect_native_unhealthy:+ # Circuit breaker (#575): the native detector hung once under the+ # watchdog; every later call would wait the full budget and strand+ # another stuck daemon thread, so route straight to pure-Python.+ return _regex_detect_content_type(content)+from headroom._core import detect_content_type as _rust_detect- global _detect_panic_warnedtry:- rust_result = _rust_detect(content)+ if sys.platform == "win32":+ # Windows is the only platform where the native detector can deadlock+ # on first use (#575); bound it with a watchdog so a hang degrades to+ # the pure-Python detector below. Elsewhere it is the trusted default+ # hot path — call it directly, with no per-call thread overhead.+ rust_result = _rust_detect_watchdogged(_rust_detect, content, _detect_timeout_secs())+ else:+ rust_result = _rust_detect(content)# Rust's `content_type` is the lowercase string tag (e.g.# "json_array"); translate to the Python `ContentType` enum so# downstream mapping keys match.@@ -178,7 +246,17 @@ def _detect_content(content: str) -> DetectionResult:# as asyncio.CancelledError — keep them propagating.if isinstance(exc, asyncio.CancelledError):raise- if not _detect_panic_warned:+ if isinstance(exc, TimeoutError):+ # Watchdog tripped: the native detector hung (#575). Disable it+ # process-wide so later calls don't each wait the full budget and+ # strand another daemon thread in the wedged native call.+ _detect_native_unhealthy = True+ logger.warning(+ "Native content detector hung (%s); disabling it for this process "+ "and using pure-Python detection.",+ exc,+ )+ elif not _detect_panic_warned:_detect_panic_warned = Truelogger.warning("Native content detector failed (%s); falling back to pure-Python detection.",diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.pyindex 838eabbe4..d98701616 100644--- a/tests/test_transforms_content_router.py+++ b/tests/test_transforms_content_router.py@@ -21,6 +21,19 @@ from headroom.transforms.content_router import ()[email protected](autouse=True)+def _reset_detect_module_state(monkeypatch: pytest.MonkeyPatch) -> None:+ """Keep the module-level detect flags from leaking across tests.++ The circuit breaker (#575) is process-wide, so a test that trips it would+ otherwise force later tests onto the pure-Python path. ``monkeypatch.setattr``+ zeroes each flag for the test and auto-restores it afterward.+ """+ monkeypatch.setattr(content_router_module, "_detect_native_unhealthy", False)+ monkeypatch.setattr(content_router_module, "_detect_backend_warned", False)+ monkeypatch.setattr(content_router_module, "_detect_panic_warned", False)++def test_compression_cache_handles_hits_skips_evictions_and_clear(monkeypatch: pytest.MonkeyPatch,) -> None:@@ -864,3 +877,115 @@ def test_detect_content_python_backend_skips_native(result = _detect_content('[{"id": 1}, {"id": 2}]')assert result.content_type is ContentType.JSON_ARRAY+++def test_detect_timeout_secs_env_parsing(monkeypatch: pytest.MonkeyPatch) -> None:+ """The watchdog budget reads HEADROOM_DETECT_TIMEOUT_SECS; bad values → default."""+ get = content_router_module._detect_timeout_secs+ default = content_router_module._DEFAULT_DETECT_TIMEOUT_SECS++ monkeypatch.delenv("HEADROOM_DETECT_TIMEOUT_SECS", raising=False)+ assert get() == default++ monkeypatch.setenv("HEADROOM_DETECT_TIMEOUT_SECS", "0.25")+ assert get() == 0.25++ monkeypatch.setenv("HEADROOM_DETECT_TIMEOUT_SECS", "nope")+ assert get() == default++ monkeypatch.setenv("HEADROOM_DETECT_TIMEOUT_SECS", "0")+ assert get() == default+++def test_rust_detect_watchdog_passes_through_result() -> None:+ """A fast native detector returns its result unchanged through the watchdog."""+ sentinel = SimpleNamespace(content_type="json_array", confidence=1.0, metadata={})+ out = content_router_module._rust_detect_watchdogged(lambda _content: sentinel, "payload", 5.0)+ assert out is sentinel+++def test_rust_detect_watchdog_relays_native_error() -> None:+ """An exception raised inside the native detector propagates to the caller."""++ def boom(_content: str) -> None:+ raise ValueError("native boom")++ with pytest.raises(ValueError, match="native boom"):+ content_router_module._rust_detect_watchdogged(boom, "payload", 5.0)+++def test_detect_content_watchdog_degrades_on_windows_hang(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A hung native detect on Windows degrades to pure-Python, never deadlocks (#575)."""+ import threading as _threading++ import headroom._core as _core++ monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "rust")+ monkeypatch.setattr(content_router_module.sys, "platform", "win32")+ monkeypatch.setenv("HEADROOM_DETECT_TIMEOUT_SECS", "0.1")++ release = _threading.Event()++ def _hang(_content: str):+ release.wait() # simulate the WaitOnAddress park (GIL released while waiting)+ return SimpleNamespace(content_type="plain_text", confidence=1.0, metadata={})++ monkeypatch.setattr(_core, "detect_content_type", _hang)++ try:+ # JSON content: the pure-Python regex fallback recognizes it as JSON_ARRAY,+ # proving we took the degrade path rather than the (hung) native result.+ result = _detect_content('[{"id": 1}]')+ assert result.content_type is ContentType.JSON_ARRAY+ finally:+ release.set() # let the daemon worker finish so it does not linger+++def test_detect_content_watchdog_uses_native_result_on_windows(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """On Windows with rust forced, a fast native result still flows through unchanged."""+ import headroom._core as _core++ monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "rust")+ monkeypatch.setattr(content_router_module.sys, "platform", "win32")++ fake = SimpleNamespace(content_type="source_code", confidence=1.0, metadata={})+ monkeypatch.setattr(_core, "detect_content_type", lambda _content: fake)++ result = _detect_content("def main(): pass")+ assert result.content_type is ContentType.SOURCE_CODE+++def test_detect_content_circuit_breaker_skips_native_after_hang(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """After one watchdog timeout, native detection is disabled process-wide (#575)."""+ import threading as _threading++ import headroom._core as _core++ monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "rust")+ monkeypatch.setattr(content_router_module.sys, "platform", "win32")+ monkeypatch.setenv("HEADROOM_DETECT_TIMEOUT_SECS", "0.1")++ release = _threading.Event()+ calls = 0++ def _hang(_content: str):+ nonlocal calls+ calls += 1+ release.wait() # park with GIL released, like the real WaitOnAddress hang+ return SimpleNamespace(content_type="plain_text", confidence=1.0, metadata={})++ monkeypatch.setattr(_core, "detect_content_type", _hang)+ try:+ first = _detect_content('[{"id": 1}]')+ second = _detect_content('[{"id": 2}]')+ assert first.content_type is ContentType.JSON_ARRAY+ assert second.content_type is ContentType.JSON_ARRAY+ assert calls == 1 # breaker tripped: native entered once, 2nd call skipped it+ finally:+ release.set() # let the lone daemon worker finish