diff options
Diffstat (limited to 'docs/guides/federation/common-changes.md')
| -rw-r--r-- | docs/guides/federation/common-changes.md | 119 |
1 files changed, 77 insertions, 42 deletions
diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md index a18d863..8a31080 100644 --- a/docs/guides/federation/common-changes.md +++ b/docs/guides/federation/common-changes.md @@ -1,91 +1,121 @@ # Common changes -Recipes for the changes a federation makes most, each a version to propose and vote on -([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes by itself. +The changes a federation makes most, each a version proposed by a command of its own and +voted on ([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes +by itself. The rules are the design's ([`federation.md`](../../federation.md), [The policy](../../federation.md#the-policy), [Keys](../../federation.md#keys), [Nodes](../../federation.md#nodes)). -## The next version +## How -Every change below begins from the current version: the next number, the current one's -hash as `changes`, and no `checkpoint` (a version names one only to move the store -on, and the current version's heads are behind): +Each change below is a subcommand of `propose`: the client writes the next version, the +current one with the next number, its hash as `changes`, no `checkpoint`, and the change; +says what it does; asks on a terminal; and proposes it. `--yes` votes `true` on it too. +The client's options are as everywhere (`--node`, `--key`, `--record`, or a federation's +directory, [`configuration.md`](../../configuration.md), +[The party's client](../../configuration.md#the-partys-client)), left out below: ```sh -continuum-party --node http://tv:secret@localhost:3000 next > next.json +continuum-party propose admit makefu --keys makefu.key.pub --nodes continuum:e2a8… --yes +# version 2 on 1: +# lets makefu in: 1 key (ssh-ed25519 SHA256:2kq…); 1 node (continuum:e2a8…) +# Propose it, and vote `true` on it? [y/N] y +# c41e… taken +# proposal 8d02… +# 5a77… taken ``` -Each recipe is a `jq` filter on that file; then propose the result, and vote. +The other parties vote as on any proposal (`continuum-party vote 8d02 yes`). ## Letting a party in -Name its keys and its node list anew, `since` the new version's number: - -```sh -jq --arg key "$(cut -d' ' -f1,2 makefu.key.pub)" --arg node continuum:e2a8… ' - .keys.makefu = {since: .number, keys: [$key]} - | .nodes.makefu = {since: .number, nodes: [$node]}' next.json -``` - -A party let in without nodes has an empty list (`nodes: []`) and writes through any node -that takes its events. It begins its record before it votes: from the root, as it never -voted ([`proposing-and-voting.md`](proposing-and-voting.md), +`propose admit PARTY --keys KEY… [--nodes NODE…]`: its keys, each an `authorized_keys` +line as one argument or a file of them (`makefu.key.pub`), and its node list, by node ID, +named anew, `since` the new version's number. A party let in without nodes has an empty +list and writes through any node that takes its events. It begins its record before it +votes: from the root, as it never voted +([`proposing-and-voting.md`](proposing-and-voting.md), [Voting](proposing-and-voting.md#voting)). ## Taking a party out -Leave out its keys and its node list, and the rules giving it places: - -```sh -jq 'del(.keys.lass, .nodes.lass) | .rules |= map(select(.writer != "lass"))' next.json -``` - +`propose remove PARTY`: its keys and node list left out, and the rules giving it places. What it wrote counts no more, nor its key set and node list: its nodes are members no more. To come back, the parties let it in anew. ## Giving a place, taking it back A place goes to a party by a rule before any other that matches its path; the first -match decides: +match decides. `propose give PATH PARTY` adds that rule first, and drops one of the same +path that came before: ```sh -jq '.rules = [{path: "names/r/wiki", writer: "lass"}] + .rules' next.json +continuum-party propose give names/r/wiki lass ``` -To give it to another, change the rule's writer; to take it back, remove the rule or -make its writer `false`. What the former writer signed there counts no more; given back -later, it shows again, unless something replaced it or a checkpoint left it out. +`propose take PATH` gives the places the path matches to nobody: it drops the rule of +that path, and where another rule still gives one of them, adds a rule giving them to +nobody (`"writer": false`) first. What the former writer signed there counts no more; +given back later, it shows again, unless something replaced it or a checkpoint left it +out. ## Zones and blocks -A rule a party holds by its name gives it a zone without a vote for each name in it: +A rule a party holds by its name gives it a zone without a vote for each name in it, a +rule for the name and one for what lies under it: ```sh -jq '.rules += [{path: "names/r/{party}", writer: "{party}"}, - {path: "names/r/{party}/**", writer: "{party}"}]' next.json +continuum-party propose give 'names/r/{party}' '{party}' +continuum-party propose give 'names/r/{party}/**' '{party}' ``` and a block of addresses by its parts, to one party: ```sh -jq '.rules += [{path: "ip4/10/243/7/*", writer: "tv"}]' next.json +continuum-party propose give 'ip4/10/243/7/*' tv ``` Then a new host in the zone or the block is a write, no vote -([`designing-rules.md`](designing-rules.md)). +([`designing-rules.md`](designing-rules.md)). Each `propose` is a version of its own: +the second of two proposed at once lapses when the first passes, so propose the next once +one passed, or write both rules in one version by hand ([By hand](#by-hand)). -## Keys named anew +## Keys and node lists named anew A party that lost a key its version names, or had one stolen, gets its keys named anew (`since` the new number); every key set it wrote before counts no more, and it writes its set again ([`keys.md`](keys.md)): ```sh -jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" ' - .keys.tv = {since: .number, keys: [$key]}' next.json +continuum-party propose keys tv tv-new.key.pub ``` +`propose nodes PARTY NODE…` names a party's node list anew, likewise: where it can't +write its own. + +## By hand + +Anything else, or several changes in one version, is written by hand from the next +version, the current one with the next number, its hash as `changes`, and no +`checkpoint`: + +```sh +continuum-party next > next.json +``` + +or from what a command above would propose, `--print` writing it instead: + +```sh +continuum-party propose give 'names/r/{party}' '{party}' --print > next.json +jq '.rules = [{path: "names/r/{party}/**", writer: "{party}"}] + .rules' next.json \ + > both.json +continuum-party propose both.json +``` + +What each field holds is in [`proposing-and-voting.md`](proposing-and-voting.md), +[Writing a version](proposing-and-voting.md#writing-a-version). + ## What a party does by itself * **Its node list**, signed with a key its version names, no vote: the list as it counts @@ -111,7 +141,12 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" ' ## Moving to a checkpoint -A version that only moves the store on changes nothing else: the next version, with -`checkpoint` set to the heads ([`checkpoints.md`](checkpoints.md)). Keep other changes -out of it: a node voting by itself backs no version naming a checkpoint that changes -more. +`propose checkpoint`: a version that only moves the store on, to a checkpoint at the +heads the node shows ([`checkpoints.md`](checkpoints.md)). Keep other changes out of it: +a node voting by itself backs no version naming a checkpoint that changes more. + +## Moving to a revision + +`propose revision FEATURE`: the next version, following the revision that adds the +feature, once every party's nodes run a continuum that knows it +([`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)). |
