En-tte Cache-Control

Syntaxe

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

Les directives pour la mise en cache suivent les rgles suivantes :

• Elles sont insensibles la casse. Toutefois, l'utilisation de minuscules est recommande, car certaines implmentations ne reconnaissent pas les directives en majuscules.
• Plusieurs directives sont spares entre elles par des virgules.
• Certaines directives ont un argument optionnel.

Directives de mise en cache

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

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

Vocabulaire

Cette section dfinit les termes utiliss dans ce document, certains provenant de la spcification.

Cache (HTTP)

Une implmentation qui contient les requtes et les rponses afin de les rutiliser pour les requtes suivantes. Il peut s'agir 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 rponse pour la rutiliser avec plusieurs utilisatrices et utilisateurs (les quipes de dveloppement 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 rutiliser du contenu personnalis pour une personne.

Stockage de la rponse

Stocker une rponse dans les caches lorsqu'elle peut tre mise en cache. Toutefois, la rponse mise en cache n'est pas ncessairement rutilise telle quelle (la plupart du temps, mettre en cache signifie stocker une rponse).

Rutilisation des rponses

Rutiliser des rponses mises en cache pour les requtes suivantes.

Revalidation de la rponse

Demander au serveur d'origine si la rponse stocke est toujours frache. Gnralement, la revalidation est ralise avec une requte conditionnelle.

Rponse frache

Indique que la rponse est frache. Cela signifie en gnral que la rponse peut tre utilise pour les requtes suivantes, selon les directives de la requte.

Rponse prime

Indique que la rponse est prime. Cela signifie en gnral que la rponse ne peut tre rutilise telle quelle. Le stockage du cache ne doit pas ncessairement retirer immdiatement des rponses primes, car une revalidation peut modifier la rponse et la faire devenir frache nouveau.

ge

Le temps coul depuis la gnration de la rponse. Il s'agit d'un critre pour dterminer si une rponse est frache ou prime.

Directives

Cette section indique les directives qui jouent un rle pour la mise en cache, tant pour les rponses que pour les requtes.

Directives de rponse

max-age

La directive de rponse max-age=N indique que la rponse reste frache jusqu' N secondes aprs la gnration de la rponse.

Cache-Control: max-age=604800

Cela indique que les caches peuvent stocker cette rponse et la rutiliser pour les requtes suivantes tant qu'elle est frache.

Notez que max-age ne correspond pas au temps coul depuis que la rponse a t reue, il s'agit du temps coul depuis que la rponse a t gnre sur le serveur d'origine. Ainsi, si les autres caches situs sur la route rseau emprunte par la rponse stockent la rponse pendant 100 secondes (en l'indiquant avec l'en-tte de rponse Age), le cache du navigateur dduit 100 secondes de la dure de fracheur.

Si la valeur de max-age est ngative (par exemple, -1) ou n'est pas un entier (par exemple, 3599.99), alors le comportement de la mise en cache n'est pas dfini. Il est recommand aux caches de traiter la valeur comme si elle valait 0 (cela est indiqu dans la section Calcul de la dure de fracheur (angl.) de la spcification HTTP).

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

s-maxage

La directive de rponse s-maxage indique galement la dure pendant laquelle la rponse est frache (de faon analogue max-age), mais s'applique spcifiquement aux caches partags. La directive s-maxage est ignore par les caches privs et remplace la valeur dfinie par la directive max-age ou l'en-tte Expires pour les caches partags, si elles sont prsentes.

Cache-Control: s-maxage=604800

no-cache

La directive de rponse no-cache indique que la rponse peut tre stocke en cache, mais qu'elle doit tre valide avec le serveur d'origine avant chaque rutilisation, mme si le cache est dconnect du serveur d'origine.

Cache-Control: no-cache

Si vous souhaitez que les caches vrifient leur contenu chaque mise jour tout en rutilisant du contenu stock, no-cache est la directive utiliser.

Notez que no-cache ne signifie pas  ne pas mettre en cache . no-cache permet aux caches de stocker une rponse, mais impose une revalidation avant toute rutilisation. Si vous souhaitez effectivement ne pas stocker de donnes pour ne pas avoir de cache du tout, il faut utiliser la directive no-store.

must-revalidate

