router

Documentation

Index

• Variables
• func RegisterHandlerArgFactory[T any](factory HandlerArgFactory)
• func RegisterStatefulHandlerArgFactory[T any](factory HandlerArgFactory)
• type Context
  • func NewContext(req Request, res Response) (Context, func(cause error))
  • func NewContextFromStdlib(w http.ResponseWriter, req *http.Request) (Context, func(cause error))
• type Group
  • func NewGroup() Group
• type Handleable
• type Handler
  • func GetHandler(handler interface{}) (Handler, error)
  • func GetOrCreateHandler(handler interface{}) (Handler, error)
  • func NewHandler(handler interface{}) (Handler, error)
• type HandlerArgFactory
• type HandlerFunc
  • func HandlerChain(f HandlerFunc, middleware MiddlewareHandlerFunc) HandlerFunc
• type HandlerIntrospection
• type MiddlewareHandlerFunc
• type Request
  • func NewRequest(req *http.Request) Request
• type Response
  • func NewResponse(res http.ResponseWriter) Response
• type Router

Variables

var (
	// ErrorNotAHandler is returned when an attempt to get a handler from an interface{} failed.
	ErrorNotAHandler = errors.New("given handler value is not of the type router.Handler")
)

Functions

func RegisterHandlerArgFactory

func RegisterHandlerArgFactory[T any](factory HandlerArgFactory)

RegisterHandlerArgFactory will register a factory function for the given generic type which will enable the generic type to be automatically resolved in all handlers.

func RegisterStatefulHandlerArgFactory

func RegisterStatefulHandlerArgFactory[T any](factory HandlerArgFactory)

RegisterStatefulHandlerArgFactory will register a factory function for the given generic type which will enable the generic type to be automatically resolved in all handlers. The factory function will be called only once per request.

Types

type Context

type Context interface {
	// Context embeds the standard context.Context interface
	context.Context

	// Metadata is used to decorate the context with additional data.
	// Useful to provide additional context about the current request.
	// Examples: User, RequestID, Ingress, etc.
	// Metadata is not a data store, use Value and SetValue for that.
	Metadata() structures.Map[string, interface{}]

	// Request returns a wrapper around the standard http.Request object
	// which provides assistive functions.
	//
	// The contained http.Request is the original request object passed to the
	// handler. The request object may be modified or replaced by the middleware chain.
	Request() Request

	// Response returns a wrapper around the response writer which provides
	// assistive functions for writing to the response body.
	//
	// The contained response writer is the original response writer passed to
	// the handler. The response writer may be modified or replaced by the middleware chain.
	Response() Response

	// SetValue modifies the context to contain the given value for the given key
	// This is a replacement for the context.WithValue function, since the type is not retained.
	// The embedded context.Context is kept immutable and gets replaced, never modified.
	SetValue(key any, value any)
}

Context defines the basic feature and dataset of a context A context is a set of data that is passed through the middleware chain and finally the handler. It is used to store data and provide access to the request and response objects.

The context may be extended using a custom context type. The custom context type must implement the Context interface. To use a custom context type, it must be registered using a HandlerArgFactory. See "router.RegisterHandlerArgFactory" and "router.RegisterStatefulHandlerArgFactory" for more information.

func NewContext

func NewContext(req Request, res Response) (Context, func(cause error))

func NewContextFromStdlib

func NewContextFromStdlib(w http.ResponseWriter, req *http.Request) (Context, func(cause error))

type Group

type Group interface {
	// GET will add a route to this route group for the get method
	GET(path string, handler interface{})
	// HEAD will add a route to this route group for the head method
	HEAD(path string, handler interface{})
	// POST will add a route to this route group for the post method
	POST(path string, handler interface{})
	// PUT will add a route to this route group for the put method
	PUT(path string, handler interface{})
	// DELETE will add a route to this route group for the delete method
	DELETE(path string, handler interface{})
	// CONNECT will add a route to this route group for the connect method
	CONNECT(path string, handler interface{})
	// OPTIONS will add a route to this route group for the options method
	OPTIONS(path string, handler interface{})
	// TRACE will add a route to this route group for the trace method
	TRACE(path string, handler interface{})
	// PATCH will add a route to this route group for the patch method
	PATCH(path string, handler interface{})

	// WithMiddleware will add a middleware to the route group
	WithMiddleware(handler interface{})
	// WithRoute will add a new route with the given http method to the router group
	WithRoute(method string, path string, handler interface{})

	// Middleware will return a list of potential middlewares that were registered on this router group
	Middleware() []interface{}

	// ApplyToRouter will attempt to merge all middlewares with the collected route handlers
	// and then attempt to register the routes on the router with a given prefix.
	// Will return an error if any of the steps throw an error
	ApplyToRouter(router Router, prefix string) error
}

Router defines the minimal surface of a router group compatible with this package

func NewGroup

func NewGroup() Group

type Handleable

type Handleable interface {
	ToHandler() interface{}
}

