microsandbox 0.7.0

`microsandbox` is the core library for the microsandbox project.
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! Backend-neutral snapshot result and operation types.

use serde::Serialize;
use std::path::PathBuf;

/// Result of explicit snapshot verification.
#[derive(Debug, Clone)]
pub struct SnapshotVerifyReport {
    /// Snapshot manifest digest.
    pub digest: String,
    /// Artifact directory.
    pub path: PathBuf,
    /// Upper-layer content verification result.
    pub upper: UpperVerifyStatus,
    /// Composite-checkpoint closure verification result, when this is a full snapshot.
    pub checkpoint: Option<CheckpointVerifyStatus>,
}

/// Verified identity of a composite-checkpoint closure.
#[derive(Debug, Clone)]
pub struct CheckpointVerifyStatus {
    /// SHA-256 identity of the canonical checkpoint root manifest.
    pub root: String,
}

/// Upper-layer content verification result.
#[derive(Debug, Clone)]
pub enum UpperVerifyStatus {
    /// The snapshot intentionally has no persistent payload integrity.
    NotRecorded,
    /// Recorded content integrity matched the computed digest.
    Verified {
        /// Digest algorithm.
        algorithm: String,
        /// Matching digest or Merkle root.
        digest: String,
    },
}

/// Options for installing an archive in a local snapshot group.
#[derive(Debug, Clone, Default)]
pub struct LoadOpts {
    /// Group-store root; defaults to the configured snapshots directory.
    pub dest: Option<PathBuf>,
    /// Explicit base selector for omitted disk layers and RAM objects.
    pub base: Option<String>,
    /// Existing/new destination group, or a freshly generated group when omitted.
    pub group: Option<String>,
    /// Select the imported target even when it is not a fast-forward.
    pub set_head: bool,
}

/// Options for [`super::Snapshot::save`].
#[derive(Debug, Clone, Default)]
pub struct SaveOpts {
    /// Walk parent chain and include each ancestor in the archive.
    pub with_parents: bool,
    /// Include the OCI image artifacts (EROFS layers, VMDK descriptor)
    /// from the global cache so the archive boots offline.
    pub with_image: bool,
    /// Skip zstd compression and write a plain `.tar`. Default: zstd.
    pub plain_tar: bool,
    /// Omit disk layers and RAM objects supplied by this base (name, directory, or archive).
    /// The base must be an exact physical disk prefix; full-snapshot metadata stays complete.
    /// Mutually exclusive with `last_layers` and `with_parents`.
    pub since: Option<String>,
    /// Export the newest N sealed disk layers, requiring an explicit base when loading omissions.
    /// Memory, execution, and device objects remain complete for full snapshots.
    pub last_layers: Option<usize>,
}

/// Outcome of publishing snapshots into a local group or explicitly selecting its head.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct HeadUpdate {
    /// Local group name.
    pub group: String,
    /// Previously selected stable snapshot ID, if the group had a head.
    pub previous: Option<String>,
    /// Stable snapshot ID selected after the operation.
    pub head: String,
    /// Explanation for advancing or retaining the selected head.
    pub reason: HeadUpdateReason,
    /// Whether the selected head changed.
    pub changed: bool,
}

/// Why a snapshot group's head advanced or remained selected.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum HeadUpdateReason {
    /// The first candidate initialized an empty group.
    Initialized,
    /// The candidate is a proven descendant of the current head.
    FastForwarded,
    /// The caller explicitly selected an installed member.
    Selected,
    /// The candidate was already selected, or the caller only read the head.
    Unchanged,
    /// The candidate is not a descendant of the current head.
    Diverged,
    /// Missing history prevents proving that the candidate descends from the head.
    UnknownAncestry,
    /// Supplied archive heads have multiple tips that known ancestry cannot order.
    AmbiguousCandidates,
}