feather

README

feather

Documentation

Index

• Constants
• Variables
• func AcceptedLanguages(r *http.Request) (languages []string)
• func Attachment(w http.ResponseWriter, r io.Reader, filename string) (err error)
• func ClientIP(r *http.Request) (clientIP string)
• func Decode(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
• func DecodeForm(r *http.Request, qp QueryParamsOption, v interface{}) (err error)
• func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) error
• func DecodeMultipartForm(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)
• func DecodeQueryParams(r *http.Request, qp QueryParamsOption, v interface{}) error
• func DecodeSEOQueryParams(r *http.Request, v interface{}) (err error)
• func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) error
• func EncodeToURLValues(v interface{}) (url.Values, error)
• func Inline(w http.ResponseWriter, r io.Reader, filename string) (err error)
• func JSON(w http.ResponseWriter, status int, i interface{}) error
• func JSONBytes(w http.ResponseWriter, status int, b []byte) (err error)
• func JSONP(w http.ResponseWriter, status int, i interface{}, callback string) error
• func JSONStream(w http.ResponseWriter, status int, i interface{}) error
• func ParseForm(r *http.Request) error
• func ParseMultipartForm(r *http.Request, maxMemory int64) error
• func QueryParams(r *http.Request, qp QueryParamsOption) (values url.Values)
• func XML(w http.ResponseWriter, status int, i interface{}) error
• func XMLBytes(w http.ResponseWriter, status int, b []byte) (err error)
• type FormDecoder
• type FormEncoder
• type IRouteGroup
• type IRoutes
• type LimitedReader
  • func LimitReader(r io.Reader, n int64) *LimitedReader
  • func (l *LimitedReader) Read(p []byte) (n int, err error)
• type Middleware
• type Mux
  • func New() *Mux
  • func (g *Mux) Any(path string, h http.HandlerFunc)
  • func (g *Mux) Connect(path string, h http.HandlerFunc)
  • func (g *Mux) Delete(path string, h http.HandlerFunc)
  • func (g *Mux) Get(path string, h http.HandlerFunc)
  • func (g *Mux) Group(prefix string) IRouteGroup
  • func (g *Mux) GroupWithMore(prefix string, middleware ...Middleware) IRouteGroup
  • func (g *Mux) GroupWithNone(prefix string) IRouteGroup
  • func (g *Mux) Handle(method string, path string, h http.HandlerFunc)
  • func (g *Mux) Head(path string, h http.HandlerFunc)
  • func (g *Mux) Match(methods []string, path string, h http.HandlerFunc)
  • func (g *Mux) Options(path string, h http.HandlerFunc)
  • func (g *Mux) Patch(path string, h http.HandlerFunc)
  • func (g *Mux) Post(path string, h http.HandlerFunc)
  • func (g *Mux) Put(path string, h http.HandlerFunc)
  • func (p *Mux) Register404(notFound http.HandlerFunc, middleware ...Middleware)
  • func (p *Mux) RegisterAutomaticOPTIONS(middleware ...Middleware)
  • func (p *Mux) RegisterMethodNotAllowed(middleware ...Middleware)
  • func (p *Mux) Serve() http.Handler
  • func (p *Mux) SetRedirectTrailingSlash(set bool)
  • func (g *Mux) Trace(path string, h http.HandlerFunc)
  • func (g *Mux) Use(m ...Middleware)
• type QueryParamsOption
• type ReqVars
  • func RequestVars(r *http.Request) ReqVars

Constants

const (
	WildcardParam = "*wildcard"
)

Variables

var (
	// DefaultFormDecoder of this package, which is configurable.
	DefaultFormDecoder FormDecoder = form.NewDecoder()

	// DefaultFormEncoder of this package, which is configurable.
	DefaultFormEncoder FormEncoder = form.NewEncoder()
)

var ErrLimitedReaderEOF = errors.New("LimitedReader EOF: limit reached")

ErrLimitedReaderEOF is an error returned by LimitedReader to give feedback to the fact that we did not hit an EOF of the Reader but hit the limit imposed by the LimitedReader.

