doc.go (4533B)
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. 80 package retry