docs(arch): endpoint types and entry points (ADR-086) — resolves OQ-62
Name the three-endpoint-type model (web/native/iroh) and the entry-point vs. endpoint ALPN distinction. This untangles the hub/endpoint/ALPN-config confusion that OQ-62 hinted at: - A hub composes a SUBSET of three endpoint types (web, native, iroh), each with its own identity model, auth model, and transport(s). A full hub runs all three; a minimal hub runs iroh alone (no public IP required). The first real use case is web + native. Corrects the hub README's 'must support TCP+TLS and QUIC' framing. - ALPNs split into entry points (accepted without identity — h2, http/1.1, future alknet/register) and endpoints (identity required before dispatch — alknet/channels, alknet/call, alknet/ssh). This resolves OQ-62: split ALPN lists by endpoint type (Option B), because each endpoint type serves a different client class with different negotiable ALPNs. The assembly-layer wiring pattern is now guessable. - Foundational handlers are two categories, not one: channels data-channel ALPNs (tunnel, socks5, fs, sftp — gated by channels, not in any TLS ALPN list) vs. SSH (an endpoint ALPN that wraps channels inside it, RFC 7250 keys, legacy compat, comes later). Files OQ-65 (WebSocket carrying channels — the browser story update) filed as a one-way-door question, open. ADR-048 is not superseded; OQ-65 may extend it. The web config advertises alknet/channels by default so the hub is ready if OQ-65 resolves to 'WebSocket carries channels.'
This commit is contained in:
1 parent
7610ec1f31
commit
7d9b1ebad9
9 files changed
+800
-129
No files matched your search
@@ -106,15 +106,25 @@ ALPN-list construction is the **assembly layer's** responsibility, not
|
||||
the endpoint's. After ADR-083, the endpoint takes no TLS config and
|
||||
builds no transports — the assembly layer reads `registry.alpn_strings()`
|
||||
and passes the appropriate ALPN list to each `TlsServerConfig::new()`
|
||||
(see [`crates/tls/README.md`](../tls/README.md)). For a single-config
|
||||
deployment (one identity, one set of ALPNs), all transports advertise
|
||||
the same set. For a two-config hub (raw key + X.509/ACME — see OQ-62),
|
||||
the assembly layer may pass different lists to each config; that split
|
||||
is a hub-assembly-layer concern, not an endpoint concern.
|
||||
(see [`crates/tls/README.md`](../tls/README.md)).
|
||||
|
||||
The ALPN list is **split by endpoint type** (ADR-086 §3, resolving
|
||||
OQ-62): each `TlsServerConfig` advertises only the ALPNs its endpoint
|
||||
type's client class can negotiate. The native config (raw key) gets
|
||||
`alknet/channels`, `alknet/call`, `alknet/ssh` (future); the web config
|
||||
(X.509/ACME) gets `h2`, `http/1.1`, `alknet/channels` (for
|
||||
WebSocket-carrying-channels, OQ-65); the iroh builder gets
|
||||
`alknet/channels`, `alknet/call`. The distinction is between
|
||||
**entry points** (ALPNs accepted without identity — `h2`/`http/1.1`,
|
||||
future `alknet/register`) and **endpoints** (ALPNs requiring identity —
|
||||
`alknet/channels`, `alknet/call`, `alknet/ssh`). See
|
||||
[ADR-086](../../decisions/086-endpoint-types-and-entry-points.md) for
|
||||
the full model and ALPN-list table.
|
||||
|
||||
The iroh endpoint's ALPN list is set via `iroh::Endpoint::builder().alpns()`
|
||||
by the assembly layer at construction time, from the same
|
||||
`registry.alpn_strings()` source.
|
||||
`registry.alpn_strings()` source (filtered to the iroh endpoint type's
|
||||
ALPNs).
|
||||
|
||||
## Accept Loops
|
||||
|
||||
@@ -370,6 +380,7 @@ Non-fatal errors within a handler. See [core-types.md](core-types.md) for detail
|
||||
| Stealth mode = HTTP handler on standard ALPNs | [ADR-010](../../decisions/010-alpn-router-and-endpoint.md) | Decoy via ALPN routing, not byte-peek |
|
||||
| Network identity ≠ auth identity | [ADR-010](../../decisions/010-alpn-router-and-endpoint.md) | TLS cert/NodeId = network, SSH key/token = auth |
|
||||
| Handler panics isolated | [ADR-010](../../decisions/010-alpn-router-and-endpoint.md) | tokio task isolation, connection closes |
|
||||
| Endpoint types and entry points | [ADR-086](../../decisions/086-endpoint-types-and-entry-points.md) | Three endpoint types (web/native/iroh); entry-point vs. endpoint ALPN distinction; split ALPN lists per endpoint type |
|
||||
|
||||
## Open Questions
|
||||
|
||||
|
||||
Reference in new issue
Block a user