chevron

README

Chevron

Chevron is a REST API framework built on top of the concepts brought to you by nacelle. For example usage, see the examples directory.

---

Overview

TODO

License

Copyright (c) 2018 Eric Fritz

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• Variables
• func BootAndExit(name string, initializer RouteInitializer)
• func NewInitializer(initializer RouteInitializer, configs ...RouterConfigFunc) basehttp.ServerInitializer
• type EmptySpec
  • func (es *EmptySpec) Delete(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
  • func (es *EmptySpec) Get(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
  • func (es *EmptySpec) Options(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
  • func (es *EmptySpec) Patch(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
  • func (es *EmptySpec) Post(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
  • func (es *EmptySpec) Put(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response
• type Handler
  • func GetNotImplementedHandler(ctx context.Context) Handler
• type Method
  • func (m Method) String() string
• type Middleware
• type MiddlewareConfigFunc
  • func WithMiddleware(middleware Middleware) MiddlewareConfigFunc
  • func WithMiddlewareFor(middleware Middleware, methods ...Method) MiddlewareConfigFunc
• type MiddlewareFunc
  • func (f MiddlewareFunc) Convert(h Handler) (Handler, error)
• type Resource
• type ResourceSpec
• type RouteInitializer
• type RouteInitializerFunc
  • func (f RouteInitializerFunc) Init(config nacelle.Config, router Router) error
• type Router
  • func NewRouter(services nacelle.ServiceContainer, configs ...RouterConfigFunc) Router
• type RouterConfigFunc
  • func WithLogger(logger nacelle.Logger) RouterConfigFunc
  • func WithNotFoundHandler(handler Handler) RouterConfigFunc
  • func WithNotImplementedHandler(handler Handler) RouterConfigFunc
• type ServerInitializer
  • func (i *ServerInitializer) Init(config nacelle.Config, server *http.Server) error

Variables

var TokenNotImplementedHandler = tokenNotImplementedHandler("chevron.not_implemented_handler")

TokenNotImplementedHandler is the unique token to which the router's not implemented handler is written to the request context.

Functions

func BootAndExit

func BootAndExit(name string, initializer RouteInitializer)

BootAndExit creates a nacelle Bootstrapper with the given name and registers an HTTP server with the given route initializer. This method does not return.

func NewInitializer

func NewInitializer(initializer RouteInitializer, configs ...RouterConfigFunc) basehttp.ServerInitializer

NewInitializer creates a new ServerInitializer.

Types

type EmptySpec

type EmptySpec struct{}

EmptySpec is a complete implementation of ResourceSpec that invokes the router's not implemented handler. A pointer to this struct should be the first embedded field in any resource - this allows a resource to simply "override" the handlers for methods relevant to a resource.

func (*EmptySpec) Delete

func (es *EmptySpec) Delete(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Delete invokes the router's not implemented handler.

func (*EmptySpec) Get

func (es *EmptySpec) Get(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Get invokes the router's not implemented handler.

func (*EmptySpec) Options

func (es *EmptySpec) Options(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Options invokes the router's not implemented handler.

func (*EmptySpec) Patch

func (es *EmptySpec) Patch(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Patch invokes the router's not implemented handler.

func (*EmptySpec) Post

func (es *EmptySpec) Post(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Post invokes the router's not implemented handler.

func (*EmptySpec) Put

func (es *EmptySpec) Put(ctx context.Context, req *http.Request, logger nacelle.Logger) response.Response

Put invokes the router's not implemented handler.

type Handler

type Handler func(context.Context, *http.Request, nacelle.Logger) response.Response

Handler converts an HTTP request into a response object. The handler also has access to a request context populated by the router and registered middleware as well as a request logger which may also be decorated by registered middleware.

func GetNotImplementedHandler

func GetNotImplementedHandler(ctx context.Context) Handler

GetNotImplementedHandler retrieves the router's not implemented handler from the given context. If no handler is registered with this context, the default handler is returned.

type Method

type Method int

Method is an enumeration of HTTP methods.

const (
	// MethodGet represents the GET HTTP method.
	MethodGet Method = iota

	// MethodOptions represents the OPTIONS HTTP method.
	MethodOptions

	// MethodPost represents the POST HTTP method.
	MethodPost

	// MethodPut represents the PUT HTTP method.
	MethodPut

	// MethodPatch represents the PATCH HTTP method.
	MethodPatch

	// MethodDelete represents the DELETE HTTP method.
	MethodDelete
)

func (Method) String

func (m Method) String() string

String returns the uppercased HTTP method name.

type Middleware

type Middleware interface {
	// Convert applies the middleware transformation to a handler. If
	// the middleware is supplied invalid arguments it may return an
	// error at the time of decoration.
	Convert(Handler) (Handler, error)
}

Middleware transforms a handler into another decorated handler.

type MiddlewareConfigFunc

type MiddlewareConfigFunc func(handlerMap) error

MiddlewareConfigFunc is a function that decorates a map from HTTP methods to handlers.

func WithMiddleware

func WithMiddleware(middleware Middleware) MiddlewareConfigFunc

WithMiddleware applies the given middleware to all HTTP methods in the handler map.

func WithMiddlewareFor

func WithMiddlewareFor(middleware Middleware, methods ...Method) MiddlewareConfigFunc

WithMiddlewareFor applies the given middleware to the provided HTTP methods in the handler map.

type MiddlewareFunc

type MiddlewareFunc func(Handler) (Handler, error)

MiddlewareFunc is signature for single-function middleware.

func (MiddlewareFunc) Convert

func (f MiddlewareFunc) Convert(h Handler) (Handler, error)

type Resource

type Resource interface {
	// Handle is invoked when the resource is requested, regardless of the
	// HTTP method.
	Handle(context.Context, *http.Request, nacelle.Logger) response.Response
}

Resource represents an object or behavior accessible from a unique URL pattern.

type ResourceSpec

type ResourceSpec interface {
	// Get is the handler invoked for the GET HTTP method.
	Get(context.Context, *http.Request, nacelle.Logger) response.Response

	// Options is the handler invoked for the OPTIONS HTTP method.
	Options(context.Context, *http.Request, nacelle.Logger) response.Response

	// Post is the handler invoked for the POST HTTP method.
	Post(context.Context, *http.Request, nacelle.Logger) response.Response

	// Put is the handler invoked for the PUT HTTP method.
	Put(context.Context, *http.Request, nacelle.Logger) response.Response

	// Patch is the handler invoked for the PATCH HTTP method.
	Patch(context.Context, *http.Request, nacelle.Logger) response.Response

	// Delete is the handler invoked for the DELETE HTTP method.
	Delete(context.Context, *http.Request, nacelle.Logger) response.Response
}

ResourceSpec represents the set of handlers (one for each HTTP method) to which a resource can respond.

type RouteInitializer

type RouteInitializer interface {
	// Init registers resources and middleware to the router.
	Init(config nacelle.Config, router Router) error
}

RouteInitializer initializes a Router instance.

type RouteInitializerFunc

type RouteInitializerFunc func(config nacelle.Config, router Router) error

RouteInitializerFunc is a function conforming to the RouteInitializer interface.

func (RouteInitializerFunc) Init

func (f RouteInitializerFunc) Init(config nacelle.Config, router Router) error

Init calls the wrapped function.

type Router

type Router interface {
	http.Handler

	// AddMiddleware registers middleware for all resources registered after
	// the invocation of this method.
	AddMiddleware(middleware Middleware)

	// Register creates a resource from the given resource spec and set of
	// middleware instances and registers it to the given URL pattern.
	Register(url string, spec ResourceSpec, configs ...MiddlewareConfigFunc) error

	// MustRegister calls Register and panics on error.
	MustRegister(url string, spec ResourceSpec, configs ...MiddlewareConfigFunc)

	RegisterHandler(url string, handler http.Handler)
}

Router stores

func NewRouter

func NewRouter(services nacelle.ServiceContainer, configs ...RouterConfigFunc) Router

NewRouter creates a new router.

type RouterConfigFunc

type RouterConfigFunc func(*router)

RouterConfigFunc is a function used to initialize a new router.

func WithLogger

func WithLogger(logger nacelle.Logger) RouterConfigFunc

WithLogger sets the router's logger.

func WithNotFoundHandler

func WithNotFoundHandler(handler Handler) RouterConfigFunc

WithNotFoundHandler sets the handler invoked when a requested URL cannot be matched with any registered URL pattern.

func WithNotImplementedHandler

func WithNotImplementedHandler(handler Handler) RouterConfigFunc

WithNotImplementedHandler sets the handler invoked when a resource does not implemented the requested HTTP verb.

type ServerInitializer

type ServerInitializer struct {
	Services nacelle.ServiceContainer `service:"container"`
	Logger   nacelle.Logger           `service:"logger"`
	// contains filtered or unexported fields
}

ServerInitializer implements basehttp.ServerInitializer.

func (*ServerInitializer) Init

func (i *ServerInitializer) Init(config nacelle.Config, server *http.Server) error

Init creates a router which becomes the server's handler and calls the attached route initializer.