retryable

Documentation

Overview

Package retryable provides a retryable HTTP client with configurable options for request delay, random jitter, and exponential backoff.

Index

• Variables
• type Client
  • func (client *Client) CloseIdleConnections()
  • func (client *Client) Do(request *http.Request) (response *http.Response, err error)
  • func (client *Client) Get(url string) (response *http.Response, err error)
  • func (client *Client) Head(url string) (response *http.Response, err error)
  • func (client *Client) Post(url string, contentType string, body io.Reader) (response *http.Response, err error)
  • func (client *Client) PostForm(url string, data url.Values) (response *http.Response, err error)

Examples

• Client

Variables

var DefaultClient = &Client{
	Client:          *http.DefaultClient,
	RetryStatus:     DefaultStatus,
	RetryCount:      20,
	RetryDelay:      500 * time.Millisecond,
	RetryMultiplier: 1.5,
	RetryJitter:     0.5,
	RetryTimeout:    60 * time.Minute,
	RequestDelay:    10 * time.Millisecond,
	RequestJitter:   0.5,
	RequestTimeout:  5 * time.Minute,
	RequestSize:     2 * 1024 * 1024 * 1024,
	ResponseSize:    2 * 1024 * 1024 * 1024,
}

DefaultClient is the default retryable HTTP client.

var DefaultStatus = []int{
	http.StatusRequestTimeout,
	http.StatusConflict,
	unofficial.StatusEnhanceYourCalm,
	http.StatusLocked,
	http.StatusTooEarly,
	http.StatusTooManyRequests,
	unofficial.StatusRequestHeaderFieldsTooLarge,
	http.StatusInternalServerError,
	http.StatusBadGateway,
	http.StatusServiceUnavailable,
	http.StatusGatewayTimeout,
	http.StatusInsufficientStorage,
	unofficial.StatusBandwidthLimitExceeded,
	unofficial.StatusWebServerReturnedAnUnknownError,
	unofficial.StatusWebServerIsDown,
	unofficial.StatusConnectionTimedOut,
	unofficial.StatusOriginIsUnreachable,
	unofficial.StatusTimeoutOccurred,
	unofficial.StatusRailgunError,
	unofficial.StatusSiteIsOverloaded,
	unofficial.StatusCloudflareError,
	unofficial.StatusNetworkReadTimeout,
	unofficial.StatusNetworkConnectTimeout,
}

DefaultStatus contains the default retryable status codes.

var ErrNonRetryable = errors.New("non-retryable error")

ErrNonRetryable defines a non-retryable error.

var ErrRetryable = errors.New("retryable error")

ErrRetryable defines a retryable error.

Types

type Client

type Client struct {
	// Client specifies the base HTTP client.
	http.Client

	// RetryStatus specifies the status codes that are retryable.
	RetryStatus []int

	// RetryCount specifies the maximum number of retries per request.
	RetryCount int

	// RetryDelay specifies the delay between retries.
	RetryDelay time.Duration

	// RetryMultiplier specifies the exponential backoff multiplier for the
	// retry delay. If the retry multiplier is less than one, it will be
	// ignored.
	RetryMultiplier float64

	// RetryJitter specifies the random jitter applied to the retry delay.
	RetryJitter float64

	// RetryTimeout specifies the maximum total duration of retries per request.
	RetryTimeout time.Duration

	// RequestDelay specifies a fixed delay applied to each request.
	RequestDelay time.Duration

	// RequestJitter specifies the random jitter applied to the request delay.
	RequestJitter float64

	// RequestTimeout specifies the maximum duration per request.
	RequestTimeout time.Duration

	// RequestSize specifies the maximum request size in bytes.
	RequestSize int64

	// ResponseSize specifies the maximum response size in bytes.
	ResponseSize int64
}

Client is an HTTP client that can automatically retry failed requests, and provides a drop-in replacement for net/http.Client.

Example

request, err := http.NewRequest(http.MethodGet, "https://www.github.com/", nil)
if err != nil {
	log.Fatal(err)
}
response, err := DefaultClient.Do(request)
if err != nil {
	log.Fatal(err)
}
defer response.Body.Close()
fmt.Println(response.StatusCode)

Output:

200

func (*Client) CloseIdleConnections

func (client *Client) CloseIdleConnections()

CloseIdleConnections closes any connections on its net/http.Transport which were previously connected from previous requests but are now sitting idle in a "keep-alive" state. It does not interrupt any connections currently in use.

func (*Client) Do

func (client *Client) Do(request *http.Request) (response *http.Response, err error)

Do sends an HTTP request and returns an HTTP response, following policy (such as redirects, cookies, auth) as configured on the client.

func (*Client) Get

func (client *Client) Get(url string) (response *http.Response, err error)

Get issues a GET to the specified URL.

func (*Client) Head

func (client *Client) Head(url string) (response *http.Response, err error)

Head issues a HEAD to the specified URL.

func (*Client) Post

func (client *Client) Post(url string, contentType string, body io.Reader) (response *http.Response, err error)

Post issues a POST to the specified URL.

func (*Client) PostForm

func (client *Client) PostForm(url string, data url.Values) (response *http.Response, err error)

PostForm issues a POST to the specified URL, with data's keys and values URL-encoded as the request body.