Add default backoff strategies

core/pom.xml

@@ -47,6 +47,7 @@
         <module>endpoints-spi</module>
         <module>imds</module>
         <module>retries-api</module>
+        <module>retries</module>
     </modules>
 
     <dependencyManagement>

core/retries-api/pom.xml

@@ -20,7 +20,7 @@
     <parent>
         <artifactId>core</artifactId>
         <groupId>software.amazon.awssdk</groupId>
-        <version>2.20.4-SNAPSHOT</version>
+        <version>2.20.7-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

core/retries/pom.xml

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License").
+  ~ You may not use this file except in compliance with the License.
+  ~ A copy of the License is located at
+  ~
+  ~  http://aws.amazon.com/apache2.0
+  ~
+  ~ or in the "license" file accompanying this file. This file is distributed
+  ~ on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+  ~ express or implied. See the License for the specific language governing
+  ~ permissions and limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>core</artifactId>
+        <groupId>software.amazon.awssdk</groupId>
+        <version>2.20.7-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>retries</artifactId>
+    <name>AWS Java SDK :: Retries</name>
+    <build>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-jar-plugin</artifactId>
+          <configuration>
+            <archive>
+              <manifestEntries>
+                <Automatic-Module-Name>software.amazon.awssdk.retries</Automatic-Module-Name>
+              </manifestEntries>
+            </archive>
+          </configuration>
+        </plugin>
+      </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>retries-api</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>annotations</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

core/retries/src/main/java/software/amazon/awssdk/retries/backoff/BackoffStrategiesConstants.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.retries.backoff;
+
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkInternalApi;
+
+/**
+ * Constants and utility functions shared by the BackoffStrategy implementations.
+ */
+@SdkInternalApi
+class BackoffStrategiesConstants {
+    static final Duration BASE_DELAY_CEILING = Duration.ofMillis(Integer.MAX_VALUE); // Around ~24.8 days
+    static final Duration MAX_BACKOFF_CEILING = Duration.ofMillis(Integer.MAX_VALUE); // Around ~24.8 days
+    /**
+     * Max permitted retry times. To prevent exponentialDelay from overflow, there must be 2 ^ retriesAttempted <= 2 ^ 31 - 1,
+     * which means retriesAttempted <= 30, so that is the ceil for retriesAttempted.
+     */
+    static final int RETRIES_ATTEMPTED_CEILING = (int) Math.floor(Math.log(Integer.MAX_VALUE) / Math.log(2));
+
+    private BackoffStrategiesConstants() {
+    }
+
+    /**
+     * Returns the computed exponential delay in milliseconds given the retries attempted, the base delay and the max backoff
+     * time.
+     *
+     * <p>Specifically it returns {@code min(maxDelay, baseDelay * (1 << (attempt - 2)))}. To prevent overflowing the attempts
+     * get capped to 30.
+     */
+    static int calculateExponentialDelay(int retriesAttempted, Duration baseDelay, Duration maxBackoffTime) {
+        int cappedRetries = Math.min(retriesAttempted, BackoffStrategiesConstants.RETRIES_ATTEMPTED_CEILING);
+        return (int) Math.min(baseDelay.multipliedBy(1L << (cappedRetries - 2)).toMillis(), maxBackoffTime.toMillis());
+    }
+}

core/retries/src/main/java/software/amazon/awssdk/retries/backoff/DefaultBackoffStrategies.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.retries.backoff;
+
+import java.time.Duration;
+import java.util.concurrent.ThreadLocalRandom;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.retries.api.BackoffStrategy;
+
+/**
+ * Determines how long to wait before each execution attempt.
+ */
+@SdkPublicApi
+public final class DefaultBackoffStrategies {
+
+    private DefaultBackoffStrategies() {
+    }
+
+    /**
+     * Do not back off: retry immediately.
+     */
+    public static BackoffStrategy retryImmediately() {
+        return new Immediately();
+    }
+
+    /**
+     * Wait for a random period of time between 0ms and the provided delay.
+     */
+    public static BackoffStrategy fixedDelay(Duration delay) {
+        return new FixedDelayWithJitter(ThreadLocalRandom::current, delay);
+    }
+
+    /**
+     * Wait for a period of time equal to the provided delay.
+     */
+    public static BackoffStrategy fixedDelayWithoutJitter(Duration delay) {
+        return new FixedDelayWithoutJitter(delay);
+    }
+
+    /**
+     * Wait for a random period of time between 0ms and an exponentially increasing amount of time between each subsequent attempt
+     * of the same call.
+     *
+     * <p>Specifically, the first attempt waits 0ms, and each subsequent attempt waits between
+     * 0ms and {@code min(maxDelay, baseDelay * (1 << (attempt - 2)))}.
+     */
+    public static BackoffStrategy exponentialDelay(Duration baseDelay, Duration maxDelay) {
+        return new ExponentialDelayWithJitter(ThreadLocalRandom::current, baseDelay, maxDelay);
+    }
+
+    /**
+     * Wait for an exponentially increasing amount of time between each subsequent attempt of the same call.
+     *
+     * <p>Specifically, the first attempt waits 0ms, and each subsequent attempt waits for
+     * {@code min(maxDelay, baseDelay * (1 << (attempt - 2)))}.
+     */
+    public static BackoffStrategy exponentialDelayWithoutJitter(Duration baseDelay, Duration maxDelay) {
+        return new ExponentialDelayWithoutJitter(baseDelay, maxDelay);
+    }
+
+}

