multipart/form-data: como um upload de formulário é estruturado na rede

O que é

Uma requisição com Content-Type: multipart/form-data; boundary=xYz tem um corpo como este:

--xYz
Content-Disposition: form-data; name="title"

Quarterly report
--xYz
Content-Disposition: form-data; name="file"; filename="q3.pdf"
Content-Type: application/pdf

%PDF-1.7 ...
--xYz--

A RFC 7578 define as regras. As partes são delimitadas por CRLF, -- e o boundary, que NÃO PODE (MUST NOT) aparecer dentro de nenhuma parte. Cada parte DEVE (MUST) ter Content-Disposition: form-data com um name; um filename DEVERIA (SHOULD) acompanhar o conteúdo de arquivos, mas não deve ser usado às cegas, e qualquer informação de diretório nele deve ser descartada. Vários arquivos para um mesmo campo são enviados como partes separadas com o mesmo name; a forma antiga com multipart/mixed aninhado está obsoleta, mas os parsers ainda devem aceitá-la. O Content-Type de uma parte é opcional e, por padrão, é text/plain; a codificação do texto vem de um parâmetro charset ou de um campo oculto _charset_. Content-Transfer-Encoding está obsoleto para HTTP, e os demais cabeçalhos Content-* devem ser ignorados. Partes com o mesmo nome NÃO PODEM (MUST NOT) ser mescladas, e a ordem é preservada. Nomes de arquivo não ASCII podem ser codificados com percent-encoding, costumam ser enviados como UTF-8 puro, e a forma filename* da RFC 5987 NÃO PODE (MUST NOT) ser usada. O padrão HTML especifica como os navegadores montam o corpo e geram a string do boundary.

Por que importa

Ao contrário de application/x-www-form-urlencoded, cada parte pode declarar um tipo de mídia e carregar bytes binários sem o acréscimo de um terço no tamanho que o base64 impõe (quatro bytes de saída para cada três de entrada). É o formato que todo navegador produz para <input type="file"> e o que a maioria das APIs de upload aceita. Parsers que mantêm o corpo inteiro em memória, confiam no filename como se fosse um caminho ou mesclam nomes repetidos são fonte recorrente de bugs e vulnerabilidades em uploads.

Como aplicar

• Faça o parsing em stream: leia parte por parte, grave as partes de arquivo em armazenamento temporário e imponha limites de tamanho por parte e no total antes de consumir os dados.
• Identifique os campos pelo parâmetro name; trate filename como texto de exibição não confiável e gere você mesmo o nome de armazenamento.
• Trate o Content-Type de uma parte como uma dica e valide os bytes.
• Em APIs, documente os nomes dos campos, que podem se repetir, e os limites; envie metadados JSON como uma parte própria com Content-Type: application/json, em vez de escondê-los num campo de texto.
• Nos clientes, deixe a biblioteca gerar o boundary e o Content-Length; não concatene manualmente.

Armadilhas

Evite nomes de campo não ASCII; se forem inevitáveis, a RFC 7578 recomenda usar UTF-8 de forma uniforme. Os delimitadores são CRLF; um parser que divide em LF isolado corrompe partes binárias. Frameworks que processam multipart de forma antecipada em toda requisição transformam uploads grandes numa via de negação de serviço. O charset das partes de texto muitas vezes está ausente, por isso é preciso conhecer o charset do formulário.