retrypolicy

Documentation

Overview

Package retrypolicy provides a RetryPolicy.

Index

• Variables
• type ExceededError
  • func (e *ExceededError) Error() string
  • func (e *ExceededError) Is(err error) bool
  • func (e *ExceededError) LastError() error
  • func (e *ExceededError) LastResult() any
  • func (e *ExceededError) Unwrap() error
• type RetryPolicy
  • func WithDefaults[R any]() RetryPolicy[R]
• type RetryPolicyBuilder
  • func Builder[R any]() RetryPolicyBuilder[R]

Variables

var ErrExceeded = &ExceededError{}

ErrExceeded is an empty ExceededError instance, useful for building policies that want to handle this error.

Types

type ExceededError

type ExceededError struct {
	// contains filtered or unexported fields
}

ExceededError is returned when a RetryPolicy's max attempts or max duration are exceeded.

func (*ExceededError) Error

func (e *ExceededError) Error() string

func (*ExceededError) Is

func (e *ExceededError) Is(err error) bool

Is returns whether err is of the type ExceededError.

func (*ExceededError) LastError

func (e *ExceededError) LastError() error

LastError returns the last error that caused the ExceededError.

func (*ExceededError) LastResult

func (e *ExceededError) LastResult() any

LastResult returns the last result that caused the ExceededError.

func (*ExceededError) Unwrap

func (e *ExceededError) Unwrap() error

type RetryPolicy

type RetryPolicy[R any] interface {
	failsafe.Policy[R]
}

RetryPolicy is a policy that defines when retries should be performed. See RetryPolicyBuilder for configuration options.

This type is concurrency safe.

func WithDefaults

func WithDefaults[R any]() RetryPolicy[R]

WithDefaults creates a RetryPolicy for execution result type R that allows 3 execution attempts max with no delay. To configure additional options on a RetryPolicy, use Builder instead.

type RetryPolicyBuilder

