aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2017-10-17 21:57:11 -0700
committerBryan Newbold <bnewbold@robocracy.org>2017-10-17 21:57:11 -0700
commit989f9a632034074b03d73b992d8bcebcc774ee54 (patch)
treecd484baa1ed07e452ae44afb21bb532424c8df0a
parent224e0524028e65ff7d5cf53c5b18d1dd407dfd43 (diff)
downloadgeniza-989f9a632034074b03d73b992d8bcebcc774ee54.tar.gz
geniza-989f9a632034074b03d73b992d8bcebcc774ee54.zip
more docs progress
-rw-r--r--src/lib.rs49
1 files changed, 43 insertions, 6 deletions
diff --git a/src/lib.rs b/src/lib.rs
index c51ce89..6d1c4cf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,15 @@
-//! Is this where crate-level docs go?
-//! Yes.
+//! This is a hobby/learning implementation of the dat distributed data synchronization system.
+//!
+//! Subcomponents are roughly organized in library form for easier reading/review, but buyer-beware
+//! actually trying to reuse this code for anything other than education or interop testing.
+//!
+//! ### References
+//!
+//! [Dat Whitepaper](https://github.com/datproject/docs)
+//!
+//! Additional notes in the source code for this repo, under the 'notes' directory. Also, see
+//! README.
#[macro_use]
extern crate error_chain;
@@ -26,10 +35,13 @@ mod errors {
Io(::std::io::Error) #[cfg(unix)]; }
}
}
+
+#[doc(hidden)]
pub use errors::*;
-/// Abstract access to SLEEP content.
+/// Abstract access to SLEEP content
+///
/// Back-ends could be in RAM, on disk, remote HTTP, etc.
pub trait SleepStorage {
@@ -56,9 +68,9 @@ pub trait SleepStorage {
fn len(&self) -> Result<u64>;
}
+/// Local File implementation of SleepStorage
#[derive(Debug)]
pub struct SleepFile {
- /// Local File implementation of SleepStorage
file: File,
magic: u32,
entry_size: u16,
@@ -173,20 +185,45 @@ impl SleepStorage for SleepFile {
}
-// Abstract access to hypercore register
+/// Abstract access to Hypercore register
pub trait HyperRegister {
+
+ /// Whether the register store contains the given (data) entry
fn has(&self, index: u64) -> Result<bool>;
+
+ /// Whether the register store contains *all* known (data) entries
fn has_all(&self) -> Result<bool>;
+
+ /// If the contiguous range of entries is in the store
fn has_range(&self, start: u64, end: u64) -> Result<bool>;
- fn get(&mut self, index: u64) -> Result<Vec<u8>>;
+
+ /// Reads a single data entry from the store.
+ fn get_data_entry(&mut self, index: u64) -> Result<Vec<u8>>;
+
+ /// Writes an entry to the store. Requires the private key to be present.
fn append(&mut self, data: &[u8]) -> Result<u64>;
+
+ /// Count of data entries for this register. This is the total count (highest entry index plus
+ /// one); this particular store might be sparse.
fn len(&self) -> Result<u64>;
+
+ /// Total size of this register in bytes.
fn len_bytes(&self) -> Result<u64>;
+
+ /// [UNIMPLEMENTED] Intended to do a deeper merkel-tree verification of all stored data
fn verify(&self) -> Result<()>;
+
+ /// Quick sanity checks on register store robust-ness
fn check(&self) -> Result<()>;
+
+ /// Can this register be appended to?
fn writable(&self) -> bool;
+
+ /// Returns a single tree entry (using tree indexing, not data indexing).
+ fn get_tree_entry(&mut self, index: u64) -> Result<Vec<u8>>;
}
+/// Implementation of HyperRegister using a local directory of SLEEP files
#[derive(Debug)]
pub struct SleepDirRegister {
tree_sleep: SleepFile,