Skip to main content

second_brain_core/
model_cache.rs

1use std::ffi::OsString;
2use std::path::PathBuf;
3
4use anyhow::{Context, Result, bail};
5
6pub const MODEL_CACHE_DIR_ENV: &str = "FASTEMBED_CACHE_DIR";
7
8/// Directory the embedding and reranker models are downloaded to and loaded
9/// from: `FASTEMBED_CACHE_DIR` when set, otherwise `second-brain/models` under
10/// the OS user cache dir. Created if missing. Errors instead of resolving to a
11/// path relative to the working directory.
12pub fn model_cache_dir() -> Result<PathBuf> {
13    let dir = resolve(std::env::var_os(MODEL_CACHE_DIR_ENV), dirs::cache_dir())?;
14    std::fs::create_dir_all(&dir)
15        .with_context(|| format!("creating model cache dir {}", dir.display()))?;
16    Ok(dir)
17}
18
19fn resolve(env_override: Option<OsString>, user_cache: Option<PathBuf>) -> Result<PathBuf> {
20    if let Some(value) = env_override.filter(|v| !v.is_empty()) {
21        let dir = PathBuf::from(value);
22        if !dir.is_absolute() {
23            bail!(
24                "{MODEL_CACHE_DIR_ENV} must be an absolute path, got {}",
25                dir.display()
26            );
27        }
28        return Ok(dir);
29    }
30    let user_cache = user_cache.with_context(|| {
31        format!("cannot determine the user cache directory; set {MODEL_CACHE_DIR_ENV}")
32    })?;
33    if !user_cache.is_absolute() {
34        bail!(
35            "user cache directory {} is not absolute; set {MODEL_CACHE_DIR_ENV}",
36            user_cache.display()
37        );
38    }
39    Ok(user_cache.join("second-brain").join("models"))
40}
41
42#[cfg(test)]
43pub(crate) mod test_support {
44    use std::ffi::OsString;
45    use std::path::Path;
46    use std::sync::{Mutex, MutexGuard};
47
48    use super::MODEL_CACHE_DIR_ENV;
49
50    static ENV_LOCK: Mutex<()> = Mutex::new(());
51
52    /// Points `FASTEMBED_CACHE_DIR` at `dir` while held and restores the
53    /// previous value on drop. Holds a crate-wide lock, because the variable
54    /// is process-global and unit tests run on parallel threads.
55    pub(crate) struct CacheDirOverride {
56        previous: Option<OsString>,
57        _lock: MutexGuard<'static, ()>,
58    }
59
60    impl CacheDirOverride {
61        pub(crate) fn new(dir: &Path) -> Self {
62            let lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
63            let previous = std::env::var_os(MODEL_CACHE_DIR_ENV);
64            // SAFETY: every test that touches this variable holds ENV_LOCK.
65            unsafe { std::env::set_var(MODEL_CACHE_DIR_ENV, dir) };
66            Self {
67                previous,
68                _lock: lock,
69            }
70        }
71    }
72
73    impl Drop for CacheDirOverride {
74        fn drop(&mut self) {
75            // SAFETY: ENV_LOCK is still held until this guard's fields drop.
76            unsafe {
77                match &self.previous {
78                    Some(value) => std::env::set_var(MODEL_CACHE_DIR_ENV, value),
79                    None => std::env::remove_var(MODEL_CACHE_DIR_ENV),
80                }
81            }
82        }
83    }
84}
85
86#[cfg(test)]
87mod tests {
88    use super::test_support::CacheDirOverride;
89    use super::*;
90
91    #[test]
92    fn unset_override_resolves_under_the_os_user_cache_dir() {
93        let user_cache = dirs::cache_dir().expect("test host has a user cache dir");
94
95        let dir = resolve(None, Some(user_cache.clone())).unwrap();
96
97        assert_eq!(dir, user_cache.join("second-brain").join("models"));
98        assert!(dir.is_absolute());
99    }
100
101    #[test]
102    fn set_override_wins_over_the_user_cache_dir() {
103        let dir = resolve(
104            Some(OsString::from("/srv/models")),
105            Some(PathBuf::from("/home/u/.cache")),
106        )
107        .unwrap();
108
109        assert_eq!(dir, PathBuf::from("/srv/models"));
110    }
111
112    #[test]
113    fn empty_override_counts_as_unset() {
114        let dir = resolve(Some(OsString::new()), Some(PathBuf::from("/home/u/.cache"))).unwrap();
115
116        assert_eq!(dir, PathBuf::from("/home/u/.cache/second-brain/models"));
117    }
118
119    #[test]
120    fn relative_override_is_rejected() {
121        let err = resolve(
122            Some(OsString::from(".fastembed_cache")),
123            Some(PathBuf::from("/home/u/.cache")),
124        )
125        .unwrap_err();
126
127        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
128    }
129
130    #[test]
131    fn missing_user_cache_dir_is_an_error_not_a_cwd_fallback() {
132        let err = resolve(None, None).unwrap_err();
133
134        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
135    }
136
137    #[test]
138    fn relative_user_cache_dir_is_rejected() {
139        let err = resolve(None, Some(PathBuf::from("home/.cache"))).unwrap_err();
140
141        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
142    }
143
144    #[test]
145    fn model_cache_dir_returns_and_creates_the_override_dir() {
146        let tmp = tempfile::tempdir().unwrap();
147        let target = tmp.path().join("nested").join("models");
148        let _env = CacheDirOverride::new(&target);
149
150        let dir = model_cache_dir().unwrap();
151
152        assert_eq!(dir, target);
153        assert!(dir.is_dir());
154    }
155}