status

README

Package Status

This package help to manage status router in a API to respond a standard response for status of API and his component. This package requires golib/router + go Gin Tonic API Framework.

Example of implementation

We will work on an example of file/folder tree like this :

/
  bin/
    api/
      config/
      routers/
        status/
          get.go

in the get.go file, we will implement the status package call :

package status

import (
    "github.com/gin-gonic/gin"
    "github.com/nabbar/golib/status"
    "github.com/nabbar/golib/version"
    "net/http"
)

const (
	msgOk = "API is working"
	msgKO = "API is not working"
	msgWarn = "something is not well working"
)

type EmptyStruct struct{}

var vers version.Version

func init() {
    // optional, get or create a new version interface
    vers = version.NewVersion(version.License_MIT, "Package", "Description", "2017-10-21T00:00:00+0200", "0123456789abcdef", "v0.0-dev", "Author Name", "pfx", EmptyStruct{}, 1)

    // to create new status, you will need some small function to give data, this is type func : 
    // FctHealth        func() error
    // FctInfo          func() (name, release, build string)

    // create new status not as later
    sts := status.NewVersion(vers, msgOk, msgKO, msgWarn)

	// add some middleware before router
	sts.MiddlewareAdd(func(context *gin.Context) {
	    // add here your middleware need to be run before the status route
	})

    // register to the router list
	sts.Register("/status", routers.RouterList.Register)

    // register to the router list with a group
	sts.Register("/v1", "/status", routers.RouterList.Register)

    // add a new component mandatory
	sts.ComponentNew(
	    "myComponentMandatory",
	    NewComponent(true, infoMandatory, healthMandatory,
	        func() (msgOk string, msgKo string) {
                return msgOk, msgKO
	        },
	        24 * time.Hour, 5 * time.second,
        ),
    )

    // add a new component mandatory
	sts.ComponentNew(
	    "myComponentNotMandatory",
	    NewComponent(true, infoNotMandatory, healthNotMandatory,
	        func() (msgOk string, msgKo string) {
                return msgOk, msgKO
	        },
	        24 * time.Hour, 5 * time.second,
        ),
    )

    // use this func to customize return code for each status
    sts.SetErrorCode(http.StatusOK, http.StatusInternalServerError, http.StatusAccepted)
}

func GetHealth() error {
    // any function to return check global API is up or not 
    return nil
}

func GetHeader(c *gin.Context) {
    // any function to return global & generic header (like CSP, HSTS, ...)
}

func GetAWSHealth() error {
    // any function to return the check of the component AWS is up or not 
    return nil
}

func GetLDAPHealth() error {
    // any function to return the check of the component LDAP is up or not 
    return nil
}

func infoMandatory() (name, release, build string) {
	return "Name of my component mandatory", "v0.1.2.3.4", "abcd1234abcd1234"
}

func healthMandatory() error {
	return nil
}

func infoNotMandatory() (name, release, build string) {
	return "Name of my component not mandatory", "v0.1.2.3.4", "abcd1234abcd1234"
}

func healthNotMandatory() error {
	return nil
}

In some case, using init function could make mistake (specially if you need to read flag or config file). In this case, you will have func "Later" to allow the init package on first call of status router.

Documentation

Index

• Constants
• func DefaultConfig(indent string) []byte
• func RegisterFlag(prefix string, Command *spfcbr.Command, Viper *spfvpr.Viper) error
• type Component
  • func NewComponent(mandatory bool, info FctInfo, health FctHealth, msg FctMessage, ...) Component
• type ConfigStatus
  • func (c *ConfigStatus) Component(fctInfo FctInfo, fctHealth FctHealth) Component
  • func (c *ConfigStatus) RegisterStatus(sts RouteStatus, key string, fctInfo FctInfo, fctHealth FctHealth)
• type CptResponse
• type FctHealth
• type FctInfo
• type FctMessage
• type Info
  • func NewInfo(fct FctInfo, mandatory bool, cacheDuration time.Duration) Info
• type InfoResponse
  • func (i *InfoResponse) Clone() InfoResponse
• type Response
  • func (r Response) IsOk() bool
  • func (r Response) IsOkMandatory() bool
• type RouteStatus
  • func New(Name string, Release string, Hash string, msgOk string, msgKo string, ...) RouteStatus
  • func NewVersion(version libver.Version, msgOk string, msgKO string, msgWarm string) RouteStatus
• type Status
  • func NewStatus(health FctHealth, msg FctMessage, cacheDuration time.Duration) Status
