DEV Community: Max

Four Ways to Cache in Rust

Max — Mon, 06 Apr 2026 00:00:00 +0000

tl;dr: Caching can live in four places: as HTTP middleware, as a client-side proxy, as a function wrapper, or as a raw data structure. Each solves a different problem. Hitbox covers the first three; the fourth is what Moka and Redis already do on their own.

There are a few ways to add caching to a project. They look similar on the surface — all of them store a result and return it later — but they differ in where the cache sits, what it wraps, and how much of your code it touches.

In this article we’ll walk through four approaches, look at each one from the Hitbox perspective, and show a small intro for getting started.

1. Cache as HTTP middleware

This is the reverse-proxy approach. Instead of modifying your handlers, you place a caching layer between the client and your service. The layer intercepts requests, checks the cache, and either returns a stored response or forwards the request upstream.

This is the same idea as enabling cache in NGINX --- but inside your application, with full control over predicates, keys, and TTLs.

In Hitbox, this is the Tower integration. You create a Cache layer and attach it to a route. The layer handles everything: cache key generation, storage, hit/miss logic, and response headers.

use std::time::Duration;

use hitbox::Config;
use hitbox::policy::PolicyConfig;
use hitbox::predicate::PredicateExt;
use hitbox_http::{
    extractors::{MethodConfig, MethodExtractor, query::QueryExtractor},
    predicates::{
        header::{HeaderPredicate, Operation as HeaderOperation},
        response::StatusCodePredicate,
    },
    request, response,
};
use hitbox_moka::MokaBackend;
use hitbox_tower::Cache;

#[tokio::main]
async fn main() {
    let backend = MokaBackend::builder()
        .max_entries(1024 * 1024)
        .build();

    let config = Config::builder()
        .request_predicate(
            // Skip cache when client sends Cache-Control: no-cache
            request::predicate()
                .header(HeaderOperation::Contains(
                    http::header::CACHE_CONTROL,
                    "no-cache".to_string(),
                ))
                .not(),
        )
        .response_predicate(
            // Only cache successful responses
            response::predicate()
                .status(http::StatusCode::OK),
        )
        .extractor(
            request::extractor()
                .method(MethodConfig::new())
                .query("page".to_string())
                .query("limit".to_string()),
        )
        .policy(PolicyConfig::builder()
            .ttl(Duration::from_secs(60))
            .build())
        .build();

    let cache = Cache::builder()
        .backend(backend)
        .config(config)
        .build();

    let app = Router::new()
        .route("/tasks", get(list_tasks).layer(cache))
        .route("/health", get(health));

    // ...
}

The handler code stays untouched. Cache configuration — what to cache, how to build the key, how long to keep it — lives outside the business logic. And you get the full set of Hitbox features: predicates, extractors, stale-while-revalidate, dogpile prevention, and observability.

This approach works best when you own the service and want transparent caching that wraps the entire request-response cycle without modifying handlers.

For a step-by-step walkthrough with Axum, see Add Response Caching to Axum in 10 Minutes. The full example is also available in the repository.

2. Cache as a client-side proxy

This one looks a little unusual, but it is very useful in practice.

This approach requires no changes to your handler code --- just swap the HTTP client for one with a caching middleware.

Imagine your service makes a request to a third-party API on every incoming request. The data you fetch is shared across all users — say, a configuration map or a feature-flag set — but the external call adds significant latency. Your SLA is tight and that extra round-trip makes it hard to stay within bounds.

Here’s a concrete scenario: you fetch a lookup table for all users from a remote service, and your own API has per-user endpoints. If you use the middleware approach (option 1), each user that isn’t in cache triggers a separate call to the remote service. But the remote service returns the same data regardless of which user you’re serving.

The solution is to cache on the client side. Wrap your HTTP client with a caching middleware so it makes only one request per TTL window to the remote service. All subsequent calls within that window return the cached response instantly.

In Hitbox, the hitbox-reqwest crate integrates with reqwest-middleware:

use std::time::Duration;

