http-cache-tower 1.0.0-alpha.8

HTTP cache middleware for Tower/Hyper
Documentation

http-cache-tower

CI Crates.io Docs.rs Codecov Crates.io

An HTTP caching middleware for Tower and Hyper.

This crate provides Tower Layer and Service implementations that add HTTP caching capabilities to your HTTP clients and services.

Minimum Supported Rust Version (MSRV)

1.90.0

Install

With cargo add installed :

cargo add http-cache-tower

Features

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

  • manager-redb (default): enable redb, an embedded, persistent disk cache, backend manager.
  • manager-cacache: 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 for memory-efficient handling of large responses using StreamingManager.
  • rate-limiting (disabled): enable cache-aware rate limiting functionality.
  • url-ada (disabled): enable ada-url for URL parsing.

Example

Basic HTTP Cache

use http_cache_tower::HttpCacheLayer;
use http_cache::RedbManager;
use tower::{ServiceBuilder, ServiceExt};
use http::{Request, Response};
use http_body_util::Full;
use bytes::Bytes;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a cache manager
    let cache_manager = RedbManager::new("./http-cache.redb")?;

    // Create the cache layer
    let cache_layer = HttpCacheLayer::new(cache_manager);

    // Build your service stack
    let service = ServiceBuilder::new()
        .layer(cache_layer)
        .service_fn(|_req: Request<Full<Bytes>>| async {
            Ok::<_, std::convert::Infallible>(
                Response::new(Full::new(Bytes::from("Hello, world!")))
            )
        });

    // Use the service
    let request = Request::builder()
        .uri("https://httpbin.org/cache/300")
        .body(Full::new(Bytes::new()))?;

    let response = service.oneshot(request).await?;

    println!("Status: {}", response.status());

    Ok(())
}

Streaming HTTP Cache

For large responses or when memory efficiency is important, use the streaming cache layer:

# #[cfg(feature = "streaming")]
use http_cache_tower::HttpCacheStreamingLayer;
# #[cfg(feature = "streaming")]
use http_cache::StreamingManager;
# #[cfg(feature = "streaming")]
use tower::{ServiceBuilder, ServiceExt};
# #[cfg(feature = "streaming")]
use http::{Request, Response};
# #[cfg(feature = "streaming")]
use http_body_util::Full;
# #[cfg(feature = "streaming")]
use bytes::Bytes;

# #[cfg(feature = "streaming")]
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // StreamingManager uses redb (metadata) + raw files on disk (bodies), fronted by moka as a hot cache
    let streaming_manager = StreamingManager::with_temp_dir(1000).await?;

    // Create the streaming cache layer
    let cache_layer = HttpCacheStreamingLayer::new(streaming_manager);

    // Build your service stack
    let service = ServiceBuilder::new()
        .layer(cache_layer)
        .service_fn(|_req: Request<Full<Bytes>>| async {
            Ok::<_, std::convert::Infallible>(
                Response::new(Full::new(Bytes::from("Large response data...")))
            )
        });

    // Use the service - responses are streamed without buffering entire body
    let request = Request::builder()
        .uri("https://example.com/large-file")
        .body(Full::new(Bytes::new()))?;

    let response = service.oneshot(request).await?;

    println!("Status: {}", response.status());

    Ok(())
}

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

Note: For memory-efficient streaming of large responses, use StreamingManager with HttpCacheStreamingLayer. For traditional caching with smaller responses, use CACacheManager or MokaManager with HttpCacheLayer.

Cache Backends

This crate supports multiple cache backends through feature flags:

  • manager-redb (default): Persistent disk caching using redb
  • manager-cacache: Disk-based caching using cacache
  • manager-moka: In-memory caching using moka

Integration with Hyper Client

use http_cache_tower::HttpCacheLayer;
use http_cache::RedbManager;
use hyper_util::client::legacy::Client;
use hyper_util::rt::TokioExecutor;
use tower::{ServiceBuilder, ServiceExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cache_manager = RedbManager::new("./http-cache.redb")?;
    let cache_layer = HttpCacheLayer::new(cache_manager);

    let client = Client::builder(TokioExecutor::new()).build_http();

    let cached_client = ServiceBuilder::new()
        .layer(cache_layer)
        .service(client);

    // Now use cached_client for HTTP requests
    Ok(())
}

Documentation

License

Licensed under either of

at your option.