diff options
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/building-on-the-api.md | 89 |
2 files changed, 91 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index a4af7f7..1c8e049 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -34,3 +34,5 @@ by them, in its words. federation's number says. * [`watching.md`](watching.md): what a node's API and its log say that needs an operator or a party. +* [`building-on-the-api.md`](building-on-the-api.md): an application reading what + counts and writing as a party, through the client or with code of its own. diff --git a/docs/guides/federation/building-on-the-api.md b/docs/guides/federation/building-on-the-api.md new file mode 100644 index 0000000..9f144be --- /dev/null +++ b/docs/guides/federation/building-on-the-api.md @@ -0,0 +1,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. |
