gapic-common 0.7.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb55a8128893e307e6f1237157b9456481ce7aa2e09a6dbeb19786359cf774ef
-  data.tar.gz: 37b93b8e7b2d444679279d6f9e4b87b1ccfc460d4c9fc041ca390a22f115e4f5
+  metadata.gz: 5962314c78d1864ee6b768003c887d15af76619c8644a96392f0931ad6f2712c
+  data.tar.gz: 89920288c50070f089949eb11ff94010a52b69d1919b5e4ab6eb50cd9a3610ad
 SHA512:
-  metadata.gz: b635e99c7a32cd3926e278312103197299a48679ea3d5ce6286ab7e5a5873cbb718106e3e69ac28b33316c5ff61c7b22fe67d5499b62298d1dc75c1f7f70eda6
-  data.tar.gz: 81cefba38844981e6c137aff1d2de3fc5282e77b93c7761d20ae04007e7d46d07529b29fcf8315e98505268d101c500ad8e8d8e3df38fab5e0f4d8edbb914e4d
+  metadata.gz: 02c0113ca2287b79558c698393b3315b85c4359b15b90bf54929ea7e7f04a5189769559a69d22f35cebcedb99d62d1a02b2a7ca16739ea724565ace848a89279
+  data.tar.gz: cf43e6bedb320bc4f91f22e4b0354c87583b92e5734ea4d5d40d280bd9ffeaf0d272eda97e1e9bae2ce7e507e8a56a76c4a5c26ca5156326e7edd1bc88dfc5d9

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Release History
 
+### 0.10.0 (2022-06-20)
+
+#### Features
+
+* Require at least Ruby 2.6
+* Support faraday 2.0
+#### Bug Fixes
+
+* Fix precision issues in protobuf timestamp conversion
+* Fix some Ruby 3.0 keyword argument usage errors
+
+### 0.9.0 (2022-05-18)
+
+#### Features
+
+* add full grpc transcoding to gapic-common
+#### Bug Fixes
+
+* small fixes for combined libraries and testing
+
+### 0.8.0 / 2022-01-20
+
+* Add generic LROs helpers. These are used for the Nonstandard (not conforming to AIP-151) Cloud LROs.
+
 ### 0.7.0 / 2021-08-03
 
 * Require googleauth 0.17 for proper support of JWT credentials with custom scopes

data/README.md

@@ -15,11 +15,11 @@ convenient and idiomatic API surface to callers.
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 2.4+.
+This library is supported on Ruby 2.6+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
-security maintenance, and not end of life. Currently, this means Ruby 2.4 and
+security maintenance, and not end of life. Currently, this means Ruby 2.6 and
 later. Older versions of Ruby _may_ still work, but are unsupported and not
 recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
 about the Ruby support schedule.
@@ -28,7 +28,7 @@ about the Ruby support schedule.
 
 Contributions to this library are always welcome and highly encouraged.
 
-See the [CONTRIBUTING](CONTRIBUTING.md) documentation for more information on how to get started.
+See the {file:CONTRIBUTING.md CONTRIBUTING} documentation for more information on how to get started.
 
 ## Versioning
 

data/lib/gapic/common/error.rb

@@ -0,0 +1,23 @@
+# Copyright 2022 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 "json"
+
+module Gapic
+  module Common
+    # Gapic Common exception class
+    class Error < StandardError
+    end
+  end
+end

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.7.0".freeze
+    VERSION = "0.10.0".freeze
   end
 end

data/lib/gapic/common.rb

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

data/lib/gapic/generic_lro/base_operation.rb

@@ -0,0 +1,38 @@
+# Copyright 2021 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 GenericLRO
+    ##
+    # A base class for the wrappers over the long-running operations.
+    #
+    # @attribute [r] operation
+    #   @return [Object] The wrapped operation object.
+    #
+    class BaseOperation
+      attr_reader :operation
+
+      ##
+      # @private
+      # @param operation [Object] The operation object to be wrapped
+      def initialize operation
+        @operation = operation
+      end
+
+      protected
+
+      attr_writer :operation
+    end
+  end
+end