use hitbox::Config;
use hitbox::policy::PolicyConfig;
use hitbox_http::{
    extractors::{MethodConfig, MethodExtractor, PathExtractor},
    predicates::request::MethodPredicate,
    request, response,
};
use hitbox_moka::MokaBackend;
use hitbox_reqwest::CacheMiddleware;
use reqwest::Client;
use reqwest_middleware::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = MokaBackend::builder()
        .max_entries(1000)
        .build();

    let config = Config::builder()
        .request_predicate(request::predicate().method(http::Method::GET))
        .response_predicate(response::predicate())
        .extractor(
            request::extractor()
                .method(MethodConfig::new())
                .path("/{path}*"),
        )
        .policy(PolicyConfig::builder()
            .ttl(Duration::from_secs(60))
            .build())
        .build();

    let cache_middleware = CacheMiddleware::builder()
        .backend(backend)
        .config(config)
        .build();

    // Build the reqwest client with caching middleware
    let client = ClientBuilder::new(Client::new())
        .with(cache_middleware)
        .build();

    // First request: cache miss, fetches from the remote service
    let response = client
        .get("https://api.example.com/config")
        .send()
        .await?;

    // Second request: cache hit, no network call
    let response = client
        .get("https://api.example.com/config")
        .send()
        .await?;

    Ok(())
}

You don’t rewrite your request logic. You swap the HTTP client for one with a caching layer and the cache takes care of the rest. The same predicates, extractors, and policies from the middleware approach work here too.

The full example is in the repository.

3. Cache as a function wrapper

This is memoization — a well-known pattern, especially if you’ve worked with Python’s @functools.lru_cache or similar decorators.

All Hitbox features --- backends, TTL, stale policies --- work with memoized functions too.

You find a function whose result is expensive to compute and doesn’t change often, and you wrap it with a cache macro. In Hitbox, the hitbox-fn crate provides the #[cached] attribute and derive macros for cache key extraction:

use std::time::Duration;

use hitbox::CacheStatus;
use hitbox_fn::Cache;
use hitbox_fn::prelude::*;
use hitbox_moka::MokaBackend;
use serde::{Deserialize, Serialize};

// Domain types derive KeyExtract for automatic cache key generation
#[derive(Debug, Clone, Copy, KeyExtract)]
pub struct UserId(#[key_extract(name = "user_id")] pub u64);

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, CacheableResponse)]
pub struct UserProfile {
    pub id: u64,
    pub name: String,
}

#[derive(Debug, Clone, PartialEq)]
pub struct ApiError;

// The #[cached] macro transforms this into a cacheable function
#[cached]
pub async fn get_user(user_id: UserId) -> Result<UserProfile, ApiError> {
    println!("[upstream] fetching user {}", user_id.0);
    Ok(UserProfile {
        id: user_id.0,
        name: format!("User {}", user_id.0),
    })
}

#[tokio::main]
async fn main() {
    let cache = Cache::builder()
        .backend(MokaBackend::builder().max_entries(100).build())
        .policy(PolicyConfig::builder()
            .ttl(Duration::from_secs(60))
            .build())
        .build();

    // First call: executes the function, caches the result
    let (result, ctx) = get_user(UserId(1)).cache(&cache).with_context().await;
    assert_eq!(ctx.status, CacheStatus::Miss);

    // Second call: returns cached result, function body never runs
    let (result, ctx) = get_user(UserId(1)).cache(&cache).with_context().await;
    assert_eq!(ctx.status, CacheStatus::Hit);
}

A few things to note:

#[derive(KeyExtract)] on arguments controls which fields become part of the cache key. The #[key_extract(skip)] attribute excludes fields like request IDs that shouldn’t affect caching.
#[derive(CacheableResponse)] on return types controls serialization. The #[cacheable_response(skip)] attribute excludes sensitive fields like access tokens from the cache.
The #[cached] attribute on the function handles the rest — wrapping the call, checking the cache, storing on miss.

This approach works best for expensive computations or data-fetching functions where you want per-call caching without restructuring your code. All Hitbox features — pluggable backends, TTL, stale-while-revalidate — are available through the Cache builder.

The full example with more patterns (multi-argument functions, skipped fields, zero-argument functions) is in the repository.

4. Cache as a data structure

