//! `continuum-party status`: everything about the federation at a node but the values //! (`values`, `get`). The store; the node; the current version; every party's keys and //! nodes, when the node last heard from each and what each runs; the proposals on the //! current version, how they stand and what each does; what the node refused of its own; //! and the party the client works as: its key, its record against the node, what it signs //! again; with what may keep votes away. //! //! As people read it, in colours on a terminal (`Paint`), which may change from release to //! release; with `--json`, the same as one JSON object (`model`), of a format versioned by //! its `format` (`FORMAT`). use std::collections::BTreeSet; use std::path::Path; use anyhow::{Result, anyhow}; use serde_json::{Value as JsonValue, json}; use super::{ Given, LATELY, Node, Options, current, cut_off, given_key, listed, proposal_hashes, unrecorded, version_lines, }; use crate::access::sshsig::PublicKey; use crate::federation::client::{self, Record}; use crate::federation::event::{Does, Event, Signed}; use crate::federation::store::Id; use crate::federation::version::Version; /// The version of `--json`'s format: raised with every change to it that isn't an /// addition. pub(super) const FORMAT: u64 = 1; /// Says what the node and the party's record say, as people read it or with `json` as one /// JSON object; of `party`, where the client works as one (else the node's). pub(super) async fn status( node: &Node, options: &Options, party: Option<&str>, json: bool, ) -> Result<()> { let model = model(node, options, party).await?; if json { println!("{}", serde_json::to_string_pretty(&model)?); return Ok(()); } for line in render(&model, &Paint::detect()) { println!("{line}"); } Ok(()) } /// What `status` says, as one JSON object of `FORMAT`. async fn model(node: &Node, options: &Options, party: Option<&str>) -> Result { let summary = node.get("/events").await?; let counts = node.counts().await?; let refused = node.get("/events/refused").await?; let current = current(&counts)?; let needed = (2 * current.parties.len()).div_ceil(3); let parties: serde_json::Map = current .parties .iter() .map(|(name, given)| { let of = &counts["parties"][name]; let nodes: Vec = listed(&counts, name, "nodes") .iter() .map(|id| { json!({ "id": id, "name": of["names"][id], "here": summary["node"].as_str() == Some(id.as_str()), "heard": of["heard"][id], "knows": of["knows"][id], }) }) .collect(); ( name.clone(), json!({ "keys": given.keys, "keySet": listed(&counts, name, "keys"), "nodes": nodes, }), ) }) .collect(); let mut proposals = Vec::new(); for hash in proposal_hashes(&counts) { proposals.push(proposal(node, &counts, ¤t, &hash).await?); } let revisions: Vec<&JsonValue> = summary["revisions"] .as_array() .into_iter() .flatten() .map(|revision| &revision["named"]) .collect(); let party = party .map(str::to_owned) .or_else(|| summary["party"].as_str().map(str::to_owned)); let you = match &party { Some(party) => Some(you(&counts, ¤t, &refused, options, party)?), None => None, }; let warnings = party .as_deref() .map(|party| cut_off(&counts, party)) .unwrap_or_default(); Ok(json!({ "format": FORMAT, "store": { "id": summary["store"], "checkpoint": summary["checkpoint"], "heads": summary["heads"].as_array().map_or(0, Vec::len), "taken": summary["taken"], "stopped": summary["stopped"], }, "node": { "id": summary["node"], "party": summary["party"], "votesByItself": summary["votesByItself"], "revisions": revisions, }, "version": { "number": current.number, "hash": current.hash.to_string(), "federation": counts["version"]["version"]["federation"], "revision": counts["version"]["revision"], "parties": current.parties.len(), "needed": needed, }, "parties": parties, "proposals": proposals, "refused": {"own": refused["own"]}, "you": you, "warnings": warnings, })) } /// The proposal of `hash` on `current`, as `counts` reads it and the event proposing it /// says: how it stands (`open`, `passed`, `dead`), how many more `true` pass it, who voted /// what and who not yet; who proposed it and what its version does (`version_lines`); of /// a checkpoint, how much moving there refuses; why no client backs it, where none does. async fn proposal( node: &Node, counts: &JsonValue, current: &Version, hash: &str, ) -> Result { let ballot = &counts["proposals"][hash]; let names = |what: &str| -> Vec { ballot[what] .as_array() .into_iter() .flatten() .filter_map(|party| party.as_str().map(str::to_owned)) .collect() }; let (yes, no) = (names("yes"), names("no")); let not_yet: Vec<&String> = current .parties .keys() .filter(|party| !yes.contains(party) && !no.contains(party)) .collect(); let standing = if ballot["passed"].as_bool() == Some(true) { "passed" } else if ballot["dead"].as_bool() == Some(true) { "dead" } else { "open" }; let needed = (2 * current.parties.len()).div_ceil(3); let mut model = json!({ "hash": hash, "standing": standing, "needed": needed, "more": needed.saturating_sub(yes.len()), "yes": yes, "no": no, "notYet": not_yet, "proposedBy": null, "number": null, "does": [], "beside": ballot["beside"].as_array().map(Vec::len), "none": ballot["none"], }); let Some(id) = ballot["proposals"][0].as_str().and_then(Id::from_hex) else { return Ok(model); }; if let Some(Event::Signed(Signed { party, does: Does::Proposal { hash: of, version }, .. })) = Event::read(&node.event(&id).await?) && of.to_string() == hash { model["proposedBy"] = party.into(); match client::backable(current, &version) { Ok(proposed) => { model["number"] = proposed.number.into(); model["does"] = version_lines(counts, current, &proposed).into(); } Err(why) => model["none"] = why.into(), } } Ok(model) } /// The party the client works as: its `--key`, whether the version names it or it is of /// the party's key set; its record held against the node's votes (`unrecorded`); and how /// many of its latest events a move refused, which `again` signs again. fn you( counts: &JsonValue, current: &Version, refused: &JsonValue, options: &Options, party: &str, ) -> Result { let key = options .key .as_deref() .and_then(|given| given_key(given).ok()) .map(|given| match given { Given::Private(key) => PublicKey(key.verifying_key().to_bytes()).line(), Given::Public(key, _) => key.line(), }); let named = current .parties .get(party) .map(|given| given.keys.clone()) .unwrap_or_default(); let set = listed(counts, party, "keys"); let record = options .record .as_deref() .map(Path::new) .filter(|path| path.exists()) .map(|path| Record::load(path).map(|record| (path, record))) .transpose() .map_err(|why| anyhow!(why))? .filter(|(_, record)| record.party == party); let moved: BTreeSet = refused["refused"] .as_array() .into_iter() .flatten() .filter(|entry| matches!(entry["kind"].as_str(), Some("notAbove" | "builtOn"))) .filter_map(|entry| entry["id"].as_str().and_then(Id::from_hex)) .collect(); Ok(json!({ "party": party, "isParty": current.parties.contains_key(party), "key": key.map(|line| json!({ "key": line, "named": named.contains(&line), "inKeySet": set.contains(&line), })), "record": record.as_ref().map(|(path, record)| { let (theirs, ours) = unrecorded(counts, current, record); json!({ "path": path.display().to_string(), "agrees": theirs.is_empty(), "unrecorded": theirs, "notShown": ours, }) }), "again": record .as_ref() .map(|(_, record)| record.again(|id| moved.contains(id)).len()), })) } /// How many colours the terminal shows. #[derive(Clone, Copy, Debug, PartialEq, Eq)] enum Colours { None, /// The eight of ANSI, bright or not. Basic, Ansi256, True, } /// What a part of what `status` says is, for its colour. #[derive(Clone, Copy, Debug)] enum Style { /// A section's heading. Heading, Party, /// A node's name. Name, /// An ID or a hash. Id, Good, Warn, Bad, /// Nothing there: `nobody`, `none`. Quiet, } /// Colours for a terminal of so many (`Colours`). struct Paint(Colours); impl Paint { /// As standard output shows them: none where it is no terminal, `NO_COLOR` is set, or /// `TERM` is `dumb`; true colour where `COLORTERM` says so; 256 where `TERM` does; /// else the basic eight. fn detect() -> Paint { use std::io::IsTerminal; let var = |name: &str| std::env::var(name).unwrap_or_default(); let colours = if !std::io::stdout().is_terminal() || std::env::var_os("NO_COLOR").is_some_and(|value| !value.is_empty()) || var("TERM") == "dumb" { Colours::None } else if matches!(var("COLORTERM").as_str(), "truecolor" | "24bit") { Colours::True } else if var("TERM").contains("256color") { Colours::Ansi256 } else { Colours::Basic }; Paint(colours) } /// The SGR parameters of `style`, as this terminal shows colours. fn code(&self, style: Style) -> &'static str { use Colours::{Ansi256, Basic, None, True}; match (self.0, style) { (None, _) => "", (_, Style::Heading) => "1", (True, Style::Party) => "1;38;2;95;175;215", (Ansi256, Style::Party) => "1;38;5;74", (Basic, Style::Party) => "1;36", (True, Style::Name) => "38;2;95;175;215", (Ansi256, Style::Name) => "38;5;74", (Basic, Style::Name) => "36", (True, Style::Id) => "38;2;138;138;138", (Ansi256, Style::Id) => "38;5;245", (Basic, Style::Id) => "90", (True, Style::Good) => "38;2;95;175;95", (Ansi256, Style::Good) => "38;5;71", (Basic, Style::Good) => "32", (True, Style::Warn) => "38;2;215;175;95", (Ansi256, Style::Warn) => "38;5;179", (Basic, Style::Warn) => "33", (True, Style::Bad) => "1;38;2;215;95;95", (Ansi256, Style::Bad) => "1;38;5;167", (Basic, Style::Bad) => "1;31", (_, Style::Quiet) => "2", } } fn paint(&self, style: Style, text: &str) -> String { match self.code(style) { "" => text.to_owned(), code => format!("\x1b[{code}m{text}\x1b[0m"), } } /// `hash`, its first `length` digits, which name it among those shown, in bold. fn marked(&self, hash: &str, length: usize) -> String { let (named, rest) = hash.split_at(length.min(hash.len())); format!( "{}{}", self.paint(Style::Heading, named), self.paint(Style::Id, rest) ) } } /// `n` and `one` or `many`, as `n` asks. fn counted(n: u64, one: &str, many: &str) -> String { format!("{n} {}", if n == 1 { one } else { many }) } /// How long ago, in seconds, said: `12 s ago`, `4 min ago`, `3 h ago`, `2 d ago`. fn ago(seconds: u64) -> String { match seconds { 0..120 => format!("{seconds} s ago"), 120..7200 => format!("{} min ago", seconds / 60), 7200..172_800 => format!("{} h ago", seconds / 3600), _ => format!("{} d ago", seconds / 86_400), } } /// What a node said it runs (`knows`, `speaking::shown`): its wire versions and the /// newest revision it knows. fn runs(knows: &JsonValue) -> Option { let wire = knows["wire"].as_array()?; let (oldest, newest) = (wire.first()?.as_u64()?, wire.last()?.as_u64()?); let wire = if oldest == newest { format!("wire {newest}") } else { format!("wire {oldest} to {newest}") }; Some(match knows["revision"]["named"].as_str() { Some(revision) => format!("{wire}; {revision}"), None => format!("{wire}; no federation"), }) } /// Names `list` holds, by `, `; `nobody` where it holds none. fn names(paint: &Paint, list: &JsonValue) -> String { let names: Vec = list .as_array() .into_iter() .flatten() .filter_map(JsonValue::as_str) .map(|name| paint.paint(Style::Party, name)) .collect(); if names.is_empty() { paint.paint(Style::Quiet, "nobody") } else { names.join(", ") } } /// `model` as people read it, a line each, its parts in colours by `paint`. fn render(model: &JsonValue, paint: &Paint) -> Vec { let mut out = Vec::new(); let heading = |text: &str| paint.paint(Style::Heading, text); let text = |value: &JsonValue| value.as_str().unwrap_or_default().to_owned(); let number = |value: &JsonValue| value.as_u64().unwrap_or_default(); let store = &model["store"]; out.push(format!( "{} {}", heading("store"), paint.paint(Style::Id, &text(&store["id"])) )); out.push(format!( " checkpoint {}", paint.paint(Style::Id, &text(&store["checkpoint"])) )); out.push(format!( " {}, {} taken after the checkpoint", counted(number(&store["heads"]), "head", "heads"), counted(number(&store["taken"]), "event", "events") )); if store["stopped"].is_object() { out.push(format!( " {}", paint.paint( Style::Bad, &format!( "stopped at {}: {}", text(&store["stopped"]["id"]), text(&store["stopped"]["why"]) ) ) )); } let node = &model["node"]; out.push(heading("the node")); out.push(match node["party"].as_str() { Some(party) => format!( " {}'s{}", paint.paint(Style::Party, party), if node["votesByItself"].as_bool() == Some(true) { ", voting for it by itself" } else { "" } ), None => format!(" {}", paint.paint(Style::Quiet, "of no party")), }); let revisions: Vec = node["revisions"] .as_array() .into_iter() .flatten() .map(text) .collect(); out.push(format!(" knows {}", revisions.join(", "))); let version = &model["version"]; out.push(format!( "{} {} ({})", heading("version"), number(&version["number"]), paint.paint(Style::Id, &text(&version["hash"])) )); out.push(format!( " federation {}, {}", version["federation"], text(&version["revision"]["named"]) )); out.push(format!( " {}, {} passing a change", counted(number(&version["parties"]), "party", "parties"), number(&version["needed"]) )); let key = model["you"]["key"]["key"].as_str(); out.push(heading("parties")); for (name, party) in model["parties"].as_object().into_iter().flatten() { out.push(format!(" {}", paint.paint(Style::Party, name))); let key_line = |line: &JsonValue| { let line = text(line); let mark = if key == Some(line.as_str()) { format!(" {}", paint.paint(Style::Good, "(--key)")) } else { String::new() }; format!(" {}{mark}", client::fingerprint(&line)) }; out.push(" keys the version names (votes, proposals, key set, node list):".to_owned()); out.extend(party["keys"].as_array().into_iter().flatten().map(key_line)); if party["keySet"] == party["keys"] { out.push(" keys of its key set (writes): the same".to_owned()); } else { out.push(" keys of its key set (writes):".to_owned()); out.extend( party["keySet"] .as_array() .into_iter() .flatten() .map(key_line), ); } let nodes = party["nodes"].as_array().cloned().unwrap_or_default(); if nodes.is_empty() { out.push(format!(" nodes: {}", paint.paint(Style::Quiet, "none"))); } else { out.push(" nodes:".to_owned()); } for node in &nodes { let name = match node["name"].as_str() { Some(name) => format!(" ({})", paint.paint(Style::Name, name)), None => String::new(), }; out.push(format!( " {}{name}", paint.paint(Style::Id, &text(&node["id"])) )); let heard = match node["heard"].as_u64() { _ if node["here"].as_bool() == Some(true) => paint.paint(Style::Good, "this node"), Some(seconds) if seconds <= LATELY => { paint.paint(Style::Good, &format!("heard {}", ago(seconds))) } Some(seconds) => paint.paint(Style::Warn, &format!("heard {}", ago(seconds))), None => paint.paint(Style::Bad, "not heard from since the node started"), }; let runs = runs(&node["knows"]) .map(|runs| format!("; {runs}")) .unwrap_or_else(|| { format!( "; {}", paint.paint(Style::Quiet, "said nothing of what it runs") ) }); out.push(format!(" {heard}{runs}")); } } let proposals = model["proposals"].as_array().cloned().unwrap_or_default(); let on = number(&version["number"]); if proposals.is_empty() { out.push(format!( "{} on version {on}: {}", heading("proposals"), paint.paint(Style::Quiet, "none") )); } else { out.push(format!("{} on version {on}", heading("proposals"))); } let hashes: Vec = proposals.iter().map(|p| text(&p["hash"])).collect(); let hashes: Vec<&str> = hashes.iter().map(String::as_str).collect(); let lengths = client::prefixes(&hashes); for (proposal, length) in proposals.iter().zip(lengths) { let standing = match proposal["standing"].as_str() { Some("passed") => paint.paint(Style::Good, "passed"), Some("dead") => paint.paint(Style::Bad, "dead"), _ => paint.paint( Style::Warn, &format!( "can still pass, {} more `true` passing it ({} of {})", number(&proposal["more"]), number(&proposal["needed"]), number(&version["parties"]) ), ), }; out.push(format!( " {}: {standing}", paint.marked(&text(&proposal["hash"]), length) )); out.push(format!( " true: {}; false: {}; not yet: {}", names(paint, &proposal["yes"]), names(paint, &proposal["no"]), names(paint, &proposal["notYet"]) )); if let Some(by) = proposal["proposedBy"].as_str() { match proposal["number"].as_u64() { Some(number) => out.push(format!( " proposed by {}: version {number} on {on}", paint.paint(Style::Party, by) )), None => out.push(format!(" proposed by {}", paint.paint(Style::Party, by))), } } for line in proposal["does"].as_array().into_iter().flatten() { out.push(format!(" {}", text(line))); } match proposal["beside"].as_u64() { Some(0) => out.push(" moving there refuses nothing this node took".to_owned()), Some(n) => out.push(format!( " {}", paint.paint( Style::Warn, &format!( "moving there refuses {n} of the writes, key sets and node lists this \ node took, which their parties sign again" ) ) )), None => {} } if let Some(why) = proposal["none"].as_str() { out.push(format!( " {}", paint.paint(Style::Bad, &format!("backed by no client: {why}")) )); } } out.push(heading("refused")); match model["refused"]["own"].as_array().map_or(0, Vec::len) { 0 => out.push(format!( " {}", paint.paint(Style::Good, "no version event of its own") )), n => out.push(format!( " {}", paint.paint( Style::Bad, &format!( "{} by what the node took before: keys may have voted twice, and nodes be \ apart (GET /events/refused)", counted(n as u64, "version event", "version events") ) ) )), } let you = &model["you"]; if let Some(party) = you["party"].as_str() { out.push(format!( "{} {}", heading("you:"), paint.paint(Style::Party, party) )); if you["isParty"].as_bool() != Some(true) { out.push(format!( " {}", paint.paint(Style::Bad, &format!("no party of version {on}")) )); } if let Some(line) = you["key"]["key"].as_str() { let (style, what) = match ( you["key"]["named"].as_bool() == Some(true), you["key"]["inKeySet"].as_bool() == Some(true), ) { (true, true) => ( Style::Good, "the version names it, and it is of the key set", ), (true, false) => ( Style::Good, "the version names it: votes, proposals, key set, node list", ), (false, true) => (Style::Good, "of the key set: writes"), (false, false) => (Style::Bad, "none of the party's keys: it signs nothing"), }; out.push(format!( " --key {}: {}", client::fingerprint(line), paint.paint(style, what) )); } let record = &you["record"]; match record["path"].as_str() { None => out.push(format!( " {}", paint.paint(Style::Quiet, "no record: reading only, as votes go by one") )), Some(path) => { let unrecorded: Vec = record["unrecorded"] .as_array() .into_iter() .flatten() .map(text) .collect(); if unrecorded.is_empty() { out.push(format!( " record {path}: {}", paint.paint(Style::Good, "agrees with the node") )); } else { out.push(format!( " record {path}: {}", paint.paint( Style::Bad, &format!( "lacks votes the node shows: {}: `restore` takes them in", unrecorded.join(", ") ) ) )); } let not_shown: Vec = record["notShown"] .as_array() .into_iter() .flatten() .map(text) .collect(); if !not_shown.is_empty() { out.push(format!( " {}", paint.paint( Style::Warn, &format!( "the node doesn't show the record's {} yet", not_shown.join(", ") ) ) )); } } } if let Some(again) = you["again"].as_u64().filter(|again| *again > 0) { out.push(format!( " {}", paint.paint( Style::Warn, &format!( "{} a move refused: `again` signs {} again", counted(again, "event", "events"), if again == 1 { "it" } else { "them" } ) ) )); } } let warnings = model["warnings"].as_array().cloned().unwrap_or_default(); if !warnings.is_empty() { out.push(heading("warnings")); for warning in &warnings { out.push(format!(" {}", paint.paint(Style::Warn, &text(warning)))); } } out } #[cfg(test)] mod tests { use super::*; /// A model as `model` makes one, of two parties, a proposal and the party's own. fn sample() -> JsonValue { json!({ "format": FORMAT, "store": {"id": "6d1e", "checkpoint": "6d1e", "heads": 3, "taken": 1, "stopped": null}, "node": {"party": "lass", "votesByItself": true, "revisions": ["the base revision"]}, "version": { "number": 3, "hash": "a7c2", "federation": 1, "revision": {"named": "the base revision"}, "parties": 2, "needed": 2, }, "parties": { "lass": { "keys": ["ssh-ed25519 AAAAone"], "keySet": ["ssh-ed25519 AAAAone"], "nodes": [ { "id": "continuum:9c07", "name": "beta", "here": true, "heard": 0, "knows": {"wire": [52, 52], "revision": {"named": "the base revision"}}, }, { "id": "continuum:3b1e", "name": null, "here": false, "heard": 0, "knows": {"wire": [52, 52], "revision": null}, }, ], }, "tv": { "keys": ["ssh-ed25519 AAAAtwo"], "keySet": ["ssh-ed25519 AAAAthree"], "nodes": [ {"id": "continuum:5be1", "name": null, "here": false, "heard": LATELY + 1, "knows": null}, {"id": "continuum:77d0", "name": null, "here": false, "heard": null, "knows": null}, ], }, }, "proposals": [{ "hash": "8d02f1e3", "standing": "open", "needed": 2, "more": 1, "yes": ["tv"], "no": [], "notYet": ["lass"], "proposedBy": "tv", "number": 4, "does": ["lets makefu in: 1 key (…); no node"], "beside": null, "none": null, }], "refused": {"own": []}, "you": { "party": "tv", "isParty": true, "key": {"key": "ssh-ed25519 AAAAthree", "named": false, "inKeySet": true}, "record": { "path": "tv.record", "agrees": false, "unrecorded": ["`false` on 8d02f1e3"], "notShown": [], }, "again": 2, }, "warnings": ["the node hasn't heard from these nodes of tv lately: continuum:77d0"], }) } /// Without colours, what people read: a heading each, every party's keys and nodes, each /// node with its name, when it was heard from and what it runs; each proposal with who /// voted what and who not yet, and what it does; the party's own key, record and what /// it signs again; the warnings. #[test] fn everything_but_the_values_at_a_glance() { let lines = render(&sample(), &Paint(Colours::None)); let has = |wanted: &str| { assert!( lines.iter().any(|line| line == wanted), "{wanted:?} missing:\n{}", lines.join("\n") ); }; has("store 6d1e"); has("the node"); has(" lass's, voting for it by itself"); has("version 3 (a7c2)"); has(" 2 parties, 2 passing a change"); has(" tv"); has(" continuum:9c07 (beta)"); has(" this node; wire 52; the base revision"); // Another node heard from within the second is no less another. has(" heard 0 s ago; wire 52; no federation"); has(&format!( " heard {}; said nothing of what it runs", ago(LATELY + 1) )); has(" not heard from since the node started; said nothing of what it runs"); has(" keys of its key set (writes): the same"); has("proposals on version 3"); has(" 8d02f1e3: can still pass, 1 more `true` passing it (2 of 2)"); has(" true: tv; false: nobody; not yet: lass"); has(" proposed by tv: version 4 on 3"); has(" lets makefu in: 1 key (…); no node"); has(" no version event of its own"); has("you: tv"); has( " record tv.record: lacks votes the node shows: `false` on 8d02f1e3: `restore` takes them in", ); has(" 2 events a move refused: `again` signs them again"); has("warnings"); assert!(lines.iter().all(|line| !line.contains('\x1b'))); } /// Colours as the terminal shows them: true colour, 256, the basic eight, none. #[test] fn colours_as_the_terminal_shows_them() { assert_eq!(Paint(Colours::None).paint(Style::Bad, "x"), "x"); assert_eq!( Paint(Colours::Basic).paint(Style::Bad, "x"), "\x1b[1;31mx\x1b[0m" ); assert!( Paint(Colours::Ansi256) .paint(Style::Good, "x") .contains("38;5;") ); assert!( Paint(Colours::True) .paint(Style::Good, "x") .contains("38;2;") ); let marked = Paint(Colours::Basic).marked("8d02f1", 4); assert!(marked.starts_with("\x1b[1m8d02\x1b[0m"), "{marked:?}"); let lines = render(&sample(), &Paint(Colours::True)); assert!(lines.iter().any(|line| line.contains("\x1b["))); } #[test] fn times_ago_said() { assert_eq!(ago(12), "12 s ago"); assert_eq!(ago(240), "4 min ago"); assert_eq!(ago(3 * 3600), "3 h ago"); assert_eq!(ago(2 * 86_400), "2 d ago"); } }