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, 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:
curl -s -u tv:secret localhost:3000/events/counts | jq .version.version.rules
Writing
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, 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).
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:
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, itsnumber, itshash, and the version itself;parties: each party'skeysandnodes, 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, the votes on it, the parties votingtrueandfalse, and whether it passed and whether it is dead (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.
