gapic-common 0.22.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6143272a78f1ebc1b6510a51e3c9c4f649b4095bf0ff97d9148cdaa50a7d508
-  data.tar.gz: ac0b0d305c54b0db5a12efa4fd829076f807e1e33e8dcf81e329f78e6dfc73e7
+  metadata.gz: 28ba6b92736665b67d4b1618bf09b98a4951c9977cd85ed25b190e03216b1ff2
+  data.tar.gz: ece960000b24d5c1f36c508b23e70d5f7edcdf94fb257fd1182f0e9892047108
 SHA512:
-  metadata.gz: 7b5d9797b9a635235ab8804a1435c02f9e96214fc0b0d5f8c660a0f9d89d3d67f0fae9300ec489a38800a08c00e8297360b9e680bc3c3e72f42f0083e511981c
-  data.tar.gz: 313c2bea43584fe99d48a38bacb816c56625e4cf1b704565e6b69beed3e9a509fe176a2f81c8ccebc684f1d8a083774a531c72524fba77fe9958f0dd66a8ca26
+  metadata.gz: c41746a88f4395985296dd5ec97259ff861401186af7648b263199ee1817f686453525d64fb2f733d6479a160518e88103b5a7f7397cd9cfead7134aec5782a7
+  data.tar.gz: 8fa6f167f8b4a48186d97a8f2907ee082c3c2d8c3b8f3437d0d6a7e33c8d80c3acb17acc0a496fafbf6e918e032b7476ff7280602c5bbe4a0914715359a7c49d

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Release History
 
