From 0d2467e15ec0c9c035b1074a2dd4eece6b24c599 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 04:00:12 +0000 Subject: federation: revisions shown, named, and moved to by hand An operator moving the federation to a revision had nothing to say which revisions a node knows, nor which one the current version follows, and a hash where a name would do. `GET /events` lists the revisions the node's continuum knows, each its number, its ID, the feature it adds and what that adds, and as people read it ("revision 1 (merge-events)"); `GET /events/counts`, the current version's. `continuum-party next --revision FEATURE` begins a version following the revision adding it, never an earlier one than the current version's, and `next` says so where the node knows a later one. `proposals` shows a change of revision as people read it, a revision this continuum doesn't know so said. A client backs a version moving to a revision only where its node knows it, and says why otherwise: once passed, a node that doesn't stops there. The upgrades guide walks through moving to a revision: upgrade every node, propose, vote, and what follows; the proposing guide lists `revision`, and the API's spec the rest. --- src/federation/client.rs | 22 ++++++++- src/federation/party.rs | 117 +++++++++++++++++++++++++++++++++++++++++---- src/federation/revision.rs | 24 ++++++++++ 3 files changed, 153 insertions(+), 10 deletions(-) (limited to 'src/federation') diff --git a/src/federation/client.rs b/src/federation/client.rs index 4d61944..7b9d3d7 100644 --- a/src/federation/client.rs +++ b/src/federation/client.rs @@ -433,7 +433,8 @@ pub(crate) fn binding( /// What the version `proposed` changes of `current`, a line each: each field whose value /// differs, and of `keys` and `nodes` each party's, as `field: before -> after`, its JCS -/// on either side, `-` where a version lacks it. +/// on either side, `-` where a version lacks it; the revision as people read it +/// (`revision::described`). pub(crate) fn changes(current: &Json, proposed: &Json) -> Vec { fn text(json: Option<&Json>) -> String { json.map_or_else( @@ -450,6 +451,14 @@ pub(crate) fn changes(current: &Json, proposed: &Json) -> Vec { if before == after { continue; } + if name == "revision" { + lines.push(format!( + "revision: {} -> {}", + super::revision::described(before), + super::revision::described(after) + )); + continue; + } let by_party = matches!(name, "keys" | "nodes") && [before, after] .iter() @@ -887,5 +896,16 @@ mod tests { ] ); assert!(changes(¤t, ¤t).is_empty()); + let one = super::super::revision::Revision(1).id(); + let revised = read(&format!( + r#"{{"number": 0, "changes": null, "keys": {{"tv": {{"since": 0, "keys": ["a"]}}}}, + "revision": "{one}", "rules": []}}"# + )); + assert_eq!( + changes(¤t, &revised), + [format!( + "revision: the base revision -> revision 1 (merge-events), {one}" + )] + ); } } diff --git a/src/federation/party.rs b/src/federation/party.rs index cfcc569..148bd20 100644 --- a/src/federation/party.rs +++ b/src/federation/party.rs @@ -54,6 +54,7 @@ use super::event::{self, Does, Event, Signed}; use super::fold::Federation; use super::jcs::Json; use super::keys::{self, Key}; +use super::revision::{FEATURES, Revision}; use super::store::Id; use super::store::memory::Store; use super::version::Version; @@ -117,10 +118,23 @@ fn command() -> Command { .args(changing("NODE", "nodes", "node list")) .group(changes()), ) - .subcommand(Command::new("next").about( - "The version after the current one, to change and propose: numbered on, naming the \ - current one's hash, without its checkpoint", - )) + .subcommand( + Command::new("next") + .about( + "The version after the current one, to change and propose: numbered on, \ + naming the current one's hash, without its checkpoint", + ) + .arg( + Arg::new("revision") + .long("revision") + .value_name("FEATURE") + .help( + "Following the revision that adds FEATURE (federation.md, Changing \ + the federation): pass it once every party's nodes run a continuum \ + that knows it", + ), + ), + ) .subcommand( Command::new("propose") .about("Proposes the version a file holds (JSON), and says the proposal's hash") @@ -268,7 +282,28 @@ pub(crate) async fn main() -> Result<()> { return proposals(&node).await; } if name == "next" { - let next = next(&node.current().await?)?; + let current = node.current().await?; + let feature = sub.get_one::("revision"); + let next = next(¤t, feature.map(String::as_str))?; + if feature.is_none() { + // A later revision this client and the node know, said. + let known = node.revisions().await?; + if let Some(later) = Revision::known() + .filter(|revision| *revision > current.revision && known.contains(&revision.id())) + .last() + { + let name = later + .features() + .last() + .expect("a later revision adds one") + .name(); + eprintln!( + "The node knows {later}, the current version follows {}: --revision {name} \ + moves to it, once every party's nodes run a continuum that knows it", + current.revision + ); + } + } println!("{}", serde_json::to_string_pretty(&next)?); return Ok(()); } @@ -708,6 +743,19 @@ async fn vote( })) if hash == proposal => version, _ => bail!("the node's {proposing} isn't the proposal it names"), }; + // A later revision: the node knows it, or it stops at the version once it passes. + if yes + && let Ok(version) = Version::read(&proposed) + && version.revision != current.revision + && !node.revisions().await?.contains(&version.revision.id()) + { + bail!( + "{proposal} moves to {}, which the node doesn't know: once it passed, a node that \ + doesn't stops at it, and votes nothing till upgraded; upgrade this node and every \ + other of the party to a continuum that knows it, then back it", + version.revision + ); + } // The votes on its party's earlier proposals it backed, for the nays among them. let mut nays = Vec::new(); let backed: BTreeSet = record @@ -842,8 +890,9 @@ async fn proposals(node: &Node) -> Result<()> { /// The version after `current`, to change and propose: `current` numbered on, naming its /// hash as the version it changes, and without the checkpoint it names, whose heads are -/// behind: a version naming them again is never written. -fn next(current: &Version) -> Result { +/// behind: a version naming them again is never written. With `feature`, following the +/// revision that adds it, where that isn't earlier than the current one's. +fn next(current: &Version, feature: Option<&str>) -> Result { let mut next: JsonValue = serde_json::from_slice(¤t.json.bytes())?; let fields = next .as_object_mut() @@ -851,6 +900,28 @@ fn next(current: &Version) -> Result { fields.insert("number".to_owned(), (current.number + 1).into()); fields.insert("changes".to_owned(), current.hash.to_string().into()); fields.remove("checkpoint"); + if let Some(name) = feature { + let Some(feature) = FEATURES.iter().find(|feature| feature.name() == name) else { + let names: Vec<&str> = FEATURES.iter().map(|feature| feature.name()).collect(); + bail!( + "no feature {name:?} this continuum knows: it knows {}", + if names.is_empty() { + "none".to_owned() + } else { + names.join(", ") + } + ); + }; + let revision = feature.revision(); + if revision < current.revision { + bail!( + "the current version follows {}, later than {revision}: a version never \ + follows an earlier revision than the one it changes", + current.revision + ); + } + fields.insert("revision".to_owned(), revision.id().to_string().into()); + } Ok(next) } @@ -937,6 +1008,18 @@ impl Node { current(&self.counts().await?) } + /// The IDs of the revisions the node knows: none where it says none, as one too old to + /// know the base revision by name. + async fn revisions(&self) -> Result> { + let summary = self.get("/events").await?; + Ok(summary["revisions"] + .as_array() + .into_iter() + .flatten() + .filter_map(|revision| revision["id"].as_str().and_then(Id::from_hex)) + .collect()) + } + /// The bytes of an event the node's store holds. async fn event(&self, id: &Id) -> Result> { let response = self @@ -1104,22 +1187,38 @@ mod tests { } /// The next version is the current one numbered on, naming its hash, without its - /// checkpoint: a version changing it, as its parties may pass. + /// checkpoint: a version changing it, as its parties may pass. With a feature, it + /// follows the revision adding it, never an earlier one than the current version's. #[test] fn the_next_version_changes_the_current_one() { use crate::federation::harness::{Party, Spec}; + use crate::federation::revision::{Feature, Revision}; use crate::federation::store::Id; use crate::federation::version::Version; let first = Spec::first(&[&Party::new("tv", 1), &Party::new("lass", 2)], &[]); let mut second = first.after(first.hash()); second.checkpoint = Some(vec![Id::of(b"a head")]); let current = Version::read(&second.json()).unwrap(); - let next = super::next(¤t).unwrap(); + let next = super::next(¤t, None).unwrap(); assert_eq!(next["number"], current.number + 1); assert_eq!(next["changes"], current.hash.to_string()); assert!(next.get("checkpoint").is_none()); + assert!(next.get("revision").is_none()); let next = Version::read(&crate::federation::client::json(&next).unwrap()).unwrap(); next.changes_validly(Some(¤t)).unwrap(); + let revised = super::next(¤t, Some("merge-events")).unwrap(); + let revised = Version::read(&crate::federation::client::json(&revised).unwrap()).unwrap(); + assert_eq!(revised.revision, Feature::MergeEvents.revision()); + revised.changes_validly(Some(¤t)).unwrap(); + // Kept on, where nothing is said. + let kept = super::next(&revised, None).unwrap(); + let kept = Version::read(&crate::federation::client::json(&kept).unwrap()).unwrap(); + assert_eq!(kept.revision, revised.revision); + let why = super::next(¤t, Some("elsewhere")) + .unwrap_err() + .to_string(); + assert!(why.contains("merge-events"), "{why}"); + assert_ne!(revised.revision, Revision::default()); } /// Its options come from configuration files as the node's do, arguments winning. diff --git a/src/federation/revision.rs b/src/federation/revision.rs index 3c6261b..7be6254 100644 --- a/src/federation/revision.rs +++ b/src/federation/revision.rs @@ -111,6 +111,22 @@ impl Revision { } } +/// The revision a version's `revision` names (`named`, none for the base revision), as +/// people read it: with its ID where it names one, and where this continuum doesn't know +/// it, so said. +pub(crate) fn described(named: Option<&Json>) -> String { + let Some(named) = named else { + return Revision::default().to_string(); + }; + match named.as_str().and_then(Id::from_hex) { + Some(id) => match Revision::of(&id) { + Some(revision) => format!("{revision}, {id}"), + None => format!("{id}, a revision this continuum doesn't know"), + }, + None => "no revision's ID".to_owned(), + } +} + /// 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 { @@ -148,5 +164,13 @@ mod tests { for revision in Revision::known() { assert_eq!(Revision::of(&revision.id()), Some(revision)); } + assert_eq!(described(None), "the base revision"); + let one = Json::Str(Revision(1).id().to_string()); + assert_eq!( + described(Some(&one)), + format!("revision 1 (merge-events), {}", Revision(1).id()) + ); + let unknown = Json::Str(Id::of(b"elsewhere").to_string()); + assert!(described(Some(&unknown)).ends_with("a revision this continuum doesn't know")); } } -- cgit v1.3.1