1 commit

Author	SHA1	Message	Date
Parideboy	d5ac07fc45	fix(proxy): bind before eager preload so a hung compressor load can't block startup (#1500) ... ## Description On Windows, `headroom proxy` with optimization enabled sometimes never opens its listening port. `HeadroomProxy.startup()` runs inside the ASGI lifespan, which completes **before** uvicorn binds the socket, and the eager compressor/parser/detector preload ran synchronously there. The per-transform loop already swallows exceptions, so the only thing that can still block the bind is a **hang or an uncatchable native stall** during a model load. That matches the report exactly, including that `--no-optimize` (which skips the preload) binds fine. This decouples the preload from the bind by running it off the event loop under a timeout, so startup always returns and the port binds. Closes #790 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `proxy/server.py`: - Extracted the eager-preload loop into a pure sync helper `_eager_preload_transforms()` that returns `(eager_status, transform_statuses)` and does **not** mutate `self.warmup` (so it is safe to run off-thread). - `startup()` now runs it via `asyncio.wait_for(asyncio.to_thread(self._eager_preload_transforms), timeout=EAGER_PRELOAD_TIMEOUT_SECONDS)`. On timeout/exception it logs a warning and continues with empty status, so startup returns and uvicorn binds; transforms fall back to lazy loading on first use. Warmup status is merged on the main thread after the await. - `proxy/helpers.py`: added `EAGER_PRELOAD_TIMEOUT_SECONDS` (default 120s, override via `HEADROOM_EAGER_PRELOAD_TIMEOUT_SECONDS`). The preload is cache-only (`allow_download=False`), so the cap only ever fires on a true hang, never on normal load. - Tests: `tests/test_proxy_eager_preload_bind.py` — helper dedup/exception-swallow, and (via a real `startup()`) that a hung preload no longer blocks startup from returning while a normal transform still merges its warmup status. The happy path is unchanged: a fast preload still completes before `startup()` returns and still populates `self.warmup`. ## Testing - [x] Unit tests pass (`pytest tests/test_proxy_eager_preload_bind.py`) - [x] Linting passes (`ruff check`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed (live Windows proxy smoke — see proof) ### Test Output ```text $ pytest tests/test_proxy_eager_preload_bind.py -q tests\test_proxy_eager_preload_bind.py ... [100%] 3 passed in 7.66s $ ruff check headroom/proxy/server.py headroom/proxy/helpers.py tests/test_proxy_eager_preload_bind.py All checks passed! $ mypy headroom --ignore-missing-imports # changed files: no new errors ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.13.11, `headroom` 0.28.0, Rust `_core` loaded. - Exact command / steps: start the proxy with optimization enabled (which runs the preload), then curl `/health`. ```text headroom proxy --port 8799 --no-telemetry # optimization ENABLED (runs the preload) curl http://127.0.0.1:8799/health ``` - Observed result: the port binds and `/health` returns HTTP 200 with the preload-bearing startup reported healthy: ```text HTTP_STATUS=200 {"service":"headroom-proxy","status":"healthy","ready":true, "checks":{"startup":{"enabled":true,"ready":true,"status":"healthy","error":null}, ...}, "config":{"optimize":true, ...}, "rust_core":"loaded"} ``` Startup completed and the socket bound with `optimize:true` on a Windows host — the path that previously could hang before binding. - Not tested: a real native model-load hang on Windows (no reliable way to induce the uncatchable native stall on demand). The regression test proves the timeout/bind decoupling deterministically by injecting a transform that blocks past the timeout and asserting `startup()` still returns promptly. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes - Linux CI cannot reproduce the native Windows hang; the regression test proves the decoupling (startup returns despite a blocking preload), not the native root cause. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-28 13:15:50 -07:00