summaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 18:49:50 +0000
committertv <tv@krebsco.de>2026-11-18 20:29:41 +0100
commitc64fcc05d8c53bee99ab039bd709039afb730cdd (patch)
tree45baad78d7b92de42283be2954fc3f9b4dd6129d /docs/openapi.yaml
parent598366b03679eac9d04f32d9194f3ba4ba9c3da8 (diff)
federation: a node stops at a version it doesn't read
A version event writing a proposal passed on the version a node reads, which doesn't read as a version there (of a later federation, using what a later continuum takes, or none at all), the node can't judge: `Fold::stops`. The store stops at it: it takes nothing and refuses nothing from then on, holding back whatever comes, that event first (`Offered::Stopped`), and keeps none of it across a restart, where it stops there again. One beside the version the node reads is refused of its own, as any other. Its operator has it drop that event (`POST /admin/events/drop`), or one it builds on: it is refused as dropped, or as built on what was, any version event writing that version with it, kept in the store file; the node judges what it held back and goes on under the version before. Allowed again, it stops there once more. The node logs the stop and its end; `GET /events` names the event, why, and how many it holds back (`stopped`); a put answers `stopped`, written into the document all the same; a node voting by itself casts nothing while stopped. The test fold's eras tagged `new` stop a store. Row 39 is tested (`federation_attack_39`); of rows 9, 10 and 48, a node stops at the version event.
Diffstat (limited to 'docs/openapi.yaml')
-rw-r--r--docs/openapi.yaml40
1 files changed, 28 insertions, 12 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 3dbcd62..e1e602a 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1419,9 +1419,12 @@ paths:
description: |
The store's ID (its root's), its checkpoint's ID, its heads (what a new event
builds on) and how many events it took after its checkpoint, as this node reads
- it now; 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`).
+ it now; the event it stopped at, if any (`stopped`: a version event writing a
+ version that passed, which this continuum doesn't read), why, and how many
+ events it holds back since, 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`).
responses:
'200':
description: The store.
@@ -1429,7 +1432,7 @@ paths:
application/json:
schema:
type: object
- required: [store, checkpoint, heads, taken, party, votesByItself]
+ required: [store, checkpoint, heads, taken, stopped, party, votesByItself]
properties:
store:
type: string
@@ -1441,6 +1444,16 @@ paths:
type: string
taken:
type: integer
+ stopped:
+ type: [object, 'null']
+ required: [id, why, heldBack]
+ properties:
+ id:
+ type: string
+ why:
+ type: string
+ heldBack:
+ type: integer
party:
type: [string, 'null']
votesByItself:
@@ -1454,7 +1467,8 @@ paths:
Puts an event, the body as its bytes, whoever signed it: offered to the store,
and written into the document at its ID (the SHA-256 of its bytes) unless the
store refuses it. `event` says what became of it: `taken`, `held` (taken
- before), or `waiting` for what it builds on.
+ before), `waiting` for what it builds on, or `stopped`: held back, the store
+ stopped at a version it doesn't read (`stopped` in `GET /events`).
requestBody:
required: true
content:
@@ -1474,7 +1488,7 @@ paths:
type: string
event:
type: string
- enum: [taken, held, waiting]
+ enum: [taken, held, waiting, stopped]
'404':
$ref: '#/components/responses/Error'
'422':
@@ -1680,12 +1694,14 @@ paths:
tags: [Events]
summary: Drop events this node took
description: |
- Drops events the store took after its checkpoint, version events naming the
- version one of them names, and everything built on them: this node refuses them
- from then on, from whoever brings them, and any version event naming a version
- among them, and keeps so across restarts (`--store-file`), until it is told
- otherwise (`/admin/events/allow`). Not what the checkpoint keeps or holds by
- ID. Answers what it dropped, in the order taken. Needs `write` on `_continuum`.
+ Drops events the store took after its checkpoint, or the version event it
+ stopped at (`stopped` in `GET /events`), version events naming the version one
+ of them names, and everything built on them: this node refuses them from then
+ on, from whoever brings them, and any version event naming a version among
+ them, and keeps so across restarts (`--store-file`), until it is told otherwise
+ (`/admin/events/allow`). Not what the checkpoint keeps or holds by ID. Answers
+ what it dropped, in the order taken, then the event it stopped at, after which
+ it takes again. Needs `write` on `_continuum`.
requestBody:
required: true
content: