capstan/api.go

package capstan

import (
	"net/http"

	"git.destrealm.org/go/capstan/config"
	"git.destrealm.org/go/capstan/mappers"
	"git.destrealm.org/go/capstan/render"
	"git.destrealm.org/go/capstan/session"
	"git.destrealm.org/go/logging"
	"github.com/gorilla/websocket"
)

type Application interface {
	AttachApplication(Application)
	DestroyApplication(Application)
	Application() *application
	LoadSession()
	BindGroup(path string) *RouterGroup
	Bind(controller Controller) error
	ReplaceController(from, to Controller) error
	ReplacePath(from, to string)
	Unmount(path string)
	UnmountController(controller Controller) error
	UnmountGroup(path string) error
	DefaultMiddleware()
	SetMiddleware(middleware ...func(http.Handler) http.Handler) Application
	SetDefaultRenderer(renderer render.Renderer) Application
	SetMaster(app Application)
	RegisterShutdownHook(hook ShutdownHook)
	Listen() error
	Stop()
	Config() *config.Config
	Dependencies() *mappers.DependencyMapper
	Logger() *logging.Log
	Router() *Router
	Extensions() *ExtensionManager
	Reload(config *config.Config)
}

type Controller interface {
	middleware() Middleware
	name() string
	mandatoryNoSlash() bool
	mandatorySlash() bool
	optionalSlash() bool
	slashIsDefault() bool
	noInterpolation() bool
	path() string
	prefix() string
	index() string
	webSocketPath() string
	upgrader() *websocket.Upgrader
	renderer() render.Renderer
	endpoints() map[string]RouteFlag
	options() BaseController
}

type ConnectHandler interface {
	Connect(Context) error
}

type DeleteHandler interface {
	Delete(Context) error
}

type GetHandler interface {
	Get(Context) error
}

type HeadHandler interface {
	Head(Context) error
}

type OptionsHandler interface {
	Options(Context) error
}

type PostHandler interface {
	Post(Context) error
}

type PutHandler interface {
	Put(Context) error
}

type PatchHandler interface {
	Patch(Context) error
}

type TraceHandler interface {
	Trace(Context) error
}

// Binder controllers are those that wish to implement or handle binding
// themselves. Consequently, a *Router is passed as the Bind() function's sole
// argument such that the controller may use it to interface directly with the
// router instance or may call Router.Mux() to use the muxer directly. If an
// implementation uses the latter, the underlying configured go-chi instance is
// exposed for external management.
type Binder interface {
	Bind(*Router)
}

type IndexHandler interface {
	Index(Context) error
}

// MiddlewareHandler, when implemented, allows controllers to return middleware
// that utilizes attached fields and methods as internal context. This is useful
// if your middleware requires access to a database or other dependencies
// (including injected dependencies).
type MiddlewareHandler interface {
	Middleware() []func(http.Handler) http.Handler
}

type WebSocketHandler interface {
	WebSocket(Context) error
}

// MapperHandler returns a map of a route (map key) and the endpoint + method
// (RouteMap) it should be bound to. MapperHandlers are controllers that define
// their own route-to-endpoint handling routines.
type MapperHandler interface {
	Mapper() map[string]RouteMap
}

