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/// Options for [`Registry::pull()`](crate::Registry::pull).
27#[derive(Debug, Clone, Default)]
28pub struct PullOptions {
29 /// Controls when the registry is contacted.
30 pub pull_policy: PullPolicy,
31
32 /// Re-download blobs and re-materialize rootfs images even if cached.
33 pub force: bool,
34}
35
36/// Result of a successful image pull.
37pub struct PullResult {
38 /// Layer diff_ids in bottom-to-top order.
39 pub layer_diff_ids: Vec<Digest>,
40
41 /// Parsed OCI image configuration.
42 pub config: ImageConfig,
43
44 /// Content-addressable digest of the resolved manifest.
45 pub manifest_digest: Digest,
46
47 /// True if all layers were already cached and no downloads occurred.
48 pub cached: bool,
49}
50
51//--------------------------------------------------------------------------------------------------
52// Trait Implementations
53//--------------------------------------------------------------------------------------------------