Cache-Control

Les directives pour la mise en cache suivent les règles suivantes :

• Elles sont insensibles à la casse. Toutefois, l'utilisation de minuscules est recommandée, car certaines implémentations ne reconnaissent pas les directives en majuscules.
• Plusieurs directives sont séparées entre elles par des virgules.
• Certaines directives ont un argument optionnel.

Le tableau qui suit indique les directives standard pour Cache-Control :

Voir le tableau de compatibilité pour leur prise en charge respective. Les agents utilisateur qui ne reconnaissent pas une directive doivent l'ignorer.

Cette section définit les termes utilisés dans ce document, certains provenant de la spécification.

Cache (HTTP)

Une implémentation qui contient les requêtes et les réponses afin de les réutiliser pour les requêtes suivantes. Il peut s'agit d'un cache partagé ou d'un cache privé.

Cache partagé

Un cache qui existe entre le serveur d'origine et les clients (par exemple un proxy ou un CDN). Il stocke une seule réponse pour la réutiliser avec plusieurs utilisatrices et utilisateurs (les équipes de développement devraient donc éviter de stocker du contenu personnalisé dans un cache partagé).

Cache privé

Un cache qui existe au niveau du client. On parle également de cache local ou de cache du navigateur. Il peut stocker et réutiliser du contenu personnalisé pour une personne.

Stockage de la réponse

Stocker une réponse dans les caches lorsqu'elle peut être mise en cache. Toutefois, la réponse mise en cache n'est pas nécessairement réutilisée telle quelle (la plupart du temps, mettre en cache signifie stocker une réponse).

Réutilisation des réponses

Réutiliser des réponses mises en cache pour les requêtes suivantes.

Revalidation de la réponse

Demander au serveur d'origine si la réponse stockée est toujours fraîche. Généralement, la revalidation est réalisée avec une requête conditionnelle.

Réponse fraîche

Indique que la réponse est fraîche. Cela signifie en général que la réponse peut être utilisée pour les requêtes suivantes, selon les directives de la requête.

Réponse périmée

Indique que la réponse est périmée. Cela signifie en général que la réponse ne peut être réutilisée telle quelle. Le stockage du cache ne doit pas nécessairement retirer immédiatement des réponses périmées, car une revalidation pourrait modifier la réponse et la faire devenir fraîche à nouveau.

Âge

Le temps écoulé depuis la génération de la réponse. Il s'agit d'un critère pour déterminer si une réponse est fraîche ou périmée.

Cette section indique les directives qui jouent un rôle pour la mise en cache, tant pour les réponses que pour les requêtes.

max-age

La directive de réponse max-age=N indique que la réponse reste fraîche jusqu'à N secondes après la génération de la réponse.

Cache-Control: max-age=604800

Cela indique que les caches peuvent stocker cette réponse et la réutiliser pour les requêtes suivantes tant qu'elle est fraîche.

On notera que max-age ne correspond pas au temps écoulé depuis que la réponse a été reçue, il s'agit du temps écoulé depuis que la réponse a été générée sur le serveur d'origine. Ainsi, si les autres caches situés sur la route réseau empruntée par la réponse stockent la réponse pendant 100 secondes (en l'indiquant avec l'en-tête de réponse Age), le cache du navigateur déduira 100 secondes de la durée de fraîcheur.

Cache-Control: max-age=604800
Age: 100

s-maxage

La directive de réponse s-maxage indique également la durée pendant laquelle la réponse est fraîche (de façon analogue à max-age), mais s'applique spécifiquement aux caches partagés. Ceux-ci ignoreront max-age si s-maxage est présente.

Cache-Control: s-maxage=604800

no-cache

La directive de réponse no-cache indique que la réponse peut être stockée en cache, mais qu'elle doit être validée avec le serveur d'origine avant chaque réutilisation, même si le cache est déconnecté du serveur d'origine.

Cache-Control: no-cache

