README

retrier

Build Status GoDoc Code of Conduct

The retriable resiliency pattern for golang.

Creating a retrier takes two parameters:

  • the times to back-off between retries (and implicitly the number of times to retry)
  • the classifier that determines which errors to retry
r := retrier.New(retrier.ConstantBackoff(3, 100*time.Millisecond), nil)

err := r.Run(func() error {
	// do some work
	return nil
})

if err != nil {
	// handle the case where the work failed three times
}
Expand ▾ Collapse ▴

Documentation

Overview

    Package retrier implements the "retriable" resiliency pattern for Go.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func ConstantBackoff

    func ConstantBackoff(n int, amount time.Duration) []time.Duration

      ConstantBackoff generates a simple back-off strategy of retrying 'n' times, and waiting 'amount' time after each one.

      func ExponentialBackoff

      func ExponentialBackoff(n int, initialAmount time.Duration) []time.Duration

        ExponentialBackoff generates a simple back-off strategy of retrying 'n' times, and doubling the amount of time waited after each one.

        Types

        type Action

        type Action int

          Action is the type returned by a Classifier to indicate how the Retrier should proceed.

          const (
          	Succeed Action = iota // Succeed indicates the Retrier should treat this value as a success.
          	Fail                  // Fail indicates the Retrier should treat this value as a hard failure and not retry.
          	Retry                 // Retry indicates the Retrier should treat this value as a soft failure and retry.
          )

          type BlacklistClassifier

          type BlacklistClassifier []error

            BlacklistClassifier classifies errors based on a blacklist. If the error is nil, it returns Succeed; if the error is in the blacklist, it returns Fail; otherwise, it returns Retry.

            func (BlacklistClassifier) Classify

            func (list BlacklistClassifier) Classify(err error) Action

              Classify implements the Classifier interface.

              type Classifier

              type Classifier interface {
              	Classify(error) Action
              }

                Classifier is the interface implemented by anything that can classify Errors for a Retrier.

                type DefaultClassifier

                type DefaultClassifier struct{}

                  DefaultClassifier classifies errors in the simplest way possible. If the error is nil, it returns Succeed, otherwise it returns Retry.

                  func (DefaultClassifier) Classify

                  func (c DefaultClassifier) Classify(err error) Action

                    Classify implements the Classifier interface.

                    type Retrier

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

                      Retrier implements the "retriable" resiliency pattern, abstracting out the process of retrying a failed action a certain number of times with an optional back-off between each retry.

                      Example
                      Output:
                      
                      

                      func New

                      func New(backoff []time.Duration, class Classifier) *Retrier

                        New constructs a Retrier with the given backoff pattern and classifier. The length of the backoff pattern indicates how many times an action will be retried, and the value at each index indicates the amount of time waited before each subsequent retry. The classifier is used to determine which errors should be retried and which should cause the retrier to fail fast. The DefaultClassifier is used if nil is passed.

                        func (*Retrier) Run

                        func (r *Retrier) Run(work func() error) error

                          Run executes the given work function by executing RunCtx without context.Context.

                          func (*Retrier) RunCtx

                          func (r *Retrier) RunCtx(ctx context.Context, work func(ctx context.Context) error) error

                            RunCtx executes the given work function, then classifies its return value based on the classifier used to construct the Retrier. If the result is Succeed or Fail, the return value of the work function is returned to the caller. If the result is Retry, then Run sleeps according to the its backoff policy before retrying. If the total number of retries is exceeded then the return value of the work function is returned to the caller regardless.

                            func (*Retrier) SetJitter

                            func (r *Retrier) SetJitter(jit float64)

                              SetJitter sets the amount of jitter on each back-off to a factor between 0.0 and 1.0 (values outside this range are silently ignored). When a retry occurs, the back-off is adjusted by a random amount up to this value.

                              type WhitelistClassifier

                              type WhitelistClassifier []error

                                WhitelistClassifier classifies errors based on a whitelist. If the error is nil, it returns Succeed; if the error is in the whitelist, it returns Retry; otherwise, it returns Fail.

                                func (WhitelistClassifier) Classify

                                func (list WhitelistClassifier) Classify(err error) Action

                                  Classify implements the Classifier interface.