laded 1.2.0

A chunk-based file downloader and XML catalog archiving engine.
Documentation
/*  src/error.rs  Centralized error definitions for the laded engine.
 *
 *  Copyright 2026 Emerge Cooperative
 *
 *  Permission is hereby granted, free of charge, to any person
 *  obtaining a copy of this software and associated documentation
 *  files (the "Software"), to deal in the Software without
 *  restriction, including without limitation the rights to use, copy,
 *  modify, merge, publish, distribute, sublicense, and/or sell copies
 *  of the Software, and to permit persons to whom the Software is
 *  furnished to do so, subject to the following conditions:
 *
 *  The above copyright notice and this permission notice shall be
 *  included in all copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 *  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 *  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 *  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 *                                                                    */

use thiserror::Error;

/// `Error` standardizes every failure state that can occur here
///
/// DESIGN RATIONALE:
/// Modern Rust libraries avoid returning untyped strings or
/// `Box<dyn Error>` because caller applications need to
/// programmatically inspect and react to specific failure modes (eg,
/// retrying if mirrors fail vs aborting if XML format is corrupted).
/// We use the `thiserror` procedural macro to auto-generate
/// `std::fmt::Display` and `std::error::Error` trait implementations
/// without verbose boilerplate.
#[derive(Error, Debug)]
pub enum Error {
    /// Triggered when no valid download sources are specified
    #[error("No mirror URLs available in catalog or command arguments")]
    NoMirrors,

    /// Triggered when no mirrors are available
    #[error("No download mirrors available")]
    NoMirrorsAvailable,

    /// Triggered when a chunk fails to download
    #[error("Failed to download chunk {0} from all available mirrors")]
    ChunkDownloadFailed(usize),

    /// Triggered when the mirror queue runs dry before fully downloaded
    #[error("Download incomplete. {0} chunks failed across all mirrors")]
    IncompleteDownload(usize),

    /// Triggered when all provided download mirrors time out
    #[error("All mirrors failed or were banned due to corruption/errors")]
    AllMirrorsFailed,

    /// Wraps errors encountered during XML decoding via `quick-xml`.
    #[error("XML parse error: {0}")]
    XmlParse(String),

    /// Wraps errors encountered during XML serialization
    #[error("XML serialization error: {0}")]
    XmlSerialize(String),

    /// Triggered if `<hash>` tag text contains invalid Base64
    #[error("Base64 decoding error: {0}")]
    Base64Decode(String),

    /// Triggered if binary lengths do not align cleanly with SHA-256
    #[error("Hash table length is not a multiple of 32 bytes")]
    InvalidHashLength,

    /// Triggered when a block hash fails isn't 32-byte (256-bit) length
    #[error("Hash decoded to {0} bytes, expected 32")]
    InvalidHashSize(usize),

    /// Converts std::io::Error automatically using `#[from]`.
    /// Design Note: This allows functions returning `Result<T, Error>`
    /// to use the `?` operator directly on file operations.
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// Captures HTTP layer network failures generated by `reqwest`.
    #[error("Network error: {0}")]
    Network(String),
}