healthchecks

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 29, 2021 License: BSD-3-Clause Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// DefaultManagementEndpoint is Healthchecks.io's v1 management endpoint.
	DefaultManagementEndpoint = "https://healthchecks.io/api/v1/"

	// ErrInvalidKey will be returned if the supplied API key is not valid.
	//
	// If you come across one of these, make sure the supplied API key is valid.
	ErrInvalidKey = errors.New("invalid api key")

	// ErrStatusBadRequest will be returned if the response to a HTTP request
	// made to `HealthchecksAPI.endpoint` returns a 400 response.
	//
	// A 400 response should only be caused by the package itself, never by the
	// wrongful use of a program using this package. If you come across one of
	// these, please raise an issue to the developer team.
	ErrStatusBadRequest = errors.New("bad request")

	// ErrStatusUnauthorized will be returned if the response to a HTTP request
	// made to `HealthchecksAPI.endpoint` returns a 401 response.
	//
	// A 401 response is typically caused by configuring an invalid API key.
	// If you see one of these, make sure there is an API key, and it is valid.
	ErrStatusUnauthorized = errors.New("unauthorized")

	// ErrStatusForbidden will be returned if the response to a HTTP request
	// made to `HealthchecksAPI.endpoint` returns a 403 response.
	//
	// A 403 response is typically caused by configuring an invalid API key.
	// If you see one of these, make sure the API key is valid, and if you are
	// making write operations onto the Healthchecks API, ensure it is not a
	// read-only key.
	ErrStatusForbidden = errors.New("forbidden")

	// ErrStatusNotFound will be returned if the response to a HTTP request
	// made to `HealthchecksAPI.endpoint` returns a 404 response.
	//
	// A 404 response is typically caused by accessing an unexistent resource.
	// If you come across one of these, ensure all references to resources (such
	// as UUIDs and names) are to resources that do exist.
	ErrStatusNotFound = errors.New("not found")

	// ErrStatus4xx will be returned if the response to a HTTP request made to
	// `HealthchecksAPI.endpoint` returns a 4xx response.
	// ErrStatus5xx will be returned if the response to a HTTP request made to
	// `HealthchecksAPI.endpoint` returns a 5xx response.
	//
	// A 4xx or 5xx response not listed above should not be returned according
	// to Healthchecks' API reference, but is, nonetheless, possible.
	// If you come across one of these, it is most likely that the Healthchecks
	// server is experiencing some trouble, or is misconfigured somehow.
	// It is also possible that a new response is supported and this package is
	// not up-to-date. If so, please raise an issue to the developer team.
	ErrStatus4xx = errors.New("4xx response status")
	ErrStatus5xx = errors.New("5xx response status")
)
View Source
var (
	// For use when evaluating Status. Represents the STARTED check status.
	CheckStatusUp = "up"
	// For use when evaluating Status. Represents the DOWN check status.
	CheckStatusDown = "down"
	// For use when evaluating Status. Represents the STARTED check status.
	CheckStatusStarted = "started"
	// For use when evaluating Status. Represents the GRACE check status.
	CheckStatusGrace = "grace"
	// For use when evaluating Status. Represents the PAUSED check status.
	CheckStatusPaused = "paused"
	// For use when evaluating Status. Represents the NEW check status.
	CheckStatusNew = "new"

	// For use when setting Methods. Represents all supported methods.
	CheckMethodsAll = &Strings{""}
	// For use when setting Methods. Represents POST.
	CheckMethodsPost = &Strings{"POST"}

	// For use when setting ManualResume. Represents true.
	CheckManualResumeTrue = &_true
	// For use when setting ManualResume. Represents false.
	CheckManualResumeFalse = &_false
)
View Source
var (
	// DefaultPingingEndpoint is Healthchecks.io's pinging endpoint.
	DefaultPingingEndpoint = "https://hc-ping.com/"
)

Functions

func ExitStatus

func ExitStatus(uuid string, code int) error

ExitStatus wraps PingCustom to send a script's exit code for check `uuid`.

func Fail

