aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/upgrades.md
blob: f6964a6f70fc76e1388feca3fa3485a702d859da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# 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`](../../federation.md),
[Changing the federation](../../federation.md#changing-the-federation)).

## Upgrading continuum

A node of a federated swarm upgrades as any node does
([`operations.md`](../../operations.md), [Upgrading](../../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`](when-things-go-wrong.md),
[A node stopped](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](../../federation.md#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.

1. **Upgrade.** Each party's operators restart every node of the party on such a
   continuum. A node says which revisions it knows:

   ```sh
   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`](../../peers.md),
   [Handshake and join](../../peers.md#handshake-and-join)), as far as this node heard
   from it: the nodes still to upgrade, every party's.

   ```sh
   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 nothing
   ```

   A 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.

2. **Propose.** A party begins the next version following it, by the feature it adds;
   `next` says so where its node knows a later revision than the current version's:

   ```sh
   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, `next` warns, 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.

3. **Vote.** Each party backs it once every node of the party knows the revision:

   ```sh
   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… yes
   ```

   The 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 from
   ```

   A 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 `false` to end it.

4. **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 (`stopped` in `GET /events`,
   [`when-things-go-wrong.md`](when-things-go-wrong.md),
   [A node stopped](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.