second-brain-core 0.11.0

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use std::ffi::OsString;
use std::path::PathBuf;

use anyhow::{Context, Result, bail};

pub const MODEL_CACHE_DIR_ENV: &str = "FASTEMBED_CACHE_DIR";

/// Directory the embedding and reranker models are downloaded to and loaded
/// from: `FASTEMBED_CACHE_DIR` when set, otherwise `second-brain/models` under
/// the OS user cache dir. Created if missing. Errors instead of resolving to a
/// path relative to the working directory.
pub fn model_cache_dir() -> Result<PathBuf> {
    let dir = resolve(std::env::var_os(MODEL_CACHE_DIR_ENV), dirs::cache_dir())?;
    std::fs::create_dir_all(&dir)
        .with_context(|| format!("creating model cache dir {}", dir.display()))?;
    Ok(dir)
}

fn resolve(env_override: Option<OsString>, user_cache: Option<PathBuf>) -> Result<PathBuf> {
    if let Some(value) = env_override.filter(|v| !v.is_empty()) {
        let dir = PathBuf::from(value);
        if !dir.is_absolute() {
            bail!(
                "{MODEL_CACHE_DIR_ENV} must be an absolute path, got {}",
                dir.display()
            );
        }
        return Ok(dir);
    }
    let user_cache = user_cache.with_context(|| {
        format!("cannot determine the user cache directory; set {MODEL_CACHE_DIR_ENV}")
    })?;
    if !user_cache.is_absolute() {
        bail!(
            "user cache directory {} is not absolute; set {MODEL_CACHE_DIR_ENV}",
            user_cache.display()
        );
    }
    Ok(user_cache.join("second-brain").join("models"))
}

#[cfg(test)]
pub(crate) mod test_support {
    use std::ffi::OsString;
    use std::path::Path;
    use std::sync::{Mutex, MutexGuard};

    use super::MODEL_CACHE_DIR_ENV;

    static ENV_LOCK: Mutex<()> = Mutex::new(());

    /// Points `FASTEMBED_CACHE_DIR` at `dir` while held and restores the
    /// previous value on drop. Holds a crate-wide lock, because the variable
    /// is process-global and unit tests run on parallel threads.
    pub(crate) struct CacheDirOverride {
        previous: Option<OsString>,
        _lock: MutexGuard<'static, ()>,
    }

    impl CacheDirOverride {
        pub(crate) fn new(dir: &Path) -> Self {
            let lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
            let previous = std::env::var_os(MODEL_CACHE_DIR_ENV);
            // SAFETY: every test that touches this variable holds ENV_LOCK.
            unsafe { std::env::set_var(MODEL_CACHE_DIR_ENV, dir) };
            Self {
                previous,
                _lock: lock,
            }
        }
    }

    impl Drop for CacheDirOverride {
        fn drop(&mut self) {
            // SAFETY: ENV_LOCK is still held until this guard's fields drop.
            unsafe {
                match &self.previous {
                    Some(value) => std::env::set_var(MODEL_CACHE_DIR_ENV, value),
                    None => std::env::remove_var(MODEL_CACHE_DIR_ENV),
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::test_support::CacheDirOverride;
    use super::*;

    #[test]
    fn unset_override_resolves_under_the_os_user_cache_dir() {
        let user_cache = dirs::cache_dir().expect("test host has a user cache dir");

        let dir = resolve(None, Some(user_cache.clone())).unwrap();

        assert_eq!(dir, user_cache.join("second-brain").join("models"));
        assert!(dir.is_absolute());
    }

    #[test]
    fn set_override_wins_over_the_user_cache_dir() {
        let dir = resolve(
            Some(OsString::from("/srv/models")),
            Some(PathBuf::from("/home/u/.cache")),
        )
        .unwrap();

        assert_eq!(dir, PathBuf::from("/srv/models"));
    }

    #[test]
    fn empty_override_counts_as_unset() {
        let dir = resolve(Some(OsString::new()), Some(PathBuf::from("/home/u/.cache"))).unwrap();

        assert_eq!(dir, PathBuf::from("/home/u/.cache/second-brain/models"));
    }

    #[test]
    fn relative_override_is_rejected() {
        let err = resolve(
            Some(OsString::from(".fastembed_cache")),
            Some(PathBuf::from("/home/u/.cache")),
        )
        .unwrap_err();

        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
    }

    #[test]
    fn missing_user_cache_dir_is_an_error_not_a_cwd_fallback() {
        let err = resolve(None, None).unwrap_err();

        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
    }

    #[test]
    fn relative_user_cache_dir_is_rejected() {
        let err = resolve(None, Some(PathBuf::from("home/.cache"))).unwrap_err();

        assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
    }

    #[test]
    fn model_cache_dir_returns_and_creates_the_override_dir() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join("nested").join("models");
        let _env = CacheDirOverride::new(&target);

        let dir = model_cache_dir().unwrap();

        assert_eq!(dir, target);
        assert!(dir.is_dir());
    }
}