alkhttp/tasks/websocket/overlay-ops.md at 5f12abf80e2ff2a7d99f93c1da5b5d6be5419f80

Files

T

glm-5.3-flash bc99ec7188 test(websocket): connection-local overlay verification for browser-registered ops

Ported the alknet-http overlay verification to the channels-over-WS
session (tests/ws_overlay_ops.rs, test-support feature, 8 tests):

- overlay mechanism: browser-registered ops land in the connection's
  Layer 2 overlay (register_imported), exposed via overlay_env() —
  no PeerIds (browsers are not peers); PeerRef::Specific to a browser
  id routes to nothing (NOT_FOUND)
- hub→browser call through compose_root_env's attached overlay
- AccessControl on browser ops gates hub calls (scope match allows,
  missing scope FORBIDDEN)
- overlay dies with the connection; no leak between connections;
  in-flight calls to browser ops resolve on close
- wire-level: 10 interleaved concurrent calls across two WS sessions
  — no cross-correlation, no deadlock; disconnect mid-call resolves
  and a fresh session works (no listener wedge)

byte_adapter: read_eof Notify now gated to the wss feature (its only
consumer is from_wss) so a test-support-only build is warning-free.

Verified: cargo test (182 lib), --all-features (227 lib + 5 MCP + 8
overlay + 10 WS integration), clippy -D warnings (default,
test-support, all-features), fmt.

2026-08-28 15:49:25 +00:00

3.4 KiB

Raw Blame History

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

name

status

depends_on

scope

risk

impact

level

Description

Port the connection-local Layer 2 overlay verification from /workspace/@alkdev/alknet/crates/alknet-http/src/websocket/overlay.rs to the channels-over-WS session: a WS client registers ops (via call-protocol registration on channel 0), the hub reaches them through the live connection handle's overlay_env() — not PeerRef. Tests: hub→browser call over the same session; overlay ops die on disconnect; AccessControl gating on browser ops; bidirectional concurrent calls (both sides initiating on channel 0).

Acceptance Criteria

Hub→browser call test passes (browser registered an op, hub invokes it)
Disconnect drops overlay; subsequent reach attempts fail cleanly
Concurrent bidirectional calls don't deadlock or cross-correlate
cargo test passes

References

docs/architecture/websocket.md (§Connection-local overlay, §Bidirectionality)
docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md (§4)
alkcall ADR-019 (registry layering)
Old source: /workspace/@alkdev/alknet/crates/alknet-http/src/websocket/overlay.rs

Notes

Ported as tests/ws_overlay_ops.rs (feature test-support — needs the tokio-tungstenite WS client). The old alknet-http overlay.rs unit tests exercised CallConnection::new_overlay_only + register_imported

overlay_env + compose_root_env directly — that verification carried over 1:1 since the overlay machinery is alkcall's (no fork). The wire-level additions exercise both call directions over a real axum channels session (the alknet upgrade.rs session shape was envelope-per-message; the alkhttp session is channels-over-WS with the byte adapter, so the wire tests use chunk framing).

Summary

Ported the connection-local Layer 2 overlay verification to the channels-over-WS session (tests/ws_overlay_ops.rs, 8 tests, test-support feature):

Overlay mechanism (hub reaches browser ops through the live connection handle's overlay_env(), not PeerRef — ADR-034 §4, alkcall ADR-019):

browser-registered op lands in the overlay, exposes no PeerIds (browser is not a peer)
hub→browser call routes through compose_root_env's attached peer overlay (identity-keyed, the browser's identity.id)
PeerRef::Specific("browser-X") routes to nothing (NOT_FOUND) — no peer entry for a browser
AccessControl on browser ops gates hub calls (allowed with matching scope, FORBIDDEN without)
overlay drops with the connection; no leak between connections; connection-local isolation between two sessions
ws close mid-call aborts the pending call (CONNECTION_CLOSED)

Wire-level bidirectionality over the real WS server (axum + upgrade

channels session):

concurrent bidirectional calls: two WS sessions each fire 5 interleaved echo calls on channel 0; ids and outputs verified not to cross-correlate (stream-agnostic correlation, alkcall ADR-015)
disconnect mid-call: pending resolves, a fresh session connects and completes a call (no hang, no listener wedge)

8 tests green. Also fixed a cfg-gating gap: WsPumps::read_eof (the from_wss drop monitor's EOF signal) is now gated on the wss feature only (it has no test-support-only consumer), keeping a test-support-without-wss build warning-free.

3.4 KiB Raw Blame History