feat: support request hedging

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

@@ -1,7 +1,7 @@
 /*
- * Copyright 2017 LINE Corporation
+ * Copyright 2025 LY Corporation
  *
- * LINE Corporation licenses this file to you under the Apache License,
+ * 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:
  *
@@ -187,7 +187,7 @@ static RandomBackoffBuilder builderForRandom() {
     }
 
     /**
-     * Returns the number of milliseconds to wait for before attempting a retry.
+     * Returns the number of milliseconds to wait for before attempting a retry. This method is idempotent.
      *
      * @param numAttemptsSoFar the number of attempts made by a client so far, including the first attempt and
      *                         its following retries.

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

@@ -1,7 +1,7 @@
 /*
- * Copyright 2020 LINE Corporation
+ * Copyright 2025 LY Corporation
  *
- * LINE Corporation licenses this file to you under the Apache License,
+ * 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:
  *
@@ -77,6 +77,7 @@ static <T extends Response> RetryConfigBuilder<T> builder0(
 
     private final int maxTotalAttempts;
     private final long responseTimeoutMillisForEachAttempt;
+    private final long hedgingDelayMillis;
     private final int maxContentLength;
 
     @Nullable
@@ -90,7 +91,16 @@ static <T extends Response> RetryConfigBuilder<T> builder0(
 
     RetryConfig(RetryRule retryRule, int maxTotalAttempts, long responseTimeoutMillisForEachAttempt) {
         this(requireNonNull(retryRule, "retryRule"), null,
-                maxTotalAttempts, responseTimeoutMillisForEachAttempt, 0);
+             maxTotalAttempts, responseTimeoutMillisForEachAttempt,
+             0, -1);
+        checkArguments(maxTotalAttempts, responseTimeoutMillisForEachAttempt);
+    }
+
+    RetryConfig(RetryRule retryRule, int maxTotalAttempts, long responseTimeoutMillisForEachAttempt,
+                long hedgingDelayMillis) {
+        this(requireNonNull(retryRule, "retryRule"), null,
+             maxTotalAttempts, responseTimeoutMillisForEachAttempt,
+             0, hedgingDelayMillis);
         checkArguments(maxTotalAttempts, responseTimeoutMillisForEachAttempt);
     }
 
@@ -100,21 +110,36 @@ static <T extends Response> RetryConfigBuilder<T> builder0(
             int maxTotalAttempts,
             long responseTimeoutMillisForEachAttempt) {
         this(null, requireNonNull(retryRuleWithContent, "retryRuleWithContent"),
-                maxTotalAttempts, responseTimeoutMillisForEachAttempt, maxContentLength);
+             maxTotalAttempts, responseTimeoutMillisForEachAttempt,
+             maxContentLength, -1);
+    }
+
+    RetryConfig(
+            RetryRuleWithContent<T> retryRuleWithContent,
+            int maxContentLength,
+            int maxTotalAttempts,
+            long responseTimeoutMillisForEachAttempt,
+            long hedgingDelayMillis) {
+        this(null, requireNonNull(retryRuleWithContent, "retryRuleWithContent"),
+             maxTotalAttempts, responseTimeoutMillisForEachAttempt,
+             maxContentLength, hedgingDelayMillis);
     }
 
     private RetryConfig(
             @Nullable RetryRule retryRule,
             @Nullable RetryRuleWithContent<T> retryRuleWithContent,
             int maxTotalAttempts,
             long responseTimeoutMillisForEachAttempt,
-            int maxContentLength) {
+            int maxContentLength,
+            long hedgingDelayMillis
+    ) {
         checkArguments(maxTotalAttempts, responseTimeoutMillisForEachAttempt);
         this.retryRule = retryRule;
         this.retryRuleWithContent = retryRuleWithContent;
         this.maxTotalAttempts = maxTotalAttempts;
         this.responseTimeoutMillisForEachAttempt = responseTimeoutMillisForEachAttempt;
         this.maxContentLength = maxContentLength;
+        this.hedgingDelayMillis = hedgingDelayMillis;
         if (retryRuleWithContent == null) {
             fromRetryRuleWithContent = null;
         } else {
@@ -145,9 +170,15 @@ public RetryConfigBuilder<T> toBuilder() {
             assert retryRule != null;
             builder = builder0(retryRule);
         }
-        return builder
+        builder
                 .maxTotalAttempts(maxTotalAttempts)
                 .responseTimeoutMillisForEachAttempt(responseTimeoutMillisForEachAttempt);
+
+        if (hedgingDelayMillis >= 0) {
+            builder.hedgingDelayMillis(hedgingDelayMillis);
+        }
+
+        return builder;
     }
 
     /**
@@ -166,6 +197,13 @@ public long responseTimeoutMillisForEachAttempt() {
         return responseTimeoutMillisForEachAttempt;
     }
 
+    /**
+     * todo(szymon): [doc].
+     */
+    public long hedgingDelayMillis() {
+        return hedgingDelayMillis;
+    }
+
     /**
      * Returns the {@link RetryRule} which was specified with {@link RetryConfig#builder(RetryRule)}.
      */

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

