En-tête Cache-Control

Conseils
3 semaines ago
53
42 minutes read

http

Cache-Control: , , ...

Les directives de mise en cache respectent les règles suivantes :

Les directives de mise en cache ne sont pas sensibles à la casse. Il est toutefois recommandé d’utiliser les minuscules, car certaines implémentations ne reconnaissent pas les directives en majuscules.
Il est possible d’utiliser plusieurs directives, qui doivent être séparées par des virgules (par exemple, Cache-control: max-age=180, public).
Certaines directives comportent un argument facultatif. Lorsqu’un argument est fourni, il est séparé du nom de la directive par le signe égal (=). En règle générale, les arguments des directives sont des nombres entiers et ne sont donc pas placés entre guillemets (par exemple, Cache-control: max-age=12).

Directives de cache

Le tableau suivant répertorie les directives standard Cache-Control :

Requête	Réponse
`max-age`	`max-age`
`max-stale`	–
`min-fresh`	–
–	`s-maxage`
`no-cache`	`no-cache`
`no-store`	`no-store`
`no-transform`	`no-transform`
`only-if-cached`	–
–	`must-revalidate`
–	`proxy-revalidate`
–	`must-understand`
–	`private`
–	`public`
–	`immutable`
–	`stale-while-revalidate`
`stale-if-error`	`stale-if-error`

Remarque : consultez le table de compatibilité pour connaître leur prise en charge ; les agents utilisateurs qui ne les reconnaissent pas doivent les ignorer.

Cette section définit les termes utilisés dans le présent document, dont certains proviennent de la spécification.

Cache (HTTP): Implémentation qui conserve les requêtes et les réponses en vue de leur réutilisation dans des requêtes ultérieures. Il peut s’agir d’un cache partagé ou d’un cache privé.
Cache partagé: Cache situé entre le serveur d’origine et les clients (par exemple, un proxy ou un CDN). Il stocke une seule réponse et la réutilise pour plusieurs utilisateurs ; les développeurs doivent donc éviter de stocker du contenu personnalisé destiné à être mis en cache dans le cache partagé.
Cache privé: Cache présent au niveau du client. Il est également appelé cache local ou cache du navigateur. Il peut stocker et réutiliser du contenu personnalisé pour un seul utilisateur.
Stockage de la réponse: Stocker une réponse dans les caches lorsque celle-ci est mise en cache. Cependant, la réponse mise en cache n’est pas toujours réutilisée telle quelle. (En général, le terme « cache » désigne le stockage d’une réponse.)
Réutilisation de la réponse: Réutiliser les réponses mises en cache pour les requêtes suivantes.
Revalider la réponse: Demander au serveur d’origine si la réponse stockée est toujours à jour. Généralement, la revalidation s’effectue via une requête conditionnelle.
Réponse à jour: Indique que la réponse est à jour. Cela signifie généralement que la réponse peut être réutilisée pour les requêtes suivantes, en fonction des directives de requête.
Réponse périmée: Indique que la réponse est périmée. Cela signifie généralement que la réponse ne peut pas être réutilisée telle quelle. Le cache n’est pas tenu de supprimer immédiatement les réponses périmées, car une revalidation pourrait faire passer la réponse du statut « périmée » à « récente ».
Âge: Temps écoulé depuis la génération d’une réponse. Il s’agit d’un critère permettant de déterminer si une réponse est à jour ou périmée.

Cette section répertorie les directives qui affectent la mise en cache — aussi bien les directives de réponse que les directives de requête.

Directives de réponse

`max-age`

La max-age=N directive de réponse indique que la réponse reste à jour jusqu’à N secondes après sa génération.

http

Cache-Control: max-age=604800

Indique que les caches peuvent stocker cette réponse et la réutiliser pour les requêtes suivantes tant qu’elle est valide.

Notez que max-age ne correspond pas au temps écoulé depuis la réception de la réponse ; il s’agit du temps écoulé depuis la génération de la réponse sur le serveur d’origine.
Ainsi, si le ou les autres caches — situés sur le chemin emprunté par la réponse — stockent la réponse pendant 100 secondes (comme indiqué par le champ d’en-tête de réponse Age ), le cache du navigateur déduirait 100 secondes de sa durée de validité.

Si la max-age est négative (par exemple, -1) ou n’est pas un nombre entier (par exemple, 3599.99), le comportement de mise en cache n’est pas spécifié. Les caches sont encouragés à traiter cette valeur comme si elle était 0 (ceci est indiqué dans la section « Calcul de la durée de validité » de la spécification HTTP).

http

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

