car-inference 0.56.1

//! Where the Hugging Face hub cache is — one answer for every reader and writer.
//!
//! CAR reaches the hub cache three ways: hf-hub (Rust) downloads, readers that
//! look for a ready snapshot, and Python runtimes (mlx-vlm, mflux, ltx-2-mlx,
//! mlx-audio, vllm-mlx) that download on their own. They disagreed. hf-hub's
//! `Api::new()` always wrote `~/.cache/huggingface/hub` while CAR's readers
//! honored `HF_HOME`, so with `HF_HOME` set CAR downloaded to one place and
//! looked in another; the Python side also honors `HF_HUB_CACHE`, which no Rust
//! code read.
//!
//! [`hub_dir`] follows `huggingface_hub/constants.py`: `HF_HUB_CACHE`, then the
//! legacy `HUGGINGFACE_HUB_CACHE`, then `<HF_HOME>/hub`, where `HF_HOME`
//! defaults to `$XDG_CACHE_HOME/huggingface` and then `~/.cache/huggingface`.
//! Each value is expanded as Python's `expandvars(expanduser(…))` does — `~`
//! first, then `$NAME` / `${NAME}` (and `%NAME%` on Windows). Two deliberate
//! differences, both toward safety:
//!
//! - an **empty** variable counts as unset (Python's `os.getenv(name, default)`
//!   would take `""` and produce a relative `hub`);
//! - the result is always **absolute**: a relative value is anchored to the
//!   current directory once, here, and that absolute path is what every hf-hub
//!   client writes and what every Python subprocess is handed as
//!   `HF_HUB_CACHE` ([`apply_to`]). A relative value would otherwise resolve
//!   against each process's own working directory — and a later delete would
//!   act relative to the daemon's.
//!
//! `~user` is not looked up (CAR has no password-database access here); it is
//! kept as written and then anchored like any relative path.

use std::path::{Path, PathBuf};

/// The hub cache directory (`…/hub`), absolute.
pub fn hub_dir() -> PathBuf {
    absolute(resolve(&env, home_dir().as_deref()))
}

/// `HF_HOME`: the directory holding `hub/` (by default), `token` and `xet/`.
pub fn hf_home() -> PathBuf {
    absolute(resolve_home(&env, home_dir().as_deref()))
}

/// The cache directory of one repo, `<hub>/models--<org>--<name>`. For reading;
/// see [`checked_repo_dir_in`] before deleting anything.
pub fn repo_dir(repo_id: &str) -> PathBuf {
    repo_dir_in(&hub_dir(), repo_id)
}

/// [`repo_dir`] under an explicit hub directory.
pub fn repo_dir_in(hub: &Path, repo_id: &str) -> PathBuf {
    hub.join(format!("models--{}", repo_id.replace('/', "--")))
}

/// [`repo_dir_in`] for a repo id that matches the Hub's grammar —
/// `name` or `owner/name`, each `[A-Za-z0-9._-]+` and neither `.` nor `..` —
/// so the result is exactly one `models--…` component under `hub`. `None` for
/// anything else; a path built for deletion must come from here.
pub fn checked_repo_dir_in(hub: &Path, repo_id: &str) -> Option<PathBuf> {
    let part_ok = |p: &str| {
        !p.is_empty()
            && p != "."
            && p != ".."
            && p.chars()
                .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))
    };
    let mut parts = repo_id.split('/');
    let ok = match (parts.next(), parts.next(), parts.next()) {
        (Some(name), None, None) => part_ok(name),
        (Some(owner), Some(name), None) => part_ok(owner) && part_ok(name),
        _ => false,
    };
    ok.then(|| repo_dir_in(hub, repo_id))
}

