sisa_caching/lib.rs
1//! Caching for Rust services: an in-memory store, a store on Redis, Valkey, Dragonfly or Garnet,
2//! and a hybrid that keeps a local copy on each node and drops it when another node writes. Every
3//! store has the same calls (`get`, `set`, `get_or_set`, `remove`, `remove_prefix` and `clear`)
4//! through the [`CacheStore`] trait, so switching stores changes one line.
5//!
6//! No store is on by default; turn on the ones you use:
7//!
8//! | Feature | Adds |
9//! | --- | --- |
10//! | `memory` | `InMemoryCacheStore` |
11//! | `redis` | `RedisCacheStore`, and the `redis` crate it is built on |
12//! | `hybrid` | `HybridCacheStore`; turns on `memory` and `redis` |
13//! | `tls-rustls` | `rediss://` URLs through rustls; turns on `redis` |
14//! | `tls-native-tls` | `rediss://` URLs through the system's TLS library; turns on `redis` |
15//!
16//! ```
17//! # #[cfg(feature = "memory")]
18//! # #[tokio::main(flavor = "current_thread")]
19//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
20//! use sisa_caching::{CacheStore, InMemoryCacheStore};
21//!
22//! // It drops expired entries every 60 seconds by itself.
23//! let cache = InMemoryCacheStore::new("app")?;
24//!
25//! let name = cache
26//! .get_or_set("user:v1:42", async || Ok::<_, std::io::Error>("Ada".to_string()), None)
27//! .await?;
28//!
29//! assert_eq!(name, "Ada");
30//! # Ok(())
31//! # }
32//! # #[cfg(not(feature = "memory"))]
33//! # fn main() {}
34//! ```
35//!
36//! A hybrid on one Redis server, which applies the other nodes' invalidations by itself:
37//!
38//! ```no_run
39//! # #[cfg(feature = "hybrid")]
40//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
41//! use sisa_caching::{CacheStore, HybridCacheSettings, HybridCacheStore};
42//!
43//! let settings = HybridCacheSettings::default();
44//! let cache = HybridCacheStore::connect("app", "redis://127.0.0.1:6379", &settings).await?;
45//!
46//! cache.set("user:v1:42", "Ada".to_string(), None).await?;
47//! # Ok(())
48//! # }
49//! ```
50//!
51//! Each part is also its own crate (`sisa-caching-core`, `-memory`, `-redis`, `-hybrid`), whose
52//! docs cover the details: key and entry formats, Cluster and Sentinel, the backplane, and the
53//! metrics. An application that uses one store can depend on the core crate and that store's
54//! crate instead. `CacheStore` is sealed, so these stores are its only implementations; the Redis
55//! store runs on any `RedisConnection`.
56
57#![cfg_attr(docsrs, feature(doc_cfg))]
58#![forbid(unsafe_code)]
59#![warn(missing_debug_implementations)]
60#![warn(missing_docs)]
61
62pub use sisa_caching_core::{
63 CacheEntry, CacheError, CacheKey, CacheOptions, CacheSettings, CacheStore, CacheValue,
64 KeyPrefix,
65 clock::{Clock, SystemClock},
66};
67
68#[cfg(feature = "memory")]
69pub use sisa_caching_memory::{InMemoryCacheSettings, InMemoryCacheStore, MemorySettings};
70
71#[cfg(feature = "redis")]
72pub use sisa_caching_redis::{
73 RedisCacheError, RedisCacheSettings, RedisCacheStore, RedisConnection, RedisSettings,
74 SentinelConnection, connection_config, redis,
75};
76
77#[cfg(feature = "hybrid")]
78pub use sisa_caching_hybrid::{
79 BackplaneWorkerSettings, HybridCacheError, HybridCacheSettings, HybridCacheStore,
80 LocalSettings, NodeId, RedisBackplane, RedisHybridCacheStore,
81};