aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/upgrades.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 13:34:24 +0000
committertv <tv@krebsco.de>2026-11-19 14:39:54 +0100
commit9164ebfe9a4014cbbaaaff90c5a1d722e39457fd (patch)
tree9a45156bd4919054939d12c97a19672e92e07b98 /docs/guides/federation/upgrades.md
parent7a5aeb02024ddff71ba60f40913555cd21a633ad (diff)
federation: which nodes know a revision, in counts and before a `true`
`GET /events/counts` says, of each node a party lists, what it said it speaks and knows (`knows`, by node ID): the wire versions, the oldest and the newest, and the newest revision of the federation it knows, by number and ID and as people read it, its number null where this continuum doesn't know it; null where it said nothing, a build from before SPEAKS or one the node didn't hear from; the node's own as it is. So the nodes still to upgrade before a revision passes show, every party's, where before a party's operators could check only their own. A party's client, backing a proposal that moves to another revision, warns of every node of any party not known to know it, a line a party naming each and what it said: once it passes, those stop at it till upgraded. `next` warns alike, of the revision it moves to, or of the later one it suggests. A warning, not a refusal: what a node heard is no proof, and a node not heard from may well be upgraded.
Diffstat (limited to 'docs/guides/federation/upgrades.md')
-rw-r--r--docs/guides/federation/upgrades.md43
1 files changed, 35 insertions, 8 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`,