data/lib/gapic/generic_lro/operation.rb

@@ -0,0 +1,325 @@
+# Copyright 2021 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/generic_lro/base_operation"
+require "gapic/operation/retry_policy"
+
+module Gapic
+  module GenericLRO
+    ##
+    # A class used to wrap the longrunning operation objects, including the nonstandard ones
+    # (`nonstandard` meaning not conforming to the AIP-151).
+    # It provides helper methods to poll and check for status of these operations.
+    #
+    class Operation < Gapic::GenericLRO::BaseOperation
+      ##
+      # @param operation [Object] The long-running operation object that is returned by the initial method call.
+      #
+      # @param client [Object] The client that handles the polling for the longrunning operation.
+      #
+      # @param polling_method_name [String] The name of the methods on the client that polls the longrunning operation.
+      #
+      # @param operation_status_field [String] The name of the `status` field in the underlying long-running operation
+      #   object. The `status` field signals that the operation has finished. It should either contain symbols, and
+      #   be set to `:DONE` when finished or contain a boolean and be set to `true` when finished.
+      #
+      # @param request_values [Map<String, String>] The values that are to be copied from the request that
+      #   triggered the longrunning operation, into the request that polls for the longrunning operation.
+      #   The format is `name of the request field` -> `value`
+      #
+      # @param operation_name_field [String, nil] The name of the `name` field in the underlying long-running operation
+      #   object. Optional.
+      #
+      # @param operation_err_field [String, nil] The name of the `error` field in the underlying long-running operation
+      #   object. The `error` field should be a message-type, and have same semantics as `google.rpc.Status`, including
+      #   an integer `code` subfield, that carries an error code. If the `operation_err_field` field is given,
+      #   the `operation_err_code_field` and `operation_err_msg_field` parameters are ignored. Optional.
+      #
+      # @param operation_err_code_field [String, nil] The name of the `error_code` field in the underlying
+      #   long-running operation object. It is ignored if `operation_err_field` is given. Optional.
+      #
+      # @param operation_err_msg_field [String, nil] The name of the `error_message` field in the underlying
+      #   long-running operation object. It is ignored if `operation_err_field` is given. Optional.
+      #
+      # @param operation_copy_fields [Map<String, String>] The map of the fields that need to be copied from the
+      #   long-running operation object that the polling method returns to the polling request.
+      #   The format is `name of the operation object field` -> `name of the request field` (`from` -> `to`)
+      #
+      # @param options [Gapic::CallOptions] call options for this operation
+      #
+      def initialize operation, client:, polling_method_name:, operation_status_field:,
+                     request_values: {}, operation_name_field: nil, operation_err_field: nil,
+                     operation_err_code_field: nil, operation_err_msg_field: nil, operation_copy_fields: {},
+                     options: {}
+        @client = client
+        @polling_method_name = polling_method_name
+        @operation_status_field = operation_status_field
+
+        @request_values = request_values || {}
+
+        @operation_name_field = operation_name_field
+        @operation_err_field = operation_err_field
+        @operation_err_code_field = operation_err_code_field
+        @operation_err_msg_field = operation_err_msg_field
+
+        @operation_copy_fields = operation_copy_fields || {}
+
+        @on_done_callbacks = []
+        @on_reload_callbacks = []
+        @options = options || {}
+
+        super operation
+      end
+
+      ##
+      # If the operation is done, returns the response. If the operation response is an error, the error will be
+      # returned. Otherwise returns nil.
+      #
+      # @return [Object, nil] The result of the operation or an error.
+      #
+      def results
+        return error if error?
+        return response if response?
+      end
+
+      ##
+      # Returns the name of the operation, if specified.
+      #
+      # @return [String, nil] The name of the operation.
+      #
+      def name
+        return nil if @operation_name_field.nil?
+        operation.send @operation_name_field if operation.respond_to? @operation_name_field
+      end
+
+      ##
+      # Checks if the operation is done. This does not send a new api call, but checks the result of the previous api
+      # call to see if done.
+      #
+      # @return [Boolean] Whether the operation is done.
+      #
+      def done?
+        return status if [true, false].include? status
+
+        status == :DONE
+      end
+
+      ##
+      # Checks if the operation is done and the result is not an error. If the operation is not finished then this will
+      # return false.
+      #
+      # @return [Boolean] Whether a response has been returned.
+      #
+      def response?
+        done? && !error?
+      end
+
+      ##
+      # If the operation is completed successfully, returns the underlying operation object, otherwise returns nil.
+      #
+      # @return [Object, nil] The response of the operation.
+      def response
+        operation if response?
+      end
+
+      ##
+      # Checks if the operation is done and the result is an error. If the operation is not finished then this will
+      # return false.
+      #
+      # @return [Boolean] Whether an error has been returned.
+      #
+      def error?
+        done? && (!err.nil? || !error_code.nil?)
+      end
+
+      ##
+      # If the operation response is an error, the error will be returned, otherwise returns nil.
+      #
+      # @return [Object, nil] The error object.
+      #
+      def error
+        return unless error?
+        err || GenericError.new(error_code, error_msg)
+      end
+
+      ##
+      # Reloads the operation object.
+      #
+      # @param options [Gapic::CallOptions, Hash] The options for making the RPC call. A Hash can be provided
+      # to customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}.
+      #
+      # @return [Gapic::GenericLRO::Operation] Since this method changes internal state, it returns itself.
+      #
+      def reload! options: nil
+        return self if done?
+
+        @on_reload_callbacks.each { |proc| proc.call self }
+
+        request_hash = @request_values.transform_keys(&:to_sym)
+        @operation_copy_fields.each do |field_from, field_to|
+          request_hash[field_to.to_sym] = operation.send field_from.to_s if operation.respond_to? field_from.to_s
+        end
+
+        options = merge_options options, @options
+
+        ops = @client.send @polling_method_name, request_hash, options
+        ops = ops.operation if ops.is_a? Gapic::GenericLRO::BaseOperation
+
+        self.operation = ops
+
+        if done?
+          @on_reload_callbacks.clear
+          @on_done_callbacks.each { |proc| proc.call self }
+          @on_done_callbacks.clear
+        end
+
+        self
+      end
+      alias refresh! reload!
+
+      ##
+      # Blocking method to wait until the operation has completed or the maximum timeout has been reached. Upon
+      # completion, registered callbacks will be called, then - if a block is given - the block will be called.
+      #
+      # @param retry_policy [RetryPolicy, Hash, Proc] The policy for retry. A custom proc that takes the error as an
+      #   argument and blocks can also be provided.
+      #
+      # @yield operation [Gapic::GenericLRO::Operation] Yields the finished Operation.
+      #
+      def wait_until_done! retry_policy: nil
+        retry_policy = ::Gapic::Operation::RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
+        retry_policy ||= ::Gapic::Operation::RetryPolicy.new
+
+        until done?
+          reload!
+          break unless retry_policy.call
+        end
+
+        yield self if block_given?
+
+        self
+      end
+
+      ##
+      # Registers a callback to be run when an operation is being reloaded. If the operation has completed
+      # prior to a call to this function the callback will NOT be called or registered.
+      #
+      # @yield operation [Gapic::Operation] Yields the finished Operation.
+      #
+      def on_reload &block
+        return if done?
+        @on_reload_callbacks.push block
+      end
+
+      ##
+      # Registers a callback to be run when a refreshed operation is marked as done. If the operation has completed
+      # prior to a call to this function the callback will be called instead of registered.
+      #
+      # @yield operation [Gapic::Operation] Yields the finished Operation.
+      #
+      def on_done &block
+        if done?
+          yield self
+        else
+          @on_done_callbacks.push block
+        end
+      end
+
+      private
+
+      ##
+      # @return [String, Boolean, nil] A status, whether operation is Done,
+      #   as either a boolean (`true` === Done) or a symbol (`:DONE` === Done)
+      #
+      def status
+        return nil if @operation_status_field.nil?
+        operation.send @operation_status_field
+      end
+
+      ##
+      # @return [String, nil] An error message if the error message field is specified
+      #
+      def err
+        return nil if @operation_err_field.nil?
+        operation.send @operation_err_field if operation.respond_to? @operation_err_field
+      end
+
+      ##
+      # @return [String, nil] An error code if the error code field is specified
+      #
+      def error_code
+        return nil if @operation_err_code_field.nil?
+        operation.send @operation_err_code_field if operation.respond_to? @operation_err_code_field
+      end
+
+      ##
+      # @return [String, nil] An error message if the error message field is specified
+      #
+      def error_msg
+        return nil if @operation_err_msg_field.nil?
+        operation.send @operation_err_msg_field if operation.respond_to? @operation_err_msg_field
+      end
+
+      ##
+      # Merges options given to the method with a baseline Gapic::Options object
+      #
+      # @param method_opts [Gapic::CallOptions, Hash] The options for making the RPC call given to a method invocation.
+      #   A Hash can be provided to customize the options object, using keys that match the arguments
+      #   for {Gapic::CallOptions.new}.
+      #
+      # @param baseline_opts [Gapic::CallOptions, Hash] The baseline options for making the RPC call.
+      #   A Hash can be provided to customize the options object, using keys that match the arguments
+      #   for {Gapic::CallOptions.new}.
+      #
+      def merge_options method_opts, baseline_opts
+        options = if method_opts.respond_to? :to_h
+                    method_opts.to_h.merge baseline_opts.to_h
+                  else
+                    baseline_opts.to_h
+                  end
+
+        Gapic::CallOptions.new(**options)
+      end
+
+      ##
+      # Represents a generic error that a generic LRO can report
+      #
+      # @!attribute [r] code
+      #   @return [String] An error code
+      #
+      # @!attribute [r] message
+      #   @return [String] An error message
+      #
+      class GenericError
+        attr_accessor :code
+        attr_accessor :message
+
+        ##
+        # @param code [String] An error code
+        # @param message [String] An error message
+        def initialize code, message
+          @code = code
+          @message = message
+        end
+      end
+
+      protected
+
+      ##
+      # @private
+      # @return [Object] The client that handles the polling for the longrunning operation.
+      attr_accessor :client
+    end
+  end
+end

data/lib/gapic/headers.rb

@@ -38,7 +38,7 @@ module Gapic
 
       ruby_version ||= ::RUBY_VERSION
       gax_version  ||= ::Gapic::Common::VERSION
-      grpc_version ||= ::GRPC::VERSION if defined? ::GRPC
+      grpc_version ||= ::GRPC::VERSION if defined? ::GRPC::VERSION
       rest_version ||= ::Faraday::VERSION if defined? ::Faraday
 
       x_goog_api_client_header = ["gl-ruby/#{ruby_version}"]

data/lib/gapic/operation.rb

@@ -64,7 +64,7 @@ module Gapic
   #
   #   # Or block until the operation completes, passing a block to be called
   #   # on completion.
-  #   op.wait_until_done do |operation|
+  #   op.wait_until_done! do |operation|
   #     raise operation.results.message if operation.error?
   #     # process(operation.results)
   #     # process(operation.rmetadata)
@@ -253,7 +253,7 @@ module Gapic
     # @yield operation [Gapic::Operation] Yields the finished Operation.
     #
     def wait_until_done! retry_policy: nil
-      retry_policy = RetryPolicy.new retry_policy if retry_policy.is_a? Hash
+      retry_policy = RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
       retry_policy ||= RetryPolicy.new
 
       until done?