This is probably the first thing most developers think of when they hear “caching”: a key-value store. You pick a spot in the code, create a HashMap (or a Cache from Moka, or a Redis connection), and manually manage get, insert, and delete operations.

use moka::future::Cache;

async fn get_user(
    cache: &Cache<String, Vec<u8>>,
    user_service: &UserService,
    user_id: u64,
) -> Result<User, AppError> {
    let key = format!("user:{user_id}");

    // Manual cache lookup
    if let Some(bytes) = cache.get(&key).await {
        return Ok(serde_json::from_slice(&bytes)?);
    }

    // Cache miss: fetch, serialize, store
    let user = user_service.get_user(user_id).await?;
    let bytes = serde_json::to_vec(&user)?;
    cache.insert(key, bytes).await;

    Ok(user)
}

This gives you maximum control. You decide exactly when to read, when to write, and when to evict. It’s the caching equivalent of working with raw sockets instead of an HTTP framework.

Hitbox doesn't operate at this level --- it's an orchestrator, not a storage engine. For raw key-value access, use Moka or Redis directly.

But it comes with downsides. The caching logic spreads across your codebase, mixed in with business logic. Every handler repeats the same pattern: build a key, check the cache, handle the miss, serialize, store. And as the system grows, you end up reimplementing the features that Hitbox provides out of the box: dogpile prevention, stale-while-revalidate, multi-tier composition, observability.

The difference is similar to using a web framework versus raw TCP sockets. More control, but more work — and more room for subtle bugs.

Hitbox doesn’t work at this level. If raw key-value access is what you need, reach for Moka or Redis directly. For a deeper comparison, see Should I Use Moka or Hitbox?.

Comparison

	HTTP Middleware	Client-Side Proxy	Function Wrapper	Data Structure
Hitbox crate	`hitbox-tower`	`hitbox-reqwest`	`hitbox-fn`	— (use Moka/Redis)
What it wraps	Incoming HTTP requests	Outgoing HTTP requests	Any async function	Nothing (manual)
Code changes	None (add a layer)	Swap the HTTP client	Add `#[cached]` macro	Inline in every call site
Cache key	Extractors (path, query, headers)	Extractors (path, method)	`KeyExtract` derive	Manual string building
Predicates	Request + Response	Request + Response	N/A (cache all calls)	Manual if/else
Dogpile prevention	Built-in	Built-in	Built-in	Manual
Stale-while-revalidate	Built-in	Built-in	Built-in	Manual
Backend composition	L1/L2/L3	L1/L2/L3	L1/L2/L3	Manual
Observability	Metrics + tracing	Metrics + tracing	Metrics + tracing	Manual
Best for	API services you own	Expensive external calls	Pure computations	Fine-grained control

Choosing an approach

The approaches aren’t mutually exclusive. A single service might use HTTP middleware for its public API, a cached reqwest client for calls to external services, and memoization for an expensive internal computation.

Start with the approach that matches where your bottleneck is:

Slow API responses that repeat? HTTP middleware.
Slow external dependency called on every request? Client-side proxy.
Expensive function called with the same arguments? Memoization.
Need full manual control over every cache operation? Data structure.

The first three share the same Hitbox ecosystem — same backends, same configuration patterns, same observability. Moving between them is a configuration change, not a rewrite.

Should I Use Moka or Hitbox?

Max — Sat, 28 Feb 2026 00:00:00 +0000

tl;dr: Both. Moka is a storage backend. Hitbox is an orchestrator. They solve different problems.

Rust has a lot of caching crates: Moka, redis-rs, Memcache, lru_cache, cached, and others. They can be roughly split into two groups — storage engines (databases, data structures) and crates that add higher-level functionality, like http-cache-tower with HTTP semantics. This article focuses on the first group.

The Cache Storage Trap

A typical Moka-based handler looks like this:

use moka::future::Cache;

async fn get_user(
    State(user_service): State<UserService>,
    State(cache): State<Cache<String, Vec<u8>>>,
    Path(user_id): Path<u64>,
) -> Result<Json<User>, AppError> {
    let key = format!("user:{user_id}");

    if let Some(bytes) = cache.get(&key).await {
        return Ok(Json(serde_json::from_slice(&bytes)?));
    }

    let user = user_service.get_user(user_id).await?;
    let bytes = serde_json::to_vec(&user)?;
    cache.insert(key, bytes).await;

    Ok(Json(user))
}

