summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 04:00:12 +0000
committertv <tv@krebsco.de>2026-11-19 05:13:38 +0100
commit0d2467e15ec0c9c035b1074a2dd4eece6b24c599 (patch)
treee544ce8ae1c31e9556191d3f99157b5bd61b1f14
parentefaf79e7fd55db2b9704ccefedde33346f874a1d (diff)
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.
-rw-r--r--docs/guides/federation/README.md4
-rw-r--r--docs/guides/federation/proposing-and-voting.md3
-rw-r--r--docs/guides/federation/upgrades.md76
-rw-r--r--docs/openapi.yaml28
-rw-r--r--src/api/events.rs28
-rw-r--r--src/federation/client.rs22
-rw-r--r--src/federation/party.rs117
-rw-r--r--src/federation/revision.rs24
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": "<ID>"`); 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<AppState>) -> 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<AppState>) -> 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<JsonValue> {
+ 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<AppState>, Path(id): Path<String>) -> Response {
@@ -186,6 +205,11 @@ async fn counts(State(state): State<AppState>) -> 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(&current.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<String> {
fn text(json: Option<&Json>) -> String {
json.map_or_else(
@@ -450,6 +451,14 @@ pub(crate) fn changes(current: &Json, proposed: &Json) -> Vec<String> {
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(&current, &current).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(&current, &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::<String>("revision");
+ let next = next(&current, 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<Id> = 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<JsonValue> {
+/// 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<JsonValue> {
let mut next: JsonValue = serde_json::from_slice(&current.json.bytes())?;
let fields = next
.as_object_mut()
@@ -851,6 +900,28 @@ fn next(current: &Version) -> Result<JsonValue> {
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<Vec<Id>> {
+ 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<Vec<u8>> {
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(&current).unwrap();
+ let next = super::next(&current, 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(&current)).unwrap();
+ let revised = super::next(&current, 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(&current)).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(&current, 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"));
}
}