Si vous souhaitez que les caches vérifient leur contenu à chaque mise à jour tout en réutilisant du contenu stocké, no-cache est la directive à utiliser.

On notera que no-cache ne signifie pas « ne pas mettre en cache ». no-cache permet aux caches de stocker une réponse, mais impose une revalidation avant toute réutilisation. Si vous souhaitez effectivement ne pas stocker de données pour ne pas avoir de cache du tout, il faudra utiliser la directive no-store.

must-revalidate

La directive de réponse must-revalidate indique que la réponse peut être stockée dans les caches et peut être réutilisée tant qu'elle est fraîche. Si la réponse devient périmée, elle doit être revalidée avec le serveur d'origine avant de pouvoir être réutilisée.

On utilise généralement must-revalidate avec max-age.

Cache-Control: max-age=604800, must-revalidate

HTTP permet aux caches de réutiliser des réponses périmées lorsqu'ils sont déconnectés du serveur d'origine. must-revalidate permet d'éviter ce fonctionnement, soit la réponse enregistrée est revalidée auprès du serveur d'origine, soit une réponse 504 (Gateway Timeout) est générée.

proxy-revalidate

La directive de réponse proxy-revalidate est équivalente à must-revalidate, mais concerne uniquement les caches partagés.

no-store

La directive de réponse no-store indique qu'aucun cache (partagé ou privé) ne doit stocker la réponse.

Cache-Control: no-store

private

La directive de réponse private indique que la réponse peut uniquement être enregistrée dans un cache privé (c'est-à-dire le cache local des navigateurs).

Cache-Control: private

La directive private devrait être ajoutée pour le contenu personnalisé, notamment pour les réponses reçues après une authentification et pour les sessions gérées avec des cookies.

Si private est oubliée pour une réponse avec du contenu personnalisé, cette réponse pourra être enregistrée dans un cache partagé et finir par être réutilisée pour plusieurs personnes, causant ainsi une fuite d'informations personnelles.

public

La directive de réponse public indique que la réponse peut être enregistrée dans un cache partagé. Les réponses pour les requêtes contenant l'en-tête Authorization ne doivent jamais être enregistrées dans un cache partagé. Toutefois, si la directive public est présente, de telles réponses pourront être enregistrées dans un cache partagé.

Cache-Control: public

En général, lorsque les pages utilisent une authentification simple (Basic Auth) ou par empreinte (Digest Auth), le navigateur envoie des requêtes avec l'en-tête Authorization. Cela signifie par essence que la réponse dépend d'un contrôle d'accès, limité aux personnes qui disposent de comptes adéquats, et qu'elle ne peut pas être mise en cache, même si la réponse utilise la directive max-age.

La directive public peut être utilisée afin de lever cette restriction.

Cache-Control: public, max-age=604800

On notera que s-maxage ou must-revalidate lèvent également cette restriction.

Si une requête n'utilise pas l'en-tête Authorization, ou si s-maxage ou must-revalidate sont déjà utilisés pour la réponse, il n'est pas nécessaire d'utiliser public.

must-understand

La directive de réponse must-understand indique qu'un cache doit uniquement stocker la réponse s'il comprend les prérequis à la mise en cache selon le code de statut.

must-understand devrait être utilisée en association avec no-store, qui permet d'avoir un comportement proche si la première directive n'est pas prise en charge.

Cache-Control: must-understand, no-store

Si un cache ne prend pas en charge must-understand, celle-ci sera ignorée. Si no-store est également présente, la réponse n'est pas enregistrée.

Si un cache prend en charge must-understand, il stocke la réponse avec une compréhension des prérequis de mise en cache selon son code de statut.

no-transform

Certains intermédiaires transforment du contenu pour différentes raisons. Par exemple, certains convertissent des images afin de réduire leur taille de transfert. Dans certains cas, il peut s'agir d'un comportement qu'on souhaite éviter.

no-transform indique à l'intermédiaire (qu'il s'agisse d'un cache ou non) qu'il ne faut pas transformer le contenu de la réponse.

