Crate hitbox_backend 

hitbox-backend

Backend abstraction layer for the Hitbox caching framework.

This crate provides the core traits and utilities for implementing cache backends. It defines how cached data is stored, retrieved, serialized, and compressed.

Overview

The crate is organized around several key concepts:

• Backend - Low-level dyn-compatible trait for raw byte storage operations (read/write/remove)
• CacheBackend - High-level trait with typed operations that handle serialization
• Format - Serialization format abstraction (JSON, Bincode, RON, Rkyv)
• Compressor - Compression abstraction (Passthrough, Gzip, Zstd)
• CompositionBackend - Multi-tier caching (L1/L2)

Implementing a Backend

To implement your own backend, implement the Backend trait:

use std::collections::HashMap;
use std::sync::RwLock;
use hitbox_backend::{Backend, BackendResult, DeleteStatus};
use hitbox_core::{BackendLabel, CacheKey, CacheValue, Raw};
use async_trait::async_trait;

struct InMemoryBackend {
    store: RwLock<HashMap<CacheKey, CacheValue<Raw>>>,
}

#[async_trait]
impl Backend for InMemoryBackend {
    async fn read(&self, key: &CacheKey) -> BackendResult<Option<CacheValue<Raw>>> {
        Ok(self.store.read().unwrap().get(key).cloned())
    }

    async fn write(&self, key: &CacheKey, value: CacheValue<Raw>) -> BackendResult<()> {
        self.store.write().unwrap().insert(key.clone(), value);
        Ok(())
    }

    async fn remove(&self, key: &CacheKey) -> BackendResult<DeleteStatus> {
        match self.store.write().unwrap().remove(key) {
            Some(_) => Ok(DeleteStatus::Deleted(1)),
            None => Ok(DeleteStatus::Missing),
        }
    }

    fn label(&self) -> BackendLabel {
        BackendLabel::new_static("in-memory")
    }

    // Optional: override defaults for value_format, key_format, compressor
}

Once you implement Backend, you get CacheBackend for free via blanket implementation. This provides typed get, set, and delete operations with automatic serialization.

Feature Flags

• gzip - Enable Gzip compression via GzipCompressor
• zstd - Enable Zstd compression via ZstdCompressor
• metrics - Enable observability metrics for backend operations
• rkyv_format - Enable zero-copy Rkyv serialization via RkyvFormat

Serialization Formats

Format	Speed	Size	Human-readable
BincodeFormat	Fast	Compact	No
JsonFormat	Slow	Large	Partial*
RonFormat	Medium	Medium	Yes
RkyvFormat	Fastest	Compact	No

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

Compression Options

Compressor	Ratio	Speed
PassthroughCompressor	None	Fastest
GzipCompressor	Good	Medium
ZstdCompressor	Best	Fast

Multi-Tier Caching

Use CompositionBackend to combine backends into L1/L2/L3 hierarchies:

use hitbox_backend::composition::Compose;

// Fast local cache (L1) with distributed cache fallback (L2)
let backend = moka.compose(redis, offload);

See the composition module for details on read/write/refill policies.

Re-exports

pub use backend::Backend;

pub use backend::BackendResult;

pub use backend::CacheBackend;

pub use backend::DeleteStatus;

pub use backend::SyncBackend;

pub use backend::UnsyncBackend;

pub use composition::Compose;

pub use composition::CompositionBackend;

pub use compressor::GzipCompressor;gzip

pub use compressor::ZstdCompressor;zstd

pub use compressor::CompressionError;

pub use compressor::Compressor;

pub use compressor::PassthroughCompressor;

pub use error::BackendError;

pub use format::RkyvFormat;rkyv_format

pub use key::CacheKeyFormat;

Modules

backend

Core backend traits for cache storage implementations.

composition

Multi-tier caching by combining two backends.

compressor

Compression strategies for cached values.

context

Cache operation context.

error

Error types for backend operations.

format

Serialization formats for cached values.

key

Cache key serialization formats.