oxcache 0.3.0

English | 简体中文

Oxcache is a high-performance, production-grade two-level caching library for Rust, providing L1 (Moka in-memory cache) + L2 (Redis distributed cache) architecture.

✨ Key Features

• 🚀 Extreme Performance: L1 nanosecond response (P99 < 100ns), L1 millisecond response (P99 < 5ms)
• 🎯 Zero-Code Changes: Enable caching with a single #[cached] macro
• 🔄 Auto Recovery: Automatic degradation on Redis failure, WAL replay on recovery
• 🌐 Multi-Instance Sync: Pub/Sub + version-based invalidation synchronization
• ⚡ Batch Optimization: Intelligent batch writes for significantly improved throughput
• 🧪 Sync API: Synchronous get_sync / set_sync / get_or_sync API path alongside async, with no runtime required on multi_thread tokio
• 🌸 Bloom Filter: Optional BloomFilterBackend decorator filters negative queries at O(1) cost, skipping inner backend entirely
• ⏱️ Universal per-entry TTL: All backends (Moka / DashMap / Redis / Mock / Chain / Bloom) honor per-entry set(key, value, Some(ttl))
• 🛡️ Production Grade: Complete observability, health checks, chaos testing verified

📦 Quick Start

1. Add Dependency

Add oxcache to your Cargo.toml:

[dependencies]
oxcache = "0.3.0"

Note: tokio and serde are already included by default. If you need minimal dependencies, you can use oxcache = { version = "0.3.0", default-features = false } and add them manually.

Features: To use #[cached] macro, enable macros feature: oxcache = { version = "0.3.0", features = ["macros"] }

Feature Tiers

# Full features (recommended)
oxcache = { version = "0.3.0", features = ["full"] }

# Core functionality only
oxcache = { version = "0.3.0", features = ["core"] }

# Minimal - L1 cache only
oxcache = { version = "0.3.0", features = ["minimal"] }

# Custom selection
oxcache = { version = "0.3.0", features = ["core", "macros", "metrics", "bloom-filter"] }

Individual Features:

• memory - L1 cache backends (Moka + DashMap)
• redis - L2 distributed cache (Redis)
• macros - #[cached] attribute macro
• serialization - JSON serialization (serde + serde_json)
• compression - Data compression (flate2)
• metrics - OpenTelemetry metrics and observability
• batch-write - Optimized batch writing (tokio-util)
• lua-script - Lua script execution support
• cli - Command-line interface (clap)
• tracing - Structured logging support
• bloom-filter - Negative query filtering (BloomFilter + BloomFilterBackend); not in full, must be enabled explicitly

2. Configuration

Create a config.toml file:

[global]
default_ttl = 3600
health_check_interval = 30
serialization = "json"
enable_metrics = true

# Two-level cache (L1 + L2)
[services.user_cache]
cache_type = "two-level"  # "l1" | "l2" | "two-level"
ttl = 600

  [services.user_cache.l1]
  max_capacity = 10000
  ttl = 300  # L1 TTL must be <= L2 TTL
  tti = 180
  initial_capacity = 1000

  [services.user_cache.l2]
  mode = "standalone"  # "standalone" | "sentinel" | "cluster"
  connection_string = "redis://127.0.0.1:6379"

  [services.user_cache.two_level]
  write_through = true
  promote_on_hit = true
  enable_batch_write = true
  batch_size = 100
  batch_interval_ms = 50

# L1-only cache (memory only)
[services.session_cache]
cache_type = "l1"
ttl = 300

  [services.session_cache.l1]
  max_capacity = 5000
  ttl = 300
  tti = 120

# L2-only cache (Redis only)
[services.shared_cache]
cache_type = "l2"
ttl = 7200

  [services.shared_cache.l2]
  mode = "standalone"
  connection_string = "redis://127.0.0.1:6379"

2.1 Type-Safe Configuration API (Recommended)

Oxcache provides a type-safe builder API for configuration, enabling compile-time type checking and better IDE support. This approach is recommended over TOML configuration for most use cases.

Memory-Only Cache (L1)

use oxcache::config::UnifiedConfigBuilder;
use oxcache::{Cache, CacheBuilder};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug)]
struct User {
    id: u64,
    name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create type-safe configuration using builder API
    let config = UnifiedConfigBuilder::memory_only()
        .with_ttl(3600)           // Default TTL in seconds
        .with_l1_capacity(10000)  // L1 cache capacity
        .build();

