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
|
# 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)): one
at a time, restarted with its files. Across a change of the wire format, 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. Until
continuum's first release, take every upgrade as such a change.
Nobody runs every node of a federated swarm: each party's operators upgrade its nodes.
Agree on when, among the parties, and upgrade close together.
## 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`).
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…
```
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
can't see the party's other nodes, which its operators check. 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.
|