oxcache 0.1.3

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
• 🛡️ Production Grade: Complete observability, health checks, chaos testing verified

📦 Quick Start

1. Add Dependency

Add oxcache to your Cargo.toml:

[dependencies]
oxcache = "0.1.2"

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

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

Feature Tiers

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

# Core functionality (L1 + L2 cache)
oxcache = { version = "0.1.2", features = ["core"] }

# Minimal (L1 cache only)
oxcache = { version = "0.1.2", features = ["minimal"] }

# Custom selection
oxcache = { version = "0.1.2", features = ["core", "macros", "metrics"] }

Available Features

Advanced Features (included in full):

• macros - #[cached] attribute macro
• batch-write - Optimized batch writing
• wal-recovery - Write-ahead log for durability
• bloom-filter - Cache penetration protection
• rate-limiting - DoS protection
• database - Database integration
• cli - Command-line interface
• full-metrics - OpenTelemetry integration

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"

3. Usage

Using Macros (Recommended)

use oxcache::macros::cached;
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 (from config file)
    oxcache::init("config.toml").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::{get_client, CacheOps};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    oxcache::init("config.toml").await?;
    
    let client = get_client("user_cache")?;
    
    // Standard operation: write to both L1 and L2
    client.set("key", &my_data, Some(300)).await?;
    let data: MyData = client.get("key").await?.unwrap();
    
    // Write to L1 only (temporary data)
    client.set_l1_only("temp_key", &temp_data, Some(60)).await?;
    
    // Write to L2 only (shared data)
    client.set_l2_only("shared_key", &shared_data, Some(3600)).await?;
    
    // Delete
    client.delete("key").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
}

🏗️ Architecture

graph TD
    A[Application Code<br/>#[cached] Macro] --> B[Cache Manager<br/>Service Registry + Health Monitor]
    
    B --> C[TwoLevelClient]
    B --> D[L1OnlyClient]
    B --> E[L2OnlyClient]
    
    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

📚 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