diff options
| author | tv <tv@krebsco.de> | 2026-11-16 16:15:04 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-16 18:00:40 +0100 |
| commit | 7bb467a013a9146620b633e3c3cdd21e3a48f80f (patch) | |
| tree | 0fe86ef999faaf3547803aa73e391982a8ea3af8 /src | |
| parent | 40db32407a341f8fec2795ffb11821842e79334d (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')
| -rw-r--r-- | src/federation/mod.rs | 8 | ||||
| -rw-r--r-- | src/federation/store/mod.rs | 121 | ||||
| -rw-r--r-- | src/main.rs | 2 |
3 files changed, 131 insertions, 0 deletions
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<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); + } +} diff --git a/src/main.rs b/src/main.rs index 5f2403e..6d0d82f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -18,6 +18,8 @@ mod clock; mod compress; mod config; mod document; +#[cfg(feature = "federation")] +mod federation; mod files; mod force; mod identity; |
