alkhttp/tasks/websocket/review-002-ws13-idle-progress.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-002-ws13-idle-progress	Idle deadline off demux progress + slow-legitimate-stream decision (WS-13)	completed		moderate	high	component	implementation	websocket review-002

Description

Review 002 WS-13 [major]. The WS-01 remediation's idle timer (byte_adapter.rs:229-244) wraps only the next-message await, so it fails in both directions:

1. The attack it exists for defeats it. WS-01's dribble (declare a 16 MiB chunk, deliver one byte per WS message per minute) keeps arriving messages → the deadline resets on every dribble → the demux still parks forever with the partial chunk. The doc (:117) claims "a peer that drips bytes cannot park the single demux loop longer than this without traffic" — under the actual attack the peer supplies traffic forever.
2. Legitimate slowness is killed. A >60 s-silent-but-alive session (long handler compute, quiet subscription) is disconnected with 1001 mid-flight — no ping/pong keepalive exists, and chunk progress does not reset the timer.

The existing test (idle_read_timeout_resets_on_traffic) enshrines reset-on-message as correct — it codifies the gap.

Acceptance Criteria

• Decide + implement the progress semantics: the deadline resets on demux progress (bytes actually forwarded into read_tx), not message arrival — a peer that dribbles a chunk forever hits the deadline; a peer delivering complete chunks (even slowly per-message but productively) keeps the connection
• Decide + document the legitimate-silence stance (choose one and record it in the module doc + http-server/websocket.md): (a) add WS ping/pong keepalive so app-silence ≠ transport-silence, or (b) document that 60 s of no progress is an intentional eviction line even for silent subscriptions
• Acceptance test 1: chunk header [ch][len=N] dribbled in small messages with per-message gaps < timeout → connection closed (progress deadline fires)
• Acceptance test 2: scaled-down silent-but-alive session with a pending response is NOT disconnected when the knob's spirit says it should survive (e.g. messages flowing that make progress)
• The WS-01 knob surface (with_ws_idle_timeout) is unchanged; the semantics change is doc'd against it
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass (tungstenite-path unit tests + one axum integration mirror)

References

• docs/reviews/002-post-remediation-review.md (Part B', WS-13; Part G', COV-11b — the knob is currently untested on the axum path too)
• src/websocket/byte_adapter.rs:117 (doc claim), :229-253 (the timer), :782-1206 (tests)
• tasks/websocket/review-001-ws-session-limits.md (the WS-01 knob work)
• docs/architecture/websocket.md

Notes

Highest-risk task in the batch (touching the shared pump's read loop — the same loop the cap logic lives in). Slice suggestion: (1) progress tracking + tests on the tungstenite path, (2) doc/keepalive decision, (3) axum integration mirror. Coordinate with review-002-con18b-ws-polish (same file) — sequence, don't parallelize. If (a)-keepalive is chosen, note it interacts with FWD-15's server-side keep-alives on the HTTP SSE path — different layers, but document both in the same doc pass.

Summary

Idle deadline resets on completed inbound chunks (InboundChunkProgress observer), not message arrival; decision (b) documented - no WS keepalive, 60s no-progress eviction is intentional (pong is attacker-equivalent traffic). Tungstenite unit + axum integration tests; knob surface unchanged.