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
10commonware_macros::stability_mod!(ALPHA, pub mod authenticated);
11pub mod contiguous;
12mod frame;
13pub mod segmented;
14
15#[cfg(all(test, feature = "arbitrary"))]
16mod conformance;
17
18/// Errors that can occur when interacting with `Journal`.
19#[derive(Debug, Error)]
20pub enum Error {
21    #[error("merkle error: {0}")]
22    Merkle(anyhow::Error),
23    #[error("journal error: {0}")]
24    Journal(anyhow::Error),
25    #[error("runtime error: {0}")]
26    Runtime(#[from] commonware_runtime::Error),
27    #[error("codec error: {0}")]
28    Codec(#[from] commonware_codec::Error),
29    #[error("metadata error: {0}")]
30    Metadata(#[from] crate::metadata::Error),
31    #[error("invalid blob name: {0}")]
32    InvalidBlobName(String),
33    #[error("invalid blob size: index={0} size={1}")]
34    InvalidBlobSize(u64, u64),
35    #[error("item too large: size={0}")]
36    ItemTooLarge(usize),
37    #[error("already pruned to section: {0}")]
38    AlreadyPrunedToSection(u64),
39    #[error("section out of range: {0}")]
40    SectionOutOfRange(u64),
41    #[error("usize too small")]
42    UsizeTooSmall,
43    #[error("offset overflow")]
44    OffsetOverflow,
45    #[error("size overflow")]
46    SizeOverflow,
47    #[error("unexpected size: expected={0} actual={1}")]
48    UnexpectedSize(u32, u32),
49    #[error("missing blob: {0}")]
50    MissingBlob(u64),
51    #[error("item out of range: {0}")]
52    ItemOutOfRange(u64),
53    #[error("item pruned: {0}")]
54    ItemPruned(u64),
55    #[error("invalid rewind: {0}")]
56    InvalidRewind(u64),
57    #[error("compression failed")]
58    CompressionFailed,
59    #[error("decompression failed")]
60    DecompressionFailed,
61    #[error("value too large (> u32::MAX)")]
62    ValueTooLarge,
63    #[error("corruption detected: {0}")]
64    Corruption(String),
65    /// The offsets journal and the data journal disagree about an item's layout. Either the
66    /// on-disk state is corrupted, or the caller passed offsets that aren't byte-adjacent on disk.
67    #[error("offset/data layout mismatch in section {section} at offset {offset}: offsets journal expected {expected_len}, data varint reports {actual_len}")]
68    OffsetDataMismatch {
69        section: u64,
70        offset: u64,
71        expected_len: usize,
72        actual_len: usize,
73    },
74    #[error("invalid configuration: {0}")]
75    InvalidConfiguration(String),
76    #[error("checksum mismatch: expected={0}, found={1}")]
77    ChecksumMismatch(u32, u32),
78    #[error("empty append")]
79    EmptyAppend,
80}
commonware_storage/journal/mod.rs

commonware_storage/journal/
mod.rs
