aboutsummaryrefslogtreecommitdiffstats
path: root/src/swarm/bootstrap.rs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 19:44:37 +0000
committertv <tv@krebsco.de>2026-11-16 21:25:59 +0100
commit0ba4c7363cfa2a9963ecd6a06392ea5c4dac3ad1 (patch)
treefa40cfbfda010601eff9f9db148c5aa793aca0b2 /src/swarm/bootstrap.rs
parent3fccc4f6859cf0b4d93e7d166142e1ab9255723f (diff)
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.
Diffstat (limited to 'src/swarm/bootstrap.rs')
-rw-r--r--src/swarm/bootstrap.rs124
1 files changed, 124 insertions, 0 deletions
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<Vec<u8>>,
+}
+
+#[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<Option<Self>> {
+ 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::<Federation>::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<StartingDocument>,
+ remembered: Option<&str>,
+ ) -> Result<Option<StartingDocument>> {
+ 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());
+ }
+}