internal

Documentation

Overview

Copyright 2020 - 2022, Berk D. Demir and the runitor contributors SPDX-License-Identifier: 0BSD

Package internal contains healthchecks.io HTTP API client implementation for cmd/runitor's use.

It is not intended to be used as a standalone client package.

Copyright 2020 - 2022, Berk D. Demir and the runitor contributors SPDX-License-Identifier: 0BSD

Copyright 2020 - 2022, Berk D. Demir and the runitor contributors SPDX-License-Identifier: 0BSD

Copyright 2020 - 2022, Berk D. Demir and the runitor contributors SPDX-License-Identifier: 0BSD

Copyright 2020 - 2022, Berk D. Demir and the runitor contributors SPDX-License-Identifier: 0BSD

Index

• Constants
• Variables
• func Max[T ~int | ~uint](x, y T) T
• func Min[T ~int | ~uint](x, y T) T
• func NewDefaultTransportWithResumption() *http.Transport
• func NewUUID4() (string, error)
• type APIClient
  • func (c *APIClient) PingExitCode(handle, rid string, exitCode int, body io.Reader) (*InstanceConfig, error)
  • func (c *APIClient) PingFail(handle, rid string, body io.Reader) (*InstanceConfig, error)
  • func (c *APIClient) PingLog(handle, rid string, body io.Reader) (*InstanceConfig, error)
  • func (c *APIClient) PingStart(handle, rid string) (*InstanceConfig, error)
  • func (c *APIClient) PingSuccess(handle, rid string, body io.Reader) (*InstanceConfig, error)
  • func (c *APIClient) Post(url, contentType string, body io.Reader) (resp *http.Response, err error)
• type InstanceConfig
  • func (c *InstanceConfig) FromResponse(resp *http.Response)
• type Optional
  • func None[T any]() Optional[T]
  • func Some[T any](val T) Optional[T]
  • func (o Optional[T]) Get() (T, bool)
  • func (o Optional[T]) IsDefined() bool
• type Pinger
• type RingBuffer
  • func NewRingBuffer(cap int) *RingBuffer
  • func (r *RingBuffer) Cap() int
  • func (r *RingBuffer) Len() int
  • func (r *RingBuffer) Read(p []byte) (n int, err error)
  • func (r *RingBuffer) Wrapped() bool
  • func (r *RingBuffer) Write(p []byte) (n int, err error)

Constants

const (
	// Default Healthchecks API address.
	DefaultBaseURL = "https://hc-ping.com"
	// Default HTTP client timeout.
	DefaultTimeout = 5 * time.Second
	// Default number of retries.
	DefaultRetries = 2
	// Header to relay instance's ping body limit.
	PingBodyLimitHeader = "Ping-Body-Limit"
)

Variables

var (
	ErrNonRetriable = errors.New("nonretriable error response")
	ErrMaxTries     = errors.New("max tries reached")
	// HTTP response codes eligible for retries.
	RetriableResponseCodes = []int{
		http.StatusRequestTimeout,
		http.StatusTooManyRequests,
		http.StatusInternalServerError,
		http.StatusBadGateway,
		http.StatusServiceUnavailable,
		http.StatusGatewayTimeout,
	}
)

var ErrReadOnly = errors.New("read only")

ErrReadOnly is the error returned by Write to indicate the ring buffer is in read only mode and will not accept further writes.

Functions

func Max

func Max[T ~int | ~uint](x, y T) T

func Min

func Min[T ~int | ~uint](x, y T) T

func NewDefaultTransportWithResumption

func NewDefaultTransportWithResumption() *http.Transport

NewDefaultTransportWithResumption returns an http.Transport based on http.DefaultTransport with a TLS Client Session Cache, to enable TLS session resumption.

func NewUUID4

func NewUUID4() (string, error)

Types

type APIClient

type APIClient struct {
	// BaseURL is the base URL of Healthchecks API instance
	BaseURL string // BaseURL of the Healthchecks API

	// Retries is the number of times the pinger will retry an API request
	// if it fails with a timeout or temporary kind of error, or an HTTP
	// status of 408, 429, 500, ... (see RetriableResponseCodes)
	Retries uint

	// UserAgent, when non-empty, is the value of 'User-Agent' HTTP header
	// for outgoing requests.
	UserAgent string

	// Backoff is the duration used as the unit of linear backoff.
	Backoff time.Duration

	// ReqHeaders is a map of additional headers to be sent with every request.
	ReqHeaders map[string]string

	// Embed
	*http.Client
}

