mongreldb_core/
catalog.rs

1//! DB-wide catalog checkpoint (spec §5.1).
2//!
3//! The catalog records every table's id, name, schema, and live/dropped state
4//! plus the DB-wide monotonic counters (`db_epoch`, `next_table_id`,
5//! `open_generation` (sidecar), `next_segment_no`). CATALOG is rewritten on
6//! DDL and persisted to `<root>/CATALOG` with:
7//!
8//! - a fixed magic + SHA-256 integrity tag for plaintext, or
9//! - AES-256-GCM (`meta_dek`-derived via [`Kek::derive_meta_key`]) which both
10//!   encrypts and authenticates, plus
11//! - a directory `sync_all` after the atomic rename (review fix #19), so a crash
12//!   never leaves a half-linked catalog entry.
13
14use crate::error::{MongrelError, Result};
15use crate::external_table::ExternalTableEntry;
16use crate::procedure::ProcedureEntry;
17use crate::schema::Schema;
18use crate::trigger::TriggerEntry;
19use serde::{Deserialize, Serialize};
20use sha2::{Digest, Sha256};
21use std::io::Write;
22use std::path::Path;
23
24pub const CATALOG_FILENAME: &str = "CATALOG";
25const MAGIC: &[u8; 8] = b"MONGRCAT";
26/// 32-byte meta DEK length (matches [`crate::encryption::DEK_LEN`]).
27pub const META_DEK_LEN: usize = 32;
28
29/// Lifecycle state of a catalog table entry.
30#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
31pub enum TableState {
32    /// Live and queryable.
33    Live,
34    /// Logically dropped at `at_epoch`; the physical subdir is reaped once no
35    /// reader pins a snapshot older than `at_epoch`.
36    Dropped { at_epoch: u64 },
37}
38
39/// One row of the catalog.
40#[derive(Debug, Clone, Serialize, Deserialize)]
41pub struct CatalogEntry {
42    pub table_id: u64,
43    pub name: String,
44    pub schema: Schema,
45    pub state: TableState,
46    pub created_epoch: u64,
47}
48
49/// Persistent definition for a physical materialized-view table.
50#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
51pub struct MaterializedViewEntry {
52    pub name: String,
53    pub query: String,
54    pub last_refresh_epoch: u64,
55    #[serde(default)]
56    pub incremental: Option<IncrementalAggregateView>,
57}
58
59#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
60pub struct IncrementalAggregateView {
61    pub source_table: String,
62    pub source_table_id: u64,
63    pub group_column: u16,
64    pub group_output_column: u16,
65    pub outputs: Vec<IncrementalAggregateOutput>,
66    pub count_output_column: u16,
67    pub checkpoint_event_id: String,
68}
69
70#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
71pub struct IncrementalAggregateOutput {
72    pub output_column: u16,
73    pub kind: IncrementalAggregateKind,
74}
75
76#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
77pub enum IncrementalAggregateKind {
78    Count,
79    Sum { source_column: u16 },
80}
81
82/// The full in-memory catalog, mirrored on disk by [`write_atomic`].
83///
84/// Note: `open_generation` is intentionally **not** stored here — it bumps on
85/// every open, and keeping it in CATALOG would dirty the working tree even for
86/// a bare read. It lives in a separate sidecar file (`_meta/generation`) that
87/// callers can `.gitignore` for content-addressed storage workflows.
88#[derive(Debug, Clone, Serialize, Deserialize, Default)]
89pub struct Catalog {
90    /// Highest epoch ever assigned by this DB's commit sequencer.
91    pub db_epoch: u64,
92    /// Next table id to allocate.
93    pub next_table_id: u64,
94    /// Next shared-WAL segment number to allocate.
95    pub next_segment_no: u64,
96    pub tables: Vec<CatalogEntry>,
97    #[serde(default)]
98    pub procedures: Vec<ProcedureEntry>,
99    #[serde(default)]
100    pub triggers: Vec<TriggerEntry>,
101    #[serde(default)]
102    pub external_tables: Vec<ExternalTableEntry>,
103    #[serde(default)]
104    pub materialized_views: Vec<MaterializedViewEntry>,
105    #[serde(default)]
106    pub security: crate::security::SecurityCatalog,
107    /// Catalog-level user accounts (Argon2id-hashed credentials).
108    #[serde(default)]
109    pub users: Vec<crate::auth::UserEntry>,
110    /// Catalog-level role definitions.
111    #[serde(default)]
112    pub roles: Vec<crate::auth::RoleEntry>,
113    /// Next monotonic user id to allocate.
114    #[serde(default)]
115    pub next_user_id: u64,
116    /// When true, every Database/Table/Transaction/MongrelSession operation
117    /// requires an authenticated `Principal` with sufficient permission.
118    /// Defaults to false → existing credentialless databases open unchanged.
119    /// See `docs/15-credential-enforcement.md`.
120    #[serde(default)]
121    pub require_auth: bool,
122}
123
124/// The `open_generation` counter, stored in `_meta/generation` (NOT in CATALOG).
125/// Bumped on every open to scope `txn_id` across reopens so ids never alias.
126///
127/// Kept as a sidecar so that CATALOG is stable across bare opens — the only
128/// volatile bytes in the database directory during a read-only session are
129/// this 8-byte file + `.lock` + caches, all of which can be `.gitignore`-d.
130pub const GENERATION_FILENAME: &str = "generation";
131
132/// Read `open_generation` from `_meta/generation`. Returns 0 if the file is
133/// missing (first open or after a fresh `create`). On legacy databases that
134/// stored `open_generation` inside CATALOG, the migration path is: if the
135/// sidecar doesn't exist, default to 0 (the counter only needs to be
136/// monotonic within a process's lifetime for txn-id uniqueness).
137pub fn read_generation(meta_dir: &Path) -> u64 {
138    let p = meta_dir.join(GENERATION_FILENAME);
139    match std::fs::read(&p) {
140        Ok(bytes) => {
141            if bytes.len() >= 8 {
142                let mut arr = [0u8; 8];
143                arr.copy_from_slice(&bytes[..8]);
144                u64::from_le_bytes(arr)
145            } else {
146                0
147            }
148        }
149        Err(_) => 0,
150    }
151}
152
153/// Write `open_generation` to `_meta/generation` atomically (temp + rename +
154/// fsync). This is intentionally a separate file from CATALOG so that CATALOG
155/// stays byte-stable across bare opens (the generation counter is the only
156/// field that changes on every open).
157pub fn write_generation(meta_dir: &Path, generation: u64) -> Result<()> {
158    std::fs::create_dir_all(meta_dir)?;
159    let tmp = meta_dir.join(format!(".{GENERATION_FILENAME}.tmp"));
160    {
161        let mut f = std::fs::File::create(&tmp)?;
162        f.write_all(&generation.to_le_bytes())?;
163        f.sync_all()?;
164    }
165    let dest = meta_dir.join(GENERATION_FILENAME);
166    std::fs::rename(&tmp, &dest)?;
167    if let Ok(d) = std::fs::File::open(meta_dir) {
168        let _ = d.sync_all();
169    }
170    Ok(())
171}
172
173impl Catalog {
174    /// An empty catalog for a freshly created DB.
175    pub fn empty() -> Self {
176        Catalog::default()
177    }
178
179    /// Look up an entry by name (live only).
180    pub fn live(&self, name: &str) -> Option<&CatalogEntry> {
181        self.tables
182            .iter()
183            .find(|t| t.name == name && matches!(t.state, TableState::Live))
184    }
185}
186
187#[cfg(feature = "encryption")]
188fn seal(body: &[u8], meta_dek: Option<&[u8; META_DEK_LEN]>) -> Result<Vec<u8>> {
189    match meta_dek {
190        Some(dek) => crate::encryption::encrypt_blob(dek, body),
191        None => Ok(plaintext_frame(body)),
192    }
193}
194
195#[cfg(not(feature = "encryption"))]
196fn seal(body: &[u8], _meta_dek: Option<&[u8; META_DEK_LEN]>) -> Result<Vec<u8>> {
197    Ok(plaintext_frame(body))
198}
199
200fn plaintext_frame(body: &[u8]) -> Vec<u8> {
201    let hash = Sha256::digest(body);
202    let mut out = Vec::with_capacity(body.len() + 8 + 32);
203    out.extend_from_slice(MAGIC);
204    out.extend_from_slice(&hash);
205    out.extend_from_slice(body);
206    out
207}
208
209/// Atomically write the catalog to `<dir>/CATALOG` (review fix #19: dir-fsync).
210///
211/// If `meta_dek` is `Some`, the body is AES-256-GCM sealed (confidential +
212/// authenticated); otherwise the body carries a SHA-256 tag (integrity only).
213pub fn write_atomic(
214    dir: &Path,
215    cat: &Catalog,
216    meta_dek: Option<&[u8; META_DEK_LEN]>,
217) -> Result<()> {
218    let body = serde_json::to_vec(cat)
219        .map_err(|e| MongrelError::Other(format!("catalog serialize: {e}")))?;
220    let payload = seal(&body, meta_dek)?;
221
222    let tmp = dir.join(format!(".{CATALOG_FILENAME}.tmp"));
223    {
224        let mut f = std::fs::File::create(&tmp)?;
225        f.write_all(&payload)?;
226        f.sync_all()?;
227    }
228    let dest = dir.join(CATALOG_FILENAME);
229    std::fs::rename(&tmp, &dest)?;
230    // Directory fsync so the rename is durable across a crash.
231    if let Ok(d) = std::fs::File::open(dir) {
232        let _ = d.sync_all();
233    }
234    Ok(())
235}
236
237#[cfg(feature = "encryption")]
238fn open_payload(bytes: &[u8], meta_dek: Option<&[u8; META_DEK_LEN]>) -> Result<Option<Catalog>> {
239    match meta_dek {
240        Some(dek) => match crate::encryption::decrypt_blob(dek, bytes) {
241            Ok(body) => deserialize(&body),
242            Err(_) => Ok(None),
243        },
244        None => parse_plaintext(bytes),
245    }
246}
247
248#[cfg(not(feature = "encryption"))]
249fn open_payload(bytes: &[u8], _meta_dek: Option<&[u8; META_DEK_LEN]>) -> Result<Option<Catalog>> {
250    parse_plaintext(bytes)
251}
252
253fn deserialize(body: &[u8]) -> Result<Option<Catalog>> {
254    serde_json::from_slice(body)
255        .map(Some)
256        .map_err(|e| MongrelError::Other(format!("catalog deserialize: {e}")))
257}
258
259/// Read the catalog from `<dir>/CATALOG`. Returns `Ok(None)` if no catalog is
260/// present, or if authentication fails (tampered / wrong key).
261pub fn read(dir: &Path, meta_dek: Option<&[u8; META_DEK_LEN]>) -> Result<Option<Catalog>> {
262    let p = dir.join(CATALOG_FILENAME);
263    let bytes = match std::fs::read(&p) {
264        Ok(b) => b,
265        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
266        Err(e) => return Err(e.into()),
267    };
268    open_payload(&bytes, meta_dek)
269}
270
271fn parse_plaintext(bytes: &[u8]) -> Result<Option<Catalog>> {
272    if bytes.len() < 8 + 32 || &bytes[..8] != MAGIC {
273        return Ok(None);
274    }
275    let (tag, body) = bytes[8..].split_at(32);
276    let calc = Sha256::digest(body);
277    if tag != calc.as_slice() {
278        // tampered
279        return Ok(None);
280    }
281    deserialize(body)
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287
288    #[test]
289    fn empty_catalog_default() {
290        let c = Catalog::empty();
291        assert_eq!(c.db_epoch, 0);
292        assert_eq!(c.next_table_id, 0);
293        assert!(c.tables.is_empty());
294    }
295}
mongreldb_core/catalog.rs

mongreldb_core/
catalog.rs
