uv_resolver/resolver/

provider.rs

use std::future::Future;
use std::sync::Arc;
pub use uv_resolver_types::MetadataResponse;
pub(crate) use uv_resolver_types::MetadataUnavailable;

use uv_client::MetadataFormat;
use uv_configuration::BuildOptions;
use uv_distribution::{DistributionDatabase, Reporter};
use uv_distribution_types::{
    Dist, File, IndexCapabilities, IndexLocations, IndexMetadata, IndexMetadataRef, IndexUrl,
    InstalledDist, MinimumLibcVersion, RequestedDist, RequiresPython,
};
use uv_normalize::PackageName;
use uv_platform_tags::Tags;
use uv_static::EnvVars;
use uv_types::{BuildContext, HashStrategy};

use crate::ExcludeNewer;
use crate::flat_index::{FlatDistributions, FlatIndex};
use crate::version_map::VersionMap;
use crate::yanks::AllowedYanks;

pub type PackageVersionsResult = Result<VersionsResponse, uv_client::Error>;
pub type WheelMetadataResult = Result<MetadataResponse, uv_distribution::Error>;

/// The outcome of an index-level variant metadata lookup.
///
/// A recoverable failure belongs in [`Self::Unavailable`] so the resolver can store it and replay
/// it when it revisits the package version. Fatal client errors are returned separately and abort
/// resolution.
#[derive(Debug)]
pub enum VariantsJsonResponse {
    /// The variant metadata was fetched successfully.
    Found(Vec<u8>),
    /// The package version cannot be used.
    Unavailable(MetadataUnavailable),
}

/// The response when requesting versions for a package
#[derive(Debug)]
pub enum VersionsResponse {
    /// The package was found in the registry with the included versions
    Found(Vec<VersionMap>),
    /// The package was not found in the registry
    NotFound,
    /// The package was not found in the local registry
    NoIndex,
    /// The package was not found in the cache and the network is not available.
    Offline,
}

pub trait ResolverProvider {
    /// Get the version map for a package.
    fn get_package_versions<'io>(
        &'io self,
        package_name: &'io PackageName,
        index: Option<&'io IndexMetadata>,
    ) -> impl Future<Output = PackageVersionsResult> + 'io;

    /// Get the metadata for a distribution.
    ///
    /// For a wheel, this is done by querying it (remote) metadata. For a source distribution, we
    /// (fetch and) build the source distribution and return the metadata from the built
    /// distribution.
    fn get_or_build_wheel_metadata<'io>(
        &'io self,
        dist: &'io Dist,
    ) -> impl Future<Output = WheelMetadataResult> + 'io;

    /// Get the metadata for an installed distribution.
    fn get_installed_metadata<'io>(
        &'io self,
        dist: &'io InstalledDist,
    ) -> impl Future<Output = WheelMetadataResult> + 'io;

    /// Fetch the index-level variant metadata for a package version.
    fn fetch_variants_json<'io>(
        &'io self,
        package_name: &'io PackageName,
        file: &'io File,
        index: &'io IndexUrl,
    ) -> impl Future<Output = Result<VariantsJsonResponse, uv_client::Error>> + 'io;

    /// Set the [`Reporter`] to use for this installer.
    #[must_use]
    fn with_reporter(self, reporter: Arc<dyn Reporter>) -> Self;
}

/// The main IO backend for the resolver, which does cached requests network requests using the
/// [`RegistryClient`] and [`DistributionDatabase`].
pub struct DefaultResolverProvider<'a, Context: BuildContext> {
    /// The [`DistributionDatabase`] used to build source distributions.
    fetcher: DistributionDatabase<'a, Context>,
    /// These are the entries from `--find-links` that act as overrides for index responses.
    flat_index: &'a FlatIndex,
    tags: Option<Tags>,
    requires_python: RequiresPython,
    allowed_yanks: AllowedYanks,
    hasher: &'a HashStrategy,
    exclude_newer: ExcludeNewer,
    available_version_cutoff: Option<jiff::Timestamp>,
    index_locations: &'a IndexLocations,
    build_options: &'a BuildOptions,
    capabilities: &'a IndexCapabilities,
    minimum_libc_version: Option<MinimumLibcVersion>,
}

