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)]
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    fn emit(&self, completed: u64, artifact: &Artifact) {
644        if let Some(progress) = &self.progress {
645            progress(completed, artifact.bytes, &artifact.file);
646        }
647    }
648    pub async fn acquire(
649        &self,
650        artifact: &Artifact,
651        transport: &dyn DownloadTransport,
652        cancel: &CancellationToken,
653    ) -> Result<Acquired, String> {
654        self.acquire_sized(artifact, SizePolicy::Exact, transport, cancel)
655            .await
656    }
657    pub async fn acquire_sized(
658        &self,
659        artifact: &Artifact,
660        size: SizePolicy,
661        transport: &dyn DownloadTransport,
662        cancel: &CancellationToken,
663    ) -> Result<Acquired, String> {
664        let operation = async {
665            artifact.validate()?;
666            let coordinates: Vec<_> = artifact.repo.split('/').collect();
667            let owner = self.root.join(&artifact.backend).join(coordinates[0]);
668            self.cache_directory(&owner)?;
669            let repository = owner.join(format!("{}@{}", coordinates[1], artifact.revision));
670            let lock = ArtifactLock::acquire(suffix(&repository, ".repository.lock"))?;
671            let acquired = self
672                .acquire_inner(artifact, size, transport, cancel)
673                .await?;
674            lock.check()?;
675            Ok(acquired)
676        };
677        tokio::select! {biased;_=cancel.cancelled()=>Err("cancelled".into()),result=tokio::time::timeout(self.timeout,operation)=>result.map_err(|_|"acquisition timed out".to_owned())?}
678    }
679    async fn acquire_inner(
680        &self,
681        artifact: &Artifact,
682        size: SizePolicy,
683        transport: &dyn DownloadTransport,
684        cancel: &CancellationToken,
685    ) -> Result<Acquired, String> {
686        artifact.validate()?;
687        if cancel.is_cancelled() {
688            return Err("cancelled".into());
689        }
690        let coordinates: Vec<_> = artifact.repo.split('/').collect();
691        let directory = self
692            .root
693            .join(&artifact.backend)
694            .join(coordinates[0])
695            .join(format!("{}@{}", coordinates[1], artifact.revision));
696        let target = directory.join(&artifact.file);
697        let parent = target.parent().ok_or("missing artifact parent")?;
698        self.cache_directory(parent)?;
699        if !parent
700            .canonicalize()
701            .map_err(|error| error.to_string())?
702            .starts_with(&self.root)
703        {
704            return Err("cache escaped root".into());
705        }
706        let lock = ArtifactLock::acquire(suffix(&target, ".lock"))?;
707        cleanup_partials(parent, crate::state::process_alive)?;
708        self.emit(0, artifact);
709        if let Ok(metadata) = std::fs::symlink_metadata(&target) {
710            if !metadata.is_file() || metadata.file_type().is_symlink() {
711                return Err("unsafe cached artifact".into());
712            }
713            if size.accepts(metadata.len(), artifact.bytes)
714                && self.already_verified(&target, artifact, &metadata)
715            {
716                lock.check()?;
717                self.emit(metadata.len(), artifact);
718                return Ok(Acquired {
719                    path: target,
720                    bytes: metadata.len(),
721                    cached: true,
722                    rehashed: false,
723                });
724            }
725            let (sha, bytes) = hash_file(&target, cancel).await?;
726            if sha.eq_ignore_ascii_case(&artifact.sha256) && size.accepts(bytes, artifact.bytes) {
727                lock.check()?;
728                self.record_verified(&target, artifact, file_identity(&metadata));
729                self.emit(bytes, artifact);
730                return Ok(Acquired {
731                    path: target,
732                    bytes,
733                    cached: true,
734                    rehashed: true,
735                });
736            }
737        }
738        let mut url =
739            url::Url::parse("https://huggingface.co").map_err(|error| error.to_string())?;
740        {
741            let mut path = url.path_segments_mut().map_err(|_| "invalid URL base")?;
742            path.extend(coordinates)
743                .push("resolve")
744                .push(&artifact.revision)
745                .extend(artifact.file.split('/'));
746        }
747        url.set_query(Some("download=true"));
748        let operation = async {
749            let mut response = transport.get(url.as_str()).await?;
750            if !(200..300).contains(&response.status) {
751                return Err(format!("download HTTP {}", response.status));
752            }
753            if response
754                .commit
755                .as_ref()
756                .is_none_or(|commit| !commit.eq_ignore_ascii_case(&artifact.revision))
757            {
758                return Err("resolved commit mismatch".into());
759            }
760            if response
761                .length
762                .is_some_and(|length| length > artifact.bytes)
763            {
764                return Err("download exceeds byte limit".into());
765            }
766            let temporary = tempfile::Builder::new()
767                .prefix(&format!(".llmup-download.{}.", std::process::id()))
768                .suffix(".part")
769                .tempfile_in(parent)
770                .map_err(|error| error.to_string())?;
771            let mut output =
772                tokio::fs::File::from_std(temporary.reopen().map_err(|error| error.to_string())?);
773            let mut hash = Sha256::new();
774            let mut total = 0u64;
775            let mut reported = 0u64;
776            let mut buffer = vec![0u8; 65536];
777            let mut resumes = 0u32;
778            loop {
779                let count = match response.body.read(&mut buffer).await {
780                    Ok(count) => count,
781                    Err(error) => {
782                        // Transport failures on the resume request itself share the bounded
783                        // budget, so one blip after a dropped body does not discard the download.
784                        let mut failure = error.to_string();
785                        let resumed = loop {
786                            resumes += 1;
787                            if resumes > MAX_RESUMES {
788                                return Err(failure);
789                            }
790                            tokio::time::sleep(Duration::from_secs(u64::from(resumes.min(5))))
791                                .await;
792                            match transport.get_from(url.as_str(), total).await {
793                                Ok(resumed) => break resumed,
794                                Err(resume) => failure = format!("{error}; {resume}"),
795                            }
796                        };
797                        response = resumed;
798                        if response.status != 206
799                            || response.commit.as_ref().is_none_or(|commit| {
800                                !commit.eq_ignore_ascii_case(&artifact.revision)
801                            })
802                            || response
803                                .length
804                                .is_some_and(|length| length > artifact.bytes - total)
805                        {
806                            return Err("download resume response mismatch".into());
807                        }
808                        continue;
809                    }
810                };
811                if count == 0 {
812                    break;
813                }
814                total = total
815                    .checked_add(count as u64)
816                    .ok_or("download size overflow")?;
817                if total > artifact.bytes {
818                    return Err("download exceeds byte limit".into());
819                }
820                hash.update(&buffer[..count]);
821                output
822                    .write_all(&buffer[..count])
823                    .await
824                    .map_err(|error| error.to_string())?;
825                if total - reported >= 8 * 1024 * 1024 {
826                    self.emit(total, artifact);
827                    reported = total;
828                }
829            }
830            if !size.accepts(total, artifact.bytes)
831                || !format!("{:x}", hash.finalize()).eq_ignore_ascii_case(&artifact.sha256)
832            {
833                return Err("artifact integrity mismatch".into());
834            }
835            output.sync_all().await.map_err(|error| error.to_string())?;
836            drop(output);
837            lock.check()?;
838            if cancel.is_cancelled() {
839                return Err("cancelled".into());
840            }
841            temporary
842                .persist(&target)
843                .map_err(|error| error.to_string())?;
844            self.record_verified(&target, artifact, None);
845            self.emit(total, artifact);
846            Ok(Acquired {
847                path: target.clone(),
848                bytes: total,
849                cached: false,
850                rehashed: false,
851            })
852        };
853        tokio::select! { _=cancel.cancelled()=>Err("cancelled".into()), result=tokio::time::timeout(self.timeout,operation)=>result.map_err(|_|"download timed out".to_owned())? }
854    }
855    pub async fn repository(
856        &self,
857        artifacts: &[Artifact],
858        transport: &dyn DownloadTransport,
859        cancel: &CancellationToken,
860    ) -> Result<PathBuf, String> {
861        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())?}
862    }
863    async fn repository_inner(
864        &self,
865        artifacts: &[Artifact],
866        transport: &dyn DownloadTransport,
867        cancel: &CancellationToken,
868    ) -> Result<PathBuf, String> {
869        let first = artifacts.first().ok_or("empty repository manifest")?;
870        if artifacts.len() > 256 {
871            return Err("repository file count exceeds limit".into());
872        }
873        let mut names = HashSet::new();
874        let mut root = None;
875        for artifact in artifacts {
876            artifact.validate()?;
877            if ["py", "pyc", "pyo", "so", "dylib", "dll", "bundle"]
878                .iter()
879                .any(|extension| {
880                    artifact
881                        .file
882                        .to_ascii_lowercase()
883                        .ends_with(&format!(".{extension}"))
884                })
885            {
886                return Err("executable repository artifact forbidden".into());
887            }
888            if artifact.repo != first.repo
889                || artifact.revision != first.revision
890                || artifact.backend != first.backend
891                || !names.insert(artifact.file.clone())
892            {
893                return Err("inconsistent repository manifest".into());
894            }
895        }
896        let folded: HashSet<_> = names.iter().map(|name| name.to_lowercase()).collect();
897        if folded.len() != names.len()
898            || folded.iter().any(|name| {
899                name.match_indices('/')
900                    .any(|(index, _)| folded.contains(&name[..index]))
901            })
902        {
903            return Err("repository contains path aliases or file/directory collisions".into());
904        }
905        if first.backend == "mlx"
906            && (artifacts.len() < 3
907                || !names.contains("config.json")
908                || !names.contains("tokenizer_config.json")
909                || !names.iter().any(|name| name.ends_with(".safetensors")))
910        {
911            return Err("incomplete MLX repository manifest".into());
912        }
913        let total = artifacts
914            .iter()
915            .try_fold(0u64, |total, artifact| total.checked_add(artifact.bytes))
916            .ok_or("repository byte total overflow")?;
917        if total > 9007199254740991 {
918            return Err("repository byte total exceeds safe integer".into());
919        }
920        let coordinates: Vec<_> = first.repo.split('/').collect();
921        let owner = self.root.join(&first.backend).join(coordinates[0]);
922        self.cache_directory(&owner)?;
923        let repository = owner.join(format!("{}@{}", coordinates[1], first.revision));
924        let lock = ArtifactLock::acquire(suffix(&repository, ".repository.lock"))?;
925        for artifact in artifacts {
926            let acquired = self
927                .acquire_inner(artifact, SizePolicy::Exact, transport, cancel)
928                .await?;
929            let mut directory = acquired.path;
930            for _ in artifact.file.split('/') {
931                directory.pop();
932            }
933            if root.as_ref().is_some_and(|prior| prior != &directory) {
934                return Err("repository root mismatch".into());
935            }
936            root = Some(directory);
937        }
938        let root = root.ok_or("missing repository root")?;
939        fn list(root: &Path, path: &Path, files: &mut HashSet<String>) -> Result<(), String> {
940            for entry in std::fs::read_dir(path).map_err(|error| error.to_string())? {
941                let entry = entry.map_err(|error| error.to_string())?;
942                let kind = entry.file_type().map_err(|error| error.to_string())?;
943                if kind.is_symlink() {
944                    return Err("symlink in repository".into());
945                }
946                if kind.is_dir() {
947                    list(root, &entry.path(), files)?;
948                } else if kind.is_file() {
949                    files.insert(
950                        entry
951                            .path()
952                            .strip_prefix(root)
953                            .map_err(|error| error.to_string())?
954                            .to_string_lossy()
955                            .replace('\\', "/"),
956                    );
957                } else {
958                    return Err("special file in repository".into());
959                }
960            }
961            Ok(())
962        }
963        let mut actual = HashSet::new();
964        list(&root, &root, &mut actual)?;
965        if actual != names {
966            return Err("repository content differs from manifest".into());
967        }
968        lock.check()?;
969        Ok(root)
970    }
971}