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:
2026-06-29 07:56:35 +00:00
parent ab47dac4ad
commit 398e3d512d
6 changed files with 444 additions and 60 deletions

View File

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