What

Summary

Adds in-process loopback unit tests that drive messaging_ws_server
(src/http/websocket_server.cpp) end-to-end against a real RFC 6455
client built from internal::websocket_socket + internal::tcp_socket,
exercising branches that the existing hermetic suites
(test_messaging_ws_server.cpp, tests/unit/websocket_server_branch_test.cpp,
tests/unit/websocket_server_test.cpp) explicitly document as out of
reach without a live handshake.

Change Type

• Test
• Feature
• Bugfix
• Refactor

Affected Components

• tests/unit/websocket_server_loopback_test.cpp — new, ~620 lines
• tests/CMakeLists.txt — register network_websocket_server_loopback_test
• CHANGELOG.md, docs/CHANGELOG.md — record the new coverage work

Why

Problem Solved

src/http/websocket_server.cpp measured 39.9% line / 19.7% branch on
develop @ 2026-04-26 (run 24947193873) — priority #6
worst-coverage target. The hermetic branch tests added in #1053 cover the
public-API surfaces reachable on a never-started server, but explicitly
note in the file's "Honest scope statement" that
do_start_impl/do_stop_impl success paths, do_accept,
handle_new_connection, on_message/on_close/on_error, the four
invoke_*_callback helpers, the populated-session broadcast/get_connection
branches, and the ws_connection/ws_connection_impl methods are
reachable only with a live TCP client that completes the WebSocket
HTTP/1.1 upgrade handshake. This PR closes that gap.

Related Issues

• Closes test(websocket): expand websocket_server.cpp coverage to 80% line / 70% branch #1067 (test(websocket): expand websocket_server.cpp coverage to 80% line / 70% branch)
• Part of Expand unit test coverage from 40% to 80% #953 (project-wide coverage push to 80%/70%)

Alternatives Considered

1. Extend tests/test_messaging_ws_server.cpp in place — rejected
   because that file's header explicitly documents a no-peer / no-io_context
   invariant ("All tests operate purely on the public API; no real
   WebSocket client or live HTTP/1.1 upgrade handshake is required.").
   Mixing loopback tests there would break that invariant and confuse
   future maintainers.
2. Friend-test injection point inside messaging_ws_server — rejected
   because it would require a production-code change for testing only.
   The probe-port + real-handshake approach exercises the same branches
   without altering the production class surface.
3. Mock thread pool that does not run io_context — rejected because
   the goal is exactly to drive the real do_accept loop and per-frame
   dispatch; mocking the thread pool would re-stub out the very paths
   the test is trying to cover.

Where

Files Changed

Test Groups

How

Implementation Highlights

• probe_free_port() — opens an asio acceptor on port 0 to discover an
  OS-assigned port, then closes it before the server binds. There is a
  brief race window in which the port could be reused — accepted as a
  known limitation for tests in this file (consistent with the existing
  tests/integration/test_websocket_e2e.cpp pattern).
• wait_until(predicate, timeout) — 5 ms-poll predicate with 2 s default
  budget; used to synchronize on async server-side state transitions
  (callback invocations, session_mgr updates) without resorting to
  fixed sleep_for calls.
• WsLoopbackClient — minimal RFC 6455 client wrapping internal::tcp_socket
  and internal::websocket_socket with its own asio::io_context and
  thread; supports connect / send_text / send_binary / send_ping
  / close and exposes set_message_handler / set_pong_handler for
  observing server-to-client frames (used by the broadcast tests).
• The garbage-handshake test opens a raw asio::ip::tcp::socket (no
  websocket_socket wrapper) and writes non-HTTP bytes. The server's
  ws_socket->async_accept parses this, fails validation, and the
  connection is dropped without registration — exercising exactly the
  if (ec) failure arm in handle_new_connection.
• The bind_failed test holds the port with our own asio::ip::tcp::acceptor
  before the server tries to bind. do_start_impl's try block catches
  the std::exception and returns bind_failed while
  lifecycle_.mark_stopped() rolls back the running flag.

Testing Done

• Local build verification — not possible (no C++ toolchain
  available in the sandbox: cmake, g++, clang++, ninja all
  report not found). CI is the source of truth for AC feat: Phase 1 - Network System Separation from messaging_system #1-feat: Phase 4 - messaging_system Update and Performance Optimization #4.
• Code review of test logic against the source paths in
  src/http/websocket_server.cpp (every test references a specific
  branch with file:line traceability)
• Cross-check against tests/integration/test_websocket_e2e.cpp for
  the loopback pattern (same internal::websocket_socket client
  construction, same handshake-via-promise idiom)
• CMake registration via add_network_test macro confirmed
  consistent with sibling network_websocket_server_branch_test

Test Plan for Reviewers

1. Pull this branch and build with one of the supported presets:

   cmake --preset release && cmake --build build
   

2. Run the new test target:

   ctest --test-dir build -R network_websocket_server_loopback_test --output-on-failure
   

3. Confirm coverage uplift via the project's coverage.yml workflow
   (post-merge metrics will be tracked under Expand unit test coverage from 40% to 80% #953 per AC feat: Phase 5 - Production Readiness and Release Preparation #5).

Breaking Changes

None. This PR adds tests only.

Rollback Plan

Revert this PR. No production code is modified.

Acceptance Criteria

• AC feat: Phase 1 - Network System Separation from messaging_system #1 — src/http/websocket_server.cpp line coverage >= 80% — CI must confirm
• AC feat: Phase 2 - Core System Separation #2 — src/http/websocket_server.cpp branch coverage >= 70% — CI must confirm
• AC feat: Phase 3 - Integration Interface Implementation #3 — Tests pass on Ubuntu/macOS/Windows CI — CI must confirm
• AC feat: Phase 4 - messaging_system Update and Performance Optimization #4 — Sanitizer builds (ASAN, TSAN, UBSAN) pass — CI must confirm
• AC feat: Phase 5 - Production Readiness and Release Preparation #5 — Post-merge coverage delta recorded on Expand unit test coverage from 40% to 80% #953 — tracked separately after merge

Checklist

• Code follows project style (matches tests/unit/websocket_server_branch_test.cpp formatting)
• Self-review completed
• Tests added (this PR is tests-only)
• Documentation updated (CHANGELOG entries in both root and SSOT)
• No sensitive data exposed
• Commits are atomic and well-described
• Issue linked with Closes #1067 keyword
• Local build verification — not possible (sandbox toolchain unavailable)