diff options
| -rw-r--r-- | docs/federation.md | 77 | ||||
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/upgrades.md | 34 | ||||
| -rw-r--r-- | docs/guides/federation/when-things-go-wrong.md | 11 | ||||
| -rw-r--r-- | src/federation/mod.rs | 1 | ||||
| -rw-r--r-- | src/federation/revision.rs | 123 | ||||
| -rw-r--r-- | src/federation/version.rs | 73 |
7 files changed, 264 insertions, 57 deletions
diff --git a/docs/federation.md b/docs/federation.md index a547026..766c9a6 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -23,8 +23,9 @@ whoever wants to carry on with whom does so. Claims about the code are marked A swarm is federated from its genesis change, or not at all ([Starting a federation](#starting-a-federation)). Nothing else changes: a swarm that isn't stays as it is, its registry, rules, remakes and replay included. Which federation a -swarm follows is a number of its own, in each version of its policy: this design is -federation 1 ([Changing the federation](#changing-the-federation)). Any group carries on +swarm follows is a number of its own, in each version of its policy, with the revision of +it: this design is federation 1 +([Changing the federation](#changing-the-federation)). Any group carries on with the policy it wants by forking ([Forks](#forks)), and leaves the federation by starting a swarm of another kind, with what it takes along. @@ -203,8 +204,9 @@ current at its heads, [Forks](#forks)). Spread out: { "path": "names/**", "writer": false } ] } ``` -* **The federation** it follows, and its **number**, one more than that of the version - it changes. +* **The federation** it follows, its **revision** of it where that isn't the base + revision (`revision`, [Changing the federation](#changing-the-federation)), and its + **number**, one more than that of the version it changes. * **The parties and their keys** (`keys`): one party at least, each by name, as continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with one key or more (`ssh-ed25519` or `ecdsa-sha2-nistp256`, [Events](#events)), none twice in the version. @@ -837,36 +839,53 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. Every node of a swarm runs the same version of continuum today. A federated swarm's parties can't be made to upgrade together, so from the first federated swarm on, continuum's releases work together in one, and what all its nodes must agree on is named -by the federation's number: the rules of this design, an event and its signature, how a -path and a version are spelled and read, the sizes each may have, how an event is judged -and what the events read as, which version a node takes and which is current, what a -checkpoint keeps and how it is spelled; and of the store on Automerge -([`store.md`](store.md)), what the document holds, what a change writes, the snapshot, -and the Automerge version, whose encoding fixes a change's hash. +by the federation's number and its revision: the rules of this design, an event and its +signature, how a path and a version are spelled and read, the sizes each may have, how an +event is judged and what the events read as, which version a node takes and which is +current, what a checkpoint keeps and how it is spelled; and of the store on Automerge +([`store.md`](store.md)), what the document holds, what a change writes, the snapshot, and +the Automerge version, whose encoding fixes a change's hash. -A change to the federation is a design like this one, with the next number. A swarm -moves to it by a version of its policy that names it (`"federation": 2`), which the -parties pass once their nodes run a continuum that knows it. A node that doesn't know -the federation its swarm's root names holds no store, and says so. One that doesn't read -a version that passed on the version it reads stops at the version event writing it, and +Of that, what is judged at an event's history changes by a **revision** of federation 1, +which a version names by its ID (`"revision": "<ID>"`); one naming none follows the +**base revision**, which federation 1 began with, keys of type `ecdsa-sha2-nistp256` +among it. A revision adds a feature to those of the one before, and its ID is the SHA-256 +of the JCS list of its features' names, so that a continuum that doesn't know a revision, +another build's among them, can't read a version naming it. There are none yet but the +base revision. What no history judges, the document, a change, the snapshot and the +Automerge version, no version names: a change there splits the swarm until every node +runs it ([`guides/federation/upgrades.md`](guides/federation/upgrades.md)). + +A version leaves `revision` out for the base revision, and names a revision no earlier +than that of the version it changes. What a revision adds counts at a history only where +the version current there names that revision or a later one: before, every node judges +as before, so that what a party uses early, every node refuses alike. A version is read by +the revision it names, so one moving to a revision may already hold what that revision +adds to a version; its proposal, the votes on it and its version event are judged under +the version before. + +A node that doesn't read a version that passed on the version it reads, of a revision or +a federation it doesn't know or none at all, stops at the version event writing it, and says so: it takes nothing and refuses nothing from then on, leaving out none of it, a remake's snapshot neither, and keeps none of it across a restart, until it runs a continuum that reads it, or its operator has it drop that event ([`store.md`](store.md), -[A node's own](store.md#a-nodes-own)). Dropped, the node refuses -that event and any writing that version, as any version its operator had it drop, and -goes on under the version before. One beside the version it reads, it refuses of its own, -as any other ([Changing the policy](#changing-the-policy)). +[A node's own](store.md#a-nodes-own)). Dropped, the node refuses that event and any +writing that version, as any version its operator had it drop, and goes on under the +version before. One beside the version it reads, it refuses of its own, as any other +([Changing the policy](#changing-the-policy)). A node that doesn't know the federation its +swarm's root names holds no store, and says so. + +So a revision is rolled out, then passed: every party's operators restart its nodes on a +continuum that knows it, and the parties pass a version naming it once theirs do, as a +party's client backs no version it doesn't read. Who hasn't by then stops at that version, +and takes part again once it has. Once a store moved to a checkpoint at a version naming +a revision, nodes join it only from a pinned checkpoint, and nobody judges what came +before again: a later continuum may hold only stores at that revision or after, and leave +out the rules of the revisions before. -A change that only has the federation take what it refused, and reads nothing it took -otherwise, keeps the number: the keys of type `ecdsa-sha2-nistp256` taken beside Ed25519 -ones are such a change. It is rolled out first and used after: every node runs a -continuum that takes it before any party uses it. A node that doesn't refuses what uses -it, and reads otherwise than the others until it does; at a version naming such a key, -which it doesn't read, it stops, as above. So that no party picks the moment nodes part, -the next such change names itself in the version, by a field that only a version using -it gives: a continuum that takes it takes what it adds only under a version naming it, -which two thirds pass, and a node running one that doesn't stops at that version rather -than refusing what follows. +A change a node can't make while it reads the versions before by their own rules is a +federation of its own, a design like this one with the next number, which a version names +(`"federation": 2`). ## The registry on it diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 5a44306..32f8756 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -31,7 +31,7 @@ by them, in its words. * [`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 says. + federation's number and its revision say. * [`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/upgrades.md b/docs/guides/federation/upgrades.md index df01b05..a106137 100644 --- a/docs/guides/federation/upgrades.md +++ b/docs/guides/federation/upgrades.md @@ -16,14 +16,14 @@ continuum's first release, take every upgrade as such a change. Nobody runs every node of a federated swarm: each party's operators upgrade its nodes. Agree on when, among the parties, and upgrade close together. -## The federation's number +## The federation's number and its revision What every node must agree on, byte for byte, is named by the federation's number, -which every version gives (`"federation": 1`): the rules, how an event, a version and a -checkpoint are spelled, signed and judged, what the events read as, and, on Automerge, -what the document holds, what a change writes, the genesis change built from the root, -the snapshot, and the Automerge version, whose encoding fixes a change's hash. Their -bytes are fixed by vectors that the tests check (`federation::vectors`). +which every version gives (`"federation": 1`), and its revision: the rules, how an event, +a version and a checkpoint are spelled, signed and judged, what the events read as, and, +on Automerge, what the document holds, what a change writes, the genesis change built from +the root, the snapshot, and the Automerge version, whose encoding fixes a change's hash. +Their bytes are fixed by vectors that the tests check (`federation::vectors`). There is one federation, 1. A node knows it alone: a version naming another is none to it. Where one passes, the node stops at the version event writing it, taking nothing and @@ -32,16 +32,14 @@ that event ([`when-things-go-wrong.md`](when-things-go-wrong.md), [A node stopped](when-things-go-wrong.md#a-node-stopped)). A proposal naming another is taken as a proposal, and a party's client backs none. -A change to any of that is a federation of its own, with the next number, and its own -design. A swarm moves to it by a version naming it, which the parties pass once their -nodes run a continuum that knows it. +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. -A change that only has the federation take what it refused, and reads nothing it took -otherwise, keeps the number: `ecdsa-sha2-nistp256` keys beside Ed25519 ones. Roll it out -first, then use it: every party's operators upgrade their nodes, and only then does a -party name such a key in a version or a key set, or sign with one. A node not upgraded -refuses what uses it and reads otherwise than the others; at a version naming such a key, -none to it, it stops, until it is upgraded. Nothing but agreement keeps a party from using -it early. The next such change names itself in the version, so that two thirds decide -when it is used: what it adds is taken only under a version naming it, and a node not -upgraded stops at that version. +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). diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md index fad11c5..8171201 100644 --- a/docs/guides/federation/when-things-go-wrong.md +++ b/docs/guides/federation/when-things-go-wrong.md @@ -78,13 +78,14 @@ can't judge`), and `GET /events` names the event, why, and how many it holds bac ```sh curl -s -u tv:secret localhost:3000/events | jq -r .stopped.why -# version 3c0f… passed, and doesn't read as one here: of federation 2, and this -# continuum knows 1 alone +# version 3c0f… passed, and doesn't read as one here: revision 9f2c…, which this +# continuum doesn't know, as it knows the base revision alone: a release that knows it +# reads this version ``` -`why` says what doesn't read: a federation this continuum doesn't know, a field it -doesn't know, by its name, a key of a type it doesn't take, or whatever else makes a -version none ([`proposing-and-voting.md`](proposing-and-voting.md), +`why` says what doesn't read: a federation or a revision this continuum doesn't know, a +field it doesn't know, by its name, a key of a type it doesn't take, or whatever else +makes a version none ([`proposing-and-voting.md`](proposing-and-voting.md), [Writing a version](proposing-and-voting.md#writing-a-version)). Upgrade the node to a continuum that reads it: restarted, it reads its store anew and 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"); |
