microsandbox_image/pull.rs
1//! Pull options, policy, and result types.
2
3use std::path::PathBuf;
4
5use serde::{Deserialize, Serialize};
6
7use crate::{config::ImageConfig, digest::Digest};
8
9//--------------------------------------------------------------------------------------------------
10// Types
11//--------------------------------------------------------------------------------------------------
12
13/// Controls when the registry is contacted for manifest freshness.
14#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
15pub enum PullPolicy {
16 /// Use cached layers if complete, pull otherwise.
17 #[default]
18 IfMissing,
19
20 /// Always fetch manifest from registry, even if cached.
21 /// Reuses cached layers whose digests still match.
22 Always,
23
24 /// Never contact registry. Error if image not fully cached locally.
25 Never,
26}
27
28/// Options for [`Registry::pull()`](crate::Registry::pull).
29#[derive(Debug, Clone)]
30pub struct PullOptions {
31 /// Controls when the registry is contacted.
32 pub pull_policy: PullPolicy,
33
34 /// Re-download and re-extract even if all layers are already cached.
35 pub force: bool,
36
37 /// Generate binary sidecar indexes after extraction.
38 pub build_index: bool,
39}
40
41/// Result of a successful image pull.
42pub struct PullResult {
43 /// Extracted layer directories in bottom-to-top order.
44 pub layers: Vec<PathBuf>,
45
46 /// Parsed OCI image configuration.
47 pub config: ImageConfig,
48
49 /// Content-addressable digest of the resolved manifest.
50 pub manifest_digest: Digest,
51
52 /// True if all layers were already cached and no downloads occurred.
53 pub cached: bool,
54}
55
56//--------------------------------------------------------------------------------------------------
57// Trait Implementations
58//--------------------------------------------------------------------------------------------------
59
60impl Default for PullOptions {
61 fn default() -> Self {
62 Self {
63 pull_policy: PullPolicy::default(),
64 force: false,
65 build_index: true,
66 }
67 }
68}