Google Web Light est un exemple d'un tel intermédiaire. Il convertit les images afin de minimiser les données stockées en cache ou transmises sur une connexion lente et prend en charge no-transform comme moyen d'éviter cette transformation.

immutable

La directive de réponse immutable indique que la réponse ne sera pas mise à jour tant qu'elle est fraîche.

Cache-Control: public, max-age=604800, immutable

Une bonne pratique pour les ressources statiques consiste à inclure des versions/empreintes dans leurs URL et de ne jamais modifier ces ressources, mais, lorsque c'est nécessaire, de mettre à jour ces ressources avec de nouvelles versions utilisant un nouveau numéro de version/une nouvelle empreinte, afin que les URL soient différentes. C'est ce qu'on appelle en anglais une stratégie de cache-busting (peut-être « casse-cache » en français).

<script src=https://example.com/react.0.0.0.js></script>

Lorsqu'on recharge une page dans le navigateur, ce dernier enverra des requêtes conditionnelles pour la validation auprès du serveur d'origine. Toutefois, il n'est pas nécessaire de revalider ce type de ressources statiques, même lorsqu'on recharge une page, car elles ne sont jamais modifiées. immutable indique au cache que la réponse est immuable tant qu'elle est fraîche et évite ces requêtes conditionnelles superflues envers le serveur.

Lorsqu'on utilise une stratégie de casse-cache pour des ressources auxquelles on applique une valeur élevée de max-age, on peut également utiliser immutable pour éviter une revalidation.

stale-while-revalidate

La directive de réponse stale-while-revalidate indique que le cache peut réutiliser une réponse périmée pendant qu'il la revalide dans un cache.

Cache-Control: max-age=604800, stale-while-revalidate=86400

Dans l'exemple qui précède, la réponse est fraîche pendant 7 jours (604800s). Après 7 jours, elle devient périmée, mais le cache peut être réutilisé pour les requêtes qui sont faites le jour suivant (86400s), tant que la revalidation de la réponse a lieu en arrière-plan.

La revalidation rafraîchira le cache à nouveau et la réponse apparaîtra donc comme toujours fraîche aux clients pendant cette période, masquant ainsi la latence induite par une revalidation.

Si aucune requête n'a lieu pendant cette période intermédiaire, le cache devient périmé et la prochaine requête revalidera le cache normalement.

stale-if-error

La directive de réponse stale-if-error indique que le cache peut réutiliser une réponse périmée lorsqu'un serveur d'origine répond avec une erreur (500, 502, 503, ou 504).

Cache-Control: max-age=604800, stale-if-error=86400

Dans l'exemple précédent, la réponse est fraîche pendant 7 jours (604800s). Après 7 jours, le cache devient périmé, mais peut être utilisé jusqu'à un jour après (86400s) si le serveur répond avec une erreur.

Une fois cette période écoulée, la réponse enregistrée devient périmée. Cela signifie que le client recevra une réponse d'erreur telle que fournie par le serveur d'origine.

La directive de requête no-cache demande aux caches de valider la réponse auprès du serveur d'origine avant toute réutilisation.

Cache-Control: no-cache

no-cache permet aux clients de demander la réponse la plus à jour, même si le cache dispose d'une réponse fraîche.

Les navigateurs ajoutent généralement no-cache aux requêtes effectuées lors d'un rechargement forcé d'une page.

La directive de requête no-store permet à un client de demander à ce qu'un cache ne stocke pas la requête et la réponse correspondante, même si la réponse du serveur d'origine pourrait être enregistrée.

Cache-Control: no-store

On notera que la plupart des navigateurs principaux ne prennent pas en charge les requêtes avec no-store.

La directive de requête max-age=N indique que le client autorise une réponse enregistrée qui est générée sur le serveur d'origine dans les N secondes, où N est un nombre positif (pouvant être 0).

