fix(proxy): don't fail startup when libc_ver() can't read the interpreter (#4519)

## Description

On Windows with Microsoft Store Python, `headroom proxy` exits during
startup with code 3:

```text
  File ".../headroom/proxy/server.py", line 2007, in _start_kompress_background_warmup
    libc, version = platform.libc_ver()
  File "...\Lib\platform.py", line 200, in libc_ver
    with open(executable, 'rb') as f:
OSError: [Errno 22] Invalid argument: 'C:\\Users\\<user>\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe'
ERROR:    Application startup failed. Exiting.
```

Here's how it happens:
1. When `HEADROOM_KOMPRESS_WARMUP` is unset,
`_start_kompress_background_warmup` calls `platform.libc_ver()` to skip
warm-up on glibc < 2.28 (#1908). It does this on every OS.
2. `platform.libc_ver()` works by opening `sys.executable` and scanning
its bytes.
3. On Store Python, `sys.executable` is the
`...\WindowsApps\...\python.exe` app-execution alias, which can't be
opened for reading, so `open()` raises `OSError` (Errno 22).
4. Nothing catches it, so lifespan startup fails.

This PR catches `OSError` from `libc_ver()` and treats the interpreter
as non-glibc, which is correct on Windows. The warm-up then runs as it
does on any other non-glibc platform. The glibc < 2.28 skip is
unchanged: on glibc, `libc_ver()` returns the version from
`os.confstr('CS_GNU_LIBC_VERSION')` and never opens the executable, so
the new `except` can't fire on the hosts #1908 protects.

Workaround until this ships: set `HEADROOM_KOMPRESS_WARMUP=1` (or `0`),
which skips the `libc_ver()` call.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/proxy/server.py`: wrap `platform.libc_ver()` in `try/except
OSError`, falling back to "not glibc".
- `tests/test_proxy/test_kompress_background_warmup.py`: regression
test. When `libc_ver()` raises `OSError`, the warm-up still starts
instead of the error propagating.

## Testing

- [x] Unit tests pass (`pytest
tests/test_proxy/test_kompress_background_warmup.py`)
- [x] Linting passes (`ruff check`, `ruff format --check` on the changed
files)
- [x] New tests added
- [x] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_proxy/test_kompress_background_warmup.py -q
7 passed, 1 warning in 3.16s

# new test with the server.py change reverted:
E   OSError: [Errno 22] Invalid argument
FAILED tests/test_proxy/test_kompress_background_warmup.py::test_unreadable_interpreter_does_not_fail_startup
1 failed, 6 passed, 1 warning in 2.40s
```

## Real Behavior Proof

- Environment: Windows 11 Pro (10.0.26200), Python 3.12 from the
Microsoft Store (`sys.executable` =
`...\WindowsApps\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\python.exe`),
headroom 0.42.0 from PyPI, default config, `HEADROOM_KOMPRESS_WARMUP`
unset.
- Exact command / steps: `headroom proxy --port 8798` on the installed
0.42.0 (before), then `headroom proxy --port 8799` on 0.42.0 plus this
branch's `server.py` (after), polling `GET /health` each time. In
detail:
1. Interpreter check: `python -c "import platform; platform.libc_ver()"`
raises `OSError: [Errno 22] Invalid argument` on this machine.
  2. Before: `headroom proxy --port 8798` using the installed 0.42.0.
3. After: the installed 0.42.0 package copied to a temp directory, with
only `headroom/proxy/server.py` replaced by this branch's version
(0.42.0's `server.py` is byte-identical to `main`'s). Then `headroom
proxy --port 8799` from that copy, polling `GET /health`. I used the
copy because a source checkout has no built `headroom._core`, and the
proxy refuses to start without it.
- Observed result: 0.42.0 aborts startup with the traceback above. With
the patch, the proxy starts, `/health` returns 200, the process stays
up, and the Kompress warm-up thread starts.

```text
=== installed 0.42.0 ===
    libc, version = platform.libc_ver()
  File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.12_3.12.2800.0_x64__qbz5n2kfra8p0\Lib\platform.py", line 200, in libc_ver
OSError: [Errno 22] Invalid argument: 'C:\\Users\\<user>\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe'
ERROR:    Application startup failed. Exiting.

=== 0.42.0 + this patch ===
headroom.proxy - INFO - Headroom Proxy started (version 0.42.0)
headroom.proxy - INFO - Kompress: DEFERRED (warming in the background after startup)
GET /health -> 200 {"service":"headroom-proxy","status":"healthy","ready":true,"version":"0.42.0",...}
process alive after health check: True
```

- Not tested: python.org Windows Python (its `python.exe` is a real
file, so `libc_ver()` doesn't raise there), Linux/macOS (behavior
unchanged unless `libc_ver()` raises), and a request routed through the
proxy to a provider. I didn't wait for the background warm-up to finish;
it only had to start without breaking startup.

## Runtime Rollout Safety

- Rollout-managed feature(s): none. This changes the Kompress warm-up
gate at proxy startup.
- Minimum rollout channel: N/A
- Stable/default behavior changed: only where `platform.libc_ver()`
raises `OSError`. Startup used to fail there; now it proceeds and warms
Kompress as on any non-glibc platform. Everywhere else, behavior is
unchanged.
- Kill switch / disable path: `HEADROOM_KOMPRESS_WARMUP=0`
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (N/A: no
documented behavior changes)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Muhammad Musa
2026-10-29 20:26:21 -05:00
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent d4c0810ea3
commit 28172a921f
2 changed files with 19 additions and 1 deletions
+6 -1
View File
@@ -2004,7 +2004,12 @@ class HeadroomProxy(
if raw not in ("1", "true", "yes", "on"):
import platform
libc, version = platform.libc_ver()
try:
libc, version = platform.libc_ver()
except OSError:
# libc_ver() reads sys.executable; Microsoft Store Python's
# python.exe is an app-execution alias that can't be opened.
libc, version = "", ""
if libc == "glibc":
try:
major, minor = (int(part) for part in version.split(".")[:2])
@@ -67,6 +67,19 @@ def test_skipped_on_the_glibc_family_that_crashes(monkeypatch: pytest.MonkeyPatc
assert not kompress.preloaded.wait(0.2)
def test_unreadable_interpreter_does_not_fail_startup(monkeypatch: pytest.MonkeyPatch) -> None:
"""Microsoft Store Python's python.exe can't be opened, so libc_ver() raises."""
def _raise() -> tuple[str, str]:
raise OSError(22, "Invalid argument")
monkeypatch.setattr("platform.libc_ver", _raise)
monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
kompress = _Kompress()
assert HeadroomProxy._start_kompress_background_warmup(_proxy_with(kompress)) is True
assert kompress.preloaded.wait(5)
def test_env_switch_wins_both_ways(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr("platform.libc_ver", lambda: ("glibc", "2.17"))
monkeypatch.setenv("HEADROOM_KOMPRESS_WARMUP", "1")