gapic-common 0.15.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5902b53f0f5a46b4682ff855fb89a6a3162af38523fa273f273abeeeed0d3a3d
-  data.tar.gz: a1e9bb69d31725768f00b152efcaf29042657fbb304c2ba2f25de485831fe187
+  metadata.gz: 609c468f1e8a7e60f8b4ba911901dd99f8816cb367371dd5479d79dcd06bca82
+  data.tar.gz: 23a01faa58af17577e262852d434a6746b33f090247b05ea9dc8ce2ae07772bb
 SHA512:
-  metadata.gz: 84d77cc3d943714b8a3578ecabf3fea3a321dfe0929ee108233d4dcd8fede90a37be21a81e121142739aa3dca102ffff0826a003906bec16f03749beddf59ab2
-  data.tar.gz: 27e2815be724399a4c01ca1d47c7b2e9291ee4583018251f45a2a0162f1d5cd8298d0ca3b8a4cf90fc4ba6f2e410240439e61a22a66fbeae89c5a3e9dc223879
+  metadata.gz: 7fc2a7f8c0fdcc79434966a1e6431c29d957dd1a646cae5a8cd023da1320b7f5253b69f4edd915c98656b12e681aac66bf11713c2bb47f0482798601635ba948
+  data.tar.gz: 49a6c6aaa7fca24979d8707bc7a6ba2b8daed51951539d2235be32f932e73a02fa4cd8d7699f811b358bd216ca99ffbe63dab0469196b1815cdf37eb6ad4055c

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Release History
 
