aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 21:30:24 +0000
committertv <tv@krebsco.de>2026-11-16 23:04:45 +0100
commit9fa28bb06692cd3e9d06b678d3dfe2595d328a5f (patch)
treea4e2959a984f0bd0d416042b9d93e7f2971122aa /docs/openapi.yaml
parentd46368d5ba8d7a12e657b5f293830b6c0d8dce00 (diff)
api: a swarm holding a store at a node's API
Behind the `federation` feature, a node of a swarm holding a store has, at its API (`docs/store.md`, Members; `docs/openapi.yaml`, Events): * `GET /events`: its store's ID, its checkpoint's, its heads, and how many events it took after its checkpoint; * `POST /events`: an event put, whoever signed it, offered to the store and written into the document at its ID unless the store refuses it (`422`, with why): taken, held, or waiting for what it builds on; * `GET /events/{id}`: an event the store holds, or its checkpoint, as its bytes; * `GET /events/counts`: what counts as the store reads now: the current version, each party's keys and nodes, the values at places, the members; * `GET /events/refused`: what the store refused, its own refusals apart, its operator's drops, and the rest with why; * `POST /admin/events/drop` and `/admin/events/allow`: its operator has it drop what it took, and take it back. The events' endpoints are anyone's this node lets in, as the store's are; dropping and taking back need `write` on `_continuum`, as what operators do. While a node holds no store, they answer `404`.
Diffstat (limited to 'docs/openapi.yaml')
-rw-r--r--docs/openapi.yaml230
1 files changed, 230 insertions, 0 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 0f1af33..0bce165 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -51,6 +51,12 @@ tags:
refused (`409`).
- name: Debug
description: Test hooks, only with `--debug-api`.
+ - name: Events
+ description: |
+ A swarm holding a store (docs/store.md): its events, which whoever this node lets
+ in may have it put, whoever signed them; what its fold reads from them; and this
+ node's own refusals and drops. Only with the `federation` cargo feature; `404`
+ while the node holds no store (its swarm holds none, or it hasn't read it yet).
paths:
/store:
@@ -1405,6 +1411,221 @@ paths:
text/event-stream:
schema:
type: string
+ /events:
+ get:
+ tags: [Events]
+ summary: The store
+ 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.
+ responses:
+ '200':
+ description: The store.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [store, checkpoint, heads, taken]
+ properties:
+ store:
+ type: string
+ checkpoint:
+ type: string
+ heads:
+ type: array
+ items:
+ type: string
+ taken:
+ type: integer
+ '404':
+ $ref: '#/components/responses/Error'
+ post:
+ tags: [Events]
+ summary: Put an event
+ description: |
+ 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.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ responses:
+ '200':
+ description: Put.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [id, event]
+ properties:
+ id:
+ type: string
+ event:
+ type: string
+ enum: [taken, held, waiting]
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ description: The store refuses it; `id` and `why` say which, and why.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Error'
+ /events/{id}:
+ get:
+ tags: [Events]
+ summary: An event
+ description: |
+ An event the store holds, taken or kept by its checkpoint, or its checkpoint, as
+ its bytes.
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Its bytes.
+ content:
+ application/json:
+ schema:
+ type: object
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
+ /events/counts:
+ get:
+ tags: [Events]
+ 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
+ value at each place, and the members, each `[node, party]`.
+ responses:
+ '200':
+ description: What counts.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [version, parties, values, members]
+ properties:
+ version:
+ type: object
+ parties:
+ type: object
+ values:
+ type: object
+ members:
+ type: array
+ items:
+ type: array
+ items:
+ type: string
+ '404':
+ $ref: '#/components/responses/Error'
+ /events/refused:
+ get:
+ tags: [Events]
+ summary: What the store refused
+ description: |
+ The events the store refused: `own`, those its history takes but this node
+ doesn't, by what it took before (a version changing another than the one it
+ reads), apart from the rest; `dropped`, those its operator had it drop; and
+ `refused`, every other, with why.
+ responses:
+ '200':
+ description: What it refused.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [own, dropped, refused]
+ properties:
+ own:
+ type: array
+ items:
+ type: string
+ dropped:
+ type: array
+ items:
+ type: string
+ refused:
+ type: array
+ items:
+ type: object
+ required: [id, why]
+ properties:
+ id:
+ type: string
+ why:
+ type: string
+ '404':
+ $ref: '#/components/responses/Error'
+ /admin/events/drop:
+ post:
+ tags: [Events]
+ summary: Drop events this node took
+ description: |
+ Drops events the store took after its checkpoint, with everything built on
+ them: this node refuses them from then on, from whoever brings 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`.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EventIds'
+ responses:
+ '200':
+ description: Dropped.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [dropped]
+ properties:
+ dropped:
+ type: array
+ items:
+ type: string
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ $ref: '#/components/responses/Error'
+ /admin/events/allow:
+ post:
+ tags: [Events]
+ summary: Take back what this node refused of its own, or dropped
+ description: |
+ Takes back what this node refused of its own, or dropped, among the events
+ named, and what was refused for building on them: they are taken again where the
+ store takes them, as it reads its document again. Needs `write` on
+ `_continuum`.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/EventIds'
+ responses:
+ '204':
+ description: Taken back.
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
/admin/remakes:
get:
tags: [Remakes]
@@ -2078,6 +2299,15 @@ components:
$ref: '#/components/schemas/Error'
schemas:
+ EventIds:
+ type: object
+ required: [ids]
+ properties:
+ ids:
+ type: array
+ items:
+ type: string
+ description: Events by their IDs, in hex.
Limit:
type: object
properties: