Add example for struct validation(3rd-party) through json request body binding

Former-commit-id: 78bbbe068f219e5a264951c900b77cb9b70f2079

_examples/README.md

@@ -325,6 +325,7 @@ You can serve [quicktemplate](https://github.com/valyala/quicktemplate) and [her
 ### How to Read from `context.Request() *http.Request`
 
 - [Read JSON](http_request/read-json/main.go)
+    * [Struct Validation](http_request/read-json-struct-validation/main.go)
 - [Read XML](http_request/read-xml/main.go)
 - [Read Form](http_request/read-form/main.go)
 - [Read Custom per type](http_request/read-custom-per-type/main.go)

_examples/http_request/read-json-struct-validation/main.go

@@ -0,0 +1,143 @@
+// Package main shows the validator(latest, version 9) integration with Iris.
+// You can find more examples like this at: https://github.com/go-playground/validator/blob/v9/_examples
+package main
+
+import (
+	"fmt"
+
+	"github.com/kataras/iris"
+	// $ go get gopkg.in/go-playground/validator.v9
+	"gopkg.in/go-playground/validator.v9"
+)
+
+// User contains user information.
+type User struct {
+	FirstName      string     `json:"fname"`
+	LastName       string     `json:"lname"`
+	Age            uint8      `json:"age" validate:"gte=0,lte=130"`
+	Email          string     `json:"email" validate:"required,email"`
+	FavouriteColor string     `json:"favColor" validate:"hexcolor|rgb|rgba"`
+	Addresses      []*Address `json:"addresses" validate:"required,dive,required"` // a person can have a home and cottage...
+}
+
+// Address houses a users address information.
+type Address struct {
+	Street string `json:"street" validate:"required"`
+	City   string `json:"city" validate:"required"`
+	Planet string `json:"planet" validate:"required"`
+	Phone  string `json:"phone" validate:"required"`
+}
+
+// Use a single instance of Validate, it caches struct info.
+var validate *validator.Validate
+
+func main() {
+	validate = validator.New()
+
+	// Register validation for 'User'
+	// NOTE: only have to register a non-pointer type for 'User', validator
+	// interanlly dereferences during it's type checks.
+	validate.RegisterStructValidation(UserStructLevelValidation, User{})
+
+	app := iris.New()
+	app.Post("/user", func(ctx iris.Context) {
+		var user User
+		if err := ctx.ReadJSON(&user); err != nil {
+			// Handle error.
+		}
+
+		// Returns InvalidValidationError for bad validation input, nil or ValidationErrors ( []FieldError )
+		err := validate.Struct(user)
+		if err != nil {
+
+			// This check is only needed when your code could produce
+			// an invalid value for validation such as interface with nil
+			// value most including myself do not usually have code like this.
+			if _, ok := err.(*validator.InvalidValidationError); ok {
+				ctx.StatusCode(iris.StatusInternalServerError)
+				ctx.WriteString(err.Error())
+				return
+			}
+
+			ctx.StatusCode(iris.StatusBadRequest)
+			for _, err := range err.(validator.ValidationErrors) {
+				fmt.Println()
+				fmt.Println(err.Namespace())
+				fmt.Println(err.Field())
+				fmt.Println(err.StructNamespace()) // Can differ when a custom TagNameFunc is registered or.
+				fmt.Println(err.StructField())     // By passing alt name to ReportError like below.
+				fmt.Println(err.Tag())
+				fmt.Println(err.ActualTag())
+				fmt.Println(err.Kind())
+				fmt.Println(err.Type())
+				fmt.Println(err.Value())
+				fmt.Println(err.Param())
+				fmt.Println()
+
+				// Or collect these as json objects
+				// and send back to the client the collected errors via ctx.JSON
+				// {
+				// 	"namespace":        err.Namespace(),
+				// 	"field":            err.Field(),
+				// 	"struct_namespace": err.StructNamespace(),
+				// 	"struct_field":     err.StructField(),
+				// 	"tag":              err.Tag(),
+				// 	"actual_tag":       err.ActualTag(),
+				// 	"kind":             err.Kind().String(),
+				// 	"type":             err.Type().String(),
+				// 	"value":            fmt.Sprintf("%v", err.Value()),
+				// 	"param":            err.Param(),
+				// }
+			}
+
+			// from here you can create your own error messages in whatever language you wish.
+			return
+		}
+
+		// save user to database.
+	})
+
+	// use Postman or whatever to do a POST request
+	// to the http://localhost:8080/user with RAW BODY:
+	/*
+		{
+			"fname": "",
+			"lname": "",
+			"age": 45,
+			"email": "mail@example.com",
+			"favColor": "#000",
+			"addresses": [{
+				"street": "Eavesdown Docks",
+				"planet": "Persphone",
+				"phone": "none",
+				"city": "Unknown"
+			}]
+		}
+	*/
+	// Content-Type to application/json (optionally but good practise).
+	// This request will fail due to the empty `User.FirstName` (fname in json)
+	// and `User.LastName` (lname in json).
+	// Check your iris' application terminal output.
+	app.Run(iris.Addr(":8080"), iris.WithoutServerError(iris.ErrServerClosed))
+}
+
+// UserStructLevelValidation contains custom struct level validations that don't always
+// make sense at the field validation level. For Example this function validates that either
+// FirstName or LastName exist; could have done that with a custom field validation but then
+// would have had to add it to both fields duplicating the logic + overhead, this way it's
+// only validated once.
+//
+// NOTE: you may ask why wouldn't I just do this outside of validator, because doing this way
+// hooks right into validator and you can combine with validation tags and still have a
+// common error output format.
+func UserStructLevelValidation(sl validator.StructLevel) {
+
+	user := sl.Current().Interface().(User)
+
+	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
+		sl.ReportError(user.FirstName, "FirstName", "fname", "fnameorlname", "")
+		sl.ReportError(user.LastName, "LastName", "lname", "fnameorlname", "")
+	}
+
+	// plus can to more, even with different tag than "fnameorlname".
+}