`s-maxage`

La directive de réponse s-maxage indique la durée pendant laquelle la réponse reste à jour dans un cache partagé.
La directive s-maxage est ignorée par les caches privés et remplace la valeur spécifiée par la directive max-age ou par l’en-tête Expires pour les caches partagés, si celles-ci sont présentes.

http

Cache-Control: s-maxage=604800

`no-cache`

La no-cache directive de réponse indique que la réponse peut être stockée dans les caches, mais qu’elle doit être validée auprès du serveur d’origine avant chaque réutilisation, même lorsque le cache est déconnecté du serveur d’origine.

http

Cache-Control: no-cache

Si vous souhaitez que les caches vérifient systématiquement les mises à jour du contenu lors de la réutilisation du contenu stocké, no-cache est la directive à utiliser. Elle oblige les caches à revalider chaque requête auprès du serveur d’origine.

Notez que no-cache ne signifie pas « ne pas mettre en cache ». no-cache autorise les caches à stocker une réponse, mais leur impose de la revalider avant de la réutiliser. Si le sens de « ne pas mettre en cache » que vous recherchez correspond en réalité à « ne pas stocker », alors no-store est la directive à utiliser.

Remarque :
La no-cache directive ne garantit pas la revalidation lors des navigations dans l’historique — telles que celles effectuées à l’aide du bouton « Retour » .
Si le cache « Précédent/Suivant » (bfcache) est utilisé, le navigateur restaure un instantané de la page sans revalidation.
Même lorsque le bfcache n’est pas utilisé, le navigateur peut tout de même servir la réponse mise en cache sans revalidation.
Ceci est autorisé par la spécification car les navigations dans l’historique sont généralement considérées comme la restauration d’un instantané d’une session antérieure et non comme une nouvelle requête pour une page précédemment visitée.

La must-revalidate directive de réponse indique que la réponse peut être stockée dans des caches et réutilisée tant qu’elle est à jour. Si la réponse devient obsolète, elle doit être validée auprès du serveur d’origine avant d’être réutilisée.

En général, must-revalidate est utilisé avec max-age.

HTTP

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

Le protocole HTTP autorise les caches à réutiliser des réponses périmées lorsqu’ils sont déconnectés du serveur d’origine. must-revalidate permet d’empêcher cela : soit la réponse stockée est revalidée auprès du serveur d’origine, soit une réponse 504 (dépassement du délai d’attente de la passerelle) est générée.

Remarque :
La must-revalidate directive ne garantit pas la revalidation pour les navigations dans l’historique — telles que celles effectuées à l’aide du bouton Retour .
Si le cache de navigation (bfcache) est utilisé, le navigateur restaure un instantané de la page sans revalidation.
Même lorsque le bfcache n’est pas utilisé, le navigateur peut tout de même servir la réponse mise en cache sans revalidation.
Ceci est autorisé par la spécification car les navigations dans l’historique sont généralement considérées comme la restauration d’un instantané d’une session antérieure et non comme une nouvelle requête pour une page déjà visitée.

`proxy-revalidate`

La proxy-revalidate directive de réponse est l’équivalent de must-revalidate, mais s’applique spécifiquement aux caches partagés uniquement.

`no-store`

La directive de réponse no-store indique que les caches de tout type (privés ou partagés) ne doivent pas stocker cette réponse.

http

Cache-Control: no-store

`private`

La private directive de réponse indique que la réponse ne peut être stockée que dans un cache privé (par exemple, les caches locaux des navigateurs).

http

Cache-Control: private

Vous devriez ajouter la private directive pour le contenu personnalisé, en particulier pour les réponses reçues après une connexion et pour les sessions gérées via des cookies.

Si vous oubliez d’ajouter private à une réponse contenant du contenu personnalisé, celle-ci peut être stockée dans un cache partagé et finir par être réutilisée pour plusieurs utilisateurs, ce qui peut entraîner une fuite d’informations personnelles.

`public`

La directive de réponse public indique que la réponse peut être stockée dans un cache partagé. Les réponses aux requêtes comportant les Authorization ne doivent pas être stockées dans un cache partagé ; cependant, la directive public entraînera le stockage de ces réponses dans un cache partagé.

http

Cache-Control: public

En général, lorsque les pages sont soumises à une authentification Basic ou Digest, le navigateur envoie des requêtes avec l’en-tête Authorization . Cela signifie que l’accès à la réponse est contrôlé pour les utilisateurs autorisés (qui possèdent un compte) et qu’elle n’est en principe pas mise en cache de manière partagée, même si elle comporte max-age.

