httpin

README

httpin - HTTP Input for Go

Decode an HTTP request into a custom struct

Documentation

Core Features

httpin helps you easily decoding HTTP request data from

• Query parameters, e.g. ?name=john&is_member=true
• Headers, e.g. Authorization: xxx
• Form data, e.g. username=john&password=******
• JSON/XML Body, e.g. POST {"name":"john"}
• Path variables, e.g. /users/{username}
• File uploads

You only need to define a struct to receive/bind data from an HTTP request, without writing any parsing stuff code by yourself.

How to use?

type ListUsersInput struct {
	Token    string `in:"query=access_token;header=x-access-token"`
	Page     int    `in:"query=page;default=1"`
	PerPage  int    `in:"query=per_page;default=20"`
	IsMember bool   `in:"query=is_member"`
}

func ListUsers(rw http.ResponseWriter, r *http.Request) {
	input := r.Context().Value(httpin.Input).(*ListUsersInput)

	if input.IsMember {
		// Do sth.
	}
	// Do sth.
}

httpin is:

• well documented: at https://ggicci.github.io/httpin/
• open integrated: with net/http, go-chi/chi, gorilla/mux, gin-gonic/gin, etc.
• extensible (advanced feature): by adding your custom directives. Read httpin - custom directives for more details.

Why this package?

Compared with using net/http package

func ListUsers(rw http.ResponseWriter, r *http.Request) {
	page, err := strconv.ParseInt(r.FormValue("page"), 10, 64)
	if err != nil {
		// Invalid parameter: page.
		return
	}
	perPage, err := strconv.ParseInt(r.FormValue("per_page"), 10, 64)
	if err != nil {
		// Invalid parameter: per_page.
		return
	}
	isMember, err := strconv.ParseBool(r.FormValue("is_member"))
	if err != nil {
		// Invalid parameter: is_member.
		return
	}

	// Do sth.
}

Benefits	Before (use net/http package)	After (use ggicci/httpin package)
⌛️ Developer Time	😫 Expensive (too much parsing stuff code)	🚀 Faster (define the struct for receiving input data and leave the parsing job to httpin)
♻️ Code Repetition Rate	😞 High	😍 Lower
📖 Code Readability	😟 Poor	🤩 Highly readable
🔨 Maintainability	😡 Poor	🥰 Highly maintainable

Alternatives and Similars

• gorilla/schema: converts structs to and from form values
• google/go-querystring: encoding structs into URL query parameters

Documentation

Overview

Package httpin helps decoding an HTTP request to a custom struct by binding data with querystring (query params), HTTP headers, form data, JSON/XML payloads, URL path params, and file uploads (multipart/form-data).

Index

• Variables
• func Decode(req *http.Request, input interface{}) error
• func NewInput(inputStruct interface{}, opts ...Option) func(http.Handler) http.Handler
• func RegisterBodyDecoder(bodyType string, decoder BodyDecoder)
• func RegisterDirectiveExecutor(name string, exe DirectiveExecutor)
• func RegisterFileTypeDecoder[T any](decoder Decoder[*multipart.FileHeader])
• func RegisterNamedDecoder[T any](name string, decoder interface{})
• func RegisterValueTypeDecoder[T any](decoder Decoder[string])
• func ReplaceBodyDecoder(bodyType string, decoder BodyDecoder)
• func ReplaceDefaultErrorHandler(custom ErrorHandler)
• func ReplaceDirectiveExecutor(name string, exe DirectiveExecutor)
• func ReplaceFileTypeDecoder[T any](decoder Decoder[*multipart.FileHeader])
• func ReplaceNamedDecoder[T any](name string, decoder interface{})
• func ReplaceValueTypeDecoder[T any](decoder Decoder[string])
• func UseGochiURLParam(directive string, fn GochiURLParamFunc)
• func UseGorillaMux(executor string, fnVars GorillaMuxVarsFunc)
• type BodyDecoder
• type ContextKey
• type Core
  • func New(inputStruct interface{}, opts ...Option) (*Core, error)
  • func (c *Core) Decode(req *http.Request) (interface{}, error)
• type DataSource
• type Decoder
• type DecoderFunc
  • func (fn DecoderFunc[DT]) Decode(value DT) (interface{}, error)
• type Directive
• type DirectiveExecutor
• type DirectiveExecutorFunc
• type DirectiveRuntime
• type ErrorHandler
• type File
• type FileTypeDecoder
• type GochiURLParamFunc
• type GorillaMuxVarsFunc
• type InvalidFieldError
  • func NewInvalidFieldError(err *owl.ResolveError) *InvalidFieldError
  • func (e *InvalidFieldError) Error() string
  • func (e *InvalidFieldError) Unwrap() error
• type Option
  • func WithErrorHandler(custom ErrorHandler) Option
  • func WithMaxMemory(maxMemory int64) Option
