const (
// DefaultMaxAttempts is the maximum of attempts for an API request
DefaultMaxAttempts int = 3
// DefaultMaxBackoff is the maximum back off delay between attempts
DefaultMaxBackoff time.Duration = 20 * time.Second
)
Default retry token quota values.
const (
DefaultRetryRateTokens uint = 500
DefaultRetryCost uint = 5
DefaultRetryTimeoutCost uint = 10
DefaultNoRetryIncrement uint = 1
)
const (
// DefaultRequestCost is the cost of a single request from the adaptive
// rate limited token bucket.
DefaultRequestCost uint = 1
)
DefaultRetryableErrorCodes provides the set of API error codes that should be retried.
var DefaultRetryableErrorCodes = map[string]struct{}{ "RequestTimeout": {}, "RequestTimeoutException": {}, }
DefaultRetryableHTTPStatusCodes is the default set of HTTP status codes the SDK should consider as retryable errors.
var DefaultRetryableHTTPStatusCodes = map[int]struct{}{ 500: {}, 502: {}, 503: {}, 504: {}, }
DefaultRetryables provides the set of retryable checks that are used by default.
var DefaultRetryables = []IsErrorRetryable{ NoRetryCanceledError{}, RetryableError{}, RetryableConnectionError{}, RetryableHTTPStatusCode{ Codes: DefaultRetryableHTTPStatusCodes, }, RetryableErrorCode{ Codes: DefaultRetryableErrorCodes, }, RetryableErrorCode{ Codes: DefaultThrottleErrorCodes, }, }
DefaultThrottleErrorCodes provides the set of API error codes that are considered throttle errors.
var DefaultThrottleErrorCodes = map[string]struct{}{ "Throttling": {}, "ThrottlingException": {}, "ThrottledException": {}, "RequestThrottledException": {}, "TooManyRequestsException": {}, "ProvisionedThroughputExceededException": {}, "TransactionInProgressException": {}, "RequestLimitExceeded": {}, "BandwidthLimitExceeded": {}, "LimitExceededException": {}, "RequestThrottled": {}, "SlowDown": {}, "PriorRequestNotComplete": {}, "EC2ThrottledException": {}, }
DefaultThrottles provides the set of errors considered throttle errors that are checked by default.
var DefaultThrottles = []IsErrorThrottle{ ThrottleErrorCode{ Codes: DefaultThrottleErrorCodes, }, }
DefaultTimeouts provides the set of timeout checks that are used by default.
var DefaultTimeouts = []IsErrorTimeout{ TimeouterError{}, }
func AddRetryMiddlewares(stack *smithymiddle.Stack, options AddRetryMiddlewaresOptions) error
AddRetryMiddlewares adds retry middleware to operation middleware stack
func AddWithErrorCodes(r aws.Retryer, codes ...string) aws.Retryer
AddWithErrorCodes returns a Retryer with additional error codes considered for determining if the error should be retried.
▹ Example
func AddWithMaxAttempts(r aws.Retryer, max int) aws.Retryer
AddWithMaxAttempts returns a Retryer with MaxAttempts set to the value specified.
▹ Example
func AddWithMaxBackoffDelay(r aws.Retryer, delay time.Duration) aws.Retryer
AddWithMaxBackoffDelay returns a retryer wrapping the passed in retryer overriding the RetryDelay behavior for a alternate minimum initial backoff delay.
▹ Example
AdaptiveMode provides an experimental retry strategy that expands on the Standard retry strategy, adding client attempt rate limits. The attempt rate limit is initially unrestricted, but becomes restricted when the attempt fails with for a throttle error. When restricted AdaptiveMode may need to sleep before an attempt is made, if too many throttles have been received. AdaptiveMode's sleep can be canceled with context cancel. Set AdaptiveModeOptions FailOnNoAttemptTokens to change the behavior from sleep, to fail fast.
Eventually unrestricted attempt rate limit will be restored once attempts no longer are failing due to throttle errors.
type AdaptiveMode struct {
// contains filtered or unexported fields
}
func NewAdaptiveMode(optFns ...func(*AdaptiveModeOptions)) *AdaptiveMode
NewAdaptiveMode returns an initialized AdaptiveMode retry strategy.
func (a *AdaptiveMode) GetAttemptToken(ctx context.Context) (func(error) error, error)
GetAttemptToken returns the attempt token that can be used to rate limit attempt calls. Will be used by the SDK's retry package's Attempt middleware to get an attempt token prior to calling the temp and releasing the attempt token after the attempt has been made.
func (a *AdaptiveMode) GetInitialToken() (releaseToken func(error) error)
GetInitialToken returns the initial attempt token that can increment the retry token pool if the attempt is successful.
Deprecated: This method does not provide a way to block using Context, nor can it return an error. Use RetryerV2, and GetAttemptToken instead. Only present to implement Retryer interface.
func (a *AdaptiveMode) GetRetryToken(ctx context.Context, opErr error) ( releaseToken func(error) error, err error, )
GetRetryToken attempts to deduct the retry cost from the retry token pool. Returning the token release function, or error.
func (a *AdaptiveMode) IsErrorRetryable(err error) bool
IsErrorRetryable returns if the failed attempt is retryable. This check should determine if the error can be retried, or if the error is terminal.
func (a *AdaptiveMode) MaxAttempts() int
MaxAttempts returns the maximum number of attempts that can be made for an attempt before failing. A value of 0 implies that the attempt should be retried until it succeeds if the errors are retryable.
func (a *AdaptiveMode) RetryDelay(attempt int, opErr error) ( time.Duration, error, )
RetryDelay returns the delay that should be used before retrying the attempt. Will return error if the if the delay could not be determined.
AdaptiveModeOptions provides the functional options for configuring the adaptive retry mode, and delay behavior.
type AdaptiveModeOptions struct {
// If the adaptive token bucket is empty, when an attempt will be made
// AdaptiveMode will sleep until a token is available. This can occur when
// attempts fail with throttle errors. Use this option to disable the sleep
// until token is available, and return error immediately.
FailOnNoAttemptTokens bool
// The cost of an attempt from the AdaptiveMode's adaptive token bucket.
RequestCost uint
// Set of strategies to determine if the attempt failed due to a throttle
// error.
//
// It is safe to append to this list in NewAdaptiveMode's functional options.
Throttles []IsErrorThrottle
// Set of options for standard retry mode that AdaptiveMode is built on top
// of. AdaptiveMode may apply its own defaults to Standard retry mode that
// are different than the defaults of NewStandard. Use these options to
// override the default options.
StandardOptions []func(*StandardOptions)
}
AddRetryMiddlewaresOptions is the set of options that can be passed to AddRetryMiddlewares for configuring retry associated middleware.
type AddRetryMiddlewaresOptions struct {
Retryer aws.Retryer
// Enable the logging of retry attempts performed by the SDK. This will
// include logging retry attempts, unretryable errors, and when max
// attempts are reached.
LogRetryAttempts bool
}
Attempt is a Smithy Finalize middleware that handles retry attempts using the provided Retryer implementation.
type Attempt struct {
// Enable the logging of retry attempts performed by the SDK. This will
// include logging retry attempts, unretryable errors, and when max
// attempts are reached.
LogAttempts bool
// contains filtered or unexported fields
}
func NewAttemptMiddleware(retryer aws.Retryer, requestCloner RequestCloner, optFns ...func(*Attempt)) *Attempt
NewAttemptMiddleware returns a new Attempt retry middleware.
func (r *Attempt) HandleFinalize(ctx context.Context, in smithymiddle.FinalizeInput, next smithymiddle.FinalizeHandler) ( out smithymiddle.FinalizeOutput, metadata smithymiddle.Metadata, err error, )
HandleFinalize utilizes the provider Retryer implementation to attempt retries over the next handler
func (r *Attempt) ID() string
ID returns the middleware identifier
AttemptResult represents attempt result returned by a single request attempt.
type AttemptResult struct {
// Err is the error if received for the request attempt.
Err error
// Retryable denotes if request may be retried. This states if an
// error is considered retryable.
Retryable bool
// Retried indicates if this request was retried.
Retried bool
// ResponseMetadata is any existing metadata passed via the response middlewares.
ResponseMetadata middleware.Metadata
}
func (a AttemptResult) GetRawResponse() interface{}
GetRawResponse returns raw response recorded for the attempt result
AttemptResults represents struct containing metadata returned by all request attempts.
type AttemptResults struct {
// Results is a slice consisting attempt result from all request attempts.
// Results are stored in order request attempt is made.
Results []AttemptResult
}
func GetAttemptResults(metadata middleware.Metadata) (AttemptResults, bool)
GetAttemptResults retrieves attempts results from middleware metadata.
BackoffDelayer provides the interface for determining the delay to before another request attempt, that previously failed.
type BackoffDelayer interface {
BackoffDelay(attempt int, err error) (time.Duration, error)
}
BackoffDelayerFunc provides a wrapper around a function to determine the backoff delay of an attempt retry.
type BackoffDelayerFunc func(int, error) (time.Duration, error)
func (fn BackoffDelayerFunc) BackoffDelay(attempt int, err error) (time.Duration, error)
BackoffDelay returns the delay before attempt to retry a request.
ExponentialJitterBackoff provides backoff delays with jitter based on the number of attempts.
type ExponentialJitterBackoff struct {
// contains filtered or unexported fields
}
func NewExponentialJitterBackoff(maxBackoff time.Duration) *ExponentialJitterBackoff
NewExponentialJitterBackoff returns an ExponentialJitterBackoff configured for the max backoff.
func (j *ExponentialJitterBackoff) BackoffDelay(attempt int, err error) (time.Duration, error)
BackoffDelay returns the duration to wait before the next attempt should be made. Returns an error if unable get a duration.
IsErrorRetryable provides the interface of an implementation to determine if a error as the result of an operation is retryable.
type IsErrorRetryable interface {
IsErrorRetryable(error) aws.Ternary
}
IsErrorRetryableFunc wraps a function with the IsErrorRetryable interface.
type IsErrorRetryableFunc func(error) aws.Ternary
func (fn IsErrorRetryableFunc) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable returns if the error is retryable.
IsErrorRetryables is a collection of checks to determine of the error is retryable. Iterates through the checks and returns the state of retryable if any check returns something other than unknown.
type IsErrorRetryables []IsErrorRetryable
func (r IsErrorRetryables) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable returns if the error is retryable if any of the checks in the list return a value other than unknown.
IsErrorThrottle provides the interface of an implementation to determine if a error response from an operation is a throttling error.
type IsErrorThrottle interface {
IsErrorThrottle(error) aws.Ternary
}
IsErrorThrottleFunc wraps a function with the IsErrorThrottle interface.
type IsErrorThrottleFunc func(error) aws.Ternary
func (fn IsErrorThrottleFunc) IsErrorThrottle(err error) aws.Ternary
IsErrorThrottle returns if the error is a throttle error.
IsErrorThrottles is a collection of checks to determine of the error a throttle error. Iterates through the checks and returns the state of throttle if any check returns something other than unknown.
type IsErrorThrottles []IsErrorThrottle
func (r IsErrorThrottles) IsErrorThrottle(err error) aws.Ternary
IsErrorThrottle returns if the error is a throttle error if any of the checks in the list return a value other than unknown.
IsErrorTimeout provides the interface of an implementation to determine if a error matches.
type IsErrorTimeout interface {
IsErrorTimeout(err error) aws.Ternary
}
IsErrorTimeoutFunc wraps a function with the IsErrorTimeout interface.
type IsErrorTimeoutFunc func(error) aws.Ternary
func (fn IsErrorTimeoutFunc) IsErrorTimeout(err error) aws.Ternary
IsErrorTimeout returns if the error is retryable.
IsErrorTimeouts is a collection of checks to determine of the error is retryable. Iterates through the checks and returns the state of retryable if any check returns something other than unknown.
type IsErrorTimeouts []IsErrorTimeout
func (ts IsErrorTimeouts) IsErrorTimeout(err error) aws.Ternary
IsErrorTimeout returns if the error is retryable if any of the checks in the list return a value other than unknown.
MaxAttemptsError provides the error when the maximum number of attempts have been exceeded.
type MaxAttemptsError struct {
Attempt int
Err error
}
func (e *MaxAttemptsError) Error() string
func (e *MaxAttemptsError) Unwrap() error
Unwrap returns the nested error causing the max attempts error. Provides the implementation for errors.Is and errors.As to unwrap nested errors.
MetricsHeader attaches SDK request metric header for retries to the transport
type MetricsHeader struct{}
func (r MetricsHeader) HandleFinalize(ctx context.Context, in smithymiddle.FinalizeInput, next smithymiddle.FinalizeHandler) ( out smithymiddle.FinalizeOutput, metadata smithymiddle.Metadata, err error, )
HandleFinalize attaches the SDK request metric header to the transport layer
func (r *MetricsHeader) ID() string
ID returns the middleware identifier
NoRetryCanceledError detects if the error was an request canceled error and returns if so.
type NoRetryCanceledError struct{}
func (NoRetryCanceledError) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable returns the error is not retryable if the request was canceled.
RateLimiter provides the interface for limiting the rate of attempt retries allowed by the retryer.
type RateLimiter interface {
GetToken(ctx context.Context, cost uint) (releaseToken func() error, err error)
AddTokens(uint) error
}
RequestCloner is a function that can take an input request type and clone the request for use in a subsequent retry attempt.
type RequestCloner func(interface{}) interface{}
RetryableConnectionError determines if the underlying error is an HTTP connection and returns if it should be retried.
Includes errors such as connection reset, connection refused, net dial, temporary, and timeout errors.
type RetryableConnectionError struct{}
func (r RetryableConnectionError) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable returns if the error is caused by and HTTP connection error, and should be retried.
RetryableError is an IsErrorRetryable implementation which uses the optional interface Retryable on the error value to determine if the error is retryable.
type RetryableError struct{}
func (RetryableError) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable returns if the error is retryable if it satisfies the Retryable interface, and returns if the attempt should be retried.
RetryableErrorCode determines if an attempt should be retried based on the API error code.
type RetryableErrorCode struct {
Codes map[string]struct{}
}
func (r RetryableErrorCode) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable return if the error is retryable based on the error codes. Returns unknown if the error doesn't have a code or it is unknown.
RetryableHTTPStatusCode provides a IsErrorRetryable based on HTTP status codes.
type RetryableHTTPStatusCode struct {
Codes map[int]struct{}
}
func (r RetryableHTTPStatusCode) IsErrorRetryable(err error) aws.Ternary
IsErrorRetryable return if the passed in error is retryable based on the HTTP status code.
Standard is the standard retry pattern for the SDK. It uses a set of retryable checks to determine of the failed attempt should be retried, and what retry delay should be used.
type Standard struct {
// contains filtered or unexported fields
}
func NewStandard(fnOpts ...func(*StandardOptions)) *Standard
NewStandard initializes a standard retry behavior with defaults that can be overridden via functional options.
func (s *Standard) GetAttemptToken(context.Context) (func(error) error, error)
GetAttemptToken returns the token to be released after then attempt completes. The release token will add NoRetryIncrement to the RateLimiter token pool if the attempt was successful. If the attempt failed, nothing will be done.
func (s *Standard) GetInitialToken() func(error) error
GetInitialToken returns a token for adding the NoRetryIncrement to the RateLimiter token if the attempt completed successfully without error.
InitialToken applies to result of the each attempt, including the first. Whereas the RetryToken applies to the result of subsequent attempts.
Deprecated: use GetAttemptToken instead.
func (s *Standard) GetRetryToken(ctx context.Context, opErr error) (func(error) error, error)
GetRetryToken attempts to deduct the retry cost from the retry token pool. Returning the token release function, or error.
func (s *Standard) IsErrorRetryable(err error) bool
IsErrorRetryable returns if the error is can be retried or not. Should not consider the number of attempts made.
func (s *Standard) MaxAttempts() int
MaxAttempts returns the maximum number of attempts that can be made for a request before failing.
func (s *Standard) RetryDelay(attempt int, err error) (time.Duration, error)
RetryDelay returns the delay to use before another request attempt is made.
StandardOptions provides the functional options for configuring the standard retryable, and delay behavior.
type StandardOptions struct {
// Maximum number of attempts that should be made.
MaxAttempts int
// MaxBackoff duration between retried attempts.
MaxBackoff time.Duration
// Provides the backoff strategy the retryer will use to determine the
// delay between retry attempts.
Backoff BackoffDelayer
// Set of strategies to determine if the attempt should be retried based on
// the error response received.
//
// It is safe to append to this list in NewStandard's functional options.
Retryables []IsErrorRetryable
// Set of strategies to determine if the attempt failed due to a timeout
// error.
//
// It is safe to append to this list in NewStandard's functional options.
Timeouts []IsErrorTimeout
// Provides the rate limiting strategy for rate limiting attempt retries
// across all attempts the retryer is being used with.
//
// A RateLimiter operates as a token bucket with a set capacity, where
// attempt failures events consume tokens. A retry attempt that attempts to
// consume more tokens than what's available results in operation failure.
// The default implementation is parameterized as follows:
// - a capacity of 500 (DefaultRetryRateTokens)
// - a retry caused by a timeout costs 10 tokens (DefaultRetryCost)
// - a retry caused by other errors costs 5 tokens (DefaultRetryTimeoutCost)
// - an operation that succeeds on the 1st attempt adds 1 token (DefaultNoRetryIncrement)
//
// You can disable rate limiting by setting this field to ratelimit.None.
RateLimiter RateLimiter
// The cost to deduct from the RateLimiter's token bucket per retry.
RetryCost uint
// The cost to deduct from the RateLimiter's token bucket per retry caused
// by timeout error.
RetryTimeoutCost uint
// The cost to payback to the RateLimiter's token bucket for successful
// attempts.
NoRetryIncrement uint
}
ThrottleErrorCode determines if an attempt should be retried based on the API error code.
type ThrottleErrorCode struct {
Codes map[string]struct{}
}
func (r ThrottleErrorCode) IsErrorThrottle(err error) aws.Ternary
IsErrorThrottle return if the error is a throttle error based on the error codes. Returns unknown if the error doesn't have a code or it is unknown.
TimeouterError provides the IsErrorTimeout implementation for determining if an error is a timeout based on type with the Timeout method.
type TimeouterError struct{}
func (t TimeouterError) IsErrorTimeout(err error) aws.Ternary
IsErrorTimeout returns if the error is a timeout error.
| Name | Synopsis |
|---|---|
| .. | |