gapic-common 0.20.0 → 1.2.0

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.20.0".freeze
+    VERSION = "1.2.0".freeze
   end
 end

data/lib/gapic/common.rb

@@ -16,6 +16,7 @@ require "grpc/errors"
 require "grpc/core/status_codes"
 
 require "gapic/common/error"
+require "gapic/common/polling_harness"
 require "gapic/call_options"
 require "gapic/headers"
 require "gapic/operation"

data/lib/gapic/config.rb

@@ -50,7 +50,7 @@ module Gapic
     #
     def config_attr name, default, *valid_values, &validator
       name = String(name).to_sym
-      name_setter = "#{name}=".to_sym
+      name_setter = :"#{name}="
       raise NameError, "invalid config name #{name}" if name !~ /^[a-zA-Z]\w*$/ || name == :parent_config
       raise NameError, "method #{name} already exists" if method_defined? name
       raise NameError, "method #{name_setter} already exists" if method_defined? name_setter
@@ -58,7 +58,7 @@ module Gapic
       raise ArgumentError, "validation must be provided" if validator.nil? && valid_values.empty?
       validator ||= ->(value) { valid_values.any? { |v| v === value } }
 
-      name_ivar = "@#{name}".to_sym
+      name_ivar = :"@#{name}"
 
       create_getter name_ivar, name, default
       create_setter name_ivar, name_setter, default, validator

data/lib/gapic/grpc/service_stub/channel.rb

@@ -32,12 +32,13 @@ module Gapic
       # Creates a new Channel instance
       #
       def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil,
-                     on_channel_create: nil
+                     on_channel_create: nil, stub_logger: nil
         @grpc_stub_class = grpc_stub_class
         @endpoint = endpoint
         @credentials = credentials
         @channel_args = Hash channel_args
         @interceptors = Array interceptors
+        @stub_logger = stub_logger
         @concurrent_streams = 0
         @mutex = Mutex.new
         setup_grpc_stub
@@ -88,11 +89,10 @@ module Gapic
       def call_rpc method_name, request, options: nil, &block
         @mutex.synchronize { @concurrent_streams += 1 }
         begin
-          rpc_call = RpcCall.new @grpc_stub.method method_name
+          meth = @grpc_stub.method method_name
+          rpc_call = RpcCall.new meth, stub_logger: @stub_logger, method_name: method_name
           response = rpc_call.call request, options: options, &block
           response
-        rescue StandardError => e
-          raise e
         ensure
           @mutex.synchronize { @concurrent_streams -= 1 }
         end

data/lib/gapic/grpc/service_stub/channel_pool.rb

@@ -30,7 +30,12 @@ module Gapic
       ##
       # Initialize an instance of ServiceStub::ChannelPool
       #
-      def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil, config: nil
+      def initialize grpc_stub_class,
+                     endpoint:, credentials:,
+                     channel_args: nil,
+                     interceptors: nil,
+                     config: nil,
+                     stub_logger: nil
         if credentials.is_a? ::GRPC::Core::Channel
           raise ArgumentError, "Can't create a channel pool with GRPC::Core::Channel as credentials"
         end
@@ -41,6 +46,7 @@ module Gapic
         @channel_args = channel_args
         @interceptors = interceptors
         @config = config || Configuration.new
+        @stub_logger = stub_logger
 
         @channels = (1..@config.channel_count).map { create_channel }
       end
@@ -49,7 +55,8 @@ module Gapic
       # Creates a new channel.
       def create_channel
         Channel.new @grpc_stub_class, endpoint: @endpoint, credentials: @credentials, channel_args: @channel_args,
-                    interceptors: @interceptors, on_channel_create: @config.on_channel_create
+                    interceptors: @interceptors, on_channel_create: @config.on_channel_create,
+                    stub_logger: @stub_logger
       end
 
       ##

data/lib/gapic/grpc/service_stub/rpc_call.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "gapic/call_options"
+require "gapic/logging_concerns"
 require "grpc/errors"
 
 module Gapic
@@ -32,8 +33,11 @@ module Gapic
       #
       # @param stub_method [Proc] Used to make a bare rpc call.
       #
