tower-http-cache

Tower middleware for HTTP response caching with pluggable storage backends (in-memory, Redis, and more). tower-http-cache brings a production-grade caching layer to Tower/Axum/Hyper stacks, with stampede protection, stale-while-revalidate, header allowlisting, compression, and policy controls out of the box.

Features at a Glance

• ✅ Drop-in CacheLayer: wrap any Tower service; caches GET/HEAD by default.
• 🔒 Stampede protection: deduplicates concurrent misses and serves stale data while recomputing.
• ⏱ Flexible TTLs: positive/negative TTL, refresh-before-expiry window, stale-while-revalidate.
• 📦 Pluggable storage: in-memory backend (Moka) and optional Redis backend (async pooled).
• 📏 Policy guards: min/max body size, cache-control respect/override, custom method/status filters.
• 🧰 Custom keys: built-in extractors (path, path+query) plus custom closures.
• 📉 Observability hooks: optional metrics counters and tracing spans.

Installation

[dependencies]
tower-http-cache = "0.1"

# Enable Redis support if required
tower-http-cache = { version = "0.1", features = ["redis-backend"] }

Quick Start

use std::time::Duration;
use tower::ServiceBuilder;
use tower_http_cache::prelude::*;

let cache_layer = CacheLayer::builder(InMemoryBackend::new(10_000))
    .ttl(Duration::from_secs(120))
    .negative_ttl(Duration::from_secs(10))
    .stale_while_revalidate(Duration::from_secs(30))
    .refresh_before(Duration::from_secs(5))
    .min_body_size(Some(1024))
    .max_body_size(Some(256 * 1024))
    .respect_cache_control(true)
    .build();

let svc = ServiceBuilder::new()
    .layer(cache_layer)
    .service(tower::service_fn(|_req| async {
        Ok::<_, std::convert::Infallible>(http::Response::new("hello world"))
    }));

Using the Redis backend

use std::time::Duration;
use tower_http_cache::prelude::*;

async fn build_redis_layer(redis_url: &str) -> CacheLayer<RedisBackend> {
    let client = redis::Client::open(redis_url).expect("valid Redis URL");
    let manager = client.get_tokio_connection_manager().await.expect("connect");

    CacheLayer::builder(RedisBackend::new(manager))
        .ttl(Duration::from_secs(30))
        .stale_while_revalidate(Duration::from_secs(10))
        .build()
}

Configuration Highlights

For the full API surface, see the generated docs: cargo doc --open.

Benchmarks

Benchmarks are powered by Criterion and can be reproduced with:

cargo bench --bench cache_benchmarks

Latest results (macOS / M3 Pro / Rust 1.85, redis-backend disabled unless noted):

Full raw output, including outlier analysis, is captured in initial_benchmark.md.

Testing & Tooling

# Library unit tests + integration tests
cargo test

# Redis integration tests
REDIS_URL=redis://127.0.0.1:6379/ cargo test --features redis-backend --tests redis_example

# Redis smoke test (launches example service, verifies cache hit/miss behaviour)
docker compose -f docker-compose.redis.yml up -d redis
python3 scripts/redis_smoke.py
docker compose -f docker-compose.redis.yml down

# Examples
cargo run --example axum_basic --features middleware
cargo run --example axum_custom --features middleware
cargo run --example redis_smoke --features redis-backend

Feature Flags

Minimum Supported Rust Version

MSRV: 1.75.0 (matching the crate's rust-version field). The MSRV will only increase with a minor version bump and will be documented in release notes.

Status

tower-http-cache is under active development. Expect API adjustments while we stabilize the 0.x series. Contributions and feedback are welcome—feel free to open an issue or PR! ***

License

This project is dual-licensed under either:

• 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)

You may choose either license to suit your needs. Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in the crate shall be dual-licensed as above, without additional terms or conditions.

Contributing

1. Fork and clone the repository.
2. Install prerequisites (cargo, rustup, and Docker if you plan to run Redis tests).
3. Run the checks:

   cargo fmt --all
   cargo clippy --all-targets --all-features
   cargo test
   python3 scripts/redis_smoke.py
   

4. Open a pull request with a succinct summary, test evidence, and (when applicable) benchmark output via cargo bench.

Bug reports and feature requests are welcome in the issue tracker. For larger design changes, please start a discussion thread to align on API shape before submitting code.