rest

README

REST helpers and middleware

Install and update

go get -u github.com/go-pkgz/rest

Middlewares

AppInfo middleware

Adds info to every response header:

• App-Name - application name
• App-Version - application version
• Org - organization
• M-Host - host name from instance-level $MHOST env

Ping-Pong middleware

Responds with pong on GET /ping. Also responds to anything with /ping suffix, like /v2/ping

example for both:

> http GET https://remark42.radio-t.com/ping

HTTP/1.1 200 OK
Date: Sun, 15 Jul 2018 19:40:31 GMT
Content-Type: text/plain
Content-Length: 4
Connection: keep-alive
App-Name: remark42
App-Version: master-ed92a0b-20180630-15:59:56
Org: Umputun

pong

Logger middleware

Logs all info about request, including user, method, status code, response size, url, elapsed time, request body (optional). Can be customized by passing flags - LogNone, LogAll, LogUser and LogBody. Flags can be combined (provided multiple times)

Recoverer middleware

Recoverer is a middleware that recovers from panics, logs the panic (and a backtrace), and returns a HTTP 500 (Internal Server Error) status if possible.

OnlyFrom middleware

OnlyFrom middleware allows access for limited list of source IPs. Such IPs can be defined as complete ip (like 192.168.1.12), prefix (129.168.) or CIDR (192.168.0.0/16)

Metrics middleware

Metrics middleware responds to GET /metrics with list of expvar. Optionally allows to restrict list of source ips.

BlackWords middleware

BlackWords middleware doesn't allow user-defined words in the request body.

Helpers

• rest.JSON - map alias, just for convenience type JSON map[string]interface{}
• rest.RenderJSON - renders json response from interface{}
• rest.RenderJSONFromBytes - renders json response from []byte
• rest.RenderJSONWithHTML - renders json response with html tags and forced charset=utf-8
• rest.SendErrorJSON - makes {error: blah, details: blah} json body and responds with given error code. Also adds context to logged message

Caching

Cache wrapper provides loading cache for rest/http responses. See cache readme for more details and examples.

Documentation

Index

• func AppInfo(app string, author string, version string) func(http.Handler) http.Handler
• func BlackWords(words ...string) func(http.Handler) http.Handler
• func BlackWordsFn(fn func() []string) func(http.Handler) http.Handler
• func GetTraceID(r *http.Request) string
• func Metrics(onlyIps ...string) func(http.Handler) http.Handler
• func OnlyFrom(onlyIps ...string) func(http.Handler) http.Handler
• func Ping(next http.Handler) http.Handler
• func Recoverer(l logger.Backend) func(http.Handler) http.Handler
• func RenderJSON(w http.ResponseWriter, r *http.Request, data interface{})
• func RenderJSONFromBytes(w http.ResponseWriter, r *http.Request, data []byte) error
• func RenderJSONWithHTML(w http.ResponseWriter, r *http.Request, v interface{}) error
• func SendErrorJSON(w http.ResponseWriter, r *http.Request, l logger.Backend, code int, err error, ...)
• func Trace(next http.Handler) http.Handler
• type JSON

Functions

func AppInfo

func AppInfo(app string, author string, version string) func(http.Handler) http.Handler

AppInfo adds custom app-info to the response header

func BlackWords

func BlackWords(words ...string) func(http.Handler) http.Handler

BlackWords middleware doesn't allow some words in the request body

func BlackWordsFn

func BlackWordsFn(fn func() []string) func(http.Handler) http.Handler

BlackWordsFn middleware uses func to get the list and doesn't allow some words in the request body

func GetTraceID

func GetTraceID(r *http.Request) string

GetTraceID returns request id from the context

func Metrics

func Metrics(onlyIps ...string) func(http.Handler) http.Handler

Metrics responds to GET /metrics with list of expvar

func OnlyFrom

func OnlyFrom(onlyIps ...string) func(http.Handler) http.Handler

OnlyFrom middleware allows access for limited list of source IPs. Such IPs can be defined as complete ip (like 192.168.1.12), prefix (129.168.) or CIDR (192.168.0.0/16)

func Ping

func Ping(next http.Handler) http.Handler

Ping middleware response with pong to /ping. Stops chain if ping request detected

func Recoverer

func Recoverer(l logger.Backend) func(http.Handler) http.Handler

Recoverer is a middleware that recovers from panics, logs the panic and returns a HTTP 500 status if possible.

func RenderJSON

func RenderJSON(w http.ResponseWriter, r *http.Request, data interface{})

RenderJSON sends data as json

func RenderJSONFromBytes

func RenderJSONFromBytes(w http.ResponseWriter, r *http.Request, data []byte) error

RenderJSONFromBytes sends binary data as json

func RenderJSONWithHTML

func RenderJSONWithHTML(w http.ResponseWriter, r *http.Request, v interface{}) error

RenderJSONWithHTML allows html tags and forces charset=utf-8

func SendErrorJSON

func SendErrorJSON(w http.ResponseWriter, r *http.Request, l logger.Backend, code int, err error, msg string)

SendErrorJSON sends {error: msg} with error code and logging error and caller

func Trace

func Trace(next http.Handler) http.Handler

Trace looks for header X-Request-ID and makes it as random id if not found, then populates it to the result's header and to request context

Types

type JSON

type JSON map[string]interface{}

JSON is a map alias, just for convenience