ale

README

Ale

Ale is a collection of HTTP-related tools to be used with roll-your-own Go web applications.

This software is released under the MIT license, as outlined in the included LICENSE.md file.

Documentation

Overview

Package ale provides some utilites to extend standard HTTP handlers for easier error handling.

The core of this package is the ErrorHandler and ErrorHandlerFunc types, which simply extends their standard library companion types (http.Handler and http.HandlerFunc respectively) to return errors.

Such a handler (or middleware) should either write a response to the standard http.ResponseWriter _or_ return an error. Any such errors are converted to a response by an ErrorReporter. This allows putting all error-handling logic in a single location, rather than scattered throughout your application.

Index

• Variables
• func BasicReporter(w http.ResponseWriter, r *http.Request, err error)
• func ConvertMiddleware(emw Middleware) func(http.Handler) http.Handler
• func ErrorForwarder(handler Handler) http.Handler
• func ErrorForwarderFunc(handler HandlerFunc) http.Handler
• func HandleErrors(report ErrorReporter) func(http.Handler) http.Handler
• func IsUsed(w http.ResponseWriter) (bool, error)
• func Recover() func(Handler) Handler
• func RequestLogger(cb func(*LogContext)) func(Handler) Handler
• func ServeJSON(w http.ResponseWriter, i interface{}, status ...int) error
• func Std(h Handler) http.Handler
• func StdRecover() func(http.Handler) http.Handler
• func StdRequestLogger(cb func(*LogContext)) func(http.Handler) http.Handler
• func StdTrackWriterUsage(next http.Handler) http.Handler
• type Chain
  • func New() *Chain
  • func (c *Chain) Handler(h http.Handler) http.Handler
  • func (c *Chain) SetErrorReporter(r ErrorReporter)
  • func (c *Chain) SetLogger(l func(*LogContext))
  • func (m *Chain) Use(mw Middleware)
  • func (m *Chain) UseStd(mw func(http.Handler) http.Handler)
• type ErrorHandler
• type ErrorHandlerFunc
• type ErrorMiddleware
• type ErrorReporter
  • func (c ErrorReporter) HTTPHandlerFunc(f HandlerFunc) http.HandlerFunc
• type Handler
  • func TrackWriterUsage(next Handler) Handler
• type HandlerFunc
  • func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (f HandlerFunc) ServeHTTPE(w http.ResponseWriter, r *http.Request) error
• type LogContext
  • func NewLogContext(w http.ResponseWriter, r *http.Request) *LogContext
  • func (l *LogContext) Finalize()
  • func (l *LogContext) Header() http.Header
  • func (l *LogContext) Write(p []byte) (int, error)
  • func (l *LogContext) WriteHeader(status int)
• type Middleware
• type UsedWriter

Variables

var DefaultReporter = BasicReporter

DefaultReporter is used by Std() any time an error has not been injected with HandleErrors.

Functions

func BasicReporter

func BasicReporter(w http.ResponseWriter, r *http.Request, err error)

BasicReporter is a bare ErrorReporter, which wraps http.Error. If err satisfies the interface{ HTTPStatus() int } interface, the method is called to determine the HTTP status.

If w is a UsedWriter, and returns true, then nothing is written to the response.

func ConvertMiddleware

func ConvertMiddleware(emw Middleware) func(http.Handler) http.Handler

ConvertMiddleware converts ale middleware to standard middleware. See Std() to understand how errors are handled.

func ErrorForwarder

func ErrorForwarder(handler Handler) http.Handler

ErrorForwarder forwards any error returned by handler, by injecting it into the context. If an error is already set, the handler is not called. If the InjectError middleware has not been called, this function will panic.

Deprecated: Use Std()

func ErrorForwarderFunc

func ErrorForwarderFunc(handler HandlerFunc) http.Handler

ErrorForwarderFunc works like ErrorForwarder, but accepts a raw function.

Deprecated: HandlerFunc now supports ServeHTTP directly.

func HandleErrors

func HandleErrors(report ErrorReporter) func(http.Handler) http.Handler

HandleErrors should be called at the top of your middleware chain, likely as the very first middleware, even before any panic recovery. It injects a pointer to an error in the context of the request, to abuse the context for out-of-band error passing. Evil, I know. This allows you to mix standard HTTP handlers or middlewares with the error-aware versions in this package. If any middleware/handler returns an error, report is called.

func IsUsed

func IsUsed(w http.ResponseWriter) (bool, error)

WriterIsDIsUsedone returns true if a response has been written. An error is returned if the underlying writer is not a DoneWriter.

func Recover

func Recover() func(Handler) Handler

Recover converts any panic into an error. Requires use of HandleErrors.

func RequestLogger

func RequestLogger(cb func(*LogContext)) func(Handler) Handler

RequestLogger gathers request statistics for logging, and calls cb to do the actual logging. Any error will be included in the logging context, and consumed. This handler always returns a nil error.

func ServeJSON

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

ServeJSON marshals i and serves it on w. If the Content-Type header is not yet set on w, it will be set to "application/json; charset=utf-8". If status is passed, the first status value will be passed to w.WriteHeader, otherwise the default of http.StatusOK is used.

func Std

func Std(h Handler) http.Handler

Std converts h into a standard http.Handler. If h returns an error:

• If possible, the error is injected to the context (when HandleErrors has been called).
• Otherwise, DefaultReporter is called

func StdRecover

func StdRecover() func(http.Handler) http.Handler

StdRecover works as Recover, but with standard middleware signatures.

func StdRequestLogger

func StdRequestLogger(cb func(*LogContext)) func(http.Handler) http.Handler

StdRequestLogger gathers request statistics for logging, and calls cb to do the actual logging. If HandleErrors was called first, any error will be included in the logging context.

func StdTrackWriterUsage

