What

Add friend-test injection so unit tests can drive two server-side private methods previously unreachable from public APIs. Plus probe classes and demo tests. No behavioral changes to src/.

Targets opened to friend access

Change Type

• Test infrastructure (one-line friend declaration + namespace forward-decl per header, both gated)
• CMake gate symbol (test build only)
• No public-API additions, no behavioral changes

Why

Part of #1074 (Phase 2D). Continues #1075 (2A), #1082 (2A.2), #1102 (2B), #1103 (2C).

Issue #1074 §"Out of scope" explicitly limits this work to friend declarations. Two private methods were called out as the remaining barriers to unit-test coverage of server-side QUIC and WebSocket reception logic. Without friend access, post-private-state branches in quic_server.cpp and websocket_server.cpp remain dead code from the test runner's perspective.

Related Issues

• Part of infra(test): protocol-aware loopback peers + error injection (Phase 2 of #1060) #1074 (Phase 2 of infra: hermetic transport fixture for HTTP/2 / QUIC / WebSocket / gRPC unit tests #1060)
• Builds on infra(test): add mock_h2_server_peer for HTTP/2 loopback (Phase 2A of #1074) #1075 (Phase 2A), feat(tests/support): add HEADERS+DATA reply for h2 mock peer (Phase 2A.2) #1082 (Phase 2A.2), infra(test): add mock_grpc_server_peer for gRPC unary loopback (Phase 2B of #1074) #1102 (Phase 2B), infra(test): add mock_quic_peer_loop for QUIC Initial loopback (Phase 2C of #1074) #1103 (Phase 2C)
• Unblocks coverage expansion for messaging_quic_server (test(quic): expand experimental/quic_server.cpp coverage to 80% line / 70% branch #1066) and messaging_ws_server paths

Where

Total: 12 files, 319 insertions, 0 deletions. PR size: M.

How

Implementation Highlights

Gate symbol — NETWORK_ENABLE_TEST_INJECTION. Defined as target_compile_definitions(network_system PUBLIC NETWORK_ENABLE_TEST_INJECTION) inside an if(BUILD_TESTS) block. PUBLIC propagation so probe TUs and test executables inherit the same define. When BUILD_TESTS=OFF, the production binary is byte-identical to the previous develop tip — friend blocks compile out entirely.

Production header pattern (mirrored in both):

#if defined(NETWORK_ENABLE_TEST_INJECTION)
namespace kcenon::network::tests::support
{
    class quic_server_probe;  // forward declaration only
} // namespace kcenon::network::tests::support
#endif

namespace kcenon::network::core
{
class messaging_quic_server : public ... {
    // ...
private:
#if defined(NETWORK_ENABLE_TEST_INJECTION)
    friend class kcenon::network::tests::support::quic_server_probe;
#endif
    // ...
};
}

The forward-decl block lives outside the production namespace, so the production header pulls in zero test types. Probe definitions live entirely in tests/support/.

Probe shape (pure forwarder):

class quic_server_probe {
public:
    static auto invoke_handle_packet(
        kcenon::network::core::messaging_quic_server& srv,
        std::span<const std::uint8_t> bytes,
        const asio::ip::udp::endpoint& from) -> void;
};

Static-method forwarders, no instance state, no fixture dependency. The probe exists solely to grant the friend bridge.

Testing Done

• QuicServerProbeTest.HandlePacketEmptyBufferDoesNotCrash — passes
• QuicServerProbeTest.HandlePacketGarbageBufferDoesNotCrash — passes
• WsServerProbeTest.HandleNewConnectionEarlyReturnNoSessionManager — passes
• WsServerProbeTest.HandleNewConnectionEmptySocketEarlyReturn — passes

The WebSocket tests exercise the session_mgr_ == nullptr early-return branch (server is never started). Reaching the started-server path requires a ws_session_manager and a connected loopback peer driving the WebSocket upgrade — that is the domain of network_websocket_server_loopback_test, not the probe wiring test. Phase 2D's job is proving the friend bridge works end-to-end and that the previously-private entry points are now reachable from tests.

Test Plan for Reviewers

cmake -S . -B build -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target network_quic_server_probe_test network_ws_server_probe_test -j
ctest --test-dir build -R 'QuicServerProbe|WsServerProbe' --output-on-failure

Note: GTest test-case names are PascalCase (QuicServerProbeTest), CTest target names are snake_case (network_quic_server_probe_test) — the -R filter matches GTest names.

Off-by-default Verification

To confirm BUILD_TESTS=OFF produces a byte-identical production library:

cmake -B build-rel -DBUILD_TESTS=OFF
cmake --build build-rel --target network_system
nm build-rel/libnetwork_system.a | grep -i probe
# Should be empty.

Breaking Changes

None.

Rollback

Revert this PR. No data, no public-API impact. Production binary semantics unchanged.

Part of #1074