@aws-sdk/util-retry

What is @aws-sdk/util-retry?

The @aws-sdk/util-retry package is part of the AWS SDK for JavaScript v3. It provides utilities to add retry functionality to the AWS SDK operations. This package is designed to help manage retries in a more efficient and customizable way, allowing developers to handle transient errors by repeating requests without having to implement their own retry logic.

What are @aws-sdk/util-retry's main functionalities?

Configuring retry strategies

This feature allows developers to configure retry strategies, specifying how many times an operation should be retried before giving up. The `StandardRetryStrategy` is a built-in strategy that can be used to automatically handle retries according to the SDK's standard logic.

const { StandardRetryStrategy } = require('@aws-sdk/util-retry');
const retryStrategy = new StandardRetryStrategy(maxAttempts);

Custom retry strategy

Developers can extend the `RetryStrategy` class to implement custom retry logic. This allows for fine-grained control over when and how retries should be performed, based on the specific needs of the application.

const { RetryStrategy } = require('@aws-sdk/util-retry');
class MyRetryStrategy extends RetryStrategy {
  constructor(maxAttempts) {
    super();
    this.maxAttempts = maxAttempts;
  }
  shouldRetry(error) {
    // Custom logic to determine if a retry should be attempted
  }
  delayBeforeNextRetry(retryCount) {
    // Custom logic to determine the delay before the next retry
  }
}

Other packages similar to @aws-sdk/util-retry

retry

The `retry` package provides a simple, yet powerful abstraction for retrying asynchronous operations. Unlike @aws-sdk/util-retry, which is designed specifically for AWS SDK operations, `retry` can be used for any asynchronous operation, making it more versatile but less specialized.

async-retry

Similar to `retry`, `async-retry` is a lightweight library for retrying promises. It offers a simple API and flexible configuration options. While `async-retry` is more focused on promise-based operations, @aws-sdk/util-retry is tailored for AWS SDK operations, providing more specific functionalities for handling AWS service interactions.

p-retry

The `p-retry` package is designed for retrying promises with a specific focus on simplicity and composability. It uses a declarative approach for defining retry conditions and strategies. Compared to @aws-sdk/util-retry, `p-retry` is more generic and can be applied to any promise-based operation, not just AWS SDK calls.

README

@aws-sdk/util-retry

This package provides shared utilities for retries.

Usage

Default

By default, each client already has a default retry strategy. The default retry count is 3, and only retryable errors will be retried.

AWS Documentation: Retry behavior.

import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({}); // default retry strategy included.

MaxAttempts

If you want to change the number of attempts, you can provide maxAttempts configuration during client creation.

import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({ maxAttempts: 4 });

This is recommended because the StandardRetryStrategy includes backoff calculation, deciding whether an error should be retried, and a retry token counter.

MaxAttempts and BackoffComputation

If you want to change the number of attempts and use a custom delay computation, you can use the ConfiguredRetryStrategy from @aws-sdk/util-retry.

import { S3Client } from "@aws-sdk/client-s3";
import { ConfiguredRetryStrategy } from "@aws-sdk/util-retry";

const client = new S3Client({
  retryStrategy: new ConfiguredRetryStrategy(
    4, // max attempts.
    (attempt: number) => 100 + attempt * 1000 // backoff function.
  ),
});

This example sets the backoff at 100ms plus 1s per attempt.

MaxAttempts and RetryStrategy

If you provide both maxAttempts and retryStrategy, the retryStrategy will get precedence as it's more specific.

import { S3Client } from "@aws-sdk/client-s3";
import { ConfiguredRetryStrategy } from "@aws-sdk/util-retry";

const client = new S3Client({
  maxAttempts: 2, // ignored.
  retryStrategy: new ConfiguredRetryStrategy(
    4, // used.
    (attempt: number) => 100 + attempt * 1000 // backoff function.
  ),
});

Further customization

You can implement the RetryStrategyV2 interface.

https://github.com/aws/aws-sdk-js-v3/blob/main/packages/types/src/retry.ts

Changelog

3.374.0 (2023-07-20)

Bug Fixes

• packages: fix migrated package imports (#4990) (d800f78)

Features

• client-codecatalyst: This release adds support for updating and deleting spaces and projects in Amazon CodeCatalyst. It also adds support for creating, getting, and deleting source repositories in CodeCatalyst projects. (05a9f89)
• client-connectcases: This release adds the ability to assign a case to a queue or user. (f47d6f4)
• client-lex-models-v2: This release updates type for Channel field in SessionSpecification and UtteranceSpecification (1f77d0a)
• client-route53resolver: This release adds support for Route 53 On Outposts, a new feature that allows customers to run Route 53 Resolver and Resolver endpoints locally on their Outposts. (8acc64c)
• client-s3: Improve performance of S3 clients by simplifying and optimizing endpoint resolution. (72eb598)
• client-sagemaker-featurestore-runtime: Cross account support for SageMaker Feature Store (b0593ab)
• client-sagemaker: Cross account support for SageMaker Feature Store (e4918c1)
• client-securitylake: Adding support for Tags on Create and Resource Tagging API. (596636d)
• client-transcribe: Added API argument --toxicity-detection to startTranscriptionJob API, which allows users to view toxicity scores of submitted audio. (9e7552a)
• smithy-client: update client defaults provider (830cb06)