diff options
| author | tv <tv@krebsco.de> | 2026-11-19 18:52:37 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 20:12:23 +0100 |
| commit | ab9d79ba58562bfcd468afe8c2047a1110e34b7c (patch) | |
| tree | 835ce4e444bcd11ef9d90c8f70f2c297e128cecb /docs/guides/federation | |
| parent | 97b9c45e5f8b7eed61dd494b977d27790a9544e2 (diff) | |
continuum-party: propose admit, remove, give, take, keys, nodes, checkpoint, revision
The changes made most no longer go through `next`, jq and a file: each
is a subcommand of `propose`, which writes the next version changed so
(Intent, intended) and proposes it.
* admit PARTY --keys KEY|FILE... [--nodes NODE...]: its keys and node
list named anew since the new number; a party already, or no party's
name, refused.
* remove PARTY: its keys, node list and the rules giving it places go.
* give PATH PARTY|{party}: a rule first; one of that path before goes.
* take PATH: the rule of that path goes, and where another rule may
still give one of its places (overlaps), a rule giving them to nobody
goes first.
* keys PARTY KEY|FILE..., nodes PARTY NODE...: named anew.
* checkpoint: at the heads the node shows.
* revision FEATURE: as `next --revision`.
Keys are authorized_keys lines, or files of them. Every proposal, a
file's too, now says what its version does first (version_lines, shared
with `show`) and asks on a terminal; with --yes the one question covers
the vote, which then says and asks nothing more. A version changing
only its number isn't proposed. --print writes the version instead, to
change by hand and propose as a file.
Diffstat (limited to 'docs/guides/federation')
| -rw-r--r-- | docs/guides/federation/common-changes.md | 119 | ||||
| -rw-r--r-- | docs/guides/federation/proposing-and-voting.md | 23 |
2 files changed, 95 insertions, 47 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)). diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index d8410f6..b58a926 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -10,8 +10,15 @@ its key set are its own to write, without a vote ## Writing a version -A version is the whole policy, not a change to it. Begin from the current one, as a node -shows it, with `number` and `changes` set and its `checkpoint` left out, as below: +The changes made most have a command each, which writes the version from the current +one and proposes it: `propose admit`, `remove`, `give`, `take`, `keys`, `nodes`, +`checkpoint` and `revision` ([`common-changes.md`](common-changes.md)). With `--print`, +each writes the version to standard output instead, to change further and propose as a +file. + +A version is the whole policy, not a change to it. To write one by hand, begin from the +current one, as a node shows it, with `number` and `changes` set and its `checkpoint` +left out, as below: ```sh continuum-party --node http://tv:secret@localhost:3000 next > next.json @@ -55,13 +62,19 @@ drop it ([`when-things-go-wrong.md`](when-things-go-wrong.md), ```sh continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \ propose next.json +# version 4 on 3: +# adds rule 1: names/r/wiki -> lass +# Propose it? [y/N] y # c41e… taken # proposal 8d02… ``` -With `--yes`, the client votes `true` on it too, as `vote 8d02… yes` does -([Voting](#voting), below): a party whose node votes for it by itself votes through that -node instead. +The client says what the version does to the current one, as `show` says it of a +proposal ([Following a vote](#following-a-vote)), and asks before it signs, where its +input and its errors are a terminal; asked nothing, as in a script, it goes on. It +proposes nothing that changes the current version only by its number. With `--yes`, it +votes `true` on it too, as `vote 8d02… yes` does ([Voting](#voting), below), asking once +for both: a party whose node votes for it by itself votes through that node instead. The client proposes only a version it would back: one changing the current one as a version must (its `number`, `changes`, and each `since`), whose checkpoint, where it names |