APIClient holds API endpoint URL, client behavior configuration, and embeds http.Client.

func (*APIClient) PingExitCode

func (c *APIClient) PingExitCode(handle, rid string, exitCode int, body io.Reader) (*InstanceConfig, error)

PingExitCode sends the exit code of the monitored command for the check handle and attaches body as the logged context.

func (*APIClient) PingFail

func (c *APIClient) PingFail(handle, rid string, body io.Reader) (*InstanceConfig, error)

PingFail sends a failure ping for the check handle and attaches body as the logged context.

func (*APIClient) PingLog

func (c *APIClient) PingLog(handle, rid string, body io.Reader) (*InstanceConfig, error)

PingLog sends a logging only ping for the check handle and attaches body as the logged context.

func (*APIClient) PingStart

func (c *APIClient) PingStart(handle, rid string) (*InstanceConfig, error)

PingStart sends a start ping for the check handle.

func (*APIClient) PingSuccess

func (c *APIClient) PingSuccess(handle, rid string, body io.Reader) (*InstanceConfig, error)

PingSuccess sends a success ping for the check handle and attaches body as the logged context.

func (*APIClient) Post

func (c *APIClient) Post(url, contentType string, body io.Reader) (resp *http.Response, err error)

Post wraps embedded http.Client's Post to implement simple retry logic and custom User-Agent header injection.

Retries: The implementation is inspired from Curl's. Request timeouts and temporary network level errors will be retried. Responses with status codes 408 and 5XX are also retried. Unlike Curl's, the backoff implementation is linear instead of exponential. First retry waits for 1 second, second one waits for 2 seconds, and so on.

User-Agent: If c.UserAgent is not empty, it overrides http.Client's default header.

type InstanceConfig

type InstanceConfig struct {
	PingBodyLimit Optional[uint]
}

InstanceConfig holds the instance specific configuration parameters received as HTTP headers to ping requests.

func (*InstanceConfig) FromResponse

func (c *InstanceConfig) FromResponse(resp *http.Response)

FromResponse populates InstanceConfig values from a ping response.

type Optional

type Optional[T any] struct {
	// contains filtered or unexported fields
}

func None

func None[T any]() Optional[T]

func Some

func Some[T any](val T) Optional[T]

func (Optional[T]) Get

func (o Optional[T]) Get() (T, bool)

func (Optional[T]) IsDefined

func (o Optional[T]) IsDefined() bool

type Pinger

type Pinger interface {
	PingStart(handle, rid string) (*InstanceConfig, error)
	PingLog(handle, rid string, body io.Reader) (*InstanceConfig, error)
	PingSuccess(handle, rid string, body io.Reader) (*InstanceConfig, error)
	PingFail(handle, rid string, body io.Reader) (*InstanceConfig, error)
	PingExitCode(handle, rid string, exitCode int, body io.Reader) (*InstanceConfig, error)
}

Pinger is the interface to Healthchecks.io pinging API https://healthchecks.io/docs/http_api/

type RingBuffer

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

RingBuffer implements io.ReadWriter interface to a []byte backed ring buffer (aka circular buffer).

Can be written to repeatedly until read from. At first read, ring buffer becomes read only, refusing further writes with ErrReadOnly error.

func NewRingBuffer

func NewRingBuffer(cap int) *RingBuffer

NewRingBuffer allocates a new RingBuffer and the backing byte array with specified capacity.

func (*RingBuffer) Cap

func (r *RingBuffer) Cap() int

Cap returns the capacity of the ring buffer.

func (*RingBuffer) Len

func (r *RingBuffer) Len() int

Len returns the length of the ring buffer.

func (*RingBuffer) Read

func (r *RingBuffer) Read(p []byte) (n int, err error)

func (*RingBuffer) Wrapped

func (r *RingBuffer) Wrapped() bool

Wrapped returns true if the ring buffer overwrote at least one byte.

func (*RingBuffer) Write

func (r *RingBuffer) Write(p []byte) (n int, err error)