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:
2026-06-30 05:55:55 +00:00
parent 78b226d31b
commit 125cb49cc4
13 changed files with 769 additions and 176 deletions

View File

@@ -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)