Documentation

Overview

Package retry provides interfaces and implementations for SDK request retry behavior.

Retryer Interface and Implementations

This packages defines Retryer interface that is used to either implement custom retry behavior or to extend the existing retry implementations provided by the SDK. This packages provides a single retry implementations: Standard.

Standard

Standard is the default retryer implementation used by service clients. The standard retryer is a rate limited retryer that has a configurable max attempts to limit the number of retry attempts when a retryable error occurs. In addition, the retryer uses a configurable token bucket to rate limit the retry attempts across the client, and uses an additional delay policy to limit the time between a requests subsequent attempts.

By default the standard retryer uses the DefaultRetryables slice of IsErrorRetryable types to determine whether a given error is retryable. By default this list of retryables includes the following:

- Retrying errors that implement the RetryableError method, and return true.
- Connection Errors
  - Errors that implement a ConnectionError, Temporary, or Timeout method that return true.
  - Connection Reset Errors.
  - net.OpErr types that are dialing errors or are temporary.
  - HTTP Status Codes: 500, 502, 503, and 504.
- API Error Codes
  - RequestTimeout, RequestTimeoutException
  - Throttling, ThrottlingException, ThrottledException, RequestThrottledException, TooManyRequestsException,
    RequestThrottled, SlowDown, EC2ThrottledException
  - ProvisionedThroughputExceededException, RequestLimitExceeded, BandwidthLimitExceeded, LimitExceededException
  - TransactionInProgressException, PriorRequestNotComplete

The standard retryer will not retry a request in the event if the context associated with the request has been cancelled. Applications must handle this case explicitly if they wish to retry with a different context value.

You can configure the standard retryer implementation to fit your applications by constructing a standard retryer using the NewStandard function, and providing one more functional arguments that mutate the StandardOptions structure. StandardOptions provides the ability to modify the token bucket rate limiter, retryable error conditions, and the retry delay policy.

For example to modify the default retry attempts for the standard retryer:

// configure the custom retryer
customRetry := retry.NewStandard(func(o *retry.StandardOptions) {
    o.MaxAttempts = 5
})

// create a service client with the retryer
s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Retryer = customRetry
})

Utilities

A number of package functions have been provided to easily wrap retryer implementations in an implementation agnostic way. These are:

AddWithErrorCodes      - Provides the ability to add additional API error codes that should be considered retryable
                        in addition to those considered retryable by the provided retryer.

AddWithMaxAttempts     - Provides the ability to set the max number of attempts for retrying a request by wrapping
                         a retryer implementation.

AddWithMaxBackoffDelay - Provides the ability to set the max back off delay that can occur before retrying a
                         request by wrapping a retryer implementation.

The following package functions have been provided to easily satisfy different retry interfaces to further customize a given retryer's behavior:

BackoffDelayerFunc   - Can be used to wrap a function to satisfy the BackoffDelayer interface. For example,
                       you can use this method to easily create custom back off policies to be used with the
                       standard retryer.

IsErrorRetryableFunc - Can be used to wrap a function to satisfy the IsErrorRetryable interface. For example,
                       this can be used to extend the standard retryer to add additional logic ot determine if a
                       error should be retried.

IsErrorTimeoutFunc   - Can be used to wrap a function to satisfy IsErrorTimeout interface. For example,
                       this can be used to extend the standard retryer to add additional logic to determine if an
                        error should be considered a timeout.
Example (OverrideForAllClients)
Output:

Example (OverrideForSpecificClient)
Output:

Example (OverrideSpecificOperation)
Output:

Index

Examples

Constants

