Pular para conteúdo

dynamic-etag: módulo NGINX para adicionar ETag a conteúdo dinâmico

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-dynamic-etag
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-dynamic-etag

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_dynamic_etag_module.so;

Este documento descreve o nginx-module-dynamic-etag v0.3.0 lançado em 14 de novembro de 2026.


ETag para as respostas que sua aplicação gera dinamicamente.

O NGINX adiciona um ETag a arquivos estáticos, e nada ao que vem do PHP-FPM, de uma aplicação via proxy ou de qualquer outro upstream. Essas páginas são então baixadas por completo a cada visita, mesmo quando nenhum byte foi alterado. Este módulo calcula o hash do corpo da resposta, envia o hash como ETag e responde a um If-None-Match correspondente com 304 Not Modified e sem corpo.

Funciona com todos os módulos de upstream: proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, grpc_pass.

Sinopse

location ~ \.php$ {
    dynamic_etag on;
    fastcgi_pass unix:/run/php-fpm/www.sock;
    include      fastcgi_params;
}
$ curl -sI -X GET https://example.com/ | grep -i etag
ETag: "6f5902ac237024bdd0c176cb93063dc4"

$ curl -s -o /dev/null -w '%{http_code} %{size_download}\n' \
    -H 'If-None-Match: "6f5902ac237024bdd0c176cb93063dc4"' https://example.com/
304 0

Como funciona

O ETag precisa estar no cabeçalho da resposta, e o cabeçalho é enviado antes do corpo. Por isso o módulo retém a resposta: ele coleta o corpo conforme o upstream o entrega, calcula o hash de todo ele (MD5) e só então envia o cabeçalho, agora com o ETag, seguido do corpo.

  • O hash sempre cobre o corpo inteiro, independentemente de como ele chega: em uma única parte ou em várias, com proxy_buffering ativado ou desativado, da memória ou de um arquivo temporário para o qual o NGINX o gravou.
  • Um corpo maior que dynamic_etag_buffer_size não recebe ETag e é repassado sem alterações. Nunca há um hash parcial.
  • Requisições condicionais são respondidas pelo próprio NGINX, com base no ETag calculado: If-None-Match recebe um 304, um If-Match que falha recebe um 412.
  • O hash do corpo é calculado antes da compressão. O gzip e outros filtros de compressão então enfraquecem o ETag (W/"..."), como fazem para arquivos estáticos.

Diretivas

dynamic_etag

  • sintaxe: dynamic_etag on | off | $variable
  • padrão: off
  • contexto: http, server, location

Ativa o ETag para respostas de upstream. Com uma variável, o ETag é adicionado quando seu valor for on; veja Uso condicional.

dynamic_etag_types

  • sintaxe: dynamic_etag_types mime-type ...
  • padrão: text/html
  • contexto: http, server, location

Adiciona o ETag a respostas com os tipos MIME listados, além de text/html. O valor especial * corresponde a qualquer tipo.

dynamic_etag_strength

  • sintaxe: dynamic_etag_strength strong | weak | $variable
  • padrão: strong
  • contexto: http, server, location

Torna o ETag gerado forte ("...") ou fraco (W/"..."). Um ETag fraco indica que a página é equivalente, não idêntica byte a byte. Com uma variável, o ETag é fraco quando seu valor for weak.

dynamic_etag_buffer_size

  • sintaxe: dynamic_etag_buffer_size size
  • padrão: 1m
  • contexto: http, server, location

O maior corpo de resposta que o módulo mantém na memória para calcular o hash. Uma resposta maior é enviada sem ETag, exatamente como o NGINX a enviaria com o módulo desativado.

Quais respostas recebem um ETag

Todas estas condições precisam ser verdadeiras:

  • a resposta vem de um upstream (não de um arquivo estático, return ou uma página de erro: o NGINX cuida dos arquivos estáticos por conta própria);
  • seu status é 200;
  • seu tipo está listado em dynamic_etag_types;
  • a requisição não é HEAD (não há corpo para calcular o hash);
  • o corpo não está vazio e cabe em dynamic_etag_buffer_size;
  • o upstream não enviou um ETag próprio. Esse é mantido, e o NGINX responde a requisições condicionais com base nele.

Observações

A página precisa ser a mesma para obter o mesmo ETag. Uma página que incorpora um timestamp, um token aleatório ou um nonce por requisição muda a cada requisição, e o mesmo acontece com seu hash. Verifique com:

diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable

A resposta é enviada quando está completa. O cliente recebe o primeiro byte somente quando a aplicação produziu o último. Para uma página comum, isso representa alguns milissegundos de diferença; para uma resposta que faz streaming de propósito (saída de progresso, server-sent events), deixe o dynamic_etag desativado.

Uma resposta que o upstream não consegue terminar não é enviada de forma alguma. Se a aplicação falhar no meio da página, o cliente recebe uma conexão fechada, não meia página com um 200 e um ETag.

Testando com curl. curl -I envia uma requisição HEAD, que não recebe ETag. Use curl -sI -X GET em vez disso.

Uso condicional

As diretivas não são válidas dentro de if. Use map:

map $request_uri $dyn_etag {
    default      on;
    ~^/checkout  off;
    ~^/api/      off;
}

map $http_user_agent $etag_strength {
    default      strong;
    ~*legacybot  weak;
}

server {
    location / {
        dynamic_etag          $dyn_etag;
        dynamic_etag_strength $etag_strength;
        proxy_pass            http://backend;
    }
}