mw

README

go-mw

HTTP middleware for Go 1.8 and beyond.

What is go-mw?

go-mw is a small library for making http middleware in Go. It is not a web framework: Handling routes, rate limiting et al is up to some other library (or framework, your pick), but handling middleware is where this is key.

Why go-mw?

go-mw is based upon two observations I have done while programming web servers with Ring in Clojure:

1. Passing data around as values gives you the power to separate domain logic with serialisation and socket concerns
2. Wrapping the context (db transactions, caches, user id etc) in custom types means you can implicitly provide Context to the user, and avoid unnecessarily many error checks.

The former is not as common in Go as far as I know: All the HTTP frameworks I have seen so far focus on embracing the (w *http.ResponseWriter, r http.Request) pattern in some way – either by adding additional functions on top of the ResponseWriter (typically WriteJSON or something similar) or just using the plain old http.ServeHTTP.

Of course, this is necessary if you can't opt out of the web framework and need to stream while processing/doing domain logic; whether it is due to performance or something else. And passing by value will be slower. However, for the vast majority of users, pass-by-value will not likely be slow enough for it to matter.

License

Copyright © 2017 Jean Niklas L'orange

Distributed under the BSD 3-clause license, which is available in the file LICENSE.

Documentation

Index

• Variables
• func IntoHTTPMiddleware(m Middleware) func(http.Handler) http.Handler
• func IsErrMissingContextValue(err error) bool
• func IsErrUnhandled(err error) bool
• func WithContextValue(r *http.Request, key, val interface{}) *http.Request
• type ErrMissingContextValue
  • func (e *ErrMissingContextValue) Error() string
• type Handler
• type Middleware
  • func Chain(fs ...Middleware) Middleware
  • func (f Middleware) Then(g Middleware) Middleware
• type Response
  • func NewResponse(w http.ResponseWriter) *Response
  • func (htr *Response) Header() http.Header
  • func (htr *Response) Write(_ []byte) (int, error)
  • func (htr *Response) WriteHeader(_ int)

Variables

var ErrHandled = errors.New("Error is handled and is inside the response")

ErrHandled is the error returned when an error has been translated into a response.

Functions

func IntoHTTPMiddleware

func IntoHTTPMiddleware(m Middleware) func(http.Handler) http.Handler

IntoHTTPMiddleware converts go-mw middleware into a net/http middleware, with one caveat: The Response input should be treated just like a ResponseWriter, i.e. modification of headers after it's handed downstream will (most likely) have no effect.

func IsErrMissingContextValue

func IsErrMissingContextValue(err error) bool

IsErrMissingContextValue returns true if the error is because of a missing context value

func IsErrUnhandled

func IsErrUnhandled(err error) bool

IsErrUnhandled returns true if the error is not nill and is not ErrHandled.

func WithContextValue

func WithContextValue(r *http.Request, key, val interface{}) *http.Request

WithContextValue updates the context of the provided request such that it associates key with val. The updated *http.Request is returned.

Types

type ErrMissingContextValue

type ErrMissingContextValue struct {
	What string
}

ErrMissingContextValue is returned from functions which extracts data from contexts.

func (*ErrMissingContextValue) Error

func (e *ErrMissingContextValue) Error() string

type Handler

type Handler func(*Response, *http.Request) error

Handler is a function which takes in a respone and a request. Note that, in contrast to http.ResponseWriter, this handler can NOT stream data to the user.

It's not impossible to stream data, but this is the responsibility of the function writing Response into the actual http.ResponseWriter.

type Middleware

type Middleware func(Handler) Handler

Middleware is a function which takes a Handler and returns one.

func Chain

func Chain(fs ...Middleware) Middleware

Chain takes an arbitrary amount of Middlewares and chains them together. The first middleware will be activated first, the second second etc.

func (Middleware) Then

func (f Middleware) Then(g Middleware) Middleware

Then chains two Middleware functions and returns a new Middleware function. f will be called first, then g.

type Response

type Response struct {
	StatusCode int
	Body       interface{}
	Headers    http.Header
	// Do not use Writer unless you really know what you're doing.
	Writer http.ResponseWriter
}

A Response is the current built up response for this request. Middleware will typically set additional headers or add additional context in the http.Request.

func NewResponse

func NewResponse(w http.ResponseWriter) *Response

NewResponse returns an empty Response to be used by middleware and handlers.

func (*Response) Header

func (htr *Response) Header() http.Header

Header returns the header map of a Response.

func (*Response) Write

func (htr *Response) Write(_ []byte) (int, error)

Write is a method which always panics. It's implemented so that users can utilize functions that works on http.ResponseWriters, which only require Header() to work as intended (e.g. http.SetCookie)

func (*Response) WriteHeader

func (htr *Response) WriteHeader(_ int)

WriteHeader is a method which always panics. It's implemented so that users can utilize functions that works on http.ResponseWriters, which only require Header() to work as intended (e.g. http.SetCookie)