gapic-generator 0.9.1 → 0.11.0

data/lib/gapic/model/service/nonstandard_lro_provider.rb

@@ -0,0 +1,293 @@
+# 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.
+
+module Gapic
+  module Model
+    ##
+    # Service-level models
+    #
+    module Service
+      ##
+      # Nonstandard (AIP-151 nonconforming) long-running operation service-level model
+      # for the services that are LRO providers (contain polling methods for long-running operations)
+      #
+      # @!attribute [r] service_full_name
+      #   @return [String] Full grpc name of this service. E.g. `google.example.LroProvider`.
+      #
+      # @!attribute [r] polling_method_name
+      #   @return [String] Name of the method that is used to poll for LROs. E.g. `Poll`
+      #
+      # @!attribute [r] lro_object_full_name
+      #   @return [String] Full grpc name of the object that is returned by the polling method.
+      #   E.g. `google.cloud.compute.v1.Operation`
+      #
+      # @!attribute [r] operation_status_field
+      #   @return [String] In the Operation message for this service, the name of the `status` field.
+      #   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.
+      #
+      # @!attribute [r] operation_name_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `name` field.
+      #
+      # @!attribute [r] operation_err_code_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `error code` field.
+      #
+      # @!attribute [r] operation_err_msg_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `error message` field.
+      #
+      # @!attribute [r] operation_response_fields
+      #   @return [Hash<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 polling request field` (`from -> to`).
+      #   E.g. `{"foo" => "bar"}` means that when constructing a polling request,
+      #   the following assignment should be carried out:
+      #   `lro_polling_request.bar = operation_object.foo`.
+      #
+      class NonstandardLroProvider
+        attr_reader :service_full_name
+        attr_reader :polling_method_name
+        attr_reader :lro_object_full_name
+        attr_reader :operation_status_field
+        attr_reader :operation_name_field
+        attr_reader :operation_err_code_field
+        attr_reader :operation_err_msg_field
+        attr_reader :operation_response_fields
+
+        ##
+        # @return [Boolean] Whether this is a model for a nonstandard LRO provider service
+        #
+        def nonstandard_lro?
+          true
+        end
+
+        ##
+        # @param service_full_name [String]
+        #   Full grpc name of this service. E.g. `google.example.LroProvider`.
+        #
+        # @param polling_method_name [String]
+        #   Name of the method that is used to poll for LROs. E.g. `Poll`
+        #
+        # @param lro_object_full_name
+        #   Full grpc name of the object that is returned by the polling method.
+        #   E.g. `google.cloud.compute.v1.Operation`
+        #
+        # @param operation_status_field [String]
+        #   In the Operation message for this service, the name of the `status` field.
+        #   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 operation_name_field [String, nil]
+        #   In the Operation message for this service, the name of the `name` field.
+        #
+        # @param operation_err_code_field [String, nil]
+        #   In the Operation message for this service, the name of the `error code` field.
+        #
+        # @param operation_err_msg_field [String, nil]
+        #   In the Operation message for this service, the name of the `error message` field.
+        #
+        # @param operation_response_fields [Hash<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 polling request field` (`from -> to`).
+        #   E.g. `{"foo" => "bar"}` means that when constructing a polling request,
+        #   the following assignment should be carried out:
+        #   `lro_polling_request.bar = operation_object.foo`.
+        #
+        def initialize service_full_name,
+                       polling_method_name,
+                       lro_object_full_name,
+                       operation_status_field,
+                       operation_name_field,
+                       operation_err_code_field,
+                       operation_err_msg_field,
+                       operation_response_fields
+
+          @service_full_name = service_full_name
+          @polling_method_name = polling_method_name
+          @lro_object_full_name = lro_object_full_name
+          @operation_status_field = operation_status_field
+          @operation_name_field = operation_name_field
+          @operation_err_code_field = operation_err_code_field
+          @operation_err_msg_field = operation_err_msg_field
+          @operation_response_fields = operation_response_fields
+        end
+      end
+
+      ##
+      # Service does not provide nonstandard LRO polling capabilities
+      #
+      class NoNonstandardLro
+        include Singleton
+
+        ##
+        # @return [Boolean] Whether this is a model for a nonstandard LRO provider service
+        #
+        def nonstandard_lro?
+          false
+        end
+      end
+
+      class << self
+        ##
+        # Parses the service proto information to determine, whether it is
+        # a provider for nonstandard long-running operations polling
+        #
+        # @param service [Gapic::Schema::Service]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @return [NonstandardLroProvider, nil]
+        def parse_nonstandard_lro service
+          polling_method = find_polling_method service
+          return unless polling_method
+
+          # There should not be any methods that have the `operation_service` annotation
+          # in the LRO provider service.
+          # In theory there is nothing wrong with one LRO polling service using another
+          # LRO polling service, in practice there is potential for service intialization cycles
+          # Until we have a real usecase it's safer to assume an error in proto.
+          nonstandard_lro_candidates = service.methods.find_all do |m|
+            !m.operation_service.nil? && !m.operation_service.empty?
+          end
+
+          if nonstandard_lro_candidates.length.positive?
+            ops_service_method = nonstandard_lro_candidates[0]
+            error_text = "A service `#{service.name}` has a method annotated " \
+                        "with `polling_method` (`#{polling_method.name}`), and also a method annotated " \
+                        "with `operation_service` (`#{ops_service_method.name}`). "\
+                        "This means a grpc service tries to be a client " \
+                        "and a provider of the nonstandard LRO at the same time. " \
+                        "This is not supported."
+            raise ModelError, error_text
+          end
+
+          lro_object_full_name = polling_method.output.full_name
+
+          status_field = find_status_field service, polling_method
+          operation_status_field = status_field.name
+
+          operation_name_field = name_of_operation_field polling_method, ::Google::Cloud::OperationResponseMapping::NAME
+          operation_err_code_field = name_of_operation_field polling_method,
+                                                             ::Google::Cloud::OperationResponseMapping::ERROR_CODE
+          operation_err_msg_field = name_of_operation_field polling_method,
+                                                            ::Google::Cloud::OperationResponseMapping::ERROR_MESSAGE
+
+          # optionally, there might be fields in the polling method's input object
+          # that should be filled with information from the LRO object
+          ops_response_fields = polling_method.input.fields.find_all do |f|
+            !f.operation_response_field.nil? && !f.operation_response_field.empty?
+          end
+
+          operation_response_fields = ops_response_fields.map do |field|
+            [field.name, field.operation_response_field]
+          end.to_h
+
+          NonstandardLroProvider.new service.full_name,
+                                     polling_method.name,
+                                     lro_object_full_name,
+                                     operation_status_field,
+                                     operation_name_field,
+                                     operation_err_code_field,
+                                     operation_err_msg_field,
+                                     operation_response_fields
+        end
+
+        private
+
+        ##
+        # Returns a name of the polling method's output object (presumed to be LRO object)'s field
+        # that is marked with a given `operation_response_field` annotation,
+        # or nil if no such field exists.
+        #
+        # @param polling_method [Gapic::Schema::Method] the polling method
+        # @param ops_response_field [Integer] the value of the `operation_response_field` annotation
+        #
+        # @return [String]
+        #
+        def name_of_operation_field polling_method, ops_response_field
+          name_candidate = polling_method.output.fields.find do |f|
+            f.operation_field == ops_response_field
+          end
+          return name_candidate.name if name_candidate
+        end
+
+        ##
+        # If this service is provider for a nonstandard LRO,
+        # find the polling method.
+        # Otherwise returns nil.
+        #
+        # @param service [Gapic::Schema::Service]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Schema::Method, nil]
+        #
+        def find_polling_method service
+          # On a LRO service, one method should be marked as 'polling'
+          polling_method_candidates = service.methods.find_all do |m|
+            !m.polling_method.nil? && m.polling_method
+          end
+          if polling_method_candidates.length > 1
+            error_text = "A service #{service.name} has more than one method annotated " \
+                        "with `operation_polling_method`. This should not happen."
+            raise ModelError, error_text
+          end
+
+          return unless polling_method_candidates.length == 1
+
+          polling_method_candidates[0]
+        end
+
+        ##
+        # Find the `status` field in the LRO message that this service provides a
+        # polling functionality for
+        #
+        # @param service [Gapic::Schema::Service]
+        # @param polling_method [Gapic::Schema::Method]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Schema::Field]
+        #
+        def find_status_field service, polling_method
+          # The output of the polling method is an Operation, which should have at least
+          # a Status field
+          status_candidates = polling_method.output.fields.find_all do |f|
+            f.operation_field == ::Google::Cloud::OperationResponseMapping::STATUS
+          end
+
+          if status_candidates.length > 1
+            error_text = "A nonstandard LRO provider service `#{service.name}`'s " \
+                         "polling method `#{polling_method.name}`'s output message " \
+                         "`#{polling_method.output.name}` has more than one field annotated " \
+                         "with `google.cloud.operation_field = STATUS`. This is not supported."
+            raise ModelError, error_text
+          end
+
+          if status_candidates.length.zero?
+            error_text = "A nonstandard LRO provider service `#{service.name}`'s " \
+                         "polling method `#{polling_method.name}`'s output message " \
+                         "`#{polling_method.output.name}` does not have any fields annotated " \
+                         "with `google.cloud.operation_field = STATUS`. This is not supported."
+            raise ModelError, error_text
+          end
+
+          status_candidates[0]
+        end
+      end
+    end
+  end
+end