/// An hf-hub client that writes into [`hub_dir`], with the endpoint and token
/// the Python library would use: `HF_ENDPOINT`, and the token from `HF_TOKEN`,
/// then the file at `HF_TOKEN_PATH` (default `<HF_HOME>/token`). Built from an
/// explicit cache rather than `ApiBuilder::from_env`, whose token comes from
/// the unexpanded `HF_HOME` and whose default cache panics without a home.
pub fn api() -> hf_hub::api::tokio::ApiBuilder {
    let mut builder = hf_hub::api::tokio::ApiBuilder::from_cache(hf_hub::Cache::new(hub_dir()))
        .with_token(token());
    if let Some(endpoint) = env("HF_ENDPOINT") {
        builder = builder.with_endpoint(endpoint);
    }
    builder
}

/// Point a Python subprocess at the same hub cache CAR reads and writes.
pub fn apply_to(cmd: &mut tokio::process::Command) {
    cmd.env("HF_HUB_CACHE", hub_dir());
}

/// [`apply_to`] for a synchronous command.
pub fn apply_to_std(cmd: &mut std::process::Command) {
    cmd.env("HF_HUB_CACHE", hub_dir());
}

/// A non-empty environment variable.
fn env(name: &str) -> Option<String> {
    std::env::var(name).ok().filter(|v| !v.is_empty())
}

fn token() -> Option<String> {
    if let Some(token) = env("HF_TOKEN") {
        return Some(token);
    }
    let path = match env("HF_TOKEN_PATH") {
        Some(path) => absolute(expand(&path, &env, home_dir().as_deref())),
        None => hf_home().join("token"),
    };
    std::fs::read_to_string(path)
        .ok()
        .map(|t| t.trim().to_string())
        .filter(|t| !t.is_empty())
}

/// The user's home, as Python's `expanduser` finds it: `HOME` on unix (when
/// set and non-empty), `USERPROFILE` on Windows (Python ignores `HOME` there
/// since 3.8), else the OS account database.
fn home_dir() -> Option<PathBuf> {
    let var = if cfg!(windows) { "USERPROFILE" } else { "HOME" };
    env(var)
        .map(PathBuf::from)
        .or_else(std::env::home_dir)
        .filter(|home| home.is_absolute())
}

fn absolute(path: PathBuf) -> PathBuf {
    if path.is_absolute() {
        return path;
    }
    std::path::absolute(&path).unwrap_or(path)
}

fn resolve(env: &dyn Fn(&str) -> Option<String>, home: Option<&Path>) -> PathBuf {
    for name in ["HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"] {
        if let Some(value) = env(name) {
            return expand(&value, env, home);
        }
    }
    // Python expands the defaulted hub path again on its way through
    // `HUGGINGFACE_HUB_CACHE`; an already-expanded path is unchanged by that.
    resolve_home(env, home).join("hub")
}

fn resolve_home(env: &dyn Fn(&str) -> Option<String>, home: Option<&Path>) -> PathBuf {
    if let Some(value) = env("HF_HOME") {
        return expand(&value, env, home);
    }
    let cache = match env("XDG_CACHE_HOME") {
        Some(xdg) => PathBuf::from(xdg),
        None => home.unwrap_or(Path::new(".")).join(".cache"),
    };
    expand(&cache.join("huggingface").to_string_lossy(), env, home)
}

/// Python's `expandvars(expanduser(value))`: a leading `~` becomes home first,
/// then `$NAME` and `${NAME}` (and `%NAME%` on Windows) are replaced when set
/// and left as written when not.
fn expand(value: &str, env: &dyn Fn(&str) -> Option<String>, home: Option<&Path>) -> PathBuf {
    let tilde = match (value.strip_prefix('~'), home) {
        // `\\` separates only on Windows, as in `ntpath.expanduser`.
        (Some(tail), Some(home))
            if tail.is_empty()
                || tail.starts_with('/')
                || (cfg!(windows) && tail.starts_with('\\')) =>
        {
            home.join(tail.trim_start_matches(['/', '\\']))
                .to_string_lossy()
                .into_owned()
        }
        _ => value.to_string(),
    };
    let dollar = expand_dollar(&tilde, env);
    PathBuf::from(if cfg!(windows) {
        expand_percent(&dollar, env)
    } else {
        dollar
    })
}

