Skip to main content

Crate sisa_caching

Crate sisa_caching 

Source
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:

FeatureAdds
memoryInMemoryCacheStore
redisRedisCacheStore, and the redis crate it is built on
hybridHybridCacheStore; turns on memory and redis
tls-rustlsrediss:// URLs through rustls; turns on redis
tls-native-tlsrediss:// 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§

BackplaneWorkerSettingshybrid
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.
CacheEntry
A value with its creation time and TTL. Every store, memory, Redis and hybrid, reads and writes this one type, so get_entry from one store and set_entry into another copies an entry as it is. Its creation time and TTL can’t be changed; build a new entry instead.
CacheKey
Joins a prefix and a key into prefix:key, such as user:42. Stores take any &str as a key, and a CacheKey derefs to one, so this is only a checked way to write one: the prefix has no empty level and the key has no :.
CacheOptions
Per-call options for a write.
CacheSettings
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 }.
HybridCacheSettingshybrid
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:
HybridCacheStorehybrid
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> and set(&key, user, None) name the type per call.
InMemoryCacheSettingsmemory
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:
InMemoryCacheStorememory
An in-process store. One store holds values of every type; get::<User> and set(&key, user, None) name the type per call, and a read with the wrong type fails with CacheError::TypeMismatch.
KeyPrefix
A store name or key prefix: one or more levels joined by :, none empty, such as app or tenant:user.
LocalSettingshybrid
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.
MemorySettingsmemory
The memory store’s own settings, apart from the shared ones. A hybrid store’s local layer takes these too, under local.
NodeIdhybrid
Names one node, so a node can skip the invalidations that it sent itself.
RedisBackplanehybrid
A backplane over Redis pub/sub. Each hybrid store has its own channel, <store>:backplane, such as catalog: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.
RedisCacheSettingsredis
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:
RedisCacheStoreredis
A store on a Redis-family server. One store holds values of every type as JSON; get::<User> and set(&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.
RedisSettingsredis
The Redis store’s own settings, apart from the shared ones. A hybrid store’s Redis layer takes these too, under distributed.
SentinelConnectionredis
A connection to the primary that Redis Sentinel names, which follows a failover:
SystemClock
The real clock, and the default for every store.

Enums§

CacheError
Errors every store can return.
HybridCacheErrorhybrid
Errors from the hybrid store, by the layer they came from.
RedisCacheErrorredis
Errors from Redis-backed cache operations: the shared CacheErrors, plus Redis and JSON failures.

Traits§

CacheStore
A named store that holds values of any CacheValue type under string keys. The type is named on each call, so one store serves every type an application caches.
CacheValue
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.
RedisConnectionredis
A connection a RedisCacheStore runs on. Keys go wherever the connection routes them; only remove_prefix and clear need more, because SCAN sees one node’s keys. They scan each node from primaries.

Functions§

connection_configredis
The settings of every ConnectionManager this 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, and get_or_set goes straight to its loader. Timeouts stay redis-rs’s: 500 ms for a reply, 1 s for a connection attempt.

Type Aliases§

RedisHybridCacheStorehybrid
A hybrid store on Redis.