Source in cargo::sources::source - Rust
Description: An abstraction of different sources of Cargo packages.

Skip to main content

## Source

# Trait Source

Source

    pub trait Source {
    Show 16 methods    // Required methods
        fn source_id(&self) -> SourceId;
        fn supports_checksums(&self) -> bool;
        fn requires_precise(&self) -> bool;
        fn query<'life0, 'life1, 'life2, 'async_trait>(
            &'life0 self,
            dep: &'life1 Dependency,
            kind: QueryKind,
            f: &'life2 mut dyn FnMut(IndexSummary),
        ) -> Pin<Box<dyn Future<Output = CargoResult<()>> + 'async_trait>>
           where Self: 'async_trait,
                 'life0: 'async_trait,
                 'life1: 'async_trait,
                 'life2: 'async_trait;
        fn invalidate_cache(&self);
        fn set_quiet(&mut self, quiet: bool);
        fn download(&self, package: PackageId) -> CargoResult<MaybePackage>;
        fn finish_download(
            &self,
            pkg_id: PackageId,
            contents: Vec<u8>,
        ) -> CargoResult<Package>;
        fn fingerprint(&self, pkg: &Package) -> CargoResult<String>;
        fn describe(&self) -> String;
        fn add_to_yanked_whitelist(&self, pkgs: &[PackageId]);
        fn is_yanked<'life0, 'async_trait>(
            &'life0 self,
            pkg: PackageId,
        ) -> Pin<Box<dyn Future<Output = CargoResult<bool>> + 'async_trait>>
           where Self: 'async_trait,
                 'life0: 'async_trait;

        // Provided methods
        fn replaced_source_id(&self) -> SourceId { ... }
        fn query_vec<'life0, 'life1, 'async_trait>(
            &'life0 self,
            dep: &'life1 Dependency,
            kind: QueryKind,
        ) -> Pin<Box<dyn Future<Output = CargoResult<Vec<IndexSummary>>> + 'async_trait>>
           where Self: 'async_trait,
                 'life0: 'async_trait,
                 'life1: 'async_trait { ... }
        fn verify(&self, _pkg: PackageId) -> CargoResult<()> { ... }
        fn is_replaced(&self) -> bool { ... }
    }

Expand description

An abstraction of different sources of Cargo packages.

The `Source` trait generalizes the API to interact with these providers. For example,

- `Source::query` is for querying package metadata on a given `Dependency` requested by a Cargo manifest.
- `Source::download` is for fetching the full package information on given names and versions.
- `Source::source_id` is for defining an unique identifier of a source to distinguish one source from another, keeping Cargo safe from dependency confusion attack.

Normally, developers don’t need to implement their own `Source`s. Cargo provides several kinds of sources implementations that should cover almost all use cases. See `crate::sources` for implementations provided by Cargo.

## Required Methods§

Source

#### fn source_id(&self) -> SourceId

Returns the `SourceId` corresponding to this source.

Source

#### fn supports_checksums(&self) -> bool

Returns whether or not this source will return `IndexSummary` items with checksums listed.

Source

#### fn requires_precise(&self) -> bool

Returns whether or not this source will return `IndexSummary` items with the `precise` field in the `SourceId` listed.

Source

#### fn query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dep: &'life1 Dependency, kind: QueryKind, f: &'life2 mut dyn FnMut(IndexSummary), ) -> Pin<Box<dyn Future<Output = CargoResult<()>> + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Attempts to find the packages that match a dependency request.

The `f` argument is expected to get called when any `IndexSummary` becomes available.

Source

#### fn invalidate_cache(&self)

Ensure that the source is fully up-to-date for the current session on the next query.

Source

#### fn set_quiet(&mut self, quiet: bool)

If quiet, the source should not display any progress or status messages.

Source

#### fn download(&self, package: PackageId) -> CargoResult<MaybePackage>

Starts the process to fetch a `Package` for the given `PackageId`.

If the source already has the package available on disk, then it should return immediately with `MaybePackage::Ready` with the `Package`. Otherwise it should return a `MaybePackage::Download` to indicate the URL to download the package (this is for remote registry sources only).

In the case where `MaybePackage::Download` is returned, then the package downloader will call `Source::finish_download` after the download has finished.

Source

