retry

README

AWS API Retry Package

This package provides utilities for retrying AWS API calls with exponential backoff. It is designed to be used with the AWS SDK v2 for Go.

Features

• Exponential Backoff: Automatically retries operations with exponential backoff
• Error Categorization: Categorizes errors as retryable or non-retryable
• Context Support: Respects context cancellation and deadlines
• Logging: Provides detailed logging of retry attempts

Usage

Basic Usage

import (
    "context"
    "github.com/johnlam90/aws-multi-eni-controller/pkg/aws/retry"
    "github.com/go-logr/logr"
)

func ExampleFunction(ctx context.Context, logger logr.Logger) error {
    operation := "describe resource"
    
    err := retry.WithExponentialBackoff(
        ctx,
        logger,
        operation,
        func() (bool, error) {
            // Your AWS API call here
            result, err := awsClient.SomeOperation(ctx, input)
            if err != nil {
                return false, err
            }
            return true, nil
        },
        retry.DefaultRetryableErrors,
        retry.DefaultBackoff(),
    )
    
    return err
}

Custom Error Categorization

func CustomRetryableErrors(err error) bool {
    if err == nil {
        return false
    }
    
    errMsg := err.Error()
    return strings.Contains(errMsg, "RequestLimitExceeded") ||
        strings.Contains(errMsg, "Throttling") ||
        strings.Contains(errMsg, "ConnectionReset")
}

func ExampleWithCustomErrorCategorization(ctx context.Context, logger logr.Logger) error {
    operation := "custom operation"
    
    err := retry.WithExponentialBackoff(
        ctx,
        logger,
        operation,
        func() (bool, error) {
            // Your AWS API call here
            return true, nil
        },
        CustomRetryableErrors,
        retry.DefaultBackoff(),
    )
    
    return err
}

Custom Backoff

func ExampleWithCustomBackoff(ctx context.Context, logger logr.Logger) error {
    operation := "long-running operation"
    
    customBackoff := wait.Backoff{
        Steps:    10,
        Duration: 2 * time.Second,
        Factor:   1.5,
        Jitter:   0.2,
    }
    
    err := retry.WithExponentialBackoff(
        ctx,
        logger,
        operation,
        func() (bool, error) {
            // Your AWS API call here
            return true, nil
        },
        retry.DefaultRetryableErrors,
        customBackoff,
    )
    
    return err
}

Helper Functions

• WithContext: Wraps a RetryableFunc with context cancellation
• WithLogging: Wraps a RetryableFunc with logging
• DefaultBackoff: Returns the default backoff configuration
• DefaultRetryableErrors: Checks if an error is a retryable AWS error

Documentation

Overview

Package retry provides utilities for retrying AWS API calls with exponential backoff.

Index

• func DefaultBackoff() wait.Backoff
• func DefaultRetryableErrors(err error) bool
• func WithCategorizedRetry(ctx context.Context, logger logr.Logger, operation string, fn RetryableFunc) error
• func WithExponentialBackoff(ctx context.Context, logger logr.Logger, operation string, fn RetryableFunc, ...) error
• type CircuitBreaker
  • func NewCircuitBreaker(config *CircuitBreakerConfig, logger logr.Logger) *CircuitBreaker
  • func (cb *CircuitBreaker) Execute(ctx context.Context, operation string, fn func() error) error
  • func (cb *CircuitBreaker) GetState() CircuitBreakerState
  • func (cb *CircuitBreaker) GetStats() map[string]interface{}
  • func (cb *CircuitBreaker) IsOperationAllowed() bool
  • func (cb *CircuitBreaker) Reset()
• type CircuitBreakerConfig
  • func DefaultCircuitBreakerConfig() *CircuitBreakerConfig
• type CircuitBreakerState
• type ErrorCategorizer
• type ErrorCategory
  • func CategorizeError(err error) ErrorCategory
• type LegacyErrorCategorizer
• type RetryableFunc
  • func WithContext(ctx context.Context, fn RetryableFunc) RetryableFunc
  • func WithLogging(logger logr.Logger, operation string, fn RetryableFunc) RetryableFunc
• type Strategy
  • func GetRetryStrategy(category ErrorCategory) Strategy

Functions

func DefaultBackoff

func DefaultBackoff() wait.Backoff

DefaultBackoff returns the default backoff configuration

func DefaultRetryableErrors

func DefaultRetryableErrors(err error) bool

DefaultRetryableErrors checks if an error is a retryable AWS error (legacy function)

func WithCategorizedRetry

