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 fixed;
11pub mod variable;
12
13impl<E, Op> crate::adb::sync::Journal for 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) -> Result<u64, Self::Error> {
22        fixed::Journal::size(self).await
23    }
24
25    async fn append(&mut self, op: Self::Op) -> Result<(), Self::Error> {
26        fixed::Journal::append(self, op).await.map(|_| ())
27    }
28
29    async fn close(self) -> Result<(), Self::Error> {
30        fixed::Journal::close(self).await
31    }
32}
33
34/// Errors that can occur when interacting with `Journal`.
35#[derive(Debug, Error)]
36pub enum Error {
37    #[error("runtime error: {0}")]
38    Runtime(#[from] commonware_runtime::Error),
39    #[error("codec error: {0}")]
40    Codec(#[from] commonware_codec::Error),
41    #[error("invalid blob name: {0}")]
42    InvalidBlobName(String),
43    #[error("invalid blob size: index={0} size={1}")]
44    InvalidBlobSize(u64, u64),
45    #[error("checksum mismatch: expected={0} actual={1}")]
46    ChecksumMismatch(u32, u32),
47    #[error("item too large: size={0}")]
48    ItemTooLarge(usize),
49    #[error("already pruned to section: {0}")]
50    AlreadyPrunedToSection(u64),
51    #[error("section out of range: {0}")]
52    SectionOutOfRange(u64),
53    #[error("usize too small")]
54    UsizeTooSmall,
55    #[error("offset overflow")]
56    OffsetOverflow,
57    #[error("unexpected size: expected={0} actual={1}")]
58    UnexpectedSize(u32, u32),
59    #[error("missing blob: {0}")]
60    MissingBlob(u64),
61    #[error("item out of range: {0}")]
62    ItemOutOfRange(u64),
63    #[error("item pruned: {0}")]
64    ItemPruned(u64),
65    #[error("invalid rewind: {0}")]
66    InvalidRewind(u64),
67    #[error("compression failed")]
68    CompressionFailed,
69    #[error("decompression failed")]
70    DecompressionFailed,
71    #[error("invalid sync range: lower_bound={0} upper_bound={1}")]
72    InvalidSyncRange(u64, u64),
73}
commonware_storage/journal/mod.rs

commonware_storage/journal/
mod.rs
