Smeltery
Get started

Digging deeper

v0.1

Cache

On this page

smeltery::cache::Cache is the app's cache: a handler argument (or app.cache(), or ctx.cache() in Watchfire agents and jobs) on the default store, CACHE_STORE. Values are any Serialize / Deserialize type, stored as JSON.

rust
use std::time::Duration;
use smeltery::prelude::*;

async fn dashboard(cache: Cache) -> Result<String> {
    let total: u64 = cache
        .remember("posts.total", Duration::from_secs(300), || async { Ok(128) })
        .await?;
    cache.put("last.visit", "now", Duration::from_secs(60)).await?;
    let hits = cache.increment("hits", 1).await?;
    let first = cache.add("welcomed", &true, Duration::from_secs(3600)).await?;
    Ok(format!("{total} posts, {hits} hits, first visit: {first}"))
}

async fn import(cache: Cache) -> Result<&'static str> {
    let lock = cache.lock("import", Duration::from_secs(120));
    if !lock.block(Duration::from_secs(5)).await? {
        return Ok("an import is running");
    }
    // … the import …
    lock.release().await?;
    Ok("imported")
}
Method Does
get::<T>(key) the value, or None when missing or expired (an error when it does not deserialize into T or is larger than CACHE_MAX_VALUE_BYTES; the error never quotes the value)
put(key, &value, ttl) / forever(key, &value) store for ttl (zero removes the key) / until removed
add(key, &value, ttl) store only when the key holds no live value; true when stored (atomic)
remember(key, ttl, \|\| async { … }) / remember_forever the value, or compute, store and return it (a value of another shape is computed again)
has, forget, pull check, remove, read and remove
increment(key, by) / decrement(key, by) atomic counter; a missing key starts at 0, an entry keeps its time to live
flush() / flush_all() remove every entry and lock under this cache's prefix except Watchfire's leases and schedule claims (names starting with watchfire:) / everything under the prefix (memcached: both empty its servers)
store("redis")? / with_prefix(…) the same app's other store / another key prefix
lock(name, ttl) an atomic lock: get(), block(timeout), refresh() (the owner holds it for ttl again, from now), release() (only by its owner), force_release(), owner(); restore_lock(name, owner, ttl) rebuilds it elsewhere
Store Where entries live
database (default) the cache table (key, value, expiration in Unix ms) and cache_locks; new apps have the migration create_cache_tables (smeltery::cache::migrations::{up, down}). Keys of any length work: one longer than 191 characters is stored as its first 120 characters and its SHA-256. On MySQL keys compare byte for byte (utf8mb4_bin), so a and A are two keys. Expired rows are deleted on about one write in a hundred
redis a Redis server (REDIS_URL; feature redis of smeltery): SET NX PX for add and locks, INCRBY, a compare-and-delete script to release a lock, SCAN + UNLINK to flush a prefix; rediss:// uses rustls
memcached memcached servers (MEMCACHED_SERVERS; feature memcached): native add / incr / decr, lock release by cas; counters stop at 0 and expiry counts whole seconds
file storage/framework/cache/<2 hex>/<sha256 of the key> (CACHE_PATH; on Unix files 0600, folders 0700); writes go through a temp file and a rename, add / counters / locks hold a per-key lock file, so processes on one machine share it; flush removes only files of that shape
memory this process's memory, up to CACHE_MEMORY_CAPACITY entries (moka); shared by every app in the process, not between processes
array the memory of one app; TestApp uses it (TEST_CACHE_STORE picks another)
null nothing: reads miss, add answers false, increment answers its argument, every lock is granted

Redis is the recommended store in production: one server shared by every process and machine, with native atomic operations and locks. Memcached is the second choice; its client is synchronous and runs on blocking threads. Calls to the database, Redis and memcached stores time out after CACHE_TIMEOUT seconds. CACHE_PREFIX keeps apps that share a store apart. Locks on the database, Redis and memcached stores exclude every process using the store, e.g. serve and work running the same job; locks on the file store exclude the processes of one machine (or of a disk they share). The database and file stores remove expired entries on about one write in a hundred. smeltery cache:clear [store] empties a store from the command line and keeps the leases and schedule claims Watchfire holds there, so no singleton agent starts in a second process and no tick runs twice. cache:clear --all removes those too; the processes take their agents again within WATCHFIRE_LEASE_TTL (see "Several processes"), and meanwhile a singleton agent can run in two processes and a tick of the current minute can run again. Memcached cannot keep some keys while it flushes, so cache:clear memcached asks for --all. Memcached sends everything unencrypted: run it on the app's machine or a private network.

An app whose cache tables were created on MySQL before mysql_statements existed adds a migration that runs them (byte-for-byte keys, MEDIUMTEXT values):

rust
use smeltery::Result;
use smeltery::db::Backend;
use smeltery::db::migration::{Migration, Schema};

pub struct CacheKeysBinary;

impl Migration for CacheKeysBinary {
    fn name(&self) -> &'static str {
        "2026_10_05_000000_cache_keys_binary"
    }

    async fn up(&self, schema: &Schema) -> Result<()> {
        if schema.backend() == Backend::MySql {
            for sql in smeltery::cache::migrations::mysql_statements("cache") {
                schema.raw(&sql).await?;
            }
        }
        Ok(())
    }

    async fn down(&self, _schema: &Schema) -> Result<()> {
        Ok(())
    }
}

Rate limiting#

smeltery::cache::RateLimiter counts hits per key in fixed windows in the app's cache store, the engine of throttle:. RateLimiter::new(name, max, window) allows max hits per key per window (a window under a second counts as one second; max 0 refuses every hit); limiters with different names count apart. limiter.hit(&app, key).await? counts one hit and answers RateLimit::Allowed { remaining } or RateLimit::Limited { retry_after } (seconds until the window ends; .allowed() tells which), one atomic add + increment, so parallel hits never get more than max through. A cache error is returned, and the caller refuses what it guards. limiter.clear(&app, key).await? forgets the key's hits in the current window. limiter.peek(&app, key).await? reads the key's state without counting a hit (Allowed { remaining } or Limited { retry_after }): a read only, so parallel callers may all see Allowed; it refuses a blocked key early, and the work itself is guarded by hit. With CACHE_STORE=null the counts live in the app's process memory. Limiters with the same name, max and window share their counts in every case.

rust
use std::sync::LazyLock;
use std::time::Duration;
use smeltery::cache::RateLimiter;
use smeltery::prelude::*;

static CODES: LazyLock<RateLimiter> =
    LazyLock::new(|| RateLimiter::new("codes", 5, Duration::from_secs(300)));

async fn check_code(app: &App, user_id: i64) -> Result<bool> {
    Ok(CODES.hit(app, &format!("user:{user_id}")).await?.allowed())
}

↑↓ moveEnter openEsc close