errchain

Documentation

Overview

Package errchain provides a simple error bus for passing errors between

Index

• type ErrChain
  • func New(hdlr ErrorHandler) *ErrChain
  • func (b *ErrChain) ToHandler(h Handler, mw ...Middleware) http.Handler
  • func (b *ErrChain) ToHandlerFunc(h HandlerFunc, mw ...Middleware) http.HandlerFunc
  • func (b *ErrChain) Use(mw ...Middleware)
• type ErrorHandler
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) error
• type HandlerHook
• type Middleware
  • func AdaptMiddleware(httpMid func(http.Handler) http.Handler) Middleware
• type Mux
  • func NewMux(chain *ErrChain) *Mux
  • func (r *Mux) Connect(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Delete(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) ErrHandle(path string, h Handler, mw ...Middleware)
  • func (r *Mux) Get(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Head(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Method(method, path string, h Handler, mw ...Middleware)
  • func (r *Mux) MethodFunc(method, path string, h HandlerFunc, mw ...Middleware)
  • func (r *Mux) Options(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Patch(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Post(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Put(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Mux) Trace(path string, fn HandlerFunc, mw ...Middleware)
  • func (r *Mux) Use(mw ...func(http.Handler) http.Handler)
  • func (r *Mux) UsePrefix(prefix string) *Mux
  • func (r *Mux) UseRouter(router Router) *Mux
• type Router

Types

type ErrChain

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

ErrChain is an error bus for passing errors between middleware and handlers up the stack. You can provide a ErrHandler middleware that will be the outermost middleware in the stack. You can also provide a list of GlobalMW middleware that will be applied to all handlers.

func New

func New(hdlr ErrorHandler) *ErrChain

New creates a new ErrChain with the provided ErrHandler. If the ErrHandler is nil, this function will panic.

func (*ErrChain) ToHandler

func (b *ErrChain) ToHandler(h Handler, mw ...Middleware) http.Handler

ToHandler converts a Handler to an http.Handler. This function will wrap the provided handler with the global middleware and the provided middleware. The middleware will be applied in the order that it is provided. So the first middleware provided will be the first to be executed by requests and the last middleware provided will be the last to be executed by requests.

Example:

chain.ToHandler(handler, middleware1, middleware2, middleware3)

The above example will result in the following execution order:

middleware1 -> middleware2 -> middleware3 -> {global} -> handler

func (*ErrChain) ToHandlerFunc

func (b *ErrChain) ToHandlerFunc(h HandlerFunc, mw ...Middleware) http.HandlerFunc

ToHandlerFunc does the same thing as ToHandler except that it returns a http.HandlerFunc.

func (*ErrChain) Use

func (b *ErrChain) Use(mw ...Middleware)

Use adds middleware to the global middleware chain. This middleware will be applied to all handlers. Note that the middleware will be applied in the order that it is provided. So the first middleware provided will be the first to be executed by requests and the last middleware provided will be the last to be executed by requests.

When called multiple times, the middleware will be added to the end of the chain.

Example:

chain.Use(middleware1, middleware2, middleware3)

The above example will result in the following execution order:

middleware1 -> middleware2 -> middleware3 -> {handler specific} -> handler

type ErrorHandler

type ErrorHandler func(Handler) http.Handler

ErrorHandler defines your outermost middleware that will be used to handle errors from the handler and middleware chain.

type Handler

type Handler interface {
	ServeHTTP(http.ResponseWriter, *http.Request) error
}

Handler is an interface that is an alternative to the http.Handler interface. It is the same as http.Handler except that it returns an error.

type HandlerFunc

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

HandlerFunc is an adapter to allow the use of ordinary functions as handlers.

func (HandlerFunc) ServeHTTP

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

type HandlerHook

type HandlerHook func(pattern string, handler http.Handler) http.Handler

HandlerHook is a function that can be used to add hooks to the mux. this was implemented to allow for the otelhttp.WithRouteTag method to be easily added to the mux, but may serve other purposes as well.

type Middleware

type Middleware func(Handler) Handler

func AdaptMiddleware

func AdaptMiddleware(httpMid func(http.Handler) http.Handler) Middleware

AdaptMiddleware adapts a http middleware to a errchain middleware. This is useful when you have a http middleware that you want to use with errchain but adheres to the standard middleware signature.

In most cases, you don't need to use this and should use the errchain.Mux and it's support for standard http middleware or utilize another library outside of errchain to handle your middleware.

type Mux

type Mux struct {

	// Hook is a function that can be used to add hooks to the mux. This
	// was implemented to allow for the otelhttp.WithRouteTag method to be
	// easily added to the mux, but may serve other purposes as well.
	//
	// Do not use this for middleware. Middleware should be added using the
	// Use method, added to the ErrChain, or added to the individual routes.
	Hook HandlerHook
	// contains filtered or unexported fields
}

Mux is a simple wrapper around the standard http.ServeMux with it's new improvements in go 1.22. It extends the http.ServeMux with the following features:

1. allows prefixing of all routes 2. allows for using errchain.Handler types directly 3. provides method based functions for GET, POST, etc...

Because route embeds the http.Servermux, it can be used as a drop-in replacement for the http.ServeMux. However, because of this, if you want to use errchain.Handler types you need to use the ErrHandler method to add the handler to the route.

func NewMux

func NewMux(chain *ErrChain) *Mux

NewMux creates a new Mux with the provided prefix and ErrChain. If the ErrChain is nil, this function will panic.

if the prefix is not empty, it will be preprocessed to ensure that it starts with a '/'. If the prefix is only a single '/' then it is left as is.

If chain is nil, this function will panic.

func (*Mux) Connect

func (r *Mux) Connect(path string, fn HandlerFunc, mw ...Middleware)

Connect is a shortcut for Method(http.MethodConnect, path, h, mw...)

func (*Mux) Delete

func (r *Mux) Delete(path string, fn HandlerFunc, mw ...Middleware)

Delete is a shortcut for Method(http.MethodDelete, path, h, mw...)

func (*Mux) ErrHandle

func (r *Mux) ErrHandle(path string, h Handler, mw ...Middleware)

ErrHandle adds a handler to the mux for the provided path. It does not bind the handler to a specific method. The path is automatically prefixed with the mux's prefix set during creation. The handler is wrapped in the error chain middleware and any additional middleware provided is applied to the handler.

This is a errchain.Handler specific version of the http.ServeMux.Handle.

func (*Mux) Get

func (r *Mux) Get(path string, fn HandlerFunc, mw ...Middleware)

Get is a shortcut for Method(http.MethodGet, path, h, mw...)

func (*Mux) Head

func (r *Mux) Head(path string, fn HandlerFunc, mw ...Middleware)

Head is a shortcut for Method(http.MethodHead, path, h, mw...)

func (*Mux) Method

func (r *Mux) Method(method, path string, h Handler, mw ...Middleware)

Method adds a handler to the mux for the provided method and path. The path is automatically prefixed with the mux's prefix set during creation. The handler is wrapped in the error chain middleware and any additional middleware provided is applied to the handler.

Example:

mux.Method(http.MethodGet, "/path", handler, middleware1, middleware2)

func (*Mux) MethodFunc

func (r *Mux) MethodFunc(method, path string, h HandlerFunc, mw ...Middleware)

MethodFunc is a shortcut for Method(method, path, h, mw...) but uses a HandlerFunc instead of a Handler.

func (*Mux) Options

func (r *Mux) Options(path string, fn HandlerFunc, mw ...Middleware)

Options is a shortcut for Method(http.MethodOptions, path, h, mw...)

func (*Mux) Patch

func (r *Mux) Patch(path string, fn HandlerFunc, mw ...Middleware)

Patch is a shortcut for Method(http.MethodPatch, path, h, mw...)

func (*Mux) Post

func (r *Mux) Post(path string, fn HandlerFunc, mw ...Middleware)

Post is a shortcut for Method(http.MethodPost, path, h, mw...)

func (*Mux) Put

func (r *Mux) Put(path string, fn HandlerFunc, mw ...Middleware)

Put is a shortcut for Method(http.MethodPut, path, h, mw...)

func (*Mux) ServeHTTP

func (r *Mux) ServeHTTP(w http.ResponseWriter, req *http.Request)

func (*Mux) Trace

func (r *Mux) Trace(path string, fn HandlerFunc, mw ...Middleware)

Trace is a shortcut for Method(http.MethodTrace, path, h, mw...)

func (*Mux) Use

func (r *Mux) Use(mw ...func(http.Handler) http.Handler)

Use adds middleware to the mux. This middleware will be applied to all routes that are added to the mux, regardless of the method. These are applied outside of the error chain middleware.

Example

mux.Use(middleware1, middleware2)
mux.Get("/path", handler, middleware3)

in this the call order is:

1. middleware1
2. middleware2
3. err chain middleware
4. middleware3
5. handler

func (*Mux) UsePrefix

func (r *Mux) UsePrefix(prefix string) *Mux

UsePrefix sets the prefix for the Mux. This prefix will be prepended to all

Example:

mux := errchain.New(chain)
mux = mux.UsePrefix("/api")

func (*Mux) UseRouter

func (r *Mux) UseRouter(router Router) *Mux

UseRouter sets the internal router for the mux. This overrides the default http.ServeMux with the provided router. You should call this method before adding any routes to the mux.

type Router

type Router interface {
	http.Handler
	Handle(path string, h http.Handler)
}

Router is an interface that defines the contract required for the internal implementation of the Mux type. The Mux type is a wrapper around whatever implementation of the Router interface is provided. This allows for the Mux type to be used as a drop-in replacement for the http.ServeMux or any other implementation of the Router interface.

Note that the Router _MUST_ implement the new method in go 1.22 for adding handlers to the mux.

Example:

"GET /path"

If this is not supported, it will have unexpected behavior and may not work at all.