README
¶
retry
Simple library for retry mechanism
slightly inspired by Try::Tiny::Retry
SYNOPSIS
http get with retry:
url := "http://example.com"
var body []byte
err := retry.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
},
)
fmt.Println(body)
SEE ALSO
-
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)
BREAKING CHANGES
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
0.3.0 -> 1.0.0
-
retry.Retryfunction are changed toretry.Dofunction -
retry.RetryCustom(OnRetry) andretry.RetryCustomWithOptsfunctions are now implement via functions produces Options (akaretry.OnRetry)
Usage
var (
DefaultAttempts = uint(10)
DefaultDelay = 100 * time.Millisecond
DefaultMaxJitter = 100 * time.Millisecond
DefaultOnRetry = func(n uint, err error) {}
DefaultRetryIf = IsRecoverable
DefaultDelayType = CombineDelay(BackOffDelay, RandomDelay)
DefaultLastErrorOnly = false
DefaultContext = context.Background()
)
func BackOffDelay
func BackOffDelay(n uint, _ error, config *Config) time.Duration
BackOffDelay is a DelayType which increases delay between consecutive retries
func Do
func Do(retryableFunc RetryableFunc, opts ...Option) error
func FixedDelay
func FixedDelay(_ uint, _ error, config *Config) time.Duration
FixedDelay is a DelayType which keeps delay the same through all iterations
func IsRecoverable
func IsRecoverable(err error) bool
IsRecoverable checks if error is an instance of unrecoverableError
func RandomDelay
func RandomDelay(_ uint, _ error, config *Config) time.Duration
RandomDelay is a DelayType which picks a random delay up to config.maxJitter
func Unrecoverable
func Unrecoverable(err error) error
Unrecoverable wraps an error in unrecoverableError struct
type Config
type Config struct {
}
type DelayTypeFunc
type DelayTypeFunc func(n uint, err error, config *Config) time.Duration
DelayTypeFunc is called to return the next delay to wait after the retriable
function fails on err after n attempts.
func CombineDelay
func CombineDelay(delays ...DelayTypeFunc) DelayTypeFunc
CombineDelay is a DelayType the combines all of the specified delays into a new DelayTypeFunc
type Error
type Error []error
Error type represents list of errors in retry
func (Error) Error
func (e Error) Error() string
Error method return string representation of Error It is an implementation of error interface
func (Error) WrappedErrors
func (e Error) WrappedErrors() []error
WrappedErrors returns the list of errors that this Error is wrapping. It is an
implementation of the errwrap.Wrapper interface in package
errwrap so that retry.Error can be
used with that library.
type OnRetryFunc
type OnRetryFunc func(n uint, err error)
Function signature of OnRetry function n = count of attempts
type Option
type Option func(*Config)
Option represents an option for retry.
func Attempts
func Attempts(attempts uint) Option
Attempts set count of retry default is 10
func Context
func Context(ctx context.Context) Option
Context 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.Do(
func() error {
...
},
retry.Context(ctx),
)
func Delay
func Delay(delay time.Duration) Option
Delay set delay between retry default is 100ms
func DelayType
func DelayType(delayType DelayTypeFunc) Option
DelayType set type of the delay between retries default is BackOff
func LastErrorOnly
func LastErrorOnly(lastErrorOnly bool) Option
return the direct last error that came from the retried function default is false (return wrapped errors with everything)
func MaxDelay
func MaxDelay(maxDelay time.Duration) Option
MaxDelay set maximum delay between retry does not apply by default
func MaxJitter
func MaxJitter(maxJitter time.Duration) Option
MaxJitter sets the maximum random Jitter between retries for RandomDelay
func OnRetry
func OnRetry(onRetry OnRetryFunc) Option
OnRetry function callback are called each retry
log each retry example:
retry.Do(
func() error {
return errors.New("some error")
},
retry.OnRetry(func(n uint, err error) {
log.Printf("#%d: %s\n", n, err)
}),
)
func RetryIf
func RetryIf(retryIf RetryIfFunc) Option
RetryIf controls whether a retry should be attempted after an error (assuming there are any retry attempts remaining)
skip retry if special error example:
retry.Do(
func() error {
return errors.New("special error")
},
retry.RetryIf(func(err error) bool {
if err.Error() == "special error" {
return false
}
return true
})
)
By default RetryIf stops execution if the error is wrapped using
retry.Unrecoverable, so above example may also be shortened to:
retry.Do(
func() error {
return retry.Unrecoverable(errors.New("special error"))
}
)
type RetryIfFunc
type RetryIfFunc func(error) bool
Function signature of retry if function
type RetryableFunc
type RetryableFunc func() error
Function signature of retryable function
Contributing
Contributions are very much welcome.
Makefile
Makefile provides several handy rules, like README.md generator , setup for prepare build/dev environment, test, cover, etc...
Try make help for more information.
Before pull request
please try:
- run tests (
make test) - run linter (
make lint) - if your IDE don't automaticaly do
go fmt, rungo fmt(make fmt)
README
README.md are generate from template .godocdown.tmpl and code documentation via godocdown.
Never edit README.md direct, because your change will be lost.
Documentation
¶
Overview ¶
Simple library for retry mechanism
slightly inspired by [Try::Tiny::Retry](https://metacpan.org/pod/Try::Tiny::Retry)
SYNOPSIS ¶
http get with retry:
url := "http://example.com"
var body []byte
err := retry.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
},
)
fmt.Println(body)
[next examples](https://github.com/avast/retry-go/tree/master/examples)
SEE ALSO ¶
* giantswarm/retry-go(https://github.com/giantswarm/retry-go) - slightly complicated interface.
* sethgrid/pester(https://github.com/sethgrid/pester) - only http retry for http calls with retries and backoff
* cenkalti/backoff(https://github.com/cenkalti/backoff) - Go port of the exponential backoff algorithm from Google's HTTP Client Library for Java. Really complicated interface.
* rafaeljesus/retry-go(https://github.com/rafaeljesus/retry-go) - looks good, slightly similar as this package, don't have 'simple' `Retry` method
* matryer/try(https://github.com/matryer/try) - very popular package, nonintuitive interface (for me)
BREAKING CHANGES ¶
3.0.0
* `DelayTypeFunc` accepts a new parameter `err` - this breaking change affects only your custom Delay Functions. This change allow [make delay functions based on error](examples/delay_based_on_error_test.go).
1.0.2 -> 2.0.0
* argument of `retry.Delay` is final delay (no multiplication by `retry.Units` anymore)
* function `retry.Units` are removed
* [more about this breaking change](https://github.com/avast/retry-go/issues/7)
0.3.0 -> 1.0.0
* `retry.Retry` function are changed to `retry.Do` function
* `retry.RetryCustom` (OnRetry) and `retry.RetryCustomWithOpts` functions are now implement via functions produces Options (aka `retry.OnRetry`)
Index ¶
- Variables
- func BackOffDelay(n uint, _ error, config *Config) time.Duration
- func Do(retryableFunc RetryableFunc, opts ...Option) error
- func FixedDelay(_ uint, _ error, config *Config) time.Duration
- func IsRecoverable(err error) bool
- func RandomDelay(_ uint, _ error, config *Config) time.Duration
- func Unrecoverable(err error) error
- type Config
- type DelayTypeFunc
- type Error
- type OnRetryFunc
- type Option
- func Attempts(attempts uint) Option
- func Context(ctx context.Context) Option
- func Delay(delay time.Duration) Option
- func DelayType(delayType DelayTypeFunc) Option
- func LastErrorOnly(lastErrorOnly bool) Option
- func MaxDelay(maxDelay time.Duration) Option
- func MaxJitter(maxJitter time.Duration) Option
- func OnRetry(onRetry OnRetryFunc) Option
- func RetryIf(retryIf RetryIfFunc) Option
- type RetryIfFunc
- type RetryableFunc
Constants ¶
This section is empty.
Variables ¶
var ( DefaultAttempts = uint(10) DefaultDelay = 100 * time.Millisecond DefaultMaxJitter = 100 * time.Millisecond DefaultOnRetry = func(n uint, err error) {} DefaultRetryIf = IsRecoverable DefaultDelayType = CombineDelay(BackOffDelay, RandomDelay) DefaultLastErrorOnly = false DefaultContext = context.Background() )
Functions ¶
func BackOffDelay ¶
BackOffDelay is a DelayType which increases delay between consecutive retries
func Do ¶
func Do(retryableFunc RetryableFunc, opts ...Option) error
func FixedDelay ¶
FixedDelay is a DelayType which keeps delay the same through all iterations
func IsRecoverable ¶
IsRecoverable checks if error is an instance of `unrecoverableError`
func RandomDelay ¶
RandomDelay is a DelayType which picks a random delay up to config.maxJitter
func Unrecoverable ¶
Unrecoverable wraps an error in `unrecoverableError` struct
Types ¶
type DelayTypeFunc ¶
DelayTypeFunc is called to return the next delay to wait after the retriable function fails on `err` after `n` attempts.
func CombineDelay ¶
func CombineDelay(delays ...DelayTypeFunc) DelayTypeFunc
CombineDelay is a DelayType the combines all of the specified delays into a new DelayTypeFunc
type Error ¶
type Error []error
Error type represents list of errors in retry
func (Error) Error ¶
Error method return string representation of Error It is an implementation of error interface
func (Error) WrappedErrors ¶
WrappedErrors 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 OnRetryFunc ¶
Function signature of OnRetry function n = count of attempts
type Option ¶
type Option func(*Config)
Option represents an option for retry.
func Context ¶
Context 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.Do(
func() error {
...
},
retry.Context(ctx),
)
func DelayType ¶
func DelayType(delayType DelayTypeFunc) Option
DelayType set type of the delay between retries default is BackOff
func LastErrorOnly ¶
return the direct last error that came from the retried function default is false (return wrapped errors with everything)
func OnRetry ¶
func OnRetry(onRetry OnRetryFunc) Option
OnRetry function callback are called each retry
log each retry example:
retry.Do(
func() error {
return errors.New("some error")
},
retry.OnRetry(func(n uint, err error) {
log.Printf("#%d: %s\n", n, err)
}),
)
func RetryIf ¶
func RetryIf(retryIf RetryIfFunc) Option
RetryIf controls whether a retry should be attempted after an error (assuming there are any retry attempts remaining)
skip retry if special error example:
retry.Do(
func() error {
return errors.New("special error")
},
retry.RetryIf(func(err error) bool {
if err.Error() == "special error" {
return false
}
return true
})
)
By default RetryIf stops execution if the error is wrapped using `retry.Unrecoverable`, so above example may also be shortened to:
retry.Do(
func() error {
return retry.Unrecoverable(errors.New("special error"))
}
)
Source Files