RegistrySource in cargo::sources::registry - Rust
Description: A `Source` implementation for a local or a remote registry.

Skip to main content

## RegistrySource

# Struct RegistrySource

Source

    pub struct RegistrySource<'gctx> {
        name: InternedString,
        source_id: SourceId,
        src_path: Filesystem,
        gctx: &'gctx GlobalContext,
        ops: Box<dyn RegistryData + 'gctx>,
        index: RegistryIndex<'gctx>,
        yanked_whitelist: RefCell<HashSet<PackageId>>,
        selected_precise_yanked: RefCell<HashSet<(InternedString, Version)>>,
    }

Expand description

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§

§`name: InternedString`

A unique name of the source (typically used as the directory name where its cached content is stored).

§`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`).

§`gctx: &'gctx GlobalContext`

Local reference to `GlobalContext` for convenience.

§`ops: Box<dyn RegistryData + 'gctx>`

Abstraction for interfacing to the different registry kinds.

§`index: RegistryIndex<'gctx>`

Interface for managing the on-disk index.

§`yanked_whitelist: RefCell<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.

§`selected_precise_yanked: RefCell<HashSet<(InternedString, Version)>>`

Yanked versions that have already been selected during queries.

As of this writing, this is for not emitting the `--precise <yanked>` warning twice, with the assumption of (`dep.package_name()` + `--precise` version) being sufficient to uniquely identify the same query result.

## Implementations§

Source§

### impl<'gctx> RegistrySource<'gctx>

Source

#### pub fn remote( source_id: SourceId, yanked_whitelist: &HashSet<PackageId>, gctx: &'gctx GlobalContext, ) -> CargoResult<RegistrySource<'gctx>>

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.

Source

#### pub fn local( source_id: SourceId, path: &Path, yanked_whitelist: &HashSet<PackageId>, gctx: &'gctx GlobalContext, ) -> RegistrySource<'gctx>

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.

Source

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

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.

Source

#### pub async fn config(&self) -> CargoResult<Option<RegistryConfig>>

Decode the configuration stored within the registry.

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

Source

#### 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 delete the directory and start over again if an empty `.cargo-ok` file is found.

Source

#### pub fn unpack_package_in( &self, pkg: &PackageId, unpack_dir: &Path, include: &dyn Fn(&Path) -> bool, ) -> CargoResult<PathBuf>

Unpacks the `.crate` tarball of the package in a given directory.

Returns the path to the crate tarball directory, which is always `<unpack_dir>/<pkg>-<version>`.

This holds some assumptions

- The associated tarball already exists
- If this is a local registry, the package cache lock must be externally synchronized. Cargo does not take care of it being locked or not.

Source

#### fn get_pkg(&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§

Source§

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

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. Read more
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 source_id(&self) -> SourceId

Returns the `SourceId` corresponding to this source.
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`. Read more
Source§

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

Gives the source the downloaded `.crate` file. Read more
Source§

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

Generates a unique string which represents the fingerprint of the current state of the source. Read more
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.
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. Read more
Source§

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

Returns whether a source is being replaced by another here. Read more

## Auto Trait Implementations§

§

### impl<'gctx> !Freeze for RegistrySource<'gctx>

§

### impl<'gctx> !RefUnwindSafe for RegistrySource<'gctx>

§

### impl<'gctx> !Send for RegistrySource<'gctx>

§

### impl<'gctx> !Sync for RegistrySource<'gctx>

§

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

§

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

§

### impl<'gctx> !UnwindSafe for RegistrySource<'gctx>

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> IntoEither for T

Source§

#### fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left` is `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

#### fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left(&self)` returns `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
§

### impl<T> Pointable for T

§

#### const ALIGN: usize

The alignment of pointer.
§

#### type Init = T

The type for initializers.
§

#### unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

#### unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

#### unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

#### unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

### impl<T> Same for T

Source§

#### type Output = T

Should always be `Self`
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<T> WithSubscriber for T

§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more

## 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: 384 bytes