diff options
| author | tv <tv@krebsco.de> | 2026-11-19 17:44:03 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 19:26:01 +0100 |
| commit | 59e889254b1fda2dcc8e3e6d596635d1b77f589f (patch) | |
| tree | 2412dd262e7ae729498eb3300912395b601cd0b6 /docs/architecture.md | |
| parent | 180aba9ff89a4a294e284aa281d96adbcfe1b85b (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.md | 17 |
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 |
