handlers

Documentation

Overview

The handlers package contains tools for building pipelines of handlers which requests are run through in order to properly respond to requests.

While the main goweb package wraps most of this functionality, the handlers package allows for more advanced use cases, such as:

• When you want to write your own Handler implementations
• When you want multiple HttpHandlers within the same project
• When you want to build your own MatcherFuncs to enable you to be more selective about when to handler specific requests

Index

• Constants
• Variables
• type DefaultErrorHandler
  • func (h *DefaultErrorHandler) Handle(ctx context.Context) (stop bool, err error)
  • func (h *DefaultErrorHandler) WillHandle(context.Context) (bool, error)
• type Handler
• type HandlerError
  • func (e HandlerError) Error() string
• type HandlerExecutionFunc
• type HttpHandler
  • func NewHttpHandler(codecService codecsservices.CodecService) *HttpHandler
  • func (h *HttpHandler) AppendHandler(handler Handler)
  • func (h *HttpHandler) AppendPostHandler(handler Handler)
  • func (h *HttpHandler) AppendPreHandler(handler Handler)
  • func (handler *HttpHandler) CodecService() codecsservices.CodecService
  • func (h *HttpHandler) ErrorHandler() Handler
  • func (h *HttpHandler) HandlersPipe() Pipe
  • func (h *HttpHandler) Map(options ...interface{}) (Handler, error)
  • func (h *HttpHandler) MapAfter(options ...interface{}) (Handler, error)
  • func (h *HttpHandler) MapBefore(options ...interface{}) (Handler, error)
  • func (h *HttpHandler) MapController(options ...interface{}) error
  • func (h *HttpHandler) MapStatic(publicPath, systemPath string, matcherFuncs ...MatcherFunc) (Handler, error)
  • func (h *HttpHandler) MapStaticFile(publicPath, staticFilePath string, matcherFuncs ...MatcherFunc) (Handler, error)
  • func (h *HttpHandler) PostHandlersPipe() Pipe
  • func (h *HttpHandler) PreHandlersPipe() Pipe
  • func (h *HttpHandler) PrependPostHandler(handler Handler)
  • func (h *HttpHandler) PrependPreHandler(handler Handler)
  • func (handler *HttpHandler) ServeHTTP(responseWriter http.ResponseWriter, request *http.Request)
  • func (h *HttpHandler) SetErrorHandler(errorHandler Handler)
  • func (h *HttpHandler) String() string
• type MatcherFunc
  • func RegexPath(regexpPattern string) MatcherFunc
• type MatcherFuncDecision
• type PathMatchHandler
  • func NewPathMatchHandler(pathPattern *paths.PathPattern, executionFunc HandlerExecutionFunc) *PathMatchHandler
  • func (p *PathMatchHandler) Handle(c context.Context) (bool, error)
  • func (p *PathMatchHandler) String() string
  • func (p *PathMatchHandler) WillHandle(c context.Context) (bool, error)
• type Pipe
  • func (p Pipe) AppendHandler(handler Handler) Pipe
  • func (p Pipe) Handle(c context.Context) (bool, error)
  • func (p Pipe) PrependHandler(handler Handler) Pipe
  • func (p Pipe) WillHandle(context.Context) (bool, error)

Constants

const (
	// DataKeyForError is the data key (that goes into the context.Data map) for
	// an error that has occurred.  Then, the error Handler can Get(DataKeyForError)
	// to do work on the error.
	DataKeyForError string = "error"
)

Variables

var (
	// RestfulIDParameterName is the name Goweb will use when mapping the ID
	// parameter in RESTful mappings.
	//
	//     ctx.PathParam(RestfulIDParameterName)
	//
	// By default, "id" is used.
	//
	// To specify you own, change this value before mapping your
	// controllers.
	//
	//     handlers.RestfulIDParameterName = "resourceId"
	//
	RestfulIDParameterName string = "id"
)

Types

type DefaultErrorHandler

