hearth-pull 0.4.2

Fetch model weights from Ollama's registry or HuggingFace, digest-verified, with every step recorded in the spine.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
//! `hearth pull` — get the bytes, prove they are the right bytes, and write
//! down where they came from.
//!
//! This is the half of the aggregator that was missing. [`hearth_resolve`] is
//! deliberately network-free: it turns a reference into blob URLs, a chosen
//! quantization and a byte count, with `serde` and `serde_json` as its entire
//! dependency list. That is what lets the VRAM planner refuse a model *before*
//! forty gigabytes move. This crate is what moves them.
//!
//! Three properties, and the third is the one nobody else offers:
//!
//! 1. **Digest-verified.** Every blob is hashed and compared against the digest
//!    the registry published. A download that does not match is deleted, not
//!    kept — a corrupt GGUF fails much later as an unexplainable tokenizer
//!    error, three layers away from the truth.
//! 2. **Resumable.** A 40 GiB transfer that dies at 39 GiB resumes. Restarting
//!    is not a recovery strategy, it is a way to never finish on a bad link.
//! 3. **Recorded.** `PullStarted` and `PullCompleted` land in the spine with
//!    the resolved source, so months later "where did this file come from" is a
//!    query — `hearth why <model>` — instead of an archaeology project. Those
//!    two transitions already existed in [`hearth_store`]; the history was
//!    ready before the downloader was.

pub mod curl;
pub mod registry;
pub mod runtime;

use std::path::{Path, PathBuf};

use hearth_core::sha256;
use hearth_resolve::Reference;
use hearth_store::{EventRef, Spine, Transition};

pub use registry::{Blob, Fetched};

/// Where blobs live, and how loud to be about it.
#[derive(Debug, Clone)]
pub struct PullConfig {
    /// Content-addressed blob directory, e.g. `~/.hearth/blobs`.
    pub blobs_dir: PathBuf,
    /// Draw curl's progress meter. A silent twenty-minute pause is
    /// indistinguishable from a hang, and a downloader that looks hung gets
    /// killed halfway.
    pub progress: bool,
    /// Re-verify a blob that is already on disk instead of trusting its name.
    /// Off by default: re-hashing 40 GiB on every start is a real cost, and the
    /// filename IS the digest. On when you have reason to distrust the disk.
    pub verify_existing: bool,
}

impl Default for PullConfig {
    fn default() -> Self {
        PullConfig {
            blobs_dir: PathBuf::from("./blobs"),
            progress: true,
            verify_existing: false,
        }
    }
}

/// What a pull did.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Pulled {
    pub model: String,
    /// Resolved origin, as recorded in the spine.
    pub source: String,
    /// The weights blob on disk.
    pub weights_path: PathBuf,
    pub bytes: u64,
    /// True when everything was already present and verified — so a second
    /// `pull` of the same model is honest about having done nothing.
    pub already_had_it: bool,
}

/// Content-addressed path for a digest. The filename IS the digest, which is
/// what makes "do we already have this" a `stat` rather than a re-hash.
pub fn blob_path(blobs_dir: &Path, digest: &str) -> PathBuf {
    blobs_dir.join(format!("sha256-{}", sha256::normalize(digest)))
}

/// Fetch one blob to its content-addressed home, verifying the digest.
///
/// Downloads to a `.partial` sibling and renames only after the digest
/// matches. Without that, an interrupted transfer leaves a file whose *name*
/// claims a digest its *contents* do not have — and every later run trusts the
/// name. The rename is the commit.
pub fn fetch_blob(blob: &Blob, cfg: &PullConfig) -> Result<(PathBuf, u64, bool), String> {
    match &blob.digest {
        Some(digest) => fetch_blob_verified(blob, digest, cfg),
        None => fetch_blob_self_verified(blob, cfg),
    }
}

