binding

README

binding

Middleware binding provides request data binding and validation for net/http.

License

This project is under the Apache License, Version 2.0. See the LICENSE file for the full license text.

Acknowledgement

This library has been forked from https://github.com/go-macaron/binding and adapted to work with https://github.com/go-chi/chi .

Documentation

Overview

Package binding is a middleware that provides request data binding and validation for Chi.

Index

• Variables
• func Bind(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler
• func Form(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler
• func HandlerFunc(fn interface{}) http.HandlerFunc
• func Inject(fn func(inject.Injector) error) func(next http.Handler) http.Handler
• func Injector(r *render.Render) func(next http.Handler) http.Handler
• func JSON(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler
• func Map(val interface{}) func(next http.Handler) http.Handler
• func MapTo(val interface{}, ifacePtr interface{}) func(next http.Handler) http.Handler
• func MultipartForm(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler
• func NewBindingError(err error, obj interface{}) *apierrors.StatusError
• func Set(typ reflect.Type, val reflect.Value) func(next http.Handler) http.Handler

Variables

var MaxMemory = int64(1024 * 1024 * 10)

MaxMemory represents maximum amount of memory to use when parsing a multipart form. Set this to whatever value you prefer; default is 10 MB.

Functions

func Bind

func Bind(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler

Bind wraps up the functionality of the Form and Json middleware according to the Content-Type and verb of the request. A Content-Type is required for POST and PUT requests. Bind invokes the ErrorHandler middleware to bail out if errors occurred. If you want to perform your own error handling, use Form or Json middleware directly. An interface pointer can be added as a second argument in order to map the struct to a specific interface.

func Form

func Form(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler

Form is middleware to deserialize form-urlencoded data from the request. It gets data from the form-urlencoded body, if present, or from the query string. It uses the http.Request.ParseForm() method to perform deserialization, then reflection is used to map each field into the struct with the proper type. Structs with primitive slice types (bool, float, int, string) can support deserialization of repeated form keys, for example: key=val1&key=val2&key=val3 An interface pointer can be added as a second argument in order to map the struct to a specific interface.

func HandlerFunc

func HandlerFunc(fn interface{}) http.HandlerFunc

HandlerFunc converts a regular function into a net/http handler.

This regular function may have 3 possible signatures signature 1:

func doStuff(...)            # must write to http.ResponseWriter

signature 2:

func doStuff(...) error      # converted to metav1.Status and written to http.ResponseWriter as a JSON object
func doStuff(...) []byte     # directly written using http.ResponseWriter.Write(bytes)
func doStuff(...) some_value # converted to JSON and written to http.ResponseWriter

signature 3:

func doStuff(...) ([]byte, error)
func doStuff(...) (some_value, error)
If an error is returned, then converted to metav1.Status and written to http.ResponseWriter as a JSON object.
Otherwise, []byte is written directly and some_value is converted to JSON and written to http.ResponseWriter

Each of these functions can take any injected values as argument including the following pre-injected ones:

• r *http.Request
• w httpw.ResponseWriter # the recommended ResponseWriter as it has helper methods like macaron.Context
• w http.ResponseWriter # net/http ResponseWriter
• w middleware.WrapResponseWriter # go-chi's ResponseWriter wrapper. Use(middleware.Logger) to inject this.

func Inject

func Inject(fn func(inject.Injector) error) func(next http.Handler) http.Handler

Inject allows injecting new values for a given request

func Injector

func Injector(r *render.Render) func(next http.Handler) http.Handler

func JSON

func JSON(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler

JSON is middleware to deserialize a JSON payload from the request into the struct that is passed in. The resulting struct is then validated, but no error handling is actually performed here. An interface pointer can be added as a second argument in order to map the struct to a specific interface.

For all requests, Json parses the raw query from the URL using matching struct json tags.

For POST, PUT, and PATCH requests, it also parses the request body. Request body parameters take precedence over URL query string values.

Json follows the Request.ParseForm() method from Go's net/http library. ref: https://github.com/golang/go/blob/700e969d5b23732179ea86cfe67e8d1a0a1cc10a/src/net/http/request.go#L1176

func Map

func Map(val interface{}) func(next http.Handler) http.Handler

Maps the interface{} value based on its immediate type from reflect.TypeOf.

func MapTo

func MapTo(val interface{}, ifacePtr interface{}) func(next http.Handler) http.Handler

Maps the interface{} value based on the pointer of an Interface provided. This is really only useful for mapping a value as an interface, as interfaces cannot at this time be referenced directly without a pointer.

func MultipartForm

func MultipartForm(obj interface{}, ifacePtr ...interface{}) func(next http.Handler) http.Handler

MultipartForm works much like Form, except it can parse multipart forms and handle file uploads. Like the other deserialization middleware handlers, you can pass in an interface to make the interface available for injection into other handlers later.

func NewBindingError

func NewBindingError(err error, obj interface{}) *apierrors.StatusError

NewBindingError returns an error indicating the request is invalid and cannot be bound to an object.

func Set

func Set(typ reflect.Type, val reflect.Value) func(next http.Handler) http.Handler

Provides a possibility to directly insert a mapping based on type and value. This makes it possible to directly map type arguments not possible to instantiate with reflect like unidirectional channels.