Skip to main content

rigspark_runtime/
acquire.rs

1use async_trait::async_trait;
2use futures_util::TryStreamExt;
3use serde::{Deserialize, Serialize};
4use sha2::{Digest, Sha256};
5use std::{
6    collections::HashSet,
7    path::{Path, PathBuf},
8    pin::Pin,
9    time::Duration,
10};
11use tokio::io::{AsyncRead, AsyncReadExt, AsyncWriteExt};
12use tokio_util::{io::StreamReader, sync::CancellationToken};
13
14#[derive(Debug, Clone, Deserialize, Serialize)]
15#[serde(deny_unknown_fields)]
16pub struct Artifact {
17    pub backend: String,
18    pub repo: String,
19    pub revision: String,
20    pub file: String,
21    pub sha256: String,
22    pub bytes: u64,
23}
24pub struct DownloadResponse {
25    pub status: u16,
26    pub commit: Option<String>,
27    pub length: Option<u64>,
28    pub body: Pin<Box<dyn AsyncRead + Send>>,
29}
30#[async_trait]
31pub trait DownloadTransport: Send + Sync {
32    async fn get(&self, url: &str) -> Result<DownloadResponse, String>;
33    /// Continues a download at `offset`; transports without range support refuse.
34    async fn get_from(&self, url: &str, offset: u64) -> Result<DownloadResponse, String> {
35        if offset == 0 {
36            self.get(url).await
37        } else {
38            Err("download resume unsupported".into())
39        }
40    }
41}
42const MAX_RESUMES: u32 = 8;
43pub struct HfTransport {
44    client: reqwest::Client,
45}
46fn retain_commit(evidence: &mut Option<String>, observed: Option<&str>) -> Result<(), String> {
47    if let Some(observed) = observed {
48        if observed.len() != 40 || !observed.bytes().all(|byte| byte.is_ascii_hexdigit()) {
49            return Err("invalid repository commit evidence".into());
50        }
51        if evidence
52            .as_ref()
53            .is_some_and(|previous| !previous.eq_ignore_ascii_case(observed))
54        {
55            return Err("conflicting repository commit evidence".into());
56        }
57        *evidence = Some(observed.to_owned());
58    }
59    Ok(())
60}
61#[test]
62fn commit_evidence_survives_cdn_redirects_and_rejects_conflicts() {
63    let revision = "a".repeat(40);
64    let mut evidence = None;
65    retain_commit(&mut evidence, Some(&revision)).unwrap();
66    retain_commit(&mut evidence, None).unwrap();
67    assert_eq!(evidence.as_deref(), Some(revision.as_str()));
68    assert!(retain_commit(&mut evidence, Some(&"b".repeat(40))).is_err());
69    assert!(retain_commit(&mut None, Some("not-a-commit")).is_err());
70    let mut absent = None;
71    retain_commit(&mut absent, None).unwrap();
72    assert!(absent.is_none());
73}
74impl HfTransport {
75    pub fn new() -> Result<Self, String> {
76        Ok(Self {
77            client: reqwest::Client::builder()
78                .redirect(reqwest::redirect::Policy::none())
79                .no_proxy()
80                .dns_resolver(std::sync::Arc::new(PublicResolver))
81                .connect_timeout(Duration::from_secs(10))
82                .build()
83                .map_err(|error| error.to_string())?,
84        })
85    }
86}
87fn safe_url(raw: &str) -> Result<url::Url, String> {
88    let url = url::Url::parse(raw).map_err(|error| error.to_string())?;
89    let host = url.host_str().ok_or("missing download host")?;
90    if url.scheme() != "https"
91        || !url.username().is_empty()
92        || url.password().is_some()
93        || url.port().is_some()
94        || !["huggingface.co", "hf.co"]
95            .iter()
96            .any(|allowed| host == *allowed || host.ends_with(&format!(".{allowed}")))
97    {
98        return Err("download URL is not approved HTTPS source".into());
99    }
100    Ok(url)
101}
102/// Accepts only `bytes <offset>-<end>/<total>` so a resume can never splice the wrong range.
103fn content_range_starts_at(value: Option<&str>, offset: u64) -> bool {
104    value
105        .and_then(|value| value.strip_prefix("bytes "))
106        .and_then(|range| range.split_once('-'))
107        .and_then(|(start, _)| start.parse::<u64>().ok())
108        == Some(offset)
109}
110#[test]
111fn resume_requires_matching_content_range() {
112    assert!(content_range_starts_at(Some("bytes 40-99/100"), 40));
113    assert!(!content_range_starts_at(Some("bytes 0-99/100"), 40));
114    assert!(!content_range_starts_at(Some("items 40-99/100"), 40));
115    assert!(!content_range_starts_at(None, 40));
116}
117#[async_trait]
118impl DownloadTransport for HfTransport {
119    async fn get(&self, raw: &str) -> Result<DownloadResponse, String> {
120        self.get_from(raw, 0).await
121    }
122    async fn get_from(&self, raw: &str, offset: u64) -> Result<DownloadResponse, String> {
123        let mut url = safe_url(raw)?;
124        let mut commit = None;
125        for redirect in 0..=5 {
126            let mut request = self.client.get(url.clone());
127            if offset > 0 {
128                request = request.header("range", format!("bytes={offset}-"));
129            }
130            let response = request
131                .send()
132                .await
133                .map_err(|_| "download transport failed".to_owned())?;
134            retain_commit(
135                &mut commit,
136                response
137                    .headers()
138                    .get("x-repo-commit")
139                    .map(|value| {
140                        value
141                            .to_str()
142                            .map_err(|_| "invalid repository commit header".to_owned())
143                    })
144                    .transpose()?,
145            )?;
146            if response.status().is_redirection() {
147                if redirect == 5 {
148                    return Err("too many download redirects".into());
149                }
150                let location = response
151                    .headers()
152                    .get("location")
153                    .and_then(|value| value.to_str().ok())
154                    .ok_or("redirect has no location")?;
155                url = safe_url(
156                    url.join(location)
157                        .map_err(|error| error.to_string())?
158                        .as_str(),
159                )?;
160                continue;
161            }
162            let length = response.content_length();
163            let status = response.status().as_u16();
164            if offset > 0
165                && (status != 206
166                    || !content_range_starts_at(
167                        response
168                            .headers()
169                            .get("content-range")
170                            .and_then(|value| value.to_str().ok()),
171                        offset,
172                    ))
173            {
174                return Err("download resume was not honored".into());
175            }
176            let stream = response.bytes_stream().map_err(std::io::Error::other);
177            return Ok(DownloadResponse {
178                status,
179                commit,
180                length,
181                body: Box::pin(StreamReader::new(stream)),
182            });
183        }
184        Err("download redirect limit".into())
185    }
186}
187
188pub fn public_addresses(
189    addresses: Vec<std::net::SocketAddr>,
190) -> Result<Vec<std::net::SocketAddr>, String> {
191    fn public(address: std::net::IpAddr) -> bool {
192        match address {
193            std::net::IpAddr::V4(address) => {
194                let octets = address.octets();
195                !address.is_private()
196                    && !address.is_loopback()
197                    && !address.is_link_local()
198                    && !address.is_multicast()
199                    && !address.is_unspecified()
200                    && !address.is_broadcast()
201                    && !address.is_documentation()
202                    && octets[0] != 0
203                    && octets[0] < 224
204                    && !(octets[0] == 100 && (64..=127).contains(&octets[1]))
205                    && !(octets[0] == 198 && (18..=19).contains(&octets[1]))
206                    && !(octets[0] == 192 && octets[1] == 0 && octets[2] == 0)
207            }
208            std::net::IpAddr::V6(address) => {
209                if let Some(mapped) = address.to_ipv4_mapped() {
210                    return public(mapped.into());
211                }
212                let segments = address.segments();
213                segments[0] & 0xe000 == 0x2000
214                    && segments[0] != 0x2002
215                    && !(segments[0] == 0x2001 && (segments[1] < 0x200 || segments[1] == 0xdb8))
216            }
217        }
218    }
219    if addresses.is_empty()
220        || addresses.len() > 64
221        || addresses.iter().any(|address| !public(address.ip()))
222    {
223        return Err("download DNS contains private or unsupported addresses".into());
224    }
225    Ok(addresses)
226}
227struct PublicResolver;
228impl reqwest::dns::Resolve for PublicResolver {
229    fn resolve(&self, name: reqwest::dns::Name) -> reqwest::dns::Resolving {
230        Box::pin(async move {
231            let addresses = tokio::time::timeout(
232                Duration::from_secs(5),
233                tokio::net::lookup_host((name.as_str(), 0)),
234            )
235            .await
236            .map_err(|_| std::io::Error::other("download DNS timed out"))??;
237            let addresses =
238                public_addresses(addresses.take(65).collect()).map_err(std::io::Error::other)?;
239            Ok(Box::new(addresses.into_iter()) as reqwest::dns::Addrs)
240        })
241    }
242}
243
244#[derive(Debug)]
245pub struct Acquired {
246    pub path: PathBuf,
247    pub bytes: u64,
248    pub cached: bool,
249    pub rehashed: bool,
250}
251#[derive(Debug, Clone, Copy, PartialEq, Eq)]
252pub enum SizePolicy {
253    Exact,
254    Ceiling,
255}
256impl SizePolicy {
257    fn accepts(self, actual: u64, expected: u64) -> bool {
258        actual > 0
259            && match self {
260                Self::Exact => actual == expected,
261                Self::Ceiling => actual <= expected,
262            }
263    }
264}
265pub struct Acquisition {
266    root: PathBuf,
267    progress: Option<std::sync::Arc<Progress>>,
268    timeout: Duration,
269}
270type Progress = dyn Fn(u64, u64, &str) + Send + Sync;
271
272struct ArtifactLock {
273    guard: crate::state::LockGuard,
274}
275impl ArtifactLock {
276    fn acquire(path: PathBuf) -> Result<Self, String> {
277        let mut config =
278            crate::state::Config::from_home(path.parent().ok_or("missing lock parent")?)
279                .map_err(|error| error.to_string())?;
280        config.lock = path;
281        let guard = crate::state::StateStore::new(config)
282            .lock(Duration::ZERO)
283            .map_err(|error| error.to_string())?;
284        Ok(Self { guard })
285    }
286    fn check(&self) -> Result<(), String> {
287        self.guard.assert_owned().map_err(|error| error.to_string())
288    }
289}
290fn suffix(path: &Path, suffix: &str) -> PathBuf {
291    let mut value = path.as_os_str().to_owned();
292    value.push(suffix);
293    PathBuf::from(value)
294}
295pub fn cleanup_partials(parent: &Path, alive: impl Fn(u32) -> bool) -> Result<(), String> {
296    for (index, entry) in std::fs::read_dir(parent)
297        .map_err(|error| error.to_string())?
298        .enumerate()
299    {
300        if index >= 10000 {
301            return Err("cache directory exceeds cleanup entry limit".into());
302        }
303        let entry = entry.map_err(|error| error.to_string())?;
304        let name = entry.file_name();
305        let Some(name) = name.to_str() else {
306            continue;
307        };
308        let Some(rest) = name
309            .strip_prefix(".llmup-download.")
310            .and_then(|value| value.strip_suffix(".part"))
311        else {
312            continue;
313        };
314        let Some((pid, unique)) = rest.split_once('.') else {
315            continue;
316        };
317        if unique.is_empty()
318            || unique.contains('.')
319            || !pid.bytes().all(|byte| byte.is_ascii_digit())
320            || pid.starts_with('0')
321        {
322            continue;
323        }
324        let Some(pid) = pid
325            .parse::<u32>()
326            .ok()
327            .filter(|pid| *pid > 0 && *pid <= i32::MAX as u32)
328        else {
329            continue;
330        };
331        if entry
332            .file_type()
333            .map_err(|error| error.to_string())?
334            .is_file()
335            && !alive(pid)
336        {
337            std::fs::remove_file(entry.path()).map_err(|error| error.to_string())?;
338        }
339    }
340    Ok(())
341}
342fn segment(value: &str) -> bool {
343    !value.is_empty()
344        && portable_component(value)
345        && value.as_bytes()[0].is_ascii_alphanumeric()
346        && value
347            .bytes()
348            .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte))
349}
350fn portable_component(value: &str) -> bool {
351    let base = value.split('.').next().unwrap_or("").to_ascii_uppercase();
352    !value.is_empty()
353        && value != "."
354        && value != ".."
355        && !value.ends_with('.')
356        && value.trim() == value
357        && !["CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$"].contains(&base.as_str())
358        && !(base.starts_with("COM") || base.starts_with("LPT"))
359            .then(|| &base[3..])
360            .is_some_and(|suffix| {
361                [
362                    "1", "2", "3", "4", "5", "6", "7", "8", "9", "\u{b9}", "\u{b2}", "\u{b3}",
363                ]
364                .contains(&suffix)
365            })
366}
367pub fn safe_file(value: &str) -> bool {
368    !value.is_empty()
369        && value.len() <= 512
370        && !value
371            .chars()
372            .any(|ch| ch.is_control() || "\\%*?[]{}:".contains(ch))
373        && value.split('/').all(portable_component)
374}
375fn digest(value: &str, length: usize) -> bool {
376    value.len() == length && value.bytes().all(|byte| byte.is_ascii_hexdigit())
377}
378impl Artifact {
379    pub fn validate(&self) -> Result<(), String> {
380        let coordinates: Vec<_> = self.repo.split('/').collect();
381        if !["llamacpp", "mlx", "comfyui", "bitnet"].contains(&self.backend.as_str())
382            || coordinates.len() != 2
383            || !coordinates.iter().all(|part| segment(part))
384            || !digest(&self.revision, 40)
385            || !digest(&self.sha256, 64)
386            || !safe_file(&self.file)
387            || self.bytes == 0
388            || self.bytes > 9007199254740991
389        {
390            return Err("invalid pinned artifact".into());
391        }
392        Ok(())
393    }
394}
395fn private_directory(path: &Path) -> Result<(), String> {
396    match std::fs::symlink_metadata(path) {
397        Ok(metadata) => {
398            if !metadata.is_dir() || metadata.file_type().is_symlink() {
399                return Err("unsafe cache directory".into());
400            }
401        }
402        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
403            if let Some(parent) = path.parent() {
404                private_directory(parent)?;
405            }
406            let builder = std::fs::DirBuilder::new();
407            #[cfg(unix)]
408            let mut builder = builder;
409            #[cfg(unix)]
410            {
411                use std::os::unix::fs::DirBuilderExt;
412                builder.mode(0o700);
413            }
414            match builder.create(path) {
415                Ok(()) => (),
416                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
417                    return private_directory(path);
418                }
419                Err(error) => return Err(error.to_string()),
420            }
421        }
422        Err(error) => return Err(error.to_string()),
423    }
424    Ok(())
425}
426const VERIFIED_DIRECTORY: &str = ".verified";
427const MAX_STAMP_BYTES: u64 = 4096;
428
429/// File identity that changes on any write, rename, or replacement. `changed` (ctime)
430/// is maintained by the kernel and cannot be set back by an unprivileged process.
431#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
432#[serde(rename_all = "camelCase", deny_unknown_fields)]
433struct FileIdentity {
434    device: u64,
435    inode: u64,
436    modified: i64,
437    modified_nanos: i64,
438    changed: i64,
439    changed_nanos: i64,
440}
441#[cfg(unix)]
442fn file_identity(metadata: &std::fs::Metadata) -> Option<FileIdentity> {
443    use std::os::unix::fs::MetadataExt;
444    // Whole-second filesystems (HFS+, FAT) report zero nanoseconds; a same-size edit within
445    // that second would keep the identity, so those caches always take the full hash.
446    if metadata.mtime_nsec() == 0 && metadata.ctime_nsec() == 0 {
447        return None;
448    }
449    Some(FileIdentity {
450        device: metadata.dev(),
451        inode: metadata.ino(),
452        modified: metadata.mtime(),
453        modified_nanos: metadata.mtime_nsec(),
454        changed: metadata.ctime(),
455        changed_nanos: metadata.ctime_nsec(),
456    })
457}
458/// Without a kernel-maintained change time every cache hit is fully re-hashed.
459#[cfg(not(unix))]
460fn file_identity(_metadata: &std::fs::Metadata) -> Option<FileIdentity> {
461    None
462}
463
464/// Records that a file with this exact identity already matched its pinned digest.
465/// It lives in the same owner-only cache as the weights, so it adds no trust beyond
466/// the cache itself; any mismatch or unreadable stamp falls back to a full hash.
467#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
468#[serde(rename_all = "camelCase", deny_unknown_fields)]
469struct VerifiedStamp {
470    file: String,
471    sha256: String,
472    bytes: u64,
473    identity: FileIdentity,
474}
475
476fn open_no_follow(path: &Path) -> std::io::Result<std::fs::File> {
477    let mut options = std::fs::OpenOptions::new();
478    options.read(true);
479    #[cfg(unix)]
480    {
481        use std::os::unix::fs::OpenOptionsExt;
482        options.custom_flags(
483            (rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::NONBLOCK).bits() as i32,
484        );
485    }
486    options.open(path)
487}
488pub async fn hash_file(path: &Path, cancel: &CancellationToken) -> Result<(String, u64), String> {
489    let file = open_no_follow(path).map_err(|error| error.to_string())?;
490    if !file
491        .metadata()
492        .map_err(|error| error.to_string())?
493        .is_file()
494        || std::fs::symlink_metadata(path)
495            .map_err(|error| error.to_string())?
496            .file_type()
497            .is_symlink()
498    {
499        return Err("artifact is not a regular file".into());
500    }
501    let mut file = tokio::fs::File::from_std(file);
502    let mut hash = Sha256::new();
503    let mut total = 0u64;
504    let mut buffer = vec![0u8; 65536];
505    loop {
506        let count = tokio::select! { _=cancel.cancelled()=>return Err("cancelled".into()), result=file.read(&mut buffer)=>result.map_err(|error|error.to_string())? };
507        if count == 0 {
508            break;
509        }
510        total = total
511            .checked_add(count as u64)
512            .ok_or("artifact size overflow")?;
513        hash.update(&buffer[..count]);
514    }
515    Ok((format!("{:x}", hash.finalize()), total))
516}
517impl Acquisition {
518    fn stamp(
519        &self,
520        target: &Path,
521        artifact: &Artifact,
522        metadata: &std::fs::Metadata,
523    ) -> Option<(PathBuf, VerifiedStamp)> {
524        let file = target.strip_prefix(&self.root).ok()?.to_str()?.to_owned();
525        let key = format!("{:x}", Sha256::digest(file.as_bytes()));
526        Some((
527            self.root
528                .join(VERIFIED_DIRECTORY)
529                .join(format!("{key}.json")),
530            VerifiedStamp {
531                file,
532                sha256: artifact.sha256.to_ascii_lowercase(),
533                bytes: metadata.len(),
534                identity: file_identity(metadata)?,
535            },
536        ))
537    }
538    fn already_verified(
539        &self,
540        target: &Path,
541        artifact: &Artifact,
542        metadata: &std::fs::Metadata,
543    ) -> bool {
544        let Some((path, expected)) = self.stamp(target, artifact, metadata) else {
545            return false;
546        };
547        let Ok(file) = open_no_follow(&path) else {
548            return false;
549        };
550        if !file.metadata().is_ok_and(|stamp| stamp.is_file()) {
551            return false;
552        }
553        let mut raw = Vec::new();
554        use std::io::Read;
555        if file
556            .take(MAX_STAMP_BYTES + 1)
557            .read_to_end(&mut raw)
558            .is_err()
559            || raw.len() as u64 > MAX_STAMP_BYTES
560        {
561            return false;
562        }
563        serde_json::from_slice::<VerifiedStamp>(&raw).is_ok_and(|stamp| stamp == expected)
564    }
565    /// Best effort: a missing stamp only costs a full hash on the next cache hit.
566    fn record_verified(&self, target: &Path, artifact: &Artifact, verified: Option<FileIdentity>) {
567        let _ = (|| -> Result<(), String> {
568            let metadata = std::fs::symlink_metadata(target).map_err(|error| error.to_string())?;
569            if !metadata.is_file() || metadata.file_type().is_symlink() {
570                return Err("unsafe cached artifact".into());
571            }
572            let (path, stamp) = self
573                .stamp(target, artifact, &metadata)
574                .ok_or("no stable file identity")?;
575            if verified.is_some_and(|identity| identity != stamp.identity) {
576                return Err("artifact changed while it was being verified".into());
577            }
578            let directory = path.parent().ok_or("missing stamp directory")?;
579            private_directory(directory)?;
580            let mut temporary = tempfile::Builder::new()
581                .prefix(".stamp.")
582                .tempfile_in(directory)
583                .map_err(|error| error.to_string())?;
584            use std::io::Write;
585            temporary
586                .write_all(&serde_json::to_vec(&stamp).map_err(|error| error.to_string())?)
587                .map_err(|error| error.to_string())?;
588            temporary
589                .persist(&path)
590                .map_err(|error| error.to_string())?;
591            Ok(())
592        })();
593    }
594    fn cache_directory(&self, path: &Path) -> Result<(), String> {
595        let relative = path
596            .strip_prefix(&self.root)
597            .map_err(|_| "cache path escaped root")?;
598        let mut current = self.root.clone();
599        private_directory(&current)?;
600        for component in relative.components() {
601            let std::path::Component::Normal(name) = component else {
602                return Err("invalid cache path component".into());
603            };
604            current.push(name);
605            private_directory(&current)?;
606            if !current
607                .canonicalize()
608                .map_err(|error| error.to_string())?
609                .starts_with(&self.root)
610            {
611                return Err("cache path escaped root".into());
612            }
613        }
614        Ok(())
615    }
616    pub fn new(root: impl AsRef<Path>) -> Result<Self, String> {
617        let root = std::path::absolute(root).map_err(|error| error.to_string())?;
618        private_directory(&root)?;
619        #[cfg(unix)]
620        {
621            use std::os::unix::fs::PermissionsExt;
622            std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700))
623                .map_err(|error| error.to_string())?;
624        }
625        Ok(Self {
626            root: root.canonicalize().map_err(|error| error.to_string())?,
627            progress: None,
628            timeout: Duration::from_secs(1800),
629        })
630    }
631    pub fn with_progress(
632        mut self,
633        progress: impl Fn(u64, u64, &str) + Send + Sync + 'static,
634    ) -> Self {
635        self.progress = Some(std::sync::Arc::new(progress));
636        self
637    }
638    /// Overrides the default 30 minute limit for multi-gigabyte artifacts.
639    pub fn with_timeout(mut self, timeout: Duration) -> Self {
640        self.timeout = timeout;
641        self
642    }
643    /// Reports progress against `total`, the real size when known; a size ceiling is a
644    /// limit, not a size, so it is never shown as the total.
645    fn emit(&self, completed: u64, total: u64, artifact: &Artifact) {
646        if let Some(progress) = &self.progress {
647            progress(completed, total.max(completed), &artifact.file);
648        }
649    }
650    pub async fn acquire(
651        &self,
652        artifact: &Artifact,
653        transport: &dyn DownloadTransport,
654        cancel: &CancellationToken,
655    ) -> Result<Acquired, String> {
656        self.acquire_sized(artifact, SizePolicy::Exact, transport, cancel)
657            .await
658    }
659    pub async fn acquire_sized(
660        &self,
661        artifact: &Artifact,
662        size: SizePolicy,
663        transport: &dyn DownloadTransport,
664        cancel: &CancellationToken,
665    ) -> Result<Acquired, String> {
666        let operation = async {
667            artifact.validate()?;
668            let coordinates: Vec<_> = artifact.repo.split('/').collect();
669            let owner = self.root.join(&artifact.backend).join(coordinates[0]);
670            self.cache_directory(&owner)?;
671            let repository = owner.join(format!("{}@{}", coordinates[1], artifact.revision));
672            let lock = ArtifactLock::acquire(suffix(&repository, ".repository.lock"))?;
673            let acquired = self
674                .acquire_inner(artifact, size, transport, cancel)
675                .await?;
676            lock.check()?;
677            Ok(acquired)
678        };
679        tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(self.timeout,operation)=>result.map_err(|_|"acquisition timed out".to_owned())?}
680    }
681    async fn acquire_inner(
682        &self,
683        artifact: &Artifact,
684        size: SizePolicy,
685        transport: &dyn DownloadTransport,
686        cancel: &CancellationToken,
687    ) -> Result<Acquired, String> {
688        artifact.validate()?;
689        if cancel.is_cancelled() {
690            return Err("cancelled".into());
691        }
692        let coordinates: Vec<_> = artifact.repo.split('/').collect();
693        let directory = self
694            .root
695            .join(&artifact.backend)
696            .join(coordinates[0])
697            .join(format!("{}@{}", coordinates[1], artifact.revision));
698        let target = directory.join(&artifact.file);
699        let parent = target.parent().ok_or("missing artifact parent")?;
700        self.cache_directory(parent)?;
701        if !parent
702            .canonicalize()
703            .map_err(|error| error.to_string())?
704            .starts_with(&self.root)
705        {
706            return Err("cache escaped root".into());
707        }
708        let lock = ArtifactLock::acquire(suffix(&target, ".lock"))?;
709        cleanup_partials(parent, crate::state::process_alive)?;
710        if size == SizePolicy::Exact {
711            self.emit(0, artifact.bytes, artifact);
712        }
713        if let Ok(metadata) = std::fs::symlink_metadata(&target) {
714            if !metadata.is_file() || metadata.file_type().is_symlink() {
715                return Err("unsafe cached artifact".into());
716            }
717            if size.accepts(metadata.len(), artifact.bytes)
718                && self.already_verified(&target, artifact, &metadata)
719            {
720                lock.check()?;
721                self.emit(metadata.len(), metadata.len(), artifact);
722                return Ok(Acquired {
723                    path: target,
724                    bytes: metadata.len(),
725                    cached: true,
726                    rehashed: false,
727                });
728            }
729            let (sha, bytes) = hash_file(&target, cancel).await?;
730            if sha.eq_ignore_ascii_case(&artifact.sha256) && size.accepts(bytes, artifact.bytes) {
731                lock.check()?;
732                self.record_verified(&target, artifact, file_identity(&metadata));
733                self.emit(bytes, bytes, artifact);
734                return Ok(Acquired {
735                    path: target,
736                    bytes,
737                    cached: true,
738                    rehashed: true,
739                });
740            }
741        }
742        let mut url =
743            url::Url::parse("https://huggingface.co").map_err(|error| error.to_string())?;
744        {
745            let mut path = url.path_segments_mut().map_err(|_| "invalid URL base")?;
746            path.extend(coordinates)
747                .push("resolve")
748                .push(&artifact.revision)
749                .extend(artifact.file.split('/'));
750        }
751        url.set_query(Some("download=true"));
752        let operation = async {
753            let mut response = transport.get(url.as_str()).await?;
754            if !(200..300).contains(&response.status) {
755                return Err(format!("download HTTP {}", response.status));
756            }
757            if response
758                .commit
759                .as_ref()
760                .is_none_or(|commit| !commit.eq_ignore_ascii_case(&artifact.revision))
761            {
762                return Err("resolved commit mismatch".into());
763            }
764            if response
765                .length
766                .is_some_and(|length| length > artifact.bytes)
767            {
768                return Err("download exceeds byte limit".into());
769            }
770            let expected = match size {
771                SizePolicy::Exact => artifact.bytes,
772                SizePolicy::Ceiling => response.length.unwrap_or(0),
773            };
774            if expected > 0 {
775                self.emit(0, expected, artifact);
776            }
777            let temporary = tempfile::Builder::new()
778                .prefix(&format!(".llmup-download.{}.", std::process::id()))
779                .suffix(".part")
780                .tempfile_in(parent)
781                .map_err(|error| error.to_string())?;
782            let mut output =
783                tokio::fs::File::from_std(temporary.reopen().map_err(|error| error.to_string())?);
784            let mut hash = Sha256::new();
785            let mut total = 0u64;
786            let mut reported = 0u64;
787            let mut buffer = vec![0u8; 65536];
788            let mut resumes = 0u32;
789            loop {
790                let count = match response.body.read(&mut buffer).await {
791                    Ok(count) => count,
792                    Err(error) => {
793                        // Transport failures on the resume request itself share the bounded
794                        // budget, so one blip after a dropped body does not discard the download.
795                        let mut failure = error.to_string();
796                        let resumed = loop {
797                            resumes += 1;
798                            if resumes > MAX_RESUMES {
799                                return Err(failure);
800                            }
801                            tokio::time::sleep(Duration::from_secs(u64::from(resumes.min(5))))
802                                .await;
803                            match transport.get_from(url.as_str(), total).await {
804                                Ok(resumed) => break resumed,
805                                Err(resume) => failure = format!("{error}; {resume}"),
806                            }
807                        };
808                        response = resumed;
809                        if response.status != 206
810                            || response.commit.as_ref().is_none_or(|commit| {
811                                !commit.eq_ignore_ascii_case(&artifact.revision)
812                            })
813                            || response
814                                .length
815                                .is_some_and(|length| length > artifact.bytes - total)
816                        {
817                            return Err("download resume response mismatch".into());
818                        }
819                        continue;
820                    }
821                };
822                if count == 0 {
823                    break;
824                }
825                total = total
826                    .checked_add(count as u64)
827                    .ok_or("download size overflow")?;
828                if total > artifact.bytes {
829                    return Err("download exceeds byte limit".into());
830                }
831                hash.update(&buffer[..count]);
832                output
833                    .write_all(&buffer[..count])
834                    .await
835                    .map_err(|error| error.to_string())?;
836                if total - reported >= 8 * 1024 * 1024 {
837                    self.emit(total, expected, artifact);
838                    reported = total;
839                }
840            }
841            if !size.accepts(total, artifact.bytes)
842                || !format!("{:x}", hash.finalize()).eq_ignore_ascii_case(&artifact.sha256)
843            {
844                return Err("artifact integrity mismatch".into());
845            }
846            output.sync_all().await.map_err(|error| error.to_string())?;
847            drop(output);
848            lock.check()?;
849            if cancel.is_cancelled() {
850                return Err("cancelled".into());
851            }
852            temporary
853                .persist(&target)
854                .map_err(|error| error.to_string())?;
855            self.record_verified(&target, artifact, None);
856            self.emit(total, total, artifact);
857            Ok(Acquired {
858                path: target.clone(),
859                bytes: total,
860                cached: false,
861                rehashed: false,
862            })
863        };
864        tokio::select! { _=cancel.cancelled()=>Err("cancelled".into()), result=tokio::time::timeout(self.timeout,operation)=>result.map_err(|_|"download timed out".to_owned())? }
865    }
866    pub async fn repository(
867        &self,
868        artifacts: &[Artifact],
869        transport: &dyn DownloadTransport,
870        cancel: &CancellationToken,
871    ) -> Result<PathBuf, String> {
872        tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(Duration::from_secs(1800),self.repository_inner(artifacts,transport,cancel))=>result.map_err(|_|"repository acquisition timed out".to_owned())?}
873    }
874    async fn repository_inner(
875        &self,
876        artifacts: &[Artifact],
877        transport: &dyn DownloadTransport,
878        cancel: &CancellationToken,
879    ) -> Result<PathBuf, String> {
880        let first = artifacts.first().ok_or("empty repository manifest")?;
881        if artifacts.len() > 256 {
882            return Err("repository file count exceeds limit".into());
883        }
884        let mut names = HashSet::new();
885        let mut root = None;
886        for artifact in artifacts {
887            artifact.validate()?;
888            if ["py", "pyc", "pyo", "so", "dylib", "dll", "bundle"]
889                .iter()
890                .any(|extension| {
891                    artifact
892                        .file
893                        .to_ascii_lowercase()
894                        .ends_with(&format!(".{extension}"))
895                })
896            {
897                return Err("executable repository artifact forbidden".into());
898            }
899            if artifact.repo != first.repo
900                || artifact.revision != first.revision
901                || artifact.backend != first.backend
902                || !names.insert(artifact.file.clone())
903            {
904                return Err("inconsistent repository manifest".into());
905            }
906        }
907        let folded: HashSet<_> = names.iter().map(|name| name.to_lowercase()).collect();
908        if folded.len() != names.len()
909            || folded.iter().any(|name| {
910                name.match_indices('/')
911                    .any(|(index, _)| folded.contains(&name[..index]))
912            })
913        {
914            return Err("repository contains path aliases or file/directory collisions".into());
915        }
916        if first.backend == "mlx"
917            && (artifacts.len() < 3
918                || !names.contains("config.json")
919                || !names.contains("tokenizer_config.json")
920                || !names.iter().any(|name| name.ends_with(".safetensors")))
921        {
922            return Err("incomplete MLX repository manifest".into());
923        }
924        let total = artifacts
925            .iter()
926            .try_fold(0u64, |total, artifact| total.checked_add(artifact.bytes))
927            .ok_or("repository byte total overflow")?;
928        if total > 9007199254740991 {
929            return Err("repository byte total exceeds safe integer".into());
930        }
931        let coordinates: Vec<_> = first.repo.split('/').collect();
932        let owner = self.root.join(&first.backend).join(coordinates[0]);
933        self.cache_directory(&owner)?;
934        let repository = owner.join(format!("{}@{}", coordinates[1], first.revision));
935        let lock = ArtifactLock::acquire(suffix(&repository, ".repository.lock"))?;
936        for artifact in artifacts {
937            let acquired = self
938                .acquire_inner(artifact, SizePolicy::Exact, transport, cancel)
939                .await?;
940            let mut directory = acquired.path;
941            for _ in artifact.file.split('/') {
942                directory.pop();
943            }
944            if root.as_ref().is_some_and(|prior| prior != &directory) {
945                return Err("repository root mismatch".into());
946            }
947            root = Some(directory);
948        }
949        let root = root.ok_or("missing repository root")?;
950        fn list(root: &Path, path: &Path, files: &mut HashSet<String>) -> Result<(), String> {
951            for entry in std::fs::read_dir(path).map_err(|error| error.to_string())? {
952                let entry = entry.map_err(|error| error.to_string())?;
953                let kind = entry.file_type().map_err(|error| error.to_string())?;
954                if kind.is_symlink() {
955                    return Err("symlink in repository".into());
956                }
957                if kind.is_dir() {
958                    list(root, &entry.path(), files)?;
959                } else if kind.is_file() {
960                    files.insert(
961                        entry
962                            .path()
963                            .strip_prefix(root)
964                            .map_err(|error| error.to_string())?
965                            .to_string_lossy()
966                            .replace('\\', "/"),
967                    );
968                } else {
969                    return Err("special file in repository".into());
970                }
971            }
972            Ok(())
973        }
974        let mut actual = HashSet::new();
975        list(&root, &root, &mut actual)?;
976        if actual != names {
977            return Err("repository content differs from manifest".into());
978        }
979        lock.check()?;
980        Ok(root)
981    }
982}
983
984#[cfg(test)]
985mod boundary_tests {
986    use super::*;
987
988    struct Plain;
989    #[async_trait]
990    impl DownloadTransport for Plain {
991        async fn get(&self, _url: &str) -> Result<DownloadResponse, String> {
992            Ok(DownloadResponse {
993                status: 200,
994                commit: None,
995                length: Some(0),
996                body: Box::pin(std::io::Cursor::new(Vec::new())),
997            })
998        }
999    }
1000
1001    #[tokio::test]
1002    async fn transports_without_ranges_only_start_from_zero() {
1003        assert_eq!(
1004            Plain.get_from("https://hf.co/x", 0).await.unwrap().status,
1005            200
1006        );
1007        assert!(Plain.get_from("https://hf.co/x", 5).await.is_err());
1008    }
1009
1010    #[test]
1011    fn commit_evidence_is_exactly_forty_hex_digits() {
1012        assert!(retain_commit(&mut None, Some(&"a".repeat(39))).is_err());
1013        assert!(retain_commit(&mut None, Some(&"g".repeat(40))).is_err());
1014        assert!(retain_commit(&mut None, Some(&"A".repeat(40))).is_ok());
1015    }
1016
1017    #[test]
1018    fn downloads_come_only_from_hugging_face_over_plain_https() {
1019        for good in [
1020            "https://huggingface.co/a/b",
1021            "https://hf.co/a/b",
1022            "https://cdn-lfs.huggingface.co/x",
1023            "https://cas-bridge.xethub.hf.co/x",
1024        ] {
1025            assert!(safe_url(good).is_ok(), "{good}");
1026        }
1027        for bad in [
1028            "http://huggingface.co/a/b",
1029            "https://user@huggingface.co/a/b",
1030            "https://user:pass@huggingface.co/a/b",
1031            "https://:pass@huggingface.co/a/b",
1032            "https://huggingface.co:8443/a/b",
1033            "https://evilhuggingface.co/a/b",
1034            "https://huggingface.co.evil.com/a/b",
1035            "https://example.com/a/b",
1036        ] {
1037            assert!(safe_url(bad).is_err(), "{bad}");
1038        }
1039    }
1040
1041    fn addresses(ips: &[&str]) -> Vec<std::net::SocketAddr> {
1042        ips.iter()
1043            .map(|ip| std::net::SocketAddr::new(ip.parse().unwrap(), 443))
1044            .collect()
1045    }
1046
1047    #[test]
1048    fn download_dns_must_resolve_only_to_public_addresses() {
1049        for good in [
1050            "8.8.8.8",
1051            "100.63.255.255",
1052            "100.128.0.1",
1053            "198.17.255.255",
1054            "198.20.0.1",
1055            "192.0.1.1",
1056            "223.255.255.255",
1057            "2606:4700::1",
1058            "2001:200::1",
1059            "::ffff:8.8.8.8",
1060        ] {
1061            assert!(public_addresses(addresses(&[good])).is_ok(), "{good}");
1062        }
1063        for bad in [
1064            "10.0.0.1",
1065            "127.0.0.1",
1066            "169.254.1.1",
1067            "0.1.2.3",
1068            "224.0.0.1",
1069            "240.0.0.1",
1070            "255.255.255.255",
1071            "192.0.2.1",
1072            "100.64.0.1",
1073            "100.127.255.255",
1074            "198.18.0.1",
1075            "198.19.255.255",
1076            "192.0.0.8",
1077            "::1",
1078            "fe80::1",
1079            "fc00::1",
1080            "2002::1",
1081            "2001:1ff::1",
1082            "2001:db8::1",
1083            "::ffff:10.0.0.1",
1084        ] {
1085            assert!(public_addresses(addresses(&[bad])).is_err(), "{bad}");
1086        }
1087        assert!(public_addresses(Vec::new()).is_err());
1088        assert!(public_addresses(addresses(&["8.8.8.8", "10.0.0.1"])).is_err());
1089        assert!(public_addresses(addresses(&["8.8.8.8"; 64])).is_ok());
1090        assert!(public_addresses(addresses(&["8.8.8.8"; 65])).is_err());
1091    }
1092
1093    #[test]
1094    fn size_policies_never_accept_an_empty_file() {
1095        assert!(SizePolicy::Exact.accepts(5, 5));
1096        assert!(!SizePolicy::Exact.accepts(4, 5));
1097        assert!(SizePolicy::Ceiling.accepts(1, 5));
1098        assert!(SizePolicy::Ceiling.accepts(5, 5));
1099        assert!(!SizePolicy::Ceiling.accepts(6, 5));
1100        assert!(!SizePolicy::Exact.accepts(0, 0));
1101        assert!(!SizePolicy::Ceiling.accepts(0, 5));
1102    }
1103
1104    #[test]
1105    fn only_dead_processes_partial_downloads_are_removed() {
1106        let root = tempfile::tempdir().unwrap();
1107        let keep = [
1108            ".llmup-download.123.abc.part.extra",
1109            ".llmup-download.123..part",
1110            ".llmup-download.123.a.b.part",
1111            ".llmup-download.12x.abc.part",
1112            ".llmup-download.0123.abc.part",
1113            ".llmup-download.0.abc.part",
1114            ".llmup-download.2147483648.abc.part",
1115            ".llmup-download.123abc.part",
1116            "weights.gguf",
1117        ];
1118        for name in keep {
1119            std::fs::write(root.path().join(name), b"x").unwrap();
1120        }
1121        std::fs::write(root.path().join(".llmup-download.123.abc.part"), b"x").unwrap();
1122        std::fs::write(
1123            root.path().join(".llmup-download.2147483647.xyz.part"),
1124            b"x",
1125        )
1126        .unwrap();
1127        std::fs::write(root.path().join(".llmup-download.7.live.part"), b"x").unwrap();
1128        std::fs::create_dir(root.path().join(".llmup-download.124.dir.part")).unwrap();
1129        cleanup_partials(root.path(), |pid| pid == 7).unwrap();
1130        let mut left: Vec<String> = std::fs::read_dir(root.path())
1131            .unwrap()
1132            .map(|entry| entry.unwrap().file_name().into_string().unwrap())
1133            .collect();
1134        left.sort();
1135        let mut expected: Vec<String> = keep.iter().map(|name| (*name).to_owned()).collect();
1136        expected.extend([
1137            ".llmup-download.7.live.part".to_owned(),
1138            ".llmup-download.124.dir.part".to_owned(),
1139        ]);
1140        expected.sort();
1141        assert_eq!(left, expected);
1142    }
1143
1144    fn artifact() -> Artifact {
1145        Artifact {
1146            backend: "llamacpp".into(),
1147            repo: "owner/repo".into(),
1148            revision: "a".repeat(40),
1149            file: "models/weights.gguf".into(),
1150            sha256: "b".repeat(64),
1151            bytes: 1,
1152        }
1153    }
1154
1155    #[test]
1156    fn pinned_artifacts_name_one_safe_repository_file_and_digest() {
1157        assert!(artifact().validate().is_ok());
1158        let mut max = artifact();
1159        max.bytes = 9007199254740991;
1160        assert!(max.validate().is_ok());
1161        for backend in ["mlx", "comfyui", "bitnet"] {
1162            let mut ok = artifact();
1163            ok.backend = backend.into();
1164            assert!(ok.validate().is_ok(), "{backend}");
1165        }
1166        type Edit = Box<dyn Fn(&mut Artifact)>;
1167        let cases: Vec<Edit> = vec![
1168            Box::new(|a| a.backend = "ollama".into()),
1169            Box::new(|a| a.repo = "owner".into()),
1170            Box::new(|a| a.repo = "owner/repo/extra".into()),
1171            Box::new(|a| a.repo = "owner/.repo".into()),
1172            Box::new(|a| a.repo = "-owner/repo".into()),
1173            Box::new(|a| a.repo = "owner/re po".into()),
1174            Box::new(|a| a.repo = "owner/con".into()),
1175            Box::new(|a| a.repo = "/repo".into()),
1176            Box::new(|a| a.revision = "a".repeat(39)),
1177            Box::new(|a| a.revision = "g".repeat(40)),
1178            Box::new(|a| a.sha256 = "b".repeat(63)),
1179            Box::new(|a| a.sha256 = "z".repeat(64)),
1180            Box::new(|a| a.file = "../weights.gguf".into()),
1181            Box::new(|a| a.file = "a\\b.gguf".into()),
1182            Box::new(|a| a.file = "weights*.gguf".into()),
1183            Box::new(|a| a.file = "w\u{7}.gguf".into()),
1184            Box::new(|a| a.file = String::new()),
1185            Box::new(|a| a.file = "a".repeat(513)),
1186            Box::new(|a| a.bytes = 0),
1187            Box::new(|a| a.bytes = 9007199254740992),
1188        ];
1189        for (index, mutate) in cases.iter().enumerate() {
1190            let mut value = artifact();
1191            mutate(&mut value);
1192            assert!(value.validate().is_err(), "case {index}: {value:?}");
1193        }
1194        assert!(safe_file(&"a".repeat(512)));
1195        assert!(!safe_file("a/b:c"));
1196    }
1197
1198    #[test]
1199    fn digests_are_exact_length_hex() {
1200        assert!(digest("abc", 3));
1201        assert!(!digest("abc", 4));
1202        assert!(!digest("abz", 3));
1203    }
1204
1205    #[cfg(unix)]
1206    #[test]
1207    fn cache_directories_are_created_private_and_never_followed() {
1208        use std::os::unix::fs::PermissionsExt;
1209        let root = tempfile::tempdir().unwrap();
1210        let nested = root.path().join("a/b/c");
1211        private_directory(&nested).unwrap();
1212        assert_eq!(
1213            std::fs::metadata(&nested).unwrap().permissions().mode() & 0o777,
1214            0o700
1215        );
1216        // Existing directories are accepted again; files and symlinks are refused.
1217        private_directory(&nested).unwrap();
1218        let file = root.path().join("file");
1219        std::fs::write(&file, b"x").unwrap();
1220        assert!(private_directory(&file).is_err());
1221        assert!(private_directory(&file.join("below")).is_err());
1222        let link = root.path().join("link");
1223        std::os::unix::fs::symlink(&nested, &link).unwrap();
1224        assert!(private_directory(&link).is_err());
1225    }
1226
1227    #[cfg(unix)]
1228    #[tokio::test]
1229    async fn hashing_refuses_symlinks_and_non_files() {
1230        let root = tempfile::tempdir().unwrap();
1231        let file = root.path().join("weights");
1232        std::fs::write(&file, b"weights").unwrap();
1233        let (sha, bytes) = hash_file(&file, &CancellationToken::new()).await.unwrap();
1234        assert_eq!(bytes, 7);
1235        assert_eq!(sha, format!("{:x}", Sha256::digest(b"weights")));
1236        let link = root.path().join("link");
1237        std::os::unix::fs::symlink(&file, &link).unwrap();
1238        assert!(hash_file(&link, &CancellationToken::new()).await.is_err());
1239        assert!(
1240            hash_file(root.path(), &CancellationToken::new())
1241                .await
1242                .is_err()
1243        );
1244        // A FIFO must not block the open: it is refused as a non-file.
1245        let fifo = root.path().join("fifo");
1246        // `mkfifo` is POSIX; rustix's `mknodat` is not available on macOS.
1247        assert!(
1248            std::process::Command::new("mkfifo")
1249                .arg(&fifo)
1250                .status()
1251                .unwrap()
1252                .success()
1253        );
1254        let hashed = tokio::time::timeout(
1255            Duration::from_secs(5),
1256            hash_file(&fifo, &CancellationToken::new()),
1257        )
1258        .await
1259        .expect("opening a FIFO must not block");
1260        assert!(hashed.is_err());
1261    }
1262
1263    #[cfg(unix)]
1264    #[test]
1265    fn file_identity_tracks_device_inode_and_change_times() {
1266        let root = tempfile::tempdir().unwrap();
1267        let file = root.path().join("weights");
1268        std::fs::write(&file, b"a").unwrap();
1269        let first = file_identity(&std::fs::metadata(&file).unwrap());
1270        if let Some(first) = first {
1271            use std::os::unix::fs::MetadataExt;
1272            let metadata = std::fs::metadata(&file).unwrap();
1273            assert_eq!(
1274                (first.device, first.inode, first.modified, first.changed),
1275                (
1276                    metadata.dev(),
1277                    metadata.ino(),
1278                    metadata.mtime(),
1279                    metadata.ctime()
1280                )
1281            );
1282            std::thread::sleep(Duration::from_millis(20));
1283            std::fs::write(&file, b"b").unwrap();
1284            let second = file_identity(&std::fs::metadata(&file).unwrap()).unwrap();
1285            assert_ne!(first, second);
1286        }
1287    }
1288}