gapic-common 0.14.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea69666c3f5162e9949825974c29af5ca636527a25e67d0ce034c2bb6c39b201
-  data.tar.gz: 68df57288727233549f5ababcd296b545bd4a1e10bdc29caae1891019c3995ba
+  metadata.gz: 508b67fe556c18e32cab88da23a0097e425df549e288b72fec7d4a891b6c06f5
+  data.tar.gz: 29bbc436a310b93f2f043502344783835ba25ed91d5ac8523c190da0ecd019b4
 SHA512:
-  metadata.gz: 8c83345123a2739aa89f31aefb00288c8ae7e831af653a654872601a2e646ddd9b7d7356aa82e403b5c2571cae2bd437fbf4ff8c38e70822cfc18c89ea89f883
-  data.tar.gz: a95b2ec76934bec8140e6c65b627644833143f313117cd86d867dcda0e3bfdf00407f86c8b33d0f52165de5549c3207119a8b5b506cba5b9da8c41a58846cf78
+  metadata.gz: 34e4be1fc16714c9afc6bd0d9ca832ae7409521d0ec9f10c41860e817c8ee28599d6853a0c84a780dc3e3fc19d33882068d613f2691d6ee99392b68f2c5dbe04
+  data.tar.gz: 6f130dd5c05535efc27e67f51a6b593082519a04601d69111db010d097e7c150501e9cee2845d4937c175fce79451f413b5e125e9f74d01f66634d74d6b9604a

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Release History
 
+### 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
+
+* retry policy now works for REST calls
+
 ### 0.14.0 (2022-11-08)
 
 #### Features

data/lib/gapic/call_options/error_codes.rb

@@ -0,0 +1,74 @@
+# Copyright 2019 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
+  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

data/lib/gapic/call_options/retry_policy.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/call_options/error_codes"
+
 module Gapic
   class CallOptions
     ##
@@ -101,38 +103,12 @@ module Gapic
         [retry_codes, initial_delay, multiplier, max_delay].hash
       end
 
-      # @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.each_with_object({}) do |(str, num), hash|
-        hash[str] = num
-      end.freeze
-
       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
 
       def delay!
@@ -145,7 +121,7 @@ module Gapic
         Array(input_codes).map do |obj|
           case obj
           when String
-            ERROR_STRING_MAPPING[obj]
+            ErrorCodes::ERROR_STRING_MAPPING[obj]
           when Integer
             obj
           end

data/lib/gapic/call_options.rb

@@ -12,6 +12,7 @@
 # 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"
 
 module Gapic

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.14.0".freeze
+    VERSION = "0.17.1".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
@@ -125,21 +133,62 @@ module Gapic
       # @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
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
-      #     to the REST call. Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied to the REST call.
       # @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
+      def make_http_request verb, uri:, body:, params:, options:, is_server_streaming: false, &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
+
+        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)
+        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 check_retry?(next_timeout) && options.retry_policy.call(e)
+            retried_exception = e
+            retry
+          end
+
+          raise if @raise_faraday_errors
+          raise ::Gapic::Rest::Error.wrap_faraday_error e
+        end
+      end
+
+      ##
+      # @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
+      # @param params [Hash] query string parameters for the request
+      # @param metadata [Hash] additional headers for the request
+      # @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
         if @numeric_enums && (!params.key?("$alt") || params["$alt"] == "json")
           params = params.merge({ "$alt" => "json;enum-encoding=int" })
         end
-        options = ::Gapic::CallOptions.new(**options.to_h) unless options.is_a? ::Gapic::CallOptions
+
         @connection.send verb, uri do |req|
           req.params = params if params.any?
           req.body = body unless body.nil?
-          req.headers = req.headers.merge options.metadata
-          req.options.timeout = options.timeout if options.timeout&.positive?
+          req.headers = req.headers.merge metadata
+          req.options.timeout = timeout if timeout&.positive?
           if is_server_streaming
             req.options.on_data = proc do |chunk, _overall_received_bytes|
               yield chunk
@@ -147,6 +196,44 @@ module Gapic
           end
         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?
+
+        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

@@ -55,6 +55,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 +78,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 +144,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/grpc_transcoder/http_binding.rb

@@ -15,6 +15,7 @@
 module Gapic
   module Rest
     class GrpcTranscoder
+      ##
       # @private
       # A single binding for GRPC-REST transcoding of a request
       # It includes a uri template with bound field parameters, a HTTP method type,
@@ -25,7 +26,8 @@ module Gapic
       # @attribute [r] template
       #   @return [String] The URI template for the request.
       # @attribute [r] field_bindings
-      #   @return [Array<FieldBinding>] The field bindings for the URI template variables.
+      #   @return [Array<Gapic::Rest::GrpcTranscoder::HttpBinding::FieldBinding>]
+      #     The field bindings for the URI template variables.
       # @attribute [r] body
       #   @return [String] The body template for the request.
       class HttpBinding
