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 {
// Delay is the time duration being waited.
// Initially, it serves as the starting wait duration,
// and then it increases based on the exponential backoff formula calculation.
//
// Default: 1/2 Second
Delay 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
// Attempts is the amount of retry which is allowed before giving up the application.
//
// Default: 5 if Timeout is not set.
Attempts 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 {
// Delay is the time duration waited between attempts.
//
// Default: 1/2 Second
Delay 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
// Attempts is the amount of retry attempt which is allowed before giving up the application.
//
// Default: 5 if Timeout is not set.
Attempts int
}
Example ¶
package main
import (
"context"
"time"
"go.llib.dev/frameless/pkg/retry"
)
func main() {
ctx := context.Background()
rs := retry.FixedDelay{
Delay: 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 {
// Delay is the maximum time duration that the Jitter is willing to wait between attempts.
// There is no guarantee that it will wait the full duration.
//
// Default: 5 Second
Delay time.Duration
// Attempts is the amount of retry that is allowed before giving up the application.
//
// Default: 5
Attempts int
}
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
}
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
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
}
Source Files