Replace HTTP/3 stream wait futures with custom wakers

WaitingStreams previously stored Abortable<WaitForStream> values in a
FuturesUnordered with per-direction abort maps. Each wait existed only
to register a channel waker and return readiness to H3Driver.

Channel endpoints now remain in StreamCtx with one shared StreamWake per
stream. RecvState owns RecvDelivery in Open and FinPending, pairing the
app-bound sender with its capacity-wait flag. mark_fin_pending moves the
whole payload, preserving waits. Closed drops both without manual wait
cancellation. Capacity polling retains Pending waits and releases its
readiness permit before application reads. Closed delivery cannot wait.

The outbound receiver remains independent because queued FIN can drop
it before transport writes finish. An outbound waiting flag identifies
the receiver to re-poll, and stale ready IDs are ignored after cleanup.

ReadyStreams encapsulates coalescing: the queue owns Arc<StreamWake>
notifications, and dequeue clears their AtomicBool before returning a
stream ID. Channel polling no longer participates in queue
acknowledgment. Direct polls preserve queued notifications; dequeue
rearms wakes even without a subsequent channel poll. Wake metadata owns
no stream endpoints.

STOP is probed before H3 frame validation, except for queued
PeerStreamError. STOP drains ordinary buffered frames, preserves
PeerStreamError, and redispatches it to close both directions. Errors
sent later through outstanding permits are rejected when the receiver is
dropped.

App-bound readiness is serviced before outbound data. Ready-queue
draining retains Tokio cooperative budgeting. Regressions verify FIN
wait preservation, automatic wait removal on closure, stale wakes,
cooperative yields, wake coalescing, and deferred cleanup. Remaining
lifecycle invariant checks have runtime paths and debug assertions.

The cooperative-yield regression bounds its post-yield receive with a
deadline. A lost readiness notification fails both channel-direction
cases instead of leaving the test suite waiting indefinitely.

Peer-reset handling remains idempotent when the body reader and HTTP/3
polling both report a reset. Unit coverage checks repeated notifications
after open or FIN-pending delivery and verifies that capacity waits are
dropped without closing the response channel. Strict cancellation checks
apply only to local reset and STOP operations.

Author: nox

tokio-quiche/src/http3/driver/AGENTS.md

@@ -12,8 +12,7 @@ Async HTTP/3 driver bridging `quiche::h3::Connection` to Tokio tasks via channel
 | `hooks.rs` | `DriverHooks` trait (sealed). Defines `headers_received`, `stream_recv_closed`, `stream_closed`, `conn_established`, `conn_command`, `wait_for_action` |
 | `client.rs` | `ClientHooks` impl, `ClientH3Driver`/`ClientH3Controller` aliases, `ClientH3Event`/`ClientH3Command` |
 | `server.rs` | `ServerHooks` impl, `ServerH3Driver`/`ServerH3Controller` aliases, `ServerH3Event`/`ServerH3Command` |
-| `streams.rs` | `StreamCtx`, `FlowCtx`, `WaitForStream` future, capacity/readiness signals |
-| `waiting_streams.rs` | `WaitingStreams` keyed tracker for pending upstream-capacity and downstream-data waits |
+| `streams.rs` | `StreamCtx`, `FlowCtx`, shared per-stream waker and channel waiting flags |
 | `datagram.rs` | DATAGRAM/CONNECT-UDP flow handling |
 | `connection.rs` | `H3Conn` wrapper exposing `h3::Connection` operations |
 | `test_utils.rs` | `DriverTestHelper<H>` -- wraps `Pipe` + `H3Driver` for unit tests |
@@ -23,18 +22,22 @@ Async HTTP/3 driver bridging `quiche::h3::Connection` to Tokio tasks via channel
 
 | Task | Start at |
 |------|----------|
-| Channel architecture | `mod.rs:332` (`H3Driver` struct fields: `h3_event_sender`, `cmd_recv`, `stream_map`, `waiting_streams`) |
+| Channel architecture | `mod.rs` (`H3Driver` struct fields: `h3_event_sender`, `cmd_recv`, `stream_map`, `ready_streams`) |
 | `select!` loop / priority ordering | `mod.rs` `wait_for_data` impl -- uses `biased` select! |
 | Stream lifecycle | `cleanup_stream`, `shutdown_stream`, `process_h3_fin`, `process_h3_data` in `mod.rs` |
