//! What each revision of federation 1 takes, refuses and reads, as fixed bytes //! (`docs/federation-tests.md`, The corpus): for each revision this continuum knows, a file //! in `corpus/` of histories generated at that revision, each with what became of every //! event and what the store reads after, written once when the revision is made //! (`write_the_corpus`) and never edited after. Every later continuum judges them alike: a //! change to judging that alters what an earlier revision's corpus says comes as a later //! revision. use std::collections::{BTreeMap, BTreeSet}; use std::fmt::Write as _; use std::path::PathBuf; use super::event::{Does, Event}; use super::fold::Federation; use super::properties::{self, History, Kind}; use super::revision::{Feature, Revision}; use super::store::Id; use super::store::memory::{Refusal, Store}; use crate::testrand::Rng; /// Of each kind, the seeds histories are generated from, the first so many kept /// whatever they show, and at most how many kept. const SCANNED: u64 = 400; const FIRST: u64 = 2; const MOST: usize = 8; /// The kinds of history generated: with an adversary or not, versions naming checkpoints /// or not, and versions this continuum doesn't read or not. fn kinds() -> Vec { let mut kinds = Vec::new(); for adversary in [false, true] { for checkpoints in [false, true] { for unread in [false, true] { kinds.push(Kind { adversary, checkpoints, unread, }); } } } kinds } fn dir() -> PathBuf { PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src/federation/corpus") } /// The file of `revision`'s corpus: by its number and the feature it adds, or `base`. fn file(revision: Revision) -> PathBuf { let name = match revision.features().last() { None => "0-base".to_owned(), Some(feature) => format!("{}-{}", revision.0, feature.name()), }; dir().join(format!("{name}.txt")) } /// The first line of `revision`'s corpus, naming it by its ID, so that a renamed feature /// fails as a changed judgment does. fn header(revision: Revision) -> String { format!( "continuum federation 1, {revision}, ID {}: never edited once released", revision.id() ) } /// What became of `id` in `store`, by kind: never a refusal's words, which may change. fn became(store: &Store, id: &Id) -> String { if store.stopped().is_some_and(|(at, ..)| at == id) { return "stopped at".to_owned(); } if store.held_back().iter().any(|(held, _)| held == id) { return "held back".to_owned(); } if store.holds(id) { return "taken".to_owned(); } if store.get(id).is_some() { return "kept".to_owned(); } match store.refusal(id) { Some(Refusal::None) => "refused: none".to_owned(), Some(Refusal::Judged(_)) => "refused: judged".to_owned(), Some(Refusal::BuiltOn(_)) => "refused: built on a refused one".to_owned(), Some(Refusal::NotAbove) => "refused: not above the checkpoint".to_owned(), Some(Refusal::Own) => "refused: its own".to_owned(), Some(Refusal::Dropped) => "refused: dropped".to_owned(), None if store.is_waiting(id) => "waiting".to_owned(), None => "gone with a move".to_owned(), } } /// What `store` reads: its checkpoint, the current version, the values at places, the /// members, and the event it stopped at; a line of JSON. fn reads(store: &Store) -> String { let state = store.state(); let values: BTreeMap = 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() } /// A store from `root`, offered `events` in their order. fn offered(root: &[u8], events: &[Vec]) -> Store { let mut store = Store::new(root.to_vec(), Vec::new()).expect("a root"); for event in events { store.offer(event.clone()); } store } /// What a history shows of what a corpus is to hold: of each kind of event, what became /// of one; and whether a version was written, the store moved to a checkpoint, or stopped. fn shows(history: &History) -> BTreeSet { let store = offered(&history.root, &history.events); let mut shown = BTreeSet::new(); if store.state().current().number > 0 { shown.insert("a version written".to_owned()); } if Id::of(store.checkpoint()) != store.id() { shown.insert("a move to a checkpoint".to_owned()); } if store.stopped().is_some() { shown.insert("a stop".to_owned()); } for event in &history.events { let kind = match Event::read_taken(event) { Some(Event::Signed(signed)) => match signed.does { Does::Write { .. } => "a write", Does::Keys(_) => "a key set", Does::Nodes(_) => "a node list", Does::Proposal { .. } => "a proposal", Does::Vote { .. } => "a vote", Does::Merge => "a merge event", }, Some(Event::Version { .. }) => "a version event", None => "no event", }; shown.insert(format!("{kind}: {}", became(&store, &Id::of(event)))); } shown } /// A case: a root, and its events offered in the order written; what each became, and /// what the store reads after, as the corpus spells them. fn case(label: &str, root: &[u8], events: &[Vec]) -> String { let store = offered(root, events); let mut text = format!("case {label}\nroot {}\n", String::from_utf8_lossy(root)); for event in events { let _ = writeln!(text, "event {}", String::from_utf8_lossy(event)); let _ = writeln!(text, "became {}", became(&store, &Id::of(event))); } let _ = writeln!(text, "reads {}", reads(&store)); text } /// `revision`'s corpus, generated: of each kind, histories whose first version follows /// `revision`, those of the first seeds, and of the rest those showing what the ones kept /// don't (`shows`), up to `MOST`. fn generated(revision: Revision) -> String { let mut text = header(revision) + "\n"; for kind in kinds() { let mut held = BTreeSet::new(); let mut kept = 0; for seed in 0..SCANNED { if kept == MOST { break; } let history = properties::generate_at(&mut Rng::new(seed), kind, Some(revision)); let shown = shows(&history); if seed >= FIRST && shown.is_subset(&held) { continue; } held.extend(shown); kept += 1; let label = format!("seed {seed}, {kind:?}"); text += &case(&label, &history.root, &history.events); } } text } /// A corpus's cases, read: each its label, its root, and its events with what each /// became, and what the store reads after. struct Case { label: String, root: Vec, events: Vec<(Vec, String)>, reads: String, } fn parse(text: &str) -> Result<(String, Vec), String> { let mut lines = text.lines(); let header = lines.next().ok_or("an empty corpus")?.to_owned(); let mut cases: Vec = Vec::new(); let mut event: Option> = None; for line in lines { let (word, rest) = line.split_once(' ').ok_or(format!("no line: {line:?}"))?; let current = cases.last_mut(); match (word, current) { ("case", _) => cases.push(Case { label: rest.to_owned(), root: Vec::new(), events: Vec::new(), reads: String::new(), }), ("root", Some(case)) => case.root = rest.as_bytes().to_vec(), ("event", Some(_)) => event = Some(rest.as_bytes().to_vec()), ("became", Some(case)) => { let bytes = event.take().ok_or("`became` without its event")?; case.events.push((bytes, rest.to_owned())); } ("reads", Some(case)) => case.reads = rest.to_owned(), _ => return Err(format!("no line of a corpus: {line:?}")), } } Ok((header, cases)) } /// Writes the corpus of every revision this continuum knows that has none: once, when a /// revision is made, its file then committed and never edited. Run by hand: /// `cargo test --features federation write_the_corpus -- --ignored`. #[test] #[ignore = "writes into the source tree: run by hand when a revision is made"] fn write_the_corpus() { std::fs::create_dir_all(dir()).expect("the corpus's directory"); for revision in Revision::known() { let path = file(revision); if !path.exists() { std::fs::write(&path, generated(revision)).expect("the corpus written"); println!("wrote {}", path.display()); } } } /// Every revision this continuum knows has its corpus, which it judges and reads as the /// corpus says; and which shows a version written, a move to a checkpoint and a stop, and /// what became of a merge event at that revision: taken where it has merge events, else /// refused. #[test] fn every_revision_judges_as_its_corpus_says() { for revision in Revision::known() { let path = file(revision); let text = std::fs::read_to_string(&path).unwrap_or_else(|_| { panic!( "no corpus of {revision} ({}): write it once, as the revision is made, with \ `cargo test --features federation write_the_corpus -- --ignored`, and \ commit it", path.display() ) }); let (named, cases) = parse(&text).unwrap_or_else(|why| panic!("{}: {why}", path.display())); assert_eq!( named, header(revision), "{}: another revision", path.display() ); assert!(!cases.is_empty(), "{}: no case", path.display()); let mut shown = BTreeSet::new(); for case in cases { let events: Vec> = case.events.iter().map(|(bytes, _)| bytes.clone()).collect(); let judged = self::case(&case.label, &case.root, &events); shown.extend(shows(&History { root: case.root.clone(), events, })); let (_, again) = parse(&format!("{named}\n{judged}")).expect("as written"); let again = &again[0]; for ((bytes, was), (_, is)) in case.events.iter().zip(&again.events) { assert_eq!( was, is, "{}, {}: the event {} became otherwise", path.display(), case.label, Id::of(bytes) ); } assert_eq!( case.reads, again.reads, "{}, {}: the store reads otherwise", path.display(), case.label ); } let merged = if revision.has(Feature::MergeEvents) { "a merge event: taken" } else { "a merge event: refused: judged" }; for wanted in [ "a version written", "a move to a checkpoint", "a stop", merged, ] { assert!( shown.contains(wanted), "{}: no case shows {wanted}", path.display() ); } } }