Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

19.2 KB
Raw Blame
//! Shared direct-HTTP model download transport.
//!
//! Both legacy URL models and Hugging Face mirror fallbacks use this module;
//! source-specific orchestration and finalization remain in the parent module.

use super::{DownloadProgress, ModelManager, ProgressTarget};
use anyhow::Result;
use futures_util::StreamExt;
use hf_hub::api::tokio::CancellationToken;
use log::{info, warn};
use sha2::{Digest, Sha256};
use std::collections::VecDeque;
use std::fs;
use std::fs::File;
use std::io::{Read, Write};
use std::path::Path;
use std::time::{Duration, Instant};
use tauri::Emitter;

/// Bound on connection setup for direct HTTP downloads (mirror + URL models).
const HTTP_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);

/// No headers, body bytes, or hf-hub progress for this long means the transfer
/// is wedged, not slow: direct downloads error out (keeping the partial for
/// resume) and HF attempts are cancelled by a watchdog — either way the retry
/// loop and mirror fallback take over instead of hanging forever.
pub(super) const DOWNLOAD_STALL_TIMEOUT: Duration = Duration::from_secs(60);

/// Throttle for progress events while bytes are flowing.
pub(super) const PROGRESS_THROTTLE: Duration = Duration::from_millis(100);

/// Re-emit interval with no bytes arriving, so the rate decays instead of freezing.
pub(super) const PROGRESS_TICK: Duration = Duration::from_secs(1);

/// Rate window: smooths hf-hub's bursty parallel chunks, still shows a slowdown.
const RATE_WINDOW: Duration = Duration::from_secs(5);

/// No rate until bytes have flowed this long; shorter samples are burst noise.
const RATE_MIN_SPAN: Duration = Duration::from_secs(1);

/// Transfer rate over a trailing window, excluding resumed bytes and timed from
/// the first byte received (so connecting doesn't drag it down).
pub(super) struct RateMeter {
    start_bytes: u64,
    /// `(when, cumulative bytes)`; the front is the window's anchor. Empty
    /// until the first sample past `start_bytes`.
    samples: VecDeque<(Instant, u64)>,
}

impl RateMeter {
    pub(super) fn new(start_bytes: u64) -> Self {
        Self {
            start_bytes,
            samples: VecDeque::new(),
        }
    }

    /// Records the cumulative byte count at `now` and returns the rate in
    /// bytes/sec, or `None` until bytes have flowed for [`RATE_MIN_SPAN`].
    pub(super) fn sample(&mut self, bytes: u64, now: Instant) -> Option<f64> {
        if self.samples.is_empty() && bytes <= self.start_bytes {
            return None;
        }
        self.samples.push_back((now, bytes));
        // Keep one sample at or before the window start as the anchor.
        while self.samples.len() > 2
            && now.saturating_duration_since(self.samples[1].0) >= RATE_WINDOW
        {
            self.samples.pop_front();
        }
        let (anchor_at, anchor_bytes) = self.samples[0];
        let span = now.saturating_duration_since(anchor_at);
        if span < RATE_MIN_SPAN {
            return None;
        }
        Some(bytes.saturating_sub(anchor_bytes) as f64 / span.as_secs_f64())
    }
}

/// Start offset of a `Content-Range: bytes <start>-<end>/<total>` header.
fn content_range_start(value: &str) -> Option<u64> {
    let range = value.trim().strip_prefix("bytes")?.trim_start();
    range.split('-').next()?.trim().parse().ok()
}

/// How a [`ModelManager::download_http_resumable`] call ended, cancellation
/// being an outcome (partial kept, no error surfaced) rather than a failure.
#[derive(Debug)]
pub(super) enum HttpDownloadOutcome {
    Completed,
    Cancelled,
}

/// Side-channel notifications from the resumable HTTP downloader, decoupled
/// from Tauri (the production wrapper maps them onto app events) so the
/// transport logic is testable without an `AppHandle`.
enum HttpDownloadEvent<'a> {
    Progress(&'a DownloadProgress),
    VerificationStarted,
    VerificationCompleted,
}

