package retry

Import Path
	github.com/aws/aws-sdk-go-v2/aws/retry (on go.dev)

Dependency Relation
	imports 19 packages, and imported by one package


Involved Source Files

	      adaptive.go
	      adaptive_ratelimit.go
	      adaptive_token_bucket.go
	
		Package retry provides interfaces and implementations for SDK request retry behavior.

		# Retryer Interface and Implementations

		This package defines Retryer interface that is used to either implement custom retry behavior
		or to extend the existing retry implementations provided by the SDK. This package provides a single
		retry implementation: 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 argument 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 to determine if an
		                       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.

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


Code Examples

	
		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{}))
		}

	
		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())
		}

	
		package main
		
		import (
			"github.com/aws/aws-sdk-go-v2/aws/retry"
			"time"
		)
		
		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
		}

	
		package main
		
		import (
			"context"
			"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"
			"log"
			"time"
		)
		
		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
		}

	
		package main
		
		import (
			"context"
			"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"
			"log"
			"time"
		)
		
		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
		}

	
		package main
		
		import (
			"context"
			"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"
			"log"
		)
		
		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
			}
		}




Package-Level Type Names (total 41, in which 31 are exported)


	/* sort exporteds by:  |  */
	
		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.

		
			
		
			
				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.

			
				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.

			
				GetRetryToken attempts to deduct the retry cost from the retry token pool.
				Returning the token release function, or error.

			
				IsErrorRetryable returns if the failed attempt is retryable. This check
				should determine if the error can be retried, or if the error is
				terminal.

			
				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.

			
				RetryDelay returns the delay that should be used before retrying the
				attempt. Will return error if the if the delay could not be determined.

			
		
			*AdaptiveMode : github.com/aws/aws-sdk-go-v2/aws.Retryer
			*AdaptiveMode : github.com/aws/aws-sdk-go-v2/aws.RetryerV2
		
			func NewAdaptiveMode(optFns ...func(*AdaptiveModeOptions)) *AdaptiveMode


	
		AdaptiveModeOptions provides the functional options for configuring the
		adaptive retry mode, and delay behavior.

		
			
				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.

			
				The cost of an attempt from the AdaptiveMode's adaptive token bucket.

			
				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.

			
				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.



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

		
			
				Enable the logging of retry attempts performed by the SDK. This will
				include logging retry attempts, unretryable errors, and when max
				attempts are reached.

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


	
		Attempt is a Smithy Finalize middleware that handles retry attempts using
		the provided Retryer implementation.

		
			
				Enable the logging of retry attempts performed by the SDK. This will
				include logging retry attempts, unretryable errors, and when max
				attempts are reached.

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

			
				ID returns the middleware identifier

			
		
			*Attempt : github.com/aws/smithy-go/middleware.FinalizeMiddleware
			
		
			func NewAttemptMiddleware(retryer aws.Retryer, requestCloner RequestCloner, optFns ...func(*Attempt)) *Attempt


	
		AttemptResult represents attempt result returned by a single request attempt.

		
			
				Err is the error if received for the request attempt.

			
				ResponseMetadata is any existing metadata passed via the response middlewares.

			
				Retried indicates if this request was retried.

			
				Retryable denotes if request may be retried. This states if an
				error is considered retryable.

		
			
				GetRawResponse returns raw response recorded for the attempt result

		
			


	
		AttemptResults represents struct containing metadata returned by all request attempts.

		
			
				Results is a slice consisting attempt result from all request attempts.
				Results are stored in order request attempt is made.

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


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

		
			( BackoffDelayer) BackoffDelay(attempt int, err error) (time.Duration, error)
		
			 BackoffDelayerFunc
			*ExponentialJitterBackoff


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

		
			
				BackoffDelay returns the delay before attempt to retry a request.

		
			 BackoffDelayerFunc : BackoffDelayer


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

		
			
		
			
				BackoffDelay returns the duration to wait before the next attempt should be
				made. Returns an error if unable get a duration.

		
			*ExponentialJitterBackoff : BackoffDelayer
		
			func NewExponentialJitterBackoff(maxBackoff time.Duration) *ExponentialJitterBackoff


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

		
			( IsErrorRetryable) IsErrorRetryable(error) aws.Ternary
		
			 IsErrorRetryableFunc
			 IsErrorRetryables
			 NoRetryCanceledError
			 RetryableConnectionError
			 RetryableError
			 RetryableErrorCode
			 RetryableHTTPStatusCode


	
		IsErrorRetryableFunc wraps a function with the IsErrorRetryable interface.

		
			
				IsErrorRetryable returns if the error is retryable.

		
			 IsErrorRetryableFunc : 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.

		
			
				IsErrorRetryable returns if the error is retryable if any of the checks in
				the list return a value other than unknown.

		
			 IsErrorRetryables : IsErrorRetryable


	
		IsErrorThrottle provides the interface of an implementation to determine if
		a error response from an operation is a throttling error.

		
			( IsErrorThrottle) IsErrorThrottle(error) aws.Ternary
		
			 IsErrorThrottleFunc
			 IsErrorThrottles
			 ThrottleErrorCode


	
		IsErrorThrottleFunc wraps a function with the IsErrorThrottle interface.

		
			
				IsErrorThrottle returns if the error is a throttle error.

		
			 IsErrorThrottleFunc : IsErrorThrottle


	
		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.

		
			
				IsErrorThrottle returns if the error is a throttle error if any of the
				checks in the list return a value other than unknown.

		
			 IsErrorThrottles : IsErrorThrottle


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

		
			( IsErrorTimeout) IsErrorTimeout(err error) aws.Ternary
		
			 IsErrorTimeoutFunc
			 IsErrorTimeouts
			 TimeouterError


	
		IsErrorTimeoutFunc wraps a function with the IsErrorTimeout interface.

		
			
				IsErrorTimeout returns if the error is retryable.

		
			 IsErrorTimeoutFunc : 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.

		
			
				IsErrorTimeout returns if the error is retryable if any of the checks in
				the list return a value other than unknown.

		
			 IsErrorTimeouts : IsErrorTimeout


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

		
			Attempt int
			Err error
		
			(*MaxAttemptsError) Error() string
			
				Unwrap returns the nested error causing the max attempts error. Provides the
				implementation for errors.Is and errors.As to unwrap nested errors.

		
			*MaxAttemptsError : error


	
		MetricsHeader attaches SDK request metric header for retries to the transport

		
			
				HandleFinalize attaches the SDK request metric header to the transport layer

			
				ID returns the middleware identifier

		
			*MetricsHeader : github.com/aws/smithy-go/middleware.FinalizeMiddleware
			


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

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

		
			 NoRetryCanceledError : IsErrorRetryable


	
		RateLimiter provides the interface for limiting the rate of attempt retries
		allowed by the retryer.

		
			( RateLimiter) AddTokens(uint) error
			( RateLimiter) GetToken(ctx context.Context, cost uint) (releaseToken func() error, err error)
		
			*github.com/aws/aws-sdk-go-v2/aws/ratelimit.TokenRateLimit


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

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


	
		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.

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

		
			 RetryableConnectionError : IsErrorRetryable


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

		
			
				IsErrorRetryable returns if the error is retryable if it satisfies the
				Retryable interface, and returns if the attempt should be retried.

		
			 RetryableError : IsErrorRetryable


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

		
			Codes map[string]struct{}
		
			
				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.

		
			 RetryableErrorCode : IsErrorRetryable


	
		RetryableHTTPStatusCode provides a IsErrorRetryable based on HTTP status
		codes.

		
			Codes map[int]struct{}
		
			
				IsErrorRetryable return if the passed in error is retryable based on the
				HTTP status code.

		
			 RetryableHTTPStatusCode : IsErrorRetryable


	
		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.

		
			
		
			
				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.

			
				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.

			
				GetRetryToken attempts to deduct the retry cost from the retry token pool.
				Returning the token release function, or error.

			
				IsErrorRetryable returns if the error is can be retried or not. Should not
				consider the number of attempts made.

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

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

			
		
			*Standard : github.com/aws/aws-sdk-go-v2/aws.Retryer
			*Standard : github.com/aws/aws-sdk-go-v2/aws.RetryerV2
		
			func NewStandard(fnOpts ...func(*StandardOptions)) *Standard


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

		
			
				Provides the backoff strategy the retryer will use to determine the
				delay between retry attempts.

			
				Maximum number of attempts that should be made.

			
				MaxBackoff duration between retried attempts.

			
				The cost to payback to the RateLimiter's token bucket for successful
				attempts.

			
				Provides the rate limiting strategy for rate limiting attempt retries
				across all attempts the retryer is being used with.

			
				The cost to deduct from the RateLimiter's token bucket per retry.

			
				The cost to deduct from the RateLimiter's token bucket per retry caused
				by timeout error.

			
				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.

			
				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.



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

		
			Codes map[string]struct{}
		
			
				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.

		
			 ThrottleErrorCode : IsErrorThrottle


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

		
			
				IsErrorTimeout returns if the error is a timeout error.

		
			 TimeouterError : IsErrorTimeout


	


