Documentation
¶
Overview ¶
Package backoff provides customizable strategies for retrying operations with increasing delays.
The core of the package is the Strategy interface, which computes the next backoff duration. Implementations are stateful; the Next method returns progressively longer durations with each call. Once the retried operation is successful or abandoned, Done must be called to reset the strategy's internal state.
Usage ¶
A default exponential backoff strategy with jitter can be created using the New function. The behavior can be customized using various Option functions, such as WithMinDelay, WithMaxDelay, WithGrowthFactor, and WithJitterAmount. Jitter is added by default to prevent multiple clients from retrying in sync (the "thundering herd" problem), which can overwhelm a recovering service.
Index ¶
Constants ¶
const ( // DefaultMinDelay is the default minimum time between consecutive retries. DefaultMinDelay = 1 * time.Second // DefaultMaxDelay is the default maximum time between consecutive retries. DefaultMaxDelay = 1 * time.Minute // DefaultGrowthFactor is the default growth factor in exponential backoff. DefaultGrowthFactor float64 = 2.0 // DefaultJitterAmount is the default amount of jitter applied. DefaultJitterAmount float64 = 0.5 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*config)
Option customizes the behavior of a backoff Strategy.
func WithGrowthFactor ¶
WithGrowthFactor determines the growth factor (multiplier) for exponential backoff. A factor equal to one results in linear backoff, where the minimum delay becomes the step size. Any factor less than one is treated as one. If not customized, the DefaultGrowthFactor is used.
func WithJitterAmount ¶
WithJitterAmount specifies the amount of random jitter to apply to the backoff delays. It is expressed as a fraction of the delay, where 0 means no jitter and 1 means full jitter. The given number is capped between 0 and 1. If not customized, the DefaultJitterAmount is used.
Jitter scatters the retry attempts in time, which aims to mitigate the thundering herd problem, where many clients retry simultaneously.
func WithMaxDelay ¶
WithMaxDelay sets the maximum time between consecutive retries. It is capped at zero (meaning no delay) if a negative duration is provided. If less than or equal to the minimum delay, the backoff delays remain constant at the maximum delay. If not customized, the DefaultMaxDelay is used.
func WithMinDelay ¶
WithMinDelay sets the minimum time between consecutive retries. It is capped at zero (meaning no delay) if a negative duration is provided. If equal to or greater than the maximum delay, the backoff delays remain constant at the maximum delay. If not customized, the DefaultMinDelay is used.
When jitter is introduced, the minimum delay is effectively reduced proportional to the jitter amount. Thus, the strategy might return a delay shorter than the configured minimum delay, depending on the random output.
type Strategy ¶
type Strategy interface {
// Next returns the backoff duration for the upcoming retry attempt.
// This method is stateful and returns incrementally larger durations based
// on the number of times it has been called since the last call to Done.
// The returned duration is bounded by MinDelay() and MaxDelay().
Next() time.Duration
// Done resets the strategy's internal state, such as its attempt counter.
// This must be called after the retried operation succeeds or is abandoned.
Done()
// MinDelay returns the lower bound for the backoff duration returned by Next.
MinDelay() time.Duration
// MaxDelay returns the upper bound for the backoff duration returned by Next.
MaxDelay() time.Duration
}
Strategy defines the contract for a backoff algorithm. Implementations of this interface are expected to be safe for concurrent use.
Source Files