Invalidation du cache dans KV : le problème que personne ne résout avec élégance

Phil Karlton a déclaré qu'il n'y avait que deux choses difficiles en informatique : l'invalidation du cache et la dénomination des choses. KV rend le premier encore plus difficile, car vous ne contrôlez pas le moment où l'invalidation arrive à chaque point de présence.

Supprimer une clé dans KV ne la supprime pas immédiatement du monde. La suppression est envoyée au magasin central et se propage aux PoP avec la même dynamique de cohérence éventuelle que les écritures : jusqu'à 60 secondes pour atteindre tous les points de présence. Pendant cette fenêtre, les PoP qui n'ont pas encore reçu la suppression continuent de servir l'ancienne valeur à toutes les demandes entrantes. Vous ne savez pas quels PoPs l’ont reçu et lesquels ne l’ont pas reçu. Il n’existe aucun moyen de forcer une propagation immédiate.

Cela fait de l'invalidation du cache dans KV un problème de conception et non un problème de fonctionnement. Vous ne le résolvez pas avec un bouton « invalider maintenant » : vous le résolvez en choisissant un modèle clé qui minimise l’impact du délai de propagation.

Clés versionnées : la solution la plus robuste

La norme la plus solide pour le contenu qui doit être invalidé est de maintenir une indirection explicite entre le nom logique des données et la clé physique où elles sont stockées.

Au lieu d'écrire le rendu HTML d'une page en homepage-html, puis de le supprimer lorsque le contenu change, vous l'écrivez en homepage-html-v42. Une deuxième clé, homepage-html-version, contient uniquement la chaîne v42. Le Worker lit d'abord la clé de version, construit le nom de la clé de contenu et récupère la valeur.

Lorsque le contenu change, vous écrivez le nouveau HTML en homepage-html-v43 et mettez à jour homepage-html-version en v43. L’ancienne clé n’a pas besoin d’être supprimée immédiatement : elle cesse simplement d’être référencée. Son coût de stockage continue d'exister jusqu'à ce que vous effectuiez le nettoyage, mais l'incohérence d'invalidation n'est plus un problème : tout PoP ayant reçu la mise à jour homepage-html-version recevra déjà la nouvelle clé. L'ancien contenu n'est servi qu'aux PoP qui n'ont pas encore reçu la mise à jour de la clé de version, et cela se produit dans un délai de 60 secondes, quelle que soit votre action.

Le coût de cette approche est d'une lecture supplémentaire par requête : d'abord la clé de version, puis le contenu. Dans la plupart des cas, ce coût n'a pas d'importance en termes de latence : les deux lectures sont parallèles si le Worker les effectue avec Promise.all, et toutes deux arrivent du cache PoP en moins d'une milliseconde lorsqu'elles sont chaudes.

Coordonner KV avec la purge CDN

Pour le contenu servi depuis le CDN Cloudflare (et non directement depuis le Worker), il existe une couche supplémentaire de mise en cache au-dessus du KV. Le CDN peut avoir mis en cache une réponse générée avec une ancienne valeur KV, et même si le KV a déjà la nouvelle valeur dans tous les PoP, la réponse mise en cache dans le CDN sera toujours servie jusqu'à son expiration.

La solution consiste à coordonner la mise à jour KV avec une purge CDN. L'API Cache Purge de Cloudflare vous permet d'invalider des URL spécifiques ou des balises de cache via l'API. Vous écrivez la nouvelle valeur dans le KV et, dans la même opération administrative, appelez l'API de purge pour les URL concernées. Du point de vue des clients passant par le CDN, la nouvelle réponse apparaît immédiatement après la purge, quel que soit le nombre de PoP qui propagent encore la valeur KV.

Ce modèle nécessite que vous contrôliez le processus de mise à jour du contenu et que vous ayez accès à l'API de purge. Pour les flux CMS où un éditeur publie du contenu, c'est une intégration raisonnable : le webhook de publication met à jour le KV et déclenche la purge.

