Summary

Eliminate per-read heap allocations and avoidable data copies in the TCP receive hot path by introducing std::span-based view callbacks and migrating major consumers.

Background

tcp_socket::do_read() currently:

• Allocates + copies into std::vector<uint8_t> on every read (src/internal/tcp_socket.cpp:116)
• Takes callback_mutex_ on every read to copy callbacks (src/internal/tcp_socket.cpp:120)

Under high TPS, this amplifies allocator contention, heap fragmentation, cache misses, and context-switch overhead.

Decision

Standardize on view-based receive callbacks:

• Type: std::span<const uint8_t>
• Lifetime: valid only until the callback returns (do not store/capture across async boundaries)
• Compatibility: keep legacy std::vector<uint8_t> callbacks working, but make the span path the preferred fast path

Work Breakdown (Split into <1–2 day issues)

• perf(tcp_socket): add std::span receive callback to remove per-read allocations #316 perf(tcp_socket): add std::span receive callback to remove per-read allocations
• perf(secure_tcp_socket): add std::span receive callback to remove per-read allocations #317 perf(secure_tcp_socket): add std::span receive callback to remove per-read allocations
• refactor(websocket): migrate TCP receive path to std::span and update protocol API #318 refactor(websocket): migrate TCP receive path to std::span and update protocol API (depends on perf(tcp_socket): add std::span receive callback to remove per-read allocations #316)
• refactor(messaging): consume tcp_socket std::span receive callback internally (remove one copy) #319 refactor(messaging): consume tcp_socket std::span receive callback internally (remove one copy) (depends on perf(tcp_socket): add std::span receive callback to remove per-read allocations #316)
• feat(benchmark): add TCP receive dispatch benchmark (std::span vs std::vector) #320 feat(benchmark): add TCP receive dispatch benchmark (std::span vs std::vector)

Acceptance Criteria

• tcp_socket and secure_tcp_socket provide std::span receive callbacks with explicit lifetime rules
• TCP receive hot path performs no per-read std::vector allocation when span callback is used
• WebSocket receive pipeline no longer requires per-read std::vector just to hand off to protocol parsing
• Messaging pipeline removes at least one copy/allocation per read vs baseline
• Unit/integration/performance test suites pass in CI