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/swarm/bootstrap.rs | 124 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) (limited to 'src/swarm/bootstrap.rs') 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()); + } +} -- cgit v1.3.1