Documentation
¶
Overview ¶
Package retry provides configuration-driven retry helpers built on top of `github.com/avast/retry-go/v4`.
It exposes a small retry policy model through RetryPolicyConfiguration and convenience helpers such as RetryIf and RetryOnError. It also provides a functional-option layer for composing retry policies in code.
Backoff is the practice of waiting before the next retry attempt, often with the wait time increasing after repeated failures. Backoff is useful because it reduces pressure on a failing dependency, gives remote systems time to recover, and lowers the risk of many clients retrying at once after the same outage.
References:
Exponential backoff overview: https://en.wikipedia.org/wiki/Exponential_backoff
AWS Architecture Blog, Exponential Backoff and Jitter: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
Google Cloud retry guidance: https://cloud.google.com/storage/docs/retry-strategy
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors. All rights reserved.
SPDX-License-Identifier: Apache-2.0
Index ¶
- func BackoffStrategyStrings() []string
- func RetryIf(ctx context.Context, logger logr.Logger, retryPolicy *RetryPolicyConfiguration, ...) error
- func RetryOnError(ctx context.Context, logger logr.Logger, retryPolicy *RetryPolicyConfiguration, ...) error
- type BackoffStrategy
- func (i BackoffStrategy) IsABackoffStrategy() bool
- func (i BackoffStrategy) MarshalJSON() ([]byte, error)
- func (i BackoffStrategy) MarshalText() ([]byte, error)
- func (i BackoffStrategy) MarshalYAML() (interface{}, error)
- func (i BackoffStrategy) String() string
- func (i *BackoffStrategy) UnmarshalJSON(data []byte) error
- func (i *BackoffStrategy) UnmarshalText(text []byte) error
- func (i *BackoffStrategy) UnmarshalYAML(unmarshal func(interface{}) error) error
- type RetryOption
- func WithAttempts(attempts int) RetryOption
- func WithExponentialBackoff(delay, maxDelay time.Duration) RetryOption
- func WithFixedBackoff(delay time.Duration) RetryOption
- func WithJitterStrategy(maxJitter time.Duration) RetryOption
- func WithLinearBackoff(delay, maxDelay time.Duration) RetryOption
- func WithOptions(opts ...RetryOption) RetryOption
- func WithRetryAfterEnabled() RetryOption
- func WithRetryBudget(budget time.Duration) RetryOption
- func WithRetryEnabled() RetryOption
- type RetryPolicyConfiguration
- func DefaultBasicRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultExponentialBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultFixedBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultLinearBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultNoRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultRetryPolicyConfiguration(backoffStrategy BackoffStrategy) *RetryPolicyConfiguration
- func DefaultRobustFixedBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
- func DefaultRobustRetryPolicyConfiguration() *RetryPolicyConfiguration
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BackoffStrategyStrings ¶ added in v1.165.0
func BackoffStrategyStrings() []string
BackoffStrategyStrings returns a slice of all String values of the enum
func RetryIf ¶
func RetryIf(ctx context.Context, logger logr.Logger, retryPolicy *RetryPolicyConfiguration, fn func() error, msgOnRetry string, retryConditionFn func(err error) bool) error
RetryIf retries fn while retryConditionFn reports the returned error as retriable.
The retry timing and attempt limits are controlled by retryPolicy. If the policy is disabled, fn is executed once without retrying.
func RetryOnError ¶
func RetryOnError(ctx context.Context, logger logr.Logger, retryPolicy *RetryPolicyConfiguration, fn func() error, msgOnRetry string, retriableErr ...error) error
RetryOnError retries fn when the returned error matches any of retriableErr.
The retry timing and attempt limits are controlled by retryPolicy.
Types ¶
type BackoffStrategy ¶ added in v1.165.0
type BackoffStrategy int
BackoffStrategy describes how retry delays should grow across attempts.
A backoff strategy controls whether retries happen immediately or wait before trying again, and if they wait, how that delay changes over time.
const ( // NoBackoff performs basic retries but applies no backoff strategy between // attempts. // // In practice this means retrying again immediately, subject only to the // overall retry attempt limit. NoBackoff BackoffStrategy = iota // NoBackoffButRetryAfter disables local backoff but still honours // `Retry-After` when a server provides it. NoBackoffButRetryAfter // FixedBackoff keeps the same delay for every retry and no jitter is applied. // // This is useful when a dependency benefits from a short, stable pause but // does not need progressively longer waits. FixedBackoff // FixedBackoffOrRetryAfter keeps the same delay for every retry or considers // the `Retry-After` header value if provided. FixedBackoffOrRetryAfter // LinearBackoff increases the delay linearly with the retry number. // // This is useful when retries should slow down steadily without escalating as // aggressively as exponential backoff. LinearBackoff // ExponentialBackoff doubles the delay after each retry until the max delay. // // This is useful when repeated failures should quickly reduce retry pressure // on a struggling dependency. // // Reference: https://en.wikipedia.org/wiki/Exponential_backoff ExponentialBackoff )
func BackoffStrategyString ¶ added in v1.165.0
func BackoffStrategyString(s string) (BackoffStrategy, error)
BackoffStrategyString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.
func BackoffStrategyValues ¶ added in v1.165.0
func BackoffStrategyValues() []BackoffStrategy
BackoffStrategyValues returns all values of the enum
func (BackoffStrategy) IsABackoffStrategy ¶ added in v1.165.0
func (i BackoffStrategy) IsABackoffStrategy() bool
IsABackoffStrategy returns "true" if the value is listed in the enum definition. "false" otherwise
func (BackoffStrategy) MarshalJSON ¶ added in v1.165.0
func (i BackoffStrategy) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface for BackoffStrategy
func (BackoffStrategy) MarshalText ¶ added in v1.165.0
func (i BackoffStrategy) MarshalText() ([]byte, error)
MarshalText implements the encoding.TextMarshaler interface for BackoffStrategy
func (BackoffStrategy) MarshalYAML ¶ added in v1.165.0
func (i BackoffStrategy) MarshalYAML() (interface{}, error)
MarshalYAML implements a YAML Marshaler for BackoffStrategy
func (BackoffStrategy) String ¶ added in v1.165.0
func (i BackoffStrategy) String() string
func (*BackoffStrategy) UnmarshalJSON ¶ added in v1.165.0
func (i *BackoffStrategy) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the json.Unmarshaler interface for BackoffStrategy
func (*BackoffStrategy) UnmarshalText ¶ added in v1.165.0
func (i *BackoffStrategy) UnmarshalText(text []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface for BackoffStrategy
func (*BackoffStrategy) UnmarshalYAML ¶ added in v1.165.0
func (i *BackoffStrategy) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML implements a YAML Unmarshaler for BackoffStrategy
type RetryOption ¶ added in v1.165.0
type RetryOption func(*RetryPolicyConfiguration) *RetryPolicyConfiguration
RetryOption configures a RetryPolicyConfiguration.
func WithAttempts ¶ added in v1.165.0
func WithAttempts(attempts int) RetryOption
WithAttempts limits how many total attempts are made, including the first.
This is useful for bounding retry cost and ensuring failures surface after a predictable number of tries.
func WithExponentialBackoff ¶ added in v1.165.0
func WithExponentialBackoff(delay, maxDelay time.Duration) RetryOption
WithExponentialBackoff increases retry delays exponentially, capped at maxDelay.
This is useful when repeated failures should quickly slow retry traffic to avoid overloading a struggling dependency.
Reference: https://en.wikipedia.org/wiki/Exponential_backoff
func WithFixedBackoff ¶ added in v1.165.0
func WithFixedBackoff(delay time.Duration) RetryOption
WithFixedBackoff keeps the wait time the same between retry attempts.
This is useful when a simple constant pause is sufficient and you do not want the delay to grow over time.
func WithJitterStrategy ¶ added in v1.165.0
func WithJitterStrategy(maxJitter time.Duration) RetryOption
WithJitterStrategy adds a random component to retry delays.
Jitter helps prevent many callers from retrying in lockstep, which reduces thundering-herd behaviour after a shared failure.
func WithLinearBackoff ¶ added in v1.165.0
func WithLinearBackoff(delay, maxDelay time.Duration) RetryOption
WithLinearBackoff increases the delay by a fixed step on each retry, capped at maxDelay.
This is useful when retries should back off more gently than exponential backoff while still reducing pressure on the downstream system.
func WithOptions ¶ added in v1.165.0
func WithOptions(opts ...RetryOption) RetryOption
WithOptions combines multiple retry options into a reusable composite option applied in the order supplied.
This is useful for defining named retry profiles that can be shared across callers without repeating the same option list.
func WithRetryAfterEnabled ¶ added in v1.165.0
func WithRetryAfterEnabled() RetryOption
WithRetryAfterEnabled turns retrying on and allows callers to honour `Retry-After` response headers when they are available.
This is useful for retry flows that interact with remote systems which may explicitly tell the client when to try again. `Retry-After` is an HTTP response header whose value indicates either how many seconds to wait before the next attempt or the time after which a retry is allowed, and it is commonly returned with HTTP 429 or 503 responses.
func WithRetryBudget ¶ added in v1.165.0
func WithRetryBudget(budget time.Duration) RetryOption
WithRetryBudget sets a retry budget for the policy.
A retry budget is a limit on how much time or capacity a call is allowed to spend on retries before giving up, so that retries do not grow without bound and crowd out useful work.
func WithRetryEnabled ¶ added in v1.165.0
func WithRetryEnabled() RetryOption
WithRetryEnabled turns retrying on for a policy that would otherwise execute only once.
type RetryPolicyConfiguration ¶
type RetryPolicyConfiguration struct {
// Enabled specifies whether this retry policy is enabled. If false, no retry
// is performed.
Enabled bool `mapstructure:"enabled"`
// RetryMax is the maximum number of attempts.
RetryMax int `mapstructure:"max_retry"`
// RetryAfterDisabled tells callers not to consider the `Retry-After` header (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
// returned by a server.
RetryAfterDisabled bool `mapstructure:"retry_after_disabled"`
// RetryWaitMin specifies the minimum time to wait between retries.
RetryWaitMin time.Duration `mapstructure:"min_wait"`
// RetryWaitMax is the maximum time to wait between retries. It is primarily
// used when backoff is enabled.
RetryWaitMax time.Duration `mapstructure:"max_wait"`
// RetryMaxJitter is the maximum random jitter added to retry delays.
RetryMaxJitter time.Duration `mapstructure:"max_jitter"`
// BackOffEnabled states whether backoff should be applied between retry
// attempts (by default, exponential backoff is performed unless LinearBackoff is enabled).
BackOffEnabled bool `mapstructure:"backoff_enabled"`
// LinearBackOffEnabled switches from exponential to linear backoff when
// BackOffEnabled is true.
LinearBackOffEnabled bool `mapstructure:"linear_backoff_enabled"`
}
RetryPolicyConfiguration configures retry attempts, wait timings, jitter, and backoff behaviour for the retry helpers in this package.
func DefaultBasicRetryPolicyConfiguration ¶
func DefaultBasicRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultBasicRetryPolicyConfiguration returns a basic retry configuration with four attempts but no backoff or jitter.
func DefaultExponentialBackoffRetryPolicyConfiguration ¶
func DefaultExponentialBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultExponentialBackoffRetryPolicyConfiguration returns a configuration for retries with exponential backoff.
func DefaultFixedBackoffRetryPolicyConfiguration ¶ added in v1.165.0
func DefaultFixedBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultFixedBackoffRetryPolicyConfiguration returns a retry configuration with four attempts and fixed backoff.
func DefaultLinearBackoffRetryPolicyConfiguration ¶
func DefaultLinearBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultLinearBackoffRetryPolicyConfiguration returns a configuration for retries with linear backoff.
func DefaultNoRetryPolicyConfiguration ¶
func DefaultNoRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultNoRetryPolicyConfiguration returns a configuration with retries disabled.
func DefaultRetryPolicyConfiguration ¶ added in v1.165.0
func DefaultRetryPolicyConfiguration(backoffStrategy BackoffStrategy) *RetryPolicyConfiguration
DefaultRetryPolicyConfiguration returns the package's default retry policy for the selected backoff strategy.
func DefaultRobustFixedBackoffRetryPolicyConfiguration ¶ added in v1.165.0
func DefaultRobustFixedBackoffRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultRobustFixedBackoffRetryPolicyConfiguration returns a retry configuration with four attempts and fixed backoff that also honours `Retry-After`.
func DefaultRobustRetryPolicyConfiguration ¶
func DefaultRobustRetryPolicyConfiguration() *RetryPolicyConfiguration
DefaultRobustRetryPolicyConfiguration returns a basic retry configuration that also honours `Retry-After`.
func (*RetryPolicyConfiguration) Validate ¶
func (cfg *RetryPolicyConfiguration) Validate() error
Validate validates the retry policy configuration.
Source Files