func Fail(uuid string) error

Fail wraps PingCustom to send a "fail" signal for check `uuid`.

func Finish

func Finish(uuid string) error

Finish wraps Success for a better user experience.

func Ping

func Ping(uuid string) error

Ping wraps Success for a better user experience.

func PingCustom

func PingCustom(url string) error

PingCustom wraps ping with a custom `url`.

This allows pinging checks not within Healthchecks.io (if self-hosting Healthchecks, for example).

Can also be used to verify the status of an arbitrary `url` via a HEAD request, since the returned error will be nil if the response status code is strictly below 400, but it is not its main use case and might change in the future.

func Start

func Start(uuid string) error

Start wraps PingCustom to send a "start" signal for check `uuid`.

func String

func String(s string) *string

String returns the pointer to `s`. This helps when instantiating Check.

func Success

func Success(uuid string) error

Success wraps PingCustom to send a "success" signal for check `uuid`.

Types

type Channel

type Channel struct {
	ID   *string `json:"id"`
	Name *string `json:"name"`
	Kind *string `json:"kind"`
	// contains filtered or unexported fields
}

A Channel represents a Healthchecks notification integration.

type Check

type Check struct {
	// Name is the check's name.
	Name *string `json:"name,omitempty"`

	// Tags is the check's tags.
	Tags *Strings `json:"tags,omitempty"`

	// Description is the check's description.
	Description *string `json:"desc,omitempty"`

	// TimeoutPeriod is the check's configured period for timeout. Not to be
	// confused with GracePeriod.
	TimeoutPeriod *Duration `json:"timeout,omitempty"`

	// GracePeriod is the check's configured period for grace time after timing
	// out. Not to be confused with TimeoutPeriod.
	GracePeriod *Duration `json:"grace,omitempty"`

	// Methods is the check's list of allowed methods.
	// According to Healthchecks' API reference, it only supports:
	//   * HEAD, GET, POST, PUT; or
	//   * POST, exclusively.
	// It does not support a free combination of the above.
	// It is recommended to use CheckMethodsAll and CheckMethodsPost when
	// instantiating Check, for better code readability.
	Methods *Strings `json:"methods,omitempty"`

	// ManualResume is the check's setting for resuming when the check is in
	// paused status. If the check is paused, there are two options:
	//   * (false) leave the paused status (resume) after first ping; or
	//   * (true) continue in paused status regardless of pings.
	// It is recommended to use CheckManualResumeTrue and CheckManualResumeFalse
	// when instantiating Check, for better code readability.
	ManualResume *bool `json:"manual_resume,omitempty"`

	// Channels is the check's configured notification integrations.
	Channels *Strings  `json:"channels,omitempty"`
	Unique   *[]string `json:"unique,omitempty"`

	// Status is the check's status, as reported by Healthchecks' API.
	// It is recommended to use the following when evaluating Status:
	//   * CheckStatusUp: the check is in UP status;
	//   * CheckStatusDown: the check is in DOWN status;
	//   * CheckStatusStarted: the check has started;
	//   * CheckStatusPaused: the check is paused;
	//   * CheckStatusNew: the check was never pinged, ever;
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	Status *string `json:"status,omitempty"`

	// LastPing references the time at which the check was last pinged, as
	// reported by Healthchecks' API.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	LastPing *time.Time `json:"last_ping,omitempty"`

	// NextPing represents the time at which the check's next ping should come,
	// as reported by Healthchecks' API.
	// It is supposed to be the result of adding TimeoutPeriod to LastPing.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	NextPing *time.Time `json:"next_ping,omitempty"`

	// PingCount is the number of times the check was pinged since its creation,
	// as reported by Healthchecks' API.
	// This package represents PingCount as an uint64, thus setting the max
	// number of pings to 18446744073709551615 before overflowing. Healthchecks'
	// API internal representation of this number is undisclosed, but it may be
	// well below (or above) that ceiling.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	PingCount *uint64 `json:"n_pings,omitempty"`

	// PingURL is the URL used for Healthchecks' pinging API, as reported by
	// Healthchecks' API itself.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	PingURL *URL `json:"ping_url,omitempty"`

	// UpdateURL is the URL used for Healthchecks' management API, for updating
	// the check's settings, as reported by Healthchecks' API itself.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	UpdateURL *URL `json:"update_url,omitempty"`

	// PauseURL is the URL used for Healthchecks' management API, for pausing
	// the check, as reported by Healthchecks' API itself.
	//
	// This field is read-only, and should not be used when instantiating Check
	// for write operations within the Healthchecks API.
	PauseURL *URL `json:"pause_url,omitempty"`
	// contains filtered or unexported fields
}

