composefs-storage 0.4.0

Read-only access to containers-storage (overlay driver)
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

//! Read-only access to containers-storage overlay driver.
//!
//! This library provides efficient, capability-based access to container image
//! storage using the overlay driver. All file operations are performed using
//! file descriptor-relative operations via cap-std, providing security against
//! path traversal attacks and TOCTOU race conditions.
//!
//! # Overview
//!
//! The library is designed to access containers-storage (overlay driver) without
//! requiring tar serialization. Instead, it provides direct file descriptor access
//! to layer content, enabling zero-copy operations.
//!
//! # Key Features
//!
//! - **Capability-based security**: All file access via `cap_std::fs::Dir` handles
//! - **Zero-copy access**: File descriptors instead of data copies
//! - **Safe by design**: No path traversal vulnerabilities
//! - **Tar-split integration**: Bit-for-bit identical TAR reconstruction
//! - **OCI compatibility**: Uses oci-spec for standard image formats
//!
//! # Example
//!
//! ```no_run
//! use composefs_storage::Storage;
//!
//! // Discover storage from default locations
//! let storage = Storage::discover()?;
//!
//! // Or open storage at a specific path
//! let storage = Storage::open("/var/lib/containers/storage")?;
//!
//! // List images
//! for image in storage.list_images()? {
//!     println!("Image: {}", image.id());
//! }
//! # Ok::<(), composefs_storage::StorageError>(())
//! ```
//!
//! # Architecture
//!
//! The library uses cap-std for all file operations:
//! - `Storage` holds a `Dir` handle to the storage root
//! - All file access is relative to `Dir` handles
//! - No absolute paths are constructed during operations
//! - SQLite database accessed via fd-relative path

// Core storage access
pub mod config;
pub mod error;
pub mod image;
pub mod layer;
pub mod storage;
pub mod tar_split;

// User namespace support for rootless access
pub mod userns;
#[cfg(feature = "userns-helper")]
pub mod userns_helper;

// Re-export commonly used types
pub use config::{AdditionalLayerStore, StorageConfig};
pub use error::{Result, StorageError};
pub use image::Image;
pub use layer::Layer;
pub use storage::{LayerMetadata, Storage};
pub use tar_split::{TarHeader, TarSplitFdStream, TarSplitItem};
pub use userns::can_bypass_file_permissions;
#[cfg(feature = "userns-helper")]
pub use userns_helper::{
    GetImageResult, HelperError, ImageInfo, ProxiedLayerStream, ProxiedTarSplitItem, StorageProxy,
    init_if_helper,
};

// Re-export OCI spec types for convenience
pub use oci_spec::image::{Descriptor, ImageConfiguration, ImageManifest};