fix(selftests): raise mock-server listen backlog so load assertions measure the engine

[ian-flores]

selftests/test_load_engine.py::TestAutoRouting::test_small_uses_threadpool and TestThreadpool::test_all_succeed fail reliably on a local macOS machine. Both drive 50 concurrent requests at the shared module-scoped mock_server fixture and assert failure_rate == 0.0; the observed rate varies per run (0.48-0.82), which is what makes it read as timing flake rather than one fixture-level defect. Which of the two fails, or whether both do, varies per run.

The cause is the fixture, not the load engine. _ThreadedHTTPServer inherits request_queue_size = 5 from socketserver.TCPServer, and that value is the listen() backlog rather than any limit on concurrent work. The tests open 50-1000 connections faster than serve_forever can accept them, so everything past the fifth queued connection is reset by the kernel before it is ever accepted. Those resets are counted as request failures, so the assertion reads a failure rate the fixture produced. macOS is stricter about the ceiling than Linux, which is why it surfaced there and CI stayed green.

The fix sets request_queue_size = 128 on the fixture's server class. Note this deliberately does not change the base class: the sketch in the issue moved it to ThreadingHTTPServer, but that class is documented in the code as intentionally avoided, because a thread started per request can die under coverage's threading.settrace hook and silently swallow the request. Making that switch would have reverted an earlier fix.

Verification

Before, on macOS: 3 of 3 runs failed, e.g. assert 0.62 == 0.0 with 19 of 50 requests succeeding. After: 5 of 5 runs pass. Full suite is 1621 passed, 3 skipped. Ruff check and format clean.

The macOS skips stay

The issue asked whether the raised backlog also makes the two _skip_high_concurrency_on_macos skips removable, and asked that it be verified at higher concurrency rather than assumed. It was, and the answer is no. Driving the same fixture server with the same run_load_test calls the skipped tests make, at backlog 128: the 100-request and 1000-request cases were clean 3 of 3, but test_large_uses_async at 200 requests still flaked 1 in 8 (failure rates 0.105 and 0.02) against its strict == 0.0 assertion. The ephemeral port range is a genuinely distinct limit from the listen backlog, as the issue suspected. The skips are left in place and no test's assertion is loosened here.

Closes #575
Closes #517

[Copilot]

Pull request overview

This PR fixes a platform-specific selftest flake by making the module-scoped mock_server fixture resilient to bursts of concurrent connections on macOS, so the load-engine assertions measure the engine behavior rather than the server’s accept backlog.

Changes:

• Increase the mock HTTP server’s listen() backlog (request_queue_size) to avoid kernel connection resets under 50–1000 concurrent connection attempts.
• Add inline documentation explaining why the failure manifested as a misleading non-zero failure_rate on macOS.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.