func StdTrackWriterUsage(next http.Handler) http.Handler

StdTrackWriterUsage is an http middleware equivalent of WrapWriter.

Types

type Chain

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

Chain represents a complete middleware chain and adapter.

func New

func New() *Chain

New returns an empty Ale middleware chain.

func (*Chain) Handler

func (c *Chain) Handler(h http.Handler) http.Handler

Handler applies the middleware chain to h. This method injects an error by calling HandleErrors.

func (*Chain) SetErrorReporter

func (c *Chain) SetErrorReporter(r ErrorReporter)

SetErrerReporter sets the ErrorReporter, to handle any errors generated by a request. If unset, BasicReporter is used.

func (*Chain) SetLogger

func (c *Chain) SetLogger(l func(*LogContext))

SetLogger sets a request logger. If unset, requests are not logged by ale.

func (*Chain) Use

func (m *Chain) Use(mw Middleware)

Use adds mw to the end of the middleware chain.

func (*Chain) UseStd

func (m *Chain) UseStd(mw func(http.Handler) http.Handler)

UseStd adds mw to the end of the middleware chain.

type ErrorHandler

type ErrorHandler = Handler

ErrorHandler is an alias to Handler

Deprecated: Use Handler

type ErrorHandlerFunc

type ErrorHandlerFunc = HandlerFunc

ErrorHandlerFunc is an alias to HandlerFunc.

Deprecated: Use HandlerFunc

type ErrorMiddleware

type ErrorMiddleware = Middleware

ErrorMiddleware is an alias to Middleware.

Deprecated: Use Middleware

type ErrorReporter

type ErrorReporter func(w http.ResponseWriter, r *http.Request, err error)

ErrorReporter is a function that can report an HTTP error returned by a ErrorHandlerFunc.

func (ErrorReporter) HTTPHandlerFunc

func (c ErrorReporter) HTTPHandlerFunc(f HandlerFunc) http.HandlerFunc

HTTPHandlerFunc wraps a HandlerFunc, such that it can be used as a standard http.HandlerFunc.

type Handler

type Handler interface {
	// ServeHTTPE serves the same purpose as http.Handler's ServeHTTP, except
	// that it may return an error. The function should _either_ write to
	// http.ResponseWriter _or_ return an error.
	ServeHTTPE(http.ResponseWriter, *http.Request) error
}

Handler extends http.Handler with an error return value.

func TrackWriterUsage

func TrackWriterUsage(next Handler) Handler

TrackWriterUsage is an ale middleware which wraps the standard http.ResponseWriter with a DoneWriter. Subsequent middlewares or handlers should use the WriterIsDone method to check the status.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request) error

HandlerFunc extends the standard http.HandlerFunc to support error handling more easily.

HandlerFunc also satisfies the http.Handler interface by implementing the ServeHTTP() method. See the docs for Std() for how errors are handled.

func (HandlerFunc) ServeHTTP

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (HandlerFunc) ServeHTTPE

func (f HandlerFunc) ServeHTTPE(w http.ResponseWriter, r *http.Request) error

type LogContext

type LogContext struct {

	// Request contains a shallow copy of the original request, without the
	// body.
	Request *http.Request

	// StatusCode is the HTTP status code sent to the client.
	StatusCode int
	// ResponseHeader is the list of header values sent to the client.
	ResponseHeader http.Header
	// ResponseHeader is the list of trailer values sent to the client.
	ResponseTrailer http.Header
	// ResponseBytes is the number of bytes written in the response body.
	ResponseBytes int64
	// RequestBytes is the number of bytes read from the request body. This
	// can differ from the Content-Length value if reading is not completed, or
	// in case Content-Length is unset.
	RequestBytes int64

	// StartTime is the time the request was received by the server
	StartTime time.Time
	// ElapsedTime is the duration it took to serve the request
	ElapsedTime time.Duration

	// Error is the error, if any, returned from the handler/middlware chain.
	Error error
	// contains filtered or unexported fields
}

LogContext captures data about a request and response, for logging.

func NewLogContext

func NewLogContext(w http.ResponseWriter, r *http.Request) *LogContext

NewLogContext returns a new log context, which should be used as a ResponseWriter for subsequent handlers in middleware.

Example:

func LogMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        logCtx := NewLogContext(w,r)
        next.ServeHTTP(logCtx, r)
        logCtx.Finalize()
        // Log logCtx here
    })
}

func (*LogContext) Finalize

func (l *LogContext) Finalize()

Finalize should be called after ServeHTTP, to finalize the response values. Without this call, trailers will not be set, and elapsed time is not calculated.

func (*LogContext) Header

func (l *LogContext) Header() http.Header

Header returns the header map that will be sent by WriteHeader.

func (*LogContext) Write

func (l *LogContext) Write(p []byte) (int, error)

Write writes the data to the connection as part of an HTTP reply.

func (*LogContext) WriteHeader

func (l *LogContext) WriteHeader(status int)

WriteHeader sends an HTTP response header with the provided status code.

type Middleware

type Middleware func(Handler) Handler

Middleware extends the standard middleware with error handling.

type UsedWriter

type UsedWriter interface {
	http.ResponseWriter
	Used() bool
}

UsedWriter extends the http.ResponseWriter interface to return a bool to indicate whether anything has been written.

To use it, call the TrackWriterUsage middleware early in your middleware stack. Then in other middlewares or handlers, you can use the WasUsed method to check the status.

func main() {
    r := chi.NewRouter()

    r.Use(ale.TrackWriterUsage)
    // and other middlewares

    r.Get("/", func(w http.ResponseWriter, r *http.Request) {
        if done, _ := ale.WasUsed(w); done {
            // Nothing to do, a response was already sent
            return
        }

        // Normal operation here...

    })
}