README
¶
Retrigo - Very simple http retriable client
Retrigo is a very striped down version of the hashicorp/go-retryablehttp, it implements the familiar HTTP package with automatic retries and backoff method.
Usage
Using default client
c := retrigo.NewClient()
resp, err := c.Post("http://localhost", "text/plain", bytes.NewReader([]byte{}))
...
Setting all parameters
c := retrigo.Client{
HTTPClient: &http.Client{
Timeout: 10 * time.Second,
},
Logger: retrigo.DefaultLogger,
RetryWaitMin: 20 * time.Millisecond,
RetryWaitMax: 10 * time.Second,
RetryMax: 5,
CheckForRetry: retrigo.DefaultRetryPolicy,
Backoff: retrigo.DefaultBackoff,
Scheduler: retrigo.DefaultScheduler,
}
resp, err := c.Get("http://localhost")
...
Setting some parameters
c := retrigo.NewClient()
c.RetryWaitMin = 20 * time.Millisecond
c.RetryWaitMax = 10 * time.Second
c.Backoff = retrigo.LinearJitterBackoff
resp, err := c.Get("http://localhost")
...
Without creating a client
resp, err := retrigo.Get("http://localhost")
...
Multiple targets
The url parameter (e. g., c.Get("URL")) can be one url or a space separated list of urls that the library will choose as target (e. g., "URL1 URL2 URL3"). The default Scheduler() will round-robin around all urls of the list, you can implement other scheduling strategies by defining your own Scheduler() e.g.:
c := retrigo.NewClient()
c.Scheduler = func(servers []string, j int) (string, int) {
...
}
Logging
The Logger() function defines the logging methods/format, this function will receive a severity, a message and a error struct.
Documentation
¶
Overview ¶
Package retrigo provides a familiar HTTP client interface with automatic retries and exponential backoff and multiple target scheduling. It is a thin wrapper over the standard net/http client library and exposes nearly the same public API. This makes retrigo very easy to drop into existing programs.
retrigo 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 ¶
- Variables
- func DefaultBackoff(min, max time.Duration, attempt int, r *http.Response) time.Duration
- func DefaultLogger(req *Request, mtype, msg string, err error)
- func DefaultRetryPolicy(ctx context.Context, r *http.Response, err error) (bool, error)
- func DefaultScheduler(servers []string, j int) (string, int)
- func Delete(url, bodyType string, body interface{}) (*http.Response, error)
- func Get(url string) (*http.Response, error)
- func Head(url string) (*http.Response, error)
- func LinearJitterBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration
- func Patch(url, bodyType string, body interface{}) (*http.Response, error)
- func Post(url, bodyType string, body interface{}) (*http.Response, error)
- func PostForm(url string, data url.Values) (*http.Response, error)
- func Put(url, bodyType string, body interface{}) (*http.Response, error)
- type Backoff
- type CheckForRetry
- type Client
- func (c *Client) Delete(durl string, bodyType string, body interface{}) (*http.Response, error)
- func (c *Client) Do(req *Request) (*http.Response, error)
- func (c *Client) Get(durl string) (*http.Response, error)
- func (c *Client) Head(durl string) (*http.Response, error)
- func (c *Client) Patch(durl string, bodyType string, body interface{}) (*http.Response, error)
- func (c *Client) Post(durl, bodyType string, body interface{}) (*http.Response, error)
- func (c *Client) PostForm(url string, data url.Values) (*http.Response, error)
- func (c *Client) Put(durl, bodyType string, body interface{}) (*http.Response, error)
- type LenReader
- type Logger
- type ReaderFunc
- type Request
- type Scheduler
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultRetryWaitMin is the default minimum wait time DefaultRetryWaitMin = 1 * time.Second // DefaultRetryWaitMax is the default maximum wait time DefaultRetryWaitMax = 30 * time.Second // DefaultRetryMax is the default maximum retries DefaultRetryMax = 10 // FirstTarget in the first index that is going to be used when trying // to reach the target url from the urls slice FirstTarget = 0 )
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 DefaultLogger ¶
DefaultLogger is a simple logger
func DefaultRetryPolicy ¶
DefaultRetryPolicy provides a default callback for Client.CheckRetry, which will retry on connection errors and server errors.
func DefaultScheduler ¶
DefaultScheduler round-robins a list of urls from servers
func LinearJitterBackoff ¶
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 multiplied 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, ...)
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 CheckForRetry ¶
CheckForRetry is called following each request, it receives the http.Response and error and returns a bool and a error
type Client ¶
type Client struct {
HTTPClient *http.Client // Internal HTTP client.
RetryWaitMin time.Duration // Minimum time to wait
RetryWaitMax time.Duration // Maximum time to wait
RetryMax int // Maximum number of retries
// CheckForRetry specifies the policy for handling retries, and is called
// after each request. The default policy is DefaultRetryPolicy.
CheckForRetry CheckForRetry
Backoff Backoff // Backoff specifies the policy for how long to wait between retries
Logger Logger // Customer logger instance.
// Scheduler specifies a the which of the supplied targets should be used next, it's called
// before each request. The default Scheduler is DefaultScheduler
Scheduler Scheduler
}
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 ReaderFunc ¶
ReaderFunc is the type of function that can be given natively to NewRequest
type Request ¶
Request wraps the metadata needed to create HTTP requests.
func FromRequest ¶
FromRequest wraps an http.Request in a retryablehttp.Request
func NewRequest ¶
NewRequest create a wrapped request
Source Files