nodedb 0.2.0

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

// SPDX-License-Identifier: BUSL-1.1

//! WAL appender for surrogate hwm flushes.
//!
//! Decouples the registry's flush path from a concrete `WalManager`
//! handle so tests can substitute a no-op (or in-memory) appender
//! without spinning up a real WAL. Production wires
//! [`WalSurrogateAppender`].
//!
//! The appender is invoked from [`crate::control::surrogate::assign`]
//! immediately after the catalog hwm row has been persisted. Order is
//! load-bearing for crash recovery: post-restart we read the catalog
//! row first; the WAL record is only consulted if the catalog is
//! behind (S2 will wire the actual replay path).

use std::sync::Arc;

use crate::wal::WalManager;

/// Pluggable WAL appender. Tests substitute `NoopWalAppender`;
/// production wires [`WalSurrogateAppender`] (a thin wrapper over
/// `Arc<WalManager>`).
pub trait SurrogateWalAppender: Send + Sync {
    /// Append a `SurrogateAlloc` record carrying the new high-water
    /// surrogate value. Called by the surrogate-flush path after the
    /// catalog row has been updated.
    fn record_alloc_to_wal(&self, hi: u32) -> crate::Result<()>;

    /// Append a `SurrogateBind` record carrying the
    /// `(surrogate, collection, pk_bytes)` triple. Called by
    /// `SurrogateAssigner::assign` after the catalog two-table txn so
    /// the binding is durable before the write-lock is released.
    fn record_bind_to_wal(
        &self,
        surrogate: u32,
        collection: &str,
        pk_bytes: &[u8],
    ) -> crate::Result<()>;
}

/// Production appender — wraps `Arc<WalManager>` and forwards to
/// `WalManager::append_surrogate_alloc`.
pub struct WalSurrogateAppender {
    wal: Arc<WalManager>,
}

impl WalSurrogateAppender {
    pub fn new(wal: Arc<WalManager>) -> Self {
        Self { wal }
    }
}

impl SurrogateWalAppender for WalSurrogateAppender {
    fn record_alloc_to_wal(&self, hi: u32) -> crate::Result<()> {
        self.wal.append_surrogate_alloc(hi).map(|_| ())
    }

    fn record_bind_to_wal(
        &self,
        surrogate: u32,
        collection: &str,
        pk_bytes: &[u8],
    ) -> crate::Result<()> {
        self.wal
            .append_surrogate_bind(surrogate, collection, pk_bytes)?;
        // Force the record to disk before the assigner releases its
        // write-lock. A crash after `assign` returns must always see
        // the binding on replay; group-commit batching alone does not
        // give us that guarantee.
        self.wal.sync()
    }
}

/// No-op appender. Used by tests that exercise assign / flush logic
/// without a WAL (and by the bootstrap shim before the WAL is wired).
pub struct NoopWalAppender;

impl SurrogateWalAppender for NoopWalAppender {
    fn record_alloc_to_wal(&self, _hi: u32) -> crate::Result<()> {
        Ok(())
    }

    fn record_bind_to_wal(
        &self,
        _surrogate: u32,
        _collection: &str,
        _pk_bytes: &[u8],
    ) -> crate::Result<()> {
        Ok(())
    }
}

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

    #[test]
    fn noop_appender_succeeds() {
        let a = NoopWalAppender;
        a.record_alloc_to_wal(123).unwrap();
        a.record_alloc_to_wal(u32::MAX).unwrap();
    }
}