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 ¶
- func ConvertMiddleware(emw func(ErrorHandler) ErrorHandler) func(http.Handler) http.Handler
- func ErrorForwarder(handler ErrorHandler) http.Handler
- func ErrorForwarderFunc(handler ErrorHandlerFunc) http.Handler
- func HandleErrors(report ErrorReporter) func(http.Handler) http.Handler
- func Recover() func(ErrorHandler) ErrorHandler
- func RequestLogger(cb func(*LogContext)) func(http.Handler) http.Handler
- func ServeJSON(w http.ResponseWriter, i interface{}, status ...int) error
- func StdRecover() func(http.Handler) http.Handler
- type ErrorHandler
- type ErrorHandlerFunc
- type ErrorMiddleware
- type ErrorReporter
- type LogContext
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConvertMiddleware ¶ added in v0.13.0
func ConvertMiddleware(emw func(ErrorHandler) ErrorHandler) func(http.Handler) http.Handler
ConvertMiddleware converts ale middleware to standard middleware. Depends on having called HandleErrors middleware.
func ErrorForwarder ¶ added in v0.12.0
func ErrorForwarder(handler ErrorHandler) 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.
func ErrorForwarderFunc ¶ added in v0.12.0
func ErrorForwarderFunc(handler ErrorHandlerFunc) http.Handler
ErrorForwarderFunc works like ErrorForwarder, but accepts a raw function.
func HandleErrors ¶ added in v0.12.0
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 Recover ¶ added in v0.13.0
func Recover() func(ErrorHandler) ErrorHandler
Recover converts any panic into an error. Requires use of HandleErrors.
func RequestLogger ¶ added in v0.13.0
func RequestLogger(cb func(*LogContext)) func(http.Handler) http.Handler
RequestLogger 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 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.
Types ¶
type ErrorHandler ¶ added in v0.12.0
type ErrorHandler interface {
ServeHTTP(http.ResponseWriter, *http.Request) error
}
ErrorHandler extends http.Handler with an error return value.
type ErrorHandlerFunc ¶
type ErrorHandlerFunc func(http.ResponseWriter, *http.Request) error
ErrorHandlerFunc extends the standard http.HandlerFunc to support error handling more easily.
func (ErrorHandlerFunc) ServeHTTP ¶ added in v0.12.0
func (f ErrorHandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) error
type ErrorMiddleware ¶ added in v0.12.0
type ErrorMiddleware func(ErrorHandler) ErrorHandler
ErrorMiddleware extends the standard middleware with error handling.
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 ErrorHandlerFunc) http.HandlerFunc
HTTPHandlerFunc wraps an ErrorHandlerFunc, such that it can be used as a standard http.HandlerFunc
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package donewriter provides a simple wrapper around an http.ResponseWriter to track when a response has been sent.
|
Package donewriter provides a simple wrapper around an http.ResponseWriter to track when a response has been sent. |
|
Package envconf provides simple functionality for reading configuration from the environment, such as for use within a 12-Factor Application.
|
Package envconf provides simple functionality for reading configuration from the environment, such as for use within a 12-Factor Application. |
|
Package errors is a drop-in replacement for the errors package in the standard library, with extensions useful for developing web applications.
|
Package errors is a drop-in replacement for the errors package in the standard library, with extensions useful for developing web applications. |
|
Package httperr provides HTTP-centric extensions to standard errors.
|
Package httperr provides HTTP-centric extensions to standard errors. |
|
Package panicerr makes it easy to recover panics, and convert them to standard errors.
|
Package panicerr makes it easy to recover panics, and convert them to standard errors. |
|
Package view provides an HTTP middleware to provide a simple View, based on Go templates.
|
Package view provides an HTTP middleware to provide a simple View, based on Go templates. |