multipart/form-data: как загрузка формы устроена в передаваемом сообщении

Что это такое

У запроса с Content-Type: multipart/form-data; boundary=xYz тело выглядит так:

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

RFC 7578 определяет правила. Части отделяются CRLF, -- и границей, которая НЕ ДОЛЖНА встречаться внутри частей. Каждая часть ДОЛЖНА иметь Content-Disposition: form-data с name; файловое содержимое СЛЕДУЕТ сопровождать filename, но нельзя использовать это значение вслепую, а сведения о каталогах в нём нужно отбросить. Несколько файлов одного поля отправляются отдельными частями с одинаковым name; старая вложенная форма multipart/mixed устарела, но парсерам всё ещё следует её принимать. Content-Type части необязателен и по умолчанию равен text/plain; кодировку текста задаёт параметр charset или скрытое поле _charset_. Content-Transfer-Encoding для HTTP устарел, а другие заголовки Content-* необходимо игнорировать. Части с одинаковым именем НЕ ДОЛЖНЫ объединяться, и порядок сохраняется. Имена файлов вне ASCII могут быть процентно закодированы, обычно передаются как исходный UTF-8, а форму filename* из RFC 5987 использовать НЕЛЬЗЯ. Стандарт HTML определяет, как браузеры собирают тело и генерируют строку границы.

Почему это важно

В отличие от application/x-www-form-urlencoded, каждая часть может объявить медиатип и передавать двоичные байты без увеличения размера на треть, свойственного base64 (четыре выходных байта на три входных). Именно такой формат каждый браузер создаёт для <input type="file">, и его принимает большинство API загрузки. Парсеры, буферизующие тело целиком в памяти, доверяющие filename как пути или объединяющие повторяющиеся имена, постоянно становятся источником ошибок и уязвимостей загрузки.

Как применять

• Разбирайте потоком: читайте по частям, сохраняйте файловые части во временное хранилище и применяйте ограничения размера части и всего тела до потребления данных.
• Идентифицируйте поля параметром name; считайте filename недоверенным текстом для отображения и создавайте собственное имя для хранения.
• Рассматривайте Content-Type части как подсказку и проверяйте байты.
• В API документируйте имена полей, возможность их повторения и ограничения; передавайте метаданные JSON отдельной частью с Content-Type: application/json, а не прячьте их в текстовом поле.
• В клиентах поручайте библиотеке генерацию границы и Content-Length; не склеивайте вручную.

Подводные камни

Избегайте имён полей вне ASCII; если они неизбежны, RFC 7578 рекомендует повсюду UTF-8. Разделителями служат CRLF; парсер, разбивающий по одиночному LF, портит двоичные части. Фреймворки, заранее разбирающие multipart в каждом запросе, превращают большие загрузки в путь к отказу в обслуживании. У текстовых частей часто отсутствует charset, поэтому кодировка формы должна быть известна.