data/lib/gapic/paged_enumerable.rb

@@ -181,8 +181,7 @@ module Gapic
 
       min_repeated_field_number = fields.map(&:number).min
       if min_repeated_field_number != repeated_field.number
-        raise ArgumentError, "#{@response.class} must have one primary repeated field " \
-          "by both position and number"
+        raise ArgumentError, "#{@response.class} must have one primary repeated field by both position and number"
       end
 
       # We have the correct repeated field, save the field's name

data/lib/gapic/protobuf.rb

@@ -134,7 +134,7 @@ module Gapic
     #
     # @return [Time] The converted Time.
     def self.timestamp_to_time timestamp
-      Time.at timestamp.nanos * 10**-9 + timestamp.seconds
+      Time.at timestamp.seconds, timestamp.nanos, :nanosecond
     end
 
     ##

data/lib/gapic/rest/client_stub.rb

@@ -14,6 +14,7 @@
 
 require "googleauth"
 require "gapic/rest/faraday_middleware"
+require "faraday/retry"
 
 module Gapic
   module Rest
@@ -37,13 +38,13 @@ module Gapic
       def initialize endpoint:, credentials:
         @endpoint = endpoint
         @endpoint = "https://#{endpoint}" unless /^https?:/.match? endpoint
-        @endpoint.sub! %r{/$}, ""
+        @endpoint = @endpoint.sub %r{/$}, ""
 
         @credentials = credentials
 
         @connection = Faraday.new url: @endpoint do |conn|
           conn.headers = { "Content-Type" => "application/json" }
