diff options
| -rw-r--r-- | CHANGELOG.md | 8 | ||||
| -rw-r--r-- | docs/dashboard.md | 3 | ||||
| -rw-r--r-- | docs/guides/federation/proposing-and-voting.md | 32 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 12 | ||||
| -rw-r--r-- | src/federation/client.rs | 255 | ||||
| -rw-r--r-- | src/federation/party.rs | 223 |
6 files changed, 459 insertions, 74 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index cf54938..da25cf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ it from the release before ([`docs/operations.md`](docs/operations.md), ## Unreleased +* `continuum-party show` says what a proposal does, in words, before a vote: who voted + what, the parties let in or taken out, keys by fingerprint, rules added and dropped, a + checkpoint and what moving there refuses, a revision, who writes where after it. + `proposals` says each so, and `vote` says it, then asks on a terminal before it casts + ([`docs/guides/federation/proposing-and-voting.md`](docs/guides/federation/proposing-and-voting.md), + [Following a vote](docs/guides/federation/proposing-and-voting.md#following-a-vote); + [`src/federation/party.rs`](src/federation/party.rs)). + * `GET /events/counts` shows, of a proposed checkpoint, what moving there refuses of what the parties signed (`beside`), as the docs said a node shows ([`docs/guides/federation/checkpoints.md`](docs/guides/federation/checkpoints.md), diff --git a/docs/dashboard.md b/docs/dashboard.md index f68fb06..4ecd233 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -413,7 +413,8 @@ federation again; the page keeps the choice. While shown, it is read every 5 s: whether it passed, is dead, or can still pass; the parties voting `true` and `false`; how many events propose it and how many votes are on it; why no party's client backs it, where none does (no version as this node reads it, say); and what its version - changes of the current one, a line each, as `continuum-party proposals` says it; + changes of the current one, a line each, as `continuum-party check` says it of a fork's + version; * **refused**: what this node refused by what it took before (keys voted twice: tell its party), what it dropped as its operator says, and what it refused as every node does, each with its kind and why. diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index 739552b..d8410f6 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -196,21 +196,31 @@ curl -s -u tv:secret localhost:3000/events/counts | jq .proposals # "proposals":["c41e…"],"votes":["5a77…","e019…"],"yes":["tv"]}} ``` -The client shows the same, why it backs one not, by the federation it knows, what each -proposal's version changes of the current one, field by field and party by party, and -the places holding a value whose writer it changes (`who writes names/wiki/a: tv -> -wiki`): admitting a party named as a segment of a place is, or changing the rules or -their order, moves who writes there, rules unchanged in the first case, and what was -written there counts no more once it passes: +The client shows a proposal in words before anyone votes on it (`show`, and `proposals` +for all of them): whether it passed or is dead, who voted what and how many more `true` +pass it, who proposed it, and what its version does, not its JSON. That is the parties +it lets in or takes out, with their keys by fingerprint (as `ssh-keygen -l` gives them) +and their nodes; the keys and node lists it names anew; the rules it adds or drops, where +they are among the rules; the checkpoint it moves the store to, and what moving there +refuses of what the node took; the revision it moves to, and the nodes not known to know +it. And the places holding a value whose writer it changes (`who writes`): admitting a +party named as a segment of a place is, or changing the rules or their order, moves who +writes there, rules unchanged in the first case, and what was written there counts no +more once it passes. Where no client backs it, it says why, by the federation it knows: ```sh -continuum-party --node http://tv:secret@localhost:3000 proposals -# 8d02…: dead; true: tv; false: lass -# changes: null -> "1f4c…" -# checkpoint: - -> ["4a1d…","9e30…"] -# number: 0 -> 1 +continuum-party --node http://tv:secret@localhost:3000 show 8d02 +# 8d02…: can still pass, 1 more `true` passing it (3 of 4); true: tv, lass; false: nobody +# proposed by tv: version 2 on 1 +# lets makefu in: 1 key (ssh-ed25519 SHA256:IDPEVCc1gUXL…); 1 node (continuum:e2a8f0c1d9b3…) +# adds rule 1: names/r/wiki -> lass +# who writes names/r/wiki: tv -> lass ``` +`vote` says the same before it casts anything, then its warnings, and, on a terminal, +asks before it casts: answer `y` to cast, anything else to cast nothing. In a script, +with no terminal, it asks nothing. + A node's dashboard shows them so too, and where the node votes for its party by itself, votes through it ([`dashboard.md`](../../dashboard.md), [Federation](../../dashboard.md#federation)). diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index f6964a6..6ffde67 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -101,13 +101,13 @@ adds is refused everywhere until a version names it. 3. **Vote.** Each party backs it once every node of the party knows the revision: ```sh - continuum-party --node http://tv:secret@localhost:3000 proposals - # 5e81…: can still pass; true: tv; false: nobody - # changes: "1f4c…" -> "8a20…" - # number: 4 -> 5 - # revision: the base revision -> revision 1 (merge-events), 6c1d… + continuum-party --node http://tv:secret@localhost:3000 show 5e81 + # 5e81…: can still pass, 2 more `true` passing it (3 of 4); true: tv; false: nobody + # proposed by tv: version 5 on 4 + # moves to revision 1 (merge-events) + # not known to know revision 1 (merge-events): lass: continuum:9c07… said nothing: … continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ - --record tv.record vote 5e81… yes + --record tv.record vote 5e81 yes ``` The client backs it only where its node knows the revision, and says so otherwise. It diff --git a/src/federation/client.rs b/src/federation/client.rs index ddbc9bb..846d29c 100644 --- a/src/federation/client.rs +++ b/src/federation/client.rs @@ -395,6 +395,211 @@ pub(crate) fn backable(current: &Version, proposed: &Json) -> Result<Version, St Ok(version) } +/// What the version `proposed` does to `current`, in words, a line each: the parties it +/// lets in or takes out, the keys and node lists it names anew, the rules it adds or drops, +/// the checkpoint it moves the store to, and the revision it moves to; what a party votes +/// on, without its JSON. Its number and the hash it changes go without saying. +pub(crate) fn described(current: &Version, proposed: &Version) -> Vec<String> { + let mut lines = Vec::new(); + for (party, given) in &proposed.parties { + if !current.parties.contains_key(party) { + lines.push(format!( + "lets {party} in: {}; {}", + counted(&given.keys, "key", |key| fingerprint(key)), + counted(&given.nodes, "node", |node| node_spelled(node)), + )); + } + } + for party in current.parties.keys() { + if !proposed.parties.contains_key(party) { + lines.push(format!("takes {party} out")); + } + } + for (party, was) in ¤t.parties { + let Some(is) = proposed.parties.get(party) else { + continue; + }; + if is.keys_since != was.keys_since || is.keys != was.keys { + lines.push(format!( + "names {party}'s keys anew{}", + differing(&was.keys, &is.keys, "as they were", |key| fingerprint(key)) + )); + } + if is.nodes_since != was.nodes_since || is.nodes != was.nodes { + lines.push(format!( + "names {party}'s node list anew{}", + differing(&was.nodes, &is.nodes, "as it was", |node| node_spelled( + node + )) + )); + } + } + let spelled = |version: &Version| -> Vec<String> { + version + .rules + .iter() + .map(|rule| format!("{} -> {}", rule_path(&rule.path), rule_writer(&rule.writer))) + .collect() + }; + lines.extend(rules_changed(&spelled(current), &spelled(proposed))); + if let Some(heads) = &proposed.checkpoint { + let heads = match heads.len() { + 1 => "1 head".to_owned(), + many => format!("{many} heads"), + }; + lines.push(format!("moves the store to a checkpoint at {heads}")); + } + if proposed.revision != current.revision { + lines.push(format!("moves to {}", proposed.revision)); + } + lines +} + +/// `items` counted by `what`, each spelled by `spell`: `2 keys (a, b)`, `no node`. +fn counted<T>(items: &[T], what: &str, spell: impl Fn(&T) -> String) -> String { + match items { + [] => format!("no {what}"), + [one] => format!("1 {what} ({})", spell(one)), + many => format!( + "{} {what}s ({})", + many.len(), + many.iter().map(spell).collect::<Vec<_>>().join(", ") + ), + } +} + +/// What `after` takes in, and leaves out, of `before`, each spelled by `spell`: +/// `: + a, - b`, or `, ` and `same` where nothing differs. +fn differing( + before: &[String], + after: &[String], + same: &str, + spell: impl Fn(&String) -> String, +) -> String { + let changes: Vec<String> = after + .iter() + .filter(|item| !before.contains(item)) + .map(|item| format!("+ {}", spell(item))) + .chain( + before + .iter() + .filter(|item| !after.contains(item)) + .map(|item| format!("- {}", spell(item))), + ) + .collect(); + if changes.is_empty() { + format!(", {same}") + } else { + format!(": {}", changes.join(", ")) + } +} + +/// A key as `ssh-keygen -l` names it: its type, and the SHA-256 of its blob in base64 +/// without padding; the line itself where it isn't one. +pub(crate) fn fingerprint(line: &str) -> String { + use sha2::{Digest, Sha256}; + let mut words = line.split_whitespace(); + let (Some(kind), Some(blob)) = (words.next(), words.next()) else { + return line.to_owned(); + }; + match BASE64.decode(blob) { + Ok(bytes) => { + let digest = Sha256::digest(&bytes); + let text = base64::engine::general_purpose::STANDARD_NO_PAD.encode(digest); + format!("{kind} SHA256:{text}") + } + Err(_) => line.to_owned(), + } +} + +/// A node's ID, its first twelve hex digits enough to tell it. +fn node_spelled(node: &str) -> String { + let at = node.find(':').map_or(0, |colon| colon + 1); + match node.get(..at + 12) { + Some(start) if node.len() > at + 12 => format!("{start}…"), + _ => node.to_owned(), + } +} + +/// A rule's path as a version spells it. +fn rule_path(path: &[super::version::Segment]) -> String { + use super::version::Segment; + path.iter() + .map(|segment| match segment { + Segment::Literal(text) => text.clone(), + Segment::Party => "{party}".to_owned(), + Segment::One => "*".to_owned(), + Segment::Rest => "**".to_owned(), + }) + .collect::<Vec<_>>() + .join("/") +} + +/// Who a rule gives its places to. +fn rule_writer(writer: &super::version::Writer) -> String { + use super::version::Writer; + match writer { + Writer::Party(party) => party.clone(), + Writer::Named => "{party}".to_owned(), + Writer::Nobody => "nobody".to_owned(), + } +} + +/// The rules `after` adds and drops of `before`, each with its place among its version's +/// rules, by the longest run of rules they keep in order: a rule moved is dropped at one +/// place and added at another. Past so many rules changed at once, which rules alone. +fn rules_changed(before: &[String], after: &[String]) -> Vec<String> { + let start = before.iter().zip(after).take_while(|(a, b)| a == b).count(); + let end = before[start..] + .iter() + .rev() + .zip(after[start..].iter().rev()) + .take_while(|(a, b)| a == b) + .count(); + let (old, new) = ( + &before[start..before.len() - end], + &after[start..after.len() - end], + ); + let mut lines = Vec::new(); + if old.len().saturating_mul(new.len()) > 1 << 22 { + lines.extend( + new.iter() + .filter(|rule| !old.contains(rule)) + .map(|rule| format!("adds rule {rule}")), + ); + lines.extend( + old.iter() + .filter(|rule| !new.contains(rule)) + .map(|rule| format!("drops rule {rule}")), + ); + return lines; + } + // The longest run kept in order, from the back: kept[i][j] for old[i..] and new[j..]. + let mut kept = vec![vec![0u32; new.len() + 1]; old.len() + 1]; + for i in (0..old.len()).rev() { + for j in (0..new.len()).rev() { + kept[i][j] = if old[i] == new[j] { + kept[i + 1][j + 1] + 1 + } else { + kept[i + 1][j].max(kept[i][j + 1]) + }; + } + } + let (mut i, mut j) = (0, 0); + while i < old.len() || j < new.len() { + if i < old.len() && j < new.len() && old[i] == new[j] { + (i, j) = (i + 1, j + 1); + } else if j < new.len() && (i == old.len() || kept[i][j + 1] >= kept[i + 1][j]) { + lines.push(format!("adds rule {}: {}", start + j + 1, new[j])); + j += 1; + } else { + lines.push(format!("drops rule {}: {}", start + i + 1, old[i])); + i += 1; + } + } + lines +} + /// The fewest hex digits that name a hash in part: fewer would too soon name another, /// proposed since the part was read. pub(crate) const PREFIX: usize = 4; @@ -1059,6 +1264,56 @@ mod tests { ); } + /// A version's changes in words: a party let in and one taken out, keys named anew, + /// rules added and dropped where they are, a checkpoint and a revision; a key by its + /// fingerprint, as `ssh-keygen -l` gives it. + #[test] + fn what_a_version_does_is_said_in_words() { + assert_eq!( + fingerprint( + "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH+0RqNr1A0vrV7Ed+53/BMI50Jjcz++Bg8IG0Iiv3K1" + ), + "ssh-ed25519 SHA256:IDPEVCc1gUXLVkYd3OZhe2v4BDk7swi/Y2+Xe1gTXSU" + ); + assert_eq!(fingerprint("no key"), "no key"); + let (tv, lass, makefu) = ( + Party::new("tv", 1), + Party::new("lass", 2), + Party::new("makefu", 3), + ); + let rules = [("names/**", harness::str("tv"))]; + let read = |spec: &Spec| Version::read(&spec.json()).unwrap(); + let first = Spec::first(&[&tv, &lass], &rules); + let current = read(&first); + assert!(described(¤t, ¤t).is_empty()); + let admitted = Spec::first(&[&tv, &lass, &makefu], &rules); + assert_eq!( + described(¤t, &read(&admitted)), + [format!( + "lets makefu in: 1 key ({}); no node", + fingerprint(&makefu.key_line()) + )] + ); + let mut changed = Spec::first(&[&tv], &[]); + changed.parties[0].keys_since = 1; + changed + .rules + .insert(0, ("names/r/wiki".to_owned(), harness::str("tv"))); + changed.checkpoint = Some(vec![Id::of(b"a"), Id::of(b"b")]); + changed.revision = Revision(1); + assert_eq!( + described(¤t, &read(&changed)), + [ + "takes lass out", + "names tv's keys anew, as they were", + "adds rule 1: names/r/wiki -> tv", + "drops rule 2: names/** -> tv", + "moves the store to a checkpoint at 2 heads", + "moves to revision 1 (merge-events)", + ] + ); + } + /// Each hash is named by its shortest prefix no other has, of four digits at least, and /// found by any prefix it alone has; a whole hash is itself, a short or shared prefix /// none. diff --git a/src/federation/party.rs b/src/federation/party.rs index bacca3d..35d791e 100644 --- a/src/federation/party.rs +++ b/src/federation/party.rs @@ -193,10 +193,18 @@ fn command() -> Command { keeps (federation-tests.md, Against released revisions)", )) .subcommand(Command::new("proposals").about( - "The proposals on the current version: whether each passed or is dead, who voted \ - what, and what it changes", + "The proposals on the current version, each as show says it", )) .subcommand( + Command::new("show") + .about( + "What a proposal on the current version does, in words, before a vote: \ + who voted what, the parties, keys, nodes and rules it changes, who writes \ + where after it", + ) + .arg(id("proposal")), + ) + .subcommand( Command::new("twice") .about("Names, from records, a party that voted twice") .arg( @@ -423,6 +431,14 @@ pub(crate) async fn main() -> Result<()> { if name == "proposals" { return proposals(&node).await; } + if name == "show" { + let counts = node.counts().await?; + let proposal = proposal_named(&counts, sub)?.to_string(); + for line in preview(&node, &counts, &proposal, &proposal_hashes(&counts)).await? { + println!("{line}"); + } + return Ok(()); + } if name == "next" { let current = node.current().await?; let feature = sub.get_one::<String>("revision"); @@ -515,8 +531,22 @@ pub(crate) async fn main() -> Result<()> { } // A party that has a node vote by itself votes by hand only through it. if name == "vote" && sub.get_flag("through") { - let proposal = proposal_named(&node.counts().await?, sub)?; + let counts = node.counts().await?; + let proposal = proposal_named(&counts, sub)?; let yes = sub.get_one::<String>("yes").map(String::as_str) == Some("yes"); + let hashes = proposal_hashes(&counts); + for line in preview(&node, &counts, &proposal.to_string(), &hashes).await? { + println!("{line}"); + } + let word = if yes { "`true`" } else { "`false`" }; + let question = format!( + "Vote {word} on {}, through the node?", + marked(&proposal.to_string(), &hashes) + ); + if !confirmed(&question)? { + println!("nothing cast"); + return Ok(()); + } let answer = node .post( "/admin/events/vote", @@ -957,6 +987,11 @@ async fn vote( })) if hash == proposal => version, _ => bail!("the node's {proposing} isn't the proposal it names"), }; + // What it votes on, said before anything is cast. + let hashes = proposal_hashes(&counts); + for line in preview(node, &counts, &proposal.to_string(), &hashes).await? { + println!("{line}"); + } // A later revision: the node knows it, or it stops at the version once it passes; and // so does every other node not known to know it. if yes @@ -1029,6 +1064,14 @@ async fn vote( ); } let on = client::building(proposing, checkpoint, &kept).map_err(|why| anyhow!(why))?; + let word = if yes { "`true`" } else { "`false`" }; + if !confirmed(&format!( + "Vote {word} on {}?", + marked(&proposal.to_string(), &hashes) + ))? { + println!("nothing cast"); + return Ok(()); + } let cast = signer.sign(&on, event::vote(current.hash, proposal, yes))?; record.cast(¤t, &cast, kept); record.save(path).map_err(|why| anyhow!(why))?; @@ -1079,73 +1122,141 @@ async fn again(node: &Node, signer: &Signer, record: &mut Record, path: &Path) - Ok(()) } -/// The proposals on the current version at `node`, each with whether it passed or is dead, -/// who voted what, and what its version changes, as one of the events proposing it holds -/// it. +/// The proposals on the current version, each as `preview` says it. async fn proposals(node: &Node) -> Result<()> { let counts = node.counts().await?; - let current = current(&counts)?; - // The places holding a value, whose writer a proposal may move. - let places: Vec<&str> = counts["values"] - .as_object() - .into_iter() - .flatten() - .map(|(place, _)| place.as_str()) - .collect(); - let parties = |names: &JsonValue| -> String { - let names: Vec<&str> = names + let hashes = proposal_hashes(&counts); + for hash in &hashes { + for line in preview(node, &counts, hash, &hashes).await? { + println!("{line}"); + } + } + Ok(()) +} + +/// What a party votes on, in words: the proposal of `hash` on the current version, as +/// `counts` reads it, named among `hashes` (`marked`): whether it passed or is dead, who +/// voted what, and how many more `true` pass it; who proposed it; what its version does +/// (`client::described`); what moving to its checkpoint refuses of what this node took; +/// the places holding a value whose writer it moves; the nodes not known to know its +/// revision; and why no client backs it, where none does. +async fn preview( + node: &Node, + counts: &JsonValue, + hash: &str, + hashes: &[String], +) -> Result<Vec<String>> { + let current = current(counts)?; + let ballot = &counts["proposals"][hash]; + let names = |what: &str| -> (usize, String) { + let names: Vec<&str> = ballot[what] .as_array() .into_iter() .flatten() .filter_map(JsonValue::as_str) .collect(); - if names.is_empty() { + let spelled = if names.is_empty() { "nobody".to_owned() } else { names.join(", ") + }; + (names.len(), spelled) + }; + let ((yes, backers), (_, nays)) = (names("yes"), names("no")); + let parties = current.parties.len(); + let needed = (2 * parties).div_ceil(3); + let standing = if ballot["passed"].as_bool() == Some(true) { + "passed".to_owned() + } else if ballot["dead"].as_bool() == Some(true) { + "dead".to_owned() + } else { + let more = needed.saturating_sub(yes); + format!("can still pass, {more} more `true` passing it ({needed} of {parties})") + }; + let mut lines = vec![format!( + "{}: {standing}; true: {backers}; false: {nays}", + marked(hash, hashes) + )]; + let Some(id) = ballot["proposals"][0].as_str() else { + if let Some(why) = ballot["none"].as_str() { + lines.push(format!(" backed by no client: {why}")); } + return Ok(lines); }; - let hashes = proposal_hashes(&counts); - for (hash, proposal) in counts["proposals"].as_object().into_iter().flatten() { - let standing = match (proposal["passed"].as_bool(), proposal["dead"].as_bool()) { - (Some(true), _) => "passed", - (_, Some(true)) => "dead", - _ => "can still pass", - }; - println!( - "{}: {standing}; true: {}; false: {}", - marked(hash, &hashes), - parties(&proposal["yes"]), - parties(&proposal["no"]) - ); - let Some(id) = proposal["proposals"][0].as_str() else { - if let Some(why) = proposal["none"].as_str() { - println!(" backed by no client: {why}"); - } - continue; - }; - let id = Id::from_hex(id).ok_or_else(|| anyhow!("the node names no event ID: {id}"))?; - match Event::read(&node.event(&id).await?) { - Some(Event::Signed(Signed { - does: Does::Proposal { hash: of, version }, - .. - })) if of.to_string() == *hash => { - if let Err(why) = client::backable(¤t, &version) { - println!(" backed by no client: {why}"); - } - for line in client::changes(¤t.json, &version) { - println!(" {line}"); - } - if let Ok(proposed) = Version::read(&version) { - for line in client::writers(¤t, &proposed, places.iter().copied()) { - println!(" who writes {line}"); - } - } - } - _ => println!(" the event {id} proposes no version of that hash"), + let id = Id::from_hex(id).ok_or_else(|| anyhow!("the node names no event ID: {id}"))?; + let (party, version) = match Event::read(&node.event(&id).await?) { + Some(Event::Signed(Signed { + party, + does: Does::Proposal { hash: of, version }, + .. + })) if of.to_string() == hash => (party, version), + _ => { + lines.push(format!(" the event {id} proposes no version of that hash")); + return Ok(lines); } + }; + let proposed = match client::backable(¤t, &version) { + Ok(proposed) => proposed, + Err(why) => { + lines.push(format!(" proposed by {party}; backed by no client: {why}")); + return Ok(lines); + } + }; + lines.push(format!( + " proposed by {party}: version {} on {}", + proposed.number, current.number + )); + lines.extend( + client::described(¤t, &proposed) + .into_iter() + .map(|line| format!(" {line}")), + ); + if proposed.checkpoint.is_some() { + let beside = ballot["beside"].as_array().map_or(0, Vec::len); + lines.push(match beside { + 0 => " moving there refuses nothing this node took".to_owned(), + n => format!( + " moving there refuses {n} of the writes, key sets and node lists this node \ + took, which their parties sign again (`beside` in GET /events/counts)" + ), + }); } - Ok(()) + let places: Vec<&str> = counts["values"] + .as_object() + .into_iter() + .flatten() + .map(|(place, _)| place.as_str()) + .collect(); + lines.extend( + client::writers(¤t, &proposed, places) + .into_iter() + .map(|line| format!(" who writes {line}")), + ); + if proposed.revision != current.revision { + lines.extend( + client::unready(counts, proposed.revision) + .into_iter() + .map(|line| format!(" not known to know {}: {line}", proposed.revision)), + ); + } + Ok(lines) +} + +/// Whether the user, asked `question` where both its input and the client's errors are a +/// terminal, answers yes. Asked nothing, as in a script, it does. +fn confirmed(question: &str) -> Result<bool> { + use std::io::{BufRead, IsTerminal, Write}; + if !std::io::stdin().is_terminal() || !std::io::stderr().is_terminal() { + return Ok(true); + } + eprint!("{question} [y/N] "); + std::io::stderr().flush()?; + let mut answer = String::new(); + std::io::stdin().lock().read_line(&mut answer)?; + Ok(matches!( + answer.trim().to_ascii_lowercase().as_str(), + "y" | "yes" + )) } /// The version after `current`, to change and propose: `current` numbered on, naming its |