type DefaultErrorHandler struct{}

DefaultErrorHandler is a Handler that writes an error message out to the client.

The error will be stored in the context.Data with the DataKeyForError key.

func (*DefaultErrorHandler) Handle

func (h *DefaultErrorHandler) Handle(ctx context.Context) (stop bool, err error)

Handle writes the error from the context into the HttpResponseWriter with a 500 http.StatusInternalServerError status code.

func (*DefaultErrorHandler) WillHandle

func (h *DefaultErrorHandler) WillHandle(context.Context) (bool, error)

WillHandle is ignored on ErrorHandlers.

type Handler

type Handler interface {

	// WillHandle gets whether this handler will have its Handle method
	// called for the specified Context or not.
	WillHandle(context.Context) (bool, error)

	// Handle tells the handler to do its work.
	//
	// If stop is returned as true, no more handlers in the current pipeline
	// will be executed.
	//
	// If an error is returned, it will be handed to the HttpHandler.ErrorHandler
	// to deal with.  Ideally, you should implement your own custom error handling
	// mechanism instead of returning errors, and use that for system errors.
	Handle(context.Context) (stop bool, err error)
}

Handler represents an object capable of handling a request.

type HandlerError

type HandlerError struct {
	// Handler is the Handler that returned the error.
	Handler Handler
	// OriginalError is the error returned by the Handler.
	OriginalError error
}

HandlerError represents an error that was thrown by a particular Handler.

func (HandlerError) Error

func (e HandlerError) Error() string

Error gets the error string from the OriginalError.

type HandlerExecutionFunc

type HandlerExecutionFunc func(context.Context) error

HandlerExecutionFunc represents a function that can handle requests.

type HttpHandler

type HttpHandler struct {

	// Handlers represent a pipe of handlers that will be used
	// to handle requests.
	Handlers Pipe

	// Data contains the initial data object that gets copied to each
	// context object.
	Data objx.Map

	// HttpMethodForCreate is the HTTP method to use for this action when mapping controllers.
	HttpMethodForCreate string
	// HttpMethodForReadOne is the HTTP method to use for this action when mapping controllers.
	HttpMethodForReadOne string
	// HttpMethodForReadMany is the HTTP method to use for this action when mapping controllers.
	HttpMethodForReadMany string
	// HttpMethodForDeleteOne is the HTTP method to use for this action when mapping controllers.
	HttpMethodForDeleteOne string
	// HttpMethodForDeleteMany is the HTTP method to use for this action when mapping controllers.
	HttpMethodForDeleteMany string
	// HttpMethodForUpdateOne is the HTTP method to use for this action when mapping controllers.
	HttpMethodForUpdateOne string
	// HttpMethodForUpdateMany is the HTTP method to use for this action when mapping controllers.
	HttpMethodForUpdateMany string
	// HttpMethodForReplace is the HTTP method to use for this action when mapping controllers.
	HttpMethodForReplace string
	// HttpMethodForHead is the HTTP method to use for this action when mapping controllers.
	HttpMethodForHead string
	// HttpMethodForOptions is the HTTP method to use for this action when mapping controllers.
	HttpMethodForOptions string
	// contains filtered or unexported fields
}

func NewHttpHandler

func NewHttpHandler(codecService codecsservices.CodecService) *HttpHandler

NewHttpHandler creates a new HttpHandler obejct with the specified CodecService.

New HttpHandlers will be initialised with three handler Pipes:

0 - Pre handlers
1 - Main handlers
2 - Post handlers

func (*HttpHandler) AppendHandler

func (h *HttpHandler) AppendHandler(handler Handler)

AppendHandler appends a handler to the processing pipe.

func (*HttpHandler) AppendPostHandler

func (h *HttpHandler) AppendPostHandler(handler Handler)

AppendPostHandler appends a handler to be executed after processing completes.

func (*HttpHandler) AppendPreHandler

func (h *HttpHandler) AppendPreHandler(handler Handler)

