tsunagiandClaude Opus 5
ea7aaa2b69
The first IP plugin, built on the data plane boundary the core already had. Plugin: - one X25519 key per network in the plugin's own wireguard.sqlite, separate from the iroh identity and from the network secret; a damaged store is an error, never a silently regenerated identity - deterministic IPv6 ULA overlay: every member derives the same /64 from the network id and its own /128 from its WireGuard public key, so no coordinator allocates addresses - AllowedIPs are derived locally, never taken from a peer's announcement, so a member cannot claim another member's overlay address; a mismatched claim is rejected - bounded, versioned, validated announcement carried as the existing opaque capability payload, which the core still never parses - each agent builds its own full-mesh configuration (N-1 peers) and reconciles on every change and on a timer, repairing drift - WireguardBackend abstraction: RecordingBackend in memory, and WgToolBackend driving real wg/ip on Linux, split into a pure planner plus parsers and a thin executor so everything interesting is testable without root Core, three generic additions the plugin needed: - IpPlugin::on_network_activated, so per-network state is ready before peers - PluginContext for re-announcements and error reports from plugin tasks, with errors counted by the owning network runtime - IpPlugin::shutdown, awaited with a grace period, so system objects go away 94 tests pass offline with no privileges: 35 new WireGuard unit tests and 12 integration tests over real iroh connections. The real wg/ip backend needs root and is behind --ignored in tests/wireguard_system.rs; it was not run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
89 lines
3.9 KiB
Markdown
89 lines
3.9 KiB
Markdown
# Planned state synchronisation
|
|
|
|
**Nothing in this document is implemented.** The proof of concept exchanges
|
|
hostname and capability announcements over live sessions and keeps no
|
|
replicated history. That is also why WireGuard peer membership is
|
|
session-scoped today: a peer disappears from the overlay configuration when its
|
|
control session ends, because there is no agreed durable state to keep it. This file records the intended direction so the module
|
|
boundaries in [architecture.md](architecture.md) stay compatible with it, and so
|
|
nobody mistakes the current announcements for synchronisation.
|
|
|
|
There is no fake "ready CRDT" here and no snapshots that are not actually
|
|
verified.
|
|
|
|
## The problem
|
|
|
|
The network may be unstable. A participant can come back after months. So:
|
|
|
|
- no dependence on the author of a change being online;
|
|
- no dependence on acknowledgements from every participant ever seen;
|
|
- any available replica holding the signed data must be able to hand it to a
|
|
returning participant without the original author present.
|
|
|
|
## The model
|
|
|
|
**Signed self-contained state per author, merged between replicas.**
|
|
|
|
A record contains: the network, the author, the author's own retained version,
|
|
the full current content, and a signature. A change log may speed delivery up,
|
|
but recovery must never require the entire chain from the first event.
|
|
|
|
A network snapshot is a set of verifiable authored records plus the revocations
|
|
needed to interpret them. It is **not** a SQLite dump, and **not** a single
|
|
document trusted merely because the neighbour who forwarded it signed it.
|
|
|
|
## Merge rules
|
|
|
|
- A snapshot is merged into local state, never substituted for it wholesale.
|
|
- An older version never rolls back a newer known one.
|
|
- Absence from a snapshot does not mean deletion.
|
|
- Duplicates do not change the result.
|
|
- Two conflicting signed records at the same version from the same author need
|
|
explicit handling; they are not resolved by luck.
|
|
- Neither arrival order nor system clocks decide a winner.
|
|
- Compaction must not drop what is needed to stop revoked records being
|
|
resurrected.
|
|
|
|
## Hostnames
|
|
|
|
A hostname is a mutable binding to a persistent author, not an identity. A
|
|
rename must be a signed record that revokes the specific old binding and
|
|
announces the new one, ideally atomically in one record.
|
|
|
|
Turning a computer off is not a revocation of its hostname and does not remove
|
|
the participant. Revocations are not dropped merely because they are old, and
|
|
no acknowledgement from offline peers is required to keep working.
|
|
|
|
## Storage requirement this creates
|
|
|
|
When signed records land, writing the event and bumping the author's own
|
|
counter must happen in **one SQLite transaction, committed before the change is
|
|
published to the network**. SQLite gives atomic commit; use it instead of
|
|
separate, inconsistent writes. `state.sqlite` already has a schema version and
|
|
migrations for this.
|
|
|
|
## Limits to state honestly
|
|
|
|
- Data that every copy has lost is not recoverable from the secret.
|
|
- A signature proves authorship, not global freshness: a replica can be
|
|
behind, and you cannot tell from the signature alone.
|
|
- An isolated new client can end up with incomplete state and has no way to
|
|
know what it is missing.
|
|
- Anyone who knows the secret can author records, so a majority of records is
|
|
not evidence of anything.
|
|
|
|
## Future tests
|
|
|
|
These are **not implemented and must not be reported as passing**:
|
|
|
|
- snapshot merge against the rules above, including conflicting same-version
|
|
records;
|
|
- revocation propagation and resistance to resurrection after compaction;
|
|
- long network partitions and rejoin after an extended absence;
|
|
- hostname rename with atomic revoke-and-announce;
|
|
- recovery of a returning participant from a replica that is not the author;
|
|
- NAT traversal and hole punching between real hosts;
|
|
- relay fallback behaviour against a self-hosted relay;
|
|
- multi-process and multi-host deployment, as opposed to several library
|
|
instances inside one test process.
|