multipart

Overview ¶

Package multipart decodes multipart/form-data — as submitted by HTML forms containing file inputs — into Go structs, using github.com/ajg/form to decode the value fields and mapping file parts onto struct fields by name.

Value fields follow form's decoding rules (struct tags, nesting, custom delimiters, and so on). File fields are matched by their top-level part name — via the `form` or `json` struct tag, or the field name — and may be declared as any of:

*multipart.FileHeader   // lazily read: the first file sent under the key
[]*multipart.FileHeader // lazily read: every file sent under the key
[]byte                  // eagerly read: contents of the first file
[][]byte                // eagerly read: contents of every file

The *multipart.FileHeader forms hand over mime/multipart's own handle: the caller Opens (and Closes) the file itself and may stream it, so no bound is imposed here. The []byte forms read the file into memory during decoding, bounded by Decoder.MaxFileSize and Decoder.MaxFiles.

Like form, decoding is strict by default: a value or file whose key matches no destination field is an error. Real browser submissions often include fields that aren't interesting to model (CSRF tokens, submit-button names); either add matching struct fields or opt out of strictness with NewDecoder().IgnoreUnknownKeys(true).

Errors returned by this package are of type *form.Error, carrying Op (form.OpDecode) and Kind (form.KindUnknownKey, form.KindLimit, and so on), so they participate in the same errors.As taxonomy as form itself. Field names can be mapped to wire keys with Decoder.KeysWith, mirroring form.