//! 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; pub(crate) mod memory; #[cfg(test)] mod properties; #[cfg(test)] pub(crate) mod testfold; /// 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; /// Its name, by which a swarm holding a store names its fold (`docs/store.md`, On /// Automerge). const NAME: &'static str; /// The most bytes an event may have: larger ones are none. const LARGEST: usize; /// 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 store 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); } }