whisper-nvidia-cli 0.1.0

One-shot agent-native local NVIDIA GPU speech-to-text CLI powered by whisper.cpp
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
//! Model cache, SHA-1 verify, and TLS-only download with retry.
//!
//! The commit point is the rename, and nothing is renamed before its digest
//! matches. Verifying after the rename leaves a corrupt file in the cache
//! that the next invocation happily feeds to the engine.

use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

use sha1::{Digest, Sha1};

use crate::catalog::ModelEntry;
use crate::error::Error;
use crate::paths::AppPaths;

/// Length of a hex-encoded SHA-1 digest.
const SHA1_HEX_LEN: usize = 40;
/// Fallback read buffer for hashing and streaming.
///
/// It is the seed of the `io-chunk-bytes` key, used when the store cannot be
/// read at all.
const IO_CHUNK: usize = 64 * 1024;

/// The store keys this module resolves for itself.
///
/// Both callers of [`download`] hand it a `DownloadKnobs` built in `config`,
/// and that struct cannot grow from here, so these three keys are read from the
/// same store instead of widening a signature this file does not own.
struct StoreKnobs {
    /// Proxy URL for the download. Empty means a direct connection.
    proxy: String,
    /// Base of the exponential backoff between attempts, in milliseconds.
    backoff_ms: u64,
    /// Read and write buffer size for streaming I/O, in bytes.
    io_chunk: usize,
}

/// Resolve the store keys, falling back to the compiled seeds.
///
/// This re-reads the file rather than taking a resolved store, and that is
/// deliberate only for `verify`, which the config verbs reach without a
/// resolved store in hand. Every other caller receives the values through
/// [`crate::config::DownloadKnobs`], because configuration resolved twice is
/// configuration that can disagree with itself: this path cannot see the flags
/// the operator typed, so it must never be the one a transcription consults.
///
/// A config file that cannot be read is not this module's fault to report: the
/// config verbs answer 78 for it, and a hash must still run on the seeds rather
/// than fail on a key it only reads.
fn store_knobs(paths: &AppPaths) -> StoreKnobs {
    let seeds = crate::config::Store::seeds();
    let store = crate::config::Store::load(&paths.config_file()).unwrap_or_default();
    StoreKnobs {
        // `HTTPS_PROXY` is not the answer here: this product ignores
        // environment variables, so without this key an operator behind a
        // corporate proxy has no way at all to reach the model host.
        proxy: store.http_proxy.or(seeds.http_proxy).unwrap_or_default(),
        backoff_ms: store
            .download_backoff_ms
            .or(seeds.download_backoff_ms)
            .unwrap_or_default(),
        // A zero-byte buffer would read nothing forever, so it is never honored.
        io_chunk: store
            .io_chunk_bytes
            .or(seeds.io_chunk_bytes)
            .filter(|n| *n > 0)
            .unwrap_or(IO_CHUNK),
    }
}

/// Absolute path of a cached model file.
pub fn model_path(paths: &AppPaths, entry: &ModelEntry) -> PathBuf {
    paths.models_dir().join(&entry.filename)
}

/// True when the file exists with the exact official size.
///
/// Presence is not integrity: see [`is_verified`].
pub fn is_present(paths: &AppPaths, entry: &ModelEntry) -> bool {
    let path = model_path(paths, entry);
    path.metadata()
        .map(|m| m.len() == entry.size_bytes)
        .unwrap_or(false)
}

/// True when the cached file matches the official digest.
pub fn is_verified(paths: &AppPaths, entry: &ModelEntry) -> bool {
    verify(paths, entry).is_ok()
}

/// Compute SHA-1 of a file using the seeded read buffer.
pub fn sha1_file(path: &Path) -> Result<String, Error> {
    sha1_file_buffered(path, IO_CHUNK)
}

/// Compute SHA-1 of a file with the operator's read buffer.
fn sha1_file_buffered(path: &Path, io_chunk: usize) -> Result<String, Error> {
    let mut file = std::fs::File::open(path)?;
    let mut hasher = Sha1::new();
    // A runtime size cannot back a fixed-length array, so the buffer is a
    // heap allocation made once per file.
    let mut buf = vec![0u8; io_chunk];
    loop {
        let n = file.read(&mut buf)?;
        if n == 0 {
            break;
        }
        hasher.update(&buf[..n]);
    }
    Ok(hex::encode(hasher.finalize()))
}

