aboutsummaryrefslogtreecommitdiffstats
path: root/docs/operations.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/operations.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/operations.md')
-rw-r--r--docs/operations.md35
1 files changed, 21 insertions, 14 deletions
diff --git a/docs/operations.md b/docs/operations.md
index 0f906eb..4f3d6f2 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -125,20 +125,27 @@ continuum --version
A node upgrades by restarting with its files. What to know:
-* **The wire format.** Each change to it bumps a version byte, and nodes ignore
- messages of another version. Across such a change, upgraded nodes and the others
- don't talk: the swarm is split until every node is upgraded, both sides go on
- writing, and they merge then. Each logs it, at warn, once per peer, naming both
- versions and the node to upgrade (`Peer speaks another wire version: a newer build
- (wire version 53; this one speaks 52): upgrade this node to talk with it; ignoring its
- messages`, or of an older build, `upgrade that node`). With each handshake, a
- node says which versions it speaks, and the newest revision of the federation it knows
- (SPEAKS, outside the versions; [`peers.md`](peers.md),
- [Handshake and join](peers.md#handshake-and-join)); a build from before SPEAKS, before
- 0.0.1, logs it as another wire version, `version=0`, once of the peer, and reads the
- peer's other messages where they are of its version.
- A node speaks one version, so every change of the format is a major release; before
- 1.0.0, take every upgrade as one, and upgrade all nodes close together.
+* **The wire format.** Each change to it is a new version (the first byte of every
+ message), and a build speaks several side by side, from the oldest to the newest
+ `--version` names: it reads each, and writes to each node the newest both speak. A
+ node says which versions it speaks, and the newest revision of the federation it knows,
+ ahead of each proof of who it is and with each handshake (SPEAKS, outside the versions,
+ as are the proofs; [`peers.md`](peers.md),
+ [Handshake and join](peers.md#handshake-and-join)); it writes a node the oldest it
+ speaks until that node says. So a release whose versions meet the last one's rolls out
+ node by node, in any order: a release adds a version and keeps the older ones, and a
+ later one leaves the oldest out. A release's tag says whether it rolls out so
+ ([`development.md`](development.md), [Releasing](development.md#releasing)).
+ Nodes sharing no version don't talk: the swarm is split until every node is upgraded,
+ both sides go on writing, and they merge then. Each logs it, at warn, once per peer,
+ naming both versions and the node to upgrade (`Peer speaks another wire version: a
+ newer build (wire version 54; this one speaks 52): upgrade this node to talk with it;
+ ignoring its messages`, or of an older build, `upgrade that node`). 0.0.1 logs `Peer
+ speaks another wire version (another build); ignoring its messages`, with the peer's
+ version and its own (`ours`): upgrade the node whose version is the lower. A
+ build from before SPEAKS, before 0.0.1, logs SPEAKS as another wire version,
+ `version=0`, once of the peer, and reads the peer's other messages where they are of
+ its version.
* **Automerge.** A remake needs every node to build the same snapshot, byte for byte,
so the same Automerge version everywhere; a node with another one rejoins instead of
switching ([`remakes.md`](remakes.md), [Limits](remakes.md#limits)). Don't remake while