hyprstream_workers/image/mod.rs
1//! CRI image service implementation with Dragonfly-native blob fetching
2//!
3//! Provides Kubernetes CRI-aligned APIs for managing container images.
4//! Backed by Nydus RAFS for chunk-level CAS deduplication.
5//!
6//! # Architecture
7//!
8//! ```text
9//! The canonical ImageClient contract and client live in `hyprstream-rpc-std`.
10//! │
11//! ├── list_images() → List available images
12//! ├── image_status() → Get image details
13//! ├── pull_image() → Pull from registry (Dragonfly P2P)
14//! └── remove_image() → Remove image
15//! │
16//! └── RafsStore
17//! │
18//! ├── ManifestFetcher (HTTP - manifests only)
19//! ├── nydus-storage (Dragonfly-native blob fetch)
20//! │
21//! ├── blobs/ (layer blobs)
22//! ├── bootstrap/ (RAFS metadata)
23//! ├── cache/ (nydus blob cache)
24//! └── refs/ (tag symlinks)
25//! ```
26//!
27//! # Dragonfly Integration
28//!
29//! When `ImageConfig::dragonfly_peer` is set, all blob fetches route through
30//! the Dragonfly peer for P2P distribution. This happens transparently via
31//! nydus-storage's `blob_redirected_host` configuration.
32
33// The nydus-bound submodules (client/store/rafs_builder/image_fs) require the
34// `oci-image` feature (they pull nydus + fuse-backend-rs). `manifest` (pure
35// HTTP) and `store_trait` (the trait seam) are nydus-free and always compiled —
36// the trait surface stays feature-invariant so `WorkerService` can hold
37// `Option<Arc<dyn ImageStore>>` with no cfg mirror (#646).
38mod manifest;
39// `pub(crate)` so sibling-module tests (e.g. runtime::sandbox_fs, FS-D #365)
40// can synthesize RAFS images. The builder fn stays crate-internal.
41#[cfg(feature = "oci-image")]
42pub(crate) mod rafs_builder;
43// #633 (spine of #508): the universal mountable OCI/RAFS image filesystem
44// service — `ImageFs`, an `FsMount` = OverlayFs(in-process RAFS lower +
45// writable upper). Native-only (the overlay/RAFS FileSystem stack is Linux).
46#[cfg(all(feature = "oci-image", not(target_arch = "wasm32")))]
47mod image_fs;
48// The image-store trait + inventory registration seam — ALWAYS compiled
49// (feature-invariant). Concrete backends (RafsStore under `oci-image`) impl
50// `ImageStore` and `inventory::submit!` an `ImageBackendRegistration`.
51#[cfg(feature = "oci-image")]
52mod store;
53pub mod store_trait;
54// #652 (follow-on to #633/#641): projects `RafsStore`'s on-disk CAS as a
55// 9P/VFS `Mount` — the storage-layer namespace surface, distinct from
56// `ImageFs` (the composed filesystem a guest mounts). Only needs `RafsStore`
57// itself, not the fuse/overlay stack `image_fs` pulls in, but both are gated
58// on `oci-image` since that's what makes `RafsStore` exist at all.
59#[cfg(feature = "oci-image")]
60mod store_mount;
61
62#[cfg(all(feature = "oci-image", not(target_arch = "wasm32")))]
63pub use image_fs::{image_fs_for, image_fs_from_rafs, ImageFs};
64pub use manifest::{ImageReference, ManifestFetcher, ManifestResult, OciManifest};
65#[cfg(feature = "oci-image")]
66pub use store::{GcStats, ImageMetadata, RafsStore};
67#[cfg(feature = "oci-image")]
68pub use store_mount::RafsStoreMount;
69// The trait seam + inventory registration are always available; only the
70// concrete `RafsStore` impl + its `submit!` require `oci-image`.
71pub use store_trait::{ImageBackendRegistration, ImageStore};