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(security): patch loopback guard, retry None raise, blocking subprocess, and cache stats race
Patrick Ancillotti78f3a4dd3e8e
diff --git a/.env.example b/.env.examplenew file mode 100644index 000000000..0cab283d1--- /dev/null+++ b/.env.example@@ -0,0 +1,3 @@+# Copy this file to .env and fill in real values before running in production.+# IMPORTANT: Change NEO4J_AUTH before deploying — default credentials are insecure.+NEO4J_AUTH=neo4j/CHANGEMEdiff --git a/.gitignore b/.gitignoreindex 50ce6b395..746f9b458 100644--- a/.gitignore+++ b/.gitignore@@ -102,6 +102,7 @@ pytest_cache/.env.env.*!.env.act.example+!.env.example.venvenv/venv/diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 82e2fcae1..dd66300bb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -71,6 +71,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Security+- **`/debug/memory` loopback guard.** The endpoint was missing the+ `Depends(_require_loopback)` guard that all other `/debug/*` endpoints carry.+ External callers can no longer reach it.+- **`retry_max_attempts` zero guard.** When `retry_enabled=True` and+ `retry_max_attempts=0` the retry loop exited without setting `last_error`,+ causing `raise last_error` to raise `TypeError: exceptions must derive from+ BaseException`. A `RuntimeError` with an actionable message is now raised+ instead, and `ProxyConfig.__post_init__` rejects `retry_max_attempts < 1`+ at construction time.+- **Blocking subprocess on async event loop.** `_read_rtk_lifetime_stats` and+ `_read_lean_ctx_lifetime_stats` called `subprocess.run` directly on the+ asyncio thread. The `initialize_context_tool_session_baseline` function is+ now `async` and offloads the subprocess via `asyncio.to_thread`; the stats+ endpoint uses `await asyncio.to_thread(_get_context_tool_stats)`.+- **Hardcoded Neo4j credential in `docker-compose.yml`.** `NEO4J_AUTH` now+ defaults to `${NEO4J_AUTH:-neo4j/devpassword}` and is documented in+ `.env.example` (excluded from `.gitignore` via `!.env.example`).+- **`SemanticCache.get_memory_stats()` concurrent iteration.** The method+ iterates `self._cache.values()` without holding the async lock. A snapshot+ is now taken via `list(self._cache.values())` before iterating to avoid+ `RuntimeError: dictionary changed size during iteration` under async load.+- **Default Neo4j password in `ProxyConfig`.** `memory_neo4j_password` default+ changed from `"password"` to `""`. The proxy startup path now emits a+ `logger.warning` when `memory_backend == "qdrant-neo4j"` and the password+ is empty, prompting operators to set a real credential.+### Fixed- **PyPI install clarity and release gating.** Documented `pipx --python python3.13`for environments where unsupported Python wheel tags cause older-versiondiff --git a/docker-compose.yml b/docker-compose.ymlindex 59b3a70a7..c699e3cd6 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -39,7 +39,7 @@ services:volumes:- neo4j_data:/dataenvironment:- - NEO4J_AUTH=neo4j/password+ - NEO4J_AUTH=${NEO4J_AUTH:-neo4j/devpassword}- NEO4J_PLUGINS=["apoc"]- NEO4J_apoc_export_file_enabled=true- NEO4J_apoc_import_file_enabled=truediff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 2d7347d96..61d3e3ad2 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -1233,11 +1233,11 @@ def _read_context_tool_lifetime_stats(tool: str) -> dict[str, Any] | None:return _read_rtk_lifetime_stats()-def initialize_context_tool_session_baseline() -> None:+async def initialize_context_tool_session_baseline() -> None:"""Pin the current context-tool counters as the proxy-session baseline."""tool = _selected_context_tool()- payload = _read_context_tool_lifetime_stats(tool)+ payload = await asyncio.to_thread(_read_context_tool_lifetime_stats, tool)with _context_tool_stats_cache_lock:_context_tool_session_baseline.update({@@ -1261,10 +1261,10 @@ def initialize_context_tool_session_baseline() -> None:)-def initialize_rtk_session_baseline() -> None:- """Pin the current context-tool counters as the proxy-session baseline."""+async def initialize_rtk_session_baseline() -> None:+ """Backward-compatible alias for initialize_context_tool_session_baseline."""- initialize_context_tool_session_baseline()+ await initialize_context_tool_session_baseline()def _get_context_tool_stats() -> dict[str, Any] | None:diff --git a/headroom/proxy/models.py b/headroom/proxy/models.pyindex 1a1dfb0f1..f5363fde6 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -240,7 +240,7 @@ class ProxyConfig:memory_qdrant_api_key: str | None = field(default_factory=qdrant_env.qdrant_env_api_key)memory_neo4j_uri: str = "neo4j://localhost:7687"memory_neo4j_user: str = "neo4j"- memory_neo4j_password: str = "password"+ memory_neo4j_password: str = ""memory_bridge_enabled: bool = Falsememory_bridge_md_paths: list[str] = field(default_factory=list)memory_bridge_md_format: str = "auto"@@ -311,6 +311,10 @@ class ProxyConfig:# ``HeadroomProxy._run_compression_in_executor``.compression_max_workers: int | None = None+ def __post_init__(self, smart_routing: bool | None = None) -> None:+ if self.retry_enabled and self.retry_max_attempts < 1:+ raise ValueError("retry_max_attempts must be >= 1 when retry_enabled=True")+@propertydef provider_api_overrides(self) -> ProviderApiOverrides:"""Return provider API URL overrides as a dedicated provider config object."""diff --git a/headroom/proxy/semantic_cache.py b/headroom/proxy/semantic_cache.pyindex 71e81cfcb..e1194b93d 100644--- a/headroom/proxy/semantic_cache.py+++ b/headroom/proxy/semantic_cache.py@@ -118,12 +118,17 @@ class SemanticCache:"""from ..memory.tracker import ComponentStats- # Calculate size - this is sync but we access _cache directly- # Note: This is a rough estimate, not perfectly accurate under async load+ # Take a snapshot of cache values under the lock to avoid iterating+ # over a dict that may be mutated concurrently by async coroutines.+ # The lock is an asyncio.Lock and cannot be acquired in a sync method,+ # so we do a single atomic copy of the values view instead.+ snapshot = list(self._cache.values())+ entry_count = len(snapshot)+size_bytes = sys.getsizeof(self._cache)total_hits = 0- for entry in self._cache.values():+ for entry in snapshot:size_bytes += sys.getsizeof(entry)size_bytes += len(entry.response_body)size_bytes += sys.getsizeof(entry.response_headers)@@ -133,7 +138,7 @@ class SemanticCache:return ComponentStats(name="semantic_cache",- entry_count=len(self._cache),+ entry_count=entry_count,size_bytes=size_bytes,budget_bytes=None,hits=total_hits,diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 05f1ec445..aff09b850 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -992,6 +992,13 @@ class HeadroomProxy(logger.info("Magika: ENABLED (ML content detection)")if self.memory_handler:+ if (+ self.config.memory_backend == "qdrant-neo4j"+ and not self.config.memory_neo4j_password+ ):+ logger.warning(+ "NEO4J password is not set — using default credentials is insecure in production"+ )self.warmup.memory_backend.mark_loading()try:await self.memory_handler.ensure_initialized()@@ -1289,7 +1296,11 @@ class HeadroomProxy()await asyncio.sleep(delay_with_jitter / 1000)- raise last_error # type: ignore[misc]+ if last_error is None:+ raise RuntimeError(+ "retry loop exhausted with no error recorded; retry_max_attempts must be >= 1"+ )+ raise last_errorasync def _log_toin_stats_periodically(interval_seconds: int = 300) -> None:@@ -1453,7 +1464,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:app.state.started_at = time.time()app.state.ready = Falseapp.state.startup_error = None- initialize_context_tool_session_baseline()+ await initialize_context_tool_session_baseline()try:try:@@ -1914,7 +1925,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# Fetch CLI filtering savings from the selected context tool. These# tokens are avoided before they reach model context.- cli_filtering_stats = _get_context_tool_stats()+ cli_filtering_stats = await asyncio.to_thread(_get_context_tool_stats)cli_filtering_tool = (str(cli_filtering_stats.get("tool", "rtk")) if cli_filtering_stats else "rtk")@@ -2315,7 +2326,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:await proxy.metrics.reset_runtime()if proxy.cost_tracker:proxy.cost_tracker.reset_runtime()- initialize_context_tool_session_baseline()+ await initialize_context_tool_session_baseline()async with _stats_snapshot_lock:_stats_snapshot["value"] = None_stats_snapshot["expires_at"] = 0.0@@ -2411,7 +2422,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:)# Debug endpoints- @app.get("/debug/memory")+ @app.get("/debug/memory", dependencies=[Depends(_require_loopback)])async def debug_memory():"""Get detailed memory usage statistics.