gapic-generator 0.11.0 → 0.45.1

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

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "singleton"
+
 require "gapic/path_pattern"
 
 module Gapic
@@ -55,9 +57,9 @@ module Gapic
             !f.operation_request_field.nil? && !f.operation_request_field.empty?
           end
 
-          @operation_request_fields = ops_request_fields.map do |field|
+          @operation_request_fields = ops_request_fields.to_h do |field|
             [field.name, field.operation_request_field]
-          end.to_h
+          end
         end
 
         ##
@@ -138,14 +140,15 @@ module Gapic
             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."
+                           "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})."
+                           "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
 

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

@@ -175,8 +175,8 @@ module Gapic
             end
 
             @field_pattern = @path_pattern.simplified_pattern
-            @field_full_regex_str =  to_field_pattern @path_pattern
-            @field_regex_str = to_field_pattern Gapic::PathPattern.parse(@field_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]
@@ -200,20 +200,6 @@ module Gapic
 
           private
 
-          # Makes a regex pattern match a field
-          # - adds markers for the beginning and end of the string
-          # - adds handling of an optional tail `/` if needed
-          # @param pattern [String]
-          # @return [String]
-          def to_field_pattern pattern
-            tail_slash_accept = if pattern.segments.last.simplified_pattern == "**"
-                                  ""
-                                else
-                                  "/?"
-                                end
-            "^#{pattern.to_regex_str}#{tail_slash_accept}$"
-          end
-
           # Converts path template simplified forms into canonical
           # ResourceId representations by adding a field as a Resource Id
           # @param template [String]
@@ -244,8 +230,7 @@ module Gapic
                        "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}"
+            "A routing header parameter with the path_template #{raw_template}\n is invalid: #{reason}"
           end
         end
 

data/lib/gapic/model/mixins.rb

@@ -36,9 +36,12 @@ module Gapic
       #   List of services from the  Api model
       # @param service_config [Google::Api::Service]
       #   The service config
-      def initialize api_services, service_config
+      # @param gem_name [String]
+      #   The name of the gem.
+      def initialize api_services, service_config, gem_name
         @api_services = api_services
         @service_config = service_config
+        @gem_name = gem_name
       end
 
       # @return [Boolean] Whether there are any mix-in services
@@ -50,13 +53,14 @@ module Gapic
       #   List of Mixin objects, providing the information that is needed
       #   to add the mixin service references to the generated library
       def mixins
-        @mixins ||= mixin_services.map { |service| create_mixin(service) }
+        @mixins ||= mixin_services.map { |service| create_mixin service }
       end
 
       # @return [Enumerable<String>] Full proto names of the mix-in services
       def mixin_services
-        @mixin_services ||= services_in_config.select do |service|
-          service != LRO_SERVICE && !@api_services.include?(service)
+        @mixin_services ||= begin
+          candidates = services_in_config & SERVICE_TO_DEPENDENCY.keys
+          candidates.reject { |name| SERVICE_TO_DEPENDENCY[name].include? @gem_name }
         end
       end
 
@@ -77,12 +81,21 @@ module Gapic
       # @!attribute [r] require_str
       #   Path to `require` the client of the service
       #   @return [String]
+      # @!attribute [r] require_str_rest
+      #   Path to `require` the REST client of the service
+      #   @return [String]
       # @!attribute [r] client_class_name
       #   Full name of the class of the client of the service
       #   @return [String]
+      # @!attribute [r] client_class_name_rest
+      #   Full name of the class of the REST client of the service
+      #   @return [String]
       # @!attribute [r] client_class_docname
       #   Name of the class as it should appear in the documentation
       #   @return [String]
+      # @!attribute [r] client_class_docname_rest
+      #   Name of the REST class as it should appear in the documentation
+      #   @return [String]
       # @!attribute [r] client_var_name
       #   Name for the variable for the client of the
       #   mixin service to use when generating library's service
@@ -91,8 +104,11 @@ module Gapic
         attr_reader :service
         attr_reader :dependency
         attr_reader :require_str
+        attr_reader :require_str_rest
         attr_reader :client_class_name
+        attr_reader :client_class_name_rest
         attr_reader :client_class_docname
+        attr_reader :client_class_docname_rest
         attr_reader :client_var_name
 
         # @param service [String]
