gapic-common 0.20.0 → 1.2.0

data/lib/gapic/logging_concerns.rb

@@ -0,0 +1,214 @@
+# 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 enabled?
+        !!@logger
+      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(&)
+        log(Logger::INFO, &)
+      end
+
+      def debug(&)
+        log(Logger::DEBUG, &)
+      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

data/lib/gapic/paged_enumerable.rb

@@ -250,7 +250,7 @@ module Gapic
       # @return [Boolean]
       #
       def next_page_token?
-        return if @response.nil?
+        return if @response.nil? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
 
         !@response.next_page_token.empty?
       end

data/lib/gapic/rest/client_stub.rb

@@ -13,7 +13,9 @@
 # limitations under the License.
 
 require "googleauth"
+require "gapic/logging_concerns"
 require "gapic/rest/faraday_middleware"
+require "gapic/universe_domain_concerns"
 require "faraday/retry"
 
 module Gapic
@@ -26,35 +28,64 @@ module Gapic
     #   - store credentials and add auth information to the request
     #
     class ClientStub
+      include UniverseDomainConcerns
+      include LoggingConcerns
+
       ##
       # Initializes with an endpoint and credentials
-      # @param endpoint [String] an endpoint for the service that this stub will send requests to
+      #
+      # @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]
       #   Credentials to send with calls in form of a googleauth credentials object.
       #   (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
       # @param numeric_enums [Boolean] Whether to signal the server to JSON-encode enums as ints
-      #
       # @param raise_faraday_errors [Boolean]
       #   Whether to raise Faraday errors instead of wrapping them in `Gapic::Rest::Error`
       #   Added for backwards compatibility.
       #   Default is `true`. All REST clients (except for old versions of `google-cloud-compute-v1`)
       #   should explicitly set this parameter to `false`.
+      # @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.
       #
       # @yield [Faraday::Connection]
       #
-      def initialize endpoint:, credentials:, numeric_enums: false, raise_faraday_errors: true
-        @endpoint = endpoint
-        @endpoint = "https://#{endpoint}" unless /^https?:/.match? endpoint
-        @endpoint = @endpoint.sub %r{/$}, ""
+      def initialize credentials:,
+                     endpoint: nil,
+                     endpoint_template: nil,
+                     universe_domain: nil,
+                     numeric_enums: false,
+                     raise_faraday_errors: true,
+                     logging_system: nil,
+                     service_name: nil,
+                     logger: :default
+        setup_universe_domain universe_domain: universe_domain,
+                              endpoint: endpoint,
+                              endpoint_template: endpoint_template,
+                              credentials: credentials
+
+        endpoint_url = self.endpoint
+        endpoint_url = "https://#{endpoint_url}" unless /^https?:/.match? endpoint_url
+        endpoint_url = endpoint_url.sub %r{/$}, ""
+
+        setup_logging logger: logger,
+                      system_name: logging_system,
+                      service: service_name,
+                      endpoint: endpoint_url,
+                      client_id: object_id
 
-        @credentials = credentials
         @numeric_enums = numeric_enums
 
         @raise_faraday_errors = raise_faraday_errors
 
-        @connection = Faraday.new url: @endpoint do |conn|
+        @connection = Faraday.new url: endpoint_url do |conn|
           conn.headers = { "Content-Type" => "application/json" }
-          conn.request :google_authorization, @credentials unless @credentials.is_a? ::Symbol
+          conn.request :google_authorization, self.credentials unless self.credentials.is_a? ::Symbol
           conn.request :retry
           conn.response :raise_error
           conn.adapter :net_http
@@ -71,8 +102,8 @@ module Gapic
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
-      def make_get_request uri:, params: {}, options: {}
-        make_http_request :get, uri: uri, body: nil, params: params, options: options
+      def make_get_request uri:, params: {}, options: {}, method_name: nil
+        make_http_request :get, uri: uri, body: nil, params: params, options: options, method_name: method_name
       end
 
       ##
@@ -83,8 +114,8 @@ module Gapic
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
-      def make_delete_request uri:, params: {}, options: {}
-        make_http_request :delete, uri: uri, body: nil, params: params, options: options
+      def make_delete_request uri:, params: {}, options: {}, method_name: nil
+        make_http_request :delete, uri: uri, body: nil, params: params, options: options, method_name: method_name
       end
 
       ##
@@ -96,8 +127,8 @@ module Gapic
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
-      def make_patch_request uri:, body:, params: {}, options: {}
-        make_http_request :patch, uri: uri, body: body, params: params, options: options
+      def make_patch_request uri:, body:, params: {}, options: {}, method_name: nil
+        make_http_request :patch, uri: uri, body: body, params: params, options: options, method_name: method_name
       end
 
       ##
@@ -109,8 +140,8 @@ module Gapic
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
-      def make_post_request uri:, body: nil, params: {}, options: {}
-        make_http_request :post, uri: uri, body: body, params: params, options: options
+      def make_post_request uri:, body: nil, params: {}, options: {}, method_name: nil
+        make_http_request :post, uri: uri, body: body, params: params, options: options, method_name: method_name
       end
 
       ##