data/lib/gapic/model.rb

@@ -0,0 +1,22 @@
+# 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/model/method/http_annotation"
+require "gapic/model/method/lro"
+require "gapic/model/method/routing"
+require "gapic/model/mixins"
+require "gapic/model/model_error"
+require "gapic/model/service/nonstandard_lro_provider"

data/lib/gapic/path_pattern/pattern.rb

@@ -44,6 +44,43 @@ module Gapic
         @segments.select(&:provides_arguments?).map(&:arguments).flatten
       end
 
+      ##
+      # Whether this is a basic single-star ("*") pattern
+      # @return [Boolean]
+      def star_pattern?
+        @segments.length == 1 && @segments[0].pattern == "*"
+      end
+
+      ##
+      # Whether this is a basic double-star ("**") pattern
+      # @return [Boolean]
+      def double_star_pattern?
+        @segments.length == 1 && @segments[0].pattern == "**"
+      end
+
+      ##
+      # Converts the PathPattern into a regex string
+      # @return [String]
+      def to_regex_str
+        regex_str = segments.first.to_regex_str
+
+        # for double wildcards the leading `/`` is optional
+        # e.g. `foo/**` should match `foo`
+        # this is why segments 'bring' the leading separator
+        # with them as they build the pattern
+        segments.drop(1).each_with_index do |segment, _index|
+          is_double_wildcard = segment.pattern == "**"
+
+          regex_str = if is_double_wildcard
+                        "#{regex_str}(?:/.*)?"
+                      else
+                        "#{regex_str}/#{segment.to_regex_str}"
+                      end
+        end
+
+        regex_str
+      end
+
       ##
       # Whether pattern contains a positional segment
       # @return [Boolean]
