Aller au contenu principal

5. Définitions des champs d'en-tête

Cette section définit la syntaxe et la sémantique des champs d'en-tête HTTP/1.1 liés à la mise en cache.

5.1. Age​

Le champ d'en-tête « Age » transmet l'estimation, par l'expéditeur, du temps écoulé depuis que la réponse a été générée ou validée avec succès sur le serveur d'origine. Les valeurs de Age sont calculées comme spécifié à la Section 4.2.3.

Age = delta-seconds

La valeur du champ Age est un entier non négatif représentant un temps en secondes (voir Section 1.2.1).

La présence d'un champ d'en-tête Age implique que la réponse n'a pas été générée ni validée par le serveur d'origine pour cette requête. Toutefois, l'absence de champ d'en-tête Age n'implique pas que le serveur d'origine ait été contacté, car la réponse peut avoir été reçue d'un cache HTTP/1.0 qui n'implémente pas Age.

5.2. Cache-Control​

Le champ d'en-tête « Cache-Control » sert à spécifier des directives pour les caches le long de la chaîne requête/réponse. Ces directives de cache sont unidirectionnelles, en ce sens que la présence d'une directive dans une requête n'implique pas que la même directive doive être donnée dans la réponse.

Un cache MUST obéir aux exigences des directives Cache-Control définies dans cette section. Voir la Section 5.2.3 pour des informations sur la façon dont les directives Cache-Control définies ailleurs sont traitées.

Note : Certains caches HTTP/1.0 peuvent ne pas implémenter Cache-Control.

Un mandataire, qu'il implémente ou non un cache, MUST transmettre les directives de cache dans les messages transférés, indépendamment de leur importance pour cette application, car les directives peuvent être applicables à tous les destinataires le long de la chaîne requête/réponse. Il n'est pas possible de cibler une directive vers un cache particulier.

Les directives de cache sont identifiées par un jeton, à comparer sans tenir compte de la casse, et comportent un argument facultatif, qui peut utiliser à la fois la syntaxe jeton et la syntaxe chaîne entre guillemets. Pour les directives définies ci-dessous qui définissent des arguments, les destinataires devraient accepter les deux formes, même si l'une est documentée comme préférable. Pour toute directive non définie par cette spécification, un destinataire MUST accepter les deux formes.

Cache-Control   = 1#cache-directive

cache-directive = token [ "=" ( token / quoted-string ) ]

Pour les directives de cache définies ci-dessous, aucun argument n'est défini (ni autorisé) sauf indication contraire.

5.2.1. Directives de cache de requête​

5.2.1.1. max-age​

Syntaxe de l'argument : delta-seconds (voir Section 1.2.1)

La directive de requête « max-age » indique que le client n'est pas disposé à accepter une réponse dont l'âge est supérieur au nombre de secondes spécifié. À moins que la directive de requête max-stale ne soit également présente, le client n'est pas disposé à accepter une réponse périmée.

Cette directive utilise la forme jeton de la syntaxe d'argument : par exemple 'max-age=5' et non 'max-age="5"'. Un expéditeur SHOULD NOT générer la forme chaîne entre guillemets.

5.2.1.2. max-stale​

Syntaxe de l'argument : delta-seconds (voir Section 1.2.1)

La directive de requête « max-stale » indique que le client est disposé à accepter une réponse ayant dépassé sa durée de fraîcheur. Si une valeur est attribuée à max-stale, le client est disposé à accepter une réponse ayant dépassé sa durée de fraîcheur d'au plus le nombre de secondes spécifié. Si aucune valeur n'est attribuée à max-stale, le client est disposé à accepter une réponse périmée de n'importe quel âge.

Cette directive utilise la forme jeton de la syntaxe d'argument : par exemple 'max-stale=10' et non 'max-stale="10"'. Un expéditeur SHOULD NOT générer la forme chaîne entre guillemets.

5.2.1.3. min-fresh​

Syntaxe de l'argument : delta-seconds (voir Section 1.2.1)

