ic_backup/ops/persistence/
mod.rs

1//! Durable publication, journal/layout exclusion and retained local dependencies.
2
3mod artifact_commit;
4mod attempt_journal;
5mod command_lifetime_lock;
6mod consistency;
7mod download_journal;
8mod effect_graph;
9mod execution_settlement;
10mod fence_obligation;
11mod file_lock;
12mod inventory;
13mod journal_lock;
14mod json;
15mod layout_lifetime;
16mod operation_plan;
17mod restore_safety;
18
19pub use artifact_commit::{ArtifactCommitOutcome, commit_artifact_directory};
20pub use attempt_journal::{AttemptJournalError, AttemptJournalGuard};
21pub use command_lifetime_lock::{
22    COMMAND_CUSTODY_DESCRIPTOR_ENV, CommandLifetimeLock, CommandLifetimeLockError,
23    CommandQuiescenceGuard,
24};
25pub use consistency::{
26    ConsistencyPersistenceError, create_consistency_requirement, read_consistency_requirement,
27};
28pub use download_journal::{
29    DownloadIntegrityError, DownloadJournalError, DownloadJournalGuard, DownloadManifestError,
30    LocalRestoreArtifactError, LocalRestoreArtifactPublicationError, LocalRestoreArtifactView,
31    LocalRestoreSourceError, read_download_manifest,
32};
33#[cfg(unix)]
34pub use download_journal::{IcSnapshotArtifactError, IcSnapshotArtifactWriter};
35pub use effect_graph::{EffectGraphPersistenceError, create_effect_graph, read_effect_graph};
36pub use execution_settlement::{
37    ExecutionSettlementPersistenceError, create_execution_settlement, read_execution_settlement,
38};
39pub use fence_obligation::{
40    FenceObligationPersistenceError, FenceObligationRequirement, create_fence_obligation,
41    read_fence_obligation,
42};
43pub use inventory::{InventoryError, create_inventory, read_inventory};
44pub use journal_lock::{JournalLock, JournalLockError};
45pub use json::{create_json_durable, read_json, write_json_durable};
46pub use layout_lifetime::{BackupLayoutGuard, MAX_RESTORE_REFERENCE_BYTES};
47pub use operation_plan::{
48    OperationPlanPersistenceError, create_operation_plan, read_operation_plan,
49};
50pub use restore_safety::{
51    RestoreSafetyPersistenceError, create_restore_safety_requirement,
52    read_restore_safety_requirement,
53};
54
55use crate::{model::artifacts::ChecksumError, ops::artifacts::ArtifactError};
56use std::io;
57use thiserror::Error;
58
59/// Typed local persistence failure.
60#[derive(Debug, Error)]
61pub enum PersistenceError {
62    /// An existing layout path no longer denotes the held directory.
63    #[error("backup layout changed while held: {path:?}")]
64    LayoutChanged {
65        /// Resolved layout location.
66        path: std::path::PathBuf,
67    },
68    /// A retained dependency document or journal location has an unsafe entry type.
69    #[error("unsafe restore reference entry: {path:?}")]
70    InvalidRestoreReferences {
71        /// Rejected local path.
72        path: std::path::PathBuf,
73    },
74    /// Restore dependency validation or an immutable retention transition failed.
75    #[error(transparent)]
76    RestoreReference(#[from] crate::model::restore_references::RestoreReferenceError),
77    /// Filesystem IO failed; publication may require local reconciliation.
78    #[error(transparent)]
79    Io(#[from] io::Error),
80    /// JSON encoding or decoding failed.
81    #[error(transparent)]
82    Json(#[from] serde_json::Error),
83    /// A machine record exceeds its caller-selected byte bound.
84    #[error("record exceeds byte limit {limit}")]
85    RecordTooLarge {
86        /// Maximum accepted bytes.
87        limit: u64,
88    },
89    /// Artifact traversal or streaming failed.
90    #[error(transparent)]
91    Artifact(#[from] ArtifactError),
92    /// Verified bytes do not match the expected checksum.
93    #[error(transparent)]
94    Checksum(#[from] ChecksumError),
95    /// Publication requires distinct siblings in one directory.
96    #[error("artifact commit paths must be distinct siblings: {temporary}, {canonical}")]
97    ArtifactCommitPathMismatch {
98        /// Retained staging path.
99        temporary: String,
100        /// Canonical destination.
101        canonical: String,
102    },
103    /// Both staging and canonical trees exist; neither is overwritten.
104    #[error("artifact commit has conflicting paths: {temporary}, {canonical}")]
105    ArtifactCommitPathConflict {
106        /// Retained staging path.
107        temporary: String,
108        /// Existing canonical destination.
109        canonical: String,
110    },
111    /// Neither expected tree exists.
112    #[error("artifact commit is missing both paths: {temporary}, {canonical}")]
113    ArtifactCommitPathMissing {
114        /// Missing staging path.
115        temporary: String,
116        /// Missing canonical destination.
117        canonical: String,
118    },
119    /// Atomic no-replace directory publication is unsupported.
120    #[error("durable artifact publication is unsupported on {platform}")]
121    ArtifactCommitUnsupportedPlatform {
122        /// Host platform name.
123        platform: &'static str,
124    },
125    /// Publication found an unsafe tree entry.
126    #[error("unsupported artifact entry at {path}: {kind}")]
127    UnsupportedArtifactEntry {
128        /// Entry path.
129        path: String,
130        /// Observed entry kind.
131        kind: String,
132    },
133}
ic_backup/ops/persistence/mod.rs

ic_backup/ops/persistence/
mod.rs