La directive de rponse must-revalidate indique que la rponse peut tre stocke dans les caches et peut tre rutilise tant qu'elle est frache. Si la rponse devient prime, elle doit tre revalide avec le serveur d'origine avant de pouvoir tre rutilise.

On utilise gnralement must-revalidate avec max-age.

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

HTTP permet aux caches de rutiliser des rponses primes lorsqu'ils sont dconnects du serveur d'origine. must-revalidate permet d'viter ce fonctionnement, soit la rponse enregistre est revalide auprs du serveur d'origine, soit une rponse 504 (Gateway Timeout) est gnre.

proxy-revalidate

La directive de rponse proxy-revalidate est quivalente must-revalidate, mais concerne uniquement les caches partags.

no-store

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

Cache-Control: no-store

private

La directive de rponse private indique que la rponse peut uniquement tre enregistre dans un cache priv (c'est--dire le cache local des navigateurs).

Cache-Control: private

La directive private doit tre ajoute pour le contenu personnalis, notamment pour les rponses reues aprs une authentification et pour les sessions gres avec des cookies.

Si private est oublie pour une rponse avec du contenu personnalis, cette rponse peut tre enregistre dans un cache partag et finir par tre rutilise pour plusieurs personnes, causant ainsi une fuite d'informations personnelles.

public

La directive de rponse public indique que la rponse peut tre enregistre dans un cache partag. Les rponses pour les requtes contenant l'en-tte Authorization ne doivent jamais tre enregistres dans un cache partag. Toutefois, si la directive public est prsente, de telles rponses peuvent tre enregistres dans un cache partag.

Cache-Control: public

En gnral, lorsque les pages utilisent une authentification simple (Basic Auth) ou par empreinte (Digest Auth), le navigateur envoie des requtes avec l'en-tte Authorization. Cela signifie par essence que la rponse dpend d'un contrle d'accs, limit aux personnes qui disposent de comptes adquats, et qu'elle ne peut pas tre mise en cache, mme si la rponse utilise la directive max-age.

La directive public peut tre utilise afin de lever cette restriction.

Cache-Control: public, max-age=604800

Notez que s-maxage ou must-revalidate lvent galement cette restriction.

Si une requte n'utilise pas l'en-tte Authorization, ou si s-maxage ou must-revalidate sont dj utiliss pour la rponse, il n'est pas ncessaire d'utiliser public.

must-understand

La directive de rponse must-understand indique qu'un cache doit uniquement stocker la rponse s'il comprend les prrequis la mise en cache selon le code de statut.

must-understand doit tre utilise en association avec no-store, qui permet d'avoir un comportement proche si la premire 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 est ignore. Si no-store est galement prsente, la rponse n'est pas enregistre.

Si un cache prend en charge must-understand, il stocke la rponse avec une comprhension des prrequis de mise en cache selon son code de statut.

no-transform

Certains intermdiaires transforment du contenu pour diffrentes raisons. Par exemple, certains convertissent des images afin de rduire leur taille de transfert. Dans certains cas, il peut s'agir d'un comportement qu'on souhaite viter.

no-transform indique l'intermdiaire (qu'il s'agisse d'un cache ou non) qu'il ne faut pas transformer le contenu de la rponse.

immutable

La directive de rponse immutable indique que la rponse n'est pas mise jour tant qu'elle est frache.

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 ncessaire, de mettre jour ces ressources avec de nouvelles versions utilisant un nouveau numro de version/une nouvelle empreinte, afin que les URL soient diffrentes. C'est ce qu'on appelle en anglais une stratgie de cache-busting (peut-tre  casse-cache  en franais).

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

Lorsqu'on recharge une page dans le navigateur, ce dernier envoie des requtes conditionnelles pour la validation auprs du serveur d'origine. Toutefois, il n'est pas ncessaire de revalider ce type de ressources statiques, mme lorsqu'on recharge une page, car elles ne sont jamais modifies. immutable indique au cache que la rponse est immuable tant qu'elle est frache et vite ces requtes conditionnelles superflues envers le serveur.

Lorsqu'on utilise une stratgie de casse-cache pour des ressources auxquelles on applique une valeur leve de max-age, on peut galement utiliser immutable pour viter une revalidation.

stale-while-revalidate