Functions

func AcceptedLanguages

func AcceptedLanguages(r *http.Request) (languages []string)

AcceptedLanguages returns an array of accepted languages denoted by the Accept-Language header sent by the browser.

func Attachment

func Attachment(w http.ResponseWriter, r io.Reader, filename string) (err error)

Attachment is a helper method for returning an attachement file to be downloaded, if a line needs to be opened, see the Inline function.

func ClientIP

func ClientIP(r *http.Request) (clientIP string)

ClientIP implements a best effort algorithm to return the real client IP, it parses X-Real-IP and X-Forwarded-For in order to work properly with reverse-proxies such us: nginx or haproxy.

func Decode

func Decode(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)

Decode takes the request and attempts to discover it's content type via the http headers and then decode the request body into the provided struct. Example if header was "application/json" would decode using json.NewDecoder(ioext.LimitReader(r.Body, maxMemory)).Decode(v).

NOTE: when qp=QueryParams both query params and SEO query params will be parsed and included e. g. route /user/:id?test=true both 'id' and 'test' are treated as query params and added to the request.Form prior to decoding or added to parsed JSON or XML. SEO query params are treated just like normal query params.

func DecodeForm

func DecodeForm(r *http.Request, qp QueryParamsOption, v interface{}) (err error)

DecodeForm parses the requests form data into the provided struct.

The Content-Type and http method are not checked.

NOTE: when qp=QueryParams, both query parameters and SEO query parameters will be parsed and included, e.g. the route /user/:id?test=true both 'id' and 'test' are treated as query parameters and added to request.Form prior to decoding. SEO query params are treated just like normal query params.

func DecodeJSON

func DecodeJSON(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) error

DecodeJSON decodes the request body into the provided struct and limits the request size via an ioext.LimitReader using the maxMemory param.

The Content-Type e.g. "application/json" and http method are not checked.

NOTE: when qp=QueryParams both query params and SEO query params will be parsed and included e. g. route /user/:id?test=true both 'id' and 'test' are treated as query params and added to parsed JSON. SEO query params are treated just like normal query params.

func DecodeMultipartForm

func DecodeMultipartForm(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) (err error)

DecodeMultipartForm parses the requests form data into the provided struct.

The Content-Type and http method are not checked.

NOTE: when qp=QueryParams, both query parameters and SEO query parameters will be parsed and included, e.g. the route /user/:id?test=true both 'id' and 'test' are treated as query parameters and added to request.Form prior to decoding. SEO query params are treated just like normal query params.

func DecodeQueryParams

func DecodeQueryParams(r *http.Request, qp QueryParamsOption, v interface{}) error

DecodeQueryParams takes the URL Query params, adds SEO params or not based on the includeSEOQueryParams flag.

NOTE: DecodeQueryParams is also used/called from Decode when no contentTypeHeader is specified the only difference is that it will always decode SEO Query Params.

func DecodeSEOQueryParams

func DecodeSEOQueryParams(r *http.Request, v interface{}) (err error)

DecodeSEOQueryParams decodes the SEO Query params only and ignores the normal URL Query params.

func DecodeXML

func DecodeXML(r *http.Request, qp QueryParamsOption, maxMemory int64, v interface{}) error

DecodeXML decodes the request body into the provided struct and limits the request size via an ioext.LimitReader using the maxMemory param.

The Content-Type e.g. "application/xml" and http method are not checked.

NOTE: when qp=QueryParams both query params and SEO query params will be parsed and included e. g. route /user/:id?test=true both 'id' and 'test' are treated as query params and added to parsed XML. SEO query params are treated just like normal query params.

func EncodeToURLValues

func EncodeToURLValues(v interface{}) (url.Values, error)

EncodeToURLValues encodes a struct or field into a set of url.Values.

func Inline

func Inline(w http.ResponseWriter, r io.Reader, filename string) (err error)

Inline is a helper method for returning a file inline to be rendered/opened by the browser.

