docs(http): add ADR-040 WebTransport ALPN-stream-proxy and reframe OQ-38
The 'WebTransport proxy' concept was conflating two distinct things; this pass separates them: 1. In-process ALPN-stream-proxy (ADR-040, in alknet-http): the h3 handler hands a WebTransport stream to another ALPN handler (SshAdapter, GitAdapter, etc.) as a Connection, so a browser with a WASM parser can reach any ALPN service via WebTransport. Path-based routing (the CONNECT path declares the target: /alknet/ssh -> SshAdapter). HttpAdapter gains Arc<HandlerRegistry> for the lookup. The browser's WASM parser implements BiStream (ADR-007) over the WebTransport stream. SSH-over-WebTransport is HTTPS-shaped at the network layer (anti-censorship: the 'VPN-like without being a VPN' use case on a clean foundation). russh-sftp demonstrates WASM targeting is feasible; SSH is the next target. 2. Standalone relay service (OQ-38, future alknet-relay crate): a full relay - fork of iroh-relay - with WebTransport proxy fallback for NAT traversal. This is infrastructure, not a mode of the h3 handler. OQ-38 reframed to be the standalone-relay scope question (distinct from the in-process proxy now resolved by ADR-040). webtransport.md updated: three stream destinations (call protocol, ALPN-handler proxy, other sub-protocols) with path-based routing; new 'ALPN-stream-proxy' section covering the WASM client side, auth model (bearer token gates the session; protocol's own auth gates the protocol session), and the HandlerRegistry reference. README/overview ADR tables and OQ summaries updated for ADR-040.
This commit is contained in:
@@ -754,32 +754,49 @@ is a feature extension, not an unmade architecture decision.
|
||||
|
||||
## Theme: alknet-http
|
||||
|
||||
### OQ-38: WebTransport Relay-as-Proxy Scope
|
||||
### OQ-38: WebTransport Standalone Relay Service Scope
|
||||
|
||||
- **Origin**: [ADR-034](decisions/034-outgoing-only-x509-and-three-peer-roles.md)
|
||||
§5, [webtransport.md](crates/http/webtransport.md)
|
||||
- **Status**: open (scope, not deferral)
|
||||
- **Door type**: One-way (crate boundary), two-way (mechanism)
|
||||
- **Priority**: low
|
||||
- **Resolution**: A WebTransport proxy that 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) is a real feature for the browser-to-P2P-peer case. ADR-034 §5
|
||||
recorded it in the h3/WebTransport bucket; ADR-038 brought h3/
|
||||
WebTransport into scope, so this OQ is now the remaining scope
|
||||
question: does the proxy live in `alknet-http` (as a mode of the `h3`
|
||||
handler) or in a separate relay crate?
|
||||
- **Resolution**: There are two distinct "WebTransport proxy" concepts
|
||||
that must not be conflated:
|
||||
|
||||
This is a genuine scope question, not a deferral. The proxy use case
|
||||
is not yet concrete enough to decide the crate boundary — no
|
||||
deployment has asked for it yet, and the design (transport-only
|
||||
proxy, no auth-model change per ADR-034 §5) is clear but the home is
|
||||
not. The decision is made when the browser-to-P2P-peer proxy use
|
||||
case becomes concrete; until then it is tracked here, not deferred
|
||||
with "v1/later" language. The proxy does not change the auth model
|
||||
(bearer token + `PeerEntry.auth_token_hash`; proxy is transport-
|
||||
only), so it does not block any other ADR.
|
||||
- **Cross-references**: ADR-027, ADR-030, ADR-034, ADR-038,
|
||||
1. **In-process ALPN-stream-proxy (resolved, in `alknet-http`).**
|
||||
The `h3` handler hands a WebTransport stream to another ALPN
|
||||
handler (`SshAdapter`, `GitAdapter`, etc.) as a `Connection`, so
|
||||
a browser with a WASM parser can reach any ALPN service via
|
||||
WebTransport. This is resolved by
|
||||
[ADR-040](decisions/040-webtransport-alpn-stream-proxy.md) and
|
||||
lives in `alknet-http`'s `h3` handler. Not this OQ.
|
||||
|
||||
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
|
||||
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?
|
||||
|
||||
This is a genuine scope question, not a deferral. The relay use case
|
||||
is not yet concrete enough to commit the crate boundary — no
|
||||
deployment has asked for a standalone relay with WebTransport
|
||||
fallback yet, and the design (transport-only proxy, no auth-model
|
||||
change per ADR-034 §5) is clear but the home is not. The decision is
|
||||
made when the browser-to-P2P-peer relay use case becomes concrete;
|
||||
until then it is tracked here, not deferred with "v1/later" language.
|
||||
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)
|
||||
|
||||
### OQ-39: `to_openapi` Published-Spec Versioning
|
||||
|
||||
Reference in New Issue
Block a user