retry

README

♻️ retry

The most advanced interruptible mechanism to perform actions repetitively until successful.

💡 Idea

The package based on Rican7/retry but fully reworked and focused on integration with the 🚧 breaker and the built-in context packages.

Full description of the idea is available here.

🏆 Motivation

I developed distributed systems at Lazada, and later at Avito, which communicate with each other through a network, and I need a package to make these communications more reliable.

🤼‍♂️ How to

retry.Do

var response *http.Response

action := func() error {
	var err error
	response, err = http.Get("https://github.com/kamilsk/retry")
	return err
}

// you can combine multiple Breakers into one
interrupter := breaker.MultiplexTwo(
	breaker.BreakByTimeout(time.Minute),
	breaker.BreakBySignal(os.Interrupt),
)
defer interrupter.Close()

if err := retry.Do(interrupter, action, strategy.Limit(3)); err != nil {
	if err == breaker.Interrupted {
		// operation was interrupted
	}
	// handle error
}
// work with response

or use Context

ctx, cancel := context.WithTimeout(request.Context(), time.Minute)
defer cancel()

if err := retry.Do(ctx, action, strategy.Limit(3)); err != nil {
	if err == context.Canceled || err == context.DeadlineExceeded {
		// operation was interrupted
	}
	// handle error
}
// work with response

Complex example

import (
	"context"
	"fmt"
	"log"
	"math/rand"
	"net"
	"time"

	"github.com/kamilsk/retry/v5"
	"github.com/kamilsk/retry/v5/backoff"
	"github.com/kamilsk/retry/v5/jitter"
	"github.com/kamilsk/retry/v5/strategy"
)

func main() {
	what := SendRequest

	how := retry.How{
		strategy.Limit(5),
		strategy.BackoffWithJitter(
			backoff.Fibonacci(10*time.Millisecond),
			jitter.NormalDistribution(
				rand.New(rand.NewSource(time.Now().UnixNano())),
				0.25,
			),
		),
		strategy.CheckNetworkError(strategy.Skip),
	}

	breaker, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	if err := retry.Do(breaker, what, how...); err != nil {
		log.Fatal(err)
	}
}

func SendRequest() error {
	// communicate with some service
}

🧩 Integration

The library uses SemVer for versioning, and it is not BC-safe through major releases. You can use go modules to manage its version.

$ go get github.com/kamilsk/retry/v5@latest

🤲 Outcomes

Console tool for command execution with retries

This example shows how to repeat console command until successful.

$ retry -timeout 10m -backoff lin:500ms -- /bin/sh -c 'echo "trying..."; exit $((1 + RANDOM % 10 > 5))'

See more details here.

---

made with ❤️ for everyone

Documentation

Overview

Package retry provides the most advanced interruptible mechanism to perform actions repetitively until successful.

Example

package main

import (
	"context"
	"fmt"
	"log"
	"math/rand"
	"net"
	"time"

	"github.com/kamilsk/retry/v5"
	"github.com/kamilsk/retry/v5/backoff"
	"github.com/kamilsk/retry/v5/jitter"
	"github.com/kamilsk/retry/v5/strategy"
)

var generator = rand.New(rand.NewSource(0))

func main() {
	what := SendRequest

	how := retry.How{
		strategy.Limit(5),
		strategy.BackoffWithJitter(
			backoff.Fibonacci(10*time.Millisecond),
			jitter.NormalDistribution(
				rand.New(rand.NewSource(time.Now().UnixNano())),
				0.25,
			),
		),
		strategy.CheckNetworkError(strategy.Skip),
	}

	breaker, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()

	if err := retry.Do(breaker, what, how...); err != nil {
		log.Fatal(err)
	}
	fmt.Println("success communication")
}

func SendRequest() error {
	if generator.Intn(5) > 3 {
		return &net.DNSError{Name: "unknown host", IsTemporary: true}
	}
	return nil
}

Output:

success communication

Index

• func Do(breaker strategy.Breaker, action func() error, ...) error
• func DoAsync(breaker strategy.Breaker, action func() error, ...) error
• type Action
• type How

Examples

• Package

Functions

func Do

func Do(
	breaker strategy.Breaker,
	action func() error,
	strategies ...func(strategy.Breaker, uint, error) bool,
) error

Do takes an action and performs it, repetitively, until successful.

Optionally, strategies may be passed that assess whether or not an attempt should be made.

func DoAsync

func DoAsync(
	breaker strategy.Breaker,
	action func() error,
	strategies ...func(strategy.Breaker, uint, error) bool,
) error

DoAsync takes an action and performs it, repetitively, until successful.

Optionally, strategies may be passed that assess whether or not an attempt should be made.

Types

type Action

type Action func() error

Action defines a callable function that package retry can handle.

type How

type How []func(strategy.Breaker, uint, error) bool

How is an alias for batch of Strategies.

how := retry.How{
	strategy.Limit(3),
}