Skip to main content

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};