impl<'a, Context: BuildContext> DefaultResolverProvider<'a, Context> {
    /// Reads the flat index entries and builds the provider.
    pub fn new(
        fetcher: DistributionDatabase<'a, Context>,
        flat_index: &'a FlatIndex,
        tags: Option<&'a Tags>,
        requires_python: &'a RequiresPython,
        allowed_yanks: AllowedYanks,
        hasher: &'a HashStrategy,
        exclude_newer: ExcludeNewer,
        index_locations: &'a IndexLocations,
        build_options: &'a BuildOptions,
        capabilities: &'a IndexCapabilities,
        minimum_libc_version: Option<MinimumLibcVersion>,
    ) -> Self {
        Self {
            fetcher,
            flat_index,
            tags: tags.cloned(),
            requires_python: requires_python.clone(),
            allowed_yanks,
            hasher,
            exclude_newer,
            available_version_cutoff: std::env::var(
                EnvVars::UV_INTERNAL__TEST_AVAILABLE_VERSION_CUTOFF,
            )
            .ok()
            .and_then(|value| value.parse().ok()),
            index_locations,
            build_options,
            capabilities,
            minimum_libc_version,
        }
    }

    fn effective_exclude_newer(
        &self,
        package_name: &PackageName,
        index: &uv_distribution_types::IndexUrl,
    ) -> Option<jiff::Timestamp> {
        self.exclude_newer.exclude_newer_package_for_index(
            package_name,
            self.index_locations.exclude_newer_for(index),
        )
    }

    /// Classify a client error as recoverable metadata unavailability or a fatal client error.
    fn classify_metadata_error(
        &self,
        error: uv_client::Error,
        index: Option<&IndexUrl>,
    ) -> Result<MetadataUnavailable, uv_client::Error> {
        let retries = error.retries();
        let duration = error.duration();
        match error.into_kind() {
            uv_client::ErrorKind::Offline(_) => Ok(MetadataUnavailable::Offline),
            uv_client::ErrorKind::MetadataParseError(_, _, error) => {
                Ok(MetadataUnavailable::InvalidMetadata(Arc::new(*error)))
            }
            uv_client::ErrorKind::Metadata(_, error) => {
                Ok(MetadataUnavailable::InvalidStructure(Arc::new(error)))
            }
            kind => {
                if let uv_client::ErrorKind::WrappedReqwestError(_, error) = &kind
                    && let Some(status) = error.status()
                    && index.is_some_and(|index| {
                        self.index_locations.ignores_error_code_for(index, status)
                    })
                {
                    Ok(MetadataUnavailable::Network(status))
                } else {
                    Err(uv_client::Error::new(kind, retries, duration))
                }
            }
        }
    }
}