-      def initialize stub_method
+      def initialize stub_method, stub_logger: nil, method_name: nil
         @stub_method = stub_method
+        @stub_logger = stub_logger
+        @method_name = method_name
+        @request_id = LoggingConcerns.random_uuid4
       end
 
       ##
@@ -44,7 +48,8 @@ module Gapic
       #   customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}. This object
       #   should only be used once.
       #
-      # @yield [response, operation] Access the response along with the RPC operation.
+      # @yield [response, operation] Access the response along with the RPC operation. Additionally, throwing
+      #   `:response, obj` within the block will change the return value to `obj`.
       # @yieldparam response [Object] The response object.
       # @yieldparam operation [::GRPC::ActiveCall::Operation] The RPC operation for the response.
       #
@@ -91,7 +96,7 @@ module Gapic
       #   )
       #   response = echo_call.call request, options: options
       #
-      # @example Accessing the response and RPC operation using a block:
+      # @example Accessing the RPC operation using a block:
       #   require "google/showcase/v1beta1/echo_pb"
       #   require "google/showcase/v1beta1/echo_services_pb"
       #   require "gapic"
@@ -107,8 +112,8 @@ module Gapic
       #   echo_call = Gapic::ServiceStub::RpcCall.new echo_stub.method :echo
       #
       #   request = Google::Showcase::V1beta1::EchoRequest.new
-      #   echo_call.call request do |response, operation|
-      #     operation.trailing_metadata
+      #   metadata = echo_call.call request do |_response, operation|
+      #     throw :response, operation.trailing_metadata
       #   end
       #
       def call request, options: nil
@@ -117,21 +122,27 @@ module Gapic
         deadline = calculate_deadline options
         metadata = options.metadata
 
+        try_number = 1
         retried_exception = nil
         begin
+          request = log_request request, metadata, try_number
           operation = stub_method.call request, deadline: deadline, metadata: metadata, return_op: true
           response = operation.execute
-          yield response, operation if block_given?
-          response
+          catch :response do
+            response = log_response response, try_number
+            yield response, operation if block_given?
+            response
+          end
         rescue ::GRPC::DeadlineExceeded => e
+          log_response e, try_number
           raise Gapic::GRPC::DeadlineExceededError.new e.message, root_cause: retried_exception
         rescue StandardError => e
-          if e.is_a?(::GRPC::Unavailable) && /Signet::AuthorizationError/ =~ e.message
-            e = Gapic::GRPC::AuthorizationError.new e.message.gsub(%r{^\d+:}, "")
-          end
+          e = normalize_exception e
+          log_response e, try_number
 
           if check_retry?(deadline) && options.retry_policy.call(e)
             retried_exception = e
+            try_number += 1
             retry
           end
 
@@ -145,13 +156,110 @@ module Gapic
         return if options.timeout.nil?
         return if options.timeout.negative?
 
-        Time.now + options.timeout
+        current_time + options.timeout
       end
 
       def check_retry? deadline
         return true if deadline.nil?
 