@@ -102,17 +118,25 @@ module Gapic
         #   `{ gem_name => version pattern }` format
         # @param require_str [String]
         #   Path to require the client of the service
+        # @param require_str_rest [String]
+        #   Path to require the REST client of the service
         # @param client_class_name [String]
         #   Full name of the class of the client of the service
+        # @param client_class_name_rest [String]
+        #   Full name of the class of the REST client of the service
         # @param client_var_name [String]
         #   Name for the variable for the client of the mixin service
         #   to use when generating library's service
-        def initialize service, dependency, require_str, client_class_name, client_var_name
+        def initialize service, dependency, require_str, require_str_rest, client_class_name, client_class_name_rest,
+                       client_var_name
           @service = service
           @dependency = dependency
           @require_str = require_str
+          @require_str_rest = require_str_rest
           @client_class_name = client_class_name
+          @client_class_name_rest = client_class_name_rest
           @client_class_docname = client_class_name # For mixins, the doc name should be the full class name
+          @client_class_docname_rest = client_class_name_rest # For mixins, the doc name should be the full class name
           @client_var_name = client_var_name
         end
 
@@ -123,6 +147,21 @@ module Gapic
         end
       end
 
+      ##
+      # Returns true if the given service address is a mixin.
+      # This just checks the service against a (hard-coded) set of known mixins.
+      # If `gem_name` is provided, services that correspond to that gem_name are not considered mixins.
+      #
+      # @param service_address [String,Array<String>] The address (either array
+      #     or dot-delimited) of the service to check.
+      # @param gem_name [String] The name of the gem.
+      # @return [boolean]
+      #
+      def self.mixin_service_address? service_address, gem_name: nil
+        service_address = service_address.join "." unless service_address.is_a? String
+        MIXIN_GEM_NAMES.include?(service_address) && gem_name != MIXIN_GEM_NAMES[service_address]
+      end
+
       private
 
       # @return [Enumerable<String>] Names of all services that are specified
@@ -133,28 +172,51 @@ module Gapic
         @service_config.apis.map(&:name)
       end
 
+      MIXIN_GEM_NAMES = {
+        LOCATIONS_SERVICE => "google-cloud-location",
+        IAM_SERVICE => "google-iam-v1",
+        LRO_SERVICE => "google-longrunning-operations"
+      }.freeze
+      private_constant :MIXIN_GEM_NAMES
+
       # Since mixins are scope-limited to a couple of services, it is easier to
       # have these in lookup tables than to construct a ServicePresenter
 
       SERVICE_TO_DEPENDENCY = {
-        LOCATIONS_SERVICE => { "google-cloud-location" => "~> 0.1" },
-        IAM_SERVICE => { "google-iam-v1" => "~> 0.1" }
+        LOCATIONS_SERVICE => { "google-cloud-location" => ["~> 1.0"] },
+        IAM_SERVICE => { "google-iam-v1" => ["~> 1.3"] }
       }.freeze
+      private_constant :SERVICE_TO_DEPENDENCY
 
       SERVICE_TO_REQUIRE_STR = {
         LOCATIONS_SERVICE => "google/cloud/location",
-        IAM_SERVICE => "google/iam/v1/iam_policy"
+        IAM_SERVICE => "google/iam/v1"
+      }.freeze
+      private_constant :SERVICE_TO_REQUIRE_STR
+
+      SERVICE_TO_REQUIRE_STR_REST = {
+        LOCATIONS_SERVICE => "google/cloud/location/rest",
+        IAM_SERVICE => "google/iam/v1/rest"
       }.freeze
+      private_constant :SERVICE_TO_REQUIRE_STR_REST
 
       SERVICE_TO_CLIENT_CLASS_NAME = {
         LOCATIONS_SERVICE => "Google::Cloud::Location::Locations::Client",
         IAM_SERVICE => "Google::Iam::V1::IAMPolicy::Client"
       }.freeze
+      private_constant :SERVICE_TO_CLIENT_CLASS_NAME
+
+      SERVICE_TO_CLIENT_CLASS_NAME_REST = {
+        LOCATIONS_SERVICE => "Google::Cloud::Location::Locations::Rest::Client",
+        IAM_SERVICE => "Google::Iam::V1::IAMPolicy::Rest::Client"
+      }.freeze
+      private_constant :SERVICE_TO_CLIENT_CLASS_NAME_REST
 
       SERVICE_TO_CLIENT_ATTR_NAME = {
         LOCATIONS_SERVICE => "location_client",
         IAM_SERVICE => "iam_policy_client"
       }.freeze
