retry

package
v1.26.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2024 License: Apache-2.0 Imports: 20 Imported by: 569

Documentation

Overview

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.
Example (OverrideForAllClients) 
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
}

Output:
Example (OverrideForSpecificClient) 
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
}

Output:
Example (OverrideSpecificOperation) 
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 *s3.Options) {
		options.Retryer = retry.AddWithErrorCodes(options.Retryer, (*types.NoSuchBucketException)(nil).ErrorCode())
	})
	if err != nil {
		log.Fatal(err)
		return
	}
}

Output:

Index

Examples

Constants

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

Default retry token quota values.

View Source 
const (
	// DefaultRequestCost is the cost of a single request from the adaptive
	// rate limited token bucket.
	DefaultRequestCost uint = 1
)

Variables

View Source 
var DefaultRetryableErrorCodes = map[string]struct{}{
	"RequestTimeout":          {},
	"RequestTimeoutException": {},
}

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

View Source 
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.

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

DefaultRetryables provides the set of retryable checks that are used by default.

View Source 
var DefaultThrottleErrorCodes = map[string]struct{}{
	"Throttling":                             {},
	"ThrottlingException":                    {},
	"ThrottledException":                     {},
	"RequestThrottledException":              {},
	"TooManyRequestsException":               {},
	"ProvisionedThroughputExceededException": {},
	"TransactionInProgressException":         {},
	"RequestLimitExceeded":                   {},
	"BandwidthLimitExceeded":                 {},
	"LimitExceededException":                 {},
	"RequestThrottled":                       {},
	"SlowDown":                               {},
	"PriorRequestNotComplete":                {},
	"EC2ThrottledException":                  {},
}

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

View Source 
var DefaultThrottles = []IsErrorThrottle{
	ThrottleErrorCode{
		Codes: DefaultThrottleErrorCodes,
	},
}

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

View Source 
var DefaultTimeouts = []IsErrorTimeout{
	TimeouterError{},
}

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

Functions

func AddRetryMiddlewares added in v0.25.0 

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

Output:

Types

type AdaptiveMode added in v1.14.0 

type AdaptiveMode struct {
	// contains filtered or unexported fields
}

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.

func NewAdaptiveMode added in v1.14.0 

func NewAdaptiveMode(optFns ...func(*AdaptiveModeOptions)) *AdaptiveMode

NewAdaptiveMode returns an initialized AdaptiveMode retry strategy.

func (*AdaptiveMode) GetAttemptToken added in v1.14.0 

func (a *AdaptiveMode) GetAttemptToken(ctx context.Context) (func(error) error, error)

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.

func (*AdaptiveMode) GetInitialToken deprecated added in v1.14.0 

func (a *AdaptiveMode) GetInitialToken() (releaseToken func(error) error)

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.

func (*AdaptiveMode) GetRetryToken added in v1.14.0 

func (a *AdaptiveMode) GetRetryToken(ctx context.Context, opErr error) (
	releaseToken func(error) error, err error,
)

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

func (*AdaptiveMode) IsErrorRetryable added in v1.14.0 

func (a *AdaptiveMode) IsErrorRetryable(err error) bool

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

func (*AdaptiveMode) MaxAttempts added in v1.14.0 

func (a *AdaptiveMode) MaxAttempts() int

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.

func (*AdaptiveMode) RetryDelay added in v1.14.0 

func (a *AdaptiveMode) RetryDelay(attempt int, opErr error) (
	time.Duration, error,
)

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

type AdaptiveModeOptions added in v1.14.0 

type AdaptiveModeOptions struct {
	// 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.
	FailOnNoAttemptTokens bool

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

	// 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.
	Throttles []IsErrorThrottle

	// 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.
	StandardOptions []func(*StandardOptions)
}

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

type AddRetryMiddlewaresOptions added in v0.27.0 

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 added in v0.30.0 

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 Finalize middleware that handles retry attempts using the provided Retryer implementation.

func NewAttemptMiddleware added in v0.21.0 

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

