diff options
| author | tv <tv@krebsco.de> | 2026-11-19 04:00:12 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 05:13:38 +0100 |
| commit | 0d2467e15ec0c9c035b1074a2dd4eece6b24c599 (patch) | |
| tree | e544ce8ae1c31e9556191d3f99157b5bd61b1f14 /docs/guides/federation | |
| parent | efaf79e7fd55db2b9704ccefedde33346f874a1d (diff) | |
federation: revisions shown, named, and moved to by hand
An operator moving the federation to a revision had nothing to say which revisions a
node knows, nor which one the current version follows, and a hash where a name would do.
`GET /events` lists the revisions the node's continuum knows, each its number, its ID,
the feature it adds and what that adds, and as people read it ("revision 1
(merge-events)"); `GET /events/counts`, the current version's. `continuum-party next
--revision FEATURE` begins a version following the revision adding it, never an earlier
one than the current version's, and `next` says so where the node knows a later one.
`proposals` shows a change of revision as people read it, a revision this continuum
doesn't know so said. A client backs a version moving to a revision only where its node
knows it, and says why otherwise: once passed, a node that doesn't stops there.
The upgrades guide walks through moving to a revision: upgrade every node, propose, vote,
and what follows; the proposing guide lists `revision`, and the API's spec the rest.
Diffstat (limited to 'docs/guides/federation')
| -rw-r--r-- | docs/guides/federation/README.md | 4 | ||||
| -rw-r--r-- | docs/guides/federation/proposing-and-voting.md | 3 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 76 |
3 files changed, 72 insertions, 11 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 32f8756..4c5b33b 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -30,8 +30,8 @@ by them, in its words. is its own, the store file, dropping events and taking them back. * [`remakes.md`](remakes.md): compactions only, the electorate, the snapshot, putting again after a switch, two epochs for one, and rejoining. -* [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, and what the - federation's number and its revision say. +* [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, what the + federation's number and its revision say, and moving to a later revision. * [`watching.md`](watching.md): what a node's API and its log say that needs an operator or a party. * [`building-on-the-api.md`](building-on-the-api.md): an application reading what diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index 0c3e1a8..330d670 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -37,6 +37,9 @@ for the changes made most): * **`checkpoint`**, only where the version moves the store to a checkpoint: the heads. Otherwise leave it out, though the current version names one: its heads are behind, and a version naming them again is never written. +* **`revision`**, the revision of the federation the version follows, by its ID, left + out for the base revision: the current version's, or a later one (`next --revision`, + [`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)). Party names are 1 to 64 of `A-Z a-z 0-9 . _ @ -`; a version names up to 96 parties; a party has up to 16 keys and 64 nodes; a rule's path is a path as a write's is, its first diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index a106137..0a1a094 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -1,7 +1,8 @@ -# Upgrades and the federation's number +# Upgrades and the federation's revisions -Upgrading the continuum a federated swarm's nodes run, and what the federation's number -in each version says. The rules are the design's ([`federation.md`](../../federation.md), +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 @@ -34,12 +35,69 @@ 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. There are none yet but -the base revision. 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: roll it out first, every party's operators upgrading their nodes, then pass -a version naming it. +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. |