    // Create cache directly from configuration
    let cache: Cache<String, User> = CacheBuilder::from_unified_config(&config)
        .build()
        .await?;

    // Use the cache
    let user = User {
        id: 1,
        name: "Alice".to_string(),
    };

    cache.set(&"user:1".to_string(), &user).await?;
    let cached: Option<User> = cache.get(&"user:1".to_string()).await?;

    println!("User: {:?}", cached);
    Ok(())
}

Tiered Cache (L1 + L2)

use oxcache::config::UnifiedConfigBuilder;
use oxcache::{Cache, CacheBuilder};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug)]
struct User {
    id: u64,
    name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create tiered cache configuration
    let config = UnifiedConfigBuilder::tiered()
        .with_ttl(7200)            // Default TTL in seconds
        .with_l1_capacity(10000)   // L1 memory cache capacity
        .with_redis_url("redis://localhost:6379")  // L2 Redis connection
        .with_redis_mode("standalone")  // Redis mode
        .build();

    // Create cache directly from configuration
    let cache: Cache<String, User> = CacheBuilder::from_unified_config(&config)
        .build()
        .await?;

    // Use the cache (writes to both L1 and L2)
    let user = User {
        id: 1,
        name: "Alice".to_string(),
    };

    cache.set(&"user:1".to_string(), &user).await?;
    let cached: Option<User> = cache.get(&"user:1".to_string()).await?;

    println!("User: {:?}", cached);
    Ok(())
}

Configuration Builder Methods

Benefits of Type-Safe API

• Compile-time validation: Configuration errors caught at compile time
• IDE support: Full autocomplete and type hints
• No runtime parsing: Eliminates TOML parsing overhead
• Better error messages: Type errors instead of configuration parse errors
• Refactoring friendly: Rename refactoring works across configuration

3. Usage

Using Macros (Recommended)

use oxcache::macros::cached;
use oxcache::{Cache, CacheBuilder};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug)]
struct User {
    id: u64,
    name: String,
}

// One-line cache enable
#[cached(service = "user_cache", ttl = 600)]
async fn get_user(id: u64) -> Result<User, String> {
    // Simulate slow database query
    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
    Ok(User {
        id,
        name: format!("User {}", id),
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize cache using Builder pattern
    let cache: Cache<String, User> = Cache::builder()
        .redis("redis://127.0.0.1:6379")
        .build()
        .await?;

    // Register cache for macro usage
    cache.register_for_macro("user_cache").await;

    // First call: execute function logic + cache result (~100ms)
    let user = get_user(1).await?;
    println!("First call: {:?}", user);

    // Second call: return directly from cache (~0.1ms)
    let cached_user = get_user(1).await?;
    println!("Cached call: {:?}", cached_user);

    Ok(())
}

Manual Client Usage

use oxcache::{Cache, CacheBuilder};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct MyData {
    field: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize cache using Builder pattern
    let cache: Cache<String, MyData> = Cache::builder()
        .redis("redis://127.0.0.1:6379")
        .build()
        .await?;

    let my_data = MyData {
        field: "value".to_string(),
    };

    // Standard operation: write to cache
    cache.set(&"key".to_string(), &my_data).await?;

    let data: Option<MyData> = cache.get(&"key".to_string()).await?;
    println!("Data: {:?}", data);

    // Delete
    cache.delete(&"key".to_string()).await?;

    Ok(())
}

🎨 Use Cases

Scenario 1: User Information Cache

#[cached(service = "user_cache", ttl = 600)]
async fn get_user_profile(user_id: u64) -> Result<UserProfile, Error> {
    database::query_user(user_id).await
}

Scenario 2: API Response Cache

#[cached(
    service = "api_cache",
    ttl = 300,
    key = "api_{endpoint}_{version}"
)]
async fn fetch_api_data(endpoint: String, version: u32) -> Result<ApiResponse, Error> {
    http_client::get(&format!("/api/{}/{}", endpoint, version)).await
}

Scenario 3: L1-Only Hot Data Cache

#[cached(service = "session_cache", cache_type = "l1", ttl = 60)]
async fn get_user_session(session_id: String) -> Result<Session, Error> {
    session_store::load(session_id).await
}

🧪 Sync API (0.3.0)

