aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/writing-and-reading.md112
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.