aboutsummaryrefslogtreecommitdiffstats
path: root/src/federation/store
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 16:15:04 +0000
committertv <tv@krebsco.de>2026-11-16 18:00:40 +0100
commit7bb467a013a9146620b633e3c3cdd21e3a48f80f (patch)
tree0fe86ef999faaf3547803aa73e391982a8ea3af8 /src/federation/store
parent40db32407a341f8fec2795ffb11821842e79334d (diff)
federation: the feature, and the store's fold
`federation`, a feature of its own, builds what `docs/federation.md` and `docs/store.md` design, stage by stage; without it continuum builds and behaves as it does. The aliases build with it, and `docs/development.md` says so. Its first part is the store's: an event's ID, the SHA-256 of its bytes written as 64 lower-case hex digits and read back only so, and the `Fold` trait as `docs/store.md` gives it. The trait reads a checkpoint's parts too, the heads it was built at and the events it keeps, which a node taking a pinned checkpoint needs; the design names it. Nothing uses either yet, but a test.
Diffstat (limited to 'src/federation/store')
-rw-r--r--src/federation/store/mod.rs121
1 files changed, 121 insertions, 0 deletions
diff --git a/src/federation/store/mod.rs b/src/federation/store/mod.rs
new file mode 100644
index 0000000..da05b4b
--- /dev/null
+++ b/src/federation/store/mod.rs
@@ -0,0 +1,121 @@
+//! The store (`docs/store.md`): events, each named by the hash of its bytes and naming
+//! the events it builds on, judged at that history, and read as one state by a fold the
+//! store is generic over.
+
+use std::fmt;
+
+use sha2::{Digest, Sha256};
+
+use crate::transport::Hex;
+
+/// An event's name: the SHA-256 of its bytes, written as 64 lower-case hex digits.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub(crate) struct Id(pub(crate) [u8; 32]);
+
+impl Id {
+ /// The ID of `bytes`.
+ pub(crate) fn of(bytes: &[u8]) -> Self {
+ Self(Sha256::digest(bytes).into())
+ }
+
+ /// From 64 lower-case hex digits, and nothing else spelled otherwise.
+ pub(crate) fn from_hex(text: &str) -> Option<Self> {
+ let digits = text.as_bytes();
+ if digits.len() != 64 {
+ return None;
+ }
+ let value = |digit: u8| match digit {
+ b'0'..=b'9' => Some(digit - b'0'),
+ b'a'..=b'f' => Some(digit - b'a' + 10),
+ _ => None,
+ };
+ let mut id = [0; 32];
+ for (byte, pair) in id.iter_mut().zip(digits.chunks(2)) {
+ *byte = value(pair[0])? << 4 | value(pair[1])?;
+ }
+ Some(Self(id))
+ }
+}
+
+impl fmt::Display for Id {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ fmt::Display::fmt(&Hex(&self.0), f)
+ }
+}
+
+impl fmt::Debug for Id {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ fmt::Display::fmt(self, f)
+ }
+}
+
+/// Why a fold takes an event not, or a checkpoint not: in words, for reports.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Refused(pub(crate) String);
+
+impl Refused {
+ pub(crate) fn new(why: impl Into<String>) -> Self {
+ Self(why.into())
+ }
+}
+
+/// What the events of a store are, how one is judged, what they read as, and when the
+/// store moves to a later checkpoint (`docs/store.md`, The fold).
+pub(crate) trait Fold {
+ /// What a checkpoint and the events after it read as. It carries what judging and
+ /// reading need of the events' history.
+ type State: Clone;
+
+ /// What the event builds on; `None` where its bytes are none of this fold's events.
+ fn dependencies(event: &[u8]) -> Option<Vec<Id>>;
+
+ /// Whether the event is taken where its history reads as `at`.
+ fn judge(at: &Self::State, id: &Id, event: &[u8]) -> Result<(), Refused>;
+
+ /// Adds the event, whose dependencies are added already. Events neither of which
+ /// builds on the other may come in either order: the state is the same.
+ fn add(state: &mut Self::State, id: &Id, event: &[u8]);
+
+ /// Whether a node whose store reads as `now` takes an event its history takes.
+ fn keeps(_now: &Self::State, _id: &Id, _event: &[u8]) -> bool {
+ true
+ }
+
+ /// The checkpoint at `heads`, read as `at`: its bytes, and the events it keeps.
+ fn checkpoint(at: &Self::State, heads: &[Id]) -> (Vec<u8>, Vec<Id>);
+
+ /// The heads a checkpoint was built at, and the events it keeps; `None` where its
+ /// bytes are no checkpoint.
+ fn parts(checkpoint: &[u8]) -> Option<(Vec<Id>, Vec<Id>)>;
+
+ /// The state a checkpoint reads as, with the events it keeps.
+ fn start(checkpoint: &[u8], kept: &[(Id, Vec<u8>)]) -> Result<Self::State, Refused>;
+
+ /// The root of a fork at `heads` of the stores reading as `at`, made by `spec`: its
+ /// bytes, and the events it keeps.
+ fn fork(at: &[&Self::State], heads: &[Id], spec: &[u8]) -> Result<(Vec<u8>, Vec<Id>), Refused>;
+
+ /// The heads of a later checkpoint, where a store reading as `now` moves to one.
+ fn moves_to(now: &Self::State) -> Option<Vec<Id>>;
+
+ /// The nodes that carry the store, each with its group.
+ fn members(state: &Self::State) -> Vec<(String, String)>;
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn an_id_reads_back_from_its_hex() {
+ let id = Id::of(b"an event");
+ assert_eq!(id.to_string().len(), 64);
+ assert_eq!(Id::from_hex(&id.to_string()), Some(id));
+ let upper = id.to_string().to_uppercase();
+ if upper != id.to_string() {
+ assert_eq!(Id::from_hex(&upper), None);
+ }
+ assert_eq!(Id::from_hex(&id.to_string()[1..]), None);
+ assert_eq!(Id::from_hex(&format!("{id}0")), None);
+ }
+}