v1.3.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Feb 8, 2019 License: Apache-2.0 Imports: 13 Imported by: 2



Package handler provides the types used to coordinate the processing of a web service request.

The core type in this package is WsHandler. A handler (an instance of WsHandler) must be created for every logical web service endpoint in your application. The behaviour and configuration of handlers is described in detail at http://granitic.io/1.0/ref/web-service-handlers but a brief description follows.

Declaring handlers

A handler is declared in your component definition file like:

  "artistHandler": {
	"type": "handler.WsHandler",
	"HttpMethod": "GET",
	"Logic": "ref:artistLogic",
	"PathPattern": "^/artist/([\\d]+)[/]?$"

  "artistLogic": {
	"type": "inventory.ArtistLogic"

Each handler must have the following before it is considered a valid web service endpoint.

1. A regular expression that will be matched against the path component of incoming HTTP requests.

2. A single HTTP method that it will be responsible for handling. This is generally GET, POST, PUT or DELETE but any standard or custom HTTP method can be used.

3. A 'logic' component that implements at least WsRequestProcessor (additional WsXXX interfaces can be implemented to support advanced behaviour) OR has a method with the signature ProcessPayload(ctx context.Context, request *ws.WsRequest, response *ws.WsResponse, payload *YourStruct)



This section is empty.


This section is empty.


This section is empty.


type ErrorTemplate

type ErrorTemplate interface {
	//ErrorTemplateName returns the unique name of a template to use to render response output.
	ErrorTemplateName() string

Implemented by logic components that need to instruct the web services renderer to use a specific template to render when errors are detected in the response.

type Templated

type Templated interface {
	// TemplateName returns the unique name of a template to use to render response output.
	TemplateName() string

	// UseWhenError returns true if the template returned by TemplateName should be used errors are present in the response.
	UseWhenError() bool

Implemented by logic components that need to instruct the web services renderer to use a specific template to render a response.

type WsHandler

type WsHandler struct {

	// A component able to examine a request and see if the caller is allowed to access this endpoint.
	AccessChecker ws.WsAccessChecker

	// Whether or not the underlying HTTP request and response writer should be made available to request Logic.
	AllowDirectHTTPAccess bool

	// Whether or not query parameters should be automatically injected into the request body.
	AutoBindQuery bool

	// A component able to use a set of user-defined rules to validate a request.
	AutoValidator *validate.RuleValidator

	// A list of field names on the target object into which path parameters (groups in the request regex) should be bound to.
	BindPathParams []string

	// Check caller's permissions after request has been parsed (true) or before parsing (false).
	CheckAccessAfterParse bool

	// A function able to create an empty initialised struct to use as a target for request binding
	CreateTarget ioc.StructFactory

	// If true, do not automatically return an error response if errors are found during the parsing and binding phases of request processing.
	DeferFrameworkErrors bool

	// If true, do not automatically return an error response if errors are found during auto validation.
	DeferAutoErrors bool

	// If true, discard the request's query parameters.
	DisableQueryParsing bool

	// If true, discard any path parameters found by match the request URI against the PathMatchPattern regex.
	DisablePathParsing bool

	// An object that provides access to application defined error messages for use during validation.
	ErrorFinder ws.ServiceErrorFinder

	// A map of fields on the request body object and the names of query parameters that should be used to populate them
	FieldQueryParam map[string]string

	// An object that provides access to built-in error messages to use when an error is found during the automated phases of request processing.
	FrameworkErrors *ws.FrameworkErrorGenerator

	// The HTTP method (GET, POST etc) that this handler supports.
	HttpMethod string

	// A logger injected by the Granitic framework. Note this will be an application logger rather than a framework logger
	// as instances of WsHandler are considered application components.
	Log logging.Logger

	// The object representing the 'logic' behind this handler.
	Logic interface{}

	// A component injected by the Granitic framework that can map text representations of query and path parameters to Go
	// and Granitic types.
	ParamBinder *ws.ParamBinder

	// A regex that will be matched against inbound request paths to check if this handler should be used to service the request.
	PathPattern string

	// A component that might want to modify a response after it has been processed by the supplied Logic component.
	PostProcessor WsPostProcessor

	// A compponent that might want to modify a request after it has been parsed, but before it has been validated.
	PreValidateManipulator WsPreValidateManipulator

	// Stop the framework automatically adding this handler to an HTTP server.
	PreventAutoWiring bool

	// A component injected by the Granitic framework that writes the response from this handler to an HTTP response.
	ResponseWriter ws.WsResponseWriter

	// Whether on not the caller needs to be authenticated (using a ws.WsIdentifier) in order to access the logic behind this handler.
	RequireAuthentication bool

	// A component injected by the Granitic framework that can extract the body of the incoming HTTP request into a Go struct.
	Unmarshaller ws.WsUnmarshaller

	// A component that can examine a request to determine the calling user/service's identity.
	UserIdentifier ws.WsIdentifier

	// A component that can check if this handler supports the version of functionality required by the caller.
	VersionAssessor WsVersionAssessor
	// contains filtered or unexported fields
WsHandler co-ordinates the processing of a web service request for a particular endpoint.

Implements ws.HttpEndpointProvider

func (*WsHandler) AutoWireable

func (wh *WsHandler) AutoWireable() bool

AutoWireable returns true if this handler should be automatically registered with any instances of httpserver.HTTPServer that are running in the application.

func (*WsHandler) ComponentName

func (wh *WsHandler) ComponentName() string

See ComponentNamer.ComponentName

func (*WsHandler) ProvideErrorFinder

func (wh *WsHandler) ProvideErrorFinder(finder ws.ServiceErrorFinder)

ProvideErrorFinder receives a component that can be used to map error codes to categorised errors.

func (*WsHandler) RegexPattern

func (wh *WsHandler) RegexPattern() string

RegexPattern returns the unparsed regex pattern that should be applicaed to the path of incoming requests to see if this handler should handle the request.

func (*WsHandler) ServeHttp added in v1.1.0

ServeHttp is the entry point called by the HTTP server once it has been determined that this handler instance is the correct one to handle the incoming request.

func (*WsHandler) SetComponentName

func (wh *WsHandler) SetComponentName(name string)

See ComponentNamer.SetComponentName

func (*WsHandler) StartComponent

func (wh *WsHandler) StartComponent() error

StartComponent is called by the IoC container. Verifies that the minimum set of fields and components and fields have been set (see top of this GoDoc page) and that the configuration of the handler is valid and consistent.

func (*WsHandler) SupportedHttpMethods

func (wh *WsHandler) SupportedHttpMethods() []string

SupportedHttpMethods returns the HTTP method that this handler supports. Returns an array in order to implement HttpEndpointProvider, but will always be a single element array.

func (*WsHandler) SupportsVersion

func (wh *WsHandler) SupportsVersion(version httpendpoint.RequiredVersion) bool

SupportsVersion returns true if this handler supports the version of functionality requested by the caller. Defers to the component injected into this handler's VersionAssessor field.

func (*WsHandler) VersionAware

func (wh *WsHandler) VersionAware() bool

VersionAware returns true if this handler can be considered when a user requests a specific version of functionality.

type WsPostProcessor

type WsPostProcessor interface {
	//PostProcess may modify the supplied response object if required.
	PostProcess(ctx context.Context, handlerName string, request *ws.WsRequest, response *ws.WsResponse)

Indicates that an object is interested in observing/modifying a web service request after processing has been completed, but before the HTTP response is written. Typical uses are the writing of response headers that are generic to all/most handlers or the recording of metrics.

It is expected that WsPostProcessors may be shared between multiple instances of WsHandler

type WsPreValidateManipulator

type WsPreValidateManipulator interface {
	// PreValidate returns true if the supplied request is in a suitable state for processing to continue.
	PreValidate(ctx context.Context, request *ws.WsRequest, errors *ws.ServiceErrors) (proceed bool)

Indicates that an object is interested in observing/modifying a web service request after it has been unmarshalled and parsed, but before automatic and application-defined validation takes place.

type WsRequestProcessor

type WsRequestProcessor interface {
	// Process performs the actual 'work' of a web service request. The reponse parameter will be modified according to
	// the output or errors that the web service caller should see.
	Process(ctx context.Context, request *ws.WsRequest, response *ws.WsResponse)

Implementing WsRequestProcessor is the minimum required of a component to be considered a 'logic' component suitable for use by a WsHandler.

type WsRequestValidator

type WsRequestValidator interface {
	// Validate will add one or more CategorisedServiceError objects to the supplied errors parameter if the request is not suitable for further processing.
	Validate(ctx context.Context, errors *ws.ServiceErrors, request *ws.WsRequest)

If implemented by the same object that is used as a handler's WsRequestProcessor, the Validate method will be called to determine whether or not a request should proceed to processing.

type WsUnmarshallTarget

type WsUnmarshallTarget interface {
	// UnmarshallTarget returns a pointer to a struct. That struct can be used by the called to parse or map request data (body, query parameters etc) into.
	UnmarshallTarget() interface{}

Implemented by logic components that are able to create target objects for data from a web service request to be parsed into. For example, a web service that supports POST requests will need an object into which the request body can be stored.

type WsVersionAssessor

type WsVersionAssessor interface {
	// SupportsVersion returns true if the named handle is able to support the requested version.
	SupportsVersion(handlerName string, version httpendpoint.RequiredVersion) bool

Indicates that an object can determine whether or not handler supports a given version of a request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL