Upgrades and the federation's revisions
Upgrading the continuum a federated swarm's nodes run, what the federation's number and
its revision in each version say, and moving to a later revision. The rules are the
design's (federation.md,
Changing the federation).
Upgrading continuum
A node of a federated swarm upgrades as any node does
(operations.md, Upgrading),
restarted with its files, and a release's version says how: a patch or a minor release one
node at a time, a major one every node close together. Across a change of the wire
format, a major one, upgraded nodes and the others don't talk, and the swarm is split
until all are upgraded; a remake needs the same Automerge on every node, and one with
another rejoins instead of switching. Before 1.0.0, take every upgrade as a major one.
Nobody runs every node of a federated swarm: each party's operators upgrade its nodes. A
patch or minor release each party takes when it likes; for a major one, agree on when,
among the parties, and upgrade close together. Which wire versions each node the parties
list speaks, as far as a node heard from it, shows in GET /events/counts (knows,
below: wire, the oldest and the newest).
The federation's number and its revision
What every node must agree on, byte for byte, is named by the federation's number,
which every version gives ("federation": 1), and its revision: the rules, how an event,
a version and a checkpoint are spelled, signed and judged, what the events read as, and,
on Automerge, what the document holds, what a change writes, the genesis change built from
the root, the snapshot, and the Automerge version, whose encoding fixes a change's hash.
Their bytes are fixed by vectors that the tests check (federation::vectors).
There is one federation, 1. A node knows it alone: a version naming another is none to
it. Where one passes, the node stops at the version event writing it, taking nothing and
refusing nothing, until it runs a continuum that knows it, or its operator has it drop
that event (when-things-go-wrong.md,
A node stopped). A proposal naming another is
taken as a proposal, and a party's client backs none.
What is judged at an event's history changes by a revision of federation 1, which a
version names by its ID ("revision": "<ID>"); a version naming none follows the base
revision, ecdsa-sha2-nistp256 keys beside Ed25519 ones among it. Each later revision
adds a feature to the one before; federation.md lists them
(Changing the federation). A node that
doesn't know the revision a version names reads it as it reads one of another federation:
none, and it stops at a version event writing it. What a revision adds is taken only under
a version naming it, which two thirds pass, so no party uses it early.
What no history judges, the document, a change and the snapshot, no version names: a change there splits the swarm until every node runs it (above).
Moving to a revision
First every node runs a continuum that knows the revision, then the parties pass a version naming it. Restarting the nodes changes nothing in the swarm: what the revision adds is refused everywhere until a version names it.
Upgrade. Each party's operators restart every node of the party on such a continuum. A node says which revisions it knows:
curl -s -u tv:secret localhost:3000/events | jq -r '.revisions[].named' # the base revision # revision 1 (merge-events)and the revision of the current version, in
GET /events/counts(.version.revision.named). There too, of each node the parties list, the newest revision it said it knows (knows;peers.md, Handshake and join), as far as this node heard from it: the nodes still to upgrade, every party's.curl -s -u tv:secret localhost:3000/events/counts | jq -r '.parties | to_entries[] | .key as $party | .value.knows | to_entries[] | "\($party) \(.key): \(.value.revision.named // "said nothing")"' # lass continuum:9c07…: the base revision # tv continuum:5be1…: revision 1 (merge-events) # tv continuum:77d3…: said nothingA node says nothing on a build from before it said this, or where this node didn't hear from it since it started: each says it with each handshake.
Propose. A party begins the next version following it, by the feature it adds;
nextsays so where its node knows a later revision than the current version's:continuum-party --node http://tv:secret@localhost:3000 next --revision merge-events \ > next.json continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ --record tv.record propose next.json # proposal 5e81…Where nodes the parties list aren't known to know the revision,
nextwarns, and names them. It may already hold what the revision adds to a version: a version is read by the revision it names. Its proposal and the votes on it are judged under the current version, and what the revision adds to events counts from the version after.Vote. Each party backs it once every node of the party knows the revision:
continuum-party --node http://tv:secret@localhost:3000 proposals # 5e81…: can still pass; true: tv; false: nobody # changes: "1f4c…" -> "8a20…" # number: 4 -> 5 # revision: the base revision -> revision 1 (merge-events), 6c1d… continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ --record tv.record vote 5e81… yesThe client backs it only where its node knows the revision, and says so otherwise. It backs it where other nodes, of any party, aren't known to know it, and warns, naming them and what each said (
knows, above): once it passes, those stop at it till upgraded.Warning: these nodes aren't known to know revision 1 (merge-events), as far as the node heard from them; once a version of it passes, each stops at it till upgraded: tv: continuum:77d3… said nothing: a build from before SPEAKS, or not heard fromA node voting by itself backs no version changing the revision: vote on it by hand, through that node. A party not ready leaves it be, or votes
falseto end it.After. Once two thirds passed it, what the revision adds counts from that version on. A node that doesn't know it stops at that version (
stoppedinGET /events,when-things-go-wrong.md, A node stopped), takes nothing and votes nothing until upgraded, and reads its store anew once restarted on a continuum that knows it.
