Struct SparseIndex

pub struct SparseIndex { /* private fields */ }

Wrapper around managing a sparse HTTP index, re-using Cargo’s local disk caches.

Currently it only uses local Cargo cache, and does not access the network in any way. For examples of how to update the local cache, see examples/sparse_http_reqwest.rs and examples/sparse_http_ureq.rs.

Implementations

impl SparseIndex

pub fn from_url(url: &str) -> Result<Self, Error>

Creates a view over the sparse HTTP index from a provided URL, opening the same location on disk that Cargo uses for that registry index’s metadata and cache.

Note this function takes the CARGO_HOME environment variable into account

pub fn new_cargo_default() -> Result<Self, Error>

Creates an index for the default crates.io registry, using the same disk location as Cargo itself.

This is the recommended way to access the crates.io sparse index.

Note this function takes the CARGO_HOME environment variable into account

pub fn with_path( cargo_home: impl AsRef<Path>, url: impl AsRef<str>, ) -> Result<Self, Error>

Creates a view over the sparse HTTP index from the provided URL, rooted at the specified location

pub fn at_path(path: PathBuf, url: String) -> Self

Creates a view over the sparse HTTP index at the exact specified path

pub fn index_config(&self) -> Result<IndexConfig, Error>

Get the global configuration of the index. There are no guarantees around freshness, and if the config is not available, no fetch will be performed.

pub fn crate_from_cache(&self, name: &str) -> Result<Crate, Error>

Reads a crate from the local cache of the index. There are no guarantees around freshness, and if the crate is not known in the cache, no fetch will be performed.

pub fn url(&self) -> &str

The HTTP url of the index

pub fn crate_url(&self, name: &str) -> Option<String>

Get the URL that can be used to fetch the index entry for the specified crate

The body of a successful response for the returned URL can be parsed via Crate::from_slice

pub fn make_config_request(&self) -> Result<Builder, Error>

Available on crate feature sparse only.

Creates an HTTP request that can be sent via your HTTP client of choice to retrieve the config for this index.

See Self::parse_config_response() processing the response from the remote index.

It is highly recommended to assume HTTP/2 when making requests to remote indices, at least crates.io.

pub fn make_cache_request(&self, name: &str) -> Result<Builder, Error>

Available on crate feature sparse only.

Creates an HTTP request that can be sent via your HTTP client of choice to retrieve the current metadata for the specified crate namw.

See Self::parse_cache_response() processing the response from the remote index.

It is highly recommended to assume HTTP/2 when making requests to remote indices, at least crates.io.

pub fn parse_config_response( &self, response: Response<Vec<u8>>, write_config: bool, ) -> Result<IndexConfig, Error>

Available on crate feature sparse only.

Process the response to a request created by Self::make_config_request().

If write_config is true, write the configuration to disk after parsing it. Note that the write operation may fail, and as opposed to the similar parameter in Self::parse_cache_response(), write errors will not be ignored.

Note that the response from sparse HTTP indices, at least crates.io, may send responses with gzip compression, it is your responsibility to decompress it before sending to this function.

pub fn parse_cache_response( &self, name: &str, response: Response<Vec<u8>>, write_cache_entry: bool, ) -> Result<Option<Crate>, Error>

Available on crate feature sparse only.

Process the response to a request created by Self::make_cache_request

This handles both the scenario where the local cache is missing the specified crate, or it is out of date, as well as the local entry being up to date and can just be read from disk

You may specify whether an updated index entry is written locally to the cache or not

Note that responses from sparse HTTP indices, at least crates.io, may send responses with gzip compression, it is your responsibility to decompress it before sending to this function