retry

package
v0.255.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2024 License: Apache-2.0 Imports: 6 Imported by: 0

README

Package retry

The retry package provides tooling to do retries easily in your application code.

retry strategies

Using a retry strategy easy as iterating with a for loop, but instead of making a condition based on a max value, we check it with retry.Strategy#ShouldTry.

Example:

package mypkg

import (
	"context"
	"fmt"
	"go.llib.dev/frameless/pkg/retry"
)

func (ms MyStruct) MyFunc(ctx context.Context) error {
	var rs retry.ExponentialBackoff

	for i := 0; rs.ShouldTry(ctx, i); i++ {
		err := ms.DoAction(ctx)
		if err != nil {
			if ms.isErrTemporary(err) {
				continue
			}
			return err
		}
		return nil
	}
	return fmt.Errorf("failed to DoAction")
}

The package contains strategies for retrying operations.

ExponentialBackoff

This strategy will retry an operation up to a specified maximum number of times, with an increasing delay between each retry. The delay doubles with each failed attempt. This gives the system more time to recover from any issues.

Jitter

This strategy will also retry an operation up to a specified maximum number of times, but adds a random variation to the backoff time. This helps distribute retry attempts evenly over time and reduces the risk of overwhelming the system.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ExponentialBackoff

type ExponentialBackoff struct {
	// WaitTime is the time duration used to calculate exponential backoff wait times.
	// Initially, it serves as the starting wait duration, and then it evolves.
	//
	// Default: 1/2 Second
	WaitTime time.Duration
	// Timeout is the time within the Strategy is attempting further retries.
	// If the total waited time is greater than the Timeout, ExponentialBackoff will stop further attempts.
	// When Timeout is given, but MaxRetries is not, ExponentialBackoff will continue to retry until
	//
	// Default: ignored
	Timeout time.Duration
	// MaxRetries is the amount of retry which is allowed before giving up the application.
	//
	// Default: 5 if Timeout is not set.
	MaxRetries int
}

ExponentialBackoff will answer if retry can be made. It waits as well the amount of time based on the failure count. The waiting time before returning is doubled for each failed attempts This ensures that the system gets progressively more time to recover from any issues.

Example
package main

import (
	"context"

	"go.llib.dev/frameless/pkg/retry"
)

func main() {
	ctx := context.Background()
	rs := retry.ExponentialBackoff{}

	for i := 0; rs.ShouldTry(ctx, i); i++ {
		// do an action
		// return on success
	}
	// return failure
}

func (ExponentialBackoff) ShouldTry

func (rs ExponentialBackoff) ShouldTry(ctx context.Context, failureCount FailureCount) bool

type FailureCount added in v0.176.0

type FailureCount = int

type FixedDelay added in v0.254.0

type FixedDelay struct {
	// WaitTime is the time duration used to calculate exponential backoff wait times.
	// Initially, it serves as the starting wait duration, and then it evolves.
	//
	// Default: 1/2 Second
	WaitTime time.Duration
	// Timeout is the time within the Strategy is attempting further retries.
	// If the total waited time is greater than the Timeout, ExponentialBackoff will stop further attempts.
	// When Timeout is given, but MaxRetries is not, ExponentialBackoff will continue to retry until
	//
	// Default: ignored
	Timeout time.Duration
	// MaxRetries is the amount of retry which is allowed before giving up the application.
	//
	// Default: 5 if Timeout is not set.
	MaxRetries int
}
Example
package main

import (
	"context"
	"time"

	"go.llib.dev/frameless/pkg/retry"
)

func main() {
	ctx := context.Background()
	rs := retry.FixedDelay{
		WaitTime: 10 * time.Second,
		Timeout:  5 * time.Minute,
	}

	for i := 0; rs.ShouldTry(ctx, i); i++ {
		// do an action
		// return/break on success
	}
	// return failure
}

func (FixedDelay) ShouldTry added in v0.254.0

func (rs FixedDelay) ShouldTry(ctx context.Context, failureCount FailureCount) bool

type Jitter

type Jitter struct {
	// MaxRetries is the amount of retry that is allowed before giving up the application.
	//
	// Default: 5
	MaxRetries int
	// MaxWaitTime is the duration the Jitter will maximum wait between two retries.
	//
	// Default: 5 Second
	MaxWaitTime time.Duration
}

Jitter is a random variation added to the backoff time. This helps to distribute the retry attempts evenly over time, reducing the risk of overwhelming the system and avoiding synchronization between multiple clients that might be retrying simultaneously.

Example
package main

import (
	"context"

	"go.llib.dev/frameless/pkg/retry"
)

func main() {
	ctx := context.Background()
	rs := retry.Jitter{}

	for i := 0; rs.ShouldTry(ctx, i); i++ {
		// do an action
		// return on success
	}
	// return failure
}

func (Jitter) ShouldTry

func (rs Jitter) ShouldTry(ctx context.Context, count FailureCount) bool

type StartedAt added in v0.176.0

type StartedAt = time.Time

type Strategy

type Strategy[U StrategyUnit] interface {
	// ShouldTry will tell if retry should be attempted after a given number of failed attempts.
	ShouldTry(ctx context.Context, u U) bool
}

type StrategyUnit added in v0.176.0

type StrategyUnit interface{ FailureCount | StartedAt }

type Waiter added in v0.176.0

type Waiter struct {
	// Timeout refers to the maximum duration we can wait
	// before a retry attempt is deemed unreasonable.
	//
	// Default: 30 seconds
	Timeout time.Duration
}

func (Waiter) ShouldTry added in v0.176.0

func (rs Waiter) ShouldTry(ctx context.Context, startedAt StartedAt) bool
Example
package main

import (
	"context"
	"time"

	"go.llib.dev/frameless/pkg/retry"
)

func main() {
	var (
		ctx = context.Background()
		rs  = retry.Waiter{Timeout: time.Minute}
		now = time.Now()
	)

	for rs.ShouldTry(ctx, now) {
		// do an action
		// return on success
	}
	// return failure
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL