uv_distribution/

error.rs

use std::fmt;
use std::path::PathBuf;

use owo_colors::OwoColorize;
use tokio::task::JoinError;

use crate::metadata::MetadataError;
use uv_cache::Error as CacheError;
use uv_client::WrappedReqwestError;
use uv_distribution_filename::{VariantLabel, WheelFilename, WheelFilenameError};
use uv_distribution_types::{
    InstalledDist, InstalledDistError, IsBuildBackendError, UnsupportedVariantProperties,
};
use uv_fs::Simplified;
use uv_git::GitError;
use uv_macros::DebugNoInline;
use uv_normalize::PackageName;
use uv_pep440::{Version, VersionSpecifiers};
use uv_platform_tags::Platform;
use uv_pypi_types::{HashAlgorithm, HashDigest};
use uv_python_types::PythonVariant;
use uv_redacted::SafeUrl;
use uv_types::AnyErrorBuild;

#[derive(Debug, Clone, Copy)]
pub struct PythonVersion {
    pub(crate) version: (u8, u8),
    pub(crate) variant: PythonVariant,
}

impl fmt::Display for PythonVersion {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let (major, minor) = self.version;
        write!(f, "{major}.{minor}{}", self.variant.executable_suffix())
    }
}

#[derive(DebugNoInline, thiserror::Error)]
pub enum Error {
    #[error("Wheel variants are not supported yet: `{0}`")]
    UnsupportedWheelVariant(Box<WheelFilename>),
    #[error("Wheel variant `{label}` requires unsupported properties: {properties}")]
    IncompatibleWheelVariant {
        label: VariantLabel,
        properties: UnsupportedVariantProperties,
    },
    #[error("Building source distributions is disabled")]
    NoBuild,
    #[error("Building source distributions for `{0}` is disabled")]
    NoBuildPackage(PackageName),

    // Network error
    #[error(transparent)]
    InvalidUrl(#[from] uv_distribution_types::ToUrlError),
    #[error("Expected a file URL, but received: {0}")]
    NonFileUrl(SafeUrl),
    #[error(transparent)]
    Git(#[from] uv_git::GitResolverError),
    #[error(transparent)]
    Reqwest(#[from] WrappedReqwestError),
    #[error(transparent)]
    Client(#[from] uv_client::Error),
    #[error(transparent)]
    ClientBuild(#[from] uv_client::ClientBuildError),

    // Cache writing error
    #[error("Failed to read from the distribution cache")]
    CacheRead(#[source] std::io::Error),
    #[error("Failed to write to the distribution cache")]
    CacheWrite(#[source] std::io::Error),
    #[error("Failed to acquire lock on the distribution cache")]
    CacheLock(#[source] CacheError),
    #[error("Failed to deserialize cache entry")]
    CacheDecode(#[from] rmp_serde::decode::Error),
    #[error("Failed to serialize cache entry")]
    CacheEncode(#[from] rmp_serde::encode::Error),
    #[error("Failed to walk the distribution cache")]
    CacheWalk(#[source] walkdir::Error),
    #[error(transparent)]
    CacheInfo(#[from] uv_cache_info::CacheInfoError),

    // Build error
    #[error(transparent)]
    Build(AnyErrorBuild),
    #[error("Built wheel has an invalid filename")]
    WheelFilename(#[from] WheelFilenameError),
    #[error("Package metadata name `{metadata}` does not match given name `{given}`")]
    WheelMetadataNameMismatch {
        given: PackageName,
        metadata: PackageName,
    },
    #[error("Package metadata version `{metadata}` does not match given version `{given}`")]
    WheelMetadataVersionMismatch { given: Version, metadata: Version },
    #[error(
        "Package metadata name `{metadata}` does not match `{filename}` from the wheel filename"
    )]
    WheelFilenameNameMismatch {
        filename: PackageName,
        metadata: PackageName,
    },
    #[error(
        "Package metadata version `{metadata}` does not match `{filename}` from the wheel filename"
    )]
    WheelFilenameVersionMismatch {
        filename: Version,
        metadata: Version,
    },
    /// This shouldn't happen, it's a bug in the build backend.
    #[error(
        "The built wheel `{}` is not compatible with the current Python {} on {}",
        filename,
        python_version,
        python_platform.pretty(),
    )]
    BuiltWheelIncompatibleHostPlatform {
        filename: WheelFilename,
        python_platform: Platform,
        python_version: PythonVersion,
    },
    /// This may happen when trying to cross-install native dependencies without their build backend
    /// being aware that the target is a cross-install.
    #[error(
        "The built wheel `{}` is not compatible with the target Python {} on {}. Consider using `--no-build` to disable building wheels.",
        filename,
        python_version,
        python_platform.pretty(),
    )]
    BuiltWheelIncompatibleTargetPlatform {
        filename: WheelFilename,
        python_platform: Platform,
        python_version: PythonVersion,
    },
    #[error("Failed to parse metadata from built wheel")]
    Metadata(#[from] uv_pypi_types::MetadataError),
    #[error("Failed to read metadata: {}", _0.user_display())]
    WheelMetadata(PathBuf, #[source] Box<uv_metadata::Error>),
    #[error("Failed to read metadata from installed package `{0}`")]
    ReadInstalled(Box<InstalledDist>, #[source] InstalledDistError),
    #[error("Failed to extract archive: {0}")]
    Extract(String, #[source] uv_extract::Error),
    #[error("The source distribution is missing a `PKG-INFO` file")]
    MissingPkgInfo,
    #[error("The source distribution `{}` has no subdirectory `{}`", _0, _1.display())]
    MissingSubdirectory(SafeUrl, PathBuf),
    #[error("The source distribution `{0}` is missing Git LFS artifacts.")]
    MissingSourceDistGitLfsArtifacts(SafeUrl, #[source] GitError),
    #[error("The wheel `{0}` is missing Git LFS artifacts.")]
    MissingWheelGitLfsArtifacts(SafeUrl, #[source] GitError),
    #[error("Failed to extract static metadata from `PKG-INFO`")]
    PkgInfo(#[source] uv_pypi_types::MetadataError),
    #[error("The source distribution is missing a `pyproject.toml` file")]
    MissingPyprojectToml,
    #[error("Failed to extract static metadata from `pyproject.toml`")]
    PyprojectToml(#[source] uv_pypi_types::MetadataError),
    #[error(transparent)]
    MetadataLowering(#[from] MetadataError),
    #[error("Distribution not found at: {0}")]
    NotFound(SafeUrl),
    #[error("Attempted to re-extract the source distribution for `{}`, but the {} hash didn't match. Run `{}` to clear the cache.", _0, _1, "uv cache clean".green())]
    CacheHeal(String, HashAlgorithm),
    #[error("The source distribution requires Python {0}, but {1} is installed")]
    RequiresPython(VersionSpecifiers, Version),
    #[error("Failed to identify base Python interpreter")]
    BaseInterpreter(#[source] std::io::Error),

    /// A generic request middleware error happened while making a request.
    /// Refer to the error message for more details.
    #[error(transparent)]
    ReqwestMiddlewareError(#[from] anyhow::Error),

    /// Should not occur; only seen when another task panicked.
    #[error("The task executor is broken, did some other task panic?")]
    Join(#[from] JoinError),

    /// An I/O error that occurs while exhausting a reader to compute a hash.
    #[error("Failed to hash distribution")]
    HashExhaustion(#[source] std::io::Error),

    #[error("Hash mismatch for `{distribution}`\n\nExpected:\n{expected}\n\nComputed:\n{actual}")]
    MismatchedHashes {
        distribution: String,
        expected: String,
        actual: String,
    },

    #[error(
        "Size mismatch for `{distribution}`: expected {expected} bytes, but downloaded {actual} bytes"
    )]
    MismatchedSize {
        distribution: String,
        expected: u64,
        actual: u64,
    },

    #[error(
        "Content-Length mismatch for `{distribution}`: expected {expected} bytes, but the server advertised {actual} bytes"
    )]
    MismatchedContentLength {
        distribution: String,
        expected: u64,
        actual: u64,
    },

    #[error(
        "Range response size mismatch for `{distribution}`: expected {expected} bytes from Content-Range, but received {actual} bytes"
    )]
    MismatchedRangeSize {
        distribution: String,
        expected: u64,
        actual: u64,
    },

    #[error(
        "Hash-checking is enabled, but no hashes were provided or computed for: {distribution}"
    )]
    MissingHashes { distribution: String },

    #[error(
        "Hash-checking is enabled, but no hashes were computed for `{distribution}`\n\nExpected:\n{expected}"
    )]
    MissingActualHashes {
        distribution: String,
        expected: String,
    },

    #[error(
        "Hash-checking is enabled, but no hashes were provided for `{distribution}`\n\nComputed:\n{actual}"
    )]
    MissingExpectedHashes {
        distribution: String,
        actual: String,
    },

    #[error("Hash-checking is not supported for local directories: {0}")]
    HashesNotSupportedSourceTree(String),

    #[error("Hash-checking is not supported for Git repositories: {0}")]
    HashesNotSupportedGit(String),

    #[error(transparent)]
    InstallWheelError(uv_install_wheel::Error),
}

fn is_not_found_error(mut error: &(dyn std::error::Error + 'static)) -> bool {
    loop {
        if error
            .downcast_ref::<reqwest::Error>()
            .and_then(reqwest::Error::status)
            .is_some_and(|status| status == reqwest::StatusCode::NOT_FOUND)
        {
            return true;
        }
        let Some(source) = error.source() else {
            return false;
        };
        error = source;
    }
}

impl From<reqwest::Error> for Error {
    fn from(error: reqwest::Error) -> Self {
        Self::Reqwest(WrappedReqwestError::from(error))
    }
}

impl From<reqwest_middleware::Error> for Error {
    fn from(error: reqwest_middleware::Error) -> Self {
        match error {
            reqwest_middleware::Error::Middleware(error) => Self::ReqwestMiddlewareError(error),
            reqwest_middleware::Error::Reqwest(error) => {
                Self::Reqwest(WrappedReqwestError::from(error))
            }
        }
    }
}

impl uv_errors::Hinted for Error {
    fn hints(&self) -> uv_errors::Hints<'_> {
        match self {
            Self::Build(err) => err.hints(),
            Self::Client(err) => uv_errors::Hinted::hints(err),
            Self::MetadataLowering(err) => err.hints(),
            _ => uv_errors::Hints::none(),
        }
    }
}

impl IsBuildBackendError for Error {
    fn is_user_failure(&self) -> bool {
        Self::is_user_failure(self)
    }

    fn is_build_backend_error(&self) -> bool {
        match self {
            Self::Build(err) => err.is_build_backend_error(),
            _ => false,
        }
    }
}

impl Error {
    /// Return whether this is an expected user-facing failure.
    pub fn is_user_failure(&self) -> bool {
        match self {
            Self::UnsupportedWheelVariant(_)
            | Self::IncompatibleWheelVariant { .. }
            | Self::NoBuild
            | Self::NoBuildPackage(_)
            | Self::InvalidUrl(_)
            | Self::NonFileUrl(_)
            | Self::WheelFilename(_)
            | Self::WheelMetadataNameMismatch { .. }
            | Self::WheelMetadataVersionMismatch { .. }
            | Self::WheelFilenameNameMismatch { .. }
            | Self::WheelFilenameVersionMismatch { .. }
            | Self::BuiltWheelIncompatibleHostPlatform { .. }
            | Self::BuiltWheelIncompatibleTargetPlatform { .. }
            | Self::Metadata(_)
            | Self::WheelMetadata(..)
            | Self::Extract(..)
            | Self::MissingPkgInfo
            | Self::MissingSubdirectory(..)
            | Self::MissingSourceDistGitLfsArtifacts(..)
            | Self::MissingWheelGitLfsArtifacts(..)
            | Self::PkgInfo(_)
            | Self::MissingPyprojectToml
            | Self::PyprojectToml(_)
            | Self::MetadataLowering(_)
            | Self::NotFound(_)
            | Self::RequiresPython(..)
            | Self::MismatchedHashes { .. }
            | Self::MismatchedSize { .. }
            | Self::MismatchedContentLength { .. }
            | Self::MismatchedRangeSize { .. }
            | Self::MissingHashes { .. }
            | Self::MissingActualHashes { .. }
            | Self::MissingExpectedHashes { .. }
            | Self::HashesNotSupportedSourceTree(_)
            | Self::HashesNotSupportedGit(_) => true,
            Self::Build(error) => error.is_user_failure(),
            Self::InstallWheelError(error) => error.is_user_failure(),
            Self::Git(error) => error.is_user_failure(),
            Self::Reqwest(error) => error.is_user_failure(),
            Self::Client(error) => error.is_user_failure(),
            Self::ClientBuild(error) => error.is_user_failure(),
            Self::CacheRead(_)
            | Self::CacheWrite(_)
            | Self::CacheLock(_)
            | Self::CacheDecode(_)
            | Self::CacheEncode(_)
            | Self::CacheWalk(_)
            | Self::CacheInfo(_)
            | Self::ReadInstalled(..)
            | Self::CacheHeal(..)
            | Self::BaseInterpreter(_)
            | Self::Join(_)
            | Self::HashExhaustion(_) => false,
            Self::ReqwestMiddlewareError(error) => is_not_found_error(error.as_ref()),
        }
    }

    /// Construct a hash mismatch error.
    pub fn hash_mismatch(
        distribution: String,
        expected: &[HashDigest],
        actual: &[HashDigest],
    ) -> Self {
        match (expected.is_empty(), actual.is_empty()) {
            (true, true) => Self::MissingHashes { distribution },
            (true, false) => {
                let actual = actual
                    .iter()
                    .map(|hash| format!("  {hash}"))
                    .collect::<Vec<_>>()
                    .join("\n");

                Self::MissingExpectedHashes {
                    distribution,
                    actual,
                }
            }
            (false, true) => {
                let expected = expected
                    .iter()
                    .map(|hash| format!("  {hash}"))
                    .collect::<Vec<_>>()
                    .join("\n");

                Self::MissingActualHashes {
                    distribution,
                    expected,
                }
            }
            (false, false) => {
                let expected = expected
                    .iter()
                    .map(|hash| format!("  {hash}"))
                    .collect::<Vec<_>>()
                    .join("\n");

                let actual = actual
                    .iter()
                    .map(|hash| format!("  {hash}"))
                    .collect::<Vec<_>>()
                    .join("\n");

                Self::MismatchedHashes {
                    distribution,
                    expected,
                    actual,
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{Error, PythonVersion};
    use std::str::FromStr;
    use uv_distribution_filename::WheelFilename;
    use uv_platform_tags::{Arch, Os, Platform};
    use uv_python_types::PythonVariant;

    #[test]
    fn built_wheel_error_formats_freethreaded_python() {
        let err = Error::BuiltWheelIncompatibleHostPlatform {
            filename: WheelFilename::from_str(
                "cryptography-47.0.0.dev1-cp315-abi3t-macosx_11_0_arm64.whl",
            )
            .unwrap(),
            python_platform: Platform::new(
                Os::Macos {
                    major: 11,
                    minor: 0,
                },
                Arch::Aarch64,
            ),
            python_version: PythonVersion {
                version: (3, 15),
                variant: PythonVariant::Freethreaded,
            },
        };

        assert_eq!(
            err.to_string(),
            "The built wheel `cryptography-47.0.0.dev1-cp315-abi3t-macosx_11_0_arm64.whl` is not compatible with the current Python 3.15t on macOS aarch64"
        );
    }

    #[test]
    fn built_wheel_error_formats_target_python() {
        let err = Error::BuiltWheelIncompatibleTargetPlatform {
            filename: WheelFilename::from_str("py313-0.1.0-py313-none-any.whl").unwrap(),
            python_platform: Platform::new(
                Os::Manylinux {
                    major: 2,
                    minor: 28,
                },
                Arch::X86_64,
            ),
            python_version: PythonVersion {
                version: (3, 12),
                variant: PythonVariant::Default,
            },
        };

        assert_eq!(
            err.to_string(),
            "The built wheel `py313-0.1.0-py313-none-any.whl` is not compatible with the target Python 3.12 on Linux x86_64. Consider using `--no-build` to disable building wheels."
        );
    }
}