check

Documentation

Overview

Package check standardizes /health and /ready endpoints. This allows you to easily know when your server is ready and healthy.

Index

• type Check
  • func NewCheck() *Check
  • func (c *Check) AddHealthCheck(check Checker)
  • func (c *Check) AddReadyCheck(check Checker)
  • func (c *Check) CheckHealth(ctx context.Context) Response
  • func (c *Check) CheckReady(ctx context.Context) Response
  • func (c *Check) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (c *Check) SetPassthrough(h http.Handler)
• type Checker
  • func ErrCheck(fn func() error) Checker
  • func Named(name string, checker Checker) Checker
  • func NamedFunc(name string, fn CheckerFunc) Checker
• type CheckerFunc
  • func (f CheckerFunc) Check(ctx context.Context) Response
• type NamedChecker
• type Response
  • func Error(err error) Response
  • func Info(msg string, args ...interface{}) Response
  • func Pass() Response
  • func (r *Response) HasCheck(name string) bool
• type Responses
  • func (r Responses) Len() int
  • func (r Responses) Less(i, j int) bool
  • func (r Responses) Swap(i, j int)
• type Status

Examples

• Check.CheckHealth
• Check.ServeHTTP
• Check.SetPassthrough
• NewCheck

Types

type Check

type Check struct {
	// contains filtered or unexported fields
}

Check wraps a map of service names to status checkers.

func NewCheck

func NewCheck() *Check

NewCheck returns a Health with a default checker.

Example

// Run the default healthcheck. it always return 200. It is good if you
// have a service without any dependency
h := NewCheck()
h.CheckHealth(context.Background())

func (*Check) AddHealthCheck

func (c *Check) AddHealthCheck(check Checker)

AddHealthCheck adds the check to the list of ready checks. If c is a NamedChecker, the name will be added.

func (*Check) AddReadyCheck

func (c *Check) AddReadyCheck(check Checker)

AddReadyCheck adds the check to the list of ready checks. If c is a NamedChecker, the name will be added.

func (*Check) CheckHealth

func (c *Check) CheckHealth(ctx context.Context) Response

CheckHealth evaluates c's set of health checks and returns a populated Response.

Example

h := NewCheck()
h.AddHealthCheck(Named("google", CheckerFunc(func(ctx context.Context) Response {
	var r net.Resolver
	_, err := r.LookupHost(ctx, "google.com")
	if err != nil {
		return Error(err)
	}
	return Pass()
})))
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
h.CheckHealth(ctx)

func (*Check) CheckReady

func (c *Check) CheckReady(ctx context.Context) Response

CheckReady evaluates c's set of ready checks and returns a populated Response.

func (*Check) ServeHTTP

func (c *Check) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves /ready and /health requests with the respective checks.

Example

c := NewCheck()
http.ListenAndServe(":6060", c)

func (*Check) SetPassthrough

func (c *Check) SetPassthrough(h http.Handler)

SetPassthrough allows you to set a handler to use if the request is not a ready or health check. This can be useful if you intend to use this as a middleware.

Example

c := NewCheck()

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello friends!"))
})

c.SetPassthrough(http.DefaultServeMux)
http.ListenAndServe(":6060", c)

type Checker

type Checker interface {
	Check(ctx context.Context) Response
}

Checker indicates a service whose health can be checked.

func ErrCheck

func ErrCheck(fn func() error) Checker

ErrCheck will create a health checker that executes a function. If the function returns an error, it will return an unhealthy response. Otherwise, it will be as if the Ok function was called. Note: it is better to use CheckFunc, because with Check, the context is ignored.

func Named

func Named(name string, checker Checker) Checker

Named returns a Checker that will attach a name to the Response from the check. This way, it is possible to augment a Response with a human-readable name, but not have to encode that logic in the actual check itself.

func NamedFunc

func NamedFunc(name string, fn CheckerFunc) Checker

NamedFunc is the same as Named except it takes a CheckerFunc.

type CheckerFunc

type CheckerFunc func(ctx context.Context) Response

CheckerFunc is an adapter of a plain func() error to the Checker interface.

func (CheckerFunc) Check

func (f CheckerFunc) Check(ctx context.Context) Response

Check implements Checker.

type NamedChecker

type NamedChecker interface {
	Checker
	CheckName() string
}

NamedChecker is a superset of Checker that also indicates the name of the service. Prefer to implement NamedChecker if your service has a fixed name, as opposed to calling *Health.AddNamed.

type Response

type Response struct {
	Name    string    `json:"name"`
	Status  Status    `json:"status"`
	Message string    `json:"message,omitempty"`
	Checks  Responses `json:"checks,omitempty"`
}

Response is a result of a collection of health checks.

func Error

func Error(err error) Response

Error is a utility function for creating a response from an error message.

func Info

func Info(msg string, args ...interface{}) Response

Info is a utility function to generate a healthy status with a printf message.

func Pass

func Pass() Response

Pass is a utility function to generate a passing status response with the default parameters.

func (*Response) HasCheck

func (r *Response) HasCheck(name string) bool

HasCheck verifies whether the receiving Response has a check with the given name or not.

type Responses

type Responses []Response

Responses is a sortable collection of Response objects.

func (Responses) Len

func (r Responses) Len() int

func (Responses) Less

func (r Responses) Less(i, j int) bool

Less defines the order in which responses are sorted.

Failing responses are always sorted before passing responses. Responses with the same status are then sorted according to the name of the check.

func (Responses) Swap

func (r Responses) Swap(i, j int)

type Status

type Status string

Status string to indicate the overall status of the check.

const (
	// StatusFail indicates a specific check has failed.
	StatusFail Status = "fail"
	// StatusPass indicates a specific check has passed.
	StatusPass Status = "pass"

	// DefaultCheckName is the name of the default checker.
	DefaultCheckName = "internal"
)