From 7bb467a013a9146620b633e3c3cdd21e3a48f80f Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 16:15:04 +0000 Subject: 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. --- src/federation/mod.rs | 8 +++ src/federation/store/mod.rs | 121 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 src/federation/mod.rs create mode 100644 src/federation/store/mod.rs (limited to 'src/federation') diff --git a/src/federation/mod.rs b/src/federation/mod.rs new file mode 100644 index 0000000..0005038 --- /dev/null +++ b/src/federation/mod.rs @@ -0,0 +1,8 @@ +//! A federation of parties that don't trust each other (`docs/federation.md`), on a store +//! of events generic over what they read as (`docs/store.md`). Built stage by stage behind +//! the `federation` feature; no node runs any of it yet. + +// Until a node runs it (stage 3), parts of it are used by nothing, or by tests alone. +#![allow(dead_code)] + +pub(crate) mod store; 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 { + 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) -> 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>; + + /// 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, Vec); + + /// 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, Vec)>; + + /// The state a checkpoint reads as, with the events it keeps. + fn start(checkpoint: &[u8], kept: &[(Id, Vec)]) -> Result; + + /// 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, Vec), Refused>; + + /// The heads of a later checkpoint, where a store reading as `now` moves to one. + fn moves_to(now: &Self::State) -> Option>; + + /// 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); + } +} -- cgit v1.3.1