AppendPreHandler appends a handler to be executed before processing begins.

func (*HttpHandler) CodecService

func (handler *HttpHandler) CodecService() codecsservices.CodecService

CodecService gets the codec service that this HttpHandler will use to marshal and unmarshal objects to and from data.

func (*HttpHandler) ErrorHandler

func (h *HttpHandler) ErrorHandler() Handler

ErrorHandler gets the Handler that will be used to handle errors.

If no error handler has been set, a default error handler will be returned which will just write the error out in plain text. If you are building an API, it is recommended that you roll your own ErrorHandler.

For more information on rolling your own ErrorHandler, see the SetErrorHandler method.

func (*HttpHandler) HandlersPipe

func (h *HttpHandler) HandlersPipe() Pipe

HandlersPipe gets the pipe for handlers.

func (*HttpHandler) Map

func (h *HttpHandler) Map(options ...interface{}) (Handler, error)

Map maps a handler function to a specified path and optional HTTP method.

For usage information, see goweb.Map.

func (*HttpHandler) MapAfter

func (h *HttpHandler) MapAfter(options ...interface{}) (Handler, error)

Map maps a handler function to a specified path and optional HTTP method to be executed after any other handlers.

For usage information, see goweb.Map.

func (*HttpHandler) MapBefore

func (h *HttpHandler) MapBefore(options ...interface{}) (Handler, error)

Map maps a handler function to a specified path and optional HTTP method to be executed before any other handlers.

For usage information, see goweb.Map.

func (*HttpHandler) MapController

func (h *HttpHandler) MapController(options ...interface{}) error

MapController maps a controller to a specified path prefix.

For more information, see goweb.MapController.

func (*HttpHandler) MapStatic

func (h *HttpHandler) MapStatic(publicPath, systemPath string, matcherFuncs ...MatcherFunc) (Handler, error)

MapStatic maps static files from the specified systemPath to the specified publicPath.

goweb.MapStatic("/static", "/location/on/system/to/files")

func (*HttpHandler) MapStaticFile

func (h *HttpHandler) MapStaticFile(publicPath, staticFilePath string, matcherFuncs ...MatcherFunc) (Handler, error)

MapStaticFile maps a static file from the specified staticFilePath to the specified publicPath.

goweb.MapStaticFile("favicon.ico", "/location/on/system/to/icons/favicon.ico")

func (*HttpHandler) PostHandlersPipe

func (h *HttpHandler) PostHandlersPipe() Pipe

PostHandlersPipe gets the handlers that are executed after processing completes.

func (*HttpHandler) PreHandlersPipe

func (h *HttpHandler) PreHandlersPipe() Pipe

PreHandlersPipe gets the handlers that are executed before processing begins.

func (*HttpHandler) PrependPostHandler

func (h *HttpHandler) PrependPostHandler(handler Handler)

PrependPostHandler prepends a handler to be executed after processing completes.

func (*HttpHandler) PrependPreHandler

func (h *HttpHandler) PrependPreHandler(handler Handler)

PrepentPreHandler prepends a handler to be executed before processing begins.

func (*HttpHandler) ServeHTTP

func (handler *HttpHandler) ServeHTTP(responseWriter http.ResponseWriter, request *http.Request)

ServeHTTP servers the actual HTTP request by buidling a context and running it through all the handlers.

func (*HttpHandler) SetErrorHandler

func (h *HttpHandler) SetErrorHandler(errorHandler Handler)

SetErrorHandler sets the Handler that will be used to handle errors.

The error handler is like a normal Handler, except with a few oddities. The WillHandle method never gets called on the ErrorHandler, and any errors returned from the Handle method are ignored (as is the stop argument). If you want to log errors, you should do so from within the ErrorHandler.

Goweb will place the error object into the context.Data() map with the DataKeyForError key.

func (*HttpHandler) String

func (h *HttpHandler) String() string

String generates a list of the handlers registered inside this HttpHandler.

