http-cache-reqwest

A caching middleware that follows HTTP caching rules, thanks to http-cache-semantics. By default, it uses cacache as the backend cache manager. Uses reqwest-middleware for middleware support.

Minimum Supported Rust Version (MSRV)

1.88.0

Install

With cargo add installed :

cargo add http-cache-reqwest

Example

use reqwest::Client;
use reqwest_middleware::{ClientBuilder, Result};
use http_cache_reqwest::{Cache, CacheMode, CACacheManager, HttpCache, HttpCacheOptions};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<()> {
    let client = ClientBuilder::new(Client::new())
        .with(Cache(HttpCache {
          mode: CacheMode::Default,
          manager: CACacheManager::new(PathBuf::from("./cache"), false),
          options: HttpCacheOptions::default(),
        }))
        .build();
    client
        .get("https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching")
        .send()
        .await?;
    Ok(())
}

Streaming Support

When the streaming feature is enabled, you can use StreamingCache for efficient handling of large responses without buffering them entirely in memory. This provides significant memory savings (typically 35-40% reduction) while maintaining full HTTP caching compliance.

Note: Only StreamingCacheManager supports streaming. CACacheManager and MokaManager do not support streaming and will buffer responses in memory.

use reqwest::Client;
use reqwest_middleware::ClientBuilder;
use http_cache_reqwest::{StreamingCache, CacheMode};

#[cfg(feature = "streaming")]
use http_cache::StreamingManager;

#[cfg(feature = "streaming")]
#[tokio::main]
async fn main() -> reqwest_middleware::Result<()> {
    let streaming_manager = StreamingManager::in_memory(1000).await.unwrap();
    let client = ClientBuilder::new(Client::new())
        .with(StreamingCache::new(
            streaming_manager,
            CacheMode::Default,
        ))
        .build();
        
    // Efficiently stream large responses - cached responses are also streamed
    let response = client
        .get("https://httpbin.org/stream/1000")
        .send()
        .await?;
        
    // Process response as a stream
    use futures_util::StreamExt;
    let mut stream = response.bytes_stream();
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        // Process each chunk without loading entire response into memory
        println!("Received {} bytes", chunk.len());
    }
    
    Ok(())
}

#[cfg(not(feature = "streaming"))]
fn main() {}

Features

The following features are available. By default manager-cacache is enabled.

• manager-cacache (default): enable cacache, a high-performance disk cache, backend manager.
• manager-moka (disabled): enable moka, a high-performance in-memory cache, backend manager.
• manager-foyer (disabled): enable foyer, a hybrid in-memory + disk cache, backend manager.
• streaming (disabled): enable streaming cache support with efficient memory usage. Provides StreamingCache middleware that can handle large responses without buffering them entirely in memory, while maintaining full HTTP caching compliance. Requires cache managers that implement StreamingCacheManager.
• rate-limiting (disabled): enable cache-aware rate limiting functionality.
• url-ada (disabled): enable ada-url for URL parsing.

Documentation

• API Docs

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.