Multipart Forms and Uploads

## The body you are reading from When a client posts a form containing a file, it sends `Content-Type: multipart/form-data; boundary=...`. The body is a sequence of parts separated by that boundary. Each part has a small header block of its own — most importantly `Content-Disposition: form-data; name="avatar"; filename="cat.png"` — then a blank line, then the part's raw bytes. Text fields and file fields travel in the same body; a *file* part is simply one whose `Content-Disposition` carries a `filename` parameter. ## The signature ```go func (r *http.Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error) ``` **First value — `multipart.File`.** This is an interface, not an `*os.File`: ```go type File interface { io.Reader io.ReaderAt io.Seeker io.Closer } ``` Because it is a `ReaderAt` and a `Seeker` you can read it more than once (seek back to 0) and read ranges out of order — that holds whether the part was small enough to stay in memory or large enough to have been written to a temporary file. Because it is a `Closer`, it owns a resource: for a part backed by a temp file, an open file descriptor. Not closing it holds that descriptor for the life of the request and pins the disk blocks even after the file is unlinked. **Second value — `*multipart.FileHeader`.** A small descriptor with three exported fields: `Filename` (the name the client claimed), `Size` (the part's length in bytes), and `Header` (a `textproto.MIMEHeader` holding that part's own headers, such as its `Content-Type`). It also has an `Open()` method that hands you a fresh `multipart.File` for the same part — useful when you want a second independent reader, or when you got the header out of `r.MultipartForm.File[key]` rather than from `FormFile`. Everything in the header comes from the client. `Filename` may contain slashes, `..`, control characters, or a 4 KB name; the part's `Content-Type` is whatever the client typed and is not verified against the bytes. Use `filepath.Base` on it, or better, store the upload under a name you generate and keep the client's name only as a display label. If you care what the file really is, sniff the leading bytes yourself with `http.DetectContentType`. **Third value — `error`.** If the request is not multipart, or the body is malformed, you get the parse error. If the body parsed fine but there is no *file* part under that key, you get `http.ErrMissingFile` — test it with `errors.Is(err, http.ErrMissingFile)` when you want to distinguish "the user did not attach anything" from "the request was broken". ## What happens on the first call `FormFile` is a convenience wrapper. If `r.MultipartForm` is still nil it calls `r.ParseMultipartForm` for you with a default in-memory budget of 32 MB, which reads the **entire** request body: text parts land in `r.MultipartForm.Value`, file parts in `r.MultipartForm.File` as `[]*multipart.FileHeader`. So the error from `FormFile` may really be a parse error, and the work of receiving the upload has already been done by the time it returns. One consequence worth internalising early: `FormFile` returns only the **first** file for that key. A form with several file inputs sharing one name produces several parts under that name, and you reach the rest through `r.MultipartForm.File["docs"]`, calling `Open()` on each header. ## The shape of a correct handler The three habits that make a handler correct: close what you were handed, do not trust `fh.Filename`, and copy the bytes to a destination you control *inside* the handler rather than stashing the header for later — the storage behind it does not outlive the request.