14 releases (9 breaking)

0.10.3 Mar 22, 2023
0.10.1 Jan 2, 2023
0.10.0 Dec 29, 2020
0.9.0 Dec 30, 2019
0.6.0 Jul 27, 2019

#1253 in Asynchronous

MIT/Apache

36KB
600 lines

futures-cache

github crates.io docs.rs build status

Futures-aware cache abstraction.

Provides a cache for asynchronous operations that persist data on the filesystem using sled. The async cache works by accepting a future, but will cancel the accepted future in case the answer is already in the cache.

It requires unique cache keys that are serde serializable. To distinguish across different sub-components of the cache, they can be namespaces using Cache::namespaced.


State

The state of the library is:

  • API is limited to only wrap, which includes a timeout (#1).
  • Requests are currently racing in the wrap method, so multiple unecessary requests might occur when they should //! instead be queueing up (#2).
  • Entries only expire when the library is loaded (#3).
  • Only storage backend is sled (#4).

Usage

This library requires the user to add the following dependencies to use:

futures-cache = "0.10.2"
serde = {version = "1.0", features = ["derive"]}

Examples

Simple example showcasing fetching information on a github repository.

This is also available as an example you can run with:

cargo run --example github -- --user udoprog --repo futures-cache
use futures_cache::{Cache, Duration};
use serde::Serialize;

type Error = Box<dyn std::error::Error>;

#[derive(Debug, Serialize)]
enum GithubKey<'a> {
    Repo { user: &'a str, repo: &'a str },
}

async fn github_repo(user: &str, repo: &str) -> Result<String, Error> {
    use reqwest::header;
    use reqwest::{Client, Url};

    let client = Client::new();

    let url = Url::parse(&format!("https://api.github.com/repos/{}/{}", user, repo))?;

    let req = client
        .get(url)
        .header(header::USER_AGENT, "Reqwest/0.10")
        .build()?;

    let body = client.execute(req).await?.text().await?;
    Ok(body)
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    let db = sled::open("cache")?;
    let cache = Cache::load(db.open_tree("cache")?)?;

    let user = "udoprog";
    let repo = "futures-cache";

    let text = cache
        .wrap(
            GithubKey::Repo {
                user: user,
                repo: repo,
            },
            Duration::seconds(60),
            github_repo(user, repo),
        )
        .await?;

    println!("{}", text);
    Ok(())
}

Dependencies

~5–11MB
~111K SLoC