src

Go monorepo.
git clone git://code.dwrz.net/src
Log | Files | Refs

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