Package-Level Functions (total 19, in which 9 are exported)


	
		AddRetryMiddlewares adds retry middleware to operation middleware stack


	
		AddWithErrorCodes returns a Retryer with additional error codes considered
		for determining if the error should be retried.


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


	
		AddWithMaxBackoffDelay returns a retryer wrapping the passed in retryer
		overriding the RetryDelay behavior for a alternate minimum initial backoff
		delay.


	
		GetAttemptResults retrieves attempts results from middleware metadata.


	
		NewAdaptiveMode returns an initialized AdaptiveMode retry strategy.


	
		NewAttemptMiddleware returns a new Attempt retry middleware.


	
		NewExponentialJitterBackoff returns an ExponentialJitterBackoff configured
		for the max backoff.


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


	


Package-Level Variables (total 6, all are exported)


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


	
		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.


	
		DefaultThrottleErrorCodes provides the set of API error codes that are
		considered throttle errors.


	
		DefaultThrottles provides the set of errors considered throttle errors that
		are checked by default.


	
		DefaultTimeouts provides the set of timeout checks that are used by default.




Package-Level Constants (total 7, all are exported)


	
		DefaultMaxAttempts is the maximum of attempts for an API request


	
		DefaultMaxBackoff is the maximum back off delay between attempts


	
		Default retry token quota values.


	
		DefaultRequestCost is the cost of a single request from the adaptive
		rate limited token bucket.


	
		Default retry token quota values.


	
		Default retry token quota values.


	
		Default retry token quota values.