docs(arch): workspace scope correction (ADR-085) + tls spec review fixes
ADR-085 records the actual workspace scope: the mono-repo is the core networking toolkit (substrate: core, tls, call, channels; deployment shapes: hub, worker; foundational handlers: tty, http, ssh, tunnel, socks5, fs, sftp; vault). Consumer repos (docker, agent) are separate repos depending on the published core crates. The overview's crate graph had been describing the wrong scope since ADR-003 — a flat ~12-crate workspace including DNS/messaging/NAPI while omitting channels, hub, worker, and tls. This stale scope was a causal factor in the 'assembly layer' hedging pattern: when the overview implies everything lives in one repo but the architecture needs a hub/worker composition layer not in the graph, the gap gets filled with 'assembly layer' as an escape hatch. The overview is rewritten to match the real boundary. TLS spec review fixes (from architecture review): - C3: hub/worker/hub-worker terminology pointers (tls README + endpoint.md) - W1: server-only statement + OQ-64 (client-side TLS helper, deferred) - W2: ACME task lifecycle semantics (returns immediately, no first-cert await) - W3: remove stale EndpointError::TlsConfig variant - W4: update stale ALPN section for two-config hub - W5: add alknet-tls to hub dep graph (assembly-layer dep) - W6: trim inline rationale -> point to ADR-084 - W7: ADR-084 status dependency note New open questions: - OQ-62: ALPN list sharing for two-config hub (open, high) - OQ-63: TlsError shape (open, high) - OQ-64: client-side TLS helper (deferred, blocked on OQ-55)
This commit is contained in:
1 parent
34729c7846
commit
7610ec1f31
11 files changed
+761
-82
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-07-14
|
||||
last_updated: 2026-07-15
|
||||
---
|
||||
|
||||
# Endpoint
|
||||
@@ -46,6 +46,14 @@ A node can be reachable through different paths depending on its network context
|
||||
|
||||
These are not interchangeable transports — they are **complementary connectivity modes**. A node behind NAT that also has a public IP can use both simultaneously. Both produce QUIC connections that dispatch through the same `HandlerRegistry` by ALPN string.
|
||||
|
||||
> **Terminology — hub, worker, hub-worker.** A *hub* accepts inbound
|
||||
> connections from workers and browsers (see
|
||||
> [`crates/hub/README.md`](../hub/README.md) for the hub-and-spoke
|
||||
> topology). A *worker* dials out to a hub. A *hub-worker* does both. A
|
||||
> *pure worker* has no inbound endpoints. These terms come from ADR-029
|
||||
> / ADR-034; "assembly layer" (ADR-014) is the deployment binary that
|
||||
> wires crates — in practice, today, usually a hub or hub-worker.
|
||||
|
||||
### TCP+TLS is a first-class owned transport
|
||||
|
||||
TCP+TLS is a listener transport, same shape as quinn and iroh. The
|
||||
@@ -94,7 +102,19 @@ Registration is static at startup (see [OQ-04](../../open-questions.md)). The CL
|
||||
|
||||
### ALPN strings in TLS ServerConfig and iroh endpoint
|
||||
|
||||
The quinn endpoint's `rustls::ServerConfig` ALPN list is set from `registry.alpn_strings()` at construction time. The iroh endpoint's ALPN list is similarly derived. Both connection sources advertise the same set of ALPNs.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Accept Loops
|
||||
|
||||
@@ -301,11 +321,18 @@ Fatal errors that prevent the endpoint from starting or continuing.
|
||||
```rust
|
||||
pub enum EndpointError {
|
||||
BindFailed(io::Error),
|
||||
TlsConfig(io::Error),
|
||||
HandlerNotFound(Vec<u8>), // ALPN string with no registered handler
|
||||
}
|
||||
```
|
||||
|
||||
After ADR-083, the endpoint takes no TLS config and constructs no
|
||||
transports — TLS config errors now surface as `TlsError` in
|
||||
`alknet-tls` / the assembly layer (see
|
||||
[`crates/tls/README.md`](../tls/README.md) and OQ-62), not as
|
||||
`EndpointError`. The `TlsConfig(io::Error)` variant that existed when
|
||||
the endpoint built TLS internally is removed. `BindFailed` covers
|
||||
listener bind failures (quinn, iroh, TCP+TLS `TcpListener::bind`).
|
||||
|
||||
### HandlerError
|
||||
|
||||
Non-fatal errors within a handler. See [core-types.md](core-types.md) for details.
|
||||
|
||||
Reference in new issue
Block a user