Merge 421a4098eb496e65d9c22d53682abfffecba5980 into d7776de7d444935ea4385999711bd6331a98fecb

Co-authored-by: Bo-Yi Wu <appleboy.tw@gmail.com>

.github/ISSUE_TEMPLATE/00-bug.yml

@@ -0,0 +1,67 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+name: Bugs
+description: I found a bug
+title: "issue title"
+labels:
+  - bug
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping us improve! 🙏 Please answer these questions and provide as much information as possible about your problem.
+
+  - type: input
+    id: go-version
+    attributes:
+      label: Go version
+      description: |
+        What version of Go are you using (`go version`)?
+      placeholder: ex. go version go1.20.7 darwin/arm64
+    validations:
+      required: true
+
+  - type: input
+    id: gin-version
+    attributes:
+      label: Gin version
+      description: |
+        What version(or commit ref) of Gin are you using?
+      placeholder: ex. 1.9.1
+    validations:
+      required: true
+
+  - type: dropdown
+    id: is-reproducible
+    attributes:
+      label: Can this bug be reproduced with the latest release?
+      options:
+        - Option Yes
+        - Option No
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-did-you-do
+    attributes:
+      label: "What did you do?"
+      description: "If possible, provide a recipe for reproducing the error. A complete runnable program is good. A link on [go.dev/play](https://go.dev/play) is best."
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: "What did you see happen?"
+      description: Command invocations and their associated output, functions with their arguments and return results, full stacktraces for panics (upload a file if it is very long), etc. Prefer copying text output over using screenshots.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: "What did you expect to see?"
+      description: Why is the current output incorrect, and any additional context we may need to understand the issue.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/01-enhance.yml

@@ -0,0 +1,28 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+name: Enhancements
+description: Enhance an idea for this project
+title: "issue title"
+labels:
+  - enhancement
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping us improve! 🙏 Please answer these questions and provide as much information as possible about your problem.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: "Description"
+      description: "Please describe your idea in detail."
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: "Additional"
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/02-feature.yml

@@ -0,0 +1,44 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+name: Features
+description: Suggest an idea for this project
+title: "issue title"
+labels:
+  - feature
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping us improve! 🙏 Please answer these questions and provide as much information as possible about your problem.
+
+  - type: dropdown
+    id: is-problem
+    attributes:
+      label: Is your feature request related to a problem?
+      options:
+        - Option Yes
+        - Option No
+    validations:
+      required: true
+
+  - type: textarea
+    id: description-solution
+    attributes:
+      label: "Describe the solution you'd like"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description-considered
+    attributes:
+      label: "Describe alternatives you've considered"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: "Additional"
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/03-question.yml

@@ -0,0 +1,22 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+name: Questions
+description: I want to ask a question
+title: "issue title"
+labels:
+  - question
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use the search tool before opening a new issue.
+        Please read the document carefully.
+
+  - type: textarea
+    id: ask
+    attributes:
+      label: "What do you want to ask?"
+      description: "Please describe the details of your questions."
+    validations:
+      required: true

benchmarks_test.go

