aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/running-a-node.md
blob: d903b2dd4114e990d0349f551ee2084a117e1b21 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
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.