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 {
	Page     int  `in:"query=page"`
	PerPage  int  `in:"query=per_page"`
	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

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

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 NewInput(inputStruct interface{}, opts ...Option) middleware
• func RegisterBodyDecoder(bodyType string, decoder BodyDecoder)
• func RegisterDirectiveExecutor(name string, exe DirectiveExecutor, norm DirectiveNormalizer)
• func RegisterTypeDecoder(typ reflect.Type, decoder interface{})
• func ReplaceBodyDecoder(bodyType string, decoder BodyDecoder)
• func ReplaceDefaultErrorHandler(custom ErrorHandler)
• func ReplaceDirectiveExecutor(name string, exe DirectiveExecutor, norm DirectiveNormalizer)
• func ReplaceTypeDecoder(typ reflect.Type, decoder interface{})
• func UseGochiURLParam(executor string, fn GochiURLParamFunc)
• func UseGorillaMux(executor string, fnVars GorillaMuxVarsFunc)
• type BodyDecoder
• type ContextKey
• type Directive
  • func (d *Directive) Execute(ctx *DirectiveContext) error
• type DirectiveContext
  • func (c *DirectiveContext) DeliverContextValue(key, value interface{})
• type DirectiveExecutor
• type DirectiveExecutorFunc
  • func (f DirectiveExecutorFunc) Execute(ctx *DirectiveContext) error
• type DirectiveNormalizer
• type DirectiveNormalizerFunc
  • func (f DirectiveNormalizerFunc) Normalize(dir *Directive) error
• type Engine
  • func New(inputStruct interface{}, opts ...Option) (*Engine, error)
  • func (e *Engine) Decode(req *http.Request) (interface{}, error)
• type ErrorHandler
• type File
• type FileTypeDecoder
• type FileTypeDecoderFunc
• type GochiURLParamFunc
• type GorillaMuxVarsFunc
• type InvalidFieldError
  • func (f *InvalidFieldError) Error() string
  • func (f *InvalidFieldError) Unwrap() error
• type JSONBody
• 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
• type ValueTypeDecoderFunc
• type XMLBody

Variables

var (
	ErrMissingField             = errors.New("missing required field")
	ErrUnsupporetedType         = errors.New("unsupported type")
	ErrUnregisteredExecutor     = errors.New("unregistered executor")
	ErrDuplicateTypeDecoder     = errors.New("duplicate type decoder")
	ErrNilTypeDecoder           = errors.New("nil type decoder")
	ErrInvalidTypeDecoder       = errors.New("invalid type decoder")
	ErrDuplicateExecutor        = errors.New("duplicate executor")
	ErrNilExecutor              = errors.New("nil executor")
	ErrUnknownBodyType          = errors.New("unknown body type")
	ErrDuplicateAnnotationField = errors.New("duplicate annotation field")
	ErrNilErrorHandler          = errors.New("nil error handler")
	ErrMaxMemoryTooSmall        = errors.New("max memory too small")
	ErrNilFile                  = errors.New("nil file")
	ErrDuplicateBodyDecoder     = errors.New("duplicate body decoder")
)

Functions

func NewInput

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

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, norm DirectiveNormalizer)

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

func RegisterTypeDecoder

func RegisterTypeDecoder(typ reflect.Type, decoder interface{})

RegisterTypeDecoder registers a specific type decoder. Panics on conflicts.

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, norm DirectiveNormalizer)

ReplaceDirectiveExecutor works like RegisterDirectiveExecutor without panic on duplicate names.

func ReplaceTypeDecoder

func ReplaceTypeDecoder(typ reflect.Type, decoder interface{})

ReplaceTypeDecoder replaces a specific type decoder.

func UseGochiURLParam

func UseGochiURLParam(executor 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

	// 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

	StopRecursion
)

type Directive

type Directive struct {
	Executor string   // name of the executor
	Argv     []string // argv
}

Directive defines the profile to locate an httpin.DirectiveExecutor instance and drive it with essential arguments.

func (*Directive) Execute

func (d *Directive) Execute(ctx *DirectiveContext) error

Execute locates the executor and runs it with the specified context.

type DirectiveContext

type DirectiveContext struct {
	Directive
	ValueType reflect.Type
	Value     reflect.Value
	Request   *http.Request
	Context   context.Context
}

DirectiveContext holds essential information about the field being resolved and the active HTTP request. Working as the context in a directive executor.

func (*DirectiveContext) DeliverContextValue

func (c *DirectiveContext) DeliverContextValue(key, value interface{})

DeliverContextValue binds a value to the specified key in the context. And it will be delivered among the executors in the same field resolver.

type DirectiveExecutor

type DirectiveExecutor interface {
	Execute(*DirectiveContext) error
}

DirectiveExecutor is the interface implemented by a "directive executor".

type DirectiveExecutorFunc

type DirectiveExecutorFunc func(*DirectiveContext) error

DirectiveExecutorFunc is an adpator to allow to use of ordinary functions as httpin.DirectiveExecutor.

func (DirectiveExecutorFunc) Execute

func (f DirectiveExecutorFunc) Execute(ctx *DirectiveContext) error

Execute calls f(ctx).

type DirectiveNormalizer

type DirectiveNormalizer interface {
	Normalize(*Directive) error
}

type DirectiveNormalizerFunc

type DirectiveNormalizerFunc func(*Directive) error

DirectiveNormalizerFunc is an adaptor to allow to use of ordinary functions as httpin.DirectiveNormalizer.

func (DirectiveNormalizerFunc) Normalize

func (f DirectiveNormalizerFunc) Normalize(dir *Directive) error

Normalize calls f(dir).

type Engine

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

Engine holds the information on how to decode a request to an instance of a concrete struct type.

func New

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

New builds an HTTP request decoder for the specified struct type with custom options.

func (*Engine) Decode

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

Decode decodes an HTTP request to a struct instance.

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 = internal.FileTypeDecoder

FileTypeDecoder is the interface implemented by types that can decode a *multipart.FileHeader to themselves.

type FileTypeDecoderFunc

type FileTypeDecoderFunc = internal.FileTypeDecoderFunc

FileTypeDecoderFunc is an adaptor to allow the use of ordinary functions as httpin `FileTypeDecoder`s.

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"`

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

	// ErrorMessage is the string representation of `internalError`.
	ErrorMessage string `json:"error"`

	// directives is the list of directives bound to the field.
	Directives []*Directive `json:"-"`
	// contains filtered or unexported fields
}

func (*InvalidFieldError) Error

func (f *InvalidFieldError) Error() string

func (*InvalidFieldError) Unwrap

func (f *InvalidFieldError) Unwrap() error

type JSONBody

type JSONBody struct{}

JSONBody is the annotation for JSON body.

type Option

type Option func(*Engine) 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 = internal.ValueTypeDecoder

ValueTypeDecoder is the interface implemented by types that can decode a string to themselves.

type ValueTypeDecoderFunc

type ValueTypeDecoderFunc = internal.ValueTypeDecoderFunc

ValueTypeDecoderFunc is an adaptor to allow the use of ordinary functions as httpin `ValueTypeDecoder`s.

type XMLBody

type XMLBody struct{}

XMLBody is the annotation for XML body.