type BaseController struct {
	route *Route
	// Middleware defined for this controller.
	Middleware Middleware

	// Name to assign to this controller. Leave empty to automatically deduce
	// the name from the implementing struct.
	Name string

	// Path against which this controller will bind its routes. This may have
	// special meaning for index and other methods (e.g. custom).
	Path string

	// Paths to additionally assign to this controller and its methods. Not
	// currently used.
	Paths map[string][]string

	// Prefix to prepend to the controller's symbolic name. This may be useful
	// for namespacing controller references for reversing the URL in templates.
	Prefix string

	// OptionalSlash indicates the trailing slash is optional. It is usually
	// advised to set this via the Path component.
	OptionalSlash bool

	// Endpoints is a list of custom endpoints attached to this controller.
	Endpoints map[string]RouteFlag

	// MandatoryNoSlash indicates the trailing slash must not be present. It is
	// usually advised to set this via the Path component.
	MandatoryNoSlash bool

	// MandatorySlash indicates the trailing slash is required. It is usually
	// advised to set this via the Path component.
	MandatorySlash bool

	// SlashIsDefault indicates the presence or absence of the trailing slash is
	// the default state. This flag only holds meaning when OptionalSlash is set
	// to true. It is usually advised to set this via the Path component by
	// including a slash followed by a question mark ("/?") to indicate that the
	// slash is optional and the default redirection target.
	SlashIsDefault bool

	// NoInterpolation disables path interpolation and mandates the flags
	// (above) to configure the route slash states. This is useful for routes
	// where the special characters used to communicate slash behavior are
	// required as part of the route and should be accepted as literals.
	NoInterpolation bool

	// WebSocketPath, if set, will attach the WebSocket() method to the
	// specified path underneath the path defined for this controller.
	// Recommended.
	//
	// Leave this blank if your controller is intended strictly for websocket
	// handling.
	WebSocketPath string

	// Upgrader is the configured websocket upgrader via gorilla/websocket. This
	// provides both the configuration details for websocket connections in
	// addition to bound methods for upgrading the connection. If this is nil
	// and the controller implements the WebSocketHandler interface, the default
	// upgrader will be used instead.
	Upgrader *websocket.Upgrader

	// Renderer reference for this controller. This may be unique to each
	// controller or may be set globally via a helper.
	Renderer render.Renderer

	// BeforeResponse bindings specifically used for this controller.
	BeforeResponse []func(Context, *Route) error

	// AfterResponse bindings specifically used for this controller.
	AfterResponse []func(Context, error) error

	// Index path override. This may contain a path component, a single slash
	// indicating the path terminates with this index, a slash followed by a
	// question mark which indicates the slash is optional, or a slash followed
	// by an exclamation point indicating the route must not terminate with a
	// slash.
	Index string

	// Method path overrides.

	// Get overrides the default path for GET requests, appending the path
	// component specified here.
	Get string

	// Post overrides the default path for POST requests, appending the path
	// component specified here.
	Post string

	// Put overrides the default path for PUT requests, appending the path
	// component specified here.
	Put string

	// Patch overrides the default path for PATCH requests, appending the path
	// component specified here.
	Patch string

	// Delete overrides the default path for DELETE requests, appending the path
	// component specified here.
	Delete string

	// Head overrides the default path for HEAD requests, appending the path
	// component specified here.
	Head string
}

func (bc BaseController) middleware() Middleware {
	return bc.Middleware
}

func (bc BaseController) name() string {
	return bc.Name
}

func (bc BaseController) mandatoryNoSlash() bool {
	return bc.MandatoryNoSlash
}

func (bc BaseController) mandatorySlash() bool {
	return bc.MandatorySlash
}

func (bc BaseController) optionalSlash() bool {
	return bc.OptionalSlash
}

func (bc BaseController) slashIsDefault() bool {
	return bc.SlashIsDefault
}

func (bc BaseController) noInterpolation() bool {
	return bc.NoInterpolation
}

func (bc BaseController) path() string {
	return bc.Path
}

func (bc BaseController) prefix() string {
	return bc.Prefix
}

func (bc BaseController) renderer() render.Renderer {
	return bc.Renderer
}

func (bc BaseController) beforeResponseHandlers() []func(Context, *Route) error {
	return bc.BeforeResponse
}

func (bc BaseController) afterResponseHandlers() []func(Context, error) error {
	return bc.AfterResponse
}

func (bc BaseController) webSocketPath() string {
	return bc.WebSocketPath
}

func (bc BaseController) upgrader() *websocket.Upgrader {
	return bc.Upgrader
}

func (bc BaseController) index() string {
	return bc.Index
}

func (bc BaseController) endpoints() map[string]RouteFlag {
	return bc.Endpoints
}

func (bc BaseController) options() BaseController {
	return bc
}

type Context interface {
	Float(string) (float64, error)
	FloatDefault(string, float64) float64
	Int(string) (int64, error)
	IntDefault(string, int64) int64
	Param(string) string
	ParamDefault(string, string) string
	Params(string) []string
	String(string) (string, error)
	StringDefault(string, string) string
	In(interface{}) error
	JSON(interface{}) error
	ParamTypes() map[string]string
	Render(string, interface{}) error
	Renderer() (render.ContextRenderer, error)
	SetRenderer(render.Renderer)
	Headers() http.Header
	Request() *http.Request
	Response() http.ResponseWriter
	RequestContext(key string, value interface{})
	Route() *Route
	SetCookie(*http.Cookie)
	WebSocket() *websocket.Conn
	SetWebSocket(*websocket.Conn)
	Session() session.Session
	URLFor(string) *URLBuilder
	Write([]byte) (int, error)
	WriteHeader(int)
	WriteJSON(interface{}) error
	ContentType(ContentType)
	HasError() error
	Panic(string)
	Error() string
	SetError(error)
	Code() int
	SetCode(int)
}