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:
@@ -2,7 +2,24 @@
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
**Superseded by [ADR-044](044-defer-webtransport-browsers-use-websocket.md).**
|
||||
|
||||
This ADR's *correction* of the "two-way-door-as-deferral" anti-pattern
|
||||
(ADR-009 §"What this framework is NOT") stands as a document — the
|
||||
anti-pattern is real, and the reasoning that rejected deferral-as-hedging is
|
||||
correct. However, this ADR's *specific decision* — that `h3`/WebTransport is
|
||||
in scope now, not deferred — is reversed by ADR-044. ADR-044 is a
|
||||
**scope** decision (permitted by ADR-009: "not needed for the current
|
||||
scope"), not a hedging deferral: the browser bidirectional path uses
|
||||
WebSocket (RFC 6455, mature, native axum support), the ALPN-stream-proxy
|
||||
(ADR-040) is the speculative use case whose deferral is the reversal
|
||||
trigger, and the draft-standard + experimental-deps surface area is not
|
||||
justified by a concrete v1 requirement.
|
||||
|
||||
ADR-040 and ADR-043 are **parked, not superseded** — their designs revive
|
||||
unchanged when WebTransport revives. See ADR-044 for the full scope rationale,
|
||||
the reversal trigger, and the research note on the wtransport-vs-hyperium
|
||||
dependency choice (recorded for the revival so it is not re-derived).
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
Reference in New Issue
Block a user