Skip to main content

hf_cache_reader/
lib.rs

1//! Read the standard Hugging Face cache layout without network access.
2//!
3//! This crate performs synchronous, read-only filesystem inspection and has no
4//! runtime dependencies. It deliberately contains no HTTP client and no model
5//! format or download policy.
6
7#![forbid(unsafe_code)]
8
9use std::collections::{HashMap, HashSet};
10use std::ffi::{OsStr, OsString};
11use std::fmt;
12use std::fs;
13use std::io;
14use std::path::{Path, PathBuf};
15use std::time::SystemTime;
16
17/// A repository kind supported by the Hugging Face cache layout.
18#[non_exhaustive]
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
20pub enum RepoType {
21    /// A model repository stored below a `models--` directory.
22    Model,
23    /// A dataset repository stored below a `datasets--` directory.
24    Dataset,
25    /// A Space repository stored below a `spaces--` directory.
26    Space,
27    /// A Kernel repository stored below a `kernels--` directory.
28    Kernel,
29}
30
31impl RepoType {
32    /// Return the lowercase singular name used by APIs and diagnostics.
33    #[must_use]
34    pub const fn as_str(self) -> &'static str {
35        match self {
36            Self::Model => "model",
37            Self::Dataset => "dataset",
38            Self::Space => "space",
39            Self::Kernel => "kernel",
40        }
41    }
42
43    const fn directory_prefix(self) -> &'static str {
44        match self {
45            Self::Model => "models",
46            Self::Dataset => "datasets",
47            Self::Space => "spaces",
48            Self::Kernel => "kernels",
49        }
50    }
51
52    fn from_directory_prefix(prefix: &str) -> Option<Self> {
53        match prefix {
54            "models" => Some(Self::Model),
55            "datasets" => Some(Self::Dataset),
56            "spaces" => Some(Self::Space),
57            "kernels" => Some(Self::Kernel),
58            _ => None,
59        }
60    }
61}
62
63impl fmt::Display for RepoType {
64    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
65        formatter.write_str(self.as_str())
66    }
67}
68
69/// A readable file in one cached revision.
70#[non_exhaustive]
71#[derive(Debug, Clone, PartialEq, Eq)]
72pub struct CachedFile {
73    /// Path relative to the revision's snapshot directory.
74    pub relative_path: PathBuf,
75    /// Path to the pointer or copied file inside the snapshot directory.
76    pub snapshot_path: PathBuf,
77    /// Canonical path reached from `snapshot_path`.
78    ///
79    /// On systems where snapshots use symlinks, this normally identifies a
80    /// file below `blobs`. When a snapshot contains regular copies, this is the
81    /// canonical snapshot path instead.
82    pub blob_path: PathBuf,
83    /// Size of the resolved file in bytes.
84    pub size_on_disk: u64,
85    /// Last access time reported for the resolved file.
86    pub last_accessed: SystemTime,
87    /// Last modification time reported for the resolved file.
88    pub last_modified: SystemTime,
89}
90
91/// One cached repository revision.
92#[non_exhaustive]
93#[derive(Debug, Clone, PartialEq, Eq)]
94pub struct CachedRevision {
95    /// Snapshot directory name, normally a commit hash.
96    pub commit_hash: String,
97    /// Absolute path to the revision's snapshot directory.
98    pub snapshot_path: PathBuf,
99    /// Readable files discovered recursively below `snapshot_path`.
100    pub files: Vec<CachedFile>,
101    /// Named refs that point to this revision.
102    pub refs: Vec<String>,
103    /// Sum of file sizes within this revision.
104    pub size_on_disk: u64,
105    /// Latest file modification time within this revision.
106    pub last_modified: SystemTime,
107}
108
109/// One repository discovered in the cache.
110#[non_exhaustive]
111#[derive(Debug, Clone, PartialEq, Eq)]
112pub struct CachedRepo {
113    /// Hub repository identifier, such as `google/gemma-2-2b-it`.
114    pub repo_id: String,
115    /// Repository kind.
116    pub repo_type: RepoType,
117    /// Absolute path to this repository's cache directory.
118    pub repo_path: PathBuf,
119    /// Cached revisions, sorted by commit hash.
120    pub revisions: Vec<CachedRevision>,
121    /// Number of unique canonical file paths referenced by revisions.
122    pub blob_count: usize,
123    /// Total bytes across unique canonical file paths.
124    pub size_on_disk: u64,
125    /// Latest file access time across revisions.
126    pub last_accessed: SystemTime,
127    /// Latest file modification time across revisions.
128    pub last_modified: SystemTime,
129}
130
131/// A non-fatal problem encountered while scanning below a readable cache root.
132#[non_exhaustive]
133#[derive(Debug, Clone, PartialEq, Eq)]
134pub struct ScanWarning {
135    /// Path associated with the problem.
136    pub path: PathBuf,
137    /// Human-readable filesystem error or explanation.
138    pub message: String,
139}
140
141/// Result of scanning an entire cache directory.
142#[non_exhaustive]
143#[derive(Debug, Clone, PartialEq, Eq)]
144pub struct CacheInfo {
145    /// Cache directory that was inspected.
146    pub cache_dir: PathBuf,
147    /// Discovered repositories, sorted by kind and repository identifier.
148    pub repos: Vec<CachedRepo>,
149    /// Total bytes across repositories, with shared files deduplicated within
150    /// each repository.
151    pub size_on_disk: u64,
152    /// Non-fatal problems encountered during the scan.
153    pub warnings: Vec<ScanWarning>,
154}
155
156/// Result of scanning one requested repository.
157#[non_exhaustive]
158#[derive(Debug, Clone, PartialEq, Eq)]
159pub struct RepoScan {
160    /// Cache directory that was inspected.
161    pub cache_dir: PathBuf,
162    /// The repository, or `None` when it is not present in the cache.
163    pub repo: Option<CachedRepo>,
164    /// Non-fatal problems encountered during the scan.
165    pub warnings: Vec<ScanWarning>,
166}
167
168/// A fatal cache scanning error.
169#[non_exhaustive]
170#[derive(Debug)]
171pub enum Error {
172    /// An I/O failure prevented the requested root from being inspected.
173    Io {
174        /// Path whose operation failed.
175        path: PathBuf,
176        /// Underlying filesystem error.
177        source: io::Error,
178    },
179    /// A repository identifier could not be mapped safely to a cache path.
180    InvalidRepoId {
181        /// Rejected identifier.
182        repo_id: String,
183    },
184}
185
186impl fmt::Display for Error {
187    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
188        match self {
189            Self::Io { path, source } => {
190                write!(formatter, "failed to inspect {}: {source}", path.display())
191            }
192            Self::InvalidRepoId { repo_id } => {
193                write!(
194                    formatter,
195                    "invalid Hugging Face repository identifier {repo_id:?}"
196                )
197            }
198        }
199    }
200}
201
202impl std::error::Error for Error {
203    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
204        match self {
205            Self::Io { source, .. } => Some(source),
206            Self::InvalidRepoId { .. } => None,
207        }
208    }
209}
210
211/// Resolve the conventional Hugging Face Hub cache directory.
212///
213/// Environment variables are checked in this order: `HF_HUB_CACHE`,
214/// `HUGGINGFACE_HUB_CACHE`, `HF_HOME`, `XDG_CACHE_HOME`, `HOME`, and
215/// `USERPROFILE`. If none are set, the platform temporary directory is used.
216#[must_use]
217pub fn resolve_cache_dir() -> PathBuf {
218    resolve_cache_dir_with(|name| std::env::var_os(name), &std::env::temp_dir())
219}
220
221/// Scan the conventional Hugging Face Hub cache directory.
222///
223/// # Errors
224///
225/// Returns [`Error::Io`] when the cache root exists but cannot be read.
226pub fn scan_default_cache() -> Result<CacheInfo, Error> {
227    scan_cache(resolve_cache_dir())
228}
229
230/// Scan all supported repositories below a cache directory.
231///
232/// A missing cache directory produces an empty [`CacheInfo`]. Problems below
233/// a readable root are collected in [`CacheInfo::warnings`].
234///
235/// # Errors
236///
237/// Returns [`Error::Io`] when the cache root exists but cannot be read.
238pub fn scan_cache(cache_dir: impl AsRef<Path>) -> Result<CacheInfo, Error> {
239    let cache_dir = cache_dir.as_ref().to_path_buf();
240    let entries = match fs::read_dir(&cache_dir) {
241        Ok(entries) => entries,
242        Err(source) if source.kind() == io::ErrorKind::NotFound => {
243            return Ok(CacheInfo {
244                cache_dir,
245                repos: Vec::new(),
246                size_on_disk: 0,
247                warnings: Vec::new(),
248            });
249        }
250        Err(source) => {
251            return Err(Error::Io {
252                path: cache_dir,
253                source,
254            });
255        }
256    };
257
258    let mut warnings = Vec::new();
259    let mut repo_entries = collect_entries(entries, &cache_dir, &mut warnings);
260    repo_entries.sort_by_key(fs::DirEntry::file_name);
261
262    let mut repos = Vec::new();
263    for entry in repo_entries {
264        if !entry_is_directory(&entry, &mut warnings) {
265            continue;
266        }
267        let Some((repo_type, repo_id)) = parse_repo_folder(&entry.file_name()) else {
268            continue;
269        };
270        repos.push(scan_repo_path(
271            entry.path(),
272            repo_type,
273            repo_id,
274            &mut warnings,
275        ));
276    }
277    repos.sort_by(|left, right| {
278        left.repo_type
279            .cmp(&right.repo_type)
280            .then_with(|| left.repo_id.cmp(&right.repo_id))
281    });
282
283    let size_on_disk = repos
284        .iter()
285        .fold(0_u64, |total, repo| total.saturating_add(repo.size_on_disk));
286    sort_warnings(&mut warnings);
287    Ok(CacheInfo {
288        cache_dir,
289        repos,
290        size_on_disk,
291        warnings,
292    })
293}
294
295/// Scan one repository below a cache directory.
296///
297/// This avoids walking unrelated repositories. A missing cache or repository
298/// produces [`RepoScan`] with `repo` set to `None`.
299///
300/// # Errors
301///
302/// Returns [`Error::InvalidRepoId`] for identifiers that cannot be represented
303/// safely and unambiguously in the cache layout. Returns [`Error::Io`] when the
304/// requested repository exists but its root metadata cannot be read.
305pub fn scan_repo(
306    cache_dir: impl AsRef<Path>,
307    repo_type: RepoType,
308    repo_id: &str,
309) -> Result<RepoScan, Error> {
310    validate_repo_id(repo_id)?;
311    let cache_dir = cache_dir.as_ref().to_path_buf();
312    let repo_path = cache_dir.join(repo_folder_name(repo_type, repo_id));
313    match fs::metadata(&repo_path) {
314        Ok(metadata) if metadata.is_dir() => {}
315        Ok(_) => {
316            return Ok(RepoScan {
317                cache_dir,
318                repo: None,
319                warnings: vec![ScanWarning {
320                    path: repo_path,
321                    message: "repository cache entry is not a directory".to_owned(),
322                }],
323            });
324        }
325        Err(source) if source.kind() == io::ErrorKind::NotFound => {
326            return Ok(RepoScan {
327                cache_dir,
328                repo: None,
329                warnings: Vec::new(),
330            });
331        }
332        Err(source) => {
333            return Err(Error::Io {
334                path: repo_path,
335                source,
336            });
337        }
338    }
339
340    let mut warnings = Vec::new();
341    let repo = scan_repo_path(repo_path, repo_type, repo_id.to_owned(), &mut warnings);
342    sort_warnings(&mut warnings);
343    Ok(RepoScan {
344        cache_dir,
345        repo: Some(repo),
346        warnings,
347    })
348}
349
350fn resolve_cache_dir_with(
351    mut read_env: impl FnMut(&str) -> Option<OsString>,
352    temporary_dir: &Path,
353) -> PathBuf {
354    if let Some(path) = read_env("HF_HUB_CACHE") {
355        return PathBuf::from(path);
356    }
357    if let Some(path) = read_env("HUGGINGFACE_HUB_CACHE") {
358        return PathBuf::from(path);
359    }
360    if let Some(path) = read_env("HF_HOME") {
361        return PathBuf::from(path).join("hub");
362    }
363    if let Some(path) = read_env("XDG_CACHE_HOME") {
364        return PathBuf::from(path).join("huggingface").join("hub");
365    }
366    if let Some(path) = read_env("HOME").or_else(|| read_env("USERPROFILE")) {
367        return PathBuf::from(path)
368            .join(".cache")
369            .join("huggingface")
370            .join("hub");
371    }
372    temporary_dir.join("huggingface").join("hub")
373}
374
375fn validate_repo_id(repo_id: &str) -> Result<(), Error> {
376    let mut component_count = 0_usize;
377    for component in repo_id.split('/') {
378        component_count += 1;
379        if component.is_empty()
380            || matches!(component, "." | "..")
381            || component.contains('\\')
382            || component.contains("--")
383        {
384            return Err(Error::InvalidRepoId {
385                repo_id: repo_id.to_owned(),
386            });
387        }
388    }
389    if component_count > 2 {
390        return Err(Error::InvalidRepoId {
391            repo_id: repo_id.to_owned(),
392        });
393    }
394    Ok(())
395}
396
397fn repo_folder_name(repo_type: RepoType, repo_id: &str) -> String {
398    format!(
399        "{}--{}",
400        repo_type.directory_prefix(),
401        repo_id.replace('/', "--")
402    )
403}
404
405fn parse_repo_folder(name: &OsStr) -> Option<(RepoType, String)> {
406    let name = name.to_str()?;
407    let (prefix, encoded_id) = name.split_once("--")?;
408    let repo_type = RepoType::from_directory_prefix(prefix)?;
409    if encoded_id.is_empty() {
410        return None;
411    }
412    Some((repo_type, encoded_id.replace("--", "/")))
413}
414
415fn scan_repo_path(
416    repo_path: PathBuf,
417    repo_type: RepoType,
418    repo_id: String,
419    warnings: &mut Vec<ScanWarning>,
420) -> CachedRepo {
421    let commit_refs = read_refs(&repo_path.join("refs"), warnings);
422    let mut revisions = Vec::new();
423    let snapshots_path = repo_path.join("snapshots");
424    for entry in read_directory_or_warn(&snapshots_path, warnings) {
425        if !entry_is_directory(&entry, warnings) {
426            continue;
427        }
428        let snapshot_path = entry.path();
429        let commit_hash = entry.file_name().to_string_lossy().into_owned();
430        let mut files = scan_snapshot(&snapshot_path, warnings);
431        files.sort_by(|left, right| left.relative_path.cmp(&right.relative_path));
432        let size_on_disk = files
433            .iter()
434            .fold(0_u64, |total, file| total.saturating_add(file.size_on_disk));
435        let last_modified = files
436            .iter()
437            .map(|file| file.last_modified)
438            .max()
439            .unwrap_or(SystemTime::UNIX_EPOCH);
440        let mut refs = commit_refs.get(&commit_hash).cloned().unwrap_or_default();
441        refs.sort();
442        revisions.push(CachedRevision {
443            commit_hash,
444            snapshot_path,
445            files,
446            refs,
447            size_on_disk,
448            last_modified,
449        });
450    }
451    revisions.sort_by(|left, right| left.commit_hash.cmp(&right.commit_hash));
452
453    let mut blobs = HashMap::<PathBuf, u64>::new();
454    let mut last_accessed = SystemTime::UNIX_EPOCH;
455    let mut last_modified = SystemTime::UNIX_EPOCH;
456    for file in revisions.iter().flat_map(|revision| &revision.files) {
457        blobs
458            .entry(file.blob_path.clone())
459            .or_insert(file.size_on_disk);
460        last_accessed = last_accessed.max(file.last_accessed);
461        last_modified = last_modified.max(file.last_modified);
462    }
463    let size_on_disk = blobs
464        .values()
465        .fold(0_u64, |total, size| total.saturating_add(*size));
466
467    CachedRepo {
468        repo_id,
469        repo_type,
470        repo_path,
471        revisions,
472        blob_count: blobs.len(),
473        size_on_disk,
474        last_accessed,
475        last_modified,
476    }
477}
478
479fn read_refs(refs_path: &Path, warnings: &mut Vec<ScanWarning>) -> HashMap<String, Vec<String>> {
480    let mut refs = HashMap::<String, Vec<String>>::new();
481    for path in walk_files(refs_path, warnings) {
482        let commit_hash = match fs::read_to_string(&path) {
483            Ok(contents) => contents.trim().to_owned(),
484            Err(error) => {
485                warn(warnings, &path, error.to_string());
486                continue;
487            }
488        };
489        if commit_hash.is_empty() {
490            warn(warnings, &path, "ref file is empty");
491            continue;
492        }
493        let name = path
494            .strip_prefix(refs_path)
495            .unwrap_or(&path)
496            .to_string_lossy()
497            .replace(std::path::MAIN_SEPARATOR, "/");
498        refs.entry(commit_hash).or_default().push(name);
499    }
500    refs
501}
502
503fn scan_snapshot(snapshot_path: &Path, warnings: &mut Vec<ScanWarning>) -> Vec<CachedFile> {
504    let mut files = Vec::new();
505    for path in walk_files(snapshot_path, warnings) {
506        let blob_path = match fs::canonicalize(&path) {
507            Ok(path) => path,
508            Err(error) => {
509                warn(warnings, &path, error.to_string());
510                continue;
511            }
512        };
513        let metadata = match fs::metadata(&blob_path) {
514            Ok(metadata) => metadata,
515            Err(error) => {
516                warn(warnings, &path, error.to_string());
517                continue;
518            }
519        };
520        if !metadata.is_file() {
521            warn(warnings, &path, "snapshot entry does not resolve to a file");
522            continue;
523        }
524        files.push(CachedFile {
525            relative_path: path
526                .strip_prefix(snapshot_path)
527                .unwrap_or(&path)
528                .to_path_buf(),
529            snapshot_path: path,
530            blob_path,
531            size_on_disk: metadata.len(),
532            last_accessed: metadata.accessed().unwrap_or(SystemTime::UNIX_EPOCH),
533            last_modified: metadata.modified().unwrap_or(SystemTime::UNIX_EPOCH),
534        });
535    }
536    files
537}
538
539fn walk_files(path: &Path, warnings: &mut Vec<ScanWarning>) -> Vec<PathBuf> {
540    let mut files = Vec::new();
541    let mut pending = vec![path.to_path_buf()];
542    let mut visited_directories = HashSet::new();
543    while let Some(directory) = pending.pop() {
544        let canonical_directory = match fs::canonicalize(&directory) {
545            Ok(path) => path,
546            Err(error) if error.kind() == io::ErrorKind::NotFound => continue,
547            Err(error) => {
548                warn(warnings, &directory, error.to_string());
549                continue;
550            }
551        };
552        if !visited_directories.insert(canonical_directory) {
553            warn(warnings, &directory, "directory cycle ignored");
554            continue;
555        }
556        let mut entries = read_directory_or_warn(&directory, warnings);
557        entries.reverse();
558        for entry in entries {
559            let file_type = match entry.file_type() {
560                Ok(file_type) => file_type,
561                Err(error) => {
562                    warn(warnings, entry.path(), error.to_string());
563                    continue;
564                }
565            };
566            if file_type.is_dir() {
567                pending.push(entry.path());
568            } else {
569                files.push(entry.path());
570            }
571        }
572    }
573    files
574}
575
576fn read_directory_or_warn(path: &Path, warnings: &mut Vec<ScanWarning>) -> Vec<fs::DirEntry> {
577    match fs::read_dir(path) {
578        Ok(entries) => {
579            let mut entries = collect_entries(entries, path, warnings);
580            entries.sort_by_key(fs::DirEntry::file_name);
581            entries
582        }
583        Err(error) if error.kind() == io::ErrorKind::NotFound => Vec::new(),
584        Err(error) => {
585            warn(warnings, path, error.to_string());
586            Vec::new()
587        }
588    }
589}
590
591fn collect_entries(
592    entries: fs::ReadDir,
593    path: &Path,
594    warnings: &mut Vec<ScanWarning>,
595) -> Vec<fs::DirEntry> {
596    entries
597        .filter_map(|entry| match entry {
598            Ok(entry) => Some(entry),
599            Err(error) => {
600                warn(warnings, path, error.to_string());
601                None
602            }
603        })
604        .collect()
605}
606
607fn entry_is_directory(entry: &fs::DirEntry, warnings: &mut Vec<ScanWarning>) -> bool {
608    match entry.file_type() {
609        Ok(file_type) => file_type.is_dir(),
610        Err(error) => {
611            warn(warnings, entry.path(), error.to_string());
612            false
613        }
614    }
615}
616
617fn warn(warnings: &mut Vec<ScanWarning>, path: impl AsRef<Path>, message: impl Into<String>) {
618    warnings.push(ScanWarning {
619        path: path.as_ref().to_path_buf(),
620        message: message.into(),
621    });
622}
623
624fn sort_warnings(warnings: &mut [ScanWarning]) {
625    warnings.sort_by(|left, right| {
626        left.path
627            .cmp(&right.path)
628            .then_with(|| left.message.cmp(&right.message))
629    });
630}
631
632#[cfg(test)]
633mod tests {
634    use std::collections::HashMap;
635    use std::ffi::OsString;
636    use std::fs;
637    use std::path::{Path, PathBuf};
638    use std::sync::atomic::{AtomicU64, Ordering};
639
640    use super::{resolve_cache_dir_with, scan_cache, scan_repo, Error, RepoType};
641
642    static NEXT_TEMPORARY_DIRECTORY: AtomicU64 = AtomicU64::new(0);
643
644    struct TestDir(PathBuf);
645
646    impl TestDir {
647        fn new() -> Self {
648            loop {
649                let sequence = NEXT_TEMPORARY_DIRECTORY.fetch_add(1, Ordering::Relaxed);
650                let path = std::env::temp_dir().join(format!(
651                    "hf-cache-reader-tests-{}-{sequence}",
652                    std::process::id()
653                ));
654                match fs::create_dir(&path) {
655                    Ok(()) => return Self(path),
656                    Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
657                    Err(error) => panic!("failed to create test directory: {error}"),
658                }
659            }
660        }
661
662        fn path(&self) -> &Path {
663            &self.0
664        }
665    }
666
667    impl Drop for TestDir {
668        fn drop(&mut self) {
669            let _ = fs::remove_dir_all(&self.0);
670        }
671    }
672
673    #[test]
674    fn cache_resolution_obeys_environment_precedence() {
675        let values = HashMap::from([
676            ("HF_HUB_CACHE", OsString::from("/explicit")),
677            ("HF_HOME", OsString::from("/home")),
678            ("HOME", OsString::from("/user")),
679        ]);
680        assert_eq!(
681            resolve_cache_dir_with(|name| values.get(name).cloned(), Path::new("/temporary")),
682            Path::new("/explicit")
683        );
684
685        let values = HashMap::from([("HF_HOME", OsString::from("/home"))]);
686        assert_eq!(
687            resolve_cache_dir_with(|name| values.get(name).cloned(), Path::new("/temporary")),
688            Path::new("/home/hub")
689        );
690
691        assert_eq!(
692            resolve_cache_dir_with(|_| None, Path::new("/temporary")),
693            Path::new("/temporary/huggingface/hub")
694        );
695    }
696
697    #[test]
698    fn missing_cache_is_empty() {
699        let temporary = TestDir::new();
700        let missing = temporary.path().join("missing");
701        let cache = scan_cache(&missing).expect("scan missing cache");
702        assert_eq!(cache.cache_dir, missing);
703        assert!(cache.repos.is_empty());
704        assert!(cache.warnings.is_empty());
705    }
706
707    #[test]
708    fn scans_revisions_nested_refs_and_nested_files() {
709        let temporary = TestDir::new();
710        let cache_dir = temporary.path().join("hub");
711        let repo_dir = cache_dir.join("models--acme--tiny-model");
712        write_ref(&repo_dir, "main", "commit-a");
713        write_ref(&repo_dir, "refs/pr/7", "commit-a");
714        write_cached_file(
715            &repo_dir,
716            "commit-a",
717            "weights/model-Q4_K_M.gguf",
718            "blob-a",
719            b"weights",
720        );
721
722        let cache = scan_cache(&cache_dir).expect("scan cache");
723        assert!(cache.warnings.is_empty(), "{:?}", cache.warnings);
724        assert_eq!(cache.repos.len(), 1);
725        let repo = &cache.repos[0];
726        assert_eq!(repo.repo_type, RepoType::Model);
727        assert_eq!(repo.repo_id, "acme/tiny-model");
728        assert_eq!(repo.revisions.len(), 1);
729        let revision = &repo.revisions[0];
730        assert_eq!(revision.commit_hash, "commit-a");
731        assert_eq!(
732            revision.refs,
733            vec!["main".to_owned(), "refs/pr/7".to_owned()]
734        );
735        assert_eq!(revision.files.len(), 1);
736        assert_eq!(
737            revision.files[0].relative_path,
738            Path::new("weights/model-Q4_K_M.gguf")
739        );
740        assert_eq!(revision.files[0].size_on_disk, 7);
741    }
742
743    #[test]
744    fn targeted_scan_ignores_unrelated_repositories() {
745        let temporary = TestDir::new();
746        let cache_dir = temporary.path().join("hub");
747        let wanted = cache_dir.join("models--acme--wanted");
748        let other = cache_dir.join("models--acme--other");
749        write_cached_file(&wanted, "wanted-rev", "model.gguf", "wanted", b"wanted");
750        write_cached_file(&other, "other-rev", "model.gguf", "other", b"other");
751
752        let scan = scan_repo(&cache_dir, RepoType::Model, "acme/wanted")
753            .expect("scan requested repository");
754        assert!(scan.warnings.is_empty());
755        let repo = scan.repo.expect("cached repository");
756        assert_eq!(repo.repo_id, "acme/wanted");
757        assert_eq!(repo.revisions[0].commit_hash, "wanted-rev");
758
759        let missing = scan_repo(&cache_dir, RepoType::Model, "acme/missing")
760            .expect("scan missing repository");
761        assert!(missing.repo.is_none());
762    }
763
764    #[test]
765    fn unsafe_or_ambiguous_repository_ids_are_rejected() {
766        let temporary = TestDir::new();
767        for repo_id in ["", "../escape", "a/b/c", "a\\b", "owner/repo--name"] {
768            assert!(matches!(
769                scan_repo(temporary.path(), RepoType::Model, repo_id),
770                Err(Error::InvalidRepoId { .. })
771            ));
772        }
773    }
774
775    #[cfg(unix)]
776    #[test]
777    fn shared_blobs_are_counted_once() {
778        let temporary = TestDir::new();
779        let cache_dir = temporary.path().join("hub");
780        let repo_dir = cache_dir.join("models--acme--shared");
781        write_cached_file(&repo_dir, "one", "model.gguf", "shared", b"12345");
782        link_cached_file(&repo_dir, "two", "model.gguf", "shared");
783
784        let cache = scan_cache(&cache_dir).expect("scan cache");
785        let repo = &cache.repos[0];
786        assert_eq!(repo.revisions.len(), 2);
787        assert_eq!(repo.blob_count, 1);
788        assert_eq!(repo.size_on_disk, 5);
789    }
790
791    #[cfg(unix)]
792    #[test]
793    fn dangling_snapshot_links_are_warnings() {
794        use std::os::unix::fs::symlink;
795
796        let temporary = TestDir::new();
797        let cache_dir = temporary.path().join("hub");
798        let snapshot = cache_dir
799            .join("models--acme--broken")
800            .join("snapshots/revision");
801        fs::create_dir_all(&snapshot).expect("snapshot directory");
802        symlink("../../blobs/missing", snapshot.join("model.gguf"))
803            .expect("dangling snapshot link");
804
805        let cache = scan_cache(&cache_dir).expect("scan cache");
806        assert_eq!(cache.repos[0].revisions[0].files.len(), 0);
807        assert_eq!(cache.warnings.len(), 1);
808        assert!(cache.warnings[0].message.contains("No such file"));
809    }
810
811    fn write_ref(repo_dir: &Path, name: &str, commit: &str) {
812        let path = repo_dir.join("refs").join(name);
813        fs::create_dir_all(path.parent().expect("ref parent")).expect("create ref parent");
814        fs::write(path, commit).expect("write ref");
815    }
816
817    fn write_cached_file(
818        repo_dir: &Path,
819        revision: &str,
820        relative_path: &str,
821        blob_name: &str,
822        contents: &[u8],
823    ) {
824        let blob = repo_dir.join("blobs").join(blob_name);
825        fs::create_dir_all(blob.parent().expect("blob parent")).expect("create blob parent");
826        fs::write(&blob, contents).expect("write blob");
827        link_cached_file(repo_dir, revision, relative_path, blob_name);
828    }
829
830    fn link_cached_file(repo_dir: &Path, revision: &str, relative_path: &str, blob_name: &str) {
831        let blob = repo_dir.join("blobs").join(blob_name);
832        let pointer = repo_dir
833            .join("snapshots")
834            .join(revision)
835            .join(relative_path);
836        fs::create_dir_all(pointer.parent().expect("snapshot parent"))
837            .expect("create snapshot parent");
838        create_pointer(&blob, &pointer);
839    }
840
841    #[cfg(unix)]
842    fn create_pointer(blob: &Path, pointer: &Path) {
843        std::os::unix::fs::symlink(blob, pointer).expect("create snapshot symlink");
844    }
845
846    #[cfg(windows)]
847    fn create_pointer(blob: &Path, pointer: &Path) {
848        fs::copy(blob, pointer).expect("copy snapshot file");
849    }
850}