chore(util-retry): refine conditions for longpoll backoff (#1966)

kuhe · web-flow · commit b877fc26d9f0 · 2026-04-23T11:23:06.000-04:00
diff --git a/.changeset/sixty-singers-tease.md b/.changeset/sixty-singers-tease.md
@@ -0,0 +1,5 @@
+---
+"@smithy/util-retry": patch
+---
+
+refine conditions for long poll backoff in v2026 retry behavior
diff --git a/packages/util-retry/src/StandardRetryStrategy.spec.ts b/packages/util-retry/src/StandardRetryStrategy.spec.ts
@@ -1,11 +1,22 @@
 import type { RetryErrorInfo } from "@smithy/types";
-import { afterEach, describe, expect, test as it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test as it, vi } from "vitest";
 
 import { RETRY_MODES } from "./config";
+import { MAXIMUM_RETRY_DELAY } from "./constants";
+import { DefaultRetryBackoffStrategy } from "./DefaultRetryBackoffStrategy";
 import { DefaultRetryToken } from "./DefaultRetryToken";
 import { Retry } from "./retries-2026-config";
 import { StandardRetryStrategy } from "./StandardRetryStrategy";
 
+class DeterministicRetryBackoffStrategy extends DefaultRetryBackoffStrategy {
+  public computeNextBackoffDelay(i: number): number {
+    const b = 1; // maximum instead of Math.random()
+    const r = 2;
+    const t_i = b * Math.min(this.x * r ** i, MAXIMUM_RETRY_DELAY);
+    return Math.floor(t_i);
+  }
+}
+
 vi.mock("./DefaultRetryToken");
 
 describe(StandardRetryStrategy.name, () => {
@@ -139,4 +150,186 @@ describe(StandardRetryStrategy.name, () => {
       }
     });
   });
+
+  describe("retryCode", () => {
+    it("returns code 1 (non-retryable) with highest priority over other reasons", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 5,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(1);
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      // non-retryable + attempts exhausted: should get code 1 (non-retryable wins)
+      const result = retryStrategy["retryCode"](token, { errorType: "CLIENT_ERROR" } as RetryErrorInfo, 1);
+      expect(result).toBe(1);
+    });
+
+    it("returns code 2 (attempts exhausted) when retryable but no attempts left", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 2,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      const result = retryStrategy["retryCode"](token, errorInfo, maxAttempts);
+      expect(result).toBe(2);
+    });
+
+    it("returns code 3 (no capacity) when retryable with attempts left but no tokens", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 0,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      retryStrategy["capacity"] = 0;
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      const result = retryStrategy["retryCode"](token, errorInfo, maxAttempts);
+      expect(result).toBe(3);
+    });
+
+    it("returns code 0 (OK to retry) when all conditions are met", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 0,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      const result = retryStrategy["retryCode"](token, errorInfo, maxAttempts);
+      expect(result).toBe(0);
+    });
+  });
+
+  describe("long-poll token behavior", () => {
+    it("throws with $backoff when long-poll token has no capacity (code 3)", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 0,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+            isLongPoll: () => true,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      retryStrategy["capacity"] = 0;
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      try {
+        await retryStrategy.refreshRetryTokenForRetry(token, errorInfo);
+        fail("expected error");
+      } catch (error: any) {
+        expect(error.message).toBe("No retry token available");
+        // $backoff is 0 when Retry.v2026 is false, non-zero when true
+        expect(error.$backoff).toBe(0);
+      }
+    });
+
+    it("throws with $backoff=0 when long-poll token fails for non-capacity reason (code 1)", async () => {
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount: () => 0,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+            isLongPoll: () => true,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      try {
+        await retryStrategy.refreshRetryTokenForRetry(token, { errorType: "CLIENT_ERROR" } as RetryErrorInfo);
+        fail("expected error");
+      } catch (error: any) {
+        expect(error.message).toBe("No retry token available");
+        expect(error.$backoff).toBe(0);
+      }
+    });
+
+    it("retries long-poll token even when retryCode is non-zero, if capacity exists", async () => {
+      const getRetryCount = vi.fn().mockReturnValue(0);
+      vi.mocked(DefaultRetryToken).mockImplementation(
+        () =>
+          ({
+            getRetryCount,
+            getRetryCost: () => 0,
+            getRetryDelay: () => 0,
+            isLongPoll: () => true,
+          }) as any
+      );
+      const retryStrategy = new StandardRetryStrategy(maxAttempts);
+      const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+      const refreshed = await retryStrategy.refreshRetryTokenForRetry(token, errorInfo);
+      expect(refreshed).toBeDefined();
+    });
+
+    describe("with Retry.v2026 enabled", () => {
+      let originalV2026: boolean;
+
+      beforeEach(() => {
+        originalV2026 = Retry.v2026;
+        Retry.v2026 = true;
+      });
+
+      afterEach(() => {
+        Retry.v2026 = originalV2026;
+      });
+
+      it("throws with non-zero $backoff for code 3", async () => {
+        vi.mocked(DefaultRetryToken).mockImplementation(
+          () =>
+            ({
+              getRetryCount: () => 0,
+              getRetryCost: () => 0,
+              getRetryDelay: () => 0,
+              isLongPoll: () => true,
+            }) as any
+        );
+        const retryStrategy = new StandardRetryStrategy({
+          maxAttempts,
+          backoff: new DeterministicRetryBackoffStrategy(),
+        });
+        retryStrategy["capacity"] = 0;
+        const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+        await expect(retryStrategy.refreshRetryTokenForRetry(token, errorInfo)).rejects.toMatchObject({
+          message: "No retry token available",
+          $backoff: 50, // b=1 * min(50 * 2^0, 20000) = 50
+        });
+      });
+
+      it("throws with $backoff=0 for non-capacity code", async () => {
+        vi.mocked(DefaultRetryToken).mockImplementation(
+          () =>
+            ({
+              getRetryCount: () => 0,
+              getRetryCost: () => 0,
+              getRetryDelay: () => 0,
+              isLongPoll: () => true,
+            }) as any
+        );
+        const retryStrategy = new StandardRetryStrategy(maxAttempts);
+        const token = await retryStrategy.acquireInitialRetryToken(retryTokenScope);
+        await expect(
+          retryStrategy.refreshRetryTokenForRetry(token, { errorType: "CLIENT_ERROR" } as RetryErrorInfo)
+        ).rejects.toMatchObject({
+          message: "No retry token available",
+          $backoff: 0,
+        });
+      });
+    });
+  });
 });
diff --git a/packages/util-retry/src/StandardRetryStrategy.ts b/packages/util-retry/src/StandardRetryStrategy.ts
@@ -31,6 +31,25 @@ export type StandardRetryStrategyOptions = {
   backoff?: StandardRetryBackoffStrategy;
 };
 
+/**
+ * Reason for refusing to retry.
+ * @internal
+ */
+const refusal = {
+  /**
+   * Error is not retryable via classification.
+   */
+  incompatible: 1,
+  /**
+   * attempt count exhausted.
+   */
+  attempts: 2,
+  /**
+   * capacity exhausted.
+   */
+  capacity: 3,
+} as const;
+
 /**
  * @public
  */
@@ -70,9 +89,11 @@ export class StandardRetryStrategy implements RetryStrategyV2 {
   ): Promise<StandardRetryToken> {
     const maxAttempts = await this.getMaxAttempts();
 
-    const shouldRetry = this.shouldRetry(token, errorInfo, maxAttempts);
+    const retryCode = this.retryCode(token, errorInfo, maxAttempts);
+    const shouldRetry = retryCode === 0;
+    const isLongPoll = token.isLongPoll?.();
 
-    if (shouldRetry || token.isLongPoll?.()) {
+    if (shouldRetry || isLongPoll) {
       const errorType = errorInfo.errorType;
       this.retryBackoffStrategy.setDelayBase(errorType === "THROTTLING" ? Retry.throttlingDelay() : this.baseDelay);
 
@@ -86,8 +107,15 @@ export class StandardRetryStrategy implements RetryStrategyV2 {
         );
       }
 
-      if (!shouldRetry /* implies long poll */) {
-        throw Object.assign(new Error("No retry token available"), { $backoff: Retry.v2026 ? retryDelay : 0 });
+      if (!shouldRetry) {
+        /**
+         * We only apply additional backoff if `isLongPoll` and the retryCode=3 indicates
+         * that capacity is exhausted. Running out of attempts or having a
+         * non-retryable error does *not* apply backoff.
+         */
+        throw Object.assign(new Error("No retry token available"), {
+          $backoff: Retry.v2026 && retryCode === refusal.capacity && isLongPoll ? retryDelay : 0,
+        });
       } else {
         const capacityCost = this.getCapacityCost(errorType);
         this.capacity -= capacityCost;
@@ -116,6 +144,14 @@ export class StandardRetryStrategy implements RetryStrategyV2 {
     return this.capacity;
   }
 
+  /**
+   * There is an existing integration which accesses this field.
+   * @deprecated
+   */
+  public async maxAttempts(): Promise<number> {
+    return this.maxAttemptsProvider();
+  }
+
   private async getMaxAttempts() {
     try {
       return await this.maxAttemptsProvider();
@@ -125,14 +161,26 @@ export class StandardRetryStrategy implements RetryStrategyV2 {
     }
   }
 
-  private shouldRetry(tokenToRenew: StandardRetryToken, errorInfo: RetryErrorInfo, maxAttempts: number): boolean {
+  /**
+   * 0 - OK to retry.
+   * 1 - error is not classified as retryable.
+   * 2 - attempt count exhausted.
+   * 3 - no capacity left (retry tokens exhausted).
+   *
+   * @returns 0 or the number of the highest priority (lowest integer) reason why retry is not possible.
+   */
+  private retryCode(
+    tokenToRenew: StandardRetryToken,
+    errorInfo: RetryErrorInfo,
+    maxAttempts: number
+  ): 0 | (typeof refusal)[keyof typeof refusal] {
     const attempts = tokenToRenew.getRetryCount() + 1;
 
-    return (
-      /* has attempt remaining */ attempts < maxAttempts &&
-      /* has capacity */ this.capacity >= this.getCapacityCost(errorInfo.errorType) &&
-      /* and is retryable classification */ this.isRetryableError(errorInfo.errorType)
-    );
+    const retryableStatus = this.isRetryableError(errorInfo.errorType) ? 0 : refusal.incompatible;
+    const attemptStatus = attempts < maxAttempts ? 0 : refusal.attempts;
+    const capacityStatus = this.capacity >= this.getCapacityCost(errorInfo.errorType) ? 0 : refusal.capacity;
+
+    return retryableStatus || attemptStatus || capacityStatus;
   }
 
   private getCapacityCost(errorType: RetryErrorType) {
@@ -142,12 +190,4 @@ export class StandardRetryStrategy implements RetryStrategyV2 {
   private isRetryableError(errorType: RetryErrorType): boolean {
     return errorType === "THROTTLING" || errorType === "TRANSIENT";
   }
-
-  /**
-   * There is an existing integration which accesses this field.
-   * @deprecated
-   */
-  public async maxAttempts(): Promise<number> {
-    return this.maxAttemptsProvider();
-  }
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@smithy/util-retry": patch
 +---
++
 +refine conditions for long poll backoff in v2026 retry behavior