Gerador e verificador de cabeçalho Content-Disposition

O que o cabeçalho Content-Disposition faz

Content-Disposition é o cabeçalho de resposta que transforma uma página em download e dá nome ao arquivo salvo. Tem uma parte obrigatória, o tipo de disposição, e os parâmetros que importam aqui são filename e filename*. O tipo attachment diz ao navegador para perguntar onde salvar; inline diz para agir normalmente, e é por isso que inline só serve para alguma coisa quando vem com um nome junto — sem ele, pede exatamente o que acontece sem cabeçalho nenhum.

Há um terceiro caso que vale conhecer porque passa despercebido: a RFC 6266 diz que tipos de disposição desconhecidos ou não tratados devem ser tratados igual a attachment. Ou seja, um erro de digitação como attachement não acaba exibindo o arquivo, e sim baixando. Esta ferramenta aponta isso em vez de deixar passar, porque um cabeçalho que funciona por acaso é um cabeçalho que ninguém olha de novo.

O nome do arquivo é orientativo no sentido mais forte da palavra. A especificação pede aos destinatários que tenham muito cuidado: nunca confiar em informação de pastas, ficar só com o último segmento do caminho, não gravar em lugar nenhum que o usuário não tenha autorizado, e remover ou substituir caracteres de controle e espaços nas pontas. Se um navegador renomeou o seu arquivo, ele estava seguindo as regras.

Como usar

1. Escolha um modo. Montar um cabeçalho pega o nome que você quer que o visitante veja e escreve o cabeçalho. Conferir um cabeçalho pega o que você já tem — colado com ou sem o nome do campo — e deduz o que um destinatário faz com ele.
2. No modo de montagem, digite o nome tal como é. Com acentos e cedilha. Escolha attachment ou inline, e escolha como o retorno ASCII soletra uma letra acentuada: a grafia de passaporte transforma ä em ae, ou você pode ficar com um a só. Copie o cabeçalho no botão.
3. No modo de conferência, leia as duas linhas que importam. Nome usado é o nome que um navegador atual realmente salva, e Tirado de diz qual dos dois parâmetros o forneceu. Os achados abaixo se dividem em erros, que quebram alguma coisa; avisos, que são válidos mas jogam contra você; e notas, que são válidas e simplesmente não fazem nada.

Por que um cabeçalho correto manda o nome duas vezes

Esta é a parte que surpreende, e é a razão de a ferramenta existir. A RFC 6266 diz que os dois parâmetros diferem apenas em que filename* usa uma codificação que aceita caracteres fora do ISO-8859-1 e, em seguida — e isto é o decisivo —, que quando os dois estão presentes num mesmo valor de cabeçalho os destinatários devem ficar com filename* e ignorar filename. O conselho não é trocar um pelo outro. É mandar os dois.

A razão é compatibilidade. A forma estendida chegou quando muito software já estava no ar, então quem manda só filename* deixa o que é mais antigo sem nada, e quem manda só filename fica preso num conjunto de caracteres que não sabe escrever a maioria dos nomes do mundo. O apêndice D do mesmo documento põe a ordem no papel: inclua filename quando US-ASCII der conta, acrescente filename* quando não der, gere o retorno substituindo por sequências ASCII, e ponha filename primeiro, porque alguns analisadores existentes param no primeiro nome que entendem.

Esse conselho de substituição vem com o próprio exemplo — a letra ä vira ae —, que é a grafia de passaporte e não a de uma letra só, e é a que esta ferramenta usa por padrão. A tabela por trás é a mesma do gerador de slugs do site, tirada do Doc 9303 da OACI, e existe porque a receita óbvia está errada: normalizar e tirar as marcas de acento apaga sem avisar cerca de uma dúzia de letras latinas inteiras em vez de dobrá-las, então Ærø fica na letra r sozinha e Straße perde o ß. Aqui Ærø.txt tem como retorno AEroe.txt.