Oxcache 0.3.0 introduces a synchronous API path alongside the async API. Enable it on the builder:

use oxcache::Cache;
use serde::{Deserialize, Serialize};

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

#[tokio::main(flavor = "multi_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // sync_mode(true) makes the Cache<K,V> also hold an Arc<dyn SyncCacheBackend>
    let cache: Cache<String, User> = Cache::builder().sync_mode(true).build().await?;

    // Synchronous operations (no .await)
    cache.set_sync(&"user:1".to_string(), &User { id: 1, name: "Alice".into() })?;
    let cached = cache.get_sync(&"user:1".to_string())?;
    assert_eq!(cached, Some(User { id: 1, name: "Alice".into() }));

    // Per-entry TTL
    cache.set_with_ttl_sync(&"temp".to_string(), &User { id: 2, name: "Temp".into() }, Some(std::time::Duration::from_secs(60)))?;

    // Single-flight get_or_sync: concurrent callers share one fallback execution
    let value = cache.get_or_sync(&"user:42".to_string(), || {
        Ok(User { id: 42, name: "Bob".into() })
    })?;

    // Sync and async APIs coexist on the same Cache<K,V>
    cache.set(&"async_key".to_string(), &User { id: 99, name: "Async".into() }).await?;
    let v = cache.get_sync(&"async_key".to_string())?;
    Ok(())
}

When to use sync API:

• Blocking call sites (legacy code, FFI, sync handlers)
• Tests that don't want to thread async through every assertion
• Avoiding runtime overhead when the caller is already synchronous

Runtime notes:

• sync_mode(true) works on multi_thread tokio runtime. On current_thread runtime, Moka's sync_block_on will panic (use #[tokio::main(flavor = "multi_thread")] or call from outside a runtime).
• Without sync_mode(true), calling any *_sync method returns Err(CacheError::NotSupported).

#[cached(sync)] macro:

use oxcache::macros::cached;

#[cached(service = "user_cache", ttl = 600, sync)]
fn get_user_sync(id: u64) -> Result<User, String> {
    // Synchronous body — no async runtime required
    Ok(User { id, name: format!("User {}", id) })
}

🌸 Bloom Filter (0.3.0)

The bloom-filter feature (must be enabled explicitly; not in full) provides negative-query filtering:

[dependencies]
oxcache = { version = "0.3.0", features = ["memory", "bloom-filter"] }

use oxcache::backend::interface::{CacheReader, CacheWriter};
use oxcache::backend::MokaMemoryBackend;
use oxcache::features::bloom_filter::{BloomFilter, BloomFilterBackend};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Standalone BloomFilter type
    let bf = BloomFilter::new(10_000, 0.01);  // capacity, false-positive rate
    bf.insert("existing_key");
    assert!(bf.contains("existing_key"));    // no false negatives
    assert!(!bf.contains("missing_key"));    // may have false positives

    // 2. BloomFilterBackend decorator: wraps any CacheBackend
    let inner = MokaMemoryBackend::new();
    let backend = BloomFilterBackend::builder()
        .capacity(10_000)
        .false_positive_rate(0.01)
        .inner(inner)
        .build()?;

    // On `get`: BF says "absent" → skip inner entirely. BF says "maybe present" → query inner.
    backend.set("user:1", b"Alice".to_vec(), None).await?;
    let value = backend.get("user:1").await?;       // Some(b"Alice")
    let miss  = backend.get("user:999").await?;     // None — BF filtered, inner untouched

    Ok(())
}

Properties:

• No false negatives (inserted keys always contains == true)
• set updates both BF and inner; delete only updates inner (BF doesn't support removal)
• clear clears both; TTL passes through unchanged
• Also implements SyncCacheBackend when inner backend does

⏱️ TTL Behavior Reference (0.3.0)

All backends honor per-entry TTL since 0.3.0. Behavior summary:

Global vs per-entry TTL:

• MokaMemoryBackend::builder().ttl(Duration) sets a global TTL applied to every entry
• set(key, value, Some(ttl)) overrides the global TTL for that specific entry
• set(key, value, None) uses the global TTL (if set); otherwise the entry never expires

🏗️ Architecture

graph TD
    A[Application Code<br/>#[cached] Macro] --> B[Cache&lt;K, V&gt;<br/>Unified Cache Interface]

    B --> C[ChainCache<br/>Tiered Backend]
    B --> D[MokaMemoryBackend<br/>L1 Only]
    B --> E[RedisBackend<br/>L2 Only]

    C --> F[L1 Cache<br/>Moka]
    C --> G[L2 Cache<br/>Redis]

    D --> F
    E --> G

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#f1f8e9
    style G fill:#fdf2e9

L1: In-process high-speed cache using LRU/TinyLFU eviction strategy L2: Distributed shared cache supporting Sentinel/Cluster modes

📊 Performance Benchmarks

Test environment: M1 Pro, 16GB RAM, macOS, Redis 7.0

Note: Performance varies based on hardware, network conditions, and data size.

xychart-beta
    title "Single-thread Latency Test (P99)"
    x-axis ["L1 Cache", "L2 Cache", "Database"]
    y-axis "Latency (ms)" 0 --> 60
    bar [0.05, 3, 30]
    line [0.05, 3, 30]

xychart-beta
    title "Throughput Test (batch_size=100)"
    x-axis ["L1 Operations", "L2 Single Write", "L2 Batch Write"]
    y-axis "Ops/sec" 0 --> 600
    bar [7500, 75, 350]

Performance Summary:

• L1 Cache: 50-100ns (in-memory)
• L2 Cache: 1-5ms (Redis, localhost)
• Database: 10-50ms (typical SQL query)
• L1 Operations: 5-10M ops/sec
• L2 Single Write: 50-100K ops/sec
• L2 Batch Write: 200-500K ops/sec

🛡️ Reliability

• ✅ Single-Flight (prevent cache stampede)
• ✅ WAL (Write-Ahead Log) persistence
• ✅ Automatic degradation on Redis failure
• ✅ Graceful shutdown mechanism
• ✅ Health checks and auto-recovery

🔐 Security

Oxcache implements multiple security measures to protect against common attacks:

Input Validation

All user inputs are validated before being passed to Redis:

• Key Validation: Keys cannot be empty, exceed 512KB, or contain dangerous characters (\r, \n, \0) that could enable Redis protocol injection attacks.
• Lua Script Validation: Scripts are validated for:
  • Maximum length of 10KB
  • Maximum of 100 keys
  • Blocking dangerous commands: FLUSHALL, FLUSHDB, KEYS, SHUTDOWN, DEBUG, CONFIG, SAVE, BGSAVE, MONITOR
  • Comment and string content preprocessing to prevent bypass via comments
• SCAN Pattern Validation: Patterns are validated to prevent ReDoS attacks:
  • Maximum length of 256 characters
  • Maximum of 10 wildcard (*) characters
  • Count parameter clamped to safe range (1-1000)
• SQL/Path Traversal Detection: Redis keys are scanned for potential SQL injection and path traversal patterns

Security API (Public Functions)

For advanced use cases, you can directly use the security validation functions:

use oxcache::security::{validate_redis_key, validate_lua_script, validate_scan_pattern};

// Validate Redis keys
validate_redis_key("user:123").expect("Invalid key");

// Validate Lua scripts
validate_lua_script("return redis.call('GET', KEYS[1])", 1).expect("Invalid script");

// Validate SCAN patterns
validate_scan_pattern("user:*").expect("Invalid pattern");

Timeout Protection

Long-running operations have timeout protection:

• Lua Scripts: 30-second timeout prevents Redis blocking
• SCAN Operations: 30-second timeout prevents hanging scans

Secure Lock Values

Distributed locks use cryptographically secure UUID v4 values automatically generated by the library, eliminating the risk of lock value prediction attacks.

Connection String Redaction

Passwords in connection strings are redacted in logs by default to prevent credential leakage. Use normalize_connection_string_with_redaction() for secure logging.

Best Practices

1. Use the library's key validation - Don't bypass the validate_redis_key() function
2. Avoid custom Lua scripts - Use the built-in cache operations when possible
3. Set appropriate timeouts - Don't disable the 30-second default timeout
4. Rotate lock values - The library handles this automatically
5. Never log connection strings - Use the redaction utility for debugging

For more details, see Security Documentation.

📚 Documentation

• 📖 User Guide
• 📘 API Documentation
• 💻 Examples

🤝 Contributing

Pull Requests and Issues are welcome!

📝 Changelog

See CHANGELOG.md

📄 License

This project is licensed under MIT License. See LICENSE file.

If this project helps you, please give a ⭐ Star to show support!

Made with ❤️ by Kirky.X