@@ -41,6 +43,57 @@ module Gapic
           @body = body
         end
 
+        ##
+        # @private
+        # Creates a new HttpBinding.
+        #
+        # @param uri_method [Symbol] The rest verb for the binding.
+        # @param uri_template [String] The string with uri template for the binding.
+        #   This string will be expanded with the parameters from variable bindings.
+        # @param matches [Array<Array>] Variable bindings in an array. Every element
+        #   of the array is an [Array] triplet, where:
+        #   - the first element is a [String] field path (e.g. `foo.bar`) in the request
+        #     to bind to
+        #   - the second element is a [Regexp] to match the field value
+        #   - the third element is a [Boolean] whether the slashes in the field value
+        #     should be preserved (as opposed to escaped) when expanding the uri template.
+        # @param body [String, Nil] The body template, e.g. `*` or a field path.
+        #
+        # @return [Gapic::Rest::GrpcTranscoder::HttpBinding] The new binding.
+        def self.create_with_validation uri_method:, uri_template:, matches: [], body: nil
+          template = uri_template
+
+          matches.each do |name, _regex, _preserve_slashes|
+            unless uri_template =~ /({#{Regexp.quote name}})/
+              err_msg = "Binding configuration is incorrect: missing parameter in the URI template.\n" \
+                        "Parameter `#{name}` is specified for matching but there is no corresponding parameter " \
+                        "`{#{name}}` in the URI template."
+              raise ::Gapic::Common::Error, err_msg
+            end
+
+            template = template.gsub "{#{name}}", ""
+          end
+
+          if template =~ /{([a-zA-Z_.]+)}/
+            err_name = Regexp.last_match[1]
+            err_msg = "Binding configuration is incorrect: missing match configuration.\n" \
+                      "Parameter `{#{err_name}}` is specified in the URI template but there is no " \
+                      "corresponding match configuration for `#{err_name}`."
+            raise ::Gapic::Common::Error, err_msg
+          end
+
+          if body&.include? "."
+            raise ::Gapic::Common::Error,
+                  "Provided body template `#{body}` points to a field in a sub-message. This is not supported."
+          end
+
+          field_bindings = matches.map do |name, regex, preserve_slashes|
+            HttpBinding::FieldBinding.new name, regex, preserve_slashes
+          end
+
+          HttpBinding.new uri_method, uri_template, field_bindings, body
+        end
+
         # A single binding for a field of a request message.
         # @attribute [r] field_path
         #   @return [String] The path of the bound field, e.g. `foo.bar`.

data/lib/gapic/rest/grpc_transcoder.rb

@@ -44,36 +44,11 @@ module Gapic
       #
       # @return [Gapic::Rest::GrpcTranscoder] The updated transcoder.
       def with_bindings uri_method:, uri_template:, matches: [], body: nil
-        template = uri_template
-
-        matches.each do |name, _regex, _preserve_slashes|
-          unless uri_template =~ /({#{Regexp.quote name}})/
-            err_msg = "Binding configuration is incorrect: missing parameter in the URI template.\n" \
-                      "Parameter `#{name}` is specified for matching but there is no corresponding parameter " \
-                      "`{#{name}}` in the URI template."
-            raise ::Gapic::Common::Error, err_msg
-          end
-
-          template = template.gsub "{#{name}}", ""
-        end
-
-        if template =~ /{([a-zA-Z_.]+)}/
-          err_name = Regexp.last_match[1]
-          err_msg = "Binding configuration is incorrect: missing match configuration.\n" \
-                    "Parameter `{#{err_name}}` is specified in the URI template but there is no " \
-                    "corresponding match configuration for `#{err_name}`."
-          raise ::Gapic::Common::Error, err_msg
-        end
-
-        if body&.include? "."
-          raise ::Gapic::Common::Error,
-                "Provided body template `#{body}` points to a field in a sub-message. This is not supported."
-        end
-
-        field_bindings = matches.map do |name, regex, preserve_slashes|
-          HttpBinding::FieldBinding.new name, regex, preserve_slashes
-        end
-        GrpcTranscoder.new @bindings + [HttpBinding.new(uri_method, uri_template, field_bindings, body)]
+        binding = HttpBinding.create_with_validation(uri_method: uri_method,
+                                                     uri_template: uri_template,
+                                                     matches: matches,
+                                                     body: body)
+        GrpcTranscoder.new @bindings + [binding]
       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.14.0
+  version: 0.17.1
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-08 00:00:00.000000000 Z
+date: 2023-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -288,6 +288,7 @@ files:
 - RELEASING.md
 - lib/gapic-common.rb
 - lib/gapic/call_options.rb
+- lib/gapic/call_options/error_codes.rb
 - lib/gapic/call_options/retry_policy.rb
 - lib/gapic/common.rb
 - lib/gapic/common/error.rb
@@ -316,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:
@@ -336,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