Handleable defines the interface for a structure that can be used to create a handler

type Handler

type Handler interface {
	// AddMiddleware adds a middleware into the chain
	AddMiddleware(middleware interface{}) error

	// Introspection will return the introspected information about the handler
	Introspection() HandlerIntrospection

	// HandlerFunc will generate the original handlers function
	// without any chained middlewares
	HandlerFunc() HandlerFunc

	// Serve is the handler func that executes the handler and all the middlewares
	Serve(ctx Context) error

	// Value returns the reflection value of the handler func
	Value() reflect.Value
}

Handler defines a mojito handler

func GetHandler

func GetHandler(handler interface{}) (Handler, error)

GetHandler will try to cast the given value into a handler, but will fail if the value is not of type (*)mojito.Handler

func GetOrCreateHandler

func GetOrCreateHandler(handler interface{}) (Handler, error)

func NewHandler

func NewHandler(handler interface{}) (Handler, error)

NewHandler will introspect the given handler and, if valid, return a new handler instance that can serve a route

type HandlerArgFactory

type HandlerArgFactory func(ctx Context, next HandlerFunc) (reflect.Value, error)

HandlerArgFactory defines the signature of handler argument factories

type HandlerFunc

type HandlerFunc func(ctx Context) error

HandlerFunc describes the method signature of a mojito handler function that can process an incoming mojito.Requests. A handler func masks all middleware and dependency injection behind a simple, easy to use interface

func HandlerChain

func HandlerChain(f HandlerFunc, middleware MiddlewareHandlerFunc) HandlerFunc

HandlerChain will chain a handler func and a middleware together to form a new, single handler func

type HandlerIntrospection

type HandlerIntrospection interface {
	introspector.IntrospectorResult[HandlerArgFactory]

	// CanError returns true when the handler func is returning error
	CanError() bool

	// IsStdlibMiddleware returns true when the handler func is a stdlib middleware
	IsStdlibMiddleware() bool
}

HandlerIntrospection is a structure that contains all introspected details about a (potential) handler

type MiddlewareHandlerFunc

type MiddlewareHandlerFunc func(ctx Context, next interface{}) error

MiddlewareHandlerFunc is a special kind of HandlerFunc, that receives the next handler in line as its third parameter.

type Request

type Request interface {
	// GetRequest returns the underlying http.Request object
	GetRequest() *http.Request

	// Request replaces the underlying http.Request object
	SetRequest(req *http.Request)

	// Body returns a copy of the request body
	Body() ([]byte, error)

	// Header returns the first value for the given header name
	Header(name string) string

	// Param returns the route parameter or empty string if not found
	Param(name string) string

	// ParamOrDefault returns the route parameter or a custom default if not found
	ParamOrDefault(name string, def string) string

	// SetParams will set the routep params for this request
	SetParams(params map[string]string)

	// ParseString returns the request body as a string
	ParseString() (string, error)

	// ParseJSON will attempt to parse the request body as JSON
	ParseJSON(obj interface{}) error

	// ParseXML will attempt to parse the request body as XML
	ParseXML(obj interface{}) error

	// HasContentType determines whether a request has a given mime type as its content type
	HasContentType(mimetype string) bool
}

func NewRequest

func NewRequest(req *http.Request) Request

NewRequest will create a new instance of a mojito request for the given http.Request object

type Response

type Response interface {
	http.ResponseWriter

	// GetWriter returns the underlying response writer instance
	GetWriter() http.ResponseWriter

	// SetWriter replaces the underlying response writer instance
	SetWriter(res http.ResponseWriter)

	// WriteJSON writes any object to the response body as JSON
	WriteJSON(body interface{}, pretty bool) error

	// WriteString will write a string to the response body
	WriteString(str string) error
}

func NewResponse

func NewResponse(res http.ResponseWriter) Response

NewResponse will create a new instance of a mojito response for the given http.ResponseWriter object

type Router

type Router interface {
	// WithGroup will create a new route group for the given prefix
	WithGroup(prefix string, callback func(group Group)) error
	// WithRoute will add a new route with the given RouteMethod to the router
	WithRoute(method string, path string, handler interface{}) error

	// WithNotFound will set the not found handler for the router
	WithNotFoundHandler(handler interface{}) error
	// WithMethodNotAllowedHandler will set the not allowed handler for the router
	WithMethodNotAllowedHandler(handler interface{}) error
	// WithErrorHandler will set the error handler for the router
	WithErrorHandler(handler interface{}) error
	// WithMiddleware will add a middleware to the router
	WithMiddleware(handler interface{}) error

	// ListenAndServe will start an HTTP webserver on the given address
	ListenAndServe(address string) error
	// ListenAndServeTLS will start an HTTP/S webserver on the given address
	ListenAndServeTLS(address string, certFile string, keyFile string) error
	// Shutdown will gracefully shutdown the router
	Shutdown() error
}

Router defines the minimal surface of a router compatible with this package