Cache-Control: max-age=3600

Dans l'exemple ci-avant, si la réponse avec Cache-Control: max-age=604800 a été générée plus de trois heures auparavant (durée calculée à partir de la directive max-age et de l'en-tête Age), le cache ne pourrait pas réutiliser cette réponse.

La plupart des navigateurs utilisent cette directive pour le rechargement, comme expliqué après.

Cache-Control: max-age=0

max-age=0 est une alternative à no-cache, car de nombreuses (et anciennes) implémentations de cache (HTTP/1.0) n'implémentent pas no-cache. Les navigateurs récents continuent d'utiliser max-age=0 pour le rechargement à des fins de rétro-compatibilité, utilisant no-cache pour un rechargement forcé.

Si la valeur de max-age est négative (par exemple -1) ou n'est pas un entier (par exemple, 3599.99), le comportement pour la mise en cache n'est pas défini. Toutefois, la section sur le calcul pour la durée de la fraîcheur de la spécification HTTP indique :

Les caches sont incités à considérer les réponses portant des informations de fraîcheur invalides comme étant périmées.

Autrement dit, pour toute valeur de max-age qui n'est ni entière, ni positive, on incite à traiter la valeur comme si elle était 0.

La directive de requête max-stale=N indique que le client permet l'utilisation d'une réponse enregistrée périmée dans les N secondes.

Cache-Control: max-stale=3600

