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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
# 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
([Who syncs](#who-syncs)).
* `--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](#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](../../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.
A party writes its node list itself, without a vote, signed with a key its version names
(`continuum-party nodes --add`,
[`common-changes.md`](common-changes.md#what-a-party-does-by-itself)): a node it adds
is a member as soon as the list is taken.
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. Its users are its operators, and 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. Those named in `--store-readers` read the federation and do nothing
else: `GET` of the events API below, and checking a fork (`POST /events/fork`), but
nothing of the document (`/store`, `/stream`), the node (`/peers`, `/admin/…`), nor
what an operator does to the store (`/admin/events/…`): for an application, or
someone watching, that needn't act for the node. A token is taken by the node that
issued it only, and gives what its user may do.
* **A party's keys** log in to every node holding the store, without a password: a
challenge (`POST /auth/challenge`) signed with one of the keys that sign for the party
there (those its current version names, or of its key set as it counts), for the
namespace `continuum-login`, gives a token as the party (`POST /auth/login/party`).
Such a session does federation work alone: what a reader does, and putting events
(`POST /events`), while that key signs for the party (`401` once it doesn't). So a
party's people, each with a key of its set, work with the federation through any node
that holds it, as no operator has to let them in, and with nothing of an operator's
powers. `continuum-party` logs in so by itself, where `--node` names no user and no
`--token` is given, as the party its record names, or `--party` without one.
* **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. It learns of other members as it syncs, and needs none of its seeds once it has:
they may go away. Before a checkpoint passed, it reads from the root: of two versions
changing one, which keys voting twice wrote, it takes the first it judges, as any node,
and reports the other (`own` in `GET /events/refused`), for you to choose
([`when-things-go-wrong.md`](when-things-go-wrong.md)).
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`).
* **Merge events**, under a revision with them, where its party lists it and its store
holds more heads than an event may name (64): signed with its node key, a random wait
after there first were (`Merged heads beyond what an event may name`). They count for
nothing, and gather the heads apart, so that what is written after builds on them all.
* **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.
|