#323 - Apply TCP receive backpressure

[cliffburdick]

Summary

• Bound each TCP RX queue's internal burst backlog by the smallest num_bufs among its referenced memory regions.
• Stop consuming from a TCP socket while that backlog is full, allowing kernel TCP flow control to propagate backpressure to the sender.
• Check socket readability before reserving shared queue capacity so an idle peer cannot starve active peers.
• Wake blocked receive threads safely during dequeue and shutdown.
• Add regression coverage and synchronize the mapped socket-engine documentation.

Fixes #323.

Documentation

Updated the socket-engine behavior in:

• README.md
• AGENTS.md
• docs/getting-started.md
• docs/concepts.md
• docs/api-reference/configuration.md
• docs/tutorials/configuration-walkthrough.md
• docs/benchmarks/socket_benchmarking.md

The documentation explains how num_bufs determines the TCP backlog limit, how backpressure reaches the sender, how shared multi-peer queues behave, and why UDP behavior is unchanged.

Local verification

• Full default-engine Release build with DAQIRI_ENGINE="dpdk ibverbs", shared libraries, tests enabled, Python and examples disabled: passed in the project container.
• ctest --output-on-failure: 2/2 tests passed (daqiri_init_validation_test, daqiri_socket_rx_queue_test).
• scripts/check_pr.sh with the full-engine production validator: passed.
  • Portable pytest: 9/9 passed.
  • Seven checked-in configurations plus one compatibility configuration accepted.
  • Fourteen malformed fixtures correctly rejected.
  • MkDocs build, internal-link validation, and documentation-reference checks passed (11 binaries, 39 YAML configurations, 27 documentation files).
• TCP RX queue regression test repeated 20 times: passed.

[greptile-apps]

Confidence Score: 4/5

[High risk] Socket engine receive queue now enforces backpressure limits.

The code appears ready for merge once the required local PR check results are provided.

Summary

The PR bounds TCP receive backlogs by RX memory-region capacity and uses a non-consuming peek so idle peers do not reserve shared queue slots.

• Adds queue-capacity and shutdown tests.
• Documents backpressure behavior and sizing guidance.

_{Reviews (4) · Last reviewed commit: "#323 - Complete TCP backpressure validat..."}

[cliffburdick]

Addressed the high-risk readiness feedback in 61ff3c0:

• Updated every socket-engine documentation target mapped by .claude/rules/docs-sync.md: README.md, AGENTS.md, docs/getting-started.md, docs/concepts.md, docs/api-reference/configuration.md, and docs/tutorials/configuration-walkthrough.md. The detailed operational guidance remains in docs/benchmarks/socket_benchmarking.md.
• Recorded the complete local verification evidence in the PR description.
• Verified a full default-engine Release build in the project container (DAQIRI_ENGINE="dpdk ibverbs").
• Verified CTest: 2/2 passed.
• Verified scripts/check_pr.sh: 9 portable tests passed; all valid configurations accepted; all 14 malformed fixtures rejected; MkDocs, link, and documentation-reference checks passed.
• Repeated the TCP RX queue regression test 20 times successfully.

This also moved SocketEngine's default constructor out of line so the full default-engine test build can instantiate it while RdmaEngine remains an incomplete type in the public header.