Définissez Vary sur les noms des en-têtes de requête que votre serveur utilise pour choisir la représentation d’une page publique. Sur un Mac, testez un en-tête à la fois, comparez le document et les métadonnées renvoyés, puis vérifiez la réponse par défaut avant de modifier la configuration.

Ce guide s’adresse aux personnes qui gèrent un document public et vérifient sa diffusion depuis le Terminal d’un Mac. L’exemple présenté est un « Guide des formes » synthétique, disponible en HTML ou en texte brut à une seule URL. L’objectif est d’identifier les paramètres réellement utilisés pour le choix, de configurer l’en-tête de réponse correspondant et de vérifier le résultat.

Que doit contenir l’en-tête Vary d’une page ?

Vary indique les champs de requête susceptibles d’influer sur le choix de la représentation, en plus de la méthode de requête et de l’URL cible. Ses valeurs sont des noms d’en-tête, tels que Accept, et non les types de média demandés. Il décrit le comportement de sélection ; l’ajouter ne met pas en œuvre ce comportement. RFC 9110 : Sémantique HTTP, section 12.5.5.

Par exemple, si le serveur choisit le HTML ou le texte brut à l’aide de Accept, le champ de réponse pertinent est Vary: Accept. Si une couche de diffusion choisit également entre une sortie compressée et non compressée à l’aide de Accept-Encoding, conservez aussi cette dimension : Vary: Accept, Accept-Encoding. Ce sont des exemples conditionnels, et non une configuration universelle pour toutes les pages. Négociation de contenu.

La question pratique est la suivante : une réponse mise en cache, choisie pour une requête, pourrait-elle ne pas convenir à une autre parce que cet en-tête a changé ? La mise en cache HTTP exige que les champs indiqués correspondent avant qu’une réponse soit réutilisée sans revalidation. L’absence d’un champ indiqué correspond à l’absence de ce même champ dans une autre requête, et non à sa présence. RFC 9111 : Mise en cache HTTP, section 4.1.

Commencez par dresser un inventaire des critères de sélection. Vérifiez les règles de sélection des documents de l’application et les éventuelles transformations de réponse appliquées ensuite. Un résultat différent constitue un indice utile, mais deux requêtes qui renvoient le même résultat ne permettent pas d’établir qu’un en-tête est sans effet pour toutes les valeurs prises en charge.

Établissez une matrice de requêtes avant toute modification

Pour le Guide des formes synthétique, supposons que le comportement attendu soit de renvoyer du HTML pour une préférence HTML, du texte brut pour une préférence de texte brut, et du HTML lorsque Accept est absent. Les deux versions contiennent les mêmes informations neutres : « Cercle, carré, triangle ». Il s’agit d’exigences illustratives, et non d’observations faites sur un site publié.

Test Paramètre de la requête Résultat attendu Éléments à inspecter
HTML Accept: text/html Document HTML Corps, Content-Type, Vary
Texte brut Accept: text/plain Document en texte brut Corps, Content-Type, Vary
Par défaut Aucun champ Accept Document HTML Sélection par défaut et Vary
Répétition HTML après le texte brut Document HTML à nouveau L’incidence éventuelle de la variante précédente sur la diffusion
Entrée non utilisée Modifier un en-tête absent des règles de sélection Même représentation sélectionnée La nécessité d’examiner cet en-tête

Gardez la compression inchangée lors de la première comparaison. Sinon, une différence d’octets pourrait provenir de la compression plutôt que d’un document différent. Examinez d’abord le choix du format, puis la compression séparément. Cette distinction découle des rôles distincts de Accept et Accept-Encoding. Négociation de contenu.

Consignez les différences significatives au lieu de vous fier uniquement à la taille du fichier. Dans cet exemple, la réponse en texte brut doit contenir les noms des formes sans balisage HTML, et son type de média doit indiquer le texte brut. Un horodatage généré qui change nécessiterait une vérification avant de considérer chaque différence d’octets comme une nouvelle variante.

Cette matrice est un outil de diagnostic, pas une suite complète de tests de négociation. Une fois les cas de base fonctionnels, ajoutez les préférences mixtes et les valeurs de qualité réellement prises en charge par votre page. Une requête portant sur un seul type ne permet pas de tester toutes les branches d’un algorithme de sélection.

Capturez des réponses comparables dans le Terminal du Mac

