nodedb 0.2.1

Local-first, real-time, edge-to-cloud hybrid database for multi-modal workloads
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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

// SPDX-License-Identifier: BUSL-1.1

//! Applied-index gate.
//!
//! Ensures the metadata raft group has finished replaying its
//! committed log before the node advances past
//! `CatalogSanityCheck`. A gap here means the applier fell
//! behind between `raft_ready_rx` firing (which only waits for
//! the first entry) and the recovery check running. Serving
//! client traffic against that state is a correctness bug —
//! the next DDL would race an unapplied prior entry.
//!
//! Implementation note: `MetadataCache.applied_index` is the
//! local applier's watermark. The "expected committed index"
//! is read from the `AppliedIndexWatcher::current()` accessor,
//! which is advanced by the same applier. In practice a gap
//! can only occur if the applier crashed mid-batch or the
//! `current()` source diverges from the cache — both are
//! programming bugs the sanity check exists to surface.

use crate::control::state::SharedState;

/// Outcome of the applied-index gate.
#[derive(Debug, Clone, Copy)]
pub struct AppliedIndexGate {
    /// `MetadataCache.applied_index` observed at check time.
    pub cache_applied: u64,
    /// Watermark observed from `AppliedIndexWatcher::current`.
    pub watcher_current: u64,
    /// `watcher_current - cache_applied`. Zero means no gap.
    pub gap: u64,
}

impl AppliedIndexGate {
    pub fn is_ok(&self) -> bool {
        self.gap == 0
    }
}

/// Read both the `MetadataCache.applied_index` and the
/// `AppliedIndexWatcher::current` and report any gap.
///
/// Single-node mode (no cluster handle) returns a gate with
/// zero gap and zero indexes — there is nothing to replay.
pub fn check_applied_index(shared: &SharedState) -> AppliedIndexGate {
    // If we're in single-node mode, neither source exists in a
    // meaningful sense. Return a trivially-ok gate.
    if shared.cluster_topology.is_none() {
        return AppliedIndexGate {
            cache_applied: 0,
            watcher_current: 0,
            gap: 0,
        };
    }

    let cache_applied = {
        let cache = match shared.metadata_cache.read() {
            Ok(c) => c,
            Err(p) => {
                tracing::error!(
                    "metadata_cache RwLock poisoned during applied-index gate — \
                     recovering guard"
                );
                p.into_inner()
            }
        };
        cache.applied_index
    };

    let watcher_current = shared
        .applied_index_watcher(nodedb_cluster::METADATA_GROUP_ID)
        .current();

    let gap = watcher_current.saturating_sub(cache_applied);
    AppliedIndexGate {
        cache_applied,
        watcher_current,
        gap,
    }
}

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

    #[test]
    fn gate_ok_when_indexes_match() {
        let g = AppliedIndexGate {
            cache_applied: 42,
            watcher_current: 42,
            gap: 0,
        };
        assert!(g.is_ok());
    }

    #[test]
    fn gate_fails_on_gap() {
        let g = AppliedIndexGate {
            cache_applied: 10,
            watcher_current: 42,
            gap: 32,
        };
        assert!(!g.is_ok());
    }
}