What

Build a hermetic transport fixture (mock TLS socket / mock UDP peer / mock WebSocket upgrade harness / gRPC dummy peer) that lets unit tests drive connect() / accept() / async_* callback chains on protocol clients and servers without standing up a real network listener.

Single deliverable in tests/support/:

tests/support/
  hermetic_transport_fixture.h
  hermetic_transport_fixture.cpp
  mock_tls_socket.h          // For HTTP/2 + gRPC client/server
  mock_udp_peer.h            // For QUIC socket/server
  mock_ws_handshake.h        // For WebSocket server

Why

Sub-issues #1048-#1053 added 4,383 LOC of hermetic gtest cases for the six lowest-coverage source files yet moved overall filtered coverage by +0.05pp line / +0.07pp branch — essentially zero. Per-file analysis after PR #1059 merge:

Three files moved by exactly 0pp. The hermetic tests exercised inline-in-header code (config round-trips, callback registration, type aliases), not the .cpp body. Each PR's "Honest scope statement" named the same class of unreachable code: private async/socket-bound methods that demand a live transport stream.

Without a fixture, the remaining gap to epic #953's targets (Line ≥ 80%, Branch ≥ 70%) cannot be closed by adding more hermetic tests. This is a diminishing-returns wall, not a scale problem.

Who

• Assignee: TBD
• Stakeholders: anyone working on protocols/, experimental/, http/, internal/quic_socket.cpp
• Reviewer: anyone with ASIO + OpenSSL test-infrastructure experience

When

• Priority: high (blocks epic Expand unit test coverage from 40% to 80% #953 numeric gates)
• Dependencies: none — all six target sub-issues (test: expand coverage for src/protocols/http2/http2_client.cpp #1048-test: expand coverage for src/http/websocket_server.cpp #1053) merged
• Estimated scope: 1-2 weeks for full fixture; can land incrementally per protocol family

Where

• Primary: tests/support/ (new directory)
• Consumers: tests/unit/{http2_client,grpc_client,http2_server,quic_socket,quic_server,websocket_server}_branch_test.cpp — extended with new TEST_F cases that use the fixture
• CMake: tests/CMakeLists.txt — link the fixture as a static helper library, available to all add_network_test targets
• Related: epic Expand unit test coverage from 40% to 80% #953, closed sub-issues test: expand coverage for src/protocols/http2/http2_client.cpp #1048-test: expand coverage for src/http/websocket_server.cpp #1053

How

Technical approach

The structural blockers identified in PRs #1054-#1059 fall into three transport patterns:

1. TLS-over-TCP frame stream (HTTP/2 client + server, gRPC client)

   • Need: drive process_frame, handle_*_frame, send_* private methods
   • Approach: inject a mock asio::ssl::stream<asio::ip::tcp::socket> substitute via templated transport, OR provide an in-memory asio::ip::tcp::socket pair connected via asio::local::stream_protocol (Unix domain sockets) with TLS layer mocked at the byte level

2. UDP datagram + QUIC handshake (quic_socket, quic_server)

   • Need: drive do_receive, handle_packet, process_*_frame, find_or_create_session
   • Approach: in-process UDP peer running on a free local port, OR asio::posix::stream_descriptor-backed socketpair with QUIC initial-packet builder helpers

3. HTTP/1.1 upgrade + WebSocket frame (websocket_server)

   • Need: drive do_accept, handle_new_connection, on_message, invoke_*_callback
   • Approach: in-process TCP client that performs the WS upgrade handshake against the listening server, then sends framed payloads

Acceptance criteria

• hermetic_transport_fixture.h provides a WithMockTransport GTest fixture base
• mock_tls_socket.h allows injecting raw bytes into HTTP/2 / gRPC client/server transport without an external peer
• mock_udp_peer.h allows sending arbitrary QUIC initial/handshake packets to a quic_socket or quic_server instance under test
• mock_ws_handshake.h simulates an RFC 6455 client upgrade and frame send to a websocket_server
• At least one new TEST_F per fixture in each of the six existing branch_test files demonstrates the fixture exercising one previously-blocked private method
• CI passes on Ubuntu/macOS Debug+Release matrix
• Documentation: tests/support/README.md shows how to compose the fixture for new tests

Reproduction of structural blockers (from PRs #1054-#1059 honest-scope statements)

To validate the fixture, the new TEST_Fs MUST hit at least one method per category:

Hitting one method per file is enough to prove the fixture works; subsequent PRs can ride on the same fixture to push per-file coverage upward.

Out of scope

• Fuzzing infrastructure (separate effort)
• Sanitizer-driven race detection (separate effort)
• Removing or refactoring the existing hermetic tests in test: expand coverage for src/protocols/http2/http2_client.cpp #1048-test: expand coverage for src/http/websocket_server.cpp #1053 (handled in cleanup PR)

Testing plan for reviewers

1. Build with cmake --preset debug && cmake --build build
2. Run ctest --test-dir build -R "branch_test" — all existing tests still pass
3. Coverage delta check: cmake --build build --target coverage, verify per-file numbers for the six target files moved upward
4. Run with --repeat-until-fail=20 -j4 to validate the fixture is race-free

Additional Context

This is the strategic complement to the per-file branch-coverage batch (#1048-#1053). The batch closed all narrow follow-ups that hermetic tests could close; the gap that remains is structural and requires this fixture.