spacetimedb-commitlog 1.3.0

Implementation of the SpacetimeDB commitlog.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

use std::io;

use spacetimedb_sats::buffer::DecodeError;
use thiserror::Error;

use crate::segment;

/// Error yielded by public commitlog iterators.
#[derive(Debug, Error)]
pub enum Traversal {
    #[error("out-of-order commit: expected-offset={expected_offset} actual-offset={actual_offset}")]
    OutOfOrder {
        expected_offset: u64,
        actual_offset: u64,
        /// If the next segment starts with a commit with matching offset, a
        /// previous bad commit will be ignored. If, however, the offset does
        /// **not** match, `prev_error` contains the error encountered when
        /// trying to read the previous commit (which was skipped).
        #[source]
        prev_error: Option<Box<Self>>,
    },
    /// The log is considered forked iff a commit with the same `min_tx_offset`
    /// but a different crc32 than the previous commit is encountered.
    ///
    /// This may happen in rare circumstances where a write was considered
    /// failed (e.g. due to a failed `fsync(2)`), when it was actually successful.
    #[error("forked history: offset={offset}")]
    Forked { offset: u64 },
    #[error("failed to decode tx record at offset={offset}")]
    Decode {
        offset: u64,
        #[source]
        source: DecodeError,
    },
    #[error("checksum mismatch at offset={offset}")]
    Checksum {
        offset: u64,
        #[source]
        source: ChecksumMismatch,
    },
    #[error(transparent)]
    Io(#[from] io::Error),
}

/// Error returned by [`crate::Commitlog::append`].
#[derive(Debug, Error)]
#[error("failed to commit during append")]
pub struct Append<T> {
    /// The payload which was passed to [`crate::Commitlog::append`], but was
    /// not retained because flushing the data to the underlying storage failed.
    pub txdata: T,
    /// Why flushing to persistent storage failed.
    #[source]
    pub source: io::Error,
}

/// A checksum mismatch was detected.
///
/// Usually wrapped in another error, such as [`io::Error`].
#[derive(Debug, Error)]
#[error("checksum mismatch")]
pub struct ChecksumMismatch;

#[derive(Debug, Error)]
pub enum SegmentMetadata {
    #[error("invalid commit encountered")]
    InvalidCommit {
        sofar: segment::Metadata,
        #[source]
        source: io::Error,
    },
    #[error(transparent)]
    Io(#[from] io::Error),
}

/// Recursively concatenate `e.source()`, separated by ": ".
pub(crate) fn source_chain(e: &impl std::error::Error) -> String {
    let mut s = String::new();
    let mut source = e.source();
    while let Some(cause) = source {
        s.push(':');
        s.push(' ');
        s.push_str(&cause.to_string());
        source = cause.source()
    }

    s
}