#
cargo/core/
registry.rs

    1//! Types that hold source information for a group of packages.
    2//!
    3//! The primary type you're looking for is [`PackageRegistry`]. It is an
    4//! abstraction over multiple [`Source`]s. [`PackageRegistry`] also implements
    5//! the [`Registry`] trait, allowing a dependency resolver to query necessary
    6//! package metadata (i.e., [Summary]) from it.
    7//!
    8//! Not to be confused with [`crate::sources::registry`] and [`crate::ops::registry`].
    9//! The former is just one kind of source,
    10//! while the latter involves operations on the registry Web API.
    11
    12use std::collections::{HashMap, HashSet};
    13use std::task::{Poll, ready};
    14
    15use crate::core::PackageSet;
    16use crate::core::{Dependency, PackageId, SourceId, Summary};
    17use crate::sources::IndexSummary;
    18use crate::sources::config::SourceConfigMap;
    19use crate::sources::source::QueryKind;
    20use crate::sources::source::Source;
    21use crate::sources::source::SourceMap;
    22use crate::util::errors::CargoResult;
    23use crate::util::interning::InternedString;
    24use crate::util::{CanonicalUrl, GlobalContext};
    25use anyhow::{Context as _, bail};
    26use tracing::{debug, trace};
    27use url::Url;
    28
    29/// An abstraction provides a set of methods for querying source information
    30/// about a group of packages, without leaking too much implementation details
    31/// of the actual registry.
    32///
    33/// As of 2024-04, only [`PackageRegistry`] and `MyRegistry` in resolver-tests
    34/// are found implementing this.
    35///
    36/// See also the [`Source`] trait, as many of the methods here mirror and
    37/// abstract over its functionalities.
    38pub trait Registry {
    39    /// Attempt to find the packages that match a dependency request.
    40    fn query(
    41        &mut self,
    42        dep: &Dependency,
    43        kind: QueryKind,
    44        f: &mut dyn FnMut(IndexSummary),
    45    ) -> Poll<CargoResult<()>>;
    46
    47    /// Gathers the result from [`Registry::query`] as a list of [`IndexSummary`] items
    48    /// when they become available.
    49    fn query_vec(
    50        &mut self,
    51        dep: &Dependency,
    52        kind: QueryKind,
    53    ) -> Poll<CargoResult<Vec<IndexSummary>>> {
    54        let mut ret = Vec::new();
    55        self.query(dep, kind, &mut |s| ret.push(s)).map_ok(|()| ret)
    56    }
    57
    58    /// Gets the description of a source, to provide useful messages.
    59    fn describe_source(&self, source: SourceId) -> String;
    60
    61    /// Checks if a source is replaced with some other source.
    62    fn is_replaced(&self, source: SourceId) -> bool;
    63
    64    /// Block until all outstanding [`Poll::Pending`] requests are [`Poll::Ready`].
    65    fn block_until_ready(&mut self) -> CargoResult<()>;
    66}
    67
    68/// This structure represents a registry of known packages. It internally
    69/// contains a number of [`Source`] instances which are used to load a
    70/// [`Package`] from.
    71///
    72/// The resolution phase of Cargo uses this to drive knowledge about new
    73/// packages as well as querying for lists of new packages.
    74/// It is here that sources are updated (e.g., network operations) and
    75/// overrides/patches are handled.
    76///
    77/// The general idea behind this registry is that it is centered around the
    78/// [`SourceMap`] structure, contained within which is a mapping of a [`SourceId`]
    79/// to a [`Source`]. Each [`Source`] in the map has been updated (using network
    80/// operations if necessary) and is ready to be queried for packages.
    81///
    82/// [`Package`]: crate::core::Package
    83pub struct PackageRegistry<'gctx> {
    84    gctx: &'gctx GlobalContext,
    85    sources: SourceMap<'gctx>,
    86
    87    /// A list of sources which are considered "path-overrides" which take
    88    /// precedent when querying for packages.
    89    overrides: Vec<SourceId>,
    90
    91    /// Use for tracking sources that are already loaded into the registry.
    92    // Note that each SourceId does not take into account its `precise` field
    93    // when hashing or testing for equality. When adding a new `SourceId`, we
    94    // want to avoid duplicates in the `SourceMap` (to prevent re-updating the
    95    // same git repo twice for example), but we also want to ensure that the
    96    // loaded source is always updated.
    97    //
    98    // Sources with a `precise` field normally don't need to be updated because
    99    // their contents are already on disk, but sources without a `precise` field
    100    // almost always need to be updated. If we have a cached `Source` for a
    101    // precise `SourceId`, then when we add a new `SourceId` that is not precise
    102    // we want to ensure that the underlying source is updated.
    103    //
    104    // This is basically a long-winded way of saying that we want to know
    105    // precisely what the keys of `sources` are, so this is a mapping of key to
    106    // what exactly the key is.
    107    source_ids: HashMap<SourceId, (SourceId, Kind)>,
    108
    109    /// This is constructed via [`PackageRegistry::register_lock`].
    110    /// See also [`LockedMap`].
    111    locked: LockedMap,
    112    /// Packages allowed to be used, even if they are yanked.
    113    yanked_whitelist: HashSet<PackageId>,
    114    source_config: SourceConfigMap<'gctx>,
    115
    116    /// Patches registered during calls to [`PackageRegistry::patch`].
    117    ///
    118    /// These are available for `query` after calling [`PackageRegistry::lock_patches`],
    119    /// which `lock`s them all to specific versions.
    120    patches: HashMap<CanonicalUrl, Vec<Summary>>,
    121    /// Whether patches are locked. That is, they are available to resolution.
    122    ///
    123    /// See [`PackageRegistry::lock_patches`] and [`PackageRegistry::patch`] for more.
    124    patches_locked: bool,
    125    /// Patches available for each source.
    126    ///
    127    /// This is for determining whether a dependency entry from a lockfile
    128    /// happened through `[patch]`, during calls to [`lock`] to rewrite
    129    /// summaries to point directly at these patched entries.
    130    ///
    131    /// This is constructed during calls to [`PackageRegistry::patch`],
    132    /// along with the `patches` field, thoough these entries never get locked.
    133    patches_available: HashMap<CanonicalUrl, Vec<PackageId>>,
    134}
    135
    136/// A map of all "locked packages" which is filled in when parsing a lock file
    137/// and is used to guide dependency resolution by altering summaries as they're
    138/// queried from this source.
    139///
    140/// This map can be thought of as a glorified `Vec<MySummary>` where `MySummary`
    141/// has a `PackageId` for which package it represents as well as a list of
    142/// `PackageId` for the resolved dependencies. The hash map is otherwise
    143/// structured though for easy access throughout this registry.
    144type LockedMap = HashMap<
    145    // The first level of key-ing done in this hash map is the source that
    146    // dependencies come from, identified by a `SourceId`.
    147    // The next level is keyed by the name of the package...
    148    (SourceId, InternedString),
    149    // ... and the value here is a list of tuples. The first element of each
    150    // tuple is a package which has the source/name used to get to this
    151    // point. The second element of each tuple is the list of locked
    152    // dependencies that the first element has.
    153    Vec<(PackageId, Vec<PackageId>)>,
    154>;
    155
    156/// Kinds of sources a [`PackageRegistry`] has loaded.
    157#[derive(PartialEq, Eq, Clone, Copy)]
    158enum Kind {
    159    /// A source from a [path override].
    160    ///
    161    /// [path overrides]: https://doc.rust-lang.org/nightly/cargo/reference/overriding-dependencies.html#paths-overrides
    162    Override,
    163    /// A source that is locked and not going to change.
    164    ///
    165    /// For example, sources of workspace members are loaded during the
    166    /// workspace initialization, so not allowed to change.
    167    Locked,
    168    /// A source that is not locked nor a path-override.
    169    Normal,
    170}
    171
    172/// This tuple is an argument to [`PackageRegistry::patch`].
    173///
    174/// * The first element is the patch definition straight from the manifest.
    175/// * The second element is an optional variant where the patch has been locked.
    176///   It is the patch locked to a specific version found in Cargo.lock.
    177///   This will be `None` if `Cargo.lock` doesn't exist,
    178///   or the patch did not match any existing entries in `Cargo.lock`.
    179pub type PatchDependency<'a> = (&'a Dependency, Option<LockedPatchDependency>);
    180
    181/// Argument to [`PackageRegistry::patch`] which is information about a `[patch]`
    182/// directive that we found in a lockfile, if present.
    183pub struct LockedPatchDependency {
    184    /// The original `Dependency` directive, except "locked" so it's version
    185    /// requirement is Locked to `foo` and its `SourceId` has a "precise" listed.
    186    pub dependency: Dependency,
    187    /// The `PackageId` that was previously found in a lock file which
    188    /// `dependency` matches.
    189    pub package_id: PackageId,
    190    /// Something only used for backwards compatibility with the v2 lock file
    191    /// format where `branch=master` is considered the same as `DefaultBranch`.
    192    /// For more comments on this see the code in `ops/resolve.rs`.
    193    pub alt_package_id: Option<PackageId>,
    194}
    195
    196impl<'gctx> PackageRegistry<'gctx> {
    197    pub fn new_with_source_config(
    198        gctx: &'gctx GlobalContext,
    199        source_config: SourceConfigMap<'gctx>,
    200    ) -> CargoResult<PackageRegistry<'gctx>> {
    201        Ok(PackageRegistry {
    202            gctx,
    203            sources: SourceMap::new(),
    204            source_ids: HashMap::new(),
    205            overrides: Vec::new(),
    206            source_config,
    207            locked: HashMap::new(),
    208            yanked_whitelist: HashSet::new(),
    209            patches: HashMap::new(),
    210            patches_locked: false,
    211            patches_available: HashMap::new(),
    212        })
    213    }
    214
    215    pub fn get(self, package_ids: &[PackageId]) -> CargoResult<PackageSet<'gctx>> {
    216        trace!("getting packages; sources={}", self.sources.len());
    217        PackageSet::new(package_ids, self.sources, self.gctx)
    218    }
    219
    220    /// Ensures the [`Source`] of the given [`SourceId`] is loaded.
    221    /// If not, this will block until the source is ready.
    222    fn ensure_loaded(&mut self, namespace: SourceId, kind: Kind) -> CargoResult<()> {
    223        match self.source_ids.get(&namespace) {
    224            // We've previously loaded this source, and we've already locked it,
    225            // so we're not allowed to change it even if `namespace` has a
    226            // slightly different precise version listed.
    227            Some((_, Kind::Locked)) => {
    228                debug!("load/locked   {}", namespace);
    229                return Ok(());
    230            }
    231
    232            // If the previous source was not a precise source, then we can be
    233            // sure that it's already been updated if we've already loaded it.
    234            Some((previous, _)) if !previous.has_precise() => {
    235                debug!("load/precise  {}", namespace);
    236                return Ok(());
    237            }
    238
    239            // If the previous source has the same precise version as we do,
    240            // then we're done, otherwise we need to move forward
    241            // updating this source.
    242            Some((previous, _)) => {
    243                if previous.has_same_precise_as(namespace) {
    244                    debug!("load/match    {}", namespace);
    245                    return Ok(());
    246                }
    247                debug!("load/mismatch {}", namespace);
    248            }
    249            None => {
    250                debug!("load/missing  {}", namespace);
    251            }
    252        }
    253
    254        self.load(namespace, kind)?;
    255
    256        // This isn't strictly necessary since it will be called later.
    257        // However it improves error messages for sources that issue errors
    258        // in `block_until_ready` because the callers here have context about
    259        // which deps are being resolved.
    260        self.block_until_ready()?;
    261        Ok(())
    262    }
    263
    264    pub fn add_sources(&mut self, ids: impl IntoIterator<Item = SourceId>) -> CargoResult<()> {
    265        for id in ids {
    266            self.ensure_loaded(id, Kind::Locked)?;
    267        }
    268        Ok(())
    269    }
    270
    271    /// Adds a source which will be locked.
    272    /// Useful for path sources such as the source of a workspace member.
    273    pub fn add_preloaded(&mut self, source: Box<dyn Source + 'gctx>) {
    274        self.add_source(source, Kind::Locked);
    275    }
    276
    277    /// Adds a source to the registry.
    278    fn add_source(&mut self, source: Box<dyn Source + 'gctx>, kind: Kind) {
    279        let id = source.source_id();
    280        self.sources.insert(source);
    281        self.source_ids.insert(id, (id, kind));
    282    }
    283
    284    /// Adds a source from a [path override].
    285    ///
    286    /// [path override]: https://doc.rust-lang.org/nightly/cargo/reference/overriding-dependencies.html#paths-overrides
    287    pub fn add_override(&mut self, source: Box<dyn Source + 'gctx>) {
    288        self.overrides.push(source.source_id());
    289        self.add_source(source, Kind::Override);
    290    }
    291
    292    /// Allows a group of package to be available to query even if they are yanked.
    293    pub fn add_to_yanked_whitelist(&mut self, iter: impl Iterator<Item = PackageId>) {
    294        let pkgs = iter.collect::<Vec<_>>();
    295        for (_, source) in self.sources.sources_mut() {
    296            source.add_to_yanked_whitelist(&pkgs);
    297        }
    298        self.yanked_whitelist.extend(pkgs);
    299    }
    300
    301    /// remove all residual state from previous lock files.
    302    pub fn clear_lock(&mut self) {
    303        trace!("clear_lock");
    304        self.locked = HashMap::new();
    305    }
    306
    307    /// Registers one "locked package" to the registry, for guiding the
    308    /// dependency resolution. See [`LockedMap`] for more.
    309    pub fn register_lock(&mut self, id: PackageId, deps: Vec<PackageId>) {
    310        trace!("register_lock: {}", id);
    311        for dep in deps.iter() {
    312            trace!("\t-> {}", dep);
    313        }
    314        let sub_vec = self
    315            .locked
    316            .entry((id.source_id(), id.name()))
    317            .or_insert_with(Vec::new);
    318        sub_vec.push((id, deps));
    319    }
    320
    321    /// Insert a `[patch]` section into this registry.
    322    ///
    323    /// This method will insert a `[patch]` section for the `url` specified,
    324    /// with the given list of dependencies. The `url` specified is the URL of
    325    /// the source to patch (for example this is `crates-io` in the manifest).
    326    /// The `deps` is an array of all the entries in the `[patch]` section of
    327    /// the manifest.
    328    ///
    329    /// Here the `patch_deps` will be resolved to a precise version and stored
    330    /// internally for future calls to `query` below.
    331    ///
    332    /// Note that the patch list specified here *will not* be available to
    333    /// [`Registry::query`] until [`PackageRegistry::lock_patches`] is called
    334    /// below, which should be called once all patches have been added.
    335    ///
    336    /// The return value is a `Vec` of patches that should *not* be locked.
    337    /// This happens when the patch is locked, but the patch has been updated
    338    /// so the locked value is no longer correct.
    339    #[tracing::instrument(skip(self, patch_deps))]
    340    pub fn patch(
    341        &mut self,
    342        url: &Url,
    343        patch_deps: &[PatchDependency<'_>],
    344    ) -> CargoResult<Vec<(Dependency, PackageId)>> {
    345        // NOTE: None of this code is aware of required features. If a patch
    346        // is missing a required feature, you end up with an "unused patch"
    347        // warning, which is very hard to understand. Ideally the warning
    348        // would be tailored to indicate *why* it is unused.
    349        let canonical = CanonicalUrl::new(url)?;
    350
    351        // Return value of patches that shouldn't be locked.
    352        let mut unlock_patches = Vec::new();
    353
    354        // First up we need to actually resolve each `patch_deps` specification
    355        // to precisely one summary. We're not using the `query` method below
    356        // as it internally uses maps we're building up as part of this method
    357        // (`patches_available` and `patches`). Instead we're going straight to
    358        // the source to load information from it.
    359        //
    360        // Remember that each dependency listed in `[patch]` has to resolve to
    361        // precisely one package, so that's why we're just creating a flat list
    362        // of summaries which should be the same length as `deps` above.
    363
    364        let mut patch_deps_remaining: Vec<_> = patch_deps.iter().collect();
    365        let mut unlocked_summaries = Vec::new();
    366        while !patch_deps_remaining.is_empty() {
    367            let mut patch_deps_pending = Vec::new();
    368            for patch_dep_remaining in patch_deps_remaining {
    369                let (orig_patch, locked) = patch_dep_remaining;
    370
    371                // Use the locked patch if it exists, otherwise use the original.
    372                let dep = match locked {
    373                    Some(lock) => &lock.dependency,
    374                    None => *orig_patch,
    375                };
    376                debug!(
    377                    "registering a patch for `{}` with `{}`",
    378                    url,
    379                    dep.package_name()
    380                );
    381
    382                if dep.features().len() != 0 || !dep.uses_default_features() {
    383                    self.source_config.gctx().shell().warn(format!(
    384                        "patch for `{}` uses the features mechanism. \
    385                        default-features and features will not take effect because the patch dependency does not support this mechanism",
    386                        dep.package_name()
    387                    ))?;
    388                }
    389
    390                // Go straight to the source for resolving `dep`. Load it as we
    391                // normally would and then ask it directly for the list of summaries
    392                // corresponding to this `dep`.
    393                self.ensure_loaded(dep.source_id(), Kind::Normal)
    394                    .with_context(|| {
    395                        format!(
    396                            "failed to load source for dependency `{}`",
    397                            dep.package_name()
    398                        )
    399                    })?;
    400
    401                let source = self
    402                    .sources
    403                    .get_mut(dep.source_id())
    404                    .expect("loaded source not present");
    405
    406                let summaries = match source.query_vec(dep, QueryKind::Exact)? {
    407                    Poll::Ready(deps) => deps,
    408                    Poll::Pending => {
    409                        patch_deps_pending.push(patch_dep_remaining);
    410                        continue;
    411                    }
    412                };
    413
    414                let summaries = summaries.into_iter().map(|s| s.into_summary()).collect();
    415
    416                let (summary, should_unlock) =
    417                    match summary_for_patch(orig_patch, &locked, summaries, source) {
    418                        Poll::Ready(x) => x,
    419                        Poll::Pending => {
    420                            patch_deps_pending.push(patch_dep_remaining);
    421                            continue;
    422                        }
    423                    }
    424                    .with_context(|| {
    425                        format!(
    426                            "patch for `{}` in `{}` failed to resolve",
    427                            orig_patch.package_name(),
    428                            url,
    429                        )
    430                    })
    431                    .with_context(|| format!("failed to resolve patches for `{}`", url))?;
    432
    433                debug!(
    434                    "patch summary is {:?} should_unlock={:?}",
    435                    summary, should_unlock
    436                );
    437                if let Some(unlock_id) = should_unlock {
    438                    unlock_patches.push(((*orig_patch).clone(), unlock_id));
    439                }
    440
    441                if *summary.package_id().source_id().canonical_url() == canonical {
    442                    return Err(anyhow::anyhow!(
    443                        "patch for `{}` in `{}` points to the same source, but \
    444                        patches must point to different sources",
    445                        dep.package_name(),
    446                        url
    447                    )
    448                    .context(format!("failed to resolve patches for `{}`", url)));
    449                }
    450                unlocked_summaries.push(summary);
    451            }
    452
    453            patch_deps_remaining = patch_deps_pending;
    454            self.block_until_ready()?;
    455        }
    456
    457        let mut name_and_version = HashSet::new();
    458        for summary in unlocked_summaries.iter() {
    459            let name = summary.package_id().name();
    460            let version = summary.package_id().version();
    461            if !name_and_version.insert((name, version)) {
    462                bail!(
    463                    "cannot have two `[patch]` entries which both resolve \
    464                     to `{} v{}`",
    465                    name,
    466                    version
    467                );
    468            }
    469        }
    470
    471        // Calculate a list of all patches available for this source.
    472        let mut ids = Vec::new();
    473        for (summary, (_, lock)) in unlocked_summaries.iter().zip(patch_deps) {
    474            ids.push(summary.package_id());
    475            // This is subtle where the list of `ids` for a canonical URL is
    476            // extend with possibly two ids per summary. This is done to handle
    477            // the transition from the v2->v3 lock file format where in v2
    478            // DefaultBranch was either DefaultBranch or Branch("master") for
    479            // git dependencies. In this case if `summary.package_id()` is
    480            // Branch("master") then alt_package_id will be DefaultBranch. This
    481            // signifies that there's a patch available for either of those
    482            // dependency directives if we see them in the dependency graph.
    483            if let Some(lock) = lock {
    484                ids.extend(lock.alt_package_id);
    485            }
    486        }
    487        self.patches_available.insert(canonical.clone(), ids);
    488
    489        // Note that we do not use `lock` here to lock summaries! That step
    490        // happens later once `lock_patches` is invoked. In the meantime though
    491        // we want to fill in the `patches_available` map (later used in the
    492        // `lock` method) and otherwise store the unlocked summaries in
    493        // `patches` to get locked in a future call to `lock_patches`.
    494        self.patches.insert(canonical, unlocked_summaries);
    495
    496        Ok(unlock_patches)
    497    }
    498
    499    /// Lock all patch summaries added via [`patch`](Self::patch),
    500    /// making them available to resolution via [`Registry::query`].
    501    pub fn lock_patches(&mut self) {
    502        assert!(!self.patches_locked);
    503        for summaries in self.patches.values_mut() {
    504            for summary in summaries {
    505                debug!("locking patch {:?}", summary);
    506                *summary = lock(&self.locked, &self.patches_available, summary.clone());
    507            }
    508        }
    509        self.patches_locked = true;
    510    }
    511
    512    /// Gets all patches grouped by the source URLs they are going to patch.
    513    ///
    514    /// These patches are mainly collected from [`patch`](Self::patch).
    515    /// They might not be the same as patches actually used during dependency resolving.
    516    pub fn patches(&self) -> &HashMap<CanonicalUrl, Vec<Summary>> {
    517        &self.patches
    518    }
    519
    520    /// Loads the [`Source`] for a given [`SourceId`] to this registry, making
    521    /// them available to resolution.
    522    fn load(&mut self, source_id: SourceId, kind: Kind) -> CargoResult<()> {
    523        debug!("loading source {}", source_id);
    524        let source = self
    525            .source_config
    526            .load(source_id, &self.yanked_whitelist)
    527            .with_context(|| format!("Unable to update {}", source_id))?;
    528        assert_eq!(source.source_id(), source_id);
    529
    530        if kind == Kind::Override {
    531            self.overrides.push(source_id);
    532        }
    533        self.add_source(source, kind);
    534
    535        // If we have an imprecise version then we don't know what we're going
    536        // to look for, so we always attempt to perform an update here.
    537        //
    538        // If we have a precise version, then we'll update lazily during the
    539        // querying phase. Note that precise in this case is only
    540        // `"locked"` as other values indicate a `cargo update
    541        // --precise` request
    542        if !source_id.has_locked_precise() {
    543            self.sources.get_mut(source_id).unwrap().invalidate_cache();
    544        } else {
    545            debug!("skipping update due to locked registry");
    546        }
    547        Ok(())
    548    }
    549
    550    /// Queries path overrides from this registry.
    551    fn query_overrides(&mut self, dep: &Dependency) -> Poll<CargoResult<Option<IndexSummary>>> {
    552        for &s in self.overrides.iter() {
    553            let src = self.sources.get_mut(s).unwrap();
    554            let dep = Dependency::new_override(dep.package_name(), s);
    555
    556            let mut results = None;
    557            ready!(src.query(&dep, QueryKind::Exact, &mut |s| results = Some(s)))?;
    558            if results.is_some() {
    559                return Poll::Ready(Ok(results));
    560            }
    561        }
    562        Poll::Ready(Ok(None))
    563    }
    564
    565    /// This function is used to transform a summary to another locked summary
    566    /// if possible. This is where the concept of a lock file comes into play.
    567    ///
    568    /// If a summary points at a package ID which was previously locked, then we
    569    /// override the summary's ID itself, as well as all dependencies, to be
    570    /// rewritten to the locked versions. This will transform the summary's
    571    /// source to a precise source (listed in the locked version) as well as
    572    /// transforming all of the dependencies from range requirements on
    573    /// imprecise sources to exact requirements on precise sources.
    574    ///
    575    /// If a summary does not point at a package ID which was previously locked,
    576    /// or if any dependencies were added and don't have a previously listed
    577    /// version, we still want to avoid updating as many dependencies as
    578    /// possible to keep the graph stable. In this case we map all of the
    579    /// summary's dependencies to be rewritten to a locked version wherever
    580    /// possible. If we're unable to map a dependency though, we just pass it on
    581    /// through.
    582    pub fn lock(&self, summary: Summary) -> Summary {
    583        assert!(self.patches_locked);
    584        lock(&self.locked, &self.patches_available, summary)
    585    }
    586
    587    fn warn_bad_override(
    588        &self,
    589        override_summary: &Summary,
    590        real_summary: &Summary,
    591    ) -> CargoResult<()> {
    592        let mut real_deps = real_summary.dependencies().iter().collect::<Vec<_>>();
    593
    594        let boilerplate = "\
    595This is currently allowed but is known to produce buggy behavior with spurious
    596recompiles and changes to the crate graph. Path overrides unfortunately were
    597never intended to support this feature, so for now this message is just a
    598warning. In the future, however, this message will become a hard error.
    599
    600To change the dependency graph via an override it's recommended to use the
    601`[patch]` feature of Cargo instead of the path override feature. This is
    602documented online at the url below for more information.
    603
    604https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html
    605";
    606
    607        for dep in override_summary.dependencies() {
    608            if let Some(i) = real_deps.iter().position(|d| dep == *d) {
    609                real_deps.remove(i);
    610                continue;
    611            }
    612            let msg = format!(
    613                "path override for crate `{}` has altered the original list of\n\
    614                 dependencies; the dependency on `{}` was either added or\n\
    615                 modified to not match the previously resolved version\n\n\
    616                 {}",
    617                override_summary.package_id().name(),
    618                dep.package_name(),
    619                boilerplate
    620            );
    621            self.source_config.gctx().shell().warn(&msg)?;
    622            return Ok(());
    623        }
    624
    625        if let Some(dep) = real_deps.get(0) {
    626            let msg = format!(
    627                "path override for crate `{}` has altered the original list of\n\
    628                 dependencies; the dependency on `{}` was removed\n\n\
    629                 {}",
    630                override_summary.package_id().name(),
    631                dep.package_name(),
    632                boilerplate
    633            );
    634            self.source_config.gctx().shell().warn(&msg)?;
    635            return Ok(());
    636        }
    637
    638        Ok(())
    639    }
    640}
    641
    642impl<'gctx> Registry for PackageRegistry<'gctx> {
    643    fn query(
    644        &mut self,
    645        dep: &Dependency,
    646        kind: QueryKind,
    647        f: &mut dyn FnMut(IndexSummary),
    648    ) -> Poll<CargoResult<()>> {
    649        assert!(self.patches_locked);
    650        // Look for an override and get ready to query the real source.
    651        let override_summary = ready!(self.query_overrides(dep))?;
    652
    653        // Next up on our list of candidates is to check the `[patch]` section
    654        // of the manifest. Here we look through all patches relevant to the
    655        // source that `dep` points to, and then we match name/version. Note
    656        // that we don't use `dep.matches(..)` because the patches, by definition,
    657        // come from a different source. This means that `dep.matches(..)` will
    658        // always return false, when what we really care about is the name/version match.
    659        let mut patches = Vec::<Summary>::new();
    660        if let Some(extra) = self.patches.get(dep.source_id().canonical_url()) {
    661            patches.extend(
    662                extra
    663                    .iter()
    664                    .filter(|s| dep.matches_ignoring_source(s.package_id()))
    665                    .cloned(),
    666            );
    667        }
    668
    669        // A crucial feature of the `[patch]` feature is that we don't query the
    670        // actual registry if we have a "locked" dependency. A locked dep basically
    671        // just means a version constraint of `=a.b.c`, and because patches take
    672        // priority over the actual source then if we have a candidate we're done.
    673        if patches.len() == 1 && dep.is_locked() {
    674            let patch = patches.remove(0);
    675            match override_summary {
    676                Some(override_summary) => {
    677                    self.warn_bad_override(override_summary.as_summary(), &patch)?;
    678                    let override_summary =
    679                        override_summary.map_summary(|summary| self.lock(summary));
    680                    f(override_summary);
    681                }
    682                None => f(IndexSummary::Candidate(patch)),
    683            }
    684
    685            return Poll::Ready(Ok(()));
    686        }
    687
    688        if !patches.is_empty() {
    689            debug!(
    690                "found {} patches with an unlocked dep on `{}` at {} \
    691                     with `{}`, \
    692                     looking at sources",
    693                patches.len(),
    694                dep.package_name(),
    695                dep.source_id(),
    696                dep.version_req()
    697            );
    698        }
    699
    700        // Ensure the requested source_id is loaded
    701        self.ensure_loaded(dep.source_id(), Kind::Normal)
    702            .with_context(|| {
    703                format!(
    704                    "failed to load source for dependency `{}`",
    705                    dep.package_name()
    706                )
    707            })?;
    708
    709        let source = self.sources.get_mut(dep.source_id());
    710        match (override_summary, source) {
    711            (Some(_), None) => {
    712                return Poll::Ready(Err(anyhow::anyhow!("override found but no real ones")));
    713            }
    714            (None, None) => return Poll::Ready(Ok(())),
    715
    716            // If we don't have an override then we just ship everything upstairs after locking the summary
    717            (None, Some(source)) => {
    718                for patch in patches.iter() {
    719                    f(IndexSummary::Candidate(patch.clone()));
    720                }
    721
    722                // Our sources shouldn't ever come back to us with two summaries
    723                // that have the same version. We could, however, have an `[patch]`
    724                // section which is in use to override a version in the registry.
    725                // This means that if our `summary` in this loop has the same
    726                // version as something in `patches` that we've already selected,
    727                // then we skip this `summary`.
    728                let locked = &self.locked;
    729                let all_patches = &self.patches_available;
    730                let callback = &mut |summary: IndexSummary| {
    731                    for patch in patches.iter() {
    732                        let patch = patch.package_id().version();
    733                        if summary.package_id().version() == patch {
    734                            return;
    735                        }
    736                    }
    737                    let summary = summary.map_summary(|summary| lock(locked, all_patches, summary));
    738                    f(summary)
    739                };
    740                return source.query(dep, kind, callback);
    741            }
    742
    743            // If we have an override summary then we query the source to sanity check its results.
    744            // We don't actually use any of the summaries it gives us though.
    745            (Some(override_summary), Some(source)) => {
    746                if !patches.is_empty() {
    747                    return Poll::Ready(Err(anyhow::anyhow!("found patches and a path override")));
    748                }
    749                let mut n = 0;
    750                let mut to_warn = None;
    751                let callback = &mut |summary| {
    752                    n += 1;
    753                    to_warn = Some(summary);
    754                };
    755                let pend = source.query(dep, kind, callback);
    756                if pend.is_pending() {
    757                    return Poll::Pending;
    758                }
    759                if n > 1 {
    760                    return Poll::Ready(Err(anyhow::anyhow!(
    761                        "found an override with a non-locked list"
    762                    )));
    763                }
    764                if let Some(to_warn) = to_warn {
    765                    self.warn_bad_override(override_summary.as_summary(), to_warn.as_summary())?;
    766                }
    767                let override_summary = override_summary.map_summary(|summary| self.lock(summary));
    768                f(override_summary);
    769            }
    770        }
    771
    772        Poll::Ready(Ok(()))
    773    }
    774
    775    fn describe_source(&self, id: SourceId) -> String {
    776        match self.sources.get(id) {
    777            Some(src) => src.describe(),
    778            None => id.to_string(),
    779        }
    780    }
    781
    782    fn is_replaced(&self, id: SourceId) -> bool {
    783        match self.sources.get(id) {
    784            Some(src) => src.is_replaced(),
    785            None => false,
    786        }
    787    }
    788
    789    #[tracing::instrument(skip_all)]
    790    fn block_until_ready(&mut self) -> CargoResult<()> {
    791        if cfg!(debug_assertions) {
    792            // Force borrow to catch invalid borrows, regardless of which source is used and how it
    793            // happens to behave this time
    794            self.gctx.shell().verbosity();
    795        }
    796        for (source_id, source) in self.sources.sources_mut() {
    797            source
    798                .block_until_ready()
    799                .with_context(|| format!("Unable to update {}", source_id))?;
    800        }
    801        Ok(())
    802    }
    803}
    804
    805/// See [`PackageRegistry::lock`].
    806fn lock(
    807    locked: &LockedMap,
    808    patches: &HashMap<CanonicalUrl, Vec<PackageId>>,
    809    summary: Summary,
    810) -> Summary {
    811    let pair = locked
    812        .get(&(summary.source_id(), summary.name()))
    813        .and_then(|vec| vec.iter().find(|&&(id, _)| id == summary.package_id()));
    814
    815    trace!("locking summary of {}", summary.package_id());
    816
    817    // Lock the summary's ID if possible
    818    let summary = match pair {
    819        Some((precise, _)) => summary.override_id(*precise),
    820        None => summary,
    821    };
    822    summary.map_dependencies(|dep| {
    823        trace!(
    824            "\t{}/{}/{}",
    825            dep.package_name(),
    826            dep.version_req(),
    827            dep.source_id()
    828        );
    829
    830        // If we've got a known set of overrides for this summary, then
    831        // one of a few cases can arise:
    832        //
    833        // 1. We have a lock entry for this dependency from the same
    834        //    source as it's listed as coming from. In this case we make
    835        //    sure to lock to precisely the given package ID.
    836        //
    837        // 2. We have a lock entry for this dependency, but it's from a
    838        //    different source than what's listed, or the version
    839        //    requirement has changed. In this case we must discard the
    840        //    locked version because the dependency needs to be
    841        //    re-resolved.
    842        //
    843        // 3. We have a lock entry for this dependency, but it's from a
    844        //    different source than what's listed. This lock though happens
    845        //    through `[patch]`, so we want to preserve it.
    846        //
    847        // 4. We don't have a lock entry for this dependency, in which
    848        //    case it was likely an optional dependency which wasn't
    849        //    included previously so we just pass it through anyway.
    850        //
    851        // Cases 1/2 are handled by `matches_id`, case 3 is handled specially,
    852        // and case 4 is handled by falling through to the logic below.
    853        if let Some((_, locked_deps)) = pair {
    854            let locked = locked_deps.iter().find(|&&id| {
    855                // If the dependency matches the package id exactly then we've
    856                // found a match, this is the id the dependency was previously
    857                // locked to.
    858                if dep.matches_id(id) {
    859                    return true;
    860                }
    861
    862                // If the name/version doesn't match, then we definitely don't
    863                // have a match whatsoever. Otherwise we need to check
    864                // `[patch]`...
    865                if !dep.matches_ignoring_source(id) {
    866                    return false;
    867                }
    868
    869                // ... so here we look up the dependency url in the patches
    870                // map, and we see if `id` is contained in the list of patches
    871                // for that url. If it is then this lock is still valid,
    872                // otherwise the lock is no longer valid.
    873                match patches.get(dep.source_id().canonical_url()) {
    874                    Some(list) => list.contains(&id),
    875                    None => false,
    876                }
    877            });
    878
    879            if let Some(&locked) = locked {
    880                trace!("\tfirst hit on {}", locked);
    881                let mut dep = dep;
    882
    883                // If we found a locked version where the sources match, then
    884                // we can `lock_to` to get an exact lock on this dependency.
    885                // Otherwise we got a lock via `[patch]` so we only lock the
    886                // version requirement, not the source.
    887                if locked.source_id() == dep.source_id() {
    888                    dep.lock_to(locked);
    889                } else {
    890                    dep.lock_version(locked.version());
    891                }
    892                return dep;
    893            }
    894        }
    895
    896        // If this dependency did not have a locked version, then we query
    897        // all known locked packages to see if they match this dependency.
    898        // If anything does then we lock it to that and move on.
    899        let v = locked
    900            .get(&(dep.source_id(), dep.package_name()))
    901            .and_then(|vec| vec.iter().find(|&&(id, _)| dep.matches_id(id)));
    902        if let Some(&(id, _)) = v {
    903            trace!("\tsecond hit on {}", id);
    904            let mut dep = dep;
    905            dep.lock_to(id);
    906            return dep;
    907        }
    908
    909        trace!("\tnope, unlocked");
    910        dep
    911    })
    912}
    913
    914/// A helper for selecting the summary, or generating a helpful error message.
    915///
    916/// Returns a tuple that the first element is the summary selected. The second
    917/// is a package ID indicating that the patch entry should be unlocked. This
    918/// happens when a match cannot be found with the `locked` one, but found one
    919/// via the original patch, so we need to inform the resolver to "unlock" it.
    920fn summary_for_patch(
    921    orig_patch: &Dependency,
    922    locked: &Option<LockedPatchDependency>,
    923    mut summaries: Vec<Summary>,
    924    source: &mut dyn Source,
    925) -> Poll<CargoResult<(Summary, Option<PackageId>)>> {
    926    if summaries.len() == 1 {
    927        return Poll::Ready(Ok((summaries.pop().unwrap(), None)));
    928    }
    929    if summaries.len() > 1 {
    930        // TODO: In the future, it might be nice to add all of these
    931        // candidates so that version selection would just pick the
    932        // appropriate one. However, as this is currently structured, if we
    933        // added these all as patches, the unselected versions would end up in
    934        // the "unused patch" listing, and trigger a warning. It might take a
    935        // fair bit of restructuring to make that work cleanly, and there
    936        // isn't any demand at this time to support that.
    937        let mut vers: Vec<_> = summaries.iter().map(|summary| summary.version()).collect();
    938        vers.sort();
    939        let versions: Vec<_> = vers.into_iter().map(|v| v.to_string()).collect();
    940        return Poll::Ready(Err(anyhow::anyhow!(
    941            "patch for `{}` in `{}` resolved to more than one candidate\n\
    942            Found versions: {}\n\
    943            Update the patch definition to select only one package.\n\
    944            For example, add an `=` version requirement to the patch definition, \
    945            such as `version = \"={}\"`.",
    946            orig_patch.package_name(),
    947            orig_patch.source_id(),
    948            versions.join(", "),
    949            versions.last().unwrap()
    950        )));
    951    }
    952    assert!(summaries.is_empty());
    953    // No summaries found, try to help the user figure out what is wrong.
    954    if let Some(locked) = locked {
    955        // Since the locked patch did not match anything, try the unlocked one.
    956        let orig_matches =
    957            ready!(source.query_vec(orig_patch, QueryKind::Exact)).unwrap_or_else(|e| {
    958                tracing::warn!(
    959                    "could not determine unlocked summaries for dep {:?}: {:?}",
    960                    orig_patch,
    961                    e
    962                );
    963                Vec::new()
    964            });
    965
    966        let orig_matches = orig_matches.into_iter().map(|s| s.into_summary()).collect();
    967
    968        let summary = ready!(summary_for_patch(orig_patch, &None, orig_matches, source))?;
    969        return Poll::Ready(Ok((summary.0, Some(locked.package_id))));
    970    }
    971    // Try checking if there are *any* packages that match this by name.
    972    let name_only_dep = Dependency::new_override(orig_patch.package_name(), orig_patch.source_id());
    973
    974    let name_summaries =
    975        ready!(source.query_vec(&name_only_dep, QueryKind::Exact)).unwrap_or_else(|e| {
    976            tracing::warn!(
    977                "failed to do name-only summary query for {:?}: {:?}",
    978                name_only_dep,
    979                e
    980            );
    981            Vec::new()
    982        });
    983    let mut vers = name_summaries
    984        .iter()
    985        .map(|summary| summary.as_summary().version())
    986        .collect::<Vec<_>>();
    987    let found = match vers.len() {
    988        0 => format!(""),
    989        1 => format!("version `{}`", vers[0]),
    990        _ => {
    991            vers.sort();
    992            let strs: Vec<_> = vers.into_iter().map(|v| v.to_string()).collect();
    993            format!("versions `{}`", strs.join(", "))
    994        }
    995    };
    996    Poll::Ready(Err(if found.is_empty() {
    997        anyhow::anyhow!(
    998            "The patch location `{}` does not appear to contain any packages \
    999            matching the name `{}`.",
    1000            orig_patch.source_id(),
    1001            orig_patch.package_name()
    1002        )
    1003    } else {
    1004        anyhow::anyhow!(
    1005            "The patch location `{}` contains a `{}` package with {}, but the patch \
    1006            definition requires `{}`.\n\
    1007            Check that the version in the patch location is what you expect, \
    1008            and update the patch definition to match.",
    1009            orig_patch.source_id(),
    1010            orig_patch.package_name(),
    1011            found,
    1012            orig_patch.version_req()
    1013        )
    1014    }))
    1015}