La directive de rponse stale-while-revalidate indique que le cache peut rutiliser une rponse prime pendant qu'il la revalide dans un cache.

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

Dans l'exemple qui prcde, la rponse est frache pendant 7 jours (604800s). Aprs 7 jours, elle devient prime, mais le cache peut tre rutilis pour les requtes qui sont faites le jour suivant (86400s), tant que la revalidation de la rponse a lieu en arrire-plan.

La revalidation rafrachit le cache nouveau et la rponse apparat donc comme toujours frache aux clients pendant cette priode, masquant ainsi la latence induite par une revalidation.

Si aucune requte n'a lieu pendant cette priode intermdiaire, le cache devient prim et la prochaine requte revalide le cache normalement.

stale-if-error

La directive de rponse stale-if-error indique que le cache peut rutiliser une rponse prime lorsqu'un serveur d'origine rpond avec une erreur (500, 502, 503, ou 504).

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

Dans l'exemple prcdent, la rponse est frache pendant 7 jours (604800s). Aprs 7 jours, le cache devient prim, mais peut tre utilis jusqu' un jour aprs (86400s) si le serveur rpond avec une erreur.

Une fois cette priode coule, la rponse enregistre devient prime. Cela signifie que le client reoit une rponse d'erreur telle que fournie par le serveur d'origine.

Directives de requte

no-cache

La directive de requte no-cache demande aux caches de valider la rponse auprs du serveur d'origine avant toute rutilisation.

Cache-Control: no-cache

no-cache permet aux clients de demander la rponse la plus jour, mme si le cache dispose d'une rponse frache.

Les navigateurs ajoutent gnralement no-cache aux requtes effectues lors d'un rechargement forc d'une page.

no-store

La directive de requte no-store permet un client de demander ce qu'un cache ne stocke pas la requte et la rponse correspondante, mme si la rponse du serveur d'origine peut tre enregistre.

Cache-Control: no-store

Notez que la plupart des navigateurs principaux ne prennent pas en charge les requtes avec no-store.

max-age

