gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/model/method/http_annotation.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+# 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/uri_template"
+
+module Gapic
+  module Model
+    module Method
+      ##
+      # The information used in the generation process that
+      # can be gathered from the `google.api.http` annotation.
+      # `google.api.http` is used in two distinct ways:
+      #   - REST libs use it as part of the transcoding to set up the REST call
+      #   - gRPC libs use it as a source of implicit routing headers
+      #
+      class HttpAnnotation
+        ##
+        # The Http bindings found in the annotation
+        # this includes main binding in the annotation itself,
+        # as well as those in the `additional_bindings`.
+        #
+        # @return [Array<HttpBinding>]
+        attr_reader :bindings
+
+        ##
+        # @param proto_http [::Google::Api::HttpRule]
+        #   The base http annotation
+        #
+        def initialize proto_http
+          @bindings = parse_bindings proto_http
+        end
+
+        ##
+        # Whether any implicit routing parameters are present.
+        #
+        # @return [Boolean]
+        def routing_params?
+          routing_params.any?
+        end
+
+        ##
+        # The implicit routing parameter names.
+        #
+        # @return [Array<String>]
+        def routing_params
+          routing_params_with_patterns.map { |param, _| param }
+        end
+
+        ##
+        # The implicit routing parameter names and their corresponding paterns,
+        # including the `*` pattern implied for the named segments
+        # without an explicitly specified pattern.
+        #
+        # @return [Array<Array<String>>]
+        def routing_params_with_patterns
+          bindings.first&.routing_params_with_patterns || []
+        end
+
+        ##
+        # @param proto_method [::Gapic::Schema::Method]
+        #   The proto method this annotation model applies to
+        # @param service_config [::Google::Api::Service]
+        #   The service config that might contain an override for the http annotation.
+        #   This is used for mixins: when generating Operations sublients, and when
+        #   setting up overrides for other mixin clients in the host services's classes.
+        #   For non-mixin service generation
+        #   it is assumed that the service config is merged into protos before generation.
+        #
+        def self.create_with_override proto_method, service_config = nil
+          proto_http = proto_method.http
+
+          http_override = service_config&.http&.rules&.find { |http_rule| http_rule.selector == proto_method.full_name }
+
+          http = http_override || proto_http
+          HttpAnnotation.new http
+        end
+
+        ##
+        # A single Http binding.
+        #
+        class HttpBinding
+          ##
+          # @param binding [::Google::Api::HttpRule]
+          #   The baseline instance of the Http annotation
+          def initialize binding
+            @binding = binding
+          end
+
+          ##
+          # Whether a http verb is present for this method
+          #
+          # @return [Boolean]
+          def verb?
+            !verb.nil?
+          end
+
+          ##
+          # The http verb for this method
+          #
+          # @return [Symbol, nil]
+          def verb
+            verb_path[0] if verb_path
+          end
+
+          ##
+          # Whether a method path is present and non-empty
+          #
+          # @return [Boolean]
+          def path?
+            !path.empty?
+          end
+
+          ##
+          # A method path or an empty string if not present
+          #
+          # @return [String]
+          def path
+            return "" unless verb_path
+            verb_path[1]
+          end
+
+          ##
+          # Whether any routing params are present
+          #
+          # @return [Boolean]
+          def routing_params?
+            routing_params.any?
+          end
+
+          ##
+          # The segment key names and their corresponding paterns,
+          # including the `*` pattern implied for the named segments
+          # without pattern explicitly specified.
+          #
+          # @return [Array<Array<String>>]
+          def routing_params_with_patterns
+            @routing_params_with_patterns ||= begin
+              Gapic::UriTemplate.parse_arguments(path).map do |name, pattern|
+                [name, pattern.empty? ? "*" : pattern]
+              end
+            end
+          end
+
+          ##
+          # The segment key names.
+          #
+          # @return [Array<String>]
+          def routing_params
+            routing_params_with_patterns.map { |param, _| param }
+          end
+
+          ##
+          # Whether method has body specified in proto
+          #
+          # @return [Boolean]
+          def body?
+            !body.empty?
+          end
+
+          ##
+          # The body specified for the given method in proto
+          # or an empty string if not specified
+          #
+          # @return [String]
+          def body
+            @binding&.body || ""
+          end
+
+          private
+
+          ##
+          # The combination of verb and path found in the http annotation
+          # (or Nil if the annotation is Nil).
+          #
+          # @return [Array<Symbol, String>, Nil]
+          def verb_path
+            return nil if @binding.nil?
+
+            {
+              get:    @binding.get,
+              post:   @binding.post,
+              put:    @binding.put,
+              patch:  @binding.patch,
+              delete: @binding.delete
+            }.find { |_, value| !value.empty? }
+          end
+        end
+
+        private
+
+        ##
+        # Parses http bindings from the `google.api.http` annotation, preserving order.
+        #
+        # @param http [::Google::Api::HttpRule]
+        #   The root instance of the HttpRule to parse.
+        #
+        # @return Array<HttpBinding>
+        #  The parsed bindings.
+        def parse_bindings http
+          return [] if http.nil?
+
+          raw_binds = [http] + http.additional_bindings.to_a
+          raw_binds.map { |raw_bind| HttpBinding.new raw_bind }
+        end
+      end
+    end
+  end
+end

