pub trait Source {
Show 18 methods
// Required methods
fn source_id(&self) -> SourceId;
fn supports_checksums(&self) -> bool;
fn requires_precise(&self) -> bool;
fn query(
&mut self,
dep: &Dependency,
kind: QueryKind,
f: &mut dyn FnMut(Summary)
) -> Poll<CargoResult<()>>;
fn invalidate_cache(&mut self);
fn set_quiet(&mut self, quiet: bool);
fn download(&mut self, package: PackageId) -> CargoResult<MaybePackage>;
fn finish_download(
&mut 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(&mut self, pkgs: &[PackageId]);
fn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>;
fn block_until_ready(&mut self) -> CargoResult<()>;
// Provided methods
fn replaced_source_id(&self) -> SourceId { ... }
fn query_vec(
&mut self,
dep: &Dependency,
kind: QueryKind
) -> Poll<CargoResult<Vec<Summary>>> { ... }
fn download_now(
self: Box<Self>,
package: PackageId,
config: &Config
) -> CargoResult<Package>
where Self: Sized { ... }
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 givenDependency
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§
sourcefn supports_checksums(&self) -> bool
fn supports_checksums(&self) -> bool
Returns whether or not this source will return Summary
items with
checksums listed.
sourcefn requires_precise(&self) -> bool
fn requires_precise(&self) -> bool
sourcefn query(
&mut self,
dep: &Dependency,
kind: QueryKind,
f: &mut dyn FnMut(Summary)
) -> Poll<CargoResult<()>>
fn query( &mut self, dep: &Dependency, kind: QueryKind, f: &mut dyn FnMut(Summary) ) -> Poll<CargoResult<()>>
Attempts to find the packages that match a dependency request.
Usually you should call Source::block_until_ready
somewhere and
wait until package information become available. Otherwise any query
may return a Poll::Pending
.
The f
argument is expected to get called when any Summary
becomes available.
sourcefn invalidate_cache(&mut self)
fn invalidate_cache(&mut self)
Ensure that the source is fully up-to-date for the current session on the next query.
sourcefn set_quiet(&mut self, quiet: bool)
fn set_quiet(&mut self, quiet: bool)
If quiet, the source should not display any progress or status messages.
sourcefn download(&mut self, package: PackageId) -> CargoResult<MaybePackage>
fn download(&mut 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.
sourcefn finish_download(
&mut self,
pkg_id: PackageId,
contents: Vec<u8>
) -> CargoResult<Package>
fn finish_download( &mut 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
.
sourcefn fingerprint(&self, pkg: &Package) -> CargoResult<String>
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.
sourcefn describe(&self) -> String
fn describe(&self) -> String
Describes this source in a human readable fashion, used for display in resolver error messages currently.
sourcefn add_to_yanked_whitelist(&mut self, pkgs: &[PackageId])
fn add_to_yanked_whitelist(&mut 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.
sourcefn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>
fn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>
Query if a package is yanked. Only registry sources can mark packages as yanked. This ignores the yanked whitelist.
sourcefn block_until_ready(&mut self) -> CargoResult<()>
fn block_until_ready(&mut self) -> CargoResult<()>
Block until all outstanding Poll::Pending
requests are Poll::Ready
.
After calling this function, the source should return Poll::Ready
for
any queries that previously returned Poll::Pending
.
If no queries previously returned Poll::Pending
, and Source::invalidate_cache
was not called, this function should be a no-op.
Provided Methods§
sourcefn replaced_source_id(&self) -> SourceId
fn replaced_source_id(&self) -> SourceId
Returns the replaced SourceId
corresponding to this source.
sourcefn query_vec(
&mut self,
dep: &Dependency,
kind: QueryKind
) -> Poll<CargoResult<Vec<Summary>>>
fn query_vec( &mut self, dep: &Dependency, kind: QueryKind ) -> Poll<CargoResult<Vec<Summary>>>
Gathers the result from Source::query
as a list of Summary
items
when they become available.
sourcefn download_now(
self: Box<Self>,
package: PackageId,
config: &Config
) -> CargoResult<Package>where
Self: Sized,
fn download_now( self: Box<Self>, package: PackageId, config: &Config ) -> CargoResult<Package>where Self: Sized,
Convenience method used to immediately fetch a Package
for the
given PackageId
.
This may trigger a download if necessary. This should only be used
when a single package is needed (as in the case for cargo install
).
Otherwise downloads should be batched together via PackageSet
.
sourcefn verify(&self, _pkg: PackageId) -> CargoResult<()>
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.
sourcefn is_replaced(&self) -> bool
fn is_replaced(&self) -> bool
Returns whether a source is being replaced by another here.
Implementations on Foreign Types§
source§impl<'a, T: Source + ?Sized + 'a> Source for &'a mut T
impl<'a, T: Source + ?Sized + 'a> Source for &'a mut T
A blanket implementation forwards all methods to Source
.
fn source_id(&self) -> SourceId
fn replaced_source_id(&self) -> SourceId
fn supports_checksums(&self) -> bool
fn requires_precise(&self) -> bool
fn query( &mut self, dep: &Dependency, kind: QueryKind, f: &mut dyn FnMut(Summary) ) -> Poll<CargoResult<()>>
fn invalidate_cache(&mut self)
fn set_quiet(&mut self, quiet: bool)
fn download(&mut self, id: PackageId) -> CargoResult<MaybePackage>
fn finish_download( &mut self, id: PackageId, data: Vec<u8> ) -> CargoResult<Package>
fn fingerprint(&self, pkg: &Package) -> CargoResult<String>
fn verify(&self, pkg: PackageId) -> CargoResult<()>
fn describe(&self) -> String
fn is_replaced(&self) -> bool
fn add_to_yanked_whitelist(&mut self, pkgs: &[PackageId])
fn is_yanked(&mut self, pkg: PackageId) -> Poll<CargoResult<bool>>
fn block_until_ready(&mut self) -> CargoResult<()>
source§impl<'a, T: Source + ?Sized + 'a> Source for Box<T>
impl<'a, T: Source + ?Sized + 'a> Source for Box<T>
A blanket implementation forwards all methods to Source
.