crashlabs/huskies
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 26 Wiki Activity

huskies: merge 854

Browse Source
This commit is contained in:
dave
2026-04-29 09:25:05 +00:00
parent 8802e1fe59
commit 4ed1fb5110
18 changed files with 79 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/bft-json-crdt/src/debug.rs
+19
View File
@@ -1,3 +1,9 @@
//! Debug helpers and the [`DebugView`] trait for rendering CRDT internals.
//!
//! Most items in this module are no-ops in release builds. They are activated by
//! the `logging-base`, `logging-json`, and `logging-list` Cargo features so that
//! debug output can be toggled without changing production code.
use crate::{
json_crdt::{BaseCrdt, CrdtNode, SignedOp},
keypair::SignedDigest,
@@ -37,6 +43,7 @@ fn display_op_id<T: CrdtNode>(op: &Op<T>) -> String {
)
}
/// Log a type-mismatch warning when deserialising a JSON value into a CRDT node fails.
pub fn debug_type_mismatch(_msg: String) {
#[cfg(feature = "logging-base")]
{
@@ -44,6 +51,7 @@ pub fn debug_type_mismatch(_msg: String) {
}
}
/// Log a path-mismatch warning when an operation's path does not match the CRDT's path.
pub fn debug_path_mismatch(_our_path: Vec<PathSegment>, _op_path: Vec<PathSegment>) {
#[cfg(feature = "logging-base")]
{
@@ -56,6 +64,7 @@ pub fn debug_path_mismatch(_our_path: Vec<PathSegment>, _op_path: Vec<PathSegmen
}
}
/// Log a warning when an operation is applied to a primitive (terminal) CRDT node.
pub fn debug_op_on_primitive(_op_path: Vec<PathSegment>) {
#[cfg(feature = "logging-base")]
{
@@ -79,16 +88,20 @@ fn display_author(author: AuthorId) -> String {
.to_string()
}
/// Render CRDT state as an indented human-readable string for debugging.
pub trait DebugView {
/// Return a multi-line debug string for this CRDT node, indented by `indent` spaces.
fn debug_view(&self, indent: usize) -> String;
}
impl<T: CrdtNode + DebugView> BaseCrdt<T> {
/// Print the current document state as an indented debug tree (no-op in release builds).
pub fn debug_view(&self) {
#[cfg(feature = "logging-json")]
println!("document is now:\n{}", self.doc.debug_view(0));
}
/// Log an attempt to apply `op` before the result is known (no-op in release builds).
pub fn log_try_apply(&self, _op: &SignedOp) {
#[cfg(feature = "logging-json")]
println!(
@@ -99,6 +112,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
);
}
/// Log a signature-digest verification failure for `op` (no-op in release builds).
pub fn debug_digest_failure(&self, _op: SignedOp) {
#[cfg(feature = "logging-json")]
println!(
@@ -108,6 +122,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
);
}
/// Log that a causal dependency identified by `missing` has not yet been received.
pub fn log_missing_causal_dep(&self, _missing: &SignedDigest) {
#[cfg(feature = "logging-json")]
println!(
@@ -117,6 +132,7 @@ impl<T: CrdtNode + DebugView> BaseCrdt<T> {
);
}
/// Log that `op` is about to be integrated into the document (no-op in release builds).
pub fn log_actually_apply(&self, _op: &SignedOp) {
#[cfg(feature = "logging-json")]
{
@@ -133,6 +149,7 @@ impl<T> Op<T>
where
T: CrdtNode,
{
/// Log an operation hash verification failure showing expected and computed IDs.
pub fn debug_hash_failure(&self) {
#[cfg(feature = "logging-base")]
{
@@ -191,6 +208,7 @@ impl<T> ListCrdt<T>
where
T: CrdtNode,
{
/// Print the full operation log as a tree, optionally highlighting one operation (no-op in release builds).
pub fn log_ops(&self, _highlight: Option<OpId>) {
#[cfg(feature = "logging-list")]
{
@@ -289,6 +307,7 @@ where
}
}
/// Log the insert or delete being performed for `op` (no-op in release builds).
pub fn log_apply(&self, _op: &Op<T>) {
#[cfg(feature = "logging-list")]
{
crates/bft-json-crdt/src/keypair.rs
+6
View File
@@ -1,3 +1,9 @@
//! Ed25519 keypair utilities and type aliases for node identity and signing.
//!
//! Provides the [`AuthorId`] and [`SignedDigest`] type aliases, a SHA-256 helper,
//! and convenience wrappers around the `fastcrypto` Ed25519 primitives used
//! throughout the CRDT codebase.
use fastcrypto::traits::VerifyingKey;
pub use fastcrypto::{
ed25519::{
crates/bft-json-crdt/src/lib.rs
+13
View File
@@ -1,8 +1,21 @@
//! BFT JSON CRDT library — a Byzantine Fault-Tolerant replicated JSON document
//! built on an RGA list CRDT, an LWW register CRDT, and a signed-op substrate.
//!
//! Each document is identified by an Ed25519 keypair. Operations are signed and
//! carry causal dependencies so that every node converges to the same value
//! regardless of message delivery order.
/// Debug helpers and the [`DebugView`] trait for rendering CRDT internals.
pub mod debug;
/// JSON CRDT public interface: core traits, types, and signed-op substrate.
pub mod json_crdt;
/// Ed25519 keypair utilities and primitive type aliases used throughout the crate.
pub mod keypair;
/// RGA-style list CRDT that can store any [`CrdtNode`] as its element type.
pub mod list_crdt;
/// Last-writer-wins (LWW) register CRDT for single-value fields.
pub mod lww_crdt;
/// Core operation types: [`Op`], [`PathSegment`], and hashing helpers.
pub mod op;
extern crate self as bft_json_crdt;
crates/bft-json-crdt/src/list_crdt.rs
+6
View File
@@ -1,3 +1,9 @@
//! RGA-style list CRDT that stores any [`CrdtNode`] as its element type.
//!
//! Implements the Replicated Growable Array (RGA) algorithm with causal ordering.
//! Concurrent inserts at the same position are resolved by sequence number then
//! by author public key so that all replicas converge to the same sequence.
use crate::{
debug::debug_path_mismatch,
json_crdt::{CrdtNode, JsonValue, OpState},
crates/bft-json-crdt/src/lww_crdt.rs
+6
View File
@@ -1,3 +1,9 @@
//! Last-writer-wins (LWW) register CRDT.
//!
//! Implements a delete-wins LWW register for primitive values inside a nested
//! JSON CRDT. Concurrent writes are resolved by sequence number; ties are broken
//! by author public key so every node converges to the same value.
use crate::debug::DebugView;
use crate::json_crdt::{CrdtNode, JsonValue, OpState};
use crate::op::{join_path, print_path, Op, PathSegment, SequenceNumber};
crates/bft-json-crdt/src/op.rs
+12
View File
@@ -1,3 +1,9 @@
//! Core operation types for the BFT JSON CRDT.
//!
//! Defines [`Op`] (the fundamental unit of change), [`PathSegment`] (for
//! addressing nested CRDTs), and [`SequenceNumber`] / [`OpId`] type aliases.
//! Also provides hashing utilities used when computing operation identifiers.
use crate::debug::{debug_path_mismatch, debug_type_mismatch};
use crate::json_crdt::{CrdtNode, CrdtNodeFromValue, IntoCrdtNode, JsonValue, SignedOp};
use crate::keypair::{sha256, AuthorId};
@@ -113,6 +119,7 @@ where
/// Conversion from Op<Value> -> Op<T> given that T is a CRDT that can be created from a JSON value
impl Op<JsonValue> {
/// Convert this `Op<JsonValue>` into an `Op<T>` by deserialising the content via `T::node_from`.
pub fn into<T: CrdtNodeFromValue + CrdtNode>(self) -> Op<T> {
let content = if let Some(inner_content) = self.content {
match inner_content.into_node(self.id, self.path.clone()) {
@@ -141,10 +148,12 @@ impl<T> Op<T>
where
T: CrdtNode,
{
/// Sign this operation with `keypair`, producing a [`SignedOp`] with no causal dependencies.
pub fn sign(self, keypair: &Ed25519KeyPair) -> SignedOp {
SignedOp::from_op(self, keypair, vec![])
}
/// Sign this operation and attach explicit causal `dependencies`.
pub fn sign_with_dependencies(
self,
keypair: &Ed25519KeyPair,
@@ -160,14 +169,17 @@ where
)
}
/// Return the [`AuthorId`] (Ed25519 public key) of the node that created this operation.
pub fn author(&self) -> AuthorId {
self.author
}
/// Return the Lamport sequence number carried by this operation.
pub fn sequence_num(&self) -> SequenceNumber {
self.seq
}
/// Construct a new operation, computing its [`OpId`] hash from the supplied fields.
pub fn new(
origin: OpId,
author: AuthorId,