aboutsummaryrefslogtreecommitdiffstats
path: root/src/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 03:48:03 +0000
committertv <tv@krebsco.de>2026-11-19 05:10:06 +0100
commit54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 (patch)
tree20568ac1b47394ae9e603630fe1ab5464d1f7900 /src/federation
parente5f8df2a78f26d5928d1c96573dae5620dba5e25 (diff)
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": "<ID>"`), 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.
Diffstat (limited to 'src/federation')
-rw-r--r--src/federation/mod.rs1
-rw-r--r--src/federation/revision.rs123
-rw-r--r--src/federation/version.rs73
3 files changed, 193 insertions, 4 deletions
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<Item = Revision> {
+ (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> {
+ 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<Id>,
@@ -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");