• type UnsupportedTypeError
  • func (e UnsupportedTypeError) Error() string
  • func (e UnsupportedTypeError) Unwrap() error
• type ValueTypeDecoder

Variables

var (
	ErrMissingField          = errors.New("missing required field")
	ErrUnsupporetedType      = errors.New("unsupported type")
	ErrUnregisteredExecutor  = errors.New("unregistered executor")
	ErrDuplicateTypeDecoder  = errors.New("duplicate type decoder")
	ErrDuplicateNamedDecoder = errors.New("duplicate named decoder")
	ErrNilDecoder            = errors.New("nil decoder")
	ErrInvalidDecoder        = errors.New("invalid decoder")
	ErrReservedExecutorName  = errors.New("reserved executor name")
	ErrUnknownBodyType       = errors.New("unknown body type")
	ErrNilErrorHandler       = errors.New("nil error handler")
	ErrMaxMemoryTooSmall     = errors.New("max memory too small")
	ErrNilFile               = errors.New("nil file")
	ErrDuplicateBodyDecoder  = errors.New("duplicate body decoder")
	ErrMissingDecoderName    = errors.New("missing decoder name")
	ErrDecoderNotFound       = errors.New("decoder not found")
	ErrValueTypeMismatch     = errors.New("value type mismatch")
)

Functions

func Decode

func Decode(req *http.Request, input interface{}) error

Decode decodes an HTTP request to a struct instance. e.g.

input := &InputStruct{}
if err := Decode(req, &input); err != nil { ... }

input is now populated with data from the request.

func NewInput

func NewInput(inputStruct interface{}, opts ...Option) func(http.Handler) http.Handler

NewInput creates a "Middleware Constructor" for making a chain, which acts as a list of http.Handler constructors. We recommend using https://github.com/justinas/alice to chain your HTTP middleware functions and the app handler.

func RegisterBodyDecoder

func RegisterBodyDecoder(bodyType string, decoder BodyDecoder)

RegisterBodyDecoder registers a new body decoder. Panic if the body type is already registered.

func init() {
    RegisterBodyDecoder("yaml", &myYAMLBodyDecoder{})
}

func RegisterDirectiveExecutor

func RegisterDirectiveExecutor(name string, exe DirectiveExecutor)

RegisterDirectiveExecutor registers a named executor globally, which implemented the DirectiveExecutor interface. Will panic if the name were taken or nil executor.

func RegisterFileTypeDecoder

func RegisterFileTypeDecoder[T any](decoder Decoder[*multipart.FileHeader])

func RegisterNamedDecoder

func RegisterNamedDecoder[T any](name string, decoder interface{})

RegisterNamedDecoder registers a decoder by name. Panics on conflicts.

func RegisterValueTypeDecoder

func RegisterValueTypeDecoder[T any](decoder Decoder[string])

func ReplaceBodyDecoder

func ReplaceBodyDecoder(bodyType string, decoder BodyDecoder)

ReplaceBodyDecoder replaces or add the body decoder of the specified type. Which is useful when you want to override the default body decoder. For example, the default JSON decoder is borrowed from encoding/json. You can replace it with your own implementation, e.g. json-iterator/go.

func init() {
    ReplaceBodyDecoder("json", &myJSONBodyDecoder{})
}

func ReplaceDefaultErrorHandler

func ReplaceDefaultErrorHandler(custom ErrorHandler)

func ReplaceDirectiveExecutor

func ReplaceDirectiveExecutor(name string, exe DirectiveExecutor)

ReplaceDirectiveExecutor works like RegisterDirectiveExecutor without panic on duplicate names.

func ReplaceFileTypeDecoder

func ReplaceFileTypeDecoder[T any](decoder Decoder[*multipart.FileHeader])

func ReplaceNamedDecoder

func ReplaceNamedDecoder[T any](name string, decoder interface{})

ReplaceNamedDecoder replaces a decoder by name.

func ReplaceValueTypeDecoder

func ReplaceValueTypeDecoder[T any](decoder Decoder[string])

func UseGochiURLParam

func UseGochiURLParam(directive string, fn GochiURLParamFunc)

UseGochiURLParam registers a directive executor which can extract values from `chi.URLParam`, i.e. path variables. https://ggicci.github.io/httpin/integrations/gochi

Usage:

func init() {
    httpin.UseGochiURLParam("path", chi.URLParam)
}

func UseGorillaMux

func UseGorillaMux(executor string, fnVars GorillaMuxVarsFunc)

UseGorillaMux registers a new directive executor which can extract values from `mux.Vars`, i.e. path variables. https://ggicci.github.io/httpin/integrations/gorilla

Usage:

func init() {
    httpin.UseGorillaMux("path", mux.Vars)
}

Types

type BodyDecoder

type BodyDecoder interface {
	Decode(src io.Reader, dst interface{}) error
}

BodyDecoder decodes the request body into the specified object. Common body types are: json, xml, yaml, and others.