+      private_constant :SERVICE_TO_CLIENT_ATTR_NAME
 
       # @param service [String] full grpc name of the service
       # @raise [ModelError]
@@ -162,8 +224,10 @@ module Gapic
       def create_mixin service
         unless SERVICE_TO_DEPENDENCY.key?(service) &&
                SERVICE_TO_REQUIRE_STR.key?(service) &&
-               SERVICE_TO_CLIENT_CLASS_NAME.key?(service)
-          SERVICE_TO_CLIENT_ATTR_NAME.key? service
+               SERVICE_TO_REQUIRE_STR_REST.key?(service) &&
+               SERVICE_TO_CLIENT_CLASS_NAME.key?(service) &&
+               SERVICE_TO_CLIENT_CLASS_NAME_REST.key?(service) &&
+               SERVICE_TO_CLIENT_ATTR_NAME.key?(service)
 
           error_text = "A mixin service #{service} is specified in service config, but " \
                        "the Generator does not know of it."
@@ -173,7 +237,9 @@ module Gapic
         Mixin.new service,
                   SERVICE_TO_DEPENDENCY[service],
                   SERVICE_TO_REQUIRE_STR[service],
+                  SERVICE_TO_REQUIRE_STR_REST[service],
                   SERVICE_TO_CLIENT_CLASS_NAME[service],
+                  SERVICE_TO_CLIENT_CLASS_NAME_REST[service],
                   SERVICE_TO_CLIENT_ATTR_NAME[service]
       end
     end

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

@@ -114,7 +114,6 @@ module Gapic
                        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
@@ -166,11 +165,11 @@ module Gapic
           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."
+                         "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
 
@@ -191,9 +190,9 @@ module Gapic
             !f.operation_response_field.nil? && !f.operation_response_field.empty?
           end
 
-          operation_response_fields = ops_response_fields.map do |field|
+          operation_response_fields = ops_response_fields.to_h do |field|
             [field.name, field.operation_response_field]
-          end.to_h
+          end
 
           NonstandardLroProvider.new service.full_name,
                                      polling_method.name,
@@ -221,7 +220,7 @@ module Gapic
           name_candidate = polling_method.output.fields.find do |f|
             f.operation_field == ops_response_field
           end
-          return name_candidate.name if name_candidate
+          name_candidate&.name
         end
 
         ##
@@ -242,7 +241,7 @@ module Gapic
           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."
+                         "with `operation_polling_method`. This should not happen."
             raise ModelError, error_text
           end
 
@@ -277,7 +276,7 @@ module Gapic
             raise ModelError, error_text
           end
 
-          if status_candidates.length.zero?
+          if status_candidates.empty?
             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 " \