NewAttemptMiddleware returns a new Attempt retry middleware.

func (*Attempt) HandleFinalize added in v0.30.0 

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 added in v0.30.0 

func (r *Attempt) ID() string

ID returns the middleware identifier

type AttemptResult added in v1.0.0 

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 added in v1.0.0 

func (a AttemptResult) GetRawResponse() interface{}

GetRawResponse returns raw response recorded for the attempt result

type AttemptResults added in v1.0.0 

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 added in v1.0.0 

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 IsErrorThrottle added in v1.14.0 

type IsErrorThrottle interface {
	IsErrorThrottle(error) aws.Ternary
}

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

type IsErrorThrottleFunc added in v1.14.0 

type IsErrorThrottleFunc func(error) aws.Ternary

IsErrorThrottleFunc wraps a function with the IsErrorThrottle interface.

func (IsErrorThrottleFunc) IsErrorThrottle added in v1.14.0 

func (fn IsErrorThrottleFunc) IsErrorThrottle(err error) aws.Ternary

IsErrorThrottle returns if the error is a throttle error.

type IsErrorThrottles added in v1.14.0 

type IsErrorThrottles []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.

func (IsErrorThrottles) IsErrorThrottle added in v1.14.0 

func (r IsErrorThrottles) IsErrorThrottle(err error) aws.Ternary

IsErrorThrottle returns if the error is a throttle error 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 added in v0.25.0 

type MaxAttemptsError struct {
	Attempt int
	Err     error
}

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

func (*MaxAttemptsError) Error added in v0.25.0 

func (e *MaxAttemptsError) Error() string

func (*MaxAttemptsError) Unwrap added in v0.25.0 

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 added in v0.30.0 

type MetricsHeader struct{}

MetricsHeader attaches SDK request metric header for retries to the transport

func (MetricsHeader) HandleFinalize added in v0.30.0 

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 added in v0.30.0 

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 attempt retries allowed by the retryer.

type RequestCloner added in v0.21.0 

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 attempt 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) GetAttemptToken added in v1.14.0 

func (s *Standard) GetAttemptToken(context.Context) (func(error) error, error)

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.

func (*Standard) GetInitialToken deprecated 

func (s *Standard) GetInitialToken() func(error) error

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.

func (*Standard) GetRetryToken 

func (s *Standard) GetRetryToken(ctx context.Context, opErr 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 {
	// Maximum number of attempts that should be made.
	MaxAttempts int

	// MaxBackoff duration between retried attempts.
	MaxBackoff time.Duration

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

	// 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.
	Retryables []IsErrorRetryable

	// 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.
	Timeouts []IsErrorTimeout

	// Provides the rate limiting strategy for rate limiting attempt retries
	// across all attempts the retryer is being used with.
	//
	// A RateLimiter operates as a token bucket with a set capacity, where
	// attempt failures events consume tokens. A retry attempt that attempts to
	// consume more tokens than what's available results in operation failure.
	// The default implementation is parameterized as follows:
	//   - a capacity of 500 (DefaultRetryRateTokens)
	//   - a retry caused by a timeout costs 10 tokens (DefaultRetryCost)
	//   - a retry caused by other errors costs 5 tokens (DefaultRetryTimeoutCost)
	//   - an operation that succeeds on the 1st attempt adds 1 token (DefaultNoRetryIncrement)
	//
	// You can disable rate limiting by setting this field to ratelimit.None.
	RateLimiter RateLimiter

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

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

	// The cost to payback to the RateLimiter's token bucket for successful
	// attempts.
	NoRetryIncrement uint
}

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

type ThrottleErrorCode added in v1.14.0 

type ThrottleErrorCode struct {
	Codes map[string]struct{}
}

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

func (ThrottleErrorCode) IsErrorThrottle added in v1.14.0 

func (r ThrottleErrorCode) IsErrorThrottle(err error) aws.Ternary

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.

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

View all Source files

Directories

Path Synopsis
internal
mock

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.