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 request, request handling time and response. Log record fields in order of occurrence:

• Request's HTTP method
• Requested URL (with sanitized query)
• Remote IP
• Response's HTTP status code
• Response body size
• Request handling time
• Userinfo associated with the request (optional)
• Request subject (optional)
• Request ID (if X-Request-ID present)
• Request body (optional)

remote IP can be masked with user defined function

example: 019/03/05 17:26:12.976 [INFO] GET - /api/v1/find?site=remark - 8e228e9cfece - 200 (115) - 4.47784618s

Recoverer middleware

Recoverer is a middleware that recovers from panics, logs the panic (and a backtrace), and returns an 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 restricting list of source ips.

BlackWords middleware

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

SizeLimit middleware

SizeLimit middleware checks if body size is above the limit and returns StatusRequestEntityTooLarge (413)

Trace middleware

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

Deprecation middleware

Adds the HTTP Deprecation response header, see draft-dalal-deprecation-header-00

BasicAuth middleware

BasicAuth middleware requires basic auth and matches user & passwd with client-provided checker. In case if no basic auth headers returns StatusUnauthorized, in case if checker failed - StatusForbidden

Rewrite middleware

Rewrites requests with from->to rule. Supports regex (like nginx) and prevents multiple rewrites. For example Rewrite("^/sites/(.*)/settings/$", "/sites/settings/$1") will change request's URL from /sites/id1/settings/ to /sites/settings/id1

NoCache middleware

Sets a number of HTTP headers to prevent a router (handler's) response from being cached by an upstream proxy and/or client.

Headers middleware

Sets headers (passed as key:value) to requests. I.e. rest.Headers("Server:MyServer", "X-Blah:Foo")

Gzip middleware

Compresses response with gzip.

Helpers

• rest.Wrap - converts a list of middlewares to nested handlers calls (in reverse order)
• 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 the logged message
• rest.NewErrorLogger - creates a struct providing shorter form of logger call
• rest.FileServer - creates a file server for static assets with directory listing disabled

Documentation

Overview

Package rest provides common middlewares and helpers for rest services

Index

• func AppInfo(app, author, version string) func(http.Handler) http.Handler
• func BasicAuth(checker func(user, passwd string) bool) 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 CacheControl(expiration time.Duration, version string) func(http.Handler) http.Handler
• func CacheControlDynamic(expiration time.Duration, versionFn func(r *http.Request) string) func(http.Handler) http.Handler
• func Deprecation(version string, date time.Time) func(http.Handler) http.Handler
• func FileServer(public, local string) (http.Handler, error)
• func GetTraceID(r *http.Request) string
• func Gzip(contentTypes ...string) func(http.Handler) http.Handler
• func Headers(headers ...string) func(http.Handler) http.Handler
• func Metrics(onlyIps ...string) func(http.Handler) http.Handler
• func NoCache(h 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, 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 Rewrite(from, to string) func(http.Handler) http.Handler
• func SendErrorJSON(w http.ResponseWriter, r *http.Request, l logger.Backend, code int, err error, ...)
• func SizeLimit(size int64) func(http.Handler) http.Handler
• func Trace(next http.Handler) http.Handler
• func Wrap(handler http.Handler, mws ...func(http.Handler) http.Handler) http.Handler
• type ErrorLogger
  • func NewErrorLogger(l logger.Backend) *ErrorLogger
  • func (e *ErrorLogger) Log(w http.ResponseWriter, r *http.Request, httpCode int, err error, msg ...string)
• type JSON

Functions

func AppInfo

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

AppInfo adds custom app-info to the response header

func BasicAuth

func BasicAuth(checker func(user, passwd string) bool) func(http.Handler) http.Handler

BasicAuth middleware requires basic auth and matches user & passwd with client-provided checker

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 CacheControl

func CacheControl(expiration time.Duration, version string) func(http.Handler) http.Handler

CacheControl is a middleware setting cache expiration. Using url+version for etag

func CacheControlDynamic

func CacheControlDynamic(expiration time.Duration, versionFn func(r *http.Request) string) func(http.Handler) http.Handler

CacheControlDynamic is a middleware setting cache expiration. Using url+ func(r) for etag

func Deprecation

func Deprecation(version string, date time.Time) func(http.Handler) http.Handler

Deprecation adds a header 'Deprecation: version="version", date="date" header' see https://tools.ietf.org/id/draft-dalal-deprecation-header-00.html

func FileServer

func FileServer(public, local string) (http.Handler, error)

FileServer returns http.FileServer handler to serve static files from a http.FileSystem, prevents directory listing. - public defines base path of the url, i.e. for http://example.com/static/* it should be /static - local for the local path to the root of the served directory

func GetTraceID

func GetTraceID(r *http.Request) string

GetTraceID returns request id from the context

func Gzip

func Gzip(contentTypes ...string) func(http.Handler) http.Handler

Gzip is a middleware compressing response

func Headers

func Headers(headers ...string) func(http.Handler) http.Handler

Headers middleware adds headers to request

func Metrics

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

Metrics responds to GET /metrics with list of expvar

func NoCache

func NoCache(h http.Handler) http.Handler

NoCache is a simple piece of middleware that sets a number of HTTP headers to prevent a router (or subrouter) from being cached by an upstream proxy and/or client.

As per http://wiki.nginx.org/HttpProxyModule - NoCache sets:

Expires: Thu, 01 Jan 1970 00:00:00 UTC
Cache-Control: no-cache, private, max-age=0
X-Accel-Expires: 0
Pragma: no-cache (for HTTP/1.0 proxies/clients)

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, 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 Rewrite

func Rewrite(from, to string) func(http.Handler) http.Handler

Rewrite middleware with from->to rule. Supports regex (like nginx) and prevents multiple rewrites example: Rewrite(`^/sites/(.*)/settings/$`, `/sites/settings/$1`

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 SizeLimit

func SizeLimit(size int64) func(http.Handler) http.Handler

SizeLimit middleware checks if body size is above the limit and returns StatusRequestEntityTooLarge (413)

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

func Wrap

func Wrap(handler http.Handler, mws ...func(http.Handler) http.Handler) http.Handler

Wrap converts a list of middlewares to nested calls (in reverse order)

Types

type ErrorLogger

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

ErrorLogger wraps logger.Backend

func NewErrorLogger

func NewErrorLogger(l logger.Backend) *ErrorLogger

NewErrorLogger creates ErrorLogger for given Backend

func (*ErrorLogger) Log

func (e *ErrorLogger) Log(w http.ResponseWriter, r *http.Request, httpCode int, err error, msg ...string)

Log sends json error message {error: msg} with error code and logging error and caller

type JSON

type JSON map[string]interface{}

JSON is a map alias, just for convenience