sisa-caching-memory 0.1.1

The in-process local store of Sisa Caching, with TTLs and an optional entry limit
Documentation
sisa-caching-memory-0.1.1 has been yanked.

sisa-caching-rs

CI codecov crates.io docs.rs MSRV License: MIT

Async caching for Rust with one API over three stores: an in-memory cache, a Redis-family cache, and a hybrid of the two that keeps every node's local copy coherent.

Which store

Feature Store Use it when
memory InMemoryCacheStore One process. Fastest; TTLs, an entry limit with LRU eviction, optional shards.
redis RedisCacheStore Several processes share the cache. Redis, Valkey, Dragonfly or Garnet: one primary with or without replicas, a Redis Cluster, or Sentinel. Other languages can read and write the same keys.
hybrid HybridCacheStore Several processes, and reads must be local-fast. A memory layer per node in front of Redis, kept coherent by pub/sub invalidation.

Everything comes from one crate, sisa-caching. No store is on by default, so name the one you use; tls-rustls or tls-native-tls adds rediss:// URLs. Each part is also its own crate (core, memory, redis, hybrid), for implementing a store or a backplane of your own.

Every store has the same calls: get, set, get_or_set, remove, remove_prefix and clear, plus get_entry and set_entry for a value with its creation time and TTL. One store holds values of every type, named per call, so an application creates one store, and moving to another store doesn't touch its call sites. The crate docs cover settings and behavior in full.

Quick start

[dependencies]
sisa-caching = { version = "0.1", features = ["memory"] }   # or "redis", or "hybrid"

In memory:

use sisa_caching::{CacheStore, InMemoryCacheStore, PurgeWorker, WorkerHost};

let cache = InMemoryCacheStore::new("app")?;

// 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 user: User = cache.get_or_set(&format!("user:v1:{id}"), || load_user(id), None).await?;
cache.remove_prefix("user").await?;

On Redis (rediss:// with the tls-rustls or tls-native-tls feature):

use sisa_caching::RedisCacheStore;

let cache = RedisCacheStore::connect("app", "redis://127.0.0.1:6379").await?;

Hybrid, with the workers that apply other nodes' invalidations and drop expired local copies:

use sisa_caching::{BackplaneWorker, HybridCacheSettings, HybridCacheStore, PurgeWorker, WorkerHost};

let settings: HybridCacheSettings = load_config_section("cache")?;
let cache = HybridCacheStore::connect("app", redis_url, &settings).await?;

let workers = WorkerHost::new();
workers.register(BackplaneWorker::new(&cache).with_settings(settings.worker.clone()));
workers.register(PurgeWorker::new(cache.local_store().clone()));

A node serves a stale local copy for at most the local max_ttl_secs, 60 seconds by default, if an invalidation never reaches it.

Compatibility

Tested in CI against Redis 7.4, Redis 8, Valkey 8, Dragonfly 2 and Garnet 2, each as one primary, a three-primary cluster, and a primary and replica behind Sentinel through a failover, except Sentinel on Garnet, which has none. docs/03-compatibility.md says how to connect to each.

Observability

Stores trace through tracing and count hits, misses, loads and evictions through the OpenTelemetry metrics API, under sisa.caching.*. A hybrid write and the invalidations it causes on other nodes share one trace. docs/04-observability.md lists every metric and span; the examples show the setup.

Examples

Three axum services serve the same user API from examples/users-api, each on a different store: axum-memory, axum-redis and axum-hybrid. Each caches a scalar (GET /users/count), an object (GET /users/{id}) and a list (GET /users). The Redis and hybrid ones need a server at REDIS_URL (default redis://127.0.0.1:6379).

cargo run -p axum-memory

# Two hybrid instances: a write on one is seen by the other.
PORT=3000 cargo run -p axum-hybrid
PORT=3001 cargo run -p axum-hybrid
curl localhost:3001/users/1
curl -X PUT localhost:3000/users/1 -H 'content-type: application/json' -d '{"name":"Ada L."}'
curl localhost:3001/users/1

They push traces, metrics and logs over OTLP/HTTP to OTEL_EXPORTER_OTLP_ENDPOINT (default http://localhost:4318) and still run without a collector. To print what they send:

docker run --network host otel/opentelemetry-collector \
  --config 'yaml:receivers: {otlp: {protocols: {http: {endpoint: 0.0.0.0:4318}}}}' \
  --config 'yaml:exporters: {debug: {verbosity: detailed}}' \
  --config 'yaml:service: {pipelines: {traces: {receivers: [otlp], exporters: [debug]}, metrics: {receivers: [otlp], exporters: [debug]}, logs: {receivers: [otlp], exporters: [debug]}}}'

Benchmarks

Each release records its benchmarks on its release page: reads and writes on every store, each compared with the previous release on the same machine, and Criterion's full report. docs/05-benchmarks.md explains what each one measures and how to run them.

More

  • Docs: an overview, then architecture, flows, compatibility, observability and benchmarks, in reading order.
  • Roadmap and changelog.
  • Contributing: building, testing and conventions.
  • Security: reporting a vulnerability.

Rust 1.89 or newer. MIT licensed.