Started documenting the types in main.

crates/node/.vscode/settings.json

@@ -1,5 +1,6 @@
 {
     "cSpell.words": [
+        "Asym",
         "blocktree",
         "newtype",
         "Xsalsa"

crates/node/src/main.rs

@@ -1,81 +1,107 @@
 mod serde_blocktree;
 
-use std::collections::{hash_map, HashMap};
+use std::collections::HashMap;
 
+/// A Block tagged with its version number.
 #[allow(dead_code)]
 enum VersionedBlock {
     V0(Block)
 }
 
+/// A container which binds together ciphertext along with the metadata needed to identify,
+/// verify and decrypt it.
 #[allow(dead_code)]
 struct Block {
-    path: String,
-    read_caps: HashMap<Hash, ReadCap>,
+    /// A block is identified by this field, which defines its location in the tree.
+    path: Path,
+    /// This field contains a collection of `ReadCap`s indexed by the principal who holds them.
+    /// `ReadCap`s are envelopments of the key used to encrypt this block.
+    read_caps: HashMap<Principal, ReadCap>,
+    /// This field is used to verify that the signer of this block had permission to write it.
+    /// It contains a certificate chain that must lead back to the root key for the tree this block
+    /// is part of.
     write_cap: WriteCap,
-    body: Vec<u8>,
+    /// The encrypted data contained in this block.
+    body: SymCiphertext<Vec<u8>>,
+    /// The contents of the block are covered by a digital signature contained in this field.  
     signature: Signature
 }
 
+/// The body of every non-leaf node in a tree contains this data structure.
+#[allow(dead_code)]
+struct Directory {
+    /// The nodes that are attached to this block tree at this block.
+    nodes: Vec<Principal>,
+    /// The blocks that are descended from this one.
+    children: HashMap<String, FragmentRecord>,
+}
+
+/// An envelopment of a key, which is tagged with the principal who the key is meant for.
 #[allow(dead_code)]
 struct ReadCap {
-    issued_to: Hash,
-    key: EnvelopedKey,
+    /// The principal this `ReadCap` was issued to.
+    issued_to: Principal,
+    /// An encipherment of a block key using the public key of the principal.
+    key: AsymCiphertext<Key>,
 }
 
+/// Verifies that a principal is authorized to write blocks in a tree.
 #[allow(dead_code)]
 struct WriteCap {
-    issued_to: Hash,
-    path: String,
+    /// The principal this `WriteCap` was issued to.
+    issued_to: Principal,
+    path: Path,
     chain: Vec<Certificate>,
     signature: Signature,
 }
 
 #[allow(dead_code)]
 struct Certificate {
-    issued_to: Hash,
-    issued_by: Hash,
+    issued_to: Principal,
+    issued_by: Principal,
     signature: Signature,
+    // TODO: Add expiration.
 }
 
 #[allow(dead_code)]
-enum Hash {
-    Sha2_256([u8; 32]),
-    Sha2_512([u8; 64]),
+struct FragmentRecord {
+    stored_by: Hash,
+    serial: u32,
 }
 
 #[allow(dead_code)]
-enum Signature {
-    Ed25519([u8; 64]),
+struct Fragment {
+    path: String,
+    serial: u32,
+    body: Vec<u8>,
 }
 
-#[allow(dead_code)]
-enum EnvelopedKey {
-    Xsalsa20Poly1305([u8; 32]),
-}
+/// An identifier for a security principal, which is any entity that can be authenticated.
+struct Principal(Hash);
 
-type Directory = HashMap<String, Vec<FragmentRecord>>;
+/// Ciphertext which was produced using a symmetric algorithm.
+struct SymCiphertext<T>(T);
 
-trait IDirectory {
-    fn file_names(&self) -> hash_map::Keys<'_, String, Vec<FragmentRecord>>;
-}
+/// Ciphertext that was produced using an asymmetric algorithm.
+struct AsymCiphertext<T>(T);
 
-impl IDirectory for Directory {
-    fn file_names(&self) -> hash_map::Keys<'_, String, Vec<FragmentRecord>> {
-        self.keys()
-    }
+/// An identifier for a block in a tree.
+struct Path(Vec<String>);
+
+#[allow(dead_code)]
+enum Hash {
+    Sha2_256([u8; 32]),
+    Sha2_512([u8; 64]),
 }
 
 #[allow(dead_code)]
-struct FragmentRecord {
-    stored_by: Hash,
-    serial: u32,
+enum Signature {
+    Ed25519([u8; 64]),
 }
 
 #[allow(dead_code)]
-struct Fragment {
-    path: String,
-    serial: u32,
-    body: Vec<u8>,
+enum Key {
+    Xsalsa20Poly1305([u8; 32]),
 }
 
 fn main() {

crates/node/src/serde_blocktree/de.rs

@@ -14,12 +14,12 @@ use serde::de::{
 #[allow(dead_code)]
 pub fn from_vec<T: DeserializeOwned>(vec: &Vec<u8>) -> Result<T> {
     let mut slice = vec.as_slice();
-    let result = from_read(&mut slice);
+    let result = read_from(&mut slice);
     result
 }
 
 #[allow(dead_code)]
-pub fn from_read<T: DeserializeOwned, R: Read>(read: &mut R) -> Result<T> {
+pub fn read_from<T: DeserializeOwned, R: Read>(read: &mut R) -> Result<T> {
     let mut de = Deserializer::new(read);
     let result = Deserialize::deserialize(&mut de);
     result
@@ -34,9 +34,9 @@ fn try_from<TSource, TDest: TryFrom<TSource>>(value: TSource) -> Result<TDest> {
     Ok(cast)
 }
 
-/// Returns the number of bytes needed to store the unicode character in UTF-9 whose
+/// Returns the number of bytes needed to store the unicode character in UTF-8 whose
 /// encoding begins with the given byte. If the given byte is not valid as the first byte
-/// for any character, then a failed result with Error::InvalidUtf7Char is returned.
+/// for any character, then a failed result with Error::InvalidUtf8Char is returned.
 fn num_bytes_for_char(first_byte: u8) -> Result<usize> {
     if first_byte & 128u8 == 0  {
         return Ok(1);

crates/node/src/serde_blocktree/mod.rs

@@ -2,4 +2,8 @@ mod error;
 mod ser;
 mod de;
 
-pub use error::{Error, Result};
+pub use error::{Error, Result};
+
+pub use ser::{to_vec, write_to, Serializer};
+
+pub use de::{from_vec, read_from, Deserializer};

crates/node/src/serde_blocktree/ser.rs

@@ -18,15 +18,29 @@ use super::error::{Error, Result, MapError};
 
 type Ok = ();
 
-pub struct Serializer<T: Write> {
-    output: T,
+pub struct Serializer<'w, W: Write> {
+    output: &'w mut W,
+}
+
+impl<'w, W: Write> Serializer<'w, W> {
+    pub fn new(write: &'w mut W) -> Serializer<'w, W> {
+        Serializer { output: write }
+    }
 }
 
 #[allow(dead_code)]
 pub fn to_vec<T: Serialize + ?Sized>(value: &T) -> Result<Vec<u8>> {
-    let mut serializer = Serializer { output: Vec::new()};
-    value.serialize(&mut serializer)?;
-    Ok(serializer.output)
+    let mut vec = Vec::new();
+    let result = write_to(value, &mut vec);
+    result?;
+    Ok(vec)
+}
+
+#[allow(dead_code)]
+pub fn write_to<T: Serialize + ?Sized, W: Write>(value: &T, write: &mut W) -> Result<()> {
+    let mut serializer = Serializer::new(write);
+    let result = value.serialize(&mut serializer);
+    result
 }
 
 fn try_convert(len: Option<usize>) -> Result<u32> {
@@ -43,7 +57,7 @@ fn convert_variant_index(index: u32) -> Result<u16> {
     u16::try_from(index).or_else(|_| Err(Error::TooManyVariants(index)))
 }
 
-impl<'a, T: Write> ser::Serializer for &'a mut Serializer<T> {
+impl<'a, 'w, T: Write> ser::Serializer for &'a mut Serializer<'w, T> {
     type Ok = Ok;
     type Error = Error;
     type SerializeSeq = Self;
@@ -265,7 +279,7 @@ impl<'a, T: Write> ser::Serializer for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeSeq for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeSeq for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -280,7 +294,7 @@ impl<'a, T: Write> SerializeSeq for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeTuple for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeTuple for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -294,7 +308,7 @@ impl<'a, T: Write> SerializeTuple for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeTupleStruct for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeTupleStruct for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -308,7 +322,7 @@ impl<'a, T: Write> SerializeTupleStruct for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeTupleVariant for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeTupleVariant for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -322,7 +336,7 @@ impl<'a, T: Write> SerializeTupleVariant for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeMap for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeMap for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -341,7 +355,7 @@ impl<'a, T: Write> SerializeMap for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeStruct for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeStruct for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;
 
@@ -356,7 +370,7 @@ impl<'a, T: Write> SerializeStruct for &'a mut Serializer<T> {
     }
 }
 
-impl<'a, T: Write> SerializeStructVariant for &'a mut Serializer<T> {
+impl<'a, 'w, W: Write> SerializeStructVariant for &'a mut Serializer<'w, W> {
     type Ok = Ok;
     type Error = Error;