1pub mod curl;
25pub mod registry;
26pub mod runtime;
27
28use std::path::{Path, PathBuf};
29
30use hearth_core::sha256;
31use hearth_resolve::Reference;
32use hearth_store::{EventRef, Spine, Transition};
33
34pub use registry::{Blob, Fetched};
35
36#[derive(Debug, Clone)]
38pub struct PullConfig {
39 pub blobs_dir: PathBuf,
41 pub progress: bool,
45 pub verify_existing: bool,
49}
50
51impl Default for PullConfig {
52 fn default() -> Self {
53 PullConfig {
54 blobs_dir: PathBuf::from("./blobs"),
55 progress: true,
56 verify_existing: false,
57 }
58 }
59}
60
61#[derive(Debug, Clone, PartialEq, Eq)]
63pub struct Pulled {
64 pub model: String,
65 pub source: String,
67 pub weights_path: PathBuf,
69 pub bytes: u64,
70 pub already_had_it: bool,
73}
74
75pub fn blob_path(blobs_dir: &Path, digest: &str) -> PathBuf {
78 blobs_dir.join(format!("sha256-{}", sha256::normalize(digest)))
79}
80
81pub fn fetch_blob(blob: &Blob, cfg: &PullConfig) -> Result<(PathBuf, u64, bool), String> {
88 let final_path = blob_path(&cfg.blobs_dir, &blob.digest);
89
90 if final_path.exists() {
91 let len = std::fs::metadata(&final_path).map(|m| m.len()).unwrap_or(0);
92 if cfg.verify_existing {
93 let actual = sha256::hex_digest_file(&final_path)
94 .map_err(|e| format!("could not read {}: {e}", final_path.display()))?;
95 if !sha256::matches(&blob.digest, &actual) {
96 eprintln!(
99 "hearth: {} does not match its own name — refetching",
100 final_path.display()
101 );
102 let _ = std::fs::remove_file(&final_path);
103 } else {
104 return Ok((final_path, len, true));
105 }
106 } else if blob.size_bytes == 0 || len == blob.size_bytes {
107 return Ok((final_path, len, true));
108 } else {
109 eprintln!(
112 "hearth: {} is {len} bytes, expected {} — refetching",
113 final_path.display(),
114 blob.size_bytes
115 );
116 let _ = std::fs::remove_file(&final_path);
117 }
118 }
119
120 let partial = final_path.with_extension("partial");
121 let req = {
122 let mut r = curl::Request::get(&blob.url).to_file(&partial);
123 for (k, v) in &blob.headers {
124 r = r.header(k, v);
125 }
126 if partial.exists() && std::fs::metadata(&partial).map(|m| m.len()).unwrap_or(0) > 0 {
129 r = r.resuming();
130 }
131 r
132 };
133
134 curl::fetch_file(&req, cfg.progress).map_err(|e| e.0)?;
135
136 let actual = sha256::hex_digest_file(&partial)
137 .map_err(|e| format!("could not hash {}: {e}", partial.display()))?;
138 if !sha256::matches(&blob.digest, &actual) {
139 let _ = std::fs::remove_file(&partial);
142 return Err(format!(
143 "digest mismatch for {}\n expected sha256:{}\n got sha256:{}\n \
144 the file has been deleted; a resumed transfer over a proxy that \
145 rewrote a range will do this, so a plain retry is worth one attempt",
146 blob.name,
147 sha256::normalize(&blob.digest),
148 actual
149 ));
150 }
151
152 let len = std::fs::metadata(&partial).map(|m| m.len()).unwrap_or(0);
153 std::fs::rename(&partial, &final_path)
154 .map_err(|e| format!("could not commit {}: {e}", final_path.display()))?;
155 Ok((final_path, len, false))
156}
157
158pub fn pull(reference: &str, cfg: &PullConfig, spine: &Spine) -> Result<Pulled, String> {
165 let reference = Reference::parse(reference).map_err(|e| e.0)?;
166 let model = reference.display_name();
167 let source = registry::source_string(&reference);
168
169 if let Reference::Local { path } = &reference {
171 let p = PathBuf::from(path);
172 if !p.exists() {
173 return Err(format!("no file at {path}"));
174 }
175 let bytes = std::fs::metadata(&p).map(|m| m.len()).unwrap_or(0);
176 return Ok(Pulled {
177 model,
178 source,
179 weights_path: p,
180 bytes,
181 already_had_it: true,
182 });
183 }
184
185 let started = spine
186 .record(
187 &model,
188 &Transition::PullStarted {
189 source: source.clone(),
190 },
191 &[],
192 )
193 .map_err(|e| format!("could not record the pull: {e}"))?;
194
195 let fetched = registry::resolve_blobs(&reference).map_err(|e| {
196 let _ = spine.record(
199 &model,
200 &Transition::PullStarted {
201 source: format!("{source} — FAILED: {e}"),
202 },
203 std::slice::from_ref(&started),
204 );
205 e
206 })?;
207
208 let mut weights: Option<(PathBuf, u64)> = None;
209 let mut cached_all = true;
210 for blob in &fetched.blobs {
211 let (path, len, cached) = fetch_blob(blob, cfg)?;
212 if !cached {
213 cached_all = false;
214 }
215 if blob.is_weights {
216 weights = Some((path, len));
217 }
218 }
219
220 let (weights_path, bytes) = weights.ok_or_else(|| {
221 format!(
222 "{model} resolved with no weights layer — the registry returned \
223 {} blob(s), none of them the model",
224 fetched.blobs.len()
225 )
226 })?;
227
228 spine
229 .record(
230 &model,
231 &Transition::PullCompleted {
232 path: weights_path.display().to_string(),
233 size_bytes: bytes,
234 },
235 &[EventRef {
236 hash: started.hash,
237 seq: started.seq,
238 }],
239 )
240 .map_err(|e| format!("could not record completion: {e}"))?;
241
242 Ok(Pulled {
243 model,
244 source,
245 weights_path,
246 bytes,
247 already_had_it: cached_all,
248 })
249}
250
251#[cfg(test)]
252mod tests {
253 use super::*;
254
255 #[test]
256 fn a_blob_path_is_its_digest_so_presence_is_a_stat() {
257 let p = blob_path(Path::new("/b"), "sha256:ABC123");
258 assert_eq!(p, Path::new("/b/sha256-abc123"));
259 assert_eq!(p, blob_path(Path::new("/b"), "abc123"));
262 }
263
264 #[test]
265 fn a_local_reference_is_not_recorded_as_a_pull() {
266 let dir = std::env::temp_dir().join("hearth-pull-local");
267 std::fs::create_dir_all(&dir).unwrap();
268 let gguf = dir.join("muse.gguf");
269 std::fs::write(&gguf, b"weights").unwrap();
270
271 let spine = Spine::in_memory();
272 let out = pull(
273 &format!("file:{}", gguf.display()),
274 &PullConfig::default(),
275 &spine,
276 )
277 .unwrap();
278
279 assert!(out.already_had_it);
280 assert_eq!(out.bytes, 7);
281 assert!(
282 spine.latest(&out.model).is_none(),
283 "nothing was fetched, so claiming a pull would be a lie"
284 );
285 std::fs::remove_file(&gguf).ok();
286 }
287
288 #[test]
289 fn a_missing_local_file_is_refused_before_anything_is_recorded() {
290 let spine = Spine::in_memory();
291 let err = pull(
292 "file:/definitely/not/here.gguf",
293 &PullConfig::default(),
294 &spine,
295 )
296 .unwrap_err();
297 assert!(err.contains("no file at"), "{err}");
298 assert_eq!(spine.seq(), 0, "nothing should have been written");
299 }
300
301 #[test]
302 fn a_digest_mismatch_deletes_the_file_rather_than_caching_corruption() {
303 let dir = std::env::temp_dir().join("hearth-pull-mismatch");
306 std::fs::create_dir_all(&dir).unwrap();
307 let served = dir.join("served.bin");
308 std::fs::write(&served, b"not what we asked for").unwrap();
309
310 let blobs = dir.join("blobs");
311 let cfg = PullConfig {
312 blobs_dir: blobs.clone(),
313 progress: false,
314 verify_existing: false,
315 };
316 let blob = Blob {
317 name: "weights".into(),
318 url: format!("file://{}", served.display()),
319 digest: "sha256:0000000000000000000000000000000000000000000000000000000000000000"
320 .into(),
321 size_bytes: 0,
322 headers: vec![],
323 is_weights: true,
324 };
325
326 let err = fetch_blob(&blob, &cfg).unwrap_err();
327 assert!(err.contains("digest mismatch"), "{err}");
328 assert!(
329 !blob_path(&blobs, &blob.digest).exists(),
330 "a blob that failed verification must not be left on disk"
331 );
332 assert!(
333 !blob_path(&blobs, &blob.digest)
334 .with_extension("partial")
335 .exists(),
336 "and neither must the partial"
337 );
338 std::fs::remove_dir_all(&dir).ok();
339 }
340
341 #[test]
342 fn a_matching_digest_commits_the_file_under_its_digest() {
343 let dir = std::env::temp_dir().join("hearth-pull-match");
344 std::fs::create_dir_all(&dir).unwrap();
345 let body = b"the actual weights, honestly";
346 let served = dir.join("served.bin");
347 std::fs::write(&served, body).unwrap();
348
349 let blobs = dir.join("blobs");
350 let cfg = PullConfig {
351 blobs_dir: blobs.clone(),
352 progress: false,
353 verify_existing: false,
354 };
355 let blob = Blob {
356 name: "weights".into(),
357 url: format!("file://{}", served.display()),
358 digest: sha256::hex_digest(body),
359 size_bytes: body.len() as u64,
360 headers: vec![],
361 is_weights: true,
362 };
363
364 let (path, len, cached) = fetch_blob(&blob, &cfg).unwrap();
365 assert!(!cached);
366 assert_eq!(len, body.len() as u64);
367 assert_eq!(std::fs::read(&path).unwrap(), body);
368
369 let (_, _, cached2) = fetch_blob(&blob, &cfg).unwrap();
371 assert!(cached2, "the filename IS the digest — presence is enough");
372
373 std::fs::remove_dir_all(&dir).ok();
374 }
375
376 #[test]
377 fn a_cached_blob_of_the_wrong_size_is_refetched() {
378 let dir = std::env::temp_dir().join("hearth-pull-truncated");
379 std::fs::create_dir_all(&dir).unwrap();
380 let body = b"complete contents here";
381 let served = dir.join("served.bin");
382 std::fs::write(&served, body).unwrap();
383
384 let blobs = dir.join("blobs");
385 std::fs::create_dir_all(&blobs).unwrap();
386 let digest = sha256::hex_digest(body);
387 std::fs::write(blob_path(&blobs, &digest), b"trunc").unwrap();
390
391 let cfg = PullConfig {
392 blobs_dir: blobs.clone(),
393 progress: false,
394 verify_existing: false,
395 };
396 let blob = Blob {
397 name: "weights".into(),
398 url: format!("file://{}", served.display()),
399 digest,
400 size_bytes: body.len() as u64,
401 headers: vec![],
402 is_weights: true,
403 };
404 let (path, len, cached) = fetch_blob(&blob, &cfg).unwrap();
405 assert!(!cached, "the size did not match, so it was not trusted");
406 assert_eq!(len, body.len() as u64);
407 assert_eq!(std::fs::read(&path).unwrap(), body);
408 std::fs::remove_dir_all(&dir).ok();
409 }
410}