Add builder for Backoff

core/src/main/java/com/linecorp/armeria/client/retry/Backoff.java

@@ -131,6 +131,39 @@
         return BackoffSpec.parse(specification).build();
     }
 
+    /**
+     * Returns a {@link ExponentialBackoffBuilder} that provides methods to configure
+     * backoff delay which is exponentially-increasing.
+     */
+    static ExponentialBackoffBuilder builderForExponential() {
+        return new ExponentialBackoffBuilder();
+    }
+
+    /**
+     * Returns a {@link FixedBackoffBuilder} that provides methods to configure
+     * backoff delay which follows fibonacci sequence.
+     * f(n) = f(n-1) + f(n-2) where f(0) = f(1) = {@code initialDelayMillis}
+     */
+    static FibonacciBackoffBuilder builderForFibonacci() {
+        return new FibonacciBackoffBuilder();
+    }
+
+    /**
+     * Returns a {@link FixedBackoffBuilder} that provides methods to configure
+     * backoff delay which is a fixed value.
+     */
+    static FixedBackoffBuilder builderForFixed() {
+        return new FixedBackoffBuilder();
+    }
+
+    /**
+     * Returns a {@link RandomBackoffBuilder} that provides methods to configure
+     * backoff delay which is a random value.
+     */
+    static RandomBackoffBuilder builderForRandom() {
+        return new RandomBackoffBuilder();
+    }
+
     /**
      * Returns the number of milliseconds to wait for before attempting a retry.
      *

core/src/main/java/com/linecorp/armeria/client/retry/ExponentialBackoffBuilder.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2024 LY Corporation
+ *
+ * LY Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 com.linecorp.armeria.client.retry;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+/**
+ * A builder for creating instances of {@link ExponentialBackoff}.
+ *
+ * <p>This builder allows you to configure an exponential backoff strategy by specifying
+ * the initial delay, the maximum delay, and a multiplier. The exponential backoff
+ * increases the delay between retries exponentially, starting from the initial delay and
+ * multiplying the delay by the specified multiplier after each retry, up to the maximum delay.</p>
+ *
+ * <p>Example usage:</p>
+ *
+ * <pre>
+ * {@code
+ * ExponentialBackoff backoff = new ExponentialBackoffBuilder()
+ *     .initialDelayMillis(100)
+ *     .maxDelayMillis(10000)
+ *     .multiplier(2.0)
+ *     .build();
+ * }
+ * </pre>
+ *
+ * @see ExponentialBackoff
+ */
+@UnstableApi
+public final class ExponentialBackoffBuilder {
+    private long initialDelayMillis;
+    private long maxDelayMillis;
+    private double multiplier = 2.0;
+
+    ExponentialBackoffBuilder() {}
+
+    /**
+     * Builds and returns a new {@link ExponentialBackoff} instance with the configured
+     * initial delay, maximum delay, and multiplier.
+     *
+     * @return a newly created {@link ExponentialBackoff} with the configured delays and multiplier
+     */
+    public Backoff build() {
+        return new ExponentialBackoff(initialDelayMillis, maxDelayMillis, multiplier);
+    }
+
+    /**
+     * Sets the initial delay in milliseconds for the {@link ExponentialBackoff}.
+     *
+     * <p>The initial delay is the starting value for the exponential backoff, determining
+     * the delay before the first retry. Subsequent delays will increase exponentially
+     * based on the multiplier.</p>
+     *
+     * @param initialDelayMillis the initial delay in milliseconds
+     * @return this {@code ExponentialBackoffBuilder} instance for method chaining
+     */
+    public ExponentialBackoffBuilder initialDelayMillis(long initialDelayMillis) {
+        checkArgument(initialDelayMillis >= 0, "initialDelayMillis: %s (expected: >= 0)", initialDelayMillis);
+        this.initialDelayMillis = initialDelayMillis;
+        return this;
+    }
+
+    /**
+     * Sets the maximum delay in milliseconds for the {@link ExponentialBackoff}.
+     *
+     * <p>The maximum delay is the upper limit for the backoff delay. Once the delay reaches
+     * this value, it will not increase further, even if the multiplier would result in a higher value.</p>
+     *
+     * @param maxDelayMillis the maximum delay in milliseconds
+     * @return this {@code ExponentialBackoffBuilder} instance for method chaining
+     */
+    public ExponentialBackoffBuilder maxDelayMillis(long maxDelayMillis) {
+        checkArgument(maxDelayMillis >= 0, "maxDelayMillis: %s (expected: >= 0)", maxDelayMillis);
+        this.maxDelayMillis = maxDelayMillis;
+        return this;
+    }
+
+    /**
+     * Sets the multiplier for the {@link ExponentialBackoff}.
+     *
+     * <p>The multiplier controls how much the delay increases after each retry.
+     * The delay for each retry is determined by multiplying the previous delay by this value,
+     * until the maximum delay is reached.</p>
+     *
+     * @param multiplier the multiplier for the exponential backoff
+     * @return this {@code ExponentialBackoffBuilder} instance for method chaining
+     */
+    public ExponentialBackoffBuilder multiplier(double multiplier) {
+        checkArgument(multiplier > 1.0, "multiplier: %s (expected: > 1.0)", multiplier);
+        this.multiplier = multiplier;
+        return this;
+    }
+}

