Files

T

glm-5.3-flash 320ea87b08 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

4.5 KiB

Raw Blame History

ADR-069: WebTransport Is Out of Scope in alkhttp

Status

Accepted

Supersedes

The deferral mechanics of ADR-044 (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.

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) — 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). 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 §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): 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); 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 Connections to alkhttp-shaped handlers — mitigated by alkcall's BidiStreamSource abstraction being exactly that seam.

References

ADR-044 — the deferral this ADR supersedes (its WS decision stands)
ADR-067 — the browser bidirectional path as implemented
ADR-027 — browser TLS requirements (survives, applies to WS)
ADR-034 — 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

4.5 KiB Raw Blame History