+### 0.25.0 (2025-01-22)
+
+#### Features
+
+* Implement a polling harness ([#20](https://github.com/googleapis/ruby-core-libraries/issues/20)) 
+
+### 0.24.0 (2024-12-05)
+
+#### Features
+
+* Log requests and responses ([#1112](https://github.com/googleapis/gapic-generator-ruby/issues/1112)) 
+#### Bug Fixes
+
+* Hardened deadline determination against Time.now hacking ([#942](https://github.com/googleapis/gapic-generator-ruby/issues/942)) 
+
+### 0.23.0 (2024-10-15)
+
+#### Features
+
+* Disable universe domain check if credentials include an explicit request to do so ([#1119](https://github.com/googleapis/gapic-generator-ruby/issues/1119)) 
+
 ### 0.22.0 (2024-07-17)
 
 #### Features

data/README.md

@@ -15,14 +15,14 @@ convenient and idiomatic API surface to callers.
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 2.6+.
+This library is supported on Ruby 3.0+.
 
 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
-security maintenance, and not end of life. Currently, this means Ruby 2.6 and
-later. Older versions of Ruby _may_ still work, but are unsupported and not
-recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
-about the Ruby support schedule.
+security maintenance, and not end of life. Older versions of Ruby _may_ still
+work, but are unsupported and not recommended. See
+https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby
+support schedule.
 
 ## Contributing
 

data/lib/gapic/call_options/error_codes.rb

@@ -12,63 +12,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-module Gapic
-  class CallOptions
-    ##
-    # @private
-    # The gRPC error codes and their HTTP mapping
-    #
-    module ErrorCodes
-      # @private
-      # See https://grpc.github.io/grpc/core/md_doc_statuscodes.html for a
-      # list of error codes.
-      error_code_mapping = [
-        "OK",
-        "CANCELLED",
-        "UNKNOWN",
-        "INVALID_ARGUMENT",
-        "DEADLINE_EXCEEDED",
-        "NOT_FOUND",
-        "ALREADY_EXISTS",
-        "PERMISSION_DENIED",
-        "RESOURCE_EXHAUSTED",
-        "FAILED_PRECONDITION",
-        "ABORTED",
-        "OUT_OF_RANGE",
-        "UNIMPLEMENTED",
-        "INTERNAL",
-        "UNAVAILABLE",
-        "DATA_LOSS",
-        "UNAUTHENTICATED"
-      ].freeze
-
-      # @private
-      ERROR_STRING_MAPPING = error_code_mapping.each_with_index.to_h.freeze
-
-      # @private
-      HTTP_GRPC_CODE_MAP = {
-        400 => 3, # InvalidArgumentError
-        401 => 16, # UnauthenticatedError
-        403 => 7, # PermissionDeniedError
-        404 => 5, # NotFoundError
-        409 => 6, # AlreadyExistsError
-        412 => 9, # FailedPreconditionError
-        429 => 8, # ResourceExhaustedError
-        499 => 1, # CanceledError
-        500 => 13, # InternalError
-        501 => 12, # UnimplementedError
-        503 => 14, # UnavailableError
-        504 => 4 # DeadlineExceededError
-      }.freeze
-
-      # @private
-      # Converts http error codes into corresponding gRPC ones
-      def self.grpc_error_for http_error_code
-        return 2 unless http_error_code
-
-        # The http status codes mapped to their error classes.
-        HTTP_GRPC_CODE_MAP[http_error_code] || 2 # UnknownError
-      end
-    end
-  end
-end
+# File moved.
+require "gapic/common/error_codes"

data/lib/gapic/call_options/retry_policy.rb

@@ -12,126 +12,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "gapic/call_options/error_codes"
+require "gapic/common/retry_policy"
 
 module Gapic
   class CallOptions
     ##
-    # The policy for retrying failed RPC calls using an incremental backoff. A new object instance should be used for
-    # every RpcCall invocation.
+    # The policy for retrying failed RPC calls using an incremental backoff. A new object instance
+    # should be used for every RpcCall invocation.
     #
-    # Only errors orginating from GRPC will be retried.
+    # Only errors originating from GRPC will be retried.
     #
-    class RetryPolicy
+    class RetryPolicy < Gapic::Common::RetryPolicy
       ##
       # Create new API Call RetryPolicy.
       #
-      # @param initial_delay [Numeric] client-side timeout
-      # @param multiplier [Numeric] client-side timeout
-      # @param max_delay [Numeric] client-side timeout
+      # @param retry_codes [Array<String|Numeric>] List of retry codes.
+      # @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.
       #
       def initialize retry_codes: nil, initial_delay: nil, multiplier: nil, max_delay: nil
-        @retry_codes   = convert_codes retry_codes
-        @initial_delay = initial_delay
-        @multiplier    = multiplier
-        @max_delay     = max_delay
-        @delay         = nil
-      end
-
-      def retry_codes
-        @retry_codes || []
-      end
-
-      def initial_delay
-        @initial_delay || 1
-      end
-
-      def multiplier
-        @multiplier || 1.3
-      end
-
-      def max_delay
-        @max_delay || 15
-      end
-
-      ##
-      # The current delay value.
-      def delay
-        @delay || initial_delay
-      end
-
-      def call error
-        return false unless retry? error
-
-        delay!
-        increment_delay!
-
-        true
-      end
-
-      ##
-      # @private
-      # Apply default values to the policy object. This does not replace user-provided values, it only overrides empty
-      # values.
-      #
-      # @param retry_policy [Hash] The policy for error retry. keys must match the arguments for
-      #   {RpcCall::RetryPolicy.new}.
-      #
-      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]
-
-        self
-      end
-
-      # @private Equality test
-      def eql? other
-        other.is_a?(RetryPolicy) &&
-          other.retry_codes == retry_codes &&
-          other.initial_delay == initial_delay &&
-          other.multiplier == multiplier &&
-          other.max_delay == max_delay
-      end
-      alias == eql?
-
-      # @private Hash code
-      def hash
-        [retry_codes, initial_delay, multiplier, max_delay].hash
-      end
-
-      private
-
-      def retry? error
-        (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)))
-      end
-
-      def delay!
-        # Call Kernel.sleep so we can stub it.
-        Kernel.sleep delay
-      end
-
-      def convert_codes input_codes
-        return nil if input_codes.nil?
-        Array(input_codes).map do |obj|
-          case obj
-          when String
-            ErrorCodes::ERROR_STRING_MAPPING[obj]
-          when Integer
-            obj
-          end
-        end.compact
-      end
-
-      ##
-      # Calculate and set the next delay value.
-      def increment_delay!
-        @delay = [delay * multiplier, max_delay].min
+        super
       end
     end
   end

data/lib/gapic/call_options.rb

@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "gapic/call_options/error_codes"
 require "gapic/call_options/retry_policy"
+require "gapic/common/error_codes"
 
 module Gapic
   ##

data/lib/gapic/common/error_codes.rb

@@ -0,0 +1,74 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+module Gapic
+  module Common
+    ##
+    # @private
+    # The gRPC error codes and their HTTP mapping
+    #
+    module ErrorCodes
+      # @private
+      # See https://grpc.github.io/grpc/core/md_doc_statuscodes.html for a
+      # list of error codes.
+      error_code_mapping = [
+        "OK",
+        "CANCELLED",
+        "UNKNOWN",
+        "INVALID_ARGUMENT",
+        "DEADLINE_EXCEEDED",
+        "NOT_FOUND",
+        "ALREADY_EXISTS",
+        "PERMISSION_DENIED",
+        "RESOURCE_EXHAUSTED",
+        "FAILED_PRECONDITION",
+        "ABORTED",
+        "OUT_OF_RANGE",
+        "UNIMPLEMENTED",
+        "INTERNAL",
+        "UNAVAILABLE",
+        "DATA_LOSS",
+        "UNAUTHENTICATED"
+      ].freeze
+
+      # @private
+      ERROR_STRING_MAPPING = error_code_mapping.each_with_index.to_h.freeze
+
+      # @private
+      HTTP_GRPC_CODE_MAP = {
+        400 => 3, # InvalidArgumentError
+        401 => 16, # UnauthenticatedError
+        403 => 7, # PermissionDeniedError
+        404 => 5, # NotFoundError
+        409 => 6, # AlreadyExistsError
+        412 => 9, # FailedPreconditionError
+        429 => 8, # ResourceExhaustedError
+        499 => 1, # CanceledError
+        500 => 13, # InternalError
+        501 => 12, # UnimplementedError
+        503 => 14, # UnavailableError
+        504 => 4 # DeadlineExceededError
+      }.freeze
+
+      # @private
+      # Converts http error codes into corresponding gRPC ones
+      def self.grpc_error_for http_error_code
+        return 2 unless http_error_code
+
+        # The http status codes mapped to their error classes.
+        HTTP_GRPC_CODE_MAP[http_error_code] || 2 # UnknownError
+      end
+    end
+  end
+end

data/lib/gapic/common/polling_harness.rb

@@ -0,0 +1,82 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+require "gapic/common/retry_policy"
+
+module Gapic
+  module Common
+    ##
+    # Provides a generic mechanism for periodic polling an operation.
+    #
+    # Polling intervals are calculated from the provided retry policy.
+    #
+    # Supports exponential backoff via `multiplier`, and automatically
+    # retries gRPC errors listed in `retry_codes`.
+    #
+    class PollingHarness
+      # @return [Gapic::Common::RetryPolicy] The retry policy associated with this instance.
+      attr_reader :retry_policy
+
+      ##
+      # Create new Gapic::Common::PollingHarness instance.
+      #
+      # @param retry_policy [Gapic::Common::RetryPolicy] The retry policy to
+      #     use. If not provided, a new retry policy is constructed from the
+      #     given kwargs.
+      # @param kwargs [keywords] Keyword arguments used to create a new retry
+      #     policy. See {RetryPolicy#initialize}.
+      #
+      def initialize retry_policy: nil, **kwargs
+        @retry_policy = retry_policy ? retry_policy.dup : RetryPolicy.new(**kwargs)
+      end
+
+      ##
+      # Perform polling with exponential backoff. Repeatedly calls the given
+      # block until it returns a result other than the given sentinel value
+      # (normally `nil`), then returns that final result.
+      #
+      # Uses the retry policy regulate retries, including delays between tries,
+      # retriable errors, and final timeout. If an error code other than those
+      # listed in {RetryPolicy#retry_codes} is raised, it is propagated out. If
+      # the timeout expires, the given timeout result (normally `nil`) is
+      # returned.
+      #
+      # @param wait_sentinel [Object] The return value that should signal the
+      #     polling harness to continue waiting. Any other value is treated as
+      #     a real result and returned. Defaults to `nil`.
+      # @param timeout_result [Object] The result to return if timeout occurs.
+      #     Defaults to `nil`.
+      #
+      # @yieldreturn [Object] The result of the polling logic, either a result
+      #     to return, or the `wait_sentinel` value.
+      #
+      def wait wait_sentinel: nil, timeout_result: nil, mock_delay: false
+        unless block_given?
+          raise ArgumentError, "No callback provided to wait method."
+        end
+        retry_policy.start! mock_delay: mock_delay
+        loop do
+          begin
+            response = yield
+            return response unless response == wait_sentinel
+          rescue StandardError => e # Currently retry_error only accounts for ::GRPC::BadStatus.
+            raise unless retry_policy.retry_error? e
+          end
+          retry_policy.perform_delay!
+          return timeout_result unless retry_policy.retry_with_deadline?
+        end
+      end
+    end
+  end
+end

data/lib/gapic/common/retry_policy.rb

@@ -0,0 +1,255 @@
+# Copyright 2025 Google LLC
+#
+# Licensed 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.
+
+require "gapic/common/error_codes"
+
+module Gapic
+  module Common
+    ##
+    # Gapic Common retry policy base class.
+    #
+    class RetryPolicy
+      # @return [Numeric] Default initial delay in seconds.
+      DEFAULT_INITIAL_DELAY = 1
+      # @return [Numeric] Default maximum delay in seconds.
+      DEFAULT_MAX_DELAY = 15
+      # @return [Numeric] Default delay scaling factor for subsequent retry attempts.
+      DEFAULT_MULTIPLIER = 1.3
+      # @return [Array<String|Integer>] Default list of retry codes.
+      DEFAULT_RETRY_CODES = [].freeze
+      # @return [Numeric] Default timeout threshold value in seconds.
+      DEFAULT_TIMEOUT = 3600 # One hour
+
+      ##
+      # Create new Gapic::Common::RetryPolicy instance.
+      #
+      # @param initial_delay [Numeric] Initial delay in seconds.
+      # @param max_delay [Numeric] Maximum delay in seconds.
+      # @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.
+      #
+      def initialize initial_delay: nil, max_delay: nil, multiplier: nil, retry_codes: nil, timeout: nil
+        # 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
+        start!
+      end
+
+      # @return [Numeric] Initial delay in seconds.
+      def initial_delay
+        @initial_delay || DEFAULT_INITIAL_DELAY
+      end
+
+      # @return [Numeric] Maximum delay in seconds.
+      def max_delay
+        @max_delay || DEFAULT_MAX_DELAY
+      end
+
+      # @return [Numeric] The delay scaling factor for each subsequent retry attempt.
+      def multiplier
+        @multiplier || DEFAULT_MULTIPLIER
+      end
+
+      # @return [Array<Integer>] List of retry codes.
+      def retry_codes
+        @retry_codes || DEFAULT_RETRY_CODES
+      end
+
+      # @return [Numeric] Timeout threshold value in seconds.
+      def timeout
+        @timeout || DEFAULT_TIMEOUT
+      end
+
+      ##
+      # Returns a duplicate in a non-executing state, i.e. with the deadline
+      # and current delay reset.
+      #
+      # @return [RetryPolicy]
+      #
+      def dup
+        RetryPolicy.new initial_delay: @initial_delay,
+                        max_delay: @max_delay,
+                        multiplier: @multiplier,
+                        retry_codes: @retry_codes,
+                        timeout: @timeout
+      end
+
+      ##
+      # Perform delay if and only if retriable.
+      #
+      # If positional argument `error` is provided, the retriable logic uses
+      # `retry_codes`. Otherwise, `timeout` is used.
+      #
+      # @return [Boolean] Whether the delay was executed.
+      #
+      def call error = nil
+        should_retry = error.nil? ? retry_with_deadline? : retry_error?(error)
+        return false unless should_retry
+        perform_delay!
+      end
+      alias perform_delay call
+
+      ##
+      # Perform delay.
+      #
+      # @return [Boolean] Whether the delay was executed.
+      #
+      def perform_delay!
+        delay!
+        increment_delay!
+        @perform_delay_count += 1
+        true
+      end
+
+      ##
+      # Current delay value in seconds.
+      #
+      # @return [Numeric] Time delay in seconds.
+      #
+      def delay
+        @delay
+      end
+
+      ##
+      # Current number of times the delay has been performed
+      #
+      # @return [Integer]
+      #
+      def perform_delay_count
+        @perform_delay_count
+      end
+
+      ##
+      # Start tracking the deadline and delay by initializing those values.
+      #
+      # This is normally done when the object is constructed, but it can be
+      # done explicitly in order to reinitialize the state in case this
+      # retry policy was created in the past or is being reused.
+      #
+      # @param mock_delay [boolean,Proc] if truthy, delays are "mocked",
+      #     meaning they do not actually take time, but are measured as if they
+      #     did, which is useful for tests. If set to a Proc, it will be called
+      #     whenever a delay would happen, and passed the delay in seconds,
+      #     also useful for testing.
+      #
+      def start! mock_delay: false
+        @mock_time = mock_delay ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
+        @mock_delay_callback = mock_delay.respond_to?(:call) ? mock_delay : nil
+        @deadline = cur_time + timeout
+        @delay = initial_delay
+        @perform_delay_count = 0
+        self
+      end
+
+      ##
+      # @private
+      # @return [Boolean] Whether this error should be retried.
+      #
+      def retry_error? error
+        (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)))
+      end
+
+      # @private
+      # @return [Boolean] Whether this policy should be retried based on the deadline.
+      def retry_with_deadline?
+        deadline > cur_time
+      end
+
+      ##
+      # @private
+      # Apply default values to the policy object. This does not replace user-provided values,
+      # it only overrides empty values.
+      #
+      # @param retry_policy [Hash] The policy for error retry. Keys must match the arguments for
+      #   {Gapic::Common::RetryPolicy.new}.
+      #
+      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]
+
+        self
+      end
+
+      # @private Equality test
+      def eql? other
+        other.is_a?(RetryPolicy) &&
+          other.initial_delay == initial_delay &&
+          other.max_delay == max_delay &&
+          other.multiplier == multiplier &&
+          other.retry_codes == retry_codes &&
+          other.timeout == timeout
+      end
+      alias == eql?
+
+      # @private Hash code
+      def hash
+        [initial_delay, max_delay, multiplier, retry_codes, timeout].hash
+      end
+
+      private
+
+      # @private
+      # @return [Numeric] The performed delay.
+      def delay!
+        if @mock_time
+          @mock_time += delay
+          @mock_delay_callback&.call delay
+        else
+          Kernel.sleep delay
+        end
+      end
+
+      # @private
+      # @return [Numeric] The new delay in seconds.
+      def increment_delay!
+        @delay = [delay * multiplier, max_delay].min
+      end
+
+      # @private
+      # @return [Numeric] The deadline for timeout-based policies.
+      def deadline
+        @deadline
+      end
+
+      # @private
+      # Mockable way to get time.
+      def cur_time
+        @mock_time || Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # @private
+      # @return [Array<Integer> Error codes converted to their respective integer values.
+      def convert_codes input_codes
+        return nil if input_codes.nil?
+        Array(input_codes).map do |obj|
+          case obj
+          when String
+            ErrorCodes::ERROR_STRING_MAPPING[obj]
+          when Integer
+            obj
+          end
+        end.compact
+      end
+    end
+  end
+end

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.22.0".freeze
+    VERSION = "0.25.0".freeze
   end
 end