type ContextKey

type ContextKey int

const (
	// Input is the key to get the input object from Request.Context() injected by httpin. e.g.
	//
	//     input := r.Context().Value(httpin.Input).(*InputStruct)
	Input ContextKey = iota

	// RequestValue is the key to get the HTTP request value (of *http.Request)
	// from DirectiveRuntime.Context. The HTTP request value is injected by
	// httpin to the context of DirectiveRuntime before executing the directive.
	// See Core.Decode() for more details.
	RequestValue

	// CustomDecoder is the key to get the custom decoder for a field from
	// Resolver.Context. Which is specified by the "decoder" directive.
	// During resolver building phase, the "decoder" directive will be removed
	// from the resolver, and the targeted decoder by name will be put into
	// Resolver.Context with this key. e.g.
	//
	//    type GreetInput struct {
	//        Message string `httpin:"decoder=custom"`
	//    }
	// For the above example, the decoder named "custom" will be put into the
	// resolver of Message field with this key.
	CustomDecoder

	// FieldSet is used by executors to tell whether a field has been set. When
	// multiple executors were applied to a field, if the field value were set
	// by a former executor, the latter executors MAY skip running by consulting
	// this context value.
	FieldSet
)

type Core

type Core struct {
	// contains filtered or unexported fields
}

Core is the core of httpin. It holds the resolver of a specific struct type. Who is responsible for decoding an HTTP request to an instance of such struct type.

func New

func New(inputStruct interface{}, opts ...Option) (*Core, error)

New creates a new Core instance. It will build a resolver for the inputStruct. The resolver will be cached for future use. For the same inputStruct, the resolver will be built only once. While the applied options will be applied separately for each Core instance.

Use Core.Decode to decode an HTTP request to a struct instance.

Use NewInput to create an HTTP middleware.

func (*Core) Decode

func (c *Core) Decode(req *http.Request) (interface{}, error)

Decode decodes an HTTP request to a struct instance. The return value is a pointer to the input struct.

type DataSource

type DataSource interface{ string | *multipart.FileHeader }

type Decoder

type Decoder[DT DataSource] interface {
	Decode(value DT) (interface{}, error)
}

type DecoderFunc

type DecoderFunc[DT DataSource] func(value DT) (interface{}, error)

func (DecoderFunc[DT]) Decode

func (fn DecoderFunc[DT]) Decode(value DT) (interface{}, error)

type Directive

type Directive = owl.Directive

type DirectiveExecutor

type DirectiveExecutor = owl.DirectiveExecutor

type DirectiveExecutorFunc

type DirectiveExecutorFunc = owl.DirectiveExecutorFunc

type DirectiveRuntime

type DirectiveRuntime = owl.DirectiveRuntime

type ErrorHandler

type ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error)

type File

type File struct {
	multipart.File
	Header *multipart.FileHeader
	Valid  bool
}

type FileTypeDecoder

type FileTypeDecoder = Decoder[*multipart.FileHeader]

type GochiURLParamFunc

type GochiURLParamFunc func(r *http.Request, key string) string

GochiURLParamFunc is chi.URLParam

type GorillaMuxVarsFunc

type GorillaMuxVarsFunc func(*http.Request) map[string]string

GorillaMuxVarsFunc is mux.Vars

type InvalidFieldError

type InvalidFieldError struct {

	// Field is the name of the field.
	Field string `json:"field"`

	// Source is the directive which causes the error.
	// e.g. form, header, required, etc.
	Source string `json:"source"`

	// Key is the key to get the input data from the source.
	Key string `json:"key"`

	// Value is the input data.
	Value interface{} `json:"value"`

	// ErrorMessage is the string representation of `internalError`.
	ErrorMessage string `json:"error"`
	// contains filtered or unexported fields
}

func NewInvalidFieldError

func NewInvalidFieldError(err *owl.ResolveError) *InvalidFieldError

func (*InvalidFieldError) Error

func (e *InvalidFieldError) Error() string

func (*InvalidFieldError) Unwrap

func (e *InvalidFieldError) Unwrap() error

type Option

type Option func(*Core) error

func WithErrorHandler

func WithErrorHandler(custom ErrorHandler) Option

WithErrorHandler overrides the default error handler.

func WithMaxMemory

func WithMaxMemory(maxMemory int64) Option

WithMaxMemory overrides the default maximum memory size (32MB) when reading the request body. See https://pkg.go.dev/net/http#Request.ParseMultipartForm for more details.

type UnsupportedTypeError

type UnsupportedTypeError struct {
	Type reflect.Type
}

func (UnsupportedTypeError) Error

func (e UnsupportedTypeError) Error() string

func (UnsupportedTypeError) Unwrap

func (e UnsupportedTypeError) Unwrap() error

type ValueTypeDecoder

type ValueTypeDecoder = Decoder[string]