gapic-common 0.20.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd54dc9471821e191b81b38efd0e03c24cfaaad13093b7b20d174a7235db9408
-  data.tar.gz: dda7b540eedb2fb8f665548a6844b6c98c6b5e0b601d4627be16d229cdc1b65f
+  metadata.gz: ac5c845df865497acbdcb4656a47667dd657083d85ef964f633fc0540ef80493
+  data.tar.gz: 851ab12cf7a9e8d5e5f93c991846f0a4701a5a96047fef0ebb17392a55061984
 SHA512:
-  metadata.gz: cedbf49ae436a114a347723bda04637fee02481d7a56624f80f79ab1e2903ccc290a7667e1584d11c66bc0b60295333315f99ac15d01806c1713171ed3179dde
-  data.tar.gz: a4f733db0e1bb0e158d982fe189dc510195e24299fa8880255917ae7a68b2a2d47ff740bf304fd187678c2ace7c9a75cdabf341347e0f0066fe16e40e7e8d0be
+  metadata.gz: 3225a82b3d2b7006fa0191c55e46e836724ec07d240d7fc5eb11188ccc5613572a714a012a5e904d85cc70d13bb816cd735faf0c3b458e54552e36f483f07f21
+  data.tar.gz: 7d4e26754019a71ae7bca52e2e195b71db46c755c6eca1cce34504990e31f2055d390119d9ae0bf81d1b217f7f1d3185200557da3c4d04b8aa251a3d87a13b54

data/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Release History
 
+### 1.2.0 (2025-09-04)
+
+#### Features
+
+* update google-protobuf dependency ([#41](https://github.com/googleapis/ruby-core-libraries/issues/41)) 
+
+### 1.1.0 (2025-08-11)
+
+#### Features
+
+* add http binding configuration ([#38](https://github.com/googleapis/ruby-core-libraries/issues/38)) 
+
+### 1.0.1 (2025-07-17)
+
+#### Bug Fixes
+
+* Removed log preprocessing of large payload data when logging is disabled ([#35](https://github.com/googleapis/ruby-core-libraries/issues/35)) 
+
+### 1.0.0 (2025-04-30)
+
+#### Features
+
+* Bump version to 1.0 ([#33](https://github.com/googleapis/ruby-core-libraries/issues/33)) 
+
+### 0.26.0 (2025-04-30)
+
+#### Features
+
+* Updated required Ruby version to 3.1 ([#29](https://github.com/googleapis/ruby-core-libraries/issues/29)) 
+
+### 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
+
+* Support for google-protobuf 4.x
+* Requires at least Ruby 3.0
+
+### 0.21.2 (2024-07-02)
+
+#### Bug Fixes
+
+* Start requiring ostruct in generated test helper files ([#1065](https://github.com/googleapis/gapic-generator-ruby/issues/1065)) 
+
+### 0.21.1 (2023-12-14)
+
+#### Bug Fixes
+
+* add missing module import for universe_domain_concerns ([#1016](https://github.com/googleapis/gapic-generator-ruby/issues/1016)) 
+
+### 0.21.0 (2023-12-13)
+
+#### Features
+
+* Drop support for Ruby 2.6 ([#1009](https://github.com/googleapis/gapic-generator-ruby/issues/1009)) 
+* Honor universe domain in stubs ([#1008](https://github.com/googleapis/gapic-generator-ruby/issues/1008)) 
+
 ### 0.20.0 (2023-08-31)
 
 #### 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