impl<Context: BuildContext> ResolverProvider for DefaultResolverProvider<'_, Context> {
    /// Make a "Simple API" request for the package and convert the result to a [`VersionMap`].
    async fn get_package_versions<'io>(
        &'io self,
        package_name: &'io PackageName,
        index: Option<&'io IndexMetadata>,
    ) -> PackageVersionsResult {
        let result = self
            .fetcher
            .client()
            .manual(|client, semaphore| {
                client.simple_detail(
                    package_name,
                    index.map(IndexMetadataRef::from),
                    self.capabilities,
                    semaphore,
                )
            })
            .await;

        // If a package is pinned to an explicit index, ignore any `--find-links` entries.
        let flat_index = index.is_none().then_some(self.flat_index);
        let flat_distributions = flat_index
            .and_then(|flat_index| flat_index.get(package_name))
            .map(|entries| {
                FlatDistributions::from_entries(
                    entries.iter().cloned(),
                    self.tags.as_ref(),
                    self.hasher,
                    self.build_options,
                    self.minimum_libc_version,
                )
            });

        match result {
            Ok(results) => Ok(VersionsResponse::Found(
                results
                    .into_iter()
                    .map(|(index, metadata)| {
                        let included_version_cutoff =
                            self.effective_exclude_newer(package_name, index);
                        let available_version_cutoff = included_version_cutoff
                            .is_none()
                            .then_some(self.available_version_cutoff)
                            .flatten();

                        match metadata {
                            MetadataFormat::Simple(metadata) => VersionMap::from_simple_metadata(
                                metadata,
                                package_name,
                                index.clone(),
                                self.tags.clone(),
                                self.requires_python.clone(),
                                self.allowed_yanks.clone(),
                                self.hasher.clone(),
                                included_version_cutoff,
                                available_version_cutoff,
                                flat_distributions.clone(),
                                self.build_options,
                                self.minimum_libc_version,
                            ),
                            MetadataFormat::Flat(metadata) => VersionMap::from_flat_metadata(
                                metadata,
                                self.tags.as_ref(),
                                self.hasher,
                                self.build_options,
                                self.minimum_libc_version,
                            ),
                        }
                    })
                    .collect(),
            )),
            Err(err) => match err.kind() {
                uv_client::ErrorKind::RemotePackageNotFound(_) => {
                    if let Some(flat_index) = flat_distributions {
                        Ok(VersionsResponse::Found(vec![VersionMap::from(flat_index)]))
                    } else {
                        Ok(VersionsResponse::NotFound)
                    }
                }
                uv_client::ErrorKind::NoIndex(_) => {
                    if let Some(flat_index) = flat_distributions {
                        Ok(VersionsResponse::Found(vec![VersionMap::from(flat_index)]))
                    } else if flat_index.is_some_and(FlatIndex::offline) {
                        Ok(VersionsResponse::Offline)
                    } else {
                        Ok(VersionsResponse::NoIndex)
                    }
                }
                uv_client::ErrorKind::Offline(_) => {
                    if let Some(flat_index) = flat_distributions {
                        Ok(VersionsResponse::Found(vec![VersionMap::from(flat_index)]))
                    } else {
                        Ok(VersionsResponse::Offline)
                    }
                }
                _ => Err(err),
            },
        }
    }

    /// Fetch the metadata for a distribution, building it if necessary.
    async fn get_or_build_wheel_metadata<'io>(&'io self, dist: &'io Dist) -> WheelMetadataResult {
        match self
            .fetcher
            .get_or_build_wheel_metadata(dist, self.hasher.metadata_policy(dist))
            .await
        {
            Ok(metadata) => Ok(MetadataResponse::Found(metadata)),
            Err(err) => match err {
                uv_distribution::Error::Client(client) => {
                    // Both outcomes describe a failed request. A recoverable failure lets the
                    // resolver reject the candidate and backtrack; other client errors abort resolution.
                    match self.classify_metadata_error(client, dist.index()) {
                        Ok(reason) => Ok(MetadataResponse::Unavailable(reason)),
                        Err(error) => Err(error.into()),
                    }
                }
                uv_distribution::Error::WheelMetadataVersionMismatch { .. } => {
                    Ok(MetadataResponse::Unavailable(
                        MetadataUnavailable::InconsistentMetadata(Arc::new(err)),
                    ))
                }
                uv_distribution::Error::WheelMetadataNameMismatch { .. } => {
                    Ok(MetadataResponse::Unavailable(
                        MetadataUnavailable::InconsistentMetadata(Arc::new(err)),
                    ))
                }
                uv_distribution::Error::Metadata(err) => Ok(MetadataResponse::Unavailable(
                    MetadataUnavailable::InvalidMetadata(Arc::new(err)),
                )),
                uv_distribution::Error::WheelMetadata(_, err) => Ok(MetadataResponse::Unavailable(
                    MetadataUnavailable::InvalidStructure(Arc::new(*err)),
                )),
                uv_distribution::Error::RequiresPython(requires_python, version) => {
                    Ok(MetadataResponse::Unavailable(
                        MetadataUnavailable::RequiresPython(requires_python, version),
                    ))
                }
                err => Ok(MetadataResponse::Error(
                    Box::new(RequestedDist::Installable(dist.clone())),
                    Arc::new(err),
                )),
            },
        }
    }

    /// Return the metadata for an installed distribution.
    async fn get_installed_metadata<'io>(
        &'io self,
        dist: &'io InstalledDist,
    ) -> WheelMetadataResult {
        match self.fetcher.get_installed_metadata(dist).await {
            Ok(metadata) => Ok(MetadataResponse::Found(metadata)),
            Err(err) => Ok(MetadataResponse::Error(
                Box::new(RequestedDist::Installed(dist.clone())),
                Arc::new(err),
            )),
        }
    }

    async fn fetch_variants_json<'io>(
        &'io self,
        package_name: &'io PackageName,
        file: &'io File,
        index: &'io IndexUrl,
    ) -> Result<VariantsJsonResponse, uv_client::Error> {
        match self
            .fetcher
            .client()
            .managed(|client| client.fetch_variants_json(package_name, file, index))
            .await
        {
            Ok(contents) => Ok(VariantsJsonResponse::Found(contents)),
            Err(error) => match self.classify_metadata_error(error, Some(index)) {
                Ok(reason) => Ok(VariantsJsonResponse::Unavailable(reason)),
                Err(error) => Err(error),
            },
        }
    }

    /// Set the [`Reporter`] to use for this installer.
    fn with_reporter(self, reporter: Arc<dyn Reporter>) -> Self {
        Self {
            fetcher: self.fetcher.with_reporter(reporter),
            ..self
        }
    }
}