L'en-tête HTTPCache-Control contient desdirectives (c'est-à-dire des instructions), dans les requêtes et dans les réponses, pour contrôlerla mise en cache dans les navigateurs et caches partagées (par exemple lesproxies, CDN).

Syntaxe

Cache-Control: <directive>, <directive>, ...

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.

Cache directives

Le tableau qui suit indique les directives standard pourCache-Control :

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

Vocabulaire

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 unproxy 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 toujoursfraîche. Généralement, la revalidation est réalisée avec une requête conditionnelle.

Réponse fraîche

Indique que la réponse estfraî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 estpé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 devenirfraî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 estfraîche oupérimée.

Directives

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.

Directives de réponse

max-age

La directive de réponsemax-age=N indique que la réponse restefraî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 estfraîche.

On notera quemax-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éponseAge), le cache du navigateur déduira 100 secondes de ladurée de fraîcheur.

Si la valeur demax-age est négative (par exemple,-1) ou n'est pas un entier (par exemple,3599.99), alors le comportement de la mise en cache n'est pas défini. Il est recommandé aux caches de traiter la valeur comme si elle était0 (cela est indiqué dans la sectionCalcul de la durée de fraîcheur^(angl.) de la spécification HTTP).

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

s-maxage

La directive de réponses-maxage indique également la durée pendant laquelle la réponse estfraîche (de façon analogue àmax-age), mais s'applique spécifiquement aux caches partagés.La directives-maxage est ignorée par les caches privés et remplace la valeur définie par la directivemax-age ou l'en-têteExpires pour les caches partagés, si elles sont présentes.

Cache-Control: s-maxage=604800

no-cache

La directive de réponseno-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 queno-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 passtocker de données pour ne pas avoir de cache du tout, il faudra utiliser la directiveno-store.

must-revalidate

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

On utilise généralementmust-revalidate avecmax-age.

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

HTTP permet aux caches de réutiliserdes 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éponseproxy-revalidate est équivalente àmust-revalidate, mais concerne uniquement les caches partagés.

no-store

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

Cache-Control: no-store

private

La directive de réponseprivate 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 directiveprivate 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 descookies.

Siprivate 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éponsepublic indique que la réponse peut être enregistrée dans un cache partagé. Les réponses pour les requêtes contenant l'en-têteAuthorization ne doivent jamais être enregistrées dans un cache partagé. Toutefois, si la directivepublic 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êteAuthorization. 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 directivemax-age.

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

Cache-Control: public, max-age=604800

On notera ques-maxage oumust-revalidate lèvent également cette restriction.

Si une requête n'utilise pas l'en-têteAuthorization, ou sis-maxage oumust-revalidate sont déjà utilisés pour la réponse, il n'est pas nécessaire d'utiliserpublic.

must-understand

La directive de réponsemust-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 avecno-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 chargemust-understand, celle-ci sera ignorée. Sino-store est également présente, la réponse n'est pas enregistrée.

Si un cache prend en chargemust-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.

immutable

La directive de réponseimmutable indique que la réponse ne sera pas mise à jour tant qu'elle estfraî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, demettre à 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 decache-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 estfraî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 demax-age, on peut également utiliserimmutable pour éviter une revalidation.

stale-while-revalidate

La directive de réponsestale-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 estfraîche pendant 7 jours (604800s). Après 7 jours, elle devientpé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 revalidationrafraîchira le cache à nouveau et la réponse apparaîtra donc comme toujoursfraî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 devientpérimé et la prochaine requête revalidera le cache normalement.

stale-if-error

La directive de réponsestale-if-error indique que le cache peut réutiliser une réponsepé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 estfraîche pendant 7 jours (604800s). Après 7 jours, le cache devientpé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 devientpérimée. Cela signifie que le client recevra une réponse d'erreur telle que fournie par le serveur d'origine.

Directives de requête

no-cache

La directive de requêteno-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éponsefraîche.

Les navigateurs ajoutent généralementno-cache aux requêtes effectuées lors d'unrechargement forcé d'une page.

no-store

La directive de requêteno-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 avecno-store.

max-age

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

Cache-Control: max-age=3600

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

La plupart des navigateurs utilisent cette directive pour lerechargement, 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 pasno-cache. Les navigateurs récents continuent d'utilisermax-age=0 pour le rechargement à des fins de rétro-compatibilité, utilisantno-cache pour un rechargement forcé.

Si la valeur demax-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 surle calcul pour la durée de la fraîcheur de la spécification HTTP indique :

max-stale

La directive de requêtemax-stale=N indique que le client permet l'utilisation d'une réponse enregistréepérimée dans lesN secondes.Si aucune valeurN n'est définie, le client acceptera une réponse périmée quel que soit son âge.

Cache-Control: max-stale=3600

Dans le cas précédent, si la réponse avecCache-Control: max-age=604800 a été générée plus de trois heures auparavant (durée calculée avecmax-age et l'en-têteAge), 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 avecmax-stale.

min-fresh

La directive de requêtemin-fresh=N indique que le client permet d'utiliser une réponse enregistrée qui estfraîche pendant au moinsN secondes.

Cache-Control: min-fresh=600

Dans l'exemple qui précède, si la réponse avecCache-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 soitfraî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 avecmin-fresh.

no-transform

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

only-if-cached

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.

stale-if-error

La directive de requêtestale-if-error indique que le navigateur souhaite recevoir un contenu périmé en cas d'erreur de la part d'un serveur intermédiaire pour une origine donnée.Cette fonctionnalité n'est prise en charge par aucun navigateur (voirCompatibilité des navigateurs).

Cas d'usage

Empêcher le stockage

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

Cache-Control: no-store

On notera queno-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 suit est inutilement verbeux, carprivate,no-cache,max-age=0 etmust-revalidate sont en conflit avecno-store.

# Conflit entre les directivesCache-Control: private, no-cache, no-store, max-age=0, must-revalidate# Équivalent àCache-Control: no-store

Mise en cache des ressources statiques et partie de casse-cache

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, ethero.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 avecmax-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 pourmax-age et la directiveimmutable, 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 utiliserano-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.htmlCache-Control: no-cache

Si le service deindex.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, oumust-revalidate.

Toujours obtenir un contenu à jour

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êteCache-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êteCache-Control.

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

Cache-Control: no-cache

La plupart des caches HTTP/1.0 ne prennent pas en charge la directiveno-cache, et historiquement,max-age=0 a été utilisé comme contournement. Toutefois,max-age=0 pouvait causer la réutilisation d'uneré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'utiliserno-cache à la place.

Supprimer les informations déjà enregistrées en cache

Il n'existe aucune directive de cache permettant de supprimer les réponses déjà enregistrées dans les caches sur les serveursintermédiaires.

Imaginons qu'un client ou qu'un cache enregistre une réponsefraî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.

Clear-Site-Data: cache 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.Notez que cela n'affectera pas les caches partagés ou intermédiaires.

Spécifications

Compatibilité des navigateurs

Voir aussi

• La mise en cache avec HTTP
• Tutoriel sur la mise en cache pour les équipes web^(angl.)
• Bonnes pratiques pour la mise en cache et pièges liés àmax-age^(angl.)
• Cache-Control pour les civils^(angl.)
• RFC 9111 — Mise en cache HTTP^(angl.)
• RFC 5861 — Extensions HTTP àCache-Control pour le contenu périmé^(angl.)
• RFC 8246 — Réponses HTTP immuables^(angl.)