@@ -122,8 +153,8 @@ module Gapic
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
-      def make_put_request uri:, body: nil, params: {}, options: {}
-        make_http_request :put, uri: uri, body: body, params: params, options: options
+      def make_put_request uri:, body: nil, params: {}, options: {}, method_name: nil
+        make_http_request :put, uri: uri, body: body, params: params, options: options, method_name: method_name
       end
 
       ##
@@ -137,27 +168,38 @@ module Gapic
       # @param is_server_streaming [Boolean] flag if method is streaming
       # @yieldparam chunk [String] The chunk of data received during server streaming.
       # @return [Faraday::Response]
-      def make_http_request verb, uri:, body:, params:, options:, is_server_streaming: false, &block
+      def make_http_request verb,
+                            uri:, body:, params:, options:,
+                            is_server_streaming: false, method_name: nil,
+                            &block
         # Converts hash and nil to an options object
         options = ::Gapic::CallOptions.new(**options.to_h) unless options.is_a? ::Gapic::CallOptions
         deadline = calculate_deadline options
         retried_exception = nil
         next_timeout = get_timeout deadline
+        request_id = LoggingConcerns.random_uuid4
+        try_number = 1
 
         begin
-          base_make_http_request(verb: verb, uri: uri, body: body,
-                                 params: params, metadata: options.metadata,
-                                 timeout: next_timeout,
-                                 is_server_streaming: is_server_streaming,
-                                 &block)
+          log_request method_name, request_id, try_number, body, options.metadata
+          response = base_make_http_request verb: verb, uri: uri, body: body,
+                                            params: params, metadata: options.metadata,
+                                            timeout: next_timeout,
+                                            is_server_streaming: is_server_streaming,
+                                            &block
+          log_response method_name, request_id, try_number, response, is_server_streaming
+          response
         rescue ::Faraday::TimeoutError => e
+          log_response method_name, request_id, try_number, e, is_server_streaming
           raise if @raise_faraday_errors
           raise Gapic::Rest::DeadlineExceededError.wrap_faraday_error e, root_cause: retried_exception
         rescue ::Faraday::Error => e
+          log_response method_name, request_id, try_number, e, is_server_streaming
           next_timeout = get_timeout deadline
 
           if check_retry?(next_timeout) && options.retry_policy.call(e)
             retried_exception = e
+            try_number += 1
             retry
           end
 
@@ -234,6 +276,54 @@ module Gapic
 
         timeout.positive?
       end
+
+      def log_request method_name, request_id, try_number, body, metadata
+        return 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 = "Sending request to #{entry.service}.#{method_name} (try #{try_number})"
+        end
+        body = body.to_s
+        metadata = metadata.to_h rescue {}
+        return if body.empty? && metadata.empty?
+        stub_logger.debug do |entry|
+          entry.set "requestId", request_id
+          entry.set "request", body
+          entry.set "headers", metadata
+          entry.message = "(request payload as JSON)"
+        end
+      end
+
+      def log_response method_name, request_id, try_number, response, is_server_streaming
+        return 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
+          if response.is_a? StandardError
+            entry.set "exception", response.to_s
+            entry.message = "Received error for #{entry.service}.#{method_name} (try #{try_number}): #{response}"
+          elsif is_server_streaming
+            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
+        return if is_server_streaming || !response.respond_to?(:body)
+        body = response.body.to_s
+        return if body.empty?
+        stub_logger.debug do |entry|
+          entry.set "requestId", request_id
+          entry.set "response", body
+          entry.message = "(response payload as JSON)"
+        end
+      end
     end
   end
 end

data/lib/gapic/rest/http_binding_override_configuration.rb

@@ -0,0 +1,48 @@
+# 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/config"
+
+module Gapic
+  module Rest
+    ##
+    # @private
+    # A specialized Configuration class to use when generating
+    # package-level binding override configuration.
+    #
+    # This configuration is for internal use of the client library classes,
+    # and it is not intended that the end-users will read or change it.
+    #
+    # @attribute [rw] bindings_override
+    #  Overrides for http bindings for the RPC of the mixins for the given package.
+    #  return [::Hash{::Symbol=>::Array<::Gapic::Rest::GrpcTranscoder::HttpBinding>}]
+    #
+    class HttpBindingOverrideConfiguration
+      extend ::Gapic::Config
+
+      # @private
+      # Overrides for http bindings for the RPC of the mixins for the given package.
+      # Services in the package should use these when creating clients for the mixin services.
+      # @return [::Hash{::Symbol=>::Array<::Gapic::Rest::GrpcTranscoder::HttpBinding>}]
+      config_attr :bindings_override, {}, ::Hash, nil
+
+      # @private
+      def initialize parent_config = nil
+        @parent_config = parent_config unless parent_config.nil?
+
+        yield self if block_given?
+      end
+    end
+  end
+end

data/lib/gapic/rest.rb

@@ -25,6 +25,7 @@ require "gapic/rest/client_stub"
 require "gapic/rest/error"
 require "gapic/rest/faraday_middleware"
 require "gapic/rest/grpc_transcoder"
+require "gapic/rest/http_binding_override_configuration"
 require "gapic/rest/operation"
 require "gapic/rest/paged_enumerable"
 require "gapic/rest/server_stream"