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::{
6        JournalLock, JournalLockError, PersistenceError, read_json, write_json_durable,
7    },
8};
9use sha2::{Digest, Sha256};
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 = format!("{:x}", Sha256::digest(name.as_encoded_bytes()));
48        let lock = JournalLock::acquire(&parent.join(format!(".ic-backup-layout-{key}")))?;
49        let directory = open_directory(&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    /// No release operation is exposed until terminal/custody contracts are implemented.
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, write_json_durable)
105    }
106
107    fn retain_with(
108        &self,
109        journal: &Path,
110        authority: &str,
111        write: impl FnOnce(&Path, &RestoreReferencesRecord) -> 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            super::json::check_json_size(&references, MAX_RESTORE_REFERENCE_BYTES)?;
118            write(&path, &references)?;
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 check_root(&self) -> Result<(), PersistenceError> {
128        #[cfg(unix)]
129        {
130            use std::os::unix::fs::MetadataExt;
131            let current = fs::symlink_metadata(&self.root)?;
132            let held = self.directory.metadata()?;
133            if current.is_dir() && current.dev() == held.dev() && current.ino() == held.ino() {
134                return Ok(());
135            }
136        }
137        Err(PersistenceError::LayoutChanged {
138            path: self.root.clone(),
139        })
140    }
141}
142
143fn journal_identity(path: &Path) -> Result<PathBuf, PersistenceError> {
144    let name = path
145        .file_name()
146        .ok_or_else(|| io::Error::from(io::ErrorKind::InvalidInput))?;
147    let parent = path
148        .parent()
149        .filter(|parent| !parent.as_os_str().is_empty())
150        .unwrap_or_else(|| Path::new("."));
151    let parent = parent.canonicalize()?;
152    if !parent.is_dir() {
153        return Err(io::Error::from(io::ErrorKind::NotADirectory).into());
154    }
155    let journal = parent.join(name);
156    match fs::symlink_metadata(&journal) {
157        Ok(metadata) if !metadata.is_file() => {
158            return Err(PersistenceError::InvalidRestoreReferences { path: journal });
159        }
160        Err(error) if error.kind() != io::ErrorKind::NotFound => return Err(error.into()),
161        _ => {}
162    }
163    Ok(journal)
164}
165
166fn open_directory(path: &Path) -> io::Result<File> {
167    #[cfg(unix)]
168    {
169        use rustix::fs::{Mode, OFlags, open};
170        let fd = open(
171            path,
172            OFlags::RDONLY | OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::CLOEXEC,
173            Mode::empty(),
174        )
175        .map_err(|error| io::Error::from_raw_os_error(error.raw_os_error()))?;
176        Ok(File::from(fd))
177    }
178    #[cfg(not(unix))]
179    {
180        let _ = path;
181        Err(io::Error::from(io::ErrorKind::Unsupported))
182    }
183}
184
185fn sync_reference(path: &Path) -> io::Result<()> {
186    #[cfg(unix)]
187    {
188        use rustix::fs::{FileType, Mode, OFlags, fstat, open};
189        let fd = open(
190            path,
191            OFlags::RDONLY | OFlags::NOFOLLOW | OFlags::NONBLOCK | OFlags::CLOEXEC,
192            Mode::empty(),
193        )
194        .map_err(|error| io::Error::from_raw_os_error(error.raw_os_error()))?;
195        let metadata =
196            fstat(&fd).map_err(|error| io::Error::from_raw_os_error(error.raw_os_error()))?;
197        if !FileType::from_raw_mode(metadata.st_mode).is_file() {
198            return Err(io::Error::from(io::ErrorKind::InvalidInput));
199        }
200        File::from(fd).sync_all()
201    }
202    #[cfg(not(unix))]
203    {
204        let _ = path;
205        Err(io::Error::from(io::ErrorKind::Unsupported))
206    }
207}
208
209#[cfg(all(test, unix))]
210mod tests;
ic_backup/ops/persistence/layout_lifetime/mod.rs

ic_backup/ops/persistence/layout_lifetime/
mod.rs
