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:
@@ -774,17 +774,19 @@ is a feature extension, not an unmade architecture decision.
|
||||
|
||||
2. **Standalone relay service (this OQ).** A full relay — a fork of
|
||||
`iroh-relay` — that provides NAT traversal infrastructure with
|
||||
WebTransport-based proxy as a fallback alongside websocket. This
|
||||
WebTransport-based proxy as a fallback alongside WebSocket. This
|
||||
is a separate service, not a mode of the `h3` handler: it
|
||||
terminates the browser's WebTransport connection and forwards
|
||||
encrypted traffic to a P2P hub's Ed25519 endpoint (so the hub need
|
||||
not expose its own public X.509 cert). ADR-034 §5 recorded it in
|
||||
the h3/WebTransport bucket; ADR-038 brought h3/WebTransport into
|
||||
scope; ADR-040 resolved the in-process proxy. This OQ is the
|
||||
remaining scope question: does the standalone relay live in a
|
||||
future `alknet-relay` crate (a fork of `iroh-relay` with
|
||||
WebTransport proxy fallback) or is it out of scope for the
|
||||
current alknet work?
|
||||
scope (later superseded by [ADR-044](decisions/044-defer-webtransport-browsers-use-websocket.md),
|
||||
which deferred h3/WebTransport as a scope decision — the browser
|
||||
bidirectional path uses WebSocket); ADR-040 resolved the in-process
|
||||
proxy (now parked per ADR-044). This OQ is the remaining scope
|
||||
question: does the standalone relay live in a future `alknet-relay`
|
||||
crate (a fork of `iroh-relay` with WebTransport proxy fallback) or
|
||||
is it out of scope for the current alknet work?
|
||||
|
||||
This is a genuine scope question, not a deferral. The relay use case
|
||||
is not yet concrete enough to commit the crate boundary — no
|
||||
@@ -796,8 +798,8 @@ is a feature extension, not an unmade architecture decision.
|
||||
The relay does not change the auth model (bearer token +
|
||||
`PeerEntry.auth_token_hash`; relay is transport-only), so it does not
|
||||
block any other ADR.
|
||||
- **Cross-references**: ADR-027, ADR-030, ADR-034, ADR-038, ADR-040,
|
||||
[webtransport.md](crates/http/webtransport.md)
|
||||
- **Cross-references**: ADR-027, ADR-030, ADR-034, ADR-038 (superseded),
|
||||
ADR-040 (parked), ADR-044, [webtransport.md](crates/http/webtransport.md)
|
||||
|
||||
### OQ-39: `to_openapi` Published-Spec Versioning
|
||||
|
||||
|
||||
Reference in New Issue
Block a user