summaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 04:00:12 +0000
committertv <tv@krebsco.de>2026-11-19 05:13:38 +0100
commit0d2467e15ec0c9c035b1074a2dd4eece6b24c599 (patch)
treee544ce8ae1c31e9556191d3f99157b5bd61b1f14 /docs/openapi.yaml
parentefaf79e7fd55db2b9704ccefedde33346f874a1d (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/openapi.yaml')
-rw-r--r--docs/openapi.yaml28
1 files changed, 25 insertions, 3 deletions
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