data/lib/gapic/package_snippets.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# 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 "google/protobuf/compiler/plugin_pb"
+require "google/cloud/tools/snippetgen/snippetindex/v1/snippet_index_pb"
+require "json"
+
+module Gapic
+  # An object that collects snippets for a package and generates the metadata
+  # content.
+  class PackageSnippets
+    # @private
+    SnippetIndex = ::Google::Cloud::Tools::SnippetGen::SnippetIndex::V1
+
+    ##
+    # Start collecting snippets for a package
+    #
+    # @param proto_package [String] Fully qualified proto package name including
+    #     API version, e.g. `google.cloud.translate.v3`. Required.
+    # @param gem_name [String] Name of the gem being generated, e.g.
+    #     `google-cloud-translate-v3`. Required.
+    # @param snippet_dir [String] Directory where snippets are generated.
+    #     Optional. Defaults to `snippets`.
+    #
+    def initialize proto_package:, gem_name:, snippet_dir: "snippets"
+      api = SnippetIndex::Api.new(
+        id: proto_package,
+        version: proto_package.split(".").last
+      )
+      client_library_object = SnippetIndex::ClientLibrary.new(
+        name: gem_name,
+        version: "",
+        language: "RUBY",
+        apis: [api]
+      )
+      @index_object = SnippetIndex::Index.new(
+        client_library: client_library_object
+      )
+      @metadata_filename = "#{snippet_dir}/snippet_metadata_#{proto_package}.json"
+      @snippet_files = []
+    end
+
+    ##
+    # Add a snippet to the collection
+    #
+    # @param method_presenter [Gapic::Presenters::MethodPresenter]
+    # @param snippet_presenter [Gapic::Presenters::SnippetPresenter]
+    # @param snippet_file [Google::Protobuf::Compiler::CodeGeneratorResponse::File]
+    # @return [self]
+    #
+    def add method_presenter:, snippet_presenter:, snippet_file:
+      service_presenter = method_presenter.service
+      snippet_lines = [""] + snippet_file.content.split("\n")
+      @index_object.snippets <<
+        build_snippet_object(snippet_presenter, method_presenter, service_presenter, snippet_lines)
+      @snippet_files << snippet_file
+      self
+    end
+
+    ##
+    # Return a list of files to render for this package. This includes all the
+    # snippet files themselves, and the metadata file.
+    #
+    # @return [Array<Google::Protobuf::Compiler::CodeGeneratorResponse::File>]
+    #
+    def files
+      metadata_content = JSON.pretty_generate json_value_for @index_object
+      metadata_file = Google::Protobuf::Compiler::CodeGeneratorResponse::File.new(
+        name: @metadata_filename,
+        content: metadata_content
+      )
+      @snippet_files + [metadata_file]
+    end
+
+    private
+
+    def build_snippet_object snippet_presenter, method_presenter, service_presenter, snippet_lines
+      service_presenter = service_presenter.rest if snippet_presenter.transport == :rest
+      SnippetIndex::Snippet.new(
+        region_tag: snippet_presenter.region_tag,
+        title: snippet_presenter.snippet_name,
+        description: snippet_presenter.description,
+        file: snippet_presenter.snippet_file_path,
+        language: "RUBY",
+        client_method: build_client_method_object(method_presenter, service_presenter),
+        canonical: true,
+        origin: "API_DEFINITION",
+        segments: build_segments_array(snippet_lines, snippet_presenter.region_tag)
+      )
+    end
+
+    def build_client_method_object method_presenter, service_presenter
+      parameter = SnippetIndex::ClientMethod::Parameter.new(
+        type: method_presenter.request_type,
+        name: "request"
+      )
+      client = SnippetIndex::ServiceClient.new(
+        short_name: service_presenter.client_suffix_for_default_transport,
+        full_name: service_presenter.client_name_full
+      )
+      SnippetIndex::ClientMethod.new(
+        short_name: method_presenter.name,
+        full_name: "#{service_presenter.client_name_full}##{method_presenter.name}",
+        async: false,
+        parameters: [parameter],
+        result_type: method_presenter.return_type,
+        client: client,
+        method: build_method_object(method_presenter, service_presenter)
+      )
+    end
+
+    def build_method_object method_presenter, service_presenter
+      service = SnippetIndex::Service.new(
+        short_name: service_presenter.name,
+        full_name: service_presenter.grpc_full_name
+      )
+      SnippetIndex::Method.new(
+        short_name: method_presenter.grpc_name,
+        full_name: method_presenter.grpc_full_name,
+        service: service
+      )
+    end
+
+    # Currently this builds only the FULL segment. We can fill out additional
+    # segment types once requirements have been clarified.
+    def build_segments_array snippet_lines, region_tag
+      start_tag_line = snippet_lines.index { |line| line.include? "[START #{region_tag}]" }
+      end_tag_line = snippet_lines.index { |line| line.include? "[END #{region_tag}]" }
+      result = []
+      if start_tag_line && end_tag_line
+        result << SnippetIndex::Snippet::Segment.new(
+          start: start_tag_line + 1,
+          end: end_tag_line - 1,
+          type: "FULL"
+        )
+      end
+      result
+    end
+
+    def json_value_for value
+      json = value.class.encode_json value, preserve_proto_fieldnames: true,
+                                            emit_defaults: true
+      JSON.parse json
+    end
+  end
+end

data/lib/gapic/path_pattern/parser.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "active_support/inflector"
 require "gapic/path_pattern/segment"
 require "gapic/path_pattern/pattern"
 
@@ -39,7 +40,7 @@ module Gapic
           segments << segment
         end
 
-        Pattern.new path_pattern, segments
+        Pattern.new format_pattern(path_pattern), segments
       end
 
       # @private
@@ -117,7 +118,7 @@ module Gapic
         match = simple_resource_id_regex.match url_pattern
         segment_pattern = match[:segment_pattern]
 
