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