sisa-caching 0.1.0

Composable caching for Rust: an in-memory store, a Redis-family store, and a hybrid that keeps local copies coherent across nodes
Documentation
//! Caching for Rust services: an in-memory store, a store on Redis, Valkey, Dragonfly or Garnet,
//! and a hybrid that keeps a local copy on each node and drops it when another node writes. Every
//! store has the same calls (`get`, `set`, `get_or_set`, `remove`, `remove_prefix` and `clear`)
//! through the [`CacheStore`] trait, so switching stores changes one line.
//!
//! No store is on by default; turn on the ones you use:
//!
//! | Feature | Adds |
//! | --- | --- |
//! | `memory` | `InMemoryCacheStore` and its `PurgeWorker` |
//! | `redis` | `RedisCacheStore`, and the `redis` crate it is built on |
//! | `hybrid` | `HybridCacheStore` and its `BackplaneWorker`; turns on `memory` and `redis` |
//! | `tls-rustls` | `rediss://` URLs through rustls; turns on `redis` |
//! | `tls-native-tls` | `rediss://` URLs through the system's TLS library; turns on `redis` |
//!
//! ```
//! # #[cfg(feature = "memory")]
//! # #[tokio::main(flavor = "current_thread")]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! use sisa_caching::{CacheStore, InMemoryCacheStore, PurgeWorker, WorkerHost};
//!
//! let cache = InMemoryCacheStore::new("app")?;
//!
//! // Stores start no task of their own: this one drops expired entries nobody reads again,
//! // every 60 seconds. Keep the host as long as the cache.
//! let workers = WorkerHost::new();
//! workers.register(PurgeWorker::new(cache.clone()));
//!
//! let name = cache
//!     .get_or_set("user:v1:42", || async { Ok::<_, std::io::Error>("Ada".to_string()) }, None)
//!     .await?;
//!
//! assert_eq!(name, "Ada");
//! # Ok(())
//! # }
//! # #[cfg(not(feature = "memory"))]
//! # fn main() {}
//! ```
//!
//! A hybrid on one Redis server, with the two workers it needs:
//!
//! ```no_run
//! # #[cfg(feature = "hybrid")]
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use sisa_caching::{
//!     BackplaneWorker, CacheStore, HybridCacheSettings, HybridCacheStore, PurgeWorker, WorkerHost,
//! };
//!
//! let settings = HybridCacheSettings::default();
//! let cache = HybridCacheStore::connect("app", "redis://127.0.0.1:6379", &settings).await?;
//!
//! // Keep the host alive as long as the cache; dropping it stops the workers.
//! let workers = WorkerHost::new();
//! workers.register(BackplaneWorker::new(&cache).with_settings(settings.worker.clone()));
//! workers.register(PurgeWorker::new(cache.local_store().clone()));
//!
//! cache.set("user:v1:42", "Ada".to_string(), None).await?;
//! # Ok(())
//! # }
//! ```
//!
//! Each part is also its own crate (`sisa-caching-core`, `-memory`, `-redis`, `-hybrid`), whose
//! docs cover the details: key and entry formats, Cluster and Sentinel, the backplane, and the
//! metrics. Depend on one of those directly to implement a store or a backplane of your own.

#![forbid(unsafe_code)]
#![warn(missing_debug_implementations)]

pub use sisa_caching_core::{
    CacheEntry, CacheError, CacheKey, CacheOptions, CacheSettings, CacheStore, CacheValue,
    KeyPrefix, WorkerHost, WorkerService,
    cache::PurgeableStore,
    clock::{Clock, SystemClock},
    worker::CancellationToken,
};

#[cfg(feature = "memory")]
pub use sisa_caching_memory::{InMemoryCacheSettings, InMemoryCacheStore, PurgeWorker};

#[cfg(feature = "redis")]
pub use sisa_caching_redis::{
    RedisCacheError, RedisCacheSettings, RedisCacheStore, RedisConnection, SentinelConnection,
    connection_config, redis,
};

#[cfg(feature = "hybrid")]
pub use sisa_caching_hybrid::{
    BackplaneWorker, HybridCacheError, HybridCacheSettings, HybridCacheStore, RedisBackplane,
    RedisHybridCacheStore,
    settings::{BackplaneWorkerSettings, RedisBackplaneSettings},
};