Skip to content

fix: force IPv4 in health checker to prevent WSL2 DNS delays#761

Merged
Lightheartdevs merged 1 commit intoLight-Heart-Labs:mainfrom
yasinBursali:fix/health-check-ipv4
Apr 3, 2026
Merged

fix: force IPv4 in health checker to prevent WSL2 DNS delays#761
Lightheartdevs merged 1 commit intoLight-Heart-Labs:mainfrom
yasinBursali:fix/health-check-ipv4

Conversation

@yasinBursali
Copy link
Copy Markdown
Contributor

What

Force IPv4 connections in the aiohttp health check session by creating the TCP connector with family=socket.AF_INET.

Why

On WSL2/Docker Desktop, the default aiohttp connector attempts both IPv6 (AAAA) and IPv4 (A) DNS resolution. Docker service name AAAA queries timeout after ~8 seconds before falling back to IPv4, inflating response_time_ms to ~8016ms for most services. Docker internal networking is exclusively IPv4 — AAAA queries always fail.

How

In _get_aio_session(), changed the session creation from:

aiohttp.ClientSession(timeout=_HEALTH_TIMEOUT)

to:

aiohttp.ClientSession(
    timeout=_HEALTH_TIMEOUT,
    connector=aiohttp.TCPConnector(family=socket.AF_INET),
)

Testing

  • python -m py_compile passes
  • pytest: 374/384 pass (10 pre-existing failures on main, 0 regressions)
  • Critique Guardian: APPROVED WITH WARNINGS

Review

Critique Guardian verdict: ⚠️ APPROVED WITH WARNINGS

  • Non-blocking warning: the shared httpx.AsyncClient (used for llama-server metrics) does not force IPv4. Single-host with 5s timeout — much smaller impact than the 17-service health poll. Recommended as follow-up.

Known Considerations

The httpx client for llama-server metrics is not covered by this fix. On WSL2, llama-server requests may still see a one-time ~5s DNS delay. This is a minor follow-up — the critical fix is the health poll (17 services × 8s = 136s delay eliminated).

Platform Impact

  • macOS: No impact — Docker Desktop for Mac uses IPv4 internally
  • Linux: No impact — Docker bridge networking is IPv4
  • Windows/WSL2: Fixes the ~8016ms response_time_ms inflation

The aiohttp session used the default TCPConnector which attempts both
IPv6 and IPv4 DNS resolution. On WSL2/Docker Desktop, AAAA (IPv6) DNS
queries for Docker service names timeout after ~8 seconds before falling
back to IPv4, inflating response_time_ms to ~8016ms. Docker internal
networking is exclusively IPv4, so restricting to AF_INET is safe on all
platforms.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@Lightheartdevs Lightheartdevs merged commit a2a5b6d into Light-Heart-Labs:main Apr 3, 2026
21 of 28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants