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. --- docs/guides/federation/README.md | 4 +- docs/guides/federation/proposing-and-voting.md | 3 + docs/guides/federation/upgrades.md | 76 ++++++++++++++-- docs/openapi.yaml | 28 +++++- src/api/events.rs | 28 +++++- src/federation/client.rs | 22 ++++- src/federation/party.rs | 117 +++++++++++++++++++++++-- src/federation/revision.rs | 24 +++++ 8 files changed, 276 insertions(+), 26 deletions(-) diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 32f8756..4c5b33b 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -30,8 +30,8 @@ by them, in its words. is its own, the store file, dropping events and taking them back. * [`remakes.md`](remakes.md): compactions only, the electorate, the snapshot, putting again after a switch, two epochs for one, and rejoining. -* [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, and what the - federation's number and its revision say. +* [`upgrades.md`](upgrades.md): upgrading the nodes of a federated swarm, what the + federation's number and its revision say, and moving to a later revision. * [`watching.md`](watching.md): what a node's API and its log say that needs an operator or a party. * [`building-on-the-api.md`](building-on-the-api.md): an application reading what diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index 0c3e1a8..330d670 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -37,6 +37,9 @@ for the changes made most): * **`checkpoint`**, only where the version moves the store to a checkpoint: the heads. Otherwise leave it out, though the current version names one: its heads are behind, and a version naming them again is never written. +* **`revision`**, the revision of the federation the version follows, by its ID, left + out for the base revision: the current version's, or a later one (`next --revision`, + [`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)). Party names are 1 to 64 of `A-Z a-z 0-9 . _ @ -`; a version names up to 96 parties; a party has up to 16 keys and 64 nodes; a rule's path is a path as a write's is, its first diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md index a106137..0a1a094 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -1,7 +1,8 @@ -# Upgrades and the federation's number +# Upgrades and the federation's revisions -Upgrading the continuum a federated swarm's nodes run, and what the federation's number -in each version says. The rules are the design's ([`federation.md`](../../federation.md), +Upgrading the continuum a federated swarm's nodes run, what the federation's number and +its revision in each version say, and moving to a later revision. The rules are the +design's ([`federation.md`](../../federation.md), [Changing the federation](../../federation.md#changing-the-federation)). ## Upgrading continuum @@ -34,12 +35,69 @@ taken as a proposal, and a party's client backs none. What is judged at an event's history changes by a revision of federation 1, which a version names by its ID (`"revision": ""`); a version naming none follows the base -revision, `ecdsa-sha2-nistp256` keys beside Ed25519 ones among it. There are none yet but -the base revision. A node that doesn't know the revision a version names reads it as it -reads one of another federation: none, and it stops at a version event writing it. What a -revision adds is taken only under a version naming it, which two thirds pass, so no party -uses it early: roll it out first, every party's operators upgrading their nodes, then pass -a version naming it. +revision, `ecdsa-sha2-nistp256` keys beside Ed25519 ones among it. Each later revision +adds a feature to the one before; `federation.md` lists them +([Changing the federation](../../federation.md#changing-the-federation)). A node that +doesn't know the revision a version names reads it as it reads one of another federation: +none, and it stops at a version event writing it. What a revision adds is taken only under +a version naming it, which two thirds pass, so no party uses it early. What no history judges, the document, a change and the snapshot, no version names: a change there splits the swarm until every node runs it (above). + +## Moving to a revision + +First every node runs a continuum that knows the revision, then the parties pass a +version naming it. Restarting the nodes changes nothing in the swarm: what the revision +adds is refused everywhere until a version names it. + +1. **Upgrade.** Each party's operators restart every node of the party on such a + continuum. A node says which revisions it knows: + + ```sh + curl -s -u tv:secret localhost:3000/events | jq -r '.revisions[].named' + # the base revision + # revision 1 (merge-events) + ``` + + and the revision of the current version, in `GET /events/counts` + (`.version.revision.named`). + +2. **Propose.** A party begins the next version following it, by the feature it adds; + `next` says so where its node knows a later revision than the current version's: + + ```sh + continuum-party --node http://tv:secret@localhost:3000 next --revision merge-events \ + > next.json + continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ + --record tv.record propose next.json + # proposal 5e81… + ``` + + It may already hold what the revision adds to a version: a version is read by the + revision it names. Its proposal and the votes on it are judged under the current + version, and what the revision adds to events counts from the version after. + +3. **Vote.** Each party backs it once every node of the party knows the revision: + + ```sh + continuum-party --node http://tv:secret@localhost:3000 proposals + # 5e81…: can still pass; true: tv; false: nobody + # changes: "1f4c…" -> "8a20…" + # number: 4 -> 5 + # revision: the base revision -> revision 1 (merge-events), 6c1d… + continuum-party --node http://tv:secret@localhost:3000 --key tv.key \ + --record tv.record vote 5e81… yes + ``` + + The client backs it only where its node knows the revision, and says so otherwise; it + can't see the party's other nodes, which its operators check. A node voting by itself + backs no version changing the revision: vote on it by hand, through that node. A party + not ready leaves it be, or votes `false` to end it. + +4. **After.** Once two thirds passed it, what the revision adds counts from that version + on. A node that doesn't know it stops at that version (`stopped` in `GET /events`, + [`when-things-go-wrong.md`](when-things-go-wrong.md), + [A node stopped](when-things-go-wrong.md#a-node-stopped)), takes nothing and votes + nothing until upgraded, and reads its store anew once restarted on a continuum that + knows it. diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 5c90037..05e29d5 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1425,7 +1425,11 @@ paths: that one among them, taking nothing and refusing nothing until upgraded or told to drop it (`/admin/events/drop`); the party this node is of (`party`, `--store-party`), and whether it votes for it by itself (`votesByItself`), and so - casts votes by hand (`POST /admin/events/vote`). + casts votes by hand (`POST /admin/events/vote`); and the revisions of the + federation this continuum knows (`revisions`), the base revision first, each its + number, its ID, the feature it adds and what that adds (none for the base + revision), and as people read it (`named`): a version naming another, this node + can't read. responses: '200': description: The store. @@ -1433,7 +1437,8 @@ paths: application/json: schema: type: object - required: [store, checkpoint, heads, taken, stopped, party, votesByItself] + required: [store, checkpoint, heads, taken, stopped, party, votesByItself, + revisions] properties: store: type: string @@ -1459,6 +1464,22 @@ paths: type: [string, 'null'] votesByItself: type: boolean + revisions: + type: array + items: + type: object + required: [number, id, feature, adds, named] + properties: + number: + type: integer + id: + type: string + feature: + type: [string, 'null'] + adds: + type: [string, 'null'] + named: + type: string '404': $ref: '#/components/responses/Error' post: @@ -1528,7 +1549,8 @@ paths: summary: What counts description: | What counts, as the store reads now (docs/federation.md): the current version - (its number, its hash, and the version itself), each party's keys and nodes, the + (its number, its hash, its revision, by number and ID and as people read it, and + the version itself), each party's keys and nodes, the value at each place, the members, each `[node, party]`, and the proposals on the current version, by their hash, each with the IDs of the events proposing it that a vote may build on (`proposals`: of a version naming a checkpoint, those above diff --git a/src/api/events.rs b/src/api/events.rs index b13de63..7bb322e 100644 --- a/src/api/events.rs +++ b/src/api/events.rs @@ -21,6 +21,7 @@ use crate::federation::client; use crate::federation::fold::Federation; use crate::federation::fork; use crate::federation::jcs::Json as Jcs; +use crate::federation::revision::Revision; use crate::federation::store::Id; use crate::federation::store::memory::{Offered, Refusal, Store}; use crate::state::AppState; @@ -83,8 +84,8 @@ fn why(refusal: &Refusal) -> String { /// `GET /events`: the store's ID, its checkpoint's, its heads, as many as an event may /// name, what a new event builds on (`Store::building_on`), how many events it took -/// after its checkpoint, the event it stopped at, if any, the node's party, and whether -/// the node votes for it by itself. +/// after its checkpoint, the event it stopped at, if any, the node's party, whether the +/// node votes for it by itself, and the revisions of the federation its continuum knows. async fn summary(State(state): State) -> Response { let party = state.holding.party().map(str::to_owned); let votes = state.holding.votes_by_itself(); @@ -100,10 +101,28 @@ async fn summary(State(state): State) -> Response { "stopped": stopped, "party": party, "votesByItself": votes, + "revisions": revisions(), }) }) } +/// The revisions this continuum knows, the base revision first: each its number, its ID, +/// the feature it adds and what that adds, and as people read it. +fn revisions() -> Vec { + Revision::known() + .map(|revision| { + let adds = revision.features().last(); + json!({ + "number": revision.0, + "id": revision.id().to_string(), + "feature": adds.map(|feature| feature.name()), + "adds": adds.map(|feature| feature.what()), + "named": revision.to_string(), + }) + }) + .collect() +} + /// `GET /events/{id}`: an event the store holds, taken or kept by its checkpoint, or its /// checkpoint, as its bytes. async fn event(State(state): State, Path(id): Path) -> Response { @@ -186,6 +205,11 @@ async fn counts(State(state): State) -> Response { "version": { "number": current.number, "hash": current.hash.to_string(), + "revision": { + "number": current.revision.0, + "id": current.revision.id().to_string(), + "named": current.revision.to_string(), + }, "version": plain(¤t.json), }, "parties": parties, 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