Struct PartialConfig 

pub struct PartialConfig {

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

Fields

save_dir: Option<PathBuf>

保存的文件夹

parse_filename: Option<bool>

文件名解析

filename: Option<String>

文件名

threads: Option<usize>

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

proxy: Option<Proxy<String>>

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

headers: Option<HashMap<String, String>>

Custom request headers.

min_chunk_size: Option<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: Option<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: Option<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: Option<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: Option<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: Option<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: Option<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: Option<Duration>

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

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

pull_timeout: Option<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: Option<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: Option<bool>

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

accept_invalid_hostnames: Option<bool>

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

write_method: Option<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: Option<usize>

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

local_address: Option<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: Option<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: Option<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: Option<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: Option<usize>

Maximum number of redirects. Recommended value: 20

cookie_store: Option<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: Option<bool>

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

overwrite: Option<bool>

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

Implementations

impl PartialConfig

pub fn merge_progress(&mut self, progress: ProgressEntry)

Merge a freshly-written byte range into this partial config’s progress.

The range is folded into downloaded_chunk (created if absent), keeping it normalized and de-duplicated. This is the in-memory counterpart of DownloadState::merge_progress: callers use it to record progress before handing the config to resume.

Trait Implementations

impl Clone for PartialConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ConfigLayer for PartialConfig

type Full = Config

对应的全量配置结构体类型

fn inherit_from(&mut self, parent: &Self)

继承合并：如果自己为空，则向 parent 借用

fn simplify_from(&mut self, parent: &Self)

差分化简：移除与 parent 相同的字段，以及 parent 未设置时与默认值相同的字段

fn build(self) -> Self::Full

构建全量结构体：填补所有空白字段为默认值

fn from_full(full: Self::Full) -> Self

从全量结构体构造 Partial：所有字段包装为 Some

impl Debug for PartialConfig

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

Formats the value using the given formatter.

impl Default for PartialConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for PartialConfig

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 PartialEq for PartialConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for PartialConfig

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for PartialConfig