Multipart Upload Handling

## Why a separate body format exists A form whose fields are all short text can be sent as one encoded string of name/value pairs. That stops working the moment a field holds arbitrary bytes — an image, an archive, a document — because those bytes can contain the separator characters themselves, and escaping every occurrence would inflate the payload badly. `multipart/form-data` solves it differently: each field gets its own envelope, and the envelopes are separated by a delimiter the client picks and asserts does not occur in any of the data. ## The shape on the wire The request's `Content-Type` header names the media type and carries a `boundary` parameter — a random-looking token chosen by the client. The body is then, in order: 1. A line consisting of two hyphens and the boundary token. 2. One part: a small header block, a blank line, then the raw bytes of that field's value. 3. The boundary line again, then the next part — repeated for as many parts as the form has. 4. A final boundary line with two trailing hyphens, which marks the end of the body. A part's header block is tiny. It almost always holds a `Content-Disposition: form-data` header with a `name` parameter giving the form field name, plus a `filename` parameter when the part is a file. A part may also declare its own `Content-Type` describing its bytes. ```http POST /documents HTTP/1.1 Content-Type: multipart/form-data; boundary=ab17 --ab17 Content-Disposition: form-data; name="title" Quarterly report --ab17 Content-Disposition: form-data; name="document"; filename="q3.pdf" Content-Type: application/pdf <raw bytes of the file> --ab17-- ``` ## Field parts and file parts | | field part | file part | |---|---|---| | `Content-Disposition` | has `name`, no `filename` | has `name` **and** `filename` | | expected size | small, a form value | unbounded, whatever was selected | | how a framework surfaces it | a string in the request's form values | a handle: a stream, a temporary file, or a byte array | | its own `Content-Type` | usually absent | often present, chosen by the client | The distinguishing signal is the presence of the `filename` parameter, not the size of the part and not the declared media type. A file part can be empty, and a field part can be large. ## How the parser actually walks it A multipart parser is a sequential scanner, not a random-access reader. For each part it reads the header block, then streams bytes onward while watching for the next boundary. Several consequences follow, and they are what interviewers are usually probing: - **No part carries its length.** The format has no length prefix, so the end of a part is discovered, not announced. A per-part size cap can therefore only be enforced as bytes accumulate. - **Order is the client's order.** Parts arrive in the sequence the client wrote them, which normally mirrors the field order in the form. - **Names repeat legally.** The same `name` may appear in several parts (a multi-select, or several files under one field), so the natural in-memory shape is a multi-map, not a map. - **Each part has its own type.** The type declared on a part describes only that part; the request's own `Content-Type` describes the multipart envelope. - **The header block is untrusted input too.** Its size, the number of parameters and the encoding of the values all come from the client. ## Two ways a handler receives the parts Frameworks differ here, and many offer both: - **Collected.** The framework parses the whole body before invoking the handler, which then sees a finished collection of fields and files. Simple to use, at the cost of having buffered every part somewhere first. - **Iterated.** The handler pulls parts one at a time as the parser produces them, and must consume or explicitly discard a part's bytes before requesting the next. Cheaper in memory, but order-dependent and single-pass. ## The ordering trap in an iterated parse An iterated parse cannot look ahead. If the handler wants a small `token` field that the client wrote *after* a very large file part, the only way to reach that field is to get past the file part's bytes first — into memory, onto disk, or discarded. This is why services that want to check a small field before accepting a large payload either require clients to send the small fields first, or fall back to collecting the whole body. It is also why a consumed part cannot simply be read again: unless the framework kept a copy, those bytes are gone. ## What to say in an interview Name the three facts and you have answered it: the body is boundary-delimited, every part carries its own headers with `name` and optionally `filename`, and parsing is sequential so ordering and single-pass consumption are real constraints on the handler.