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
|
# Writing and reading
A party writes values at places, through its client; anyone a node lets in reads what
counts there. The rules are the design's ([`federation.md`](../../federation.md), The
policy, What counts).
## Places
A **place** is a path a rule of the current version matches: segments separated by `/`,
none empty, up to 32 segments of up to 255 bytes each. The first rule whose path matches
says who writes there: a party, the party the path names (`{party}`), or nobody. A path
no rule matches, nobody writes. A party's namespace is the usual rule,
`home/{party}/**`: tv writes `home/tv/` and everything below it. The rules are in the
current version, as a node shows it:
```sh
curl -s -u tv:secret localhost:3000/events/counts | jq .version.version.rules
```
## Writing
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
write home/tv/hosts/laptop '{"ip6": "42:0:a46e::1"}'
# 0c7e… taken
```
The value is any JSON: integers from −2⁵³ to 2⁵³ but no fractions, strings of whole
Unicode characters, objects and arrays nested up to 32 deep with the event's own
object, the whole event up to 256 KiB. `null` empties the place.
The client signs the write with its key (`--key`), on the heads its node shows, which
are what the party read; records it (`--record`), to sign it again after a move; and puts
it through the node. The node answers what became of it: `taken`, `held` (taken before),
or `waiting` for an event it builds on that the node doesn't hold yet.
A write counts while the key that signed it is among its party's keys: those of its key
set, or, while it has written none, those its version names
([`federation.md`](../../federation.md), Keys).
## What counts
A place's value is the latest write its party signed there that counts: one that no
other counting write there has in its history. What the party signed after replaces
what it signed before, whatever order the events came in. Two writes of one party at
one place, neither in the other's history (two of its clients at once), leave the one
with the lower ID: write again, after both, to choose.
A write stops counting, without being refused, where the current version no longer lets
its party write there (the place went to another party, a rule changed, the party is no
longer one), and where the key that signed it is no longer among its party's. A place
given back to its party shows what the party wrote before, unless something replaced it
since or a checkpoint left it out. Nothing is deleted: a party empties a place by writing
`null`.
## Why a write is refused
A node refuses what every node refuses, judged at its history, and says why (`422`, its
`why`); `GET /events/refused` lists what it refused, each with its kind:
* `tv may not write at names/r/wiki` (`judged`): no rule of the version current at the
write's history gives tv that place.
* `signed by a key that isn't its party's` (`judged`): the key isn't among the party's
keys at its history.
* `makefu is no party of the version current at its history` (`judged`): a party writes
only once a version lets it in, on heads that hold that version.
* `none of the federation's events, or larger than it allows` (`none`): not an event as
the federation spells one, or past its sizes.
* `it builds on …, refused` (`builtOn`): an event it builds on is refused.
* `it isn't above the checkpoint's heads` (`notAbove`): signed on heads a move to a
checkpoint left behind (After a move, below).
And some by what the node took before (`own`), or as its operator had it drop them
(`dropped`): those are the node's alone ([`running-a-node.md`](running-a-node.md)).
## After a move
When the store moves to a checkpoint, a node refuses whatever isn't above its heads: a
write signed on heads from before, and still on its way, is refused so. The client signs
again what a move refused: of the latest write it signed at each place, its key set and
its node list, those the node refuses as not above the checkpoint's heads or as built on
such, each on the heads it shows now:
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
again
```
Votes and proposals aren't signed again: their version is behind.
## Reading
`GET /events/counts` is what counts, as the node reads it now:
* `version`: the current version, its `number`, its `hash`, and the version itself;
* `parties`: each party's `keys` and `nodes`, as they count;
* `values`: each place holding a value, with it;
* `members`: each node of the swarm, with its party, `[node, party]`;
* `proposals`: the proposals on the current version, by hash, each with the events
proposing it and the votes on it ([`proposing-and-voting.md`](proposing-and-voting.md)).
`GET /events/{id}` is an event's bytes, as its party signed them: anyone can check its
signature, an SSH signature over its bytes without `sig` (namespace
`continuum-federation`), against the keys its party had at its history.
Reads are a node's: it may be behind the others, and it shows what it took. Two nodes
holding the same events read the same, whatever order they came in; one that refused a
version the other took reads otherwise, and says so (`own` in `GET /events/refused`).
Read from a node you trust: what it answers is its word, not the events'.
An application reads at `GET /events/counts` and writes through a party's client, never
through the store API (`/store`), whose writes a node of a federated swarm refuses.
|