One line of business logic, ten lines of caching plumbing — key construction, serialization (not required for Moka itself, but unavoidable with Redis or other byte-oriented backends), hit/miss logic. This pattern repeats in every handler that uses caching, usually with slight variations.

Under high traffic, this approach runs into several known problems.

Dogpile effect. When a cached entry expires and many requests arrive simultaneously, all of them miss the cache and hit the upstream — the actual data source behind it, whether that’s a database, an external API, or another service. A locking mechanism solves this partially — one request refreshes, the others wait — but if that request is slow or fails, all waiters are affected. A semaphore-based approach allows a few requests to race, with the first to finish broadcasting the result to the rest. There’s also a policy question: if the upstream returns an error, should waiters fail or retry independently?

Offload revalidation. To reduce cache-miss latency, the TTL can be split into two phases — a stale window and a hard expiration. Requests that hit a stale entry receive the cached value immediately while a background job refreshes it.

|── fresh ──|── stale ──|── expired ──>
0       stale_ttl      ttl

Distributed state. With multiple server instances, each running its own Moka cache, hit rates drop because instances don’t share state. Adding Redis solves sharing but removes fast local reads. Using both as L1 (Moka) and L2 (Redis Cluster) preserves local speed but requires refilling logic, write ordering, and consistency code between layers.

On top of this, a production caching system typically also requires metrics, a serialization format and compression, and the ability to add new backends.

So, one day, it becomes its own Hitbox.

Hitbox

Hitbox is a cache orchestrator. It works with storage backends — Moka, Redis, FeOxDB — and provides a Backend trait for adding others. The backends handle storage; Hitbox handles coordination.

For function-level caching, a #[cached] macro replaces the manual plumbing:

#[cached]
async fn get_user(user_id: UserId) -> Result<User, AppError> {
    db.query_user(user_id.0).await
}

For HTTP services, caching is handled as Tower middleware. Predicates define which requests and responses are cacheable, extractors define how cache keys are constructed, and policies define TTL, stale behavior, and concurrency limits. For a step-by-step walkthrough of setting this up in Axum, see Response Caching in Axum with Hitbox.

The features described above — dogpile prevention, stale-while-revalidate, L1/L2 composition — are built-in and controlled through configuration:

Dogpile prevention — a concurrency limit per cache key
Stale-While-Revalidate — a stale window with background refresh via offload policy
L1/L2 composition — backends composed with configurable refill, read, and write policies
Multi-tier — composition is recursive (Moka → FeOxDB → Redis)

Changing the caching strategy — from single-backend to multi-tier, or from no-stale to stale-while-revalidate — is a configuration change. Handler and middleware code remains the same.

Conclusion

Moka, Redis, and Hitbox solve different parts of the caching problem. Moka and Redis are storage engines. Hitbox is an orchestration layer that composes them. There is no choice to make between them — they work together.

Add Response Caching to Axum in 10 Minutes

Max — Mon, 16 Feb 2026 00:00:00 +0000

Your Axum API hits the database on every request. The same query, the same result, hundreds of times per second. Let’s fix that.

In this article we’ll add transparent response caching to an Axum application using Hitbox. No changes to your handlers. No manual cache invalidation. Just a Tower layer that sits between the client and your service.

The API

Full source code is in the examples repository.

We’re building a product catalog API. Two endpoints:

GET /products — list products with pagination and category filtering
GET /products/:id — get product details by ID

Here’s the starting point — pure Axum, no caching:

use axum::{
    Json, Router,
    extract::{Path, Query},
    routing::get,
};
use serde::{Deserialize, Serialize};

// ── Domain types ────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize)]
struct Product {
    id: u32,
    name: String,
    category: String,
    price_cents: u32,
}

#[derive(Debug, Clone, Serialize)]
struct ProductList {
    products: Vec<Product>,
    total: u32,
    page: u32,
}