La directive de requte max-age=N indique que le client autorise une rponse enregistre qui est gnre 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 rponse avec Cache-Control: max-age=604800 a t gnre plus de trois heures auparavant (dure calcule partir de la directive max-age et de l'en-tte Age), le cache ne peut pas rutiliser cette rponse.

La plupart des navigateurs utilisent cette directive pour le rechargement, comme expliqu aprs.

Cache-Control: max-age=0

max-age=0 est une alternative no-cache, car de nombreuses (et anciennes) implmentations de cache (HTTP/1.0) n'implmentent pas no-cache. Les navigateurs rcents continuent d'utiliser max-age=0 pour le rechargement des fins de rtro-compatibilit, utilisant no-cache pour un rechargement forc.

Si la valeur de max-age est ngative (par exemple -1) ou n'est pas un entier (par exemple, 3599.99), le comportement pour la mise en cache n'est pas dfini. Toutefois, la section sur le calcul pour la dure de la fracheur (angl.) de la spcification HTTP indique :

max-stale

La directive de requte max-stale=N indique que le client permet l'utilisation d'une rponse enregistre prime dans les N secondes. Si aucune valeur N n'est dfinie, le client accepte une rponse prime quel que soit son ge.

Cache-Control: max-stale=3600

Dans le cas prcdent, si la rponse avec Cache-Control: max-age=604800 a t gnre plus de trois heures auparavant (dure calcule avec max-age et l'en-tte Age), le cache ne peut pas rutiliser cette rponse.

Les clients peuvent utiliser cet en-tte lorsque le serveur d'origine est inaccessible ou trop lents rpondre afin d'accepter les rponses mises en cache, mme si elles sont un peu vieilles.

Notez que la plupart des navigateurs principaux ne prennent pas en charge les requtes avec max-stale.

min-fresh

La directive de requte min-fresh=N indique que le client permet d'utiliser une rponse enregistre qui est frache pendant au moins N secondes.

Cache-Control: min-fresh=600

Dans l'exemple qui prcde, si la rponse avec Cache-Control: max-age=3600 a t enregistre en cache 51 minutes auparavant, le cache ne peut pas rutiliser cette rponse.

Les clients peuvent utiliser cet en-tte pour demander une rponse qui soit frache, et qui ne soit pas mise jour pour une dure donne.

Notez que la plupart des navigateurs principaux ne prennent pas en charge les requtes avec min-fresh.

no-transform

quivalent no-transform telle que dfinie pour les rponses, mais ici pour les requtes.

only-if-cached

Le client indique que le cache doit obtenir une rponse dj mise en cache. Si un cache possde une rponse enregistre, celle-ci est rutilise.

stale-if-error

La directive de requte stale-if-error indique que le navigateur souhaite recevoir un contenu prim en cas d'erreur de la part d'un serveur intermdiaire pour une origine donne. Cette fonctionnalit n'est prise en charge par aucun navigateur (voir Compatibilit des navigateurs).

Cas d'usage

Empcher le stockage

Si on ne souhaite pas qu'une rponse puisse tre enregistre en cache, on utilise la directive no-store.

Cache-Control: no-store

Notez que no-cache signifie plutt que la rponse peut tre enregistre en cache mais pas rutilise sans revalidation. Cette directive n'empche donc pas qu'une rponse soit stocke.

Cache-Control: no-cache

En thorie, si les directives rentrent en conflit, c'est la plus restrictive qui est respecte. Aussi, le premier exemple qui suit est 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

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 grer 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 bibliothque React peut changer de version lors d'une mise jour, et hero.png peut aussi voluer si l'image est dite. Il est donc difficile de stocker ces fichiers tels quels dans un cache en le grant avec max-age.

Dans un tel scnario, on peut rgler le problme de cache en suffixant le nom du fichier avec la version de la bibliothque et en incluant une empreinte de l'image dans son URL.

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

Avec ce format, on peut ajouter une valeur leve pour max-age et la directive immutable, car le contenu ne change jamais pour une URL donne.

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

Lorsqu'on met jour la bibliothque ou qu'on dite l'image, le nouveau contenu a une nouvelle URL et les caches ne sont pas rutiliss. C'est ce qu'on appelle en anglais le  cache-busting , qu'on peut traduire en franais, en tant taquin par :  casse-cache .

On utilise no-cache pour s'assurer que la rponse HTML elle-mme n'est pas cache sans revalidation. Cela permet 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 contrl par une authentification (simple ou avec empreinte), les fichiers situs sous /assets ne sont pas enregistrs dans le cache partag. Si les fichiers sous /assets/ peuvent en ralit tre enregistrs dans un cache partag, il faut indiquer une des directives suivantes : public, s-maxage, ou must-revalidate.

Toujours obtenir un contenu jour

Pour le contenu gnr dynamiquement ou pour le contenu statique qui est souvent mis jour, on veut que la personne reoive la version la plus jour.

Si on ne prcise pas d'en-tte Cache-Control alors qu'on souhaite ne pas mettre en cache la rponse, on peut obtenir des rsultats inattendus. En effet, par dfaut, un cache peut dcider d'une mise en cache en fonction d'heuristiques. Si on souhaite appliquer des rgles pour la mise en cache, il faut les prciser explicitement avec l'en-tte Cache-Control.

Ajouter la directive no-cache la rponse entrane la revalidation du serveur, et une rponse frache est servie chaque fois, et si le client dispose dj d'une nouvelle rponse, le serveur rpond 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 peut causer la rutilisation d'une rponse prime lorsque le cache est dconnect du serveur d'origine. must-revalidate pallie ce problme. 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.

Supprimer les informations dj enregistres en cache

Il n'existe aucune directive de cache permettant de supprimer les rponses dj enregistres dans les caches sur les serveurs intermdiaires.

Imaginons qu'un client ou qu'un cache enregistre une rponse frache pour un chemin donn et qu'il n'effectue aucune requte vers le serveur. Il n'y a rien que le serveur peut faire ce moment.

Clear-Site-Data: cache peut nettoyer le cache du navigateur pour un site. Mais cela a ses limites, toutes les rponses stockes pour un site sont supprimes, et cela ne s'applique qu'aux navigateurs, pas aux caches partags. Notez que cela n'affecte pas les caches partags ou intermdiaires.

Spcifications

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 piges lis 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 prim (angl.)
• RFC 8246 Rponses HTTP immuables (angl.)