oci_unpack/unpacker/
event_handler.rs

1use std::{fmt::Display, path::Path};
2
3/// Handler to receive notifications for events during the unpack process.
4///
5/// All methods are optional.
6#[expect(unused_variables)]
7pub trait EventHandler: Sync + 'static {
8    /// HTTP request to the registry.
9    fn registry_request(&self, url: &str) {}
10
11    /// Registry requires an [authentication token][token].
12    ///
13    /// [token]: https://distribution.github.io/distribution/spec/auth/token/
14    fn registry_auth(&self, url: &str) {}
15
16    /// Start to download the blobs of the image.
17    ///
18    /// `layers` is the number of layers to download.
19    ///
20    /// `bytes` is the size of the data that is going to be downloaded.
21    fn download_start(&self, layers: usize, bytes: usize) {}
22
23    /// Some data (in `bytes`) has been received.
24    ///
25    /// This method is invoked very frequently.
26    fn download_progress_bytes(&self, bytes: usize) {}
27
28    /// Start to unpack a downloaded layer.
29    ///
30    /// `archive_length` is the length, in bytes, of the archive
31    /// containing the layer.
32    fn layer_start(&self, archive_length: u64) {}
33
34    /// A file was extracted from the archive and was written to the disk.
35    ///
36    /// `archive_position` is relative to `archive_length` in
37    /// [`layer_start`][Self::layer_start].
38    /// When `archive_position == archive_length`, the layer is fully
39    /// unpacked.
40    fn layer_progress(&self, archive_position: usize) {}
41
42    /// An entry in the archive's layer is skipped.
43    ///
44    /// For example, if it is an invalid entry type, like a block device.
45    fn layer_entry_skipped(&self, path: &Path, cause: &dyn Display) {}
46
47    /// All layers have been unpacked.
48    fn finished(&self) {}
49
50    #[cfg(feature = "sandbox")]
51    fn sandbox_status(&self, status: landlock::RestrictionStatus) {}
52}
53
54/// [`EventHandler`] instance to ignore all events.
55pub struct NoEventHandler;
56
57impl EventHandler for NoEventHandler {}
oci_unpack/unpacker/event_handler.rs

oci_unpack/unpacker/
event_handler.rs