La directive de requête « min-fresh » indique que le client est disposé à accepter une réponse dont la durée de fraîcheur n'est pas inférieure à son âge courant plus le temps spécifié en secondes. Autrement dit, le client veut une réponse qui restera fraîche pendant au moins le nombre de secondes spécifié.

Cette directive utilise la forme jeton de la syntaxe d'argument : par exemple 'min-fresh=20' et non 'min-fresh="20"'. Un expéditeur SHOULD NOT générer la forme chaîne entre guillemets.

5.2.1.4. no-cache​

La directive de requête « no-cache » indique qu'un cache MUST NOT utiliser une réponse stockée pour satisfaire la requête sans validation réussie sur le serveur d'origine.

5.2.1.5. no-store​

La directive de requête « no-store » indique qu'un cache MUST NOT stocker aucune partie de cette requête ni d'aucune réponse à celle-ci. Cette directive s'applique à la fois aux caches privés et aux caches partagés. « MUST NOT stocker » dans ce contexte signifie que le cache MUST NOT stocker intentionnellement les informations dans un stockage non volatil, et MUST faire son possible pour retirer les informations du stockage volatil dès que possible après les avoir transmises.

Cette directive n'est PAS un mécanisme fiable ou suffisant pour garantir la confidentialité. En particulier, des caches malveillants ou compromis peuvent ne pas reconnaître ou ne pas obéir à cette directive, et les réseaux de communication peuvent être vulnérables à l'écoute clandestine.

Notez que si une requête contenant cette directive est satisfaite à partir d'un cache, la directive de requête no-store ne s'applique pas à la réponse déjà stockée.

5.2.1.6. no-transform​

La directive de requête « no-transform » indique qu'un intermédiaire (qu'il implémente ou non un cache) MUST NOT transformer la charge utile, comme défini à la Section 5.7.2 du [RFC7230].

5.2.1.7. only-if-cached​

La directive de requête « only-if-cached » indique que le client souhaite uniquement obtenir une réponse stockée. S'il reçoit cette directive, un cache SHOULD soit répondre en utilisant une réponse stockée compatible avec les autres contraintes de la requête, soit répondre avec un code d'état 504 (Gateway Timeout). Si un groupe de caches est exploité comme un système unifié avec une bonne connectivité interne, un cache membre MAY transmettre une telle requête au sein de ce groupe de caches.

5.2.2. Directives de cache de réponse​

5.2.2.1. must-revalidate​

La directive de réponse « must-revalidate » indique qu'une fois qu'elle est devenue périmée, un cache MUST NOT utiliser la réponse pour satisfaire des requêtes ultérieures sans validation réussie sur le serveur d'origine.

La directive must-revalidate est nécessaire pour prendre en charge un fonctionnement fiable de certaines fonctionnalités du protocole. En toutes circonstances, un cache MUST obéir à la directive must-revalidate ; en particulier, si un cache ne peut atteindre le serveur d'origine pour quelque raison que ce soit, il MUST générer une réponse 504 (Gateway Timeout).

La directive must-revalidate devrait être utilisée par les serveurs si et seulement si l'échec de la validation d'une requête portant sur la représentation pouvait entraîner un fonctionnement incorrect, tel qu'une transaction financière silencieusement non exécutée.

5.2.2.2. no-cache​

Syntaxe de l'argument : #field-name

La directive de réponse « no-cache » indique que la réponse MUST NOT être utilisée pour satisfaire une requête ultérieure sans validation réussie sur le serveur d'origine. Cela permet à un serveur d'origine d'empêcher un cache de l'utiliser pour satisfaire une requête sans le contacter, même pour des caches configurés pour envoyer des réponses périmées.

Si la directive de réponse no-cache spécifie un ou plusieurs field-name, un cache MAY alors utiliser la réponse pour satisfaire une requête ultérieure, sous réserve de toute autre restriction de mise en cache. Toutefois, les champs d'en-tête de la réponse portant le ou les field-name listés MUST NOT être envoyés dans la réponse à une requête ultérieure sans revalidation réussie auprès du serveur d'origine. Cela permet à un serveur d'origine d'empêcher la réutilisation de certains champs d'en-tête dans une réponse, tout en permettant encore la mise en cache du reste de la réponse.

