One Stream Read, Fully Traced

1. Socket readiness wakes the endpoint

EndpointDriver polls AsyncUdpSocket::poll_recv. The runtime-specific socket registers its waker with the reactor when no datagram is available.

2. The endpoint routes without owning connection semantics

Received bytes enter proto::Endpoint::handle. Connection IDs select an existing ConnectionHandle, produce a new incoming attempt, or cause a stateless response. An existing packet becomes ConnectionEvent::Proto on that connection’s channel.

3. The connection driver advances pure state

ConnectionDriver drains endpoint events into proto::Connection, processes the packet, advances cryptography/acknowledgement/flow-control state, and polls protocol events. StreamEvent::Readable { id } identifies the affected stream.

4. Exactly one blocked reader is woken

The high-level connection state stores blocked reader wakers by StreamId. Forwarding the readable event removes and wakes the matching entry.

5. The application future reads buffered chunks

RecvStream::poll_read_generic locks connection state, obtains the protocol receive stream, and consumes ordered or unordered chunks. Finalizing the chunk view returns flow-control credit; if that requires a control frame, it wakes the connection driver for transmission.

6. Backpressure closes the loop

If no bytes are available, the reader stores its current waker and returns Pending. If bytes are consumed, QUIC can advertise more credit. Thus slow application consumption constrains the peer through protocol flow control rather than an unbounded local queue.