#[derive(Debug, Deserialize)]
struct ListParams {
    #[serde(default = "default_page")]
    page: u32,
    #[serde(default = "default_limit")]
    limit: u32,
    category: Option<String>,
}

fn default_page() -> u32 { 1 }
fn default_limit() -> u32 { 20 }

// ── Handlers ────────────────────────────────────────────────────────

async fn list_products(Query(params): Query<ListParams>) -> Json<ProductList> {
    // In a real app this queries a database
    tracing::info!("DB query: products page={}, category={:?}",
        params.page, params.category);

    let products = db::find_products(params.category.as_deref(),
        params.page, params.limit);
    let total = db::count_products(params.category.as_deref());

    Json(ProductList { products, total, page: params.page })
}

async fn get_product(
    Path(id): Path<u32>,
) -> Result<Json<Product>, http::StatusCode> {
    tracing::info!("DB query: product id={}", id);

    db::find_product(id)
        .map(Json)
        .ok_or(http::StatusCode::NOT_FOUND)
}

async fn health() -> &'static str { "OK" }

// ── Router ──────────────────────────────────────────────────────────

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/products", get(list_products))
        .route("/products/{id}", get(get_product))
        .route("/health", get(health));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Every request runs a database query. GET /products?page=1 — query. Same request one second later — same query, same result. Let’s fix that.

The cache layer

Hitbox is modular — pick only the crates you need.

First, add Hitbox to your Cargo.toml:

# Hitbox caching
hitbox = "0.2"
hitbox-tower = "0.2"
hitbox-http = "0.2"
hitbox-moka = "0.2"

Four crates, each with a clear role:

Crate	Role
`hitbox`	Core: config, policies, predicate traits
`hitbox-tower`	`Cache` layer for Tower/Axum
`hitbox-http`	HTTP-aware predicates and extractors
`hitbox-moka`	In-memory backend (Moka — lock-free, sub-microsecond)

Now create a backend and the simplest possible cache:

use std::time::Duration;
use hitbox::Config;
use hitbox::policy::PolicyConfig;
use hitbox_moka::MokaBackend;
use hitbox_tower::Cache;

#[tokio::main]
async fn main() {
    // 1. Create an in-memory backend
    let backend = MokaBackend::builder()
        .max_entries(10_000)
        .build();

    // 2. Build a cache config with a 60-second TTL
    let config = Config::builder()
        .policy(PolicyConfig::builder()
            .ttl(Duration::from_secs(60))
            .build())
        .build();

    // 3. Create a Cache layer
    let cache = Cache::builder()
        .backend(backend)
        .config(config)
        .build();

    // 4. Apply it to a route
    let app = Router::new()
        .route("/products", get(list_products).layer(cache))
        .route("/products/{id}", get(get_product))
        .route("/health", get(health));

    // ...
}

That’s a working cache. First request hits your handler, response gets stored. Second request gets the stored response — your handler is never called. After 60 seconds the entry expires and the cycle repeats.

Hitbox adds an x-cache-status header to every response so you can see what happened:

curl -v http://localhost:3000/products
# < x-cache-status: MISS — first request, hit your handler

curl -v http://localhost:3000/products
# < x-cache-status: HIT — served from cache, handler not called

But there’s a problem. Try requesting a negative page number:

curl -v http://localhost:3000/products?page=-1
# < HTTP/1.1 400 Bad Request

curl -v http://localhost:3000/products?page=1
# < HTTP/1.1 400 Bad Request ← cached error!

Your handler correctly rejected page=-1 with a 400 Bad Request — but Hitbox cached that error. Now every request to /products returns the cached 400 for the next 60 seconds. We need to tell Hitbox what to cache and what to let pass through.

Predicates: control what gets cached

Predicates compose with .and(), .or(), and .not() — like building a filter chain.

A predicate is a rule that decides whether a request or response is cacheable. Hitbox evaluates predicates before storing anything. If a predicate says “no”, the response passes through uncached.

There are two kinds:

Request predicates — evaluated before checking the cache. “Should we even look for a cached response?”
Response predicates — evaluated after your handler runs. “Should we store this response?”

The fix for our problem: add a response predicate that only caches 200 OK:

