zaphar/merkle-dag
1
0
Fork 0
mirror of https://github.com/zaphar/merkle-dag.git synced 2025-07-21 18:19:58 -04:00
Code Issues Packages Projects Releases Wiki Activity

More documenation fixes. Type linking

Browse Source
This commit is contained in:
Jeremy Wall 2022-09-19 14:59:21 -04:00
parent 63fb67f7bf
commit 92ee369423
8 changed files with 48 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/blake2.rs
View File

@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Implements the HashWriter interface for the Blake2 hash function.
//! Implements the [HashWriter] interface for the Blake2 hash function.
//! Requires the `blake2` feature to be enabled.
use crate::hash::*;

20
src/dag/iter.rs
View File

@ -18,14 +18,14 @@ use crate::hash::HashWriter;
use crate::node::Node;
use crate::store::{Result, Store};
/// An iterator over the missing nodes in a DAG given a set of root nodes.
/// An iterator over the missing [nodes](Node) in a [Merkle DAG](Merkle) given a set of root nodes.
pub struct Missing<'dag, S, HW>
where
S: Store<HW>,
HW: HashWriter,
{
dag: &'dag Merkle<S, HW>,
search_nodes: BTreeSet<Vec<u8>>,
root_nodes: BTreeSet<Vec<u8>>,
}
impl<'dag, S, HW> Missing<'dag, S, HW>
@ -33,19 +33,17 @@ where
S: Store<HW>,
HW: HashWriter,
{
/// Create an Iterator for the missing nodes given a set of root nodes.
pub fn new(dag: &'dag Merkle<S, HW>, search_nodes: BTreeSet<Vec<u8>>) -> Self {
Self { dag, search_nodes }
/// Create an iterator for the missing [nodes](Node) given a set of root [nodes](Node).
pub fn new(dag: &'dag Merkle<S, HW>, root_nodes: BTreeSet<Vec<u8>>) -> Self {
Self { dag, root_nodes }
}
/// Returns the next set of missing nodes in the iterator.
/// Returns the next set of missing [nodes](Node) in the iterator.
pub fn next(&mut self) -> Result<Option<Vec<Node<HW>>>> {
let nodes = self
.dag
.find_next_non_descendant_nodes(&self.search_nodes)?;
self.search_nodes = BTreeSet::new();
let nodes = self.dag.find_next_non_descendant_nodes(&self.root_nodes)?;
self.root_nodes = BTreeSet::new();
for id in nodes.iter().map(|n| n.id().to_vec()) {
self.search_nodes.insert(id);
self.root_nodes.insert(id);
}
if nodes.len() > 0 {
Ok(Some(nodes))

34
src/dag/mod.rs
View File

@ -24,7 +24,7 @@ use crate::{
mod iter;
pub use iter::*;
/// Node comparison values. In a given Merkle DAG a Node can come `After`, `Before`, be `Equivalent`, or `Uncomparable`.
/// Node comparison values. In a given Merkle DAG a Node can come [After](NodeCompare::After), [Before](NodeCompare::After), be [Equivalent](NodeCompare::Equivalent), or [Uncomparable](NodeCompare::Uncomparable).
/// If the two nodes have the same id they are eqivalent. If two nodes are not part of the same sub graph within the DAG
/// then they are Uncomparable. If one node is an ancestor of another DAG then that node comes before the other. If the
/// reverse is true then that node comes after the other.
@ -42,10 +42,9 @@ pub enum NodeCompare {
/// preserved during construction.
///
/// The merkle dag consists of a set of pointers to the current known roots as well as the total set
/// of nodes in the dag. Node payload items must be of a single type and implement the `ByteEncoder`
/// trait.
/// of [Nodes](Node) in the dag.
///
/// A merkle DAG instance is tied to a specific implementation of the HashWriter interface to ensure
/// A Merkle instance is tied to a specific implementation of the [HashWriter] interface to ensure
/// that all hash identifiers are of the same hash algorithm.
#[derive(Clone, Debug)]
pub struct Merkle<S, HW>
@ -63,7 +62,7 @@ where
HW: HashWriter,
S: Store<HW>,
{
/// Construct a new empty DAG. The empty DAG is also the default for a DAG.
/// Construct a new DAG.
pub fn new(s: S) -> Self {
Self {
nodes: s,
@ -76,7 +75,7 @@ where
/// and add it to the DAG with the given payload item and dependency id set. It is idempotent for any
/// given set of inputs.
///
/// One result of not constructing and then adding nodes in this way is that we ensure that we always
/// One result of not constructing and then adding [nodes](Node) is that we ensure that we always
/// satisfy the implementation rule in the merkel-crdt's whitepaper.
pub fn add_node<'a, N: Into<Vec<u8>>>(
&'a mut self,
@ -114,31 +113,31 @@ where
Ok(id.to_vec())
}
/// Check if we already have a copy of a node.
/// Check if we already have a copy of a [Node].
pub fn check_for_node(&self, id: &[u8]) -> Result<bool> {
return self.nodes.contains(id);
}
/// Get a node from the DAG by it's hash identifier if it exists.
/// Get a [Node] from the DAG by it's hash identifier if it exists.
pub fn get_node_by_id(&self, id: &[u8]) -> Result<Option<Node<HW>>> {
self.nodes.get(id)
}
/// Get the set of root node ids.
/// Get the set of root [Node] ids.
pub fn get_roots(&self) -> &BTreeSet<Vec<u8>> {
&self.roots
}
/// Get the map of all nodes in the DAG.
/// Get the map of all [nodes](Node) in the DAG.
pub fn get_nodes(&self) -> &S {
&self.nodes
}
/// Compare two nodes by id in the graph. If the left id is an ancestor of the right node
/// then `returns `NodeCompare::Before`. If the right id is an ancestor of the left node
/// then returns `NodeCompare::After`. If both id's are equal then the returns
/// `NodeCompare::Equivalent`. If neither id are parts of the same subgraph then returns
/// `NodeCompare::Uncomparable`.
/// Compare two [nodes](Node) by id in the graph. If the left id is an ancestor of the right node
/// then returns [NodeCompare::Before]. If the right id is an ancestor of the left node
/// then returns [NodeCompare::After]. If both id's are equal then the returns
/// [NodeCompare::Equivalent]. If neither id are parts of the same subgraph then returns
/// [NodeCompare::Uncomparable].
pub fn compare(&self, left: &[u8], right: &[u8]) -> Result<NodeCompare> {
Ok(if left == right {
NodeCompare::Equivalent
@ -155,7 +154,8 @@ where
})
}
pub fn gap_fill_iter<'dag, 'iter>(
/// Construct a [Missing] iterator for this dag given a set of remote root nodes.
pub fn missing_iter<'dag, 'iter>(
&'dag self,
search_nodes: BTreeSet<Vec<u8>>,
) -> Missing<'iter, S, HW>
@ -165,7 +165,7 @@ where
Missing::new(self, search_nodes)
}
/// Find the immediate next non descendant nodes in this graph for the given `search_nodes`.
/// Find the immediate next non descendant [nodes](Node) in this graph for the given `search_nodes`.
pub fn find_next_non_descendant_nodes(
&self,
search_nodes: &BTreeSet<Vec<u8>>,

8
src/leveldb/mod.rs
View File

@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Module implementing a store interface using LevelDB for a MerkleDag.
//! Module implementing a [Store] interface using LevelDB for a [Merkle Dag](crate::dag::Merkle).
//! Requires the `rusty-leveldb` feature to be enabled.
use std::cell::RefCell;
@ -28,9 +28,9 @@ use rusty_leveldb::{self, Options, Status};
pub type Result<T> = std::result::Result<T, Status>;
/// A `Store` implementation using the rusty-leveldb port of leveldb.
/// The Default implementation of this `Default::default()` is an in-memory
/// implementation of the store.
/// A [Store] implementation using the rusty-leveldb port of leveldb.
/// The Default implementation of this is an in-memory implementation
/// of the store.
pub struct LevelStore {
store: RefCell<rusty_leveldb::DB>,
}

8
src/node.rs
View File

@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! `Node` types for satisfying the properties necessary for a MerkleDag.
//! [Node] type satisfying the properties necessary for a [Merkle Dag](crate::dag::Merkle).
use std::{collections::BTreeSet, marker::PhantomData};
@ -38,16 +38,16 @@ where
}
}
/// A node in a merkle DAG. Nodes are composed of a payload item and a set of dependency_ids.
/// A node in a [Merkle DAG](crate::dag::Merkle). Nodes are composed of a payload item and a set of dependency_ids.
/// They provide a unique identifier that is formed from the bytes of the payload as well
/// as the bytes of the dependency_ids. This is guaranteed to be the id for the same payload
/// and dependency ids every time making Nodes content-addressable.
///
/// Nodes also expose the unique content address of the item payload alone as a convenience.
///
/// Nodes are tied to a specific implementation of the HashWriter trait which is itself tied
/// Nodes are tied to a specific implementation of the [HashWriter] trait which is itself tied
/// to the DAG they are stored in guaranteeing that the same Hashing implementation is used
/// for each node in the DAG.
/// for each node in the [Merkle DAG](crate::dag::Merkle).
#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(from = "NodeSerde")]
pub struct Node<HW>

10
src/rocksdb/mod.rs
View File

@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Module implementing a rocksdb store interfaces for a MerkleDag.
//! Module implementing a [Store] interface using rocksdb for a [Merkle Dag](crate::dag::Merkle).
//! Requires the `rocksdb` feature to be enabled.
use std::path::Path;
@ -27,6 +27,8 @@ use rocksdb::{DBWithThreadMode, MultiThreaded, Options, SingleThreaded, ThreadMo
pub type Result<T> = std::result::Result<T, rocksdb::Error>;
/// A Rocksdb `Store` implementation generic over the single and multithreaded
/// versions.
pub struct RocksStore<TM>
where
TM: ThreadMode,
@ -34,13 +36,11 @@ where
store: DBWithThreadMode<TM>,
}
/// Type alias for a `RocksStore<SingleThreaded>`.
/// Type alias for a [RocksStore<SingleThreaded>].
pub type SingleThreadedRocksStore = RocksStore<SingleThreaded>;
/// Type alias for a `RocksStore<Multithreaded>`.
/// Type alias for a [RocksStore<Multithreaded>].
pub type MultiThreadedRocksStore = RocksStore<MultiThreaded>;
/// A Rocksdb `Store` implementation generic over the single and multithreaded
/// versions.
impl<TM> RocksStore<TM>
where
TM: ThreadMode,

3
src/sqlite/mod.rs
View File

@ -11,6 +11,8 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Module implementing a [Store] interface using sqlite for a [Merkle Dag](crate::dag::Merkle).
//! Requires the `sqlite` feature to be enabled.
use std::path::Path;
use crate::{
@ -22,6 +24,7 @@ use crate::{
use ciborium;
use rusqlite::{self, OptionalExtension};
/// A [Store] implementation using the [rusqlite] bindings for sqlite.
pub struct SqliteStore {
conn: rusqlite::Connection,
}

10
src/store.rs
View File

@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! The MerkleDag backing store trait.
//! The [Merkle Dag](crate::dag::Merkle) backing store trait.
use std::collections::BTreeMap;
@ -25,16 +25,16 @@ pub enum StoreError {
NoSuchDependents,
}
/// Trait representing the backing storage interface for a `DAG`.
/// Trait representing the backing storage interface for a [Merkle DAG](crate::dag::Merkle).
pub trait Store<HW>
where
HW: HashWriter,
{
/// Checks if the `Store` contains a node with this id.
/// Checks if the [Store] contains a [Node] with this id.
fn contains(&self, id: &[u8]) -> Result<bool>;
/// Fetches a node from the `Store` by id if it exists.
/// Fetches a node from the [Store] by id if it exists.
fn get(&self, id: &[u8]) -> Result<Option<Node<HW>>>;
/// Stores a given node.
/// Stores a given [Node].
fn store(&mut self, node: Node<HW>) -> Result<()>;
}