tsunagi/docs/architecture.md

Architecture

Scope and non-scope are in ../README.md. Rules for changing the code are in ../AGENTS.md. The wire format is in protocol.md.

Two independent planes

Control plane. iroh provides connections between agents and carries control messages. On top of it, this crate's protocol handles membership authentication, participant announcements, capability exchange and — later — state synchronisation and delivery of IP-plugin data.

Data plane. Separate plugins create IP connectivity. WireGuard is the first planned one; none exists yet. Plugin keys, configuration and lifecycle are separate from iroh identity and from the network secret. The core moves an opaque, bounded payload and never parses it.

Only control messages travel over iroh. User IP traffic is not tunnelled through it.

A data plane failure never stops the daemon: the control plane keeps running and the agent stays manageable.

Module responsibilities

component	responsibility
identity	persistent device identity; network space parameters; derived identifiers and keys
discovery	obtaining and publishing address hints — not authentication, not state transfer
net	iroh connections, addresses, paths, statistics, connection events
proto	message format, handshake, membership proof, protocol limits
agent	agent and per-network lifecycle, reconnect, in-process message routing
storage	mandatory state and the separately recoverable cache
dataplane	the minimal contract future IP plugins implement

Abstractions exist only where something is really substituted or really needs isolating for tests: NetworkDiscovery and IpPlugin. Everything else is a concrete type.

Runtime shape

Agent                                   one persistent identity, one iroh endpoint,
 ├── EndpointAdapter                     one state directory, N networks
 ├── Storage  (state.sqlite + cache.sqlite + ownership lock)
 ├── accept loop task  ── weak ref, exits when the agent is dropped
 └── NetworkRuntime per NetworkId
      ├── discovery + dial loop (bounded concurrency, backoff with jitter)
      └── Session per peer
           ├── reader task  ── frames in  -> SessionEvent
           └── writer task  ── encoded frames out

The library starts no runtime, installs no logging subscriber, handles no signals, never forks and never calls process::exit. Startup (Agent::spawn) and shutdown (Agent::shutdown) are explicit, background tasks are joined on shutdown, and there is no global mutable state — several independent agents run in one test process.

Agent::spawn returns as soon as the local agent is ready. It never waits for other participants or for a relay.

Concurrency decisions

• The network runtime is a single task owning its own state, driven by a command channel plus event channels. No shared locks on the hot path.
• A session is two tasks, because a partially consumed stream read cannot be cancelled safely. The writer's frame write is cancellable, so shutdown never waits on a peer that stopped reading.
• Outbound queues are bounded. A full queue fails that send instead of stalling every other peer in the network.
• Envelopes are encoded in the runtime, not in the writer, so the exact number of control bytes queued is known and reported rather than guessed.
• Simultaneous mutual dials are resolved by a deterministic rule both sides compute identically: keep the session whose initiator has the smaller endpoint id.

Storage

Two physically separate SQLite files with their own schema versions and migrations, no ORM. All access runs on the blocking pool; no database lock is held across a network await. Files are owner-only where the platform supports it. One state directory belongs to one live agent, enforced by an advisory OS file lock — an existence check is not enough, because a crashed process must not block a restart and two agents starting at once must not both win. A clean shutdown releases the lock immediately.

Observability

AgentStatus separates the three levels deliberately:

• endpoint — bound sockets, observed addresses, cache health;
• logical network — dial attempts and failures, handshake failures, sessions established, disconnects, control message and byte counts, protocol violations, plugin errors;
• connection — verified paths, selected path, direct/relay, RTT, QUIC counters.

Values that cannot honestly be attributed to one network stay at the endpoint level. A value iroh does not report is None.

An iroh address is an address for iroh. It is not assumed usable by any other protocol; a future WireGuard plugin gathers its own reachability data and ships it through the control plane as an opaque announcement.

Relays

Standard iroh behaviour, including relay fallback, is allowed for the control plane via TransportPolicy::N0Defaults. Public relays are fine for development and carry no availability guarantee. The default is LocalOnly, and the test suite never depends on a relay.

Multiple networks

Every session, message, task and status carries an explicit NetworkId. Being authenticated in network A grants nothing in network B, even over a shared physical connection; each network gets its own sessions. Deactivating one network does not close the agent or disturb the others.

Local deactivation is distinct from a future signed revocation of membership or of a name. Nothing here is an irreversible global flag.

Planned, not built

Signed per-author state, snapshots, revocations and merge rules are described in sync-model.md. The module boundaries above are shaped so that adding them does not require rewriting the core. The data plane locking policy is likewise deliberately left coarse for now; the conflict domain is described separately so it can later be narrowed to a network, peer, name or plugin without touching the core.