Les field-name donnés ne sont pas limités à l'ensemble des champs d'en-tête définis par cette spécification. Les noms de champ sont insensibles à la casse.

Cette directive utilise la forme chaîne entre guillemets de la syntaxe d'argument. Un expéditeur SHOULD NOT générer la forme jeton (même si les guillemets semblent ne pas être nécessaires pour des listes à une seule entrée).

Note : bien qu'elle ait été rétroportée dans de nombreuses implémentations, certains caches HTTP/1.0 ne reconnaîtront pas ou n'obéiront pas à cette directive. De plus, les directives de réponse no-cache comportant des field-name sont souvent traitées par les caches comme si une directive no-cache non qualifiée avait été reçue ; autrement dit, le traitement spécial de la forme qualifiée n'est pas largement implémenté.

5.2.2.3. no-store​

La directive de réponse « no-store » indique qu'un cache MUST NOT stocker aucune partie de la requête immédiate ni de la réponse. Cette directive s'applique à la fois aux caches privés et aux caches partagés. « MUST NOT stocker » dans ce contexte signifie que le cache MUST NOT stocker intentionnellement les informations dans un stockage non volatil, et MUST faire son possible pour retirer les informations du stockage volatil dès que possible après les avoir transmises.

Cette directive n'est PAS un mécanisme fiable ou suffisant pour garantir la confidentialité. En particulier, des caches malveillants ou compromis peuvent ne pas reconnaître ou ne pas obéir à cette directive, et les réseaux de communication peuvent être vulnérables à l'écoute clandestine.

5.2.2.4. no-transform​

La directive de réponse « no-transform » indique qu'un intermédiaire (qu'il implémente ou non un cache) MUST NOT transformer la charge utile, comme défini à la Section 5.7.2 du [RFC7230].

5.2.2.5. public​

La directive de réponse « public » indique que tout cache MAY stocker la réponse, même si celle-ci serait normalement non cacheable ou cacheable uniquement dans un cache privé. (Voir la Section 3.2 pour des détails supplémentaires concernant l'utilisation de public en réponse à une requête contenant Authorization, et la Section 3 pour des détails sur la façon dont public affecte les réponses qui ne seraient normalement pas stockées, parce que leurs codes d'état ne sont pas définis comme cacheables par défaut ; voir Section 4.2.2.)

5.2.2.6. private​

Syntaxe de l'argument : #field-name

La directive de réponse « private » indique que le message de réponse est destiné à un seul utilisateur et MUST NOT être stocké par un cache partagé. Un cache privé MAY stocker la réponse et la réutiliser pour des requêtes ultérieures, même si la réponse serait normalement non cacheable.

Si la directive de réponse private spécifie un ou plusieurs field-name, cette exigence se limite aux valeurs de champ associées aux champs d'en-tête de réponse listés. Autrement dit, un cache partagé MUST NOT stocker le ou les field-name spécifiés, tandis qu'il MAY stocker le reste du message de réponse.

Les field-name donnés ne sont pas limités à l'ensemble des champs d'en-tête définis par cette spécification. Les noms de champ sont insensibles à la casse.

Cette directive utilise la forme chaîne entre guillemets de la syntaxe d'argument. Un expéditeur SHOULD NOT générer la forme jeton (même si les guillemets semblent ne pas être nécessaires pour des listes à une seule entrée).

Note : cet emploi du mot « private » ne contrôle que l'endroit où la réponse peut être stockée ; il ne peut pas garantir la confidentialité du contenu du message. De plus, les directives de réponse private comportant des field-name sont souvent traitées par les caches comme si une directive private non qualifiée avait été reçue ; autrement dit, le traitement spécial de la forme qualifiée n'est pas largement implémenté.

5.2.2.7. proxy-revalidate​

La directive de réponse « proxy-revalidate » a la même signification que la directive de réponse must-revalidate, sauf qu'elle ne s'applique pas aux caches privés.

