Skip to main content

qualia_core_db/net/qdnf/replication/
disk_crash.rs

1//! Process-local tempfile crash/recovery (E06.6).
2//!
3//! Commits identity → effect bytes → durable receipt marker as separate files.
4//! A receipt file without complete effect bytes is never a durable receipt.
5//! [`os_process_kill_qualified`] stays false: this is not an OS kill of CORE-03 WAL.
6//! [`disk_backend_crash_injected`] stays false: the tempfile adapter is not a
7//! disk WAL injector.
8//!
9//! Tiny hook: [`FilePairStore::effect_path`] lets [`super::stream`] page the
10//! effect file without loading a second copy of the replica.
11
12use std::fs::{self, OpenOptions};
13use std::io::{Read, Write};
14use std::path::{Path, PathBuf};
15
16use crate::crypto::network::digest::sha384;
17use crate::net::qdnf::errors::QdnfError;
18use crate::net::qdnf::types::StrongDigest;
19
20/// Max effect payload retained on this path. One stream page.
21pub const MAX_EFFECT_BYTES: usize = 4096;
22
23/// Durability class actually achieved on this tempfile adapter.
24#[repr(u8)]
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26pub enum ReceiptClass {
27    Identity = 1,
28    Effect = 2,
29    DurableReceipt = 3,
30}
31
32/// This tempfile adapter is injected. Not an OS process-kill qualifier.
33#[inline]
34pub const fn tempfile_crash_injected() -> bool {
35    true
36}
37
38/// OS process-kill / CORE-03 WAL remaining unproven.
39#[inline]
40pub const fn os_process_kill_qualified() -> bool {
41    false
42}
43
44/// Not CORE-03.13 WAL torn-write. Disk durability is not claimed here.
45#[inline]
46pub const fn disk_backend_crash_injected() -> bool {
47    false
48}
49
50/// Bounded on-disk pairing of identity, effect, and receipt.
51pub struct FilePairStore {
52    dir: PathBuf,
53}
54
55impl FilePairStore {
56    /// Opens the resource.
57    pub fn open(dir: impl AsRef<Path>) -> Result<Self, QdnfError> {
58        let dir = dir.as_ref();
59        fs::create_dir_all(dir).map_err(|_| QdnfError::Incomplete)?;
60        Ok(Self {
61            dir: dir.to_path_buf(),
62        })
63    }
64
65    fn path(&self, name: &str) -> PathBuf {
66        self.dir.join(name)
67    }
68
69    /// Effect file path for caller-paged verification ([`super::stream`]).
70    #[inline]
71    pub fn effect_path(&self) -> PathBuf {
72        self.path("effect")
73    }
74
75    /// Write identity digest first.
76    pub fn write_identity(&self, id: StrongDigest) -> Result<(), QdnfError> {
77        if id == StrongDigest::ZERO {
78            return Err(QdnfError::Malformed);
79        }
80        write_exact(&self.path("identity"), id.as_bytes())
81    }
82
83    /// Write exact effect bytes. Empty or oversize is Malformed/Capacity.
84    pub fn write_effect(&self, bytes: &[u8]) -> Result<StrongDigest, QdnfError> {
85        if bytes.is_empty() {
86            return Err(QdnfError::Malformed);
87        }
88        if bytes.len() > MAX_EFFECT_BYTES {
89            return Err(QdnfError::Capacity);
90        }
91        write_exact(&self.path("effect"), bytes)?;
92        Ok(sha384(bytes))
93    }
94
95    /// Durable receipt marker. Requires a complete effect file whose digest matches.
96    pub fn write_receipt(&self, effect_digest: StrongDigest) -> Result<(), QdnfError> {
97        match self.recover()? {
98            RecoveredPair {
99                receipt_class: ReceiptClass::Effect,
100                effect_digest: Some(got),
101                ..
102            } if got == effect_digest => {
103                write_exact(&self.path("receipt"), effect_digest.as_bytes())
104            }
105            _ => Err(QdnfError::Incomplete),
106        }
107    }
108
109    /// Reconstruct pairing. Truncation/corruption is Conflict or Incomplete.
110    pub fn recover(&self) -> Result<RecoveredPair, QdnfError> {
111        let identity = match read_digest(&self.path("identity")) {
112            Ok(id) => id,
113            Err(QdnfError::Incomplete) => {
114                return Ok(RecoveredPair {
115                    identity: None,
116                    effect_digest: None,
117                    receipt_class: ReceiptClass::Identity,
118                });
119            }
120            Err(e) => return Err(e),
121        };
122        let effect = match read_bounded(&self.path("effect"), MAX_EFFECT_BYTES) {
123            Ok(bytes) => Some(sha384(&bytes)),
124            Err(QdnfError::Incomplete) => None,
125            Err(e) => return Err(e),
126        };
127        let receipt = match read_digest(&self.path("receipt")) {
128            Ok(d) => Some(d),
129            Err(QdnfError::Incomplete) => None,
130            Err(e) => return Err(e),
131        };
132        let receipt_class = match (effect, receipt) {
133            (Some(ed), Some(rd)) if ed == rd => ReceiptClass::DurableReceipt,
134            (Some(_), Some(_)) => return Err(QdnfError::Conflict),
135            (None, Some(_)) => return Err(QdnfError::Incomplete),
136            (Some(_), None) => ReceiptClass::Effect,
137            (None, None) => ReceiptClass::Identity,
138        };
139        Ok(RecoveredPair {
140            identity: Some(identity),
141            effect_digest: effect,
142            receipt_class,
143        })
144    }
145
146    /// Truncate the effect file to simulate a torn write.
147    pub fn truncate_effect(&self, len: u64) -> Result<(), QdnfError> {
148        let f = OpenOptions::new()
149            .write(true)
150            .open(self.path("effect"))
151            .map_err(|_| QdnfError::Incomplete)?;
152        f.set_len(len).map_err(|_| QdnfError::Incomplete)
153    }
154}
155
156#[derive(Clone, Copy, Debug, PartialEq, Eq)]
157pub struct RecoveredPair {
158    pub identity: Option<StrongDigest>,
159    pub effect_digest: Option<StrongDigest>,
160    pub receipt_class: ReceiptClass,
161}
162
163fn write_exact(path: &Path, bytes: &[u8]) -> Result<(), QdnfError> {
164    let mut f = OpenOptions::new()
165        .create(true)
166        .write(true)
167        .truncate(true)
168        .open(path)
169        .map_err(|_| QdnfError::Incomplete)?;
170    f.write_all(bytes).map_err(|_| QdnfError::Incomplete)?;
171    f.sync_all().map_err(|_| QdnfError::Incomplete)
172}
173
174fn read_bounded(path: &Path, max: usize) -> Result<Vec<u8>, QdnfError> {
175    let meta = fs::metadata(path).map_err(|_| QdnfError::Incomplete)?;
176    let len = usize::try_from(meta.len()).map_err(|_| QdnfError::Range)?;
177    if len == 0 {
178        return Err(QdnfError::Incomplete);
179    }
180    if len > max {
181        return Err(QdnfError::Conflict);
182    }
183    let mut buf = vec![0u8; len];
184    let mut f = fs::File::open(path).map_err(|_| QdnfError::Incomplete)?;
185    f.read_exact(&mut buf).map_err(|_| QdnfError::Incomplete)?;
186    Ok(buf)
187}
188
189fn read_digest(path: &Path) -> Result<StrongDigest, QdnfError> {
190    let bytes = read_bounded(path, 48)?;
191    if bytes.len() != 48 {
192        return Err(QdnfError::Conflict);
193    }
194    let mut d = StrongDigest::ZERO;
195    d.0.copy_from_slice(&bytes);
196    if d == StrongDigest::ZERO {
197        return Err(QdnfError::Malformed);
198    }
199    Ok(d)
200}
201
202#[cfg(test)]
203mod tests {
204    use super::*;
205    use crate::net::qdnf::replication::stream::{hash_file_pages, PageWindow, PagedFile};
206    use tempfile::TempDir;
207
208    fn id() -> StrongDigest {
209        sha384(b"op-identity")
210    }
211
212    #[test]
213    fn tempfile_torn_write_recovers_consistent_pair() {
214        let dir = TempDir::new().unwrap();
215        let store = FilePairStore::open(dir.path()).unwrap();
216        store.write_identity(id()).unwrap();
217        let digest = store.write_effect(b"graph-effect-bytes").unwrap();
218        store.write_receipt(digest).unwrap();
219        let ok = store.recover().unwrap();
220        assert_eq!(ok.receipt_class, ReceiptClass::DurableReceipt);
221        assert_eq!(ok.effect_digest, Some(digest));
222        store.truncate_effect(4).unwrap();
223        let err = store.recover().unwrap_err();
224        assert!(err == QdnfError::Incomplete || err == QdnfError::Conflict);
225        assert!(tempfile_crash_injected());
226    }
227
228    #[test]
229    fn kill_before_receipt_leaves_no_false_durable() {
230        let dir = TempDir::new().unwrap();
231        let store = FilePairStore::open(dir.path()).unwrap();
232        store.write_identity(id()).unwrap();
233        let _ = store.write_effect(b"effect-only").unwrap();
234        let got = store.recover().unwrap();
235        assert_eq!(got.receipt_class, ReceiptClass::Effect);
236        assert_ne!(got.receipt_class, ReceiptClass::DurableReceipt);
237    }
238
239    #[test]
240    fn truncated_volume_is_conflict_or_incomplete() {
241        let dir = TempDir::new().unwrap();
242        let store = FilePairStore::open(dir.path()).unwrap();
243        store.write_identity(id()).unwrap();
244        let digest = store.write_effect(b"full-effect-record").unwrap();
245        store.write_receipt(digest).unwrap();
246        store.truncate_effect(0).unwrap();
247        let err = store.recover().unwrap_err();
248        assert!(err == QdnfError::Incomplete || err == QdnfError::Conflict);
249    }
250
251    #[test]
252    fn os_process_kill_qualified_is_false() {
253        assert!(!os_process_kill_qualified());
254        assert!(tempfile_crash_injected());
255        assert!(!disk_backend_crash_injected());
256    }
257
258    #[test]
259    fn effect_path_pages_without_second_replica_copy() {
260        let dir = TempDir::new().unwrap();
261        let store = FilePairStore::open(dir.path()).unwrap();
262        let bytes = [0x5Au8; 64];
263        let digest = store.write_effect(&bytes).unwrap();
264        let mut file = PagedFile::open(store.effect_path()).unwrap();
265        let mut window = PageWindow::new();
266        let mut page_digests = [StrongDigest::ZERO; 1];
267        let (got, pages) = hash_file_pages(&mut file, &mut window, &mut page_digests).unwrap();
268        assert_eq!(got, digest);
269        assert_eq!(pages, 1);
270        assert!(window.peak_bytes() <= MAX_EFFECT_BYTES);
271        assert!(window.peak_bytes() <= crate::net::qdnf::replication::stream::PAGE_BYTES);
272    }
273}