impl ModelManager {
    /// Verifies the SHA256 of `path` against `expected_sha256` (if provided).
    /// On mismatch or read error the partial file is deleted and an error is returned,
    /// so the next download attempt always starts from a clean state.
    /// When `expected_sha256` is `None` (custom user models) verification is skipped.
    fn verify_sha256(path: &Path, expected_sha256: Option<&str>, model_id: &str) -> Result<()> {
        let Some(expected) = expected_sha256 else {
            return Ok(());
        };
        match Self::compute_sha256(path) {
            Ok(actual) if actual == expected => {
                info!("SHA256 verified for model {}", model_id);
                Ok(())
            }
            Ok(actual) => {
                warn!(
                    "SHA256 mismatch for model {}: expected {}, got {}",
                    model_id, expected, actual
                );
                let _ = fs::remove_file(path);
                Err(anyhow::anyhow!(
                    "Download verification failed for model {}: file is corrupt. Please retry.",
                    model_id
                ))
            }
            Err(e) => {
                let _ = fs::remove_file(path);
                Err(anyhow::anyhow!(
                    "Failed to verify download for model {}: {}. Please retry.",
                    model_id,
                    e
                ))
            }
        }
    }

    /// Computes the SHA256 hex digest of a file, reading in 64KB chunks to handle large models.
    fn compute_sha256(path: &Path) -> Result<String> {
        let mut file = File::open(path)?;
        let mut hasher = Sha256::new();
        let mut buffer = [0u8; 65536];
        loop {
            let n = file.read(&mut buffer)?;
            if n == 0 {
                break;
            }
            hasher.update(&buffer[..n]);
        }
        Ok(format!("{:x}", hasher.finalize()))
    }

