gapic-common 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac5c845df865497acbdcb4656a47667dd657083d85ef964f633fc0540ef80493
-  data.tar.gz: 851ab12cf7a9e8d5e5f93c991846f0a4701a5a96047fef0ebb17392a55061984
+  metadata.gz: 6dbc3fc8f2b53d01d228f377851d21d941cedd307a9528e7ba732c5e8d2565e2
+  data.tar.gz: d6ded505cf91783149b49373f2efb2ef105860705a22f2940c27f6b27d83be39
 SHA512:
-  metadata.gz: 3225a82b3d2b7006fa0191c55e46e836724ec07d240d7fc5eb11188ccc5613572a714a012a5e904d85cc70d13bb816cd735faf0c3b458e54552e36f483f07f21
-  data.tar.gz: 7d4e26754019a71ae7bca52e2e195b71db46c755c6eca1cce34504990e31f2055d390119d9ae0bf81d1b217f7f1d3185200557da3c4d04b8aa251a3d87a13b54
+  metadata.gz: e7533c44cae4643cec30b87e96fc61750ca2ba2a3458c711788d51987436b25ca3248f6c8d011cf06a00992eec4458e3403ac0b64850a43d153368cd3a6c0203
+  data.tar.gz: cd51bd91e418f8d5c71c3f6e484b29f4c420121b14baca686309f074928162f97c0259555bd32d28cb6e747a397c99c0e3d5aeb6cd99085d309ed61482af7cfa

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Release History
 
