Skip to main content

hyprstream_workers/image/
store.rs

1//! RafsStore - Dragonfly-native image storage using nydus-storage
2//!
3//! The on-disk CAS layout (`blobs/`, `bootstrap/`, `cache/`, `refs/`) is
4//! driven via raw `std::fs`/path ops for ingest (`pull`/`gc`/`remove`). The
5//! read path is additionally exposed as a 9P/VFS `Mount` — see
6//! [`super::store_mount::RafsStoreMount`] (#652).
7//!
8//! Uses Nydus RAFS format for efficient image storage with:
9//! - Chunk-level deduplication (across all images)
10//! - Lazy loading (on-demand chunk fetch via Dragonfly P2P)
11//! - ~80% storage savings vs traditional layers
12//!
13//! Architecture:
14//! ```text
15//! ManifestFetcher (HTTP)  →  nydus-storage Registry backend  →  rafs_builder (TarballBuilder)
16//!      │                              │                              │
17//!      └── OCI manifests only         └── Dragonfly P2P for blobs    └── RAFS bootstrap (.meta)
18//! ```
19//!
20//! `pull()` downloads the OCI layer tarballs into the CAS and then converts them
21//! in-process into a RAFS bootstrap (`.meta`) via [`rafs_builder`], so
22//! [`RafsStore::bootstrap_path`] resolves to a real RAFS bootstrap consumable by
23//! an in-process RAFS `FileSystem` (FS-B, #363) or nydusd (FS-B0, #366).
24
25use std::path::{Path, PathBuf};
26use std::sync::Arc;
27
28use sha2::{Digest, Sha256};
29
30use nydus_api::RegistryConfig;
31use nydus_storage::backend::registry::Registry;
32use nydus_storage::backend::{BlobBackend, BlobBufReader};
33
34use crate::config::ImageConfig;
35use crate::error::{Result, WorkerError};
36
37use super::manifest::{AuthConfig, ImageReference, ManifestFetcher, ManifestResult};
38use hyprstream_rpc_std::worker_client::{
39    AuthConfig as GenAuthConfig, FilesystemIdentifier, FilesystemUsage, ImageInfo, ImageSpec,
40    ImageStatusResult,
41};
42
43/// RAFS-backed image store with Dragonfly-native blob fetching
44///
45/// Uses nydus-storage's backend-registry for blob operations, which supports
46/// Dragonfly P2P via the `blob_redirected_host` configuration.
47///
48/// Storage layout:
49/// ```text
50/// images/
51/// ├── blobs/sha256/         # Layer blobs (content-addressed)
52/// ├── bootstrap/            # RAFS metadata (per image)
53/// ├── cache/                # nydus-storage blob cache
54/// └── refs/                 # Tag → digest symlinks
55/// ```
56pub struct RafsStore {
57    /// Directory for layer blobs
58    blobs_dir: PathBuf,
59
60    /// Directory for RAFS bootstrap metadata
61    bootstrap_dir: PathBuf,
62
63    /// Directory for tag references
64    refs_dir: PathBuf,
65
66    /// Cache directory for nydus-storage
67    cache_dir: PathBuf,
68
69    /// Manifest fetcher (HTTP only, no blob handling)
70    manifest_fetcher: Arc<ManifestFetcher>,
71
72    /// Configuration
73    config: ImageConfig,
74}
75
76impl RafsStore {
77    /// Create a new RafsStore with configuration
78    pub fn new(config: ImageConfig) -> Result<Self> {
79        let manifest_fetcher = ManifestFetcher::new().map_err(|e| {
80            WorkerError::RafsError(format!("failed to create manifest fetcher: {e}"))
81        })?;
82
83        Ok(Self {
84            blobs_dir: config.blobs_dir.clone(),
85            bootstrap_dir: config.bootstrap_dir.clone(),
86            refs_dir: config.refs_dir.clone(),
87            cache_dir: config.cache_dir.clone(),
88            manifest_fetcher: Arc::new(manifest_fetcher),
89            config,
90        })
91    }
92
93    /// Pull an image from registry
94    pub async fn pull(&self, image_ref: &str) -> Result<String> {
95        self.pull_with_auth(image_ref, None).await
96    }
97
98    /// Pull an image with authentication
99    pub async fn pull_with_auth(
100        &self,
101        image_ref: &str,
102        auth: Option<&GenAuthConfig>,
103    ) -> Result<String> {
104        tracing::info!(image = %image_ref, "Pulling image");
105
106        // Ensure directories exist
107        self.ensure_dirs().await?;
108
109        // 1. Parse image reference
110        let img_ref =
111            ImageReference::parse(image_ref).map_err(|e| WorkerError::ImageParseFailed {
112                image: image_ref.to_owned(),
113                reason: e.to_string(),
114            })?;
115
116        // Convert CRI auth (GenAuthConfig with String fields) to manifest auth (Option<String> fields)
117        let manifest_auth = auth.map(|a| AuthConfig {
118            username: if a.username.is_empty() {
119                None
120            } else {
121                Some(a.username.clone())
122            },
123            password: if a.password.is_empty() {
124                None
125            } else {
126                Some(a.password.clone())
127            },
128            token: if a.auth.is_empty() {
129                None
130            } else {
131                Some(a.auth.clone())
132            },
133        });
134
135        // 2. Fetch manifest
136        let manifest = self
137            .manifest_fetcher
138            .fetch(&img_ref, manifest_auth.as_ref())
139            .await
140            .map_err(|e| WorkerError::ImagePullFailed {
141                image: image_ref.to_owned(),
142                reason: e.to_string(),
143            })?;
144
145        // 3. Handle multi-platform images - select linux/amd64 by default
146        let manifest = match manifest {
147            ManifestResult::Manifest(m) => m,
148            ManifestResult::Index(idx) => {
149                // Find linux/amd64 platform
150                let platform_manifest = idx
151                    .manifests
152                    .iter()
153                    .find(|m| {
154                        m.platform
155                            .as_ref()
156                            .is_some_and(|p| p.os == "linux" && p.architecture == "amd64")
157                    })
158                    .or_else(|| idx.manifests.first())
159                    .ok_or_else(|| WorkerError::ImagePullFailed {
160                        image: image_ref.to_owned(),
161                        reason: "no suitable platform manifest found".to_owned(),
162                    })?;
163
164                tracing::debug!(
165                    digest = %platform_manifest.digest,
166                    "Selected platform manifest"
167                );
168
169                self.manifest_fetcher
170                    .fetch_platform_manifest(
171                        &img_ref,
172                        &platform_manifest.digest,
173                        manifest_auth.as_ref(),
174                    )
175                    .await
176                    .map_err(|e| WorkerError::ImagePullFailed {
177                        image: image_ref.to_owned(),
178                        reason: e.to_string(),
179                    })?
180            }
181        };
182
183        tracing::debug!(
184            layers = %manifest.layers.len(),
185            config = %manifest.config.digest,
186            "Got manifest"
187        );
188
189        // 4. Download config blob via nydus-storage
190        let config_path = self
191            .blobs_dir
192            .join(digest_to_filename(&manifest.config.digest));
193        if !config_path.exists() {
194            self.download_blob(
195                &img_ref,
196                &manifest.config.digest,
197                &config_path,
198                manifest_auth.as_ref(),
199            )
200            .await?;
201            tracing::debug!(digest = %manifest.config.digest, "Downloaded config");
202        }
203
204        // 5. Download layer blobs via nydus-storage (Dragonfly-native)
205        for layer in &manifest.layers {
206            let layer_path = self.blobs_dir.join(digest_to_filename(&layer.digest));
207            if !layer_path.exists() {
208                tracing::info!(
209                    digest = %layer.digest,
210                    size = %layer.size,
211                    "Downloading layer via nydus-storage"
212                );
213                self.download_blob(&img_ref, &layer.digest, &layer_path, manifest_auth.as_ref())
214                    .await?;
215            } else {
216                tracing::debug!(digest = %layer.digest, "Layer already cached");
217            }
218        }
219
220        // 6. Generate image ID (SHA256 of config)
221        let config_data = tokio::fs::read(&config_path).await?;
222        let image_id = format!("sha256:{}", hex::encode(Sha256::digest(&config_data)));
223
224        // 6b. Build the RAFS bootstrap (.meta) from the pulled OCI layer tarballs.
225        //
226        // FS-B0 (#366): the layers above were downloaded into the CAS, but RAFS /
227        // nydusd consume a RAFS *bootstrap*, not raw OCI tarballs. Convert them
228        // in-process via nydus-builder so `bootstrap_path()` resolves to a real
229        // bootstrap. This MUST succeed; a missing/JSON bootstrap is a hard error.
230        let layer_blob_paths: Vec<PathBuf> = manifest
231            .layers
232            .iter()
233            .map(|l| self.blobs_dir.join(digest_to_filename(&l.digest)))
234            .collect();
235        let bootstrap_path = self.bootstrap_path(&image_id);
236        let blobs_dir = self.blobs_dir.clone();
237        let build_layers = layer_blob_paths.clone();
238        let build_bootstrap = bootstrap_path.clone();
239        tracing::info!(
240            image = %image_ref,
241            layers = %build_layers.len(),
242            bootstrap = %build_bootstrap.display(),
243            "Building RAFS bootstrap from OCI layers"
244        );
245        tokio::task::spawn_blocking(move || {
246            super::rafs_builder::build_rafs_bootstrap(&build_layers, &blobs_dir, &build_bootstrap)
247        })
248        .await
249        .map_err(|e| WorkerError::RafsError(format!("RAFS build task panicked: {e}")))?
250        .map_err(|e| WorkerError::ImagePullFailed {
251            image: image_ref.to_owned(),
252            reason: format!("RAFS bootstrap build failed: {e}"),
253        })?;
254
255        // 7. Write metadata
256        let metadata = ImageMetadata {
257            image_ref: image_ref.to_owned(),
258            image_id: image_id.clone(),
259            config_digest: manifest.config.digest.clone(),
260            layers: manifest.layers.iter().map(|l| l.digest.clone()).collect(),
261            host: img_ref.host.clone(),
262            repository: img_ref.repository.clone(),
263        };
264        let metadata_path = self
265            .bootstrap_dir
266            .join(format!("{}.json", digest_to_filename(&image_id)));
267        let metadata_json = serde_json::to_string_pretty(&metadata)?;
268        tokio::fs::write(&metadata_path, metadata_json).await?;
269
270        // 8. Create ref symlink
271        let ref_name = Self::normalize_ref(image_ref);
272        let ref_path = self.refs_dir.join(&ref_name);
273
274        // Remove existing symlink if present
275        if ref_path.exists() {
276            tokio::fs::remove_file(&ref_path).await?;
277        }
278        tokio::fs::symlink(&metadata_path, &ref_path).await?;
279
280        tracing::info!(
281            image = %image_ref,
282            image_id = %image_id,
283            layers = %manifest.layers.len(),
284            "Image pulled successfully"
285        );
286
287        Ok(image_id)
288    }
289
290    /// Download a blob using nydus-storage's Registry backend.
291    ///
292    /// This enables Dragonfly P2P when `blob_redirected_host` is configured.
293    ///
294    /// # Runtime-drop safety (#737)
295    ///
296    /// The nydus-storage `Registry` backend and its blob reader own an
297    /// **internal tokio runtime** (for their HTTP transport). tokio forbids
298    /// dropping a runtime from within another runtime's context — and that
299    /// context is thread-local, so it is present both inside an async task AND
300    /// inside a `spawn_blocking` pool thread (the pool thread still carries the
301    /// outer runtime handle). Constructing those nydus objects on a
302    /// `spawn_blocking` thread and letting them drop there therefore panics with
303    /// `Cannot drop a runtime in a context where blocking is not allowed` when
304    /// `download_blob` is called from any async caller.
305    ///
306    /// To stay safe we run the **entire** nydus create + download + drop on a
307    /// plain `std::thread` that has NO ambient tokio runtime, and ferry only the
308    /// final plain `Result` back over a `oneshot`. No nydus object ever crosses
309    /// back into the async context.
310    async fn download_blob(
311        &self,
312        img_ref: &ImageReference,
313        digest: &str,
314        dest_path: &Path,
315        auth: Option<&AuthConfig>,
316    ) -> Result<()> {
317        // Extract blob ID from digest (remove "sha256:" prefix)
318        let blob_id = digest.strip_prefix("sha256:").unwrap_or(digest).to_owned(); // Convert to owned String for 'static lifetime
319
320        // Create nydus-storage Registry backend config
321        let registry_config = self.create_registry_config(img_ref, &blob_id, auth);
322        let dest_path = dest_path.to_path_buf();
323
324        let (tx, rx) = tokio::sync::oneshot::channel();
325        std::thread::Builder::new()
326            .name("rafs-blob-download".to_owned())
327            .spawn(move || {
328                // ALL nydus objects (backend, reader, buf_reader) are created,
329                // used, AND dropped inside this closure — on a thread with no
330                // ambient tokio runtime — so their internal runtime drops off
331                // any tokio context. Only the plain Result is sent back.
332                let result = download_blob_blocking(&registry_config, &blob_id, &dest_path);
333                let _ = tx.send(result);
334            })
335            .map_err(|e| {
336                WorkerError::RafsError(format!("failed to spawn blob download thread: {e}"))
337            })?;
338
339        rx.await.map_err(|e| {
340            WorkerError::RafsError(format!("blob download thread exited without a result: {e}"))
341        })?
342    }
343
344    /// Create a nydus-storage RegistryConfig for a blob fetch.
345    fn create_registry_config(
346        &self,
347        img_ref: &ImageReference,
348        blob_id: &str,
349        auth: Option<&AuthConfig>,
350    ) -> RegistryConfig {
351        let mut config = RegistryConfig {
352            host: img_ref.host.clone(),
353            repo: img_ref.repository.clone(),
354            ..Default::default()
355        };
356
357        // DRAGONFLY INTEGRATION POINT
358        // When configured, all blob fetches route through Dragonfly peer
359        if let Some(peer) = &self.config.dragonfly_peer {
360            config.blob_redirected_host = peer.clone();
361            tracing::debug!(
362                peer = %peer,
363                blob_id = %blob_id,
364                "Using Dragonfly peer for blob fetch"
365            );
366        }
367
368        // Set authentication if provided (both now use Option<String>)
369        if let Some(auth) = auth {
370            if let (Some(username), Some(password)) = (&auth.username, &auth.password) {
371                if !username.is_empty() && !password.is_empty() {
372                    use base64::Engine;
373                    let credentials = format!("{}:{}", username, password);
374                    config.auth = Some(
375                        base64::engine::general_purpose::STANDARD.encode(credentials.as_bytes()),
376                    );
377                }
378            } else if let Some(token) = &auth.token {
379                if !token.is_empty() {
380                    config.registry_token = Some(token.clone());
381                }
382            }
383        }
384
385        // Configure timeouts
386        config.connect_timeout = 10;
387        config.timeout = 300;
388        config.retry_limit = 3;
389
390        config
391    }
392
393    /// Ensure storage directories exist
394    async fn ensure_dirs(&self) -> Result<()> {
395        tracing::debug!(path = %self.blobs_dir.display(), "Creating blobs directory");
396        tokio::fs::create_dir_all(&self.blobs_dir).await.map_err(|e| {
397            tracing::error!(path = %self.blobs_dir.display(), error = %e, "Failed to create blobs directory");
398            e
399        })?;
400
401        tracing::debug!(path = %self.bootstrap_dir.display(), "Creating bootstrap directory");
402        tokio::fs::create_dir_all(&self.bootstrap_dir).await.map_err(|e| {
403            tracing::error!(path = %self.bootstrap_dir.display(), error = %e, "Failed to create bootstrap directory");
404            e
405        })?;
406
407        tracing::debug!(path = %self.refs_dir.display(), "Creating refs directory");
408        tokio::fs::create_dir_all(&self.refs_dir).await.map_err(|e| {
409            tracing::error!(path = %self.refs_dir.display(), error = %e, "Failed to create refs directory");
410            e
411        })?;
412
413        tracing::debug!(path = %self.cache_dir.display(), "Creating cache directory");
414        tokio::fs::create_dir_all(&self.cache_dir).await.map_err(|e| {
415            tracing::error!(path = %self.cache_dir.display(), error = %e, "Failed to create cache directory");
416            e
417        })?;
418
419        Ok(())
420    }
421
422    /// Ensure an image is available locally (pull if needed)
423    pub async fn ensure(&self, image_ref: &str) -> Result<String> {
424        if self.exists(image_ref) {
425            self.get_image_id(image_ref)
426        } else {
427            self.pull(image_ref).await
428        }
429    }
430
431    /// Check if an image exists locally
432    pub fn exists(&self, image_ref: &str) -> bool {
433        let tag_path = self.refs_dir.join(Self::normalize_ref(image_ref));
434        tag_path.exists()
435    }
436
437    /// Get image ID from reference
438    pub fn get_image_id(&self, image_ref: &str) -> Result<String> {
439        let tag_path = self.refs_dir.join(Self::normalize_ref(image_ref));
440        if tag_path.exists() {
441            // Read metadata file
442            let metadata_path = std::fs::read_link(&tag_path)?;
443            let metadata_str = std::fs::read_to_string(&metadata_path)?;
444            let metadata: ImageMetadata = serde_json::from_str(&metadata_str)?;
445            Ok(metadata.image_id)
446        } else {
447            Err(WorkerError::ImageNotFound(image_ref.to_owned()))
448        }
449    }
450
451    /// Get image metadata
452    pub fn get_metadata(&self, image_ref: &str) -> Result<ImageMetadata> {
453        let tag_path = self.refs_dir.join(Self::normalize_ref(image_ref));
454        if tag_path.exists() {
455            let metadata_path = std::fs::read_link(&tag_path)?;
456            let metadata_str = std::fs::read_to_string(&metadata_path)?;
457            let metadata: ImageMetadata = serde_json::from_str(&metadata_str)?;
458            Ok(metadata)
459        } else {
460            Err(WorkerError::ImageNotFound(image_ref.to_owned()))
461        }
462    }
463
464    /// List all images
465    pub async fn list(&self) -> Result<Vec<ImageInfo>> {
466        let mut images = Vec::new();
467
468        if self.refs_dir.exists() {
469            for entry in std::fs::read_dir(&self.refs_dir)? {
470                let entry = entry?;
471                if entry.file_type()?.is_symlink() {
472                    let _tag = entry.file_name().to_string_lossy().to_string();
473                    let metadata_path = std::fs::read_link(entry.path())?;
474
475                    if let Ok(metadata_str) = std::fs::read_to_string(&metadata_path) {
476                        if let Ok(metadata) = serde_json::from_str::<ImageMetadata>(&metadata_str) {
477                            images.push(ImageInfo {
478                                id: metadata.image_id.clone(),
479                                repo_tags: vec![metadata.image_ref.clone()],
480                                repo_digests: vec![metadata.config_digest.clone()],
481                                size: self.calculate_image_size(&metadata),
482                                uid: -1,
483                                username: String::new(),
484                                spec: ImageSpec {
485                                    image: metadata.image_ref.clone(),
486                                    ..Default::default()
487                                },
488                                pinned: false,
489                            });
490                        }
491                    }
492                }
493            }
494        }
495
496        Ok(images)
497    }
498
499    /// Remove an image
500    pub async fn remove(&self, image_id: &str) -> Result<()> {
501        tracing::info!(image_id = %image_id, "Removing image");
502
503        // Find and remove ref symlinks pointing to this image
504        if self.refs_dir.exists() {
505            for entry in std::fs::read_dir(&self.refs_dir)? {
506                let entry = entry?;
507                if entry.file_type()?.is_symlink() {
508                    let metadata_path = std::fs::read_link(entry.path())?;
509                    if let Ok(metadata_str) = std::fs::read_to_string(&metadata_path) {
510                        if let Ok(metadata) = serde_json::from_str::<ImageMetadata>(&metadata_str) {
511                            if metadata.image_id == image_id {
512                                tokio::fs::remove_file(entry.path()).await?;
513                            }
514                        }
515                    }
516                }
517            }
518        }
519
520        // Remove bootstrap metadata
521        let metadata_path = self
522            .bootstrap_dir
523            .join(format!("{}.json", digest_to_filename(image_id)));
524        if metadata_path.exists() {
525            tokio::fs::remove_file(&metadata_path).await?;
526        }
527
528        // Remove the RAFS bootstrap (.meta) built by FS-B0.
529        let bootstrap_path = self.bootstrap_path(image_id);
530        if bootstrap_path.exists() {
531            tokio::fs::remove_file(&bootstrap_path).await?;
532        }
533
534        // Note: Blobs are not removed immediately as they may be shared
535        // Run gc() to clean up unreferenced blobs
536
537        Ok(())
538    }
539
540    /// Run garbage collection on unused blobs
541    pub async fn gc(&self) -> Result<GcStats> {
542        tracing::info!("Running garbage collection");
543
544        // 1. Collect all referenced layer digests
545        let mut referenced = std::collections::HashSet::new();
546
547        if self.bootstrap_dir.exists() {
548            for entry in std::fs::read_dir(&self.bootstrap_dir)? {
549                let entry = entry?;
550                let path = entry.path();
551                match path.extension().and_then(|e| e.to_str()) {
552                    Some("json") => {
553                        if let Ok(metadata_str) = std::fs::read_to_string(&path) {
554                            if let Ok(metadata) =
555                                serde_json::from_str::<ImageMetadata>(&metadata_str)
556                            {
557                                referenced.insert(digest_to_filename(&metadata.config_digest));
558                                for layer in &metadata.layers {
559                                    referenced.insert(digest_to_filename(layer));
560                                }
561                            }
562                        }
563                    }
564                    // RAFS bootstraps reference data blobs by their RAFS blob
565                    // hash (not OCI layer digests), so mark those as referenced
566                    // too — otherwise GC would delete blobs a live bootstrap
567                    // depends on.
568                    Some("meta") => {
569                        if let Ok(blob_ids) = super::rafs_builder::bootstrap_blob_ids(&path) {
570                            for blob_id in blob_ids {
571                                referenced.insert(blob_id);
572                            }
573                        }
574                    }
575                    _ => {}
576                }
577            }
578        }
579
580        // 2. Remove unreferenced blobs
581        let mut chunks_removed = 0u64;
582        let mut bytes_freed = 0u64;
583
584        if self.blobs_dir.exists() {
585            for entry in std::fs::read_dir(&self.blobs_dir)? {
586                let entry = entry?;
587                let filename = entry.file_name().to_string_lossy().to_string();
588                if !referenced.contains(&filename) {
589                    if let Ok(metadata) = entry.metadata() {
590                        bytes_freed += metadata.len();
591                        chunks_removed += 1;
592                        tokio::fs::remove_file(entry.path()).await?;
593                        tracing::debug!(blob = %filename, "Removed unreferenced blob");
594                    }
595                }
596            }
597        }
598
599        tracing::info!(
600            chunks_removed = %chunks_removed,
601            bytes_freed = %bytes_freed,
602            "Garbage collection complete"
603        );
604
605        Ok(GcStats {
606            chunks_removed,
607            bytes_freed,
608        })
609    }
610
611    /// Get bootstrap path for an image
612    pub fn bootstrap_path(&self, image_id: &str) -> PathBuf {
613        self.bootstrap_dir
614            .join(format!("{}.meta", digest_to_filename(image_id)))
615    }
616
617    /// Sum on-disk bytes for each unique config or layer blob recorded in
618    /// `metadata`.
619    ///
620    /// The config blob is counted alongside the layers to match
621    /// Docker/containerd image-size semantics. Descriptors can alias the same
622    /// content digest, so each CAS blob is counted only once. The reported
623    /// value is the fetched on-disk byte length (the compressed OCI blob), not
624    /// the descriptor's advertised size. Missing or unreadable blobs are
625    /// silently treated as zero so a partially-present image still reports a
626    /// (under-)count rather than failing the whole listing.
627    fn calculate_image_size(&self, metadata: &ImageMetadata) -> u64 {
628        std::iter::once(&metadata.config_digest)
629            .chain(metadata.layers.iter())
630            .collect::<std::collections::HashSet<_>>()
631            .into_iter()
632            .map(|digest| {
633                let path = self.blobs_dir.join(digest_to_filename(digest));
634                std::fs::metadata(&path).map(|m| m.len()).unwrap_or(0)
635            })
636            .sum()
637    }
638
639    /// Get layer blob path for a digest
640    pub fn blob_path(&self, digest: &str) -> PathBuf {
641        self.blobs_dir.join(digest_to_filename(digest))
642    }
643
644    /// Get blobs directory
645    pub fn blobs_dir(&self) -> &PathBuf {
646        &self.blobs_dir
647    }
648
649    /// Get cache directory
650    pub fn cache_dir(&self) -> &PathBuf {
651        &self.cache_dir
652    }
653
654    /// Get bootstrap (RAFS metadata) directory
655    pub fn bootstrap_dir(&self) -> &PathBuf {
656        &self.bootstrap_dir
657    }
658
659    /// Get refs (tag symlink) directory
660    pub fn refs_dir(&self) -> &PathBuf {
661        &self.refs_dir
662    }
663
664    // ─────────────────────────────────────────────────────────────────────────
665    // CRI ImageClient methods
666    // ─────────────────────────────────────────────────────────────────────────
667
668    /// List all images (CRI ImageClient aligned)
669    pub async fn list_images(&self) -> Result<Vec<ImageInfo>> {
670        self.list().await
671    }
672
673    /// Get image status (CRI ImageClient aligned)
674    pub async fn image_status(&self, image_ref: &str, _verbose: bool) -> Result<ImageStatusResult> {
675        if self.exists(image_ref) {
676            let metadata = self.get_metadata(image_ref)?;
677            Ok(ImageStatusResult {
678                image: ImageInfo {
679                    id: metadata.image_id.clone(),
680                    repo_tags: vec![metadata.image_ref.clone()],
681                    repo_digests: vec![metadata.config_digest.clone()],
682                    size: self.calculate_image_size(&metadata),
683                    uid: -1,
684                    username: String::new(),
685                    spec: ImageSpec {
686                        image: metadata.image_ref.clone(),
687                        ..Default::default()
688                    },
689                    pinned: false,
690                },
691                info: vec![],
692            })
693        } else {
694            // Empty id = not found
695            Ok(ImageStatusResult {
696                image: ImageInfo::default(),
697                info: vec![],
698            })
699        }
700    }
701
702    /// Remove image by reference (CRI ImageClient aligned)
703    pub async fn remove_image(&self, image_ref: &str) -> Result<()> {
704        // Get image ID from reference, then remove
705        let image_id = self.get_image_id(image_ref)?;
706        self.remove(&image_id).await
707    }
708
709    /// Get filesystem info (CRI ImageClient aligned)
710    pub async fn fs_info(&self) -> Result<Vec<FilesystemUsage>> {
711        let mut used_bytes = 0u64;
712        let mut inodes_used = 0u64;
713
714        // Calculate blobs usage
715        if self.blobs_dir.exists() {
716            for entry in walkdir::WalkDir::new(&self.blobs_dir)
717                .into_iter()
718                .filter_map(std::result::Result::ok)
719            {
720                if entry.file_type().is_file() {
721                    if let Ok(meta) = entry.metadata() {
722                        used_bytes += meta.len();
723                        inodes_used += 1;
724                    }
725                }
726            }
727        }
728
729        // Calculate bootstrap metadata usage
730        if self.bootstrap_dir.exists() {
731            for entry in walkdir::WalkDir::new(&self.bootstrap_dir)
732                .into_iter()
733                .filter_map(std::result::Result::ok)
734            {
735                if entry.file_type().is_file() {
736                    if let Ok(meta) = entry.metadata() {
737                        used_bytes += meta.len();
738                        inodes_used += 1;
739                    }
740                }
741            }
742        }
743
744        Ok(vec![FilesystemUsage {
745            timestamp: chrono::Utc::now().timestamp(),
746            fs_id: FilesystemIdentifier {
747                mountpoint: self.blobs_dir.to_string_lossy().to_string(),
748            },
749            used_bytes,
750            inodes_used,
751        }])
752    }
753
754    // ─────────────────────────────────────────────────────────────────────────
755    // Internal helpers
756    // ─────────────────────────────────────────────────────────────────────────
757
758    /// Normalize image reference to filesystem-safe name
759    fn normalize_ref(image_ref: &str) -> String {
760        image_ref.replace(['/', ':', '@'], "_")
761    }
762}
763
764/// Download a single blob to `dest_path` using nydus-storage's `Registry`
765/// backend, entirely synchronously.
766///
767/// This constructs and drops every nydus object (`Registry` backend, blob
768/// reader, `BlobBufReader`) locally. It MUST be called from a thread with no
769/// ambient tokio runtime — see [`RafsStore::download_blob`] and #737 — because
770/// those objects own an internal tokio runtime that panics if dropped inside a
771/// runtime context.
772fn download_blob_blocking(
773    registry_config: &RegistryConfig,
774    blob_id: &str,
775    dest_path: &Path,
776) -> Result<()> {
777    // Create the registry backend.
778    let backend = Registry::new(registry_config, Some(blob_id))
779        .map_err(|e| WorkerError::RafsError(format!("failed to create registry backend: {e:?}")))?;
780
781    // Get a blob reader.
782    let reader = backend
783        .get_reader(blob_id)
784        .map_err(|e| WorkerError::RafsError(format!("failed to get blob reader: {e:?}")))?;
785
786    // Get blob size (we need to know the size for BlobBufReader).
787    let blob_size = reader
788        .blob_size()
789        .map_err(|e| WorkerError::RafsError(format!("failed to get blob size: {e:?}")))?;
790
791    // Use BlobBufReader for efficient buffered reading.
792    let mut buf_reader = BlobBufReader::new(
793        1024 * 1024, // 1MB buffer
794        reader,
795        0,
796        blob_size,
797    );
798
799    // Create destination file.
800    let mut file = std::fs::File::create(dest_path)
801        .map_err(|e| WorkerError::IoError(format!("failed to create blob file: {e}")))?;
802
803    // Copy data.
804    std::io::copy(&mut buf_reader, &mut file)
805        .map_err(|e| WorkerError::IoError(format!("failed to write blob: {e}")))?;
806
807    // Sync to disk.
808    file.sync_all()
809        .map_err(|e| WorkerError::IoError(format!("failed to sync blob: {e}")))?;
810
811    Ok(())
812    // `backend` and `buf_reader` (which owns `reader`) drop here, on the caller's
813    // (non-tokio) thread — off any runtime context.
814}
815
816/// Convert digest to filesystem-safe filename
817///
818/// `pub(crate)` so [`super::store_mount::RafsStoreMount`] (#652) can resolve a
819/// `sha256:...`-style digest path component to the on-disk blob filename
820/// using the same convention as the rest of the store.
821pub(crate) fn digest_to_filename(digest: &str) -> String {
822    digest.replace(':', "_")
823}
824
825/// Garbage collection statistics
826#[derive(Debug, Clone)]
827pub struct GcStats {
828    /// Number of blobs removed
829    pub chunks_removed: u64,
830    /// Bytes freed
831    pub bytes_freed: u64,
832}
833
834/// Image metadata stored in bootstrap directory
835#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
836pub struct ImageMetadata {
837    /// Original image reference
838    pub image_ref: String,
839    /// Image ID (sha256 of config)
840    pub image_id: String,
841    /// Config blob digest
842    pub config_digest: String,
843    /// Layer digests
844    pub layers: Vec<String>,
845    /// Registry host
846    pub host: String,
847    /// Repository name
848    pub repository: String,
849}
850
851// ─────────────────────────────────────────────────────────────────────────────
852// ImageStore trait impl + inventory registration (#646)
853// ─────────────────────────────────────────────────────────────────────────────
854//
855// `RafsStore` already satisfies the `ImageStore` trait structurally (its public
856// methods match the CRI image ops). This impl makes it dispatchable as
857// `Arc<dyn ImageStore>` from `WorkerService` WITHOUT a cfg mirror — the trait
858// surface is always compiled; only this impl (and the nydus deps it rests on)
859// requires `oci-image`. A future non-RAFS image backend adds its own impl +
860// `submit!` with zero changes to `WorkerService`.
861//
862// The inherent methods (e.g. `RafsStore::list_images`) are called via
863// fully-qualified syntax because the trait methods share names — this avoids
864// the recursion ambiguity without renaming the inherent API.
865
866#[async_trait::async_trait]
867impl crate::image::store_trait::ImageStore for RafsStore {
868    async fn list_images(&self) -> anyhow::Result<Vec<ImageInfo>> {
869        RafsStore::list_images(self).await.map_err(Into::into)
870    }
871
872    async fn image_status(
873        &self,
874        image_ref: &str,
875        verbose: bool,
876    ) -> anyhow::Result<ImageStatusResult> {
877        RafsStore::image_status(self, image_ref, verbose)
878            .await
879            .map_err(Into::into)
880    }
881
882    async fn pull_with_auth(
883        &self,
884        image_ref: &str,
885        auth: Option<&hyprstream_rpc_std::worker_client::AuthConfig>,
886    ) -> anyhow::Result<String> {
887        RafsStore::pull_with_auth(self, image_ref, auth)
888            .await
889            .map_err(Into::into)
890    }
891
892    async fn remove_image(&self, image_ref: &str) -> anyhow::Result<()> {
893        RafsStore::remove_image(self, image_ref)
894            .await
895            .map_err(Into::into)
896    }
897
898    async fn fs_info(&self) -> anyhow::Result<Vec<FilesystemUsage>> {
899        RafsStore::fs_info(self).await.map_err(Into::into)
900    }
901}
902
903inventory::submit! {
904    crate::image::store_trait::ImageBackendRegistration {
905        name: "rafs",
906        construct: |config| {
907            let store = RafsStore::new(config.clone()).map_err(anyhow::Error::from)?;
908            Ok(std::sync::Arc::new(store) as std::sync::Arc<dyn crate::image::store_trait::ImageStore>)
909        },
910    }
911}
912
913// ─────────────────────────────────────────────────────────────────────────────
914// Regression tests (#737)
915// ─────────────────────────────────────────────────────────────────────────────
916//
917// These exercise the runtime-drop-safety of the blob download path. Before the
918// #737 fix, the nydus `Registry` backend (which owns an internal tokio runtime)
919// was created on a `spawn_blocking` thread and then dropped inside the async
920// `download_blob` context, panicking with:
921//   "Cannot drop a runtime in a context where blocking is not allowed."
922// Any of the tests below driving `download_blob` from a `#[tokio::test]` would
923// therefore PANIC (and fail) before the fix, and pass after it — the nydus
924// objects are now created and dropped on a plain `std::thread`.
925//
926// No reachable registry is required: we point the pull at an unreachable local
927// address so the download fails fast with a network error *after* the nydus
928// backend (the runtime-owning object) has been constructed and must be dropped.
929
930#[cfg(test)]
931#[allow(clippy::unwrap_used, clippy::expect_used)]
932mod store_tests {
933    use super::*;
934    use crate::config::ImageConfig;
935
936    /// Build a `RafsStore` rooted in a fresh tempdir.
937    fn test_store(tmp: &std::path::Path) -> RafsStore {
938        let config = ImageConfig {
939            blobs_dir: tmp.join("blobs"),
940            bootstrap_dir: tmp.join("bootstrap"),
941            refs_dir: tmp.join("refs"),
942            cache_dir: tmp.join("cache"),
943            runtime_dir: tmp.join("run"),
944            ..Default::default()
945        };
946        std::fs::create_dir_all(&config.blobs_dir).unwrap();
947        RafsStore::new(config).unwrap()
948    }
949
950    /// An `ImageReference` whose host refuses connections immediately, so the
951    /// blob download fails fast *after* the nydus backend is constructed.
952    fn unreachable_ref() -> ImageReference {
953        ImageReference {
954            // 127.0.0.1:1 (a privileged port nothing listens on) → connection
955            // refused, exercising the create+drop of the nydus backend without
956            // needing the network or a real registry.
957            host: "127.0.0.1:1".to_owned(),
958            repository: "library/does-not-exist".to_owned(),
959            reference: "latest".to_owned(),
960            is_digest: false,
961        }
962    }
963
964    fn metadata(config_digest: &str, layers: &[&str]) -> ImageMetadata {
965        ImageMetadata {
966            image_ref: "registry.example/image:latest".to_owned(),
967            image_id: "sha256:image".to_owned(),
968            config_digest: config_digest.to_owned(),
969            layers: layers.iter().map(|digest| (*digest).to_owned()).collect(),
970            host: "registry.example".to_owned(),
971            repository: "image".to_owned(),
972        }
973    }
974
975    #[test]
976    fn image_size_counts_each_referenced_blob_once() {
977        let tmp = tempfile::tempdir().unwrap();
978        let store = test_store(tmp.path());
979        let config = "sha256:config";
980        let layer = "sha256:layer";
981        std::fs::write(store.blob_path(config), b"config").unwrap();
982        std::fs::write(store.blob_path(layer), b"layer-bytes").unwrap();
983
984        // Both a config/layer alias and a repeated layer descriptor name the
985        // same CAS content, which must contribute only one on-disk length.
986        let metadata = metadata(config, &[config, layer, layer]);
987
988        assert_eq!(store.calculate_image_size(&metadata), 6 + 11);
989    }
990
991    #[test]
992    fn image_size_uses_fetched_bytes_and_ignores_missing_blobs() {
993        let tmp = tempfile::tempdir().unwrap();
994        let store = test_store(tmp.path());
995        let config = "sha256:config";
996        let present_layer = "sha256:present";
997        let missing_layer = "sha256:missing";
998        std::fs::write(store.blob_path(config), b"cfg").unwrap();
999        std::fs::write(store.blob_path(present_layer), b"fetched").unwrap();
1000
1001        // OCI descriptor sizes are metadata from the manifest; image storage
1002        // usage reports the actual compressed bytes in the local CAS instead.
1003        let metadata = metadata(config, &[present_layer, missing_layer]);
1004
1005        assert_eq!(store.calculate_image_size(&metadata), 3 + 7);
1006    }
1007
1008    /// Drive `download_blob` from a multi-threaded tokio runtime. Must return an
1009    /// error (unreachable registry) rather than panicking on the nydus runtime
1010    /// drop. Pre-#737 this panicked.
1011    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1012    async fn download_blob_does_not_panic_multi_thread() {
1013        let tmp = tempfile::tempdir().unwrap();
1014        let store = test_store(tmp.path());
1015        let img_ref = unreachable_ref();
1016        let dest = store.blobs_dir().join("blob_out");
1017
1018        let res = store
1019            .download_blob(&img_ref, "sha256:deadbeef", &dest, None)
1020            .await;
1021
1022        // The point of the test is that we got HERE (a returned Result) instead
1023        // of panicking with "Cannot drop a runtime ...".
1024        assert!(
1025            res.is_err(),
1026            "expected an error pulling from an unreachable registry, got: {res:?}"
1027        );
1028    }
1029
1030    /// Same, but from a current-thread runtime — the flavor most likely to trip
1031    /// the runtime-in-runtime drop rule.
1032    #[tokio::test(flavor = "current_thread")]
1033    async fn download_blob_does_not_panic_current_thread() {
1034        let tmp = tempfile::tempdir().unwrap();
1035        let store = test_store(tmp.path());
1036        let img_ref = unreachable_ref();
1037        let dest = store.blobs_dir().join("blob_out");
1038
1039        let res = store
1040            .download_blob(&img_ref, "sha256:deadbeef", &dest, None)
1041            .await;
1042
1043        assert!(
1044            res.is_err(),
1045            "expected an error pulling from an unreachable registry, got: {res:?}"
1046        );
1047    }
1048}