zlayer-toolchain 0.14.3

//! Error types for the toolchain provisioning subsystem.
//!
//! The variant names (`RegistryError`, `CacheError`, `IoError`) mirror the
//! subset of `zlayer_builder::error::BuildError` this crate bridges to via a
//! `From` impl in the builder, so toolchain-provisioning errors (source build +
//! prebuilt fetch) flow back through `?` at the builder call sites unchanged.

use thiserror::Error;

/// Errors raised while resolving or installing a runtime toolchain.
#[derive(Debug, Error)]
pub enum ToolchainError {
    /// Registry / download / resolution failure (Homebrew API, GHCR blob pull,
    /// `RepoSources` discovery, archive extraction, …). Also covers
    /// toolchain-artifact registry operations: publishing a built toolchain to
    /// an OCI registry and pulling one back down.
    #[error("Registry error: {message}")]
    RegistryError {
        /// Underlying registry error description.
        message: String,
    },

    /// Cache or config-serialisation failure.
    #[error("Cache error: {message}")]
    CacheError {
        /// Underlying cache error description.
        message: String,
    },

    /// A downloaded artifact's sha256 did not match the expected digest (either
    /// a formula `urls.stable.checksum`, an upstream-published digest, or a
    /// lockfile pin). The partial download is deleted before this is returned.
    #[error("digest mismatch for {tool}: expected {expected}, got {actual}")]
    DigestMismatch {
        /// The tool / artifact whose digest failed to verify.
        tool: String,
        /// The expected sha256 (bare lowercase hex).
        expected: String,
        /// The sha256 actually computed over the downloaded bytes.
        actual: String,
    },

    /// A containerized build step was required but no runtime executor has
    /// been registered. Toolchain builds must NEVER fall back to a host
    /// subprocess, so this is a hard error rather than a degraded path.
    #[error("no container build executor registered; cannot build toolchain '{tool}' in isolation (register one via zlayer_toolchain::executor::set_container_executor)")]
    ExecutorUnavailable {
        /// The tool whose containerized build could not be executed.
        tool: String,
    },

    /// A build recipe uses constructs this crate's recipe interpreter does not
    /// support, so the toolchain cannot be built from it.
    #[error("recipe for toolchain '{tool}' uses unsupported constructs: {}", constructs.join(", "))]
    RecipeUnsupported {
        /// The tool whose recipe could not be interpreted.
        tool: String,
        /// The unsupported recipe constructs that were encountered.
        constructs: Vec<String>,
    },

    /// Underlying I/O error.
    #[error("IO error: {0}")]
    IoError(#[from] std::io::Error),
}

/// Result alias for toolchain operations.
pub type Result<T, E = ToolchainError> = std::result::Result<T, E>;