core/src/main/java/com/linecorp/armeria/client/retry/FibonacciBackoffBuilder.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2024 LY Corporation
+ *
+ * LY Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 com.linecorp.armeria.client.retry;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+/**
+ * A builder for creating instances of {@link FibonacciBackoff}.
+ *
+ * <p>This builder allows you to configure a Fibonacci backoff strategy by specifying
+ * an initial delay and a maximum delay in milliseconds. The Fibonacci backoff strategy
+ * increases the delay between retries according to the Fibonacci sequence, while respecting
+ * the configured maximum delay.</p>
+ *
+ * <p>Example usage:</p>
+ *
+ * <pre>
+ * {@code
+ * FibonacciBackoff backoff = new FibonacciBackoffBuilder()
+ *     .initialDelayMillis(100)
+ *     .maxDelayMillis(10000)
+ *     .build();
+ * }
+ * </pre>
+ *
+ * @see FibonacciBackoff
+ */
+@UnstableApi
+public final class FibonacciBackoffBuilder {
+    private long initialDelayMillis;
+    private long maxDelayMillis;
+
+    FibonacciBackoffBuilder() {}
+
+    /**
+     * Builds and returns a new {@link FibonacciBackoff} instance with the configured
+     * initial and maximum delays.
+     *
+     * @return a newly created {@link FibonacciBackoff} with the configured delays
+     */
+    public Backoff build() {
+        return new FibonacciBackoff(initialDelayMillis, maxDelayMillis);
+    }
+
+    /**
+     * Sets the initial delay in milliseconds for the {@link FibonacciBackoff}.
+     *
+     * <p>The initial delay is the base value from which the Fibonacci sequence will start,
+     * and it determines the delay before the first retry.</p>
+     *
+     * @param initialDelayMillis the initial delay in milliseconds
+     * @return this {@code FibonacciBackoffBuilder} instance for method chaining
+     */
+    public FibonacciBackoffBuilder initialDelayMillis(long initialDelayMillis) {
+        checkArgument(initialDelayMillis >= 0,
+                      "initialDelayMillis: %s (expected: >= 0)", initialDelayMillis);
+
+        this.initialDelayMillis = initialDelayMillis;
+        return this;
+    }
+
+    /**
+     * Sets the maximum delay in milliseconds for the {@link FibonacciBackoff}.
+     *
+     * <p>The maximum delay sets an upper limit to the delays generated by the Fibonacci
+     * sequence. Once the delays reach this value, they will not increase further.</p>
+     *
+     * @param maxDelayMillis the maximum delay in milliseconds
+     * @return this {@code FibonacciBackoffBuilder} instance for method chaining
+     */
+    public FibonacciBackoffBuilder maxDelayMillis(long maxDelayMillis) {
+        checkArgument(maxDelayMillis >= 0,
+                      "maxDelayMillis: %s (expected: >= 0)", maxDelayMillis);
+        this.maxDelayMillis = maxDelayMillis;
+        return this;
+    }
+}

core/src/main/java/com/linecorp/armeria/client/retry/FixedBackoffBuilder.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2024 LY Corporation
+ *
+ * LY Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 com.linecorp.armeria.client.retry;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+/**
+ * A builder for creating instances of {@link FixedBackoff}.
+ *
+ * <p>This builder allows you to configure the delay duration for a fixed backoff strategy.
+ * You can specify the delay in milliseconds and then create a {@link FixedBackoff} instance
+ * with the configured delay.</p>
+ *
+ * <p>Example usage:</p>
+ *
+ * <pre>
+ * {@code
+ * FixedBackoff backoff = new FixedBackoffBuilder()
+ *     .delayMillis(1000)
+ *     .build();
+ * }
+ * </pre>
+ *
+ * @see FixedBackoff
+ */
+@UnstableApi
+public final class FixedBackoffBuilder {
+    private long delayMillis;
+
+    FixedBackoffBuilder() {}
+
+    /**
+     * Builds and returns a new {@link FixedBackoff} instance with the configured delay.
+     *
+     * @return a newly created {@link FixedBackoff} with the configured delay
+     */
+    public Backoff build() {
+        return new FixedBackoff(delayMillis);
+    }
+
+    /**
+     * Sets the delay duration in milliseconds for the {@link FixedBackoff}.
+     *
+     * <p>This value determines the fixed amount of time the backoff will delay
+     * before retrying an operation.</p>
+     *
+     * @param delayMillis the delay in milliseconds
+     * @return this {@code FixedBackoffBuilder} instance for method chaining
+     */
+    public FixedBackoffBuilder delayMillis(long delayMillis) {
+        checkArgument(delayMillis >= 0, "delayMillis: %s (expected: >= 0)", delayMillis);
+        this.delayMillis = delayMillis;
+        return this;
+    }
+}