/// Reject a catalog row whose digest cannot verify anything.
///
/// FR-049 requires a missing digest to stop the download before any socket.
fn ensure_digest_declared(entry: &ModelEntry) -> Result<(), Error> {
    let digest = entry.sha1.trim();
    let usable = digest.len() == SHA1_HEX_LEN && digest.bytes().all(|b| b.is_ascii_hexdigit());
    if usable {
        return Ok(());
    }
    Err(Error::Config(format!(
        "catalog entry {} has no usable sha1 digest",
        entry.name
    )))
}

/// Verify size and official digest of an arbitrary file against a catalog row.
fn verify_file(path: &Path, entry: &ModelEntry, io_chunk: usize) -> Result<String, Error> {
    ensure_digest_declared(entry)?;
    let len = path.metadata()?.len();
    // A wrong size is not evidence of tampering: no digest was computed, so
    // there is nothing to have mismatched. Reporting both as the same fault
    // told the operator to suspect the bytes when the likely cause was a
    // truncated download or a catalog row that moved on.
    if len != entry.size_bytes {
        return Err(Error::ModelSizeMismatch {
            name: entry.name.clone(),
            expected: entry.size_bytes,
            found: len,
        });
    }
    let digest = sha1_file_buffered(path, io_chunk)?;
    if digest != entry.sha1 {
        return Err(Error::ModelDigestMismatch {
            name: entry.name.clone(),
        });
    }
    Ok(digest)
}

/// Verify the cached model file.
pub fn verify(paths: &AppPaths, entry: &ModelEntry) -> Result<String, Error> {
    let path = model_path(paths, entry);
    if !path.exists() {
        return Err(Error::ModelNotFound {
            name: entry.name.clone(),
        });
    }
    verify_file(&path, entry, store_knobs(paths).io_chunk)
}

/// Download with TLS, retry, and digest check before commit.
pub fn download(
    paths: &AppPaths,
    entry: &ModelEntry,
    dl: &crate::config::DownloadKnobs,
    offline: bool,
) -> Result<PathBuf, Error> {
    let (retries, max_elapsed, timeout_secs) = (dl.retries, dl.max_elapsed_secs, dl.timeout_secs);
    if offline {
        return Err(Error::OfflineMissingModel {
            name: entry.name.clone(),
        });
    }
    // Both checks happen before any socket is opened.
    ensure_digest_declared(entry)?;
    if !entry.url.starts_with("https://") {
        return Err(Error::InsecureOrigin {
            url: entry.url.clone(),
        });
    }
    paths.ensure()?;
    // Resolved by the caller, so the flags the operator typed are honoured.
    let knobs = StoreKnobs {
        proxy: dl.proxy.clone(),
        backoff_ms: dl.backoff_ms,
        io_chunk: dl.io_chunk,
    };
    let dest = model_path(paths, entry);
    if dest.exists() && verify_file(&dest, entry, knobs.io_chunk).is_ok() {
        return Ok(dest);
    }

    let started = Instant::now();
    let mut last = anyhow::anyhow!("download failed");
    let attempts = retries.max(1);
    let part = dest.with_extension("bin.part");
    for attempt in 0..attempts {
        if started.elapsed() > Duration::from_secs(max_elapsed.max(1)) {
            break;
        }
        match download_once(
            &entry.url,
            &part,
            timeout_secs,
            &knobs.proxy,
            knobs.io_chunk,
        ) {
            Ok(()) => match verify_file(&part, entry, knobs.io_chunk) {
                // Commit only after the digest matches.
                Ok(_) => {
                    std::fs::rename(&part, &dest)?;
                    crate::signal::release_temp(&part);
                    return Ok(dest);
                }
                Err(e) => {
                    let _ = std::fs::remove_file(&part);
                    crate::signal::release_temp(&part);
                    // A digest that does not match, on bytes whose length DOES
                    // match, is not a transient fault: the same origin will
                    // serve the same bytes and fail the same way. Retrying it
                    // spent the caller's retry budget and the FR-036 deadline on
                    // an outcome that could not change, and then reported the
                    // generic download failure instead of the tampering or
                    // stale-catalog signal the operator needed.
                    //
                    // A wrong SIZE is left retryable on purpose: a connection
                    // dropped mid-body produces a short file with no network
                    // error, and that one genuinely can succeed next time.
                    if matches!(e, Error::ModelDigestMismatch { .. }) {
                        return Err(e);
                    }
                    last = anyhow::anyhow!(e.to_string());
                }
            },
            Err(e) => {
                let _ = std::fs::remove_file(&part);
                crate::signal::release_temp(&part);
                last = e;
            }
        }
        let backoff = knobs.backoff_ms.saturating_mul(1u64 << attempt.min(4));
        std::thread::sleep(Duration::from_millis(backoff));
    }
    Err(Error::ModelDownload(last))
}

