Digging deeper
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.
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):
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.
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())
}