    /// Emit verification events around a blocking sha256 check of `path`.
    /// On mismatch `verify_sha256` deletes the file, so the next attempt (or
    /// next source) starts clean. A `None` hash skips checking (custom models).
    async fn verify_file_with_events(
        model_id: &str,
        path: &Path,
        expected_sha256: Option<&str>,
        emit: &(dyn Fn(HttpDownloadEvent<'_>) + Send + Sync),
    ) -> Result<()> {
        emit(HttpDownloadEvent::VerificationStarted);
        let path = path.to_path_buf();
        let expected = expected_sha256.map(str::to_string);
        let id = model_id.to_string();
        tokio::task::spawn_blocking(move || Self::verify_sha256(&path, expected.as_deref(), &id))
            .await
            .map_err(|e| anyhow::anyhow!("SHA256 task panicked: {}", e))??;
        emit(HttpDownloadEvent::VerificationCompleted);
        Ok(())
    }

    /// [`Self::download_http_resumable_with_events`] wired to the Tauri event
    /// bus — the production entry point.
    pub(super) async fn download_http_resumable(
        &self,
        target: &ProgressTarget,
        url: &str,
        partial_path: &Path,
        expected_size: Option<u64>,
        expected_sha256: Option<&str>,
        cancel_token: &CancellationToken,
    ) -> Result<HttpDownloadOutcome> {
        let app_handle = self.app_handle.clone();
        let id = target.model_id.clone();
        Self::download_http_resumable_with_events(
            &target.model_id,
            url,
            partial_path,
            expected_size,
            expected_sha256,
            cancel_token,
            &move |event| {
                let _ = match event {
                    HttpDownloadEvent::Progress(progress) => app_handle.emit(
                        "model-download-progress",
                        target.progress(
                            progress.downloaded,
                            progress.total,
                            progress.bytes_per_sec,
                        ),
                    ),
                    HttpDownloadEvent::VerificationStarted => {
                        app_handle.emit("model-verification-started", &id)
                    }
                    HttpDownloadEvent::VerificationCompleted => {
                        app_handle.emit("model-verification-completed", &id)
                    }
                };
            },
        )
        .await
    }

    /// The one resumable HTTP downloader, shared by the mirror fallback and
    /// URL-sourced models: fetch `url` into `partial_path`, resuming what's
    /// already there, and leave verified bytes in `partial_path` on success —
    /// finalizing (rename / extract) is the caller's job. Takes progress and
    /// verification notifications as a callback instead of touching Tauri, so
    /// the failure-mode behavior below is exercised by tests against a local
    /// socket server.
    ///
    /// Robustness properties, in the order the failure modes appear:
    /// - a partial already at the expected size (crash between completion and
    ///   finalize) is verified and accepted instead of asking the server for
    ///   `Range: bytes=<EOF>-` and looping on 416 forever; an oversized one is
    ///   deleted; a live 416 finishes the partial only when a hash can prove
    ///   it, and otherwise clears it
    /// - connection setup and every body chunk are bounded by
    ///   [`HTTP_CONNECT_TIMEOUT`] / [`DOWNLOAD_STALL_TIMEOUT`] and race the
    ///   cancel token, so a wedged transfer can neither hang the download
    ///   forever nor ignore a cancel
    /// - a 200 to a Range request (server ignored it) restarts from zero
    ///   rather than appending the whole file to the partial; a 206 must start
    ///   exactly at our offset or the partial is discarded
    /// - a server claiming or sending more than the expected size is cut off
    ///   at the first excess byte, not trusted until it closes the stream
    /// - the final bytes are checked against `expected_size` (catalog, or
    ///   content-length when unknown) and `expected_sha256` before returning
    async fn download_http_resumable_with_events(
        model_id: &str,
        url: &str,
        partial_path: &Path,
        expected_size: Option<u64>,
        expected_sha256: Option<&str>,
        cancel_token: &CancellationToken,
        emit: &(dyn Fn(HttpDownloadEvent<'_>) + Send + Sync),
    ) -> Result<HttpDownloadOutcome> {
        let mut resume_from = partial_path.metadata().map(|m| m.len()).unwrap_or(0);

        if let Some(expected) = expected_size {
            if resume_from > expected {
                let _ = fs::remove_file(partial_path);
                resume_from = 0;
            } else if resume_from == expected && expected > 0 {
                info!(
                    "Partial download of {} is already full-size; verifying",
                    model_id
                );
                Self::verify_file_with_events(model_id, partial_path, expected_sha256, emit)
                    .await?;
                return Ok(HttpDownloadOutcome::Completed);
            }
        }

        if resume_from > 0 {
            info!(
                "Resuming download of {} from byte {}",
                model_id, resume_from
            );
        } else {
            info!("Starting fresh download of {} from {}", model_id, url);
        }

        let client = reqwest::Client::builder()
            .connect_timeout(HTTP_CONNECT_TIMEOUT)
            .build()?;
        let mut request = client.get(url);
        if resume_from > 0 {
            request = request.header("Range", format!("bytes={}-", resume_from));
        }
        let response = tokio::select! {
            r = tokio::time::timeout(DOWNLOAD_STALL_TIMEOUT, request.send()) => r
                .map_err(|_| anyhow::anyhow!(
                    "no response within {}s from {}",
                    DOWNLOAD_STALL_TIMEOUT.as_secs(), url
                ))??,
            _ = cancel_token.cancelled() => return Ok(HttpDownloadOutcome::Cancelled),
        };

        // 416 to our Range request means its start is at or past the object's
        // end. With a catalog size in hand that can only mean the server's
        // object is *smaller* than expected (a full-size partial never issues
        // a request — handled above), and with no hash there is no trusted
        // signal to bless the partial: both restart clean. Only a hash can
        // genuinely finish a partial here. Without a Range in flight a 416 is
        // just a broken server, which the generic status check below rejects.
        if resume_from > 0 && response.status() == reqwest::StatusCode::RANGE_NOT_SATISFIABLE {
            if expected_size.is_some() || expected_sha256.is_none() {
                let _ = fs::remove_file(partial_path);
                return Err(anyhow::anyhow!(
                    "server object ends before the expected size (HTTP 416)"
                ));
            }
            Self::verify_file_with_events(model_id, partial_path, expected_sha256, emit).await?;
            return Ok(HttpDownloadOutcome::Completed);
        }
        // A 200 to a Range request means the server ignored it and is sending
        // the whole file; appending it to the partial would corrupt the model.
        if resume_from > 0 && response.status() == reqwest::StatusCode::OK {
            let _ = fs::remove_file(partial_path);
            resume_from = 0;
        }
        if !response.status().is_success() {
            return Err(anyhow::anyhow!(
                "server returned HTTP {}",
                response.status()
            ));
        }
        // On a 206, trust but verify the offset: a reply starting anywhere but
        // exactly our partial's end would silently corrupt the file on append.
        if resume_from > 0 && response.status() == reqwest::StatusCode::PARTIAL_CONTENT {
            let starts_at = response
                .headers()
                .get(reqwest::header::CONTENT_RANGE)
                .and_then(|v| v.to_str().ok())
                .and_then(content_range_start);
            if starts_at != Some(resume_from) {
                let _ = fs::remove_file(partial_path);
                return Err(anyhow::anyhow!(
                    "server returned Content-Range starting at {:?}, expected {}",
                    starts_at,
                    resume_from
                ));
            }
        }
        // When the catalog pins the size, a server advertising a different
        // total is already misbehaving — reject before writing anything.
        if let (Some(expected), Some(len)) = (expected_size, response.content_length()) {
            if resume_from + len != expected {
                return Err(anyhow::anyhow!(
                    "server advertises {} bytes, expected {}",
                    resume_from + len,
                    expected
                ));
            }
        }

        let known_total =
            expected_size.or_else(|| response.content_length().map(|l| resume_from + l));
        let total_size = known_total.unwrap_or(0);
        let mut downloaded = resume_from;
        let mut file = if resume_from > 0 {
            std::fs::OpenOptions::new()
                .append(true)
                .open(partial_path)?
        } else {
            std::fs::File::create(partial_path)?
        };

        let emit_progress = |downloaded: u64, bytes_per_sec: Option<f64>| {
            emit(HttpDownloadEvent::Progress(&DownloadProgress {
                model_id: model_id.to_string(),
                downloaded,
                total: total_size,
                percentage: if total_size > 0 {
                    (downloaded as f64 / total_size as f64) * 100.0
                } else {
                    0.0
                },
                bytes_per_sec,
            }));
        };
        // Seeded at the resume offset (after any 200-restart reset above), so
        // only bytes from this response count toward the rate.
        let mut rate = RateMeter::new(downloaded);
        emit_progress(downloaded, None);

        let mut last_emit = Instant::now();
        // A deadline rather than a per-poll timeout: the tick arm below
        // restarts the select every second, which must not reset the clock.
        let mut stall_deadline = tokio::time::Instant::now() + DOWNLOAD_STALL_TIMEOUT;
        let mut tick =
            tokio::time::interval_at(tokio::time::Instant::now() + PROGRESS_TICK, PROGRESS_TICK);
        tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
        let mut stream = response.bytes_stream();
        loop {
            let chunk = tokio::select! {
                c = tokio::time::timeout_at(stall_deadline, stream.next()) => match c {
                    // Stalled mid-body: keep the partial for resume.
                    Err(_) => return Err(anyhow::anyhow!(
                        "transfer stalled: no data for {}s",
                        DOWNLOAD_STALL_TIMEOUT.as_secs()
                    )),
                    Ok(None) => break,
                    Ok(Some(chunk)) => chunk?,
                },
                _ = cancel_token.cancelled() => {
                    // Keep the partial for resume; caller handles state cleanup.
                    return Ok(HttpDownloadOutcome::Cancelled);
                }
                _ = tick.tick() => {
                    if last_emit.elapsed() >= PROGRESS_TICK {
                        let now = Instant::now();
                        emit_progress(downloaded, rate.sample(downloaded, now));
                        last_emit = now;
                    }
                    continue;
                }
            };
            stall_deadline = tokio::time::Instant::now() + DOWNLOAD_STALL_TIMEOUT;
            // An untrusted server must not be able to fill the disk: cut the
            // transfer at the first byte past the known total instead of
            // trusting it to eventually close the stream. Everything written
            // so far is tainted by a provably-misbehaving server — clear it.
            if let Some(cap) = known_total {
                if downloaded + chunk.len() as u64 > cap {
                    drop(file);
                    let _ = fs::remove_file(partial_path);
                    return Err(anyhow::anyhow!(
                        "server sent more than the expected {} bytes",
                        cap
                    ));
                }
            }
            file.write_all(&chunk)?;
            downloaded += chunk.len() as u64;
            if last_emit.elapsed() >= PROGRESS_THROTTLE {
                let now = Instant::now();
                emit_progress(downloaded, rate.sample(downloaded, now));
                last_emit = now;
            }
        }
        file.flush()?;
        drop(file);
        emit_progress(downloaded, rate.sample(downloaded, Instant::now()));

        if let Some(expected) = known_total {
            let actual = partial_path.metadata()?.len();
            if actual != expected {
                let _ = fs::remove_file(partial_path);
                return Err(anyhow::anyhow!(
                    "download incomplete: expected {} bytes, got {}",
                    expected,
                    actual
                ));
            }
        }

        // The catalog hash is the trust anchor: for a mirror (an untrusted
        // host) this verification is what makes the fallback safe at all.
        Self::verify_file_with_events(model_id, partial_path, expected_sha256, emit).await?;
        Ok(HttpDownloadOutcome::Completed)
    }
}

#[cfg(test)]
mod tests;