README
¶
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 code is received, then a retry is invoked after a wait period.
Otherwise, the response is returned and left to the caller to interpret.
The main difference from net/http is that requests which take a request body
(POST/PUT et. al) require an io.ReadSeeker to be provided. This enables the
request body to be "rewound" if the initial request fails so that the full
request can be attempted again.
Example Use
Using this library should look almost identical to what you would do with
net/http. The most simple example of a GET request is shown below:
resp, err := retryablehttp.Get("/foo")
if err != nil {
panic(err)
}
The returned response object is an *http.Response, the same thing you would
usually get from net/http. Had the request failed one or more times, the above
call would block and retry with exponential backoff.
For more usage and examples see the godoc.
Documentation
¶
Overview ¶
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.
The main difference from net/http is that requests which take a request body (POST/PUT et. al) require an io.ReadSeeker to be provided. This enables the request body to be "rewound" if the initial request fails so that the full request can be attempted again.
Index ¶
- func DefaultBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration
- func DefaultClient(c *Client)
- func DefaultRetryPolicy(resp *http.Response, err error) (bool, error)
- func Get(url string) (*http.Response, error)
- func Head(url string) (*http.Response, error)
- func Post(url, bodyType string, body io.ReadSeeker) (*http.Response, error)
- func PostForm(url string, data url.Values) (*http.Response, error)
- type Backoff
- type CheckRetry
- type Client
- func (c *Client) Do(req *Request) (*http.Response, error)
- func (c *Client) Get(url string) (*http.Response, error)
- func (c *Client) Head(url string) (*http.Response, error)
- func (c *Client) Post(url, bodyType string, body io.ReadSeeker) (*http.Response, error)
- func (c *Client) PostForm(url string, data url.Values) (*http.Response, error)
- type LenReader
- type Request
- type RequestLogHook
- type ResponseLogHook
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultBackoff ¶
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 DefaultClient ¶
func DefaultClient(c *Client)
DefaultClient allows you to set the client so your code can call retryablehttp.Post and friends with your settings.
func DefaultRetryPolicy ¶
DefaultRetryPolicy provides a default callback for Client.CheckRetry, which will retry on connection errors and server errors.
Types ¶
type Backoff ¶
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 ¶
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 ¶
type Client struct {
HTTPClient *http.Client // Internal HTTP client.
Logger *log.Logger // Customer logger instance.
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
}
Client is used to make HTTP requests. It adds additional functionality like automatic retries to tolerate minor outages.
type LenReader ¶
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 Request ¶
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 NewRequest ¶
func NewRequest(method, url string, body io.ReadSeeker) (*Request, error)
NewRequest creates a new wrapped request.
type RequestLogHook ¶
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 ¶
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().
Source Files