Skip to main content

qualia_client_core/wellfair/
graph_store.rs

1//! Materialized graph quins — append-only projection of checkpointed WAL commits.
2
3use std::fs::{self, OpenOptions};
4use std::io::{Read, Seek, SeekFrom, Write};
5use std::path::{Path, PathBuf};
6
7use qualia_core_db::NQuin;
8
9pub const GRAPH_QUINS_FILE: &str = "wellfair/graph/quins.bin";
10pub const MAX_LIST: usize = 512;
11
12pub struct GraphStore {
13    path: PathBuf,
14    quin_count: usize,
15}
16
17impl GraphStore {
18    /// Opens.
19    pub fn open(storage_root: impl AsRef<Path>) -> std::io::Result<Self> {
20        let path = storage_root.as_ref().join(GRAPH_QUINS_FILE);
21        if let Some(parent) = path.parent() {
22            fs::create_dir_all(parent)?;
23        }
24        if !path.exists() {
25            OpenOptions::new().create(true).write(true).open(&path)?;
26        }
27        let quin_count = count_quins(&path)?;
28        Ok(Self { path, quin_count })
29    }
30
31    /// Count.
32    pub fn count(&self) -> usize {
33        self.quin_count
34    }
35
36    /// Appends quins.
37    pub fn append_quins(&mut self, quins: &[NQuin]) -> std::io::Result<()> {
38        if quins.is_empty() {
39            return Ok(());
40        }
41        let mut file = OpenOptions::new().append(true).open(&self.path)?;
42        for quin in quins {
43            let bytes = quin_as_bytes(quin);
44            file.write_all(bytes)?;
45        }
46        file.sync_all()?;
47        self.quin_count += quins.len();
48        Ok(())
49    }
50
51    /// Lists recent entries.
52    pub fn list_recent(&self, limit: usize) -> std::io::Result<Vec<NQuin>> {
53        let mut file = fs::File::open(&self.path)?;
54        let len = file.metadata()?.len();
55        let quin_size = std::mem::size_of::<NQuin>() as u64;
56        if len < quin_size {
57            return Ok(Vec::new());
58        }
59        let total = (len / quin_size) as usize;
60        let keep = limit.min(MAX_LIST).min(total);
61        let start = len - (keep as u64 * quin_size);
62        file.seek(SeekFrom::Start(start))?;
63        let mut buffer = vec![0u8; keep * std::mem::size_of::<NQuin>()];
64        file.read_exact(&mut buffer)?;
65        Ok(decode_quins(&buffer))
66    }
67}
68
69fn count_quins(path: &Path) -> std::io::Result<usize> {
70    let len = fs::metadata(path)?.len();
71    Ok((len as usize) / std::mem::size_of::<NQuin>())
72}
73
74fn quin_as_bytes(quin: &NQuin) -> &[u8] {
75    unsafe {
76        std::slice::from_raw_parts(
77            (quin as *const NQuin) as *const u8,
78            std::mem::size_of::<NQuin>(),
79        )
80    }
81}
82
83fn decode_quins(buffer: &[u8]) -> Vec<NQuin> {
84    let quin_size = std::mem::size_of::<NQuin>();
85    buffer
86        .chunks_exact(quin_size)
87        .map(|chunk| unsafe { std::ptr::read_unaligned(chunk.as_ptr() as *const NQuin) })
88        .collect()
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn graph_store_round_trip() {
97        let dir = tempfile::tempdir().unwrap();
98        let mut store = GraphStore::open(dir.path()).unwrap();
99        let q = NQuin {
100            subject: 1,
101            predicate: 2,
102            object: 3,
103            context: 4,
104            metadata: 5,
105            parity: 6,
106        };
107        store.append_quins(&[q]).unwrap();
108        assert_eq!(store.count(), 1);
109        let listed = store.list_recent(10).unwrap();
110        assert_eq!(listed.len(), 1);
111        assert_eq!(listed[0].subject, 1);
112    }
113}