diff options
| author | tv <tv@krebsco.de> | 2026-11-17 13:06:49 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-17 14:23:07 +0100 |
| commit | df2b1579cb7525badd041ff7f98b1f6fd2763ceb (patch) | |
| tree | 52a1cc9b152a6fc62d6ed64167bacf594910795b /docs | |
| parent | d8137811dfad4adba3b1319ffe270d3ebea1de78 (diff) | |
guides: writing and reading in a federation
Places and the rules naming their writers, a write through the party's client and what
it may hold, what counts and what stops counting, the refusals a node names, signing
again what a move refused, and what `GET /events/counts` shows.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/writing-and-reading.md | 112 |
2 files changed, 114 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index b4c11a2..8efae2b 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -8,3 +8,5 @@ by them, in its words. read, and let a third one in. * [`running-a-node.md`](running-a-node.md): a node's options and files, who syncs, what its API lets in, and joining. +* [`writing-and-reading.md`](writing-and-reading.md): places, values, what counts, why + a write is refused, and signing again after a move. diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md new file mode 100644 index 0000000..0e6865c --- /dev/null +++ b/docs/guides/federation/writing-and-reading.md @@ -0,0 +1,112 @@ +# 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`](../../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: + +```sh +curl -s -u tv:secret localhost:3000/events/counts | jq .version.version.rules +``` + +## Writing + +```sh +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`](../../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`](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: + +```sh +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 and the votes on it ([`proposing-and-voting.md`](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. |
