feat(tunnel): event-driven drain with adaptive long-poll

[dazzling-no-more]

Summary

Replaces the tunnel-node's fixed-sleep batch drain (150 ms + optional 200 ms retry) with a Notify-driven wait that wakes on the first byte from any session in the batch. The same primitive enables long-polling for idle sessions: empty-poll batches hold the response open until upstream pushes data or the long-poll deadline elapses, turning push notifications and chat messages into ~RTT delivery instead of waiting for the client's next tick.

Changes

tunnel-node

• New Notify on SessionInner, fired by reader_task on each buffer extend and on EOF.
• New wait_for_any_drainable(inners, deadline) — signal-driven wait with self-filtering watchers (a stale permit left by a previous batch's spawn-race shortcut is consumed harmlessly without spuriously waking the caller).
• handle_batch phase 2 picks an adaptive deadline:
  • ACTIVE_DRAIN_DEADLINE (350 ms) when the batch had writes or new connections, plus a 30 ms STRAGGLER_SETTLE after the first wake to catch neighboring responses.
  • LONGPOLL_DEADLINE (5 s) when the batch is a pure poll — empty data ops only.
• Removed the legacy two-pass sleep+drain+retry block.

tunnel-client

• tunnel_loop no longer skips empty polls and the idle read-timeout cap drops from 30 s → 500 ms — the server-side long-poll now controls cadence.
• Backward-compat detection: an empty-in/empty-out round trip that returns under LEGACY_DETECT_THRESHOLD (1500 ms) sets a sticky server_no_longpoll flag on the mux; subsequent sessions revert to the pre-long-poll cadence (30 s read timeout, skip-empty-when-idle) so legacy tunnel-nodes don't get hammered with continuous empty polls.

Trade-offs

LONGPOLL_DEADLINE is documented as a knob, not a constant. Lower values (e.g. 2 s) make typing-burst flows snappier; higher values minimize round-trips for push-only sessions. 5 s is a middle ground — a thinking pause between keystrokes can tax the next keystroke by up to that value, since tunnel_loop is strictly serial per session.

Test plan

• cargo test --manifest-path tunnel-node/Cargo.toml — 17 tests pass, including:
  • 6 unit tests for wait_for_any_drainable (notify wake, any-of-N, deadline, stale-permit, eof, empty-list)
  • reader_task_notifies_on_incoming_bytes — end-to-end notify wiring through a real TCP pair
  • 3 integration tests on handle_batch: pure-poll wakes on push, active batch caps at active deadline (< 600 ms), Some("") payload engages long-poll
• cargo test — full workspace, 92 client tests pass including new no_longpoll_cache_is_sticky

[therealaleph]

Substantive review — this is good work. Verified locally and merging.

Tests:

• cargo test --lib — 92 passes (was 91; +1 for no_longpoll_cache_is_sticky)
• cargo test -p mhrv-tunnel-node — 17 passes (was 6; +11 for the new wait_for_any_drainable primitive, reader_task_notifies_on_incoming_bytes end-to-end wiring through a TCP pair, and the handle_batch integration tests for active-vs-long-poll cap selection)
• Test-merged against current main (post-v1.4.1 + tunnel-docker workflow changes) — clean auto-merge

Design verified:

• Notify::notify_one() on each reader_task buffer extend + on EOF — correct primitive for "wake on first byte from any of N sessions"
• wait_for_any_drainable self-filters stale permits left by a previous batch's spawn-race shortcut — important to avoid spurious wakes that would burn the new 500 ms cadence on no actual data
• LEGACY_DETECT_THRESHOLD (1500 ms) sits comfortably between the legacy fixed-sleep drain (~350 ms) and the new long-poll floor (~5 s). An empty round trip at any other RTT than those two distinct regimes shouldn't false-trigger either way
• server_no_longpoll is sticky per-mux (AtomicBool) so legacy tunnel-nodes only get one "fast empty reply" probe per session lifetime, not per request
• The 30 s → 500 ms cadence drop on the client side is exactly the change that makes long-poll viable; without it, the client's own idle-skip would still gate response delivery on the next data write

Trade-offs flagged in the body acknowledged:

• 5 s LONGPOLL_DEADLINE is the right starting default. Lower would help typing-burst flows; higher minimizes round-trips for push-only sessions. Worth tracking the empirical distribution of "time between session pokes" once this lands and tuning if there's signal.
• The STRAGGLER_SETTLE (30 ms) after first wake catches neighboring responses without holding the active batch open uselessly. Good.

Manual verification path (not blocking merge):

• Start a tunnel-node, point a v1.5.0 client at it, watch a sustained Telegram session — incoming messages should now show up in roughly RTT instead of waiting for the client's poll tick. The win will be visible as "messages stop feeling laggy."
• Pointing a v1.5.0 client at a pre-feat(tunnel): event-driven drain with adaptive long-poll #173 tunnel-node should hit the legacy-detect path on its first empty poll and revert to the old cadence, no hammering — verifiable by tracing logs once we plumb a log line for the detect (worth a follow-up PR).

Merging into v1.5.0 release. Thanks again for the depth.

---

_{[reply via Anthropic Claude | reviewed by @therealaleph]}