httpin

README

httpin

HTTP Input for Go - Decode an HTTP request into a custom struct

Documentation

Quick View

Before (use net/http)

After (use httpin)

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. }

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) // Do sth. }

Why this package?

Items	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

Documentation

Index

• Variables
• func DecodeFile(fileHeader *multipart.FileHeader) (interface{}, error)
• func NewInput(inputStruct interface{}, opts ...Option) middleware
• func RegisterDirectiveExecutor(name string, exe DirectiveExecutor, norm DirectiveNormalizer)
• func RegisterTypeDecoder(typ reflect.Type, decoder interface{})
• 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 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 Extractor
  • func NewExtractor(r *http.Request) *Extractor
  • func (e *Extractor) Execute(ctx *DirectiveContext) error
• 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")
)

Functions

func DecodeFile

func DecodeFile(fileHeader *multipart.FileHeader) (interface{}, error)

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

func UseGorillaMux

func UseGorillaMux(executor string, fnVars GorillaMuxVarsFunc)

UseGorillaMux registers a new directive executor which can extract path variables from the URL. Which works as an accompany to gorilla's mux package.

Example:

UseGorillaMux("path", mux.Vars)

type GetUserInput struct {
   UserID `httpin:"path=user_id"`
}

Types

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

	// Set this context value to true to indicate that the field has been set.
	// When multiple executors were applied to a field, if the field value were set by
	// an 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 Extractor

type Extractor struct {
	multipart.Form

	KeyNormalizer func(string) string
}

func NewExtractor

func NewExtractor(r *http.Request) *Extractor

func (*Extractor) Execute

func (e *Extractor) Execute(ctx *DirectiveContext) 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{}

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

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{}