Vous pouvez utiliser la directive public pour lever cette restriction.

http

Cache-Control: public, max-age=604800

Notez que s-maxage ou must-revalidate permettent également de lever cette restriction.

Si une requête ne comporte pas d’en-tête Authorization , ou si vous utilisez déjà s-maxage ou must-revalidate dans la réponse, vous n’avez pas besoin d’utiliser public.

`must-understand`

La directive de réponse must-understand indique qu’un cache ne doit stocker la réponse que s’il comprend les exigences de mise en cache en fonction du code d’état.

must-understand doit être associée à no-store pour définir un comportement de secours.

http

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ésent, la réponse n’est pas stockée.

Si un cache prend en charge must-understand, il stocke la réponse en tenant compte des exigences de mise en cache en fonction de son code d’état.

`no-transform`

Certains intermédiaires transforment le contenu pour diverses raisons. Par exemple, certains convertissent les images afin de réduire la taille des transferts. Dans certains cas, cela n’est pas souhaitable pour le fournisseur de contenu.

no-transform indique que tout intermédiaire (qu’il implémente ou non un cache) ne doit pas transformer le contenu de la réponse.

`immutable`

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

http

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

Une bonne pratique moderne pour les ressources statiques consiste à inclure des versions/hachages dans leurs URL, sans jamais modifier les ressources — mais plutôt, si nécessaire, mettre à jour les ressources avec des versions plus récentes comportant de nouveaux numéros de version ou hachages, de sorte que leurs URL soient différentes. C’est ce qu’on appelle le cache-busting .

Lorsqu’un utilisateur actualise son navigateur, celui-ci envoie des requêtes conditionnelles de validation au serveur d’origine. Mais il n’est pas nécessaire de revalider ce type de ressources statiques, même lorsqu’un utilisateur actualise son navigateur, car elles ne sont jamais modifiées.
immutable indique au cache que la réponse est immuable tant qu’elle est récente et évite ce genre de requêtes conditionnelles inutiles adressées au serveur.

Lorsque vous utilisez un modèle de contournement du cache pour des ressources et que vous l’appliquez à une longue max-age, vous pouvez également ajouter immutable pour éviter la revalidation.

`stale-while-revalidate`

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

http

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

Dans l’exemple ci-dessus, la réponse est à jour pendant 7 jours (604 800 s).
Au bout de 7 jours, elle devient périmée, mais le cache est autorisé à la réutiliser pour toute requête effectuée au cours du jour suivant (86 400 s), à condition qu’il revalide la réponse en arrière-plan.

La revalidation permet au cache de redevenir à jour, de sorte que les clients ont l’impression qu’il l’a toujours été pendant cette période — ce qui leur masque en fait la perte de latence liée à la revalidation.

Si aucune requête n’a eu lieu pendant cette période, le cache est devenu périmé et la requête suivante sera revalidée normalement.

`stale-if-error`

La stale-if-error indique que le cache peut réutiliser une réponse périmée lorsqu’un serveur en amont génère une erreur, ou lorsque l’erreur est générée localement. Ici, une erreur correspond à toute réponse dont le code d’état est 500, 502, 503 ou 504.

http

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

Dans l’exemple ci-dessus, la réponse reste valide pendant 7 jours (604 800 s). Passé ce délai, elle devient périmée, mais peut être réutilisée pendant 1 jour supplémentaire (86 400 s) en cas d’erreur.

Une fois la période « stale-if-error » écoulée, le client recevra toute erreur générée.

Directives de requête

`no-cache`

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

http

Cache-Control: no-cache

no-cache permet aux clients de demander la réponse la plus récente, même si le cache dispose d’une réponse récente.

Les navigateurs ajoutent généralement no-cache aux requêtes lorsque les utilisateurs forcent le rafraîchissement d’une page.

`no-store`

La no-store directive de requête permet à un client de demander que les caches s’abstiennent de stocker la requête et la réponse correspondante — même si la réponse du serveur d’origine pouvait être stockée.

http

Cache-Control: no-store

`max-age`

La max-age=N directive request indique que le client autorise une réponse mise en cache générée sur le serveur d’origine dans un délai de N secondes — où N peut être n’importe quel entier non négatif (y compris 0).

http

Cache-Control: max-age=10800

Dans le cas ci-dessus, si la réponse dont le Cache-Control: max-age=10800 a été générée il y a plus de 3 heures (calculé à partir de max-age et de l’en-tête Age ), le cache n’a pas pu réutiliser cette réponse.

De nombreux navigateurs utilisent cette directive pour recharger, comme expliqué ci-dessous.

