Defina Vary com os nomes dos cabeçalhos de solicitação que o servidor usa para selecionar a representação de uma página pública. Em um Mac, teste um cabeçalho por vez, compare o documento e os metadados retornados e confira a resposta padrão antes de alterar a configuração.

Este guia é para quem mantém um documento público e verifica sua entrega pelo Terminal do Mac. O exemplo prático é um “Guia de Formas” sintético, disponível como HTML ou texto simples no mesmo URL. A tarefa é identificar os parâmetros usados na seleção, configurar o cabeçalho de resposta correspondente e verificar o resultado.

O que deve constar no cabeçalho Vary de uma página?

Vary indica campos da solicitação que podem influenciar a seleção da representação, além do método e do URL de destino da solicitação. Seus valores são nomes de cabeçalhos, como Accept, e não os tipos de mídia solicitados. Ele descreve o comportamento de seleção; adicioná-lo não implementa esse comportamento. RFC 9110: Semântica HTTP, seção 12.5.5.

Por exemplo, se o servidor seleciona HTML ou texto simples usando Accept, o campo de resposta relevante é Vary: Accept. Se uma camada de entrega também seleciona saída compactada ou não compactada usando Accept-Encoding, preserve essa dimensão também: Vary: Accept, Accept-Encoding. Esses são exemplos condicionais, não uma configuração universal para todas as páginas. Negociação de conteúdo.

A pergunta prática é: uma resposta armazenada em cache e selecionada para uma solicitação poderia ser inadequada para outra porque este cabeçalho mudou? O armazenamento em cache HTTP exige que os campos indicados correspondam antes da reutilização sem revalidação. A ausência de um campo indicado corresponde a outra ausência, não à presença desse campo. RFC 9111: Armazenamento em cache HTTP, seção 4.1.

Comece criando um inventário dos critérios de seleção. Confira as regras de seleção de documentos do aplicativo e quaisquer transformações de resposta aplicadas depois. Um resultado diferente é uma evidência útil, mas resultados iguais em duas solicitações não provam que um cabeçalho seja irrelevante para todos os valores aceitos.

Monte uma matriz de solicitações antes de editar qualquer coisa

Para o Guia de Formas sintético, suponha que o comportamento desejado seja HTML para uma preferência por HTML, texto simples para uma preferência por texto simples e HTML quando Accept estiver ausente. As duas versões contêm as mesmas informações neutras: “Círculo, quadrado, triângulo.” Estes são requisitos ilustrativos, não observações de um site publicado.

Teste Configuração da solicitação Resultado desejado O que inspecionar
HTML Accept: text/html Documento HTML Corpo, Content-Type, Vary
Texto simples Accept: text/plain Documento de texto simples Corpo, Content-Type, Vary
Padrão Sem campo Accept Documento HTML Seleção padrão e Vary
Repetição HTML após texto simples Documento HTML novamente Se a variante anterior afeta a entrega
Entrada não usada Alterar um cabeçalho ausente das regras de seleção Mesma representação selecionada Se esse cabeçalho precisa ser investigado

Mantenha a compactação fixa durante a primeira comparação. Caso contrário, uma diferença nos bytes pode refletir a compactação, e não um documento diferente. Investigue primeiro a seleção do formato e depois a compactação separadamente. Essa distinção decorre das funções distintas de Accept e Accept-Encoding. Negociação de conteúdo.

Registre diferenças relevantes em vez de confiar apenas no tamanho do arquivo. Neste exemplo, a resposta em texto simples deve conter os nomes das formas sem marcação HTML, e seu tipo de mídia deve indicar texto simples. Uma diferença no horário gerado exigiria investigação antes de considerar toda diferença de bytes como uma nova variante.

Esta matriz é um recurso de diagnóstico, não uma suíte completa de testes de negociação. Quando os casos básicos funcionarem, adicione as preferências combinadas e os valores de qualidade que sua página realmente aceita. Uma solicitação com um único tipo não exercita todos os ramos de um algoritmo de seleção.

Capture respostas comparáveis no Terminal do Mac

Você precisa de um documento de teste público com conteúdo sintético, do URL HTTPS final e de um Mac com bash e curl disponíveis. O exemplo pressupõe que o documento de teste já aceite o comportamento de HTML/texto simples descrito acima. Ele não cria, envia nem publica esse documento.

Abra o Terminal e cole o bloco completo abaixo. Insira o URL do seu documento sintético quando solicitado. O script cria um novo diretório temporário para o relatório e mantém o corpo de cada resposta junto aos cabeçalhos; ele não substitui um relatório anterior.

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

Aqui, --header fornece o campo de solicitação controlado, e Accept: remove o campo Accept gerado internamente pelo curl. --dump-header e --output salvam cabeçalhos e corpos separadamente. Os limites de tempo da conexão e da transferência limitam a duração de cada solicitação. Essas opções estão documentadas no manual do curl.

O script para quando o curl informa uma falha de transferência ou um erro HTTP abrangido por --fail. Inspecione o diretório informado antes de tentar novamente: as capturas anteriores podem permanecer, e uma transferência com falha pode deixar arquivos incompletos. Por intenção, ele não segue redirecionamentos; portanto, confira a linha de status em cada arquivo de cabeçalho. Se capturou um redirecionamento, use o URL final do documento e inicie um novo relatório. Manual do curl.

Abra no Finder o diretório do relatório usando o caminho impresso pelo script. Inspecione os arquivos em um editor de texto simples. Compare html.body com plain.body e, em seguida, compare html.body com html-again.body. Inspecione absent.headers com tanto cuidado quanto as respostas com preferência explícita.