A Check represents a Healthchecks check.

func (*Check) Delete

func (c *Check) Delete() error

Delete permanently deletes the check.

func (*Check) ExitStatus

func (c *Check) ExitStatus(code int) error

ExitStatus wraps PingCustom to send a script's exit code for the check.

func (*Check) Fail

func (c *Check) Fail() error

Fail wraps PingCustom to send a "fail" signal for the check.

func (*Check) Finish

func (c *Check) Finish() error

Finish wraps PingCustom to send a "fail" signal for the check.

func (*Check) Flips

func (c *Check) Flips() (*[]CheckFlip, error)

Flips requests and returns the check's status flips as returned by Healthchecks' management API.

func (*Check) Pause

func (c *Check) Pause() error

Pause changes the check's status to paused.

func (*Check) Ping

func (c *Check) Ping() error

Ping wraps Success for a better user experience.

func (*Check) Pings

func (c *Check) Pings() (*[]CheckPing, error)

Pings requests and returns the check's pings as returned by Healthchecks' management API.

func (*Check) Start

func (c *Check) Start() error

Start wraps PingCustom to send a "start" signal for the check.

func (*Check) Success

func (c *Check) Success() error

Success wraps PingCustom to send a "success" signal for the check.

func (*Check) UUID

func (c *Check) UUID() string

UUID returns the check's UUID.

func (*Check) Update

func (c *Check) Update(check *Check) error

Update modifies the check's fields with the passed fields, then returns the check as reported by Healthchecks' API.

type CheckFlip

type CheckFlip struct {
	// Timestamp represents the time at which the status flipped for the check.
	Timestamp *time.Time `json:"timestamp"`

	// Up represents the status which the check switched into when it flipped.
	Up *int `json:"up"`
}

A CheckFlip represents a flip in status for a Check.

type CheckPing

type CheckPing struct {
	// Type is the type of ping, as reported by Healthchecks' API itself.
	Type *string `json:"type"`

	// Date references the time at which the check was pinged, as reported by
	// Healthchecks' API itself.
	Date *time.Time `json:"date"`

	// N is the value of PingCount after this ping happened, as reported by
	// Healthchecks' API itself.
	N *int `json:"n"`

	// Scheme is the scheme over which the ping was performed, as reported by
	// Healthchecks' API itself.
	Scheme *string `json:"scheme"`

	// RemoteAddr is the IP address from which the check was pinged, as reported
	// by Healthchecks' API itself.
	RemoteAddr *IP `json:"remote_addr"`

	// Method is the HTTP method used for pinging, as reported by Healthchecks'
	// API itself.
	Method *string `json:"method"`

	// UserAgent is the ping's HTTP request User-Agent header, as reported by
	// Healthchecks' API itself.
	UserAgent *string `json:"ua"`

	// Duration is the duration of the ping, since its start until its first
	// status report, as reported by Healthchecks' API itself.
	Duration *Duration `json:"duration"`
}

A CheckPing represents a ping to a Check.

type Duration

type Duration time.Duration

A Duration masks time.Duration. The purpose for Strings is to implement UnmarshalJSON and MarshalJSON for object serialization and deserialization over Healthchecks' RESTful API. The serialization/deserialization of time.Duration is inherited from int64, which represents nanoseconds, but Healthchecks' RESTful API represents duration in seconds.

func Hours

func Hours(n int) *Duration