-        deadline > Time.now
+        deadline > current_time
+      end
+
+      def current_time
+        # An alternative way of saying Time.now without actually calling
+        # Time.now. This allows clients that replace Time.now (e.g. via the
+        # timecop gem) to do so without interfering with the deadline.
+        nanos = Process.clock_gettime Process::CLOCK_REALTIME, :nanosecond
+        secs_part = nanos / 1_000_000_000
+        nsecs_part = nanos % 1_000_000_000
+        Time.at secs_part, nsecs_part, :nanosecond
+      end
+
+      def normalize_exception exception
+        if exception.is_a?(::GRPC::Unavailable) && /Signet::AuthorizationError/ =~ exception.message
+          exception = Gapic::GRPC::AuthorizationError.new exception.message.gsub(%r{^\d+:}, "")
+        end
+        exception
+      end
+
+      def log_request request, metadata, try_number
+        return request unless @stub_logger&.enabled?
+        @stub_logger.info do |entry|
+          entry.set_system_name
+          entry.set_service
+          entry.set "rpcName", @method_name
+          entry.set "retryAttempt", try_number
+          entry.set "requestId", @request_id
+          entry.message =
+            if request.is_a? Enumerable
+              "Sending stream to #{entry.service}.#{@method_name} (try #{try_number})"
+            else
+              "Sending request to #{entry.service}.#{@method_name} (try #{try_number})"
+            end
+        end
+        loggable_metadata = metadata.to_h rescue {}
+        if request.is_a? Enumerable
+          request.lazy.map do |req|
+            log_single_request req, loggable_metadata
+          end
+        else
+          log_single_request request, loggable_metadata
+        end
+      end
+
+      def log_single_request request, metadata
+        request_content = request.respond_to?(:to_h) ? (request.to_h rescue {}) : request.to_s
+        if !request_content.empty? || !metadata.empty?
+          @stub_logger.debug do |entry|
+            entry.set "requestId", @request_id
+            entry.set "request", request_content
+            entry.set "headers", metadata
+            entry.message = "(request payload as #{request.class})"
+          end
+        end
+        request
+      end
+
+      def log_response response, try_number
+        return response unless @stub_logger&.enabled?
+        @stub_logger.info do |entry|
+          entry.set_system_name
+          entry.set_service
+          entry.set "rpcName", @method_name
+          entry.set "retryAttempt", try_number
+          entry.set "requestId", @request_id
+          case response
+          when StandardError
+            entry.set "exception", response.to_s
+            entry.message = "Received error for #{entry.service}.#{@method_name} (try #{try_number}): #{response}"
+          when Enumerable
+            entry.message = "Receiving stream for #{entry.service}.#{@method_name} (try #{try_number})"
+          else
+            entry.message = "Received response for #{entry.service}.#{@method_name} (try #{try_number})"
+          end
+        end
+        case response
+        when StandardError
+          response
+        when Enumerable
+          response.lazy.map do |resp|
+            log_single_response resp
+          end
+        else
+          log_single_response response
+        end
+      end
+
+      def log_single_response response
+        response_content = response.respond_to?(:to_h) ? (response.to_h rescue {}) : response.to_s
+        unless response_content.empty?
+          @stub_logger.debug do |entry|
+            entry.set "requestId", @request_id
+            entry.set "response", response_content
+            entry.message = "(response payload as #{response.class})"
+          end
+        end
+        response
       end
     end
   end

data/lib/gapic/grpc/service_stub.rb

@@ -17,7 +17,8 @@ require "googleauth"
 require "gapic/grpc/service_stub/rpc_call"
 require "gapic/grpc/service_stub/channel"
 require "gapic/grpc/service_stub/channel_pool"
-
+require "gapic/logging_concerns"
+require "gapic/universe_domain_concerns"
 
 module Gapic
   ##
@@ -31,6 +32,9 @@ module Gapic
   #   @return [Gapic::ServiceStub::ChannelPool] The instance of the ChannelPool class.
   #
   class ServiceStub
+    include UniverseDomainConcerns
+    include LoggingConcerns
+
     attr_reader :grpc_stub
     attr_reader :channel_pool
 
@@ -38,7 +42,12 @@ module Gapic
     # Creates a Gapic gRPC stub object.
     #
     # @param grpc_stub_class [Class] gRPC stub class to create a new instance of.
-    # @param endpoint [String] The endpoint of the API.
+    # @param endpoint [String] The endpoint of the API. Overrides any endpoint_template.
+    # @param endpoint_template [String] The endpoint of the API, where the
+    #   universe domain component of the hostname is marked by the string in
+    #   the constant {UniverseDomainConcerns::ENDPOINT_SUBSTITUTION}.
+    # @param universe_domain [String] The universe domain in which calls should
+    #   be made. Defaults to `googleapis.com`.
     # @param credentials [Google::Auth::Credentials, Signet::OAuth2::Client, String, Hash, Proc,
     #   ::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials] Provides the means for authenticating requests made by
     #   the client. This parameter can be many types:
@@ -57,25 +66,42 @@ module Gapic
     #   be used for intercepting calls before they are executed Interceptors are an EXPERIMENTAL API.
     # @param channel_pool_config [::Gapic::ServiceStub:ChannelPool::Configuration] The configuration for channel
     #     pool. This argument will raise error when `credentials` is provided as a `::GRPC::Core::Channel`.
