Documentation
¶
Overview ¶
Package retryutils defines common retry and jitter logic.
Package retryutils defines common retry and jitter logic.
Index ¶
- func DefaultJitter(d time.Duration) time.Duration
- func FullJitter(d time.Duration) time.Duration
- func HalfJitter(d time.Duration) time.Duration
- func PermanentRetryError(err error) error
- func RetryStaticFor(d time.Duration, w time.Duration, f func() error) error
- func SeventhJitter(d time.Duration) time.Duration
- func UpdateWithRetry[R any](ctx context.Context, clock clockwork.Clock, refreshFn RefreshFn[R], ...) error
- type Driver
- type Jitter
- func NewFullJitter() Jitterdeprecated
- func NewHalfJitter() Jitterdeprecated
- func NewJitter() Jitterdeprecated
- func NewSeventhJitter() Jitterdeprecated
- func NewShardedFullJitter() Jitterdeprecated
- func NewShardedHalfJitter() Jitterdeprecated
- func NewShardedSeventhJitter() Jitterdeprecated
- type Linear
- type LinearConfig
- type RefreshFn
- type Retry
- type RetryV2
- type RetryV2Config
- type UpdateFn
- type UpdateWithRetryOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultJitter ¶
DefaultJitter is a default jitter (currently HalfJitter, i.e. a jitter on the range [d/2, d), but this is subject to change).
func FullJitter ¶
FullJitter is a jitter on the range [0, d). Most use-cases are better served by a jitter with a meaningful minimum value, but if the *only* purpose of the jitter is to spread out retries to the greatest extent possible (e.g. when retrying a ConditionalUpdate operation), a full jitter may be appropriate.
func HalfJitter ¶
HalfJitter is a jitter on the range [d/2, d). This is a large range and most suitable for jittering things like backoff operations where breaking cycles quickly is a priority.
func PermanentRetryError ¶
PermanentRetryError returns a new instance of a permanent retry error.
func RetryStaticFor ¶
RetryStaticFor retries a function repeatedly for a set amount of time before returning an error.
Intended mostly for tests.
func SeventhJitter ¶
SeventhJitter returns a jitter on the range [6d/7, d). Prefer smaller jitters such as this when jittering periodic operations (e.g. cert rotation checks) since large jitters result in significantly increased load.
func UpdateWithRetry ¶
func UpdateWithRetry[R any](ctx context.Context, clock clockwork.Clock, refreshFn RefreshFn[R], updateFn UpdateFn[R], opts ...UpdateWithRetryOpt) error
UpdateWithRetry tries to conditionally update a resource, by default retrying 3 times with a 2s half jittered constant backoff in between retries. The retry configuration can be changed with the option arguments.
UpdateWithRetry will retry only if updateFn returns an error matched with trace.IsCompareFailed. It will return any other error immediately without retries.
Types ¶
type Driver ¶
type Driver interface {
// Duration calculates the step-specific delay for a given attempt. Excludes
// base duration and jitter, which are applied by the outer retry instance.
Duration(attempt int64) time.Duration
// Check verifies the correctness of any driver-internal parameters.
Check() error
}
driver is the underlying retry driver. determines the difference in behavior between linear/exponential retries.
NOTE: drivers must be stateless. If a stateful driver needs to be implemented in the future, this interface will need to be extended to support safe use of Retry.Clone.
func NewConstantDriver ¶
NewConstantDriver creates a constant retry driver with the supplied step value. Resulting retries have always the same value of the provided step.
func NewExponentialDriver ¶
NewExponentialDriver creates a new exponential retry driver with the supplied base step value. Resulting retries double their base backoff on each increment.
func NewLinearDriver ¶
NewLinearDriver creates a linear retry driver with the supplied step value. Resulting retries have increase their backoff by a fixed step amount on each increment, with the first retry having a base step amount of zero.
type Jitter ¶
Jitter is a function which applies random jitter to a duration. Used to randomize backoff values. Must be safe for concurrent usage.
func NewFullJitter
deprecated
func NewFullJitter() Jitter
NewFullJitter returns FullJitter, i.e. a jitter on the full [0, d) range.
Deprecated: use FullJitter directly instead.
func NewHalfJitter
deprecated
func NewHalfJitter() Jitter
NewHalfJitter returns HalfJitter, i.e. a jitter on the range [d/2, d).
Deprecated: use HalfJitter directly instead.
func NewJitter
deprecated
func NewJitter() Jitter
NewJitter returns a default jitter (currently HalfJitter, i.e. a jitter on the range [d/2, d), but this is subject to change).
Deprecated: use DefaultJitter directly instead.
func NewSeventhJitter
deprecated
func NewSeventhJitter() Jitter
NewSeventhJitter returns SeventhJitter, i.e. a jitter on the range [6d/7, d).
Deprecated: use SeventhJitter directly instead.
func NewShardedFullJitter
deprecated
func NewShardedFullJitter() Jitter
NewShardedFullJitter returns FullJitter, i.e. a jitter on the full [0, d) range.
Deprecated: use FullJitter directly instead.
func NewShardedHalfJitter
deprecated
func NewShardedHalfJitter() Jitter
NewShardedHalfJitter returns HalfJitter, i.e. a jitter on the range [d/2, d).
Deprecated: use HalfJitter directly instead.
func NewShardedSeventhJitter
deprecated
func NewShardedSeventhJitter() Jitter
NewShardedSeventhJitter returns SeventhJitter, i.e. a jitter on the range [6d/7, d).
Deprecated: use SeventhJitter directly instead.
type Linear ¶
type Linear struct {
// LinearConfig is a linear retry config
LinearConfig
// contains filtered or unexported fields
}
Linear is used to calculate retry period that follows the following logic: On the first error there is no delay on the next error, delay is FastLinear on all other errors, delay is SlowLinear
func NewConstant ¶
NewConstant returns a new linear retry with constant interval.
func NewLinear ¶
func NewLinear(cfg LinearConfig) (*Linear, error)
NewLinear returns a new instance of linear retry
func (*Linear) After ¶
After returns channel that fires with timeout defined in Duration method, as a special case if Duration is 0 returns a closed channel
func (*Linear) ResetToDelay ¶
func (r *Linear) ResetToDelay()
ResetToDelay resets retry period and increments the number of attempts.
type LinearConfig ¶
type LinearConfig struct {
// First is a first element of the progression,
// could be 0
First time.Duration
// Step is a step of the progression, can't be 0
Step time.Duration
// Max is a maximum value of the progression,
// can't be 0
Max time.Duration
// Jitter is an optional jitter function to be applied
// to the delay. Note that supplying a jitter means that
// successive calls to Duration may return different results.
Jitter Jitter `json:"-"`
// AutoReset, if greater than zero, causes the linear retry to automatically
// reset after Max * AutoReset has elapsed since the last call to Incr.
AutoReset int64
// Clock to override clock in tests
Clock clockwork.Clock
}
LinearConfig sets up retry configuration using arithmetic progression
func (*LinearConfig) CheckAndSetDefaults ¶
func (c *LinearConfig) CheckAndSetDefaults() error
CheckAndSetDefaults checks and sets defaults
type RefreshFn ¶
RefreshFn refreshes the resource if needed considering if this is an retry attempt or the first attempt.
type Retry ¶
type Retry interface {
// Reset resets retry state
Reset()
// Inc increments retry attempt
Inc()
// Duration returns retry duration,
// could be 0
Duration() time.Duration
// After returns time.Time channel
// that fires after Duration delay,
// could fire right away if Duration is 0
After() <-chan time.Time
// Clone creates a copy of this retry in a
// reset state.
Clone() Retry
}
Retry is an interface that provides retry logic
type RetryV2 ¶
type RetryV2 struct {
// RetryV2Config is a linear retry config
RetryV2Config
// contains filtered or unexported fields
}
RetryV2 is used to moderate the rate of retries by applying successively increasing delays. The nature of the progression is determined by the 'Driver', which generates the portion of the delay corresponding to the attempt number (e.g. Exponential(1s) might generate the sequence 0s, 1s, 2s, 4s, 8s, etc). This progression is can be modified through the use of a custom base/start value, jitters, etc.
func NewRetryV2 ¶
func NewRetryV2(cfg RetryV2Config) (*RetryV2, error)
NewRetryV2 returns a new retry instance.
type RetryV2Config ¶
type RetryV2Config struct {
// First is a first element of the progression,
// could be 0
First time.Duration
// Driver generates the underlying progression of delays. Cannot be nil.
Driver Driver
// Max is a maximum value of the progression,
// can't be 0
Max time.Duration
// Jitter is an optional jitter function to be applied
// to the delay. Note that supplying a jitter means that
// successive calls to Duration may return different results.
Jitter Jitter `json:"-"`
// AutoReset, if greater than zero, causes the linear retry to automatically
// reset after Max * AutoReset has elapsed since the last call to Incr.
AutoReset int64
// Clock to override clock in tests
Clock clockwork.Clock
}
RetryV2Config sets up retry configuration using arithmetic progression
func (*RetryV2Config) CheckAndSetDefaults ¶
func (c *RetryV2Config) CheckAndSetDefaults() error
CheckAndSetDefaults checks and sets defaults
type UpdateWithRetryOpt ¶
type UpdateWithRetryOpt func(*updateWithRetryOptions)
UpdateWithRetryOpt is the option type for UpdateWithRetry. See With* funcs in the package to see what options are available.
func WithMaxRetries ¶
func WithMaxRetries(maxRetries int) UpdateWithRetryOpt
WithMaxRetries changes the max retry attempts number from the default [updateWithRetryMaxRetries].
func WithRetryConfig ¶
func WithRetryConfig(config RetryV2Config) UpdateWithRetryOpt
WithRetryConfig changes the default retry configuration.
Source Files