Struct Cache

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

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§

Source§

impl<C: Client> Cache<C>

Source

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.

Source

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§

Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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.
Source§

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

Source§

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

Auto Trait Implementations§

§

impl<C> Freeze for Cache<C>
where C: Freeze,

§

impl<C> !RefUnwindSafe for Cache<C>

§

impl<C> Send for Cache<C>
where C: Send,

§

impl<C> !Sync for Cache<C>

§

impl<C> Unpin for Cache<C>
where C: Unpin,

§

impl<C> !UnwindSafe for Cache<C>

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<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

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

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

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, 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.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

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
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,