1// Package retry provides interfaces and implementations for SDK request retry behavior.
 2//
 3// # Retryer Interface and Implementations
 4//
 5// This package defines Retryer interface that is used to either implement custom retry behavior
 6// or to extend the existing retry implementations provided by the SDK. This package provides a single
 7// retry implementation: Standard.
 8//
 9// # Standard
10//
11// Standard is the default retryer implementation used by service clients. The standard retryer is a rate limited
12// retryer that has a configurable max attempts to limit the number of retry attempts when a retryable error occurs.
13// In addition, the retryer uses a configurable token bucket to rate limit the retry attempts across the client,
14// and uses an additional delay policy to limit the time between a requests subsequent attempts.
15//
16// By default the standard retryer uses the DefaultRetryables slice of IsErrorRetryable types to determine whether
17// a given error is retryable. By default this list of retryables includes the following:
18//   - Retrying errors that implement the RetryableError method, and return true.
19//   - Connection Errors
20//   - Errors that implement a ConnectionError, Temporary, or Timeout method that return true.
21//   - Connection Reset Errors.
22//   - net.OpErr types that are dialing errors or are temporary.
23//   - HTTP Status Codes: 500, 502, 503, and 504.
24//   - API Error Codes
25//   - RequestTimeout, RequestTimeoutException
26//   - Throttling, ThrottlingException, ThrottledException, RequestThrottledException, TooManyRequestsException,
27//     RequestThrottled, SlowDown, EC2ThrottledException
28//   - ProvisionedThroughputExceededException, RequestLimitExceeded, BandwidthLimitExceeded, LimitExceededException
29//   - TransactionInProgressException, PriorRequestNotComplete
30//
31// The standard retryer will not retry a request in the event if the context associated with the request
32// has been cancelled. Applications must handle this case explicitly if they wish to retry with a different context
33// value.
34//
35// You can configure the standard retryer implementation to fit your applications by constructing a standard retryer
36// using the NewStandard function, and providing one more functional argument that mutate the StandardOptions
37// structure. StandardOptions provides the ability to modify the token bucket rate limiter, retryable error conditions,
38// and the retry delay policy.
39//
40// For example to modify the default retry attempts for the standard retryer:
41//
42//	// configure the custom retryer
43//	customRetry := retry.NewStandard(func(o *retry.StandardOptions) {
44//	    o.MaxAttempts = 5
45//	})
46//
47//	// create a service client with the retryer
48//	s3.NewFromConfig(cfg, func(o *s3.Options) {
49//	    o.Retryer = customRetry
50//	})
51//
52// # Utilities
53//
54// A number of package functions have been provided to easily wrap retryer implementations in an implementation agnostic
55// way. These are:
56//
57//	AddWithErrorCodes      - Provides the ability to add additional API error codes that should be considered retryable
58//	                        in addition to those considered retryable by the provided retryer.
59//
60//	AddWithMaxAttempts     - Provides the ability to set the max number of attempts for retrying a request by wrapping
61//	                         a retryer implementation.
62//
63//	AddWithMaxBackoffDelay - Provides the ability to set the max back off delay that can occur before retrying a
64//	                         request by wrapping a retryer implementation.
65//
66// The following package functions have been provided to easily satisfy different retry interfaces to further customize
67// a given retryer's behavior:
68//
69//	BackoffDelayerFunc   - Can be used to wrap a function to satisfy the BackoffDelayer interface. For example,
70//	                       you can use this method to easily create custom back off policies to be used with the
71//	                       standard retryer.
72//
73//	IsErrorRetryableFunc - Can be used to wrap a function to satisfy the IsErrorRetryable interface. For example,
74//	                       this can be used to extend the standard retryer to add additional logic to determine if an
75//	                       error should be retried.
76//
77//	IsErrorTimeoutFunc   - Can be used to wrap a function to satisfy IsErrorTimeout interface. For example,
78//	                       this can be used to extend the standard retryer to add additional logic to determine if an
79//	                        error should be considered a timeout.
80package retry