fix(mplex): serve buffered data and EOF before reporting the connection down

[gmelodie]

Summary

LPChannel.readOnce raised LPStreamConnDownError ("Stream Underlying Connection Closed!") whenever the muxer connection was closed, even when the peer's bytes and its EOF marker already sat in the channel buffer. The reader lost data that had already arrived. This is the failure in issue #2763: the Tor stream test closeWrite immediately after newStream expects the server handler to read the mplex EOF as a 0-byte read, and it instead got an unhandled AssertionDefect from should not fail: Stream Underlying Connection Closed!.

The guard now fires only when the channel holds nothing: no buffered bytes and no pushed EOF. A reader drains what the peer sent, gets the regular 0-byte EOF marker, and only then learns that the connection is down.

Caveat, stated up front: the CI failure did not reproduce locally in repeated runs of the Tor suite. The diagnosis comes from the two stack traces in the issue. Both show the assertion inside the server stream handler on its first readOnce, reached synchronously while the mplex read loop processes the New frame, and the s.conn.closed check is the only guard on that path that produces this message.

Two defects in the relay bridge put the connection down at that moment over Tor, because the test stub relays through it:

• bridge re-armed readOnce on a stream that had returned EOF. The next pass awaited that already-failed future and left the loop through the LPStreamError path. The relay still ends when either direction reaches EOF, as before; it now ends through the loop condition instead of through an exception, and it drains a direction that finished in the same pass.
• On cancellation bridge raised out of the try block and skipped its two trailing cancelAndWait calls, so both in-flight reads outlived the frame whose buffers they write into. A defer now cancels both through allFutures on every exit path.

TorServerStub now closes each connection with defer from the moment it exists, so a raise in the SOCKS handshake or a cancelled accept loop no longer leaves a socket open.

Affected Areas

• Transports
  Mplex channel read path, and the Tor test stub.

• Protocol Logic
  bridge in libp2p/protocols/connectivity/relay/utils.nim, used by relay v1 and v2.

Compatibility & Downstream Validation

• Nimbus: N/A
• Waku: N/A
• Codex: N/A

No API change and no wire change. bridge keeps the same start and end conditions, so a relay peer sees the same connection lifetime.

Impact on Library Users

A reader on an mplex channel now receives the data and the EOF that already arrived before the underlying connection went down, instead of an immediate LPStreamConnDownError. Code that treats LPStreamConnDownError as "the peer is gone" keeps working, because the error still arrives once the buffer is empty.

The relaxed guard cannot park a reader on a dead connection. pushedEof is set before pushEof queues the marker, and every path that sets it either queues the marker or has already set isEof, in which case atEof() raises LPStreamRemoteClosedError one line earlier. The read queue holds one item, so a pending addLast completes as soon as the reader pops.

Risk Assessment

• Backward compatibility: no API or wire-format change.
• Network behavior: unchanged. bridge ends on the first EOF in either direction, same as before.
• Performance: no change; the added checks are two field reads.
• Security: none.

Testing

(connection down) - should read buffered data and EOF in tests/libp2p/muxers/test_mplex.nim pushes data and an EOF into a channel, closes the underlying connection, and checks that the reader gets the bytes and then a 0-byte read. It fails on the old code with LPStreamConnDownError.

References

• Fixes flaky-test: closeWrite immediately after newStream (Tor) #2763

Additional Notes

TorServerStub.start still dies on the first bad request: self.addrTable[$(address)] raises KeyError for an unregistered address, and that escapes the accept loop, after which every later test blocks on a stub that stopped accepting. Left out of this PR because keeping the loop alive changes stub semantics for every transport test that uses it.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.44444% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 82.25%. Comparing base (0e87563) to head (fb2ed82).

Files with missing lines	Patch %	Lines
libp2p/protocols/connectivity/relay/utils.nim	93.75%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2946   +/-   ##
=======================================
  Coverage   82.25%   82.25%           
=======================================
  Files         178      178           
  Lines       32466    32473    +7     
  Branches       12       11    -1     
=======================================
+ Hits        26704    26710    +6     
- Misses       5762     5763    +1     

Files with missing lines	Coverage Δ
libp2p/muxers/mplex/lpchannel.nim	83.10% <100.00%> (-0.46%)	⬇️
libp2p/protocols/connectivity/relay/utils.nim	87.83% <93.75%> (+1.27%)	⬆️

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.