add Context.ReadHeaders

HISTORY.md

@@ -600,7 +600,8 @@ New Package-level Variables:
 
 New Context Methods:
 
-- `Context.ReadParams(ptr interface{}) error` to bind dynamic path parameters. [Example](https://github.com/kataras/iris/blob/master/_examples/request-body/read-params/main.go).
+- `Context.ReadHeaders(ptr interface{}) error` binds request headers to "ptr". [Example](https://github.com/kataras/iris/blob/master/_examples/request-body/read-headers/main.go).
+- `Context.ReadParams(ptr interface{}) error` binds dynamic path parameters to "ptr". [Example](https://github.com/kataras/iris/blob/master/_examples/request-body/read-params/main.go).
 - `Context.SaveFormFile(fh *multipart.FileHeader, dest string) (int64, error)` previously unexported. Accepts a result file of `Context.FormFile` and saves it to the disk.
 - `Context.URLParamSlice(name string) []string` is a a shortcut of `ctx.Request().URL.Query()[name]`. Like `URLParam` but it returns all values as a string slice instead of a single string separated by commas.
 - `Context.PostValueMany(name string) (string, error)` returns the post data of a given key. The returned value is a single string separated by commas on multiple values. It also reports whether the form was empty or when the "name" does not exist or whether the available values are empty. It strips any empty key-values from the slice before return. See `ErrEmptyForm`, `ErrNotFound` and `ErrEmptyFormField` respectfully. The `PostValueInt`, `PostValueInt64`, `PostValueFloat64` and `PostValueBool` now respect the above errors too (the `PostValues` method now returns a second output argument of `error` too, see breaking changes below). 

_examples/README.md

@@ -138,6 +138,7 @@
     * [Bind YAML](request-body/read-yaml/main.go)
     * [Bind Form](request-body/read-form/main.go)
     * [Bind Query](request-body/read-query/main.go)
+    * [Bind Headers](request-body/read-headers/main.go)
     * [Bind Params](request-body/read-params/main.go)
     * [Bind Body](request-body/read-body/main.go)
     * [Bind Custom per type](request-body/read-custom-per-type/main.go)

_examples/request-body/read-headers/main.go

@@ -0,0 +1,41 @@
+// package main contains an example on how to use the ReadHeaders,
+// same way you can do the ReadQuery, ReadJSON, ReadProtobuf and e.t.c.
+package main
+
+import (
+	"github.com/kataras/iris/v12"
+)
+
+type myHeaders struct {
+	RequestID      string `header:"X-Request-Id,required"`
+	Authentication string `header:"Authentication,required"`
+}
+
+func main() {
+	app := newApp()
+
+	// http://localhost:8080
+	/*
+		myHeaders: main.myHeaders{
+			RequestID: "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
+			Authentication: "Bearer my-token",
+		}
+	*/
+	app.Listen(":8080")
+}
+
+func newApp() *iris.Application {
+	app := iris.New()
+
+	app.Get("/", func(ctx iris.Context) {
+		var hs myHeaders
+		if err := ctx.ReadHeaders(&hs); err != nil {
+			ctx.StopWithError(iris.StatusInternalServerError, err)
+			return
+		}
+
+		ctx.Writef("myHeaders: %#v", hs)
+	})
+
+	return app
+}

_examples/request-body/read-headers/main_test.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/kataras/iris/v12/httptest"
+)
+
+func TestReadHeaders(t *testing.T) {
+	app := newApp()
+
+	e := httptest.New(t, app)
+
+	expectedOKBody := `myHeaders: main.myHeaders{RequestID:"373713f0-6b4b-42ea-ab9f-e2e04bc38e73", Authentication:"Bearer my-token"}`
+
+	tests := []struct {
+		headers map[string]string
+		code    int
+		body    string
+	}{
+		{headers: map[string]string{
+			"X-Request-Id":   "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
+			"Authentication": "Bearer my-token",
+		}, code: 200, body: expectedOKBody},
+		{headers: map[string]string{
+			"x-request-id":   "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
+			"authentication": "Bearer my-token",
+		}, code: 200, body: expectedOKBody},
+		{headers: map[string]string{
+			"X-Request-ID":   "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
+			"Authentication": "Bearer my-token",
+		}, code: 200, body: expectedOKBody},
+		{headers: map[string]string{
+			"Authentication": "Bearer my-token",
+		}, code: 500, body: "X-Request-Id is empty"},
+		{headers: map[string]string{
+			"X-Request-ID": "373713f0-6b4b-42ea-ab9f-e2e04bc38e73",
+		}, code: 500, body: "Authentication is empty"},
+		{headers: map[string]string{}, code: 500, body: "X-Request-Id is empty (and 1 other error)"},
+	}
+
+	for _, tt := range tests {
+		e.GET("/").WithHeaders(tt.headers).Expect().Status(tt.code).Body().Equal(tt.body)
+	}
+}

context/context.go

@@ -2289,6 +2289,18 @@ func (ctx *Context) ReadQuery(ptr interface{}) error {
 	return ctx.app.Validate(ptr)
 }
 
+// ReadHeaders binds request headers to "ptr". The struct field tag is "header".
+//
+// Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-headers/main.go
+func (ctx *Context) ReadHeaders(ptr interface{}) error {
+	err := schema.DecodeHeaders(ctx.request.Header, ptr)
+	if err != nil {
+		return err
+	}
+
+	return ctx.app.Validate(ptr)
+}
+
 // ReadParams binds URI Dynamic Path Parameters to "ptr". The struct field tag is "param".
 //
 // Example: https://github.com/kataras/iris/blob/master/_examples/request-body/read-params/main.go

go.mod

@@ -17,7 +17,7 @@ require (
 	github.com/iris-contrib/httpexpect/v2 v2.0.5
 	github.com/iris-contrib/jade v1.1.4
 	github.com/iris-contrib/pongo2 v0.0.1
-	github.com/iris-contrib/schema v0.0.3
+	github.com/iris-contrib/schema v0.0.5
 	github.com/json-iterator/go v1.1.10
 	github.com/kataras/blocks v0.0.2
 	github.com/kataras/golog v0.1.2
@@ -38,7 +38,7 @@ require (
 	go.etcd.io/bbolt v1.3.5
 	golang.org/x/crypto v0.0.0-20200820211705-5c72a883971a
 	golang.org/x/net v0.0.0-20200822124328-c89045814202
-	golang.org/x/sys v0.0.0-20200828194041-157a740278f4
+	golang.org/x/sys v0.0.0-20200831180312-196b9ba8737a
 	golang.org/x/text v0.3.3
 	golang.org/x/time v0.0.0-20200630173020-3af7569d3a1e
 	google.golang.org/protobuf v1.25.0