ic_backup/ops/persistence/download_journal/
mod.rs

1//! Locked durable local lifecycle updates and verified artifact publication.
2
3#[cfg(unix)]
4mod ic_snapshot_artifact;
5mod integrity;
6mod local_restore_source;
7mod manifest;
8#[cfg(unix)]
9pub use ic_snapshot_artifact::{
10    IcSnapshotArtifactError, IcSnapshotArtifactWriter, IcSnapshotDataUploadPreparationError,
11    IcSnapshotUploadArtifactError,
12};
13pub use integrity::DownloadIntegrityError;
14pub use local_restore_source::LocalRestoreSourceError;
15pub use manifest::{DownloadManifestError, read_download_manifest};
16
17use super::json::{check_json_size, create_encoded, encode_json, write_encoded};
18use super::{
19    BackupLayoutGuard, JournalLock, JournalLockError, PersistenceError, commit_artifact_directory,
20    read_json,
21};
22use crate::{
23    model::{
24        artifacts::canonical_hash,
25        download_journal::{
26            ArtifactStateRecord, ArtifactTransition, DownloadArtifactRequest,
27            DownloadJournalRecord, DownloadJournalRecordError, MAX_DOWNLOAD_JOURNAL_BYTES,
28        },
29    },
30    ops::artifacts::{ArtifactError, checksum_directory},
31};
32use std::{fs, io, path::PathBuf};
33use thiserror::Error;
34
35const JOURNAL_FILE: &str = "download-journal.json";
36
37/// Exclusive local lifecycle access borrowing the stable backup layout guard.
38///
39/// The caller owns backend artifact completeness and fresh remote authority.
40/// These operations never invoke a transport, remove staging or release references.
41#[derive(Debug)]
42pub struct DownloadJournalGuard<'a> {
43    layout: &'a BackupLayoutGuard,
44    _lock: JournalLock,
45    record: DownloadJournalRecord,
46    usable: bool,
47}
48
49impl<'a> DownloadJournalGuard<'a> {
50    /// Exclusively create exact intent and snapshot identities without replacing evidence.
51    ///
52    /// # Errors
53    /// Rejects existing/unsafe journals, locked or replaced layouts and invalid/bounded records.
54    pub fn create(
55        layout: &'a BackupLayoutGuard,
56        intent: &str,
57        artifacts: Vec<DownloadArtifactRequest>,
58    ) -> Result<Self, DownloadJournalError> {
59        layout.check_root()?;
60        let path = layout.root().join(JOURNAL_FILE);
61        let lock = JournalLock::acquire(&path)?;
62        let record = DownloadJournalRecord::new(intent, artifacts)?;
63        let bytes = encode_json(&record, MAX_DOWNLOAD_JOURNAL_BYTES)?;
64        create_encoded(&path, &bytes)?;
65        Ok(Self {
66            layout,
67            _lock: lock,
68            record,
69            usable: true,
70        })
71    }
72
73    /// Open retained bounded v1 evidence under exact caller-supplied intent.
74    ///
75    /// Reads only local journal evidence; it does not reverify artifacts or remote state.
76    /// # Errors
77    /// Rejects missing/unsafe/corrupt journals, intent mismatch and locked/replaced layouts.
78    pub fn open(
79        layout: &'a BackupLayoutGuard,
80        expected_intent: &str,
81    ) -> Result<Self, DownloadJournalError> {
82        layout.check_root()?;
83        let expected = canonical_hash(expected_intent).map_err(DownloadJournalRecordError::from)?;
84        let path = layout.root().join(JOURNAL_FILE);
85        let lock = JournalLock::acquire(&path)?;
86        let record: DownloadJournalRecord = read_json(&path, MAX_DOWNLOAD_JOURNAL_BYTES)?;
87        check_json_size(&record, MAX_DOWNLOAD_JOURNAL_BYTES)?;
88        if record.intent() != expected {
89            return Err(DownloadJournalError::IntentMismatch);
90        }
91        Ok(Self {
92            layout,
93            _lock: lock,
94            record,
95            usable: true,
96        })
97    }
98
99    /// Read retained progress; failed publication requires reopening before further use.
100    ///
101    /// # Errors
102    /// Rejects an indeterminate write outcome or a replaced layout.
103    pub fn record(&self) -> Result<&DownloadJournalRecord, DownloadJournalError> {
104        self.check_usable()?;
105        Ok(&self.record)
106    }
107
108    /// Return the canonical journal location whose sidecar this guard owns.
109    #[must_use]
110    pub fn path(&self) -> PathBuf {
111        self.layout.root().join(JOURNAL_FILE)
112    }
113
114    /// Retain the caller's complete-download attestation for the exact snapshot.
115    ///
116    /// Requires a safe existing staging directory. The caller must already have
117    /// validated complete backend metadata/extent coverage and command quiescence;
118    /// traversability alone does not establish IC transfer completeness.
119    /// # Errors
120    /// Rejects identity/state conflicts, unsafe or missing staging and failed persistence.
121    pub fn record_downloaded(
122        &mut self,
123        canister: &str,
124        snapshot: &str,
125    ) -> Result<(), DownloadJournalError> {
126        let next = self.next(canister, snapshot, ArtifactTransition::Downloaded)?;
127        self.check_artifact_parent()?;
128        let entry = next.artifact(canister, snapshot)?;
129        checksum_directory(&self.layout.root().join(entry.staging_path()))?;
130        self.store(next, write_encoded)
131    }
132
133    /// Verify staged bytes and durably retain their canonical checksum.
134    ///
135    /// # Errors
136    /// Rejects wrong identity/state, unsafe or missing bytes and failed persistence.
137    pub fn verify_artifact(
138        &mut self,
139        canister: &str,
140        snapshot: &str,
141    ) -> Result<(), DownloadJournalError> {
142        self.check_usable()?;
143        let entry = self.record.artifact(canister, snapshot)?;
144        if entry.state() != ArtifactStateRecord::Downloaded {
145            return Err(DownloadJournalRecordError::InvalidStateTransition {
146                from: entry.state(),
147                to: ArtifactStateRecord::ChecksumVerified,
148            }
149            .into());
150        }
151        self.check_artifact_parent()?;
152        let checksum = checksum_directory(&self.layout.root().join(entry.staging_path()))?;
153        let next = self.next(
154            canister,
155            snapshot,
156            ArtifactTransition::ChecksumVerified(checksum),
157        )?;
158        self.store(next, write_encoded)
159    }
160
161    /// Publish exact verified bytes or adopt a matching tree after a lost response.
162    ///
163    /// Leaves staging and retained intent intact on rejection. Durable state does
164    /// not silently trigger fresh artifact verification; that is a distinct action.
165    /// # Errors
166    /// Rejects wrong identity/state, changed bytes, unsafe paths and uncertain publication.
167    pub fn finalize_artifact(
168        &mut self,
169        canister: &str,
170        snapshot: &str,
171    ) -> Result<(), DownloadJournalError> {
172        self.finalize_with(canister, snapshot, write_encoded)
173    }
174
175    fn finalize_with(
176        &mut self,
177        canister: &str,
178        snapshot: &str,
179        write: impl FnOnce(&std::path::Path, &[u8]) -> Result<(), PersistenceError>,
180    ) -> Result<(), DownloadJournalError> {
181        let next = self.next(canister, snapshot, ArtifactTransition::Durable)?;
182        let bytes = encode_json(&next, MAX_DOWNLOAD_JOURNAL_BYTES)?;
183        self.check_artifact_parent()?;
184        let entry = next.artifact(canister, snapshot)?;
185        let checksum = entry
186            .checksum()
187            .ok_or(DownloadJournalRecordError::InvalidChecksumState(
188                ArtifactStateRecord::Durable,
189            ))?;
190        // A failed commit may have published bytes. Stop this guard until its
191        // durable journal is reopened and those exact bytes are reconciled.
192        self.usable = false;
193        commit_artifact_directory(
194            &self.layout.root().join(entry.staging_path()),
195            &self.layout.root().join(entry.artifact_path()),
196            checksum.hash(),
197        )?;
198        self.store_encoded(next, &bytes, write)
199    }
200
201    fn next(
202        &self,
203        canister: &str,
204        snapshot: &str,
205        transition: ArtifactTransition,
206    ) -> Result<DownloadJournalRecord, DownloadJournalError> {
207        self.check_usable()?;
208        let mut next = self.record.clone();
209        next.advance(canister, snapshot, transition)?;
210        Ok(next)
211    }
212
213    fn check_usable(&self) -> Result<(), DownloadJournalError> {
214        if !self.usable {
215            return Err(DownloadJournalError::IndeterminateWrite);
216        }
217        self.layout.check_root()?;
218        Ok(())
219    }
220
221    fn check_artifact_parent(&self) -> Result<(), DownloadJournalError> {
222        let path = self.layout.root().join("artifacts");
223        if !fs::symlink_metadata(&path)?.is_dir() {
224            return Err(DownloadJournalError::UnsafeArtifactParent { path });
225        }
226        Ok(())
227    }
228
229    fn store(
230        &mut self,
231        next: DownloadJournalRecord,
232        write: impl FnOnce(&std::path::Path, &[u8]) -> Result<(), PersistenceError>,
233    ) -> Result<(), DownloadJournalError> {
234        let bytes = encode_json(&next, MAX_DOWNLOAD_JOURNAL_BYTES)?;
235        self.store_encoded(next, &bytes, write)
236    }
237
238    fn store_encoded(
239        &mut self,
240        next: DownloadJournalRecord,
241        bytes: &[u8],
242        write: impl FnOnce(&std::path::Path, &[u8]) -> Result<(), PersistenceError>,
243    ) -> Result<(), DownloadJournalError> {
244        self.layout.check_root()?;
245        let path = self.path();
246        super::json::replace_cached_record(&mut self.record, &mut self.usable, next, || {
247            write(&path, bytes)
248        })?;
249        Ok(())
250    }
251}
252
253/// Typed local journal admission or durable lifecycle failure.
254#[derive(Debug, Error)]
255pub enum DownloadJournalError {
256    /// The caller's exact intent digest differs from retained evidence.
257    #[error("download journal immutable intent mismatch")]
258    IntentMismatch,
259    /// A publication may have completed; reopen and reconcile retained evidence.
260    #[error("download journal outcome is indeterminate; reopen retained evidence")]
261    IndeterminateWrite,
262    /// The fixed artifact parent is not an existing regular directory.
263    #[error("unsafe download artifact parent: {path:?}")]
264    UnsafeArtifactParent {
265        /// Rejected location.
266        path: PathBuf,
267    },
268    /// Model identity, schema or transition admission failed.
269    #[error(transparent)]
270    Record(#[from] DownloadJournalRecordError),
271    /// Local journal or layout exclusion failed.
272    #[error(transparent)]
273    Lock(#[from] JournalLockError),
274    /// Durable local record or artifact publication failed.
275    #[error(transparent)]
276    Persistence(#[from] PersistenceError),
277    /// Secure artifact traversal failed.
278    #[error(transparent)]
279    Artifact(#[from] ArtifactError),
280    /// Local fixture-independent filesystem access failed.
281    #[error(transparent)]
282    Io(#[from] io::Error),
283}
284
285#[cfg(all(test, unix))]
286mod tests;
ic_backup/ops/persistence/download_journal/mod.rs

ic_backup/ops/persistence/download_journal/
mod.rs
