From 0ba4c7363cfa2a9963ecd6a06392ea5c4dac3ad1 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 19:44:37 +0000 Subject: node: a swarm holding a store, started from its root or joined by its ID Behind the `federation` feature, two options: * `--store-root PATH` starts a swarm holding a store, or goes on with one, from the store's root, as bytes in the file, which the federation must take as a root. With no document to start on, the node builds the genesis change from it, as every node given the root does, and is ready at once; a document to start on must be of the root's swarm. * `--store-id ID` joins one through seeds by its ID, the root's SHA-256 in hex. An empty document of the first epoch takes as its root only that store's genesis change, built again from the root it holds (`document::events::is_genesis`), whatever peers name: the root pin doesn't wait for seeds, nor is disputed. Either names the swarm the node joins, which a state file must remember too, and can't be combined with the other, nor with what makes a new swarm's first change (`--genesis`, `--bootstrap-users`, `--bootstrap-keys`, `--bootstrap-policy`, `--remake`, `--genesis-root`). The root is read as a file of its own kind (`store`), counted among the node's files. --- src/access/screen.rs | 78 +++++++++++++++++++++++++++++++ src/config/mod.rs | 65 ++++++++++++++++++++++++++ src/files.rs | 14 ++++++ src/main.rs | 20 +++++++- src/node.rs | 10 +++- src/simtest/mod.rs | 2 + src/swarm/bootstrap.rs | 124 +++++++++++++++++++++++++++++++++++++++++++++++++ src/swarm/roots.rs | 7 +++ 8 files changed, 317 insertions(+), 3 deletions(-) (limited to 'src') diff --git a/src/access/screen.rs b/src/access/screen.rs index bbcedcf..885badc 100644 --- a/src/access/screen.rs +++ b/src/access/screen.rs @@ -81,6 +81,12 @@ pub(crate) struct Screening { /// Whether the document held a policy, known or not, since this node took it up /// (`policed`). policed: bool, + /// The store this node's swarm holds, by its root's ID (`--store-root`, + /// `--store-id`): an empty document of the first epoch takes as its root only that + /// store's genesis change (`document::events::is_genesis`), whatever peers name. + /// Kept from one document to the next. + #[cfg(feature = "federation")] + pub(crate) store: Option, } /// Which change an empty document of the first epoch takes as its root: any (nothing @@ -143,6 +149,18 @@ impl Screening { } } + /// Itself, for a swarm holding the store `store`, if any. + pub(crate) fn holding( + self, + #[cfg(feature = "federation")] store: Option, + ) -> Self { + Screening { + #[cfg(feature = "federation")] + store, + ..self + } + } + /// Whether `doc` holds anything at the policy's place, a policy known or not or what /// reads as none (an envelope holding `null`), in any of the maps on the way to it, a /// read showing them or not (`store::held_anywhere`), or did since this node took it up: @@ -166,6 +184,8 @@ impl Screening { epoch_seq, root_pin: std::mem::take(&mut self.root_pin), policed: self.policed, + #[cfg(feature = "federation")] + store: self.store, ..Screening::default() }; } @@ -791,6 +811,29 @@ pub(crate) fn apply_bytes( } }); } + #[cfg(feature = "federation")] + if epoch.generation == 0 + && doc.get_heads().is_empty() + && let Some(store) = &screening.store + { + use crate::federation::store::Fold; + changes.retain(|change| { + if !change.deps().is_empty() + || crate::document::events::is_genesis( + change, + crate::federation::fold::Federation::NAME, + store, + ) + { + return true; + } + pinned_out.push(( + change.clone(), + format!("a root other than the genesis change of the store {store}"), + )); + false + }); + } let mut refused_roots = Vec::new(); for (change, why) in pinned_out { screening.refusals.insert(change.hash(), change.hash()); @@ -1252,6 +1295,41 @@ mod tests { assert_ne!(ours.get_actor(), &actor); } + /// An empty document of a swarm holding a store takes as its root only that store's + /// genesis change, under the root's writer or not. + #[cfg(feature = "federation")] + #[test] + fn a_store_takes_its_genesis_change_as_its_root() { + use crate::document::events; + use crate::federation::store::{Fold, Id}; + let root = b"a root".to_vec(); + let id = Id::of(&root); + let screening = std::sync::Mutex::new(Screening::default().holding(Some(id))); + let offer = |doc: &mut Document, change: &Change| { + apply_bytes( + doc, + Epoch::GENESIS, + 0, + change.raw_bytes(), + &screening, + None, + &mut crate::document::PatchLog::inactive(), + ) + .unwrap() + }; + let mut forged = Document::new().with_actor(events::genesis_writer(&id)); + crate::document::testing::change(&mut forged, |doc| { + store::write_path(doc, &path("_continuum/swarm"), &json!(id.to_string())).unwrap(); + }); + let forged = forged.get_last_local_change().unwrap().clone(); + let mut doc = Document::new(); + offer(&mut doc, &forged); + assert!(doc.get_heads().is_empty()); + let genesis = events::genesis(crate::federation::fold::Federation::NAME, &root); + offer(&mut doc, &genesis); + assert_eq!(doc.get_heads(), vec![genesis.hash()]); + } + /// Judged as its writer saw the registry: a grant earlier in the same batch counts. #[test] fn a_grant_in_the_same_batch_counts() { diff --git a/src/config/mod.rs b/src/config/mod.rs index 14bd984..ae6070f 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -200,6 +200,22 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[ None, "The hash of the swarm's genesis change (hex, as its genesis node logs it and GET /admin/epochs shows it): joining with an empty document, the only root this node takes. Without, the one its peers name once each seed named one or ten seconds passed since the first did, none while they name different ones (docs/access.md).", ), + #[cfg(feature = "federation")] + option( + "store-root", + Kind::Text, + "PATH", + None, + "Start a swarm holding a store (docs/store.md), or go on with one, from the store's root, as bytes in this file: the node builds the swarm's genesis change from it, as every node given the root does, and is ready at once. The swarm's ID is the root's: its SHA-256, in hex. Can't be combined with store-id, genesis, or what makes a new swarm's first change (bootstrap-users, bootstrap-keys, bootstrap-policy, remake, genesis-root).", + ), + #[cfg(feature = "federation")] + option( + "store-id", + Kind::Text, + "ID", + None, + "Join a swarm holding a store (docs/store.md) through seeds, by its ID: its root's SHA-256, in hex. Joining with an empty document, the node takes as its root only that store's genesis change, built again from the root it holds. Can't be combined with store-root, genesis, or what makes a new swarm's first change.", + ), option( "strict-keys", Kind::List, @@ -631,6 +647,10 @@ pub(crate) struct Settings { pub(crate) bootstrap_keys: Vec, pub(crate) bootstrap_policy: Option, pub(crate) genesis_root: Option, + #[cfg(feature = "federation")] + pub(crate) store_root: Option, + #[cfg(feature = "federation")] + pub(crate) store_id: Option, #[serde(default)] pub(crate) strict_keys: Vec, @@ -953,6 +973,8 @@ impl Settings { if self.genesis && self.recover_from.is_some() { bail!("recover-from starts the swarm from a backup; it can't be combined with genesis"); } + #[cfg(feature = "federation")] + self.check_store()?; if self.node_key_create && self.node_key_file.is_none() { bail!("node-key-create creates the key at node-key-file; set that too"); } @@ -1079,6 +1101,45 @@ impl Settings { }) } + /// A swarm holding a store, started from its root or joined by its ID: one of them, and + /// nothing that makes a new swarm's first change. + #[cfg(feature = "federation")] + fn check_store(&self) -> Result<()> { + if let Some(id) = &self.store_id + && crate::federation::store::Id::from_hex(id).is_none() + { + bail!("store-id: {id:?} isn't a store's ID (64 hex digits)"); + } + let store = match (&self.store_root, &self.store_id) { + (Some(_), Some(_)) => { + bail!("store-root names the store's ID itself; unset store-id") + } + (Some(_), None) => "store-root", + (None, Some(_)) => "store-id", + (None, None) => return Ok(()), + }; + let first_change = [ + ("genesis", self.genesis), + ("bootstrap-users", !self.bootstrap_users.is_empty()), + ("bootstrap-keys", !self.bootstrap_keys.is_empty()), + ("bootstrap-policy", self.bootstrap_policy.is_some()), + ("remake", self.remake.is_some()), + ("genesis-root", self.genesis_root.is_some()), + ]; + let set: Vec<&str> = first_change + .iter() + .filter(|(_, set)| *set) + .map(|(name, _)| *name) + .collect(); + if !set.is_empty() { + bail!( + "{store}: a swarm holding a store starts from its root's genesis change, so these don't apply: {}", + set.join(", ") + ); + } + Ok(()) + } + /// A relay that is no node: libp2p alone, dialable, with a key kept, and nothing /// about a swarm or a document. fn check_relay_only(&self) -> Result<()> { @@ -1104,6 +1165,10 @@ impl Settings { ("bootstrap-users", !self.bootstrap_users.is_empty()), ("bootstrap-keys", !self.bootstrap_keys.is_empty()), ("bootstrap-policy", self.bootstrap_policy.is_some()), + #[cfg(feature = "federation")] + ("store-root", self.store_root.is_some()), + #[cfg(feature = "federation")] + ("store-id", self.store_id.is_some()), ("alias", self.alias.is_some()), ("dashboard-url", self.dashboard_url.is_some()), ("debug-api", self.debug_api), diff --git a/src/files.rs b/src/files.rs index bc8fb8e..7c9d808 100644 --- a/src/files.rs +++ b/src/files.rs @@ -21,15 +21,27 @@ pub(crate) enum FileKind { Backup, /// The input of a genesis remake (`--genesis --remake`). Remake, + /// A store's root (`--store-root`). + #[cfg(feature = "federation")] + Store, } impl FileKind { + #[cfg(not(feature = "federation"))] pub(crate) const ALL: [FileKind; 4] = [ FileKind::State, FileKind::Document, FileKind::Backup, FileKind::Remake, ]; + #[cfg(feature = "federation")] + pub(crate) const ALL: [FileKind; 5] = [ + FileKind::State, + FileKind::Document, + FileKind::Backup, + FileKind::Remake, + FileKind::Store, + ]; pub(crate) fn as_str(self) -> &'static str { match self { @@ -37,6 +49,8 @@ impl FileKind { FileKind::Document => "document", FileKind::Backup => "backup", FileKind::Remake => "remake", + #[cfg(feature = "federation")] + FileKind::Store => "store", } } diff --git a/src/main.rs b/src/main.rs index 6d0d82f..d074475 100644 --- a/src/main.rs +++ b/src/main.rs @@ -173,6 +173,17 @@ async fn main() -> Result<()> { &files, &force, )?; + // A swarm holding a store: started from its root, or joined by its ID. + #[cfg(feature = "federation")] + let store = + bootstrap::StoreStart::of(args.store_root.as_deref(), args.store_id.as_deref(), &files)?; + #[cfg(feature = "federation")] + let starting = match &store { + Some(store) => { + store.starting(starting, remembered.as_ref().map(|r| r.swarm_id.as_str()))? + } + None => starting, + }; let ( initial_doc, starting_epoch, @@ -298,6 +309,8 @@ async fn main() -> Result<()> { session_lifetime: args.session_lifetime, challenge_lifetime: args.challenge_lifetime, genesis_root: args.genesis_root.as_deref().and_then(swarm::roots::parse), + #[cfg(feature = "federation")] + store: store.as_ref().map(|store| store.id), strict_keys: args .strict_keys .iter() @@ -322,8 +335,11 @@ async fn main() -> Result<()> { bootstrap::Start::FromDocument(origin) } None => { - if let Some(remembered) = remembered { - state.set_expected_swarm_id(remembered.swarm_id).await?; + let expected = remembered.map(|remembered| remembered.swarm_id); + #[cfg(feature = "federation")] + let expected = expected.or_else(|| store.as_ref().map(bootstrap::StoreStart::swarm_id)); + if let Some(expected) = expected { + state.set_expected_swarm_id(expected).await?; } if args.genesis { bootstrap::Start::Genesis diff --git a/src/node.rs b/src/node.rs index e5c68e0..f722112 100644 --- a/src/node.rs +++ b/src/node.rs @@ -85,6 +85,10 @@ pub(crate) struct NodeConfig { pub(crate) refused_writes_per_minute: usize, /// `--genesis-root`. pub(crate) genesis_root: Option, + /// The store a swarm holding one holds, by its root's ID (`--store-root`, + /// `--store-id`). + #[cfg(feature = "federation")] + pub(crate) store: Option, /// `--strict-keys`. pub(crate) strict_keys: Vec, /// `--cors-origins`. @@ -194,7 +198,11 @@ impl Node { config.genesis_root, &Default::default(), false, - )), + )) + .holding( + #[cfg(feature = "federation")] + config.store, + ), )), roots: Default::default(), genesis_root: config.genesis_root, diff --git a/src/simtest/mod.rs b/src/simtest/mod.rs index 40f2244..476658f 100644 --- a/src/simtest/mod.rs +++ b/src/simtest/mod.rs @@ -225,6 +225,8 @@ impl Sim { key_logins_per_user: 100, refused_writes_per_minute: 10, genesis_root: None, + #[cfg(feature = "federation")] + store: None, strict_keys: Vec::new(), cors_origins: Vec::new(), files: Arc::new(Files::default()), diff --git a/src/swarm/bootstrap.rs b/src/swarm/bootstrap.rs index aa6d06b..e6d5d21 100644 --- a/src/swarm/bootstrap.rs +++ b/src/swarm/bootstrap.rs @@ -249,6 +249,9 @@ pub(crate) enum Origin { Backup, /// This node's document file (`--document-file`). DocumentFile, + /// A store's root, its genesis change built from it (`--store-root`). + #[cfg(feature = "federation")] + Root, } impl Origin { @@ -256,10 +259,94 @@ impl Origin { match self { Origin::Backup => "the backup", Origin::DocumentFile => "the document file", + #[cfg(feature = "federation")] + Origin::Root => "the store's root", } } } +/// The swarm holding a store that a node starts from its root (`--store-root`) or joins +/// by its ID (`--store-id`). +#[cfg(feature = "federation")] +pub(crate) struct StoreStart { + /// The root's ID, the swarm's. + pub(crate) id: crate::federation::store::Id, + /// The root, given. + root: Option>, +} + +#[cfg(feature = "federation")] +impl StoreStart { + /// The store `root` (a file holding it) or `id` names, if either does: a root the + /// federation takes as one, which a store's root must be. + pub(crate) fn of(root: Option<&Path>, id: Option<&str>, files: &Files) -> Result> { + use crate::federation::fold::Federation; + use crate::federation::store::{Id, memory::Store}; + let Some(path) = root else { + return Ok(id + .and_then(Id::from_hex) + .map(|id| StoreStart { id, root: None })); + }; + let root = files + .read(FileKind::Store, path) + .with_context(|| format!("Reading the store's root {}", path.display()))? + .with_context(|| format!("The store's root {} doesn't exist", path.display()))?; + if let Err(refused) = Store::::new(root.clone(), Vec::new()) { + bail!("The store's root {} is none: {}", path.display(), refused.0); + } + Ok(Some(StoreStart { + id: Id::of(&root), + root: Some(root), + })) + } + + /// The swarm's ID: the root's, in hex. + pub(crate) fn swarm_id(&self) -> String { + self.id.to_string() + } + + /// The document to start from, `starting` checked against the store: of its swarm, + /// as the state file's `remembered` is. Without one, given the root, the document of + /// its genesis change, which every node given the root builds alike; joining, none. + pub(crate) fn starting( + &self, + starting: Option, + remembered: Option<&str>, + ) -> Result> { + let swarm_id = self.swarm_id(); + if let Some(remembered) = remembered.filter(|remembered| *remembered != swarm_id) { + bail!( + "The state file remembers swarm {remembered}, not the store's ({swarm_id}): give the store's state file, or another" + ); + } + if let Some(starting) = starting { + if starting.swarm_id != swarm_id { + bail!( + "{} is of swarm {}, not the store's ({swarm_id})", + starting.origin.describe(), + starting.swarm_id + ); + } + return Ok(Some(starting)); + } + let Some(root) = &self.root else { + return Ok(None); + }; + use crate::federation::store::Fold; + let doc = document::events::started(crate::federation::fold::Federation::NAME, root)?; + info!(swarm_id = %swarm_id, "Starting the swarm holding the store from its root (--store-root)"); + Ok(Some(StartingDocument { + doc, + epoch: Epoch::GENESIS, + swarm_id, + origin: Origin::Root, + earlier_actors: Vec::new(), + signatures: Vec::new(), + resumable: None, + })) + } +} + /// A document the node starts from, ready at once: on the swarm and epoch it names. pub(crate) struct StartingDocument { /// Under a fresh actor. @@ -468,3 +555,40 @@ async fn report_joining(state: &AppState, seeds: &[String], unresolved: &[String "Still joining the swarm; trying on" ); } + +#[cfg(all(test, feature = "federation"))] +mod tests { + use super::*; + use crate::federation::store::Id; + + /// Given its root, a node starts the swarm holding the store from its genesis change, + /// on no other swarm's document; joining by its ID, from nothing. + #[test] + fn a_store_starts_from_its_root() { + let root = b"a root".to_vec(); + let store = StoreStart { + id: Id::of(&root), + root: Some(root), + }; + let started = store.starting(None, None).unwrap().unwrap(); + assert_eq!(started.swarm_id, store.swarm_id()); + assert_eq!(started.origin, Origin::Root); + assert_eq!(started.epoch, Epoch::GENESIS); + assert_eq!(read_swarm_id(&started.doc), Some(store.swarm_id())); + assert!(store.starting(None, Some("another")).is_err()); + let other = StoreStart { + id: Id::of(b"another"), + root: Some(b"another".to_vec()), + }; + assert!( + store + .starting(other.starting(None, None).unwrap(), None) + .is_err() + ); + let joining = StoreStart { + id: store.id, + root: None, + }; + assert!(joining.starting(None, None).unwrap().is_none()); + } +} diff --git a/src/swarm/roots.rs b/src/swarm/roots.rs index 930c190..2fb6d6e 100644 --- a/src/swarm/roots.rs +++ b/src/swarm/roots.rs @@ -206,6 +206,13 @@ pub(crate) fn repin(state: &AppState) { pin(state.genesis_root, &roots.named, awaiting) }; let mut screening = state.screening.lock_or_recover(); + // A swarm holding a store: its genesis change, whatever peers name. + #[cfg(feature = "federation")] + let pin = if screening.store.is_some() { + RootPin::Any + } else { + pin + }; if screening.root_pin != pin { match &pin { RootPin::Disputed => { -- cgit v1.3.1