Struct Config 

pub struct Config {

    pub save_dir: PathBuf,
    pub parse_filename: bool,
    pub filename: String,
    pub threads: usize,
    pub proxy: Proxy<String>,
    pub headers: HashMap<String, String>,
    pub min_chunk_size: u64,
    pub sync_all: bool,
    pub pre_alloc: bool,
    pub write_buffer_size: usize,
    pub cache_high_watermark: usize,
    pub cache_low_watermark: usize,
    pub write_queue_cap: usize,
    pub retry_gap: Duration,
    pub pull_timeout: Duration,
    pub progress_emit_gap: Duration,
    pub accept_invalid_certs: bool,
    pub accept_invalid_hostnames: bool,
    pub write_method: WriteMethod,
    pub retry_times: usize,
    pub local_address: Vec<IpAddr>,
    pub max_speculative: usize,
    pub downloaded_chunk: Vec<ProgressEntry>,
    pub chunk_window: u64,
    pub max_redirects: usize,
    pub cookie_store: bool,
    pub resume: bool,
    pub overwrite: bool,
}

Configuration for a download task.

All fields have sensible defaults; see Config::default for values.

Fields

save_dir: PathBuf

保存的文件夹

parse_filename: bool

文件名解析

filename: String

文件名

threads: usize

Number of threads. Recommended: 32 / 16 / 8. More threads does not always mean faster.

proxy: Proxy<String>

Proxy setting. Supports https, http, and socks5 proxies.

headers: HashMap<String, String>

Custom request headers.

min_chunk_size: u64

Minimum chunk size in bytes. Recommended: 1024 * 1024

• Chunks that are too small may cause heavy contention.
• When chunking is no longer possible, speculative mode is used.

sync_all: bool

Whether to ensure data is fully flushed to disk. Recommended: false

Set to true only if you need to power off immediately after download.

pre_alloc: bool

Reserve the whole file size on disk before downloading. Recommended: false

Claiming the space up front keeps the file in fewer fragments and turns a full disk into an error before any bytes are fetched instead of halfway through. The cost depends on the platform: fallocate on Unix and SetFileValidData on Windows reserve the space instantly, but without them the fallback writes zeros across the whole file, which takes as long as a full-size write pass.

SetFileValidData needs the SeManageVolumePrivilege, which is enabled automatically when available; without it Windows falls back to the zero-fill path. Failure to reserve is reported as crate::Event::AllocError and does not stop the download.

write_buffer_size: usize

Write buffer size in bytes. Recommended: 16 * 1024 * 1024

• Only effective for WriteMethod::Std. Reduces the number of write syscalls by batching small writes into larger ones via BufWriter.
• Not used for WriteMethod::Mmap, as the buffer is managed by the OS.

cache_high_watermark: usize

Cache high watermark in bytes. Recommended: 16 * 1024 * 1024

When the byte merge buffer reaches this size, a merge flush is triggered to reduce the buffer to cache_low_watermark or below.

• Only effective for WriteMethod::Std.
• Not used for WriteMethod::Mmap.

cache_low_watermark: usize

Cache low watermark in bytes. Recommended: 8 * 1024 * 1024

After a merge flush, the byte merge buffer size is reduced to this level or below.

• Only effective for WriteMethod::Std.
• Not used for WriteMethod::Mmap.

write_queue_cap: usize

Write queue capacity. Recommended: 10240

If download threads fill the write queue, backpressure is applied to slow down downloads and prevent excessive memory usage.

retry_gap: Duration

Default retry interval after a request failure. Recommended: 500ms

If the server returns a Retry-After header, that value takes precedence.

pull_timeout: Duration

Pull timeout. Recommended: 5s

If no bytes are received within pull_timeout after sending the request, the connection is dropped and re-established. This helps TCP detect congestion and can improve download speed.

progress_emit_gap: Duration

Minimum interval between crate::Event::Progress emissions. Recommended: 500ms

The progress reporter runs on its own timer, so this cadence is driven purely by progress_emit_gap and is never delayed by other download work (flushing, state saving, event forwarding) or by a slow consumer — the event channel is unbounded, so crate::Event::Progress is sent without blocking. Set it smaller for a smoother progress bar, larger to cut channel traffic. Duration::ZERO emits at the maximum rate (busy-loop, not recommended).

accept_invalid_certs: bool

Whether to accept invalid certificates (dangerous). Recommended: false

accept_invalid_hostnames: bool

Whether to accept invalid hostnames (dangerous). Recommended: false

write_method: WriteMethod

Write method. Recommended: WriteMethod::Mmap

• WriteMethod::Mmap is fastest — it delegates writes to the OS, but:
  1. On 32-bit systems, the maximum file size is 4 GB, so it automatically falls back to WriteMethod::Std.
  2. Mmap requires the file size to be known and byte-range support from the server; when the fast_download flag (set during prefetch) is false, it falls back to WriteMethod::Std.
  3. In rare cases, the OS may cache all data in memory and flush it all at once after the download completes, causing a long post-download delay.
• WriteMethod::Std has the best compatibility. Out-of-order chunks are re-ordered into sequential order by the cache layer before being written.

retry_times: usize

Number of retries for fetching metadata. Recommended: 10. Note: this is not the retry count during download.

local_address: Vec<IpAddr>

Local IP addresses to bind for outgoing requests. Recommended: Vec::new()

If you have multiple network interfaces, you can provide their IP addresses; each time the puller is cloned (e.g. on retry or work-stealing) the next address in the list is used. This may not always improve speed.

max_speculative: usize

Maximum number of speculative workers. Recommended: 3

When the remaining chunk is smaller than min_chunk_size and cannot be split, speculative mode is used. Up to max_speculative workers compete on the same chunk to prevent the download from stalling near 99%.

downloaded_chunk: Vec<ProgressEntry>

Already downloaded chunks (resume progress), stored as an HTTP Range-style list, e.g. downloaded_chunk = "1-3,4-9". Ends are inclusive, matching the HTTP Range header (bytes=1-3 covers bytes 1,2,3); the internal half-open start..end is mapped to start-(end-1) on disk. Absent when nothing has been downloaded yet.

chunk_window: u64

Smoothing window for downloaded chunks in bytes. Recommended: 8 * 1024

Filters out small gaps in downloaded_chunk that are smaller than chunk_window to reduce the number of HTTP requests.

max_redirects: usize

Maximum number of redirects. Recommended value: 20

cookie_store: bool

Enable cookie store. When true, the client will automatically save Set-Cookie headers from responses and send matching cookies in subsequent requests (including across redirects).

resume: bool

是否尝试断点续传，推荐值: true

overwrite: bool

是否覆盖已存在的文件，推荐值: false

Trait Implementations

impl Clone for Config

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<Config> for PartialConfig

fn from(full: Config) -> Self

Converts to this type from the input type.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.