aboutsummaryrefslogtreecommitdiffstats

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, 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, 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:

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, 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:

{ "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, its type (ssh-ed25519 or ecdsa-sha2-nistp256), 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. Of an ECDSA key, its s low, at most half the curve's order: ssh-keygen makes a high one half the time, which no node takes; sign again, or put the order less s in its place.
  • The value is any JSON with integers only, from −2⁵³ to 2⁵³; the event up to 256 KiB.

Put its bytes as they are:

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.