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

commonware_storage/journal/
mod.rs
