diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/running-a-node.md | 109 |
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. |
