udoprog/futures-cache

Futures-aware cache backed by sled

futures-cache

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.3"
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(())
}

futures-cache's Issues

Support multiple backends

Currently only sled is supported. It would be a nice to have to support other databases, like memcached.

Prevent request-racing in futures wrapper

Currently any asynchronous request that enters wrap will race against each other, causing more requests than needed to go through.

Instead, do:

• Only one request for a given unique key may be pending at a time, the other futures should queue up.
• If that one request fails, all queued up futures should be marked as failed with the same error (this might be an issue if the error is not Clone). Alternatively, we provide our own error variant for this case.

Expire entries and run compactions explicitly in the background

Compactions are currently handled by rocksdb which spawns its own threads for this purpose.

Instead, allow the user to setup their own background process (the following is just an example):

let cleaner = cache.cleaner().entry_limit(100).interval(Duration::secs(10)).build();
tokio::spawn(cleaner);

This way, if the cleaner is dropped, so is the background procedure.

API is not fleshed out

Currently this API was lifted from what was needed in OxidizeBot, but it has not been fleshed out at all to support more use-cases.

Possible things that can be fixed:

• Rename wrap
• wrap can return a builder with sensible defaults, that can be configured per namespaced cache.