microsandbox_image/
pull.rs

1//! Pull options, policy, and result types.
2
3use serde::{Deserialize, Serialize};
4
5use crate::{config::ImageConfig, digest::Digest};
6
7//--------------------------------------------------------------------------------------------------
8// Types
9//--------------------------------------------------------------------------------------------------
10
11/// Controls when the registry is contacted for manifest freshness.
12#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
13pub enum PullPolicy {
14    /// Use cached layers if complete, pull otherwise.
15    #[default]
16    IfMissing,
17
18    /// Always fetch manifest from registry, even if cached.
19    /// Reuses cached layers whose digests still match.
20    Always,
21
22    /// Never contact registry. Error if image not fully cached locally.
23    Never,
24}
25
26/// Filesystem representations produced by an image pull.
27#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(rename_all = "kebab-case")]
29pub enum RootfsMaterialization {
30    /// Produce the stitched EROFS, fsmeta and VMDK representation.
31    #[default]
32    Layered,
33
34    /// Produce a reusable flat ext4 rootfs without layered-only artifacts.
35    Flat,
36
37    /// Produce both layered and flat rootfs representations from one layer stage.
38    All,
39}
40
41/// Options for [`Registry::pull()`](crate::Registry::pull).
42#[derive(Debug, Clone, Default)]
43pub struct PullOptions {
44    /// Controls when the registry is contacted.
45    pub pull_policy: PullPolicy,
46
47    /// Re-download blobs and re-materialize rootfs images even if cached.
48    pub force: bool,
49
50    /// Filesystem representations to prepare. Defaults to [`RootfsMaterialization::Layered`].
51    pub materialization: RootfsMaterialization,
52}
53
54/// Result of a successful image pull.
55pub struct PullResult {
56    /// Layer diff_ids in bottom-to-top order.
57    pub layer_diff_ids: Vec<Digest>,
58
59    /// Parsed OCI image configuration.
60    pub config: ImageConfig,
61
62    /// Content-addressable digest of the resolved manifest.
63    pub manifest_digest: Digest,
64
65    /// True if all layers were already cached and no downloads occurred.
66    pub cached: bool,
67}
68
69//--------------------------------------------------------------------------------------------------
70// Methods
71//--------------------------------------------------------------------------------------------------
72
73impl RootfsMaterialization {
74    /// Whether the pull must produce the stitched layered representation.
75    pub const fn includes_layered(self) -> bool {
76        matches!(self, Self::Layered | Self::All)
77    }
78
79    /// Whether the pull must produce a flat ext4 representation.
80    pub const fn includes_flat(self) -> bool {
81        matches!(self, Self::Flat | Self::All)
82    }
83}
84
85//--------------------------------------------------------------------------------------------------
86// Trait Implementations
87//--------------------------------------------------------------------------------------------------
microsandbox_image/pull.rs

microsandbox_image/
pull.rs