@@ -76,6 +113,15 @@ module Gapic
         parent_pattern_segments = last_segment.provides_arguments? ? segments[0...-2] : segments[0...-1]
         parent_pattern_segments.map(&:pattern_template).join("/")
       end
+
+      ##
+      # The pattern with the resource names stripped
+      # from the ResourceId segments
+      # (e.g. `collections/{resource_id=foo/*}` => `collections/foo/*`)
+      #
+      def simplified_pattern
+        @segments.map(&:simplified_pattern).join("/")
+      end
     end
   end
 end

data/lib/gapic/path_pattern/segment.rb

@@ -97,6 +97,32 @@ module Gapic
         pattern
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        false
+      end
+
+      ##
+      # The difference between `simplified_pattern` and `pattern`
+      # does not exist for the Positional segments
+      # @return [String]
+      def simplified_pattern
+        pattern
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        if pattern == "**"
+          ".*"
+        else
+          "[^/]+"
+        end
+      end
+
       # @private
       def == other
         return false unless other.is_a? self.class
@@ -129,6 +155,12 @@ module Gapic
         @type              = type
         @pattern           = pattern
         @resource_names    = resource_names
+
+        # For the segments specified like `{foo}`, the implied resource pattern is `*`
+        # `{foo}` === `{foo=*}`
+        if resource_patterns.empty?
+          resource_patterns = ["*"]
+        end
         @resource_patterns = resource_patterns
       end
 
@@ -139,15 +171,9 @@ module Gapic
         false
       end
 
-      ##
-      # Whether the segment provides a resource pattern
-      # @return [Boolean]
-      def resource_pattern?
-        resource_patterns.any?
-      end
-
       ##
       # Whether the segment provides a nontrivial resource pattern
+      # (not `*` or `**`)
       # @return [Boolean]
       def nontrivial_resource_pattern?
         resource_patterns.any? { |res_pattern| !res_pattern.match?(/^\*+$/) }
@@ -168,8 +194,8 @@ module Gapic
       end
 
       ##
-      # Returns a segment's pattern filled with dummy values
-      #   names of the values are generated starting from the index provided
+      # Returns a segment's pattern filled with dummy values.
+      # Names of the values are generated starting from the index provided.
       # @param start_index [Integer] a starting index for dummy value generation
       # @return [String] a pattern filled with dummy values
       def expected_path_for_dummy_values start_index