View Source
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
)
View Source
const (
	DefaultRetryRateTokens  uint = 500
	DefaultRetryCost        uint = 5
	DefaultRetryTimeoutCost uint = 10
	DefaultNoRetryIncrement uint = 1
)

    Default retry token quota values.

    Variables

    View Source
    var DefaultRetryableErrorCodes = map[string]struct{}{
    	"RequestTimeout":          {},
    	"RequestTimeoutException": {},
    
    	"Throttling":                             {},
    	"ThrottlingException":                    {},
    	"ThrottledException":                     {},
    	"RequestThrottledException":              {},
    	"TooManyRequestsException":               {},
    	"ProvisionedThroughputExceededException": {},
    	"TransactionInProgressException":         {},
    	"RequestLimitExceeded":                   {},
    	"BandwidthLimitExceeded":                 {},
    	"LimitExceededException":                 {},
    	"RequestThrottled":                       {},
    	"SlowDown":                               {},
    	"PriorRequestNotComplete":                {},
    	"EC2ThrottledException":                  {},
    }

      DefaultRetryableErrorCodes provides the set of API error codes that should be retried.

      View Source
      var DefaultRetryableHTTPStatusCodes = map[int]struct{}{
      	500: {},
      	502: {},
      	503: {},
      	504: {},
      }

        DefaultRetryableHTTPStatusCodes is the default set of HTTP status codes the SDK should consider as retryable errors.

          DefaultRetryables provides the set of retryable checks that are used by default.

          Functions

          func AddRetryMiddlewares

          func AddRetryMiddlewares(stack *smithymiddle.Stack, options AddRetryMiddlewaresOptions) error

            AddRetryMiddlewares adds retry middleware to operation middleware stack

            func AddWithErrorCodes

            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
              Output:
              
              true
              

              func AddWithMaxAttempts

              func AddWithMaxAttempts(r aws.Retryer, max int) aws.Retryer

                AddWithMaxAttempts returns a Retryer with MaxAttempts set to the value specified.

                Example
                Output:
                
                5
                

                func AddWithMaxBackoffDelay

                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
                  Output:
                  
                  

                  Types

                  type AddRetryMiddlewaresOptions

                  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
                  }

                    AddRetryMiddlewaresOptions is the set of options that can be passed to AddRetryMiddlewares for configuring retry associated middleware.

                    type Attempt

                    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
                    }

                      Attempt is a Smithy FinalizeMiddleware that handles retry attempts using the provided Retryer implementation

                      func NewAttemptMiddleware

                      func NewAttemptMiddleware(retryer aws.Retryer, requestCloner RequestCloner, optFns ...func(*Attempt)) *Attempt

                        NewAttemptMiddleware returns a new Attempt retry middleware.

                        func (Attempt) HandleFinalize

                          HandleFinalize utilizes the provider Retryer implementation to attempt retries over the next handler

                          func (*Attempt) ID

                          func (r *Attempt) ID() string

                            ID returns the middleware identifier

                            type AttemptResult

                            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
                            }

                              AttemptResult represents attempt result returned by a single request attempt.

                              func (AttemptResult) GetRawResponse

                              func (a AttemptResult) GetRawResponse() interface{}

                                GetRawResponse returns raw response recorded for the attempt result

                                type AttemptResults

                                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
                                }

                                  AttemptResults represents struct containing metadata returned by all request attempts.

                                  func GetAttemptResults

                                  func GetAttemptResults(metadata middleware.Metadata) (AttemptResults, bool)

                                    GetAttemptResults retrieves attempts results from middleware metadata.

                                    type BackoffDelayer

                                    type BackoffDelayer interface {
                                    	BackoffDelay(attempt int, err error) (time.Duration, error)
                                    }

                                      BackoffDelayer provides the interface for determining the delay to before another request attempt, that previously failed.

                                      type BackoffDelayerFunc

                                      type BackoffDelayerFunc func(int, error) (time.Duration, error)

                                        BackoffDelayerFunc provides a wrapper around a function to determine the backoff delay of an attempt retry.

                                        func (BackoffDelayerFunc) BackoffDelay

                                        func (fn BackoffDelayerFunc) BackoffDelay(attempt int, err error) (time.Duration, error)

                                          BackoffDelay returns the delay before attempt to retry a request.

                                          type ExponentialJitterBackoff

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

                                            ExponentialJitterBackoff provides backoff delays with jitter based on the number of attempts.

                                            func NewExponentialJitterBackoff

                                            func NewExponentialJitterBackoff(maxBackoff time.Duration) *ExponentialJitterBackoff

                                              NewExponentialJitterBackoff returns an ExponentialJitterBackoff configured for the max backoff.

                                              func (*ExponentialJitterBackoff) BackoffDelay

                                              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.

                                                type IsErrorRetryable

                                                type IsErrorRetryable interface {
                                                	IsErrorRetryable(error) aws.Ternary
                                                }

                                                  IsErrorRetryable provides the interface of an implementation to determine if a error as the result of an operation is retryable.

                                                  type IsErrorRetryableFunc

                                                  type IsErrorRetryableFunc func(error) aws.Ternary

                                                    IsErrorRetryableFunc wraps a function with the IsErrorRetryable interface.

                                                    func (IsErrorRetryableFunc) IsErrorRetryable

                                                    func (fn IsErrorRetryableFunc) IsErrorRetryable(err error) aws.Ternary

                                                      IsErrorRetryable returns if the error is retryable.

                                                      type IsErrorRetryables

                                                      type IsErrorRetryables []IsErrorRetryable

                                                        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.

                                                        func (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.

                                                          type IsErrorTimeout

                                                          type IsErrorTimeout interface {
                                                          	IsErrorTimeout(err error) aws.Ternary
                                                          }

                                                            IsErrorTimeout provides the interface of an implementation to determine if a error matches.

                                                            type IsErrorTimeoutFunc

                                                            type IsErrorTimeoutFunc func(error) aws.Ternary

                                                              IsErrorTimeoutFunc wraps a function with the IsErrorTimeout interface.

                                                              func (IsErrorTimeoutFunc) IsErrorTimeout

                                                              func (fn IsErrorTimeoutFunc) IsErrorTimeout(err error) aws.Ternary

                                                                IsErrorTimeout returns if the error is retryable.

                                                                type IsErrorTimeouts

                                                                type IsErrorTimeouts []IsErrorTimeout

                                                                  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.

                                                                  func (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.

                                                                    type MaxAttemptsError

                                                                    type MaxAttemptsError struct {
                                                                    	Attempt int
                                                                    	Err     error
                                                                    }

                                                                      MaxAttemptsError provides the error when the maximum number of attempts have been exceeded.

                                                                      func (*MaxAttemptsError) Error

                                                                      func (e *MaxAttemptsError) Error() string

                                                                      func (*MaxAttemptsError) Unwrap

                                                                      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.

                                                                        type MetricsHeader

                                                                        type MetricsHeader struct{}

                                                                          MetricsHeader attaches SDK request metric header for retries to the transport

                                                                          func (MetricsHeader) HandleFinalize

                                                                            HandleFinalize attaches the sdk request metric header to the transport layer

                                                                            func (*MetricsHeader) ID

                                                                            func (r *MetricsHeader) ID() string

                                                                              ID returns the middleware identifier

                                                                              type NoRetryCanceledError

                                                                              type NoRetryCanceledError struct{}

                                                                                NoRetryCanceledError detects if the error was an request canceled error and returns if so.

                                                                                func (NoRetryCanceledError) IsErrorRetryable

                                                                                func (NoRetryCanceledError) IsErrorRetryable(err error) aws.Ternary

                                                                                  IsErrorRetryable returns the error is not retryable if the request was canceled.

                                                                                  type RateLimiter

                                                                                  type RateLimiter interface {
                                                                                  	GetToken(ctx context.Context, cost uint) (releaseToken func() error, err error)
                                                                                  	AddTokens(uint) error
                                                                                  }

                                                                                    RateLimiter provides the interface for limiting the rate of request retries allowed by the retrier.

                                                                                    type RequestCloner

                                                                                    type RequestCloner func(interface{}) interface{}

                                                                                      RequestCloner is a function that can take an input request type and clone the request for use in a subsequent retry attempt

                                                                                      type RetryableConnectionError

                                                                                      type RetryableConnectionError struct{}

                                                                                        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.

                                                                                        func (RetryableConnectionError) IsErrorRetryable

                                                                                        func (r RetryableConnectionError) IsErrorRetryable(err error) aws.Ternary

                                                                                          IsErrorRetryable returns if the error is caused by and HTTP connection error, and should be retried.

                                                                                          type RetryableError

                                                                                          type RetryableError struct{}

                                                                                            RetryableError is an IsErrorRetryable implementation which uses the optional interface Retryable on the error value to determine if the error is retryable.

                                                                                            func (RetryableError) IsErrorRetryable

                                                                                            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.

                                                                                              type RetryableErrorCode

                                                                                              type RetryableErrorCode struct {
                                                                                              	Codes map[string]struct{}
                                                                                              }

                                                                                                RetryableErrorCode determines if an attempt should be retried based on the API error code.

                                                                                                func (RetryableErrorCode) IsErrorRetryable

                                                                                                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.

                                                                                                  type RetryableHTTPStatusCode

                                                                                                  type RetryableHTTPStatusCode struct {
                                                                                                  	Codes map[int]struct{}
                                                                                                  }

                                                                                                    RetryableHTTPStatusCode provides a IsErrorRetryable based on HTTP status codes.

                                                                                                    func (RetryableHTTPStatusCode) IsErrorRetryable

                                                                                                    func (r RetryableHTTPStatusCode) IsErrorRetryable(err error) aws.Ternary

                                                                                                      IsErrorRetryable return if the passed in error is retryable based on the HTTP status code.

                                                                                                      type Standard

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

                                                                                                        Standard is the standard retry pattern for the SDK. It uses a set of retryable checks to determine of the failed request should be retried, and what retry delay should be used.

                                                                                                        func NewStandard

                                                                                                        func NewStandard(fnOpts ...func(*StandardOptions)) *Standard

                                                                                                          NewStandard initializes a standard retry behavior with defaults that can be overridden via functional options.

                                                                                                          func (*Standard) GetInitialToken

                                                                                                          func (s *Standard) GetInitialToken() func(error) error

                                                                                                            GetInitialToken returns the initial request token that can increment the retry token pool if the request is successful.

                                                                                                            func (*Standard) GetRetryToken

                                                                                                            func (s *Standard) GetRetryToken(ctx context.Context, err 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 (*Standard) IsErrorRetryable

                                                                                                              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 (*Standard) MaxAttempts

                                                                                                                func (s *Standard) MaxAttempts() int

                                                                                                                  MaxAttempts returns the maximum number of attempts that can be made for a request before failing.

                                                                                                                  func (*Standard) RetryDelay

                                                                                                                  func (s *Standard) RetryDelay(attempt int, err error) (time.Duration, error)

                                                                                                                    RetryDelay returns the delay to use before another request attempt is made.

                                                                                                                    type StandardOptions

                                                                                                                    type StandardOptions struct {
                                                                                                                    	MaxAttempts int
                                                                                                                    	MaxBackoff  time.Duration
                                                                                                                    	Backoff     BackoffDelayer
                                                                                                                    
                                                                                                                    	Retryables []IsErrorRetryable
                                                                                                                    	Timeouts   []IsErrorTimeout
                                                                                                                    
                                                                                                                    	RateLimiter      RateLimiter
                                                                                                                    	RetryCost        uint
                                                                                                                    	RetryTimeoutCost uint
                                                                                                                    	NoRetryIncrement uint
                                                                                                                    }

                                                                                                                      StandardOptions provides the functional options for configuring the standard retryable, and delay behavior.

                                                                                                                      type TimeouterError

                                                                                                                      type TimeouterError struct{}

                                                                                                                        TimeouterError provides the IsErrorTimeout implementation for determining if an error is a timeout based on type with the Timeout method.

                                                                                                                        func (TimeouterError) IsErrorTimeout

                                                                                                                        func (t TimeouterError) IsErrorTimeout(err error) aws.Ternary

                                                                                                                          IsErrorTimeout returns if the error is a timeout error.

                                                                                                                          Directories

                                                                                                                          Path Synopsis
                                                                                                                          internal