Vous avez besoin d’un document public de test contenant du matériel synthétique, de son URL HTTPS finale et d’un Mac sur lequel bash et curl sont disponibles. L’exemple suppose que le document de test prend déjà en charge le comportement HTML/texte brut décrit ci-dessus. Il ne crée pas, ne téléverse pas et ne publie pas ce document.

Ouvrez Terminal et collez le bloc complet ci-dessous. Saisissez l’URL de votre document synthétique lorsque vous y êtes invité. Le script crée un nouveau répertoire de rapport temporaire et conserve le corps de chaque réponse à côté de ses en-têtes ; il n’écrase pas un rapport antérieur.

bash <<'BASH'
set -eu

printf 'Public synthetic page URL: ' > /dev/tty
IFS= read -r page_url < /dev/tty

case "$page_url" in
  https://*) ;;
  *) printf 'Enter an HTTPS URL.\n' >&2; exit 1 ;;
esac

report_dir=$(mktemp -d "${TMPDIR:-/tmp}/vary-check.XXXXXX")
printf 'Report directory: %s\n' "$report_dir"

for sample in html plain absent html-again; do
  case "$sample" in
    html|html-again) accept_header='Accept: text/html' ;;
    plain) accept_header='Accept: text/plain' ;;
    absent) accept_header='Accept:' ;;
  esac

  curl --disable --silent --show-error --fail \
    --connect-timeout 5 --max-time 20 \
    --header "$accept_header" \
    --header 'Accept-Encoding: identity' \
    --dump-header "$report_dir/$sample.headers" \
    --output "$report_dir/$sample.body" \
    --url "$page_url"
done

printf 'Finished. Responses saved in: %s\n' "$report_dir"
BASH

Ici, --header fournit le champ de requête contrôlé, et Accept: supprime le champ Accept généré en interne par curl. --dump-header et --output enregistrent séparément les en-têtes et les corps. Les limites de temps de connexion et de transfert encadrent chaque requête. Ces options sont documentées dans le manuel de curl.

Le script s’arrête lorsque curl signale un échec de transfert ou une erreur HTTP couverte par --fail. Examinez le répertoire indiqué avant de réessayer : les captures précédentes peuvent subsister, et un transfert échoué peut laisser des fichiers incomplets. Le script ne suit volontairement pas les redirections ; vérifiez donc la ligne d’état dans chaque fichier d’en-têtes. Si vous avez capturé une redirection, utilisez l’URL finale du document et créez un nouveau rapport. Manuel de curl.

Ouvrez dans le Finder le répertoire de rapport en utilisant le chemin affiché par le script. Inspectez les fichiers dans un éditeur de texte brut. Comparez html.body avec plain.body, puis html.body avec html-again.body. Inspectez absent.headers aussi soigneusement que les réponses correspondant à une préférence explicite.

Considérez les résultats enregistrés comme des observations issues de cette séquence de requêtes. Ils ne prouvent pas qu’un cache partagé a stocké quoi que ce soit. Pour tester la réutilisation du cache, répétez la séquence par le chemin de diffusion prévu et dans les conditions documentées permettant la mise en cache, puis inversez également l’ordre afin de commencer par le texte brut.

Appliquez le résultat à la couche qui produit la réponse

Pour le Guide des formes illustratif, les éléments recueillis sur le choix du format doivent confirmer que Accept est un champ de sélection. Configurez-le à l’endroit où la réponse HTTP est générée ou finalisée. Si une autre couche fournit déjà un membre Vary nécessaire, conservez-le lors de l’ajout du membre relatif au choix du format. La liste finale doit décrire le comportement de sélection combiné. RFC 9110 : Sémantique HTTP.

Voici un fragment d’en-tête de réponse pour l’exemple où le choix du format et la négociation de la compression sont tous deux actifs. Il ne s’agit ni d’une réponse HTTP complète ni d’un fichier de configuration de serveur.

Vary: Accept, Accept-Encoding

Utilisez la même liste Vary prévue pour les variantes négociées et la réponse par défaut, et conservez-la dans les réponses 304 Not Modified applicables. MDN documente explicitement cette exigence de cohérence. Intégrez ces chemins de réponse à vos vérifications au lieu de ne contrôler que la première réponse HTML réussie. En-tête Vary.

