aboutsummaryrefslogtreecommitdiffstats

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). 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, 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, the node's party, and whether it votes for it by itself), 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).

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.