microsandbox-image 0.3.13

OCI image pulling, layer extraction, and caching for microsandbox.
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

//! Pull progress reporting.

use std::sync::Arc;

use tokio::sync::mpsc;

//--------------------------------------------------------------------------------------------------
// Constants
//--------------------------------------------------------------------------------------------------

/// Default channel capacity.
const DEFAULT_PROGRESS_CHANNEL_CAPACITY: usize = 256;

//--------------------------------------------------------------------------------------------------
// Types
//--------------------------------------------------------------------------------------------------

/// Progress events emitted during image pull and layer extraction.
#[derive(Debug, Clone)]
pub enum PullProgress {
    /// Resolving the image reference.
    Resolving {
        /// The image reference being resolved.
        reference: Arc<str>,
    },

    /// Manifest parsed. Layer count and total sizes now known.
    Resolved {
        /// The image reference.
        reference: Arc<str>,
        /// Resolved manifest digest.
        manifest_digest: Arc<str>,
        /// Number of layers.
        layer_count: usize,
        /// Sum of compressed layer sizes. `None` if manifest omits sizes.
        total_download_bytes: Option<u64>,
    },

    /// Byte-level download progress for a single layer.
    LayerDownloadProgress {
        /// Layer index (0-based).
        layer_index: usize,
        /// Layer digest.
        digest: Arc<str>,
        /// Bytes downloaded so far.
        downloaded_bytes: u64,
        /// Total bytes (if known).
        total_bytes: Option<u64>,
    },

    /// A single layer download completed and verified.
    LayerDownloadComplete {
        /// Layer index.
        layer_index: usize,
        /// Layer digest.
        digest: Arc<str>,
        /// Total downloaded bytes.
        downloaded_bytes: u64,
    },

    /// Layer extraction started.
    LayerExtractStarted {
        /// Layer index.
        layer_index: usize,
        /// Layer diff ID.
        diff_id: Arc<str>,
    },

    /// Byte-level extraction progress for a single layer.
    /// Tracks compressed bytes read from the layer tarball.
    LayerExtractProgress {
        /// Layer index (0-based).
        layer_index: usize,
        /// Compressed bytes read so far.
        bytes_read: u64,
        /// Total compressed file size.
        total_bytes: u64,
    },

    /// Layer extraction completed.
    LayerExtractComplete {
        /// Layer index.
        layer_index: usize,
        /// Layer diff ID.
        diff_id: Arc<str>,
    },

    /// Sidecar index generation started for a layer.
    LayerIndexStarted {
        /// Layer index.
        layer_index: usize,
    },

    /// Sidecar index generation completed for a layer.
    LayerIndexComplete {
        /// Layer index.
        layer_index: usize,
    },

    /// Entire image pull completed.
    Complete {
        /// The image reference.
        reference: Arc<str>,
        /// Number of layers.
        layer_count: usize,
    },
}

/// Receiver for progress events.
pub struct PullProgressHandle {
    rx: mpsc::Receiver<PullProgress>,
}

/// Emits progress events. Uses `try_send` — never blocks downloads.
#[derive(Clone)]
pub struct PullProgressSender {
    tx: mpsc::Sender<PullProgress>,
}

//--------------------------------------------------------------------------------------------------
// Methods
//--------------------------------------------------------------------------------------------------

impl PullProgressHandle {
    /// Receive the next event. Returns `None` when the pull completes.
    pub async fn recv(&mut self) -> Option<PullProgress> {
        self.rx.recv().await
    }

    /// Convert into the underlying receiver for use with `tokio::select!`.
    pub fn into_receiver(self) -> mpsc::Receiver<PullProgress> {
        self.rx
    }
}

impl PullProgressSender {
    /// Emit a progress event. Silently discards if receiver is full or dropped.
    pub fn send(&self, event: PullProgress) {
        let _ = self.tx.try_send(event);
    }
}

//--------------------------------------------------------------------------------------------------
// Functions
//--------------------------------------------------------------------------------------------------

/// Create a progress channel pair.
pub fn progress_channel() -> (PullProgressHandle, PullProgressSender) {
    let (tx, rx) = mpsc::channel(DEFAULT_PROGRESS_CHANNEL_CAPACITY);
    (PullProgressHandle { rx }, PullProgressSender { tx })
}