func WithCategorizedRetry(
	ctx context.Context,
	logger logr.Logger,
	operation string,
	fn RetryableFunc,
) error

WithCategorizedRetry retries a function with category-specific backoff strategies

func WithExponentialBackoff

func WithExponentialBackoff(
	ctx context.Context,
	logger logr.Logger,
	operation string,
	fn RetryableFunc,
	isRetryable LegacyErrorCategorizer,
	backoff wait.Backoff,
) error

WithExponentialBackoff retries a function with exponential backoff (legacy function)

Types

type CircuitBreaker

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

CircuitBreaker implements the circuit breaker pattern for AWS operations

func NewCircuitBreaker

func NewCircuitBreaker(config *CircuitBreakerConfig, logger logr.Logger) *CircuitBreaker

NewCircuitBreaker creates a new circuit breaker

func (*CircuitBreaker) Execute

func (cb *CircuitBreaker) Execute(ctx context.Context, operation string, fn func() error) error

Execute executes a function with circuit breaker protection

func (*CircuitBreaker) GetState

func (cb *CircuitBreaker) GetState() CircuitBreakerState

GetState returns the current state of the circuit breaker

func (*CircuitBreaker) GetStats

func (cb *CircuitBreaker) GetStats() map[string]interface{}

GetStats returns statistics about the circuit breaker

func (*CircuitBreaker) IsOperationAllowed

func (cb *CircuitBreaker) IsOperationAllowed() bool

IsOperationAllowed checks if an operation would be allowed without executing it

func (*CircuitBreaker) Reset

func (cb *CircuitBreaker) Reset()

Reset resets the circuit breaker to closed state

type CircuitBreakerConfig

type CircuitBreakerConfig struct {
	// FailureThreshold is the number of consecutive failures before opening the circuit
	FailureThreshold int
	// SuccessThreshold is the number of consecutive successes needed to close the circuit from half-open
	SuccessThreshold int
	// Timeout is how long to wait before transitioning from open to half-open
	Timeout time.Duration
	// MaxConcurrentRequests is the maximum number of requests allowed in half-open state
	MaxConcurrentRequests int
}

CircuitBreakerConfig holds configuration for the circuit breaker

func DefaultCircuitBreakerConfig

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns a default circuit breaker configuration

type CircuitBreakerState

type CircuitBreakerState int

CircuitBreakerState represents the state of the circuit breaker

const (
	// CircuitBreakerClosed - normal operation, requests are allowed
	CircuitBreakerClosed CircuitBreakerState = iota
	// CircuitBreakerOpen - circuit is open, requests are rejected
	CircuitBreakerOpen
	// CircuitBreakerHalfOpen - testing if the service has recovered
	CircuitBreakerHalfOpen
)

type ErrorCategorizer

type ErrorCategorizer func(error) ErrorCategory

ErrorCategorizer categorizes errors into different categories

type ErrorCategory

type ErrorCategory int

ErrorCategory represents different categories of errors

const (
	// ErrorCategoryNonRetryable - errors that should not be retried
	ErrorCategoryNonRetryable ErrorCategory = iota
	// ErrorCategoryThrottling - rate limiting errors (long backoff)
	ErrorCategoryThrottling
	// ErrorCategoryTransient - temporary errors (medium backoff)
	ErrorCategoryTransient
	// ErrorCategoryNetwork - network-related errors (short backoff)
	ErrorCategoryNetwork
	// ErrorCategoryResource - resource-related errors (medium backoff)
	ErrorCategoryResource
)

func CategorizeError

func CategorizeError(err error) ErrorCategory

CategorizeError categorizes an AWS error into appropriate retry category

type LegacyErrorCategorizer

type LegacyErrorCategorizer func(error) bool

LegacyErrorCategorizer categorizes errors as retryable or not (for backward compatibility)

type RetryableFunc

type RetryableFunc func() (bool, error)

RetryableFunc is a function that can be retried

func WithContext

func WithContext(ctx context.Context, fn RetryableFunc) RetryableFunc

WithContext wraps a RetryableFunc with context cancellation

func WithLogging

func WithLogging(logger logr.Logger, operation string, fn RetryableFunc) RetryableFunc

WithLogging wraps a RetryableFunc with logging

type Strategy

type Strategy struct {
	Category    ErrorCategory
	Backoff     wait.Backoff
	MaxAttempts int
}

Strategy defines retry behavior for different error categories

func GetRetryStrategy

func GetRetryStrategy(category ErrorCategory) Strategy

GetRetryStrategy returns the appropriate retry strategy for an error category