_examples/http_request/upload-files/main.go

@@ -5,6 +5,8 @@ import (
 	"fmt"
 	"io"
 	"mime/multipart"
+	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"time"
@@ -44,10 +46,53 @@ func main() {
 		ctx.UploadFormFiles("./uploads", beforeSave)
 	})
 
+	app.Post("/upload_manual", func(ctx iris.Context) {
+		// Get the max post value size passed via iris.WithPostMaxMemory.
+		maxSize := ctx.Application().ConfigurationReadOnly().GetPostMaxMemory()
+
+		err := ctx.Request().ParseMultipartForm(maxSize)
+		if err != nil {
+			ctx.StatusCode(iris.StatusInternalServerError)
+			ctx.WriteString(err.Error())
+			return
+		}
+
+		form := ctx.Request().MultipartForm
+
+		files := form.File["files[]"]
+		failures := 0
+		for _, file := range files {
+			_, err = saveUploadedFile(file, "./uploads")
+			if err != nil {
+				failures++
+				ctx.Writef("failed to upload: %s\n", file.Filename)
+			}
+		}
+		ctx.Writef("%d files uploaded", len(files)-failures)
+	})
+
 	// start the server at http://localhost:8080 with post limit at 32 MB.
 	app.Run(iris.Addr(":8080"), iris.WithPostMaxMemory(32<<20))
 }
 
+func saveUploadedFile(fh *multipart.FileHeader, destDirectory string) (int64, error) {
+	src, err := fh.Open()
+	if err != nil {
+		return 0, err
+	}
+	defer src.Close()
+
+	out, err := os.OpenFile(filepath.Join(destDirectory, fh.Filename),
+		os.O_WRONLY|os.O_CREATE, os.FileMode(0666))
+
+	if err != nil {
+		return 0, err
+	}
+	defer out.Close()
+
+	return io.Copy(out, src)
+}
+
 func beforeSave(ctx iris.Context, file *multipart.FileHeader) {
 	ip := ctx.RemoteAddr()
 	// make sure you format the ip in a way

_examples/miscellaneous/file-logger/main.go

@@ -7,8 +7,7 @@ import (
 	"github.com/kataras/iris"
 )
 
-// get a filename based on the date, file logs works that way the most times
-// but these are just a sugar.
+// Get a filename based on the date, just for the sugar.
 func todayFilename() string {
 	today := time.Now().Format("Jan 02 2006")
 	return today + ".txt"
@@ -16,7 +15,7 @@ func todayFilename() string {
 
 func newLogFile() *os.File {
 	filename := todayFilename()
-	// open an output file, this will append to the today's file if server restarted.
+	// Open the file, this will append to the today's file if server restarted.
 	f, err := os.OpenFile(filename, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
 	if err != nil {
 		panic(err)
@@ -30,20 +29,20 @@ func main() {
 	defer f.Close()
 
 	app := iris.New()
-	// attach the file as logger, remember, iris' app logger is just an io.Writer.
-	app.Logger().SetOutput(newLogFile())
+	// Attach the file as logger, remember, iris' app logger is just an io.Writer.
+	// Use the following code if you need to write the logs to file and console at the same time.
+	// app.Logger().SetOutput(io.MultiWriter(f, os.Stdout))
+	app.Logger().SetOutput(f)
 
-	app.Get("/", func(ctx iris.Context) {
+	app.Get("/ping", func(ctx iris.Context) {
 		// for the sake of simplicity, in order see the logs at the ./_today_.txt
-		ctx.Application().Logger().Info("Request path: " + ctx.Path())
-		ctx.Writef("hello")
+		ctx.Application().Logger().Infof("Request path: %s", ctx.Path())
+		ctx.WriteString("pong")
 	})
 
-	// navigate to http://localhost:8080
-	// and open the ./logs.txt file
-	if err := app.Run(iris.Addr(":8080"), iris.WithoutBanner); err != nil {
-		if err != iris.ErrServerClosed {
-			app.Logger().Warn("Shutdown with error: " + err.Error())
-		}
+	// Navigate to http://localhost:8080/ping
+	// and open the ./logs{TODAY}.txt file.
+	if err := app.Run(iris.Addr(":8080"), iris.WithoutBanner, iris.WithoutServerError(iris.ErrServerClosed)); err != nil {
+		app.Logger().Warn("Shutdown with error: " + err.Error())
 	}
 }

_examples/miscellaneous/recover/main.go

@@ -8,7 +8,6 @@ import (
 
 func main() {
 	app := iris.New()
-	// use this recover(y) middleware
 	app.Use(recover.New())
 
 	i := 0