retry

Documentation

Overview

Package retry implements frequently used retry strategies and options.

Index

• type Option
  • func Breaker(name string) Option
  • func BreakerWithOverloadRatio(name string, overloadRatio float64) Option
  • func C() Option
  • func Hook(hook func(attempts int, err error)) Option
  • func J(jitter float64) Option
  • func L(step time.Duration) Option
  • func MaxErrors(max int) Option
  • func MaxSleep(max time.Duration) Option
  • func NoJitter() Option
• type Result
  • func Const(attempts int, sleep time.Duration, f func() error, opts ...Option) Result
  • func Default(f func() error, opts ...Option) Result
  • func Forever(sleep, maxSleep time.Duration, f func() error, opts ...Option) Result
  • func Linear(attempts int, sleep time.Duration, f func() error, opts ...Option) Result
  • func Retry(attempts int, sleep time.Duration, f func() error, opts ...Option) Result
• type SizedError
  • func NewSizedError(size int) *SizedError
  • func (E *SizedError) Append(errs ...error)
  • func (E *SizedError) ErrOrNil() error
  • func (E *SizedError) Error() string
  • func (E *SizedError) Errors() (errors []error)
  • func (E *SizedError) Format(f fmt.State, c rune)
• type Stop
  • func (e Stop) Error() string

Types

type Option

type Option func(options) options

func Breaker

func Breaker(name string) Option

Breaker uses sliding window algorithm to protect system from overload with default overload ratio 0.1 (10%).

To prevent overload, Google SRE has some recommendations:

First, we implement a per-request retry budget of up to three attempts. If a request has already failed three times, we let the failure bubble up to the caller. The rationale is that if a request has already landed on overloaded tasks three times, it's relatively unlikely that attempting it again will help because the whole datacenter is likely overloaded.

Secondly, we implement a per-client retry budget. Each client keeps track of the ratio of requests that correspond to retries. A request will only be retried as long as this ratio is below 10%. The rationale is that if only a small subset of tasks are overloaded, there will be relatively little need to retry.

A third approach has clients include a counter of how many times the request has already been tried in the request metadata. For instance, the counter starts at 0 in the first attempt and is incremented on every retry until it reaches 2, at which point the per-request budget causes it to stop being retried. Backends keep histograms of these values in recent history. When a backend needs to reject a request, it consults these histograms to determine the likelihood that other backend tasks are also overloaded. If these histograms reveal a significant amount of retries (indicating that other backend tasks are likely also overloaded), they return an "overloaded; don't retry" error response instead of the standard "task overloaded" error that triggers retries.

Reference: https://sre.google/sre-book/handling-overload/

func BreakerWithOverloadRatio

func BreakerWithOverloadRatio(name string, overloadRatio float64) Option

BreakerWithOverloadRatio is similar to Breaker, excepts that it accepts an additional param `overloadRatio` to specify the overload ratio to control the retry behavior, it's value should be greater than zero, else the default value 0.1 will be used.

NOTE: generally, the default overload ratio 0.1 or even smaller value should be used, a big overload ratio will not really protect the backend system.

Reference: https://sre.google/sre-book/handling-overload/

func C

func C() Option

C makes the retry function sleep constant time between each retry.

func Hook

func Hook(hook func(attempts int, err error)) Option

Hook let the retry function call the given hook when an error happens.

func J

func J(jitter float64) Option

J makes the retry function use specified jitter between each retry.

func L

func L(step time.Duration) Option

L makes the retry function sleep linear growing time between each retry.

func MaxErrors

func MaxErrors(max int) Option

MaxErrors set max errors to hold when retry for many times.

func MaxSleep

func MaxSleep(max time.Duration) Option

MaxSleep will restrict the retry sleep time to at most max.

func NoJitter

func NoJitter() Option

NoJitter disables the retry function to add jitter to sleep time between each retry.

type Result

type Result struct {
	Ok       bool
	Attempts int
	Error    error
}

func Const

func Const(attempts int, sleep time.Duration, f func() error, opts ...Option) Result

Const retry the target function with constant sleep time. It is shorthand for Retry(attempts, sleep, f, C()).

func Default

func Default(f func() error, opts ...Option) Result

Default will call param function f at most 3 times before returning error. Between each retry will sleep an exponential time starts at 500ms. In case of all retry fails, the total sleep time will be about 750ms - 2250ms.

It is shorthand for Retry(3, 500*time.Millisecond, f).

func Forever

func Forever(sleep, maxSleep time.Duration, f func() error, opts ...Option) Result

Forever retry the target function endlessly if it returns error. To stop the the retry loop on error, the target function should return Stop.

The caller should take care of dead loop.

func Linear

func Linear(attempts int, sleep time.Duration, f func() error, opts ...Option) Result

Linear retry the target function with linear sleep time. It is shorthand for Retry(attempts, sleep, f, L(sleep)).

func Retry

func Retry(attempts int, sleep time.Duration, f func() error, opts ...Option) Result

Retry retry the target function with exponential sleep time. It implements algorithm described in https://upgear.io/blog/simple-golang-retry-function/.

type SizedError

type SizedError struct {
	// contains filtered or unexported fields
}

func NewSizedError

func NewSizedError(size int) *SizedError

NewSizedError returns an multiple error which holds at most size errors. The SizedError implementation is copied from github.com/jxskiss/errors to remove dependency of the package and for better compatibility for future go versions.

func (*SizedError) Append

func (E *SizedError) Append(errs ...error)

func (*SizedError) ErrOrNil

func (E *SizedError) ErrOrNil() error

func (*SizedError) Error

func (E *SizedError) Error() string

func (*SizedError) Errors

func (E *SizedError) Errors() (errors []error)

Errors returns the errors as a slice in reversed order, if the underlying errors are more than size, only size errors will be returned, plus an additional error indicates the omitted error count.

func (*SizedError) Format

func (E *SizedError) Format(f fmt.State, c rune)

type Stop

type Stop struct {
	Err error
}

Stop is used to indicate the retry function to stop retry.

func (Stop) Error

func (e Stop) Error() string