glm-5.3-flash
320ea87b08
Phase 1 (SDD) — architecture documentation: Ported specs (adapted for alkcall, producer/consumer terms, 6-endpoint gateway, channels-over-WS, Sub/Pub operation types): - overview.md, http-server.md, http-adapters.md, http-mcp.md - README.md index (rewritten for alkhttp) New ADRs: - 067: WebSocket carries the channels protocol (8-byte chunk demux, channel 0 = alk/call, upgrade path /alk/channels) - 068: gateway /publish endpoint for Pub operations (NDJSON body) - 069: WebTransport out of scope in alkhttp (alknet concern) - 070: from_wss consumer adapter (wss feature, tokio-tungstenite) Ported ADRs (25, same numbers, port notes + amendments where the extraction changed facts): 001-004, 010, 014, 015, 017, 022, 023, 027, 034, 036, 037, 039, 041, 042, 044, 045, 046, 047, 048, 049, 051, 066. websocket.md rewritten for the channels session; open-questions.md seeded (OQ-01 WS byte-stream adapter, OQ-02 /publish framing, OQ-03 from_wss reconnect, OQ-04 browser client ownership). Verified: cargo test, clippy -D warnings, fmt, doc --no-deps.
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# ADR-069: WebTransport Is Out of Scope in alkhttp
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Supersedes
|
|
|
|
The deferral mechanics of
|
|
[ADR-044](044-defer-webtransport-browsers-use-websocket.md) (as applied
|
|
to the `alknet-http` crate): the "deferred within this crate, revives
|
|
on trigger" framing is replaced by removal from the crate's scope. The
|
|
substantive outcome ADR-044 committed — **the browser bidirectional
|
|
path is WebSocket** — stands, now realized as
|
|
[ADR-067](067-websocket-carries-channels.md).
|
|
|
|
## Context
|
|
|
|
The alknet design went back and forth on HTTP/3 + WebTransport
|
|
(`h3`): first-class (ADR-038), then deferred-with-revival-trigger
|
|
(ADR-044), with the ALPN-stream-proxy and bidirectional-substrate
|
|
designs parked (ADR-040, ADR-043) pending a concrete browser-side use
|
|
case (a WASM SSH/SFTP/git client reaching non-call ALPNs).
|
|
|
|
The extraction changes the frame. alkhttp is a lean HTTP interface
|
|
crate on top of alkcall, which is transport-agnostic. WebTransport is
|
|
a *transport* concern — it involves the h3 handshake, QUIC stream
|
|
management, and TLS identity provisioning (X.509 for browsers,
|
|
[ADR-027](027-tls-identity-redesign-acme-rawkey-decoupling.md)) — all
|
|
of which live in the alknet layer, not in the HTTP interface library.
|
|
Keeping WebTransport in alkhttp would mean either shipping a transport
|
|
stack in this crate (violating the extraction's lean-crate goal) or
|
|
keeping a dormant design doc for a feature with no concrete consumer.
|
|
|
|
Meanwhile, the concrete browser need that motivated the whole
|
|
WebTransport track is now met differently: the browser bidirectional
|
|
path is WebSocket *carrying the channels protocol*
|
|
([ADR-067](067-websocket-carries-channels.md)). A WASM SSH client in a
|
|
browser no longer needs WebTransport's multi-stream model — it opens a
|
|
data channel over the WS channels session, exactly as a Rust
|
|
consumer would.
|
|
|
|
## Decision
|
|
|
|
**alkhttp does not implement, feature-gate, or specc `h3`/WebTransport.
|
|
No `h3` ALPN registration, no `wtransport`/h3 dependency, no
|
|
webtransport spec document in this crate.** The `h3` ALPN handler,
|
|
the ALPN-stream-proxy, and any WebTransport relay are alknet-layer
|
|
concerns — if and when the alknet layer revives them, the alkcall ADRs
|
|
(parked in the mono-repo's history) and the alknet architecture docs
|
|
are the reference, and the alkhttp `HttpAdapter` design is
|
|
transport-agnostic enough to compose with whatever substrate alknet
|
|
provides.
|
|
|
|
### What survives from the WebTransport work
|
|
|
|
- **The "browser is not a peer" rationale**
|
|
([ADR-034](034-outgoing-only-x509-and-three-peer-roles.md) §4,
|
|
amended by ADR-044 §5): stated transport-agnostically, it applies to
|
|
any browser transport — WS today, WebTransport if alknet ever
|
|
revives it.
|
|
- **Browsers require X.509** ([ADR-027](027-tls-identity-redesign-acme-rawkey-decoupling.md)):
|
|
applies to any browser-facing TLS, including the WS path's TLS.
|
|
- **The channels substrate modes** (alkcall ADR-034): the in-line mode
|
|
is implemented (TCP+TLS today, WS per
|
|
[ADR-067](067-websocket-carries-channels.md)); a native
|
|
multi-stream mode (QUIC, WebTransport) composes later without
|
|
changing the wire format or the handler experience.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
|
|
- alkhttp stays lean: no h3 stack, no dormant code paths, no parked
|
|
design docs in this repo.
|
|
- The browser bidirectional story is complete without WebTransport
|
|
(ADR-067).
|
|
- Transport experimentation stays in the alknet layer where TLS, dial,
|
|
and endpoint ownership already live.
|
|
|
|
**Negative:**
|
|
|
|
- A browser cannot use HTTP/3-native multiplexing for alk sessions.
|
|
WebSocket over HTTP/2 (or HTTP/1.1) is the path; its framing cost
|
|
(one chunk stream over one message stream) is accepted.
|
|
- If WebTransport revives in alknet, some coordination is needed so the
|
|
alknet-side handler can present `Connection`s to alkhttp-shaped
|
|
handlers — mitigated by alkcall's `BidiStreamSource` abstraction
|
|
being exactly that seam.
|
|
|
|
## References
|
|
|
|
- [ADR-044](044-defer-webtransport-browsers-use-websocket.md) — the
|
|
deferral this ADR supersedes (its WS decision stands)
|
|
- [ADR-067](067-websocket-carries-channels.md) — the browser
|
|
bidirectional path as implemented
|
|
- [ADR-027](027-tls-identity-redesign-acme-rawkey-decoupling.md) —
|
|
browser TLS requirements (survives, applies to WS)
|
|
- [ADR-034](034-outgoing-only-x509-and-three-peer-roles.md) — the
|
|
browser-is-not-a-peer rationale (survives, transport-agnostic)
|
|
- The alknet mono-repo — owner of the endpoint, TLS, QUIC, and
|
|
(deferred/removed) WebTransport concerns and their ADR history |