5. Définitions des champs d'en-tête (Header Field Definitions)

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

5.1. Age

Le champ d'en-tête "Age" transmet l'estimation de l'expéditeur du temps écoulé depuis que la réponse a été générée ou validée avec succès au serveur d'origine. Les valeurs Age sont calculées comme spécifié dans la section 4.2.3.

Age = delta-seconds

La valeur du champ Age est un entier non négatif représentant le 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 ou validée par le serveur d'origine pour cette requête. Cependant, l'absence d'un champ d'en-tête Age n'implique pas que l'origine a été contactée, car la réponse pourrait 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" est utilisé pour 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 DOIT 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 proxy, qu'il implémente ou non un cache, DOIT transmettre les directives de cache dans les messages transmis, quelle que soit leur importance pour cette application, car les directives pourraient ê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 spécifique.

Les directives de cache sont identifiées par un jeton, à comparer sans tenir compte de la casse, et ont un argument optionnel qui peut utiliser à la fois la syntaxe de jeton et de 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érée. Pour toute directive non définie par cette spécification, un destinataire DOIT 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 Cache-Control de requête (Request Cache-Control Directives)

5.2.1.1. max-age

Syntaxe d'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 ex., 'max-age=5' et non 'max-age="5"'. Un expéditeur NE DEVRAIT PAS générer la forme chaîne entre guillemets.

5.2.1.2. max-stale

Syntaxe d'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 qui a dépassé sa durée de vie de fraîcheur. Si une valeur est assignée à max-stale, alors le client est disposé à accepter une réponse qui a dépassé sa durée de vie de fraîcheur d'au maximum le nombre de secondes spécifié. Si aucune valeur n'est assignée à max-stale, alors le client est disposé à accepter une réponse périmée de tout âge.

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

5.2.1.3. min-fresh

Syntaxe d'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 vie de fraîcheur n'est pas inférieure à son âge actuel plus le temps spécifié en secondes. C'est-à-dire que le client souhaite 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 ex., 'min-fresh=20' et non 'min-fresh="20"'. Un expéditeur NE DEVRAIT PAS 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 NE DOIT PAS 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 NE DOIT PAS stocker une quelconque partie de cette requête ou de toute réponse à celle-ci. Cette directive s'applique aux caches privés et partagés. "NE DOIT PAS stocker" dans ce contexte signifie que le cache NE DOIT PAS stocker intentionnellement les informations dans un stockage non volatile, et DOIT faire un effort de bonne foi pour supprimer les informations du stockage volatile 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, les caches malveillants ou compromis pourraient ne pas reconnaître ou obéir à cette directive, et les réseaux de communication pourraient ê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) NE DOIT PAS transformer le contenu, comme défini dans la section 5.7.2 de [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 DEVRAIT soit répondre en utilisant une réponse stockée qui est cohérente avec les autres contraintes de la requête, soit répondre avec un code d'état 504 (Gateway Timeout). Si un groupe de caches fonctionne comme un système unifié avec une bonne connectivité interne, un cache membre PEUT transmettre une telle requête au sein de ce groupe de caches.

5.2.2. Directives Cache-Control de réponse (Response Cache-Control Directives)

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 NE DOIT PAS 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 supporter le fonctionnement fiable de certaines fonctionnalités du protocole. Dans toutes les circonstances, un cache DOIT obéir à la directive must-revalidate ; en particulier, si un cache ne peut pas atteindre le serveur d'origine pour quelque raison que ce soit, il DOIT 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 validation d'une requête sur la représentation pourrait entraîner un fonctionnement incorrect, comme une transaction financière exécutée silencieusement.

5.2.2.2. no-cache

Syntaxe d'argument :

#field-name

La directive de réponse "no-cache" indique que la réponse NE DOIT PAS ê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 par des caches qui ont été configurés pour envoyer des réponses périmées.

Si la directive de réponse no-cache spécifie un ou plusieurs noms de champs, alors un cache PEUT utiliser la réponse pour satisfaire une requête ultérieure, sous réserve de toute autre restriction sur la mise en cache. Cependant, tous les champs d'en-tête de la réponse qui ont le(s) nom(s) de champ listé(s) NE DOIVENT PAS être envoyés dans la réponse à une requête ultérieure sans revalidation réussie avec le 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 la mise en cache du reste de la réponse.

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

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

Note : Bien qu'elle ait été rétro-portée vers de nombreuses implémentations, certains caches HTTP/1.0 ne reconnaissent pas ou n'obéissent pas à cette directive. De plus, la directive de réponse no-cache avec des noms de champs est généralement traitée par les caches comme si une directive no-cache non qualifiée était reçue ; c'est-à-dire que 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 NE DOIT PAS stocker une quelconque partie de la requête immédiate ou de la réponse. Cette directive s'applique aux caches privés et partagés. "NE DOIT PAS stocker" dans ce contexte signifie que le cache NE DOIT PAS stocker intentionnellement les informations dans un stockage non volatile, et DOIT faire un effort de bonne foi pour supprimer les informations du stockage volatile 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, les caches malveillants ou compromis pourraient ne pas reconnaître ou obéir à cette directive, et les réseaux de communication pourraient ê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) NE DOIT PAS transformer le contenu, comme défini dans la section 5.7.2 de [RFC7230].

