api

Documentation

Index

• Constants
• func RequestContext(ctx *gin.Context) ladon.Context
• type CtxKey
• type DependencyManager
• type Module
  • func PrefixedModule(prefix string, md Module) Module
• type PropertyError
  • func (p *PropertyError) Error() string
• type Router
  • func NewRouter(options ...RouterOption) (Router, error)
  • func NewRouterWithEngine(e *gin.Engine, options ...RouterOption) (Router, error)
  • func RouterFromContext(ctx context.Context) Router
• type RouterOption
  • func WithLogger(log log.Interface) RouterOption
  • func WithModule(name string, fn SetupModuleFunc) RouterOption
  • func WithPrefixedModule(prefix, name string, fn SetupModuleFunc) RouterOption
  • func WithProvider(name, value interface{}) RouterOption
• type SetupModuleFunc
• type ValidationError
  • func (v *ValidationError) Add(field, message string)
  • func (v *ValidationError) AddForbidden(p string)
  • func (v *ValidationError) AddInvalid(p string)
  • func (v *ValidationError) AddMissing(p string)
  • func (v *ValidationError) AddTaken(p string)
  • func (v *ValidationError) Build() error
  • func (v *ValidationError) Error() string

Constants

const (
	// PropertyMissing should be used when a required request body property is
	// missing
	PropertyMissing = "MISSING"

	// PropertyForbidden should be used when a request property must not be specified
	PropertyForbidden = "FORBIDDEN"

	// PropertyTaken should be used when the value of a request property should be unique
	// it a given scope but is already used
	PropertyTaken = "TAKEN"

	// PropertyInvalid should be used if the format of a request body property is invalid
	PropertyInvalid = "INVALID_FORMAT"
)

Functions

func RequestContext

func RequestContext(ctx *gin.Context) ladon.Context

RequestContext extracts data from a HTTP request that may be valuable when verifying ladon policies

Types

type CtxKey

type CtxKey struct{}

CtxKey is used to associate a Router with a http.Request context

type DependencyManager

type DependencyManager interface {
	// AddProvider adds a new dependecy provider
	AddProvider(name, value interface{})

	// DeleteProvider deletes a dependecy provider
	DeleteProvider(name interface{})
}

DependencyManager allows to manage dependencies The default router implemented by this package always implements the dependency manager interface but has been split to allow easier testing and custom implementations

type Module

type Module struct {
	// Name is the name of the module
	Name string

	// Setup is the setup function called when the module should
	// mount on the Router
	Setup SetupModuleFunc
}

Module is a module mounted and exposed via the router

func PrefixedModule

func PrefixedModule(prefix string, md Module) Module

PrefixedModule returns a Module that is prefixed with the given path

type PropertyError

type PropertyError struct {
	// Field is the name of the property that caused the error
	Field string `json:"field"`

	// Description is the description of the error
	Description string `json:"message"`
}

PropertyError represents an error condition that encountered on a request body property

func (*PropertyError) Error

func (p *PropertyError) Error() string

Error implemenets the error interface

type Router

type Router interface {
	http.Handler

	gin.IRouter

	// GetKey returns a service from the router
	GetKey(name interface{}) interface{}

	// Engine returns the underlying gin.Engine
	Engine() *gin.Engine

	// PrivateOnly returns a gin.HandlerFunc that makes
	// an endpoint private (i.e. only accessible by other micro
	// services)
	PrivateOnly() gin.HandlerFunc

	// Log returns a logging instance
	Log() log.Interface

	// AbortRequest aborts the given HTTP request with status and logs the error
	// message. If status is 0 AbortRequest will try to determine the status
	// code on it's own
	AbortRequest(ctx *gin.Context, status int, err error)
}

Router is the API router that is used by micro-services It basically wraps *gin.Engine with some service/dependency discovery features and utility methods for authn and authz

func NewRouter

func NewRouter(options ...RouterOption) (Router, error)

NewRouter returns a new service API router with a default gin.Engine configuration that includes a logger, recovery and CORS middleware For more control on the actual gin.Engine used by the router use NewRouterWithEngine

func NewRouterWithEngine

func NewRouterWithEngine(e *gin.Engine, options ...RouterOption) (Router, error)

NewRouterWithEngine creates a new router instance using e and with options applied.

func RouterFromContext

func RouterFromContext(ctx context.Context) Router

RouterFromContext returns the router from the given context

type RouterOption

type RouterOption func(Router) error

RouterOption configures a new service router instance

func WithLogger

func WithLogger(log log.Interface) RouterOption

WithLogger configures the logging instance to use

func WithModule

func WithModule(name string, fn SetupModuleFunc) RouterOption

WithModule mounts fn on the routers root scope ("/")

func WithPrefixedModule

func WithPrefixedModule(prefix, name string, fn SetupModuleFunc) RouterOption

WithPrefixedModule mounts fn on the prefix (/{prefix}/)

func WithProvider

func WithProvider(name, value interface{}) RouterOption

WithProvider adds a new dependecy provider to the router The router must implement the DependecyManager interface as well

type SetupModuleFunc

type SetupModuleFunc func(router Router) error

SetupModuleFunc is called for each API module that should be mounted and served via a router instance

type ValidationError

type ValidationError struct {
	// Fields holds all field/property errors
	Fields []*PropertyError `json:"errors"`
}

ValidationError is a common request body validation error

func (*ValidationError) Add

func (v *ValidationError) Add(field, message string)

Add adds a new property validation error to v

func (*ValidationError) AddForbidden

func (v *ValidationError) AddForbidden(p string)

AddForbidden adds a PropertyForbidden error for p

func (*ValidationError) AddInvalid

func (v *ValidationError) AddInvalid(p string)

AddInvalid adds a PropertyInvalid error for p

func (*ValidationError) AddMissing

func (v *ValidationError) AddMissing(p string)

AddMissing adds a PropertyMissing error for p

func (*ValidationError) AddTaken

func (v *ValidationError) AddTaken(p string)

AddTaken adds a PropertyTaken error for p

func (*ValidationError) Build

func (v *ValidationError) Build() error

Build returns v itself if it contains property errors. If no errors have been added nil is returned

func (*ValidationError) Error

func (v *ValidationError) Error() string

Error implements the error interface