Skip to main content

hoike_core/
storage.rs

1//! Process exclusion for state directories (audit remediation F04).
2//!
3//! One writer per state directory is a structural rule of the anti-rollback
4//! store: high-water marks, manifest digests, and committed generation
5//! snapshots must advance as one coherent unit. In-process mutexes cannot
6//! fence a second process, so every mutating surface (`serve`, `init-state`,
7//! offline `import`) holds an OS advisory exclusive lock on `.writer.lock`
8//! inside the state directory for its full lifetime.
9//!
10//! The lock file is never unlinked: removing a live lock inode would let a
11//! second writer create a fresh, unlocked inode and bypass exclusion. The
12//! file's presence is not the lock — the kernel-held `flock` is.
13
14use std::fs::{File, OpenOptions};
15use std::path::{Path, PathBuf};
16
17use crate::error::{CoreError, Result};
18
19/// Name of the advisory writer lock file inside the state directory.
20/// `StateStore::initialize` ignores exactly this one file when checking that
21/// a new directory is empty; every other entry is recovery material.
22pub const WRITER_LOCK_FILE: &str = ".writer.lock";
23/// An exclusive, non-blocking OS lock on a state directory.
24///
25/// The guard owns the open lock file; dropping it closes the descriptor and
26/// releases the kernel lock. It also records the canonical state directory so
27/// `ResponderState::load` can verify that the guard it retains really protects
28/// the directory the configuration names. Cloning the enclosing `Arc` (as the
29/// responder and every detached writer task does) keeps the lock held; only
30/// the final drop releases it.
31pub struct StateDirectoryLock {
32    /// The open lock file. Never read or written: owning it is what holds the
33    /// kernel lock, and dropping it is what releases exclusion.
34    #[allow(dead_code)]
35    file: File,
36    state_dir: PathBuf,
37}
38
39impl StateDirectoryLock {
40    /// Acquire the exclusive writer lock on `state_dir`, creating the
41    /// directory and lock file if needed. Fails immediately (never blocks)
42    /// when another process holds the lock.
43    pub fn acquire(state_dir: &Path) -> Result<Self> {
44        std::fs::create_dir_all(state_dir).map_err(|e| {
45            CoreError::StateLock(format!(
46                "failed to create state directory {}: {e}",
47                state_dir.display()
48            ))
49        })?;
50        let canonical = std::fs::canonicalize(state_dir).map_err(|e| {
51            CoreError::StateLock(format!(
52                "failed to resolve state directory {}: {e}",
53                state_dir.display()
54            ))
55        })?;
56        let lock_path = canonical.join(WRITER_LOCK_FILE);
57        let file = OpenOptions::new()
58            .read(true)
59            .write(true)
60            .create(true)
61            .truncate(false)
62            .open(&lock_path)
63            .map_err(|e| {
64                CoreError::StateLock(format!(
65                    "failed to open writer lock {}: {e}",
66                    lock_path.display()
67                ))
68            })?;
69        lock_exclusive(&file, &lock_path)?;
70        Ok(Self {
71            file,
72            state_dir: canonical,
73        })
74    }
75
76    /// The canonical state directory protected by this guard.
77    pub fn state_dir(&self) -> &Path {
78        &self.state_dir
79    }
80}
81
82#[cfg(unix)]
83fn lock_exclusive(file: &File, lock_path: &Path) -> Result<()> {
84    use std::os::fd::AsFd;
85    match rustix::fs::flock(
86        file.as_fd(),
87        rustix::fs::FlockOperation::NonBlockingLockExclusive,
88    ) {
89        Ok(()) => Ok(()),
90        Err(e) if e == rustix::io::Errno::AGAIN => Err(CoreError::StateLock(format!(
91            "another writer process holds the state directory lock {} — one writer per \
92             state directory; stop the other process before restarting",
93            lock_path.display()
94        ))),
95        Err(e) => Err(CoreError::StateLock(format!(
96            "failed to lock {}: {e}",
97            lock_path.display()
98        ))),
99    }
100}
101
102#[cfg(not(unix))]
103fn lock_exclusive(_file: &File, lock_path: &Path) -> Result<()> {
104    let _ = lock_path;
105    Err(CoreError::StateLock(
106        "writer exclusion is only implemented for Unix flock targets".into(),
107    ))
108}
109
110/// Durable, atomic replacement of `path` with `bytes` (design §S5).
111///
112/// The single consolidated publication primitive for state descriptors,
113/// immutable generation snapshots, and configured bundle paths: write a
114/// fresh temporary file in the destination directory, fsync it, rename it
115/// over the target, then fsync the directory so the rename itself is
116/// durable. Readers see either the complete old or the complete new bytes.
117///
118/// A failure before the rename leaves the previous contents untouched (the
119/// temporary file is removed). A directory-fsync failure *after* the rename
120/// is reported as [`CoreError::DurabilityUncertain`]: the replacement may
121/// or may not survive a crash, and callers must neither claim rollback nor
122/// completion.
123pub fn write_atomic(path: &Path, bytes: &[u8]) -> Result<()> {
124    use std::io::Write;
125    use std::sync::atomic::{AtomicU64, Ordering};
126    static COUNTER: AtomicU64 = AtomicU64::new(0);
127
128    let parent = path
129        .parent()
130        .filter(|p| !p.as_os_str().is_empty())
131        .unwrap_or(Path::new("."));
132    std::fs::create_dir_all(parent).map_err(|e| {
133        CoreError::StateStore(format!("cannot create directory {}: {e}", parent.display()))
134    })?;
135    let tmp = parent.join(format!(
136        ".hoike-{}-{}.tmp",
137        std::process::id(),
138        COUNTER.fetch_add(1, Ordering::Relaxed)
139    ));
140    let result = (|| -> Result<()> {
141        let mut file = std::fs::OpenOptions::new()
142            .write(true)
143            .create_new(true)
144            .open(&tmp)?;
145        file.write_all(bytes)?;
146        file.sync_all()?;
147        #[cfg(test)]
148        if let Some(mode) = fault_injection::check() {
149            return match mode {
150                fault_injection::FaultMode::BeforeRename => Err(CoreError::Io(
151                    std::io::Error::other("injected failure before rename (test)"),
152                )),
153                fault_injection::FaultMode::DirFsyncAfterRename => {
154                    std::fs::rename(&tmp, path)?;
155                    Err(CoreError::DurabilityUncertain {
156                        path: path.to_path_buf(),
157                        reason: "injected directory-fsync failure (test)".into(),
158                    })
159                }
160            };
161        }
162        std::fs::rename(&tmp, path)?;
163        let dir_fsync = std::fs::File::open(parent).and_then(|dir| dir.sync_all());
164        if let Err(e) = dir_fsync {
165            return Err(CoreError::DurabilityUncertain {
166                path: path.to_path_buf(),
167                reason: format!("directory fsync failed after replacing the file: {e}"),
168            });
169        }
170        Ok(())
171    })();
172    if result.is_err() {
173        let _ = std::fs::remove_file(&tmp);
174    }
175    result
176}
177
178/// Test-only fault injection for [`write_atomic`] (audit remediation F05).
179///
180/// Unit tests in the owning modules use this to fail a specific write at a
181/// specific point (before the rename, or at the post-rename directory
182/// fsync). It is a thread-local counter — cargo's parallel test threads
183/// never see each other's configuration — and compiles away entirely in
184/// production builds; it is not a filesystem abstraction.
185#[cfg(test)]
186pub(crate) mod fault_injection {
187    use std::cell::Cell;
188
189    #[derive(Clone, Copy, PartialEq, Eq, Debug)]
190    pub enum FaultMode {
191        /// Fail after the temporary file is written and synced, before the
192        /// rename: the previous file is untouched.
193        BeforeRename,
194        /// Perform the rename, then fail the directory fsync: the outcome
195        /// is indeterminate.
196        DirFsyncAfterRename,
197    }
198
199    thread_local! {
200        static SPEC: Cell<Option<(usize, FaultMode)>> = const { Cell::new(None) };
201        static CALLS: Cell<usize> = const { Cell::new(0) };
202    }
203
204    /// Fail the `fail_at_call`-th (0-based) `write_atomic` call on this
205    /// thread at `mode`, counting from this call.
206    pub fn set(fail_at_call: usize, mode: FaultMode) {
207        SPEC.with(|s| s.set(Some((fail_at_call, mode))));
208        CALLS.with(|c| c.set(0));
209    }
210
211    pub fn clear() {
212        SPEC.with(|s| s.set(None));
213    }
214
215    /// Returns the injected failure mode when the current call is the
216    /// configured one.
217    pub fn check() -> Option<FaultMode> {
218        let call = CALLS.with(|c| {
219            let n = c.get();
220            c.set(n + 1);
221            n
222        });
223        SPEC.with(|s| s.get().filter(|(at, _)| *at == call).map(|(_, mode)| mode))
224    }
225}
226
227#[cfg(test)]
228mod tests {
229    use super::*;
230
231    #[test]
232    fn write_atomic_replaces_durably_and_cleans_up_on_pre_rename_failure() {
233        let dir = tempfile::tempdir().unwrap();
234        let path = dir.path().join("target");
235        write_atomic(&path, b"first").unwrap();
236        write_atomic(&path, b"second").unwrap();
237        assert_eq!(std::fs::read(&path).unwrap(), b"second");
238
239        // A rename onto a directory fails after the temporary file is
240        // written: old contents survive, no temporary is left behind.
241        let blocked = dir.path().join("blocked");
242        std::fs::create_dir(&blocked).unwrap();
243        std::fs::write(blocked.join("previous"), b"old").unwrap();
244        assert!(write_atomic(&blocked, b"new").is_err());
245        assert_eq!(std::fs::read(blocked.join("previous")).unwrap(), b"old");
246        assert!(
247            !std::fs::read_dir(dir.path()).unwrap().any(|e| e
248                .unwrap()
249                .file_name()
250                .to_string_lossy()
251                .ends_with(".tmp"))
252        );
253    }
254
255    #[test]
256    fn write_atomic_reports_post_rename_fsync_failure_as_durability_uncertain() {
257        let dir = tempfile::tempdir().unwrap();
258        let path = dir.path().join("target");
259        write_atomic(&path, b"old").unwrap();
260
261        fault_injection::set(0, fault_injection::FaultMode::DirFsyncAfterRename);
262        let err = write_atomic(&path, b"new").unwrap_err();
263        fault_injection::clear();
264        assert!(
265            matches!(err, CoreError::DurabilityUncertain { .. }),
266            "post-rename directory-fsync failure must be the typed error: {err}"
267        );
268        // The rename itself happened; the outcome is genuinely indeterminate,
269        // and the error must say so instead of claiming nothing changed.
270        assert!(err.to_string().contains("durability uncertain"), "{err}");
271        assert!(
272            !err.to_string().to_lowercase().contains("nothing changed"),
273            "{err}"
274        );
275        assert_eq!(std::fs::read(&path).unwrap(), b"new");
276    }
277}