aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 03:30:43 +0000
committertv <tv@krebsco.de>2026-11-17 04:40:15 +0100
commitc2f47d6f4cb37d482eddf9e2c31e40161c4111de (patch)
treeeae4a0672a56b98c0983aa43d6c25ec1513009b6
parentd5cc9482dd527ef9beb82671f6f35832b3280d57 (diff)
remake: a holding swarm's snapshot holds the store read at its base
A compaction's snapshot in a swarm holding a store holds the store as the node reads it from the document at the base, by its own refusals and its operator's drops (`docs/store.md`, Remakes): the checkpoint it reaches there, where it isn't the root, at `_continuum/checkpoint`; the root, the events that checkpoint keeps and those after it, each at its ID; and of the entries, the members'. What the checkpoint forgot, events nobody takes, and the entries of nodes that aren't members stay behind (`Holding::at_base`, `events::snapshot`, `Host::holding`).
-rw-r--r--src/document/events.rs24
-rw-r--r--src/federation/held.rs149
-rw-r--r--src/remake/catchup.rs2
-rw-r--r--src/remake/coordinator.rs4
-rw-r--r--src/remake/mod.rs5
-rw-r--r--src/remake/records.rs2
-rw-r--r--src/remake/snapshot.rs42
-rw-r--r--src/remake/switch.rs4
-rw-r--r--src/state/host.rs5
9 files changed, 237 insertions, 0 deletions
diff --git a/src/document/events.rs b/src/document/events.rs
index 1079999..37f1c70 100644
--- a/src/document/events.rs
+++ b/src/document/events.rs
@@ -179,6 +179,30 @@ pub(crate) fn checkpoint(doc: &impl ReadDoc) -> Option<Vec<u8>> {
}
}
+/// Writes into `write`, a remake's snapshot, the store it holds (`docs/store.md`,
+/// Remakes): `checkpoint`, where it isn't the root, at `_continuum/checkpoint`, and
+/// `events`, each at its ID, in the order of their IDs; all as bytes.
+pub(crate) fn snapshot(
+ write: &mut impl super::Transactable,
+ checkpoint: Option<&[u8]>,
+ events: &std::collections::BTreeMap<Id, Vec<u8>>,
+) -> Result<(), store::StoreError> {
+ let bytes = |bytes: &[u8]| Val::Scalar(ScalarValue::Bytes(bytes.to_vec()));
+ let writing = || store::Writing::sticky(TimestampFormat::default());
+ if let Some(checkpoint) = checkpoint {
+ store::write_val_path(
+ write,
+ &meta::path(&[meta::CHECKPOINT]),
+ &bytes(checkpoint),
+ writing(),
+ )?;
+ }
+ for (id, event) in events {
+ store::write_val_path(write, &self::event(id), &bytes(event), writing())?;
+ }
+ Ok(())
+}
+
/// The ID of the store `doc` holds, its swarm's, where it holds one.
pub(crate) fn swarm(doc: &impl ReadDoc) -> Option<Id> {
match store::read_plain(doc, &meta::path(&[meta::SWARM])) {
diff --git a/src/federation/held.rs b/src/federation/held.rs
index ce97788..a081efb 100644
--- a/src/federation/held.rs
+++ b/src/federation/held.rs
@@ -131,6 +131,17 @@ struct Inner {
unrecorded: Option<String>,
}
+/// What a remake's snapshot holds of the store (`docs/store.md`, Remakes), as a node reads
+/// it at the remake's base (`Holding::at_base`).
+pub(crate) struct AtBase {
+ /// The checkpoint the store reaches there, where it isn't the root.
+ pub(crate) checkpoint: Option<Vec<u8>>,
+ /// The root, the events that checkpoint keeps, and those after it, by ID.
+ pub(crate) events: BTreeMap<Id, Vec<u8>>,
+ /// The members there, by node ID.
+ pub(crate) members: BTreeSet<String>,
+}
+
/// What a document holds that its store wasn't offered from it.
pub(crate) struct Unread {
epoch_seq: u32,
@@ -672,6 +683,48 @@ impl Holding {
pub(crate) fn with<T>(&self, f: impl FnOnce(&Store<Federation>) -> T) -> Option<T> {
self.inner.lock_or_recover().store.as_ref().map(f)
}
+
+ /// What a remake's snapshot holds of the store: as this node reads it anew from
+ /// `base`, the document at the remake's base, by its own refusals and its operator's
+ /// drops, as it reads its document whenever it starts. None where `base` holds no
+ /// store, or none this node reads there.
+ pub(crate) fn at_base(&self, base: &impl ReadDoc) -> Option<AtBase> {
+ let reading = Holding {
+ pin: self.pin,
+ inner: Mutex::new(Inner {
+ kept: self.inner.lock_or_recover().kept.clone(),
+ ..Inner::default()
+ }),
+ ..Holding::default()
+ };
+ reading.read(reading.unread(base, 0)?);
+ let swarm = events::swarm(base)?;
+ let root = events::bytes(base, &swarm)?;
+ reading.with(|store| {
+ let checkpoint = store.checkpoint();
+ let mut events: BTreeMap<Id, Vec<u8>> = store
+ .kept()
+ .into_iter()
+ .map(|bytes| (Id::of(&bytes), bytes))
+ .collect();
+ for id in store.taken() {
+ if let Some(bytes) = store.get(id) {
+ events.insert(*id, bytes.to_vec());
+ }
+ }
+ events.insert(swarm, root);
+ AtBase {
+ checkpoint: (Id::of(checkpoint) != swarm).then(|| checkpoint.to_vec()),
+ events,
+ members: store
+ .state()
+ .members()
+ .into_iter()
+ .map(|(node, _)| node)
+ .collect(),
+ }
+ })
+ }
}
/// The checkpoint `pin` names, found in the document's `events`: at heads a proposal's
@@ -981,6 +1034,102 @@ mod tests {
}
}
+ /// A compaction of a swarm whose store moved to a checkpoint: its snapshot holds that
+ /// checkpoint, the root, what the checkpoint keeps and what came after it, and the
+ /// members' entries; not what the checkpoint forgot, an event nobody takes, nor the
+ /// entry of a node that isn't a member. A node reading it reaches the same store.
+ #[test]
+ fn a_snapshot_holds_the_store_read_at_its_base() {
+ let (tv, lass, makefu) = (
+ Party::new("tv", 1),
+ Party::new("lass", 2),
+ Party::new("makefu", 3),
+ );
+ let node = |seed: u8| crate::identity::NodeKey::from_seed([seed; 32]).id();
+ let (member, stranger) = (node(1), node(2));
+ let mut first = Spec::first(&[&tv, &lass, &makefu], &[]);
+ first.parties[0].nodes = vec![member.clone()];
+ let root = first.root();
+ let on = first.hash();
+ let gone = tv.write(&[Id::of(&root)], "home/tv/a", harness::str("1"));
+ let kept = tv.write(&[Id::of(&gone)], "home/tv/a", harness::str("2"));
+ let head = lass.write(&[Id::of(&kept)], "home/lass/b", harness::str("3"));
+ let mut next = first.after(on);
+ next.checkpoint = Some(vec![Id::of(&head)]);
+ let proposal = tv.propose(&[Id::of(&head)], &next.json());
+ let votes = [
+ tv.vote(&[Id::of(&proposal)], on, next.hash(), true),
+ lass.vote(&[Id::of(&proposal)], on, next.hash(), true),
+ ];
+ let written = harness::version_event(&[Id::of(&votes[0]), Id::of(&votes[1])], next.hash());
+ let after = makefu.write(&[Id::of(&written)], "home/makefu/c", harness::str("3"));
+ let nobodys = Party::new("nobody", 9).write(&[Id::of(&root)], "home/x", harness::str("4"));
+ let mut doc = events::started(Federation::NAME, &root, &[]).unwrap();
+ for event in [
+ &gone, &kept, &head, &proposal, &votes[0], &votes[1], &written,
+ ]
+ .into_iter()
+ .chain([&after, &nobodys])
+ {
+ put(&mut doc, event);
+ }
+ for entry in [&member, &stranger] {
+ let mut write = doc.transaction();
+ store::write_path(
+ &mut write,
+ &meta::path(&[meta::MEMBERS, entry]),
+ &serde_json::json!({"alias": entry}),
+ )
+ .unwrap();
+ write.commit();
+ }
+ let holding = Holding::default();
+ read(&holding, &doc, 0);
+ let (checkpoint, mut taken) = holding
+ .with(|store| (store.checkpoint().to_vec(), store.taken().to_vec()))
+ .unwrap();
+ taken.sort_unstable();
+ assert_ne!(Id::of(&checkpoint), Id::of(&root));
+
+ let heads = doc.get_heads();
+ let policy = serde_json::json!({});
+ let snapshot = crate::remake::snapshot::build(
+ &doc,
+ &crate::remake::snapshot::SnapshotParams {
+ remake_id: "c-1",
+ coordinator: &member,
+ previous: crate::document::replica::Epoch::GENESIS,
+ base_heads: &heads,
+ policy: &policy,
+ proposed_at: crate::clock::UnixMillis(0),
+ kind: "compact",
+ content: None,
+ translation: &serde_json::Value::Null,
+ held: Some(&holding),
+ },
+ )
+ .unwrap()
+ .doc;
+ assert_eq!(events::checkpoint(&snapshot), Some(checkpoint.clone()));
+ let held = events::ids(&snapshot);
+ for kept in [&root, &kept, &after] {
+ assert!(held.contains(&Id::of(kept)));
+ }
+ for left in [&gone, &nobodys] {
+ assert!(!held.contains(&Id::of(left)));
+ }
+ let entries = store::keys_at(&snapshot, &meta::path(&[meta::MEMBERS])).unwrap();
+ assert_eq!(entries, Some(vec![member.clone()]));
+
+ let anew = Holding::default();
+ read(&anew, &snapshot, 1);
+ let (reached, mut read_taken) = anew
+ .with(|store| (store.checkpoint().to_vec(), store.taken().to_vec()))
+ .unwrap();
+ read_taken.sort_unstable();
+ assert_eq!((reached, read_taken), (checkpoint, taken));
+ }
+
/// An event put at the API is offered to the store; what the operator drops is
/// refused, and kept so, until it allows it again.
#[test]
diff --git a/src/remake/catchup.rs b/src/remake/catchup.rs
index 68fa117..35add67 100644
--- a/src/remake/catchup.rs
+++ b/src/remake/catchup.rs
@@ -753,6 +753,8 @@ mod tests {
kind: "compact",
content: None,
translation: &JsonValue::Null,
+ #[cfg(feature = "federation")]
+ held: None,
},
)
.unwrap();
diff --git a/src/remake/coordinator.rs b/src/remake/coordinator.rs
index 0d7a434..a235308 100644
--- a/src/remake/coordinator.rs
+++ b/src/remake/coordinator.rs
@@ -234,6 +234,10 @@ async fn commit<H: Host>(host: &H, id: &str, record: &Record) -> Result<(), Stor
};
let base_heads = fixed_now.then(|| records::encode_heads(&request.base_heads));
request.content = content;
+ #[cfg(feature = "federation")]
+ {
+ request.held = snapshot::Held(Some(host.holding()));
+ }
let snapshot = match snapshot::build_detached(copy, request).await {
Ok((snapshot, _copy)) => snapshot,
Err(error) => {
diff --git a/src/remake/mod.rs b/src/remake/mod.rs
index 9891760..bd814da 100644
--- a/src/remake/mod.rs
+++ b/src/remake/mod.rs
@@ -212,6 +212,11 @@ pub(crate) trait Host: Clone + Send + Sync + 'static {
/// This node's ID (its peers know it by this).
fn node_id(&self) -> String;
+ /// What this node holds of its store, where its swarm holds one
+ /// (`federation::held`).
+ #[cfg(feature = "federation")]
+ fn holding(&self) -> Arc<crate::federation::held::Holding>;
+
/// The epoch of the local replica.
fn current_epoch(&self) -> Epoch;
diff --git a/src/remake/records.rs b/src/remake/records.rs
index 21cf0ae..22aaee3 100644
--- a/src/remake/records.rs
+++ b/src/remake/records.rs
@@ -314,6 +314,8 @@ impl Record {
kind: self.proposal.kind.clone(),
content: None,
translation: self.proposal.translation.clone(),
+ #[cfg(feature = "federation")]
+ held: Default::default(),
})
}
diff --git a/src/remake/snapshot.rs b/src/remake/snapshot.rs
index fa1fa39..0c3b658 100644
--- a/src/remake/snapshot.rs
+++ b/src/remake/snapshot.rs
@@ -52,6 +52,22 @@ pub(crate) struct SnapshotParams<'a> {
pub(crate) content: Option<&'a [u8]>,
/// The kind's translation input; recorded in the epoch metadata.
pub(crate) translation: &'a JsonValue,
+ /// The node's store, where its swarm holds one: the snapshot holds it as the node
+ /// reads it at the base (`Holding::at_base`).
+ #[cfg(feature = "federation")]
+ pub(crate) held: Option<&'a crate::federation::held::Holding>,
+}
+
+/// The node's store, for a snapshot request (`SnapshotParams::held`).
+#[cfg(feature = "federation")]
+#[derive(Clone, Default)]
+pub(crate) struct Held(pub(crate) Option<std::sync::Arc<crate::federation::held::Holding>>);
+
+#[cfg(feature = "federation")]
+impl std::fmt::Debug for Held {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(if self.0.is_some() { "Held" } else { "None" })
+ }
}
pub(crate) struct Snapshot {
@@ -96,6 +112,8 @@ pub(crate) struct SnapshotRequest {
pub(crate) kind: String,
pub(crate) content: Option<std::sync::Arc<Vec<u8>>>,
pub(crate) translation: JsonValue,
+ #[cfg(feature = "federation")]
+ pub(crate) held: Held,
}
impl SnapshotRequest {
@@ -110,6 +128,8 @@ impl SnapshotRequest {
kind: &self.kind,
content: self.content.as_deref().map(Vec::as_slice),
translation: &self.translation,
+ #[cfg(feature = "federation")]
+ held: self.held.0.as_deref(),
}
}
@@ -369,6 +389,9 @@ pub(crate) fn build(
let base = source.fork_at(params.base_heads)?;
let clock = clock_of(&base);
+ // A swarm holding a store: the store as the node reads it there.
+ #[cfg(feature = "federation")]
+ let held = params.held.and_then(|held| held.at_base(&base));
let generation = params.previous.generation + 1;
let kind =
@@ -395,8 +418,25 @@ pub(crate) fn build(
.into_iter()
.filter(|key| key != REMAKES && key != VOTES && key != EPOCHS)
{
+ #[cfg(feature = "federation")]
+ if held.is_some() && [meta::EVENTS, meta::CHECKPOINT, meta::MEMBERS].contains(&key.as_str())
+ {
+ continue;
+ }
store::copy_path(&base, &mut target, &meta::path(&[key.as_str()]))?;
}
+ // Of the store, its checkpoint, what that keeps and what came after; of the entries,
+ // the members'. What the checkpoint forgot, and events nobody takes, stay behind.
+ #[cfg(feature = "federation")]
+ if let Some(held) = &held {
+ crate::document::events::snapshot(&mut target, held.checkpoint.as_deref(), &held.events)?;
+ for node in &held.members {
+ let entry = meta::path(&[meta::MEMBERS, node]);
+ if store::read_path(&base, &entry)?.is_some() {
+ store::copy_path(&base, &mut target, &entry)?;
+ }
+ }
+ }
// Earlier epochs' metadata as the base's epoch built it, whatever was written there
// since (with no policy, a member's own change could): copied from there, and judged
// there which to leave out. The first epoch follows none and carries none.
@@ -533,6 +573,8 @@ mod tests {
kind: "compact",
content: None,
translation: &NULL,
+ #[cfg(feature = "federation")]
+ held: None,
}
}
diff --git a/src/remake/switch.rs b/src/remake/switch.rs
index df3fcc8..94956f6 100644
--- a/src/remake/switch.rs
+++ b/src/remake/switch.rs
@@ -189,6 +189,10 @@ async fn switch<H: Host>(
if let Some(reference) = &record.proposal.content {
request.content = Some(content::ensure(host, reference).await?);
}
+ #[cfg(feature = "federation")]
+ {
+ request.held = super::snapshot::Held(Some(host.holding()));
+ }
let translator = request
.translator()
.ok_or_else(|| format!("unknown remake kind {:?}", request.kind))?;
diff --git a/src/state/host.rs b/src/state/host.rs
index 771884e..4da5836 100644
--- a/src/state/host.rs
+++ b/src/state/host.rs
@@ -305,6 +305,11 @@ impl Host for AppState {
self.local_id().to_owned()
}
+ #[cfg(feature = "federation")]
+ fn holding(&self) -> Arc<crate::federation::held::Holding> {
+ Arc::clone(&self.holding)
+ }
+
fn current_epoch(&self) -> Epoch {
self.local_epoch()
}