Por que cabeçalhos HTTP com underscores são descartados pelo Nginx?

A remoção silenciosa: Comportamento padrão do Nginx

O Nginx descarta cabeçalhos com sublinhados por padrão. Isso ocorre sem qualquer aviso ou mensagem de erro. Quando o Nginx recebe uma solicitação com cabeçalhos contendo sublinhados, ele remove esses cabeçalhos antes de enviar a solicitação para o servidor ou aplicação backend. Essa remoção pode causar problemas em aplicações web que usam esses cabeçalhos personalizados para funcionalidade ou transferência de dados.

A natureza oculta desse processo dificulta a identificação da causa dos problemas relacionados à falta de dados de cabeçalho por desenvolvedores e administradores de sistema. Os usuários podem gastar tempo depurando suas aplicações, sem saber que o Nginx está removendo seus cabeçalhos personalizados. Esse comportamento padrão pode ser um problema ao trabalhar com serviços ou APIs de terceiros que usam cabeçalhos com sublinhados, pois pode interromper o fluxo de informações entre sistemas.

Contexto histórico: Variáveis CGI e conversão de cabeçalhos

O comportamento do Nginx de descartar cabeçalhos com sublinhados tem origem no legado do Common Gateway Interface (CGI). O CGI é um padrão antigo para servidores web executarem programas externos e retornarem sua saída para clientes web. Ele influenciou a forma como os servidores web lidam com cabeçalhos HTTP.

No CGI, os cabeçalhos HTTP são convertidos em variáveis de ambiente para uso pelos scripts. Durante essa conversão, traços e sublinhados nos nomes dos cabeçalhos são alterados para sublinhados. Por exemplo, um cabeçalho como "Custom-Header" se torna "HTTP_CUSTOM_HEADER" como uma variável de ambiente CGI. Esse processo pode criar confusão quando os cabeçalhos já possuem sublinhados.

Para evitar essas ambiguidades, o Nginx descarta cabeçalhos com sublinhados por padrão. Essa decisão evita problemas em que diferentes cabeçalhos poderiam ser mapeados para o mesmo nome de variável CGI. Por exemplo, "Custom_Header" e "Custom-Header" se tornariam ambos "HTTP_CUSTOM_HEADER" no CGI, tornando confuso qual cabeçalho original a variável representa.

Embora essa abordagem resolva o problema de ambiguidade, pode causar comportamentos inesperados em aplicações web modernas que não usam CGI e dependem de cabeçalhos personalizados com sublinhados. Entender esse contexto histórico ajuda a explicar por que o Nginx lida com cabeçalhos contendo sublinhados dessa maneira, mesmo que nem sempre seja o comportamento desejado nas práticas atuais de desenvolvimento web.

Esclarecendo o RFC HTTP

O RFC HTTP (Request for Comments) permite o uso de sublinhados em nomes de cabeçalhos. Isso é frequentemente mal compreendido por desenvolvedores e administradores de sistemas. A especificação HTTP permite muitos caracteres em nomes de cabeçalhos, incluindo sublinhados.

A confusão geralmente vem da interpretação equivocada das regras de caracteres ASCII no RFC. A especificação HTTP/1.1 (RFC 2616) se refere ao RFC 822 para formatos de campos de cabeçalho. O RFC 822 afirma que os nomes dos campos devem usar caracteres ASCII imprimíveis, que incluem caracteres com valores decimais entre 33 e 126, exceto o dois-pontos. O caractere sublinhado (valor decimal 95) está dentro desta faixa permitida.

Alguns desenvolvedores pensam que sublinhados não são permitidos porque certos servidores web, como Apache ou Nginx, os tratam como inválidos por padrão. No entanto, isso é uma escolha específica do servidor, não um requisito do padrão HTTP.

Embora sublinhados sejam permitidos em nomes de cabeçalhos HTTP de acordo com o RFC, usá-los pode causar problemas com alguns servidores ou proxies que não estão configurados para lidar com eles. Por esse motivo, é geralmente melhor usar hifens em vez de sublinhados em nomes de cabeçalhos personalizados para evitar possíveis problemas.

Habilitando cabeçalhos com sublinhados: A solução de configuração

Para resolver o problema do Nginx descartar cabeçalhos com sublinhados, você pode usar a diretiva 'underscores_in_headers on;' na sua configuração do Nginx. Essa diretiva instrui o Nginx a aceitar e passar adiante os cabeçalhos que contêm sublinhados.

Para implementar essa solução, adicione a seguinte linha à sua configuração do Nginx:

underscores_in_headers on;

Você pode colocar essa diretiva em diferentes locais dentro do seu arquivo de configuração do Nginx, dependendo de quão amplamente você deseja aplicá-la:

1. Bloco server: Se você quiser habilitar cabeçalhos com sublinhados para um servidor específico, adicione a diretiva dentro do bloco server. Por exemplo:

server {
    listen 80;
    server_name example.com;
    underscores_in_headers on;
    # Outras configurações do servidor...
}

2. Bloco http: Para habilitar cabeçalhos com sublinhados para todos os servidores, coloque a diretiva no bloco http da sua configuração do Nginx:

http {
    underscores_in_headers on;
    # Outras configurações http...
}

3. Bloco location: Se você só precisar permitir cabeçalhos com sublinhados para locais específicos, adicione a diretiva ao bloco location relevante:

location /api {
    underscores_in_headers on;
    # Outras configurações de location...
}

Após adicionar a diretiva, reinicie o Nginx para aplicar as mudanças. Isso permitirá que o Nginx processe e passe adiante cabeçalhos contendo sublinhados, resolvendo o problema de cabeçalhos personalizados ausentes em suas aplicações.

Lembre-se de testar sua configuração após fazer essas alterações para garantir que tudo funcione como esperado.

curl -I -H "X_Custom_Header: TestValue" http://seu-dominio.com