tonic

README

🍸 Tonic

What is Tonic?

Tonic is a set of helpers and pre-built endpoints helpful for setting up a Gin based website/API. It's primarily set up to enable quick setup of a web API with cookie and bearer token auth using an OIDC provider.

Tonic is great for quickly getting something up and running, especially if you don't need to adjust how users and permissions are handled. In larger projects it works better as a kind of template where youc an pull useful handlers and services to modify

Technologies in use:

• Gin
• Zerolog: Each request will add a logger to the context which contains pre-populated values
• Mabma: The options are all annotated ready to be supplied directly to mamba

Quick start

1. Install Tonic

go get github.com/scottkgregory/mamba

1. Call tonic.Init

router, authedRouter, logger, err := tonic.Init(cfg.Tonic)
if err != nil {
  panic(err)
}

1. Use the Gin engine and router groups as normal

router.GET("/tonic", func(c *gin.Context) {
  // Calling GetLogger with context will populate the logger with request specific values
  logger := helpers.GetLogger(c)
  logger.Info().Msg("Cheers!")
  c.JSON(http.StatusOK, gin.H{"message": "Hello!"})
})

1. Start the listener

// Get a pre-configured logger
logger := helpers.GetLogger()
logger.Info().Msg("Starting listener")
r.Run(fmt.Sprintf(":%d", cfg.Port))

1. Visit the site, the homepage should show a Tonic default with a log in button. Logging in using your configured provider should insert the user details in to the provided backend and present you with a token.

What's not here?

There are a few things that aren't currently set up how I'd like and may change going forward:

1. More configurable backends, currently defaults to storing user details in mongodb
2. Configuration (or optional removal) of default pages

Documentation

Index

• Constants
• func Authed(backend backends.Backend, cookieOptions *models.CookieOptions, ...) gin.HandlerFunc
• func ErrorResponse(c *gin.Context, code int, err error, validation ...map[string]string)
• func ForbiddenResponse(c *gin.Context, errs ...*ForbiddenErr)
• func GetID(c *gin.Context) (id string)
• func GetLogger(c ...*gin.Context) *zerolog.Logger
• func GetUser(c *gin.Context) (user *pkgModels.User, ok bool)
• func HasAll(required ...string) gin.HandlerFunc
• func HasAny(required ...string) gin.HandlerFunc
• func IDPath(path ...string) string
• func Init(opt models.Options) (*gin.Engine, *gin.RouterGroup, error)
• func NoContentResponse(c *gin.Context)
• func NotFoundResponse(c *gin.Context, errs ...*NotFoundErr)
• func SmartResponse(c *gin.Context, data interface{}, err error)
• func SuccessResponse(c *gin.Context, data interface{})
• func UnauthorisedResponse(c *gin.Context, errs ...*UnauthorisedErr)
• func ValidationErrorResponse(c *gin.Context, errs ...*ValidationErr)
• type AuthOptions
• type BackendOptions
• type CookieOptions
• type ForbiddenErr
  • func NewForbiddenError(required ...string) *ForbiddenErr
• type GenericErr
  • func NewGenericError(err ...error) *GenericErr
• type JWTOptions
• type LogOptions
• type NotFoundErr
  • func NewNotFoundError(id string) *NotFoundErr
• type OIDCOptions
• type Options
• type PermissionsOptions
• type ResponseModel
• type UnauthorisedErr
  • func NewUnauthorisedError() *UnauthorisedErr
• type ValidationErr
  • func NewValidationError(validation ...map[string]string) *ValidationErr

Constants

const GlobalKey = constants.GlobalKey

GlobalKey is a const for global validation errors

Functions

func Authed

func Authed(backend backends.Backend,
	cookieOptions *models.CookieOptions,
	jwtOptions *models.JWTOptions,
	authOptions *models.AuthOptions,
	permissionOptions *models.PermissionsOptions,
	cancel bool) gin.HandlerFunc

