docs(tasks): decompose review 001 remediation Units 1-5 into taskgraph tasks
21 review-001 tasks across server/adapters/client/gateway/websocket/infra, chunked from the 7-unit remediation plan in docs/reviews/001-initial-implementation-review.md. - Scope split by mechanism, not one-per-finding: 15 tasks in generation 1 (parallelizable), 6 sequenced after their file-sharing precursors - Deliberately deferred until dependent fixes land: projection/doc fidelity partial (Unit 6 beyond dependency hygiene), coverage backfills (COV-01..07 via in-task acceptance for forward.rs), and per-finding minors (OAI-06/07, HY-02/04/06/10/11, CON-08) - Cross-crate WS-12 (alkcall demux 4 GiB discard alloc) noted for filing in alkcall, not here taskgraph: validate clean, no cycles, 6 generations
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
---
|
||||
id: review-001-ws-data-channel-decision
|
||||
name: Reconcile ADR-067 browser data channels with the v1 implementation (WS-03, planning)
|
||||
status: pending
|
||||
depends_on: []
|
||||
scope: narrow
|
||||
risk: low
|
||||
impact: project
|
||||
level: planning
|
||||
tags: [websocket, review-001, planning]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Review 001 finding WS-03: ADR-067 (websocket.md §"Data channels for
|
||||
browsers") promises browser-opened data channels and ADR-048 promises bidirectionality
|
||||
via the connection-local overlay, but the implementation hands the base
|
||||
registry to `install_channel_zero` and runs
|
||||
`Dispatcher::run_loop_single_stream` (`src/websocket/upgrade.rs:40,62-98`);
|
||||
no `ChannelCore`/`register_openable`/`ChannelOperations` wiring exists
|
||||
anywhere (grep-verified). A browser can never open a data channel — the
|
||||
capability ADR-067 says the channels design exists to provide.
|
||||
|
||||
This may have been a deliberate v1 cut (the WS tasks scoped channel-0
|
||||
dispatch only), but the spec promise and the implementation have not been
|
||||
reconciled in writing. This is a **decision task**, not an implementation
|
||||
task: either (a) wire the data-channel path, or (b) file the OQ / amend
|
||||
ADR-067 (+ ADR-048's overlay contract) to defer with a rationale.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Decision made and recorded (implementation task + ADR/OQ update, or ADR-067 amendment)
|
||||
- [ ] If v1-cut: ADR-067 and ADR-048 carry the reconciliation note; the gap is not silently silent
|
||||
- [ ] If in-scope: a follow-up task file exists with scoped acceptance criteria (incl. a browser-opened-channel test)
|
||||
|
||||
## References
|
||||
|
||||
- docs/reviews/001-initial-implementation-review.md (Part B, WS-03)
|
||||
- docs/architecture/decisions/067-websocket-carries-channels.md
|
||||
- docs/architecture/decisions/048-websocket-native-session-not-gateway.md
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation. Deliberately sequenced as
|
||||
> planning so the WS-01/02 robustness work is not blocked on a design
|
||||
> discussion.
|
||||
|
||||
## Summary
|
||||
|
||||
> Filled on completion.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: review-001-ws-eof-signal
|
||||
name: Lossless EOF signal + pending-map sweep for from_wss (WS-02, CON-02)
|
||||
status: pending
|
||||
depends_on: []
|
||||
scope: narrow
|
||||
risk: high
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [websocket, adapters, review-001, from-wss]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Review 001 findings WS-02 + CON-02 — one mechanism, verified end-to-end:
|
||||
|
||||
`src/websocket/byte_adapter.rs:138-139` (and the tungstenite twin at
|
||||
`:319`) fires `read_eof.notify_waiters()`, which wakes only
|
||||
*already-registered* waiters and stores no permit. `from_wss` spawns its
|
||||
drop-monitor *after* session setup (`from_wss.rs:156-166`); if the read
|
||||
task hits EOF before the monitor first polls `Notified`, the signal is
|
||||
lost. `import()` does `std::mem::forget(session)` (`:193`), so the
|
||||
`close_rx` fallback never fires either — the monitor never runs
|
||||
`fail_all`, and in-flight imported-op calls hang (Once-calls recover only
|
||||
at the 30 s sweeper *if* a sweeper runs; CON-02 establishes it doesn't on
|
||||
this path — `Dispatcher::run_loop`'s sweeper is never taken; `Sub`/`Pub`
|
||||
pendings hang forever). The module doc at `from_wss.rs:111-113` promises
|
||||
the opposite of the behavior.
|
||||
|
||||
Fix both halves:
|
||||
|
||||
- Replace `notify_waiters` with a permit-storing signal: `tokio::sync::watch`,
|
||||
`CancellationToken`, or a checked `AtomicBool` — anything a late
|
||||
subscriber observes. Apply to both the axum and tungstenite pump paths.
|
||||
- Extend the from_wss monitor to sweep the pending map periodically while
|
||||
the session lives (or otherwise ensure post-`fail_all` registrations
|
||||
still resolve), since calls registered after the one-shot `fail_all`
|
||||
are currently never resolved.
|
||||
|
||||
Acceptance gates from the review: (1) a from_wss test that drops the
|
||||
connection **while a call is being registered** — the CON-02 race — with
|
||||
no hang; (2) the module doc's promise ("no hang") becomes true.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] EOF-notify is stored (late subscriber observes it) — race test: drop during session setup/first call registration resolves all in-flight calls as retryable
|
||||
- [ ] Post-`fail_all`-registered pendings also resolve (sweep or equivalent), not hang forever
|
||||
- [ ] The `connection_drop_fails_in_flight_calls_retryable_no_hang` test remains green; add the racing-drop variant (COV gap 10)
|
||||
- [ ] Module doc at `from_wss.rs:111-113` matches implemented behavior
|
||||
- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass
|
||||
|
||||
## References
|
||||
|
||||
- docs/reviews/001-initial-implementation-review.md (Part B, WS-02; Part G, CON-02; COV-03)
|
||||
- docs/architecture/decisions/070-from-wss-consumer-adapter.md
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation. Highest-priority WS fix — lossy
|
||||
> notification hangs calls; everything else in the WS subsystem can
|
||||
> follow.
|
||||
|
||||
## Summary
|
||||
|
||||
> Filled on completion.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
id: review-001-ws-pump-consolidation
|
||||
name: Dedupe pumps + byte-based caps + write-side validation (WS-11, WS-04, WS-05, WS-06, HY-09)
|
||||
status: pending
|
||||
depends_on: []
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [websocket, review-001]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Review 001 findings where the correct fix is restructuring the duplicated
|
||||
pump code in `src/websocket/byte_adapter.rs`, so they are done once
|
||||
instead of twice (axum path `:119-180`, tungstenite twin `:299-364`):
|
||||
|
||||
- **WS-11**: ~60 lines of pump logic (read task, write task, close
|
||||
handling) are copy-pasted between the axum and tungstenite paths while
|
||||
the module doc claims "one implementation, both directions". Factor
|
||||
over a generic sink/stream of messages. This also closes COV-03 (the
|
||||
tungstenite twins are untested).
|
||||
- **WS-04 + HY-09**: the write-side chunk parser does no length
|
||||
validation (`:161-163`, twin `:343-345`) — non-chunk-framed bytes make
|
||||
the parser silently wait to accumulate `8 + len` (up to ~4 GiB) from
|
||||
misaligned offsets. Validate `len > MAX_CHUNK_LEN` → fail the stream
|
||||
loudly; saturating add for the 32-bit overflow.
|
||||
- **WS-05**: the write-side `pending` buffer is bounded in slots (64) but
|
||||
not in bytes (~1 GiB worst case per connection with a slow sink).
|
||||
Cap `pending` growth in bytes.
|
||||
- **WS-06**: inbound per-connection memory bound is 64 slots × 64 MiB
|
||||
(axum/tungstenite defaults) ≈ 4 GiB — `max_message_size`/
|
||||
`max_frame_size` are never configured. Set explicit caps consistent
|
||||
with the plan's ~1 MiB write-side intent.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Pump bodies factored into one generic implementation (both paths share it)
|
||||
- [ ] Write-side rejects `len > MAX_CHUNK_LEN` with a stream error (test); no `8 + len` overflow path
|
||||
- [ ] Write `pending` byte-capped; inbound message/frame size explicitly configured (tests)
|
||||
- [ ] Tungstenite path exercised by the shared test suite (COV-03 backfilled)
|
||||
- [ ] 16 MiB round-trip and disconnect-cleanup tests still pass
|
||||
- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass
|
||||
|
||||
## References
|
||||
|
||||
- docs/reviews/001-initial-implementation-review.md (Part B, WS-04, WS-05, WS-06, WS-11; HY-09; COV-03)
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation. Sequenced with (or after)
|
||||
> review-001-ws-eof-signal so the dedup doesn't churn under it — both
|
||||
> touch byte_adapter.rs.
|
||||
|
||||
## Summary
|
||||
|
||||
> Filled on completion.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: review-001-ws-session-limits
|
||||
name: WS session lifecycle — idle timeout, shutdown, teardown, caps (WS-01, WS-07..WS-10)
|
||||
status: pending
|
||||
depends_on: [review-001-ws-eof-signal]
|
||||
scope: narrow
|
||||
risk: medium
|
||||
impact: component
|
||||
level: implementation
|
||||
tags: [websocket, review-001]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Review 001 WS subsystem lifecycle/staleness findings over
|
||||
`src/websocket/upgrade.rs` and `byte_adapter.rs`:
|
||||
|
||||
- **WS-01 (major)**: the single demux loop means one dribbled chunk
|
||||
stalls all channels indefinitely — alkcall's demux has no read timeout
|
||||
and a peer header `[ch=0][len=16 MiB]` + one byte/ minute parks the
|
||||
allocation and hangs every outstanding channel-0 call (Sub/Pub pendings
|
||||
until the socket dies). Add a configurable idle timeout on the WS read
|
||||
that closes with 1001 on staleness (deployment knob; default bounds the
|
||||
stall).
|
||||
- **WS-07**: `poll_shutdown` drops a *fresh clone* of `write_tx`
|
||||
(`byte_adapter.rs:269-276`) so the channel never closes and the
|
||||
documented `ws_sink.close()` never runs at shutdown — the `from_wss`
|
||||
path never emits a WS Close frame at all. Drop the held sender.
|
||||
- **WS-08**: `_pumps` is dropped immediately (`upgrade.rs:36`); the
|
||||
documented forced-teardown lever `WsPumps::abort()` is never callable
|
||||
on the server path. Retain the handle so a stuck session is evictable
|
||||
in-crate.
|
||||
- **WS-09**: no cap on WS sessions (post-auth DoS); the assembly layer
|
||||
cannot add one because the route is built inside `HttpAdapter`. Add a
|
||||
semaphore in `ws_upgrade_handler` (configurable; document the default).
|
||||
- **WS-10**: dispatcher/mux tasks outlive a failed session task
|
||||
(`upgrade.rs:65-97`) — self-healing but a peer-behavior-tied leak
|
||||
window. Document the semantics (the cheap fix) or tie task lifetimes
|
||||
to the session.
|
||||
- Fold-in from review-001-hyper-server-knobs: SRV-10's policy-injection
|
||||
point (channel cap) belongs here if that task doesn't land it.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Idle timeout bounds a dribble stall (test: dribbling peer's channels fail/bound rather than hang forever)
|
||||
- [ ] `shutdown()` causes a WS Close frame to the peer (test)
|
||||
- [ ] `_pumps` retained; `abort()` reachable on the server path
|
||||
- [ ] Session concurrency cap configurable in `HttpAdapter`; enforced (test)
|
||||
- [ ] Detached-task lifetime semantics documented (WS-10)
|
||||
- [ ] `cargo test` and `cargo clippy --all-targets -- -D warnings` pass
|
||||
|
||||
## References
|
||||
|
||||
- docs/reviews/001-initial-implementation-review.md (Part B, WS-01, WS-07..WS-10)
|
||||
- docs/architecture/decisions/048-websocket-native-session-not-gateway.md
|
||||
|
||||
## Notes
|
||||
|
||||
> Agent fills during implementation. Takes the EOF-signal task first
|
||||
> (same files, and the lifecycle knobs build on the lossless signal).
|
||||
|
||||
## Summary
|
||||
|
||||
> Filled on completion.
|
||||
Reference in New Issue
Block a user