5.2.2.8. max-age​

Syntaxe de l'argument : delta-seconds (voir Section 1.2.1)

La directive de réponse « max-age » indique que la réponse doit être considérée comme périmée dès que son âge dépasse le nombre de secondes spécifié.

Cette directive utilise la forme jeton de la syntaxe d'argument : par exemple 'max-age=5' et non 'max-age="5"'. Un expéditeur SHOULD NOT générer la forme chaîne entre guillemets.

5.2.2.9. s-maxage​

Syntaxe de l'argument : delta-seconds (voir Section 1.2.1)

La directive de réponse « s-maxage » indique que, dans les caches partagés, l'âge maximal spécifié par cette directive supplante l'âge maximal spécifié par la directive max-age ou par le champ d'en-tête Expires. La directive s-maxage implique également la sémantique de la directive de réponse proxy-revalidate.

Cette directive utilise la forme jeton de la syntaxe d'argument : par exemple 's-maxage=10' et non 's-maxage="10"'. Un expéditeur SHOULD NOT générer la forme chaîne entre guillemets.

5.2.3. Extensions de contrôle de cache​

Le champ d'en-tête Cache-Control peut être étendu au moyen d'un ou plusieurs jetons cache-extension, chacun avec une valeur facultative. Un cache MUST ignorer les directives de cache non reconnues.