fn download_once(
    url: &str,
    part: &Path,
    timeout_secs: u64,
    proxy: &str,
    io_chunk: usize,
) -> Result<(), anyhow::Error> {
    let mut builder = reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .https_only(true)
        .timeout(Duration::from_secs(timeout_secs.max(1)));
    // An empty proxy means a direct connection. The usual answer, `HTTPS_PROXY`,
    // is not one here: this product ignores environment variables, so the
    // `http-proxy` key is the only way an operator behind a corporate proxy can
    // reach the model host at all.
    if !proxy.trim().is_empty() {
        builder = builder.proxy(reqwest::Proxy::all(proxy.trim())?);
    }
    let client = builder.build()?;
    let mut resp = client.get(url).send()?.error_for_status()?;
    // Track before the first byte so a forced exit cannot leak the part file.
    crate::signal::register_temp(part);
    let mut file = std::fs::File::create(part)?;
    let mut buf = vec![0u8; io_chunk];
    loop {
        let n = resp.read(&mut buf)?;
        if n == 0 {
            break;
        }
        file.write_all(&buf[..n])?;
    }
    file.flush()?;
    Ok(())
}

/// Remove a cached model. Requires `--yes` at the command layer.
/// Delete a cached model. Returns whether a file was actually deleted.
///
/// Removing what is not there is a success, not a fault: the caller asked for
/// the model to be gone and it is. But the two outcomes are not the same fact,
/// and the caller the PRD names for this verb is "an agent freeing disk". It
/// has to be able to tell a removal from a no-op, or a mistyped cache
/// directory reads exactly like a successful cleanup.
pub fn remove(paths: &AppPaths, entry: &ModelEntry) -> Result<bool, Error> {
    let path = model_path(paths, entry);
    if !path.exists() {
        return Ok(false);
    }
    std::fs::remove_file(path)?;
    Ok(true)
}

#[cfg(test)]
mod tests {
    /// One attempt, one second, tiny buffer: enough to reach the refusal these
    /// tests are about, without waiting on a retry sequence.
    fn test_knobs() -> crate::config::DownloadKnobs {
        crate::config::DownloadKnobs {
            retries: 1,
            max_elapsed_secs: 1,
            timeout_secs: 5,
            backoff_ms: 1,
            proxy: String::new(),
            io_chunk: 4096,
        }
    }
    use super::*;

    fn paths_in(dir: &Path) -> AppPaths {
        AppPaths::resolve(Some(dir), Some(dir)).expect("resolve")
    }

    fn entry(url: &str, sha1: &str, size: u64) -> ModelEntry {
        ModelEntry {
            name: "tiny".into(),
            filename: "ggml-tiny.bin".into(),
            url: url.into(),
            size_bytes: size,
            sha1: sha1.into(),
            vram_bytes: 1,
        }
    }

    const VALID_SHA1: &str = "bd577a113a864445d4c299885e0cb97d4ba92b5f";