+### 1.4.0 (2026-09-23)
+
+#### Features
+
+* add custom predicate matching to RetryPolicy ([#59](https://github.com/googleapis/ruby-core-libraries/issues/59)) 
+#### Bug Fixes
+
+* require grpc >= 1.83 for post-quantum key exchange ([#73](https://github.com/googleapis/ruby-core-libraries/issues/73)) 
+* only use emit_default for proto messages ([#75](https://github.com/googleapis/ruby-core-libraries/issues/75)) 
+
+### 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/README.md

@@ -15,7 +15,7 @@ convenient and idiomatic API surface to callers.
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 3.0+.
+This library is supported on Ruby 3.2+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
@@ -24,6 +24,35 @@ work, but are unsupported and not recommended. See
 https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby
 support schedule.
 
+## Post-Quantum Key Exchange
+
+Clients built on this library negotiate the hybrid post-quantum key exchange
+group `X25519MLKEM768` — classical X25519 paired with ML-KEM-768 ([NIST FIPS
+203][]) — over TLS 1.3. No application code changes are required, because the
+handshake belongs to the transport layer. The two transports source that
+support differently:
+
+| Transport | Cryptographic provider | Requirement | Enforced by this gem? |
+| --- | --- | --- | --- |
+| gRPC | BoringSSL, vendored inside the `grpc` gem | `grpc >= 1.83` | Yes |
+| REST | Host system OpenSSL, via `Net::HTTP` and Faraday | OpenSSL `>= 3.5` | No |
+
+gRPC clients get post-quantum key exchange automatically: `gapic-common`
+depends on `grpc >= 1.83`, the first release to offer `X25519MLKEM768` in the
+TLS ClientHello by default.
+
+The REST requirement cannot be expressed as a gem dependency. Ruby's `openssl`
+is a default gem bound to whatever `libssl` the host provides, and ML-KEM first
+ships in OpenSSL 3.5. On an older host, REST connections negotiate classical
+X25519 instead — a safe fallback rather than an error, but not post-quantum. To
+check the OpenSSL your Ruby is linked against:
+
+```sh
+ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION'
+```
+
+[NIST FIPS 203]: https://csrc.nist.gov/pubs/fips/203/final
+
 ## Contributing
 
 Contributions to this library are always welcome and highly encouraged.

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,27 @@ 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.
+      # @param retry_predicate [Proc, nil] The predicate to evaluate whether to retry on a given error. Optional.
+      #   If the predicate is specified, it is run first. If it returns nil, the decision on
+      #   whether to retry is made on the basis of retry_codes. Otherwise, the truthiness of
+      #   the return value determines whether to retry.
       #
-      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, retry_predicate: nil
+        raise ArgumentError, "jitter cannot be negative" if jitter&.negative?
+        if retry_predicate && !retry_predicate.respond_to?(:call)
+          raise ArgumentError, "retry_predicate must respond to :call"
+        end
+
         # 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
+        @retry_predicate = retry_predicate
         start!
       end
 
@@ -75,6 +93,24 @@ module Gapic
         @timeout || DEFAULT_TIMEOUT
       end
 
+      # @return [Numeric] Random jitter added to the delay in seconds.
+      def jitter
+        @jitter || DEFAULT_JITTER
+      end
+
+      ##
+      # The predicate to evaluate whether to retry on a given error. Optional.
+      #
+      # When a predicate is specified:
+      # 1. The predicate is executed first on the error.
+      # 2. If it returns nil, the decision on whether to retry is made on the basis of retry_codes.
+      # 3. Otherwise, the truthiness of the return value determines whether to retry.
+      #
+      # @return [Proc, nil]
+      def retry_predicate
+        @retry_predicate
+      end
+
       ##
       # Returns a duplicate in a non-executing state, i.e. with the deadline
       # and current delay reset.
@@ -86,7 +122,9 @@ module Gapic
                         max_delay: @max_delay,
                         multiplier: @multiplier,
                         retry_codes: @retry_codes,
-                        timeout: @timeout
+                        timeout: @timeout,
+                        jitter: @jitter,
+                        retry_predicate: @retry_predicate
       end
 
       ##
@@ -161,6 +199,13 @@ module Gapic
       # @return [Boolean] Whether this error should be retried.
       #
       def retry_error? error
+        # Run predicate first. If it returns nil, decision is made on the basis of retry_codes.
+        # Otherwise return truthiness.
+        if @retry_predicate.respond_to? :call
+          result = @retry_predicate.call error
+          return !!result unless result.nil?
+        end
+
         (defined?(::GRPC) && error.is_a?(::GRPC::BadStatus) && retry_codes.include?(error.code)) ||
           (error.respond_to?(:response_status) &&
             retry_codes.include?(ErrorCodes.grpc_error_for(error.response_status)))
@@ -182,10 +227,12 @@ module Gapic
       #
       def apply_defaults retry_policy
         return unless retry_policy.is_a? Hash
-        @retry_codes   ||= convert_codes retry_policy[:retry_codes]
-        @initial_delay ||= retry_policy[:initial_delay]
-        @multiplier    ||= retry_policy[:multiplier]
-        @max_delay     ||= retry_policy[:max_delay]
+        @retry_codes     ||= convert_codes retry_policy[:retry_codes]
+        @initial_delay   ||= retry_policy[:initial_delay]
+        @multiplier      ||= retry_policy[:multiplier]
+        @max_delay       ||= retry_policy[:max_delay]
+        @jitter          ||= retry_policy[:jitter]
+        @retry_predicate ||= retry_policy[:retry_predicate]
 
         self
       end
@@ -197,30 +244,35 @@ module Gapic
           other.max_delay == max_delay &&
           other.multiplier == multiplier &&
           other.retry_codes == retry_codes &&
-          other.timeout == timeout
+          other.timeout == timeout &&
+          other.jitter == jitter &&
+          other.retry_predicate == retry_predicate
       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, retry_predicate].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.4.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

data/lib/gapic/rest/grpc_transcoder.rb

@@ -160,7 +160,16 @@ module Gapic
           request_body_field = request.send body_template.to_sym if request.respond_to? body_template.to_sym
           if request_body_field
             request_hash_without_uri.delete camel_name_for body_template
-            body = request_body_field.to_json emit_defaults: true
+            # `emit_defaults` is only meaningful for, and only accepted by,
+            # `Google::Protobuf::MessageExts#to_json`. When the body template points at a
+            # scalar, enum or repeated field, `to_json` resolves to the json gem's
+            # `Object#to_json`, which has never accepted the keyword: json 2.x silently
+            # discarded unknown keywords, json 3.x raises ArgumentError.
+            body = if request_body_field.is_a? ::Google::Protobuf::MessageExts
+                     request_body_field.to_json emit_defaults: true
+                   else
+                     request_body_field.to_json
+                   end
           end
 
           query_params = build_query_params request_hash_without_uri

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Google API Authors
@@ -137,16 +137,22 @@ dependencies:
   name: grpc
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.83'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.66'
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.83'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.66'
+        version: 2.a
 email:
 - googleapis-packages@google.com
 executables: []
@@ -213,7 +219,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="