Struct DownloadBuilder 

pub struct DownloadBuilder { /* private fields */ }

Fluent builder for a single download.

Create one via crate::builder() or DownloadBuilder::new().

Implementations

impl DownloadBuilder

pub fn new(url: impl Into<String>) -> Self

Start building a download for url.

pub fn output(self, path: impl Into<String>) -> Self

Set the output file path or directory.

If a directory is given, the filename is inferred from the URL.

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

Number of parallel HTTP connections. Clamped to 1–32.

pub fn speed_limit(self, bytes_per_sec: u64) -> Self

Global speed limit in bytes per second.

pub fn proxy(self, url: impl Into<String>) -> Self

HTTP proxy URL (e.g. "http://proxy:8080" or "socks5://host:1080").

pub fn proxy_auth( self, user: impl Into<String>, pass: impl Into<String>, ) -> Self

Proxy credentials (optional, required only for authenticated proxies).

pub fn sha256(self, hash: impl Into<String>) -> Self

Expect a SHA-256 digest. The download fails if the file doesn’t match.

pub fn sha512(self, hash: impl Into<String>) -> Self

Expect a SHA-512 digest.

pub fn sha1(self, hash: impl Into<String>) -> Self

Expect a SHA-1 digest.

pub fn md5(self, hash: impl Into<String>) -> Self

Expect an MD5 digest.

pub fn blake3(self, hash: impl Into<String>) -> Self

Expect a BLAKE3 digest.

pub fn verify_from(self, url: impl Into<String>) -> Self

Download a checksum sidecar file from url and use it to populate the expected digest automatically.

Supports GNU (<hash> <file>) and BSD (SHA256 (<file>) = <hash>) formats.

pub fn header(self, name: impl Into<String>, value: impl Into<String>) -> Self

Add a custom HTTP request header. Can be called multiple times.

pub fn retry(self, config: RetryConfig) -> Self

Override the default retry policy.

pub fn range(self, start: u64, end: u64) -> Self

Request only a byte range of the file: [start, end] (both inclusive).

Sends Range: bytes=start-end. The returned DownloadResult will have bytes_downloaded equal to end - start + 1.

pub fn quiet(self, q: bool) -> Self

Suppress all progress output.

pub fn download(self) -> Result<DownloadResult, KgetError>

Execute the download synchronously and return metrics on success.

pub fn download_to_bytes(self) -> Result<Vec<u8>, KgetError>

Download entirely into memory and return the raw bytes.

Respects .range(), .proxy(), and .header() settings. Does not write to disk, so .output() is ignored.

pub fn download_to_reader(self) -> Result<impl Read, KgetError>

Download to memory and return an impl Read.

Convenience wrapper over download_to_bytes.

pub fn spawn( self, ) -> (JoinHandle<Result<DownloadResult, KgetError>>, Receiver<DownloadEvent>)

Spawn the download in a background thread and return an event channel.

The DownloadEvent receiver yields progress updates until the channel is closed (on completion or error). Call .join() on the handle to retrieve the final DownloadResult.