-          conn.request :google_authorization, @credentials
+          conn.request :google_authorization, @credentials unless @credentials.is_a? ::Symbol
           conn.request :retry
           conn.response :raise_error
           conn.adapter :net_http
@@ -115,9 +116,8 @@ module Gapic
         make_http_request :put, uri: uri, body: body, params: params, options: options
       end
 
-      protected
-
       ##
+      # @private
       # Sends a http request via Faraday
       # @param verb [Symbol] http verb
       # @param uri [String] uri to send this request to

data/lib/gapic/rest/error.rb

@@ -13,11 +13,12 @@
 # limitations under the License.
 
 require "json"
+require "gapic/common/error"
 
 module Gapic
   module Rest
     # Gapic REST exception class
-    class Error < StandardError
+    class Error < ::Gapic::Common::Error
       # @return [Integer] the http status code for the error
       attr_reader :status_code
 

data/lib/gapic/rest/grpc_transcoder/http_binding.rb

@@ -0,0 +1,66 @@
+# Copyright 2022 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
+    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,
+      # and a body template
+      #
+      # @attribute [r] method
+      #   @return [Symbol] The REST verb for the request.
+      # @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.
+      # @attribute [r] body
+      #   @return [String] The body template for the request.
+      class HttpBinding
+        attr_reader :method
+        attr_reader :template
+        attr_reader :field_bindings
+        attr_reader :body
+
+        def initialize method, template, field_bindings, body
+          @method = method
+          @template = template
+          @field_bindings = field_bindings
+          @body = 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`.
+        # @attribute [r] regex
+        #   @return [Regexp] The regex to match on the bound field's string representation.
+        # @attribute [r] preserve_slashes
+        #   @return [Boolean] Whether the slashes in the field value should be preserved
+        #     (as opposed to percent-escaped)
+        class FieldBinding
+          attr_reader :field_path
+          attr_reader :regex
+          attr_reader :preserve_slashes
+
+          def initialize field_path, regex, preserve_slashes
+            @field_path = field_path
+            @regex = regex
+            @preserve_slashes = preserve_slashes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/rest/grpc_transcoder.rb

@@ -0,0 +1,298 @@
+# Copyright 2022 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/rest/grpc_transcoder/http_binding"
+
+module Gapic
+  module Rest
+    # @private
+    # Transcodes a proto request message into HTTP Rest call components
+    # using a configuration of bindings.
+    # Internal doc go/actools-regapic-grpc-transcoding.
+    class GrpcTranscoder
+      def initialize bindings = nil
+        @bindings = bindings || []
+      end
+
+      ##
+      # @private
+      # Creates a new trascoder that is a copy of this one, but with an additional
+      # binding defined by the parameters.
+      #
+      # @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] 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)]
+      end
+
+      ##
+      # @private
+      # Performs the full grpc transcoding -- creating a REST request from the GRPC request
+      # by matching the http bindings and choosing the last one to match.
+      # From the matching binding and the request the following components of the REST request
+      # are produced:
+      # - A [Symbol] representing the Rest verb (e.g. `:get`)
+      # - Uri [String] (e.g. `books/100:read`)
+      # - Query string params in the form of key-value pairs [Array<Array{String, String}>]
+      #   (e.g. [["foo", "bar"], ["baz", "qux"]])
+      # - Body of the request [String]
+      #
+      # @param request [Object] The GRPC request object
+      #
+      # @return [Array] The components of the transcoded request.
+      def transcode request
+        # Using bindings in reverse here because of the "last one wins" rule
+        @bindings.reverse.each do |http_binding|
+          # The main reason we are using request.to_json here
+          # is that the unset proto3_optional fields will not be
+          # in that JSON, letting us skip the checks that would look like
+          #   `request.respond_to?("has_#{key}?".to_sym) && !request.send("has_#{key}?".to_sym)`
+          # The reason we set emit_defaults: true is to avoid
+          # having to figure out default values for the required
+          # fields at a runtime.
+          #
+          # Make a new one for each binding because extract_scalar_value! is destructive
+          request_hash = JSON.parse request.to_json emit_defaults: true
+
+          uri_values = bind_uri_values! http_binding, request_hash
+          next if uri_values.any? { |_, value| value.nil? }
+
+          if http_binding.body && http_binding.body != "*"
+            # Note that the body template can only point to a top-level field,
+            # so there is no need to split the path.
+            body_binding_camel = camel_name_for http_binding.body
+            next unless request_hash.key? body_binding_camel
+          end
+
+          method = http_binding.method
+          uri = expand_template http_binding.template, uri_values
+          body, query_params = construct_body_query_params http_binding.body, request_hash, request
+
+          return method, uri, query_params, body
+        end
+
+        raise ::Gapic::Common::Error,
+              "Request object does not match any transcoding template. Cannot form a correct REST call."
+      end
+
+      private
+
+      # Binds request values for the uri template expansion.
+      # This method modifies the provided `request_hash` parameter.
+      # Returned values are percent-escaped with slashes potentially preserved.
+      # @param http_binding [Gapic::Rest::GrpcTranscoder::HttpBinding]
+      #   Http binding to get the field bindings from.
+      # @param request_hash [Hash]
+      #   A hash of the GRPC request with the unset proto3_optional fields pre-removed.
+      #   !!! This hash will be modified. The bound fields will be deleted. !!!
+      # @return [Hash{String, String}]
+      #   Name to value hash of the variables for the uri template expansion.
+      #   The values are percent-escaped with slashes potentially preserved.
+      def bind_uri_values! http_binding, request_hash
+        http_binding.field_bindings.to_h do |field_binding|
+          field_path_camel = field_binding.field_path.split(".").map { |part| camel_name_for part }.join(".")
+          field_value = extract_scalar_value! request_hash, field_path_camel, field_binding.regex
+
+          if field_value
+            field_value = if field_binding.preserve_slashes
+                            field_value.split("/").map { |segment| percent_escape(segment) }.join("/")
+                          else
+                            percent_escape field_value
+                          end
+          end
+
+          [field_binding.field_path, field_value]
+        end
+      end
+
+      # Percent-escapes a string.
+      # @param str [String] String to escape.
+      # @return str [String] Escaped string.
+      def percent_escape str
+        # `+` to represent spaces is not currently supported in Showcase server.
+        CGI.escape(str).gsub("+", "%20")
+      end
+
+      # Constructs body and query parameters for the Rest request.
+      # @param body_template [String, Nil] The template for the body, e.g. `*`.
+      # @param request_hash_without_uri [Hash]
+      #   The hash of the GRPC request with the unset proto3_optional fields
+      #   and the values that are bound to URI removed.
+      # @param request [Object] The GRPC request.
+      # @return [Array{String, Array}] A pair of body and query parameters.
+      def construct_body_query_params body_template, request_hash_without_uri, request
+        body = ""
+        query_params = []
+
+        if body_template == "*"
+          body = request_hash_without_uri.to_json
+        elsif body_template && body_template != ""
+          # Using a `request` here instead of `request_hash_without_uri`
+          # because if `body` is bound to a message field,
+          # the fields of the corresponding sub-message,
+          # which were used when constructing the URI, should not be deleted
+          # (as opposed to the case when `body` is `*`).
+          #
+          # The `request_hash_without_uri` at this point was mutated to delete these fields.
+          #
+          # Note that the body template can only point to a top-level field
+          request_hash_without_uri.delete camel_name_for body_template
+          body = request.send(body_template.to_sym).to_json(emit_defaults: true)
+          query_params = build_query_params request_hash_without_uri
+        else
+          query_params = build_query_params request_hash_without_uri
+        end
+
+        [body, query_params]
+      end
+
+      # Builds query params for the REST request.
+      # This function calls itself recursively for every submessage field, passing
+      # the submessage hash as request and the path to the submessage field as a prefix.
+      # @param request_hash [Hash]
+      #   A hash of the GRPC request or the sub-request with the unset
+      #   proto3_optional fields and the values that are bound to URI removed.
+      # @param prefix [String] A prefix to form the correct query parameter key.
+      # @return [Array{String, String}] Query string params as key-value pairs.
+      def build_query_params request_hash, prefix = ""
+        result = []
+        request_hash.each do |key, value|
+          full_key_name = "#{prefix}#{key}"
+          case value
+          when ::Array
+            value.each do |_val|
+              result.push "#{full_key_name}=#{value}"
+            end
+          when ::Hash
+            result += build_query_params value, "#{full_key_name}."
+          else
+            result.push "#{full_key_name}=#{value}" unless value.nil?
+          end
+        end
+
+        result
+      end
+
+      # Extracts a non-submessage non-array value from the request hash by path
+      # if its string representation matches the regex provided.
+      # This method modifies the provided `request_hash` parameter.
+      # Returns nil if:
+      # - the field is not found
+      # - the field is a Message or an array,
+      # - the regex does not match
+      # @param request_hash [Hash]
+      #   A hash of the GRPC request or the sub-request with the unset
+      #   proto3_optional fields removed.
+      #   !!! This hash will be modified. The extracted field will be deleted. !!!
+      # @param field_path [String] A path to the field, e.g. `foo.bar`.
+      # @param regex [Regexp] A regex to match on the field's string representation.
+      # @return [String, Nil] the field's string representation or nil.
+      def extract_scalar_value! request_hash, field_path, regex
+        parent, name = find_value request_hash, field_path
+        value = parent.delete name
+
+        # Covers the case where in `foo.bar.baz`, `baz` is still a submessage or an array.
+        return nil if value.is_a?(::Hash) || value.is_a?(::Array)
+        return value.to_s if value.to_s =~ regex
+      end
+
+      # Finds a value in the hash by path.
+      # @param request_hash [Hash] A hash of the GRPC request or the sub-request.
+      # @param field_path [String] A path of the field, e.g. `foo.bar`.
+      def find_value request_hash, field_path
+        path_split = field_path.split "."
+
+        value_parent = nil
+        value = request_hash
+        last_field_name = nil
+        path_split.each do |curr_field|
+          # Covers the case when in `foo.bar.baz`, `bar` is not a submessage field
+          # or is a submessage field initialized with nil.
+          return {}, nil unless value.is_a? ::Hash
+          value_parent = value
+          last_field_name = curr_field
+          value = value[curr_field]
+        end
+
+        [value_parent, last_field_name]
+      end
+
+      # Performs variable expansion on the template using the bindings provided
+      # @param template [String] The Uri template.
+      # @param bindings [Hash{String, String}]
+      #   The variable bindings. The values should be percent-escaped
+      #   (with slashes potentially preserved).
+      # @return [String] The expanded template.
+      def expand_template template, bindings
+        result = template
+        bindings.each do |name, value|
+          result = result.gsub "{#{name}}", value
+        end
+        result
+      end
+
+      ##
+      # Converts a snake_case parameter name into camelCase for query string parameters.
+      # @param attr_name [String] Parameter name.
+      # @return [String] Camel-cased parameter name.
+      def camel_name_for attr_name
+        parts = attr_name.split "_"
+        first_part = parts[0]
+        other_parts = parts[1..]
+        other_parts_pascal = other_parts.map(&:capitalize).join
+        "#{first_part}#{other_parts_pascal}"
+      end
+    end
+  end
+end

data/lib/gapic/rest/operation.rb

@@ -12,22 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/generic_lro/base_operation"
+
 module Gapic
   module Rest
     ##
-    # A base class for the wrappers over the long-running operations to the response of a REST LRO method.
-    #
-    # @attribute [r] operation
-    #   @return [Object] The wrapped operation object.
-    class BaseOperation
-      attr_reader :operation
-
-      ##
-      # @private
-      # @param operation [Object] The wrapped operation object.
-      def initialize operation
-        @operation = operation
-      end
-    end
+    # This alias is left here for the backwards compatibility purposes.
+    # Rest LROs now use the same GenericLRO base as the GRPC LROs.
+    # @deprecated Use {Gapic::GenericLRO::BaseOperation} instead.
+    BaseOperation = Gapic::GenericLRO::BaseOperation
   end
 end

data/lib/gapic/rest.rb

@@ -24,6 +24,7 @@ require "gapic/protobuf"
 require "gapic/rest/client_stub"
 require "gapic/rest/error"
 require "gapic/rest/faraday_middleware"
+require "gapic/rest/grpc_transcoder"
 require "gapic/rest/operation"
 require "gapic/rest/paged_enumerable"
 require "json"

metadata

@@ -1,56 +1,62 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-05 00:00:00.000000000 Z
+date: 2022-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 3.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.a
 - !ruby/object:Gem::Dependency
-  name: googleapis-common-protos
+  name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.11
+        version: '1.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.a
+        version: 3.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.11
+        version: '1.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.a
+        version: 3.a
 - !ruby/object:Gem::Dependency
-  name: googleapis-common-protos-types
+  name: googleapis-common-protos
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.6
+        version: 1.3.12
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -60,17 +66,17 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.6
+        version: 1.3.12
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
 - !ruby/object:Gem::Dependency
-  name: googleauth
+  name: googleapis-common-protos-types
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -80,10 +86,24 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.3.1
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
@@ -132,28 +152,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.25.1
+        version: 1.26.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.25.1
+        version: 1.26.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -196,6 +216,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -256,9 +290,12 @@ files:
 - lib/gapic/call_options.rb
 - lib/gapic/call_options/retry_policy.rb
 - lib/gapic/common.rb
+- lib/gapic/common/error.rb
 - lib/gapic/common/version.rb
 - lib/gapic/config.rb
 - lib/gapic/config/method.rb
+- lib/gapic/generic_lro/base_operation.rb
+- lib/gapic/generic_lro/operation.rb
 - lib/gapic/grpc.rb
 - lib/gapic/grpc/service_stub.rb
 - lib/gapic/grpc/service_stub/rpc_call.rb
@@ -272,6 +309,8 @@ files:
 - lib/gapic/rest/client_stub.rb
 - lib/gapic/rest/error.rb
 - lib/gapic/rest/faraday_middleware.rb
+- lib/gapic/rest/grpc_transcoder.rb
+- lib/gapic/rest/grpc_transcoder/http_binding.rb
 - lib/gapic/rest/operation.rb
 - lib/gapic/rest/paged_enumerable.rb
 - lib/gapic/stream_input.rb
@@ -287,14 +326,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.14
 signing_key: 
 specification_version: 4
 summary: Common code for GAPIC-generated API clients