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 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}
102fn 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", "whispercpp"].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#[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 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#[cfg(not(unix))]
460fn file_identity(_metadata: &std::fs::Metadata) -> Option<FileIdentity> {
461 None
462}
463
464#[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 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(¤t)?;
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(¤t)?;
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 pub fn with_timeout(mut self, timeout: Duration) -> Self {
640 self.timeout = timeout;
641 self
642 }
643 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 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 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 let fifo = root.path().join("fifo");
1246 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}