diff options
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/federation/upgrades.md | 43 | ||||
| -rw-r--r-- | docs/guides/federation/watching.md | 4 | ||||
| -rw-r--r-- | docs/guides/federation/writing-and-reading.md | 5 |
3 files changed, 43 insertions, 9 deletions
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index 0a1a094..55dd921 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -15,7 +15,9 @@ the same Automerge on every node, and one with another rejoins instead of switch 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. +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 @@ -61,7 +63,22 @@ adds is refused everywhere until a version names it. ``` and the revision of the current version, in `GET /events/counts` - (`.version.revision.named`). + (`.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: @@ -74,8 +91,9 @@ adds is refused everywhere until a version names it. # 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 + 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: @@ -90,10 +108,19 @@ adds is refused everywhere until a version names it. --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. + 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`, diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md index da4a93f..9db3399 100644 --- a/docs/guides/federation/watching.md +++ b/docs/guides/federation/watching.md @@ -25,6 +25,10 @@ store, through its API and its log. is worth a look at what passed and who voted for it. * **The members** (`members` in `GET /events/counts`): a node of your party missing there syncs with nobody. +* **What the nodes run** (`knows` of each party in `GET /events/counts`): the wire + versions each node speaks and the newest revision it knows, as far as the node heard + from it: the nodes still to upgrade before a revision passes + ([`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)). * **Events beyond the checkpoint** (`taken` in `GET /events`): what a move to a checkpoint would let nodes forget; a node voting by itself proposes one at a count you set ([`voting-by-itself.md`](voting-by-itself.md)). diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md index 057aad7..d45bf0d 100644 --- a/docs/guides/federation/writing-and-reading.md +++ b/docs/guides/federation/writing-and-reading.md @@ -97,7 +97,10 @@ Votes and proposals aren't signed again: their version is behind. `GET /events/counts` is what counts, as the node reads it now: * `version`: the current version, its `number`, its `hash`, and the version itself; -* `parties`: each party's `keys` and `nodes`, as they count; +* `parties`: each party's `keys` and `nodes`, as they count, and of those nodes what + each said it speaks and knows (`knows`: the wire versions, the newest revision; null + where the node heard nothing from it), for upgrades + ([`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)); * `values`: each place holding a value, with it; * `members`: each node of the swarm, with its party, `[node, party]`; * `proposals`: the proposals on the current version, by hash, each with the events |