func JSON

func JSON(w http.ResponseWriter, status int, i interface{}) error

JSON marshals provided interface + returns JSON + status code.

func JSONBytes

func JSONBytes(w http.ResponseWriter, status int, b []byte) (err error)

JSONBytes returns provided JSON response with status code.

func JSONP

func JSONP(w http.ResponseWriter, status int, i interface{}, callback string) error

JSONP sends a JSONP response with status code and uses `callback` to construct the JSONP payload.

func JSONStream

func JSONStream(w http.ResponseWriter, status int, i interface{}) error

JSONStream uses json.Encoder to stream the JSON reponse body.

This differs from the JSON helper which unmarshalls into memory first allowing the capture of JSON encoding errors.

func ParseForm

func ParseForm(r *http.Request) error

ParseForm calls the underlying http.Request ParseForm but also adds the URL params to the request Form as if they were defined as query params i.e. ?id=13&ok=true but does not add the params to the http.Request.URL.RawQuery for SEO purposes.

func ParseMultipartForm

func ParseMultipartForm(r *http.Request, maxMemory int64) error

ParseMultipartForm calls the underlying http.Request ParseMultipartForm but also adds the URL params to the request Form as if they were defined as query params i.e. ?id=13&ok=true but does not add the params to the http.Request.URL.RawQuery for SEO purposes.

func QueryParams

func QueryParams(r *http.Request, qp QueryParamsOption) (values url.Values)

QueryParams returns the r.URL.Query() values and optionally have them include the SEO query params eg. route /users/:id?test=val if qp=QueryParams then values will include 'id' as well as 'test' values.

func XML

func XML(w http.ResponseWriter, status int, i interface{}) error

XML marshals provided interface + returns XML + status code.

func XMLBytes

func XMLBytes(w http.ResponseWriter, status int, b []byte) (err error)

XMLBytes returns provided XML response with status code.

Types

type FormDecoder

type FormDecoder interface {
	Decode(interface{}, url.Values) error
}

FormDecoder is the type used for decoding a form for use

type FormEncoder

type FormEncoder interface {
	Encode(interface{}) (url.Values, error)
}

FormEncoder is the type used for encoding form data.

type IRouteGroup

type IRouteGroup interface {
	IRoutes
	GroupWithNone(prefix string) IRouteGroup
	GroupWithMore(prefix string, middleware ...Middleware) IRouteGroup
	Group(prefix string) IRouteGroup
}

IRouteGroup interface for router group.

type IRoutes

type IRoutes interface {
	Use(...Middleware)
	Any(string, http.HandlerFunc)
	Get(string, http.HandlerFunc)
	Post(string, http.HandlerFunc)
	Delete(string, http.HandlerFunc)
	Patch(string, http.HandlerFunc)
	Put(string, http.HandlerFunc)
	Options(string, http.HandlerFunc)
	Head(string, http.HandlerFunc)
	Connect(string, http.HandlerFunc)
	Trace(string, http.HandlerFunc)
}

IRoutes interface for routes.

type LimitedReader

type LimitedReader struct {
	R io.Reader
	N int64 // bytes allotted
}

LimitedReader reads from R but limits the amount of data returned to just N bytes. Each call to Read updates N to reflect the new amount remaining. Read returns ErrLimitedReaderEOF when N <= 0 or when the underlying R returns EOF. Unlike the std io.LimitedReader this provides feedback that the limit was reached through the returned error.

func LimitReader

func LimitReader(r io.Reader, n int64) *LimitedReader

LimitReader returns a LimitedReader that reads from r but stops with ErrLimitedReaderEOF after n bytes.

func (*LimitedReader) Read

func (l *LimitedReader) Read(p []byte) (n int, err error)

type Middleware

type Middleware func(h http.HandlerFunc) http.HandlerFunc

Middleware is feather's middleware definition.

type Mux

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

Mux is the main request multiplexer.

func New

func New() *Mux

New Creates and returns a new feather instance.

func (*Mux) Any