• type StatusResponse
  • func (s *StatusResponse) Clone() StatusResponse

Constants

const DefMessageKO = "KO"

const DefMessageOK = "OK"

Functions

func DefaultConfig

func DefaultConfig(indent string) []byte

func RegisterFlag

func RegisterFlag(prefix string, Command *spfcbr.Command, Viper *spfvpr.Viper) error

Types

type Component

type Component interface {
	Get(x *gin.Context) CptResponse
	Clean()
}

func NewComponent

func NewComponent(mandatory bool, info FctInfo, health FctHealth, msg FctMessage, infoCacheDuration, statusCacheDuration time.Duration) Component

type ConfigStatus

type ConfigStatus struct {
	// Mandatory define if the component must be available for the api.
	// If yes, api status will be KO if this component is down.
	// If no, api status can be OK if this component is down.
	Mandatory bool `json:"mandatory" yaml:"mandatory" toml:"mandatory" mapstructure:"mandatory"`

	// MessageOK define the message if the status is OK. Default is "OK"
	MessageOK string `json:"message_ok" yaml:"message_ok" toml:"message_ok" mapstructure:"message_ok" validate:"printascii"`

	// MessageKO define the message if the status is KO. Default is "KO"
	MessageKO string `json:"message_ko" yaml:"message_ko" toml:"message_ko" mapstructure:"message_ko" validate:"printascii"`

	// CacheTimeoutInfo define the time between checking the component information (name, release, ...), to prevent asking it too many. Default is 1 hour.
	CacheTimeoutInfo time.Duration `json:"cache_timeout_info" yaml:"cache_timeout_info" toml:"cache_timeout_info" mapstructure:"cache_timeout_info"`

	// CacheTimeoutHealth define the time between checking the component health to prevent asking it too many. Default is 5 second.
	CacheTimeoutHealth time.Duration `json:"cache_timeout_health" yaml:"cache_timeout_health" toml:"cache_timeout_health" mapstructure:"cache_timeout_health"`
}

func (*ConfigStatus) Component

func (c *ConfigStatus) Component(fctInfo FctInfo, fctHealth FctHealth) Component

func (*ConfigStatus) RegisterStatus

func (c *ConfigStatus) RegisterStatus(sts RouteStatus, key string, fctInfo FctInfo, fctHealth FctHealth)

type CptResponse

type CptResponse struct {
	InfoResponse
	StatusResponse
}

type FctHealth

type FctHealth func() error

type FctInfo

type FctInfo func() (name string, release string, build string)

type FctMessage

type FctMessage func() (msgOk string, msgKO string)

type Info

type Info interface {
	Get(x *gin.Context) InfoResponse
	Clean()
	IsValid() bool
}

func NewInfo

func NewInfo(fct FctInfo, mandatory bool, cacheDuration time.Duration) Info

type InfoResponse

type InfoResponse struct {
	Name      string `json:"name"`
	Release   string `json:"release"`
	HashBuild string `json:"hash_build"`
	Mandatory bool   `json:"mandatory"`
}

func (*InfoResponse) Clone

func (i *InfoResponse) Clone() InfoResponse

type Response

type Response struct {
	InfoResponse
	StatusResponse

	Components []CptResponse `json:"components"`
	// contains filtered or unexported fields
}

func (Response) IsOk

func (r Response) IsOk() bool

func (Response) IsOkMandatory

func (r Response) IsOkMandatory() bool

type RouteStatus

type RouteStatus interface {
	MiddlewareAdd(mdw ...gin.HandlerFunc)
	HttpStatusCode(codeOk, codeKO, codeWarning int)

	Get(c *gin.Context)
	Register(prefix string, register librtr.RegisterRouter)
	RegisterGroup(group, prefix string, register librtr.RegisterRouterInGroup)

	ComponentNew(key string, cpt Component)
	ComponentDel(key string)
	ComponentDelAll(containKey string)
}

func New

func New(Name string, Release string, Hash string, msgOk string, msgKo string, msgWarm string) RouteStatus

func NewVersion

func NewVersion(version libver.Version, msgOk string, msgKO string, msgWarm string) RouteStatus

type Status

type Status interface {
	Get(x *gin.Context) StatusResponse
	Clean()
	IsValid() bool
}

func NewStatus

func NewStatus(health FctHealth, msg FctMessage, cacheDuration time.Duration) Status

type StatusResponse

type StatusResponse struct {
	Status  string `json:"status"`
	Message string `json:"message"`
}

func (*StatusResponse) Clone

func (s *StatusResponse) Clone() StatusResponse