retry

README

retry

An expressive, flexible retry package for Go.

Features

• Any combination of:
  • Exponential backoff
  • Jitter
  • Bound to context
  • Bound to timeout
  • Limit total number of attempts
  • Retry only on certain kinds of errors
    • Defaults to retrying on all errors
• Retrying net.Listener wrapper

Examples

This code will succeed after about a second.

start := time.Now()

err := retry.New(time.Millisecond).
    Backoff(time.Millisecond * 50).
    Timeout(time.Second * 2).
    Run(
        func() error {
            if time.Since(start) < time.Second {
                return errors.New("not enough time has elapsed")
            }
            return nil
        },
    )
fmt.Printf("err: %v, took %v\n", err, time.Since(start))

---

This code will block forever, since no Timeout or Context option was provided.

start := time.Now()

err := retry.New(time.Millisecond).
    Backoff(time.Millisecond * 50).
    Run(
        func() error {
            return errors.New("not enough time has elapsed")
        },
    )
fmt.Printf("err: %v, took %v\n", err, time.Since(start))

---

This code will sleep anywhere from 500ms to 1.5s between attempts.

The attempts condition will fail before the timeout. It will return the not enough time... error after 2.5 to 7.5 seconds.

start := time.Now()

err := retry.New(time.Second).
    Jitter(0.5).
    Timeout(time.Second * 10).
    Attempts(5).
    Run(
        func() error {
            return errors.New("not enough time has elapsed")
        },
    )
fmt.Printf("err: %v, took %v\n", err, time.Since(start))

Documentation

Overview

Package retry contains utilities for retrying an action until it succeeds.

Index

• type Condition
  • func NotOnErrors(errs ...error) Condition
  • func OnErrors(errs ...error) Condition
• type Listener
  • func (l *Listener) Accept() (net.Conn, error)
• type Retry
  • func New(sleep time.Duration) *Retry
  • func (r *Retry) Attempts(n int) *Retry
  • func (r *Retry) Backoff(ceil time.Duration) *Retry
  • func (r *Retry) Condition(fn Condition) *Retry
  • func (r *Retry) Conditions(fns ...Condition) *Retry
  • func (r *Retry) Context(ctx context.Context) *Retry
  • func (r *Retry) Jitter(rat float64) *Retry
  • func (r *Retry) Log(logFn func(error)) *Retry
  • func (r *Retry) Run(fn func() error) error
  • func (r *Retry) Timeout(to time.Duration) *Retry

Types

type Condition

type Condition func(error) bool

Condition is a function that decides based on the given error whether to retry.

func NotOnErrors

func NotOnErrors(errs ...error) Condition

NotOnErrors returns a condition which retries only if the error does not match one of the provided errors.

func OnErrors

func OnErrors(errs ...error) Condition

OnErrors returns a condition which retries on one of the provided errors.

type Listener

type Listener struct {
	LogTmpErr func(err error)
	net.Listener
}

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

type Retry

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

Retry holds state about a retryable operation. Callers should create this via New.

func New

func New(sleep time.Duration) *Retry

New creates a new retry. The default retry will run forever, sleeping sleep.

func (*Retry) Attempts

func (r *Retry) Attempts(n int) *Retry

Attempts sets the maximum amount of retry attempts before the current error is returned.

func (*Retry) Backoff

func (r *Retry) Backoff(ceil time.Duration) *Retry

Backoff turns retry into an exponential backoff with a maximum sleep of ceil.

func (*Retry) Condition

func (r *Retry) Condition(fn Condition) *Retry

Condition appends the passed retry condition. The condition must return true for the retry to progress. Deprecated: Use Conditions instead.

func (*Retry) Conditions

func (r *Retry) Conditions(fns ...Condition) *Retry

Condition appends the passed retry conditions. All conditions must return true for the retry to progress.

func (*Retry) Context

func (r *Retry) Context(ctx context.Context) *Retry

Context bounds the retry to when the context expires.

func (*Retry) Jitter

func (r *Retry) Jitter(rat float64) *Retry

Jitter adds some random jitter to the retry's sleep.

Ratio must be between 0 and 1, and determines how jittery the sleeps will be. For example, a rat of 0.1 and a sleep of 1s restricts the jitter to the range of 900ms to 1.1 seconds.

func (*Retry) Log

func (r *Retry) Log(logFn func(error)) *Retry

Log adds a function to log any returned errors. It is added as a post condition that always returns true. If you want an error to stop the retry and not be logged, use Log() after the Condition. If you want an error to stop the retry and be logged, use Log() before the Condition.

func (*Retry) Run

func (r *Retry) Run(fn func() error) error

Run runs the retry. The retry must not be ran twice.

func (*Retry) Timeout

func (r *Retry) Timeout(to time.Duration) *Retry

Timeout returns the retry with a bounding timeout. If the passed timeout is 0, Timeout does nothing. This has been done to match the behaviour of the previous retry API and to make it easy for functions that call into retry to offer optional timeouts.