@@ -194,6 +220,46 @@ module Gapic
         "*"
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        true
+      end
+
+      ##
+      # The pattern with the resource name
+      # (e.g. `foo` in `{foo=bar/*}`) stripped.
+      # So `{foo=bar/*}` -> `bar/*`.
+      #
+      # Not implemented for multivariate segments
+      # (e.g `{foo}~{bar}`).
+      #
+      # @return [String]
+      def simplified_pattern
+        if resource_patterns.count > 1
+          raise "Not implemented for multivariate ResourceId segments"
+        end
+        resource_patterns[0]
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        raise "Not implemented for multivariate ResourceId segments" if resource_patterns.count > 1
+
+        resource_pattern = if resource_patterns[0].nil?
+                             "*"
+                           else
+                             resource_patterns[0]
+                           end
+
+        resource_pattern_regex = Gapic::PathPattern::Parser.parse(resource_pattern).to_regex_str
+
+        "(?<#{resource_names[0]}>#{resource_pattern_regex})"
+      end
+
       ##
       # Initialization helper to create a simple resource without a pattern
       # @param name [String] resource name
@@ -272,6 +338,28 @@ module Gapic
         pattern
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        false
+      end
+
+      ##
+      # The difference between `simplified_pattern` and `pattern`
+      # does not exist for the CollectionId segments
+      # @return [String]
+      def simplified_pattern
+        pattern
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        pattern
+      end
+
       # @private
       def == other
         return false unless other.is_a? self.class

data/lib/gapic/presenters/gem_presenter.rb

@@ -30,6 +30,7 @@ module Gapic
 
       def initialize api
         @api = api
+        @mixins_model = Gapic::Model::Mixins.new api.services.map(&:full_name), api.service_config
       end
 
       ##
@@ -46,6 +47,9 @@ module Gapic
         !packages.empty?
       end
 
+      ##
+      # @return [Enumerable<Gapic::Presenters::ServicePresenter>]
+      #
       def services
         @services ||= begin
           files = @api.generate_files
@@ -135,7 +139,7 @@ module Gapic
       end
 
       def library_documentation_url
-        gem_config(:library_documentation_url) || "https://googleapis.dev/ruby/#{name}/latest"
+        gem_config(:library_documentation_url) || "https://rubydoc.info/gems/#{name}"
       end
 
       def product_documentation_url
@@ -178,7 +182,15 @@ module Gapic
         gem_config(:generic_endpoint) || false
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def generate_rest_clients?
+        @api.generate_rest_clients?
+      end
+
       def entrypoint_require
+        return "" unless packages?
         packages.first.package_require
       end
 
@@ -192,10 +204,11 @@ module Gapic
 
       def dependencies
         @dependencies ||= begin
-          deps = { "gapic-common" => [">= 0.5", "< 2.a"] }
+          deps = { "gapic-common" => [">= 0.7", "< 2.a"] }
           deps["grpc-google-iam-v1"] = [">= 0.6.10", "< 2.a"] if iam_dependency?
           extra_deps = gem_config_dependencies
           deps.merge! extra_deps if extra_deps
+          deps.merge! mixins_model.dependencies if mixins_model.mixins?
           deps
         end
       end
@@ -215,7 +228,7 @@ module Gapic
       # @return [Hash]
       def first_package_drift_manifest
         return {} unless packages?
-        packages[0].drift_manifest
+        packages.first.drift_manifest
       end
 
       ##
@@ -239,6 +252,36 @@ module Gapic
         result || first_non_common_service
       end
 
+      ##
+      # Whether the "Enabling (gRPC) Logging" section of the readme should
+      # appear. This is true if there is a quick-start service displayed in the
+      # readme, AND it uses gRPC.
+      #
+      # @return [Boolean]
+      #
+      def show_grpc_logging_docs?
+        packages? && quick_start_service.usable_service_presenter.is_a?(ServicePresenter)
+      end
+
+      ##
+      # Whether there are mixin services that should be referenced
+      # in the services for this gem
+      #
+      # @return [Boolean]
+      #
+      def mixins?
+        @mixins_model.mixins?
+      end
+
+      ##
+      # The model for the mixin services
+      #
+      # @return [Gapic::Model::Mixins]
+      #
+      def mixins_model
+        @mixins_model
+      end
+
       private
 
       def gem_config key

data/lib/gapic/presenters/{service_config_presenter.rb → grpc_service_config_presenter.rb}

@@ -19,7 +19,7 @@ module Gapic
     ##
     # A presenter for grpc service config.
     #
-    class ServiceConfigPresenter
+    class GrpcServiceConfigPresenter
       def initialize grpc_service_config
         @grpc_service_config = grpc_service_config
       end