Authed is a middleware that requires a user be authenticated. If cancel is set to false the request will be allowed to continue, but tonic.GetUser will return false

func ErrorResponse

func ErrorResponse(c *gin.Context, code int, err error, validation ...map[string]string)

ErrorResponse returns a new ErrorResponse, use at the end of a request

func ForbiddenResponse

func ForbiddenResponse(c *gin.Context, errs ...*ForbiddenErr)

ForbiddenResponse returns a new ForbiddenResponse, use at the end of a request

func GetID

func GetID(c *gin.Context) (id string)

GetID gets the id from the path, setup using tonic.IDPath

func GetLogger

func GetLogger(c ...*gin.Context) *zerolog.Logger

GetLogger returns a zerolog logger with context

func GetUser

func GetUser(c *gin.Context) (user *pkgModels.User, ok bool)

GetUser returns the current user from context

func HasAll

func HasAll(required ...string) gin.HandlerFunc

HasAny is a middleware that requires the user has all of the provided permissions to pass

func HasAny

func HasAny(required ...string) gin.HandlerFunc

HasAny is a middleware that requires the user has any of the provided permissions to pass

func IDPath

func IDPath(path ...string) string

IDPath will add the standard ID param to the given path

func Init

func Init(opt models.Options) (*gin.Engine, *gin.RouterGroup, error)

Init sets up tonic

func NoContentResponse

func NoContentResponse(c *gin.Context)

NoContentResponse returns a new NoContentResponse, use at the end of a request

func NotFoundResponse

func NotFoundResponse(c *gin.Context, errs ...*NotFoundErr)

NotFoundResponse returns a new NotFoundResponse, use at the end of a request

func SmartResponse

func SmartResponse(c *gin.Context, data interface{}, err error)

SmartResponse returns a response object appropriate to the supplied error

func SuccessResponse

func SuccessResponse(c *gin.Context, data interface{})

SuccessResponse returns a new SuccessResponse, use at the end of a request

func UnauthorisedResponse

func UnauthorisedResponse(c *gin.Context, errs ...*UnauthorisedErr)

UnauthorisedResponse returns a new UnauthorisedResponse, use at the end of a request

func ValidationErrorResponse

func ValidationErrorResponse(c *gin.Context, errs ...*ValidationErr)

ValidationErrorResponse returns a new ValidationErrorResponse, use at the end of a request

Types

type AuthOptions

type AuthOptions = models.AuthOptions

type BackendOptions

type BackendOptions = models.BackendOptions

type CookieOptions

type CookieOptions = models.CookieOptions

type ForbiddenErr

type ForbiddenErr = errors.ForbiddenErr

Surface errors

func NewForbiddenError

func NewForbiddenError(required ...string) *ForbiddenErr

NewForbiddenError creates a new ForbiddenErr

type GenericErr

type GenericErr = errors.GenericErr

func NewGenericError

func NewGenericError(err ...error) *GenericErr

NewGenericError creates a new GenericErr

type JWTOptions

type JWTOptions = models.JWTOptions

type LogOptions

type LogOptions = models.LogOptions

type NotFoundErr

type NotFoundErr = errors.NotFoundErr

func NewNotFoundError

func NewNotFoundError(id string) *NotFoundErr

NewNotFoundError creates a new NotFoundErr

type OIDCOptions

type OIDCOptions = models.OIDCOptions

type Options

type Options = models.Options

Surface structs

type PermissionsOptions

type PermissionsOptions = models.PermissionsOptions

type ResponseModel

type ResponseModel = api.ResponseModel

type UnauthorisedErr

type UnauthorisedErr = errors.UnauthorisedErr

func NewUnauthorisedError

func NewUnauthorisedError() *UnauthorisedErr

NewUnauthorisedError creates a new UnauthorisedErr

type ValidationErr

type ValidationErr = errors.ValidationErr

func NewValidationError

func NewValidationError(validation ...map[string]string) *ValidationErr

NewValidationError creates a new ValidationErr