Trate os resultados salvos como observações desta sequência de solicitações. Eles não provam que um cache compartilhado armazenou algo. Se precisar testar a reutilização do cache, repita a sequência pelo caminho de entrega pretendido, nas condições documentadas para armazenamento em cache, e também inverta a ordem para que o texto simples venha primeiro.

Aplique o resultado na camada que gera a resposta

Para o Guia de Formas ilustrativo, as evidências da seleção do formato devem indicar Accept como campo de seleção. Configure-o onde a resposta HTTP é gerada ou finalizada. Se outra camada já fornecer um membro necessário de Vary, preserve-o ao adicionar o membro de seleção do formato. A lista final deve descrever o comportamento de seleção combinado. RFC 9110: Semântica HTTP.

O trecho a seguir mostra cabeçalhos de resposta para o exemplo quando a seleção de formato e a negociação de compactação estão ativas. Ele não é uma resposta HTTP completa nem um arquivo de configuração do servidor.

Vary: Accept, Accept-Encoding

Use a mesma lista pretendida de Vary nas variantes negociadas e na resposta padrão, e preserve-a nas respostas 304 Not Modified aplicáveis. A MDN documenta explicitamente esse requisito de consistência. Inclua esses caminhos de resposta na verificação, em vez de conferir apenas a primeira resposta HTML bem-sucedida. Cabeçalho Vary.

Adicionar um elemento meta com http-equiv="Vary" não é uma alternativa compatível. O WHATWG define um conjunto específico de diretivas pragma do HTML, que não inclui Vary, e explica que essas diretivas são, em grande parte, independentes dos cabeçalhos HTTP. Use a configuração real dos cabeçalhos de resposta. Padrão HTML: Diretivas pragma.

Se sua interface de publicação não puder definir cabeçalhos de resposta, verifique se a camada de hospedagem ou do aplicativo oferece suporte documentado. Se isso não estiver disponível, uma alternativa prática para este exemplo sintético é dar URLs separados aos documentos HTML e de texto simples, mantendo representações estáveis, em vez de negociar seus formatos em um único URL. Isso elimina essa dimensão específica de seleção; outras transformações ainda precisam ser avaliadas.

Diagnostique variações ausentes, excessivas e enganosas

Use as capturas para escolher a próxima investigação. O recurso de decisão a seguir aplica-se ao comportamento declarado no exemplo; não é uma afirmação sobre nenhum serviço de hospedagem específico.

Observação Próxima investigação
As solicitações de HTML e texto simples produzem formatos diferentes, mas Vary não inclui Accept Inspecione onde o cabeçalho de resposta final é montado
As variantes explícitas incluem Accept, mas a resposta padrão não Inspecione o caminho da resposta alternativa
A solicitação repetida de HTML recebe a versão em texto simples Compare a seleção na origem com a entrega pelo cache
Todas as solicitações produzem o mesmo documento HTML Confira se há negociação de formato antes de adicionar um membro relacionado ao formato
Um cabeçalho não relacionado aparece em Vary Encontre a regra de seleção que o exige antes de removê-lo
Redimensionar o navegador altera o layout sem mudar o HTML entregue Verifique se isso é apresentação responsiva, e não seleção no servidor

O caso de ausência na resposta padrão merece atenção especial: a RFC 9111 descreve como omitir Vary de uma resposta padrão pode fazer com que essa resposta seja selecionada para solicitações posteriores, apesar da existência de alternativas. Corrija o caminho padrão junto com as variantes explícitas. RFC 9111: Armazenamento em cache HTTP.

Evite usar Vary: * como atalho para um inventário incompleto. De acordo com as regras de armazenamento em cache HTTP, uma resposta armazenada que contenha esse membro sempre falha no teste de correspondência. Ele não identifica quais campos da solicitação selecionam seu documento. RFC 9111: Armazenamento em cache HTTP.

Uma verificação no navegador continua sendo útil após a comparação pelo Terminal. O Fetch Standard do WHATWG leva explicitamente Vary em conta ao selecionar uma resposta do cache HTTP. Confira o documento pelo caminho normal de carregamento do navegador, assim como pelas solicitações controladas do curl. Fetch Standard: Busca HTTP ou no cache.

Alinhe a entrega da página aos requisitos da Pesquisa Google

Para páginas que dependem do dispositivo, diferencie design responsivo de entrega dinâmica. O Google documenta o design responsivo como a entrega do mesmo HTML no mesmo URL em todos os dispositivos, enquanto a entrega dinâmica seleciona HTML diferente usando User-Agent e depende de Vary: User-Agent. O Google recomenda o design responsivo por ser mais fácil de implementar e manter. Práticas recomendadas para sites móveis e indexação que prioriza dispositivos móveis.

Consequentemente, um Guia de Formas sintético que apenas reorganiza o mesmo HTML com CSS não passa a ter motivo para variar com base em User-Agent apenas por essa alteração de layout. Se o servidor realmente selecionar HTML diferente por dispositivo, adicione esses casos à matriz de solicitações. O Google também recomenda manter o conteúdo principal equivalente nas versões para computador e dispositivos móveis. Práticas recomendadas para sites móveis e indexação que prioriza dispositivos móveis.

Conclua com um registro de entrega curto e fácil de revisar: as regras de seleção do documento, a matriz de solicitações, as respostas capturadas e a lista resultante de Vary. Cada cabeçalho listado deve ter uma função identificável, cada variante aceita deve continuar distinguível e a resposta padrão deve seguir o mesmo contrato de entrega.

Fontes