diff options
| author | tv <tv@krebsco.de> | 2026-11-18 20:10:53 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-18 21:17:46 +0100 |
| commit | 657765cc512743c248d71b852b4f2e81fa124af7 (patch) | |
| tree | 546fca8830af331b448786a1d757f41cd56f1232 | |
| parent | 79614926332977718956f35e1adf80ae67e219f1 (diff) | |
version: say why a version is none
`Version::read` names what makes a version none: the field it lacks, or the one more it
has, that this continuum doesn't know (of the version, a party's keys or node list, a
rule), the federation it names beside the one this continuum knows, how many keys or
nodes a party has against how many it may, the node ID that is none, and of a key why it
is none (`keys::spelled`): its type, its point, or its spelling. A node that stops at a
version says so in `stopped` (`GET /events`) and its log; a party's client in what it
won't propose or back.
The guide to a node that stopped says what `why` tells.
| -rw-r--r-- | docs/guides/federation/when-things-go-wrong.md | 10 | ||||
| -rw-r--r-- | src/federation/keys.rs | 24 | ||||
| -rw-r--r-- | src/federation/version.rs | 113 |
3 files changed, 107 insertions, 40 deletions
diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md index b59b69b..7c814c2 100644 --- a/docs/guides/federation/when-things-go-wrong.md +++ b/docs/guides/federation/when-things-go-wrong.md @@ -75,10 +75,16 @@ nothing by itself or by hand; what is put through it, it still writes into the d can't judge`), and `GET /events` names the event, why, and how many it holds back: ```sh -curl -s -u tv:secret localhost:3000/events | jq .stopped -# {"heldBack":12,"id":"9a1e…","why":"version 3c0f… passed, and doesn't read as one…"} +curl -s -u tv:secret localhost:3000/events | jq -r .stopped.why +# version 3c0f… passed, and doesn't read as one here: of federation 2, and this +# continuum knows 1 alone ``` +`why` says what doesn't read: a federation this continuum doesn't know, a field it +doesn't know, by its name, a key of a type it doesn't take, or whatever else makes a +version none ([`proposing-and-voting.md`](proposing-and-voting.md), +[Writing a version](proposing-and-voting.md#writing-a-version)). + Upgrade the node to a continuum that reads it: restarted, it reads its store anew and takes it. Where none does (two thirds passed a proposal that is no version), have the node drop that event: it goes on under the version before, refuses the event and any writing diff --git a/src/federation/keys.rs b/src/federation/keys.rs index 22940ad..0dbe5f7 100644 --- a/src/federation/keys.rs +++ b/src/federation/keys.rs @@ -100,12 +100,24 @@ impl Key { /// The key `text` spells, where it spells one as the federation does. pub(crate) fn key(text: &str) -> Option<Key> { - let key = Key::parse(text).ok()?; - let valid = match &key { - Key::Ed25519(public) => VerifyingKey::from_bytes(&public.0).is_ok(), - Key::P256(_) => true, - }; - (key.line() == text && valid).then_some(key) + spelled(text).ok() +} + +/// The key `text` spells as the federation does, or why it spells none. +pub(crate) fn spelled(text: &str) -> Result<Key, String> { + let key = Key::parse(text)?; + if let Key::Ed25519(public) = &key + && VerifyingKey::from_bytes(&public.0).is_err() + { + return Err("not a point on Ed25519".to_owned()); + } + if key.line() != text { + return Err(format!( + "not spelled as the federation spells it: `{}`, without a comment", + key.line() + )); + } + Ok(key) } /// Whether `text` is a node ID spelled as continuum spells one. diff --git a/src/federation/version.rs b/src/federation/version.rs index 1547ec1..d714a47 100644 --- a/src/federation/version.rs +++ b/src/federation/version.rs @@ -119,31 +119,46 @@ fn since(json: &Json) -> Result<u64, String> { .ok_or_else(|| "a `since` that is no number".to_owned()) } -/// Whether `json` has these names and no others; `optional` ones it may leave out. -fn names(json: &Json, required: &[&str], optional: &[&str]) -> bool { - json.is_object() - && required.iter().all(|name| json.get(name).is_some()) - && json - .names() - .iter() - .all(|name| required.contains(name) || optional.contains(name)) +/// That `json`, `what`, has these names and no others, `optional` ones it may leave out; +/// else which it lacks, or which it has more, that this continuum doesn't know. +fn fields(json: &Json, what: &str, required: &[&str], optional: &[&str]) -> Result<(), String> { + if !json.is_object() { + return Err(format!("{what} that is no object")); + } + if let Some(name) = required.iter().find(|name| json.get(name).is_none()) { + return Err(format!("{what} without `{name}`")); + } + match json + .names() + .into_iter() + .find(|name| !required.contains(name) && !optional.contains(name)) + { + Some(name) => Err(format!( + "{what} with `{name}`, a field this continuum doesn't know" + )), + None => Ok(()), + } } impl Version { /// The version `json` is, where it is one by itself: a field missing or more, or any of - /// the rest of what makes a version none, is an error. Whether it changes the version - /// it says is asked apart (`changes_validly`). + /// the rest of what makes a version none, is an error, saying which. Whether it changes + /// the version it says is asked apart (`changes_validly`). pub(crate) fn read(json: &Json) -> Result<Version, String> { - if !names( + fields( json, + "a version", &["federation", "number", "changes", "keys", "nodes", "rules"], &["checkpoint"], - ) { - return Err("a field missing or more".to_owned()); - } - let federation = json.get("federation").and_then(Json::as_int); - if federation != Some(FEDERATION) { - return Err(format!("of federation {federation:?}, not {FEDERATION}")); + )?; + match json.get("federation").and_then(Json::as_int) { + Some(FEDERATION) => {} + Some(federation) => { + return Err(format!( + "of federation {federation}, and this continuum knows {FEDERATION} alone" + )); + } + None => return Err("a federation that is no number".to_owned()), } let number = json .get("number") @@ -204,23 +219,26 @@ impl Version { let (Some(key_json), Some(node_json)) = (keys.get(name), nodes.get(name)) else { return Err("keys and node lists not of the same parties".to_owned()); }; - if !names(key_json, &["since", "keys"], &[]) - || !names(node_json, &["since", "nodes"], &[]) - { - return Err(format!( - "{name}'s keys or node list: a field missing or more" - )); - } + fields(key_json, &format!("{name}'s keys"), &["since", "keys"], &[])?; + fields( + node_json, + &format!("{name}'s node list"), + &["since", "nodes"], + &[], + )?; let party_keys = key_json .get("keys") .and_then(distinct_strings) .ok_or_else(|| format!("{name}'s keys aren't a list of keys"))?; if party_keys.is_empty() || party_keys.len() > KEYS { - return Err(format!("{name} with {} keys", party_keys.len())); + return Err(format!( + "{name} with {} keys, not 1 to {KEYS}", + party_keys.len() + )); } for key in &party_keys { - if keys::key(key).is_none() { - return Err(format!("{name}'s key {key:?} isn't spelled as a key")); + if let Err(why) = keys::spelled(key) { + return Err(format!("{name}'s key {key:?}: {why}")); } if !every_key.insert(key.clone()) { return Err(format!("{key:?} twice in the version")); @@ -230,8 +248,14 @@ impl Version { .get("nodes") .and_then(distinct_strings) .ok_or_else(|| format!("{name}'s node list isn't a list of node IDs"))?; - if party_nodes.len() > NODES || !party_nodes.iter().all(|id| keys::node_id(id)) { - return Err(format!("{name}'s node list")); + if party_nodes.len() > NODES { + return Err(format!( + "{name}'s node list of {} nodes, more than {NODES}", + party_nodes.len() + )); + } + if let Some(id) = party_nodes.iter().find(|id| !keys::node_id(id)) { + return Err(format!("{name}'s node {id:?}, no node ID")); } parties.insert( name.to_owned(), @@ -315,9 +339,7 @@ impl Version { impl Rule { fn read(json: &Json, parties: &BTreeMap<String, Party>) -> Result<Rule, String> { - if !names(json, &["path", "writer"], &[]) { - return Err("a rule: a field missing or more".to_owned()); - } + fields(json, "a rule", &["path", "writer"], &[])?; let text = json .get("path") .and_then(Json::as_str) @@ -485,6 +507,33 @@ mod tests { assert!(with_rule(&vec!["a"; SEGMENTS + 1].join("/"), tv()).is_err()); } + /// What makes a version none, said: a field it lacks or one more, which this + /// continuum doesn't know, a federation it doesn't know, a key of a type it doesn't + /// take. + #[test] + fn a_version_that_is_none_says_why() { + let edited = |edit: &dyn Fn(&str) -> String| { + let text = String::from_utf8(first().bytes()).expect("UTF-8"); + Version::read(&jcs::read(edit(&text).as_bytes()).expect("JCS")).unwrap_err() + }; + let why = edited(&|text| text.replacen(r#""nodes":"#, r#""later":true,"nodes":"#, 1)); + assert_eq!( + why, + "a version with `later`, a field this continuum doesn't know" + ); + let why = edited(&|text| text.replace(r#""federation":1,"#, "")); + assert_eq!(why, "a version without `federation`"); + let why = edited(&|text| text.replace(r#""federation":1"#, r#""federation":2"#)); + assert_eq!(why, "of federation 2, and this continuum knows 1 alone"); + let why = edited(&|text| text.replace("ssh-ed25519 ", "sk-ssh-ed25519@openssh.com ")); + assert!(why.contains("a sk-ssh-ed25519@openssh.com key"), "{why}"); + let why = edited(&|text| text.replacen(r#""since":0"#, r#""since":0,"x":1"#, 1)); + assert!( + why.ends_with("with `x`, a field this continuum doesn't know"), + "{why}" + ); + } + #[test] fn a_version_changes_another_by_its_number_hash_and_sinces() { let first = Version::read(&first()).expect("a version"); |
