Crate hitbox 

Hitbox

Highly customizable async caching framework for Rust designed for high-performance applications.

Hitbox is protocol-agnostic at its core, with first-class HTTP support via hitbox-http. It provides pluggable backends from in-memory (Moka) to distributed solutions (Redis). Built on Tower, it works with any tokio-based service.

Quick Start

If you need to add caching to your project, choose the appropriate integration based on your use case:

Use Case	Crate	Description
Server-side (Axum, Tower-based frameworks)	hitbox-tower	Tower middleware layer for HTTP handlers
Client-side (Hyper)	hitbox-tower	Tower middleware layer for hyper client
Client-side (Reqwest)	hitbox-reqwest	Cache responses from external APIs via reqwest-middleware

For detailed usage, see the documentation for these crates and the examples directory.

Understanding Hitbox

The Hitbox Ecosystem

Hitbox is organized as a collection of crates, each with a specific responsibility:

Crate	Description
hitbox	Main crate — re-exports core types, policy configuration, error types
hitbox-core	Protocol-agnostic core traits (Predicate, Extractor, CacheableRequest, CacheableResponse)
hitbox-backend	Backend trait and utilities for implementing storage backends
hitbox-http	HTTP-specific predicates and extractors for request/response caching
hitbox-tower	Tower middleware (Cache layer) for server-side caching
hitbox-moka	In-memory backend using Moka
hitbox-redis	Distributed backend using Redis (single node and cluster)
hitbox-feoxdb	Embedded persistent backend using FeOxDB
hitbox-reqwest	Client-side caching for Reqwest via reqwest-middleware
hitbox-test	Testing utilities including MockTime for deterministic cache tests

Core Principles

Under the hood, Hitbox uses a Finite State Machine (FSM) to orchestrate cache operations. The FSM operates with four abstract traits that make Hitbox extensible to any protocol:

Backend

A Backend is a storage where cached data lives. It can be:

• In-memory — like Moka for single-instance, high-speed caching
• Distributed — like Redis (single node or cluster) for shared caching across instances
• Embedded — like FeOxDB for persistent local storage

If you need a backend for a database that isn’t in our list, you can add it by implementing the Backend trait. See the hitbox-backend documentation for details.

Upstream

An Upstream is a source of data. It could be:

• An HTTP handler in a web framework
• An external API call via Reqwest or Hyper
• Any async function that produces data

The FSM calls the Upstream when the cache misses (data not found in the Backend).

Predicate

A Predicate answers the question: “Should this request/response be cached?”

The easiest way to explain predicates is through HTTP examples:

Request predicates — We might want to cache requests that:

• Have a specific HTTP method (e.g., only GET requests)
• Match a particular path pattern
• Do NOT contain a Cache-Control: no-cache header
• Do NOT have a cache=false query parameter

Response predicates — We might want to cache responses that:

• Have a successful status code (2xx)
• Do NOT contain sensitive headers
• Have a body smaller than a certain size

Predicates implement the Predicate trait, which takes a request or response and returns Cacheable or NonCacheable. They can be combined using AND (chaining), OR, and NOT logic.

Extractor

An Extractor creates the cache key from request components.

For HTTP, you might extract:

• Method and path as the base key
• Path parameters like {user_id} from /api/users/{user_id}
• Query parameters like page or limit that affect the response
• Headers like Accept-Language for localized content

Multiple extractors can be chained together, each contributing parts to the final cache key.

Example: For a request to GET /api/users/123/posts?page=2 with Accept-Language: en, an extractor configured for method, path params, query, and headers would produce a key containing: ["GET", "123", "2", "en"].

Re-exports

pub use error::CacheError;

pub use config::CacheConfig;

pub use config::Config;

pub use config::ConfigBuilder;

pub use config::NotSet;

Modules

backend

Backend-related re-exports and utilities.

concurrency

Dogpile prevention via concurrency management.

config

Cache configuration types.

context

Cache context and status types.

error

Error types for cache operations.

extractor

Extractor trait for cache key generation.

fsm

Finite State Machine for cache orchestration.

metrics

Metrics collection for cache observability.

offload

Background task offloading for stale-while-revalidate.

policy

Policy configuration for cache behavior.

predicate

Predicate trait and combinators for cache decisions.

prelude

The hitbox prelude.

Structs

And

Requires both predicates to return Cacheable.

BackendLabel

A label identifying a cache backend.

CacheContext

Context information about a cache operation.

CacheKey

A cache key identifying a cached entry.

CacheValue

A cached value with expiration metadata.

CacheablePolicyData

A cacheable request bundled with its generated cache key.

EntityPolicyConfig

Configuration for entity caching TTLs.

KeyPart

A single component of a cache key.

KeyParts

Builder for accumulating cache key parts during extraction.

Neutral

A predicate that always returns Cacheable.

Not

Inverts a predicate result.

Or

Requires either predicate to return Cacheable.

Enums

CachePolicy

Result of a cache decision.

CacheState

Freshness state of cached data.

CacheStatus

Whether the request resulted in a cache hit, miss, or stale data.

ResponseSource

Source of the response - either from upstream or from a cache backend.

Traits

CacheStatusExt

Extension trait for enriching responses with cache status information.

CacheableRequest

Trait for request types that can participate in caching.

CacheableResponse

Trait for response types that can be cached.

Context

Unified context for cache operations.

Extractor

Trait for extracting cache key components from a subject.

Predicate

Trait for evaluating whether a subject should be cached.

PredicateExt

Extension trait for fluent predicate composition.

Type Aliases

BoxContext

Boxed context trait object using SmallBox for inline storage.

Raw

Raw byte data type used for serialized cache values. Using Bytes provides efficient zero-copy cloning via reference counting.

RequestCachePolicy

Cache policy for requests.

ResponseCachePolicy

Cache policy for responses.