diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-12-31 09:00:21 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-12-31 12:10:10 +0200 |
commit | acf1ba3f8f1492b961c9a6eb09eb93e882f5eb3f (patch) | |
tree | 1ce0288f878cac71990bb01f358d6035f1626c92 /src/chunk.rs | |
parent | 686e87981db210fa443404c8473dfe7a3f39b241 (diff) | |
download | obnam2-acf1ba3f8f1492b961c9a6eb09eb93e882f5eb3f.tar.gz |
docs: add documentation comments to crate
Also, make it an error for a public symbol to not be documented.
Sponsored-by: author
Diffstat (limited to 'src/chunk.rs')
-rw-r--r-- | src/chunk.rs | 29 |
1 files changed, 24 insertions, 5 deletions
diff --git a/src/chunk.rs b/src/chunk.rs index 266d1a7..15e3288 100644 --- a/src/chunk.rs +++ b/src/chunk.rs @@ -1,15 +1,18 @@ +//! Chunks of data. + use crate::checksummer::Checksum; use crate::chunkid::ChunkId; use crate::chunkmeta::ChunkMeta; use serde::{Deserialize, Serialize}; use std::default::Default; -/// Store an arbitrary chunk of data. -/// -/// The data is just arbitrary binary data. +/// An arbitrary chunk of arbitrary binary data. /// /// A chunk also contains its associated metadata, except its -/// identifier. +/// identifier, so that it's easy to keep the data and metadata +/// together. The identifier is used to find the chunk, and it's +/// assigned by the server when the chunk is uploaded, so it's not +/// stored in the chunk itself. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] pub struct DataChunk { data: Vec<u8>, @@ -17,7 +20,7 @@ pub struct DataChunk { } impl DataChunk { - /// Construct a new chunk. + /// Create a new chunk. pub fn new(data: Vec<u8>, meta: ChunkMeta) -> Self { Self { data, meta } } @@ -33,6 +36,13 @@ impl DataChunk { } } +/// A chunk representing a backup generation. +/// +/// A generation chunk lists all the data chunks for the SQLite file +/// with the backup's metadata. It's different from a normal data +/// chunk so that we can do things that make no sense to a data chunk. +/// Generation chunks can be converted into or created from data +/// chunks, for uploading to or downloading from the server. #[derive(Default, Debug, Serialize, Deserialize)] pub struct GenerationChunk { chunk_ids: Vec<ChunkId>, @@ -41,39 +51,48 @@ pub struct GenerationChunk { /// All the errors that may be returned for `GenerationChunk` operations. #[derive(Debug, thiserror::Error)] pub enum GenerationChunkError { + /// Error converting text from UTF8. #[error(transparent)] Utf8Error(#[from] std::str::Utf8Error), + /// Error parsing JSON as chunk metadata. #[error("failed to parse JSON: {0}")] JsonParse(serde_json::Error), + /// Error generating JSON from chunk metadata. #[error("failed to serialize to JSON: {0}")] JsonGenerate(serde_json::Error), } impl GenerationChunk { + /// Create a new backup generation chunk from metadata chunk ids. pub fn new(chunk_ids: Vec<ChunkId>) -> Self { Self { chunk_ids } } + /// Create a new backup generation chunk from a data chunk. pub fn from_data_chunk(chunk: &DataChunk) -> Result<Self, GenerationChunkError> { let data = chunk.data(); let data = std::str::from_utf8(data)?; serde_json::from_str(data).map_err(GenerationChunkError::JsonParse) } + /// Does the generation chunk contain any metadata chunks? pub fn is_empty(&self) -> bool { self.chunk_ids.is_empty() } + /// How many metadata chunks does generation chunk contain? pub fn len(&self) -> usize { self.chunk_ids.len() } + /// Return iterator over the metadata chunk identifiers. pub fn chunk_ids(&self) -> impl Iterator<Item = &ChunkId> { self.chunk_ids.iter() } + /// Convert generation chunk to a data chunk. pub fn to_data_chunk(&self, ended: &str) -> Result<DataChunk, GenerationChunkError> { let json: String = serde_json::to_string(self).map_err(GenerationChunkError::JsonGenerate)?; |