5.2.2.5. public

La directive de réponse "public" indique que tout cache PEUT stocker la réponse, même si la réponse serait normalement non cacheable ou cacheable uniquement dans un cache privé. (Voir la section 3.2 pour des détails supplémentaires relatifs à 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, en raison de leurs codes d'état qui ne sont pas définis comme cacheables par défaut ; voir section 4.2.2.)

5.2.2.6. private

Syntaxe d'argument :

#field-name

La directive de réponse "private" indique que le message de réponse est destiné à un seul utilisateur et NE DOIT PAS être stocké par un cache partagé. Un cache privé PEUT 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 noms de champs, cette exigence est limitée aux valeurs de champs associées aux champs d'en-tête de réponse listés. C'est-à-dire qu'un cache partagé NE DOIT PAS stocker le(s) nom(s) de champ spécifié(s), alors qu'il PEUT stocker le reste du message de réponse.

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

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

Note : Cette utilisation de "private" contrôle uniquement l'endroit où la réponse peut être stockée ; elle ne peut pas garantir la confidentialité du contenu du message. De plus, la directive de réponse private avec des noms de champs est généralement traitée par les caches comme si une directive private non qualifiée était reçue ; c'est-à-dire que 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 d'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 après que son âge soit supérieur au nombre de secondes spécifié.

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

5.2.2.9. s-maxage

Syntaxe d'argument :

delta-seconds (voir section 1.2.1)

La directive de réponse "s-maxage" indique que, dans les caches partagés, l'âge maximum spécifié par cette directive remplace l'âge maximum spécifié par la directive max-age ou 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 ex., 's-maxage=10' et non 's-maxage="10"'. Un expéditeur NE DEVRAIT PAS générer la forme chaîne entre guillemets.

5.2.3. Extensions Cache-Control (Cache Control Extensions)

Le champ d'en-tête Cache-Control peut être étendu par l'utilisation d'un ou plusieurs jetons d'extension de cache, chacun avec une valeur optionnelle. Un cache DOIT ignorer les directives de cache non reconnues.

Les extensions informatives (celles qui ne nécessitent pas de changement dans le 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érez une nouvelle directive de réponse hypothétique appelée "community" qui agit comme un modificateur de la directive private : en plus des caches privés, tout cache qui est partagé uniquement par les membres de la communauté nommée est autorisé à mettre en cache la réponse. Un serveur d'origine souhaitant permettre à la communauté UCI d'utiliser une réponse autrement privée dans leur(s) cache(s) partagé(s) pourrait le faire en incluant :

Cache-Control: private, community="UCI"

Un cache qui reconnaît une telle extension de cache communautaire pourrait élargir son comportement conformément à cette extension. Un cache qui ne reconnaît pas l'extension de cache communautaire l'ignorerait et adhérerait à 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 originale changera ou cessera d'exister à, avant ou après ce moment.

La valeur Expires est un horodatage HTTP-date, comme défini dans la section 7.1.1.1 de [RFC7231].

Expires = HTTP-date

Par exemple :

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

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

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

Un serveur d'origine sans horloge NE DOIT PAS générer un champ Expires à moins que sa valeur ne représente un moment fixe dans le passé (toujours expiré) ou que sa valeur n'ait été associée à la ressource par un système ou un utilisateur avec une horloge fiable.

Historiquement, HTTP exigeait que la valeur du champ Expires ne soit pas supérieure à un an dans le futur. Bien que des durées de vie de fraîcheur plus longues ne soient plus interdites, il a été démontré que des valeurs extrêmement grandes causent des problèmes (par ex., débordements d'horloge dus à l'utilisation d'entiers 32 bits pour les valeurs temporelles), et de nombreux caches expulseront une réponse bien plus tôt que cela.

5.4. Pragma

Le champ d'en-tête "Pragma" permet la rétrocompatibilité avec les caches HTTP/1.0, de sorte que les clients puissent spécifier une requête "no-cache" qu'ils comprendront (car Cache-Control n'a été défini qu'avec 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é.

En HTTP/1.0, Pragma était défini comme un champ extensible pour les directives spécifiques à l'implémentation pour les destinataires. Cette spécification déprécie de telles extensions pour 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 DOIVENT considérer la directive 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, à moins que Cache-Control: no-cache ne soit intentionnellement omis pour cibler d'autres directives de réponse Cache-Control sur 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 pas plus ancienne que 30 secondes, tout en empêchant les implémentations qui ne comprennent pas Cache-Control de servir une réponse mise en cache.

Note : Parce que la signification de "Pragma: no-cache" dans les réponses n'est pas spécifiée, elle ne peut pas fournir un substitut fiable pour "Cache-Control: no-cache" pour elles.

5.5. Warning

Le champ d'en-tête "Warning" est utilisé pour transporter des informations supplémentaires sur le statut ou la transformation d'un message qui pourraient ne pas être reflétées dans le code d'état. Ces informations sont généralement utilisées pour avertir d'une possible inexactitude introduite par des opérations de mise en cache ou des transformations appliquées au contenu du message.

Les avertissements peuvent être utilisés à d'autres fins, liées au cache ou autres. L'utilisation d'un avertissement, plutôt qu'un code d'état d'erreur, distingue ces réponses des véritables échecs.

Les champs d'en-tête Warning peuvent en général être appliqués à tout message, cependant certains codes d'avertissement sont spécifiques aux caches et ne peuvent être appliqués qu'aux 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
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 avec le même numéro de code d'avertissement qui ne diffèrent que dans le texte d'avertissement.

Un agent utilisateur qui reçoit un ou plusieurs champs d'en-tête Warning DEVRAIT informer l'utilisateur d'autant d'entre eux que possible, 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 tenant compte de ce comportement de l'agent utilisateur. Un expéditeur qui génère de nouveaux champs d'en-tête Warning DOIT les ajouter après tous les champs d'en-tête Warning existants.

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

• Les codes d'avertissement 1xx décrivent le statut de fraîcheur ou de validation de la réponse, et ils DOIVENT donc être supprimés par un cache après validation. Ils ne peuvent être générés que par un cache lors de la validation d'une entrée de cache, et NE DOIVENT PAS être générés dans toute autre situation.

• Les codes d'avertissement 2xx décrivent un aspect de la représentation qui n'est pas rectifié par une validation (par exemple, une compression avec perte de la représentation) et ils NE DOIVENT PAS être supprimés par un cache après validation, sauf si une réponse complète est envoyée, auquel cas ils DOIVENT l'être.

Si un expéditeur génère un ou plusieurs codes d'avertissement 1xx dans un message à envoyer à un destinataire connu pour implémenter uniquement HTTP/1.0, l'expéditeur DOIT inclure dans chaque valeur d'avertissement correspondante une date d'avertissement qui correspond au champ d'en-tête Date dans le 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 ont un texte d'avertissement accompagnant qui décrit l'erreur, par ex., pour la journalisation. Il n'est que consultatif, et son contenu n'affecte pas l'interprétation du code d'avertissement.

Si un destinataire qui utilise, évalue ou affiche des champs d'en-tête Warning reçoit une date d'avertissement différente de la valeur Date dans le même message, le destinataire DOIT exclure la valeur d'avertissement contenant cette date d'avertissement avant de stocker, transmettre ou utiliser le message. Cela permet aux destinataires d'exclure les valeurs d'avertissement qui ont été incorrectement conservées après une validation de cache. Si toutes les valeurs d'avertissement sont exclues, le destinataire DOIT également exclure le champ d'en-tête Warning.

Les codes d'avertissement suivants sont définis par cette spécification, chacun avec un texte d'avertissement recommandé en anglais et une description de sa signification. La procédure de définition de codes d'avertissement supplémentaires est décrite dans la section 7.2.1.

5.5.1. Warning: 110 - "Response is Stale"

Un cache DEVRAIT 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 DEVRAIT générer ceci lors de l'envoi d'une réponse périmée parce qu'une tentative de validation de la réponse a échoué, en raison d'une incapacité à atteindre le serveur.

5.5.3. Warning: 112 - "Disconnected Operation"

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

5.5.4. Warning: 113 - "Heuristic Expiration"

Un cache DEVRAIT générer ceci s'il a heuristiquement choisi une durée de vie 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 inclure des informations arbitraires à présenter à un utilisateur humain ou à journaliser. Un système recevant cet avertissement NE DOIT PAS prendre d'action automatisée, à part présenter l'avertissement à l'utilisateur.

5.5.6. Warning: 214 - "Transformation Applied"

Ce code d'avertissement DOIT être ajouté par un proxy s'il applique une transformation à la représentation, comme changer le codage de contenu, le type de média ou modifier les données de représentation, sauf si ce code d'avertissement apparaît déjà dans la réponse.

5.5.7. Warning: 299 - "Miscellaneous Persistent Warning"

Le texte d'avertissement peut inclure des informations arbitraires à présenter à un utilisateur humain ou à journaliser. Un système recevant cet avertissement NE DOIT PAS prendre d'action automatisée.