fn expand_dollar(value: &str, env: &dyn Fn(&str) -> Option<String>) -> String {
    let mut out = String::with_capacity(value.len());
    let mut rest = value;
    while let Some(i) = rest.find('$') {
        out.push_str(&rest[..i]);
        let after = &rest[i + 1..];
        let (name, consumed) = match after.strip_prefix('{') {
            Some(braced) => match braced.find('}') {
                Some(end) => (&braced[..end], end + 2),
                None => ("", 0),
            },
            None => {
                let end = after
                    .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
                    .unwrap_or(after.len());
                (&after[..end], end)
            }
        };
        match env(name).filter(|_| !name.is_empty()) {
            Some(v) => out.push_str(&v),
            None => out.push_str(&rest[i..i + 1 + consumed]),
        }
        // A bare `$` or an unterminated `${` consumed nothing and was kept.
        rest = &rest[i + 1 + consumed..];
    }
    out.push_str(rest);
    out
}

/// Windows `%NAME%`, as `ntpath.expandvars` reads it.
fn expand_percent(value: &str, env: &dyn Fn(&str) -> Option<String>) -> String {
    let mut out = String::with_capacity(value.len());
    let mut rest = value;
    while let Some(i) = rest.find('%') {
        out.push_str(&rest[..i]);
        let after = &rest[i + 1..];
        match after.find('%') {
            Some(end) if end > 0 => {
                let name = &after[..end];
                match env(name) {
                    Some(v) => out.push_str(&v),
                    None => out.push_str(&rest[i..i + end + 2]),
                }
                rest = &after[end + 1..];
            }
            _ => {
                out.push('%');
                rest = after;
            }
        }
    }
    out.push_str(rest);
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashMap;

    fn with(vars: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> {
        let map: HashMap<String, String> = vars
            .iter()
            .filter(|(_, v)| !v.is_empty())
            .map(|(k, v)| (k.to_string(), v.to_string()))
            .collect();
        move |name| map.get(name).cloned()
    }

    const HOME: &str = "/Users/someone";

    fn hub(vars: &[(&str, &str)]) -> PathBuf {
        resolve(&with(vars), Some(Path::new(HOME)))
    }

    fn home_of(vars: &[(&str, &str)]) -> PathBuf {
        resolve_home(&with(vars), Some(Path::new(HOME)))
    }

    /// The order `huggingface_hub/constants.py` uses, case by case.
    #[test]
    fn resolves_the_hub_the_way_the_python_library_does() {
        assert_eq!(
            hub(&[]),
            PathBuf::from("/Users/someone/.cache/huggingface/hub")
        );
        assert_eq!(
            hub(&[("XDG_CACHE_HOME", "/xdg")]),
            PathBuf::from("/xdg/huggingface/hub")
        );
        assert_eq!(
            hub(&[("HF_HOME", "/hf"), ("XDG_CACHE_HOME", "/xdg")]),
            PathBuf::from("/hf/hub")
        );
        assert_eq!(
            hub(&[("HUGGINGFACE_HUB_CACHE", "/legacy"), ("HF_HOME", "/hf")]),
            PathBuf::from("/legacy")
        );
        assert_eq!(
            hub(&[
                ("HF_HUB_CACHE", "/hub"),
                ("HUGGINGFACE_HUB_CACHE", "/legacy"),
                ("HF_HOME", "/hf"),
            ]),
            PathBuf::from("/hub")
        );
        assert_eq!(
            home_of(&[("HF_HOME", "~/hf")]),
            PathBuf::from("/Users/someone/hf")
        );
        assert_eq!(
            home_of(&[("XDG_CACHE_HOME", "~/xdg")]),
            PathBuf::from("/Users/someone/xdg/huggingface")
        );
    }

    /// An empty variable is unset — deliberately, where Python would take `""`
    /// and produce a relative `hub`.
    #[test]
    fn empty_variables_count_as_unset() {
        assert_eq!(
            hub(&[("HF_HUB_CACHE", ""), ("HF_HOME", "/hf")]),
            PathBuf::from("/hf/hub")
        );
        assert_eq!(
            hub(&[("HF_HOME", "")]),
            PathBuf::from("/Users/someone/.cache/huggingface/hub")
        );
    }

    #[test]
    fn expands_home_then_variables_as_python_does() {
        assert_eq!(
            hub(&[("HF_HOME", "~/hf")]),
            PathBuf::from("/Users/someone/hf/hub")
        );
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "~")]),
            PathBuf::from("/Users/someone")
        );
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "$ROOT/cache"), ("ROOT", "/data")]),
            PathBuf::from("/data/cache")
        );
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "${ROOT}/cache"), ("ROOT", "/data")]),
            PathBuf::from("/data/cache")
        );
        // `~` is expanded before variables, so a variable holding `~` stays.
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "$T/x"), ("T", "~")]),
            PathBuf::from("~/x")
        );
        // Unset, empty-named, bare and unterminated forms are kept as written.
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "$NOPE/c")]),
            PathBuf::from("$NOPE/c")
        );
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "/a/${}/b")]),
            PathBuf::from("/a/${}/b")
        );
        assert_eq!(hub(&[("HF_HUB_CACHE", "/a$")]), PathBuf::from("/a$"));
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "/a/${OPEN")]),
            PathBuf::from("/a/${OPEN")
        );
        // `~user` is not looked up.
        assert_eq!(
            hub(&[("HF_HUB_CACHE", "~root/x")]),
            PathBuf::from("~root/x")
        );
    }

    #[test]
    fn percent_variables_expand_as_windows_does() {
        let env = with(&[("LOCALAPPDATA", "C:\\Users\\me\\AppData\\Local")]);
        assert_eq!(
            expand_percent("%LOCALAPPDATA%\\hf", &env),
            "C:\\Users\\me\\AppData\\Local\\hf"
        );
        assert_eq!(expand_percent("%NOPE%\\hf", &env), "%NOPE%\\hf");
        assert_eq!(expand_percent("50%", &env), "50%");
    }

    /// With no home at all, the default is anchored rather than left relative,
    /// so no process resolves it against its own working directory.
    #[test]
    fn no_home_still_yields_an_absolute_hub() {
        let relative = resolve(&with(&[]), None);
        assert!(!relative.is_absolute(), "{relative:?}");
        assert!(relative.ends_with(".cache/huggingface/hub"));
        assert!(absolute(relative).is_absolute());
        assert!(absolute(PathBuf::from("rel/hub")).is_absolute());
    }

    #[test]
    fn a_repo_dir_is_the_hub_layout() {
        assert_eq!(
            repo_dir_in(Path::new("/h"), "mlx-community/Qwen3-4B-4bit"),
            PathBuf::from("/h/models--mlx-community--Qwen3-4B-4bit")
        );
    }

    /// A path built for deletion is exactly one `models--…` component.
    #[test]
    fn checked_repo_dirs_accept_only_hub_repo_ids() {
        let hub = Path::new("/h");
        assert_eq!(
            checked_repo_dir_in(hub, "mlx-community/Qwen3-4B-4bit"),
            Some(PathBuf::from("/h/models--mlx-community--Qwen3-4B-4bit"))
        );
        assert_eq!(
            checked_repo_dir_in(hub, "gpt2"),
            Some(PathBuf::from("/h/models--gpt2"))
        );
        for bad in [
            "", "/", "a/", "/b", "a/b/c", "..", "a/..", ".", "a\\..\\x", "a b/c", "a/b:c",
        ] {
            assert_eq!(checked_repo_dir_in(hub, bad), None, "{bad:?}");
        }
    }
}