+### 0.18.0 (2023-02-27)
+
+#### Features
+
+* add alias for details field in Rest Error ([#928](https://github.com/googleapis/gapic-generator-ruby/issues/928)) 
+
+### 0.17.1 (2023-02-09)
+
+#### Bug Fixes
+
+* add new class to the rest imports ([#913](https://github.com/googleapis/gapic-generator-ruby/issues/913)) 
+
+### 0.17.0 (2023-02-09)
+
+#### Features
+
+* add a transport operation class in Rest ([#911](https://github.com/googleapis/gapic-generator-ruby/issues/911)) 
+
+### 0.16.0 (2022-12-12)
+
+#### Features
+
+* custom regapic exception wrapping ([#866](https://github.com/googleapis/gapic-generator-ruby/issues/866)) 
+
+### 0.15.1 (2022-11-18)
+
+#### Bug Fixes
+
+* Fixed uninitialized constant when checking retry policy for a REST call ([#857](https://github.com/googleapis/gapic-generator-ruby/issues/857)) 
+
 ### 0.15.0 (2022-11-17)
 
 #### Features

data/lib/gapic/call_options/error_codes.rb

@@ -45,26 +45,29 @@ module Gapic
       # @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.
-        {
-          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
-        }[http_error_code] || 2 # UnknownError
+        HTTP_GRPC_CODE_MAP[http_error_code] || 2 # UnknownError
       end
     end
   end

data/lib/gapic/call_options/retry_policy.rb

@@ -106,7 +106,7 @@ module Gapic
       private
 
       def retry? error
-        (error.is_a?(::GRPC::BadStatus) && retry_codes.include?(error.code)) ||
+        (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

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.15.0".freeze
+    VERSION = "0.18.0".freeze
   end
 end

data/lib/gapic/rest/client_stub.rb

@@ -34,9 +34,15 @@ module Gapic
       #   (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`.
+      #
       # @yield [Faraday::Connection]
       #
-      def initialize endpoint:, credentials:, numeric_enums: false
+      def initialize endpoint:, credentials:, numeric_enums: false, raise_faraday_errors: true
         @endpoint = endpoint
         @endpoint = "https://#{endpoint}" unless /^https?:/.match? endpoint
         @endpoint = @endpoint.sub %r{/$}, ""
@@ -44,6 +50,8 @@ module Gapic
         @credentials = credentials
         @numeric_enums = numeric_enums
 
+        @raise_faraday_errors = raise_faraday_errors
+
         @connection = Faraday.new url: @endpoint do |conn|
           conn.headers = { "Content-Type" => "application/json" }
           conn.request :google_authorization, @credentials unless @credentials.is_a? ::Symbol
@@ -137,35 +145,31 @@ module Gapic
         next_timeout = get_timeout deadline
 
         begin
-          base_make_http_request(verb,
-                                 uri: uri,
-                                 body: body,
-                                 params: params,
-                                 metadata: options.metadata,
+          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)
+        rescue ::Faraday::TimeoutError => e
+          raise if @raise_faraday_errors
+          raise Gapic::Rest::DeadlineExceededError.wrap_faraday_error e, root_cause: retried_exception
         rescue ::Faraday::Error => e
           next_timeout = get_timeout deadline
 
-          if next_timeout&.positive? && options.retry_policy.call(e)
+          if check_retry?(next_timeout) && options.retry_policy.call(e)
             retried_exception = e
             retry
           end
 
-          unless next_timeout&.positive?
-            raise Gapic::GRPC::DeadlineExceededError.new e.message, root_cause: retried_exception
-          end
-
-          raise e
+          raise if @raise_faraday_errors
+          raise ::Gapic::Rest::Error.wrap_faraday_error e
         end
       end
 
-      private
-
       ##
       # @private
       # Sends a http request via Faraday
+      #
       # @param verb [Symbol] http verb
       # @param uri [String] uri to send this request to
       # @param body [String, nil] a body to send with the request, nil for requests without a body
@@ -174,7 +178,8 @@ 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 base_make_http_request verb, uri:, body:, params:, metadata:, timeout:, is_server_streaming: false
+      def base_make_http_request verb:, uri:, body:, params:, metadata:,
+                                 timeout:, is_server_streaming: false
         if @numeric_enums && (!params.key?("$alt") || params["$alt"] == "json")
           params = params.merge({ "$alt" => "json;enum-encoding=int" })
         end
@@ -192,6 +197,14 @@ module Gapic
         end
       end
 
+      private
+
+      ##
+      # Calculates deadline
+      #
+      # @param options [Gapic::CallOptions] call options for this call
+      #
+      # @return [Numeric, nil] Deadline against a POSIX clock_gettime()
       def calculate_deadline options
         return if options.timeout.nil?
         return if options.timeout.negative?
@@ -199,10 +212,28 @@ module Gapic
         Process.clock_gettime(Process::CLOCK_MONOTONIC) + options.timeout
       end
 
+      ##
+      # Calculates timeout (seconds) to use as a Faraday timeout
+      #
+      # @param deadline [Numeric, nil] deadline
+      #
+      # @return [Numeric, nil] Timeout (seconds)
       def get_timeout deadline
         return if deadline.nil?
         deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
+
+      ##
+      # Whether the timeout should be retried
+      #
+      # @param timeout [Numeric, nil]
+      #
+      # @return [Boolean] whether the timeout should be retried
+      def check_retry? timeout
+        return true if timeout.nil?
+
+        timeout.positive?
+      end
     end
   end
 end

data/lib/gapic/rest/error.rb

@@ -14,6 +14,9 @@
 
 require "json"
 require "gapic/common/error"
+require "google/protobuf/well_known_types"
+# Not technically required but GRPC counterpart loads it and so should we for test parity
+require "google/rpc/error_details_pb"
 
 module Gapic
   module Rest
@@ -25,6 +28,8 @@ module Gapic
       attr_reader :status
       # @return [Object, nil] the details as parsed from the response body
       attr_reader :details
+      # The Cloud error wrapper expect to see a `status_details` property
+      alias status_details details
       # @return [Object, nil] the headers of the REST error
       attr_reader :headers
       # The Cloud error wrapper expect to see a `header` property
@@ -55,6 +60,17 @@ module Gapic
         #
         # @return [ Gapic::Rest::Error]
         def wrap_faraday_error err
+          message, status_code, status, details, headers = parse_faraday_error err
+          Gapic::Rest::Error.new message, status_code, status: status, details: details, headers: headers
+        end
+
+        ##
+        # @private
+        # Tries to get the error information from Faraday error
+        #
+        # @param err [Faraday::Error] the Faraday error to extract information from
+        # @return [Array(String, String, String, String, String)]
+        def parse_faraday_error err
           message = err.message
           status_code = err.response_status
           status = nil
@@ -67,7 +83,7 @@ module Gapic
             status_code = code unless code.nil?
           end
 
-          Gapic::Rest::Error.new message, status_code, status: status, details: details, headers: headers
+          [message, status_code, status, details, headers]
         end
 
         private
@@ -133,5 +149,62 @@ module Gapic
         end
       end
     end
+
+    ##
+    # An error class that represents DeadlineExceeded error for Rest
+    # with an optional retry root cause.
+    #
+    # If the deadline for making a call was exceeded during the rest calls,
+    # this exception is thrown wrapping Faraday::TimeoutError.
+    #
+    # If there were other exceptions retried before that, the last one will be
+    # saved as a "root_cause".
+    #
+    # @!attribute [r] root_cause
+    #   @return [Object, nil] The exception that was being retried
+    #     when the Faraday::TimeoutError error occured.
+    #
+    class DeadlineExceededError < Error
+      attr_reader :root_cause
+
+      ##
+      # @private
+      # @param message [String, nil] error message
+      # @param status_code [Integer, nil] HTTP status code of this error
+      # @param status [String, nil] The text representation of status as parsed from the response body
+      # @param details [Object, nil] Details data of this error
+      # @param headers [Object, nil] Http headers data of this error
+      # @param root_cause [Object, nil] The exception that was being retried
+      #   when the Faraday::TimeoutError occured.
+      #
+      def initialize message, status_code, status: nil, details: nil, headers: nil, root_cause: nil
+        super message, status_code, status: status, details: details, headers: headers
+        @root_cause = root_cause
+      end
+
+      class << self
+        ##
+        # @private
+        # This creates a new error message wrapping the Faraday's one. Additionally
+        # it tries to parse and set a detailed message and an error code from
+        # from the Google Cloud's response body
+        #
+        # @param err [Faraday::TimeoutError] the Faraday error to wrap
+        #
+        # @param root_cause [Object, nil] The exception that was being retried
+        #   when the Faraday::TimeoutError occured.
+        #
+        # @return [ Gapic::Rest::DeadlineExceededError]
+        def wrap_faraday_error err, root_cause: nil
+          message, status_code, status, details, headers = parse_faraday_error err
+          Gapic::Rest::DeadlineExceededError.new message,
+                                                 status_code,
+                                                 status: status,
+                                                 details: details,
+                                                 headers: headers,
+                                                 root_cause: root_cause
+        end
+      end
+    end
   end
 end

data/lib/gapic/rest/server_stream.rb

@@ -50,7 +50,7 @@ module Gapic
         return enum_for :each unless block_given?
 
         loop do
-          while @ready_objs.length.zero?
+          while @ready_objs.empty?
             begin
               chunk = @json_enumerator.next
               next unless chunk

data/lib/gapic/rest/transport_operation.rb

@@ -0,0 +1,38 @@
+# Copyright 2023 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 Rest
+    ##
+    # Surfaces information about the active call
+    # from the underlying transport library.
+    #
+    class TransportOperation
+      ##
+      # @private
+      # The underlying transport's library object that describes the active call, if any.
+      # It is not guaranteed to be any specific type, and its value is not guarateed to be stable.
+      # @return [::Object, nil, ::Faraday::Response]
+      attr_reader :underlying_op
+
+      ##
+      # @private
+      # @param request [::Object, nil, ::Faraday::Response]
+      #   The underlying transport's library object that describes the active call, if any.
+      def initialize underlying_op
+        @underlying_op = underlying_op
+      end
+    end
+  end
+end

data/lib/gapic/rest.rb

@@ -29,4 +29,5 @@ require "gapic/rest/operation"
 require "gapic/rest/paged_enumerable"
 require "gapic/rest/server_stream"
 require "gapic/rest/threaded_enumerator"
+require "gapic/rest/transport_operation"
 require "json"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-18 00:00:00.000000000 Z
+date: 2023-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -317,6 +317,7 @@ files:
 - lib/gapic/rest/paged_enumerable.rb
 - lib/gapic/rest/server_stream.rb
 - lib/gapic/rest/threaded_enumerator.rb
+- lib/gapic/rest/transport_operation.rb
 - lib/gapic/stream_input.rb
 homepage: https://github.com/googleapis/gapic-generator-ruby
 licenses:
@@ -337,7 +338,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.14
+rubygems_version: 3.4.2
 signing_key: 
 specification_version: 4
 summary: Common code for GAPIC-generated API clients