diff options
| -rw-r--r-- | docs/guides/federation/common-changes.md | 10 | ||||
| -rw-r--r-- | docs/guides/federation/keys.md | 17 | ||||
| -rw-r--r-- | docs/guides/federation/running-a-node.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/when-things-go-wrong.md | 4 | ||||
| -rw-r--r-- | src/federation/party.rs | 156 |
5 files changed, 128 insertions, 61 deletions
diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md index 1f7f331..1dd30c1 100644 --- a/docs/guides/federation/common-changes.md +++ b/docs/guides/federation/common-changes.md @@ -86,8 +86,9 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" ' ## What a party does by itself -* **Its node list**, signed with a key its version names, no vote: the list whole, or the - list as it counts at the node with nodes added (`--add`) or taken off (`--remove`): +* **Its node list**, signed with a key its version names, no vote: the list as it counts + at the node with nodes added (`--add`) or taken off (`--remove`), or set whole + (`--set`); `nodes` alone shows it: ```sh continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ @@ -96,8 +97,9 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" ' # 9b2c… taken ``` - The client checks first that the current version names the key it signs with for the - party, and says otherwise: then only a version naming the party's keys or its list + A list left empty, taking all of the party's nodes out of the swarm, is written with + `--force` only. The client checks first that the current version names the key it + signs with for the party, and says otherwise: then only a version naming the party's keys or its list anew changes it, which a party proposes and the parties pass. A version names a party's list anew only where it must: when the party is let in, or when it can't write its own. diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md index 6f9fc10..7f5bd7a 100644 --- a/docs/guides/federation/keys.md +++ b/docs/guides/federation/keys.md @@ -18,16 +18,17 @@ So keep the keys a version names apart, offline, on one machine with the party's ```sh ssh-keygen -t ed25519 -N '' -f laptop.key continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \ - keys "$(cat laptop.key.pub)" "$(cat desk.key.pub)" + keys --set "$(cat laptop.key.pub)" "$(cat desk.key.pub)" continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \ --record tv.record write home/tv/motd '"from the laptop"' ``` -Each key goes as one argument, an `authorized_keys` line; its comment is left out. With -`--add` and `--remove` instead, the client writes the set as it counts at the node with -those keys added or taken off (`keys --add "$(cat phone.pub)"`). A set holds up to 16 -keys, signed with a key the current version names for the party, which the client checks -first. A node voting by itself keeps a key its version names on that +Each key goes as one argument, an `authorized_keys` line; its comment is left out. +`--set` writes the set whole; `--add` and `--remove` write it as it counts at the node, +with those keys added or taken off (`keys --add "$(cat phone.pub)"`); `keys` alone shows +it. A set left empty, so that none of the party's writes count, is written with +`--force` only. A set holds up to 16 keys, signed with a key the current version names +for the party, which the client checks first. A node voting by itself keeps a key its version names on that node (`--store-vote-key`), an Ed25519 key in a file: one stolen there votes for the party. @@ -69,7 +70,7 @@ A write counts only while the key that signed it is among the party's keys: what signed counts no more once the party's set drops it, wherever in history it is. So before dropping a key, sign again with a new one what should stay: -1. Write a set with the new keys beside the old. +1. Add the new keys to the set, beside the old (`keys --add`). 2. Write again, with a new key, every value the party wants kept, on heads that hold that set (the client signs on the heads its node shows). For a namespace: @@ -82,7 +83,7 @@ before dropping a key, sign again with a new one what should stay: done ``` -3. Write a set without the old keys. +3. Take the old keys off the set (`keys --remove`). A key added back, from a backup say, brings back what it signed, where nothing the party signed since replaced it and no checkpoint left it out. diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md index 371bd10..a423376 100644 --- a/docs/guides/federation/running-a-node.md +++ b/docs/guides/federation/running-a-node.md @@ -52,7 +52,7 @@ with it (`This node is a member of its store`). A party that takes a node off it takes it out of the swarm. A party writes its node list itself, without a vote, signed with a key its version names -(`continuum-party nodes`, +(`continuum-party nodes --add`, [`common-changes.md`](common-changes.md#what-a-party-does-by-itself)): a node it adds is a member as soon as the list is taken. diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md index e4a3b81..de2e34a 100644 --- a/docs/guides/federation/when-things-go-wrong.md +++ b/docs/guides/federation/when-things-go-wrong.md @@ -71,8 +71,8 @@ record. document (yet)`), or its document's root is no store's (`The document's root is no store's: not reading it`). * **Nobody syncs with it** (`This node isn't a member of its store`): its party's node - list doesn't name it, as the store reads now. The party writes its list - (`continuum-party nodes`), through any member. + list doesn't name it, as the store reads now. The party adds it to its list + (`continuum-party nodes --add`), through any member. * **An event waits** (`waiting` when put): the node lacks an event it builds on. It takes it once that one arrives. * **It doesn't start**: its store file doesn't read, or an option of a swarm that isn't diff --git a/src/federation/party.rs b/src/federation/party.rs index 9a74556..788bde9 100644 --- a/src/federation/party.rs +++ b/src/federation/party.rs @@ -10,9 +10,10 @@ //! FILE`, from the file the store's swarm starts from, for a party that never voted in //! it: the record casts on every version, the first too; //! * `write PATH VALUE`: writes `VALUE` (JSON) at `PATH`; -//! * `keys KEY...`, `nodes NODE...`: writes the party's key set (`authorized_keys` lines, -//! each one argument, their comments left out) or node list (node IDs); with `--add` and -//! `--remove`, the set or list as it counts at the node, changed; +//! * `keys`, `nodes`: the party's key set (`authorized_keys` lines, each one argument, +//! their comments left out) or node list (node IDs) as it counts at the node, one a line +//! (`--list`); or written: with `--add` and `--remove`, the set or list as it counts, +//! changed; with `--set`, set whole. One left empty is written with `--force` only; //! * `next`: the version after the current one, to change and propose: the current one //! numbered on, naming its hash, without its checkpoint (JSON), to standard output; //! * `propose FILE`: proposes the version `FILE` holds (JSON), where it changes the @@ -43,7 +44,7 @@ use std::collections::BTreeSet; use std::path::{Path, PathBuf}; use anyhow::{Context, Result, anyhow, bail}; -use clap::{Arg, ArgAction, ArgMatches, Command}; +use clap::{Arg, ArgAction, ArgGroup, ArgMatches, Command}; use ed25519_dalek::SigningKey; use serde::Deserialize; use serde_json::Value as JsonValue; @@ -100,24 +101,21 @@ fn command() -> Command { ) .subcommand( Command::new("keys") - .about("Writes the party's key set: these keys, or the set as it counts, changed") - .arg( - Arg::new("keys") - .num_args(1..) - .required_unless_present_any(["add", "remove"]) - .conflicts_with_all(["add", "remove"]), + .about( + "The party's key set as it counts at the node, or written with keys added, \ + taken off, or set whole", ) - .args(changing("KEY", "keys")), + .args(changing("KEY", "keys", "key set")) + .group(changes()), ) .subcommand( Command::new("nodes") - .about("Writes the party's node list: these nodes, or the list as it counts, changed") - .arg( - Arg::new("nodes") - .num_args(0..) - .conflicts_with_all(["add", "remove"]), + .about( + "The party's node list as it counts at the node, or written with nodes \ + added, taken off, or set whole", ) - .args(changing("NODE", "nodes")), + .args(changing("NODE", "nodes", "node list")) + .group(changes()), ) .subcommand(Command::new("next").about( "The version after the current one, to change and propose: numbered on, naming the \ @@ -179,17 +177,27 @@ fn command() -> Command { ) } -/// `--add` and `--remove`, of the party's key set or node list as it counts: `what`, of -/// values named `value`. -fn changing(value: &'static str, what: &str) -> [Arg; 2] { +/// What lists or changes the party's key set or node list (`whole`), of `items` named +/// `value`: `--list`, as it counts, what the command does given none of the others; +/// `--add` and `--remove`, changing it as it counts; `--set`, setting it whole; `--force`, +/// writing it empty. +fn changing(value: &'static str, items: &str, whole: &str) -> [Arg; 5] { [ + Arg::new("list") + .long("list") + .action(ArgAction::SetTrue) + .conflicts_with("changes") + .help(format!( + "Shows the party's {whole} as it counts at the node, one a line: what the \ + command does given nothing" + )), Arg::new("add") .long("add") .value_name(value) .num_args(1..) .action(ArgAction::Append) .help(format!( - "Adds these {what} to the party's, as they count at the node" + "Adds these {items} to the party's {whole}, as it counts at the node" )), Arg::new("remove") .long("remove") @@ -197,11 +205,32 @@ fn changing(value: &'static str, what: &str) -> [Arg; 2] { .num_args(1..) .action(ArgAction::Append) .help(format!( - "Takes these {what} off the party's, as they count at the node" + "Takes these {items} off the party's {whole}, as it counts at the node" + )), + Arg::new("set") + .long("set") + .value_name(value) + .num_args(0..) + .action(ArgAction::Append) + .conflicts_with_all(["add", "remove"]) + .help(format!("Sets the party's {whole} to these {items}, whole")), + Arg::new("force") + .long("force") + .action(ArgAction::SetTrue) + .requires("changes") + .help(format!( + "Writes the party's {whole} where the change leaves it empty" )), ] } +/// What changes a key set or node list: `--add`, `--remove`, `--set`. +fn changes() -> ArgGroup { + ArgGroup::new("changes") + .args(["add", "remove", "set"]) + .multiple(true) +} + /// Runs the client, as its arguments say. pub(crate) async fn main() -> Result<()> { let matches = command().get_matches(); @@ -316,6 +345,13 @@ pub(crate) async fn main() -> Result<()> { return Ok(()); } let mut record = Record::load(&path).map_err(|why| anyhow!(why))?; + // The party's key set or node list as it counts, given no change: no key needed. + if matches!(name, "keys" | "nodes") && !sub.contains_id("changes") { + for item in listed(&node.counts().await?, &record.party, name) { + println!("{item}"); + } + return Ok(()); + } let key = signing_key(&options)?; let signer = Signer { key, @@ -351,12 +387,15 @@ pub(crate) async fn main() -> Result<()> { }; let counts = node.counts().await?; signer.named_by(¤t(&counts)?)?; + let party = &signer.party; let keys = changed( - listed(&counts, &signer.party, "keys"), - spelled("keys")?, + listed(&counts, party, "keys"), + sub.contains_id("set").then(|| spelled("set")).transpose()?, spelled("add")?, spelled("remove")?, - &format!("{}'s key set", signer.party), + sub.get_flag("force"), + &format!("{party}'s key set"), + &format!("none of {party}'s writes would count"), )?; sign(&node, &signer, &mut record, &path, event::keys(&keys)).await } @@ -370,12 +409,15 @@ pub(crate) async fn main() -> Result<()> { }; let counts = node.counts().await?; signer.named_by(¤t(&counts)?)?; + let party = &signer.party; let nodes = changed( - listed(&counts, &signer.party, "nodes"), - given("nodes")?, + listed(&counts, party, "nodes"), + sub.contains_id("set").then(|| given("set")).transpose()?, given("add")?, given("remove")?, - &format!("{}'s node list", signer.party), + sub.get_flag("force"), + &format!("{party}'s node list"), + &format!("none of {party}'s nodes would be members"), )?; sign(&node, &signer, &mut record, &path, event::nodes(&nodes)).await } @@ -423,21 +465,26 @@ fn listed(counts: &JsonValue, party: &str, what: &str) -> Vec<String> { .collect() } -/// The key set or node list to write: `given` where neither `add` nor `remove` names any, -/// else `now`, as it counts, with `add` added and `remove` taken off, each of which must -/// change it (`what` names it in the error otherwise). Said where it is changed, before it +/// The key set or node list to write: `set`, where given, else `now`, as it counts, with +/// `add` added and `remove` taken off, each of which must change it. Left empty, only with +/// `force`, as then `empty` (`what` names the set or list in the errors). Said before it /// is signed. fn changed( now: Vec<String>, - given: Vec<String>, + set: Option<Vec<String>>, add: Vec<String>, remove: Vec<String>, + force: bool, what: &str, + empty: &str, ) -> Result<Vec<String>> { - if add.is_empty() && remove.is_empty() { - return Ok(given); + let mut list = Vec::new(); + for item in set.unwrap_or(now) { + if list.contains(&item) { + bail!("{what} would hold {item} twice"); + } + list.push(item); } - let mut list = now; for item in add { if list.contains(&item) { bail!("{what} holds {item} already"); @@ -450,6 +497,9 @@ fn changed( }; list.remove(at); } + if list.is_empty() && !force { + bail!("{what} would be empty: {empty}. --force writes it so"); + } let shown = if list.is_empty() { "none".to_owned() } else { @@ -974,8 +1024,8 @@ mod tests { assert!(why.contains("OpenSSH private key"), "{why}"); } - /// A key set or node list changed as it counts: each name added absent, each taken off - /// held; named whole, it is as named. + /// A key set or node list changed as it counts: each item added absent, each taken off + /// held; set whole, it is as set, none twice; left empty only by force. #[test] fn a_list_changed_as_it_counts() { use super::changed; @@ -983,20 +1033,34 @@ mod tests { items.iter().map(|item| (*item).to_owned()).collect() }; let now = list(&["a", "b"]); - let changed_by = |given: &[&str], add: &[&str], remove: &[&str]| { + let changed_by = |set: Option<&[&str]>, add: &[&str], remove: &[&str], force: bool| { + let set = set.map(list); + let (add, remove) = (list(add), list(remove)); changed( now.clone(), - list(given), - list(add), - list(remove), + set, + add, + remove, + force, "tv's list", + "nothing left", ) }; - assert_eq!(changed_by(&["c"], &[], &[]).unwrap(), list(&["c"])); - assert_eq!(changed_by(&[], &["c"], &["a"]).unwrap(), list(&["b", "c"])); - assert_eq!(changed_by(&[], &[], &["a", "b"]).unwrap(), list(&[])); - assert!(changed_by(&[], &["a"], &[]).is_err()); - assert!(changed_by(&[], &[], &["c"]).is_err()); + assert_eq!( + changed_by(Some(&["c"]), &[], &[], false).unwrap(), + list(&["c"]) + ); + assert_eq!( + changed_by(None, &["c"], &["a"], false).unwrap(), + list(&["b", "c"]) + ); + assert!(changed_by(None, &["a"], &[], false).is_err()); + assert!(changed_by(None, &[], &["c"], false).is_err()); + assert!(changed_by(Some(&["c", "c"]), &[], &[], false).is_err()); + assert!(changed_by(None, &[], &["a", "b"], false).is_err()); + assert!(changed_by(Some(&[]), &[], &[], false).is_err()); + assert_eq!(changed_by(None, &[], &["a", "b"], true).unwrap(), list(&[])); + assert_eq!(changed_by(Some(&[]), &[], &[], true).unwrap(), list(&[])); } /// Votes, proposals, key sets and node lists are signed with a key the current version |
