Skip to main content

CacheStore

Trait CacheStore 

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

Source

type Error: From<CacheError> + Error + Send + Sync + 'static

What the store’s calls fail with. Every CacheError converts into it.

Required Methods§

Source

fn name(&self) -> &KeyPrefix

The store’s name, written in front of every key it stores.

Source

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.

Source

fn get_entry<CV>( &self, key: &str, ) -> impl Future<Output = Result<Option<CacheEntry<CV>>, Self::Error>> + Send
where 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.

Source

fn set_entry<CV>( &self, key: &str, entry: CacheEntry<CV>, ) -> impl Future<Output = Result<(), Self::Error>> + Send
where 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.

Source

fn remove( &self, key: &str, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

Removes key, and returns whether it was there.

Source

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

fn clear(&self) -> impl Future<Output = Result<(), Self::Error>> + Send

Removes every key in this store, and nothing outside it.

Provided Methods§

Source

fn get<CV>( &self, key: &str, ) -> impl Future<Output = Result<Option<CV>, Self::Error>> + Send
where CV: CacheValue,

The value under key as a CV, or None when it is missing or expired.

Source

fn set<CV>( &self, key: &str, value: CV, options: impl Into<Option<CacheOptions>> + Send, ) -> impl Future<Output = Result<(), Self::Error>> + Send
where 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(())
}
Source

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,

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".

Implementors§