Skip to main content

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