/// The original path: a digest is already known, so the final home is known
/// before a single byte moves, and every byte is checked against it.
fn fetch_blob_verified(
    blob: &Blob,
    digest: &str,
    cfg: &PullConfig,
) -> Result<(PathBuf, u64, bool), String> {
    let final_path = blob_path(&cfg.blobs_dir, digest);

    if final_path.exists() {
        let len = std::fs::metadata(&final_path).map(|m| m.len()).unwrap_or(0);
        if cfg.verify_existing {
            let actual = sha256::hex_digest_file(&final_path)
                .map_err(|e| format!("could not read {}: {e}", final_path.display()))?;
            if !sha256::matches(digest, &actual) {
                // On disk under a digest it does not have. Say so loudly and
                // re-fetch rather than quietly serving the wrong weights.
                eprintln!(
                    "hearth: {} does not match its own name — refetching",
                    final_path.display()
                );
                let _ = std::fs::remove_file(&final_path);
            } else {
                return Ok((final_path, len, true));
            }
        } else if blob.size_bytes == 0 || len == blob.size_bytes {
            return Ok((final_path, len, true));
        } else {
            // Right name, wrong size: a previous run was interrupted after the
            // rename, or something truncated it. Not trustworthy.
            eprintln!(
                "hearth: {} is {len} bytes, expected {} — refetching",
                final_path.display(),
                blob.size_bytes
            );
            let _ = std::fs::remove_file(&final_path);
        }
    }

    let partial = final_path.with_extension("partial");
    download_to(&partial, blob, cfg)?;

    let actual = sha256::hex_digest_file(&partial)
        .map_err(|e| format!("could not hash {}: {e}", partial.display()))?;
    if !sha256::matches(digest, &actual) {
        // Delete it. Keeping a blob that failed verification is how a corrupt
        // download becomes a permanent, cached, corrupt download.
        let _ = std::fs::remove_file(&partial);
        return Err(format!(
            "digest mismatch for {}\n  expected sha256:{}\n  got      sha256:{}\n  \
             the file has been deleted; a resumed transfer over a proxy that \
             rewrote a range will do this, so a plain retry is worth one attempt",
            blob.name,
            sha256::normalize(digest),
            actual
        ));
    }

    let len = std::fs::metadata(&partial).map(|m| m.len()).unwrap_or(0);
    std::fs::rename(&partial, &final_path)
        .map_err(|e| format!("could not commit {}: {e}", final_path.display()))?;
    Ok((final_path, len, false))
}

/// No digest was published to check against — a bare URL, or a HuggingFace
/// file the tree listing did not mark as LFS.
///
/// The final home cannot be known before downloading, because the digest
/// that names it is the thing being discovered. So this downloads to a
/// TEMPORARY name (never a content-addressed one — a partial file must never
/// sit under the name its finished content will claim), hashes what actually
/// arrived, and only then computes the path a verified blob would have had
/// from the start. If that path already exists, this exact content was
/// already fetched under some other name, and the new download is discarded
/// as a duplicate rather than kept as a second copy of the same bytes.
///
/// This is self-consistency, not verification: the file matches its own
/// name by construction, which is trivially true of every file and proves
/// nothing about whether the content is what the operator meant to fetch.
/// Callers that need real verification pin a digest — the URL scheme's
/// `#sha256:HEX` fragment exists for exactly that.
fn fetch_blob_self_verified(blob: &Blob, cfg: &PullConfig) -> Result<(PathBuf, u64, bool), String> {
    std::fs::create_dir_all(&cfg.blobs_dir).map_err(|e| e.to_string())?;
    let safe_name = blob
        .name
        .chars()
        .map(|c| {
            if c.is_ascii_alphanumeric() || c == '.' || c == '-' {
                c
            } else {
                '_'
            }
        })
        .collect::<String>();
    let partial = cfg
        .blobs_dir
        .join(format!("{safe_name}.unverified.partial"));

    download_to(&partial, blob, cfg)?;

    let actual = sha256::hex_digest_file(&partial)
        .map_err(|e| format!("could not hash {}: {e}", partial.display()))?;
    let final_path = blob_path(&cfg.blobs_dir, &actual);

    if final_path.exists() {
        // Already have this exact content under its rightful name — this
        // download was redundant, not wrong.
        let _ = std::fs::remove_file(&partial);
        let len = std::fs::metadata(&final_path).map(|m| m.len()).unwrap_or(0);
        return Ok((final_path, len, true));
    }

    let len = std::fs::metadata(&partial).map(|m| m.len()).unwrap_or(0);
    std::fs::rename(&partial, &final_path)
        .map_err(|e| format!("could not commit {}: {e}", final_path.display()))?;
    eprintln!(
        "hearth: {} has no published digest — stored as sha256:{actual}, \
         self-consistent only (not checked against a source, because the \
         source published none)",
        blob.name
    );
    Ok((final_path, len, false))
}

