httpeeve

README

HTTPeeve

HTTPeeve is a library for making HTTP requests with exponential backoff. It wraps around https://github.com/cenkalti/backoff and provides some helper functions.

Installation

go get github.com/Onefootball/httpeeve

Usage

An example of how to use the library can be found in the helper function NewDefaultBackoffClient5XX:

func NewDefaultBackoffClient5XX(httpClient http.Client) Client {
	return NewBackoffClient(httpClient, backoff.NewExponentialBackOff(), func(resp *http.Response) (bool, error) {
		if resp.StatusCode >= 500 && resp.StatusCode < 600 {
			return RetriableErrorf("bad status code %d", resp.StatusCode)
		}

		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
			return OK()
		}

		return PermanentErrorf("bad status code %d", resp.StatusCode)
	})
}

This function takes a "net/http".Client. It initializes a NewBackoffClient with this, as well as an instance of "cenkalti/backoff".Backoff and a Conditioner.

In the example, the Conditioner determines that 5XX status codes can be retried, 2XXs are OK, and everything else results in an unretriable error.

This library also provides a helper function to see how many attempts a request took:

resp, err := client.Do(req)
if err != nil {
    // something
}
fmt.Println(httpeeve.Attempts(resp))

Documentation

Index

• func Attempts(resp *http.Response) int
• func OK() (bool, error)
• func PermanentError(msg string) (bool, error)
• func PermanentErrorf(msg string, values ...interface{}) (bool, error)
• func RetriableError(msg string) (bool, error)
• func RetriableErrorf(msg string, values ...interface{}) (bool, error)
• type Client
  • func NewBackoffClient(httpClient http.Client, backoffer backoff.BackOff, conditioner Conditioner) Client
  • func NewDefaultBackoffClient5XX(httpClient http.Client) Client
• type Conditioner

Functions

func Attempts

func Attempts(resp *http.Response) int

Attempts can be used to tell how many attempts a response took for its execution.

func OK

func OK() (bool, error)

OK signals that no error occurred and we do not need to retry

func PermanentError

func PermanentError(msg string) (bool, error)

PermanentError signals that an error occurred that cannot be retried

func PermanentErrorf

func PermanentErrorf(msg string, values ...interface{}) (bool, error)

PermanentErrorf is like PermanentError but allows string formatting

func RetriableError

func RetriableError(msg string) (bool, error)

RetriableError signals that a retriable error ocurred

func RetriableErrorf

func RetriableErrorf(msg string, values ...interface{}) (bool, error)

RetriableErrorf is like RetriableError but allows string formatting

Types

type Client

type Client interface {
	Do(*http.Request) (*http.Response, error)
}

Client represents an HTTP client. The "net/http".Client implements it for easy substitution in your project.

func NewBackoffClient

func NewBackoffClient(httpClient http.Client, backoffer backoff.BackOff, conditioner Conditioner) Client

NewBackoffClient returns a Client implementation. It takes an implementation of backoff.Backoff, which determines the rate and limits of retrying. It takes a Conditioner which determines when to stop or continue retrying.

func NewDefaultBackoffClient5XX

func NewDefaultBackoffClient5XX(httpClient http.Client) Client

NewDefaultBackoffClient5XX retries requests if they result in 5XXs and accepts them if they result in 2XXs. If they are neither they return an error and retry no longer.

type Conditioner

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

Conditioner determines whether a response is erroneous and whether to retry it.