Struct DownloadPlan 

pub struct DownloadPlan { /* private fields */ }

A prepared, not-yet-started download.

Produced by plan / plan_resume after the remote has been prefetched and the disk inspected. Holding one keeps the prefetch Response open so the first range request can reuse it; dropping one abandons the download without having touched the filesystem.

Implementations

impl DownloadPlan

pub const fn info(&self) -> &UrlInfo

Metadata resolved for the remote file: size, identity headers, and whether the server supports ranged (and therefore parallel) requests.

pub const fn config(&self) -> &Config

The fully-resolved configuration this plan will run with.

pub fn final_path(&self) -> &Path

Where the finished file is intended to land.

When overwrite is disabled the actual destination is uniquified at the very end, so the file may land on a name (1).ext variant instead; Event::Renamed carries the path it really landed on.

pub fn tmp_path(&self) -> &Path

The .part file this plan inspected.

For ResumeOutcome::Resumable and ResumeOutcome::Mismatch this is the existing file that was examined. For a normal ResumeOutcome::Fresh it is the name that was free at probe time — because planning claims nothing, a concurrent download can take it first, in which case starting the plan moves on to the next free name. A manifest-driven Fresh plan instead reports the .part paired with that manifest.

pub fn config_path(&self) -> &Path

The .fd state file paired with DownloadPlan::tmp_path.

pub const fn resume_outcome(&self) -> &ResumeOutcome

What the disk probe found, and therefore what starting the plan will do.

pub async fn start(self)

Run the plan as probed.

ResumeOutcome::Resumable continues from the saved progress and ResumeOutcome::Fresh downloads the whole file. A ResumeOutcome::Mismatch falls back to a fresh download, except for a plan made by plan_resume, where it is reported as Event::ResumeError and ends the run — that caller asked to continue one specific file, not to fetch it again.

Emits exactly one Event::Terminated as the last event on the channel.

pub async fn start_fresh(self)

Ignore any resumable state and download the whole file again.

With overwrite enabled the existing .part is reused as scratch space and every byte is rewritten; otherwise a new, unclaimed .part name is taken so the existing one is left untouched.

Emits exactly one Event::Terminated as the last event on the channel.

pub async fn start_forced_resume(self)

Continue from a ResumeOutcome::Mismatch state despite the failed validation.

This is only safe when the byte layout is unchanged, so the forced resume is refused unless the mismatch is limited to the identity headers (etag / last-modified) and both sides agree on the file size. A size change means the recorded ranges describe different bytes, and reusing them would splice two versions of the file together.

The .part is also measured against the recorded progress: a file shorter than the highest recorded offset is rejected with StateError::Truncated, because the sink would extend it with zeros over the missing span and never fetch those bytes.

A refusal is reported as Event::ResumeError followed by TerminationReason::Failed. Called on a plan that is not a mismatch, this behaves exactly like DownloadPlan::start.

Emits exactly one Event::Terminated as the last event on the channel.