@@ -1,7 +1,7 @@
 /*
- * Copyright 2020 LINE Corporation
+ * Copyright 2025 LY Corporation
  *
- * LINE Corporation licenses this file to you under the Apache License,
+ * 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:
  *
@@ -36,6 +36,7 @@
 public final class RetryConfigBuilder<T extends Response> {
     private int maxTotalAttempts = Flags.defaultMaxTotalAttempts();
     private long responseTimeoutMillisForEachAttempt = Flags.defaultResponseTimeoutMillis();
+    private long hedgingDelayMillis = -1;
     private int maxContentLength;
 
     @Nullable
@@ -84,6 +85,33 @@
         return this;
     }
 
+    /**
+     * todo(szymon): [doc].
+     */
+    public RetryConfigBuilder<T> hedgingDelay(Duration hedgingDelay) {
+        final long millis =
+                requireNonNull(hedgingDelay, "hedgingDelay")
+                        .toMillis();
+        checkArgument(
+                millis >= 0,
+                "responseTimeoutForEachAttempt.toMillis(): %s (expected: >= 0)",
+                millis);
+        hedgingDelayMillis = millis;
+        return this;
+    }
+
+    /**
+     * todo(szymon): [doc].
+     */
+    public RetryConfigBuilder<T> hedgingDelayMillis(long hedgingDelayMillis) {
+        checkArgument(
+                hedgingDelayMillis >= 0,
+                "hedgingDelayMillis: %s (expected: >= 0)",
+                hedgingDelayMillis);
+        this.hedgingDelayMillis = hedgingDelayMillis;
+        return this;
+    }
+
     /**
      * Sets the specified {@code responseTimeoutMillisForEachAttempt}.
      */
@@ -116,14 +144,22 @@
      */
     public RetryConfig<T> build() {
         if (retryRule != null) {
-            return new RetryConfig<>(retryRule, maxTotalAttempts, responseTimeoutMillisForEachAttempt);
+            if (hedgingDelayMillis >= 0) {
+                return new RetryConfig<>(retryRule, maxTotalAttempts, responseTimeoutMillisForEachAttempt,
+                                         hedgingDelayMillis);
+            } else {
+                return new RetryConfig<>(retryRule, maxTotalAttempts, responseTimeoutMillisForEachAttempt);
+            }
         }
         assert retryRuleWithContent != null;
-        return new RetryConfig<>(
-                retryRuleWithContent,
-                maxContentLength,
-                maxTotalAttempts,
-                responseTimeoutMillisForEachAttempt);
+
+        if (hedgingDelayMillis >= 0) {
+            return new RetryConfig<>(retryRuleWithContent, maxContentLength, maxTotalAttempts,
+                                     responseTimeoutMillisForEachAttempt, hedgingDelayMillis);
+        } else {
+            return new RetryConfig<>(retryRuleWithContent, maxContentLength, maxTotalAttempts,
+                                     responseTimeoutMillisForEachAttempt);
+        }
     }
 
     @Override
@@ -139,6 +175,7 @@
                 .add("retryRuleWithContent", retryRuleWithContent)
                 .add("maxTotalAttempts", maxTotalAttempts)
                 .add("responseTimeoutMillisForEachAttempt", responseTimeoutMillisForEachAttempt)
+                .add("hedgingDelayMillis", hedgingDelayMillis)
                 .add("maxContentLength", maxContentLength);
     }
 }