@@ -154,7 +154,7 @@ func runRequest(B *testing.B, r *Engine, method, path string) {
 	w := newMockWriter()
 	B.ReportAllocs()
 	B.ResetTimer()
-	for i := 0; i < B.N; i++ {
+	for B.Loop() {
 		r.ServeHTTP(w, req)
 	}
 }

binding/binding.go

@@ -23,6 +23,7 @@ const (
 	MIMEYAML              = "application/x-yaml"
 	MIMEYAML2             = "application/yaml"
 	MIMETOML              = "application/toml"
+	MIMEBSON              = "application/bson"
 )
 
 // Binding describes the interface which needs to be implemented for binding the
@@ -86,6 +87,7 @@ var (
 	Header        Binding     = headerBinding{}
 	Plain         BindingBody = plainBinding{}
 	TOML          BindingBody = tomlBinding{}
+	BSON          BindingBody = bsonBinding{}
 )
 
 // Default returns the appropriate Binding instance based on the HTTP method
@@ -110,6 +112,8 @@ func Default(method, contentType string) Binding {
 		return TOML
 	case MIMEMultipartPOSTForm:
 		return FormMultipart
+	case MIMEBSON:
+		return BSON
 	default: // case MIMEPOSTForm:
 		return Form
 	}

binding/binding_nomsgpack.go

@@ -21,6 +21,7 @@ const (
 	MIMEYAML              = "application/x-yaml"
 	MIMEYAML2             = "application/yaml"
 	MIMETOML              = "application/toml"
+	MIMEBSON              = "application/bson"
 )
 
 // Binding describes the interface which needs to be implemented for binding the
@@ -82,6 +83,7 @@ var (
 	Header        = headerBinding{}
 	TOML          = tomlBinding{}
 	Plain         = plainBinding{}
+	BSON          BindingBody = bsonBinding{}
 )
 
 // Default returns the appropriate Binding instance based on the HTTP method
@@ -104,6 +106,8 @@ func Default(method, contentType string) Binding {
 		return FormMultipart
 	case MIMETOML:
 		return TOML
+	case MIMEBSON:
+		return BSON
 	default: // case MIMEPOSTForm:
 		return Form
 	}

binding/binding_test.go

@@ -21,6 +21,7 @@ import (
 	"github.com/gin-gonic/gin/testdata/protoexample"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.mongodb.org/mongo-driver/bson"
 	"google.golang.org/protobuf/proto"
 )
 
@@ -172,6 +173,9 @@ func TestBindingDefault(t *testing.T) {
 
 	assert.Equal(t, TOML, Default(http.MethodPost, MIMETOML))
 	assert.Equal(t, TOML, Default(http.MethodPut, MIMETOML))
+
+	assert.Equal(t, BSON, Default(http.MethodPost, MIMEBSON))
+	assert.Equal(t, BSON, Default(http.MethodPut, MIMEBSON))
 }
 
 func TestBindingJSONNilBody(t *testing.T) {
@@ -731,6 +735,18 @@ func TestBindingProtoBufFail(t *testing.T) {
 		string(data), string(data[1:]))
 }
 
+func TestBindingBSON(t *testing.T) {
+	var obj FooStruct
+	obj.Foo = "bar"
+	data, _ := bson.Marshal(&obj)
+	testBodyBinding(t,
+		BSON, "bson",
+		"/", "/",
+		string(data),
+		// note: for badbody, we remove first byte to make it invalid
+		string(data[1:]))
+}
+
 func TestValidationFails(t *testing.T) {
 	var obj FooStruct
 	req := requestWithBody(http.MethodPost, "/", `{"bar": "foo"}`)

binding/bson.go

@@ -0,0 +1,30 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+package binding
+
+import (
+	"io"
+	"net/http"
+
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+type bsonBinding struct{}
+
+func (bsonBinding) Name() string {
+	return "bson"
+}
+
+func (b bsonBinding) Bind(req *http.Request, obj any) error {
+	buf, err := io.ReadAll(req.Body)
+	if err == nil {
+		err = b.BindBody(buf, obj)
+	}
+	return err
+}
+
+func (bsonBinding) BindBody(body []byte, obj any) error {
+	return bson.Unmarshal(body, obj)
+}

binding/default_validator.go

@@ -27,7 +27,7 @@ func (err SliceValidationError) Error() string {
 	}
 
 	var b strings.Builder
-	for i := 0; i < len(err); i++ {
+	for i := range len(err) {
 		if err[i] != nil {
 			if b.Len() > 0 {
 				b.WriteString("\n")
@@ -58,7 +58,7 @@ func (v *defaultValidator) ValidateStruct(obj any) error {
 	case reflect.Slice, reflect.Array:
 		count := value.Len()
 		validateRet := make(SliceValidationError, 0)
-		for i := 0; i < count; i++ {
+		for i := range count {
 			if err := v.ValidateStruct(value.Index(i).Interface()); err != nil {
 				validateRet = append(validateRet, err)
 			}

binding/form_mapping.go

@@ -5,6 +5,7 @@
 package binding
 
 import (
+	"encoding"
 	"errors"
 	"fmt"
 	"maps"
@@ -118,7 +119,7 @@ func mapping(value reflect.Value, field reflect.StructField, setter setter, tag
 		tValue := value.Type()
 
 		var isSet bool
-		for i := 0; i < value.NumField(); i++ {
+		for i := range value.NumField() {
 			sf := tValue.Field(i)
 			if sf.PkgPath != "" && !sf.Anonymous { // unexported
 				continue
@@ -137,6 +138,8 @@ func mapping(value reflect.Value, field reflect.StructField, setter setter, tag
 type setOptions struct {
 	isDefaultExists bool
 	defaultValue    string
+	// parser specifies what interface to use for reading the request & default values (e.g. `encoding.TextUnmarshaler`)
+	parser string
 }
 
 func tryToSetValue(value reflect.Value, field reflect.StructField, setter setter, tag string) (bool, error) {
@@ -168,6 +171,8 @@ func tryToSetValue(value reflect.Value, field reflect.StructField, setter setter
 					setOpt.defaultValue = strings.ReplaceAll(v, ";", ",")
 				}
 			}
+		} else if k, v = head(opt, "="); k == "parser" {
+			setOpt.parser = v
 		}
 	}
 
@@ -191,6 +196,20 @@ func trySetCustom(val string, value reflect.Value) (isSet bool, err error) {
 	return false, nil
 }
 
+// trySetUsingParser tries to set a custom type value based on the presence of the "parser" tag on the field.
+// If the parser tag does not exist or does not match any of the supported parsers, gin will skip over this.
+func trySetUsingParser(val string, value reflect.Value, parser string) (isSet bool, err error) {
+	switch parser {
+	case "encoding.TextUnmarshaler":
+		v, ok := value.Addr().Interface().(encoding.TextUnmarshaler)
+		if !ok {
+			return false, nil
+		}
+		return true, v.UnmarshalText([]byte(val))
+	}
+	return false, nil
+}
+
 func trySplit(vs []string, field reflect.StructField) (newVs []string, err error) {
 	cfTag := field.Tag.Get("collection_format")
 	if cfTag == "" || cfTag == "multi" {
@@ -208,7 +227,7 @@ func trySplit(vs []string, field reflect.StructField) (newVs []string, err error
 	case "pipes":
 		sep = "|"
 	default:
-		return vs, fmt.Errorf("%s is not supported in the collection_format. (csv, ssv, pipes)", cfTag)
+		return vs, fmt.Errorf("%s is not supported in the collection_format. (multi, csv, ssv, tsv, pipes)", cfTag)
 	}
 
 	totalLength := 0
@@ -244,7 +263,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][
 			}
 		}
 
-		if ok, err = trySetCustom(vs[0], value); ok {
+		if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok {
+			return ok, err
+		} else if ok, err = trySetCustom(vs[0], value); ok {
 			return ok, err
 		}
 
@@ -252,7 +273,7 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][
 			return false, err
 		}
 
-		return true, setSlice(vs, value, field)
+		return true, setSlice(vs, value, field, opt)
 	case reflect.Array:
 		if len(vs) == 0 {
 			if !opt.isDefaultExists {
@@ -267,7 +288,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][
 			}
 		}
 
-		if ok, err = trySetCustom(vs[0], value); ok {
+		if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok {
+			return ok, err
+		} else if ok, err = trySetCustom(vs[0], value); ok {
 			return ok, err
 		}
 
@@ -279,27 +302,32 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][
 			return false, fmt.Errorf("%q is not valid value for %s", vs, value.Type().String())
 		}
 
-		return true, setArray(vs, value, field)
+		return true, setArray(vs, value, field, opt)
 	default:
 		var val string
-		if !ok {
+		if !ok || len(vs) == 0 || (len(vs) > 0 && vs[0] == "") {
 			val = opt.defaultValue
+		} else if len(vs) > 0 {
+			val = vs[0]
 		}
 
-		if len(vs) > 0 {
-			val = vs[0]
-			if val == "" {
-				val = opt.defaultValue
-			}
-		}
-		if ok, err := trySetCustom(val, value); ok {
+		if ok, err = trySetUsingParser(val, value, opt.parser); ok {
+			return ok, err
+		} else if ok, err = trySetCustom(val, value); ok {
 			return ok, err
 		}
-		return true, setWithProperType(val, value, field)
+		return true, setWithProperType(val, value, field, opt)
 	}
 }
 
-func setWithProperType(val string, value reflect.Value, field reflect.StructField) error {
+func setWithProperType(val string, value reflect.Value, field reflect.StructField, opt setOptions) error {
+	// this if-check is required for parsing nested types like []MyId, where MyId is [12]byte
+	if ok, err := trySetUsingParser(val, value, opt.parser); ok {
+		return err
+	} else if ok, err = trySetCustom(val, value); ok {
+		return err
+	}
+
 	// If it is a string type, no spaces are removed, and the user data is not modified here
 	if value.Kind() != reflect.String {
 		val = strings.TrimSpace(val)
@@ -352,7 +380,7 @@ func setWithProperType(val string, value reflect.Value, field reflect.StructFiel
 		if !value.Elem().IsValid() {
 			value.Set(reflect.New(value.Type().Elem()))
 		}
-		return setWithProperType(val, value.Elem(), field)
+		return setWithProperType(val, value.Elem(), field, opt)
 	default:
 		return errUnknownType
 	}
@@ -459,9 +487,9 @@ func setTimeField(val string, structField reflect.StructField, value reflect.Val
 	return nil
 }
 
-func setArray(vals []string, value reflect.Value, field reflect.StructField) error {
+func setArray(vals []string, value reflect.Value, field reflect.StructField, opt setOptions) error {
 	for i, s := range vals {
-		err := setWithProperType(s, value.Index(i), field)
+		err := setWithProperType(s, value.Index(i), field, opt)
 		if err != nil {
 			return err
 		}
@@ -469,9 +497,9 @@ func setArray(vals []string, value reflect.Value, field reflect.StructField) err
 	return nil
 }
 
-func setSlice(vals []string, value reflect.Value, field reflect.StructField) error {
+func setSlice(vals []string, value reflect.Value, field reflect.StructField, opt setOptions) error {
 	slice := reflect.MakeSlice(value.Type(), len(vals), len(vals))
-	err := setArray(vals, slice, field)
+	err := setArray(vals, slice, field, opt)
 	if err != nil {
 		return err
 	}

binding/form_mapping_test.go

@@ -5,6 +5,7 @@
 package binding
 
 import (
+	"encoding"
 	"encoding/hex"
 	"errors"
 	"mime/multipart"
@@ -524,6 +525,16 @@ func TestMappingCustomUnmarshalParamHexWithURITag(t *testing.T) {
 	assert.EqualValues(t, 245, s.Foo)
 }
 
+func TestMappingCustomUnmarshalParamHexDefault(t *testing.T) {
+	var s struct {
+		Foo customUnmarshalParamHex `form:"foo,default=f5"`
+	}
+	err := mappingByPtr(&s, formSource{"foo": {}}, "form")
+	require.NoError(t, err)
+
+	assert.EqualValues(t, 0xf5, s.Foo)
+}
+
 type customUnmarshalParamType struct {
 	Protocol string
 	Path     string
@@ -624,6 +635,33 @@ func TestMappingCustomSliceForm(t *testing.T) {
 	assert.Equal(t, "foo", s.FileData[1])
 }
 
+func TestMappingCustomSliceStopsWhenError(t *testing.T) {
+	var s struct {
+		FileData customPath `form:"path"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"invalid"}}, "form")
+	require.ErrorContains(t, err, "invalid format")
+	require.Empty(t, s.FileData)
+}
+
+func TestMappingCustomSliceOfSliceUri(t *testing.T) {
+	var s struct {
+		FileData []customPath `uri:"path" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"bar/foo,bar/foo/spam"}}, "uri")
+	require.NoError(t, err)
+	assert.Equal(t, []customPath{{"bar", "foo"}, {"bar", "foo", "spam"}}, s.FileData)
+}
+
+func TestMappingCustomSliceOfSliceForm(t *testing.T) {
+	var s struct {
+		FileData []customPath `form:"path" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"bar/foo,bar/foo/spam"}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []customPath{{"bar", "foo"}, {"bar", "foo", "spam"}}, s.FileData)
+}
+
 type objectID [12]byte
 
 func (o *objectID) UnmarshalParam(param string) error {
@@ -675,6 +713,358 @@ func TestMappingCustomArrayForm(t *testing.T) {
 	assert.Equal(t, expected, s.FileData)
 }
 
+func TestMappingCustomArrayOfArrayUri(t *testing.T) {
+	id1, _ := convertTo(`664a062ac74a8ad104e0e80e`)
+	id2, _ := convertTo(`664a062ac74a8ad104e0e80f`)
+
+	var s struct {
+		FileData []objectID `uri:"ids" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"ids": {`664a062ac74a8ad104e0e80e,664a062ac74a8ad104e0e80f`}}, "uri")
+	require.NoError(t, err)
+	assert.Equal(t, []objectID{id1, id2}, s.FileData)
+}
+
+func TestMappingCustomArrayOfArrayForm(t *testing.T) {
+	id1, _ := convertTo(`664a062ac74a8ad104e0e80e`)
+	id2, _ := convertTo(`664a062ac74a8ad104e0e80f`)
+
+	var s struct {
+		FileData []objectID `form:"ids" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"ids": {`664a062ac74a8ad104e0e80e,664a062ac74a8ad104e0e80f`}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []objectID{id1, id2}, s.FileData)
+}
+
+// ====  TextUnmarshaler tests START ====
+
+type customUnmarshalTextHex int
+
+func (f *customUnmarshalTextHex) UnmarshalText(text []byte) error {
+	v, err := strconv.ParseInt(string(text), 16, 64)
+	if err != nil {
+		return err
+	}
+	*f = customUnmarshalTextHex(v)
+	return nil
+}
+
+// verify type implements TextUnmarshaler
+var _ encoding.TextUnmarshaler = (*customUnmarshalTextHex)(nil)
+
+func TestMappingCustomUnmarshalTextHexUri(t *testing.T) {
+	var s struct {
+		Field customUnmarshalTextHex `uri:"field,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"field": {`f5`}}, "uri")
+	require.NoError(t, err)
+	assert.EqualValues(t, 245, s.Field)
+}
+
+func TestMappingCustomUnmarshalTextHexForm(t *testing.T) {
+	var s struct {
+		Field customUnmarshalTextHex `form:"field,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"field": {`f5`}}, "form")
+	require.NoError(t, err)
+	assert.EqualValues(t, 245, s.Field)
+}
+
+func TestMappingCustomUnmarshalTextHexDefault(t *testing.T) {
+	var s struct {
+		Field customUnmarshalTextHex `form:"field,default=f5,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"field1": {}}, "form")
+	require.NoError(t, err)
+	assert.EqualValues(t, 0xf5, s.Field)
+}
+
+type customUnmarshalTextType struct {
+	Protocol string
+	Path     string
+	Name     string
+}
+
+func (f *customUnmarshalTextType) UnmarshalText(text []byte) error {
+	parts := strings.Split(string(text), ":")
+	if len(parts) != 3 {
+		return errors.New("invalid format")
+	}
+	f.Protocol = parts[0]
+	f.Path = parts[1]
+	f.Name = parts[2]
+	return nil
+}
+
+var _ encoding.TextUnmarshaler = (*customUnmarshalTextType)(nil)
+
+func TestMappingCustomStructTypeUnmarshalTextForm(t *testing.T) {
+	var s struct {
+		FileData customUnmarshalTextType `form:"data,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"data": {`file:/foo:happiness`}}, "form")
+	require.NoError(t, err)
+
+	assert.Equal(t, "file", s.FileData.Protocol)
+	assert.Equal(t, "/foo", s.FileData.Path)
+	assert.Equal(t, "happiness", s.FileData.Name)
+}
+
+func TestMappingCustomStructTypeUnmarshalTextUri(t *testing.T) {
+	var s struct {
+		FileData customUnmarshalTextType `uri:"data,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"data": {`file:/foo:happiness`}}, "uri")
+	require.NoError(t, err)
+
+	assert.Equal(t, "file", s.FileData.Protocol)
+	assert.Equal(t, "/foo", s.FileData.Path)
+	assert.Equal(t, "happiness", s.FileData.Name)
+}
+
+func TestMappingCustomPointerStructTypeUnmarshalTextForm(t *testing.T) {
+	var s struct {
+		FileData *customUnmarshalTextType `form:"data,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"data": {`file:/foo:happiness`}}, "form")
+	require.NoError(t, err)
+
+	assert.Equal(t, "file", s.FileData.Protocol)
+	assert.Equal(t, "/foo", s.FileData.Path)
+	assert.Equal(t, "happiness", s.FileData.Name)
+}
+
+func TestMappingCustomPointerStructTypeUnmarshalTextUri(t *testing.T) {
+	var s struct {
+		FileData *customUnmarshalTextType `uri:"data,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"data": {`file:/foo:happiness`}}, "uri")
+	require.NoError(t, err)
+
+	assert.Equal(t, "file", s.FileData.Protocol)
+	assert.Equal(t, "/foo", s.FileData.Path)
+	assert.Equal(t, "happiness", s.FileData.Name)
+}
+
+type customPathUnmarshalText []string
+
+func (p *customPathUnmarshalText) UnmarshalText(text []byte) error {
+	elems := strings.Split(string(text), "/")
+	n := len(elems)
+	if n < 2 {
+		return errors.New("invalid format")
+	}
+
+	*p = elems
+	return nil
+}
+
+var _ encoding.TextUnmarshaler = (*customPathUnmarshalText)(nil)
+
+func TestMappingCustomSliceUnmarshalTextUri(t *testing.T) {
+	var s struct {
+		FileData customPathUnmarshalText `uri:"path,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {`bar/foo`}}, "uri")
+	require.NoError(t, err)
+
+	assert.Equal(t, "bar", s.FileData[0])
+	assert.Equal(t, "foo", s.FileData[1])
+}
+
+func TestMappingCustomSliceUnmarshalTextForm(t *testing.T) {
+	var s struct {
+		FileData customPathUnmarshalText `form:"path,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {`bar/foo`}}, "form")
+	require.NoError(t, err)
+
+	assert.Equal(t, "bar", s.FileData[0])
+	assert.Equal(t, "foo", s.FileData[1])
+}
+
+func TestMappingCustomSliceUnmarshalTextStopsWhenError(t *testing.T) {
+	var s struct {
+		FileData customPathUnmarshalText `form:"path,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"invalid"}}, "form")
+	require.ErrorContains(t, err, "invalid format")
+	require.Empty(t, s.FileData)
+}
+
+func TestMappingCustomSliceOfSliceUnmarshalTextUri(t *testing.T) {
+	var s struct {
+		FileData []customPathUnmarshalText `uri:"path,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"bar/foo,bar/foo/spam"}}, "uri")
+	require.NoError(t, err)
+	assert.Equal(t, []customPathUnmarshalText{{"bar", "foo"}, {"bar", "foo", "spam"}}, s.FileData)
+}
+
+func TestMappingCustomSliceOfSliceUnmarshalTextForm(t *testing.T) {
+	var s struct {
+		FileData []customPathUnmarshalText `form:"path,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {"bar/foo,bar/foo/spam"}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []customPathUnmarshalText{{"bar", "foo"}, {"bar", "foo", "spam"}}, s.FileData)
+}
+
+func TestMappingCustomSliceOfSliceUnmarshalTextDefault(t *testing.T) {
+	var s struct {
+		FileData []customPathUnmarshalText `form:"path,default=bar/foo;bar/foo/spam,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"path": {}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []customPathUnmarshalText{{"bar", "foo"}, {"bar", "foo", "spam"}}, s.FileData)
+}
+
+type objectIDUnmarshalText [12]byte
+
+func (o *objectIDUnmarshalText) UnmarshalText(text []byte) error {
+	oid, err := convertToOidUnmarshalText(string(text))
+	if err != nil {
+		return err
+	}
+
+	*o = oid
+	return nil
+}
+
+func convertToOidUnmarshalText(s string) (objectIDUnmarshalText, error) {
+	oid, err := convertTo(s)
+	return objectIDUnmarshalText(oid), err
+}
+
+var _ encoding.TextUnmarshaler = (*objectIDUnmarshalText)(nil)
+
+func TestMappingCustomArrayUnmarshalTextUri(t *testing.T) {
+	var s struct {
+		FileData objectIDUnmarshalText `uri:"id,parser=encoding.TextUnmarshaler"`
+	}
+	val := `664a062ac74a8ad104e0e80f`
+	err := mappingByPtr(&s, formSource{"id": {val}}, "uri")
+	require.NoError(t, err)
+
+	expected, _ := convertToOidUnmarshalText(val)
+	assert.Equal(t, expected, s.FileData)
+}
+
+func TestMappingCustomArrayUnmarshalTextForm(t *testing.T) {
+	var s struct {
+		FileData objectIDUnmarshalText `form:"id,parser=encoding.TextUnmarshaler"`
+	}
+	val := `664a062ac74a8ad104e0e80f`
+	err := mappingByPtr(&s, formSource{"id": {val}}, "form")
+	require.NoError(t, err)
+
+	expected, _ := convertToOidUnmarshalText(val)
+	assert.Equal(t, expected, s.FileData)
+}
+
+func TestMappingCustomArrayOfArrayUnmarshalTextUri(t *testing.T) {
+	id1, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80e`)
+	id2, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80f`)
+
+	var s struct {
+		FileData []objectIDUnmarshalText `uri:"ids,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"ids": {`664a062ac74a8ad104e0e80e,664a062ac74a8ad104e0e80f`}}, "uri")
+	require.NoError(t, err)
+	assert.Equal(t, []objectIDUnmarshalText{id1, id2}, s.FileData)
+}
+
+func TestMappingCustomArrayOfArrayUnmarshalTextForm(t *testing.T) {
+	id1, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80e`)
+	id2, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80f`)
+
+	var s struct {
+		FileData []objectIDUnmarshalText `form:"ids,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"ids": {`664a062ac74a8ad104e0e80e,664a062ac74a8ad104e0e80f`}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []objectIDUnmarshalText{id1, id2}, s.FileData)
+}
+
+func TestMappingCustomArrayOfArrayUnmarshalTextDefault(t *testing.T) {
+	id1, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80e`)
+	id2, _ := convertToOidUnmarshalText(`664a062ac74a8ad104e0e80f`)
+
+	var s struct {
+		FileData []objectIDUnmarshalText `form:"ids,default=664a062ac74a8ad104e0e80e;664a062ac74a8ad104e0e80f,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+	}
+	err := mappingByPtr(&s, formSource{"ids": {}}, "form")
+	require.NoError(t, err)
+	assert.Equal(t, []objectIDUnmarshalText{id1, id2}, s.FileData)
+}
+
+// If someone specifies parser=TextUnmarshaler and it's not defined for the type, gin should revert to using its default
+// binding logic.
+func TestMappingUsingBindUnmarshalerAndTextUnmarshalerWhenOnlyBindUnmarshalerDefined(t *testing.T) {
+	var s struct {
+		Hex                customUnmarshalParamHex `form:"hex"`
+		HexByUnmarshalText customUnmarshalParamHex `form:"hex2,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{
+		"hex":  {`f5`},
+		"hex2": {`f5`},
+	}, "form")
+	require.NoError(t, err)
+
+	assert.EqualValues(t, 0xf5, s.Hex)
+	assert.EqualValues(t, 0xf5, s.HexByUnmarshalText) // reverts to BindUnmarshaler binding
+}
+
+// If someone does not specify parser=TextUnmarshaler even when it's defined for the type, gin should ignore the
+// UnmarshalText logic and continue using its default binding logic. (This ensures gin does not break backwards
+// compatibility)
+func TestMappingUsingBindUnmarshalerAndTextUnmarshalerWhenOnlyTextUnmarshalerDefined(t *testing.T) {
+	var s struct {
+		Hex                customUnmarshalTextHex `form:"hex"`
+		HexByUnmarshalText customUnmarshalTextHex `form:"hex2,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{
+		"hex":  {`11`},
+		"hex2": {`11`},
+	}, "form")
+	require.NoError(t, err)
+
+	assert.EqualValues(t, 11, s.Hex)                  // this is using default int binding, not our custom hex binding. 0x11 should be 17 in decimal
+	assert.EqualValues(t, 0x11, s.HexByUnmarshalText) // correct expected value for normal hex binding
+}
+
+type customHexUnmarshalParamAndUnmarshalText int
+
+func (f *customHexUnmarshalParamAndUnmarshalText) UnmarshalParam(param string) error {
+	return errors.New("should not be called in unit test if parser tag present")
+}
+
+func (f *customHexUnmarshalParamAndUnmarshalText) UnmarshalText(text []byte) error {
+	v, err := strconv.ParseInt(string(text), 16, 64)
+	if err != nil {
+		return err
+	}
+	*f = customHexUnmarshalParamAndUnmarshalText(v)
+	return nil
+}
+
+// If a type has both UnmarshalParam and UnmarshalText methods defined, but the parser tag is set to TextUnmarshaler,
+// then only the UnmarshalText method should be invoked.
+func TestMappingUsingTextUnmarshalerWhenBindUnmarshalerAlsoDefined(t *testing.T) {
+	var s struct {
+		Hex customHexUnmarshalParamAndUnmarshalText `form:"hex,parser=encoding.TextUnmarshaler"`
+	}
+	err := mappingByPtr(&s, formSource{
+		"hex": {`f5`},
+	}, "form")
+	require.NoError(t, err)
+
+	assert.EqualValues(t, 0xf5, s.Hex)
+}
+
+// ====  TextUnmarshaler tests END ====
+
 func TestMappingEmptyValues(t *testing.T) {
 	t.Run("slice with default", func(t *testing.T) {
 		var s struct {

context.go

@@ -40,6 +40,7 @@ const (
 	MIMEYAML2             = binding.MIMEYAML2
 	MIMETOML              = binding.MIMETOML
 	MIMEPROTOBUF          = binding.MIMEPROTOBUF
+	MIMEBSON              = binding.MIMEBSON
 )
 
 // BodyBytesKey indicates a default body bytes key.
@@ -386,6 +387,11 @@ func (c *Context) GetDuration(key any) time.Duration {
 	return getTyped[time.Duration](c, key)
 }
 
+// GetError returns the value associated with the key as an error.
+func (c *Context) GetError(key any) error {
+	return getTyped[error](c, key)
+}
+
 // GetIntSlice returns the value associated with the key as a slice of integers.
 func (c *Context) GetIntSlice(key any) []int {
 	return getTyped[[]int](c, key)
@@ -451,6 +457,11 @@ func (c *Context) GetStringSlice(key any) []string {
 	return getTyped[[]string](c, key)
 }
 
+// GetErrorSlice returns the value associated with the key as a slice of errors.
+func (c *Context) GetErrorSlice(key any) []error {
+	return getTyped[[]error](c, key)
+}
+
 // GetStringMap returns the value associated with the key as a map of interfaces.
 func (c *Context) GetStringMap(key any) map[string]any {
 	return getTyped[map[string]any](c, key)
@@ -978,18 +989,32 @@ func (c *Context) ClientIP() string {
 		}
 	}
 
-	// It also checks if the remoteIP is a trusted proxy or not.
-	// In order to perform this validation, it will see if the IP is contained within at least one of the CIDR blocks
-	// defined by Engine.SetTrustedProxies()
-	remoteIP := net.ParseIP(c.RemoteIP())
-	if remoteIP == nil {
-		return ""
+	var (
+		trusted  bool
+		remoteIP net.IP
+	)
+	// If gin is listening a unix socket, always trust it.
+	localAddr, ok := c.Request.Context().Value(http.LocalAddrContextKey).(net.Addr)
+	if ok && strings.HasPrefix(localAddr.Network(), "unix") {
+		trusted = true
+	}
+
+	// Fallback
+	if !trusted {
+		// It also checks if the remoteIP is a trusted proxy or not.
+		// In order to perform this validation, it will see if the IP is contained within at least one of the CIDR blocks
+		// defined by Engine.SetTrustedProxies()
+		remoteIP = net.ParseIP(c.RemoteIP())
+		if remoteIP == nil {
+			return ""
+		}
+		trusted = c.engine.isTrustedProxy(remoteIP)
 	}
-	trusted := c.engine.isTrustedProxy(remoteIP)
 
 	if trusted && c.engine.ForwardedByClientIP && c.engine.RemoteIPHeaders != nil {
 		for _, headerName := range c.engine.RemoteIPHeaders {
-			ip, valid := c.engine.validateHeader(c.requestHeader(headerName))
+			headerValue := strings.Join(c.Request.Header.Values(headerName), ",")
+			ip, valid := c.engine.validateHeader(headerValue)
 			if valid {
 				return ip
 			}
@@ -1213,6 +1238,11 @@ func (c *Context) ProtoBuf(code int, obj any) {
 	c.Render(code, render.ProtoBuf{Data: obj})
 }
 
+// BSON serializes the given struct as BSON into the response body.
+func (c *Context) BSON(code int, obj any) {
+	c.Render(code, render.BSON{Data: obj})
+}
+
 // String writes the given string into the response body.
 func (c *Context) String(code int, format string, values ...any) {
 	c.Render(code, render.String{Format: format, Data: values})
@@ -1320,6 +1350,7 @@ type Negotiate struct {
 	Data         any
 	TOMLData     any
 	PROTOBUFData any
+	BSONData     any
 }
 
 // Negotiate calls different Render according to acceptable Accept format.
@@ -1349,6 +1380,10 @@ func (c *Context) Negotiate(code int, config Negotiate) {
 		data := chooseData(config.PROTOBUFData, config.Data)
 		c.ProtoBuf(code, data)
 
+	case binding.MIMEBSON:
+		data := chooseData(config.BSONData, config.Data)
+		c.BSON(code, data)
+
 	default:
 		c.AbortWithError(http.StatusNotAcceptable, errors.New("the accepted formats are not offered by the server")) //nolint: errcheck
 	}

context_test.go

@@ -32,6 +32,7 @@ import (
 	testdata "github.com/gin-gonic/gin/testdata/protoexample"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.mongodb.org/mongo-driver/bson"
 	"google.golang.org/protobuf/proto"
 )
 
@@ -516,6 +517,14 @@ func TestContextGetDuration(t *testing.T) {
 	assert.Equal(t, time.Second, c.GetDuration("duration"))
 }
 
+func TestContextGetError(t *testing.T) {
+	c, _ := CreateTestContext(httptest.NewRecorder())
+	key := "error"
+	value := errors.New("test error")
+	c.Set(key, value)
+	assert.Equal(t, value, c.GetError(key))
+}
+
 func TestContextGetIntSlice(t *testing.T) {
 	c, _ := CreateTestContext(httptest.NewRecorder())
 	key := "int-slice"
@@ -618,6 +627,14 @@ func TestContextGetStringSlice(t *testing.T) {
 	assert.Equal(t, []string{"foo"}, c.GetStringSlice("slice"))
 }
 
+func TestContextGetErrorSlice(t *testing.T) {
+	c, _ := CreateTestContext(httptest.NewRecorder())
+	key := "error-slice"
+	value := []error{errors.New("error1"), errors.New("error2")}
+	c.Set(key, value)
+	assert.Equal(t, value, c.GetErrorSlice(key))
+}
+
 func TestContextGetStringMap(t *testing.T) {
 	c, _ := CreateTestContext(httptest.NewRecorder())
 	m := make(map[string]any)
@@ -1143,6 +1160,37 @@ func TestContextRenderNoContentIndentedJSON(t *testing.T) {
 	assert.Equal(t, "application/json; charset=utf-8", w.Header().Get("Content-Type"))
 }
 
+func TestContextClientIPWithMultipleHeaders(t *testing.T) {
+	c, _ := CreateTestContext(httptest.NewRecorder())
+	c.Request, _ = http.NewRequest(http.MethodGet, "/test", nil)
+
+	// Multiple X-Forwarded-For headers
+	c.Request.Header.Add("X-Forwarded-For", "1.2.3.4, "+localhostIP)
+	c.Request.Header.Add("X-Forwarded-For", "5.6.7.8")
+	c.Request.RemoteAddr = localhostIP + ":1234"
+
+	c.engine.ForwardedByClientIP = true
+	c.engine.RemoteIPHeaders = []string{"X-Forwarded-For"}
+	_ = c.engine.SetTrustedProxies([]string{localhostIP})
+
+	// Should return 5.6.7.8 (last non-trusted IP)
+	assert.Equal(t, "5.6.7.8", c.ClientIP())
+}
+
+func TestContextClientIPWithSingleHeader(t *testing.T) {
+	c, _ := CreateTestContext(httptest.NewRecorder())
+	c.Request, _ = http.NewRequest(http.MethodGet, "/test", nil)
+	c.Request.Header.Set("X-Forwarded-For", "1.2.3.4, "+localhostIP)
+	c.Request.RemoteAddr = localhostIP + ":1234"
+
+	c.engine.ForwardedByClientIP = true
+	c.engine.RemoteIPHeaders = []string{"X-Forwarded-For"}
+	_ = c.engine.SetTrustedProxies([]string{localhostIP})
+
+	// Should return 1.2.3.4
+	assert.Equal(t, "1.2.3.4", c.ClientIP())
+}
+
 // Tests that the response is serialized as Secure JSON
 // and Content-Type is set to application/json
 func TestContextRenderSecureJSON(t *testing.T) {
@@ -1654,6 +1702,23 @@ func TestContextNegotiationWithPROTOBUF(t *testing.T) {
 	assert.Equal(t, "application/x-protobuf", w.Header().Get("Content-Type"))
 }
 
+func TestContextNegotiationWithBSON(t *testing.T) {
+	w := httptest.NewRecorder()
+	c, _ := CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodPost, "", nil)
+
+	c.Negotiate(http.StatusOK, Negotiate{
+		Offered: []string{MIMEBSON, MIMEXML, MIMEJSON, MIMEYAML, MIMEYAML2},
+		Data:    H{"foo": "bar"},
+	})
+
+	bData, _ := bson.Marshal(H{"foo": "bar"})
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, string(bData), w.Body.String())
+	assert.Equal(t, "application/bson", w.Header().Get("Content-Type"))
+}
+
 func TestContextNegotiationNotSupport(t *testing.T) {
 	w := httptest.NewRecorder()
 	c, _ := CreateTestContext(w)
@@ -1884,6 +1949,16 @@ func TestContextClientIP(t *testing.T) {
 	c.engine.trustedCIDRs, _ = c.engine.prepareTrustedCIDRs()
 	resetContextForClientIPTests(c)
 
+	// unix address
+	addr := &net.UnixAddr{Net: "unix", Name: "@"}
+	c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), http.LocalAddrContextKey, addr))
+	c.Request.RemoteAddr = addr.String()
+	assert.Equal(t, "20.20.20.20", c.ClientIP())
+
+	// reset
+	c.Request = c.Request.WithContext(context.Background())
+	resetContextForClientIPTests(c)
+
 	// Legacy tests (validating that the defaults don't break the
 	// (insecure!) old behaviour)
 	assert.Equal(t, "20.20.20.20", c.ClientIP())
@@ -3620,22 +3695,22 @@ func BenchmarkGetMapFromFormData(b *testing.B) {
 
 	// Test case 3: Large dataset with many bracket keys
 	largeData := make(map[string][]string)
-	for i := 0; i < 100; i++ {
+	for i := range 100 {
 		key := fmt.Sprintf("ids[%d]", i)
 		largeData[key] = []string{fmt.Sprintf("value%d", i)}
 	}
-	for i := 0; i < 50; i++ {
+	for i := range 50 {
 		key := fmt.Sprintf("names[%d]", i)
 		largeData[key] = []string{fmt.Sprintf("name%d", i)}
 	}
-	for i := 0; i < 25; i++ {
+	for i := range 25 {
 		key := fmt.Sprintf("other[key%d]", i)
 		largeData[key] = []string{fmt.Sprintf("other%d", i)}
 	}
 
 	// Test case 4: Dataset with many non-matching keys (worst case)
 	worstCaseData := make(map[string][]string)
-	for i := 0; i < 100; i++ {
+	for i := range 100 {
 		key := fmt.Sprintf("nonmatching%d", i)
 		worstCaseData[key] = []string{fmt.Sprintf("value%d", i)}
 	}
@@ -3671,7 +3746,7 @@ func BenchmarkGetMapFromFormData(b *testing.B) {
 	for _, bm := range benchmarks {
 		b.Run(bm.name, func(b *testing.B) {
 			b.ReportAllocs()
-			for i := 0; i < b.N; i++ {
+			for b.Loop() {
 				_, _ = getMapFromFormData(bm.data, bm.key)
 			}
 		})

docs/doc.md

@@ -911,7 +911,7 @@ curl -X POST http://localhost:8080/person
 
 NOTE: For default [collection values](#collection-format-for-arrays), the following rules apply:
 - Since commas are used to delimit tag options, they are not supported within a default value and will result in undefined behavior
-- For the collection formats "multi" and "csv", a semicolon should be used in place of a comma to delimited default values
+- For the collection formats "multi" and "csv", a semicolon should be used in place of a comma to delimit default values
 - Since semicolons are used to delimit default values for "multi" and "csv", they are not supported within a default value for "multi" and "csv"
 
 
@@ -1009,12 +1009,68 @@ curl -v localhost:8088/thinkerou/not-uuid
 
 ### Bind custom unmarshaler
 
+To override gin's default binding logic, define a function on your type that satisfies the `encoding.TextUnmarshaler` interface from the Golang standard library. Then specify `parser=encoding.TextUnmarshaler` in the `uri`/`form` tag of the field being bound.
+
 ```go
 package main
 
 import (
-  "github.com/gin-gonic/gin"
+  "encoding"
   "strings"
+
+  "github.com/gin-gonic/gin"
+)
+
+type Birthday string
+
+func (b *Birthday) UnmarshalText(text []byte) error {
+  *b = Birthday(strings.Replace(string(text), "-", "/", -1))
+  return nil
+}
+
+var _ encoding.TextUnmarshaler = (*Birthday)(nil) //assert Birthday implements encoding.TextUnmarshaler
+
+func main() {
+  route := gin.Default()
+  var request struct {
+    Birthday         Birthday   `form:"birthday,parser=encoding.TextUnmarshaler"`
+    Birthdays        []Birthday `form:"birthdays,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+    BirthdaysDefault []Birthday `form:"birthdaysDef,default=2020-09-01;2020-09-02,parser=encoding.TextUnmarshaler" collection_format:"csv"`
+  }
+  route.GET("/test", func(ctx *gin.Context) {
+    _ = ctx.BindQuery(&request)
+    ctx.JSON(200, request)
+  })
+  _ = route.Run(":8088")
+}
+```
+
+Test it with:
+
+```sh
+curl 'localhost:8088/test?birthday=2000-01-01&birthdays=2000-01-01,2000-01-02'
+```
+Result
+```sh
+{"Birthday":"2000/01/01","Birthdays":["2000/01/01","2000/01/02"],"BirthdaysDefault":["2020/09/01","2020/09/02"]}
+```
+
+Note:
+- If `parser=encoding.TextUnmarshaler` is specified for a type that does **not** implement `encoding.TextUnmarshaler`, gin will ignore it and proceed with its default binding logic.
+- If `parser=encoding.TextUnmarshaler` is specified for a type and that type's implementation of `encoding.TextUnmarshaler` returns an error, gin will stop binding and return the error to the client.
+
+---
+
+If a type already implements `encoding.TextUnmarshaler` but you want to customize how gin binds the type differently (eg to change what error message is returned), you can implement the dedicated `BindUnmarshaler` interface provided by gin instead.
+
+```go
+package main
+
+import (
+  "strings"
+
+  "github.com/gin-gonic/gin"
+  "github.com/gin-gonic/gin/binding"
 )
 
 type Birthday string
@@ -1024,29 +1080,37 @@ func (b *Birthday) UnmarshalParam(param string) error {
   return nil
 }
 
+var _ binding.BindUnmarshaler = (*Birthday)(nil) //assert Birthday implements binding.BindUnmarshaler
+
 func main() {
   route := gin.Default()
   var request struct {
-    Birthday Birthday `form:"birthday"`
+    Birthday         Birthday   `form:"birthday"`
+    Birthdays        []Birthday `form:"birthdays" collection_format:"csv"`
+    BirthdaysDefault []Birthday `form:"birthdaysDef,default=2020-09-01;2020-09-02" collection_format:"csv"`
   }
   route.GET("/test", func(ctx *gin.Context) {
     _ = ctx.BindQuery(&request)
-    ctx.JSON(200, request.Birthday)
+    ctx.JSON(200, request)
   })
-  route.Run(":8088")
+  _ = route.Run(":8088")
 }
 ```
 
 Test it with:
 
 ```sh
-curl 'localhost:8088/test?birthday=2000-01-01'
+curl 'localhost:8088/test?birthday=2000-01-01&birthdays=2000-01-01,2000-01-02'
 ```
 Result
 ```sh
-"2000/01/01"
+{"Birthday":"2000/01/01","Birthdays":["2000/01/01","2000/01/02"],"BirthdaysDefault":["2020/09/01","2020/09/02"]}
 ```
 
+Note:
+- If a type implements both `encoding.TextUnmarshaler` and `BindUnmarshaler`, gin will use `BindUnmarshaler` by default unless you specify `parser=encoding.TextUnmarshaler` in the binding tag.
+- If a type returns an error from its implementation of `BindUnmarshaler`, gin will stop binding and return the error to the client.
+
 ### Bind Header
 
 ```go

gin_integration_test.go

@@ -400,7 +400,7 @@ func TestConcurrentHandleContext(t *testing.T) {
 	var wg sync.WaitGroup
 	iterations := 200
 	wg.Add(iterations)
-	for i := 0; i < iterations; i++ {
+	for range iterations {
 		go func() {
 			req, err := http.NewRequest(http.MethodGet, "/", nil)
 			assert.NoError(t, err)

go.mod

@@ -2,12 +2,14 @@ module github.com/gin-gonic/gin
 
 go 1.24.0
 
+toolchain go1.24.7
+
 require (
 	github.com/bytedance/sonic v1.14.2
 	github.com/gin-contrib/sse v1.1.0
 	github.com/go-playground/validator/v10 v10.28.0
-	github.com/goccy/go-json v0.10.2
-	github.com/goccy/go-yaml v1.19.0
+	github.com/goccy/go-json v0.10.5
+	github.com/goccy/go-yaml v1.19.1
 	github.com/json-iterator/go v1.1.12
 	github.com/mattn/go-isatty v0.0.20
 	github.com/modern-go/reflect2 v1.0.2
@@ -15,10 +17,13 @@ require (
 	github.com/quic-go/quic-go v0.57.1
 	github.com/stretchr/testify v1.11.1
 	github.com/ugorji/go/codec v1.3.1
+	go.mongodb.org/mongo-driver v1.17.7
 	golang.org/x/net v0.47.0
 	google.golang.org/protobuf v1.36.10
 )
 
+require gopkg.in/yaml.v3 v3.0.1 // indirect
+
 require (
 	github.com/bytedance/gopkg v0.1.3 // indirect
 	github.com/bytedance/sonic/loader v0.4.0 // indirect
@@ -30,13 +35,13 @@ require (
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/kr/text v0.2.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
-	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
-	golang.org/x/arch v0.20.0 // indirect
+	go.uber.org/mock v0.6.0 // indirect
+	golang.org/x/arch v0.22.0 // indirect
 	golang.org/x/crypto v0.45.0 // indirect
 	golang.org/x/sys v0.38.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -22,10 +22,10 @@ github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJn
 github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
 github.com/go-playground/validator/v10 v10.28.0 h1:Q7ibns33JjyW48gHkuFT91qX48KG0ktULL6FgHdG688=
 github.com/go-playground/validator/v10 v10.28.0/go.mod h1:GoI6I1SjPBh9p7ykNE/yj3fFYbyDOpwMn5KXd+m2hUU=
-github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
-github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
-github.com/goccy/go-yaml v1.19.0 h1:EmkZ9RIsX+Uq4DYFowegAuJo8+xdX3T/2dwNPXbxEYE=
-github.com/goccy/go-yaml v1.19.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/goccy/go-yaml v1.19.1 h1:3rG3+v8pkhRqoQ/88NYNMHYVGYztCOCIZ7UQhu7H+NE=
+github.com/goccy/go-yaml v1.19.1/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -41,8 +41,9 @@ github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 h1:ZqeYNhU3OHLH3mGKHDcjJRFFRrJa6eAM5H+CtDdOsPc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
@@ -70,10 +71,12 @@ github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
 github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
-go.uber.org/mock v0.5.2 h1:LbtPTcP8A5k9WPXj54PPPbjcI4Y6lhyOZXn+VS7wNko=
-go.uber.org/mock v0.5.2/go.mod h1:wLlUxC2vVTPTaE3UD51E0BGOAElKrILxhVSDYQLld5o=
-golang.org/x/arch v0.20.0 h1:dx1zTU0MAE98U+TQ8BLl7XsJbgze2WnNKF/8tGp/Q6c=
-golang.org/x/arch v0.20.0/go.mod h1:bdwinDaKcfZUGpH09BB7ZmOfhalA8lQdzl62l8gGWsk=
+go.mongodb.org/mongo-driver v1.17.7 h1:a9w+U3Vt67eYzcfq3k/OAv284/uUUkL0uP75VE5rCOU=
+go.mongodb.org/mongo-driver v1.17.7/go.mod h1:Hy04i7O2kC4RS06ZrhPRqj/u4DTYkFDAAccj+rVKqgQ=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
+golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
 golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
 golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=

internal/bytesconv/bytesconv_test.go

@@ -30,7 +30,7 @@ func rawStrToBytes(s string) []byte {
 
 func TestBytesToString(t *testing.T) {
 	data := make([]byte, 1024)
-	for i := 0; i < 100; i++ {
+	for range 100 {
 		_, err := cRand.Read(data)
 		if err != nil {
 			t.Fatal(err)
@@ -79,7 +79,7 @@ func RandStringBytesMaskImprSrcSB(n int) string {
 }
 
 func TestStringToBytes(t *testing.T) {
-	for i := 0; i < 100; i++ {
+	for range 100 {
 		s := RandStringBytesMaskImprSrcSB(64)
 		if !bytes.Equal(rawStrToBytes(s), StringToBytes(s)) {
 			t.Fatal("don't match")

recovery.go

@@ -12,12 +12,12 @@ import (
 	"fmt"
 	"io"
 	"log"
-	"net"
 	"net/http"
 	"net/http/httputil"
 	"os"
 	"runtime"
 	"strings"
+	"syscall"
 	"time"
 
 	"github.com/gin-gonic/gin/internal/bytesconv"
@@ -57,40 +57,33 @@ func CustomRecoveryWithWriter(out io.Writer, handle RecoveryFunc) HandlerFunc {
 	}
 	return func(c *Context) {
 		defer func() {
-			if err := recover(); err != nil {
+			if rec := recover(); rec != nil {
 				// Check for a broken connection, as it is not really a
 				// condition that warrants a panic stack trace.
-				var brokenPipe bool
-				if ne, ok := err.(*net.OpError); ok {
-					var se *os.SyscallError
-					if errors.As(ne, &se) {
-						seStr := strings.ToLower(se.Error())
-						if strings.Contains(seStr, "broken pipe") ||
-							strings.Contains(seStr, "connection reset by peer") {
-							brokenPipe = true
-						}
-					}
-				}
-				if e, ok := err.(error); ok && errors.Is(e, http.ErrAbortHandler) {
-					brokenPipe = true
+				var isBrokenPipe bool
+				err, ok := rec.(error)
+				if ok {
+					isBrokenPipe = errors.Is(err, syscall.EPIPE) ||
+						errors.Is(err, syscall.ECONNRESET) ||
+						errors.Is(err, http.ErrAbortHandler)
 				}
 				if logger != nil {
-					if brokenPipe {
-						logger.Printf("%s\n%s%s", err, secureRequestDump(c.Request), reset)
+					if isBrokenPipe {
+						logger.Printf("%s\n%s%s", rec, secureRequestDump(c.Request), reset)
 					} else if IsDebugging() {
 						logger.Printf("[Recovery] %s panic recovered:\n%s\n%s\n%s%s",
-							timeFormat(time.Now()), secureRequestDump(c.Request), err, stack(stackSkip), reset)
+							timeFormat(time.Now()), secureRequestDump(c.Request), rec, stack(stackSkip), reset)
 					} else {
 						logger.Printf("[Recovery] %s panic recovered:\n%s\n%s%s",
-							timeFormat(time.Now()), err, stack(stackSkip), reset)
+							timeFormat(time.Now()), rec, stack(stackSkip), reset)
 					}
 				}
-				if brokenPipe {
+				if isBrokenPipe {
 					// If the connection is dead, we can't write a status to it.
-					c.Error(err.(error)) //nolint: errcheck
+					c.Error(err) //nolint: errcheck
 					c.Abort()
 				} else {
-					handle(c, err)
+					handle(c, rec)
 				}
 			}
 		}()

recovery_test.go

@@ -98,13 +98,13 @@ func TestFunction(t *testing.T) {
 func TestPanicWithBrokenPipe(t *testing.T) {
 	const expectCode = 204
 
-	expectMsgs := map[syscall.Errno]string{
-		syscall.EPIPE:      "broken pipe",
-		syscall.ECONNRESET: "connection reset by peer",
+	expectErrnos := []syscall.Errno{
+		syscall.EPIPE,
+		syscall.ECONNRESET,
 	}
 
-	for errno, expectMsg := range expectMsgs {
-		t.Run(expectMsg, func(t *testing.T) {
+	for _, errno := range expectErrnos {
+		t.Run("Recovery from "+errno.Error(), func(t *testing.T) {
 			var buf strings.Builder
 
 			router := New()
@@ -122,7 +122,8 @@ func TestPanicWithBrokenPipe(t *testing.T) {
 			w := PerformRequest(router, http.MethodGet, "/recovery")
 			// TEST
 			assert.Equal(t, expectCode, w.Code)
-			assert.Contains(t, strings.ToLower(buf.String()), expectMsg)
+			assert.Contains(t, strings.ToLower(buf.String()), errno.Error())
+			assert.NotContains(t, strings.ToLower(buf.String()), "[Recovery]")
 		})
 	}
 }

render/bson.go

@@ -0,0 +1,34 @@
+// Copyright 2025 Gin Core Team. All rights reserved.
+// Use of this source code is governed by a MIT style
+// license that can be found in the LICENSE file.
+
+package render
+
+import (
+	"net/http"
+
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// BSON contains the given interface object.
+type BSON struct {
+	Data any
+}
+
+var bsonContentType = []string{"application/bson"}
+
+// Render (BSON) marshals the given interface object and writes data with custom ContentType.
+func (r BSON) Render(w http.ResponseWriter) error {
+	r.WriteContentType(w)
+
+	bytes, err := bson.Marshal(&r.Data)
+	if err == nil {
+		_, err = w.Write(bytes)
+	}
+	return err
+}
+
+// WriteContentType (BSONBuf) writes BSONBuf ContentType.
+func (r BSON) WriteContentType(w http.ResponseWriter) {
+	writeContentType(w, bsonContentType)
+}

render/render_test.go

@@ -19,6 +19,7 @@ import (
 	testdata "github.com/gin-gonic/gin/testdata/protoexample"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.mongodb.org/mongo-driver/bson"
 	"google.golang.org/protobuf/proto"
 )
 
@@ -359,6 +360,31 @@ func TestRenderProtoBufFail(t *testing.T) {
 	require.Error(t, err)
 }
 
+func TestRenderBSON(t *testing.T) {
+	w := httptest.NewRecorder()
+	reps := []int64{int64(1), int64(2)}
+	type mystruct struct {
+		Label string
+		Reps  []int64
+	}
+
+	data := &mystruct{
+		Label: "test",
+		Reps:  reps,
+	}
+
+	(BSON{data}).WriteContentType(w)
+	bsonData, err := bson.Marshal(data)
+	require.NoError(t, err)
+	assert.Equal(t, "application/bson", w.Header().Get("Content-Type"))
+
+	err = (BSON{data}).Render(w)
+
+	require.NoError(t, err)
+	assert.Equal(t, bsonData, w.Body.Bytes())
+	assert.Equal(t, "application/bson", w.Header().Get("Content-Type"))
+}
+
 func TestRenderXML(t *testing.T) {
 	w := httptest.NewRecorder()
 	data := xmlmap{

tree.go

@@ -671,12 +671,7 @@ walk: // Outer loop for walking the tree
 func (n *node) findCaseInsensitivePath(path string, fixTrailingSlash bool) ([]byte, bool) {
 	const stackBufSize = 128
 
-	// Use a static sized buffer on the stack in the common case.
-	// If the path is too long, allocate a buffer on the heap instead.
-	buf := make([]byte, 0, stackBufSize)
-	if length := len(path) + 1; length > stackBufSize {
-		buf = make([]byte, 0, length)
-	}
+	buf := make([]byte, 0, max(stackBufSize, len(path)+1))
 
 	ciPath := n.findCaseInsensitivePathRec(
 		path,

utils.go

@@ -162,7 +162,7 @@ func resolveAddress(addr []string) string {
 
 // https://stackoverflow.com/questions/53069040/checking-a-string-contains-only-ascii-characters
 func isASCII(s string) bool {
-	for i := 0; i < len(s); i++ {
+	for i := range len(s) {
 		if s[i] > unicode.MaxASCII {
 			return false
 		}