Ajouter un élément meta avec http-equiv="Vary" n’est pas une solution de remplacement prise en charge. WHATWG définit un ensemble précis de directives pragma HTML, qui n’inclut pas Vary, et explique que ces directives sont dans une large mesure distinctes des en-têtes HTTP. Configurez réellement l’en-tête de réponse. Standard HTML : Directives pragma.

Si votre interface de publication ne permet pas de définir des en-têtes de réponse, vérifiez si la couche d’hébergement ou d’application propose une prise en charge documentée. Si ce n’est pas le cas, une solution pratique pour cet exemple synthétique consiste à attribuer des URL distinctes aux documents HTML et texte brut, dont les représentations restent stables, plutôt que de négocier leurs formats à une seule URL. Cela supprime cette dimension de sélection particulière ; les autres transformations doivent toujours être évaluées séparément.

Diagnostiquez les variations absentes, excessives et trompeuses

Servez-vous des captures pour déterminer la prochaine vérification. L’aide à la décision suivante s’applique au comportement spécifié dans l’exemple ; elle ne décrit aucun service d’hébergement en particulier.

Observation Vérification suivante
Les requêtes HTML et texte brut renvoient des formats différents, mais Vary ne mentionne pas Accept Examinez l’endroit où l’en-tête de réponse final est assemblé
Les variantes explicites incluent Accept, mais la réponse par défaut ne le mentionne pas Examinez le chemin de réponse de repli
La requête HTML répétée reçoit la version en texte brut Comparez la sélection à l’origine avec la diffusion par le cache
Toutes les requêtes renvoient le même document HTML Vérifiez s’il existe une négociation de format avant d’ajouter un membre lié au format
Un en-tête sans rapport apparaît dans Vary Identifiez la règle de sélection qui le nécessite avant de le supprimer
Le redimensionnement de la fenêtre du navigateur modifie la mise en page sans modifier le HTML diffusé Vérifiez s’il s’agit d’une présentation adaptative plutôt que d’une sélection par le serveur

Le cas où la réponse par défaut n’est pas correctement traitée mérite une attention particulière : la RFC 9111 décrit comment l’omission de Vary dans une réponse par défaut peut conduire à sélectionner cette réponse pour des requêtes ultérieures malgré la disponibilité d’autres options. Corrigez le chemin par défaut en même temps que les variantes explicites. RFC 9111 : Mise en cache HTTP.

Évitez d’utiliser Vary: * comme raccourci pour un inventaire inachevé. Selon les règles de mise en cache HTTP, une réponse stockée contenant ce membre échoue toujours au test de correspondance. Il n’indique pas quels champs de requête servent à sélectionner votre document. RFC 9111 : Mise en cache HTTP.

Une vérification dans un navigateur reste utile après la comparaison dans le Terminal. Le standard Fetch de WHATWG tient explicitement compte de Vary pour sélectionner une réponse dans le cache HTTP. Vérifiez également le document par le chemin de chargement normal du navigateur, ainsi qu’avec les requêtes curl contrôlées. Standard Fetch : récupération depuis le réseau HTTP ou le cache.

Harmonisez la diffusion des pages avec les exigences de Google Search

Pour les pages qui dépendent de l’appareil, faites la distinction entre la conception adaptative et la diffusion dynamique. Google indique que la conception adaptative diffuse le même HTML à la même URL sur tous les appareils, tandis que la diffusion dynamique sélectionne un HTML différent à l’aide de User-Agent et s’appuie sur Vary: User-Agent. Google recommande la conception adaptative pour sa facilité de mise en œuvre et de maintenance. Bonnes pratiques pour les sites mobiles et l’indexation orientée mobile.

Par conséquent, le fait qu’un Guide des formes synthétique réorganise simplement le même HTML au moyen de CSS ne justifie pas à lui seul l’ajout de User-Agent à Vary. Si le serveur sélectionne réellement un HTML différent selon l’appareil, ajoutez ces cas à la matrice de requêtes. Google recommande également de conserver un contenu principal équivalent entre les versions pour ordinateur et mobile. Bonnes pratiques pour les sites mobiles et l’indexation orientée mobile.

Terminez par un bref relevé de diffusion facile à examiner : les règles de sélection du document, la matrice de requêtes, les réponses capturées et la liste Vary obtenue. Chaque en-tête indiqué doit avoir un rôle identifiable, chaque variante prise en charge doit rester différenciable et la réponse par défaut doit respecter le même contrat de diffusion.

Sources