pub trait CacheStore:
Sealed
+ Send
+ Sync {
type Error: From<CacheError> + Error + Send + Sync + 'static;
// Required methods
fn name(&self) -> &KeyPrefix;
fn cache_settings(&self) -> &CacheSettings;
fn get_entry<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CacheEntry<CV>>, Self::Error>> + Send
where CV: CacheValue;
fn set_entry<CV>(
&self,
key: &str,
entry: CacheEntry<CV>,
) -> impl Future<Output = Result<(), Self::Error>> + Send
where CV: CacheValue;
fn remove(
&self,
key: &str,
) -> impl Future<Output = Result<bool, Self::Error>> + Send;
fn remove_prefix(
&self,
prefix: &str,
) -> impl Future<Output = Result<usize, Self::Error>> + Send;
fn clear(&self) -> impl Future<Output = Result<(), Self::Error>> + Send;
// Provided methods
fn get<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Send
where CV: CacheValue { ... }
fn set<CV>(
&self,
key: &str,
value: CV,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<(), Self::Error>> + Send
where CV: CacheValue { ... }
fn get_or_set<CV, F, Fut, E>(
&self,
key: &str,
load: F,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<CV, E>> + Send
where CV: CacheValue,
F: FnOnce() -> Fut + Send,
Fut: Future<Output = Result<CV, E>> + Send,
E: Send { ... }
}Expand description
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.
A key is any string, such as "user:42" or &format!("user:v1:{id}"); levels are separated by
:, and remove_prefix removes whole levels. CacheKey builds a
checked one.
Since each call names its value type, the trait can’t be used as dyn CacheStore. To pick a
store at startup, such as memory in development and the hybrid in production, write the code
that uses the cache generic over C: CacheStore, or wrap the stores you use in an enum:
use serde::{Deserialize, Serialize};
use sisa_caching_core::CacheStore;
// What a cached value needs: `Clone`, and serde's two derives.
#[derive(Clone, Serialize, Deserialize)]
struct User {
id: u64,
name: String,
}
// The same code runs on the memory, Redis and hybrid stores.
struct Users<C> {
cache: C,
}
impl<C: CacheStore> Users<C> {
async fn get(&self, id: u64) -> Result<User, std::io::Error> {
self.cache
.get_or_set(&format!("user:v1:{id}"), || load_user(id), None)
.await
}
async fn forget(&self, id: u64) -> Result<bool, C::Error> {
self.cache.remove(&format!("user:v1:{id}")).await
}
}
async fn load_user(id: u64) -> Result<User, std::io::Error> {
Ok(User { id, name: "Ada".to_string() })
}Only the memory, Redis and hybrid stores implement it, so a later release can add a method
without breaking code that uses a store. The Sealed trait it needs is public only so those
crates can reach it; implementing it elsewhere isn’t supported and may break in any release.
Required Associated Types§
Sourcetype Error: From<CacheError> + Error + Send + Sync + 'static
type Error: From<CacheError> + Error + Send + Sync + 'static
What the store’s calls fail with. Every CacheError converts into it.
Required Methods§
Sourcefn cache_settings(&self) -> &CacheSettings
fn cache_settings(&self) -> &CacheSettings
The store’s TTL, refresh-ahead and lock settings. A hybrid store returns its own, which both of its layers follow.
Sourcefn get_entry<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CacheEntry<CV>>, Self::Error>> + Sendwhere
CV: CacheValue,
fn get_entry<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CacheEntry<CV>>, Self::Error>> + Sendwhere
CV: CacheValue,
The entry under key as a CV, or None when it is missing or expired. The memory store
fails with CacheError::TypeMismatch when it holds another Rust type there. The Redis
store decodes its JSON into CV, so another type whose fields fit reads it too, and JSON
that doesn’t fit is an error. The entry is as it was when looked up: it can expire while
a slow Clone of its value, or its decoding, runs.
Sourcefn set_entry<CV>(
&self,
key: &str,
entry: CacheEntry<CV>,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
fn set_entry<CV>(
&self,
key: &str,
entry: CacheEntry<CV>,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
Stores entry as it is: its creation time and TTL are kept, and it expires when the entry
does, not after this store’s default TTL. A store may hold it for less, as a hybrid store’s
local layer does for local.ttl_secs. get_entry from one store and set_entry into
another copies an entry without changing it.
Sourcefn remove(
&self,
key: &str,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
fn remove( &self, key: &str, ) -> impl Future<Output = Result<bool, Self::Error>> + Send
Removes key, and returns whether it was there.
Sourcefn remove_prefix(
&self,
prefix: &str,
) -> impl Future<Output = Result<usize, Self::Error>> + Send
fn remove_prefix( &self, prefix: &str, ) -> impl Future<Output = Result<usize, Self::Error>> + Send
Removes every key under prefix, matched by whole levels (user removes user:42, not
users:42, nor the key user itself), and returns how many. Fails with
CacheError::InvalidKey when prefix is empty or has an empty level.
It visits every key the store holds, not only those under prefix: a memory store walks
all its entries, and a Redis store runs SCAN over the whole database on each primary. A
hybrid store walks Redis once and the memory layer of every node, and reads in progress on
those nodes keep no local copy. Use remove for keys you can name.
use sisa_caching_core::CacheStore;
// `User` changed shape and its keys moved to `user:v2`: drop the old entries.
async fn drop_old_users<C: CacheStore>(cache: &C) -> Result<usize, C::Error> {
cache.remove_prefix("user:v1").await
}Provided Methods§
Sourcefn get<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Sendwhere
CV: CacheValue,
fn get<CV>(
&self,
key: &str,
) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Sendwhere
CV: CacheValue,
The value under key as a CV, or None when it is missing or expired.
Sourcefn set<CV>(
&self,
key: &str,
value: CV,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
fn set<CV>(
&self,
key: &str,
value: CV,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<(), Self::Error>> + Sendwhere
CV: CacheValue,
Stores value under key, replacing what is there. options sets this write’s TTL;
None uses the store’s default TTL. Fails when the TTL is over 365 days.
use std::time::Duration;
use sisa_caching_core::{CacheOptions, CacheStore};
async fn start_session<C: CacheStore>(cache: &C, token: &str) -> Result<(), C::Error> {
// The store's default TTL.
cache.set("settings:theme", "dark".to_string(), None).await?;
// A TTL of its own.
let fifteen_minutes = CacheOptions::with_ttl(Duration::from_secs(15 * 60));
cache.set(&format!("session:{token}"), true, fifteen_minutes).await?;
let theme = cache.get::<String>("settings:theme").await?;
assert_eq!(theme.as_deref(), Some("dark"));
Ok(())
}Sourcefn get_or_set<CV, F, Fut, E>(
&self,
key: &str,
load: F,
options: impl Into<Option<CacheOptions>> + Send,
) -> impl Future<Output = Result<CV, E>> + Send
fn get_or_set<CV, F, Fut, E>( &self, key: &str, load: F, options: impl Into<Option<CacheOptions>> + Send, ) -> impl Future<Output = Result<CV, E>> + Send
Returns the value under key, or runs load when there is none, then stores and returns
what it gives. Of the callers on this store and its clones, one per key runs load; the
others wait for it and get what it stored, or after lock_timeout_ms run load too. Other
stores, such as those in other processes, load on their own, and a write made while load
runs can be overwritten by its result. With refresh_threshold set, a value past that
share of its TTL is loaded again by one caller, while the others get the cached value; if
that load fails, its caller gets the cached value as long as the store still holds it.
use std::time::Duration;
use serde::{Deserialize, Serialize};
use sisa_caching_core::{CacheOptions, CacheStore};
#[derive(Clone, Serialize, Deserialize)]
struct User {
id: u64,
name: String,
}
#[derive(Debug)]
struct DbError;
async fn query_user(id: u64) -> Result<User, DbError> {
Ok(User { id, name: "Ada".to_string() })
}
// On a miss, a failed query comes back as it is, and nothing is cached.
async fn user<C: CacheStore>(cache: &C, id: u64) -> Result<User, DbError> {
let five_minutes = CacheOptions::with_ttl(Duration::from_secs(300));
cache
.get_or_set(&format!("user:v1:{id}"), || query_user(id), five_minutes)
.await
}When the key holds something it can’t read as CV, such as another type or JSON that no
longer fits after a field was added without #[serde(default)], it loads and stores the
loaded value over it. When a field is renamed or changes type, or a value keeps its shape
but changes meaning, bump the version in its key (user:v1 to user:v2, see
CacheKey); otherwise the old and new versions of a rolling deploy
replace each other’s entries, or misread them.
A store call that fails inside it doesn’t fail the call, since it returns the loader’s
error type: a failed read loads, and a failed store returns the loaded value without
caching it. Each failure counts in sisa.caching.errors; the first of a run logs a
warning, and the success that ends it an info line. Options over the 365-day limit fail
the store the same way.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".