docs(http): add ADR-048 and websocket.md — WS carries native session, not gateway

Promote the WebSocket browser path from a section in http-server.md to a
first-class spec (websocket.md) and commit the contract-pattern decision
(ADR-048): a WS connection carries the native EventEnvelope call-protocol
session, not the HTTP gateway shape. The gateway endpoints are HTTP-only;
discovery on WS is via services/list/services/schema as ordinary call-protocol
ops; subscriptions project as native call.responded events (no SSE).

ADR-044 already decided WS as the v1 browser bidirectional path; ADR-048
clarifies the shape of what ADR-044 committed (§1 implies native session;
the ADR makes it an explicit implementer-visible rule). The from_wss adapter
(importing a remote node's ops over WS) is recorded as out-of-scope with a
concrete reversal trigger so it is not re-derived later.

Spec cleanup: http-server.md WS section collapsed to a stub pointer;
websocket.md Why section references ADRs rather than re-arguing them;
length-prefix decision made canonical (no prefix on WS — message boundary
is the delimiter); default upgrade path pinned (/alknet/call) with HTTP/2
extended CONNECT noted; indexes (README, http/README, overview) updated.
This commit is contained in:
2026-06-30 12:27:00 +00:00
parent bfd1621b9b
commit b71db99753
9 changed files with 859 additions and 90 deletions

View File

@@ -219,7 +219,8 @@ require it for the common case.
browser bidirectional path, ADR-044), subscriptions project onto the
WS connection directly as binary messages — the gateway's `/subscribe`
is the `h2`/`http/1.1` SSE path; the WebSocket path is the native
call-protocol session (`http-server.md` §"WebSocket browser path").
call-protocol session (`websocket.md`; the gateway shape does not
appear on WS per [ADR-048](048-websocket-native-session-not-gateway.md)).
WebTransport (`h3`, deferred per ADR-044) would project onto
WebTransport streams; the deferred design is at
`webtransport.md`.