gapic-common 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b3ff94cc009d187db3bbcaa3268adc302baf7918c4027da5b6b7eeb35156f9b
-  data.tar.gz: 48ffb516c68d49a72203f76f99e5bebd6cdd9760d96520f754cb6f51e9b39d52
+  metadata.gz: 4187157fccf115d742dc9e5b074feccf9b65a5dc241bab8214810b4c257288a8
+  data.tar.gz: 7160ec37659fd5bbffc3e517bd40a65295da42fad7743b38869b58d59a34b09f
 SHA512:
-  metadata.gz: f347fc6aae5fba58ab1fba7d090d34f116cbad71d02d8eaa7f7d6b498d830fb6fe0fdfc8fa80c2605a5077a194ee3b15c5ddb6d4d2be22f96f23c7e620afc36f
-  data.tar.gz: dd712b166b3c4c2d5946fc4498fc36cc1758d236a987ff8f9efce7ccf8a8af75b07e447e35f29d98db7c00b42a2e67335ca84a9e55d29aa9606b48fb9a714f11
+  metadata.gz: 71cdc0f8c19c10a51dee060c3048b8b13b8223c0e527e103629058504b60013180e24232ae729014943e1d4b66ba98563796f35558d0d2b5fd955a49f0abf720
+  data.tar.gz: 31b53d85d36746f58b17e778f8fd4b5469a782ae9a68c3847eee309dcb5b2b4ae068785e295763ac17d081518656427408142426cfa7b0f128287599df3e2c47

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 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.

data/README.md

@@ -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.8.0".freeze
+    VERSION = "0.9.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/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)

data/lib/gapic/rest/client_stub.rb

@@ -37,13 +37,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 +115,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.map 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.to_h
+      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..-1]
+        other_parts_pascal = other_parts.map(&:capitalize).join
+        "#{first_part}#{other_parts_pascal}"
+      end
+    end
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-20 00:00:00.000000000 Z
+date: 2022-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -270,6 +270,7 @@ 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
@@ -288,6 +289,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
@@ -310,7 +313,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.5
 signing_key: 
 specification_version: 4
 summary: Common code for GAPIC-generated API clients