Rustango docs
← Guides

Mise en cache

La mise en cache stocke le résultat d'un travail coûteux — une requête lourde, un fragment rendu, un appel d'API tierce — afin que la requête suivante l'obtienne instantanément au lieu de le recalculer. Rustango vous donne un unique trait Cache avec des backends interchangeables (in-memory, Redis, base de données), un helper de calcul-au-miss (get_or_set), et des helpers JSON typés. Changez de backend sans toucher à un seul site d'appel : les appels restent identiques, seule la configuration change.

Caching in Rustango: get_or_set checks the cache, runs the factory only on a miss, stores the result with a TTL, and serves hits instantly; the same Cache trait backs InMemory, Redis, and DB

Un terme vous est inconnu ? cache, TTL, clé, backend — voir le glossaire.

Source : rustango::cache (Cache, InMemoryCache, NullCache, get_or_set, get_json, set_json, BoxedCache, from_settings) — derrière la feature cache (activée par défaut). RedisCache requiert la feature cache-redis (désactivée par défaut).

Version exécutable : chaque extrait est copié depuis cache_doc.rs (cargo test -p rustango --test cache_doc) ; le backend base de données est éprouvé en dogfooding sur SQLite par cache_db_backend_sqlite_live.rs.

Table des matières


Étape 1 — Choisir un backend

Chaque backend implémente le même trait Cache, donc votre code est identique quel que soit celui que vous choisissez. Le code applicatif détient un BoxedCache (Arc<dyn Cache>) et ne nomme jamais le type concret :

use rustango::cache::{BoxedCache, InMemoryCache};
use std::sync::Arc;

let cache: BoxedCache = Arc::new(InMemoryCache::new());
BackendFeature[cache] backendÀ utiliser pour
InMemoryCachecachememory (défaut)dev, tests, processus unique (HashMap par processus + TTL)
RedisCachecache-redisredisproduction ; partagé entre réplicas
DatabaseCachecachedb / databaseproduction sans Redis ; une table rustango_cache
FileCachecachefileun fichier par clé sous file_cache_dir ; partagé seulement si le répertoire l'est
NullCachecachenull / nonedésactiver la mise en cache (chaque lecture rate) — pratique en tests

Il n'y a pas de valeur postgres — le backend base de données est db ou database. Un commentaire de doc de CacheSettings affirmait le contraire autrefois, et une valeur non reconnue vous donne un cache en mémoire avec un avertissement.

Il n'y a pas de valeur postgres : le backend base de données est db ou database. Les valeurs sont en minuscules. Une valeur inconnue ou mal casée (Redis, une faute de frappe), ou file sans file_cache_dir, est refusée : from_settings panique au démarrage et from_settings_async renvoie l'erreur. Un substitut par processus casserait ce que garantit un cache partagé.

FileCache balaie un seizième de son répertoire à la recherche d'entrées expirées toutes les 16 écritures. Appelez FileCache::purge_expired() de façon planifiée pour tout balayer. Sous Unix, les nouveaux répertoires sont créés en 0700 et les entrées en 0600.


Étape 2 — get / set / delete

