retry

Documentation

Index

• Variables
• func NewClient() *http.Client
• type Backoff
  • func ExponentialBackoff(backoff time.Duration, factor, jitter float64) Backoff
• type GenericPolicy
  • func (p *GenericPolicy) Retry(attempt int, resp *http.Response, err error) (time.Duration, error)
• type Policy
• type Predicate
• type Transport
  • func NewTransport(base http.RoundTripper) *Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Variables

var DefaultClient = NewClient()

DefaultClient is a client with the default retry policy.

Functions

func NewClient

func NewClient() *http.Client

NewClient creates an HTTP client with the default retry policy.

Types

type Backoff

type Backoff func(attempt int, resp *http.Response) time.Duration

Backoff is a function that returns the duration to wait before retrying the request. The attempt, is the next attempt number. The response is the response from the previous request.

var DefaultBackoff Backoff = ExponentialBackoff(250*time.Millisecond, 2, 0.1)

DefaultBackoff is a backoff that uses an exponential backoff with jitter. It uses a base of 250ms, a factor of 2 and a jitter of 10%.

func ExponentialBackoff

func ExponentialBackoff(backoff time.Duration, factor, jitter float64) Backoff

ExponentialBackoff returns a Backoff that uses an exponential backoff with jitter. The backoff is calculated as:

temp = backoff * factor ^ attempt
interval = temp * (1 - jitter) + rand.Int63n(2 * jitter * temp)

The HTTP response is checked for a Retry-After header. If it is present, the value is used as the backoff duration.

type GenericPolicy

type GenericPolicy struct {
	// Retryable is a predicate that returns true if the request should be
	// retried.
	Retryable Predicate

	// Backoff is a function that returns the duration to wait before retrying.
	Backoff Backoff

	// MinWait is the minimum duration to wait before retrying.
	MinWait time.Duration

	// MaxWait is the maximum duration to wait before retrying.
	MaxWait time.Duration

	// MaxRetry is the maximum number of retries.
	MaxRetry int
}

GenericPolicy is a generic retry policy.

func (*GenericPolicy) Retry

func (p *GenericPolicy) Retry(attempt int, resp *http.Response, err error) (time.Duration, error)

Retry returns the duration to wait before retrying the request. It returns -1 if the request should not be retried.

type Policy

type Policy interface {
	// Retry returns the duration to wait before retrying the request.
	// It returns a negative value if the request should not be retried.
	// The attempt is used to:
	//  - calculate the backoff duration, the default backoff is an exponential backoff.
	//  - determine if the request should be retried.
	// The attempt starts at 0 and should be less than MaxRetry for the request to
	// be retried.
	Retry(attempt int, resp *http.Response, err error) (time.Duration, error)
}

Policy is a retry policy.

var DefaultPolicy Policy = &GenericPolicy{
	Retryable: DefaultPredicate,
	Backoff:   DefaultBackoff,
	MinWait:   200 * time.Millisecond,
	MaxWait:   3 * time.Second,
	MaxRetry:  5,
}

DefaultPolicy is a policy with fine-tuned retry parameters. It uses an exponential backoff with jitter.

type Predicate

type Predicate func(resp *http.Response, err error) (bool, error)

Predicate is a function that returns true if the request should be retried.

var DefaultPredicate Predicate = func(resp *http.Response, err error) (bool, error) {
	if err != nil {

		if err, ok := err.(net.Error); ok && err.Timeout() {
			return true, nil
		}
		return false, err
	}

	if resp.StatusCode == http.StatusRequestTimeout || resp.StatusCode == http.StatusTooManyRequests {
		return true, nil
	}

	if resp.StatusCode == 0 || resp.StatusCode >= 500 {
		return true, nil
	}

	return false, nil
}

DefaultPredicate is a predicate that retries on 5xx errors, 429 Too Many Requests, 408 Request Timeout and on network dial timeout.

type Transport

type Transport struct {
	// Base is the underlying HTTP transport to use.
	// If nil, http.DefaultTransport is used for round trips.
	Base http.RoundTripper

	// Policy returns a retry Policy to use for the request.
	// If nil, DefaultPolicy is used to determine if the request should be retried.
	Policy func() Policy
}

Transport is an HTTP transport with retry policy.

func NewTransport

func NewTransport(base http.RoundTripper) *Transport

NewTransport creates an HTTP Transport with the default retry policy.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes a single HTTP transaction, returning a Response for the provided Request. It relies on the configured Policy to determine if the request should be retried and to backoff.