A deadline for the coroutine receive, contract-wide (#130)

[aaylward]

What

Closes #130: co_await stream.Receive(timeout) — the completion-driven twin of #128's blocking deadline, with the same contract. A Detached serve loop can now bound every await instead of parking its frame forever (heap-invisible, holding its session) on a peer that never sends.

• WebSocket::ReceiveAsync(timeout, callback) joins the contract: same four outcomes as the blocking overload — message, clean close, terminal error, Error::Timeout (code TimeoutError) — and the same rule: a timeout is not terminal, the receive slot is released exactly as a completed receive releases it, a message the wire delivers after the deadline waits for the next receive, and a non-positive timeout polls. A refusing default keeps every implementor compiling (the async family is opt-in, unlike the pure-virtual blocking overload); the shared contract suite holds every SupportsAsync() implementation to it.
• The design question the issue flags (stash vs. cancel) dissolves at the socket layer: both transports already land inbound messages in per-session state and hand them to whoever receives next, so timing out a parked callback releases the slot without touching the wire, the read pump, or any in-flight message — no per-stream stash above, no cancellation primitive below.
• The exactly-once race (timer vs. delivery vs. terminal transition) settles under the session lock via a park generation: every park bumps it, a deadline fires only for the generation it was armed with, so a stale deadline can never time out a later receive (timed or not). Beast arms a steady_timer on the connection's executor, captured weakly so a deadline never extends a session's life; the executor-less in-memory pair arms a short-lived watchdog thread on its shared state; JsonRpcStreamSocket passes the deadline through its classifier, where a timeout rides untouched (no violation, no close — the blocking overload's exact posture).
• The coroutine layer: AsyncEventStream::Receive(timeout) (the async twin of EventStream's timed Receive — the matrix is now complete) and a ReceiveMessage(socket, timeout) overload for the raw pre-stream await (the jsonRpc2 opening-envelope read). Only decoder rejections close the session; the timeout passes through the awaitable untouched.
• No ADR: like Add a deadline to WebSocket::Receive() #128's blocking half, this extends the ADR-0019 contract rather than changing architecture.

Folded in, as asked: out-of-tree, real-socket e2e for the #109 numeric bounds. The consumer's todo model gains an intEnum priority and float effortHours (optional — handlers and the model-evolution script untouched), so the narrowing/membership checks now run through the exact pipeline consumers ship: generator at build time → regenerated server on the production transport → hostile wire values (2^32+2, an unknown member, 1e300) rejected before the handler with suite-exact identities → the generated client serializing valid ones.

Also: TSan on the new deadline tests surfaced a latent race in the test suite's own Mailbox (notify outside the lock — the rule ContractMailbox already documents); fixed to match.

Testing

• Contract suite (websocket_contract_test.h): four new type-parameterized deadline cases — quiet-wire timeout with slot release across two rounds, the non-positive poll, a terminal transition beating a parked deadline (with the one-shot mailbox proving the stale timer never double-completes), and one-outstanding across the overloads. They run over every instantiation: the pair, Beast, JsonRpcStreamSocket, and the consumer's own out-of-tree socket (which now implements the timed op, watchdog-shaped and generation-guarded).
• Pair + coroutine layers (async_event_stream_test.cc): delivery-beats-deadline, timeout-then-late-message (nothing lost), the stale-deadline no-op, the zero-timeout poll, a serve loop that ticks through timeouts and then echoes, and the raw awaitable's deadline.
• Real wire: beast_websocket_test.cc runs the timer against Beast's executor (timeout, then delivery under a fresh deadline with the stale timer live); jsonrpc_stream_socket_test.cc pins the wrapper's timed pass-through next to its blocking twin; the consumer's async_acceptance_test.cc runs the stated audience end to end — a hand-written Detached loop over a real Beast socket bounding its awaits out of tree.
• Consumer numeric bounds: todo_beast_acceptance_test.cc posts the hostile bodies over the real socket and asserts the suite-exact rejections, then round-trips valid values through the generated client.
• Locally: bazel test //... in-tree 126/126 and in the consumer module 13/13, both --config=werror; TSan over the four touched concurrency suites (which is what caught the Mailbox race) and gcc UBSan over the same, all green; clang-format/buildifier/changelog lint clean. The consumer's model-evolution script anchors are untouched by the model change.

Checklist

• Tests added/updated for the change
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally (no codegen/Java changes in this PR)
• Formatting clean (clang-format, buildifier, spotless)
• Architectural decisions recorded as an ADR (not applicable — extends the ADR-0019 contract the way Add a deadline to WebSocket::Receive() #128 extended the blocking half; no new architecture)

🤖 Generated with Claude Code

https://claude.ai/code/session_014C7WdBD99mUFWGxMvGSjSU

---

Generated by Claude Code

[cursor]

Review

LGTM — closes the #130 gap cleanly as the completion-driven twin of #128, and the prior panel survivors (spawn-failure refuse, lock scope around pthread_create, far-future saturation, park-off-the-slot) look correctly landed. CI is green across the full matrix.

What looks right

• Park generation settles the timer/delivery/terminal race exactly once under the session lock on every path that matters: Beast (ArmReceiveDeadlineLocked / OnReceiveDeadline), the in-memory pair watchdog, and the out-of-tree ConsumerSocket. A stale deadline cannot complete a later park; a terminal transition that beats the deadline leaves the one-shot mailbox alone.
• Timeout is not terminal is held end to end: slot released, session usable, late wire message waits for the next receive. ClassifyInbound passes !ok() through untouched, so JsonRpcStreamSocket neither violates nor closes on TimeoutError — matching the blocking overload.
• Coroutine layer is the thin pass-through it should be (Receive / ReceiveMessage timeout overloads); only decoder rejection closes. The Detached serve-loop test and the consumer Beast acceptance test are the right audience proofs.
• Contract suite gains the four deadline cases every SupportsAsync() driver must pass, including the consumer module — so the refusing default cannot silently strand a third-party socket that claims async.
• Mailbox notify-under-lock fix matches ContractMailbox's rule; TSan catching it on the new deadline tests is the right failure mode.
• Tracking: C++ Core Guidelines conformance review #109 fold (optional priority / effortHours over the real socket) is a clean consumer-boundary pin and leaves handlers / model-evolution anchors alone.

Nits (non-blocking)

1. Beast spent timers — Deliver / TakeAsyncWaitersLocked clear pending_receive_ but leave receive_deadline_ armed until it fires or the next timed park emplaces over it. Correct via generation + weak capture; receive_deadline_.reset() on slot release would just spare a useless executor wakeup.
2. ConsumerSocket overload shape — untimed ReceiveAsync still early-returns under the lock; timed uses the deliver-slot / std::exchange shape the pair settled on for clang-tidy. Behavior matches; unifying the untimed path would remove the last parallel park style in that file.

No correctness issues found; happy to see this land.