-| Per-stream backpressure | `streams.rs` defines wait futures; `waiting_streams.rs` tracks and cancels them by stream ID |
+| Per-stream backpressure | `streams.rs` keeps endpoints in `StreamCtx`; one generic waker queues each stream ID once, and the driver re-polls both waiting directions |
 | Adding endpoint-specific behavior | `hooks.rs` -- add method to `DriverHooks`, impl in `client.rs`/`server.rs` |
 | Writing tests | `test_utils.rs` for `DriverTestHelper`, `tests.rs` for examples |
 
 ## ANTI-PATTERNS
 
 - Store receive and send lifecycle states explicitly; channel absence does not
-  imply completion, especially when a waiting future owns the endpoint.
-  Received FIN and app-channel FIN delivery are distinct receive states.
+  imply completion. Received FIN and app-channel FIN delivery are distinct
+  receive states. Open and pending receive states own an `InboundDelivery` payload
+  with its sender and capacity-wait flag; closing the state drops both. FIN
+  preserves the payload, including an existing wait. The outbound receiver is
+  independent: queued FIN can drop it
+  while the transport still has body data to send.
 - Do not add overlapping boolean completion methods for these states. A single
   derived helper can centralize the cleanup decision without conflating pending
   FIN with closed delivery. Match lifecycle enums exhaustively where a new
@@ -45,7 +48,15 @@ Async HTTP/3 driver bridging `quiche::h3::Connection` to Tokio tasks via channel
 - **`process_write_frame` uses `Error::Done` as success** -- non-obvious control flow, don't replicate elsewhere.
 - **`DriverHooks` is sealed** -- `mod hooks` is `pub(crate)`, trait has `#[allow(private_interfaces)]`. Do not expose.
 - **Stream cleanup is distributed** across 4+ functions (`cleanup_stream`, `shutdown_stream`, `process_h3_fin`, `process_h3_data`). Understand all paths before modifying.
-- **Waiting-stream cancellation must be keyed** -- cancelling waiting streams must not linearly walk all pending futures for performance reasons.
+- **Waiting-stream cancellation must be keyed** -- clear flags and drop endpoints
+  through `stream_map`; do not linearly scan the ready queue.
+- `ReadyStreams` owns queue acknowledgment: dequeueing clears the queued wake
+  flag before returning the stream ID. Channel polling never changes that flag.
+  Keep waiting flags set on `Pending`, including spurious wakes and
+  cooperative-budget yields.
+- Stream cleanup drops channel endpoints immediately; stale ready IDs are ignored.
+- STOP_SENDING discards ordinary outbound frames, but a buffered `PeerStreamError`
+  must still shut down both directions.
 - **`STREAM_CAPACITY`** is 1 in test/debug, 16 in release. Tests exercise backpressure differently from prod.
 
 ## NOTES

tokio-quiche/src/http3/driver/client.rs

@@ -211,8 +211,11 @@ impl ClientHooks {
         };
 
         // log::info!("sent h3 request"; "stream_id" => stream_id);
-        let (mut stream_ctx, send, recv) =
-            StreamCtx::new(stream_id, STREAM_CAPACITY);
+        let (mut stream_ctx, send, recv) = StreamCtx::new(
+            stream_id,
+            STREAM_CAPACITY,
+            driver.ready_stream_sender.clone(),
+        );
 
         if body_finished {
             // `send_request()` already sent FIN for bodyless requests, so
@@ -235,9 +238,7 @@ impl ClientHooks {
 
         if let Some(body_writer) = request.body_writer {
             let _ = body_writer.send(send.clone());
-            driver
-                .waiting_streams
-                .push(stream_ctx.wait_for_recv(stream_id))?;
+            stream_ctx.wait_for_recv();
         }
 
         driver.insert_stream(stream_id, stream_ctx);