#### fn finish_download( &self, pkg_id: PackageId, contents: Vec<u8>, ) -> CargoResult<Package>

Gives the source the downloaded `.crate` file.

When a source has returned `MaybePackage::Download` in the `Source::download` method, then this function will be called with the results of the download of the given URL. The source is responsible for saving to disk, and returning the appropriate `Package`.

Source

#### fn fingerprint(&self, pkg: &Package) -> CargoResult<String>

Generates a unique string which represents the fingerprint of the current state of the source.

This fingerprint is used to determine the “freshness” of the source later on. It must be guaranteed that the fingerprint of a source is constant if and only if the output product will remain constant.

The `pkg` argument is the package which this fingerprint should only be interested in for when this source may contain multiple packages.

Source

#### fn describe(&self) -> String

Describes this source in a human readable fashion, used for display in resolver error messages currently.

Source

#### fn add_to_yanked_whitelist(&self, pkgs: &[PackageId])

Add a number of crates that should be whitelisted for showing up during queries, even if they are yanked. Currently only applies to registry sources.

Source

#### fn is_yanked<'life0, 'async_trait>( &'life0 self, pkg: PackageId, ) -> Pin<Box<dyn Future<Output = CargoResult<bool>> + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Query if a package is yanked. Only registry sources can mark packages as yanked. This ignores the yanked whitelist.

## Provided Methods§

Source

#### fn replaced_source_id(&self) -> SourceId

Returns the replaced `SourceId` corresponding to this source.

Source

#### fn query_vec<'life0, 'life1, 'async_trait>( &'life0 self, dep: &'life1 Dependency, kind: QueryKind, ) -> Pin<Box<dyn Future<Output = CargoResult<Vec<IndexSummary>>> + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Gathers the result from `Source::query` as a list of `IndexSummary` items when they become available.

Source

#### fn verify(&self, _pkg: PackageId) -> CargoResult<()>

If this source supports it, verifies the source of the package specified.

Note that the source may also have performed other checksum-based verification during the `download` step, but this is intended to be run just before a crate is compiled so it may perform more expensive checks which may not be cacheable.

Source

#### fn is_replaced(&self) -> bool

Returns whether a source is being replaced by another here.

Builtin replacement of `crates.io` doesn’t count as replacement here.

## Implementations on Foreign Types§

Source§

### impl<'a, T: Source + ?Sized + 'a> Source for &'a mut T

A blanket implementation forwards all methods to `Source`.

Source§

#### fn source_id(&self) -> SourceId

Source§

#### fn replaced_source_id(&self) -> SourceId

Source§

#### fn supports_checksums(&self) -> bool

Source§

#### fn requires_precise(&self) -> bool

Source§

#### fn query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, dep: &'life1 Dependency, kind: QueryKind, f: &'life2 mut dyn FnMut(IndexSummary), ) -> Pin<Box<dyn Future<Output = CargoResult<()>> + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Source§

#### fn invalidate_cache(&self)

Source§

#### fn set_quiet(&mut self, quiet: bool)

Source§

#### fn download(&self, id: PackageId) -> CargoResult<MaybePackage>

Source§

#### fn finish_download(&self, id: PackageId, data: Vec<u8>) -> CargoResult<Package>

Source§

#### fn fingerprint(&self, pkg: &Package) -> CargoResult<String>

Source§

#### fn verify(&self, pkg: PackageId) -> CargoResult<()>

Source§

#### fn describe(&self) -> String

Source§

#### fn is_replaced(&self) -> bool

Source§

#### fn add_to_yanked_whitelist(&self, pkgs: &[PackageId])

Source§

#### fn is_yanked<'life0, 'async_trait>( &'life0 self, pkg: PackageId, ) -> Pin<Box<dyn Future<Output = CargoResult<bool>> + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

## Implementors§

Source§

### impl<'gctx> Source for DirectorySource<'gctx>

Source§

### impl<'gctx> Source for GitSource<'gctx>

Source§

### impl<'gctx> Source for DependencyConfusionThreatOverlaySource<'gctx>

Source§

### impl<'gctx> Source for PathSource<'gctx>

Source§

### impl<'gctx> Source for RecursivePathSource<'gctx>

Source§

### impl<'gctx> Source for RegistrySource<'gctx>

Source§

### impl<'gctx> Source for ReplacedSource<'gctx>