type MatcherFunc

type MatcherFunc func(context.Context) (MatcherFuncDecision, error)

MatcherFunc is a function capable of helping PathMatchHandlers decide whether it should handle a specific context. While the path is matched automatically, MatcherFuncs allow you to specify additional checks or constraints.

func RegexPath

func RegexPath(regexpPattern string) MatcherFunc

RegexPath returns a MatcherFunc that mathces the path based on the specified Regex pattern.

For more information, see the goweb.RegexPath shortcut function.

type MatcherFuncDecision

type MatcherFuncDecision int8

MatcherFuncDecision is the return type of MatcherFunc and should be one of, DontCare, NoMatch or Match.

const (
	// Indicates that the MatcherFunc does not have an opinion about whether this
	// matches or not, and it will leave it to other MatcherFuncs (or the PathPattern)
	// to decide.
	DontCare MatcherFuncDecision = -1

	// NoMatch indicates that the handler does not match.
	NoMatch MatcherFuncDecision = 0

	// Match indicates that the handler does match and should handle the Context.
	Match MatcherFuncDecision = 1
)

type PathMatchHandler

type PathMatchHandler struct {

	// PathPattern is the pattern which paths must match in order for this
	// object to handle the context.
	PathPattern *paths.PathPattern

	// ExecutionFunc is the function that will be executed if there is a successful
	// match.
	ExecutionFunc HandlerExecutionFunc

	// MatcherFuncs are additional functions that are each consulted until a decision is
	// made as to whether this object will handle the context or not.
	MatcherFuncs []MatcherFunc

	// HttpMethods contains a list of HTTP Methods that will match, or an empty list if all
	// methods match.
	HttpMethods []string

	// Description is an optional string that describes the mapping.  If present, it will
	// be returned instead of the default when String() is called.
	Description string

	// BreakCurrentPipeline indicates whether the rest of the handlers in the Pipe
	// should be skipped once this handler has done its work.
	//
	// Usually for the main pipe, these handlers will skip as they are responsible
	// for actually returning a response to the clients.
	//
	// In Before and After handlers however, the likelihood is that all handlers
	// in the pipe will want to do something without being skipped.
	//
	// goweb.Map will set this value to true, whereas goweb.MapBefore and goweb.MapAfter
	// will set it to false.
	BreakCurrentPipeline bool
}

PathMatchHandler is a Handler that maps a path to handler code.

func NewPathMatchHandler

func NewPathMatchHandler(pathPattern *paths.PathPattern, executionFunc HandlerExecutionFunc) *PathMatchHandler

NewPathMatchHandler makes a new PathMatchHandler with the specified PathPattern and HandlerExecutionFunc.

func (*PathMatchHandler) Handle

func (p *PathMatchHandler) Handle(c context.Context) (bool, error)

Handle gives each sub handle the opportinuty to handle the context.

func (*PathMatchHandler) String

func (p *PathMatchHandler) String() string

String gets a human readable string describing this PathMatchHandler.

func (*PathMatchHandler) WillHandle

func (p *PathMatchHandler) WillHandle(c context.Context) (bool, error)

WillHandle checks whether this handler will be used to handle the specified request or not.

type Pipe

type Pipe []Handler

Pipe represents a collection of handlers.

func (Pipe) AppendHandler

func (p Pipe) AppendHandler(handler Handler) Pipe

AppendHandler adds a handler to the end of this pipe. Returns a copy of the Pipe with the specified handler appended.

func (Pipe) Handle

func (p Pipe) Handle(c context.Context) (bool, error)

Handle gives each sub handle the opportinuty to handle the context.

func (Pipe) PrependHandler

func (p Pipe) PrependHandler(handler Handler) Pipe

PrependHandler adds a handler to the start of this pipe. Returns a copy of the Pipe with the specified handler prepended.

func (Pipe) WillHandle

func (p Pipe) WillHandle(context.Context) (bool, error)

WillHandle always return true for Pipes.