hitbox-redis

Redis cache backend for the Hitbox caching framework.

This crate provides [RedisBackend], a cache backend powered by redis-rs. It supports both single-node Redis instances and Redis Cluster deployments (with the cluster feature).

Overview

Single-node or cluster: Connect to a single Redis instance or a Redis Cluster
Multiplexed connection: Efficient connection reuse via ConnectionManager
Automatic TTL: Entries expire using native Redis TTL mechanism
Lazy connection: Connection established on first operation, not at construction

Quickstart

Single Node

use hitbox_redis::{RedisBackend, ConnectionMode};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let backend = RedisBackend::builder()
    .connection(ConnectionMode::single("redis://localhost:6379/"))
    .build()?;
# Ok(())
# }

Cluster

Requires the cluster feature.

# #[cfg(feature = "cluster")]
# fn main() -> Result<(), Box<dyn std::error::Error>> {
use hitbox_redis::{RedisBackend, ConnectionMode};

let backend = RedisBackend::builder()
    .connection(ConnectionMode::cluster([
        "redis://node1:6379",
        "redis://node2:6379",
        "redis://node3:6379",
    ]))
    .build()?;
# Ok(())
# }
# #[cfg(not(feature = "cluster"))]
# fn main() {}

Configuration

Option	Default	Description
`connection`	(required)	Connection mode (single or cluster)
`username`	None	Redis 6+ ACL username
`password`	None	Redis password
`key_format`	`Bitcode`	Cache key serialization format
`value_format`	`BincodeFormat`	Value serialization format
`compressor`	`PassthroughCompressor`	Compression strategy
`label`	`"redis"`	Backend label for multi-tier composition

Serialization Formats

The value_format option controls how cached data is serialized. Available formats are provided by hitbox_backend::format:

Format	Speed	Size	Human-readable	Use case
`BincodeFormat`	Fast	Compact	No	Production (default, recommended)
`JsonFormat`	Slow	Large	Partial*	Debugging, interoperability
`RonFormat`	Medium	Medium	Yes	Config files, debugging
`RkyvFormat`	Fastest	Compact	No	Zero-copy, max performance

* JSON serializes binary data as byte arrays [104, 101, ...], not readable strings.

Note: RkyvFormat requires enabling the rkyv_format feature on hitbox-backend.

Key Formats

The key_format option controls how CacheKey values are serialized for Redis:

Format	Size	Human-readable	Use case
`Bitcode`	Compact	No	Production (default, recommended)
`UrlEncoded`	Larger	Yes	Debugging, CDN/HTTP integration

Compression Strategies

The compressor option controls whether cached data is compressed. Available compressors are provided by [hitbox_backend]:

Compressor	Ratio	Speed	Feature flag
`PassthroughCompressor`	None	Fastest	—
`GzipCompressor`	Good	Medium	`gzip`
`ZstdCompressor`	Best	Fast	`zstd`

For Redis backends, compression is often recommended since it reduces:

Network bandwidth between application and Redis
Redis memory usage
Storage costs for Redis persistence (RDB/AOF)

Consider compression when cached values exceed ~1KB.

When to Use This Backend

Use RedisBackend when you need:

Distributed caching: Share cache across multiple application instances
Persistence: Survive application restarts (with Redis RDB/AOF)
Large capacity: Store more data than fits in process memory

Consider other backends when you need:

Lowest latency: Use hitbox-moka for in-process caching
Both: Use multi-tier composition (Moka L1 + Redis L2)

Multi-Tier Composition

RedisBackend works well as an L2 cache behind a fast in-memory L1:

use hitbox::offload::OffloadManager;
use hitbox_backend::composition::Compose;
use hitbox_moka::MokaBackend;
use hitbox_redis::{RedisBackend, ConnectionMode};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Fast local cache (L1) backed by Redis (L2)
let l1 = MokaBackend::builder().max_entries(10_000).build();
let l2 = RedisBackend::builder()
    .connection(ConnectionMode::single("redis://localhost:6379/"))
    .build()?;

let offload = OffloadManager::with_defaults();
let composed = l1.compose(l2, offload);
# Ok(())
# }

hitbox-redis 0.2.0