zoocache 2026.2.25

Cache that invalidates when your data changes, not when a timer expires. Rust-powered semantic invalidation for Python.

Zoocache is a high-performance caching library with a Rust core, designed for applications where data consistency and read performance are critical.

📖 Read the User Guide

---

✨ Key Features

• 🚀 Rust-Powered Performance: Core logic implemented in Rust for ultra-low latency and safe concurrency.
• 🧠 Semantic Invalidation: Use a PrefixTrie for hierarchical invalidation. Clear "user:*" to invalidate all keys related to a specific user instantly.
• 🛡️ Causal Consistency: Built-in support for Hybrid Logical Clocks (HLC) ensures consistency even in distributed systems.
• ⚡ Anti-Avalanche (SingleFlight): Protects your backend from "thundering herd" effects by coalescing concurrent identical requests.
• 📦 Smart Serialization: Transparently handles MsgPack and LZ4 compression for maximum throughput and minimum storage.
• 🔄 Self-Healing Distributed Cache: Automatic synchronization via Redis Bus with robust error recovery.
• 🛡️ Hardened Safety: Strict tag validation and mutex-poisoning protection to ensure zero-crash operations.
• 📊 Observability & Telemetry: Built-in support for Logs, Prometheus, and OpenTelemetry to monitor cache performance.

---

🚀 Performance

Zoocache is continuously benchmarked to ensure zero performance regressions. We track micro-latency, scaling with dependencies, and storage overhead.

Performance Context

The benchmark results reflect ZooCache's specific architectural choices:

• Rust Core: Implementing the core logic in Rust reduces the processing time spent on internal cache management and synchronization compared to pure Python implementations.
• Trie-based Invalidation: Instead of matching and deleting individual keys, ZooCache uses a PrefixTrie to manage dependencies. Invalidation is performed by updating versions in the trie, which remains efficient even as the number of cached items grows.
• Pub/Sub Bus: Using Redis Pub/Sub for the invalidation bus enables low-latency propagation of invalidation signals across multiple nodes, typically completing in under 1ms.

Note: Benchmark scale: 5,000 operations. Redis is running on localhost (loopback) to eliminate network latency interference and focus on internal engine overhead. ZooCache maintains O(1) tagging overhead and scales linearly. Latency values represent the end-to-end operation time including storage overhead.

Optional CLI & TUI

Zoocache includes an optional CLI for real-time monitoring and cache management. It can be installed using the cli extra:

uv add "zoocache[cli]"

---

⚖️ Comparison

Feature	🐾 Zoocache	🔴 Redis (Raw)	🐶 Dogpile	diskcache
Invalidation	🧠 Semantic (Trie)	🔧 Manual	🔧 Manual	⏳ TTL
Consistency	🛡️ Causal (HLC)	❌ Eventual	❌ No	❌ No
Anti-Avalanche	✅ Native	❌ No	✅ Yes (Locks)	❌ No
Performance	🚀 Very High	🏎️ High	🐢 Medium	🐢 Medium

---

⚡ Quick Start

Installation

Using uv (recommended):

uv add zoocache

Using pip:

pip install zoocache

Simple Usage

from zoocache import cacheable, invalidate

@cacheable(deps=lambda user_id: [f"user:{user_id}"])
def get_user(user_id: int):
    return db.fetch_user(user_id)

def update_user(user_id: int, data: dict):
    db.save(user_id, data)
    invalidate(f"user:{user_id}")  # All cached 'get_user' calls for this ID die instantly

Complex Dependencies

from zoocache import cacheable, add_deps

@cacheable
def get_product_page(product_id: int, store_id: int):
    # This page stays cached as long as none of these change:
    add_deps([
        f"prod:{product_id}",
        f"store:{store_id}:inv",
        f"region:eu:pricing",
        "campaign:blackfriday"
    ])
    return render_page(product_id, store_id)

# Any of these will invalidate the page:
# invalidate("prod:42")
# invalidate("store:1:inv")
# invalidate("region:eu") -> Clears ALL prices in that region

Terminal User Interface (TUI)

Zoocache comes with a built-in TUI to monitor metrics, view the caching trie, and run real-time commands such as cache invalidation.

uv run zoocache cli

---

📖 Documentation

Explore the deep dives into Zoocache's architecture and features:

• Architecture Overview - How the Rust core and Python wrapper interact.
• Hierarchical Invalidation - Deep dive into the PrefixTrie and O(D) invalidation.
• Serialization Pipeline - Efficient data handling with MsgPack and LZ4.
• Concurrency & SingleFlight - Shielding your database from traffic spikes.
• Distributed Consistency - HLC, Redis Bus, and robust consistency models.
• FastAPI Integration - Out-of-box caching for FastAPI endpoints.
• Litestar Integration - Out-of-box caching for Litestar endpoints.
• Django Integration - Using ZooCache with the Django ORM.
• Django User Guide - Detailed guide for Django users.
• Django Serializers Auto - Automatic caching for Django REST Framework.
• Reliability & Edge Cases - Fail-fast mechanisms and memory management.

Architectural Decisions (ADR)

• ADR 0001: Prefix-Trie Invalidation
• ADR 0002: Rust Core Python Wrapper
• ADR 0003: HLC Distributed Consistency
• ADR 0004: Serialization Strategy
• ADR 0005: SingleFlight Pattern
• ADR 0006: Trie Performance Optimizations
• ADR 0007: Zero-Bridge Serialization
• ADR 0008: Redis Bus Connection Pooling
• ADR 0009: Robust Sync and Error Handling

---

❓ When to Use Zoocache

✅ Good Fit

• Complex Data Relationships: Use dependencies to invalidate groups of data.
• High Read/Write Ratio: Where TTL causes stale data or unnecessary cache churn.
• Distributed Systems: Native Redis Pub/Sub invalidation and HLC consistency.
• Strict Consistency: When users must see updates immediately (e.g., pricing, inventory).

❌ Not Ideal

• Pure Time-Based Expiry: If you only need simple TTL for session tokens.
• Simple Key-Value: If you don't need dependencies or hierarchical invalidation.
• Minimal Dependencies: For small, local-only apps where basic lru_cache suffices.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.