aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/running-a-node.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation/running-a-node.md')
-rw-r--r--docs/guides/federation/running-a-node.md109
1 files changed, 109 insertions, 0 deletions
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.