gapic-common 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac5c845df865497acbdcb4656a47667dd657083d85ef964f633fc0540ef80493
-  data.tar.gz: 851ab12cf7a9e8d5e5f93c991846f0a4701a5a96047fef0ebb17392a55061984
+  metadata.gz: e4338a183319704aa9fb613e73d34b4092a94ad56f3136c2d4a0490a3218770f
+  data.tar.gz: 3a0d1456f8c2bc573245e5c46afae6b2c83be393085bf6bebc5b28c06368d3f7
 SHA512:
-  metadata.gz: 3225a82b3d2b7006fa0191c55e46e836724ec07d240d7fc5eb11188ccc5613572a714a012a5e904d85cc70d13bb816cd735faf0c3b458e54552e36f483f07f21
-  data.tar.gz: 7d4e26754019a71ae7bca52e2e195b71db46c755c6eca1cce34504990e31f2055d390119d9ae0bf81d1b217f7f1d3185200557da3c4d04b8aa251a3d87a13b54
+  metadata.gz: 696026e2b9ca26c060c2b65a336f790ec193938a7740d8bdce3008c6bfae40cd80290077b717174554d7e6a1530e470f2523a5859b210c2bf9bd583e7dd72041
+  data.tar.gz: 42979948486f1e55f990bdbcc0ee2a697ffbf3c450b4013a7ae293e0960291533bfc4356fcfb8cfdeca5eae94d97a7ff522e2b5667cd1e9611de93cf39af560e

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 1.3.0 (2026-03-05)
+
+#### Features
+
+* add jitter to retries ([#54](https://github.com/googleapis/ruby-core-libraries/issues/54)) 
+
 ### 1.2.0 (2025-09-04)
 
 #### Features

data/lib/gapic/call_options/retry_policy.rb

@@ -30,8 +30,9 @@ module Gapic
       # @param initial_delay [Numeric] Initial delay in seconds.
       # @param multiplier [Numeric] The delay scaling factor for each subsequent retry attempt.
       # @param max_delay [Numeric] Maximum delay in seconds.
+      # @param jitter [Numeric] Random jitter added to the delay in seconds.
       #
-      def initialize retry_codes: nil, initial_delay: nil, multiplier: nil, max_delay: nil
+      def initialize retry_codes: nil, initial_delay: nil, multiplier: nil, max_delay: nil, jitter: nil
         super
       end
     end

data/lib/gapic/common/retry_policy.rb

@@ -31,6 +31,11 @@ module Gapic
       # @return [Numeric] Default timeout threshold value in seconds.
       DEFAULT_TIMEOUT = 3600 # One hour
 
+      # @private
+      # @return [Numeric] Default random jitter added to delay in seconds.
+      DEFAULT_JITTER = 1.0
+      private_constant :DEFAULT_JITTER
+
       ##
       # Create new Gapic::Common::RetryPolicy instance.
       #
@@ -39,14 +44,18 @@ module Gapic
       # @param multiplier [Numeric] The delay scaling factor for each subsequent retry attempt.
       # @param retry_codes [Array<String|Integer>] List of retry codes.
       # @param timeout [Numeric] Timeout threshold value in seconds.
+      # @param jitter [Numeric] Random jitter added to the delay in seconds.
       #
-      def initialize initial_delay: nil, max_delay: nil, multiplier: nil, retry_codes: nil, timeout: nil
+      def initialize initial_delay: nil, max_delay: nil, multiplier: nil, retry_codes: nil, timeout: nil, jitter: nil
+        raise ArgumentError, "jitter cannot be negative" if jitter&.negative?
+
         # Instance values are set as `nil` to determine whether values are overriden from default.
         @initial_delay = initial_delay
         @max_delay = max_delay
         @multiplier = multiplier
         @retry_codes = convert_codes retry_codes
         @timeout = timeout
+        @jitter = jitter
         start!
       end
 
@@ -75,6 +84,11 @@ module Gapic
         @timeout || DEFAULT_TIMEOUT
       end
 
+      # @return [Numeric] Random jitter added to the delay in seconds.
+      def jitter
+        @jitter || DEFAULT_JITTER
+      end
+
       ##
       # Returns a duplicate in a non-executing state, i.e. with the deadline
       # and current delay reset.
@@ -86,7 +100,8 @@ module Gapic
                         max_delay: @max_delay,
                         multiplier: @multiplier,
                         retry_codes: @retry_codes,
-                        timeout: @timeout
+                        timeout: @timeout,
+                        jitter: @jitter
       end
 
       ##
@@ -186,6 +201,7 @@ module Gapic
         @initial_delay ||= retry_policy[:initial_delay]
         @multiplier    ||= retry_policy[:multiplier]
         @max_delay     ||= retry_policy[:max_delay]
+        @jitter        ||= retry_policy[:jitter]
 
         self
       end
@@ -197,30 +213,34 @@ module Gapic
           other.max_delay == max_delay &&
           other.multiplier == multiplier &&
           other.retry_codes == retry_codes &&
-          other.timeout == timeout
+          other.timeout == timeout &&
+          other.jitter == jitter
       end
       alias == eql?
 
       # @private Hash code
       def hash
-        [initial_delay, max_delay, multiplier, retry_codes, timeout].hash
+        [initial_delay, max_delay, multiplier, retry_codes, timeout, jitter].hash
       end
 
       private
 
       # @private
+      # Perform the currently calculated delay, adding a jitter.
+      #
       # @return [Numeric] The performed delay.
       def delay!
+        delay_to_perform = [delay + Kernel.rand(0.0..jitter), max_delay].min
         if @mock_time
-          @mock_time += delay
-          @mock_delay_callback&.call delay
+          @mock_time += delay_to_perform
+          @mock_delay_callback&.call delay_to_perform
         else
-          Kernel.sleep delay
+          Kernel.sleep delay_to_perform
         end
       end
 
       # @private
-      # @return [Numeric] The new delay in seconds.
+      # @return [Numeric] The new delay (sans jitter) in seconds.
       def increment_delay!
         @delay = [delay * multiplier, max_delay].min
       end

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "1.2.0".freeze
+    VERSION = "1.3.0".freeze
   end
 end

data/lib/gapic/operation/retry_policy.rb

@@ -38,13 +38,15 @@ module Gapic
       # @param multiplier [Numeric] The delay scaling factor for each subsequent retry attempt.
       # @param max_delay [Numeric] Maximum delay in seconds.
       # @param timeout [Numeric] Timeout threshold value in seconds.
+      # @param jitter [Numeric] Random jitter added to the delay in seconds.
       #
-      def initialize initial_delay: nil, multiplier: nil, max_delay: nil, timeout: nil
+      def initialize initial_delay: nil, multiplier: nil, max_delay: nil, timeout: nil, jitter: nil
         super(
           initial_delay: initial_delay || DEFAULT_INITIAL_DELAY,
           max_delay: max_delay || DEFAULT_MAX_DELAY,
           multiplier: multiplier || DEFAULT_MULTIPLIER,
-          timeout: timeout || DEFAULT_TIMEOUT
+          timeout: timeout || DEFAULT_TIMEOUT,
+          jitter: jitter
         )
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Google API Authors