ic_backup/ops/persistence/layout_lifetime/
mod.rs

1//! Stable parent-side layout locks and durable unfinished restore dependencies.
2
3use crate::{
4    model::restore_references::{RestoreReferenceRecord, RestoreReferencesRecord},
5    ops::persistence::{JournalLock, JournalLockError, PersistenceError, read_json},
6};
7use ic_host_artifacts::artifact::Sha256Digest;
8#[cfg(unix)]
9use ic_host_fs::read::open_directory_no_follow;
10use std::{
11    fs::{self, File},
12    io,
13    path::{Path, PathBuf},
14};
15
16const REFERENCES_FILE: &str = "restore-references.json";
17/// Maximum bytes decoded or published for one restore-dependency record.
18pub const MAX_RESTORE_REFERENCE_BYTES: u64 = 1024 * 1024;
19
20/// Exclusive access to an existing resolved backup layout and its dependencies.
21///
22/// All layout writers/removers must use the same parent-side lock. The operator
23/// owns the trusted parent; this guard does not fence arbitrary filesystem writers.
24#[derive(Debug)]
25pub struct BackupLayoutGuard {
26    root: PathBuf,
27    directory: File,
28    _lock: JournalLock,
29}
30
31impl BackupLayoutGuard {
32    /// Resolve and exclusively lock an existing directory without recreating it.
33    ///
34    /// An explicitly selected root symlink resolves once. The lock remains beside
35    /// the resolved directory, including after that directory is removed.
36    ///
37    /// # Errors
38    /// Returns lock contention, unsafe lock entries, missing roots or IO failures.
39    pub fn acquire(root: &Path) -> Result<Self, JournalLockError> {
40        let root = root.canonicalize()?;
41        let parent = root
42            .parent()
43            .ok_or_else(|| io::Error::from(io::ErrorKind::InvalidInput))?;
44        let name = root
45            .file_name()
46            .ok_or_else(|| io::Error::from(io::ErrorKind::InvalidInput))?;
47        let key = Sha256Digest::compute(name.as_encoded_bytes()).to_string();
48        let lock = JournalLock::acquire(&parent.join(format!(".ic-backup-layout-{key}")))?;
49        let directory = open_directory_no_follow(&root)?;
50        Ok(Self {
51            root,
52            directory,
53            _lock: lock,
54        })
55    }
56
57    /// Return the resolved root protected by this guard.
58    #[must_use]
59    pub fn root(&self) -> &Path {
60        &self.root
61    }
62
63    /// Read bounded, validated restore dependencies; absent records mean empty.
64    ///
65    /// # Errors
66    /// Rejects replaced layouts, unsafe entries, invalid records and IO failures.
67    pub fn restore_references(&self) -> Result<RestoreReferencesRecord, PersistenceError> {
68        self.check_root()?;
69        let path = self.root.join(REFERENCES_FILE);
70        match fs::symlink_metadata(&path) {
71            Err(error) if error.kind() == io::ErrorKind::NotFound => {
72                return Ok(RestoreReferencesRecord::empty());
73            }
74            Err(error) => return Err(error.into()),
75            Ok(metadata) if !metadata.is_file() => {
76                return Err(PersistenceError::InvalidRestoreReferences { path });
77            }
78            Ok(_) => {}
79        }
80        read_json(&path, MAX_RESTORE_REFERENCE_BYTES)
81    }
82
83    /// Report retained dependencies even if their external journals are missing.
84    ///
85    /// # Errors
86    /// Returns the same conservative read failures as [`Self::restore_references`].
87    pub fn has_restore_references(&self) -> Result<bool, PersistenceError> {
88        Ok(!self.restore_references()?.is_empty())
89    }
90
91    /// Durably retain exact immutable restore intent before publishing its journal.
92    ///
93    /// Resolve the existing journal parent once; the journal itself may be absent.
94    /// This binds local custody only and does not establish restore authority.
95    /// Release requires the separate terminal/custody provider boundary.
96    ///
97    /// # Errors
98    /// Rejects conflicting intent, invalid locations, unsafe records, limits and IO failures.
99    pub fn retain_restore(
100        &self,
101        journal: &Path,
102        authority: &str,
103    ) -> Result<RestoreReferenceRecord, PersistenceError> {
104        self.retain_with(journal, authority, super::json::write_encoded)
105    }
106
107    fn retain_with(
108        &self,
109        journal: &Path,
110        authority: &str,
111        write: impl FnOnce(&Path, &[u8]) -> Result<(), PersistenceError>,
112    ) -> Result<RestoreReferenceRecord, PersistenceError> {
113        let mut references = self.restore_references()?;
114        let reference = RestoreReferenceRecord::new(journal_identity(journal)?, authority)?;
115        let path = self.root.join(REFERENCES_FILE);
116        if references.retain(reference.clone())? {
117            let bytes = super::json::encode_json(&references, MAX_RESTORE_REFERENCE_BYTES)?;
118            write(&path, &bytes)?;
119        } else {
120            // Complete durability after a rename whose response was lost.
121            sync_reference(&path)?;
122            self.directory.sync_all()?;
123        }
124        Ok(reference)
125    }
126
127    pub(super) fn sync_references(&self) -> Result<(), PersistenceError> {
128        self.check_root()?;
129        let path = self.root.join(REFERENCES_FILE);
130        match fs::symlink_metadata(&path) {
131            Ok(_) => sync_reference(&path)?,
132            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
133            Err(error) => return Err(error.into()),
134        }
135        self.directory.sync_all()?;
136        Ok(())
137    }
138
139    pub(super) fn check_root(&self) -> Result<(), PersistenceError> {
140        match ic_host_fs::durable::admit_directory(&self.root, &self.directory) {
141            Ok(()) => Ok(()),
142            Err(error) if error.kind() == io::ErrorKind::InvalidInput => {
143                Err(PersistenceError::LayoutChanged {
144                    path: self.root.clone(),
145                })
146            }
147            Err(error) => Err(error.into()),
148        }
149    }
150}
151
152#[cfg(not(unix))]
153fn open_directory_no_follow(_path: &Path) -> io::Result<File> {
154    Err(io::Error::from(io::ErrorKind::Unsupported))
155}
156
157pub(super) fn journal_identity(path: &Path) -> Result<PathBuf, PersistenceError> {
158    let name = path
159        .file_name()
160        .ok_or_else(|| io::Error::from(io::ErrorKind::InvalidInput))?;
161    let parent = path
162        .parent()
163        .filter(|parent| !parent.as_os_str().is_empty())
164        .unwrap_or_else(|| Path::new("."));
165    let parent = parent.canonicalize()?;
166    if !parent.is_dir() {
167        return Err(io::Error::from(io::ErrorKind::NotADirectory).into());
168    }
169    let journal = parent.join(name);
170    match fs::symlink_metadata(&journal) {
171        Ok(metadata) if !metadata.is_file() => {
172            return Err(PersistenceError::InvalidRestoreReferences { path: journal });
173        }
174        Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error.into()),
175        _ => {}
176    }
177    Ok(journal)
178}
179
180fn sync_reference(path: &Path) -> io::Result<()> {
181    #[cfg(unix)]
182    {
183        use rustix::fs::{FileType, Mode, OFlags, fstat, open};
184        let fd = open(
185            path,
186            OFlags::RDONLY | OFlags::NOFOLLOW | OFlags::NONBLOCK | OFlags::CLOEXEC,
187            Mode::empty(),
188        )
189        .map_err(io::Error::from)?;
190        let metadata = fstat(&fd).map_err(io::Error::from)?;
191        if !FileType::from_raw_mode(metadata.st_mode).is_file() {
192            return Err(io::Error::from(io::ErrorKind::InvalidInput));
193        }
194        File::from(fd).sync_all()
195    }
196    #[cfg(not(unix))]
197    {
198        let _ = path;
199        Err(io::Error::from(io::ErrorKind::Unsupported))
200    }
201}
202
203#[cfg(all(test, unix))]
204mod tests;
ic_backup/ops/persistence/layout_lifetime/mod.rs

ic_backup/ops/persistence/layout_lifetime/
mod.rs
