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
|
# Building on the API
An application on a federated swarm reads what counts at a node and writes as a party.
This guide says how, through the client or with code of its own. The formats are the
design's ([`federation.md`](../../federation.md), Events, The policy, What counts).
## Reading
`GET /events/counts` is what counts, as the node reads it now: the values at places
(`values`), the current version and its rules, each party's keys and nodes, the members
([`writing-and-reading.md`](writing-and-reading.md), Reading). There is no stream of what
counts: read it again when the store's heads change (`heads` in `GET /events`).
What a node answers is its word: it may be behind, and an application that must not take
it on trust reads the events themselves (`GET /events/{id}`) and checks their signatures,
or asks nodes of several parties.
## Writing through the client
The simplest is the party's client, a command per write:
```sh
continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \
--record tv.record write home/tv/hosts/laptop '{"ip6": "42:0:a46e::1"}'
```
It signs on the heads the node shows, records what it signed, and puts it; `again` signs
anew what a move to a checkpoint refused ([`writing-and-reading.md`](writing-and-reading.md),
After a move).
## Writing with code of its own
An event is the JCS encoding (RFC 8785) of an object, its member names sorted as JCS
sorts them:
```json
{ "deps": ["<ID>"], "key": "ssh-ed25519 AAAA…",
"party": "tv", "sig": "<signature>",
"write": { "path": "home/tv/hosts/laptop", "value": {"ip6": "42:0:a46e::1"} } }
```
* `deps`: the heads it read (`heads` in `GET /events`), each as 64 lower-case hex digits,
ascending, one at least.
* `key`: the key it signs with, `ssh-ed25519`, a space, the base64 of its blob, no
comment; one of the party's keys.
* `sig`: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`, hashed
with `sha512`) over the JCS bytes of the object without `sig`: the SSHSIG blob, its
reserved field empty, in base64, unarmored.
* The value is any JSON with integers only, from −2⁵³ to 2⁵³; the event up to 256 KiB.
Put its bytes as they are:
```sh
curl -u tv:secret -X POST -H 'Content-Type: application/json' \
--data-binary @event.json localhost:3000/events
# {"event":"taken","id":"0c7e…"}
```
Its ID is the SHA-256 of its bytes. A node takes no event that isn't byte for byte as
the federation spells it; the vectors (`federation::vectors`) give events and their IDs
to check code against.
Keep what it signed: once the store moves to a checkpoint, a write signed on heads from
before is refused (`it isn't above the checkpoint's heads`), and is to be signed again on
the heads a node shows then.
## When a write counts
At the node it was put through, at once where it is `taken` and the latest its party
signed at that place: `GET /events/counts` shows it. At another node, once that node holds
it (`GET /events/{id}` answers `200` there), as both read the same from the same events.
## One writer at a place
Two writes of one party at one place, neither in the other's history, leave the one with
the lower ID, whichever came last. Write each place from one client, on heads read just
before; where two did, write again, after both.
## Keeping a namespace in step
To have a party's namespace hold what an application keeps elsewhere: read `values`,
write each place whose value differs, and `null` at each place of the namespace that the
application holds no value for any more. Write nothing where a place holds the value
already: a write is an event every node keeps until a checkpoint leaves it out.
## Not through the store API
A node of a federated swarm refuses writes through the store API (`/store`): the document
takes events and each node's own protocol data only.
|