type RetryPolicyBuilder[R any] interface {
	failsafe.FailurePolicyBuilder[RetryPolicyBuilder[R], R]
	failsafe.DelayablePolicyBuilder[RetryPolicyBuilder[R], R]

	// AbortOnResult specifies that retries should be aborted if the execution result matches the result using
	// reflect.DeepEqual.
	AbortOnResult(result R) RetryPolicyBuilder[R]

	// AbortOnErrors specifies that retries should be aborted if the execution error matches any of the errs using errors.Is.
	AbortOnErrors(errs ...error) RetryPolicyBuilder[R]

	// AbortIf specifies that retries should be aborted if the predicate matches the result or error.
	AbortIf(predicate func(R, error) bool) RetryPolicyBuilder[R]

	// ReturnLastFailure configures the policy to return the last failure result or error after attempts are exceeded,
	// rather than returning ExceededError.
	ReturnLastFailure() RetryPolicyBuilder[R]

	// WithMaxAttempts sets the max number of execution attempts to perform. -1 indicates no limit. This method has the same
	// effect as setting 1 more than WithMaxRetries. For example, 2 retries equal 3 attempts.
	WithMaxAttempts(maxAttempts int) RetryPolicyBuilder[R]

	// WithMaxRetries sets the max number of retries to perform when an execution attempt fails. -1 indicates no limit. This
	// method has the same effect as setting 1 less than WithMaxAttempts. For example, 2 retries equal 3 attempts.
	WithMaxRetries(maxRetries int) RetryPolicyBuilder[R]

	// WithMaxDuration sets the max duration to perform retries for, else the execution will be failed.
	WithMaxDuration(maxDuration time.Duration) RetryPolicyBuilder[R]

	// WithBackoff wets the delay between retries, exponentially backing off to the maxDelay and multiplying consecutive
	// delays by a factor of 2. Replaces any previously configured fixed or random delays.
	WithBackoff(delay time.Duration, maxDelay time.Duration) RetryPolicyBuilder[R]

	// WithBackoffFactor sets the delay between retries, exponentially backing off to the maxDelay and multiplying
	// consecutive delays by the delayFactor. Replaces any previously configured fixed or random delays.
	WithBackoffFactor(delay time.Duration, maxDelay time.Duration, delayFactor float32) RetryPolicyBuilder[R]

	// WithRandomDelay sets a random delay between the delayMin and delayMax (inclusive) to occur between retries.
	// Replaces any previously configured delay or backoff delay.
	WithRandomDelay(delayMin time.Duration, delayMax time.Duration) RetryPolicyBuilder[R]

	// WithJitter sets the jitter to randomly vary retry delays by. For each retry delay, a random portion of the jitter will
	// be added or subtracted to the delay. For example: a jitter of 100 milliseconds will randomly add between -100 and 100
	// milliseconds to each retry delay. Replaces any previously configured jitter factor.
	//
	// Jitter should be combined with fixed, random, or exponential backoff delays. If no delays are configured, this setting
	// is ignored.
	WithJitter(jitter time.Duration) RetryPolicyBuilder[R]

	// WithJitterFactor sets the jitterFactor to randomly vary retry delays by. For each retry delay, a random portion of the
	// delay multiplied by the jitterFactor will be added or subtracted to the delay. For example: a retry delay of 100
	// milliseconds and a jitterFactor of .25 will result in a random retry delay between 75 and 125 milliseconds. Replaces
	// any previously configured jitter duration.
	//
	// Jitter should be combined with fixed, random, or exponential backoff delays. If no delays are configured, this setting
	// is ignored.
	WithJitterFactor(jitterFactor float32) RetryPolicyBuilder[R]

	// OnAbort registers the listener to be called when an execution is aborted.
	OnAbort(listener func(failsafe.ExecutionEvent[R])) RetryPolicyBuilder[R]

	// OnRetryScheduled registers the listener to be called when a retry is about to be scheduled. This method differs from
	// OnRetry since it is called when a retry is initially scheduled but before any configured delay, whereas OnRetry is
	// called after a delay, just before the retry attempt takes place.
	OnRetryScheduled(listener func(failsafe.ExecutionScheduledEvent[R])) RetryPolicyBuilder[R]

	// OnRetry registers the listener to be called when a retry is about to be attempted.
	OnRetry(listener func(failsafe.ExecutionEvent[R])) RetryPolicyBuilder[R]

	// OnRetriesExceeded registers the listener to be called when an execution fails and the max retry attempts or max
	// duration are exceeded. The provided event will contain the last execution result and error.
	OnRetriesExceeded(listener func(failsafe.ExecutionEvent[R])) RetryPolicyBuilder[R]

	// Build returns a new RetryPolicy using the builder's configuration.
	Build() RetryPolicy[R]
}

RetryPolicyBuilder builds RetryPolicy instances.

• By default, a RetryPolicy will retry a failed execution up to 2 times when any error is returned, with no delay between retry attempts. If retries are exceeded, ExceededError is returned by default. Alternatively, ReturnLastFailure can be used to configure the policy to return the last execution failure.
• You can change the default number of retry attempts and delay between retries by using the with configuration methods.
• By default, any error is considered a failure and will be handled by the policy. You can override this by specifying your own HandleErrors conditions. The default error handling condition will only be overridden by another condition that handles error such as HandleErrors or HandleIf. Specifying a condition that only handles results, such as HandleResult or HandleResultIf will not replace the default error handling condition.
• If multiple HandleErrors conditions are specified, any condition that matches an execution result or error will trigger policy handling.
• The AbortOn, AbortWhen and AbortIf methods describe when retries should be aborted.

This class extends failsafe.FailurePolicyBuilder and failsafe.DelayablePolicyBuilder which offer additional configuration.

This type is not concurrency safe.

func Builder

func Builder[R any]() RetryPolicyBuilder[R]

Builder creates a RetryPolicyBuilder for execution result type R, which by default will build a RetryPolicy that allows 3 execution attempts max with no delay, unless configured otherwise.