diff options
| author | tv <tv@krebsco.de> | 2026-11-19 11:22:42 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 13:09:59 +0100 |
| commit | d62c36d10e916bff09dff56c384e38bb93e82d86 (patch) | |
| tree | 7c5e1abed5ae996331de1c676f75888525d37b22 /src/federation/judge.rs | |
| parent | 680e1cd6fdeeb6dacb48598545d9e384dc52ffdc (diff) | |
federation: continuum-party judge, a store's verdicts in a format releases keep
To check that a release judges histories as an earlier one did, under every revision
that one knows, each must say what its store makes of the same histories, in the same
words.
`continuum-party judge` reads histories from its input, each `case <label>`, `root
<hex>` and `event <hex>` for each event in the order offered, and prints for each what
became of every event by kind (`became <ID> <kind>`, never a refusal's words) and what
the store reads after (`reads <JSON>`): its checkpoint, the current version, the values
at places, the members, and the event it stopped at; `root none` where the root reads as
none, as one of a revision this continuum doesn't know (`federation::judge`). The format
is never to change: an earlier release prints it too.
Diffstat (limited to 'src/federation/judge.rs')
| -rw-r--r-- | src/federation/judge.rs | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/src/federation/judge.rs b/src/federation/judge.rs new file mode 100644 index 0000000..4fc4ce8 --- /dev/null +++ b/src/federation/judge.rs @@ -0,0 +1,192 @@ +//! What a store makes of histories, in a format every release of continuum keeps +//! (`continuum-party judge`; `docs/federation-tests.md`, Against released revisions), so +//! that a release judges the same histories as an earlier one, under every revision that +//! one knows. Never change the format: an earlier release prints it too. +//! +//! In, a history after another: `case <label>`, `root <hex>`, the bytes of its root, then +//! `event <hex>` for each of its events, in the order offered. +//! +//! Out, for each: `case <label>`; then `root none` where the root reads as none here, as +//! one of a revision this continuum doesn't know; else `became <ID> <kind>` for each event +//! in the order offered, what became of it by kind (never a refusal's words, which may +//! change), and `reads <JSON>`, what the store reads after: its checkpoint's ID, the +//! current version's hash, the values at places, the members, and the event it stopped +//! at. + +use std::collections::BTreeMap; +use std::fmt::Write as _; + +use super::fold::Federation; +use super::store::Id; +use super::store::memory::{Refusal, Store}; + +/// A history: its label, its root, and its events in the order offered. +pub(crate) struct History { + pub(crate) label: String, + pub(crate) root: Vec<u8>, + pub(crate) events: Vec<Vec<u8>>, +} + +/// `histories` as `judge` reads them. +pub(crate) fn spelled(histories: &[History]) -> String { + let mut text = String::new(); + for history in histories { + let _ = writeln!(text, "case {}", history.label); + let _ = writeln!(text, "root {}", hex(&history.root)); + for event in &history.events { + let _ = writeln!(text, "event {}", hex(event)); + } + } + text +} + +/// The histories `text` spells (`spelled`). +pub(crate) fn read(text: &str) -> Result<Vec<History>, String> { + let mut histories: Vec<History> = Vec::new(); + for line in text.lines() { + let (word, rest) = line.split_once(' ').unwrap_or((line, "")); + let bytes = || unhex(rest).ok_or_else(|| format!("no hex: {line:?}")); + match (word, histories.last_mut()) { + ("case", _) => histories.push(History { + label: rest.to_owned(), + root: Vec::new(), + events: Vec::new(), + }), + ("root", Some(history)) => history.root = bytes()?, + ("event", Some(history)) => history.events.push(bytes()?), + _ => return Err(format!("no line of a history: {line:?}")), + } + } + Ok(histories) +} + +fn hex(bytes: &[u8]) -> String { + bytes.iter().map(|byte| format!("{byte:02x}")).collect() +} + +fn unhex(text: &str) -> Option<Vec<u8>> { + if !text.len().is_multiple_of(2) || !text.bytes().all(|byte| byte.is_ascii_hexdigit()) { + return None; + } + (0..text.len()) + .step_by(2) + .map(|at| u8::from_str_radix(text.get(at..at + 2)?, 16).ok()) + .collect() +} + +/// What a store makes of `histories`, as the format says. +pub(crate) fn judge(histories: &[History]) -> String { + let mut text = String::new(); + for history in histories { + let _ = writeln!(text, "case {}", history.label); + let Ok(mut store) = Store::<Federation>::new(history.root.clone(), Vec::new()) else { + text.push_str("root none\n"); + continue; + }; + for event in &history.events { + store.offer(event.clone()); + } + for event in &history.events { + let id = Id::of(event); + let _ = writeln!(text, "became {id} {}", became(&store, &id)); + } + let _ = writeln!(text, "reads {}", reads(&store)); + } + text +} + +/// What became of `id` in `store`, by kind. +fn became(store: &Store<Federation>, id: &Id) -> &'static str { + if store.stopped().is_some_and(|(at, ..)| at == id) { + return "stopped at"; + } + if store.held_back().iter().any(|(held, _)| held == id) { + return "held back"; + } + if store.holds(id) { + return "taken"; + } + if store.get(id).is_some() { + return "kept"; + } + match store.refusal(id) { + Some(Refusal::None) => "refused: none", + Some(Refusal::Judged(_)) => "refused: judged", + Some(Refusal::BuiltOn(_)) => "refused: built on a refused one", + Some(Refusal::NotAbove) => "refused: not above the checkpoint", + Some(Refusal::Own) => "refused: its own", + Some(Refusal::Dropped) => "refused: dropped", + None if store.is_waiting(id) => "waiting", + None => "gone with a move", + } +} + +/// What `store` reads, a line of JSON. +fn reads(store: &Store<Federation>) -> String { + let state = store.state(); + let values: BTreeMap<String, String> = state + .values() + .into_iter() + .map(|(path, value)| (path, String::from_utf8_lossy(&value.bytes()).into_owned())) + .collect(); + serde_json::json!({ + "checkpoint": Id::of(store.checkpoint()).to_string(), + "current": state.current().hash.to_string(), + "values": values, + "members": state.members(), + "stopped": store.stopped().map(|(id, ..)| id.to_string()), + }) + .to_string() +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::federation::harness::{self, Party, Spec}; + + /// Histories read back as spelled, and judged as the format says: an event taken, one + /// refused, and a root of a revision this continuum doesn't know read as none. + #[test] + fn histories_are_judged_as_the_format_says() { + let tv = Party::new("tv", 1); + let first = Spec::first(&[&tv, &Party::new("lass", 2)], &[]); + let root = first.root(); + let write = tv.write(&[Id::of(&root)], "home/tv/a", harness::str("1")); + let unknown = String::from_utf8(root.clone()).expect("UTF-8").replacen( + r#""rules":"#, + &format!(r#""revision":"{}","rules":"#, Id::of(b"elsewhere")), + 1, + ); + let histories = vec![ + History { + label: "one".to_owned(), + root: root.clone(), + events: vec![write.clone(), b"not an event".to_vec()], + }, + History { + label: "unknown".to_owned(), + root: unknown.into_bytes(), + events: vec![write.clone()], + }, + ]; + let again = read(&spelled(&histories)).expect("as spelled"); + assert_eq!(again.len(), 2); + assert_eq!(again[0].events, histories[0].events); + let judged = judge(&again); + let lines: Vec<&str> = judged.lines().collect(); + assert_eq!(lines[0], "case one"); + assert_eq!(lines[1], format!("became {} taken", Id::of(&write))); + assert_eq!( + lines[2], + format!("became {} refused: none", Id::of(b"not an event")) + ); + assert!( + lines[3].starts_with(r#"reads {"checkpoint":"#), + "{}", + lines[3] + ); + assert!(lines[3].contains(r#""home/tv/a":"\"1\"""#), "{}", lines[3]); + assert_eq!(&lines[4..], ["case unknown", "root none"]); + assert!(read("nothing").is_err()); + } +} |
