gosyphus

README

Gosyphus: Retries with exponential backoff in Go

See docs and examples on pkg.go.dev.

Documentation

Overview

Package gosyphus implements jittered capped exponential backoff and provides functionality for retrying failed function calls.

The top-level functions retry using the default wait time parameters. If you need to configure the wait time parameters, create a new Gosyphus.

When calling functions from this package, you can use context to set an overall deadline on the call or to cancel retries at any time.

All functions in this package are safe for concurrent use by multiple goroutines.

To learn more about jittered capped exponential backoff, see the article Exponential Backoff And Jitter. This package implements the “Full Jitter” algorithm mentioned in the article.

Example

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/soroushj/gosyphus"
)

func main() {
	n := 0
	printTheAnswer := func() error {
		fmt.Println("calculating the answer")
		if n < 2 {
			n++
			return errors.New("calculation error")
		}
		fmt.Println("the answer is 42")
		return nil
	}
	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Minute)
	defer cancel()
	err := gosyphus.Do(ctx, printTheAnswer)
	if err != nil {
		fmt.Println("failure:", err)
		return
	}
	fmt.Println("success")
}

Output:

calculating the answer
calculating the answer
calculating the answer
the answer is 42
success

Example (ShouldRetry)

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/soroushj/gosyphus"
)

func main() {
	impossible := errors.New("impossible to calculate the answer")
	n := 0
	printTheAnswer := func() error {
		fmt.Println("calculating the answer")
		if n < 2 {
			n++
			return errors.New("calculation error")
		}
		return impossible
	}
	shouldRetry := func(err error) bool {
		return err != impossible
	}
	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Minute)
	defer cancel()
	err := gosyphus.Dos(ctx, printTheAnswer, shouldRetry)
	if err != nil {
		fmt.Println("failure:", err)
		return
	}
	fmt.Println("success")
}

Output:

calculating the answer
calculating the answer
calculating the answer
failure: impossible to calculate the answer

Example (Timeout)

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/soroushj/gosyphus"
)

func main() {
	printTheAnswer := func() error {
		return errors.New("calculation error")
	}
	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
	defer cancel()
	g := gosyphus.New(100*time.Millisecond, 500*time.Millisecond)
	err := g.Do(ctx, printTheAnswer)
	if err != nil {
		fmt.Println("failure:", err)
		return
	}
	fmt.Println("success")
}

Output:

failure: context deadline exceeded

Index

• func Do(ctx context.Context, f func() error) error
• func Dos(ctx context.Context, f func() error, shouldRetry func(error) bool) error
• type Gosyphus
  • func New(initial, max time.Duration) *Gosyphus
  • func (g *Gosyphus) Do(ctx context.Context, f func() error) error
  • func (g *Gosyphus) Dos(ctx context.Context, f func() error, shouldRetry func(error) bool) error

Examples

• Package
• Package (ShouldRetry)
• Package (Timeout)

Functions

func Do

func Do(ctx context.Context, f func() error) error

Do calls f and retries until it succeeds. The wait time between retries is a random value between 0 and d, where d starts at 1 second and doubles every retry, but is capped at 30 seconds.

func Dos

func Dos(ctx context.Context, f func() error, shouldRetry func(error) bool) error

Dos calls f and retries until it succeeds or returns an error for which shouldRetry returns false. The wait time between retries is a random value between 0 and d, where d starts at 1 second and doubles every retry, but is capped at 30 seconds.

Types

type Gosyphus

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

Gosyphus implements jittered capped exponential backoff.

func New

func New(initial, max time.Duration) *Gosyphus

New returns a new Gosyphus. The wait time between retries is a random value between 0 and d, where d starts at initial and doubles every retry, but is capped at max.

If initial < 1, it will be set to 1. If max < initial, max will be set to initial.

func (*Gosyphus) Do

func (g *Gosyphus) Do(ctx context.Context, f func() error) error

Do calls f and retries until it succeeds.

func (*Gosyphus) Dos

func (g *Gosyphus) Dos(ctx context.Context, f func() error, shouldRetry func(error) bool) error

Dos calls f and retries until it succeeds or returns an error for which shouldRetry returns false.