docs: port architecture specs and ADRs from alknet-http; write new alkhttp ADRs 067-070

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.
2026-08-27 14:19:24 +00:00
parent 28c521b2f3
commit 320ea87b08
42 changed files with 11275 additions and 1 deletions
@@ -0,0 +1,102 @@
+# 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