use hitbox::predicate::PredicateExt;
use hitbox_http::predicates::response::StatusCode as ResponseStatusCode;

let config = Config::builder()
    .response_predicate(
        // Only cache 200 OK responses.
        // 400s, 404s, 500s — everything else passes through uncached.
        ResponseStatusCode::new(http::StatusCode::OK),
    )
    .policy(PolicyConfig::builder()
        .ttl(Duration::from_secs(60))
        .build())
    .build();

Now errors never enter the cache. A 400 Bad Request or 404 Not Found goes straight to the client without being stored.

Predicates compose. Want to cache both 200 and 304 responses?

let predicate = ResponseStatusCode::new(http::StatusCode::OK)
    .or(ResponseStatusCode::new(http::StatusCode::NOT_MODIFIED));

The .and(), .or(), and .not() combinators let you build complex rules from simple building blocks.

With the error caching problem solved, there’s still the pagination issue:

curl http://localhost:3000/products?page=1 # MISS — returns page 1, cached
curl http://localhost:3000/products?page=2 # HIT — returns page 1 again!

Both requests hit the same cache entry because Hitbox doesn’t know that page matters. That’s what extractors fix.

Extractors: smart cache keys

Without an extractor, all requests to the same path share one cache entry.

Right now /products?page=1 and /products?page=2 return the same cached response. That’s because the default cache key doesn’t include query parameters. An extractor tells Hitbox which parts of the request to include in the cache key.

Product list — keyed by query params

use hitbox_http::extractors::{
    Method as MethodExtractor,
    query::QueryExtractor as QueryExtractorTrait,
};

let list_config = Config::builder()
    .response_predicate(ResponseStatusCode::new(http::StatusCode::OK))
    .extractor(
        // Cache key = HTTP method + query params
        MethodExtractor::new()
            .query("page".to_string())
            .query("limit".to_string())
            .query("category".to_string()),
    )
    .policy(PolicyConfig::builder()
        .ttl(Duration::from_secs(60))
        .build())
    .build();

Now each combination of page, limit, and category gets its own cache entry:

curl http://localhost:3000/products?page=1 # MISS → cached as key A
curl http://localhost:3000/products?page=2 # MISS → cached as key B
curl http://localhost:3000/products?page=1 # HIT → returns key A
curl http://localhost:3000/products?category=tools # MISS → cached as key C

Product details — keyed by path segment

For /products/{id}, we need the product ID in the cache key. Use a path extractor:

use hitbox_http::extractors::path::PathExtractor;

let details_config = Config::builder()
    .response_predicate(ResponseStatusCode::new(http::StatusCode::OK))
    .extractor(
        // Cache key = HTTP method + product ID from path
        MethodExtractor::new().path("/products/{id}"),
    )
    .policy(PolicyConfig::builder()
        .ttl(Duration::from_secs(300)) // Details change less often
        .build())
    .build();

The .path("/products/{id}") pattern extracts {id} from the URL. Product 1 and product 2 get separate cache entries, each valid for 5 minutes.

Wire both configs into the router:

let list_cache = Cache::builder()
    .backend(backend.clone())
    .config(list_config)
    .build();

let details_cache = Cache::builder()
    .backend(backend.clone())
    .config(details_config)
    .build();

let app = Router::new()
    .route("/products", get(list_products).layer(list_cache))
    .route("/products/{id}", get(get_product).layer(details_cache))
    .route("/health", get(health));

Each route gets its own cache config with its own TTL, extractors, and predicates. The /health endpoint has no cache layer — it always hits the handler.

Auth-aware caching

Header extractors support regex value extraction and transform chains — extract what
you need, hash what's sensitive.

Your API uses API keys or Basic Auth — credentials that don’t expire. Users send an Authorization header with every request. You want each user to get their own cache — but you don’t want raw credentials sitting in your cache keys.

Simple: full header value

The quickest approach — add the Authorization header to the cache key with.header():

use hitbox_http::extractors::header::HeaderExtractor;

