From 990b9f2e0fdcb398f13bb2f824c28b1893339019 Mon Sep 17 00:00:00 2001 From: tsunagi Date: Mon, 21 Sep 2026 19:57:27 +0100 Subject: [PATCH] Describe the layers as they now stand The module table still had the plugin inside the core and no mention of the overlay or the DNS view, and the stale path in the testing notes pointed at a directory that had moved. Co-Authored-By: Claude Opus 5 (1M context) --- docs/architecture.md | 23 +++++++++++++++++++---- docs/testing.md | 2 +- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 67456bb..0f900a8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -47,13 +47,28 @@ and the agent stays manageable. | `storage` | mandatory state and the separately recoverable cache | | `state` | signed records that outlive a session, merged between replicas | | `dataplane::transport` | authenticated datagram links to peers; where reachability lives | -| `dataplane` | the contract IP plugins implement, plus the WireGuard plugin | +| `dataplane` | the contract a protocol implements, and nothing else | +| `overlay` | the one interface an agent owns: provisioning, the TUN, whose packet is whose | +| `dns` | the DNS view of a network, and telling the system resolver about it | + +And in crates of their own: + +| crate | responsibility | +|---|---| +| `tsunagi-wg-quic` | the `wg-quic` protocol: its keys, its announcement, its tunnels | +| `tsunagi-cli` | the command line agent: the only place that owns a runtime, a logger and signals | + +A protocol is a separate crate so the boundary is the compiler's to enforce, +and so it can carry its own version. That version is not what peers compare: +they compare the *wire* version, which moves only when the bytes do, so two +peers on different releases keep working. Abstractions exist only where something is really substituted or really needs isolating for tests: `NetworkDiscovery`, `IpPlugin`, `PacketTransport` / -`PacketLink` (so the data plane's carrier can change), and `TunFactory` (which -is what lets the whole data plane be tested without privileges). Everything -else is a concrete type. +`PacketLink` (so a protocol's carrier can change), `TunFactory` (which is what +lets the whole data plane be tested without privileges), `InterfaceProvisioner` +and `DnsPublisher` (which are where the platforms differ). Everything else is a +concrete type. ## Runtime shape diff --git a/docs/testing.md b/docs/testing.md index 763c6bb..79d7152 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -72,7 +72,7 @@ Unit tests in `crates/tsunagi/src/proto/handshake.rs` cover the transcript const itself: role separation, channel binding, identity and network binding, unambiguous encoding, and rejection under the wrong key. -Unit tests in `crates/tsunagi/src/dataplane/wireguard/` cover key clamping against the RFC +Unit tests in `crates/tsunagi-wg-quic/src/` cover key clamping against the RFC 7748 vector, overlay derivation, announcement validation including the address-hijack attempt, interface naming, and IP header parsing against truncated and nonsense input.