package retry

import "github.com/aws/aws-sdk-go-v2/aws/retry"

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:

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)

Code:play  

package main

import (
	"context"
	"log"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/aws/retry"

	config "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"

	s3 "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"
)

func main() {
	cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
		// Generally you will always want to return new instance of a Retryer. This will avoid a global rate limit
		// bucket being shared between across all service clients.
		return retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5)
	}))
	if err != nil {
		log.Fatal(err)
		return
	}

	client := s3.NewFromConfig(cfg)
	_ = client
}
Example (OverrideForSpecificClient)

Code:play  

package main

import (
	"context"
	"log"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws/retry"

	config "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"

	s3 "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"
)

func main() {
	cfg, err := config.LoadDefaultConfig(context.TODO())
	if err != nil {
		log.Fatal(err)
		return
	}

	client := s3.NewFromConfig(cfg, func(options *s3.Options) {
		options.Retryer = retry.AddWithMaxBackoffDelay(options.Retryer, time.Second*5)
	})
	_ = client
}
Example (OverrideSpecificOperation)

Code:play  

package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/aws/retry"

	config "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"

	s3 "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"

	types "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"
)

func main() {
	cfg, err := config.LoadDefaultConfig(context.TODO())
	if err != nil {
		log.Fatal(err)
		return
	}

	client := s3.NewFromConfig(cfg)

	// Wrap the default client retryer with an additional retryable error code for this specific
	// operation invocation
	_, err = client.GetObject(context.Background(), &s3.GetObjectInput{
		Bucket: aws.String("my-bucket"),
		Key:    aws.String("my-key"),
	}, func(options *types.Options) {
		options.Retryer = retry.AddWithErrorCodes(options.Retryer, (*types.NoSuchBucketException)(nil).ErrorCode())
	})
	if err != nil {
		log.Fatal(err)
		return
	}
}

Index

Examples

Constants 

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

Default retry token quota values.

Variables 

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. 

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. 

var DefaultRetryables = []IsErrorRetryable{
	NoRetryCanceledError{},
	RetryableError{},
	RetryableConnectionError{},
	RetryableHTTPStatusCode{
		Codes: DefaultRetryableHTTPStatusCodes,
	},
	RetryableErrorCode{
		Codes: DefaultRetryableErrorCodes,
	},
}

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

Code:play  

package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go-v2/aws/retry"

	types "github.com/aws/aws-sdk-go-v2/aws/retry/internal/mock"
)

func main() {
	// Wrap a standard retyer and add the types.NoSuchBucketException Amazon S3 error code as retryable
	custom := retry.AddWithErrorCodes(retry.NewStandard(), (*types.NoSuchBucketException)(nil).ErrorCode())

	fmt.Println(custom.IsErrorRetryable(&types.NoSuchBucketException{}))
}

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

Code:play  

package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go-v2/aws/retry"
)

func main() {
	// Wrap a standard retyer and set the max attempts to 5
	custom := retry.AddWithMaxAttempts(retry.NewStandard(), 5)

	fmt.Println(custom.MaxAttempts())
}

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

Code:play  

package main

import (
	"time"

	"github.com/aws/aws-sdk-go-v2/aws/retry"
)

func main() {
	// Wrap a standard retyer and add tthe NoSuchBucket API error code to the list of retryables
	custom := retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5)
	_ = custom
}

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 

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 (*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 

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

Source Files

doc.go errors.go jitter_backoff.go metadata.go middleware.go retry.go retryable_error.go standard.go timeout_error.go

Directories

PathSynopsis
aws/retry/internal
Version
v1.3.1
Published
Apr 2, 2021
Platform
linux/amd64
Imports
18 packages
Last checked
8 minutes ago –

Tools for package owners.