Dans le cas précédent, si la réponse avec Cache-Control: max-age=604800 a été générée plus de trois heures auparavant (durée calculée avec max-age et l'en-tête Age), le cache ne pourrait pas réutiliser cette réponse.

Les clients peuvent utiliser cet en-tête lorsque le serveur d'origine est inaccessible ou trop lents à répondre afin d'accepter les réponses mises en cache, même si elles sont un peu vieilles.

On notera que la plupart des navigateurs principaux ne prennent pas en charge les requêtes avec max-stale.

La directive de requête min-fresh=N indique que le client permet d'utiliser une réponse enregistrée qui est fraîche pendant au moins N secondes.

Cache-Control: min-fresh=600

Dans l'exemple qui précède, si la réponse avec Cache-Control: max-age=3600 avait été enregistrée en cache 51 minutes auparavant, le cache ne pourrait pas réutiliser cette réponse.

Les clients peuvent utiliser cet en-tête pour demander une réponse qui soit fraîche, et qui ne soit pas mise à jour pour une durée donnée.

On notera que la plupart des navigateurs principaux ne prennent pas en charge les requêtes avec min-fresh.

Équivalent à no-transform telle que définie pour les réponses, mais ici pour les requêtes.

Le client indique que le cache devrait obtenir une réponse déjà mise en cache. Si un cache possède une réponse enregistrée, celle-ci est réutilisée.

Si on ne souhaite pas qu'une réponse puisse être enregistrée en cache, on utilisera la directive no-store.

Cache-Control: no-store

On notera que no-cache signifie plutôt que la réponse peut être enregistrée en cache mais pas réutilisée sans revalidation. Cette directive n'empêche donc pas qu'une réponse soit stockée.

Cache-Control: no-cache

En théorie, si les directives rentrent en conflit, c'est la plus restrictive qui est respectée. Aussi, le premier exemple qui inutilement verbeux, car private, no-cache, max-age=0 et must-revalidate sont en conflit avec no-store.

# Conflit entre les directives
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate

# Équivalent à
Cache-Control: no-store

Lorsqu'on compile des ressources statiques avec des suffixes de version ou d'empreinte, cela permet de gérer plus simplement le cache et surtout sa mise à jour.

Ainsi :

<!-- index.html -->
<script src="/assets/react.min.js"></script>
<img src="/assets/hero.png" width="900" height="400">

La bibliothèque React pourra changer de version lors d'une mise à jour, et hero.png pourra aussi évoluer si l'image est éditée. Il est donc difficile de stocker ces fichiers tels quels dans un cache en le gérant avec max-age.

Dans un tel scénario, on peut régler le problème de cache en suffixant le nom du fichier avec la version de la bibliothèque et en incluant une empreinte de l'image dans son URL.

<!-- index.html -->
<script src="/assets/react.0.0.0min.js"></script>
<img src="/assets/hero.png?hash=deadbeef" width="900" height="400">

Avec ce format, on peut ajouter une valeur élevée pour max-age et la directive immutable, car le contenu ne changera jamais pour une URL donnée.

# /assets/*
Cache-Control: max-age=31536000, immutable

Lorsqu'on met à jour la bibliothèque ou qu'on édite l'image, le nouveau contenu aura une nouvelle URL et les caches ne seront pas réutilisés. C'est ce qu'on appelle en anglais le « cache-busting », qu'on pourrait traduire en français, en étant taquin par : « casse-cache ».

On utilisera no-cache pour s'assurer que la réponse HTML elle-même n'est pas cachée sans revalidation. Cela permettra au client de recevoir correctement une nouvelle version du fichier HTML et les ressources correspondants.

# /index.html
Cache-Control: no-cache

Si le service de index.html est contrôlé par une authentification (simple ou avec empreinte), les fichiers situés sous /assets ne sont pas enregistrés dans le cache partagé. Si les fichiers sous /assets/ peuvent en réalité être enregistrés dans un cache partagé, il faudra indiquer une des directives suivantes : public, s-maxage, ou must-revalidate.

Pour le contenu généré dynamiquement ou pour le contenu statique qui est souvent mis à jour, on voudra que la personne reçoive la version la plus à jour.

Si on ne précise pas d'en-tête Cache-Control alors qu'on souhaite ne pas mettre en cache la réponse, on pourra obtenir des résultats inattendus. En effet, par défaut, un cache peut décider d'une mise en cache en fonction d'heuristiques. Si on souhaite appliquer des règles pour la mise en cache, il faudra les préciser explicitement avec l'en-tête Cache-Control.

Ajouter la directive no-cache à la réponse entraînera la revalidation du serveur, et une réponse fraîche sera servie à chaque fois, et si le client dispose déjà d'une nouvelle réponse, le serveur répondra simplement 304 Not Modified.

Cache-Control: no-cache

La plupart des caches HTTP/1.0 ne prennent pas en charge la directive no-cache, et historiquement, max-age=0 a été utilisé comme contournement. Toutefois, max-age=0 pouvait causer la réutilisation d'une réponse périmée lorsque le cache était déconnecté du serveur d'origine. must-revalidate pallie ce problème. C'est pourquoi, ce qui suit est équivalent à no-cache.

Cache-Control: max-age=0, must-revalidate

Ceci étant écrit, avec un cache moderne, il suffit d'utiliser no-cache à la place.

Malheureusement, il n'existe pas de directives pour supprimer les réponses déjà enregistrées dans les caches.

Imaginons qu'un client ou qu'un cache enregistre une réponse fraîche pour un chemin donné et qu'il n'effectue aucune requête vers le serveur. Il n'y a rien que le serveur pourrait faire à ce moment.

Sinon, Clear-Site-Data peut nettoyer le cache du navigateur pour un site. Mais cela a ses limites, toutes les réponses stockées pour un site sont supprimées, et cela ne s'applique qu'aux navigateurs, pas aux caches partagés.

• Mise en cache avec HTTP
• Tutoriel sur la mise en cache pour les équipes web
• Bonnes pratiques pour la mise en cache et pièges liés à max-age (en anglais)
• Cache-Control pour les civils (en anglais)
• RFC 7234 — Hypertext Transfer Protocol (HTTP/1.1) : mise en cache (en anglais)
• RFC 5861 — Extensions HTTP à Cache-Control pour le contenu périmé (en anglais)
• RFC 8246 — Réponses HTTP immuables (en anglais)