Um CDN retirou o GZIP e produziu mojibake em nomes de arquivos e a aplicação de cabeçalho de conjunto de caracteres que corrigiu downloads corrompidos

Quando sites de grande escala dependem de infraestrutura global para entregar conteúdo de maneira confiável e eficiente, as Redes de Entrega de Conteúdo (CDNs) desempenham um papel crítico. Além de simplesmente armazenar ativos em cache mais próximos dos usuários, os CDNs também auxiliam na compactação de arquivos, acelerando downloads e melhorando a experiência do usuário. No entanto, sob certas condições, podem introduzir inadvertidamente novos problemas. Um desses incidentes envolveu compactação GZIP e conjuntos de caracteres manipulados incorretamente, levando a downloads corrompidos e mojibake (texto ilegível) em nomes de arquivos – um fenômeno que desafiou desenvolvedores e operadores.

DR: Uma configuração incorreta em um serviço CDN levou à remoção dos cabeçalhos de compactação GZIP dos arquivos para download e à compreensão incorreta da codificação de caracteres dos nomes dos arquivos. Isso resultou em downloads com nomes de arquivos corrompidos ou ilegíveis (mojibake). O problema foi finalmente resolvido forçando o charset correto nos cabeçalhos HTTP, garantindo que a codificação do nome do arquivo e o conteúdo fossem interpretados corretamente pelo navegador. Este caso destaca a importância da consistência na codificação de conteúdo, especialmente ao usar CDNs que podem modificar cabeçalhos HTTP.

O que deu errado: mau gerenciamento de compressão

No centro do problema estava o tratamento inadequado do cabeçalho Content-Encoding pelo CDN. O servidor de origem comprimiu corretamente os arquivos usando GZIP e os rotulou com o seguinte cabeçalho:

 Content-Encoding: gzip

No entanto, o CDN – destinado a otimizar a entrega – decidiu retirar esse cabeçalho e servir o conteúdo como se estivesse descompactado. Isso funcionou bem para navegadores que esperavam arquivos brutos como CSS ou JavaScript, mas quando os usuários tentaram baixar arquivos como CSVs, PDFs ou arquivos ZIP, eles receberam downloads corrompidos. A descompactação desses arquivos falhou completamente ou produziu dados que pareciam ilegíveis ou incompletos.

Além da corrupção binária, surgiu um problema ainda mais misterioso: alguns nomes de arquivos pareciam distorcidos com símbolos estranhos, principalmente quando baixados em navegadores como Chrome ou Firefox. Esse fenômeno é conhecido como mojibake e ocorre quando um programa interpreta uma sequência de bytes usando uma codificação de caracteres não intencional.

Confusão nas codificações de caracteres

Mojibake em nomes de arquivos baixados normalmente ocorre quando:

• O nome do arquivo contém caracteres não ASCII (como letras acentuadas ou scripts asiáticos)
• O navegador não sabe qual conjunto de caracteres usar
• Os cabeçalhos Content-Disposition ou Content-Type não possuem declarações de conjunto de caracteres adequadas

O navegador, adivinhando errado, tenta interpretar o nome do arquivo usando uma codificação padrão ou substituta como ISO-8859-1, levando a caracteres sem sentido no lugar de caracteres legíveis. Isso geralmente afeta os usuários que baixam arquivos com nomes em idiomas como japonês, russo ou alemão, onde os caracteres especiais prevalecem.

Originalmente, os desenvolvedores definiram cabeçalhos apropriados no servidor de aplicativos, como:

 Content-Type: application/octet-stream; charset=utf-8 Content-Disposition: attachment; filename="resume.pdf"

Mas, mais uma vez, o CDN alterou esses cabeçalhos removendo-os ou substituindo-os, levando a downloads sem a dica do conjunto de caracteres. Isso desencadeou um comportamento incorreto do navegador, pois o nome do arquivo foi interpretado com a codificação errada.

A correção: aplicando Charset em cabeçalhos HTTP

Depois de muita depuração e rastreamento de log, os desenvolvedores confirmaram que:

• Os arquivos não foram corrompidos no servidor de origem.
• Os downloads foram bem-sucedidos via curl e acesso IP direto.
• O problema só ocorreu quando atendido por meio do CDN.

Portanto, a solução adequada era dupla:

1. Forçar o CDN a preservar os cabeçalhos Content-Encoding para que os navegadores recebam e descompactem o conteúdo GZIP corretamente.
2. Defina o charset explícito nos cabeçalhos Content-Type e Content-Disposition para garantir a decodificação adequada do nome do arquivo internacional.

A configuração final do cabeçalho de trabalho ficou assim:

 Content-Type: application/octet-stream; charset=utf-8 Content-Disposition: attachment; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf Content-Encoding: gzip

O uso de filename* com sintaxe de codificação de URL UTF-8'' garante que os navegadores interpretem o nome do arquivo de acordo com RFC 5987. Isso é particularmente suportado em navegadores modernos, alinhando o comportamento de plataforma cruzada.

Por que os CDNs alteram os cabeçalhos

As CDNs geralmente visam otimizar o desempenho, reduzir a redundância e padronizar as respostas. Para tanto, poderão:

• Remover ou substituir diretivas de compactação
• Normalizar tipos de conteúdo
• Remova cabeçalhos que não passam por filtros de segurança ou regras de cache

No entanto, essas otimizações podem sair pela culatra quando substituem parâmetros cuidadosamente definidos e críticos para renderização de conteúdo ou download de arquivos. Neste incidente, a falha do CDN em preservar a Content-Encoding e charset corretos provou ser prejudicial tanto para a usabilidade quanto para a internacionalização.

Lições aprendidas

Este problema serve como um lembrete valioso para desenvolvedores que trabalham em ambientes distribuídos:

• Sempre teste a entrega de conteúdo de ponta a ponta. Os arquivos que funcionam no seu servidor podem se comportar de maneira diferente atrás de um CDN.
• Seja explícito nos cabeçalhos. Não presuma nada sobre comportamentos padrão – sempre declare o tipo de conteúdo, a codificação e o conjunto de caracteres.
• Controle o comportamento do CDN por meio da configuração. A maioria dos CDNs permite substituições ou regras para preservar os cabeçalhos. Utilize-os.
• Verifique o comportamento do download em vários navegadores e localidades. Os bugs de internacionalização geralmente aparecem apenas nessas condições.

Perguntas frequentes

O que é mojibake?

Mojibake é um termo usado para descrever a exibição distorcida ou incorreta de caracteres causada por incompatibilidades de codificação de caracteres. Muitas vezes ocorre quando o software interpreta mal a codificação de caracteres usada para armazenar ou enviar dados de texto.

Como o gzip afeta os downloads de arquivos?

Quando usado corretamente, o GZIP compacta os arquivos para reduzir o tempo de download. No entanto, se um arquivo for servido como compactado GZIP sem o cabeçalho Content-Encoding: gzip apropriado, os navegadores podem não descompactá-lo, levando a downloads corrompidos ou ilegíveis.

Por que um CDN removeria cabeçalhos como Content-Encoding ou charset?

CDNs priorizam desempenho e segurança. Ao fazer isso, muitas vezes normalizam cabeçalhos ou aplicam políticas que removem informações potencialmente inseguras ou desnecessárias. Isso pode remover inadvertidamente metadados críticos necessários para o manuseio correto do conteúdo.

Qual é a maneira correta de especificar nomes de arquivos não ASCII para downloads?

Use o cabeçalho Content-Disposition com o atributo filename* usando codificação UTF-8 e formato com escape percentual, conforme especificado em RFC 5987. Por exemplo:

Content-Disposition: attachment; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf

Como os desenvolvedores podem evitar esses problemas no futuro?

Eles devem realizar testes por meio da camada CDN, especificar cabeçalhos explicitamente e fazer uso de configurações de CDN que preservem ou passem por todos os metadados necessários. Além disso, manter a documentação sobre como os CDNs alteram o tráfego é essencial durante as fases de depuração.