Skip to content

Commit d6f2a37

Browse files
lsdchrobtme
andauthored
feat(form-data): handle unmarshalling and validation of non-file JSON form data fields (#1060)
* feat(form-data): handle unmarshalling and validation of non-file JSON form data fields * fix(form-data): harden JSON multipart field handling - Emit the tagged content type in the generated OpenAPI encoding instead of always text/plain, so the spec matches how the field is parsed. - Precompute the field schema and defaults at registration time rather than on every request, avoiding a per-request reflection walk. - Panic at registration with actionable guidance when a struct/map form field lacks contentType:"application/json", instead of a confusing request-time "unsupported param type" error. - Resolve the content type via parseContentType so +json suffixes and ;charset parameters are handled consistently with the body codecs. - Share default application with the request body path (setDefaults) and add a benchmark. --------- Co-authored-by: Robert Thomas <[email protected]>
1 parent 214a18c commit d6f2a37

5 files changed

Lines changed: 480 additions & 11 deletions

File tree

‎bench_test.go‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,51 @@ type ComplexOutput struct {
181181
}
182182
}
183183

184+
func BenchmarkMultipartJSONField(b *testing.B) {
185+
_, api := humatest.New(b, huma.DefaultConfig("Test API", "1.0.0"))
186+
187+
type Metadata struct {
188+
Name string `json:"name" default:"anon"`
189+
Email string `json:"email" format:"email"`
190+
Age int `json:"age" default:"18"`
191+
Client string `json:"client"`
192+
}
193+
194+
huma.Register(api, huma.Operation{
195+
Method: http.MethodPost,
196+
Path: "/upload",
197+
}, func(ctx context.Context, input *struct {
198+
RawBody huma.MultipartFormFiles[struct {
199+
Metadata Metadata `form:"metadata" contentType:"application/json" required:"true"`
200+
File huma.FormFile `form:"file" contentType:"text/plain"`
201+
}]
202+
}) (*struct{}, error) {
203+
return nil, nil
204+
})
205+
206+
body := "--SimpleBoundary\r\n" +
207+
"Content-Disposition: form-data; name=\"metadata\"\r\n" +
208+
"Content-Type: application/json\r\n\r\n" +
209+
`{"name":"John Doe","email":"[email protected]","age":30,"client":"bench"}` + "\r\n" +
210+
"--SimpleBoundary\r\n" +
211+
"Content-Disposition: form-data; name=\"file\"; filename=\"test.txt\"\r\n" +
212+
"Content-Type: text/plain\r\n\r\n" +
213+
"Hello World\r\n" +
214+
"--SimpleBoundary--\r\n"
215+
216+
b.ResetTimer()
217+
b.ReportAllocs()
218+
for i := 0; i < b.N; i++ {
219+
r := httptest.NewRequest(http.MethodPost, "/upload", strings.NewReader(body))
220+
r.Header.Set("Content-Type", "multipart/form-data; boundary=SimpleBoundary")
221+
w := httptest.NewRecorder()
222+
api.Adapter().ServeHTTP(w, r)
223+
if w.Code < 200 || w.Code >= 300 {
224+
b.Fatalf("unexpected status %d: %s", w.Code, w.Body.String())
225+
}
226+
}
227+
}
228+
184229
func BenchmarkFullRequest_Complex(b *testing.B) {
185230
_, api := humatest.New(b, huma.DefaultConfig("Test API", "1.0.0"))
186231

‎docs/docs/features/request-inputs.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,9 @@ huma.Register(api, huma.Operation{
173173
MyGreeting string `form:"greeting", minLength:"6"`
174174
SomeNumbers []int `form:"numbers"`
175175
NonTaggedValuesAreIgnored string // ignored
176+
// Field content is unmarshalled and validated
177+
MyStruct SomeStruct `form:"my_struct" contentType:"application/json"`
178+
MyStructSlice []SomeStruct `form:"my_struct_slice" contentType:"application/json"`
176179
}]
177180
}) (*struct{}, error) {
178181
// The raw multipart.Form body is again available under input.RawBody.Form.
@@ -213,6 +216,9 @@ huma.Register(api, huma.Operation{
213216

214217
The files are decoded according to the specified contentType. If no contentType is provided, it defaults to `application/octet-stream`.
215218

219+
Non-file fields in multipart form data can be unmarshalled from JSON and validated, by setting their content-type to `application/json`. Field content in the request must be valid JSON.
220+
221+
216222
## Request Example
217223

218224
Here is an example request input struct, which has a path param, query param, header param, and a structured body alongside the raw body bytes:

‎formdata.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,11 +255,18 @@ func multiPartContentEncoding(t reflect.Type) map[string]*Encoding {
255255
name := formDataFieldName(f)
256256

257257
contentType := "text/plain"
258-
if f.Type == reflect.TypeFor[FormFile]() || f.Type == reflect.TypeFor[[]FormFile]() {
258+
switch {
259+
case f.Type == reflect.TypeFor[FormFile]() || f.Type == reflect.TypeFor[[]FormFile]():
259260
contentType = f.Tag.Get("contentType")
260261
if contentType == "" {
261262
contentType = "application/octet-stream"
262263
}
264+
default:
265+
// Honor an explicit content type (e.g. application/json) so the
266+
// generated encoding matches how the field is actually parsed.
267+
if c := f.Tag.Get("contentType"); c != "" {
268+
contentType = c
269+
}
263270
}
264271
encoding[name] = &Encoding{
265272
ContentType: contentType,

‎huma.go‎

Lines changed: 114 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,47 @@ type StreamResponse struct {
100100
const styleDeepObject = "deepObject"
101101

102102
type paramFieldInfo struct {
103-
Type reflect.Type
104-
Name string
105-
Loc string
106-
Required bool
107-
Default string
108-
TimeFormat string
109-
Explode bool
110-
Style string
111-
Schema *Schema
103+
Type reflect.Type
104+
Name string
105+
Loc string
106+
Required bool
107+
Default string
108+
TimeFormat string
109+
Explode bool
110+
Style string
111+
ContentType string
112+
Schema *Schema
113+
}
114+
115+
// jsonFormFieldInfo holds precomputed metadata for a multipart form field that
116+
// is unmarshalled and validated as JSON (via `contentType:"application/json"`).
117+
// It is computed once at registration time to keep request handling cheap.
118+
type jsonFormFieldInfo struct {
119+
schema *Schema
120+
defaults *findResult[any]
121+
}
122+
123+
// multipartFieldNeedsJSONTag reports whether a multipart form field of type t
124+
// can only be handled by unmarshalling it as JSON, i.e. it cannot be parsed
125+
// from a plain-text form value by parseInto. Such fields must be tagged
126+
// `contentType:"application/json"`.
127+
//
128+
// It is intentionally conservative: it flags only struct and map types that are
129+
// not otherwise scalar-parseable, so it never reports a field that parseInto
130+
// would have handled successfully.
131+
func multipartFieldNeedsJSONTag(t reflect.Type) bool {
132+
switch t.Kind() {
133+
case reflect.Struct, reflect.Map:
134+
if t == timeType || t == urlType {
135+
return false
136+
}
137+
if reflect.PointerTo(t).Implements(paramWrapperType) ||
138+
reflect.PointerTo(t).Implements(textUnmarshalerType) {
139+
return false
140+
}
141+
return true
142+
}
143+
return false
112144
}
113145

114146
// paramLocation holds the result of parsing a struct field's parameter location tags.
@@ -248,6 +280,10 @@ func findParams(registry Registry, op *Operation, t reflect.Type) *findResult[*p
248280
pfi.Required = boolTag(f, "required", false)
249281
}
250282

283+
if _, ok = f.Tag.Lookup("contentType"); ok {
284+
pfi.ContentType = f.Tag.Get("contentType")
285+
}
286+
251287
// Per OpenAPI 3.x spec, path parameters MUST always be required.
252288
// Override any user-set `required:"false"` tag for path params.
253289
if pfi.Loc == "path" {
@@ -779,8 +815,44 @@ func Register[I, O any](api API, op Operation, handler func(context.Context, *I)
779815

780816
a := api.Adapter()
781817
var rawBodyInputParams *findResult[*paramFieldInfo]
818+
// jsonFormFields holds precomputed metadata for multipart form fields that
819+
// carry `contentType:"application/json"`, so the per-request handler avoids
820+
// repeating schema lookups and reflection-based default discovery.
821+
var jsonFormFields map[*paramFieldInfo]*jsonFormFieldInfo
782822
if rawBodyDataT != nil {
783823
rawBodyInputParams = findParams(registry, &op, rawBodyDataT)
824+
for i := range rawBodyInputParams.Paths {
825+
p := rawBodyInputParams.Paths[i].Value
826+
if p.Loc != "form" || p.Type == formFileType || p.Type == formFilesType {
827+
continue
828+
}
829+
// Resolve the field's content type the same way body codecs do (via
830+
// parseContentType), so `+json` suffixes and `;charset` parameters
831+
// are handled consistently.
832+
ct := ""
833+
if start, end, err := parseContentType(p.ContentType); err == nil {
834+
ct = strings.ToLower(p.ContentType[start:end])
835+
}
836+
if ct != "application/json" && ct != "json" {
837+
// Fail fast at registration with actionable guidance rather than
838+
// a confusing "unsupported param type" error at request time.
839+
if multipartFieldNeedsJSONTag(p.Type) {
840+
panic(fmt.Errorf(`multipart form field '%s' of type '%s' requires contentType:"application/json" to be unmarshalled as JSON`, p.Name, p.Type))
841+
}
842+
continue
843+
}
844+
if jsonFormFields == nil {
845+
jsonFormFields = map[*paramFieldInfo]*jsonFormFieldInfo{}
846+
}
847+
var schema *Schema
848+
if mt := op.RequestBody.Content["multipart/form-data"]; mt != nil && mt.Schema != nil {
849+
schema = mt.Schema.Properties[p.Name]
850+
}
851+
jsonFormFields[p] = &jsonFormFieldInfo{
852+
schema: schema,
853+
defaults: findDefaults(registry, p.Type),
854+
}
855+
}
784856
}
785857
a.Handle(&op, api.Middlewares().Handler(op.Middlewares.Handler(func(ctx Context) {
786858
var input I
@@ -925,6 +997,7 @@ func Register[I, O any](api API, op Operation, handler func(context.Context, *I)
925997
if rbt.isMultipart() {
926998
// Read form
927999
form, err := readForm(ctx)
1000+
jsonUnmarshaler := func(data []byte, v any) error { return api.Unmarshal("application/json", data, v) }
9281001

9291002
if err != nil {
9301003
res.Errors = append(res.Errors, err)
@@ -968,6 +1041,30 @@ func Register[I, O any](api API, op Operation, handler func(context.Context, *I)
9681041
res.Add(pb, value, "expected at most one value, but received multiple values")
9691042
return
9701043
}
1044+
1045+
// JSON fields
1046+
if jf := jsonFormFields[p]; jf != nil {
1047+
errorsBeforeValidation := len(res.Errors)
1048+
1049+
var parsed any
1050+
if err := jsonUnmarshaler([]byte(value[0]), &parsed); err != nil {
1051+
res.Add(pb, value, "invalid JSON: "+err.Error())
1052+
} else if !op.SkipValidateParams {
1053+
Validate(oapi.Components.Schemas, jf.schema, pb, ModeWriteToServer, parsed, res)
1054+
}
1055+
1056+
if errorsBeforeValidation == len(res.Errors) {
1057+
if err := jsonUnmarshaler([]byte(value[0]), f.Addr().Interface()); err != nil {
1058+
// Should have been caught by the validation above.
1059+
res.Add(pb, value, "invalid JSON: "+err.Error())
1060+
}
1061+
// Set defaults on the unmarshalled value.
1062+
setDefaults(f, jf.defaults)
1063+
}
1064+
return
1065+
}
1066+
1067+
// Regular fields
9711068
pv, err := parseInto(ctx, f, value[0], value, *p)
9721069
if err != nil {
9731070
res.Add(pb, value, err.Error())
@@ -2173,6 +2270,14 @@ func parseBodyInto(v reflect.Value, bodyIndex []int, u intoUnmarshaler, body []b
21732270
}
21742271
}
21752272
// Set defaults for any fields that were not in the input.
2273+
setDefaults(v, defaults)
2274+
return nil
2275+
}
2276+
2277+
// setDefaults sets default values on every field reachable from v that was left
2278+
// at its zero value. It is shared by the request body and multipart JSON form
2279+
// field decoding paths.
2280+
func setDefaults(v reflect.Value, defaults *findResult[any]) {
21762281
defaults.Every(v, func(item reflect.Value, def any) {
21772282
if item.IsZero() {
21782283
if item.Kind() == reflect.Pointer {
@@ -2182,7 +2287,6 @@ func parseBodyInto(v reflect.Value, bodyIndex []int, u intoUnmarshaler, body []b
21822287
item.Set(reflect.Indirect(reflect.ValueOf(def)))
21832288
}
21842289
})
2185-
return nil
21862290
}
21872291

21882292
// readBody reads the message body from ctx into buf, respecting the

0 commit comments

Comments
 (0)