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

Add a single orchestrator helper to the root runtime package that
dedupes the parse-and-bind dance go-swagger codegen emits for every
operation with form-data parameters:

  - BindForm(r, opts...) (fatal bool, err error) — parses the body
    (multipart/form-data, fallback to application/x-www-form-urlencoded)
    and runs per-file binders declared via BindFormFile options.
  - BindFormFile(name, required, FileBinder) — declares a file field.
  - BindFormMaxParseMemory, BindFormMaxBody, BindFormMaxFiles,
    BindFormMaxFilenameLen — security caps injectable via options.

The (fatal, err) return preserves the codegen pattern of bailing on
parse failure but accumulating per-file validation errors into a
composite. Body cap defaults to 32 MiB via http.MaxBytesReader so the
helper is bounded out of the box (413 on overflow); filename cap
defaults to 1 KiB.

All helper-produced errors are *errors.ParseError values built via
errors.NewParseError, matching the untyped middleware/parameter.go
path. Already-structured errors.Error values (e.g. 413 from a
MaxBytesReader hit) pass through with their original code. Binder
errors flow through verbatim — binders own their HTTP-aware shape.

Pure addition to this module. The go-swagger codegen change consuming
the helper is a separate PR in that repo.

refactor(middleware): untyped formData binder uses runtime.BindForm

Consolidate the multipart/urlencoded parse dance in
middleware/parameter.go's "formData" case onto runtime.BindForm. The
pre-flight content-type check (errors.InvalidContentType) and the
per-file FormFile block stay open-coded; the manual
ParseMultipartForm/ParseForm dance plus the err-wrap dance collapse
into one helper call. Untyped error shapes are byte-identical to
before; body is now capped at 32 MiB by default via http.MaxBytesReader
(helper default).

The helper also unifies errors reported by both the codegen use case and the untyped use case.

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: fredbi

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)
+}