Struct FetchConfigBuilder 

pub struct FetchConfigBuilder { /* private fields */ }

Builder for FetchConfig.

Implementations

impl FetchConfigBuilder

pub fn revision(self, revision: &str) -> Self

Sets the git revision (branch, tag, or commit SHA) to download.

Defaults to "main" if not set.

pub fn token(self, token: &str) -> Self

Sets the authentication token.

pub fn token_from_env(self) -> Self

Reads the authentication token from the HF_TOKEN environment variable.

pub fn filter(self, pattern: &str) -> Self

Adds an include glob pattern. Only files matching at least one include pattern will be downloaded.

Can be called multiple times to add multiple patterns.

pub fn exclude(self, pattern: &str) -> Self

Adds an exclude glob pattern. Files matching any exclude pattern will be skipped, even if they match an include pattern.

Can be called multiple times to add multiple patterns.

pub fn concurrency(self, concurrency: usize) -> Self

Sets the number of files to download concurrently.

When omitted, the download plan optimizer auto-tunes this value based on file count and size distribution. Falls back to 4 if no plan recommendation is available.

pub fn output_dir(self, dir: PathBuf) -> Self

Sets a custom output directory for downloaded files.

By default, files are stored in the standard HuggingFace cache directory (~/.cache/huggingface/hub/). When set, the HuggingFace cache hierarchy is created inside this directory instead.

pub fn timeout_per_file(self, duration: Duration) -> Self

Sets the maximum time allowed per file download.

Defaults to 300 seconds when not set. If a single file download exceeds this duration, it is aborted and may be retried according to the retry policy.

For chunked (multi-connection) downloads, an abort here does not discard work already on disk: the partial .chunked.part file and its per-chunk progress sidecar are preserved, and a subsequent call for the same file resumes from each chunk’s last checkpoint via Range requests — provided the upstream etag still matches. Raise this when downloading large files on slow links (e.g. Duration::from_secs(1800) for 5–15 GiB files at home-broadband speeds).

pub fn timeout_total(self, duration: Duration) -> Self

Sets the maximum total time for the entire download operation.

Defaults to no limit when not set. If the total download time exceeds this duration, remaining files are skipped and a FetchError::Timeout is returned.

Independent of timeout_per_file: the per-file budget bounds any single transfer, while this bounds the whole batch (including retries between transfers). Files that completed before the total elapsed are kept; an interrupted in-flight chunked transfer leaves its partial + sidecar on disk for resume on a future call.

pub fn max_retries(self, retries: u32) -> Self

Sets the maximum number of retry attempts per file.

Defaults to 3. Set to 0 to disable retries. Uses exponential backoff with jitter (base 300ms, cap 10s).

pub fn verify_checksums(self, verify: bool) -> Self

Enables or disables SHA256 checksum verification after download.

When enabled, downloaded files are verified against the SHA256 hash from HuggingFace LFS metadata. Files without LFS metadata (small config files stored directly in git) are skipped.

Defaults to true.

pub fn chunk_threshold(self, bytes: u64) -> Self

Sets the minimum file size (in bytes) for chunked parallel download.

Files at or above this threshold are downloaded using multiple HTTP Range connections in parallel. Files below use the standard single connection. Set to u64::MAX to disable chunked downloads entirely.

When omitted, the download plan optimizer auto-tunes this value based on file size distribution. Falls back to 100 MiB (104_857_600 bytes) if no plan recommendation is available.

pub fn connections_per_file(self, connections: usize) -> Self

Sets the number of parallel HTTP connections per large file.

Only applies to files at or above chunk_threshold. When omitted, the download plan optimizer auto-tunes this value based on file size distribution. Falls back to 8 if no plan recommendation is available.

pub fn on_progress<F>(self, callback: F) -> Self

where F: Fn(&ProgressEvent) + Send + Sync + 'static,

Sets a progress callback invoked for each progress event.

pub fn progress_channel(self) -> (Self, ProgressReceiver)

Creates a tokio::sync::watch channel for async progress consumption.

Returns (self, receiver). The receiver yields the latest ProgressEvent via .changed().await + .borrow(). Only the most recent event is retained.

The channel is initialized with ProgressEvent::default() (all zeros, empty filename). Use .changed().await rather than eager .borrow() to avoid observing this sentinel value before the first real event.

Composes with on_progress() — if a callback was already set, both the callback and the watch channel fire for every event.

pub fn build(self) -> Result<FetchConfig, FetchError>

Builds the FetchConfig.

Errors

Returns FetchError::InvalidPattern if any glob pattern is invalid.

Trait Implementations

impl Default for FetchConfigBuilder

fn default() -> FetchConfigBuilder

Returns the “default value” for a type.