aboutsummaryrefslogtreecommitdiffstats
path: root/docs/architecture.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 17:44:03 +0000
committertv <tv@krebsco.de>2026-11-19 19:26:01 +0100
commit59e889254b1fda2dcc8e3e6d596635d1b77f589f (patch)
tree2412dd262e7ae729498eb3300912395b601cd0b6 /docs/architecture.md
parent180aba9ff89a4a294e284aa281d96adbcfe1b85b (diff)
transport: wire versions spoken side by side
A build speaks wire versions OLDEST to VERSION and writes each node the newest both speak (wire::choose), as the node's SPEAKS says; the oldest until it says. The identity layer keeps that per address (Book::speaks): a SPEAKS from an address sets it for the address, and for every address of the node proven there, and a new address of a node takes it over. Paths encodes each message for an address in its version (Transport::encode_in; Transport::encode is the newest). So that two nodes know what the other speaks once they have proven themselves to each other, before any other message goes between them, a SPEAKS goes ahead of every WHO and ME, and WHO and ME are read in every version from 52 on (wire::PROOFS): their tags and layout never change. Without that, a node whose oldest version is past the other's couldn't read its proofs, and the two would never get to the handshake that says what each speaks. A SPEAKS naming no version this build speaks is logged as a message of another version is, naming the node to upgrade, the versions as ranges. A 0.0.1 node takes a SPEAKS from an address not yet proven for any other message from there: it drops it, and asks WHO. This build speaks 52 alone, so nothing it sends changes but the SPEAKS ahead of the proofs. A release adding a version encodes and decodes the older ones from their own, frozen, types.
Diffstat (limited to 'docs/architecture.md')
-rw-r--r--docs/architecture.md17
1 files changed, 9 insertions, 8 deletions
diff --git a/docs/architecture.md b/docs/architecture.md
index f70f132..f462fe7 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -79,9 +79,9 @@ it switched to the right document without trusting anyone.
**[`transport/`](../src/transport/)** — [`mod.rs`](../src/transport/mod.rs) defines the message types (HELLO, HELLO_REPLY, sync
envelope, STATUS/STATUS_REPLY, PING/PONG, blob messages, PROBE/PROBE_REPLY, REFUSALS, SPEAKS) and the `Transport` trait;
-[`wire.rs`](../src/transport/wire.rs) is the wire format (a version byte, bumped with every change to the format,
-and a kind byte, then the message in MessagePack, derived from the types in [`mod.rs`](../src/transport/mod.rs)
-with codecs for hashes and IDs; SPEAKS, outside the versions, is laid out as no build changes); [`mycelium/`](../src/transport/mycelium/) (with the `mycelium` feature) is the REST
+[`wire.rs`](../src/transport/wire.rs) is the wire format (a version byte, a new version with every change to the format,
+several spoken side by side, and a kind byte, then the message in MessagePack, derived from the types in [`mod.rs`](../src/transport/mod.rs)
+with codecs for hashes and IDs; SPEAKS, WHO and ME, outside the versions, are laid out as no build changes); [`mycelium/`](../src/transport/mycelium/) (with the `mycelium` feature) is the REST
client (polling inbox, outbound POST, one topic, `continuum`, for every message), with
[`mycelium/daemon.rs`](../src/transport/mycelium/daemon.rs) running the daemon (an external one by its URL, or one it starts
and supervises); [`libp2p/`](../src/transport/libp2p/) (with the `libp2p` feature) is libp2p as a transport,
@@ -288,11 +288,12 @@ places that rely on it.
* **Conflicts are errors; overrides are named.** A contradiction in the configuration
or at the API refuses with a message that names the `force` value that would
override it, in one camelCase vocabulary everywhere.
-* **Builds tell each other apart.** Every change of the wire format bumps its version,
- and a node ignores messages of another version instead of misreading them: across a
- change, the swarm is split until every node runs it, and merges then. A release's
- version says whether it is such a change ([`operations.md`](operations.md),
- [Upgrading](operations.md#upgrading)).
+* **Builds tell each other apart.** Every change of the wire format is a new version; a
+ build speaks several side by side and writes each node the newest both speak, and a
+ node ignores messages of a version it doesn't speak instead of misreading them. Where
+ two releases share none, the swarm is split until every node runs the later, and
+ merges then. A release's version says whether it is such a change
+ ([`operations.md`](operations.md), [Upgrading](operations.md#upgrading)).
## Where the complexity sits