let config = Config::builder()
    .response_predicate(ResponseStatusCode::new(http::StatusCode::OK))
    .extractor(
        MethodExtractor::new()
            .query("page".to_string())
            .query("limit".to_string())
            .query("category".to_string())
            .header("authorization".to_string()),
    )
    .policy(PolicyConfig::builder()
        .ttl(Duration::from_secs(60))
        .build())
    .build();

Now user A and user B each get their own cache entries. Anonymous requests (no header) share a separate entry. But the full Authorization value — including the raw token — ends up in the cache key. We can do better.

Transforms: hash sensitive values

Use Header::new_with for full control over extraction. Add Transform::Hash to SHA256-hash the value before it enters the cache key:

use hitbox_http::extractors::header::{
    Header, NameSelector, ValueExtractor, Transform,
};

let extractor = Header::new_with(
    MethodExtractor::new()
        .query("page".to_string())
        .query("limit".to_string())
        .query("category".to_string()),
    NameSelector::Exact("authorization".to_string()),
    ValueExtractor::Full,
    vec![Transform::Hash],
);

let config = Config::builder()
    .response_predicate(ResponseStatusCode::new(http::StatusCode::OK))
    .extractor(extractor)
    .policy(PolicyConfig::builder()
        .ttl(Duration::from_secs(60))
        .build())
    .build();

Transform::Hash produces a truncated SHA256 (16 hex characters). Different tokens produce different cache keys, but the actual token never appears in the key. Good for security audits, good for logging.

Value extraction: pull out what matters

Sometimes you don’t need the whole header value. ValueExtractor::Regex extracts just the part you care about using a capture group.

For Bearer tokens — extract the token part, then hash it:

use regex::Regex;

let extractor = Header::new_with(
    MethodExtractor::new()
        .query("page".to_string()),
    NameSelector::Exact("authorization".to_string()),
    // "Bearer eyJhbG..." → captures "eyJhbG..."
    ValueExtractor::Regex(Regex::new(r"Bearer (.+)").unwrap()),
    vec![Transform::Hash],
);

Transforms chain — each one applies to the output of the previous, left to right. Normalize before hashing for case-insensitive matching:

vec![Transform::Lowercase, Transform::Hash]

Cache-Control: let clients decide

RFC 9111 defines Cache-Control: no-cache — the client asks for a fresh response.

Sometimes a client needs fresh data. An admin refreshing a dashboard, a CI pipeline fetching the latest state. HTTP already has a standard for this: the Cache-Controlheader.

Add a request predicate that respects Cache-Control: no-cache:

let config = Config::builder()
    .request_predicate(
        RequestHeader::new(HeaderOperation::Contains(
            http::header::CACHE_CONTROL,
            "no-cache".to_string(),
        ))
        .not(),
    )
    // ... rest of config
    .build();

The pattern: match the header, invert with .not(). If the client sendsCache-Control: no-cache, the cache is bypassed:

# Normal request — served from cache
curl http://localhost:3000/products
# < x-cache-status: HIT

# Force fresh response
curl -H 'Cache-Control: no-cache' http://localhost:3000/products
# < x-cache-status: MISS

Your API now speaks the HTTP caching language. Clients that need control have it. Clients that don’t send the header get fast cached responses.

Full example

The complete product catalog API with all the caching patterns from this article is available as a runnable example:axum-caching-in-10-minutes.

What’s next

Everything in Hitbox composes — backends, predicates, extractors.
Mix and match to fit your architecture.

This article covered the core concepts: backends, predicates, and extractors. Hitbox can do more:

Different backends — Replace hitbox-moka with hitbox-redis for distributed caching across multiple instances. Same builder API, shared cache.
Backend composition — Combine backends into layered caches. Local Moka in front of remote Redis — L1/L2 caching with configurable promotion policies.
Body predicates and extractors — Cache based on response body content. For example, skip caching empty product lists or extract cache keys from JSON payloads.
Stale-while-revalidate — Serve stale data instantly while refreshing in the background with PolicyConfig::builder().stale(Duration::from_secs(300)).
Dogpile prevention — When a cache entry expires, only one request triggers the upstream call. The rest subscribe to a broadcast channel and wait for the result. Built in, no configuration needed.

Check the documentation and the examples repository for the full feature set.