pub mod api;
pub mod client;
pub mod download;
pub mod oci;
pub mod progress;
pub mod pull;
pub mod transfer;
use std::path::PathBuf;
use std::time::Duration;
use anyhow::{anyhow, Context, Result};
use serde::Deserialize;
pub fn is_hf_host(server: &str) -> bool {
let host = server
.trim_start_matches("https://")
.trim_start_matches("http://")
.split('/')
.next()
.unwrap_or(server)
.to_ascii_lowercase();
matches!(
host.as_str(),
"hf.co" | "huggingface.co" | "www.huggingface.co"
)
}
pub fn endpoint() -> String {
std::env::var("HF_ENDPOINT")
.ok()
.filter(|v| !v.is_empty())
.unwrap_or_else(|| "https://huggingface.co".to_string())
.trim_end_matches('/')
.to_string()
}
fn hf_home() -> PathBuf {
if let Ok(dir) = std::env::var("HF_HOME") {
if !dir.is_empty() {
return PathBuf::from(dir);
}
}
dirs::home_dir()
.unwrap_or_else(|| PathBuf::from("."))
.join(".cache")
.join("huggingface")
}
const DEFAULT_MAX_TRANSFER_STREAMS: usize = 4;
pub fn max_transfer_streams() -> usize {
parse_max_transfer_streams(std::env::var("LLMMAN_MAX_TRANSFER_STREAMS").ok().as_deref())
}
fn parse_max_transfer_streams(value: Option<&str>) -> usize {
match value.map(str::trim).and_then(|v| v.parse::<usize>().ok()) {
None => DEFAULT_MAX_TRANSFER_STREAMS,
Some(n) => n.max(1),
}
}
pub fn token_path() -> PathBuf {
if let Ok(p) = std::env::var("HF_TOKEN_PATH") {
if !p.is_empty() {
return PathBuf::from(p);
}
}
hf_home().join("token")
}
pub fn token() -> Option<String> {
for var in ["HF_TOKEN", "HUGGING_FACE_HUB_TOKEN"] {
if let Ok(t) = std::env::var(var) {
let t = t.trim().to_string();
if !t.is_empty() {
return Some(t);
}
}
}
std::fs::read_to_string(token_path())
.ok()
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
}
#[derive(Deserialize)]
struct WhoAmI {
name: Option<String>,
}
pub fn whoami(token: &str) -> Result<String> {
let client = reqwest::blocking::Client::builder()
.timeout(Duration::from_secs(30))
.build()
.context("build http client")?;
let resp = client
.get(format!("{}/api/whoami-v2", endpoint()))
.header("authorization", format!("Bearer {token}"))
.send()
.context("request whoami-v2")?;
let status = resp.status();
if status == reqwest::StatusCode::UNAUTHORIZED {
anyhow::bail!("invalid user token");
}
if !status.is_success() {
let body = resp.text().unwrap_or_default();
anyhow::bail!("whoami-v2 returned {status}: {body}");
}
let info: WhoAmI = resp.json().context("parse whoami-v2 response")?;
info.name
.ok_or_else(|| anyhow!("whoami-v2 response missing \"name\""))
}
pub fn login(token: &str) -> Result<String> {
let username = whoami(token)?;
let path = token_path();
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).with_context(|| format!("create {}", parent.display()))?;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let _ = std::fs::set_permissions(parent, std::fs::Permissions::from_mode(0o700));
}
}
#[cfg(unix)]
{
use std::io::Write as _;
use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
std::fs::OpenOptions::new()
.write(true)
.create(true)
.truncate(true)
.mode(0o600)
.open(&path)
.and_then(|mut f| {
f.set_permissions(std::fs::Permissions::from_mode(0o600))?;
f.write_all(token.trim().as_bytes())
})
.with_context(|| format!("write {}", path.display()))?;
}
#[cfg(not(unix))]
std::fs::write(&path, token.trim()).with_context(|| format!("write {}", path.display()))?;
Ok(username)
}
pub fn logout() -> Result<()> {
let path = token_path();
match std::fs::remove_file(&path) {
Ok(()) => Ok(()),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(e) => Err(e).context(format!("remove {}", path.display())),
}
}
fn is_known_oci_host(host: &str) -> bool {
matches!(
host,
"ghcr.io"
| "docker.io"
| "index.docker.io"
| "registry-1.docker.io"
| "quay.io"
| "gcr.io"
| "mcr.microsoft.com"
| "public.ecr.aws"
)
}
pub(crate) fn is_known_hf_host(host: &str) -> bool {
matches!(host, "hf.co" | "huggingface.co" | "modelscope.cn")
}
async fn is_oci_registry(host: &str) -> bool {
let Ok(client) = reqwest::Client::builder()
.timeout(Duration::from_secs(5))
.build()
else {
return false;
};
for scheme in ["https", "http"] {
let Ok(resp) = client
.get(format!("{scheme}://{host}/v2/"))
.timeout(Duration::from_secs(3))
.send()
.await
else {
continue;
};
let headers = resp.headers();
if headers.contains_key("docker-distribution-api-version") {
return true;
}
if resp.status() == reqwest::StatusCode::UNAUTHORIZED
&& headers.contains_key("www-authenticate")
{
return true;
}
}
false
}
pub async fn is_oci_host(host: &str) -> bool {
if is_known_hf_host(host) {
return false;
}
if is_known_oci_host(host) || crate::config::has_registry_mirrors(host) {
return true;
}
is_oci_registry(host).await
}
pub enum ClassifiedRef {
Hf(String),
Source(String),
Other(String),
}
pub async fn classify(reference: &str) -> ClassifiedRef {
for prefix in ["hf://", "huggingface://"] {
if let Some(rest) = reference.strip_prefix(prefix) {
let host_less = rest.split('/').filter(|s| !s.is_empty()).count() == 2;
return ClassifiedRef::Hf(if host_less {
format!("huggingface.co/{rest}")
} else {
rest.to_string()
});
}
}
if crate::sources::handles(reference) {
return ClassifiedRef::Source(reference.to_string());
}
if reference.contains("://") || reference.starts_with('/') {
return ClassifiedRef::Other(reference.to_string());
}
let normalized = if reference.rfind(':').unwrap_or(0) <= reference.rfind('/').unwrap_or(0) {
format!("{reference}:latest")
} else {
reference.to_string()
};
let host = normalized.split('/').next().unwrap_or(&normalized);
if !is_oci_host(host).await {
ClassifiedRef::Hf(normalized)
} else {
ClassifiedRef::Other(normalized)
}
}
pub fn hf_endpoint(host: &str) -> String {
for var in ["MODEL_ENDPOINT", "HF_ENDPOINT"] {
if let Ok(v) = std::env::var(var) {
if !v.is_empty() {
return format!("{}/", v.trim_end_matches('/'));
}
}
}
if host == "hf.co" {
"https://huggingface.co/".to_string()
} else {
format!("https://{host}/")
}
}
pub(crate) fn api_client() -> Result<reqwest::Client> {
reqwest::Client::builder()
.timeout(Duration::from_secs(120))
.build()
.context("build HF API client")
}
pub(crate) fn download_client() -> Result<reqwest::Client> {
reqwest::Client::builder()
.connect_timeout(Duration::from_secs(30))
.tcp_keepalive(Duration::from_secs(30))
.read_timeout(Duration::from_secs(60))
.build()
.context("build HF download client")
}
pub(crate) fn head_client() -> Result<reqwest::Client> {
reqwest::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.build()
.context("build no-redirect HTTP client")
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn is_hf_host_matches_known_hosts_case_insensitively() {
assert!(is_hf_host("hf.co"));
assert!(is_hf_host("HuggingFace.co"));
assert!(is_hf_host("https://huggingface.co"));
assert!(is_hf_host("www.huggingface.co"));
assert!(!is_hf_host("registry.example.com"));
assert!(!is_hf_host("docker.io"));
assert!(!is_hf_host("modelscope.cn"));
}
#[test]
fn parse_max_transfer_streams_defaults_to_four_on_unset_or_unparseable() {
assert_eq!(parse_max_transfer_streams(None), 4);
assert_eq!(parse_max_transfer_streams(Some("")), 4);
assert_eq!(parse_max_transfer_streams(Some("garbage")), 4);
assert_eq!(parse_max_transfer_streams(Some("8")), 8);
assert_eq!(parse_max_transfer_streams(Some(" 2 ")), 2);
}
#[test]
fn parse_max_transfer_streams_clamps_an_explicit_zero_to_one() {
assert_eq!(parse_max_transfer_streams(Some("0")), 1);
}
#[test]
fn is_known_hf_host_includes_modelscope() {
assert!(is_known_hf_host("modelscope.cn"));
assert!(is_known_hf_host("huggingface.co"));
assert!(!is_known_hf_host("docker.io"));
}
#[test]
fn is_known_oci_host_matches_the_usual_registries() {
assert!(is_known_oci_host("docker.io"));
assert!(is_known_oci_host("ghcr.io"));
assert!(!is_known_oci_host("huggingface.co"));
}
#[tokio::test]
async fn classify_strips_hf_scheme_prefixes_and_defaults_the_host() {
match classify("hf://owner/repo:tag").await {
ClassifiedRef::Hf(r) => assert_eq!(r, "huggingface.co/owner/repo:tag"),
_ => panic!("expected Hf"),
}
match classify("huggingface://owner/repo").await {
ClassifiedRef::Hf(r) => assert_eq!(r, "huggingface.co/owner/repo"),
_ => panic!("expected Hf"),
}
}
#[tokio::test]
async fn classify_leaves_an_explicit_host_after_the_hf_scheme_alone() {
match classify("hf://modelscope.cn/owner/repo").await {
ClassifiedRef::Hf(r) => assert_eq!(r, "modelscope.cn/owner/repo"),
_ => panic!("expected Hf"),
}
}
#[tokio::test]
async fn classify_routes_every_uri_scheme_source_and_local_path_to_sources() {
for r in [
"ms://owner/repo",
"modelscope://owner/repo",
"ngc://org/team/model",
"s3://bucket/key",
"gs://bucket/key",
"/abs/path",
] {
match classify(r).await {
ClassifiedRef::Source(got) => assert_eq!(got, r),
_ => panic!("expected Source for {r}"),
}
}
}
#[tokio::test]
async fn classify_leaves_an_unknown_scheme_alone() {
match classify("wat://owner/repo").await {
ClassifiedRef::Other(got) => assert_eq!(got, "wat://owner/repo"),
_ => panic!("expected Other"),
}
}
#[tokio::test]
async fn classify_treats_a_known_registry_host_as_other() {
match classify("docker.io/library/alpine").await {
ClassifiedRef::Other(got) => assert_eq!(got, "docker.io/library/alpine:latest"),
_ => panic!("expected Other"),
}
}
#[tokio::test]
async fn classify_treats_a_bare_hf_host_as_hf() {
match classify("huggingface.co/owner/repo").await {
ClassifiedRef::Hf(got) => assert_eq!(got, "huggingface.co/owner/repo:latest"),
_ => panic!("expected Hf"),
}
}
#[test]
fn hf_endpoint_defaults_hf_co_to_the_canonical_huggingface_domain() {
assert_eq!(hf_endpoint("hf.co"), "https://huggingface.co/");
}
#[test]
fn hf_endpoint_uses_the_host_verbatim_otherwise() {
assert_eq!(hf_endpoint("modelscope.cn"), "https://modelscope.cn/");
}
}