ic-backup 0.5.0

Host-side snapshot backup and same-release recovery for Internet Computer canisters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! Immutable original restore/source safety retention under both layout guards.

use super::{
    BackupLayoutGuard, JournalLock, JournalLockError, OperationPlanPersistenceError,
    PersistenceError, create_json_durable, read_json, read_operation_plan,
};
use crate::model::{
    artifacts::ArtifactChecksumRecord,
    operation_plan::OperationPlanRecord,
    restore_safety::{
        MAX_RESTORE_SAFETY_REQUIREMENT_BYTES, RestoreSafetyRequirementError,
        RestoreSafetyRequirementRecord,
    },
};
use thiserror::Error;

/// Durably create fixed `restore-safety-requirement.json` without replacement.
///
/// Both exact original plans must already be retained under their layout guards.
/// Artifact completeness, source-reference retention and current application/fence
/// custody remain separately admitted by their owners. This persists declarations.
/// # Errors
/// Rejects changed/missing plans, inappropriate source, excessive bytes or unsafe/existing paths.
pub fn create_restore_safety_requirement(
    layout: &BackupLayoutGuard,
    source_layout: &BackupLayoutGuard,
    plan: &OperationPlanRecord,
    source: &OperationPlanRecord,
    record: &RestoreSafetyRequirementRecord,
) -> Result<(), RestoreSafetyPersistenceError> {
    record.validate_plans(plan, source)?;
    read_operation_plan(layout, &plan.digest())?;
    read_operation_plan(source_layout, &source.digest())?;
    let path = layout.root().join("restore-safety-requirement.json");
    let _lock = JournalLock::acquire(&path)?;
    check_size(record)?;
    create_json_durable(&path, record)?;
    Ok(())
}
/// Read bounded exact original requirement under both unchanged retained plans.
///
/// Lost creation replies reconcile through this read; absence never recreates a
/// requirement, grants fresh source/fence authority or replenishes original attempts.
/// # Errors
/// Rejects missing/unsafe/oversized records, changed plans or exact requirement digest mismatch.
pub fn read_restore_safety_requirement(
    layout: &BackupLayoutGuard,
    source_layout: &BackupLayoutGuard,
    plan: &OperationPlanRecord,
    source: &OperationPlanRecord,
    expected: &ArtifactChecksumRecord,
) -> Result<RestoreSafetyRequirementRecord, RestoreSafetyPersistenceError> {
    read_operation_plan(layout, &plan.digest())?;
    read_operation_plan(source_layout, &source.digest())?;
    let path = layout.root().join("restore-safety-requirement.json");
    let _lock = JournalLock::acquire(&path)?;
    let record: RestoreSafetyRequirementRecord =
        read_json(&path, MAX_RESTORE_SAFETY_REQUIREMENT_BYTES)?;
    check_size(&record)?;
    record.validate_plans(plan, source)?;
    if &record.digest() != expected {
        return Err(RestoreSafetyPersistenceError::DigestMismatch);
    }
    Ok(record)
}
fn check_size(record: &RestoreSafetyRequirementRecord) -> Result<(), PersistenceError> {
    super::json::check_json_size(record, MAX_RESTORE_SAFETY_REQUIREMENT_BYTES)
}
/// Typed original restore/source safety persistence denial.
#[derive(Debug, Error)]
pub enum RestoreSafetyPersistenceError {
    /// Exact original retained requirement differs.
    #[error("restore safety requirement digest mismatch")]
    DigestMismatch,
    /// Original source or restore declarations differ.
    #[error(transparent)]
    Requirement(#[from] RestoreSafetyRequirementError),
    /// An exact original plan is not retained under its unchanged layout.
    #[error(transparent)]
    Plan(#[from] OperationPlanPersistenceError),
    /// Journal exclusion failed.
    #[error(transparent)]
    Lock(#[from] JournalLockError),
    /// Bounded JSON/durable IO failed.
    #[error(transparent)]
    Persistence(#[from] PersistenceError),
}

#[cfg(all(test, unix))]
mod tests;