Périmé pendant la revalidation avec waitUntil

Le modèle obsolète pendant la revalidation diffuse du contenu potentiellement obsolète tout en déclenchant une mise à jour en arrière-plan. Dans le contexte de Workers, ctx.waitUntil() permet d'exécuter un travail asynchrone après l'envoi de la réponse au client.

Implémentation typique : le travailleur lit la valeur KV actuelle et sert immédiatement. Parallèlement, il déclenche via ctx.waitUntil() une fonction qui vérifie si la valeur doit être mise à jour — en consultant une source par exemple — et écrit la nouvelle valeur dans le KV si nécessaire. Le client reçoit la réponse sans attendre la mise à jour. La requête suivante peut déjà recevoir la nouvelle valeur, selon le moment où la propagation se termine.

Le compromis est explicite : vous échangez une latence nulle avec le client contre une fenêtre dans laquelle un contenu obsolète peut être servi. Pour la plupart des scénarios de mise en cache de contenu, ce compromis est acceptable. Pour les données dont l’obsolescence a des conséquences opérationnelles (prix, disponibilité des stocks, autorisations d’accès), la norme n’est pas appropriée.

TTL en remplacement de l'invalidation explicite

Pour les cas où une invalidation précise n’est pas nécessaire, le TTL est le mécanisme le plus simple. KV prend en charge expirationTtl (dans quelques secondes) et expiration (horodatage Unix) définis au moment de la rédaction.

Un indicateur de fonctionnalité avec une durée de vie de 60 secondes expire automatiquement. La requête suivante après l'expiration récupérera le magasin central et renverra la valeur la plus récente – ou une valeur vide, que le Worker peut interpréter comme « drapeau désactivé ». Vous n'avez pas besoin de supprimer ou de suivre explicitement l'état.

Pour le contenu avec une fréquence de rafraîchissement prévisible, la durée de vie alignée sur le cycle de rafraîchissement élimine le besoin d’invalidation active. Un rapport généré à chaque fois peut avoir une durée de vie de 3 600 secondes. La valeur la plus ancienne possible qu'un utilisateur verra est d'environ une heure, et il s'agit d'un choix de conception et non d'un défaut de cohérence.

Ce qui ne fonctionne pas : suppression et réécriture immédiates

Un modèle qui apparaît fréquemment et ne résout pas le problème consiste à supprimer l’ancienne clé et à écrire la nouvelle dans l’ordre. Cela n’élimine pas la fenêtre d’incohérence : les deux opérations se propagent indépendamment aux PoP. Un PoP peut recevoir la suppression mais n'a pas encore reçu la nouvelle écriture, et pendant cette fenêtre, il renverra "non trouvé" pour cette clé. Selon la manière dont le Worker gère ce cas, cela peut entraîner une erreur ou un repli inattendu.

La suppression et la réécriture ont le double des opérations de propagation avec le triple des états intermédiaires possibles : ancien, non trouvé, nouveau. Les clés versionnées ou TTL sont toujours préférables.

Comment la cohérence éventuelle change la conception

Le modèle le plus sain pour travailler avec KV est d’accepter la cohérence éventuelle comme une caractéristique du système, et non comme une limitation à contourner. Cela signifie concevoir des flux dans lesquels une fenêtre d'incohérence allant jusqu'à 60 secondes est tolérable, et utiliser des outils différents lorsque ce n'est pas le cas.

Pour les données qui nécessitent une cohérence immédiate sur tous les PoP, KV n'est pas le bon outil. D1 avec des lectures dirigées vers le primaire, ou des objets durables pour un état avec accès sérialisé, couvrent les cas où le modèle de cohérence éventuelle KV ne fonctionne pas.

Une invalidation élégante dans KV ne doit pas se produire de toute urgence, car la conception du système a été conçue pour tolérer la fenêtre de propagation. Toute tentative visant à imposer une cohérence immédiate fonctionnera contre l’architecture, et non avec elle.