{"id":36236804,"url":"https://github.com/kirky-x/oxcache","last_synced_at":"2026-01-11T06:01:31.776Z","repository":{"id":330966274,"uuid":"1123229880","full_name":"Kirky-X/oxcache","owner":"Kirky-X","description":"Oxcache is a high-performance, production grade Rust multi-level cache library that provides a two-layer caching architecture of L1 (Moka) and L2 (Redis).","archived":false,"fork":false,"pushed_at":"2025-12-31T05:46:05.000Z","size":365,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T11:09:33.938Z","etag":null,"topics":["cache","moka","redis","two-level-cache"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kirky-X.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-26T12:47:45.000Z","updated_at":"2025-12-31T05:46:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kirky-X/oxcache","commit_stats":null,"previous_names":["kirky-x/oxcache"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Kirky-X/oxcache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Foxcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Foxcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Foxcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Foxcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kirky-X","download_url":"https://codeload.github.com/Kirky-X/oxcache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Foxcache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28293188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T04:44:51.577Z","status":"ssl_error","status_checked_at":"2026-01-11T04:44:44.232Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","moka","redis","two-level-cache"],"created_at":"2026-01-11T06:01:31.044Z","updated_at":"2026-01-11T06:01:31.768Z","avatar_url":"https://github.com/Kirky-X.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🚀 Oxcache\n\n[![CI](https://github.com/Kirky-X/oxcache/actions/workflows/ci.yml/badge.svg)](https://github.com/Kirky-X/oxcache/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/oxcache.svg)](https://crates.io/crates/oxcache)\n[![Documentation](https://docs.rs/oxcache/badge.svg)](https://docs.rs/oxcache)\n[![Downloads](https://img.shields.io/crates/d/oxcache.svg)](https://crates.io/crates/oxcache)\n[![codecov](https://codecov.io/gh/Kirky-X/oxcache/branch/main/graph/badge.svg)](https://codecov.io/gh/Kirky-X/oxcache)\n[![Dependency Status](https://deps.rs/repo/github/Kirky-X/oxcache/status.svg)](https://deps.rs/repo/github/Kirky-X/oxcache)\n[![License](https://img.shields.io/crates/l/oxcache.svg)](https://github.com/Kirky-X/oxcache/blob/main/LICENSE)\n[![Rust Version](https://img.shields.io/badge/rust-1.70%2B-blue.svg)](https://www.rust-lang.org)\n\n[English](../README.md) | [简体中文](README_zh.md)\n\nOxcache is a high-performance, production-grade two-level caching library for Rust, providing L1 (Moka in-memory\ncache) + L2 (Redis distributed cache) architecture.\n\n\u003c/div\u003e\n\n## ✨ Key Features\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"20%\" align=\"center\"\u003e\n\u003cimg src=\"https://img.icons8.com/fluency/96/000000/rocket.png\" width=\"48\"\u003e\u003cbr\u003e\n\u003cb\u003eExtreme Performance\u003c/b\u003e\u003cbr\u003eL1 in nanoseconds\n\u003c/td\u003e\n\u003ctd width=\"20%\" align=\"center\"\u003e\n\u003cimg src=\"https://img.icons8.com/fluency/96/000000/magic-wand.png\" width=\"48\"\u003e\u003cbr\u003e\n\u003cb\u003eZero-Code Changes\u003c/b\u003e\u003cbr\u003eOne-line cache enable\n\u003c/td\u003e\n\u003ctd width=\"20%\" align=\"center\"\u003e\n\u003cimg src=\"https://img.icons8.com/fluency/96/000000/cloud.png\" width=\"48\"\u003e\u003cbr\u003e\n\u003cb\u003eAuto Recovery\u003c/b\u003e\u003cbr\u003eRedis fault degradation\n\u003c/td\u003e\n\u003ctd width=\"20%\" align=\"center\"\u003e\n\u003cimg src=\"https://img.icons8.com/fluency/96/000000/synchronize.png\" width=\"48\"\u003e\u003cbr\u003e\n\u003cb\u003eMulti-Instance Sync\u003c/b\u003e\u003cbr\u003eBased on Pub/Sub\n\u003c/td\u003e\n\u003ctd width=\"20%\" align=\"center\"\u003e\n\u003cimg src=\"https://img.icons8.com/fluency/96/000000/lightning.png\" width=\"48\"\u003e\u003cbr\u003e\n\u003cb\u003eBatch Optimization\u003c/b\u003e\u003cbr\u003eSmart batch writes\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\n- **🚀 Extreme Performance**: L1 nanosecond response (P99 \u003c 100ns), L1 millisecond response (P99 \u003c 5ms)\n- **🎯 Zero-Code Changes**: Enable caching with a single `#[cached]` macro\n- **🔄 Auto Recovery**: Automatic degradation on Redis failure, WAL replay on recovery\n- **🌐 Multi-Instance Sync**: Pub/Sub + version-based invalidation synchronization\n- **⚡ Batch Optimization**: Intelligent batch writes for significantly improved throughput\n- **🛡️ Production Grade**: Complete observability, health checks, chaos testing verified\n\n## 📦 Quick Start\n\n### 1. Add Dependency\n\nAdd `oxcache` to your `Cargo.toml`:\n\n```toml\n[dependencies]\noxcache = \"0.1\"\n```\n\n\u003e **Note**: `tokio` and `serde` are already included by default. If you need minimal dependencies, you can use\n`oxcache = { version = \"0.1\", default-features = false }` and add them manually.\n\n### 2. Configuration\n\nCreate a `config.toml` file:\n\n```toml\n[global]\ndefault_ttl = 3600\nhealth_check_interval = 30\nserialization = \"json\"\nenable_metrics = true\n\n[services.user_cache]\ncache_type = \"two-level\"  # \"l1\" | \"l2\" | \"two-level\"\nttl = 600\n\n  [services.user_cache.l1]\n  max_capacity = 10000\n  ttl = 300  # L1 TTL must be \u003c= L2 TTL\n  tti = 180\n  initial_capacity = 1000\n\n  [services.user_cache.l2]\n  mode = \"standalone\"  # \"standalone\" | \"sentinel\" | \"cluster\"\n  connection_string = \"redis://127.0.0.1:6379\"\n\n  [services.user_cache.two_level]\n  write_through = true\n  promote_on_hit = true\n  enable_batch_write = true\n  batch_size = 100\n  batch_interval_ms = 50\n```\n\n### 3. Usage\n\n#### Using Macros (Recommended)\n\n```rust\nuse oxcache::macros::cached;\nuse serde::{Deserialize, Serialize};\n\n#[derive(Serialize, Deserialize, Clone, Debug)]\nstruct User {\n    id: u64,\n    name: String,\n}\n\n// One-line cache enable\n#[cached(service = \"user_cache\", ttl = 600)]\nasync fn get_user(id: u64) -\u003e Result\u003cUser, String\u003e {\n    // Simulate slow database query\n    tokio::time::sleep(std::time::Duration::from_millis(100)).await;\n    Ok(User {\n        id,\n        name: format!(\"User {}\", id),\n    })\n}\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Initialize cache (from config file)\n    oxcache::init(\"config.toml\").await?;\n    \n    // First call: execute function logic + cache result (~100ms)\n    let user = get_user(1).await?;\n    println!(\"First call: {:?}\", user);\n    \n    // Second call: return directly from cache (~0.1ms)\n    let cached_user = get_user(1).await?;\n    println!(\"Cached call: {:?}\", cached_user);\n    \n    Ok(())\n}\n```\n\n#### Manual Client Usage\n\n```rust\nuse oxcache::{get_client, CacheOps};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    oxcache::init(\"config.toml\").await?;\n    \n    let client = get_client(\"user_cache\")?;\n    \n    // Standard operation: write to both L1 and L2\n    client.set(\"key\", \u0026my_data, Some(300)).await?;\n    let data: MyData = client.get(\"key\").await?.unwrap();\n    \n    // Write to L1 only (temporary data)\n    client.set_l1_only(\"temp_key\", \u0026temp_data, Some(60)).await?;\n    \n    // Write to L2 only (shared data)\n    client.set_l2_only(\"shared_key\", \u0026shared_data, Some(3600)).await?;\n    \n    // Delete\n    client.delete(\"key\").await?;\n    \n    Ok(())\n}\n```\n\n## 🎨 Use Cases\n\n### Scenario 1: User Information Cache\n\n```rust\n#[cached(service = \"user_cache\", ttl = 600)]\nasync fn get_user_profile(user_id: u64) -\u003e Result\u003cUserProfile, Error\u003e {\n    database::query_user(user_id).await\n}\n```\n\n### Scenario 2: API Response Cache\n\n```rust\n#[cached(\n    service = \"api_cache\",\n    ttl = 300,\n    key = \"api_{endpoint}_{version}\"\n)]\nasync fn fetch_api_data(endpoint: String, version: u32) -\u003e Result\u003cApiResponse, Error\u003e {\n    http_client::get(\u0026format!(\"/api/{}/{}\", endpoint, version)).await\n}\n```\n\n### Scenario 3: L1-Only Hot Data Cache\n\n```rust\n#[cached(service = \"session_cache\", cache_type = \"l1\", ttl = 60)]\nasync fn get_user_session(session_id: String) -\u003e Result\u003cSession, Error\u003e {\n    session_store::load(session_id).await\n}\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Application Code                      │\n│                  (#[cached] Macro)                       │\n└──────────────────────┬──────────────────────────────────┘\n                       │\n                       ↓\n┌─────────────────────────────────────────────────────────┐\n│                   CacheManager                           │\n│        (Service Registry + Health Monitor)               │\n└───┬─────────────────────────────────────────────────┬───┘\n    │                                                  │\n    ↓                                                  ↓\n┌──────────────┐                              ┌──────────────┐\n│ TwoLevelClient│                              │ L1OnlyClient │\n│               │                              │ L2OnlyClient │\n└───┬──────┬───┘                              └──────────────┘\n    │      │\n    ↓      ↓\n┌────────┐ ┌────────────────────────────────────────┐\n│  L1    │ │                L2                       │\n│ (Moka) │ │              (Redis)                    │\n│        │ │                                        │\n└────────┘ └────────────────────────────────────────┘\n```\n\n**L1**: In-process high-speed cache using LRU/TinyLFU eviction strategy  \n**L2**: Distributed shared cache supporting Sentinel/Cluster modes\n\n## 📊 Performance Benchmarks\n\n\u003e Test environment: M1 Pro, 16GB RAM, macOS\n\n```\nSingle-thread Latency Test (P99):\n├── L1 Cache:  ~50ns\n├── L2 Cache:  ~1ms\n└── Database:   ~10ms\n\nThroughput Test (batch_size=100):\n├── Single Write:  ~10K ops/s\n└── Batch Write:   ~50K ops/s\n```\n\n## 🛡️ Reliability\n\n- ✅ Single-Flight (prevent cache stampede)\n- ✅ WAL (Write-Ahead Log) persistence\n- ✅ Automatic degradation on Redis failure\n- ✅ Graceful shutdown mechanism\n- ✅ Health checks and auto-recovery\n\n## 📚 Documentation\n\n- [📖 User Guide](docs/USER_GUIDE.md)\n- [📘 API Documentation](https://docs.rs/oxcache)\n- [💻 Examples](../examples/)\n\n## 🤝 Contributing\n\nPull Requests and Issues are welcome!\n\n## 📝 Changelog\n\nSee [CHANGELOG.md](../CHANGELOG.md)\n\n## 📄 License\n\nThis project is licensed under MIT License. See [LICENSE](../LICENSE) file.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project helps you, please give a ⭐ Star to show support!**\n\nMade with ❤️ by oxcache Team\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirky-x%2Foxcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkirky-x%2Foxcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirky-x%2Foxcache/lists"}