Skip to main content

hyprstream_workers/image/
store_trait.rs

1//! Feature-invariant image-store trait + inventory registration.
2//!
3//! The `ImageStore` trait is the seam between the CRI `ImageHandler` RPC surface
4//! (generated, always compiled) and concrete image backends (`RafsStore` today,
5//! future plain-OCI / stargz / squashfs backends). It mirrors the five CRI image
6//! ops the handler dispatches to.
7//!
8//! A trait object keeps `WorkerService` feature-invariant: it holds
9//! `Option<Arc<dyn ImageStore>>` (always compiled) and the handler dispatches
10//! through it with a single fallback error path. The only `#[cfg(feature)]` is
11//! on the concrete `RafsStore` impl + its `inventory::submit!`, which live in
12//! `image/store.rs` next to the nydus deps they pull.
13//!
14//! **Pluggability:** a new image backend is a new `impl ImageStore` + one
15//! `inventory::submit!{ ImageBackendRegistration }`. Zero changes to
16//! `WorkerService`. Same pattern as `SandboxBackend` / `BackendRegistration`
17//! (`runtime/selection.rs`).
18
19use std::sync::Arc;
20
21use async_trait::async_trait;
22
23use hyprstream_rpc_std::worker_client::{
24    AuthConfig, FilesystemUsage, ImageInfo, ImageStatusResult,
25};
26
27/// The image-store operations the CRI `ImageHandler` RPC surface dispatches to.
28///
29/// `RafsStore` satisfies this structurally (its existing public methods match).
30/// The trait is `Send + Sync` so it can be held as `Arc<dyn ImageStore>` on the
31/// long-lived `WorkerService`.
32#[async_trait]
33pub trait ImageStore: Send + Sync {
34    /// List available images.
35    async fn list_images(&self) -> anyhow::Result<Vec<ImageInfo>>;
36
37    /// Get image details for `image_ref`.
38    async fn image_status(
39        &self,
40        image_ref: &str,
41        verbose: bool,
42    ) -> anyhow::Result<ImageStatusResult>;
43
44    /// Pull `image_ref` from a registry, optionally with `auth`. Returns the
45    /// resolved image id (content address).
46    async fn pull_with_auth(
47        &self,
48        image_ref: &str,
49        auth: Option<&AuthConfig>,
50    ) -> anyhow::Result<String>;
51
52    /// Remove a pulled image.
53    async fn remove_image(&self, image_ref: &str) -> anyhow::Result<()>;
54
55    /// Filesystem usage for the store's backing storage (for CRI `fsInfo`).
56    async fn fs_info(&self) -> anyhow::Result<Vec<FilesystemUsage>>;
57}
58
59/// Inventory-based registration for image backends (mirrors
60/// `BackendRegistration` in `runtime/selection.rs`).
61///
62/// A backend submits one of these next to its `impl ImageStore`; the worker
63/// service startup resolves the highest-priority available registration and
64/// constructs the store. When no backend is compiled in (e.g. a build without
65/// `oci-image`), there is no registration and the slot is `None`.
66#[derive(Clone)]
67pub struct ImageBackendRegistration {
68    /// Backend name (e.g. `"rafs"`). Selectable for explicit `image_backend`
69    /// config; today there is only one per build.
70    pub name: &'static str,
71    /// Construct the store from an `ImageConfig`. Boxed because the config is
72    /// owned by the caller and construction may fail.
73    pub construct: fn(&crate::config::ImageConfig) -> anyhow::Result<Arc<dyn ImageStore>>,
74}
75
76inventory::collect!(ImageBackendRegistration);