gapic-common 0.22.0 → 0.25.0

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/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,7 +89,8 @@ 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
         ensure

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
+        @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
+        @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,6 +17,7 @@ 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
@@ -32,6 +33,7 @@ module Gapic
   #
   class ServiceStub
     include UniverseDomainConcerns
+    include LoggingConcerns
 
     attr_reader :grpc_stub
     attr_reader :channel_pool
@@ -64,6 +66,9 @@ 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`.
+    # @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:,
@@ -72,13 +77,19 @@ module Gapic
                    universe_domain: nil,
                    channel_args: nil,
                    interceptors: nil,
-                   channel_pool_config: nil
+                   channel_pool_config: nil,
+                   logger: :default
       raise ArgumentError, "grpc_stub_class is required" if grpc_stub_class.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
@@ -102,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
@@ -201,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

data/lib/gapic/logging_concerns.rb

@@ -0,0 +1,210 @@
+# Copyright 2024 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 "google/cloud/env"
+require "google/logging/message"
+require "google/logging/structured_formatter"
+
+module Gapic
+  ##
+  # A mixin module that handles logging setup for a stub.
+  #
+  module LoggingConcerns
+    ##
+    # The logger for this object.
+    #
+    # @return [Logger]
+    #
+    attr_reader :logger
+
+    ##
+    # @private
+    # A convenience object used by stub-based logging.
+    #
+    class StubLogger
+      OMIT_FILES = [
+        /^#{Regexp.escape __dir__}/
+      ].freeze
+
+      def initialize logger: nil, **kwargs
+        @logger = logger
+        @kwargs = kwargs
+      end
+
+      def log severity
+        return unless @logger
+        locations = caller_locations
+        @logger.add severity do
+          builder = LogEntryBuilder.new(**@kwargs)
+          builder.set_source_location_from locations
+          yield builder
+          builder.build
+        rescue StandardError
+          # Do nothing
+        end
+      end
+
+      def info &block
+        log Logger::INFO, &block
+      end
+
+      def debug &block
+        log Logger::DEBUG, &block
+      end
+
+      ##
+      # @private
+      # Builder for a log entry, passed to {StubLogger#log}.
+      #
+      class LogEntryBuilder
+        def initialize system_name: nil,
+                       service: nil,
+                       endpoint: nil,
+                       client_id: nil
+          @system_name = system_name
+          @service = service
+          @endpoint = endpoint
+          @client_id = client_id
+          @message = nil
+          @caller_locations = caller_locations
+          @fields = { "clientId" => @client_id }
+        end
+
+        attr_reader :system_name
+
+        attr_reader :service
+
+        attr_reader :endpoint
+
+        attr_accessor :message
+
+        attr_writer :source_location
+
+        attr_reader :fields
+
+        def set name, value
+          fields[name] = value
+        end
+
+        def set_system_name
+          set "system", system_name
+        end
+
+        def set_service
+          set "serviceName", service
+        end
+
+        def set_credentials_fields creds
+          creds = creds.client if creds.respond_to? :client
+          set "credentialsId", creds.object_id
+          set "credentialsType", creds.class.name
+          set "credentialsScope", creds.scope if creds.respond_to? :scope
+          set "useSelfSignedJWT", creds.enable_self_signed_jwt? if creds.respond_to? :enable_self_signed_jwt?
+          set "universeDomain", creds.universe_domain if creds.respond_to? :universe_domain
+        end
+
+        def source_location
+          @source_location ||= Google::Logging::SourceLocation.for_caller omit_files: OMIT_FILES,
+                                                                          locations: @caller_locations
+        end
+
+        def set_source_location_from locations
+          @caller_locations = locations
+          @source_location = nil
+        end
+
+        def build
+          Google::Logging::Message.from message: message, source_location: source_location, fields: fields
+        end
+      end
+    end
+
+    ##
+    # @private
+    # Initialize logging concerns.
+    #
+    def setup_logging logger: :default,
+                      stream: nil,
+                      formatter: nil,
+                      level: nil,
+                      system_name: nil,
+                      service: nil,
+                      endpoint: nil,
+                      client_id: nil
+      service = LoggingConcerns.normalize_service service
+      system_name = LoggingConcerns.normalize_system_name system_name
+      logging_env = ENV["GOOGLE_SDK_RUBY_LOGGING_GEMS"].to_s.downcase
+      logger = nil if ["false", "none"].include? logging_env
+      if logger == :default
+        logger = nil
+        if ["true", "all"].include?(logging_env) || logging_env.split(",").include?(system_name)
+          stream ||= $stderr
+          level ||= "DEBUG"
+          formatter ||= Google::Logging::StructuredFormatter.new if Google::Cloud::Env.get.logging_agent_expected?
+          logger = Logger.new stream, progname: system_name, level: level, formatter: formatter
+        end
+      end
+      @logger = logger
+      @stub_logger = StubLogger.new logger: logger,
+                                    system_name: system_name,
+                                    service: service,
+                                    endpoint: endpoint,
+                                    client_id: client_id
+    end
+
+    # @private
+    attr_reader :stub_logger
+
+    class << self
+      # @private
+      def random_uuid4
+        ary = Random.bytes 16
+        ary.setbyte 6, ((ary.getbyte(6) & 0x0f) | 0x40)
+        ary.setbyte 8, ((ary.getbyte(8) & 0x3f) | 0x80)
+        ary.unpack("H8H4H4H4H12").join "-"
+      end
+
+      # @private
+      def normalize_system_name input
+        case input
+        when String
+          input
+        when Class
+          input.name.split("::")[..-3]
+               .map { |elem| elem.scan(/[A-Z][A-Z]*(?=[A-Z][a-z0-9]|$)|[A-Z][a-z0-9]+/).map(&:downcase).join("_") }
+               .join("-")
+        else
+          "googleapis"
+        end
+      end
+
+      # @private
+      def normalize_service input
+        case input
+        when String
+          input
+        when Class
+          mod = input.name.split("::")[..-2].inject(Object) { |m, n| m.const_get n }
+          if mod.const_defined? "Service"
+            mod.const_get("Service").service_name
+          else
+            name_segments = input.name.split("::")[..-3]
+            mod = name_segments.inject(Object) { |m, n| m.const_get n }
+            name_segments.join "." if mod.const_defined? "Rest"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/operation/retry_policy.rb

@@ -12,80 +12,40 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/common/retry_policy"
+
 module Gapic
   class Operation
     ##
-    # The policy for retrying operation reloads using an incremental backoff. A new object instance should be used for
-    # every Operation invocation.
+    # The policy for retrying operation reloads using an incremental backoff.
+    #
+    # A new object instance should be used for every Operation invocation.
     #
-    class RetryPolicy
+    class RetryPolicy < Gapic::Common::RetryPolicy
+      # @return [Numeric] Default initial delay in seconds.
+      DEFAULT_INITIAL_DELAY = 10
+      # @return [Numeric] Default maximum delay in seconds.
+      DEFAULT_MAX_DELAY = 300 # Five minutes
+      # @return [Numeric] Default delay scaling factor for subsequent retry attempts.
+      DEFAULT_MULTIPLIER = 1.3
+      # @return [Numeric] Default timeout threshold value in seconds.
+      DEFAULT_TIMEOUT = 3600 # One hour
+
       ##
       # Create new Operation RetryPolicy.
       #
-      # @param initial_delay [Numeric] client-side timeout
-      # @param multiplier [Numeric] client-side timeout
-      # @param max_delay [Numeric] client-side timeout
-      # @param timeout [Numeric] client-side timeout
+      # @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 timeout [Numeric] Timeout threshold value in seconds.
       #
       def initialize initial_delay: nil, multiplier: nil, max_delay: nil, timeout: nil
-        @initial_delay = initial_delay
-        @multiplier    = multiplier
-        @max_delay     = max_delay
-        @timeout       = timeout
-        @delay         = nil
-      end
-
-      def initial_delay
-        @initial_delay || 10
-      end
-
-      def multiplier
-        @multiplier || 1.3
-      end
-
-      def max_delay
-        @max_delay || 300 # Five minutes
-      end
-
-      def timeout
-        @timeout || 3600 # One hour
-      end
-
-      def call
-        return unless retry?
-
-        delay!
-        increment_delay!
-
-        true
-      end
-
-      private
-
-      def deadline
-        # memoize the deadline
-        @deadline ||= Time.now + timeout
-      end
-
-      def retry?
-        deadline > Time.now
-      end
-
-      ##
-      # The current delay value.
-      def delay
-        @delay || initial_delay
-      end
-
-      def delay!
-        # Call Kernel.sleep so we can stub it.
-        Kernel.sleep delay
-      end
-
-      ##
-      # Calculate and set the next delay value.
-      def increment_delay!
-        @delay = [delay * multiplier, max_delay].min
+        super(
+          initial_delay: initial_delay || DEFAULT_INITIAL_DELAY,
+          max_delay: max_delay || DEFAULT_MAX_DELAY,
+          multiplier: multiplier || DEFAULT_MULTIPLIER,
+          timeout: timeout || DEFAULT_TIMEOUT
+        )
       end
     end
   end