aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--.cargo/config.toml6
-rw-r--r--Cargo.toml3
-rw-r--r--docs/development.md23
-rw-r--r--docs/store.md2
-rw-r--r--src/federation/mod.rs8
-rw-r--r--src/federation/store/mod.rs121
-rw-r--r--src/main.rs2
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"
diff --git a/Cargo.toml b/Cargo.toml
index ba6ce00..8a372a0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -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;