multipart/form-data: how a form upload is framed on the wire

What it is

A request with Content-Type: multipart/form-data; boundary=xYz has a body like:

--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 states the rules. Parts are delimited by CRLF, -- and the boundary, which MUST NOT occur inside any part. Each part MUST have Content-Disposition: form-data with a name; a filename SHOULD accompany file contents but must not be used blindly, and any directory information in it is to be dropped. Several files for one field are sent as separate parts with the same name; the older nested multipart/mixed form is deprecated but parsers should still accept it. A part's Content-Type is optional and defaults to text/plain; the text encoding comes from a charset parameter or from a hidden _charset_ field. Content-Transfer-Encoding is deprecated for HTTP and other Content-* headers must be ignored. Parts with the same name MUST NOT be merged and order is preserved. Non-ASCII file names may be percent-encoded, are commonly sent as raw UTF-8, and the filename* form of RFC 5987 MUST NOT be used. The HTML standard specifies how browsers assemble the body and generate the boundary string.

Why it matters

Unlike application/x-www-form-urlencoded, each part can declare a media type and carry binary bytes without the one-third size overhead of base64 (four output bytes per three input bytes). It is the format every browser produces for <input type="file"> and what most upload APIs accept. Parsers that buffer whole bodies in memory, trust filename as a path, or merge repeated names are a recurring source of upload bugs and vulnerabilities.

How to apply

• Parse as a stream: read part by part, spool file parts to temporary storage, and enforce per-part and total size limits before consuming data.
• Key fields by the name parameter; treat filename as untrusted display text and generate your own storage name.
• Treat a part's Content-Type as a hint and validate the bytes.
• For APIs, document field names, which may repeat, and limits; send JSON metadata as its own part with Content-Type: application/json instead of hiding it in a text field.
• In clients, let the library generate the boundary and Content-Length; do not concatenate by hand.

Pitfalls

Avoid non-ASCII field names; RFC 7578 recommends UTF-8 uniformly if they are unavoidable. Delimiters are CRLF; a parser splitting on bare LF corrupts binary parts. Frameworks that parse multipart eagerly on every request turn large uploads into a denial-of-service path. The charset of text parts is often absent, so the form's charset must be known.