HTTP/3: don't block the transport/reactor thread with business logic (ACK-timing budget)

Problem

In QUIC/HTTP/3 the entire transport — ACK generation, loss detection, congestion control, RTT estimation, PTO/pacing/idle timers — lives in userspace, driven by our own reactor loop (ngtcp2 has no internal threads). If a per-request coroutine runs a long synchronous / blocking burst on that same reactor thread, nobody reads incoming datagrams or sends ACKs while it runs. This is fundamentally different from TCP, where the kernel ACKs independently of the application thread.

This is not "you can never run handler code on the transport thread". Cooperative, non-blocking execution on the same thread is fine. The rule is: the reactor must never be stalled long enough to delay ACKs / timers.

Why it breaks (mechanisms)

Delayed ACKs inflate RTT and PTO. We advertise max_ack_delay (default 25 ms). The peer subtracts our reported ack_delay from RTT samples, but capped at max_ack_delay. Delay an ACK longer (thread stuck in handler) → the excess is attributed to "scheduler latency at the peer", folded into path RTT → smoothed_rtt and PTO = smoothed_rtt + 4·rttvar + max_ack_delay inflate → slower loss recovery. We effectively lie about RTT and poison the peer's congestion control. (RFC 9002 §5–6.)
ACK-clocking stall / spurious retransmits. QUIC is ACK-clocked. Not draining the socket and not ACKing promptly → peer's bytes_in_flight doesn't drain, cwnd can't grow, or it infers loss → spurious retransmits.
Idle timeout / connection drop. Block long enough and we miss idle deadline, PTO probes, PATH_CHALLENGE responses → connection killed. msquic literally documents this as "dropped connections".
Thread-level head-of-line blocking — the irony. QUIC removes HoL blocking between streams. But running request A's handler on the reactor blocks the transport for every connection/stream on that thread — reintroducing HoL at a worse layer. One slow handler stalls everyone's ACKs.

What other implementations do (consensus: transport thread ≠ business-logic thread)

msquic (Microsoft), most explicit: "MsQuic does not use separate threads for protocol execution and upcalls to the application. Therefore, any significant delays in the callback will delay the protocol." / "Any substantial work required by the application must be performed on threads created by the application." / "Any significant delays will delay other QUIC processing (such as sending acknowledgments), which can cause protocol issues (dropped connections)."
ngtcp2 (what we use): pure callback state machine, no internal threads; app drives recv → writev_stream → update_pkt_tx_time → get_expiry2 → timer. Stuck thread ⇒ that connection's PTO/ACK/idle/pacing timers are simply not serviced.
nginx: single-threaded event-driven worker; blocking/synchronous work is offloaded to a thread pool.
quic-go: transport runs in its own goroutines; each stream is handled in a separate goroutine — the runtime offloads handler work off the receive loop for you.

The deadline budget

Loop-iteration latency must stay well under, in order of strictness:

max_ack_delay (default 25 ms) — keep ACK latency under this or you start inflating peer RTT;
PTO (~smoothed_rtt + 4·rttvar + max_ack_delay);
idle timeout (seconds, hard kill).

Practical target: single-digit-ms reactor iterations.

Action items (our codebase)

Audit the H3 request path for any synchronous CPU burst without a yield under the reactor loop (heavy render/serialize, sync DB, large gzip, big smart_str builds). Same class of bug as [no-sync-in-async-loop] and [tls-no-coroutine-in-internals].
Confirm per-request coroutines yield back to the reactor frequently enough; document the ~ms budget.
Add a rule to CODING_STANDARDS: transport reactor stays strictly non-blocking; long synchronous CPU work goes to a worker thread/queue.
(Optional) Instrumentation: reactor-iteration latency histogram + "time since last ACK sent per connection"; a watchdog that logs when an iteration exceeds the budget.
Cross-link with the inter-thread queue work (companion issue) — the offload target for heavy handlers must itself be lock-free so the handoff doesn't reintroduce a stall.