vault: github.com/hashicorp/vault/vendor/github.com/hashicorp/go-retryablehttp Index | Files

package retryablehttp

import "github.com/hashicorp/vault/vendor/github.com/hashicorp/go-retryablehttp"

The retryablehttp package provides a familiar HTTP client interface with automatic retries and exponential backoff. It is a thin wrapper over the standard net/http client library and exposes nearly the same public API. This makes retryablehttp very easy to drop into existing programs.

retryablehttp performs automatic retries under certain conditions. Mainly, if an error is returned by the client (connection errors etc), or if a 500-range response is received, then a retry is invoked. Otherwise, the response is returned and left to the caller to interpret.

Requests which take a request body should provide a non-nil function parameter. The best choice is to provide either a function satisfying ReaderFunc which provides multiple io.Readers in an efficient manner, a *bytes.Buffer (the underlying raw byte slice will be used) or a raw byte slice. As it is a reference type, and we will wrap it as needed by readers, we can efficiently re-use the request body without needing to copy it. If an io.Reader (such as a *bytes.Reader) is provided, the full body will be read prior to the first request, and will be efficiently re-used for any retries. ReadSeeker can be used, but some users have observed occasional data races between the net/http library and the Seek functionality of some implementations of ReadSeeker, so should be avoided if possible.

Index

Package Files

client.go

func DefaultBackoff Uses

func DefaultBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

DefaultBackoff provides a default callback for Client.Backoff which will perform exponential backoff based on the attempt number and limited by the provided minimum and maximum durations.

func DefaultRetryPolicy Uses

func DefaultRetryPolicy(ctx context.Context, resp *http.Response, err error) (bool, error)

DefaultRetryPolicy provides a default callback for Client.CheckRetry, which will retry on connection errors and server errors.

func Get Uses

func Get(url string) (*http.Response, error)

Get is a shortcut for doing a GET request without making a new client.

func Head(url string) (*http.Response, error)

Head is a shortcut for doing a HEAD request without making a new client.

func LinearJitterBackoff Uses

func LinearJitterBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

LinearJitterBackoff provides a callback for Client.Backoff which will perform linear backoff based on the attempt number and with jitter to prevent a thundering herd.

min and max here are *not* absolute values. The number to be multipled by the attempt number will be chosen at random from between them, thus they are bounding the jitter.

For instance: * To get strictly linear backoff of one second increasing each retry, set both to one second (1s, 2s, 3s, 4s, ...) * To get a small amount of jitter centered around one second increasing each retry, set to around one second, such as a min of 800ms and max of 1200ms (892ms, 2102ms, 2945ms, 4312ms, ...) * To get extreme jitter, set to a very wide spread, such as a min of 100ms and a max of 20s (15382ms, 292ms, 51321ms, 35234ms, ...)

func PassthroughErrorHandler Uses

func PassthroughErrorHandler(resp *http.Response, err error, _ int) (*http.Response, error)

PassthroughErrorHandler is an ErrorHandler that directly passes through the values from the net/http library for the final request. The body is not closed.

func Post Uses

func Post(url, bodyType string, body interface{}) (*http.Response, error)

Post is a shortcut for doing a POST request without making a new client.

func PostForm Uses

func PostForm(url string, data url.Values) (*http.Response, error)

PostForm is a shortcut to perform a POST with form data without creating a new client.

type Backoff Uses

