Struct cargo::sources::registry::RegistrySource

pub struct RegistrySource<'cfg> {
    source_id: SourceId,
    src_path: Filesystem,
    config: &'cfg Config,
    ops: Box<dyn RegistryData + 'cfg>,
    index: RegistryIndex<'cfg>,
    yanked_whitelist: HashSet<PackageId>,
}

A Source implementation for a local or a remote registry.

This contains common functionality that is shared between each registry kind, with the registry-specific logic implemented as part of the RegistryData trait referenced via the ops field.

For general concepts of registries, see the module-level documentation.

Fields

source_id: SourceId

The unique identifier of this source.

src_path: Filesystem

The path where crate files are extracted ($CARGO_HOME/registry/src/$REG-HASH).

config: &'cfg Config

Local reference to Config for convenience.

ops: Box<dyn RegistryData + 'cfg>

Abstraction for interfacing to the different registry kinds.

index: RegistryIndex<'cfg>

Interface for managing the on-disk index.

yanked_whitelist: HashSet<PackageId>

A set of packages that should be allowed to be used, even if they are yanked.

This is populated from the entries in Cargo.lock to ensure that cargo update somepkg won’t unlock yanked entries in Cargo.lock. Otherwise, the resolver would think that those entries no longer exist, and it would trigger updates to unrelated packages.

Implementations

impl<'cfg> RegistrySource<'cfg>

pub fn remote( source_id: SourceId, yanked_whitelist: &HashSet<PackageId>, config: &'cfg Config ) -> CargoResult<RegistrySource<'cfg>>

Creates a Source of a “remote” registry. It could be either an HTTP-based http_remote::HttpRegistry or a Git-based remote::RemoteRegistry.

• yanked_whitelist — Packages allowed to be used, even if they are yanked.

pub fn local( source_id: SourceId, path: &Path, yanked_whitelist: &HashSet<PackageId>, config: &'cfg Config ) -> RegistrySource<'cfg>

Creates a Source of a local registry, with local::LocalRegistry under the hood.

• path — The root path of a local registry on the file system.
• yanked_whitelist — Packages allowed to be used, even if they are yanked.

fn new( source_id: SourceId, config: &'cfg Config, name: &str, ops: Box<dyn RegistryData + 'cfg>, yanked_whitelist: &HashSet<PackageId> ) -> RegistrySource<'cfg>

Creates a source of a registry. This is a inner helper function.

• name — Name of a path segment which may affect where .crate tarballs, the registry index and cache are stored. Expect to be unique.
• ops — The underlying RegistryData type.
• yanked_whitelist — Packages allowed to be used, even if they are yanked.

pub fn config(&mut self) -> Poll<CargoResult<Option<RegistryConfig>>>

Decode the configuration stored within the registry.

This requires that the index has been at least checked out.

fn unpack_package(&self, pkg: PackageId, tarball: &File) -> CargoResult<PathBuf>

Unpacks a downloaded package into a location where it’s ready to be compiled.

No action is taken if the source looks like it’s already unpacked.

History of interruption detection with .cargo-ok file

Cargo has always included a .cargo-ok file (PACKAGE_SOURCE_LOCK) to detect if extraction was interrupted, but it was originally empty.

In 1.34, Cargo was changed to create the .cargo-ok file before it started extraction to implement fine-grained locking. After it was finished extracting, it wrote two bytes to indicate it was complete. It would use the length check to detect if it was possibly interrupted.

In 1.36, Cargo changed to not use fine-grained locking, and instead used a global lock. The use of .cargo-ok was no longer needed for locking purposes, but was kept to detect when extraction was interrupted.

In 1.49, Cargo changed to not create the .cargo-ok file before it started extraction to deal with .crate files that inexplicably had a .cargo-ok file in them.

In 1.64, Cargo changed to detect .crate files with .cargo-ok files in them in response to CVE-2022-36113, which dealt with malicious .crate files making .cargo-ok a symlink causing cargo to write “ok” to any arbitrary file on the filesystem it has permission to.

In 1.71, .cargo-ok changed to contain a JSON { v: 1 } to indicate the version of it. A failure of parsing will result in a heavy-hammer approach that unpacks the .crate file again. This is in response to a security issue that the unpacking didn’t respect umask on Unix systems.

This is all a long-winded way of explaining the circumstances that might cause a directory to contain a .cargo-ok file that is empty or otherwise corrupted. Either this was extracted by a version of Rust before 1.34, in which case everything should be fine. However, an empty file created by versions 1.36 to 1.49 indicates that the extraction was interrupted and that we need to start again.

Another possibility is that the filesystem is simply corrupted, in which case deleting the directory might be the safe thing to do. That is probably unlikely, though.

To be safe, we deletes the directory and starts over again if an empty .cargo-ok file is found.

fn get_pkg(&mut self, package: PackageId, path: &File) -> CargoResult<Package>

Turns the downloaded .crate tarball file into a Package.

This unconditionally sets checksum for the returned package, so it should only be called after doing integrity check. That is to say, you need to call either RegistryData::download or RegistryData::finish_download before calling this method.

Trait Implementations

impl<'cfg> Source for RegistrySource<'cfg>

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.

fn supports_checksums(&self) -> bool

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

fn requires_precise(&self) -> bool

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

fn source_id(&self) -> SourceId

Returns the SourceId corresponding to this source.

fn invalidate_cache(&mut self)

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

fn set_quiet(&mut self, quiet: bool)

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

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

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

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

Gives the source the downloaded .crate file.

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

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

fn describe(&self) -> String

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

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.

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.

fn block_until_ready(&mut self) -> CargoResult<()>

Block until all outstanding Poll::Pending requests are Poll::Ready.

fn replaced_source_id(&self) -> SourceId

Returns the replaced SourceId corresponding to this source.

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.

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.

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

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

fn is_replaced(&self) -> bool

Returns whether a source is being replaced by another here.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 192 bytes