make most requested changes

src/model/block.rs

@@ -157,7 +157,7 @@ impl BlockManager {
 	}
 
 	/// Write a block to disk
-	pub async fn write_block(&self, hash: &Hash, data: &[u8]) -> Result<Message, Error> {
+	async fn write_block(&self, hash: &Hash, data: &[u8]) -> Result<Message, Error> {
 		let _lock = self.data_dir_lock.lock().await;
 
 		let mut path = self.block_dir(hash);
@@ -176,7 +176,7 @@ impl BlockManager {
 	}
 
 	/// Read block from disk, verifying it's integrity
-	pub async fn read_block(&self, hash: &Hash) -> Result<Message, Error> {
+	async fn read_block(&self, hash: &Hash) -> Result<Message, Error> {
 		let path = self.block_path(hash);
 
 		let mut f = match fs::File::open(&path).await {
@@ -208,7 +208,7 @@ impl BlockManager {
 	}
 
 	/// Check if this node should have a block, but don't actually have it
-	pub async fn need_block(&self, hash: &Hash) -> Result<bool, Error> {
+	async fn need_block(&self, hash: &Hash) -> Result<bool, Error> {
 		let needed = self
 			.rc
 			.get(hash.as_ref())?

src/model/block_ref_table.rs

@@ -10,16 +10,14 @@ use crate::block::*;
 
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct BlockRef {
-	// Primary key
-	/// Hash of the block
+	/// Hash of the block, used as partition key
 	pub block: Hash,
 
-	// Sort key
-	// why a version on a hashed (probably immutable) piece of data?
+	/// Id of the Version for the object containing this block, used as sorting key
 	pub version: UUID,
 
 	// Keep track of deleted status
-	/// Is that block deleted
+	/// Is the Version that contains this block deleted
 	pub deleted: crdt::Bool,
 }
 

src/model/key_table.rs

@@ -6,7 +6,7 @@ use garage_table::*;
 /// An api key
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct Key {
-	/// The id of the key (immutable)
+	/// The id of the key (immutable), used as partition key
 	pub key_id: String,
 
 	/// The secret_key associated
@@ -19,6 +19,7 @@ pub struct Key {
 	pub deleted: crdt::Bool,
 
 	/// Buckets in which the key is authorized. Empty if `Key` is deleted
+	// CRDT interaction: deleted implies authorized_buckets is empty
 	pub authorized_buckets: crdt::LWWMap<String, PermissionSet>,
 }
 

src/model/lib.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 #[macro_use]
 extern crate log;
 

src/model/object_table.rs

@@ -14,13 +14,13 @@ use crate::version_table::*;
 /// An object
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct Object {
-	/// The bucket in which the object is stored
+	/// The bucket in which the object is stored, used as partition key
 	pub bucket: String,
 
-	/// The key at which the object is stored in its bucket
+	/// The key at which the object is stored in its bucket, used as sorting key
 	pub key: String,
 
-	/// The list of known versions of the object
+	/// The list of currenty stored versions of the object
 	versions: Vec<ObjectVersion>,
 }
 
@@ -53,7 +53,7 @@ impl Object {
 		}
 	}
 
-	/// Get a list of all versions known for `Object`
+	/// Get a list of currently stored versions of `Object`
 	pub fn versions(&self) -> &[ObjectVersion] {
 		&self.versions[..]
 	}
@@ -77,7 +77,7 @@ pub enum ObjectVersionState {
 	Uploading(ObjectVersionHeaders),
 	/// The version is fully received
 	Complete(ObjectVersionData),
-	/// The version was never fully received
+	/// The version uploaded containded errors or the upload was explicitly aborted
 	Aborted,
 }
 
@@ -105,7 +105,7 @@ impl CRDT for ObjectVersionState {
 /// Data about an object version
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug, Serialize, Deserialize)]
 pub enum ObjectVersionData {
-	/// The version is deleted
+	/// The object was deleted, this Version is a tombstone to mark it as such
 	DeleteMarker,
 	/// The object is short, it's stored inlined
 	Inline(ObjectVersionMeta, #[serde(with = "serde_bytes")] Vec<u8>),
@@ -159,7 +159,7 @@ impl ObjectVersion {
 		}
 	}
 
-	/// Is the object version available (received and not deleted)
+	/// Is the object version available (received and not a tombstone)
 	pub fn is_data(&self) -> bool {
 		match self.state {
 			ObjectVersionState::Complete(ObjectVersionData::DeleteMarker) => false,

src/model/version_table.rs

@@ -13,7 +13,7 @@ use crate::block_ref_table::*;
 /// A version of an object
 #[derive(PartialEq, Clone, Debug, Serialize, Deserialize)]
 pub struct Version {
-	/// UUID of the version
+	/// UUID of the version, used as partition key
 	pub uuid: UUID,
 
 	// Actual data: the blocks for this version
@@ -49,9 +49,9 @@ impl Version {
 
 #[derive(PartialEq, Eq, Clone, Copy, Debug, Serialize, Deserialize)]
 pub struct VersionBlockKey {
-	/// Number of the part, starting at 1
+	/// Number of the part
 	pub part_number: u64,
-	/// offset of the block in the file, starting at 0
+	/// Offset of this sub-segment in its part
 	pub offset: u64,
 }