From 54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 03:48:03 +0000 Subject: federation: a version names the revision of federation 1 it follows What every node must agree on was named by the federation's number alone, and a change that only took more kept it: a party could use it before every node ran it, and nodes not upgraded refused what followed and parted from the others. A version now names the revision it follows by its ID (`"revision": ""`), the SHA-256 of the JCS list of the features it adds to the base revision federation 1 began with (`federation::revision`); a version naming none follows the base revision, ECDSA keys among it, so the versions written so far read as they did. A version names the base revision only by leaving `revision` out, and a revision no earlier than the one of the version it changes. A continuum that doesn't know a revision, another build's among them, can't read a version naming it: it stops at a version event writing one, and says which revision and what it knows. There are no revisions yet but the base revision. `federation.md` says how a revision is rolled out, then passed, and what a later continuum may leave out; the upgrades guide, and the one on a node stopped, alike. --- src/federation/mod.rs | 1 + src/federation/revision.rs | 123 +++++++++++++++++++++++++++++++++++++++++++++ src/federation/version.rs | 73 +++++++++++++++++++++++++-- 3 files changed, 193 insertions(+), 4 deletions(-) create mode 100644 src/federation/revision.rs (limited to 'src') diff --git a/src/federation/mod.rs b/src/federation/mod.rs index bb14be3..2edc7c4 100644 --- a/src/federation/mod.rs +++ b/src/federation/mod.rs @@ -24,6 +24,7 @@ mod model; pub(crate) mod party; #[cfg(test)] mod properties; +pub(crate) mod revision; pub(crate) mod store; #[cfg(test)] mod vectors; diff --git a/src/federation/revision.rs b/src/federation/revision.rs new file mode 100644 index 0000000..876ec15 --- /dev/null +++ b/src/federation/revision.rs @@ -0,0 +1,123 @@ +//! 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 {} + +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 {} + } + + /// What it adds, in a line. + pub(crate) fn what(self) -> &'static str { + match self {} + } +} + +/// 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] = &[]; + +/// 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"); + 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)); + } + } +} diff --git a/src/federation/version.rs b/src/federation/version.rs index 378e122..fa534b3 100644 --- a/src/federation/version.rs +++ b/src/federation/version.rs @@ -5,6 +5,7 @@ use std::collections::{BTreeMap, BTreeSet}; use super::jcs::Json; use super::keys; +use super::revision::Revision; use super::store::Id; /// The federation this is: a version naming another is none here. @@ -31,6 +32,8 @@ pub(crate) struct Version { /// The SHA-256 of its JCS bytes, written as an ID is. pub(crate) hash: Id, pub(crate) json: Json, + /// The revision of the federation it follows: the base revision where it names none. + pub(crate) revision: Revision, pub(crate) number: u64, /// The version it changes; none for the first. pub(crate) changes: Option, @@ -154,7 +157,7 @@ impl Version { json, "a version", &["federation", "number", "changes", "keys", "nodes", "rules"], - &["checkpoint"], + &["checkpoint", "revision"], )?; match json.get("federation").and_then(Json::as_int) { Some(FEDERATION) => {} @@ -165,6 +168,30 @@ impl Version { } None => return Err("a federation that is no number".to_owned()), } + let revision = match json.get("revision") { + None => Revision::default(), + Some(named) => { + let id = named + .as_str() + .and_then(Id::from_hex) + .ok_or("a `revision` that is no revision's ID")?; + match Revision::of(&id) { + Some(Revision(0)) => { + return Err("a `revision` naming the base revision, which a version \ + names by leaving it out" + .to_owned()); + } + Some(revision) => revision, + None => { + return Err(format!( + "revision {id}, which this continuum doesn't know, as it knows {}: \ + a release that knows it reads this version", + Revision::knowing() + )); + } + } + } + }; let number = json .get("number") .and_then(Json::as_int) @@ -198,6 +225,7 @@ impl Version { Ok(Version { hash: Id::of(&json.bytes()), json: json.clone(), + revision, number, changes, parties, @@ -282,8 +310,9 @@ impl Version { } /// Whether it changes `before` as a version must: numbered one past it, naming its - /// hash, and with each `since` its own number, or that `before` gives the party with - /// the same keys, or node list. The first version gives every party its own. + /// hash, of its revision or a later one, and with each `since` its own number, or that + /// `before` gives the party with the same keys, or node list. The first version gives + /// every party its own. pub(crate) fn changes_validly(&self, before: Option<&Version>) -> Result<(), String> { match before { None => { @@ -303,6 +332,12 @@ impl Version { self.number, before.number )); } + if self.revision < before.revision { + return Err(format!( + "{}, before {} of the version it changes", + self.revision, before.revision + )); + } for (name, party) in &self.parties { let was = before.parties.get(name); let keys_kept = was.is_some_and(|was| { @@ -326,7 +361,7 @@ impl Version { } /// Whether it changes nothing of `before` but its number, what it changes and its - /// checkpoint: one that only moves the store on. + /// checkpoint, its revision neither: one that only moves the store on. pub(crate) fn only_moves_on(&self, before: &Version) -> bool { let strip = |json: &Json| { json.without("number") @@ -559,6 +594,36 @@ mod tests { assert_eq!(why, "97 parties, more than 96"); } + /// A version follows the base revision where it names none; one naming the base + /// revision, or one this continuum doesn't know, is none, and says so. + #[test] + fn a_version_names_a_revision_it_follows_or_none() { + assert_eq!( + Version::read(&first()).expect("a version").revision, + Revision::default() + ); + let named = |id: &str| { + let text = String::from_utf8(first().bytes()).expect("UTF-8"); + let text = text.replacen(r#""rules":"#, &format!(r#""revision":"{id}","rules":"#), 1); + Version::read(&jcs::read(text.as_bytes()).expect("JCS")) + }; + let why = named(&Revision::default().id().to_string()).unwrap_err(); + assert!(why.contains("naming the base revision"), "{why}"); + let unknown = Id::of(br#"["elsewhere"]"#); + let why = named(&unknown.to_string()).unwrap_err(); + assert!( + why.starts_with(&format!( + "revision {unknown}, which this continuum doesn't know" + )), + "{why}" + ); + assert!(named("no ID").unwrap_err().contains("no revision's ID")); + for revision in Revision::known().skip(1) { + let version = named(&revision.id().to_string()).expect("a version"); + assert_eq!(version.revision, revision); + } + } + #[test] fn a_version_changes_another_by_its_number_hash_and_sinces() { let first = Version::read(&first()).expect("a version"); -- cgit v1.3.1