82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
---
|
|
id: review-001-ws-data-channel-decision
|
|
name: Reconcile ADR-067 browser data channels with the v1 implementation (WS-03, planning)
|
|
status: completed
|
|
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
|
|
|
|
- [x] Decision made and recorded (implementation task + ADR/OQ update, or ADR-067 amendment)
|
|
- [x] 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.
|
|
|
|
Decision: **option (b) — v1 cut, recorded**. The design (ADR-067) needs
|
|
no changes; only the wiring is missing, and building it was out of scope
|
|
for the review-001 remediation cycle. The recently landed WS robustness
|
|
work (WS-01 idle-read timeout, WS-08/09 session caps/eviction, pump
|
|
consolidation) is the foundation the future data-channel wiring builds
|
|
on; a fresh, properly scoped implementation task in a later cycle is the
|
|
honest sequencing (tracked via OQ-05, reopened when a browser consumer
|
|
lands).
|
|
|
|
## Summary
|
|
|
|
Decision: option (b) — record the v1 cut; do not wire the data-channel
|
|
path in this cycle. Where recorded:
|
|
|
|
- `docs/architecture/open-questions.md` — new **OQ-05** ("Browser-opened
|
|
data channels over WS — v1 cut"), status `deferred(scope: v1 cut —
|
|
no browser consumer yet; reopened when one lands)`, with the gap
|
|
spelled out (channel-0-only wiring in `src/websocket/upgrade.rs`; no
|
|
`ChannelCore`/`register_openable`/`ChannelOperations` path) and the
|
|
deferred scope named (openable-ALPN/policy pass-through + a
|
|
browser-opened-channel end-to-end test).
|
|
- `docs/architecture/decisions/067-websocket-carries-channels.md` —
|
|
Status line amended (2026-08-29) and a v1-cut note added under the
|
|
data-channel step of the upgrade path; References point to OQ-05.
|
|
- `docs/architecture/decisions/048-websocket-native-session-not-gateway.md`
|
|
— dated reconciliation note under Status: §4's bidirectionality via
|
|
the connection-local overlay is decided design, not a v1
|
|
implementation commitment.
|
|
- `docs/architecture/websocket.md` — status note on §"Data channels for
|
|
browsers" and a parenthetical on upgrade step 7, so the spec no
|
|
longer silently promises the capability.
|
|
|
|
Verification: `taskgraph validate` passes (38 tasks); `cargo doc
|
|
--no-deps` unaffected (only pre-existing src/ rustdoc warnings — no
|
|
source changes in this task). |