Le cœur du trait est quatre méthodes async. set prend un TTL optionnel (None = pas d'expiration) ; get retourne Option<String> (None sur un miss) :

use rustango::cache::{Cache, InMemoryCache};

let cache = InMemoryCache::new();

assert_eq!(cache.get("greeting").await?, None);     // miss
cache.set("greeting", "hello", None).await?;        // store, no expiry
assert_eq!(cache.get("greeting").await?.as_deref(), Some("hello"));
assert!(cache.exists("greeting").await?);

cache.delete("greeting").await?;                    // gone

Il existe aussi des variantes par lots — get_many / set_many / delete_many.


Étape 3 — get_or_set (cache-aside)

C'est celle que vous utiliserez le plus. get_or_set retourne la valeur en cache, ou — sur un miss — exécute votre factory, stocke le résultat avec un TTL, et le retourne. La factory ne s'exécute que sur un miss :

use rustango::cache::get_or_set;
use std::time::Duration;

let stats: HomeStats = get_or_set(
    &*cache,                       // &dyn Cache
    "home:stats",
    || async { compute_home_stats(&pool).await },   // runs only on a miss
    Some(Duration::from_secs(60)),                   // cache for 60s
).await?;

Le test sous-jacent appelle get_or_set deux fois pour la même clé et affirme que la factory s'est exécutée exactement une fois — le second appel est servi depuis le cache.

Invalidez à l'écriture. Le cache-aside signifie des données périmées jusqu'à ce que le TTL expire. Pour des données qui changent, faites aussi delete(key) quand vous les écrivez — p. ex. depuis un signal post_save que vous envoyez après l'enregistrement (l'enregistrement ne l'envoie pas) — pour que la lecture suivante recalcule.


Valeurs JSON typées

get_json / set_json sérialisent n'importe quel type Serialize/Deserialize en JSON, de sorte que vous mettez en cache des structs et des listes, pas seulement des chaînes :

use rustango::cache::{get_json, set_json};

#[derive(serde::Serialize, serde::Deserialize)]
struct Profile { id: i64, name: String }

set_json(&*cache, "profile:7", &profile, None).await?;
let back: Option<Profile> = get_json(&*cache, "profile:7").await?;   // None on a miss

(get_or_set les utilise en interne, c'est pourquoi son type de valeur doit être Serialize + Deserialize.)


TTL et expiration

Passez une Duration à set (ou get_or_set) et l'entrée disparaît après elle. Vérifié : une entrée de 50 ms est lisible immédiatement et disparue après 80 ms.

cache.set("flash", "x", Some(Duration::from_millis(50))).await?;
// ...50ms later...
assert_eq!(cache.get("flash").await?, None);   // expired

InMemoryCache::with_default_ttl(d) définit un TTL par défaut appliqué lorsque vous passez None.

Un TTL est une borne supérieure, pas une garantie

InMemoryCache est borné en taille par défaut — 256 Mio ou 100 000 entrées, selon ce qui est atteint en premier — avec une éviction LRU approximative. Un afflux de clés uniques ne peut donc pas faire croître le processus sans limite, mais cela signifie aussi qu'une entrée peut disparaître avant l'expiration de son TTL si elle est la moins récemment utilisée au moment où le budget est atteint. L'éviction supprime d'abord les entrées déjà expirées, puis les moins récemment utilisées, jusqu'à passer 10 % sous les deux budgets. Les entrées écrites avec set_forever (feature flags) sont hors budget et jamais évincées tant qu'elles restent dans leurs propres plafonds — 16 Mio ou 10 000 entrées (.with_max_pinned_bytes(..) / .with_max_pinned_entries(..)). Au-delà, les nouvelles entrées set_forever sont stockées comme des entrées ordinaires, évinçables, et un avertissement est journalisé une fois.

Traitez donc une lecture de cache comme « peut être absente » même à l'intérieur du TTL. C'est vrai de tout backend de cache, mais ici la cause est compréhensible et réglable :

InMemoryCache::new()
    .with_max_bytes(512 * 1024 * 1024)   // relever le budget
    .with_max_entries(0)                 // 0 = illimité (comportement d'avant le bornage)

Le TTL lui-même est appliqué paresseusement, à la lecture — il n'y a pas de thread d'éviction en arrière-plan, donc une entrée expirée occupe encore sa place jusqu'à ce que quelque chose la demande ou que l'éviction l'atteigne.


Changer de backend

Parce que tout repose sur le trait Cache, passer de l'in-memory à Redis est un changement d'une ligne au démarrage — habituellement piloté par la config afin qu'il diffère selon l'environnement :

// Build the cache from `[cache]` settings. `from_settings_async` is the one
// to reach for — it can build the backends that need to connect.
let cache: BoxedCache = rustango::cache::from_settings_async(&settings.cache).await?;
backendfrom_settings (synchrone)from_settings_async
memory, null, file✓✓
redispanique — non constructible de façon synchrone✓
dbpanique — exige un &Pool à l'exécutionerreur ; construisez-le là où est le pool

Le résolveur synchrone panique plutôt que de substituer un backend. Il avertissait auparavant et renvoyait un cache en mémoire, qui n'est pas un cache partagé dégradé : c'est un autre cache. Un cache par processus multiplie la limite de CacheRateLimitLayer par le nombre de réplicas et empêche verify_single_use d'échouer en fermeture, si bien que le même lien de réinitialisation fonctionne une fois par réplica. Les deux sont documentés comme fonctionnant parce que le cache est partagé, et un avertissement au démarrage n'atteint pas la personne qui débogue cela une semaine plus tard.

db ne peut pas venir de [cache] du tout, car DatabaseCache a besoin d'un pool que les réglages ne transportent pas :

let cache = DatabaseCache::new(pool.clone(), "rustango_cache");
cache.ensure_table().await?;
let boxed: BoxedCache = std::sync::Arc::new(cache);

En production, pointez-le vers Redis (partagé entre tous vos réplicas) :

use rustango::cache::RedisCache;   // needs the `cache-redis` feature
let cache: BoxedCache = std::sync::Arc::new(RedisCache::new("redis://localhost").await?);

Les mêmes appels get / set / get_or_set — seul le constructeur a changé.


La mise en cache en multi-tenancy

Cache est un magasin plat indexé par &str, ce qui en multi-tenancy fait de la clé naturelle la clé qui fuit : un handler — ou pire une tâche d'arrière-plan, qui n'a aucun tenant ambiant où puiser — écrit "stats:monthly" pour un tenant et tous les autres le relisent.

Prenez la vue du tenant avec CacheScope::for_tenant(..).app() (un ScopedCache en interne) pour que l'espace de noms soit appliqué à votre place et que le site d'appel ne puisse pas l'oublier :

use rustango::cache::CacheScope;

// From the Org the resolver already produced:
let tenant = TenantSlug::of(&t.org).expect("a registry org");
let cache = CacheScope::for_tenant(shared.clone(), &tenant).app();

cache.set("stats:monthly", &json, ttl).await?;   // stored as tenant:#org:7:acme:app:stats:monthly
cache.get("stats:monthly").await?;               // reads only acme's entry
cache.clear().await?;                            // drops ONLY acme's entries

La vue est elle-même un Cache, elle se glisse donc partout où un BoxedCache est attendu — cache_page, cache_fragment, les rate limiters, DistributedLock. Elle transmet au backend interne avec les clés remappées plutôt que de réimplémenter quoi que ce soit, si bien que les primitives natives (Redis INCRBY, SET NX) gardent leur atomicité. get_many / set_many / delete_many sont aussi transmis, mais aucun backend fourni ne les regroupe encore : chaque clé coûte un aller-retour.

Compteurs atomiques et verrous. Cache::incr est derrière le rate limiting et le verrouillage par compte ; Cache::add (set-if-absent) est derrière DistributedLock. Cache::add est atomique sur les trois — RedisCache (SET NX), InMemoryCache (qui garde son verrou pendant le read-modify-write) et DatabaseCache, qui effectue le test-and-set sous des verrous de ligne, de sorte qu'une course se résout en exactement un gagnant. Cache::incr est atomique sur les trois aussi : DatabaseCache le fait en un seul upsert. FileCache fait les deux sous un verrou par entrée, valable sur un seul hôte. Un DistributedLock ou un compteur exact entre réplicas fonctionne donc avec Redis ou la base de données. Chaque backend compte sur toute la plage i64 ; un dépassement est une erreur et laisse le compteur inchangé. Une valeur stockée ne compte que sous la forme exacte écrite par incr ("7", "-3") ; "+7", "007", " 5" ou "abc" valent 0 partout. Une valeur texte contenant un caractère NUL est refusée par tous les backends ; stockez ces données avec set_bytes.

Deux choses à savoir :

C'est un espace de noms, pas une frontièreTout vit encore dans un seul backend, et du code détenant le cache non cadré peut lire n'importe quelle clé. L'idée est que le chemin ergonomique soit le chemin correct.
clear() a besoin d'énumérer les clésIl passe par Cache::delete_prefix, et tous les backends intégrés l'implémentent : InMemoryCache filtre sa map, DatabaseCache émet DELETE … LIKE 'prefix%' avec %, _ et le caractère d'échappement eux-mêmes échappés, RedisCache utilise SCAN+MATCH avec les métacaractères glob échappés, et FileCache parcourt son répertoire et compare la clé stockée dans chaque entrée. Un backend qui ne l'implémente pas renvoie désormais une erreur plutôt qu'un repli. DatabaseCache stocke les clés de plus de 255 octets hachées et compare un préfixe de plus de 190 octets sur ses 190 premiers octets seulement : il peut supprimer des clés en trop, jamais en moins.

Le Cache::clear() non cadré reste global au processus : utilisez la vue cadrée dès que c'est le changement d'un seul tenant qui a déclenché l'invalidation.

Les clés de tenant sont tenant:#org:<id>:<slug>:<area>:<rest>, avec une zone pour les clés de l'app, les verrous, l'idempotence, les pages, les limites de débit KeyBy::Tenant, les sessions et les overrides de flags. Le throttle de login, le verrouillage de compte et le cache de clés MCP gardent leur propre format et leur propre purge. Un clear() du cache d'app du tenant ne supprime que la zone app : il ne libère donc jamais le verrou d'un job en cours.

Le slug d'un tenant purgé peut être réutilisé par un nouveau tenant. Pour que purge-tenant supprime les clés de l'ancien tenant, appelez rustango::tenancy::decommission::clear_on_purge(cache) au démarrage pour chaque cache qui les contient. La purge y supprime toutes les zones (CacheScope::for_tenant(cache, &tenant).purge() fait de même à la main).


Mettre en cache des pages entières

CachePageLayer::new(cache) (dans rustango::cache_page) stocke les réponses GET dans n'importe quel BoxedCache ; .timeout(dur) fixe leur durée (60 s par défaut). Il est sûr par défaut :

  • Une requête avec Authorization, Cookie ou X-Api-Key n'est ni servie depuis le cache ni stockée dedans. Nommez d'autres en-têtes d'identifiants (un en-tête de jeton personnalisé) avec .credential_headers(["x-my-token"]). .cache_authenticated(true) désactive cela, seulement pour une route dont la page est la même pour chaque appelant.
  • Une réponse avec Set-Cookie, ou Cache-Control: private, no-cache ou no-store, n'est jamais mise en cache.
  • .vary_on([...]) met des en-têtes de requête dans la clé.
  • Par défaut la query brute est dans la clé : chaque query distincte crée son entrée, et ?x=<aléatoire> peut remplir le cache. .query_keys(["page", "q"]) ne garde que ces paramètres, triés ; .ignore_query() retire la query.
  • .key_prefix(..) donne à chaque couche son propre espace de clés (par défaut rustango.cache_page). .cache_query(true) met aussi en cache les requêtes QUERY, avec un condensé du corps (jusqu'à 1 Mio) dans la clé. .tenant_agnostic(true) met en cache sans locataire résolu, seulement pour une page identique pour tous les locataires.

Pour retirer une page après une écriture, appelez layer.invalidate(&[PageKey::new(path, host)]).await? sur un clone de la couche (en multi-tenancy ajoutez .tenant(&slug) à la clé, le TenantSlug de la requête, par exemple via RequestTenant::tenant()). Cela purge chaque variante en cache de ce chemin : toute chaîne de requête, toute valeur vary_on, GET et QUERY confondus. Cela passe par un compteur de génération par chemin, donc chaque GET en cache lit une petite clé de cache de plus.

En multi-tenancy, montez la couche à l'intérieur de la couche tenancy ; voir Middleware.


Référence

Trait Cache : get · set(key, value, ttl) · set_forever · delete · exists / has_key · clear · delete_prefix · incr / decr · add (si absent) · touch (nouveau TTL) · get_bytes / set_bytes · get_many / set_many / delete_many · get_or(key, default).

Helpers libres : get_or_set(cache, key, factory, ttl) · get_json / set_json · from_settings(&CacheSettings) · from_settings_async(&CacheSettings).

Entretien : DatabaseCache::purge_expired() et FileCache::purge_expired() suppriment les entrées expirées ; appelez-les à intervalle régulier. DatabaseCache supprime aussi un lot de lignes expirées toutes les 256 écritures (.purge_every(n), 0 le désactive). FileCache garde au plus 100 000 entrées et 1 Gio (.max_entries(n), .max_bytes(n), ou file_cache_max_entries / file_cache_max_bytes dans [cache] ; 0 lève une limite) et retire les plus anciennes d'abord.

Ce qui est bâti sur le cache : les sessions côté serveur, la limitation de débit distribuée (CacheRateLimitLayer), les clés d'idempotence, et les feature flags prennent tous un BoxedCache — de sorte qu'une seule instance Redis les adosse tous.


Voir aussi

  • Tâches d'arrière-plan — l'autre moitié pour garder les requêtes rapides (différer le travail au lieu de mettre en cache son résultat).
  • Sessions — un stockage côté serveur bâti sur Cache.
  • Middleware — CacheRateLimitLayer partage un compteur entre réplicas via le cache.
  • Cookbook de l'ORM — invalider les lectures en cache depuis un signal post_save.