docs(util-retry): add readme for util-retry, add configurable backoff (#4702)

* docs(util-retry): add docs for util retry

* docs(util-retry): add readme for util-retry, add configurable backoff

* fix: typo getRetyErrorInfo to getRetryErrorInfo

---------

Co-authored-by: Trivikram Kamat <[email protected]>

Author: kuhe

packages/middleware-retry/src/retryMiddleware.ts

@@ -53,7 +53,7 @@ export const retryMiddleware =
           output.$metadata.totalRetryDelay = totalRetryDelay;
           return { response, output };
         } catch (e) {
-          const retryErrorInfo = getRetyErrorInto(e);
+          const retryErrorInfo = getRetryErrorInfo(e);
           lastError = asSdkError(e);
           try {
             retryToken = await retryStrategy.refreshRetryTokenForRetry(retryToken, retryErrorInfo);
@@ -85,7 +85,7 @@ const isRetryStrategyV2 = (retryStrategy: RetryStrategy | RetryStrategyV2) =>
   typeof (retryStrategy as RetryStrategyV2).refreshRetryTokenForRetry !== "undefined" &&
   typeof (retryStrategy as RetryStrategyV2).recordSuccess !== "undefined";
 
-const getRetyErrorInto = (error: SdkError): RetryErrorInfo => {
+const getRetryErrorInfo = (error: SdkError): RetryErrorInfo => {
   const errorInfo: RetryErrorInfo = {
     errorType: getRetryErrorType(error),
   };

packages/types/src/retry.ts

@@ -142,7 +142,7 @@ export interface RetryStrategyV2 {
   refreshRetryTokenForRetry(tokenToRenew: RetryToken, errorInfo: RetryErrorInfo): Promise<RetryToken>;
 
   /**
-   * Upon successful completion of the operation, a user calls this function
+   * Upon successful completion of the operation, this function is called
    * to record that the operation was successful.
    */
   recordSuccess(token: RetryToken): void;

packages/util-retry/README.md

@@ -3,10 +3,61 @@
 [![NPM version](https://img.shields.io/npm/v/@aws-sdk/util-retry/latest.svg)](https://www.npmjs.com/package/@aws-sdk/util-retry)
 [![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/util-retry.svg)](https://www.npmjs.com/package/@aws-sdk/util-retry)
 
-> An internal package
-
 This package provides shared utilities for retries.
 
 ## Usage
 
-You probably shouldn't, at least directly.
+### 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](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html).
+
+```js
+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 use the `StandardRetryStrategy` from `@aws-sdk/util-retry`.
+
+```js
+import { S3Client } from "@aws-sdk/client-s3";
+import { StandardRetryStrategy } from "@aws-sdk/util-retry";
+
+const client = new S3Client({
+  // custom max number of attempts.
+  retryStrategy: new StandardRetryStrategy(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`.
+
+```js
+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.
+
+### Further customization
+
+You can implement the `RetryStrategyV2` interface.
+
+https://github.com/aws/aws-sdk-js-v3/blob/main/packages/types/src/retry.ts

packages/util-retry/src/AdaptiveRetryStrategy.ts

@@ -6,17 +6,17 @@ import { StandardRetryStrategy } from "./StandardRetryStrategy";
 import { RateLimiter } from "./types";
 
 /**
- * @internal
- * 
+ * @public
+ *
  * Strategy options to be passed to AdaptiveRetryStrategy
  */
 export interface AdaptiveRetryStrategyOptions {
   rateLimiter?: RateLimiter;
 }
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The AdaptiveRetryStrategy is a retry strategy for executing against a very
  * resource constrained set of resources. Care should be taken when using this
  * retry strategy. By default, it uses a dynamic backoff delay based on load

packages/util-retry/src/ConfiguredRetryStrategy.spec.ts

@@ -0,0 +1,17 @@
+import { ConfiguredRetryStrategy } from "./ConfiguredRetryStrategy";
+
+describe(ConfiguredRetryStrategy.name, () => {
+  it("allows setting a custom backoff function", async () => {
+    const strategy = new ConfiguredRetryStrategy(5, (attempt) => attempt * 1000);
+
+    const token = await strategy.acquireInitialRetryToken("");
+    token.getRetryCount = () => 4;
+
+    const retryToken = await strategy.refreshRetryTokenForRetry(token, {
+      errorType: "TRANSIENT",
+    });
+
+    expect(retryToken.getRetryCount()).toBe(4);
+    expect(retryToken.getRetryDelay()).toBe(4000);
+  });
+});

packages/util-retry/src/ConfiguredRetryStrategy.ts

@@ -0,0 +1,59 @@
+import type {
+  Provider,
+  RetryBackoffStrategy,
+  RetryErrorInfo,
+  RetryStrategyV2,
+  StandardRetryToken,
+} from "@aws-sdk/types";
+
+import { DEFAULT_RETRY_DELAY_BASE } from "./constants";
+import { StandardRetryStrategy } from "./StandardRetryStrategy";
+
+/**
+ * @public
+ *
+ * This extension of the StandardRetryStrategy allows customizing the
+ * backoff computation.
+ */
+export class ConfiguredRetryStrategy extends StandardRetryStrategy implements RetryStrategyV2 {
+  private readonly computeNextBackoffDelay: (attempt: number) => number;
+  /**
+   * @param maxAttempts - the maximum number of retry attempts allowed.
+   *                      e.g., if set to 3, then 4 total requests are possible.
+   * @param computeNextBackoffDelay - a millisecond delay for each retry or a function that takes the retry attempt
+   *                                  and returns the delay.
+   *
+   * @example exponential backoff.
+   * ```js
+   * new Client({
+   *   retryStrategy: new ConfiguredRetryStrategy(3, (attempt) => attempt ** 2)
+   * });
+   * ```
+   * @example constant delay.
+   * ```js
+   * new Client({
+   *   retryStrategy: new ConfiguredRetryStrategy(3, 2000)
+   * });
+   * ```
+   */
+  public constructor(
+    maxAttempts: number | Provider<number>,
+    computeNextBackoffDelay: number | RetryBackoffStrategy["computeNextBackoffDelay"] = DEFAULT_RETRY_DELAY_BASE
+  ) {
+    super(typeof maxAttempts === "function" ? maxAttempts : async () => maxAttempts);
+    if (typeof computeNextBackoffDelay === "number") {
+      this.computeNextBackoffDelay = () => computeNextBackoffDelay;
+    } else {
+      this.computeNextBackoffDelay = computeNextBackoffDelay;
+    }
+  }
+
+  public async refreshRetryTokenForRetry(
+    tokenToRenew: StandardRetryToken,
+    errorInfo: RetryErrorInfo
+  ): Promise<StandardRetryToken> {
+    const token = await super.refreshRetryTokenForRetry(tokenToRenew, errorInfo);
+    token.getRetryDelay = () => this.computeNextBackoffDelay(token.getRetryCount());
+    return token;
+  }
+}

packages/util-retry/src/DefaultRateLimiter.ts

@@ -3,7 +3,7 @@ import { isThrottlingError } from "@aws-sdk/service-error-classification";
 import { RateLimiter } from "./types";
 
 /**
- * @internal
+ * @public
  */
 export interface DefaultRateLimiterOptions {
   beta?: number;
@@ -14,7 +14,7 @@ export interface DefaultRateLimiterOptions {
 }
 
 /**
- * @internal
+ * @public
  */
 export class DefaultRateLimiter implements RateLimiter {
   // User configurable constants

packages/util-retry/src/StandardRetryStrategy.ts

@@ -5,15 +5,18 @@ import { DEFAULT_RETRY_DELAY_BASE, INITIAL_RETRY_TOKENS } from "./constants";
 import { getDefaultRetryToken } from "./defaultRetryToken";
 
 /**
- * @internal
+ * @public
  */
 export class StandardRetryStrategy implements RetryStrategyV2 {
-  private retryToken: StandardRetryToken;
   public readonly mode: string = RETRY_MODES.STANDARD;
+  private retryToken: StandardRetryToken;
+  private readonly maxAttemptsProvider: Provider<number>;
 
-  constructor(private readonly maxAttemptsProvider: Provider<number>) {
+  constructor(maxAttempts: number);
+  constructor(maxAttemptsProvider: Provider<number>);
+  constructor(private readonly maxAttempts: number | Provider<number>) {
     this.retryToken = getDefaultRetryToken(INITIAL_RETRY_TOKENS, DEFAULT_RETRY_DELAY_BASE);
-    this.maxAttemptsProvider = maxAttemptsProvider;
+    this.maxAttemptsProvider = typeof maxAttempts === "function" ? maxAttempts : async () => maxAttempts;
   }
 
   public async acquireInitialRetryToken(retryTokenScope: string): Promise<StandardRetryToken> {

packages/util-retry/src/config.ts

@@ -1,22 +1,22 @@
 /**
- * @internal
+ * @public
  */
 export enum RETRY_MODES {
   STANDARD = "standard",
   ADAPTIVE = "adaptive",
 }
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The default value for how many HTTP requests an SDK should make for a
  * single SDK operation invocation before giving up
  */
 export const DEFAULT_MAX_ATTEMPTS = 3;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The default retry algorithm to use.
  */
-export const DEFAULT_RETRY_MODE = "STANDARD" as RETRY_MODES;
+export const DEFAULT_RETRY_MODE = RETRY_MODES.STANDARD;

packages/util-retry/src/constants.ts

@@ -1,67 +1,67 @@
 /**
- * @internal
- * 
+ * @public
+ *
  * The base number of milliseconds to use in calculating a suitable cool-down
  * time when a retryable error is encountered.
  */
 export const DEFAULT_RETRY_DELAY_BASE = 100;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The maximum amount of time (in milliseconds) that will be used as a delay
  * between retry attempts.
  */
 export const MAXIMUM_RETRY_DELAY = 20 * 1000;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The retry delay base (in milliseconds) to use when a throttling error is
  * encountered.
  */
 export const THROTTLING_RETRY_DELAY_BASE = 500;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * Initial number of retry tokens in Retry Quota
  */
 export const INITIAL_RETRY_TOKENS = 500;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The total amount of retry tokens to be decremented from retry token balance.
  */
 export const RETRY_COST = 5;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The total amount of retry tokens to be decremented from retry token balance
  * when a throttling error is encountered.
  */
 export const TIMEOUT_RETRY_COST = 10;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * The total amount of retry token to be incremented from retry token balance
  * if an SDK operation invocation succeeds without requiring a retry request.
  */
 export const NO_RETRY_INCREMENT = 1;
 
 /**
- * @internal
- * 
+ * @public
+ *
  * Header name for SDK invocation ID
  */
 export const INVOCATION_ID_HEADER = "amz-sdk-invocation-id";
 
 /**
- * @internal
- * 
+ * @public
+ *
  * Header name for request retry information.
  */
 export const REQUEST_HEADER = "amz-sdk-request";

packages/util-retry/src/defaultRetryToken.ts

@@ -11,7 +11,7 @@ import {
 import { getDefaultRetryBackoffStrategy } from "./defaultRetryBackoffStrategy";
 
 /**
- * @internal
+ * @public
  */
 export interface DefaultRetryTokenOptions {
   /**

packages/util-retry/src/index.ts

@@ -1,24 +1,7 @@
-/**
- * @internal
- */
 export * from "./AdaptiveRetryStrategy";
-/**
- * @internal
- */
+export * from "./ConfiguredRetryStrategy";
 export * from "./DefaultRateLimiter";
-/**
- * @internal
- */
 export * from "./StandardRetryStrategy";
-/**
- * @internal
- */
 export * from "./config";
-/**
- * @internal
- */
 export * from "./constants";
-/**
- * @internal
- */
 export * from "./types";