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, 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`](../../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.
|