From 0d2467e15ec0c9c035b1074a2dd4eece6b24c599 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 04:00:12 +0000 Subject: 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. --- docs/openapi.yaml | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) (limited to 'docs/openapi.yaml') diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 5c90037..05e29d5 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1425,7 +1425,11 @@ paths: that one among them, taking nothing and refusing nothing until upgraded or told to drop it (`/admin/events/drop`); the party this node is of (`party`, `--store-party`), and whether it votes for it by itself (`votesByItself`), and so - casts votes by hand (`POST /admin/events/vote`). + casts votes by hand (`POST /admin/events/vote`); and the revisions of the + federation this continuum knows (`revisions`), the base revision first, each its + number, its ID, the feature it adds and what that adds (none for the base + revision), and as people read it (`named`): a version naming another, this node + can't read. responses: '200': description: The store. @@ -1433,7 +1437,8 @@ paths: application/json: schema: type: object - required: [store, checkpoint, heads, taken, stopped, party, votesByItself] + required: [store, checkpoint, heads, taken, stopped, party, votesByItself, + revisions] properties: store: type: string @@ -1459,6 +1464,22 @@ paths: type: [string, 'null'] votesByItself: type: boolean + revisions: + type: array + items: + type: object + required: [number, id, feature, adds, named] + properties: + number: + type: integer + id: + type: string + feature: + type: [string, 'null'] + adds: + type: [string, 'null'] + named: + type: string '404': $ref: '#/components/responses/Error' post: @@ -1528,7 +1549,8 @@ paths: summary: What counts description: | What counts, as the store reads now (docs/federation.md): the current version - (its number, its hash, and the version itself), each party's keys and nodes, the + (its number, its hash, its revision, by number and ID and as people read it, and + the version itself), each party's keys and nodes, the value at each place, the members, each `[node, party]`, and the proposals on the current version, by their hash, each with the IDs of the events proposing it that a vote may build on (`proposals`: of a version naming a checkpoint, those above -- cgit v1.3.1