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}