horror

README

Horror

Package horror implements interfaces for http error handling.

Horror was created to simplify error handling with standard go http.Handler and give developers tools to encapsulate common error scenarios.

Thanks to WithError function and Adapter type you can use horror.Handler with existing go code based on http.Handler interface.

If you're interested in using this module, please see examples that are placed in examples directory.

See github.com/thinkofher/horror/status for convenient http errors that satisfy Error interface from this module.

Documentation

Overview

Package horror implements interfaces for http error handling.

Horror was created to simplify error handling with go standard http.Handlers and give developers tools to encapsulate common error scenarios. Thanks to WithError function and Adapter type you can use horror.Handler with existing go code based on http.Handler interface.

See "github.com/thinkofher/horror/status" for convenient http errors that satisfy Error interface from this module.

Index

• func InternalHandler(f func(error, http.ResponseWriter, *http.Request)) func(http.Handler) http.Handler
• func WithError(h Handler) http.Handler
• type Adapter
  • func NewAdapter(b *AdapterBuilder) (a *Adapter)
  • func (a Adapter) WithError(h Handler) http.Handler
• type AdapterBuilder
• type Error
• type Handler
• type HandlerFunc
  • func (h HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request) error

Functions

func InternalHandler

func InternalHandler(f func(error, http.ResponseWriter, *http.Request)) func(http.Handler) http.Handler

InternalHandler returns http middleware that can be used by popular http go router libraries. Returned middleware injects given function f as new default internal server error handler, that will be called when WithError function will meet unknown error that doesn't satisfy Error (from horror package) interface.

Be aware that Adapter, no matter what, will never use registered function. You have to use AdapterBuilder to overwrite default behaviour.

func WithError

func WithError(h Handler) http.Handler

WithError wraps Handler, adapts it and returns http.Handler that can be used with other APIs that relies on go standard library.

Types

type Adapter

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

Adapter creates a custom way for adapting the Handler to the standard http.Handler implementation with it's WithError method.

You should always use New factory function with AdapterBuilder structure for creating your adapters.

func NewAdapter

func NewAdapter(b *AdapterBuilder) (a *Adapter)

NewAdapter returns pointer to Adapter that is safe to use and will not panic during runtime because of nil pointers.

Using NewAdapter is only preferable way to create Adapter.

func (Adapter) WithError

func (a Adapter) WithError(h Handler) http.Handler

WithError wraps Handler, adapts it and returns http.Handler that can be used with other APIs that relies on go standard library.

This method will never use internal server error handler registered with InternalHandler function. You have to define your own InternalHandler with AdapterBuilder. Otherwise: Adapter will use default internal server error handler that writes string returned by error.Error() to http.ResponseWriter with http.StatusInterlaServerError code.

type AdapterBuilder

type AdapterBuilder struct {
	// BeforeError is the function that will be called by Adapter.WithError
	// method before using ServerHTTP method of Error interface.
	BeforeError func(error, http.ResponseWriter, *http.Request)

	// AfterError is the function that will be called by Adapter.WithError
	// method after using ServerHTTP method of Error interface.
	AfterError func(error, http.ResponseWriter, *http.Request)

	// InternalHandler is the function that will be called when
	// Adapter.WithError method will meet error without ServeHTTP method.
	InternalHandler func(error, http.ResponseWriter, *http.Request)

	// WrapInternal is the flag. When set to true: BeforeError and AfterError
	// functions will ba called before and after internal server error
	// handled by InternalHandler function.
	WrapInternal bool
}

AdapterBuilder holds arguments for creating new Adapter.

type Error

type Error interface {
	http.Handler
	error
}

Error interface is the resultant of error and http.Handler interfaces. You can use it to encapsulate error handling logic within error itself.

See github.com/thinkofher/horror/status module for standard http status implementations of Error interface.

type Handler

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

Handler is an alternative to http.Handler. It expands ServerHTTP method by adding error as return value.

You can propagate error value further and eventually wrap it with fmt.Errorf when implementing ServeHTTP method. The logic for handling specific erorrs can be encapsulated in the Error interface.

type HandlerFunc

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

HandlerFunc is an adapter type that wraps function to use it as regular Handler interface.

func (HandlerFunc) ServeHTTP

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