O apêndice D também admite o limite do próprio conselho, numa frase: isso pode não ser possível em alguns idiomas. Um nome escrito inteiramente em japonês ou em árabe não tem grafia ASCII nenhuma, então esta ferramenta não inventa uma. Escreve uma raiz marcadora, mantém a extensão, lista cada caractere que não soube soletrar e diz isso na página. Qualquer navegador atual lê filename* e recebe o nome real de todo jeito; o marcador só aparece para software realmente antigo.

O valor estendido não é encodeURIComponent

A codificação de filename* é definida pela RFC 8187, e não é a codificação de URL, embora se pareça o bastante para enganar quase todo mundo. O valor é um nome de codificação de caracteres, duas aspas simples e depois uma sequência em que cada caractere ou está escapado com porcentagem ou pertence a um conjunto que a especificação chama de attr-char: os caracteres de token menos o asterisco, o apóstrofo e a porcentagem.

Compare esse conjunto com encodeURIComponent, que é o que praticamente todo exemplo de código usa, e os dois discordam nos dois sentidos. Varrendo todo o ASCII, encodeURIComponent deixa intactos exatamente quatro caracteres que attr-char proíbe: o apóstrofo, os dois parênteses e o asterisco. Também escapa sete que attr-char permite, o que é inofensivo, porque um escape de porcentagem é sempre legal. Os quatro não são inofensivos, e não são exóticos: relatório (final).pdf e O'Brien.pdf são nomes comuníssimos, e os dois saem do encodeURIComponent carregando um caractere que a gramática não aceita.

No mesmo lugar há uma segunda armadilha. A RFC 8187 removeu na revisão de 2017 a obrigação de suportar ISO-8859-1 e agora diz que os emissores devem usar UTF-8, então um valor que anuncia outra codificação está atrás da especificação mesmo onde ainda funciona. E o valor estendido nunca pode ir entre aspas: o mesmo documento observa que um analisador montado com peças genéricas pode muito bem aceitar a forma entre aspas assim mesmo, que é exatamente como um erro desses sobrevive aos testes.

O que isto não vai te dizer

Isto confere o texto que você cola e nada mais. Um navegador não consegue buscar os cabeçalhos do seu servidor, então a ferramenta não faz ideia se o cabeçalho que você está olhando é o que está sendo enviado, se o arquivo por trás dele existe, nem se o tipo de mídia bate com a extensão. Um cabeçalho pode estar impecável e descrever a resposta errada.

Também não diz nada sobre se o nome é legal quando cai no disco. Nomes de dispositivo reservados, os caracteres que o Windows proíbe e limites de comprimento são outro conjunto de regras com outra resposta, e este site tem um sanitizador de nomes de arquivo para essa pergunta. Os dois problemas se parecem e não compartilham nada: este é sobre sobreviver ao cabeçalho, aquele é sobre sobreviver ao sistema de arquivos.

Uma omissão deliberada: as continuações de parâmetro, o mecanismo da RFC 2231 que divide um valor longo entre filename*0* e filename*1*. A RFC 8187 afirma que continuações não são necessárias em cabeçalhos HTTP e não as adota, então um cabeçalho que as use fica fora do que isto analisa. Se você tem um, ele veio de software seguindo uma convenção MIME mais antiga num lugar que nunca a pediu.

Por fim, nada disso torna um nome de arquivo obrigatório. A especificação é enfática: o destinatário trata o nome como conselho, pode substituir um nome que signifique algo especial para o sistema de arquivos, e precisa garantir que qualquer extensão em que confie seja segura. O que um cabeçalho correto compra é a melhor chance de sair o nome que você quis, não a garantia dele.

Por que é grátis?

Montar e analisar um cabeçalho é trabalho de texto e roda no seu navegador. Não há servidor envolvido, então não há nada para cobrar nem conta para criar.

Nada é enviado e nada é guardado. Recarregue a página e ela terá esquecido o seu nome de arquivo.