aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 00:27:24 +0000
committertv <tv@krebsco.de>2026-11-17 01:47:46 +0100
commit202bb27664956f9dc113c751e1fd36877d48978c (patch)
tree0d5976d6b173c5b86fed7723f5551c401c31d6ba /docs/openapi.yaml
parent438d4f06103ba7ae17a80f48aa589219c7d8dd61 (diff)
api: a fork's root made, and what a node finds of one
`POST /admin/events/fork`: the root of the fork at the heads named by the version given, as the node's store builds it, with the events it keeps, as the file the fork's founders start its swarm from (`--store-root`). `POST /events/fork`: what the node finds of the fork whose root the body holds: whether it builds that root at its heads, and why not; what it holds that those heads lack; and the parties whose keys the fork's version gives otherwise than they had there (`federation::fork`).
Diffstat (limited to 'docs/openapi.yaml')
-rw-r--r--docs/openapi.yaml99
1 files changed, 99 insertions, 0 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index c99cb65..c2cee82 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1592,6 +1592,66 @@ paths:
type: string
'404':
$ref: '#/components/responses/Error'
+ /events/fork:
+ post:
+ tags: [Events]
+ summary: What this node finds of a fork's root
+ description: |
+ What this node, holding its federation's history, finds of the fork whose root
+ is the body's first line, as the file the fork's founders start from holds it
+ (`/admin/events/fork`): whether it builds that root at its heads by its version,
+ byte for byte, and why it builds none where it doesn't (heads it doesn't hold,
+ a version that is no fork); what it holds that those heads lack (`lacking`:
+ events it took that are neither among them, nor in their history, nor above
+ them); and the parties whose keys the fork's version gives otherwise than they
+ had at those heads, each with its keys there and in the fork. A node that
+ doesn't hold that history takes a fork's root on its operator's word, who names
+ the fork by its ID (`--store-id`).
+ requestBody:
+ required: true
+ content:
+ application/octet-stream:
+ schema:
+ type: string
+ format: binary
+ responses:
+ '200':
+ description: What it finds.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [fork, builds, why, lacking, keys]
+ properties:
+ fork:
+ type: string
+ builds:
+ type: boolean
+ why:
+ type: string
+ nullable: true
+ lacking:
+ type: array
+ items:
+ type: string
+ keys:
+ type: object
+ additionalProperties:
+ type: object
+ required: [there, fork]
+ properties:
+ there:
+ type: array
+ items:
+ type: string
+ fork:
+ type: array
+ items:
+ type: string
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ $ref: '#/components/responses/Error'
/admin/events/drop:
post:
tags: [Events]
@@ -1689,6 +1749,45 @@ paths:
$ref: '#/components/responses/Error'
'422':
$ref: '#/components/responses/Error'
+ /admin/events/fork:
+ post:
+ tags: [Events]
+ summary: Make a fork's root
+ description: |
+ The root of the fork at `heads` by `version` (`docs/federation.md`, Forks), as
+ this node's store builds it, with the events it keeps there: the file the fork's
+ founders start its swarm from (`--store-root`), the root on its first line and
+ each event it keeps on a line of its own. The version changes the one current at
+ those heads and is numbered one past it; a fork is named by its root's ID. Needs
+ `write` on `_continuum`.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [heads, version]
+ properties:
+ heads:
+ type: array
+ items:
+ type: string
+ version:
+ type: object
+ responses:
+ '200':
+ description: The fork's root, and the events it keeps.
+ content:
+ application/octet-stream:
+ schema:
+ type: string
+ format: binary
+ '400':
+ $ref: '#/components/responses/Error'
+ '404':
+ $ref: '#/components/responses/Error'
+ '422':
+ $ref: '#/components/responses/Error'
/admin/remakes:
get:
tags: [Remakes]