perf(proxy): avoid eager dependency imports (#3546)

## Summary

- Use `importlib.util.find_spec` for proxy dependency availability
checks so startup does not eagerly import heavyweight optional modules
before the server needs them.
- Preserve the existing actionable missing-extra error path.
- Keep stateless proxy processes from creating proxy log files,
savings-ledger files, or a persistent telemetry install ID.
- Refresh the branch from current `main`; the only merge conflict
combined stateless log suppression with `main`'s per-port/per-worker log
naming.

## Validation

- `pytest tests/test_cli_proxy_improvements.py
tests/test_savings_ledger.py tests/test_stateless_writers.py
tests/test_perf_per_port_logs.py -q`: 101 passed, 2 skipped.
- `ruff check` on all touched Python files and focused tests: passed.
- Windows cumulative fork benchmark reported by the contributor: readyz
53.9s → 25.7s, with zero stateless state entries.

## Runtime safety

Default stateful behavior is preserved. Stateless suppression is gated
by the existing `ProxyConfig.stateless` / process stateless setting.
Rollback is a normal revert; no schema or persisted-data migration is
introduced.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3546"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Syamsul Alam
2026-10-08 10:43:20 -05:00
committed by GitHub
co-authored by JerrettDavis
parent d9e29bb260
commit 59bd482fa1
8 changed files with 60 additions and 44 deletions
+4 -3
View File
@@ -5,7 +5,7 @@ import os
import platform
import sys
import warnings
from importlib import import_module
from importlib.util import find_spec
from pathlib import Path
from typing import Any, Literal, cast
@@ -49,8 +49,9 @@ def ensure_proxy_dependencies() -> None:
required_modules.append("orjson")
try:
for module in required_modules:
import_module(module)
missing = next((module for module in required_modules if find_spec(module) is None), None)
if missing is not None:
raise ImportError(f"No module named '{missing}'")
except ImportError as e:
click.secho(
"Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]",
+7 -5
View File
@@ -3180,11 +3180,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
# Installed here (not at module import) so importing headroom.proxy.server
# in tests or library contexts does not silently attach a RotatingFileHandler
# to the user's live proxy log. Multi-worker processes add their PID so
# same-port workers never share a RotatingFileHandler target.
_setup_file_logging(
config.port,
process_id=os.getpid() if config.worker_processes > 1 else None,
)
# same-port workers never share a RotatingFileHandler target. Stateless
# mode must not create a log directory or file.
if not config.stateless:
_setup_file_logging(
config.port,
process_id=os.getpid() if config.worker_processes > 1 else None,
)
# Defensive re-apply of file-backed settings for embedded/non-CLI callers
# that construct the app without going through the `headroom` CLI entrypoint
+3
View File
@@ -306,6 +306,9 @@ def record_savings_event(
zero-saving request is skipped exactly as before.
"""
if _paths.process_is_stateless():
return False
try:
before = max(int(tokens_before), 0)
after = max(int(tokens_after), 0)
+5
View File
@@ -604,6 +604,11 @@ def install_id() -> str:
# outside the lock in read_install_id().
if _install_id is not None:
return _install_id
from headroom import paths
if paths.process_is_stateless():
_install_id = uuid.uuid4().hex
return _install_id
path = _install_id_path()
_install_id = uuid.uuid4().hex
try:
+12 -30
View File
@@ -303,22 +303,16 @@ class TestMissingProxyDepsError:
def test_proxy_command_exits_when_mcp_missing(
self, runner: CliRunner, monkeypatch: pytest.MonkeyPatch
) -> None:
import builtins
from importlib.util import find_spec
real_import = builtins.__import__
def fake_find_spec(name: str) -> object:
return None if name == "mcp" else find_spec(name)
def fake_import(
name: str,
globals: dict | None = None,
locals: dict | None = None,
fromlist: tuple = (),
level: int = 0,
):
if name == "mcp":
raise ImportError("No module named 'mcp'")
return real_import(name, globals, locals, fromlist, level)
monkeypatch.setattr(builtins, "__import__", fake_import)
monkeypatch.setattr("headroom.cli.proxy.find_spec", fake_find_spec)
monkeypatch.setattr(
"uvicorn.run",
lambda *args, **kwargs: pytest.fail("missing dependencies must not start a server"),
)
result = runner.invoke(main, ["proxy"])
assert result.exit_code == 1, result.output
assert "pip install headroom-ai[proxy]" in result.output
@@ -328,24 +322,12 @@ class TestMissingProxyDepsError:
def test_ensure_proxy_dependencies_exits_when_fastapi_missing(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
import builtins
from headroom.cli.proxy import ensure_proxy_dependencies
real_import = builtins.__import__
def fake_import(
name: str,
globals: dict | None = None,
locals: dict | None = None,
fromlist: tuple = (),
level: int = 0,
):
if name == "fastapi":
raise ImportError("No module named 'fastapi'")
return real_import(name, globals, locals, fromlist, level)
monkeypatch.setattr(builtins, "__import__", fake_import)
monkeypatch.setattr(
"headroom.cli.proxy.find_spec",
lambda name: None if name == "fastapi" else object(),
)
with pytest.raises(SystemExit) as exc_info:
ensure_proxy_dependencies()
+7 -4
View File
@@ -78,14 +78,17 @@ def test_proxy_starts_without_watchdog(monkeypatch: pytest.MonkeyPatch) -> None:
requested: list[str] = []
def fake_import(name: str) -> object:
from importlib.machinery import ModuleSpec
def fake_find_spec(name: str) -> ModuleSpec | None:
requested.append(name)
if name == "watchdog":
raise ImportError("No module named 'watchdog'")
return object()
return None
return ModuleSpec(name, loader=None)
monkeypatch.setattr(proxy, "import_module", fake_import)
monkeypatch.setattr(proxy, "find_spec", fake_find_spec)
proxy.ensure_proxy_dependencies()
assert "fastapi" in requested
assert "watchdog" not in requested
+7
View File
@@ -72,6 +72,13 @@ def test_zero_or_negative_savings_not_recorded(monkeypatch, tmp_path):
assert L.aggregate_savings().lifetime["calls"] == 0
def test_stateless_mode_does_not_create_ledger(monkeypatch, tmp_path):
path = _events_env(monkeypatch, tmp_path)
monkeypatch.setenv("HEADROOM_STATELESS", "true")
assert L.record_savings_event(tokens_before=100, tokens_after=50) is False
assert not path.exists()
def test_breakdowns_aggregate_by_dimension(monkeypatch, tmp_path):
_events_env(monkeypatch, tmp_path)
L.record_savings_event(tokens_before=1000, tokens_after=300, model=None, client="claude-code")
+15 -2
View File
@@ -53,6 +53,18 @@ def test_process_stateless_env(monkeypatch, value, expected):
assert paths.process_is_stateless() is expected
def test_install_id_stays_in_memory_when_stateless(tmp_path, monkeypatch):
from headroom.telemetry import session
workspace = tmp_path / "state"
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))
monkeypatch.setattr(session, "_install_id", None)
paths.set_process_stateless(True)
assert len(session.install_id()) == 32
assert not workspace.exists()
# ---- output-savings recorder ----------------------------------------------
@@ -79,14 +91,15 @@ def test_output_savings_flush_persists_when_not_stateless(tmp_path, monkeypatch)
def test_memory_disabled_under_stateless(tmp_path, monkeypatch):
"""A stateless proxy with --memory must not initialize memory or write a DB."""
workspace = tmp_path / "state"
monkeypatch.chdir(tmp_path)
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))
from headroom.proxy.server import ProxyConfig, create_app
app = create_app(ProxyConfig(memory_enabled=True, stateless=True))
proxy = app.state.proxy
assert proxy.memory_handler is None
assert not (tmp_path / ".headroom" / "memory.db").exists()
assert not workspace.exists()
# ---- fastembed model pinning ----------------------------------------------