//! The revisions of federation 1 (`docs/federation.md`, Changing the federation): what a //! version names of what nodes take, refuse and count beyond the base revision the //! federation began with. Each adds a feature to those of the one before. A revision is //! named by the SHA-256 of the JCS list of its features' names, so that a continuum that //! doesn't know it, another build's among them, can't read a version naming it, and stops //! there. use std::fmt; use super::jcs::Json; use super::store::Id; /// A feature a revision adds. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) enum Feature { /// Merge events: a node its party lists, with its own key, builds on events it holds, /// writing nothing (`Does::Merge`). MergeEvents, } impl Feature { /// Its name, in the IDs of the revisions that have it: never changed once released, /// and specific, so that a feature another build names alike is one it adds alike. pub(crate) fn name(self) -> &'static str { match self { Feature::MergeEvents => "merge-events", } } /// What it adds, in a line. pub(crate) fn what(self) -> &'static str { match self { Feature::MergeEvents => { "merge events, which a node its party lists signs with its own key, building \ on events it holds and writing nothing" } } } /// The revision that adds it. pub(crate) fn revision(self) -> Revision { let at = FEATURES .iter() .position(|feature| *feature == self) .expect("every feature is in FEATURES"); Revision(at + 1) } } /// The features, in the order revisions add them: revision n has the first n, the base /// revision none. Only ever appended to. pub(crate) const FEATURES: &[Feature] = &[Feature::MergeEvents]; /// A revision: how many of `FEATURES` it has. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)] pub(crate) struct Revision(pub(crate) usize); impl Revision { /// The newest this continuum knows. pub(crate) fn newest() -> Revision { Revision(FEATURES.len()) } /// Every revision this continuum knows, the base revision first. pub(crate) fn known() -> impl Iterator { (0..=FEATURES.len()).map(Revision) } /// Its ID: the SHA-256 of the JCS list of its features' names. pub(crate) fn id(self) -> Id { let names = self .features() .iter() .map(|feature| Json::Str(feature.name().to_owned())) .collect(); Id::of(&Json::Array(names).bytes()) } /// The revision of ID `id`, of those this continuum knows. pub(crate) fn of(id: &Id) -> Option { Revision::known().find(|revision| revision.id() == *id) } /// Its features. pub(crate) fn features(self) -> &'static [Feature] { &FEATURES[..self.0] } /// Whether it has `feature`. pub(crate) fn has(self, feature: Feature) -> bool { self.features().contains(&feature) } /// What this continuum knows, as people read it: "the base revision alone", or /// "revisions up to 2 (…)". pub(crate) fn knowing() -> String { match Revision::newest() { Revision(0) => "the base revision alone".to_owned(), newest => format!("revisions up to {} ({})", newest.0, newest.names()), } } /// Its features' names, as people read them. fn names(self) -> String { let names: Vec<&str> = self .features() .iter() .map(|feature| feature.name()) .collect(); names.join(", ") } } /// As people read it: "the base revision", or "revision 2 (merge-events, …)". impl fmt::Display for Revision { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self.0 { 0 => f.write_str("the base revision"), n => write!(f, "revision {n} ({})", self.names()), } } } #[cfg(test)] mod tests { use super::*; /// A revision's ID is the SHA-256 of the JCS list of its features' names: the base /// revision's, of `[]`. #[test] fn a_revision_is_named_by_its_features() { assert_eq!(Revision::default().id(), Id::of(b"[]")); assert_eq!(Revision::of(&Id::of(b"[]")), Some(Revision(0))); assert_eq!(Revision::of(&Id::of(b"[\"elsewhere\"]")), None); assert_eq!(Revision::default().to_string(), "the base revision"); assert_eq!( Feature::MergeEvents.revision().to_string(), "revision 1 (merge-events)" ); assert_eq!( Revision(1).id(), Id::of(br#"["merge-events"]"#), "a released revision's ID changes never" ); let names: Vec<&str> = FEATURES.iter().map(|feature| feature.name()).collect(); let distinct: std::collections::BTreeSet<&str> = names.iter().copied().collect(); assert_eq!(distinct.len(), names.len(), "a feature named twice"); for revision in Revision::known() { assert_eq!(Revision::of(&revision.id()), Some(revision)); } } }