http

Cache-Control: max-age=0

max-age=0 est une solution de contournement pour no-cache, car de nombreuses anciennes implémentations de cache (HTTP/1.0) ne prennent pas en charge no-cache. Récemment, les navigateurs continuent d’utiliser max-age=0 lors du « rechargement » — pour des raisons de compatibilité ascendante — et utilisent par ailleurs no-cache pour provoquer un « rechargement forcé ».

Si la max-age valeur est négative (par exemple, -1) ou n’est pas un entier (par exemple, 3599.99), le comportement de mise en cache n’est pas spécifié. Il est recommandé aux caches de traiter cette valeur comme s’il s’agissait de 0.

Remarque :
La directive max-age ne garantit pas la revalidation lors des navigations dans l’historique — telles que celles effectuées à l’aide du bouton Retour .
Si le cache de navigation (bfcache) est utilisé, le navigateur restaure un instantané de la page sans revalidation.
Même lorsque le bfcache n’est pas utilisé, le navigateur peut tout de même servir la réponse mise en cache sans revalidation.
Ceci est autorisé par la spécification car les navigations dans l’historique sont généralement considérées comme la restauration d’un instantané d’une session antérieure et non comme une nouvelle requête pour une page déjà visitée.

`max-stale`

La max-stale=N directive de requête indique que le client autorise une réponse mise en cache dont l’ancienneté ne dépasse pas N secondes.
Si aucune valeur N n’est spécifiée, le client acceptera une réponse périmée, quel que soit son âge.

http

Cache-Control: max-stale=3600

Par exemple, une requête comportant l’en-tête ci-dessus indique que le navigateur acceptera une réponse périmée provenant du cache dont la validité a expiré au cours de la dernière heure.

Les clients peuvent utiliser cet en-tête lorsque le serveur d’origine est hors service ou trop lent, et peuvent accepter des réponses mises en cache même si celles-ci sont un peu anciennes.

Notez que les principaux navigateurs ne prennent pas en charge les requêtes comportant max-stale.

`min-fresh`

La directive de requête min-fresh=N indique que le client autorise une réponse mise en cache dont la fraîcheur est d’au moins N secondes.

http

Cache-Control: min-fresh=600

Dans le cas ci-dessus, si la réponse avec Cache-Control: max-age=3600 a été mise en cache il y a 51 minutes, le cache ne pourrait pas réutiliser cette réponse.

Les clients peuvent utiliser cet en-tête lorsque l’utilisateur exige non seulement que la réponse soit récente, mais aussi qu’elle ne soit pas mise à jour pendant un certain temps.

Notez que les principaux navigateurs ne prennent pas en charge les requêtes comportant min-fresh.

`no-transform`

Même signification que celle de no-transform pour une réponse, mais pour une requête à la place.

`only-if-cached`

Le client indique qu’une réponse déjà mise en cache doit être renvoyée. Si un cache contient une réponse, même périmée, celle-ci sera renvoyée. Si aucune réponse mise en cache n’est disponible, une réponse 504 Gateway Timeout sera renvoyée.

`stale-if-error`

La directive de requête stale-if-error indique que le navigateur souhaite recevoir du contenu périmé en cas d’erreur de la part de n’importe quel serveur intermédiaire pour une origine particulière.
Cette fonctionnalité n’est prise en charge par aucun navigateur (voir Compatibilité avec les navigateurs).

Empêcher la mise en cache

Si vous ne souhaitez pas qu’une réponse soit mise en cache, utilisez la no-store directive.

http

Cache-Control: no-store

Notez que no-cache signifie « la réponse peut être mise en cache, mais ne doit pas être réutilisée avant validation » — cette directive ne sert donc pas à empêcher la mise en cache d’une réponse.

http

Cache-Control: no-cache

En théorie, en cas de conflit entre directives, c’est la directive la plus restrictive qui doit prévaloir. L’exemple ci-dessous n’a donc pratiquement aucun sens, car private, no-cache, max-age=0 et must-revalidate sont en conflit avec no-store.

http

# conflicted
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate

# equivalent to
Cache-Control: no-store

Mise en cache des ressources statiques avec « cache busting »

Lorsque vous générez des ressources statiques à l’aide de mécanismes de gestion des versions ou de hachage, l’ajout d’une version ou d’un hachage au nom de fichier ou à la chaîne de requête constitue un bon moyen de gérer la mise en cache.

Par exemple :

html




    
        
    
    			
			
	
	


































		
		We use cookies to ensure that we give you the best experience on our website. If you continue to use this site we will assume that you are happy with it.