data/lib/gapic/model/method/lro.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# 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 "singleton"
+
+require "gapic/path_pattern"
+
+module Gapic
+  module Model
+    ##
+    # Method-level models
+    #
+    module Method
+      ##
+      # Nonstandard (AIP-151 nonconforming) long-running operation method-level  model
+      #
+      # @!attribute [r] service_full_name
+      #   @return [String] Full grpc name of the provider service for this method's LRO
+      #   e.g. `google.example.LroProvider`
+      #
+      # @!attribute [r] operation_request_fields
+      #   @return [Map<String, String>] Map of the field names of this method's request message
+      #   that should be saved and later used when constructing the LRO polling request.
+      #   The values are the names of the fields in the polling request.
+      #   The semantics are `from -> to`, e.g. `{"foo" => "bar"}` means that
+      #   when constructing a polling request, the following assignment should be carried out:
+      #   `lro_polling_request.bar = this_method_request.foo`.
+      #
+      class NonStandardLro
+        # @return [String]
+        attr_reader :service_full_name
+        # @return [Map<String, String>]
+        attr_reader :operation_request_fields
+
+        ##
+        # @param method [Gapic::Schema::Method]
+        # @param service_full_name [String] Full grpc name of the provider service for this method's LRO
+        def initialize method, service_full_name
+          @service_full_name = service_full_name
+
+          # optionally, there might be things to copy from this method's input object
+          # to the LRO service's input object (`operation_request_field` annotation)
+          ops_request_fields = method.input.fields.find_all do |f|
+            !f.operation_request_field.nil? && !f.operation_request_field.empty?
+          end
+
+          @operation_request_fields = ops_request_fields.to_h do |field|
+            [field.name, field.operation_request_field]
+          end
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          true
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          false
+        end
+      end
+
+      ##
+      # AIP-151 LRO Model
+      #
+      class AipLro
+        include Singleton
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          false
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          true
+        end
+      end
+
+      ##
+      # Method does not represent a long-running operation
+      #
+      class NoLro
+        include Singleton
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          false
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          false
+        end
+      end
+
+      class << self
+        ##
+        # Inspects the method and returns it's long-running operation model
+        #
+        # @param method [Gapic::Schema::Method]
+        # @param api [Gapic::Schema::Api]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Model::Method::NonStandardLro, Gapic::Model::Method::AipLro, Gapic::Model::Method::NoLro]
+        #
+        def parse_lro method, api
+          is_aip_lro = method.output.full_name == "google.longrunning.Operation"
+          return AipLro.instance if is_aip_lro
+
+          # If a method is annotated with operation_service, this is a nonstandard LRO consumer method
+          is_nonstandard_lro = !method.operation_service.nil? && !method.operation_service.empty?
+          if is_nonstandard_lro
+            # LRO service name is given plain, so it has to be in the same package as this method's service
+            service_full_name = (method.address[0..-3] << method.operation_service).join "."
+            ops_service_lro = api.nonstandard_lro_model_for service_full_name
+            unless ops_service_lro.nonstandard_lro?
+              error_text = "A service #{service_full_name} specified as a nonstandard LRO service for " \
+                           "the method #{method.full_name} was not found."
+              raise ModelError, error_text
+            end
+
+            unless method.output.full_name == ops_service_lro.lro_object_full_name
+              error_text = "A service #{service_full_name} specified as a nonstandard LRO service for " \
+                           "the method #{method.full_name} has a different LRO object " \
+                           "(#{ops_service_lro.lro_object_full_name}) from the method's return type " \
+                           "(#{method.output.full_name})."
+              raise ModelError, error_text
+            end
+
+            return NonStandardLro.new method, service_full_name
+          end
+
+          NoLro.instance
+        end
+      end
+    end
+  end
+end

