Pular para conteúdo

loop-detect: suporte ao cabeçalho CDN-Loop para prevenção de loops de requisição

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-loop-detect

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-loop-detect

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

load_module modules/ngx_http_loop_detect_module.so;

Este documento descreve o nginx-module-loop-detect v0.1.0 lançado em 06 de janeiro de 2026.

http {
    # Ative o módulo em um bloco de localização
    loop_detect on;
    loop_detect_cdn_id my_cdn_id;
    loop_detect_status 508;
    loop_detect_max_allow_loops 10;

    server {
        listen 80;
        server_name example.com;
        location / {
            proxy_set_header CDN-Loop $loop_detect_proxy_add_cdn_loop;
            proxy_pass http://example.upstream.com;
        }
    }
}

Diretrizes

loop_detect

Sintaxe: loop_detect on | off;

Padrão: loop_detect off;

Contexto: http, server, location

Habilita ou desabilita a detecção de loops para o escopo atual. Quando habilitado, o módulo verifica o cabeçalho CDN-Loop para rastrear o número de saltos e bloqueia requisições que excedem o limite permitido.

loop_detect_cdn_id

Sintaxe: loop_detect_cdn_id string;

Padrão: loop_detect_cdn_id openresty;

Contexto: http, server, location

Define o identificador único para seus clusters. Este identificador é usado para analisar e rastrear loops no cabeçalho CDN-Loop.

loop_detect_status

Sintaxe: loop_detect_status code;

Padrão: loop_detect_status 508;

Contexto: http, server, location

Define o código de status HTTP retornado quando uma requisição excede o limite de loops permitido. O código deve estar entre 400 e 599 (erros de cliente ou servidor).

loop_detect_max_allow_loops

Sintaxe: loop_detect_max_allow_loops number;

Padrão: loop_detect_max_allow_loops 10;

Contexto: http, server, location

Define o número máximo de loops permitidos antes de bloquear a requisição. O número deve ser maior que 0.

Variáveis

$loop_detect_current_loops

Retorna a contagem atual de loops detectados extraída do cabeçalho CDN-Loop. Este valor representa o número de saltos que sua requisição já passou pelos nós do CDN.

$loop_detect_proxy_add_cdn_loop

Constrói o novo valor do cabeçalho CDN-Loop a ser enviado para proxies a jusante. Este valor inclui:

  1. O identificador do nó CDN atual e a contagem de loops incrementada (por exemplo, my_cdn; loops=2).
  2. Outras entradas restantes do cabeçalho original CDN-Loop (se houver).

Exemplo de Uso:

location / {
    proxy_set_header CDN-Loop $loop_detect_proxy_add_cdn_loop;
    proxy_pass http://backend;
}

Como Funciona

  1. Detecção: O módulo analisa o cabeçalho CDN-Loop para identificar o número de saltos. Cada salto é formatado como: Formato: Cdn-Loop: <cdn_id>; loops=<count>, ... Exemplo: Cdn-Loop: my_cdn; loops=2, another_cdn; loops=1.

  2. Rastreamento: A contagem atual de saltos (current_loops) é extraída do cabeçalho. O módulo incrementa a contagem e constrói um novo valor CDN-Loop para proxies a jusante.

  3. Bloqueio: Se a contagem de loops detectada exceder loop_detect_max_allow_loops, o NGINX retorna o loop_detect_status configurado (por exemplo, 508).

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-loop-detect.