aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 18:57:54 +0000
committertv <tv@krebsco.de>2026-11-19 20:13:11 +0100
commit2a8575ce6562e1579f9c9bd9c9964e3ef36d08f1 (patch)
tree39347d78deb93b431258109b8d943cc10c29c723
parentb710146b9e17d844a1e2647a2b43eeadd62893aa (diff)
continuum-party: status and values
`status` says at a glance where the party and its node stand, from the node's /events, /events/counts and /events/refused and the party's record where there is one: the store, its checkpoint and heads; the current version, its federation, revision and parties, and how many pass a change; the party's keys (by fingerprint) and nodes as they count, and whether the version names --key; the node's party, whether it votes by itself, and its stop; each proposal on the current version as `show` begins (ballot_line, shared with it); the versions the node refused of its own; and how many of the party's events a move refused, which `again` signs again. `values [PATH]` shows the values that count, all or under a place, each with who writes there by the current version's rules; --json as one object, by place.
-rw-r--r--CHANGELOG.md7
-rw-r--r--docs/guides/federation/watching.md4
-rw-r--r--docs/guides/federation/writing-and-reading.md8
-rw-r--r--src/federation/party.rs297
4 files changed, 287 insertions, 29 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7840755..0f615be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,13 @@ it from the release before ([`docs/operations.md`](docs/operations.md),
## Unreleased
+* `continuum-party status` says at a glance where the party and its node stand: the
+ store and its version, the party's keys and nodes, a stop, the proposals, refused
+ versions, and what to sign again; `values [PATH]` shows what counts, with who writes
+ there ([`docs/guides/federation/watching.md`](docs/guides/federation/watching.md),
+ [`docs/guides/federation/writing-and-reading.md`](docs/guides/federation/writing-and-reading.md);
+ [`src/federation/party.rs`](src/federation/party.rs)).
+
* `continuum-party fork` takes the changes `propose` does, or a proposal's version
(`fork proposal PROPOSAL`), forking at the heads the node shows unless others are named
(`--at`); `--founder PARTY=NODE,…` names a founder's node list anew in the fork
diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md
index 9db3399..d99d36c 100644
--- a/docs/guides/federation/watching.md
+++ b/docs/guides/federation/watching.md
@@ -7,6 +7,10 @@ store, through its API and its log.
## Through the API
+`continuum-party status` says most of what follows at a glance: the store and its
+version, the party's keys and nodes, the node's stop, the proposals on the current version,
+the versions the node refused of its own, and what the party signs again after a move.
+
* **A version the node refused** (`own` in `GET /events/refused` not empty): keys voted
twice, and nodes may be apart. Act on it at once
([`when-things-go-wrong.md`](when-things-go-wrong.md)).
diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md
index d45bf0d..abd5221 100644
--- a/docs/guides/federation/writing-and-reading.md
+++ b/docs/guides/federation/writing-and-reading.md
@@ -94,6 +94,14 @@ Votes and proposals aren't signed again: their version is behind.
## Reading
+The client shows the values that count, each with who writes there, all or under a
+place (`--json` as one object, by place):
+
+```sh
+continuum-party --node http://lass:secret@localhost:3000 values home/tv
+# home/tv/motd "hello" (tv)
+```
+
`GET /events/counts` is what counts, as the node reads it now:
* `version`: the current version, its `number`, its `hash`, and the version itself;
diff --git a/src/federation/party.rs b/src/federation/party.rs
index 4b7820f..9a77829 100644
--- a/src/federation/party.rs
+++ b/src/federation/party.rs
@@ -30,6 +30,9 @@
//! twice;
//! * `proposals`: the proposals on the current version at the node, each with whether it
//! passed or is dead, who voted what, and what its version changes (`client::changes`);
+//! * `status`: the store, its version and parties, the party's keys and nodes, the node,
+//! the proposals, the versions the node refused of its own, what to sign again;
+//! * `values [PATH]`: the values that count, all or under `PATH`, with who writes there;
//! * `root FILE`: the root of the federation whose first version `FILE` holds (JSON),
//! the file its founders start its swarm from (`--store-root`), to standard output;
//! * `fork FILE [HEAD...]`: the root of the fork at the heads named (those the node shows,
@@ -224,6 +227,21 @@ fn command() -> Command {
.subcommand(Command::new("proposals").about(
"The proposals on the current version, each as show says it",
))
+ .subcommand(Command::new("status").about(
+ "The store, its version and parties, the party's keys and nodes, the node, the \
+ proposals on the current version, and what the party has to sign again",
+ ))
+ .subcommand(
+ Command::new("values")
+ .about("The values that count, each with who writes there: all, or under a path")
+ .arg(Arg::new("path").help("The place, and those under it"))
+ .arg(
+ Arg::new("json")
+ .long("json")
+ .action(ArgAction::SetTrue)
+ .help("As one JSON object, by place"),
+ ),
+ )
.subcommand(
Command::new("show")
.about(
@@ -560,6 +578,12 @@ pub(crate) async fn main() -> Result<()> {
if name == "proposals" {
return proposals(&node).await;
}
+ if name == "status" {
+ return status(&node, &options).await;
+ }
+ if name == "values" {
+ return values(&node, sub).await;
+ }
if name == "show" {
let counts = node.counts().await?;
let proposal = proposal_named(&counts, sub)?.to_string();
@@ -1439,6 +1463,202 @@ async fn again(node: &Node, signer: &Signer, record: &mut Record, path: &Path) -
Ok(())
}
+/// What the node and the party's record say at a glance: the store, its checkpoint and
+/// heads; the current version, its federation and revision, and its parties; the party's
+/// keys and node list as they count, and whether the version names `--key`; the node's
+/// party, whether it votes for it by itself, and where it stopped; the proposals on the
+/// current version, each as `show` begins; the versions the node refused of its own; and
+/// what a move refused that the party signs again (`again`).
+async fn status(node: &Node, options: &Options) -> Result<()> {
+ let summary = node.get("/events").await?;
+ let counts = node.counts().await?;
+ let current = current(&counts)?;
+ let short = |id: &str| match id.get(..12) {
+ Some(start) if id.len() > 12 => format!("{start}…"),
+ _ => id.to_owned(),
+ };
+ let text = |value: &JsonValue| value.as_str().unwrap_or_default().to_owned();
+ let heads = summary["heads"].as_array().map_or(0, Vec::len);
+ println!(
+ "store {}: checkpoint {}, {heads} head{}, {} events taken after it",
+ short(&text(&summary["store"])),
+ short(&text(&summary["checkpoint"])),
+ if heads == 1 { "" } else { "s" },
+ summary["taken"]
+ );
+ let parties: Vec<&String> = current.parties.keys().collect();
+ let needed = (2 * parties.len()).div_ceil(3);
+ println!(
+ "version {} ({}) of federation {}, {}: {} part{}, {needed} passing a change ({})",
+ current.number,
+ short(&current.hash.to_string()),
+ counts["version"]["version"]["federation"],
+ current.revision,
+ parties.len(),
+ if parties.len() == 1 { "y" } else { "ies" },
+ parties
+ .iter()
+ .map(|party| party.as_str())
+ .collect::<Vec<_>>()
+ .join(", ")
+ );
+ let record = options
+ .record
+ .as_ref()
+ .map(PathBuf::from)
+ .filter(|path| path.exists())
+ .map(|path| Record::load(&path).map_err(|why| anyhow!(why)))
+ .transpose()?;
+ let party = record
+ .as_ref()
+ .map(|record| record.party.clone())
+ .or_else(|| summary["party"].as_str().map(str::to_owned));
+ if let Some(party) = &party {
+ let keys = listed(&counts, party, "keys");
+ let nodes = listed(&counts, party, "nodes");
+ let named = match options.key.as_deref().map(given_key) {
+ Some(Ok(given)) => {
+ let line = match given {
+ Given::Private(key) => PublicKey(key.verifying_key().to_bytes()).line(),
+ Given::Public(key, _) => key.line(),
+ };
+ let names = current
+ .parties
+ .get(party)
+ .is_some_and(|given| given.keys.contains(&line));
+ if names {
+ "; the version names --key's"
+ } else {
+ "; the version doesn't name --key's: it signs none of its votes, proposals, \
+ key set or node list"
+ }
+ }
+ _ => "",
+ };
+ let spelled = |items: &[String], spell: fn(&str) -> String| {
+ items
+ .iter()
+ .map(|item| spell(item))
+ .collect::<Vec<_>>()
+ .join(", ")
+ };
+ if current.parties.contains_key(party) {
+ println!(
+ "{party}: {} key{} ({}){named}; {} node{} ({})",
+ keys.len(),
+ if keys.len() == 1 { "" } else { "s" },
+ spelled(&keys, client::fingerprint),
+ nodes.len(),
+ if nodes.len() == 1 { "" } else { "s" },
+ spelled(&nodes, |node| node.to_owned()),
+ );
+ } else {
+ println!("{party}: no party of version {}", current.number);
+ }
+ }
+ let by_itself = if summary["votesByItself"].as_bool() == Some(true) {
+ ", voting for it by itself"
+ } else {
+ ""
+ };
+ match summary["party"].as_str() {
+ Some(of) => println!("the node: {of}'s{by_itself}"),
+ None => println!("the node: of no party"),
+ }
+ if let Some(stopped) = summary["stopped"].as_object() {
+ println!(
+ " stopped at {}: {}",
+ stopped
+ .get("id")
+ .and_then(JsonValue::as_str)
+ .unwrap_or_default(),
+ stopped
+ .get("why")
+ .and_then(JsonValue::as_str)
+ .unwrap_or_default()
+ );
+ }
+ let hashes = proposal_hashes(&counts);
+ match hashes.len() {
+ 0 => println!("no proposal on version {}", current.number),
+ 1 => println!("1 proposal on version {} (show says more):", current.number),
+ n => println!(
+ "{n} proposals on version {} (show says more):",
+ current.number
+ ),
+ }
+ for hash in &hashes {
+ println!(" {}", ballot_line(&counts, &current, hash, &hashes));
+ }
+ let refused = node.get("/events/refused").await?;
+ let own = refused["own"].as_array().map_or(0, Vec::len);
+ if own > 0 {
+ println!(
+ "the node refused {own} version event{} by what it took before: keys may have \
+ voted twice, and nodes be apart (GET /events/refused)",
+ if own == 1 { "" } else { "s" }
+ );
+ }
+ if let Some(record) = &record {
+ let moved: BTreeSet<Id> = 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();
+ let again = record.again(|id| moved.contains(id)).len();
+ if again > 0 {
+ println!(
+ "{} of {}'s latest events a move refused: `again` signs {} again",
+ again,
+ record.party,
+ if again == 1 { "it" } else { "them" }
+ );
+ }
+ }
+ Ok(())
+}
+
+/// The values that count, all or under the place `path` names (and it), each with who
+/// writes there, a line each: `PATH VALUE (WRITER)`, the value as JSON; or with `--json`,
+/// one JSON object of them, by place.
+async fn values(node: &Node, sub: &ArgMatches) -> Result<()> {
+ let counts = node.counts().await?;
+ let current = current(&counts)?;
+ let under = sub
+ .get_one::<String>("path")
+ .map(|path| path.trim_end_matches('/').to_owned());
+ let selected: serde_json::Map<String, JsonValue> = counts["values"]
+ .as_object()
+ .into_iter()
+ .flatten()
+ .filter(|(place, _)| is_under(place, under.as_deref()))
+ .map(|(place, value)| (place.clone(), value.clone()))
+ .collect();
+ if sub.get_flag("json") {
+ println!("{}", serde_json::to_string_pretty(&selected)?);
+ return Ok(());
+ }
+ for (place, value) in &selected {
+ let writer = super::version::path(place)
+ .and_then(|segments| current.writer(&segments).map(str::to_owned))
+ .unwrap_or_else(|| "nobody".to_owned());
+ println!("{place} {} ({writer})", serde_json::to_string(value)?);
+ }
+ Ok(())
+}
+
+/// Whether `place` is the place `under` names, or under it; any, where `under` is none.
+fn is_under(place: &str, under: Option<&str>) -> bool {
+ under.is_none_or(|under| {
+ place == under
+ || place
+ .strip_prefix(under)
+ .is_some_and(|rest| rest.starts_with('/'))
+ })
+}
+
/// The proposals on the current version, each as `preview` says it.
async fn proposals(node: &Node) -> Result<()> {
let counts = node.counts().await?;
@@ -1465,35 +1685,7 @@ async fn preview(
) -> 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();
- 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 mut lines = vec![ballot_line(counts, &current, 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}"));
@@ -1541,6 +1733,42 @@ async fn preview(
Ok(lines)
}
+/// The proposal of `hash` on `current`, as `counts` reads it, named among `hashes`
+/// (`marked`): whether it passed or is dead, how many more `true` pass it, and who voted
+/// what.
+fn ballot_line(counts: &JsonValue, current: &Version, hash: &str, hashes: &[String]) -> String {
+ 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();
+ 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})")
+ };
+ format!(
+ "{}: {standing}; true: {backers}; false: {nays}",
+ marked(hash, hashes)
+ )
+}
+
/// What `proposed` does to `current`, in words, a line each: what its version does
/// (`client::described`), the places holding a value in `counts` whose writer it moves,
/// and the nodes not known to know its revision.
@@ -2306,6 +2534,17 @@ mod tests {
assert_ne!(revised.revision, current.revision);
}
+ /// `values` shows a place and those under it, not those beside it.
+ #[test]
+ fn places_under_a_path() {
+ use super::is_under;
+ assert!(is_under("home/tv/motd", None));
+ assert!(is_under("home/tv/motd", Some("home/tv")));
+ assert!(is_under("home/tv", Some("home/tv")));
+ assert!(!is_under("home/tvx/motd", Some("home/tv")));
+ assert!(!is_under("home", Some("home/tv")));
+ }
+
/// Two rule paths overlap where some path matches both.
#[test]
fn rule_paths_overlap() {