feat(http): add form parser

The form parser is useful for parsing application/x-www-form-urlencoded
data.

Signed-off-by: Marek Cermak <[email protected]>

Author: CermakM

CHANGELOG.md

@@ -5,6 +5,9 @@ How to release a new version:
 
 ## [Unreleased]
 
+### Added
+- package `http/param`: can parse form data into embedded structs.
+
 ## [0.8.0] - 2024-11-14
 ### Added
 - package `http/param`: can parse into embedded structs.

http/param/param.go

@@ -13,6 +13,7 @@ const (
 	defaultTagName      = "param"
 	queryTagValuePrefix = "query"
 	pathTagValuePrefix  = "path"
+	formTagValuePrefix  = "form"
 )
 
 // TagResolver is a function that decides from a field tag what parameter should be searched.
@@ -34,6 +35,9 @@ func TagNameResolver(tagName string) TagResolver {
 // PathParamFunc is a function that returns value of specified http path parameter.
 type PathParamFunc func(r *http.Request, key string) string
 
+// FormParamFunc is a function that returns value of specified form parameter.
+type FormParamFunc func(r *http.Request, key string) string
+
 // Parser can Parse query and path parameters from http.Request into a struct.
 // Fields struct have to be tagged such that either QueryParamTagResolver or PathParamTagResolver returns
 // valid parameter name from the provided tag.
@@ -43,6 +47,7 @@ type PathParamFunc func(r *http.Request, key string) string
 type Parser struct {
 	ParamTagResolver TagResolver
 	PathParamFunc    PathParamFunc
+	FormParamFunc    FormParamFunc
 }
 
 // DefaultParser returns query and path parameter Parser with intended struct tags
@@ -51,6 +56,7 @@ func DefaultParser() Parser {
 	return Parser{
 		ParamTagResolver: TagNameResolver(defaultTagName),
 		PathParamFunc:    nil, // keep nil, as there is no sensible default of how to get value of path parameter
+		FormParamFunc:    nil, // keep nil, as there is no sensible default of how to get value of form parameter
 	}
 }
 
@@ -61,6 +67,13 @@ func (p Parser) WithPathParamFunc(f PathParamFunc) Parser {
 	return p
 }
 
+// WithFormParamFunc returns a copy of Parser with set function for getting form parameters from http.Request.
+// For more see Parser description.
+func (p Parser) WithFormParamFunc(f FormParamFunc) Parser {
+	p.FormParamFunc = f
+	return p
+}
+
 // Parse accepts the request and a pointer to struct with its fields tagged with appropriate tags set in Parser.
 // Such tagged fields must be in top level struct, or in exported struct embedded in top-level struct.
 // All such tagged fields are assigned the respective parameter from the actual request.
@@ -113,6 +126,7 @@ type paramType int
 const (
 	paramTypeQuery paramType = iota
 	paramTypePath
+	paramTypeForm
 )
 
 type taggedFieldIndexPath struct {
@@ -139,6 +153,7 @@ func (p Parser) findTaggedIndexPaths(typ reflect.Type, currentNestingIndexPath [
 		}
 		tag := typeField.Tag
 		pathParamName, okPath := p.resolvePath(tag)
+		formParamName, okForm := p.resolveForm(tag)
 		queryParamName, okQuery := p.resolveQuery(tag)
 		if okPath {
 			newPath := make([]int, 0, len(currentNestingIndexPath)+1)
@@ -150,6 +165,16 @@ func (p Parser) findTaggedIndexPaths(typ reflect.Type, currentNestingIndexPath [
 				indexPath: newPath,
 			})
 		}
+		if okForm {
+			newPath := make([]int, 0, len(currentNestingIndexPath)+1)
+			newPath = append(newPath, currentNestingIndexPath...)
+			newPath = append(newPath, i)
+			paths = append(paths, taggedFieldIndexPath{
+				paramType: paramTypeForm,
+				paramName: formParamName,
+				indexPath: newPath,
+			})
+		}
 		if okQuery {
 			newPath := make([]int, 0, len(currentNestingIndexPath)+1)
 			newPath = append(newPath, currentNestingIndexPath...)
@@ -194,6 +219,11 @@ func (p Parser) parseParam(r *http.Request, path taggedFieldIndexPath) error {
 		if err != nil {
 			return err
 		}
+	case paramTypeForm:
+		err := p.parseFormParam(r, path.paramName, path.destValue)
+		if err != nil {
+			return err
+		}
 	case paramTypeQuery:
 		err := p.parseQueryParam(r, path.paramName, path.destValue)
 		if err != nil {
@@ -217,6 +247,22 @@ func (p Parser) parsePathParam(r *http.Request, paramName string, v reflect.Valu
 	return nil
 }
 
+func (p Parser) parseFormParam(r *http.Request, paramName string, v reflect.Value) error {
+	if r.Method != http.MethodPost && r.Method != http.MethodPut && r.Method != http.MethodPatch {
+		return fmt.Errorf("struct's field was tagged for parsing the form parameter (%s) but request method is not POST, PUT or PATCH", paramName)
+	}
+	if err := r.ParseForm(); err != nil {
+		return fmt.Errorf("parsing form data: %w", err)
+	}
+	if values, ok := r.Form[paramName]; ok && len(values) > 0 {
+		err := unmarshalValueOrSlice(values, v)
+		if err != nil {
+			return fmt.Errorf("unmarshaling form parameter %s: %w", paramName, err)
+		}
+	}
+	return nil
+}
+
 func (p Parser) parseQueryParam(r *http.Request, paramName string, v reflect.Value) error {
 	query := r.URL.Query()
 	if values, ok := query[paramName]; ok && len(values) > 0 {
@@ -331,6 +377,10 @@ func (p Parser) resolvePath(fieldTag reflect.StructTag) (string, bool) {
 	return p.resolveTagWithModifier(fieldTag, pathTagValuePrefix)
 }
 
+func (p Parser) resolveForm(fieldTag reflect.StructTag) (string, bool) {
+	return p.resolveTagWithModifier(fieldTag, formTagValuePrefix)
+}
+
 func (p Parser) resolveQuery(fieldTag reflect.StructTag) (string, bool) {
 	return p.resolveTagWithModifier(fieldTag, queryTagValuePrefix)
 }

http/param/param_test.go

@@ -451,6 +451,45 @@ func TestParser_Parse_PathParam_FuncNotDefinedError(t *testing.T) {
 	assert.Error(t, err)
 }
 
+type structWithFormParams struct {
+	Subject string            `param:"form=subject"`
+	Amount  *int              `param:"form=amount"`
+	Object  *maybeShinyObject `param:"form=object"`
+	Nothing string            `param:"form=nothing"`
+}
+
+func TestParser_Parse_FormParam(t *testing.T) {
+	r := chi.NewRouter()
+	p := DefaultParser().WithFormParamFunc(func(r *http.Request, key string) string {
+		return r.FormValue(key)
+	})
+	result := structWithFormParams{
+		Nothing: "should be replaced",
+	}
+	expected := structWithFormParams{
+		Subject: "world",
+		Amount:  ptr(69),
+		Object: &maybeShinyObject{
+			IsShiny: true,
+			Object:  "apples",
+		},
+		Nothing: "",
+	}
+	var parseError error
+	r.Post("/hello/objects", func(w http.ResponseWriter, r *http.Request) {
+		parseError = p.Parse(r, &result)
+	})
+
+	urlEncodedBodyContent := "subject=world&amount=69&object=shiny-apples&nothing="
+	urlEncodedBody := strings.NewReader(urlEncodedBodyContent)
+	req := httptest.NewRequest(http.MethodPost, "https://test.com/hello/objects", urlEncodedBody)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	r.ServeHTTP(httptest.NewRecorder(), req)
+
+	assert.NoError(t, parseError)
+	assert.Equal(t, expected, result)
+}
+
 type otherFieldsStruct struct {
 	Q     string `param:"query=q"`
 	Other string `json:"other"`