Enum DownloadError 

pub enum DownloadError {
    Transport {
        provider: String,
        reason: String,
    },
    Timeout {
        provider: String,
    },
    Verify(VerifyError),
    NoProviders {
        needed: usize,
    },
    NotFound {
        content: String,
    },
    MetadataProbeFailed {
        content: String,
        holders: usize,
        reasons: Vec<String>,
    },
    PagedPrologueUnsupported {
        provider: String,
        chunk_count: u64,
        delivered: u64,
    },
    Cancelled,
    State(String),
    Sink(String),
    NotDownloadable,
    TaskEnded,
}

An error from a download operation.

Variants

Transport

A transport-level failure fetching from one provider (connect failed, stream dropped, availability/range RPC errored, timeout). Carries the reason as text. Recoverable: the orchestrator marks the provider suspect and re-queues the range to another holder.

Fields

provider: String

The provider peer_id (64-hex) the failure came from.

reason: String

The underlying reason (stable, greppable text).

Timeout

A range fetch exceeded the configured per-range timeout (DownloadConfig::range_timeout) — a too-slow or stalled source. Recoverable: the range is re-queued to another holder and the slow source is backed off (its TimedOut outcome is reported to the selector).

Fields

provider: String

The provider peer_id (64-hex) whose fetch timed out.

Verify(VerifyError)

A fetched range failed integrity verification. Recoverable: the bad range is discarded and re-fetched from a different provider, and the serving provider is penalized.

The wrapped reason is SANITIZED here for the same reason a transport reason is: a verify failure routinely quotes peer-reported metadata (a first-frame root, a declared length), so it is untrusted text arriving through a different door.

NoProviders

A still-needed range has no live provider left to fetch it from — every known holder has been tried + failed and a fresh find_providers discovered no more. This is terminal for the download (there is nowhere left to get the missing bytes).

Fields

needed: usize

How many ranges were still missing when the provider set was exhausted.

NotFound

The content could not be fetched at all — either find_providers returned no holders, or no located holder could answer the metadata probe. Terminal.

content names the content id AND which of those two steps failed: the message must never blame discovery for a probe failure (that ambiguity cost four #1586 investigations).

Fields

content: String

The content id that could not be fetched, plus the step that failed.

MetadataProbeFailed

Holders WERE located and confirmed, but not one of them could seed the resource layout. Terminal.

This is the named replacement for reporting that outcome as a generic NotFound. The two failures are not the same event and must not read the same: “nobody has this content” is a discovery result, while “several holders have it and every one of them served metadata this reader cannot use” is a compatibility or hostility result, and only the second is actionable by whoever operates the holders. Collapsing them cost four separate #1586 investigations.

reasons carries the per-holder cause, which was previously written to a tracing::debug! and then dropped — so the one fact that identifies the fault survived only if debug logging happened to be on.

Fields

content: String

The content id whose layout could not be established.

holders: usize

How many confirmed holders were probed.

reasons: Vec<String>

One peer_id: reason line per probed holder, in probe order.

PagedPrologueUnsupported

The resource’s chunk_lens paged prologue could not be COMPLETED — the stream ended short of the declared chunk_count, or a first frame that declared no multi-page layout was followed by a frame paging one. Recoverable per holder: the range is retried elsewhere and the adoption path probes the next holder.

Fail-closed, not a reader limitation

This reader DOES reassemble a paged prologue (SPEC.md §2.2), so a conforming multi-page holder reads end-to-end. The error is raised only when the layout stays INCOMPLETE — a decrypt-input array short of chunk_count would decrypt every chunk to garbage, so it is refused rather than adopted partial. It reports the declared count and the entries delivered so a short prologue is distinguishable from “nobody holds this content”. (A page that violates a placement rule — misaligned, duplicated, overshooting — surfaces instead as a recoverable Transport naming the broken rule.)

Fields

provider: String

The provider peer_id (64-hex) whose layout could not be assembled.

chunk_count: u64

The whole array’s declared entry count.

delivered: u64

How many entries had been delivered when the reader gave up.

Cancelled

The download was cancelled via DownloadHandle::cancel. Terminal (by request).

State(String)

Persisting or loading resume state failed. Carries the reason.

Sink(String)

The sink (store-write path) rejected a write. Carries the reason.

NotDownloadable

The requested content id cannot be downloaded as a byte stream — a bare store id names a whole store (many capsules), not a single resource/capsule to fetch. Supply a root/capsule or resource content id.

TaskEnded

The orchestrator task ended unexpectedly (its channel closed before a terminal result). This indicates a bug or an aborted runtime, not a normal download outcome.

Implementations

impl DownloadError

pub fn transport(provider: impl Into<String>, reason: impl Display) -> Self

Build a DownloadError::Transport for provider from anything displayable.

pub fn sink(reason: impl Display) -> Self

Build a DownloadError::Sink from anything displayable.

pub fn state(reason: impl Display) -> Self

Build a DownloadError::State from anything displayable.

pub fn is_recoverable(&self) -> bool

Whether this error is recoverable per range (the download can continue by retrying the range elsewhere) rather than terminal for the whole download.

PagedPrologueUnsupported is recoverable for the same reason a transport failure is: it rules out ONE holder’s stream, not the content. The other new variants are terminal — each already reports that every holder was tried.

pub fn attributed_to(self, peer_id: &str) -> Self

Fill in an as-yet-unattributed provider with the peer the failure came from, leaving every other variant untouched.

The pure reassembly core cannot know which peer it is reading, so it raises errors with an empty provider for the transport layer to stamp. Stamping must not be done by WRAPPING, which is what this replaced: re-wrapping every reassembly failure into a Transport flattened the typed ones, so a variant the reassembler raised deliberately — and that is_recoverable treats specially — could never be observed by a caller.

An already-attributed error is returned unchanged, so stamping twice cannot relabel a failure onto the wrong peer.

Trait Implementations

impl Debug for DownloadError

Debug delegates to the SANITIZING Display rather than printing raw fields.

Debug is not a developer-only rendering in practice: tracing’s ?field, a {:?} in a log line, and every unwrap/expect panic message emit it. A derived Debug would print the untrusted provider / reason / verify text verbatim — unbounded, with markup intact — bypassing the very sanitization Display applies. One rendering, one door.

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

Formats the value using the given formatter.

impl Display for DownloadError

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

Formats the value using the given formatter.

impl Error for DownloadError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<HopPathError> for DownloadError

fn from(e: HopPathError) -> Self

Converts to this type from the input type.

impl From<VerifyError> for DownloadError

fn from(source: VerifyError) -> Self

Converts to this type from the input type.