Simple library for retry mechanism
Slightly inspired by Try::Tiny::Retry
HTTP GET with retry:
url := "http://example.com"
var body []byte
err := retry.New(
retry.Attempts(5),
retry.Delay(100*time.Millisecond),
).Do(
func() error {
resp, err := http.Get(url)
if err != nil {
return err
}
defer resp.Body.Close()
body, err = ioutil.ReadAll(resp.Body)
if err != nil {
return err
}
return nil
},
)
if err != nil {
// handle error
}
fmt.Println(string(body))HTTP GET with retry with data:
url := "http://example.com"
body, err := retry.NewWithData[[]byte]().Do(
func() ([]byte, error) {
resp, err := http.Get(url)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}
return body, nil
},
)
if err != nil {
// handle error
}
fmt.Println(string(body))Reusable retrier for high-frequency retry operations:
// Create retrier once, reuse many times
retrier := retry.New(
retry.Attempts(5),
retry.Delay(100*time.Millisecond),
)
// Minimal allocations in happy path
for {
err := retrier.Do(
func() error {
return doWork()
},
)
if err != nil {
// handle error
}
}-
codeGROOVE-dev/retry - Modern fork of avast/retry-go/v4 focused on correctness, reliability and efficiency. 100% API-compatible drop-in replacement. Looks really good.
-
giantswarm/retry-go - slightly complicated interface.
-
sethgrid/pester - only http retry for http calls with retries and backoff
-
cenkalti/backoff - Go port of the exponential backoff algorithm from Google's HTTP Client Library for Java. Really complicated interface.
-
rafaeljesus/retry-go - looks good, slightly similar as this package, don't have 'simple'
Retrymethod -
matryer/try - very popular package, nonintuitive interface (for me)
5.0.0
- Complete API redesign: method-based retry operations
- Renamed
Configtype toRetrier - Renamed
NewConfig()toNew() - Changed from package-level functions to methods:
retry.Do(func, config)→retry.New(opts...).Do(func) - Replaced package-level
DoWithDatawith typed retrier:retry.DoWithData(func, opts...)→retry.NewWithData\[T](opts...).Do(func) DelayTypeFuncsignature changed:func(n uint, err error, config \*Config)→func(n uint, err error, r \*Retrier)- Migration for
Do:retry.Do(func, opts...)→retry.New(opts...).Do(func)(simple find & replace) - Migration for
DoWithData:retry.DoWithData(func, opts...)→retry.NewWithData\[T](opts...).Do(func)whereTis your return type - This change improves performance, simplifies the API, and provides a cleaner interface
Unwrap()now returns\[]errorinstead oferrorto support Go 1.20 multiple error wrapping.errors.Unwrap(err)will now returnnil(same aserrors.Join). Useerrors.Isorerrors.Asto inspect wrapped errors.
4.0.0
- infinity retry is possible by set
Attempts(0)by PR #49
3.0.0
DelayTypeFuncaccepts a new parametererr- this breaking change affects only your custom Delay Functions. This change allow make delay functions based on error.
1.0.2 -> 2.0.0
- argument of
retry.Delayis final delay (no multiplication byretry.Unitsanymore) - function
retry.Unitsare removed - more about this breaking change
0.3.0 -> 1.0.0
retry.Retryfunction are changed toretry.Dofunctionretry.RetryCustom(OnRetry) andretry.RetryCustomWithOptsfunctions are now implement via functions produces Options (akaretry.OnRetry)
func BackOffDelay(n uint, _ error, config DelayContext) time.DurationBackOffDelay is a DelayType which increases delay between consecutive retries
func FixedDelay(_ uint, _ error, config DelayContext) time.DurationFixedDelay is a DelayType which keeps delay the same through all iterations
func FullJitterBackoffDelay(n uint, err error, config DelayContext) time.DurationFullJitterBackoffDelay is a DelayTypeFunc that calculates delay using exponential backoff with full jitter. The delay is a random value between 0 and the current backoff ceiling. Formula: sleep = random_between(0, min(cap, base * 2^attempt)) It uses config.Delay as the base delay and config.MaxDelay as the cap.
func IsRecoverable(err error) boolIsRecoverable checks if error is an instance of unrecoverableError
func RandomDelay(_ uint, _ error, config DelayContext) time.DurationRandomDelay is a DelayType which picks a random delay up to maxJitter
func Unrecoverable(err error) errorUnrecoverable wraps an error in unrecoverableError struct
type DelayContext interface {
Delay() time.Duration
MaxJitter() time.Duration
MaxBackOffN() uint
MaxDelay() time.Duration
}DelayContext provides configuration values needed for delay calculation.
type DelayTypeFunc func(n uint, err error, config DelayContext) time.DurationDelayTypeFunc is called to return the next delay to wait after the retriable function fails on err after n attempts.
func CombineDelay(delays ...DelayTypeFunc) DelayTypeFuncCombineDelay is a DelayType the combines all of the specified delays into a new DelayTypeFunc
type Error []errorError type represents list of errors in retry
func (e Error) As(target interface{}) boolfunc (e Error) Error() stringError method return string representation of Error It is an implementation of error interface
func (e Error) Is(target error) boolfunc (e Error) LastError() errorLastError returns the last error in the error list.
This is a convenience method for users migrating from retry-go v4.x where errors.Unwrap(err) returned the last error. In v5.0.0, errors.Unwrap(err) returns nil due to the switch to Unwrap() []error for Go 1.20 compatibility.
Migration example:
// v4.x code:
lastErr := errors.Unwrap(retryErr)
// v5.0.0 code (option 1 - recommended):
if errors.Is(retryErr, specificError) { ... }
// v5.0.0 code (option 2 - if you need the last error):
lastErr := retryErr.(retry.Error).LastError()Note: Using errors.Is or errors.As is preferred as they check ALL wrapped errors, not just the last one.
func (e Error) Unwrap() []errorUnwrap returns the list of errors that this Error is wrapping.
This method implements the Unwrap() []error interface introduced in Go 1.20 for multi-error unwrapping. This allows errors.Is and errors.As to traverse all wrapped errors, not just the last one.
IMPORTANT: errors.Unwrap(err) will return nil because the standard library's errors.Unwrap function only calls Unwrap() error, not Unwrap() []error. This is the same behavior as errors.Join in Go 1.20.
Example - Use errors.Is to check for specific errors:
err := retry.New(retry.Attempts(3)).Do(func() error {
return os.ErrNotExist
})
if errors.Is(err, os.ErrNotExist) {
// Handle not exist error
}Example - Use errors.As to extract error details:
var pathErr *fs.PathError
if errors.As(err, &pathErr) {
fmt.Println("Failed at path:", pathErr.Path)
}Example - Get the last error directly (for migration):
if retryErr, ok := err.(retry.Error); ok {
lastErr := retryErr.LastError()
}See also: LastError() for direct access to the last error.
func (e Error) WrappedErrors() []errorWrappedErrors returns the list of errors that this Error is wrapping. It is an implementation of the errwrap.Wrapper interface in package [errwrap](https://github.com/hashicorp/errwrap) so that retry.Error can be used with that library.
type FixedTokenBucketThrottleConfig struct {
// MaxCapacity is the bucket size: 0 means the default (100),
// a negative value means unlimited (never throttles).
MaxCapacity int64
// ThrottleCost is taken from the bucket for each retry (default 5).
ThrottleCost int64
// SuccessReleaseCost is returned to the bucket on a success after retries
// (default ThrottleCost).
SuccessReleaseCost int64
// FirstSuccessReleaseCost is returned to the bucket on a first-attempt
// success (default 1).
FirstSuccessReleaseCost int64
}FixedTokenBucketThrottleConfig configures a FixedTokenBucketThrottleManager. Zero and negative costs are replaced by defaults.
type FixedTokenBucketThrottleManager struct {
// contains filtered or unexported fields
}FixedTokenBucketThrottleManager is a ThrottleManager backed by a fixed-size token bucket: retries take tokens, successes return them (capped at MaxCapacity). Retries are denied while the bucket lacks ThrottleCost tokens.
func NewFixedTokenBucketThrottle(config FixedTokenBucketThrottleConfig) *FixedTokenBucketThrottleManagerNewFixedTokenBucketThrottle creates a FixedTokenBucketThrottleManager with a full bucket.
func (m *FixedTokenBucketThrottleManager) AllowRetry(_ uint, _ error) boolAllowRetry takes ThrottleCost tokens, or returns false if not enough are left.
func (m *FixedTokenBucketThrottleManager) OnSuccess(attempt uint)OnSuccess returns FirstSuccessReleaseCost tokens when attempt is 0, SuccessReleaseCost otherwise.
type OnRetryFunc func(attempt uint, err error)Function signature of OnRetry function
type Option func(*retrierCore)Option represents an option for retry.
func Attempts(attempts uint) OptionAttempts set count of retry. Setting to 0 will retry until the retried function succeeds. default is 10
func AttemptsForError(attempts uint, err error) OptionAttemptsForError sets count of retry in case execution results in given err Retries for the given err are also counted against total retries. The retry will stop if any of given retries is exhausted.
added in 4.3.0
func Context(ctx context.Context) OptionContext allow to set context of retry default are Background context
example of immediately cancellation (maybe it isn't the best example, but it describes behavior enough; I hope)
ctx, cancel := context.WithCancel(context.Background())
cancel()
retry.New(
retry.Context(ctx),
).Do(
func() error {
...
},
)func Delay(delay time.Duration) OptionDelay set delay between retry default is 100ms
func DelayType(delayType DelayTypeFunc) OptionDelayType set type of the delay between retries default is a combination of BackOffDelay and RandomDelay for exponential backoff with jitter
func LastErrorOnly(lastErrorOnly bool) Optionreturn the direct last error that came from the retried function default is false (return wrapped errors with everything)
func MaxDelay(maxDelay time.Duration) OptionMaxDelay set maximum delay between retry does not apply by default
func MaxJitter(maxJitter time.Duration) OptionMaxJitter sets the maximum random Jitter between retries for RandomDelay
func OnRetry(onRetry OnRetryFunc) OptionOnRetry function callback are called each retry
log each retry example:
retry.New(
retry.OnRetry(func(n uint, err error) {
log.Printf("#%d: %s\n", n, err)
}),
).Do(
func() error {
return errors.New("some error")
},
)func RetryIf(retryIf RetryIfFunc) OptionRetryIf controls whether a retry should be attempted after an error (assuming there are any retry attempts remaining)
skip retry if special error example:
retry.New(
retry.RetryIf(func(err error) bool {
if err.Error() == "special error" {
return false
}
return true
}),
).Do(
func() error {
return errors.New("special error")
},
)By default RetryIf stops execution if the error is wrapped using retry.Unrecoverable, so above example may also be shortened to:
retry.New().Do(
func() error {
return retry.Unrecoverable(errors.New("special error"))
},
)func UntilSucceeded() OptionUntilSucceeded will retry until the retried function succeeds. Equivalent to setting Attempts(0).
func WithFixedTokenBucketThrottle(config FixedTokenBucketThrottleConfig) OptionWithFixedTokenBucketThrottle is a shortcut for WithThrottle(NewFixedTokenBucketThrottle(config)). Every New call builds a fresh bucket shared by that Retrier's Do calls, so reusing this Option for several Retriers does not share a bucket. To share one, create it with NewFixedTokenBucketThrottle and pass it to WithThrottle.
func WithThrottle(manager ThrottleManager) OptionWithThrottle limits retries with the given ThrottleManager. Before each retry that would actually happen, manager.AllowRetry is called; if it returns false, retrying stops immediately with an error matching ErrThrottled. manager.OnSuccess is called when the retryable function succeeds. Option order does not matter; passing nil disables throttling.
func WithTimer(t Timer) OptionWithTimer provides a way to swap out timer module implementations. This primarily is useful for mocking/testing, where you may not want to explicitly wait for a set duration for retries.
example of augmenting time.After with a print statement
type struct MyTimer {}
func (t *MyTimer) After(d time.Duration) <- chan time.Time {
fmt.Print("Timer called!")
return time.After(d)
}
retry.New(
retry.WithTimer(&MyTimer{}),
).Do(
func() error { ... },
)func WrapContextErrorWithLastError(wrapContextErrorWithLastError bool) OptionWrapContextErrorWithLastError allows the context error to be returned wrapped with the last error that the retried function returned. This is only applicable when Attempts is set to 0 to retry indefinitly and when using a context to cancel / timeout
default is false
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
retry.New(
retry.Context(ctx),
retry.Attempts(0),
retry.WrapContextErrorWithLastError(true),
).Do(
func() error {
...
},
)type Retrier struct {
// contains filtered or unexported fields
}Retrier is for retry operations that return only an error.
func New(opts ...Option) *RetrierNew creates a new Retrier with the given options. The returned Retrier can be safely reused across multiple retry operations.
func (r Retrier) Delay() time.DurationDelay implements DelayContext
func (r *Retrier) Do(retryableFunc RetryableFunc) errorDo executes the retryable function using this Retrier's configuration.
func (r Retrier) MaxBackOffN() uintMaxBackOffN implements DelayContext
func (r Retrier) MaxDelay() time.DurationMaxDelay implements DelayContext
func (r Retrier) MaxJitter() time.DurationMaxJitter implements DelayContext
type RetrierWithData[T any] struct {
// contains filtered or unexported fields
}RetrierWithData is for retry operations that return data and an error.
func NewWithData[T any](opts ...Option) *RetrierWithData[T]NewWithData creates a new RetrierWithData[T] with the given options. The returned retrier can be safely reused across multiple retry operations.
func (r RetrierWithData) Delay() time.DurationDelay implements DelayContext
func (r *RetrierWithData[T]) Do(retryableFunc RetryableFuncWithData[T]) (T, error)Do executes the retryable function using this RetrierWithData's configuration.
func (r RetrierWithData) MaxBackOffN() uintMaxBackOffN implements DelayContext
func (r RetrierWithData) MaxDelay() time.DurationMaxDelay implements DelayContext
func (r RetrierWithData) MaxJitter() time.DurationMaxJitter implements DelayContext
type RetryIfFunc func(error) boolFunction signature of retry if function
type RetryableFunc func() errorFunction signature of retryable function
type RetryableFuncWithData[T any] func() (T, error)Function signature of retryable function with data
type ThrottleManager interface {
// AllowRetry is called after attempt failed with err, only when a retry
// would otherwise follow, and before the delay. Returning false stops
// retrying immediately with an error matching ErrThrottled.
// If the context is cancelled during the delay, no retry happens even
// though AllowRetry returned true.
AllowRetry(attempt uint, err error) bool
// OnSuccess is called when attempt succeeded (0 is the first attempt).
OnSuccess(attempt uint)
}ThrottleManager limits retries across calls, see WithThrottle. Implementations must be safe for concurrent use.
type Timer interface {
After(time.Duration) <-chan time.Time
}Timer represents the timer used to track time for a retry.
Contributions are very much welcome.
Makefile provides several handy rules, like README.md generator , setup for prepare build/dev environment, test, cover, etc...
Try make help for more information.
maybe you need
make setupin order to setup environment
please try:
- run tests (
make test) - run linter (
make lint) - if your IDE don't automaticaly do
go fmt, rungo fmt(make fmt)
README.md is generated from the package documentation by tools/genreadme (layout in tools/genreadme/README.tmpl).
Never edit README.md direct, because your change will be lost.