type Backoff func(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

Backoff specifies a policy for how long to wait between retries. It is called after a failing request to determine the amount of time that should pass before trying again.

type CheckRetry Uses

type CheckRetry func(ctx context.Context, resp *http.Response, err error) (bool, error)

CheckRetry specifies a policy for handling retries. It is called following each request with the response and error values returned by the http.Client. If CheckRetry returns false, the Client stops retrying and returns the response to the caller. If CheckRetry returns an error, that error value is returned in lieu of the error from the request. The Client will close any response body when retrying, but if the retry is aborted it is up to the CheckResponse callback to properly close any response body before returning.

type Client Uses

type Client struct {
    HTTPClient *http.Client // Internal HTTP client.
    Logger     interface{}  // Customer logger instance. Can be either Logger or hclog.Logger

    RetryWaitMin time.Duration // Minimum time to wait
    RetryWaitMax time.Duration // Maximum time to wait
    RetryMax     int           // Maximum number of retries

    // RequestLogHook allows a user-supplied function to be called
    // before each retry.
    RequestLogHook RequestLogHook

    // ResponseLogHook allows a user-supplied function to be called
    // with the response from each HTTP request executed.
    ResponseLogHook ResponseLogHook

    // CheckRetry specifies the policy for handling retries, and is called
    // after each request. The default policy is DefaultRetryPolicy.
    CheckRetry CheckRetry

    // Backoff specifies the policy for how long to wait between retries
    Backoff Backoff

    // ErrorHandler specifies the custom error handler to use, if any
    ErrorHandler ErrorHandler
    // contains filtered or unexported fields
}

Client is used to make HTTP requests. It adds additional functionality like automatic retries to tolerate minor outages.

func NewClient Uses

func NewClient() *Client

NewClient creates a new Client with default settings.

func (*Client) Do Uses

func (c *Client) Do(req *Request) (*http.Response, error)

Do wraps calling an HTTP method with retries.

func (*Client) Get Uses

func (c *Client) Get(url string) (*http.Response, error)

Get is a convenience helper for doing simple GET requests.

func (*Client) Head Uses

func (c *Client) Head(url string) (*http.Response, error)

Head is a convenience method for doing simple HEAD requests.

func (*Client) Post Uses

func (c *Client) Post(url, bodyType string, body interface{}) (*http.Response, error)

Post is a convenience method for doing simple POST requests.

func (*Client) PostForm Uses

func (c *Client) PostForm(url string, data url.Values) (*http.Response, error)

PostForm is a convenience method for doing simple POST operations using pre-filled url.Values form data.

type ErrorHandler Uses

type ErrorHandler func(resp *http.Response, err error, numTries int) (*http.Response, error)

ErrorHandler is called if retries are expired, containing the last status from the http library. If not specified, default behavior for the library is to close the body and return an error indicating how many tries were attempted. If overriding this, be sure to close the body if needed.

type LenReader Uses

type LenReader interface {
    Len() int
}

LenReader is an interface implemented by many in-memory io.Reader's. Used for automatically sending the right Content-Length header when possible.

type Logger Uses

type Logger interface {
    Printf(string, ...interface{})
}

Logger interface allows to use other loggers than standard log.Logger.

type ReaderFunc Uses

type ReaderFunc func() (io.Reader, error)

ReaderFunc is the type of function that can be given natively to NewRequest

type Request Uses

type Request struct {

    // Embed an HTTP request directly. This makes a *Request act exactly
    // like an *http.Request so that all meta methods are supported.
    *http.Request
    // contains filtered or unexported fields
}

Request wraps the metadata needed to create HTTP requests.

func FromRequest Uses

func FromRequest(r *http.Request) (*Request, error)

FromRequest wraps an http.Request in a retryablehttp.Request

func NewRequest Uses

func NewRequest(method, url string, rawBody interface{}) (*Request, error)

NewRequest creates a new wrapped request.

func (*Request) BodyBytes Uses

func (r *Request) BodyBytes() ([]byte, error)

BodyBytes allows accessing the request body. It is an analogue to http.Request's Body variable, but it returns a copy of the underlying data rather than consuming it.

This function is not thread-safe; do not call it at the same time as another call, or at the same time this request is being used with Client.Do.

func (*Request) WithContext Uses

func (r *Request) WithContext(ctx context.Context) *Request

WithContext returns wrapped Request with a shallow copy of underlying *http.Request with its context changed to ctx. The provided ctx must be non-nil.

type RequestLogHook Uses

type RequestLogHook func(Logger, *http.Request, int)

RequestLogHook allows a function to run before each retry. The HTTP request which will be made, and the retry number (0 for the initial request) are available to users. The internal logger is exposed to consumers.

type ResponseLogHook Uses

type ResponseLogHook func(Logger, *http.Response)

ResponseLogHook is like RequestLogHook, but allows running a function on each HTTP response. This function will be invoked at the end of every HTTP request executed, regardless of whether a subsequent retry needs to be performed or not. If the response body is read or closed from this method, this will affect the response returned from Do().

Package retryablehttp imports 16 packages (graph). Updated 2019-08-29. Refresh now. Tools for package owners.