func (g *Mux) Any(path string, h http.HandlerFunc)

Any adds a route & handler to the router for all HTTP methods.

func (*Mux) Connect

func (g *Mux) Connect(path string, h http.HandlerFunc)

Connect adds a CONNECT route & handler to the router.

func (*Mux) Delete

func (g *Mux) Delete(path string, h http.HandlerFunc)

Delete adds a DELETE route & handler to the router.

func (*Mux) Get

func (g *Mux) Get(path string, h http.HandlerFunc)

Get adds a GET route & handler to the router.

func (*Mux) Group

func (g *Mux) Group(prefix string) IRouteGroup

Group creates a new sub router with specified prefix and retains existing middleware.

func (*Mux) GroupWithMore

func (g *Mux) GroupWithMore(prefix string, middleware ...Middleware) IRouteGroup

GroupWithMore creates a new sub router with specified prefix, retains existing middleware and adds new middleware.

func (*Mux) GroupWithNone

func (g *Mux) GroupWithNone(prefix string) IRouteGroup

GroupWithNone creates a new sub router with specified prefix and no middleware attached.

func (*Mux) Handle

func (g *Mux) Handle(method string, path string, h http.HandlerFunc)

Handle allows for any method to be registered with the given route & handler. Allows for non standard methods to be used like CalDavs PROPFIND and so forth.

func (*Mux) Head

func (g *Mux) Head(path string, h http.HandlerFunc)

Head adds a HEAD route & handler to the router.

func (*Mux) Match

func (g *Mux) Match(methods []string, path string, h http.HandlerFunc)

Match adds a route & handler to the router for multiple HTTP methods provided.

func (*Mux) Options

func (g *Mux) Options(path string, h http.HandlerFunc)

Options adds an OPTIONS route & handler to the router.

func (*Mux) Patch

func (g *Mux) Patch(path string, h http.HandlerFunc)

Patch adds a PATCH route & handler to the router.

func (*Mux) Post

func (g *Mux) Post(path string, h http.HandlerFunc)

Post adds a POST route & handler to the router.

func (*Mux) Put

func (g *Mux) Put(path string, h http.HandlerFunc)

Put adds a PUT route & handler to the router.

func (*Mux) Register404

func (p *Mux) Register404(notFound http.HandlerFunc, middleware ...Middleware)

Register404 allows to override the handler function for routes not found. Runs after a route is not found, even after redirecting with the trailing slash.

func (*Mux) RegisterAutomaticOPTIONS

func (p *Mux) RegisterAutomaticOPTIONS(middleware ...Middleware)

RegisterAutomaticOPTIONS specifies feather whether OPTION requests should be handled automatically. Manually configured OPTION handlers take precedence. By default, true.

func (*Mux) RegisterMethodNotAllowed

func (p *Mux) RegisterMethodNotAllowed(middleware ...Middleware)

RegisterMethodNotAllowed indicates feather whether the http 405 Method Not Allowed status code should be processed.

func (*Mux) Serve

func (p *Mux) Serve() http.Handler

Serve returns an http.Handler to be used.

func (*Mux) SetRedirectTrailingSlash

func (p *Mux) SetRedirectTrailingSlash(set bool)

SetRedirectTrailingSlash tells feather whether to attempt to fix the URL by trying to find it. lowercase -> with or without slash -> 404

func (*Mux) Trace

func (g *Mux) Trace(path string, h http.HandlerFunc)

Trace adds a TRACE route & handler to the router.

func (*Mux) Use

func (g *Mux) Use(m ...Middleware)

Use adds a middleware handler to the group middleware chain.

type QueryParamsOption

type QueryParamsOption uint8

QueryParamsOption represents the options for including query parameters during Decode helper functions.

type ReqVars

type ReqVars interface {
	URLParam(pname string) string
}

ReqVars is the interface of request scoped variables tracked by feather.

func RequestVars

func RequestVars(r *http.Request) ReqVars

RequestVars returns the request scoped variables tracked by feather.