core/retries/src/main/java/software/amazon/awssdk/retries/backoff/ExponentialDelayWithJitter.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.retries.backoff;
+
+import static software.amazon.awssdk.retries.backoff.BackoffStrategiesConstants.calculateExponentialDelay;
+
+import java.time.Duration;
+import java.util.Random;
+import java.util.function.Supplier;
+import software.amazon.awssdk.annotations.SdkInternalApi;
+import software.amazon.awssdk.retries.api.BackoffStrategy;
+import software.amazon.awssdk.utils.NumericUtils;
+import software.amazon.awssdk.utils.ToString;
+import software.amazon.awssdk.utils.Validate;
+
+/**
+ * Strategy that waits for a random period of time between 0ms and an exponentially increasing amount of time between each
+ * subsequent attempt of the same call.
+ *
+ * <p>Specifically, the first attempt waits 0ms, and each subsequent attempt waits between
+ * 0ms and {@code min(maxDelay, baseDelay * (1 << (attempt - 2)))}.
+ */
+@SdkInternalApi
+final class ExponentialDelayWithJitter implements BackoffStrategy {
+    private final Supplier<Random> randomSupplier;
+    private final Duration baseDelay;
+    private final Duration maxDelay;
+
+    ExponentialDelayWithJitter(Supplier<Random> randomSupplier, Duration baseDelay, Duration maxDelay) {
+        this.randomSupplier = Validate.paramNotNull(randomSupplier, "random");
+        this.baseDelay = NumericUtils.min(Validate.isPositive(baseDelay, "baseDelay"),
+                                          BackoffStrategiesConstants.BASE_DELAY_CEILING);
+        this.maxDelay = NumericUtils.min(Validate.isPositive(maxDelay, "maxDelay"),
+                                         BackoffStrategiesConstants.MAX_BACKOFF_CEILING);
+    }
+
+    @Override
+    public Duration computeDelay(int attempt) {
+        Validate.isPositive(attempt, "attempt");
+        if (attempt == 1) {
+            return Duration.ZERO;
+        }
+        int delay = calculateExponentialDelay(attempt, baseDelay, maxDelay);
+        int randInt = randomSupplier.get().nextInt(delay);
+        return Duration.ofMillis(randInt);
+    }
+
+    @Override
+    public String toString() {
+        return ToString.builder("ExponentialDelayWithJitter")
+                       .add("baseDelay", baseDelay)
+                       .add("maxDelay", maxDelay)
+                       .build();
+    }
+}

core/retries/src/main/java/software/amazon/awssdk/retries/backoff/ExponentialDelayWithoutJitter.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.retries.backoff;
+
+import static software.amazon.awssdk.retries.backoff.BackoffStrategiesConstants.calculateExponentialDelay;
+
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkInternalApi;
+import software.amazon.awssdk.retries.api.BackoffStrategy;
+import software.amazon.awssdk.utils.NumericUtils;
+import software.amazon.awssdk.utils.ToString;
+import software.amazon.awssdk.utils.Validate;
+
+/**
+ * Strategy that waits for an exponentially increasing amount of time between each subsequent attempt of the same call.
+ *
+ * <p>Specifically, the first attempt waits 0ms, and each subsequent attempt waits for
+ * {@code min(maxDelay, baseDelay * (1 << (attempt - 2)))}.
+ */
+@SdkInternalApi
+final class ExponentialDelayWithoutJitter implements BackoffStrategy {
+    private final Duration baseDelay;
+    private final Duration maxDelay;
+
+    ExponentialDelayWithoutJitter(Duration baseDelay, Duration maxDelay) {
+        this.baseDelay = NumericUtils.min(Validate.isPositive(baseDelay, "baseDelay"),
+                                          BackoffStrategiesConstants.BASE_DELAY_CEILING);
+        this.maxDelay = NumericUtils.min(Validate.isPositive(maxDelay, "maxDelay"),
+                                         BackoffStrategiesConstants.MAX_BACKOFF_CEILING);
+    }
+
+    @Override
+    public Duration computeDelay(int attempt) {
+        Validate.isPositive(attempt, "attempt");
+        if (attempt == 1) {
+            return Duration.ZERO;
+        }
+        int delay = calculateExponentialDelay(attempt, baseDelay, maxDelay);
+        return Duration.ofMillis(delay);
+    }
+
+    @Override
+    public String toString() {
+        return ToString.builder("ExponentialDelayWithoutJitter")
+                       .add("baseDelay", baseDelay)
+                       .add("maxDelay", maxDelay)
+                       .build();
+    }
+}

core/retries/src/main/java/software/amazon/awssdk/retries/backoff/FixedDelayWithJitter.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.retries.backoff;
+
+import java.time.Duration;
+import java.util.Random;
+import java.util.function.Supplier;
+import software.amazon.awssdk.annotations.SdkInternalApi;
+import software.amazon.awssdk.retries.api.BackoffStrategy;
+import software.amazon.awssdk.utils.NumericUtils;
+import software.amazon.awssdk.utils.ToString;
+import software.amazon.awssdk.utils.Validate;
+
+/**
+ * Strategy that waits for a random period of time between 0ms and the provided delay.
+ */
+@SdkInternalApi
+final class FixedDelayWithJitter implements BackoffStrategy {
+    private final Supplier<Random> randomSupplier;
+    private final Duration delay;
+
+    FixedDelayWithJitter(Supplier<Random> randomSupplier, Duration delay) {
+        this.randomSupplier = Validate.paramNotNull(randomSupplier, "random");
+        this.delay = NumericUtils.min(Validate.isPositive(delay, "delay"), BackoffStrategiesConstants.BASE_DELAY_CEILING);
+    }
+
+    @Override
+    public Duration computeDelay(int attempt) {
+        Validate.isPositive(attempt, "attempt");
+        return Duration.ofMillis(randomSupplier.get().nextInt((int) delay.toMillis()));
+    }
+
+    @Override
+    public String toString() {
+        return ToString.builder("FixedDelayWithJitter")
+                       .add("delay", delay)
+                       .build();
+    }
+}