again

README

go-again

go-again thread safely wraps a given function and executes it until it returns a nil error or exceeds the maximum number of retries. The configuration consists of the maximum number of retries, the interval, a jitter to add a randomized backoff, the timeout, and a registry to store errors that you consider temporary, hence worth a retry. The Retry method takes a context, a function, and an optional list of temporary errors as arguments. It supports cancellation from the context and a channel invoking the Cancel() function. The registry only allows you to retry a function if it returns a registered error:

    retrier := again.NewRetrier(3, time.Millisecond*10, time.Second, time.Second)
    retrier.Registry.RegisterTemporaryError("http.ErrAbortHandler", func() ITemporaryError {
        return http.ErrAbortHandler
    })

    defer retrier.Registry.UnRegisterTemporaryError("http.ErrAbortHandler")
    var retryCount int
    err := retrier.Retry(context.TODO(), func() error {
        retryCount++
        if retryCount < 3 {
            return http.ErrAbortHandler
        }
        return nil
    }, "http.ErrAbortHandler")

    if err != nil {
        // handle error
    }

Should you retry regardless of the error returned, that's easy. It's enough calling the Retry function without passing a plausible set of registered error names:

    var retryCount int
    retrier := again.NewRetrier(3, time.Millisecond*10, time.Second, time.Second)
    err := retrier.Retry(context.TODO(), func() error {
        retryCount++
        if retryCount < 3 {
            return http.ErrAbortHandler
        }
        return nil
    })
    if err != nil {
        // handle error
    }

It's also possible to create a Registry with the temporary default errors: retrier.Registry.LoadDefaults(). You can extend the list with your errors by calling the RegisterTemporaryError method.

go-again is helpful in cases where you want to retry a function if it returns a temporary error, for example, when connecting to a database or a network service.

Installation

go get github.com/hyp3rd/go-again

Usage

For examples with cancellation, see examples.

Retrier

package main

import (
    "fmt"
    "time"

    "github.com/hyp3rd/go-again"
)

func main() {
    // Create a new retrier.
    retrier := again.NewRetrier(5, time.Millisecond*10, time.Second, time.Second)

    // Register a temporary error.
    retrier.Registry.RegisterTemporaryError("temporary error", func() again.ITemporaryError {
        return fmt.Errorf("temporary error")
    })

    // Retry a function.
    err := retrier.Retry(context.TODO(), func() error {
        // Do something here.
        return fmt.Errorf("temporary error")
    }, "temporary error")
    if err != nil {
        fmt.Println(err)
    }
}

License

The code and documentation in this project are released under Mozilla Public License 2.0.

Author

I'm a surfer, a crypto trader, and a software architect with 15 years of experience designing highly available distributed production environments and developing cloud-native apps in public and private clouds. Feel free to hook me up on LinkedIn.

Documentation

Index

• func NewRegistry() *registry
• func NewTimerPool(size int, timeout time.Duration) *timerPool
• type ITemporaryError
• type Retrier
  • func NewRetrier(maxRetries int, jitter time.Duration, interval time.Duration, ...) *Retrier
  • func (r *Retrier) Cancel()
  • func (r *Retrier) IsTemporaryError(err error, names ...string) bool
  • func (r *Retrier) Retry(ctx context.Context, fn func() error, temporaryErrors ...string) error
  • func (r *Retrier) SetRegistry(reg *registry)
• type RetryError
  • func (e *RetryError) Error() string
  • func (e *RetryError) Unwrap() error

Functions

func NewRegistry

func NewRegistry() *registry

NewRegistry creates a new registry.

func NewTimerPool

func NewTimerPool(size int, timeout time.Duration) *timerPool

NewTimerPool creates a new timer pool.

Types

type ITemporaryError

type ITemporaryError interface {
	error
}

ITemporaryError is an interface for temporary errors.

type Retrier

type Retrier struct {
	// MaxRetries is the maximum number of retries.
	MaxRetries int
	// Jitter is the amount of jitter to apply to the retry interval.
	Jitter time.Duration
	// Interval is the interval between retries.
	Interval time.Duration
	// Timeout is the timeout for the retry function.
	Timeout time.Duration
	// Registry is the registry for temporary errors.
	Registry *registry
	// contains filtered or unexported fields
}

Retrier is a type that retries a function until it returns a nil error or the maximum number of retries is reached.

func NewRetrier

func NewRetrier(maxRetries int, jitter time.Duration, interval time.Duration, timeout time.Duration) *Retrier

NewRetrier returns a new Retrier.

func (*Retrier) Cancel

func (r *Retrier) Cancel()

Cancel cancels the retries.

func (*Retrier) IsTemporaryError

func (r *Retrier) IsTemporaryError(err error, names ...string) bool

IsTemporaryError checks if the error is in the list of temporary errors.

func (*Retrier) Retry

func (r *Retrier) Retry(ctx context.Context, fn func() error, temporaryErrors ...string) error

Retry retries a function until it returns a nil error or the maximum number of retries is reached.

func (*Retrier) SetRegistry

func (r *Retrier) SetRegistry(reg *registry)

SetRegistry sets the registry for temporary errors.

type RetryError

type RetryError struct {
	MaxRetries int
	Err        error
}

RetryError is an error returned by the Retry function when the maximum number of retries is reached.

func (*RetryError) Error

func (e *RetryError) Error() string

Error returns the error message.

func (*RetryError) Unwrap

func (e *RetryError) Unwrap() error

Unwrap returns the underlying error.