aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:06:49 +0000
committertv <tv@krebsco.de>2026-11-17 14:23:04 +0100
commitd8137811dfad4adba3b1319ffe270d3ebea1de78 (patch)
tree77d218b1b9793b7a7c5a03e97a68d1bac07b93de
parentb7771be595b76cfa26540acda5234bdefa0c4e54 (diff)
guides: running a node of a federation
What a node of a federated swarm does otherwise than any: its store options and file, members syncing with members only, its API letting in whoever its operator lets in to do everything, the store API refusing writes, joining by ID and from a pinned checkpoint, and what it writes by itself.
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/running-a-node.md109
2 files changed, 111 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 5a6b227..b4c11a2 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -6,3 +6,5 @@ by them, in its words.
* [`getting-started.md`](getting-started.md): two parties start a federation, write,
read, and let a third one in.
+* [`running-a-node.md`](running-a-node.md): a node's options and files, who syncs, what
+ its API lets in, and joining.
diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md
new file mode 100644
index 0000000..d903b2d
--- /dev/null
+++ b/docs/guides/federation/running-a-node.md
@@ -0,0 +1,109 @@
+# Running a node of a federation
+
+A node of a federated swarm runs as any continuum node: its node key, its state and
+document files, its transports, a supervisor ([`operations.md`](../../operations.md)).
+This guide says what is otherwise: the options of a swarm holding a store, who syncs,
+what its API lets in, and joining.
+
+## Its options
+
+* `--store-root FILE` starts the swarm from its root, or goes on with it: the file the
+ founders made (`continuum-party root`), the root on its first line and, for a fork,
+ the events the root keeps, a line each. The node builds the changes founding the
+ swarm from it, as every node given the file builds them, and is ready at once.
+* `--store-id ID` joins the swarm by its ID, the root's SHA-256, through `--seeds`.
+ Joining with an empty document, the node takes as its root that store's genesis change
+ only.
+* `--store-party NAME`, which both need: the party the node is of, named in its entry
+ and its handshakes. It is a member once that party's node list names it.
+* `--store-file PATH`: what is the node's own, written whenever it changes: the events
+ it refused by what it took before (of two versions changing one, the second it judged)
+ and those its operator had it drop. A node reads its store anew from its document
+ whenever it starts: without the file, it may then take what it refused. Keep it beside
+ the document file; one that doesn't read stops the node from starting.
+* `--store-checkpoint ID`: a checkpoint the node reads its store from whenever it starts,
+ instead of from the document's checkpoint, by its ID (Joining, below).
+* `--store-neighbour-parties NAME,…`: parties among whose members, with its own party's,
+ the node keeps some of its neighbours.
+* `--store-vote-key PATH` and the options with it: the node votes and proposes for its
+ party by itself; its party then votes by hand only through it.
+
+What makes a new swarm's first change (`--genesis`, `--bootstrap-users`,
+`--bootstrap-keys`, `--bootstrap-policy`, `--remake`, `--genesis-root`) doesn't apply, nor
+a swarm key (`--swarm-key-file`, `--swarm-key-create`) nor `--protocol-writers`: the
+node refuses to start with them.
+
+## Its files
+
+Beside those of every node ([`lifecycle.md`](../../lifecycle.md), What the files are
+for), the store file. Back up the node key, as every node's: its node ID is what its
+party lists, and a new key is a new node, which the party lists anew. The document file
+and the store file go together: the store file says what the node refuses of what the
+document holds.
+
+## Who syncs
+
+The members are the nodes the parties' node lists name, as the current version reads
+them, each as its party's; nodes sync with members only. There is no swarm key: the
+parties say who syncs. A node its party doesn't list syncs with nobody, and says so in
+its log (`This node isn't a member of its store`); once it is listed, the others sync
+with it (`This node is a member of its store`). A party that takes a node off its list
+takes it out of the swarm.
+
+Of a node's neighbours (`--neighbours`), some are kept among the members of its own
+party and of the parties in `--store-neighbour-parties`, by the graph among those
+alone, so that a party listing many nodes can't be all of a node's neighbours.
+
+## Its API
+
+* **Who it lets in** is its own (`--htpasswd`, or a reverse proxy naming the user):
+ there is no user registry, and every user it lets in may do everything at it: put
+ events, read, have it drop what it took and take it back, vote through it, make a
+ fork's root. A token is taken by the node that issued it only. Let in those who act
+ for the node, and give a party without nodes of its own a user to put its events.
+* **The events** (`docs/openapi.yaml`, Events): `GET /events` (the store's ID, its
+ checkpoint, its heads, how many events it took), `POST /events` (an event, whoever
+ signed it), `GET /events/{id}`, `GET /events/counts` (what counts),
+ `GET /events/refused` (what the store refused, and why), `POST /events/fork` (what the
+ node finds of a fork's root); and its operator's: `POST /admin/events/drop`,
+ `/admin/events/allow`, `/admin/events/vote`, `/admin/events/fork`. Each answers
+ `404` while the node holds no store.
+* **The store API** (`/store`) reads the document, where events are bytes at
+ `_continuum/events/<ID>`; what counts is read at `GET /events/counts`. A write through
+ it is refused (`403`): the document takes events and each node's own protocol data
+ only.
+
+## Joining
+
+A node with an empty document joins by the store's ID (`--store-id`) through a member
+(`--seeds`), and holds its store once it has read the document: `GET /events` answers
+then.
+
+Once the store moved to a checkpoint, a node joining starts from that checkpoint, which
+its operator pins by its ID (`--store-checkpoint`): ask a node you trust for it
+(`checkpoint` in `GET /events`). The node finds it in its document, built from what the
+document holds as any node builds it, and holds no store until then (`The pinned
+checkpoint isn't in the document (yet)`). It takes no epoch whose snapshot holds a
+checkpoint it neither builds nor has pinned: from the root, it would take what was grown
+anew from it since, by keys of versions long replaced.
+
+A node that was away across a move to a checkpoint builds that checkpoint from its
+document, which holds what came before until a remake leaves it out; after such a remake,
+it takes the checkpoint only where its operator pins it. Pin it, and restart the node.
+
+## What it writes by itself
+
+* **A version that passed**, as soon as it holds the votes passing it (`Writing a
+ version that passed`): any node may write it, and the same version written by several
+ is one.
+* **Events its document lacks**, that its store would take and that it has: after a
+ remake, a rejoin, or a change of another node it refused (`Put again events the
+ document lacked`).
+* **Its own protocol data**: its entry, its acks of remakes, and the remakes it
+ coordinates. Remakes are compactions only, acked by the members
+ ([`remakes.md`](../../remakes.md)).
+
+It refuses events as every node does, and some by what it took before: of two versions
+changing the one it reads, the second it judged (`Refused an event its history takes, by
+what this node took before: kept so`). `GET /events/refused` lists them apart (`own`):
+tell its party, which decides what the node keeps.