    #[test]
    fn rejects_http_origin() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        let e = entry("http://example.invalid/ggml-tiny.bin", VALID_SHA1, 10);
        let err = download(&paths, &e, &test_knobs(), false).expect_err("must refuse");
        assert!(matches!(err, Error::InsecureOrigin { .. }));
    }

    #[test]
    fn empty_digest_refuses_download_before_any_socket() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        // A reachable-looking https URL: the refusal must come from the
        // digest check, not from the network.
        let e = entry("https://example.invalid/ggml-tiny.bin", "", 10);
        let err = download(&paths, &e, &test_knobs(), false).expect_err("must refuse");
        assert_eq!(err.exit_code(), 78);
    }

    #[test]
    fn short_digest_is_refused() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        let e = entry("https://example.invalid/ggml-tiny.bin", "abc123", 10);
        assert!(download(&paths, &e, &test_knobs(), false).is_err());
    }

    #[test]
    fn offline_refuses_before_digest_work() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        let e = entry("https://example.invalid/ggml-tiny.bin", VALID_SHA1, 10);
        let err = download(&paths, &e, &test_knobs(), true).expect_err("must refuse");
        assert!(matches!(err, Error::OfflineMissingModel { .. }));
    }

    #[test]
    fn wrong_digest_never_commits_the_file() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        paths.ensure().expect("ensure");
        let e = entry("https://example.invalid/ggml-tiny.bin", VALID_SHA1, 4);
        let part = model_path(&paths, &e).with_extension("bin.part");
        std::fs::write(&part, b"junk").expect("write part");
        // The digest of "junk" is not the official one, so the part file must
        // never become the cached model.
        assert!(verify_file(&part, &e, IO_CHUNK).is_err());
        assert!(!model_path(&paths, &e).exists());
    }

    #[test]
    fn truncated_cache_file_fails_verify() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        paths.ensure().expect("ensure");
        let e = entry("https://example.invalid/ggml-tiny.bin", VALID_SHA1, 1_000);
        std::fs::write(model_path(&paths, &e), b"short").expect("write");
        let err = verify(&paths, &e).expect_err("must refuse");
        // A truncated file is a size fault, not evidence of tampering: the
        // digest was never computed, so it cannot have mismatched.
        assert!(
            matches!(
                err,
                Error::ModelSizeMismatch {
                    expected: 1_000,
                    found: 5,
                    ..
                }
            ),
            "expected a size mismatch naming both numbers, got {err}"
        );
        assert_eq!(err.exit_code(), 78);
    }

    /// The right size with the wrong bytes is the case that does suggest
    /// tampering, and it must stay distinguishable from a truncation.
    #[test]
    fn right_size_wrong_bytes_is_a_digest_mismatch() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        paths.ensure().expect("ensure");
        let body = b"exactly-twenty-bytes";
        let e = entry(
            "https://example.invalid/ggml-tiny.bin",
            VALID_SHA1,
            body.len() as u64,
        );
        std::fs::write(model_path(&paths, &e), body).expect("write");
        let err = verify(&paths, &e).expect_err("must refuse");
        assert!(
            matches!(err, Error::ModelDigestMismatch { .. }),
            "expected a digest mismatch, got {err}"
        );
    }

    #[test]
    fn half_size_file_is_not_present() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        paths.ensure().expect("ensure");
        let e = entry("https://example.invalid/ggml-tiny.bin", VALID_SHA1, 100);
        std::fs::write(model_path(&paths, &e), vec![0u8; 60]).expect("write");
        assert!(!is_present(&paths, &e), "60 of 100 bytes is not present");
        assert!(!is_verified(&paths, &e));
    }

    #[test]
    fn exact_size_and_digest_verifies() {
        let dir = tempfile::tempdir().expect("tempdir");
        let paths = paths_in(dir.path());
        paths.ensure().expect("ensure");
        let body = b"whisper";
        let digest = {
            let mut h = Sha1::new();
            h.update(body);
            hex::encode(h.finalize())
        };
        let e = entry(
            "https://example.invalid/ggml-tiny.bin",
            &digest,
            body.len() as u64,
        );
        std::fs::write(model_path(&paths, &e), body).expect("write");
        assert!(is_present(&paths, &e));
        assert_eq!(verify(&paths, &e).expect("verify"), digest);
    }
}