Hours returns the pointer to a Duration of `n` hours. It helps when instantiating Check.

func Minutes

func Minutes(n int) *Duration

Minutes returns the pointer to a Duration of `n` minutes. It helps when instantiating Check.

func (*Duration) MarshalJSON

func (v *Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. Performs the inverse of UnmarshalJSON.

func (*Duration) UnmarshalJSON

func (v *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. The duration is expected to be a number of seconds.

type HealthchecksAPI

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

A HealthchecksAPI holds the Healthchecks RESTful API settings, and most importantly, the HTTP client used for talking with Healthchecks.

HealthchecksAPI is reusable.

func New

func New(key string) *HealthchecksAPI

New instantiates HealthchecksAPI using Healthchecks.io's endpoint.

When instantiating HealthchecksAPI with a custom endpoint (if self-hosting Healthchecks, for example), use NewWithCustomEndpoint.

func NewWithCustomEndpoint

func NewWithCustomEndpoint(key string, endpoint string) *HealthchecksAPI

NewWithCustomEndpoint instantiates HealthchecksAPI using the provided endpoint. For use when talking to a self-hosted Healthchecks installation.

When instantiating HealthchecksAPI for use with Healthchecks.io, use New.

func (*HealthchecksAPI) CreateCheck

func (hc *HealthchecksAPI) CreateCheck(check *Check) (*Check, error)

CreateCheck creates and returns the check as returned by Healthchecks' management API.

func (*HealthchecksAPI) GetCheck

func (hc *HealthchecksAPI) GetCheck(uuid string) (*Check, error)

GetCheck wraps GetCheckByUUID.

func (*HealthchecksAPI) GetCheckByUUID

func (hc *HealthchecksAPI) GetCheckByUUID(uuid string) (*Check, error)

GetCheckByUUID requests and returns the check as returned by Healthchecks' management API.

func (*HealthchecksAPI) GetCheckByUniqueKey

func (hc *HealthchecksAPI) GetCheckByUniqueKey(uniqueKey string) (*Check, error)

GetCheckByUniqueKey requests and returns the check as returned by Healthchecks' management API.

func (*HealthchecksAPI) ListChannels

func (hc *HealthchecksAPI) ListChannels() (*[]Channel, error)

ListChannels requests and returns the list of Channel as returned by Healthchecks' management API.

func (*HealthchecksAPI) ListChecks

func (hc *HealthchecksAPI) ListChecks() (*[]Check, error)

ListChecks requests and returns the list of Check as returned by Healthchecks' management API.

type IP

type IP net.IP

An IP masks net.IP. The purpose for IP is to implement UnmarshalJSON and MarshalJSON for object serialization and deserialization over Healthchecks' RESTful API. The serialization/deserialization of net.IP is inherited from []byte, but Healthchecks' RESTful API represents URLs as strings.

func (*IP) MarshalJSON

func (v *IP) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. Performs the inverse of UnmarshalJSON.

func (*IP) UnmarshalJSON

func (v *IP) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. Parses an IP in []byte representation into a net.IP.

type Strings

type Strings []string

A Strings masks []string. The purpose for Strings is to implement UnmarshalJSON and MarshalJSON for object serialization and deserialization over Healthchecks' RESTful API.

func (*Strings) MarshalJSON

func (v *Strings) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. Performs the inverse of UnmarshalJSON.

func (*Strings) UnmarshalJSON

func (v *Strings) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. The strings are expected to be a quoted string of elements separated by spaces.

type URL

type URL url.URL

A URL masks url.URL. The purpose for URL is to implement UnmarshalJSON and MarshalJSON for object serialization and deserialization over Healthchecks' RESTful API. The serialization/deserialization of url.URL is inherited from struct, which marshals/unmarshals to/from a JSON object, but Healthchecks' RESTful API represents URLs as strings.

func (*URL) MarshalJSON

func (v *URL) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. Performs the inverse of UnmarshalJSON.

func (*URL) UnmarshalJSON

func (v *URL) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface. Parses a URL in []byte representation into a url.URL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL