Support backoff for long-polling

For operations that are long-polling, support backoffs in the Standard
retry strategy even there is insufficient retry quota.

Author: dagnir

core/retries-spi/src/main/java/software/amazon/awssdk/retries/api/RefreshRetryTokenRequest.java

@@ -43,6 +43,12 @@ public interface RefreshRetryTokenRequest extends ToCopyableBuilder<RefreshRetry
      */
     Optional<Duration> suggestedDelay();
 
+    /**
+     * Whether the operation that is being retried is a long polling operation. Returns {@code false} by default.
+     */
+    default boolean isLongPolling() {
+        return false;
+    }
     /**
      * The cause of the last attempt failure.
      */
@@ -66,6 +72,13 @@ interface Builder extends CopyableBuilder<Builder, RefreshRetryTokenRequest> {
          */
         Builder suggestedDelay(Duration duration);
 
+        /**
+         * Configures whether this refresh request is for a long polling operation. The default implementation is a no-op.
+         */
+        default Builder isLongPolling(boolean isLongPolling) {
+            return this;
+        }
+
         /**
          * Configures the latest caught exception.
          */

core/retries-spi/src/main/java/software/amazon/awssdk/retries/api/TokenAcquisitionFailedException.java

@@ -15,6 +15,8 @@
 
 package software.amazon.awssdk.retries.api;
 
+import java.time.Duration;
+import java.util.Optional;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
@@ -23,13 +25,15 @@
 @SdkPublicApi
 public final class TokenAcquisitionFailedException extends RuntimeException {
     private final transient RetryToken token;
+    private final transient Duration delay;
 
     /**
      * Exception construction accepting message with no root cause.
      */
     public TokenAcquisitionFailedException(String msg) {
         super(msg);
         token = null;
+        delay = null;
     }
 
     /**
@@ -38,6 +42,7 @@ public TokenAcquisitionFailedException(String msg) {
     public TokenAcquisitionFailedException(String msg, Throwable cause) {
         super(msg, cause);
         token = null;
+        delay = null;
     }
 
     /**
@@ -46,6 +51,23 @@ public TokenAcquisitionFailedException(String msg, Throwable cause) {
     public TokenAcquisitionFailedException(String msg, RetryToken token, Throwable cause) {
         super(msg, cause);
         this.token = token;
+        this.delay = null;
+    }
+
+    /**
+     * Exception constructor accepting message, retry token, a root cause, and delay.
+     */
+    public TokenAcquisitionFailedException(String msg, RetryToken token, Throwable cause, Duration delay) {
+        super(msg, cause);
+        this.token = token;
+        this.delay = delay;
+    }
+
+    /**
+     * The amount of time to wait before returning to the caller.
+     */
+    public Optional<Duration> delay() {
+        return Optional.ofNullable(delay);
     }
 
     /**

core/retries-spi/src/main/java/software/amazon/awssdk/retries/api/internal/RefreshRetryTokenRequestImpl.java

@@ -29,12 +29,14 @@
 public final class RefreshRetryTokenRequestImpl implements RefreshRetryTokenRequest {
     private final RetryToken token;
     private final Duration suggestedDelay;
+    private final boolean isLongPolling;
     private final Throwable failure;
 
     private RefreshRetryTokenRequestImpl(Builder builder) {
         this.token = Validate.paramNotNull(builder.token, "token");
         this.suggestedDelay = Validate.paramNotNull(builder.suggestedDelay, "suggestedDelay");
         Validate.isNotNegative(this.suggestedDelay, "suggestedDelay");
+        this.isLongPolling = builder.isLongPolling;
         this.failure = Validate.paramNotNull(builder.failure, "failure");
     }
 
@@ -48,6 +50,11 @@ public Optional<Duration> suggestedDelay() {
         return Optional.of(suggestedDelay);
     }
 
+    @Override
+    public boolean isLongPolling() {
+        return isLongPolling;
+    }
+
     @Override
     public Throwable failure() {
         return failure;
@@ -68,11 +75,13 @@ public static Builder builder() {
     public static final class Builder implements RefreshRetryTokenRequest.Builder {
         private RetryToken token;
         private Duration suggestedDelay = Duration.ZERO;
+        private boolean isLongPolling;
         private Throwable failure;
 
         Builder(RefreshRetryTokenRequestImpl refreshRetryTokenRequest) {
             this.token = refreshRetryTokenRequest.token;
             this.suggestedDelay = refreshRetryTokenRequest.suggestedDelay;
+            this.isLongPolling = refreshRetryTokenRequest.isLongPolling;
             this.failure = refreshRetryTokenRequest.failure;
         }
 
@@ -91,6 +100,12 @@ public Builder suggestedDelay(Duration duration) {
             return this;
         }
 
+        @Override
+        public RefreshRetryTokenRequest.Builder isLongPolling(boolean isLongPolling) {
+            this.isLongPolling = isLongPolling;
+            return this;
+        }
+
         @Override
         public Builder failure(Throwable throwable) {
             this.failure = throwable;

core/retries/src/main/java/software/amazon/awssdk/retries/StandardRetryStrategy.java

@@ -76,6 +76,7 @@ static Builder builder(boolean retries2026Enabled) {
                                                 : exceptionCost;
         return DefaultStandardRetryStrategy
             .builder()
+            .retries2026Enabled(retries2026Enabled)
             .maxAttempts(DefaultRetryStrategy.Standard.MAX_ATTEMPTS)
             .tokenBucketStore(TokenBucketStore
                                   .builder()

core/retries/src/main/java/software/amazon/awssdk/retries/internal/BaseRetryStrategy.java

@@ -166,7 +166,7 @@ protected Duration computeInitialBackoff(AcquireInitialTokenRequest request) {
 
     /**
      * Computes the backoff before a retry using the configured backoff strategy. Extending classes can override this method to
-     * compute different a different depending on their logic.
+     * compute different a different duration depending on their logic.
      */
     protected Duration computeBackoff(RefreshRetryTokenRequest request, DefaultRetryToken token) {
         Duration backoff;
@@ -179,6 +179,17 @@ protected Duration computeBackoff(RefreshRetryTokenRequest request, DefaultRetry
         return maxOf(suggested, backoff);
     }
 
+    /**
+     * Computes the backoff before exiting the retry loop using the configured backoff strategy. Extending classes can override
+     * this method to compute different a different duration depending on their logic. The default implementation returns
+     * 0 delay.
+     *
+     * @param request The refresh request that failed to acquire sufficient capacity.
+     */
+    protected Duration computeAcquireFailureBackoff(RefreshRetryTokenRequest request) {
+        return Duration.ZERO;
+    }
+
     /**
      * Called inside {@link #recordSuccess} to allow extending classes to update their internal state after a successful request.
      */
@@ -299,7 +310,8 @@ private void throwOnAcquisitionFailure(RefreshRetryTokenRequest request, Acquire
                      .build();
             String message = acquisitionFailedMessage(acquireResponse);
             log.debug(() -> message, failure);
-            throw new TokenAcquisitionFailedException(message, refreshedToken, failure);
+            Duration delay = computeAcquireFailureBackoff(request);
+            throw new TokenAcquisitionFailedException(message, refreshedToken, failure, delay);
         }
     }
 

core/retries/src/main/java/software/amazon/awssdk/retries/internal/DefaultStandardRetryStrategy.java

@@ -15,20 +15,24 @@
 
 package software.amazon.awssdk.retries.internal;
 
+import java.time.Duration;
 import java.util.function.Predicate;
 import software.amazon.awssdk.annotations.SdkInternalApi;
 import software.amazon.awssdk.retries.StandardRetryStrategy;
 import software.amazon.awssdk.retries.api.BackoffStrategy;
+import software.amazon.awssdk.retries.api.RefreshRetryTokenRequest;
 import software.amazon.awssdk.retries.internal.circuitbreaker.TokenBucketStore;
 import software.amazon.awssdk.utils.Logger;
 
 @SdkInternalApi
 public final class DefaultStandardRetryStrategy
     extends BaseRetryStrategy implements StandardRetryStrategy {
     private static final Logger LOG = Logger.loggerFor(DefaultStandardRetryStrategy.class);
+    private final boolean retries2026Enabled;
 
     DefaultStandardRetryStrategy(Builder builder) {
         super(LOG, builder);
+        this.retries2026Enabled = builder.retries2026Enabled;
     }
 
     @Override
@@ -40,7 +44,20 @@ public static Builder builder() {
         return new Builder();
     }
 
+    @Override
+    protected Duration computeAcquireFailureBackoff(RefreshRetryTokenRequest request) {
+        if (!retries2026Enabled || !request.isLongPolling()) {
+            return super.computeAcquireFailureBackoff(request);
+        }
+
+        DefaultRetryToken attemptIncremented = asDefaultRetryToken(request.token()).toBuilder()
+                                                                                   .increaseAttempt()
+                                                                                   .build();
+        return computeBackoff(request, attemptIncremented);
+    }
+
     public static class Builder extends BaseRetryStrategy.Builder implements StandardRetryStrategy.Builder {
+        private boolean retries2026Enabled;
 
         Builder() {
         }
@@ -106,6 +123,14 @@ public Builder useClientDefaults(boolean useClientDefaults) {
             return this;
         }
 
+        /**
+         * Whether retries 2.1 behavior is enabled.
+         */
+        public Builder retries2026Enabled(boolean retries2026Enabled) {
+            this.retries2026Enabled = retries2026Enabled;
+            return this;
+        }
+
         @Override
         public StandardRetryStrategy build() {
             return new DefaultStandardRetryStrategy(this);