feat(runtime): BindForm helper for multipart/urlencoded body binding

file.go

@@ -5,4 +5,10 @@ package runtime
 
 import "github.com/go-openapi/swag/fileutils"
 
+// File represents an uploaded file. Re-exported from
+// [fileutils.File] for backwards compatibility.
+//
+// See [BindForm] (in form.go) for the orchestrator that parses
+// multipart / urlencoded request bodies and binds declared file
+// fields onto handler-side targets.
 type File = fileutils.File

form.go

@@ -0,0 +1,291 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package runtime
+
+import (
+	stderrors "errors"
+	"fmt"
+	"mime/multipart"
+	"net/http"
+
+	"github.com/go-openapi/errors"
+)
+
+// DefaultMaxUploadFilenameLength is the default cap applied to
+// FileHeader.Filename for each declared file when BindForm is invoked
+// without an explicit [BindFormMaxFilenameLen] option.
+//
+// Multipart headers are allocated per part; an attacker submitting
+// multi-MB filenames inflates the parser's memory footprint. 1 KiB
+// matches the IETF guidance for sane filename length and is enough
+// for realistic uploads.
+const DefaultMaxUploadFilenameLength = 1024
+
+// DefaultMaxUploadBodySize limits the size of the body to upload forms to 32MB.
+//
+// Use an explicit [BindFormMaxBody] option to change this limit.
+const DefaultMaxUploadBodySize = int64(32) << 20
+
+// filenamePreviewLen caps the byte length of the FileHeader.Filename
+// preview embedded as the ParseError.Value field when the helper
+// rejects a too-long filename.
+const filenamePreviewLen = 32
+
+// FileBinder is the per-file callback invoked by [BindForm] when a
+// declared file field is present.
+//
+// The callback is responsible for BOTH validating the file (size, MIME, etc.) AND assigning the bound
+// file to its destination — typically using:
+//
+//	o.FieldName = &runtime.File{Data: file, Header: header}
+//
+// Returning a non-nil error surfaces the error in BindForm's per-field
+// accumulator. Errors from the binder flow through verbatim — the
+// binder is expected to produce HTTP-aware errors (e.g.
+// errors.ExceedsMaximum from go-openapi/validate).
+type FileBinder func(file multipart.File, header *multipart.FileHeader) error
+
+// BindOption configures [BindForm]. The variadic style keeps simple
+// call sites simple and lets new knobs (security caps, additional
+// behaviour) be added without breaking the signature.
+type BindOption func(*bindConfig)
+
+type bindConfig struct {
+	maxParseMemory int64
+	maxBody        int64
+	maxFiles       int
+	maxFilenameLen int
+	files          []formFileSpec
+}
+
+type formFileSpec struct {
+	name     string
+	required bool
+	bind     FileBinder
+}
+
+// BindFormMaxParseMemory caps the in-memory portion of a multipart
+// body. Bytes beyond this are spilled to temporary files on disk by
+// the stdlib parser. 0 (the default) defers to the stdlib's 32 MB.
+//
+// This option does NOT cap total body bytes — see [BindFormMaxBody]
+// for that. The default body cap ([DefaultMaxUploadBodySize] = 32 MB)
+// is applied even when this option is not supplied, so out of the box
+// BindForm is bounded; callers with stricter or looser requirements
+// adjust via [BindFormMaxBody].
+func BindFormMaxParseMemory(n int64) BindOption {
+	return func(c *bindConfig) { c.maxParseMemory = n }
+}
+
+// BindFormMaxBody caps the size of the body read from a http form before parsing.
+//
+// The limit is set to 32MB by default. This default limit is applied for any n=0.
+//
+// The limit is disabled for n<0, assuming the caller has already capped the body size upstream.
+func BindFormMaxBody(n int64) BindOption {
+	return func(c *bindConfig) { c.maxBody = n }
+}
+
+// BindFormMaxFiles rejects parses where the total number of file
+// parts across all field names exceeds n. 0 (the default) means no
+// cap. Exceeding the cap is a fatal error — [BindForm] returns
+// fatal=true and no per-file binders run.
+func BindFormMaxFiles(n int) BindOption {
+	return func(c *bindConfig) { c.maxFiles = n }
+}
+
+// BindFormMaxFilenameLen rejects per-file headers whose Filename
+// length exceeds n. 0 means no cap; the default applied when this
+// option is not supplied is [DefaultMaxUploadFilenameLength]. The
+// cap is a per-field bind error (non-fatal); other declared files
+// still run.
+func BindFormMaxFilenameLen(n int) BindOption {
+	return func(c *bindConfig) { c.maxFilenameLen = n }
+}
+
+// BindFormFile declares a file field to bind under the given form
+// name. If required is true and the field is absent, [BindForm]
+// produces the per-field error
+//
+//	errors.NewParseError(name, "formData", "", http.ErrMissingFile)
+//
+// If required is false, absence is silent (no error, no bind).
+//
+// The bind callback runs only when the field is present. It is the
+// site where both validation and assignment happen — see [FileBinder].
+//
+// FileHeader.Filename is attacker-controlled text; the binder MUST
+// NOT use it directly as a filesystem path. The helper does not
+// touch the filesystem.
+func BindFormFile(name string, required bool, bind FileBinder) BindOption {
+	return func(c *bindConfig) {
+		c.files = append(c.files, formFileSpec{
+			name:     name,
+			required: required,
+			bind:     bind,
+		})
+	}
+}
+
+// BindForm parses r as multipart/form-data, falling back to
+// application/x-www-form-urlencoded when the request is not
+// multipart. On success, r.MultipartForm and r.PostForm are populated;
+// the caller can read non-file form values via [Values](r.Form) after
+// the call returns.
+//
+// All errors produced by BindForm itself (parse failure, missing
+// required field, cap exceeded) are *errors.ParseError values built
+// via [errors.NewParseError], matching the untyped
+// middleware/parameter.go path. Errors returned by per-file binders
+// flow through verbatim — binders own their HTTP-aware error shape.
+//
+// Per-file binders declared via [BindFormFile] run in declaration
+// order after a successful parse. Their errors are accumulated and
+// returned wrapped in [errors.CompositeValidationError]; the caller
+// typically appends the returned err to its own []error and continues
+// with non-file parameter binding.
+//
+// Return semantics:
+//
+//   - fatal=true, err!=nil: parse failure or a hard cap (e.g.
+//     [BindFormMaxFiles]) was exceeded. No per-file binders ran; the
+//     caller MUST return err immediately.
+//   - fatal=false, err!=nil: one or more per-file binders produced
+//     errors. The form parsed successfully; r.Form is populated. The
+//     caller appends err to its accumulator and continues.
+//   - fatal=false, err==nil: full success.
+//
+// fatal==true implies err!=nil.
+//
+// Defaults applied out of the box:
+//
+//   - Total body bytes capped at [DefaultMaxUploadBodySize] (32 MB)
+//     via [http.MaxBytesReader]. Adjust with [BindFormMaxBody]
+//     (negative n disables, when the caller has already capped the
+//     body upstream).
+//   - FileHeader.Filename length capped at
+//     [DefaultMaxUploadFilenameLength]. Adjust with
+//     [BindFormMaxFilenameLen].
+//
+// Caller responsibilities the helper does NOT cover:
+//
+//   - Set http.Server.ReadTimeout / IdleTimeout to defend against
+//     slow-read attacks.
+//   - Decompress Content-Encoding: gzip request bodies upstream if
+//     the API accepts them, using a size-limited reader.
+//   - Treat FileHeader.Filename as untrusted user input; never use
+//     it directly as a filesystem path.
+func BindForm(r *http.Request, opts ...BindOption) (fatal bool, err error) {
+	cfg := bindConfig{
+		maxFilenameLen: DefaultMaxUploadFilenameLength,
+	}
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	if perr := parseFormBody(r, cfg.maxParseMemory, cfg.maxBody); perr != nil {
+		// Body-cap hit gets the 413 status; everything else maps to a
+		// 400 ParseError. parseFormBody returns the raw stdlib error
+		// in both cases — the HTTP-aware wrapping happens here.
+		var maxBytesErr *http.MaxBytesError
+		if stderrors.As(perr, &maxBytesErr) {
+			return true, errors.New(http.StatusRequestEntityTooLarge, "formData: %v", perr)
+		}
+		return true, errors.NewParseError("body", "formData", "", perr)
+	}
+
+	if cfg.maxFiles > 0 {
+		if got := countFileParts(r); got > cfg.maxFiles {
+			return true, errors.NewParseError("body", "formData", "",
+				fmt.Errorf("multipart form contains %d file parts, exceeds limit %d", got, cfg.maxFiles))
+		}
+	}
+
+	var bindErrs []error
+	for _, spec := range cfg.files {
+		if e := bindFormFile(r, spec, cfg.maxFilenameLen); e != nil {
+			bindErrs = append(bindErrs, e)
+		}
+	}
+	if len(bindErrs) > 0 {
+		return false, errors.CompositeValidationError(bindErrs...)
+	}
+	return false, nil
+}
+
+// parseFormBody parses the request body. Content-Type drives the
+// parser: multipart/form-data → r.ParseMultipartForm, everything else
+// → r.ParseForm (stdlib's parsePostForm only actually reads the body
+// when Content-Type is application/x-www-form-urlencoded, so calling
+// ParseForm is safe for unrecognised types).
+//
+// Caveat: ParseMultipartForm calls ParseForm internally and discards its error
+// when the body turns out not to be multipart, returning ErrNotMultipart instead
+// — the subsequent retry then short-circuits because r.PostForm is already
+// set. Content-type-based routing avoids the lossy detour.
+//
+// Returns the raw stdlib error on failure; the caller (BindForm)
+// handles HTTP-aware wrapping (413 for MaxBytesError, 400 ParseError
+// otherwise).
+//
+// maxMemory == 0 falls through to the stdlib default (32 MB).
+// maxBody == 0 defaults to DefaultMaxUploadBodySize; maxBody < 0
+// disables the body cap (caller has capped upstream).
+func parseFormBody(r *http.Request, maxMemory, maxBody int64) error {
+	if r.Body != nil && maxBody >= 0 {
+		if maxBody == 0 {
+			maxBody = DefaultMaxUploadBodySize
+		}
+		r.Body = http.MaxBytesReader(nil, r.Body, maxBody)
+	}
+
+	mt, _, _ := ContentType(r.Header)
+	if mt == MultipartFormMime {
+		//nolint:gosec // G120: false positive (gosec doesn't track the Body). See https://github.com/securego/gosec/blob/de65614d10a6b84029e3e1215567b8ce7e490f23/testutils/g120_samples.go#L57
+		return r.ParseMultipartForm(maxMemory)
+	}
+	return r.ParseForm()
+}
+
+func countFileParts(r *http.Request) int {
+	if r.MultipartForm == nil {
+		return 0
+	}
+	var n int
+	for _, fhs := range r.MultipartForm.File {
+		n += len(fhs)
+	}
+
+	return n
+}
+
+func bindFormFile(r *http.Request, spec formFileSpec, maxFilenameLen int) error {
+	file, header, err := r.FormFile(spec.name)
+	if err != nil {
+		if stderrors.Is(err, http.ErrMissingFile) {
+			if spec.required {
+				return errors.New(http.StatusBadRequest, "formData: %v", http.ErrMissingFile)
+			}
+
+			return nil
+		}
+
+		return errors.NewParseError(spec.name, "formData", "", err)
+	}
+
+	if maxFilenameLen > 0 && len(header.Filename) > maxFilenameLen {
+		preview := header.Filename
+		if len(preview) > filenamePreviewLen {
+			preview = preview[:filenamePreviewLen]
+		}
+		return errors.NewParseError(spec.name, "formData", preview,
+			fmt.Errorf("filename length %d exceeds limit %d", len(header.Filename), maxFilenameLen))
+	}
+
+	if spec.bind == nil {
+		return nil
+	}
+
+	return spec.bind(file, header)
+}