README.md

Documentation: github.com/hashicorp/go-retryablehttp

     1go-retryablehttp
     2================
     3
     4[![Build Status](http://img.shields.io/travis/hashicorp/go-retryablehttp.svg?style=flat-square)][travis]
     5[![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)][godocs]
     6
     7[travis]: http://travis-ci.org/hashicorp/go-retryablehttp
     8[godocs]: http://godoc.org/github.com/hashicorp/go-retryablehttp
     9
    10The `retryablehttp` package provides a familiar HTTP client interface with
    11automatic retries and exponential backoff. It is a thin wrapper over the
    12standard `net/http` client library and exposes nearly the same public API. This
    13makes `retryablehttp` very easy to drop into existing programs.
    14
    15`retryablehttp` performs automatic retries under certain conditions. Mainly, if
    16an error is returned by the client (connection errors, etc.), or if a 500-range
    17response code is received (except 501), then a retry is invoked after a wait
    18period.  Otherwise, the response is returned and left to the caller to
    19interpret.
    20
    21The main difference from `net/http` is that requests which take a request body
    22(POST/PUT et. al) can have the body provided in a number of ways (some more or
    23less efficient) that allow "rewinding" the request body if the initial request
    24fails so that the full request can be attempted again. See the
    25[godoc](http://godoc.org/github.com/hashicorp/go-retryablehttp) for more
    26details.
    27
    28Version 0.6.0 and before are compatible with Go prior to 1.12. From 0.6.1 onward, Go 1.12+ is required.
    29From 0.6.7 onward, Go 1.13+ is required.
    30
    31Example Use
    32===========
    33
    34Using this library should look almost identical to what you would do with
    35`net/http`. The most simple example of a GET request is shown below:
    36
    37```go
    38resp, err := retryablehttp.Get("/foo")
    39if err != nil {
    40    panic(err)
    41}
    42```
    43
    44The returned response object is an `*http.Response`, the same thing you would
    45usually get from `net/http`. Had the request failed one or more times, the above
    46call would block and retry with exponential backoff.
    47
    48## Getting a stdlib `*http.Client` with retries
    49
    50It's possible to convert a `*retryablehttp.Client` directly to a `*http.Client`.
    51This makes use of retryablehttp broadly applicable with minimal effort. Simply
    52configure a `*retryablehttp.Client` as you wish, and then call `StandardClient()`:
    53
    54```go
    55retryClient := retryablehttp.NewClient()
    56retryClient.RetryMax = 10
    57
    58standardClient := retryClient.StandardClient() // *http.Client
    59```
    60
    61For more usage and examples see the
    62[godoc](http://godoc.org/github.com/hashicorp/go-retryablehttp).
View as plain text