Enum Event 

pub enum Event {
    Prefetch(UrlInfo),
    PrefetchError(ReqwestResponseError),
    GenPathError(Error),
    StateSaveError(StateError),
    BuildClientError(Error),
    BuildPusherError(Error),
    Allocating(u64),
    AllocError(Error),
    RenameFailed(Error),
    Renamed(PathBuf),
    Start {
        tmp_path: PathBuf,
        config_path: PathBuf,
        parsed_config: PartialConfig,
    },
    Resumed {
        config_path: PathBuf,
        progress: Vec<ProgressEntry>,
        size: u64,
    },
    ResumeError(StateError),
    Pulling(WorkerId),
    PullError(WorkerId, Error),
    PullTimeout(WorkerId),
    PullProgress(WorkerId, ProgressEntry),
    Pushing(WorkerId, ProgressEntry),
    PushError(WorkerId, ProgressEntry, Error),
    PushProgress(ProgressEntry),
    Progress(ProgressSample),
    Flushing,
    FlushError(Error),
    Finished(WorkerId),
    Terminated(TerminationReason),
}

Events emitted by a download run, consumed through the crossfire channel returned by crate::create_channel.

Events cover the full lifecycle: prefetch (Event::Prefetch), pipeline setup (Event::Start), per-worker fetch/write progress (Event::Pulling … Event::Finished), aggregated progress (Event::Progress), resume (Event::Resumed, Event::ResumeError), and completion (Event::Renamed). Error variants (*Error) report failures without aborting the stream, so a consumer can decide whether to retry, cancel, or surface them in a UI.

Every run ends with exactly one Event::Terminated, which is always the last event on the channel. A consumer that only needs the outcome can wait for it instead of draining until the channel disconnects.

Variants

Prefetch(UrlInfo)

Emitted after the prefetch step resolves the remote file’s metadata.

Carries the UrlInfo (size, identity headers, range support) so a caller can inspect the remote before or while the download proceeds.

PrefetchError(ReqwestResponseError)

The prefetch request failed (server unreachable, non-2xx response, etc.).

Fatal for the download: without UrlInfo the engine cannot plan ranges.

GenPathError(Error)

Failed to compute the output / .part / .fd paths.

For example the target directory is not writable or the file name is invalid on this platform.

StateSaveError(StateError)

Persisting the .fd state file failed (see StateError).

Non-fatal for the current run, but the download can no longer be resumed reliably if it is interrupted afterwards.

BuildClientError(Error)

Building the HTTP client failed (TLS / backend initialization, etc.).

BuildPusherError(Error)

Creating the output sink — opening the .part file — failed.

Allocating(u64)

Disk space for the whole file is about to be reserved, carrying the target size in bytes.

Only emitted when crate::Config::pre_alloc is enabled and the remote size is known. Where the platform has no fast-reservation path this is followed by a full-size zero-fill pass, which can take a while — this event exists so a UI can say so instead of appearing frozen.

AllocError(Error)

Reserving disk space failed.

Non-fatal: the download continues and the file grows on demand. The trade-off is more fragmentation and the chance of running out of space mid-download rather than up front.

RenameFailed(Error)

The final rename of the .part file to its destination failed.

The success counterpart is Event::Renamed. The bytes are already on disk under the .part name, so they can still be resumed or retried.

Renamed(PathBuf)

Emitted after the .part file is successfully renamed to its final destination. Carries the actual landing path, which in unique mode may differ from the originally-planned name (e.g. xxx (1).mp4) when the target got occupied during the download.

Start

Emitted once the pipeline is set up and writing is about to begin.

Carries the .part path, the .fd state-file path, and the resolved PartialConfig actually used for this run (after merging any resumed progress and applying defaults).

Fields

tmp_path: PathBuf

config_path: PathBuf

parsed_config: PartialConfig

Resumed

Emitted when a download resumes from a previously-saved state, before Event::Start. Carries the progress that will be continued from and the total file size, so a UI can show e.g. “resuming from 42%”.

Fields

config_path: PathBuf

progress: Vec<ProgressEntry>

size: u64

ResumeError(StateError)

Emitted when an explicit resume() call cannot continue the download. Unlike download() (which silently falls back to a full re-download), resume() reports the failure so the caller can decide what to do.

Pulling(WorkerId)

Worker id started fetching its assigned byte range from the network.

PullError(WorkerId, Error)

Worker id failed to fetch its assigned range (network / decode error).

PullTimeout(WorkerId)

Worker id’s fetch exceeded its time budget and was aborted.

PullProgress(WorkerId, ProgressEntry)

Worker id pulled some bytes into memory.

ProgressEntry describes the contiguous range that just arrived from the network but is not yet written to disk.

Pushing(WorkerId, ProgressEntry)

Worker id is handing a pulled range to the sink (writing it to .part).

ProgressEntry is the range being written.

PushError(WorkerId, ProgressEntry, Error)

Worker id failed to write ProgressEntry to the sink.

PushProgress(ProgressEntry)

A range was written to the sink.

ProgressEntry is the range persisted (at least to the OS page cache) by this write. This drives the progress bar and the resume bookkeeping; it is intentionally emitted before fsync, so it reflects “written”, not “durably flushed”.

Progress(ProgressSample)

Aggregated download progress, emitted on a fixed cadence (crate::Config::progress_emit_gap) by a dedicated reporter task.

Unlike Event::PushProgress, which fires once per written byte range, this carries a full ProgressSample — the current progress snapshot plus computed transfer rates — so a consumer can render a progress bar directly without re-accumulating individual ranges.

The reporter runs on its own timer, so the cadence is driven purely by progress_emit_gap and is never delayed by flushing, state saving, event forwarding, or a slow consumer (the channel is unbounded). One final Progress is sent when the run ends (success, cancellation, or error).

Flushing

The sink is being flushed and synced to the .part file.

FlushError(Error)

Flushing / syncing the sink failed.

Finished(WorkerId)

Worker id completed its assigned range and exited.

Terminated(TerminationReason)

The run has ended. Sent exactly once, as the last event on the channel.

Preceding *Error events carry the details of whatever went wrong; this one only reports the outcome.

Trait Implementations

impl Debug for Event

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

Formats the value using the given formatter.