diff options
| -rw-r--r-- | .cargo/config.toml | 6 | ||||
| -rw-r--r-- | Cargo.toml | 3 | ||||
| -rw-r--r-- | docs/development.md | 23 | ||||
| -rw-r--r-- | docs/store.md | 2 | ||||
| -rw-r--r-- | src/federation/mod.rs | 8 | ||||
| -rw-r--r-- | src/federation/store/mod.rs | 121 | ||||
| -rw-r--r-- | src/main.rs | 2 |
7 files changed, 152 insertions, 13 deletions
diff --git a/.cargo/config.toml b/.cargo/config.toml index 7544206..36c105c 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,9 +1,9 @@ # Shortcuts for the development loop (docs/development.md). [alias] # Everything but the simulations: a few seconds. -quick = "test --features mycelium,libp2p,tor,dashboard -- --skip simtest" +quick = "test --features mycelium,libp2p,tor,dashboard,federation -- --skip simtest" # The simulations: whole swarms in one process, in real time. -sim = "test --features mycelium,libp2p,tor,dashboard simtest" +sim = "test --features mycelium,libp2p,tor,dashboard,federation simtest" # The benchmarks: ignored tests named bench_*, in release builds, one at a time, with # what they print (`cargo bench` itself takes no aliases). -benchmark = "test --release --features mycelium,libp2p,tor,dashboard bench_ -- --ignored --nocapture --test-threads=1" +benchmarks = "test --release --features mycelium,libp2p,tor,dashboard,federation bench_ -- --ignored --nocapture --test-threads=1" @@ -9,6 +9,9 @@ edition = "2024" tokio-console = ["dep:console-subscriber"] # A dashboard of the node and a map of the swarm in the HTTP API (`/admin/dashboard`). dashboard = [] +# The federation (`docs/federation.md`) and the store it is built on (`docs/store.md`), +# stage by stage: without it, continuum builds and behaves as it does. +federation = [] # The Mycelium transport (`--mycelium-enable`): through a Mycelium daemon's API, one it # supervises or one running elsewhere. mycelium = ["dep:reqwest", "dep:rustls", "dep:libc"] diff --git a/docs/development.md b/docs/development.md index 85f6fce..314ae11 100644 --- a/docs/development.md +++ b/docs/development.md @@ -3,19 +3,22 @@ ## The loop ```sh -cargo check --features mycelium,libp2p,tor,dashboard # does it compile: seconds -cargo quick # every test but the simulations: seconds -cargo sim # the simulations (src/simtest/): under a minute -cargo test --features mycelium,libp2p,tor,dashboard # both -cargo benchmarks # the benchmarks, in release builds +cargo check --features mycelium,libp2p,tor,dashboard,federation # does it compile: seconds +cargo quick # every test but the simulations: seconds +cargo sim # the simulations (src/simtest/): under a minute +cargo test --features mycelium,libp2p,tor,dashboard,federation # both +cargo benchmarks # the benchmarks, in release builds ``` `cargo quick`, `cargo sim` and `cargo benchmarks` are aliases ([`.cargo/config.toml`](../.cargo/config.toml)), -with every transport and the dashboard (`dashboard`, `GET /admin/dashboard`; -[`docs/dashboard.md`](dashboard.md)). Each transport is a feature, none of them default, and a build -needs at least one: a transport left out takes its tests and dependencies with it -(`--features libp2p` builds neither `reqwest` and the daemon supervision of Mycelium, -nor arti; among Mycelium's tests is a swarm simulated on its envelope). +with every transport, the dashboard (`dashboard`, `GET /admin/dashboard`; +[`docs/dashboard.md`](dashboard.md)) and the federation (`federation`, built stage by stage and +not yet run by a node: [`docs/federation.md`](federation.md), [`docs/store.md`](store.md)); a +build without `federation` runs the tests continuum has without it. Each transport is a feature, +none of them default, and a build needs at least one: a transport left out takes its tests +and dependencies with it (`--features libp2p` builds neither `reqwest` and the daemon +supervision of Mycelium, nor arti; among Mycelium's tests is a swarm simulated on its +envelope). The benchmarks are ignored tests named `bench_*`: the document's (writes and sync messages, what signing and checking every change would cost: `bench_change_signatures`, diff --git a/docs/store.md b/docs/store.md index 002b906..b766d41 100644 --- a/docs/store.md +++ b/docs/store.md @@ -113,6 +113,8 @@ pub trait Fold { } /// 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. + 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`. 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; |
