aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
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
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')
-rw-r--r--docs/guides/federation/upgrades.md43
-rw-r--r--docs/guides/federation/watching.md4
-rw-r--r--docs/guides/federation/writing-and-reading.md5
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