docs(adrs): reconcile WS-03 browser data-channel promise (ADR-067/048)
Record the v1 cut for browser-opened data channels over WS (review-001 WS-03): the design (ADR-067) stands; only the wiring is deferred. - open-questions.md: add OQ-05 (deferred(scope: v1 cut)) with gap detail and deferred scope - ADR-067: dated status amendment + v1-cut note at the data-channel step; References point to OQ-05 - ADR-048: dated reconciliation note — overlay bidirectionality is decided design, not a v1 implementation commitment - websocket.md: status notes on §"Data channels for browsers" and upgrade step 7 - task review-001-ws-data-channel-decision: completed, Summary filled Verification: taskgraph validate (38 tasks OK); cargo doc --no-deps (pre-existing warnings only).
This commit is contained in:
@@ -6,6 +6,16 @@
|
||||
|
||||
Accepted
|
||||
|
||||
> **Reconciliation note (2026-08-29):** the bidirectionality this ADR
|
||||
> promises for the WS path (§4 — the hub calling browser-registered ops
|
||||
> through the connection-local Layer 2 overlay) is **decided design,
|
||||
> not a v1 implementation commitment**. Today the WS path installs
|
||||
> channel 0 only; no data-channel open path and no browser-side
|
||||
> registration wiring exists (review-001 finding WS-03). The cut and
|
||||
> its rationale are recorded in
|
||||
> [OQ-05](../open-questions.md); the native-session contract below
|
||||
> stands as what the deferred wiring must satisfy.
|
||||
|
||||
## Status amendment (alkhttp port)
|
||||
|
||||
- **The WS path carries the channels session** (alkhttp ADR-067): a
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
Accepted (amended 2026-08-29 — the data-channel half of the WS path is
|
||||
deferred, not yet wired; see [OQ-05](../open-questions.md))
|
||||
|
||||
## Context
|
||||
|
||||
@@ -99,6 +100,13 @@ On upgrade, the handler:
|
||||
ops on channel 0 (alkcall ADR-047), the same mechanism as any
|
||||
consumer.
|
||||
|
||||
> **v1 cut (2026-08-29):** step 4 is designed but not wired in v1 —
|
||||
> today the WS upgrade path installs channel 0 only and no
|
||||
> `register_openable`/data-channel dispatch path exists for browser
|
||||
> sessions (review-001, WS-03). The deferral and its rationale are
|
||||
> recorded in [OQ-05](../open-questions.md); the design above is the
|
||||
> contract the deferred wiring implements.
|
||||
|
||||
Everything ADR-048 says about dispatch — `call.requested` →
|
||||
`Dispatcher::dispatch_requested` with `AccessControl::check` gating,
|
||||
`call.responded`/`call.completed`/`call.aborted` correlated by `id` via
|
||||
@@ -158,7 +166,10 @@ in-line channels session:
|
||||
|
||||
## References
|
||||
|
||||
- [websocket.md](../websocket.md) — the full WS session spec
|
||||
- [websocket.md](../websocket.md) — the full WS session spec (its
|
||||
§"Data channels for browsers" carries the same v1-cut note)
|
||||
- [OQ-05](../open-questions.md) — the data-channel v1 cut deferral
|
||||
(status `deferred(scope)`; reopened when a browser consumer lands)
|
||||
- [ADR-048](048-websocket-native-session-not-gateway.md) — the native
|
||||
session (not gateway shape) decision this ADR amends (channel 0
|
||||
framing; upgrade path)
|
||||
|
||||
@@ -75,6 +75,35 @@ with their resolutions; new alkhttp OQs start at OQ-01.
|
||||
alkcall BAST document (`chunk-header.bast.json`); the client library
|
||||
lives outside this crate. Deferred(scope: browser UI work).
|
||||
|
||||
### OQ-05: Browser-opened data channels over WS — v1 cut
|
||||
|
||||
- **Origin**: review-001 finding WS-03 (`docs/reviews/001-initial-implementation-review.md`),
|
||||
[ADR-067](decisions/067-websocket-carries-channels.md),
|
||||
[ADR-048](decisions/048-websocket-native-session-not-gateway.md)
|
||||
- **Status**: deferred(scope: v1 cut — no browser consumer yet; reopened
|
||||
when one lands)
|
||||
- **Priority**: medium
|
||||
- **Question**: ADR-067 §"Data channels for browsers" promises
|
||||
browser-opened data channels (open ops on channel 0 → chunk
|
||||
demultiplexing of channels 1..N), and ADR-048's bidirectionality
|
||||
promise leans on the same connection-local machinery. The v1
|
||||
implementation wires channel 0 only (`install_channel_zero` +
|
||||
`Dispatcher::run_loop_single_stream`, `src/websocket/upgrade.rs`);
|
||||
no `ChannelCore`/`register_openable`/`ChannelOperations` path exists
|
||||
for a browser to open a data channel (grep-verified, review-001).
|
||||
The design is decided (ADR-067: the browser opens data channels
|
||||
exactly as any channels consumer — nothing new to design); what is
|
||||
deferred is the *wiring*: passing the deployment's openable-ALPN
|
||||
registrations and `ChannelLifecyclePolicy` through the WS upgrade
|
||||
path, plus a browser-opened-channel end-to-end test.
|
||||
- **Resolution**: (pending — v1 cut recorded 2026-08-29 in ADR-067 and
|
||||
ADR-048; the recently landed WS robustness work — idle-read timeout,
|
||||
session caps/eviction, pump consolidation — is the foundation the
|
||||
deferred work builds on)
|
||||
- **Cross-references**: [ADR-067](decisions/067-websocket-carries-channels.md),
|
||||
[ADR-048](decisions/048-websocket-native-session-not-gateway.md),
|
||||
[websocket.md](websocket.md), tasks/websocket/review-001-ws-data-channel-decision.md
|
||||
|
||||
## Resolved (ported)
|
||||
|
||||
Resolutions inherited from the alknet architecture; recorded here for
|
||||
|
||||
@@ -89,6 +89,8 @@ route on `HttpAdapter`'s router. The handler:
|
||||
7. Data channels (1..N) route per the deployment's openable-ALPN
|
||||
registrations; the browser opens them via the per-ALPN open ops on
|
||||
channel 0 (alkcall ADR-047), the same mechanism any consumer uses.
|
||||
*(Deferred wiring, v1 cut — see [OQ-05](open-questions.md);
|
||||
step 6, channel 0, is all v1 implements.)*
|
||||
|
||||
The **default upgrade path is `/alk/channels`** (was `/alknet/call` in
|
||||
the alknet design). The path must not collide with the reserved
|
||||
@@ -198,6 +200,11 @@ before ACL). This is alkcall ADR-017's model; see also
|
||||
|
||||
### Data channels for browsers
|
||||
|
||||
> **Status (2026-08-29):** decided design, deferred wiring — the v1 WS
|
||||
> path installs channel 0 only; browser data-channel opens are not yet
|
||||
> wired (review-001, WS-03; [OQ-05](open-questions.md)). The mechanism
|
||||
> below is the contract the deferred wiring implements.
|
||||
|
||||
A browser opens a data channel exactly as any channels consumer:
|
||||
|
||||
1. Calls the per-ALPN open op on channel 0
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
|
||||
---
|
||||
id: review-001-ws-data-channel-decision
|
||||
name: Reconcile ADR-067 browser data channels with the v1 implementation (WS-03, planning)
|
||||
status: pending
|
||||
status: completed
|
||||
depends_on: []
|
||||
scope: narrow
|
||||
risk: low
|
||||
@@ -29,8 +30,8 @@ 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
|
||||
- [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
|
||||
@@ -45,6 +46,38 @@ ADR-067 (+ ADR-048's overlay contract) to defer with a rationale.
|
||||
> 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
|
||||
|
||||
> Filled on completion.
|
||||
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).
|
||||
Reference in New Issue
Block a user