Add jitter to RetryBackof

Author: jderusse

Retry/ExponentialBackOff.php

@@ -17,7 +17,7 @@
 /**
  * A retry backOff with a constant or exponential retry delay.
  *
- * For example, if $delayMilliseconds=10000 & $multiplier=1 (default),
+ * For example, if $delayMilliseconds=10000 & $multiplier=1,
  * each retry will wait exactly 10 seconds.
  *
  * But if $delayMilliseconds=10000 & $multiplier=2:
@@ -33,13 +33,15 @@ final class ExponentialBackOff implements RetryBackOffInterface
     private $delayMilliseconds;
     private $multiplier;
     private $maxDelayMilliseconds;
+    private $jitter;
 
     /**
      * @param int   $delayMilliseconds    Amount of time to delay (or the initial value when multiplier is used)
      * @param float $multiplier           Multiplier to apply to the delay each time a retry occurs
      * @param int   $maxDelayMilliseconds Maximum delay to allow (0 means no maximum)
+     * @param float $jitter               Probability of randomness int delay (0 = none, 1 = 100% random)
      */
-    public function __construct(int $delayMilliseconds = 1000, float $multiplier = 2.0, int $maxDelayMilliseconds = 0)
+    public function __construct(int $delayMilliseconds = 1000, float $multiplier = 2.0, int $maxDelayMilliseconds = 0, float $jitter = 0.1)
     {
         if ($delayMilliseconds < 0) {
             throw new InvalidArgumentException(sprintf('Delay must be greater than or equal to zero: "%s" given.', $delayMilliseconds));
@@ -55,11 +57,20 @@ public function __construct(int $delayMilliseconds = 1000, float $multiplier = 2
             throw new InvalidArgumentException(sprintf('Max delay must be greater than or equal to zero: "%s" given.', $maxDelayMilliseconds));
         }
         $this->maxDelayMilliseconds = $maxDelayMilliseconds;
+
+        if ($jitter < 0 || $jitter > 1) {
+            throw new InvalidArgumentException(sprintf('Jitter must be between 0 and 1: "%s" given.', $jitter));
+        }
+        $this->jitter = $jitter;
     }
 
     public function getDelay(int $retryCount, string $requestMethod, string $requestUrl, array $requestOptions, int $responseStatusCode, array $responseHeaders, ?string $responseContent, ?TransportExceptionInterface $exception): int
     {
         $delay = $this->delayMilliseconds * $this->multiplier ** $retryCount;
+        if ($this->jitter > 0) {
+            $randomness = $delay * $this->jitter;
+            $delay = $delay + random_int(-$randomness, +$randomness);
+        }
 
         if ($delay > $this->maxDelayMilliseconds && 0 !== $this->maxDelayMilliseconds) {
             return $this->maxDelayMilliseconds;

Tests/Retry/ExponentialBackOffTest.php

@@ -21,7 +21,7 @@ class ExponentialBackOffTest extends TestCase
      */
     public function testGetDelay(int $delay, int $multiplier, int $maxDelay, int $previousRetries, int $expectedDelay)
     {
-        $backOff = new ExponentialBackOff($delay, $multiplier, $maxDelay);
+        $backOff = new ExponentialBackOff($delay, $multiplier, $maxDelay, 0);
 
         self::assertSame($expectedDelay, $backOff->getDelay($previousRetries, 'GET', 'http://example.com/', [], 200, [], null, null));
     }
@@ -50,4 +50,22 @@ public function provideDelay(): iterable
         yield [0, 2, 10000, 0, 0];
         yield [0, 2, 10000, 1, 0];
     }
+
+    public function testJitter()
+    {
+        $backOff = new ExponentialBackOff(1000, 1, 0, 1);
+        $belowHalf = 0;
+        $aboveHalf = 0;
+        for ($i = 0; $i < 20; ++$i) {
+            $delay = $backOff->getDelay(0, 'GET', 'http://example.com/', [], 200, [], null, null);
+            if ($delay < 500) {
+                ++$belowHalf;
+            } elseif ($delay > 1500) {
+                ++$aboveHalf;
+            }
+        }
+
+        $this->assertGreaterThanOrEqual(1, $belowHalf);
+        $this->assertGreaterThanOrEqual(1, $aboveHalf);
+    }
 }