Struct Cache

pub struct Cache<C: Client> { /* private fields */ }

Represents a local cache of HTTP resources.

Whenever you ask it for the contents of a URL, it will re-use a previously-downloaded copy if the resource has not changed on the server. Otherwise, it will download the new version and use that instead.

See an example.

Implementations

impl<C: Client> Cache<C>

pub fn new(root: PathBuf, client: C) -> Result<Cache<C>, Box<dyn Error>>

Returns a Cache that wraps client and caches data in root.

If the directory root does not exist, it will be created. If multiple instances share the same root (concurrently or in series), each instance will be able to re-use resources downloaded by the others.

For best results, choose a root that is directly attached to the computer running your program, such as somewhere inside the %LOCALAPPDATA% directory on Windows, or the $XDG_CACHE_HOME directory on POSIX systems.

client should almost certainly be a reqwest::Client, but you can use any type that implements reqwest_mock::Client if you want to use a different HTTP client library or a test double of some kind.

let mut cache = static_http_cache::Cache::new(
    PathBuf::from("my_cache_directory"),
    reqwest::blocking::Client::new(),
)?;

Errors

This method may return an error:

• if root cannot be created, or cannot be written to
• if the metadata database cannot be created or cannot be written to
• if the metadata database is corrupt

In all cases, it should be safe to blow away the entire directory and start from scratch. It’s only cached data, after all.

pub fn get(&mut self, url: Url) -> Result<File, Box<dyn Error>>

Retrieve the content of the given URL.

If we’ve never seen this URL before, we will try to retrieve it (with a GET request) and store its data locally.

If we have seen this URL before, we will ask the server whether our cached data is stale. If our data is stale, we’ll download the new version and store it locally. If our data is fresh, we’ll re-use the local copy we already have.

If we can’t talk to the server to see if our cached data is stale, we’ll silently re-use the data we have.

Returns a file-handle to the local copy of the data, open for reading.

let file = cache.get(reqwest::Url::parse("http://example.com/some-resource")?)?;

Errors

This method may return an error:

• if the cache metadata is corrupt
• if the requested resource is not cached, and we can’t connect to/download it
• if we can’t update the cache metadata
• if the cache metadata points to a local file that no longer exists

After returning a network-related or disk I/O-related error, this Cache instance should be OK and you may keep using it. If it returns a database-related error, the on-disk storage should be OK, so you might want to destroy this Cache instance and create a new one pointing at the same location.

Trait Implementations

impl<C: Debug + Client> Debug for Cache<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: PartialEq + Client> PartialEq for Cache<C>

fn eq(&self, other: &Cache<C>) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C: Eq + Client> Eq for Cache<C>

impl<C: Client> StructuralPartialEq for Cache<C>