-    #
-    def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil,
-                   interceptors: nil, channel_pool_config: nil
+    # @param logger [Logger,:default,nil] An explicit logger to use, or one
+    #   of the values `:default` (the default) to construct a default logger,
+    #   or `nil` to disable logging explicitly.
+    #
+    def initialize grpc_stub_class,
+                   credentials:,
+                   endpoint: nil,
+                   endpoint_template: nil,
+                   universe_domain: nil,
+                   channel_args: nil,
+                   interceptors: nil,
+                   channel_pool_config: nil,
+                   logger: :default
       raise ArgumentError, "grpc_stub_class is required" if grpc_stub_class.nil?
-      raise ArgumentError, "endpoint is required" if endpoint.nil?
-      raise ArgumentError, "credentials is required" if credentials.nil?
+
+      setup_universe_domain universe_domain: universe_domain,
+                            endpoint: endpoint,
+                            endpoint_template: endpoint_template,
+                            credentials: credentials
+      setup_logging logger: logger,
+                    system_name: grpc_stub_class,
+                    service: grpc_stub_class,
+                    endpoint: self.endpoint,
+                    client_id: object_id
 
       @channel_pool = nil
       @grpc_stub = nil
       channel_args = Hash channel_args
       interceptors = Array interceptors
 
-
       if channel_pool_config && channel_pool_config.channel_count > 1
-        create_channel_pool grpc_stub_class, endpoint: endpoint, credentials: credentials,
+        create_channel_pool grpc_stub_class, endpoint: self.endpoint, credentials: self.credentials,
                             channel_args: channel_args, interceptors: interceptors,
                             channel_pool_config: channel_pool_config
       else
-        create_grpc_stub grpc_stub_class, endpoint: endpoint, credentials: credentials,
+        create_grpc_stub grpc_stub_class, endpoint: self.endpoint, credentials: self.credentials,
                          channel_args: channel_args, interceptors: interceptors
       end
     end
@@ -87,7 +113,7 @@ module Gapic
       end
       @channel_pool = ChannelPool.new grpc_stub_class, endpoint: endpoint, credentials: credentials,
                         channel_args: channel_args, interceptors: interceptors,
-                        config: channel_pool_config
+                        config: channel_pool_config, stub_logger: stub_logger
     end
 
     def create_grpc_stub grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil
@@ -186,7 +212,8 @@ module Gapic
     #
     def call_rpc method_name, request, options: nil, &block
       if @channel_pool.nil?
-        rpc_call = RpcCall.new @grpc_stub.method method_name
+        meth = @grpc_stub.method method_name
+        rpc_call = RpcCall.new meth, stub_logger: stub_logger, method_name: method_name
         rpc_call.call request, options: options, &block
       else
         @channel_pool.call_rpc method_name, request, options: options, &block

data/lib/gapic/headers.rb

@@ -19,6 +19,8 @@ require "gapic/common/version"
 module Gapic
   # A collection of common header values.
   module Headers
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
     ##
     # @param ruby_version [String] The ruby version. Defaults to `RUBY_VERSION`.
     # @param lib_name [String] The client library name.
@@ -32,10 +34,10 @@ module Gapic
     #     `:grpc` to send the GRPC library version (if defined)
     #     `:rest` to send the REST library version (if defined)
     #   Defaults to `[:grpc]`
+    #
     def self.x_goog_api_client ruby_version: nil, lib_name: nil, lib_version: nil, gax_version: nil,
                                gapic_version: nil, grpc_version: nil, rest_version: nil, protobuf_version: nil,
                                transports_version_send: [:grpc]
-
       ruby_version ||= ::RUBY_VERSION
       gax_version  ||= ::Gapic::Common::VERSION
       grpc_version ||= ::GRPC::VERSION if defined? ::GRPC::VERSION
@@ -52,4 +54,6 @@ module Gapic
       x_goog_api_client_header.join " ".freeze
     end
   end
+
+  # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
 end