commonware_storage/journal/
mod.rs

1//! An append-only log for storing arbitrary data.
2//!
3//! Journals provide append-only logging for persisting arbitrary data with fast replay, historical
4//! pruning, and rudimentary support for fetching individual items. A journal can be used on its own
5//! to serve as a backing store for some in-memory data structure, or as a building block for a more
6//! complex construction that prescribes some meaning to items in the log.
7
8use thiserror::Error;
9
10pub mod contiguous;
11pub mod segmented;
12
13impl<E, Op> crate::adb::sync::Journal for contiguous::fixed::Journal<E, Op>
14where
15    E: commonware_runtime::Storage + commonware_runtime::Clock + commonware_runtime::Metrics,
16    Op: commonware_codec::Codec<Cfg = ()> + commonware_codec::FixedSize + Send + 'static,
17{
18    type Op = Op;
19    type Error = Error;
20
21    async fn size(&self) -> u64 {
22        contiguous::fixed::Journal::size(self).await
23    }
24
25    async fn append(&mut self, op: Self::Op) -> Result<(), Self::Error> {
26        contiguous::fixed::Journal::append(self, op)
27            .await
28            .map(|_| ())
29    }
30}
31
32/// Errors that can occur when interacting with `Journal`.
33#[derive(Debug, Error)]
34pub enum Error {
35    #[error("runtime error: {0}")]
36    Runtime(#[from] commonware_runtime::Error),
37    #[error("codec error: {0}")]
38    Codec(#[from] commonware_codec::Error),
39    #[error("invalid blob name: {0}")]
40    InvalidBlobName(String),
41    #[error("invalid blob size: index={0} size={1}")]
42    InvalidBlobSize(u64, u64),
43    #[error("checksum mismatch: expected={0} actual={1}")]
44    ChecksumMismatch(u32, u32),
45    #[error("item too large: size={0}")]
46    ItemTooLarge(usize),
47    #[error("already pruned to section: {0}")]
48    AlreadyPrunedToSection(u64),
49    #[error("section out of range: {0}")]
50    SectionOutOfRange(u64),
51    #[error("usize too small")]
52    UsizeTooSmall,
53    #[error("offset overflow")]
54    OffsetOverflow,
55    #[error("unexpected size: expected={0} actual={1}")]
56    UnexpectedSize(u32, u32),
57    #[error("missing blob: {0}")]
58    MissingBlob(u64),
59    #[error("item out of range: {0}")]
60    ItemOutOfRange(u64),
61    #[error("item pruned: {0}")]
62    ItemPruned(u64),
63    #[error("invalid rewind: {0}")]
64    InvalidRewind(u64),
65    #[error("compression failed")]
66    CompressionFailed,
67    #[error("decompression failed")]
68    DecompressionFailed,
69    #[error("corruption detected: {0}")]
70    Corruption(String),
71    #[error("invalid configuration: {0}")]
72    InvalidConfiguration(String),
73}
commonware_storage/journal/mod.rs

commonware_storage/journal/
mod.rs
