retry

Documentation

Overview

This is actually moved from aks/common/retry and we should switch to use the retry in the aks/rp/core/retry filed one work item to track this: https://dev.azure.com/msazure/CloudNativeCompute/_workitems/edit/7483207

Package retry provides utility functions to execute retriable action with alloted timeout duration.

Index

• func GetTimex(ctx context.Context) timing.Timex
• func WithTimex(ctx context.Context, timex timing.Timex) context.Context
• type Actuator
  • func (a *Actuator) Do(ctx context.Context, fn func() error) error
• type CommonError
• type Error
  • func GetError(response *http.Response, err error, extraRetryCodes ...int) *Error
  • func GetGRPCError(err error, extraRetryableCodes ...codes.Code) *Error
  • func NewError(retriable bool, err error) *Error
  • func NewRetriableError(msg string, args ...interface{}) *Error
  • func NewTerminalError(msg string, args ...interface{}) *Error
  • func (err *Error) Status() Status
  • func (err Error) String() string
• type Func
  • func (f Func) RunOnce(ctx context.Context) (Status, interface{}, error)
• type Result
  • func DoFixedRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, ...) (Result, error)
  • func DoJitteryRetry(action func() Result, interval time.Duration, timeout time.Duration, ...) (Result, error)
  • func DoLinearRetry(action func() Result, interval time.Duration, timeout time.Duration) (Result, error)
  • func DoLinearRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, ...) (Result, error)
  • func DoLinearRetryWithMaxCountWithTimex(action func() Result, interval time.Duration, timeout time.Duration, ...) (Result, error)
  • func DoRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, ...) (Result, error)
• type RetryerInterface
  • func NewRetry(name string, settings Settings, singleIteration SingleIterationInterface) RetryerInterface
• type Settings
• type SingleIterationInterface
• type Status
  • func (s Status) String() string
• type TimeoutError
  • func (t *TimeoutError) Error() string
• type WaitFunc
  • func Fixed(interval time.Duration) WaitFunc
  • func Linear(interval time.Duration) WaitFunc

Functions

func GetTimex

func GetTimex(ctx context.Context) timing.Timex

func WithTimex

func WithTimex(ctx context.Context, timex timing.Timex) context.Context

Types

type Actuator

type Actuator struct {
	// MaxAttempts specifies an optional limit of failed attempts.
	MaxAttempts *int

	// Timeout is an optional time limit for the entire operation including
	// every attempt.
	Timeout *time.Duration

	// Wait is used to determine the amount of time to sleep between attempts.
	// Required.
	Wait WaitFunc

	// BeforeSleep is an optional hook to update the context before the next
	// attempt. Can be used to add the attempt number to a logger.
	BeforeSleep func(ctx context.Context, attempt int, interval time.Duration) context.Context
}

Actuator is capable of invoking an operation with retry logic.

func (*Actuator) Do

func (a *Actuator) Do(ctx context.Context, fn func() error) error

Do retries the given function until err == nil, MaxAttempts is reached, context timeout, or context cancelation.

Retry loop is broken if the returned error satisfies the Error interface and IsTerminal returns true. Otherwise, returning an error will result in another attempt. The caller is responsible for logging or otherwise handling errors.

type CommonError

type CommonError interface {
	// IsTerminal indicates that an operation should not be retried
	// because it cannot succeed.
	IsTerminal() bool
}

Error can be implemented by error types returned by lambdas provided to Do functions in order to influence the retry logic.

type Error

type Error struct {
	Retriable bool
	Error     error
}

Error represents an error returned by APIs

func GetError

func GetError(response *http.Response, err error, extraRetryCodes ...int) *Error

GetError gets common error based on error and http response

func GetGRPCError

func GetGRPCError(err error, extraRetryableCodes ...codes.Code) *Error

GetGRPCError gets common error based on error and grpc status codes

func NewError

func NewError(retriable bool, err error) *Error

NewError creates an error

func NewRetriableError

