composefs_storage/
lib.rs

1//! Read-only access to containers-storage overlay driver.
2//!
3//! This library provides efficient, capability-based access to container image
4//! storage using the overlay driver. All file operations are performed using
5//! file descriptor-relative operations via cap-std, providing security against
6//! path traversal attacks and TOCTOU race conditions.
7//!
8//! # Overview
9//!
10//! The library is designed to access containers-storage (overlay driver) without
11//! requiring tar serialization. Instead, it provides direct file descriptor access
12//! to layer content, enabling zero-copy operations.
13//!
14//! # Key Features
15//!
16//! - **Capability-based security**: All file access via `cap_std::fs::Dir` handles
17//! - **Zero-copy access**: File descriptors instead of data copies
18//! - **Safe by design**: No path traversal vulnerabilities
19//! - **Tar-split integration**: Bit-for-bit identical TAR reconstruction
20//! - **OCI compatibility**: Uses oci-spec for standard image formats
21//!
22//! # Example
23//!
24//! ```no_run
25//! use composefs_storage::Storage;
26//!
27//! // Discover storage from default locations
28//! let storage = Storage::discover()?;
29//!
30//! // Or open storage at a specific path
31//! let storage = Storage::open("/var/lib/containers/storage")?;
32//!
33//! // List images
34//! for image in storage.list_images()? {
35//!     println!("Image: {}", image.id());
36//! }
37//! # Ok::<(), composefs_storage::StorageError>(())
38//! ```
39//!
40//! # Architecture
41//!
42//! The library uses cap-std for all file operations:
43//! - `Storage` holds a `Dir` handle to the storage root
44//! - All file access is relative to `Dir` handles
45//! - No absolute paths are constructed during operations
46//! - SQLite database accessed via fd-relative path
47
48// Core storage access
49pub mod config;
50pub mod error;
51pub mod image;
52pub mod layer;
53pub mod storage;
54pub mod tar_split;
55
56// User namespace support for rootless access
57pub mod userns;
58#[cfg(feature = "userns-helper")]
59pub mod userns_helper;
60
61// Re-export commonly used types
62pub use config::{AdditionalLayerStore, StorageConfig};
63pub use error::{Result, StorageError};
64pub use image::Image;
65pub use layer::Layer;
66pub use storage::{LayerMetadata, Storage};
67pub use tar_split::{TarHeader, TarSplitFdStream, TarSplitItem};
68pub use userns::can_bypass_file_permissions;
69#[cfg(feature = "userns-helper")]
70pub use userns_helper::{
71    GetImageResult, HelperError, ImageInfo, ProxiedLayerStream, ProxiedTarSplitItem, StorageProxy,
72    init_if_helper,
73};
74
75// Re-export OCI spec types for convenience
76pub use oci_spec::image::{Descriptor, ImageConfiguration, ImageManifest};
composefs_storage/lib.rs

composefs_storage/
lib.rs