data/lib/gapic/model/method/routing.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+# 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/path_pattern"
+
+module Gapic
+  module Model
+    module Method
+      ##
+      # Routing headers info determined from the proto method
+      #
+      # @!attribute [r] routing
+      #   @return [::Google::Api::RoutingRule] Explicit routing annotation for the Api
+      class Routing
+        attr_reader :routing
+
+        ##
+        # @param routing [::Google::Api::RoutingRule] Explict routing annotation for the Api
+        # @param http [Gapic::Model::Method::HttpAnnotation] Model for the Http annotation
+        #
+        def initialize routing, http
+          @routing = routing
+          @http = http
+        end
+
+        ##
+        # Whether routing parameters are specified
+        #
+        # @return [Boolean]
+        def routing_params?
+          explicit_params? || implicit_params?
+        end
+
+        ##
+        # Whether an explicit routing annotation (`google.api.routing`) is present
+        #
+        # @return [Boolean]
+        def explicit_annotation?
+          !@routing.nil?
+        end
+
+        ##
+        # Whether an annotation that might contain implicit routing (`google.api.http`) is present
+        #
+        # @return [Boolean]
+        def implicit_annotation?
+          !@http.nil?
+        end
+
+        ##
+        # Whether explicit routing parameters are present
+        #
+        # @return [Boolean]
+        def explicit_params?
+          return false unless explicit_annotation?
+
+          explicit_params.any?
+        end
+
+        ##
+        # Explicit routing parameters, if present.
+        # Grouped by the routing key, in order, with the extraction and matching information.
+        #
+        # @return [Hash<String, Array>]
+        def explicit_params
+          all_explicit_params.group_by(&:key).transform_values do |params|
+            params.sort_by(&:order).to_a
+          end
+        end
+
+        ##
+        # Whether implict routing parameters from `google.api.http` annotation are present
+        #
+        # @return [Boolean]
+        def implicit_params?
+          @http.routing_params?
+        end
+
+        ##
+        # Implicit routing parameters.
+        # These strings are both field and routing header key names.
+        #
+        # @return [Array<String>]
+        def implicit_params
+          return {} unless implicit_params?
+          @http.routing_params
+        end
+
+        ##
+        # Full routing parameter information, including parsing order
+        # and matching/extraction patterns and regexes.
+        #
+        # @!attribute [r] order
+        #   @return [Integer] Order of the parameter in the annotation
+        #
+        # @!attribute [r] field
+        #   @return [String] Field to extract the routing header from
+        #
+        # @!attribute [r] raw_template
+        #   @return [String, nil] Raw template as given in the annotation
+        #
+        # @!attribute [r] path_template
+        #   @return [String] 'Processed' template, handling such cases as
+        #      empty or nameless template
+        #
+        # @!attribute [r] key
+        #   @return [String] Name of the key to add to the routing header
+        #
+        # @!attribute [r] value_pattern
+        #   @return [String] The pattern of the value to be extracted
+        #
+        # @!attribute [r] field_pattern
+        #   @return [String] The pattern of the full field (simplified)
+        #      The field as a whole should match this pattern
+        #      This pattern is simplified, stipped of the names of the
+        #      resource id segments.
+        #      (e.g. `collections/{resource_id=foo/*}` => `collections/foo/*`)
+        #
+        # @!attribute [r] field_regex_str
+        #   @return [String] The regex matching the `field_pattern`
+        #      (the regex form of the simplified pattern)
+        #
+        # @!attribute [r] field_full_regex_str
+        #   @return [String] The regex matching the full unsimplified field pattern
+        #      (it will contain the named capture corresponding to the
+        #       resource id segment name)
+        #
+        class RoutingParameter
+          attr_reader :order
+          attr_reader :field
+          attr_reader :raw_template
+          attr_reader :path_template
+          attr_reader :key
+          attr_reader :value_pattern
+          attr_reader :field_pattern
+          attr_reader :field_regex_str
+          attr_reader :field_full_regex_str
+
+          ##
+          # @param routing_parameter [::Google::Api::RoutingParameter]
+          #   Routing parameter annotation
+          #
+          # @param order [Integer]
+          #   Order of this annotation among its peers
+          def initialize routing_parameter, order
+            @order = order
+            @field = routing_parameter.field
+            @raw_template = routing_parameter.path_template
+            @path_template = infer_template @raw_template, @field
+            @path_pattern = Gapic::PathPattern.parse @path_template
+
+            resource_segment = @path_pattern.segments.find(&:resource_id_segment?)
+
+            # Only one segment providing an argument and only one argument in the segment
+            # (no `{foo}~{bar}` segments)
+            valid = @path_pattern.segments.count(&:resource_id_segment?) == 1 &&
+                    resource_segment.arguments.count == 1
+
+            unless valid
+              error_text = create_invalid_error_text @path_pattern, @raw_template
+              raise ModelError, error_text
+            end
+
+            @field_pattern = @path_pattern.simplified_pattern
+            @field_full_regex_str = @path_pattern.to_field_regex_str
+            @field_regex_str = Gapic::PathPattern.parse(@field_pattern).to_field_regex_str
+
+            @key = resource_segment.arguments[0]
+            @value_pattern = resource_segment.resource_patterns[0]
+          end
+
+          ##
+          # Whether pattern matching is not needed
+          # since the patterns allow all strings
+          # @return [Boolean]
+          def pattern_matching_not_needed?
+            field_pattern == "**" && value_pattern == "**"
+          end
+
+          ##
+          # Whether the value to be added to the routing header
+          # is the value of the whole field
+          # @return [Boolean]
+          def value_is_full_field?
+            @path_pattern.segments.count == 1
+          end
+
+          private
+
+          # Converts path template simplified forms into canonical
+          # ResourceId representations by adding a field as a Resource Id
+          # @param template [String]
+          # @param field [String]
+          # @return [String]
+          def infer_template template, field
+            if template.nil? || template.empty?
+              return "{#{field}=**}"
+            end
+
+            if template.strip == "**"
+              return "{#{field}=**}"
+            end
+
+            if template.strip == "*"
+              return "{#{field}=*}"
+            end
+
+            template
+          end
+
+          def create_invalid_error_text path_pattern, raw_template
+            reason = if path_pattern.segments.count(&:resource_id_segment?).zero?
+                       "it contains no ResourceId (e.g. `{foo=*}`) segments"
+                     elsif path_pattern.segments.count(&:resource_id_segment?) > 1
+                       "it contains more than one ResourceId (e.g. `{foo=*}`) segments "
+                     else
+                       "it contains a multivariate ResourceId segment (e.g. `{foo}~{bar}`)"
+                     end
+
+            "A routing header parameter with the path_template #{raw_template}\n is invalid: #{reason}"
+          end
+        end
+
+        private
+
+        # All explicit routing parameters in an array.
+        # @return [Array<RoutingParameter>]
+        def all_explicit_params
+          return [] unless explicit_annotation?
+          @routing.routing_parameters.each_with_index.map { |param, index| RoutingParameter.new param, index }.to_a
+        end
+      end
+    end
+  end
+end