oci_unpack/lib.rs
1//! This crate implements the basic support to download and unpack
2//! [OCI images](https://github.com/opencontainers/image-spec) stored
3//! in a [container registry](https://distribution.github.io/distribution/).
4//!
5//! It is not expected to support every feature in the OCI specifications. Instead,
6//! the goal is to implement all features used in the most common images.
7//!
8//! # Usage
9//!
10//! The first step for unpacking an OCI image is to get a [reference][Reference]
11//! instance to describe its location:
12//!
13//! ```
14//! # use oci_unpack::*;
15//! let reference = Reference::try_from("debian:stable").unwrap();
16//! ```
17//!
18//! The string is parsed following the same rules as the `docker pull` command,
19//! as described in the [`Reference`] documentation.
20//!
21//! Then, an [`Unpacker`] instance is created to configure how to download and
22//! unpack the referenced image.
23//!
24//! ```
25//! # use oci_unpack::*;
26//! # fn f(reference: Reference) {
27//! Unpacker::new(reference).unpack("/tmp/image").unwrap();
28//! # }
29//! ```
30//!
31//! An instance of [`EventHandler`] can be used to receive notifications during
32//! the download/unpack process. The file `examples/unpack.rs` in the repository
33//! has a full implementation of a handler.
34//!
35//! # Sandbox
36//!
37//! Before creating any file in the target directory, [`Unpacker::unpack`] tries
38//! to create a sandbox with [Landlock](https://landlock.io/), so the process will
39//! be able to create files only beneath the target directory.
40//!
41//! Errors on creating the sandbox can be ignored by setting [`Unpacker::require_sandbox`]
42//! to `false`.
43//!
44//! The sandbox is only available if the crate is built with the `sandbox` feature, which
45//! is enabled by default.
46//!
47//! # Zstd Compression
48//!
49//! The `zstd` feature (enabled by default) is required to support images compressed with zstd.
50
51mod digest;
52mod fs;
53mod http;
54mod manifests;
55mod reference;
56mod unpacker;
57
58pub use digest::{Digest, DigestAlgorithm};
59pub use reference::{MediaType, Reference, Repository};
60pub use unpacker::{EventHandler, NoEventHandler, Unpacker};
61
62/// Errors from the functions in the public API.
63pub mod errors {
64 pub use super::digest::DigestError;
65 pub use super::reference::ParseError;
66 pub use super::unpacker::UnpackError;
67}