aboutsummaryrefslogtreecommitdiffstats

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, 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, the votes on it, the parties voting true and false, 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.