nodedb-types 0.1.0

Portable type definitions shared between NodeDB Origin and NodeDB-Lite
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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

// SPDX-License-Identifier: Apache-2.0

//! Cross-engine bitemporal retention configuration.
//!
//! Bitemporal collections split "retention" along two independent axes:
//!
//! - `data_retain_ms` — how long the *current* logical row stays queryable
//!   in live reads (the "as of now" view). Superseded by normal
//!   engine-specific retention when the collection is not bitemporal.
//! - `audit_retain_ms` — how long *superseded versions* of a row are
//!   preserved for historical / audit-time queries (the "as of then" view).
//!
//! The minimum audit retention is a floor enforced by policy — some
//! deployments (regulated, GDPR-on-paper, SOC2) require audit history to
//! survive beyond the default so operators can't silently configure it
//! below the compliance floor.
//!
//! Lives in `nodedb-types` because multiple engines (Columnar, Array,
//! EdgeStore, DocumentStrict) compose it into their engine-specific
//! config. Engine code consults the two axes separately: data purge
//! deletes the live row when `data_retain_ms` elapses; audit purge
//! deletes superseded versions when `audit_retain_ms` elapses.

use serde::{Deserialize, Serialize};

/// Error validating a [`BitemporalRetention`].
#[derive(Debug, thiserror::Error)]
#[error("bitemporal retention: {field} — {reason}")]
pub struct RetentionValidationError {
    pub field: String,
    pub reason: String,
}

/// Per-collection bitemporal retention policy.
///
/// Two independent axes: data (live rows) and audit (superseded
/// versions). Zero on either axis means "retain forever".
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct BitemporalRetention {
    /// Retention for currently-live rows (versions where
    /// `_ts_valid_until == MAX`). `0` = retain forever.
    pub data_retain_ms: u64,

    /// Retention for superseded versions (versions where
    /// `_ts_valid_until < MAX`). `0` = retain forever.
    pub audit_retain_ms: u64,

    /// Policy floor for `audit_retain_ms`. Operators cannot configure
    /// `audit_retain_ms` below this value. `0` = no floor.
    pub minimum_audit_retain_ms: u64,
}

impl BitemporalRetention {
    /// Retain everything forever. Sensible conservative default for
    /// bitemporal collections where operator intent is unstated.
    pub const fn retain_forever() -> Self {
        Self {
            data_retain_ms: 0,
            audit_retain_ms: 0,
            minimum_audit_retain_ms: 0,
        }
    }

    /// Validate axis consistency and policy floor.
    pub fn validate(&self) -> Result<(), RetentionValidationError> {
        if self.minimum_audit_retain_ms > 0
            && self.audit_retain_ms > 0
            && self.audit_retain_ms < self.minimum_audit_retain_ms
        {
            return Err(RetentionValidationError {
                field: "audit_retain_ms".into(),
                reason: format!(
                    "{} is below minimum_audit_retain_ms ({})",
                    self.audit_retain_ms, self.minimum_audit_retain_ms
                ),
            });
        }
        Ok(())
    }
}

impl Default for BitemporalRetention {
    fn default() -> Self {
        Self::retain_forever()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn retain_forever_validates() {
        assert!(BitemporalRetention::retain_forever().validate().is_ok());
    }

    #[test]
    fn audit_below_floor_rejected() {
        let r = BitemporalRetention {
            data_retain_ms: 0,
            audit_retain_ms: 60_000,
            minimum_audit_retain_ms: 120_000,
        };
        let err = r.validate().expect_err("must reject");
        assert_eq!(err.field, "audit_retain_ms");
    }

    #[test]
    fn audit_at_or_above_floor_ok() {
        let r = BitemporalRetention {
            data_retain_ms: 0,
            audit_retain_ms: 120_000,
            minimum_audit_retain_ms: 120_000,
        };
        assert!(r.validate().is_ok());
    }

    #[test]
    fn zero_audit_ignores_floor() {
        // audit_retain_ms == 0 means "retain forever" — floor does not apply.
        let r = BitemporalRetention {
            data_retain_ms: 0,
            audit_retain_ms: 0,
            minimum_audit_retain_ms: 120_000,
        };
        assert!(r.validate().is_ok());
    }

    #[test]
    fn data_and_audit_are_independent() {
        let r = BitemporalRetention {
            data_retain_ms: 30_000,
            audit_retain_ms: 300_000,
            minimum_audit_retain_ms: 0,
        };
        assert!(r.validate().is_ok());
    }
}