-        resource_name = match[:resource_name]
+        resource_name = ActiveSupport::Inflector.underscore match[:resource_name]
         resource_pattern = match[:resource_pattern] if match.names.include? "resource_pattern"
         resource_patterns = resource_pattern.nil? ? [] : [resource_pattern]
 
@@ -141,6 +142,14 @@ module Gapic
         remainder = match.post_match
         [segment, remainder]
       end
+
+      # Formats variables within a path pattern.
+      # @private
+      def self.format_pattern pattern
+        pattern.gsub(/\{([a-zA-Z0-9_]+)\}/) do
+          "{#{ActiveSupport::Inflector.underscore ::Regexp.last_match(1)}}"
+        end
+      end
     end
   end
 end

data/lib/gapic/path_pattern/pattern.rb

@@ -38,7 +38,7 @@ module Gapic
       end
 
       ##
-      # All argument names from this pattern
+      # All argument from this pattern, including ids for positional arguments
       # @return [Array<String>]
       def arguments
         @segments.select(&:provides_arguments?).map(&:arguments).flatten
@@ -58,6 +58,13 @@ module Gapic
         @segments.length == 1 && @segments[0].pattern == "**"
       end
 
+      ##
+      # Whether this pattern ends with a double-star ("**")
+      # @return [Boolean]
+      def ends_with_double_star_pattern?
+        segments.last.pattern.end_with? "**"
+      end
+
       ##
       # Converts the PathPattern into a regex string
       # @return [String]
@@ -81,6 +88,16 @@ module Gapic
         regex_str
       end
 
+      ##
+      # Converts the PathPattern into a regex string that matches a whole field
+      # - adds markers for the beginning and end of the string
+      # - adds handling of an optional tail `/` if needed
+      # @return [String]
+      def to_field_regex_str
+        tail_slash_accept = ends_with_double_star_pattern? ? "" : "/?"
+        "^#{to_regex_str}#{tail_slash_accept}$"
+      end
+
       ##
       # Whether pattern contains a positional segment
       # @return [Boolean]

data/lib/gapic/path_pattern/segment.rb

@@ -127,7 +127,7 @@ module Gapic
       def == other
         return false unless other.is_a? self.class
 
-        (pattern == other.pattern && position == other.position)
+        pattern == other.pattern && position == other.position
       end
     end
 
@@ -210,7 +210,13 @@ module Gapic
       # Path string for this segment
       # @return [String]
       def path_string
-        type == :simple_resource_id ? "\#{#{resource_names[0]}}" : pattern.gsub("{", "\#{")
+        if type == :simple_resource_id
+          name = resource_names[0]
+          name = "binding.local_variable_get :#{name}" if Gapic::RubyInfo.keywords.include? name
+          "\#{#{name}}"
+        else
+          pattern.gsub "{", "\#{"
+        end
       end
 
       ##
@@ -272,9 +278,10 @@ module Gapic
       def == other
         return false unless other.is_a? self.class
 
-        (type == other.type && pattern == other.pattern &&
+        type == other.type &&
+          pattern == other.pattern &&
           resource_names == other.resource_names &&
-          resource_patterns == other.resource_patterns)
+          resource_patterns == other.resource_patterns
       end
     end
 

data/lib/gapic/presenters/enum_presenter.rb

@@ -20,8 +20,15 @@ module Gapic
     # A presenter for proto enums.
     #
     class EnumPresenter
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param enum [Gapic::Schema::Enum]
+      #
       def initialize enum
         @enum = enum
+        @type = "enum"
       end
 
       def name
@@ -35,6 +42,13 @@ module Gapic
       def values
         @values ||= @enum.values.map { |v| EnumValuePresenter.new v }
       end
+
+      ##
+      # @return [Boolean] Whether the enum is marked as deprecated.
+      #
+      def is_deprecated?
+        @enum.is_deprecated?
+      end
     end
   end
 end

data/lib/gapic/presenters/enum_value_presenter.rb

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/ruby_info"
+
 module Gapic
   module Presenters
     ##
@@ -24,8 +26,9 @@ module Gapic
         @value = value
       end
 
+      # @return [String] The enum value name without keyword collision.
       def name
-        @value.name
+        Gapic::RubyInfo.keywords.include?(@value.name) ? "#{@value.parent.name}::#{@value.name}" : @value.name
       end
 
       def doc_description