/// Download one blob to `dest`, resuming a partial transfer if one is
/// already there. Shared by both verification paths — they differ in what
/// happens to the bytes afterward, not in how the bytes arrive.
fn download_to(dest: &Path, blob: &Blob, cfg: &PullConfig) -> Result<(), String> {
    let req = {
        let mut r = curl::Request::get(&blob.url).to_file(dest);
        for (k, v) in &blob.headers {
            r = r.header(k, v);
        }
        // Resume only if there is something to resume; `-C -` on a missing file
        // is fine, but on a zero-byte one some servers answer 416.
        if dest.exists() && std::fs::metadata(dest).map(|m| m.len()).unwrap_or(0) > 0 {
            r = r.resuming();
        }
        r
    };
    curl::fetch_file(&req, cfg.progress).map_err(|e| e.0)?;
    Ok(())
}

/// Pull a model reference, recording the whole thing in the spine.
///
/// The recording is not decoration. `PullStarted` goes in *before* any bytes
/// move, so a pull that dies halfway leaves evidence that it was attempted and
/// from where — the alternative is a half-empty blob directory and no idea
/// which model it belongs to.
pub fn pull(reference: &str, cfg: &PullConfig, spine: &Spine) -> Result<Pulled, String> {
    let reference = Reference::parse(reference).map_err(|e| e.0)?;
    let model = reference.display_name();
    let source = registry::source_string(&reference);

    // A local file is already here. Recording a pull for it would be a lie.
    if let Reference::Local { path } = &reference {
        let p = PathBuf::from(path);
        if !p.exists() {
            return Err(format!("no file at {path}"));
        }
        let bytes = std::fs::metadata(&p).map(|m| m.len()).unwrap_or(0);
        return Ok(Pulled {
            model,
            source,
            weights_path: p,
            bytes,
            already_had_it: true,
        });
    }

    let started = spine
        .record(
            &model,
            &Transition::PullStarted {
                source: source.clone(),
            },
            &[],
        )
        .map_err(|e| format!("could not record the pull: {e}"))?;

    let fetched = registry::resolve_blobs(&reference).map_err(|e| {
        // The failure is worth recording too — "we tried and the registry said
        // no" is a different fact from "nobody ever tried".
        let _ = spine.record(
            &model,
            &Transition::PullStarted {
                source: format!("{source} — FAILED: {e}"),
            },
            std::slice::from_ref(&started),
        );
        e
    })?;

    let mut weights: Option<(PathBuf, u64)> = None;
    let mut cached_all = true;
    for blob in &fetched.blobs {
        let (path, len, cached) = fetch_blob(blob, cfg)?;
        if !cached {
            cached_all = false;
        }
        if blob.is_weights {
            weights = Some((path, len));
        }
    }

    let (weights_path, bytes) = weights.ok_or_else(|| {
        format!(
            "{model} resolved with no weights layer — the registry returned \
             {} blob(s), none of them the model",
            fetched.blobs.len()
        )
    })?;

    spine
        .record(
            &model,
            &Transition::PullCompleted {
                path: weights_path.display().to_string(),
                size_bytes: bytes,
            },
            &[EventRef {
                hash: started.hash,
                seq: started.seq,
            }],
        )
        .map_err(|e| format!("could not record completion: {e}"))?;

    Ok(Pulled {
        model,
        source,
        weights_path,
        bytes,
        already_had_it: cached_all,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_blob_path_is_its_digest_so_presence_is_a_stat() {
        let p = blob_path(Path::new("/b"), "sha256:ABC123");
        assert_eq!(p, Path::new("/b/sha256-abc123"));
        // Both spellings of the same digest land on the same file, or a cache
        // would miss every time the registry changed its formatting.
        assert_eq!(p, blob_path(Path::new("/b"), "abc123"));
    }

    #[test]
    fn a_local_reference_is_not_recorded_as_a_pull() {
        let dir = std::env::temp_dir().join("hearth-pull-local");
        std::fs::create_dir_all(&dir).unwrap();
        let gguf = dir.join("muse.gguf");
        std::fs::write(&gguf, b"weights").unwrap();

        let spine = Spine::in_memory();
        let out = pull(
            &format!("file:{}", gguf.display()),
            &PullConfig::default(),
            &spine,
        )
        .unwrap();

        assert!(out.already_had_it);
        assert_eq!(out.bytes, 7);
        assert!(
            spine.latest(&out.model).is_none(),
            "nothing was fetched, so claiming a pull would be a lie"
        );
        std::fs::remove_file(&gguf).ok();
    }

    #[test]
    fn a_missing_local_file_is_refused_before_anything_is_recorded() {
        let spine = Spine::in_memory();
        let err = pull(
            "file:/definitely/not/here.gguf",
            &PullConfig::default(),
            &spine,
        )
        .unwrap_err();
        assert!(err.contains("no file at"), "{err}");
        assert_eq!(spine.seq(), 0, "nothing should have been written");
    }

    #[test]
    fn a_digest_mismatch_deletes_the_file_rather_than_caching_corruption() {
        // The blob is served by a local file:// URL whose contents do not match
        // the digest we claim. curl handles file:// so this needs no network.
        let dir = std::env::temp_dir().join("hearth-pull-mismatch");
        std::fs::create_dir_all(&dir).unwrap();
        let served = dir.join("served.bin");
        std::fs::write(&served, b"not what we asked for").unwrap();

        let blobs = dir.join("blobs");
        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "weights".into(),
            url: format!("file://{}", served.display()),
            digest: Some(
                "sha256:0000000000000000000000000000000000000000000000000000000000000000".into(),
            ),
            size_bytes: 0,
            headers: vec![],
            is_weights: true,
        };

        let err = fetch_blob(&blob, &cfg).unwrap_err();
        assert!(err.contains("digest mismatch"), "{err}");
        let digest = blob.digest.as_deref().unwrap();
        assert!(
            !blob_path(&blobs, digest).exists(),
            "a blob that failed verification must not be left on disk"
        );
        assert!(
            !blob_path(&blobs, digest).with_extension("partial").exists(),
            "and neither must the partial"
        );
        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn a_matching_digest_commits_the_file_under_its_digest() {
        let dir = std::env::temp_dir().join("hearth-pull-match");
        std::fs::create_dir_all(&dir).unwrap();
        let body = b"the actual weights, honestly";
        let served = dir.join("served.bin");
        std::fs::write(&served, body).unwrap();

        let blobs = dir.join("blobs");
        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "weights".into(),
            url: format!("file://{}", served.display()),
            digest: Some(sha256::hex_digest(body)),
            size_bytes: body.len() as u64,
            headers: vec![],
            is_weights: true,
        };

        let (path, len, cached) = fetch_blob(&blob, &cfg).unwrap();
        assert!(!cached);
        assert_eq!(len, body.len() as u64);
        assert_eq!(std::fs::read(&path).unwrap(), body);

        // Second call is a stat, not a download.
        let (_, _, cached2) = fetch_blob(&blob, &cfg).unwrap();
        assert!(cached2, "the filename IS the digest — presence is enough");

        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn a_cached_blob_of_the_wrong_size_is_refetched() {
        let dir = std::env::temp_dir().join("hearth-pull-truncated");
        std::fs::create_dir_all(&dir).unwrap();
        let body = b"complete contents here";
        let served = dir.join("served.bin");
        std::fs::write(&served, body).unwrap();

        let blobs = dir.join("blobs");
        std::fs::create_dir_all(&blobs).unwrap();
        let digest = sha256::hex_digest(body);
        // A truncated file already sitting under the right name — what an
        // interrupted run leaves behind if it renames before verifying.
        std::fs::write(blob_path(&blobs, &digest), b"trunc").unwrap();

        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "weights".into(),
            url: format!("file://{}", served.display()),
            digest: Some(digest),
            size_bytes: body.len() as u64,
            headers: vec![],
            is_weights: true,
        };
        let (path, len, cached) = fetch_blob(&blob, &cfg).unwrap();
        assert!(!cached, "the size did not match, so it was not trusted");
        assert_eq!(len, body.len() as u64);
        assert_eq!(std::fs::read(&path).unwrap(), body);
        std::fs::remove_dir_all(&dir).ok();
    }

    // ---- fetch_blob_self_verified: no published digest to check against ----

    #[test]
    fn no_digest_still_lands_the_file_under_its_own_computed_sha256() {
        // A bare URL pull: nothing published a digest, so `blob.digest` is
        // `None`. The file must still end up content-addressed — hearth
        // computes the digest itself rather than trusting a caller-supplied
        // filename for the final path.
        let dir = std::env::temp_dir().join("hearth-pull-no-digest");
        std::fs::create_dir_all(&dir).unwrap();
        let body = b"weights nobody published a digest for";
        let served = dir.join("served.bin");
        std::fs::write(&served, body).unwrap();

        let blobs = dir.join("blobs");
        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "model.gguf".into(),
            url: format!("file://{}", served.display()),
            digest: None,
            size_bytes: 0,
            headers: vec![],
            is_weights: true,
        };

        let (path, len, cached) = fetch_blob(&blob, &cfg).unwrap();
        assert!(!cached);
        assert_eq!(len, body.len() as u64);
        assert_eq!(std::fs::read(&path).unwrap(), body);

        let expected_name = format!("sha256-{}", sha256::hex_digest(body));
        assert_eq!(
            path.file_name().unwrap().to_str().unwrap(),
            expected_name,
            "the final path must be the digest hearth computed, not a guess"
        );
        assert!(
            !blobs.join("model.gguf.unverified.partial").exists(),
            "the working file must not survive under its temporary name"
        );

        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn a_second_no_digest_pull_of_identical_content_is_recognised_as_cached() {
        // Two different URLs (or the same URL fetched twice under different
        // callers) that happen to serve byte-identical content must land on
        // the SAME blob, not two copies — that is the entire point of
        // content addressing, and the no-digest path has to preserve it even
        // though it does not know the address until after downloading.
        let dir = std::env::temp_dir().join("hearth-pull-no-digest-dup");
        std::fs::create_dir_all(&dir).unwrap();
        let body = b"identical weights served from two places";
        let served = dir.join("served.bin");
        std::fs::write(&served, body).unwrap();

        let blobs = dir.join("blobs");
        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "model.gguf".into(),
            url: format!("file://{}", served.display()),
            digest: None,
            size_bytes: 0,
            headers: vec![],
            is_weights: true,
        };

        let (first_path, ..) = fetch_blob(&blob, &cfg).unwrap();
        let (second_path, _, cached) = fetch_blob(&blob, &cfg).unwrap();
        assert!(
            cached,
            "identical content must be recognised, not re-stored"
        );
        assert_eq!(first_path, second_path);

        std::fs::remove_dir_all(&dir).ok();
    }

    #[test]
    fn an_unsafe_blob_name_does_not_escape_the_blobs_directory() {
        // blob.name comes from a URL path or a registry listing — untrusted
        // input. A name containing "../" must not let the temporary working
        // file land outside blobs_dir.
        let dir = std::env::temp_dir().join("hearth-pull-unsafe-name");
        std::fs::create_dir_all(&dir).unwrap();
        let body = b"contents";
        let served = dir.join("served.bin");
        std::fs::write(&served, body).unwrap();

        let blobs = dir.join("blobs");
        let cfg = PullConfig {
            blobs_dir: blobs.clone(),
            progress: false,
            verify_existing: false,
        };
        let blob = Blob {
            name: "../../etc/model.gguf".into(),
            url: format!("file://{}", served.display()),
            digest: None,
            size_bytes: 0,
            headers: vec![],
            is_weights: true,
        };

        let (path, ..) = fetch_blob(&blob, &cfg).unwrap();
        assert!(
            path.starts_with(&blobs),
            "the final path must stay under blobs_dir, got {}",
            path.display()
        );

        std::fs::remove_dir_all(&dir).ok();
    }
}