docs(http): defer h3/WebTransport (ADR-044); browsers use WebSocket for v1
Working through the WebTransport implementation path surfaced a scope question distinct from the hedging-as-deferral anti-pattern ADR-038 was written to correct. Three findings drove the re-evaluation: 1. The browser bidirectional call-protocol path doesn't require WebTransport — WebSocket is full-duplex, EventEnvelope fits a WS binary message boundary cleanly, and the Dispatcher is stream- agnostic (ADR-012). What WebTransport gives over WebSocket (native multi-stream multiplexing, the ALPN-as-stream substrate) benefits the proxy use case, not the call protocol. 2. WebTransport is a draft standard (-07, not RFC) on an experimental Rust dependency stack (wtransport/h3 both self-describe as not production-ready). Either choice puts a draft protocol on the security surface of the first release. 3. The ALPN-stream-proxy (ADR-040) is speculative — its WASM parser consumers (browser SSH/SFTP/git clients) don't exist yet, and the downstream crates WebTransport deferral blocks (SSH, git, SFTP) expose their ALPNs natively over QUIC regardless. This is a scope decision (per ADR-009: a decision that 'genuinely doesn't need to be made yet because the use case isn't concrete'), not hedging. The reversal trigger is concrete: a real deployment needing the ALPN-stream-proxy. ADR-038 is superseded (its anti-pattern correction stands; its specific 'h3 in scope now' decision is reversed). ADR-040 and ADR-043 are parked, not superseded — their designs revive unchanged when WebTransport revives, with §2 (bidirectionality) and §3 (no-PeerId overlay) of ADR-043 transferring to WebSocket for v1. ADR-044 §5 also states the 'browser is not a peer' rationale that ADR-034 §4 closed without arguing: peer = addressable node in the call-protocol peer graph (stable PeerId, PeerRef::Specific-reachable, identity stable across reconnects), not 'any endpoint that exchanges calls during a live session.' A browser is the second but not the first (no stable crypto identity of its own, ephemeral, not addressable from other nodes). ADR-034 §4 and Assumption 2 are amended by reference. The wtransport-vs-hyperium dependency question is recorded (not resolved — WebTransport is deferred) in ADR-044 §'Research note' and webtransport.md so the revival doesn't re-derive it: wtransport probably isn't the right choice (axum-bridge friction — it owns its own HTTP serving path); the hyperium stack (h3 + h3-quinn + h3-webtransport) fits the axum integration better but its server-side WebTransport API needs verification before commitment. Reviewed by architecture-review subagent; all critical cross-reference issues (ADR-034 §5 stale 'in scope' assertion, ADR-036 Context listing h3 as implemented, webtransport.md Design Decisions table) resolved.
This commit is contained in:
@@ -214,11 +214,14 @@ require it for the common case.
|
||||
`/schema` at build time.
|
||||
|
||||
4. **`subscribe` (SSE) is the streaming projection for the gateway.**
|
||||
Over `h2`/`http/1.1`, subscriptions are SSE. Over WebTransport
|
||||
(`h3`), subscriptions project onto WebTransport streams directly
|
||||
(ADR-038) — the gateway's `/subscribe` is the `h2`/`http/1.1` path;
|
||||
the WebTransport path is the native call-protocol session
|
||||
(`webtransport.md`).
|
||||
Over `h2`/`http/1.1`, subscriptions are SSE. Over WebSocket (the v1
|
||||
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").
|
||||
WebTransport (`h3`, deferred per ADR-044) would project onto
|
||||
WebTransport streams; the deferred design is at
|
||||
`webtransport.md`.
|
||||
|
||||
## References
|
||||
|
||||
@@ -232,9 +235,11 @@ require it for the common case.
|
||||
- [ADR-036](036-http-to-call-operation-mapping.md) — the SSE projection
|
||||
for subscriptions over `h2`/`http/1.1` (the gateway's `/subscribe`
|
||||
endpoint uses the same SSE framing)
|
||||
- [ADR-038](038-http3-and-webtransport-as-first-class.md) — the
|
||||
WebTransport streaming path (the gateway's `/subscribe` is the
|
||||
`h2`/`http/1.1` path; WebTransport is native)
|
||||
- [ADR-044](044-defer-webtransport-browsers-use-websocket.md) —
|
||||
WebSocket is the v1 browser bidirectional path; `h3`/WebTransport
|
||||
deferred (the gateway's `/subscribe` is the `h2`/`http/1.1` SSE path;
|
||||
the WS path is the native call-protocol session). ADR-038 is
|
||||
superseded by ADR-044.
|
||||
- [ADR-041](041-mcp-tool-gateway-pattern.md) — the sibling gateway
|
||||
pattern for `to_mcp` (4 tools; `subscribe` excluded because MCP tool
|
||||
calls are request/response)
|
||||
|
||||
Reference in New Issue
Block a user