Les extensions informationnelles (celles qui n'exigent pas de changement du comportement du cache) peuvent être ajoutées sans modifier la sémantique des autres directives.

Les extensions comportementales sont conçues pour fonctionner en agissant comme des modificateurs de la base existante de directives de cache. La nouvelle directive et l'ancienne directive sont toutes deux fournies, de sorte que les applications qui ne comprennent pas la nouvelle directive adopteront par défaut le comportement spécifié par l'ancienne directive, et celles qui comprennent la nouvelle directive la reconnaîtront comme modifiant les exigences associées à l'ancienne directive. De cette façon, des extensions aux directives de contrôle de cache existantes peuvent être apportées sans casser les caches déployés.

Par exemple, considérons une nouvelle directive de réponse hypothétique appelée « community » qui agit comme modificateur de la directive private : outre les caches privés, tout cache partagé uniquement par les membres de la communauté nommée est autorisé à mettre la réponse en cache. Un serveur d'origine souhaitant permettre à la communauté UCI d'utiliser une réponse par ailleurs privée dans son ou ses caches partagés pourrait le faire en incluant

Cache-Control: private, community="UCI"

Un cache qui reconnaît une telle extension de cache community pourrait élargir son comportement conformément à cette extension. Un cache qui ne reconnaît pas l'extension de cache community l'ignorerait et s'en tiendrait à la directive private.

5.3. Expires​

Le champ d'en-tête « Expires » donne la date/heure après laquelle la réponse est considérée comme périmée. Voir la Section 4.2 pour une discussion plus approfondie du modèle de fraîcheur.

La présence d'un champ Expires n'implique pas que la ressource d'origine changera ou cessera d'exister à cet instant, avant ou après celui-ci.

La valeur de Expires est un horodatage HTTP-date, tel que défini à la Section 7.1.1.1 du [RFC7231].

Expires = HTTP-date

Par exemple

Expires: Thu, 01 Dec 1994 16:00:00 GMT

Un destinataire de cache MUST interpréter les formats de date invalides, en particulier la valeur « 0 », comme représentant un instant dans le passé (c'est-à-dire « déjà expiré »).

Si une réponse comporte un champ Cache-Control avec la directive max-age (Section 5.2.2.8), un destinataire MUST ignorer le champ Expires. De même, si une réponse comporte la directive s-maxage (Section 5.2.2.9), un destinataire de cache partagé MUST ignorer le champ Expires. Dans ces deux cas, la valeur de Expires n'est destinée qu'aux destinataires qui n'ont pas encore implémenté le champ Cache-Control.

Un serveur d'origine dépourvu d'horloge MUST NOT générer de champ Expires, sauf si sa valeur représente un instant fixe dans le passé (toujours expiré) ou si sa valeur a été associée à la ressource par un système ou un utilisateur disposant d'une horloge fiable.

Historiquement, HTTP exigeait que la valeur du champ Expires ne dépasse pas un an dans le futur. Bien que des durées de fraîcheur plus longues ne soient plus interdites, des valeurs extrêmement grandes se sont révélées problématiques (par exemple, des débordements d'horloge dus à l'emploi d'entiers de 32 bits pour les valeurs de temps), et de nombreux caches évinceront une réponse bien plus tôt que cela.

5.4. Pragma​

Le champ d'en-tête « Pragma » permet une compatibilité descendante avec les caches HTTP/1.0, afin que les clients puissent spécifier une requête « no-cache » qu'ils comprendront (Cache-Control n'ayant été défini qu'à partir de HTTP/1.1). Lorsque le champ d'en-tête Cache-Control est également présent et compris dans une requête, Pragma est ignoré.

Dans HTTP/1.0, Pragma était défini comme un champ extensible pour des directives spécifiées par l'implémentation à l'intention des destinataires. Cette spécification déprécie de telles extensions afin d'améliorer l'interopérabilité.

Pragma           = 1#pragma-directive
pragma-directive = "no-cache" / extension-pragma
extension-pragma = token [ "=" ( token / quoted-string ) ]

Lorsque le champ d'en-tête Cache-Control n'est pas présent dans une requête, les caches MUST considérer la pragma-directive de requête no-cache comme ayant le même effet que si « Cache-Control: no-cache » était présent (voir Section 5.2.1).

Lors de l'envoi d'une requête no-cache, un client devrait inclure à la fois les directives pragma et cache-control, sauf si Cache-Control: no-cache est délibérément omis afin de cibler d'autres directives de réponse Cache-Control vers les caches HTTP/1.1. Par exemple :

GET / HTTP/1.1
Host: www.example.com
Cache-Control: max-age=30
Pragma: no-cache

contraindra les caches HTTP/1.1 à servir une réponse vieille de 30 secondes au plus, tout en empêchant les implémentations qui ne comprennent pas Cache-Control de servir une réponse mise en cache.

Note : Comme la signification de « Pragma: no-cache » dans les réponses n'est pas spécifiée, il ne fournit pas un remplacement fiable de « Cache-Control: no-cache » dans celles-ci.

5.5. Warning​

Le champ d'en-tête « Warning » sert à transporter des informations supplémentaires sur l'état ou la transformation d'un message qui pourraient ne pas être reflétées dans le code d'état. Ces informations servent typiquement à avertir d'une possible incorrection introduite par des opérations de mise en cache ou par des transformations appliquées à la charge utile du message.

Les avertissements peuvent être utilisés à d'autres fins, liées ou non à la mise en cache. L'emploi d'un avertissement, plutôt que d'un code d'état d'erreur, distingue ces réponses de véritables échecs.

Les champs d'en-tête Warning peuvent en général être appliqués à tout message, cependant certains warn-code sont spécifiques aux caches et ne peuvent être appliqués qu'à des messages de réponse.

Warning       = 1#warning-value

warning-value = warn-code SP warn-agent SP warn-text
[ SP warn-date ]

warn-code = 3DIGIT
warn-agent = ( uri-host [ ":" port ] ) / pseudonym
; the name or pseudonym of the server adding
; the Warning header field, for use in debugging
; a single "-" is recommended when agent unknown
warn-text = quoted-string
warn-date = DQUOTE HTTP-date DQUOTE

Plusieurs avertissements peuvent être générés dans une réponse (soit par le serveur d'origine, soit par un cache), y compris plusieurs avertissements portant le même numéro de warn-code et ne différant que par le warn-text.

Un agent utilisateur qui reçoit un ou plusieurs champs d'en-tête Warning SHOULD informer l'utilisateur du plus grand nombre possible d'entre eux, dans l'ordre où ils apparaissent dans la réponse. Les expéditeurs qui génèrent plusieurs champs d'en-tête Warning sont encouragés à les ordonner en gardant ce comportement de l'agent utilisateur à l'esprit. Un expéditeur qui génère de nouveaux champs d'en-tête Warning MUST les ajouter après tout champ d'en-tête Warning existant.

Les avertissements se voient attribuer des warn-code à trois chiffres. Le premier chiffre indique si le Warning doit être supprimé d'une réponse stockée après validation :

  • Les warn-code 1xx décrivent l'état de fraîcheur ou de validation de la réponse, et doivent donc être supprimés par un cache après validation (MUST). Ils ne peuvent être générés par un cache que lors de la validation d'une entrée mise en cache, et ne doivent être générés dans aucune autre situation (MUST NOT).

  • Les warn-code 2xx décrivent un aspect de la représentation qui n'est pas rectifié par une validation (par exemple, une compression avec pertes de la représentation) et ils ne doivent pas être supprimés par un cache après validation (MUST NOT), sauf si une réponse complète est envoyée, auquel cas ils doivent l'être (MUST).

Si un expéditeur génère un ou plusieurs warn-code 1xx dans un message destiné à un destinataire connu pour n'implémenter que HTTP/1.0, l'expéditeur MUST inclure dans chaque warning-value correspondante un warn-date qui correspond au champ d'en-tête Date du message. Par exemple :

HTTP/1.1 200 OK
Date: Sat, 25 Aug 2012 23:34:45 GMT
Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"

Les avertissements sont accompagnés d'un warn-text décrivant l'erreur, par exemple pour la journalisation. Il est purement indicatif, et son contenu n'affecte pas l'interprétation du warn-code.

Si un destinataire qui utilise, évalue ou affiche des champs d'en-tête Warning reçoit un warn-date différent de la valeur Date du même message, le destinataire MUST exclure le warning-value contenant ce warn-date avant de stocker, transmettre ou utiliser le message. Cela permet aux destinataires d'exclure les warning-value qui ont été conservés de manière inappropriée après une validation de cache. Si tous les warning-value sont exclus, le destinataire MUST exclure également le champ d'en-tête Warning.

Les warn-code suivants sont définis par cette spécification, chacun avec un warn-text recommandé en anglais et une description de sa signification. La procédure de définition de warn-code supplémentaires est décrite à la Section 7.2.1.

5.5.1. Warning: 110 - "Response is Stale"​

Un cache SHOULD générer ceci chaque fois que la réponse envoyée est périmée.

5.5.2. Warning: 111 - "Revalidation Failed"​

Un cache SHOULD générer ceci lorsqu'il envoie une réponse périmée parce qu'une tentative de validation de la réponse a échoué, faute de pouvoir atteindre le serveur.

5.5.3. Warning: 112 - "Disconnected Operation"​

Un cache SHOULD générer ceci s'il est intentionnellement déconnecté du reste du réseau pendant une certaine période.

5.5.4. Warning: 113 - "Heuristic Expiration"​

Un cache SHOULD générer ceci s'il a choisi de manière heuristique une durée de fraîcheur supérieure à 24 heures et que l'âge de la réponse est supérieur à 24 heures.

5.5.5. Warning: 199 - "Miscellaneous Warning"​

Le texte d'avertissement peut contenir des informations arbitraires à présenter à un utilisateur humain ou à journaliser. Un système recevant cet avertissement MUST NOT entreprendre d'action automatisée, hormis présenter l'avertissement à l'utilisateur.

5.5.6. Warning: 214 - "Transformation Applied"​

Ce code Warning MUST être ajouté par un mandataire s'il applique une transformation quelconque à la représentation, telle que la modification du codage de contenu, du type de média, ou la modification des données de représentation, sauf si ce code Warning apparaît déjà dans la réponse.

5.5.7. Warning: 299 - "Miscellaneous Persistent Warning"​

Le texte d'avertissement peut contenir des informations arbitraires à présenter à un utilisateur humain ou à journaliser. Un système recevant cet avertissement MUST NOT entreprendre d'action automatisée.