nodedb-columnar 0.1.0

Columnar segment format and memtable for NodeDB analytical storage
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
89
90
91
92
93
94

// SPDX-License-Identifier: Apache-2.0

//! Error types for columnar segment operations.

/// Errors from columnar segment encoding, decoding, and validation.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ColumnarError {
    #[error("codec error: {0}")]
    Codec(#[from] nodedb_codec::CodecError),

    #[error("segment too short: expected at least {expected} bytes, got {got}")]
    TruncatedSegment { expected: usize, got: usize },

    #[error("invalid magic bytes: expected NDBS, got {0:?}")]
    InvalidMagic([u8; 4]),

    #[error(
        "incompatible segment version: reader {reader_major}.x, segment {segment_major}.{segment_minor}"
    )]
    IncompatibleVersion {
        reader_major: u8,
        segment_major: u8,
        segment_minor: u8,
    },

    #[error("footer CRC32C mismatch: stored {stored:#010x}, computed {computed:#010x}")]
    FooterCrcMismatch { stored: u32, computed: u32 },

    #[error("column index {index} out of range (segment has {count} columns)")]
    ColumnOutOfRange { index: usize, count: usize },

    #[error("schema mismatch: expected {expected} columns, memtable has {got}")]
    SchemaMismatch { expected: usize, got: usize },

    #[error("memtable is empty — nothing to flush")]
    EmptyMemtable,

    #[error("serialization error: {0}")]
    Serialization(String),

    #[error("value type mismatch for column '{column}': expected {expected}")]
    TypeMismatch { column: String, expected: String },

    #[error("null violation: column '{0}' is NOT NULL")]
    NullViolation(String),

    #[error("duplicate primary key")]
    DuplicatePrimaryKey,

    #[error("primary key not found")]
    PrimaryKeyNotFound,

    #[error("segment ID space exhausted: u64::MAX segments have been allocated")]
    SegmentIdExhausted,

    /// Structural corruption detected while parsing a segment header or footer.
    ///
    /// `offset` is the byte position from the start of the segment where the
    /// problem was detected. `segment_id` is `None` when the parse fails before
    /// the id can be resolved (e.g. inside the footer itself).
    #[error("segment corruption in {segment_id:?} at offset {offset:?}: {reason}")]
    Corruption {
        segment_id: Option<String>,
        reason: String,
        offset: Option<u64>,
    },

    /// Segment is encrypted (starts with `SEGV`) but no KEK was supplied.
    #[error(
        "columnar segment is encrypted but no encryption key was provided; \
         cannot read an encrypted segment without a key"
    )]
    MissingKek,

    /// Segment is plaintext (`NDBS`) but a KEK is configured (policy violation).
    #[error(
        "columnar segment is plaintext but an encryption key is configured; \
         refusing to load an unencrypted segment when encryption is required"
    )]
    KekRequired,

    /// AES-256-GCM encryption of the segment payload failed.
    #[error("columnar segment encryption failed: {0}")]
    EncryptionFailed(String),

    /// AES-256-GCM decryption of the segment payload failed.
    #[error("columnar segment decryption failed: {0}")]
    DecryptionFailed(String),

    /// Memory budget exhausted or global ceiling exceeded.
    #[error("memory budget exhausted: {0}")]
    BudgetExhausted(#[from] nodedb_mem::MemError),
}