Documentation
¶
Overview ¶
Package retry provides flexible policies for retrying failed attempts during an HTTP request plan execution, and how long to wait before retrying.
The interface Policy defines a retry Policy. A Policy instance can be constructed using NewPolicy by providing a decision-maker, Decider, and a wait time calculator, Waiter. Both Decider and Waiter have constructors for common use cases, so that a useful policy can be quickly assembled:
decider := retry.Times(3).
And(retry.Before(5 * time.Second)).
And(retry.StatusCode(500).Or(retry.TransientErr))
waiter := retry.NewExpWaiter{100 * time.Millisecond, 2 * time.Second}
policy := retry.NewPolicy(d, w)
If the built-in functionality is insufficient, fully custom retry policies can be created by via custom implementations of Decider, Waiter, or Policy.
Index ¶
Constants ¶
const DefaultTimes = 5
DefaultTimes is the number of times DefaultPolicy will retry.
Variables ¶
var DefaultDecider = Times(DefaultTimes).And(StatusCode(429, 502, 503, 504).Or(TransientErr))
DefaultDecider is a general-purpose retry decider suitable for common use cases. It will allow up to DefaultTimes retries (i.e. up to 6 total attempts), and will retry in the case of a transient error (TransientErr) or if a valid HTTP response is received, but it contains one of the following status codes: 429 (Too Many Requests); 502 (Bad Gateway); 503 (Service Unavailable); or 504 (Gateway Timeout).
var DefaultWaiter = NewExpWaiter(50*time.Millisecond, 1*time.Second, time.Now())
DefaultWaiter is the default retry wait policy. It uses a jittered exponential backoff formula with a base wait of 50 milliseconds and a maximum wait of 1 second.
Functions ¶
This section is empty.
Types ¶
type Decider ¶
A Decider decides if a retry should be done.
Implementations of Decider must be safe for concurrent use by multiple goroutines.
Use the built-in constructors Times, StatusCode, and Before, and the built-in decider TransientErr; or implement your Decider. Use DeciderFunc to convert an ordinary function into a Decider, and to compose deciders logically using DeciderFunc.And and DeciderFunc.Or.
type DeciderFunc ¶
The DeciderFunc type is an adapter to allow the use of ordinary functions as retry deciders. It implements the Decider interface, and also provides the logical composition methods And and Or.
Every DeciderFunc must be safe for concurrent use by multiple goroutines.
Simple DeciderFunc functions can be composed into complex decision trees using the logical composition functions DeciderFunc.And and DeciderFunc.Or. Because of this composition ability, it will often be convenient to work directly with DeciderFunc rather than with Decider.
var TransientErr DeciderFunc = transientErr
TransientErr is a decider that indicates a retry if the current error is transient according to transient.Categorize.
TransientErr only looks at the error, so it will always return false if a valid HTTP response is returned. Compose it with other deciders, for example a status code decider constructed with StatusCode, to get more complex functionality.
func Before ¶
func Before(d time.Duration) DeciderFunc
Before constructs a retry decider allowing retries until a certain amount of time has elapsed since the start of the logical HTTP request plan execution. The returned decider returns true while the execution duration is less than d, and false afterward.
func StatusCode ¶
func StatusCode(ss ...int) DeciderFunc
StatusCode constructs a retry decider allowing retries based on the HTTP response status code. If the most recent request attempt within the plan execution received a valid HTTP response, and the response status code is contained in the list ss, the decider returns true. Otherwise, it returns false.
func Times ¶
func Times(n int) DeciderFunc
Times constructs a retry decider which allows up to n retries. The returned decider returns true while the number of finished attempts within the execution is less than or equal to n, and false otherwise.
func (DeciderFunc) And ¶
func (f DeciderFunc) And(g DeciderFunc) DeciderFunc
And composes two retry deciders into a new decider which returns true if both sub-deciders return true, and false otherwise.
Short-circuit logic is used, so g will not be evaluated if f returns false.
func (DeciderFunc) Decide ¶
func (f DeciderFunc) Decide(e *request.Execution) bool
Decide returns true if a retry should be done, and false otherwise, after examining the current HTTP request plan execution state.
func (DeciderFunc) Or ¶
func (f DeciderFunc) Or(g DeciderFunc) DeciderFunc
Or composes two retry deciders into a new decider which returns true if either of the two sub-deciders returns true, but false if they both return false.
Short-circuit logic is used, so g will not be evaluated if f returns true.
type Policy ¶
A Policy controls if and how retries are done in an HTTP request plan execution. In particular, after every attempt during the HTTP request plan execution, a Policy decides whether a retry should be done and, if so, how long the wait period should be before retrying the attempt.
Implementations of Policy must be safe for concurrent use by multiple goroutines.
A Policy is composed of the Decider and Waiter interfaces. While you can implement Policy yourself, it may be more efficient to use one of the built-in retry policies, DefaultPolicy or Never, or to construct your policy using the NewPolicy constructor using existing Decider and Waiter implementations.
var DefaultPolicy Policy = policy{DefaultDecider, DefaultWaiter}
DefaultPolicy is a general-purpose retry policy suitable for common use cases. It is a composition of DefaultDecider for retry decisions and DefaultWaiter for wait time calculations.
var Never Policy = policy{Times(0), DefaultWaiter}
Never is a policy that never retries. It is useful if you want to use the other features of httpx.Client but do not want retries.
type Waiter ¶
A Waiter specifies how long to wait before retrying a failed HTTP request attempt.
Implementations of Waiter must be safe for concurrent use by multiple goroutines.
The robust HTTP client, httpx.Client, will not call the Waiter on a retry policy if the policy Decider returned false.
This package provides one Waiter implementations, using the constructor function NewExpWaiter. In addition it provides a concrete instance suitable for many typical use cases, DefaultWaiter.
func NewExpWaiter ¶
NewExpWaiter constructs a Waiter implementing an exponential backoff formula with optional jitter.
The formula implemented is the "Full Jitter" approach described in: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter.
Parameters base and max control the exponential calculation of the ceiling:
ceil := max(base * 2**attempt, max)
Base and max must be positive values, and max must be at least equal to base.
Parameter jitter is used to generate a random number between 0 and ceil. To make a waiter that does not jitter and simply returns ceil on each attempt, pass nil for jitter. Otherwise you may specify either a random number generator seed value (as a time.Time, int, or int64) or a random number generator (as a rand.Source). If a seed value is specified, it is used to seed a random number generator for calculating jitter. If a rand.Source is specified, it is used to calculate jitter.
func NewFixedWaiter ¶ added in v1.1.0
NewFixedWaiter constructs a Waiter that always returns the given duration.
Use NewFixedWaiter to obtain a constant retry backoff.
Source Files