Skip to main content

hearth_pull/
lib.rs

1//! `hearth pull` — get the bytes, prove they are the right bytes, and write
2//! down where they came from.
3//!
4//! This is the half of the aggregator that was missing. [`hearth_resolve`] is
5//! deliberately network-free: it turns a reference into blob URLs, a chosen
6//! quantization and a byte count, with `serde` and `serde_json` as its entire
7//! dependency list. That is what lets the VRAM planner refuse a model *before*
8//! forty gigabytes move. This crate is what moves them.
9//!
10//! Three properties, and the third is the one nobody else offers:
11//!
12//! 1. **Digest-verified.** Every blob is hashed and compared against the digest
13//!    the registry published. A download that does not match is deleted, not
14//!    kept — a corrupt GGUF fails much later as an unexplainable tokenizer
15//!    error, three layers away from the truth.
16//! 2. **Resumable.** A 40 GiB transfer that dies at 39 GiB resumes. Restarting
17//!    is not a recovery strategy, it is a way to never finish on a bad link.
18//! 3. **Recorded.** `PullStarted` and `PullCompleted` land in the spine with
19//!    the resolved source, so months later "where did this file come from" is a
20//!    query — `hearth why <model>` — instead of an archaeology project. Those
21//!    two transitions already existed in [`hearth_store`]; the history was
22//!    ready before the downloader was.
23
24pub 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/// Where blobs live, and how loud to be about it.
37#[derive(Debug, Clone)]
38pub struct PullConfig {
39    /// Content-addressed blob directory, e.g. `~/.hearth/blobs`.
40    pub blobs_dir: PathBuf,
41    /// Draw curl's progress meter. A silent twenty-minute pause is
42    /// indistinguishable from a hang, and a downloader that looks hung gets
43    /// killed halfway.
44    pub progress: bool,
45    /// Re-verify a blob that is already on disk instead of trusting its name.
46    /// Off by default: re-hashing 40 GiB on every start is a real cost, and the
47    /// filename IS the digest. On when you have reason to distrust the disk.
48    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/// What a pull did.
62#[derive(Debug, Clone, PartialEq, Eq)]
63pub struct Pulled {
64    pub model: String,
65    /// Resolved origin, as recorded in the spine.
66    pub source: String,
67    /// The weights blob on disk.
68    pub weights_path: PathBuf,
69    pub bytes: u64,
70    /// True when everything was already present and verified — so a second
71    /// `pull` of the same model is honest about having done nothing.
72    pub already_had_it: bool,
73}
74
75/// Content-addressed path for a digest. The filename IS the digest, which is
76/// what makes "do we already have this" a `stat` rather than a re-hash.
77pub fn blob_path(blobs_dir: &Path, digest: &str) -> PathBuf {
78    blobs_dir.join(format!("sha256-{}", sha256::normalize(digest)))
79}
80
81/// Fetch one blob to its content-addressed home, verifying the digest.
82///
83/// Downloads to a `.partial` sibling and renames only after the digest
84/// matches. Without that, an interrupted transfer leaves a file whose *name*
85/// claims a digest its *contents* do not have — and every later run trusts the
86/// name. The rename is the commit.
87pub 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                // On disk under a digest it does not have. Say so loudly and
97                // re-fetch rather than quietly serving the wrong weights.
98                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            // Right name, wrong size: a previous run was interrupted after the
110            // rename, or something truncated it. Not trustworthy.
111            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        // Resume only if there is something to resume; `-C -` on a missing file
127        // is fine, but on a zero-byte one some servers answer 416.
128        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        // Delete it. Keeping a blob that failed verification is how a corrupt
140        // download becomes a permanent, cached, corrupt download.
141        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
158/// Pull a model reference, recording the whole thing in the spine.
159///
160/// The recording is not decoration. `PullStarted` goes in *before* any bytes
161/// move, so a pull that dies halfway leaves evidence that it was attempted and
162/// from where — the alternative is a half-empty blob directory and no idea
163/// which model it belongs to.
164pub 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    // A local file is already here. Recording a pull for it would be a lie.
170    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        // The failure is worth recording too — "we tried and the registry said
197        // no" is a different fact from "nobody ever tried".
198        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        // Both spellings of the same digest land on the same file, or a cache
260        // would miss every time the registry changed its formatting.
261        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        // The blob is served by a local file:// URL whose contents do not match
304        // the digest we claim. curl handles file:// so this needs no network.
305        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        // Second call is a stat, not a download.
370        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        // A truncated file already sitting under the right name — what an
388        // interrupted run leaves behind if it renames before verifying.
389        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}