Expand description
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 |
redis | RedisCacheStore, and the redis crate it is built on |
hybrid | HybridCacheStore; 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 |
use sisa_caching::{CacheStore, InMemoryCacheStore};
// It drops expired entries every 60 seconds by itself.
let cache = InMemoryCacheStore::new("app")?;
let name = cache
.get_or_set("user:v1:42", async || Ok::<_, std::io::Error>("Ada".to_string()), None)
.await?;
assert_eq!(name, "Ada");A hybrid on one Redis server, which applies the other nodes’ invalidations by itself:
use sisa_caching::{CacheStore, HybridCacheSettings, HybridCacheStore};
let settings = HybridCacheSettings::default();
let cache = HybridCacheStore::connect("app", "redis://127.0.0.1:6379", &settings).await?;
cache.set("user:v1:42", "Ada".to_string(), None).await?;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. An application that uses one store can depend on the core crate and that store’s
crate instead. CacheStore is sealed, so these stores are its only implementations; the Redis
store runs on any RedisConnection.
Re-exports§
pub use redis;redis
Structs§
- Backplane
Worker Settings hybrid - How a hybrid store’s backplane worker waits before subscribing again, and how it tells that
invalidations were lost while it stayed subscribed, as
HybridCacheSettings::worker. - Cache
Entry - A value with its creation time and TTL. Every store, memory, Redis and hybrid, reads and writes
this one type, so
get_entryfrom one store andset_entryinto another copies an entry as it is. Its creation time and TTL can’t be changed; build a new entry instead. - Cache
Key - Joins a prefix and a key into
prefix:key, such asuser:42. Stores take any&stras a key, and aCacheKeyderefs to one, so this is only a checked way to write one: the prefix has no empty level and the key has no:. - Cache
Options - Per-call options for a write.
- Cache
Settings - Settings every store has. Each store’s settings flatten them, so in a config file they sit
beside the store’s own:
{ "default_ttl_secs": 300, "max_entries": 10000 }. - Hybrid
Cache Settings hybrid - Everything a hybrid store is configured with, as one config section. The shared settings sit at the top, beside the sections for the two layers and the worker, and an unknown field fails:
- Hybrid
Cache Store hybrid - An in-memory layer in front of a distributed store, with invalidations carried by a
RedisBackplane. One store holds values of every type:get::<User>andset(&key, user, None)name the type per call. - InMemory
Cache Settings memory - Settings for an
InMemoryCacheStore: the shared ones and the memory store’s own. In a config file both sit side by side, and an unknown field fails, so a misspelled setting can’t silently keep its default: - InMemory
Cache Store memory - An in-process store. One store holds values of every type;
get::<User>andset(&key, user, None)name the type per call, and a read with the wrong type fails withCacheError::TypeMismatch. - KeyPrefix
- A store name or key prefix: one or more levels joined by
:, none empty, such asapportenant:user. - Local
Settings hybrid - The in-memory layer of a hybrid store: how long its copies live, and the memory store’s own
settings beside it. Its copies always expire: after
ttl_secs, or when the entry they copy does, if that is sooner. - Memory
Settings memory - The memory store’s own settings, apart from the shared ones. A hybrid store’s local layer
takes these too, under
local. - NodeId
hybrid - Names one node, so a node can skip the invalidations that it sent itself.
- Redis
Backplane hybrid - A backplane over Redis pub/sub. Each hybrid store has its own channel,
<store>:backplane, such ascatalog:backplane, so a node gets only its own stores’ messages. Publishing shares one connection. Each subscription opens its own connection, on RESP3, and holds up to 8,192 messages its worker hasn’t read. The connection keeps reading, so Redis’s limit on slow subscribers never applies: a worker that falls further behind loses its subscription instead, so the node clears its local layer and subscribes again, rather than messages piling up or getting lost without a sign. - Redis
Cache Settings redis - Settings for a
RedisCacheStore: the shared ones and the Redis store’s own. In a config file both sit side by side, and an unknown field fails, so a misspelled setting can’t silently keep its default: - Redis
Cache Store redis - A store on a Redis-family server. One store holds values of every type as JSON;
get::<User>andset(&key, user, None)name the type per call. Reads decode the JSON into the type you name, and nothing in Redis records a Rust type, so other languages can share the keys. - Redis
Settings redis - The Redis store’s own settings, apart from the shared ones. A hybrid store’s Redis layer takes
these too, under
distributed. - Sentinel
Connection redis - A connection to the primary that Redis Sentinel names, which follows a failover:
- System
Clock - The real clock, and the default for every store.
Enums§
- Cache
Error - Errors every store can return.
- Hybrid
Cache Error hybrid - Errors from the hybrid store, by the layer they came from.
- Redis
Cache Error redis - Errors from Redis-backed cache operations: the shared
CacheErrors, plus Redis and JSON failures.
Traits§
- Cache
Store - A named store that holds values of any
CacheValuetype under string keys. The type is named on each call, so one store serves every type an application caches. - Cache
Value - Any value a store can hold. One store holds values of many types; the type is named on each
call (
get::<User>,set(&key, user, None)), not on the store. - Clock
- Where stores read the time. Tests swap in a clock they can move. A store holds its clock by value and is generic over its type, so each read is a direct call. Each clone of a store holds a clone of its clock, so a clock whose time can move shares that time between its clones.
- Redis
Connection redis - A connection a
RedisCacheStoreruns on. Keys go wherever the connection routes them; onlyremove_prefixandclearneed more, becauseSCANsees one node’s keys. They scan each node fromprimaries.
Functions§
- connection_
config redis - The settings of every
ConnectionManagerthis crate builds. While the server is down, a call fails at once instead of waiting through redis-rs’s default six reconnect attempts, about 9 s, and the next call connects again. A cache that is down then costs a caller milliseconds, andget_or_setgoes straight to its loader. Timeouts stay redis-rs’s: 500 ms for a reply, 1 s for a connection attempt.
Type Aliases§
- Redis
Hybrid Cache Store hybrid - A hybrid store on Redis.