func NewRetriableError(msg string, args ...interface{}) *Error

NewRetriableError returns a new retriable error with an fmt formatted message.

func NewTerminalError

func NewTerminalError(msg string, args ...interface{}) *Error

NewTerminalError returns a new non-retriable error with an fmt formatted message.

func (*Error) Status

func (err *Error) Status() Status

Status get status from an error

func (Error) String

func (err Error) String() string

type Func

type Func func(context.Context) (interface{}, *Error)

func (Func) RunOnce

func (f Func) RunOnce(ctx context.Context) (Status, interface{}, error)

type Result

type Result struct {
	Status
	Body interface{}
}

A Result specifies the result of retryable action.

func DoFixedRetryWithMaxCount

func DoFixedRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, maxRetries int) (Result, error)

DoFixedRetryWithMaxCount retries the action for either the maxRetries times or the timeout duration with interval duration in between retries

func DoJitteryRetry

func DoJitteryRetry(action func() Result, interval time.Duration, timeout time.Duration, maxRetries int) (Result, error)

DoJitteryRetry retry with random delay at least max times. This avoids multiple clients retrying the same resource at same time Jitter is defined here: https://github.com/App-vNext/Polly/wiki/Retry-with-jitter &https://github.com/avast/retry-go

func DoLinearRetry

func DoLinearRetry(action func() Result, interval time.Duration, timeout time.Duration) (Result, error)

DoLinearRetry retries the action for timeout duration with interval duration in between retries

func DoLinearRetryWithMaxCount

func DoLinearRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, maxRetries int) (Result, error)

DoLinearRetryWithMaxCount retries the action for either the maxRetries times or the timeout duration with (interval * attempt) [attempt starts at 0] in between retries

func DoLinearRetryWithMaxCountWithTimex

func DoLinearRetryWithMaxCountWithTimex(action func() Result, interval time.Duration, timeout time.Duration, maxRetries int, timex timing.Timex) (Result, error)

DoLinearRetryWithMaxCountWithTimex retries the action for either the maxRetries times or the timeout duration with (interval * attempt) [attempt starts at 0] in between retries

func DoRetryWithMaxCount

func DoRetryWithMaxCount(action func() Result, interval time.Duration, timeout time.Duration, maxRetries int, delayfunc func(int, time.Duration) time.Duration) (Result, error)

DoRetryWithMaxCount retries the action for timeout duration with interval duration in between retries, with custom delayfunc, which could be exponential,fixed etc As this function heavily depends on the global function of Time package, which is not easy to mock when testing. As a result, replace it with a new method which has an extra parameter, Timex interface.

type RetryerInterface

type RetryerInterface interface {
	Run(ctx context.Context) (interface{}, error)
}

RetryerInterface is the interface for retryer

func NewRetry

func NewRetry(name string, settings Settings, singleIteration SingleIterationInterface) RetryerInterface

type Settings

type Settings struct {
	Interval      time.Duration
	Timeout       time.Duration
	RetryMaxCount int
}

Settings is settings for retry

type SingleIterationInterface

type SingleIterationInterface interface {
	RunOnce(ctx context.Context) (Status, interface{}, error)
}

type Status

type Status int

Status is an arbitrary status code representing the status of a retry

const (
	Success Status = iota
	Failed
	NeedRetry
	Timedout
)

Status definitions

func (Status) String

func (s Status) String() string

type TimeoutError

type TimeoutError struct {
	Original error
}

TimeoutError is returned when a retry operation has timed out.

func (*TimeoutError) Error

func (t *TimeoutError) Error() string

type WaitFunc

type WaitFunc func(i int) time.Duration

WaitFunc is responsible for determining how long to wait before retrying an operation.

func Fixed

func Fixed(interval time.Duration) WaitFunc

Fixed returns a WaitFunc that always waits for the given duration.

func Linear

func Linear(interval time.Duration) WaitFunc

Linear returns a WaitFunc that always waits for one given duration per attempt.