From 9d18983e4b643eac04de49a42a6f29805570dba3 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 20:06:42 +0000 Subject: federation: a pinned checkpoint, found in the document Once a store moved to a checkpoint, a node reading it from the root could take what was grown anew from the root since, by keys of versions long replaced: so its operator pins the checkpoint (`--store-checkpoint`, by its ID), and the node reads its store from there whenever it starts (`docs/store.md`, Pinned checkpoints). It finds it in its document: at heads a proposal's version names, built from their history read from the root, as any node builds the checkpoint it moves to (`Store::checkpoint_at`), the one whose ID is pinned. Until the document holds it, the node holds no store, and says so once. --- src/federation/held.rs | 139 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 127 insertions(+), 12 deletions(-) (limited to 'src/federation/held.rs') diff --git a/src/federation/held.rs b/src/federation/held.rs index 5c0d8c8..8f48c65 100644 --- a/src/federation/held.rs +++ b/src/federation/held.rs @@ -3,7 +3,10 @@ //! it from anywhere, and by the node's own: what it refused by what it took before, and //! what its operator had it drop, which it keeps in a file of its own (`--store-file`). //! It keeps nothing else of the store across a restart: whenever it starts, it reads the -//! store anew from its document, from the root. +//! store anew from its document, from the root, or from a checkpoint its operator pins +//! (`--store-checkpoint`), found in the document (`found`): once its store moved, a node +//! reading from the root could take what was grown anew from it since, by keys of +//! versions long replaced. //! //! A worker reads the events the document holds that it hasn't read yet, whenever the //! document changes (`run_worker`). Which change put an event, and how often, changes @@ -26,9 +29,11 @@ use anyhow::{Context, Result, bail}; use serde::{Deserialize, Serialize}; use tracing::{error, info, warn}; +use super::event::{Does, Event, Signed}; use super::fold::Federation; -use super::store::Id; -use super::store::memory::{Offered, Store}; +use super::store::memory::{Built, Offered, Store}; +use super::store::{Fold, Id}; +use super::version::Version; use crate::document::{Change, ChangeHash, ReadDoc, ScalarValue, events, meta, store}; use crate::files::{FileKind, Files}; use crate::locks::MutexExt; @@ -72,10 +77,12 @@ impl Kept { } } -/// The store a node holds, if its swarm holds one, and the file it keeps its own in. +/// The store a node holds, if its swarm holds one, the file it keeps its own in, and the +/// checkpoint its operator pins. #[derive(Default)] pub(crate) struct Holding { file: Option<(PathBuf, Arc)>, + pin: Option, // A std mutex: never held while waiting for the document. inner: Mutex, } @@ -91,6 +98,8 @@ struct Inner { kept: Kept, /// The root that is none, logged once. none: Option, + /// The pinned checkpoint not found in the document, logged once. + unfound: bool, /// The refused changes looked at, of those screening keeps (`look`). looked: HashSet, } @@ -106,10 +115,13 @@ pub(crate) struct Unread { impl Holding { /// Keeping the node's own in the file at `path`, if any, which holds what it kept /// before: a missing file nothing. One that doesn't read is an error: the node would - /// take what it refused. - pub(crate) fn open(path: Option, files: Arc) -> Result { + /// take what it refused. Its store starts from the checkpoint `pin`, if any. + pub(crate) fn open(path: Option, files: Arc, pin: Option) -> Result { let Some(path) = path else { - return Ok(Holding::default()); + return Ok(Holding { + pin, + ..Holding::default() + }); }; let kept = match files .read(FileKind::Store, &path) @@ -126,6 +138,7 @@ impl Holding { }; Ok(Holding { file: Some((path, files)), + pin, inner: Mutex::new(Inner { kept, ..Inner::default() @@ -179,7 +192,22 @@ impl Holding { }; let id = Id::of(&root); let (own, dropped) = inner.kept.ids().unwrap_or_default(); - match Store::new(root, Vec::new()) { + let started = match self.pin { + None => Store::new(root, Vec::new()), + Some(pin) => match found(&pin, &root, &unread.events) { + Some((checkpoint, kept)) => { + info!(store = %id, checkpoint = %pin, "Found the pinned checkpoint in the document"); + Store::pinned(id, checkpoint, kept.into_values().collect()) + } + None => { + if !std::mem::replace(&mut inner.unfound, true) { + warn!(store = %id, checkpoint = %pin, "The pinned checkpoint isn't in the document (yet): holding no store until it is"); + } + return; + } + }, + }; + match started { Ok(store) => { info!(store = %id, refused = own.len(), dropped = dropped.len(), "Reading the store from the document"); inner.store = Some(store.refusing(&own, &dropped)); @@ -285,6 +313,38 @@ impl Holding { } } +/// The checkpoint `pin` names, found in the document's `events`: at heads a proposal's +/// version names, built from their history, read from the root, as any node builds the +/// checkpoint it moves to (`Store::checkpoint_at`). +fn found(pin: &Id, root: &[u8], events: &BTreeMap>) -> Option { + let named = events + .values() + .filter_map(|bytes| match Event::read_taken(bytes)? { + Event::Signed(Signed { + does: Does::Proposal { version, .. }, + .. + }) => Version::read(&version).ok()?.checkpoint, + _ => None, + }); + for heads in named { + let mut store = Store::::new(root.to_vec(), Vec::new()).ok()?; + let mut history = heads.clone(); + let mut seen = HashSet::new(); + while let Some(id) = history.pop() { + if let Some(bytes) = events.get(&id).filter(|_| seen.insert(id)) { + history.extend(Federation::dependencies(bytes).unwrap_or_default()); + store.offer(bytes.clone()); + } + } + if let Some((checkpoint, kept)) = store.checkpoint_at(&heads) + && Id::of(&checkpoint) == *pin + { + return Some((checkpoint, kept)); + } + } + None +} + /// Reads the store from the document whenever it changes, and from the changes the node /// refused now and then; puts again what the document lacks, a random wait after it /// first lacked it. @@ -396,7 +456,6 @@ mod tests { use crate::document::{Document, ScalarValue}; use crate::federation::event::Checkpoint; use crate::federation::harness::{self, Party, Spec}; - use crate::federation::store::Fold; use crate::federation::version::Version; fn root_of(spec: &Spec) -> Vec { @@ -424,6 +483,62 @@ mod tests { holding.read(holding.unread(doc, epoch_seq).unwrap()); } + /// A checkpoint at a write of lass's built on two of tv's, a write of makefu's beside + /// it: a node pinning it starts there, found in the document. + #[test] + fn a_node_starts_from_the_checkpoint_its_operator_pins() { + let (tv, lass, makefu) = ( + Party::new("tv", 1), + Party::new("lass", 2), + Party::new("makefu", 3), + ); + let first = Spec::first(&[&tv, &lass, &makefu], &[]); + let root = root_of(&first); + 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 beside = makefu.write(&[Id::of(&root)], "home/makefu/c", harness::str("4")); + 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 mut doc = events::started(Federation::NAME, &root).unwrap(); + for event in [&gone, &kept, &head, &beside, &proposal] + .into_iter() + .chain(&votes) + .chain([&written]) + { + put(&mut doc, event); + } + let from_root = Holding::default(); + read(&from_root, &doc, 0); + let pin = from_root.with(|store| Id::of(store.checkpoint())).unwrap(); + assert_ne!(pin, Id::of(&root)); + + let files = Arc::new(Files::default()); + let pinned = Holding::open(None, Arc::clone(&files), Some(pin)).unwrap(); + read(&pinned, &doc, 0); + assert_eq!(pinned.with(|store| Id::of(store.checkpoint())), Some(pin)); + let taken = |holding: &Holding| { + let mut taken = holding.with(|store| store.taken().to_vec()).unwrap(); + taken.sort_unstable(); + taken + }; + assert_eq!(taken(&pinned), taken(&from_root)); + assert_eq!( + pinned.with(|store| store.holds(&Id::of(&beside))), + Some(false) + ); + let elsewhere = Holding::open(None, files, Some(Id::of(b"elsewhere"))).unwrap(); + read(&elsewhere, &doc, 0); + assert!(elsewhere.with(|_| ()).is_none()); + } + #[test] fn a_node_puts_again_what_its_document_lacks() { let tv = Party::new("tv", 1); @@ -523,7 +638,7 @@ mod tests { let dir = crate::files::scratch_dir("held"); let path = dir.join("store.json"); let files = Arc::new(Files::default()); - let holding = Holding::open(Some(path.clone()), Arc::clone(&files)).unwrap(); + let holding = Holding::open(Some(path.clone()), Arc::clone(&files), None).unwrap(); let mut doc = events::started(Federation::NAME, &root).unwrap(); for event in before.iter().copied().chain([&first_taken]) { put(&mut doc, event); @@ -535,12 +650,12 @@ mod tests { assert!(!taken(&holding).contains(&Id::of(&later))); // Restarted: the store read anew, all at once, refuses the later as before. - let anew = Holding::open(Some(path.clone()), Arc::clone(&files)).unwrap(); + let anew = Holding::open(Some(path.clone()), Arc::clone(&files), None).unwrap(); read(&anew, &all, 0); assert!(taken(&anew).contains(&Id::of(&first_taken))); assert!(!taken(&anew).contains(&Id::of(&later))); std::fs::write(&path, b"{\"refused\": [\"not an ID\"]}").unwrap(); - assert!(Holding::open(Some(path), files).is_err()); + assert!(Holding::open(Some(path), files, None).is_err()); } } -- cgit v1.3.1