gapic-generator 0.11.0 → 0.45.1

data/lib/gapic/presenters/field_presenter.rb

@@ -25,16 +25,33 @@ module Gapic
     class FieldPresenter
       include Gapic::Helpers::NamespaceHelper
 
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param api [Gapic::Schema::Api]
+      # @param message [Gapic::Schema::Message]
+      # @param field [Gapic::Schema::Field]
+      #
       def initialize api, message, field
         @api = api
         @message = message
         @field = field
+        @type = "field"
       end
 
       def name
         @field.name
       end
 
+      ##
+      # @return [String] The field name to be used as a value without reserved keywords.
+      #
+      def value_name
+        name = @field.name
+        Gapic::RubyInfo.keywords.include?(name) ? "#{name}_param" : name
+      end
+
       def doc_types
         field_doc_types @field, false
       end
@@ -48,8 +65,15 @@ module Gapic
         field_doc_types @field, true
       end
 
-      def doc_description
-        @field.docs_leading_comments
+      ##
+      # The description as it should appear in YARD docs.
+      #
+      # @param transport [:grpc,:rest] Whether xref links should go to REST or
+      #   gRPC client classes. Uses the default transport if not provided.
+      # @return [String]
+      #
+      def doc_description transport: nil
+        @field.docs_leading_comments transport: transport
       end
 
       def default_value
@@ -59,7 +83,7 @@ module Gapic
       end
 
       def as_kwarg value: nil
-        "#{name}: #{value || name}"
+        "#{name}: #{value || value_name}"
       end
 
       # TODO: remove, only used in tests
@@ -126,14 +150,60 @@ module Gapic
       end
 
       ##
-      # Name of this field, camel-cased
+      # Name of this field, camel-cased.
       # @return [String]
+      #
       def camel_name
         camel_name_for name
       end
 
+      ##
+      # @return [Boolean] Whether the field is marked as deprecated.
+      #
+      def is_deprecated?
+        @field.is_deprecated?
+      end
+
       protected
 
+      # @private
+      FIELD_TYPE_MAPPING = {
+        TYPE_DOUBLE: "::Float",
+        TYPE_FLOAT: "::Float",
+        TYPE_INT64: "::Integer",
+        TYPE_UINT64: "::Integer",
+        TYPE_INT32: "::Integer",
+        TYPE_FIXED64: "::Integer",
+        TYPE_FIXED32: "::Integer",
+        TYPE_BOOL: "::Boolean",
+        TYPE_STRING: "::String",
+        TYPE_BYTES: "::String",
+        TYPE_UINT32: "::Integer",
+        TYPE_SFIXED32: "::Integer",
+        TYPE_SFIXED64: "::Integer",
+        TYPE_SINT32: "::Integer",
+        TYPE_SINT64: "::Integer"
+      }.freeze
+
+      # @private
+      FIELD_VALUE_MAPPING = {
+        TYPE_DOUBLE: "3.5",
+        TYPE_FLOAT: "3.5",
+        TYPE_INT64: "42",
+        TYPE_UINT64: "42",
+        TYPE_INT32: "42",
+        TYPE_FIXED64: "42",
+        TYPE_FIXED32: "42",
+        TYPE_BOOL: "true",
+        TYPE_STRING: "\"hello world\"",
+        TYPE_BYTES: "\"hello world\"",
+        TYPE_UINT32: "42",
+        TYPE_SFIXED32: "42",
+        TYPE_SFIXED64: "42",
+        TYPE_SINT32: "42",
+        TYPE_SINT64: "42"
+      }.freeze
+
       def field_doc_types field, output
         return field_map_type field.message, output if field.map?
         base_type =
@@ -144,14 +214,7 @@ module Gapic
             # TODO: handle when arg message is nil and enum is the type
             message_ruby_type field.enum
           else
-            case field.type
-            when 1, 2                              then "::Float"
-            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
-            when 9, 12                             then "::String"
-            when 8                                 then "::Boolean"
-            else
-              "::Object"
-            end
+            FIELD_TYPE_MAPPING[field.type] || "::Object"
           end
         field.repeated? ? "::Array<#{base_type}>" : base_type
       end
@@ -179,14 +242,8 @@ module Gapic
           # TODO: select the first non-0 enum value
           ":#{@field.enum.values.first.name}"
         else
-          case @field.type
-          when 1, 2                              then "3.5"
-          when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "42"
-          when 9, 12                             then "\"hello world\""
-          when 8                                 then "true"
-          else
-            "::Object"
-          end
+          # BUG: This should default to a better value
+          FIELD_VALUE_MAPPING[@field.type] || "::Object"
         end
       end
 
@@ -201,7 +258,7 @@ module Gapic
       def camel_name_for attr_name
         parts = attr_name.split "_"
         first_part = parts[0]
-        other_parts = parts[1..-1]
+        other_parts = parts[1..]
         other_parts_pascal = other_parts.map(&:capitalize).join
         "#{first_part}#{other_parts_pascal}"
       end

data/lib/gapic/presenters/gem_presenter.rb

@@ -30,7 +30,8 @@ module Gapic
 
       def initialize api
         @api = api
-        @mixins_model = Gapic::Model::Mixins.new api.services.map(&:full_name), api.service_config
+        service_config = api.configuration[:common_services] ? nil : api.service_config
+        @mixins_model = Gapic::Model::Mixins.new api.services.map(&:full_name), service_config, name
       end
 
       ##
@@ -53,7 +54,10 @@ module Gapic
       def services
         @services ||= begin
           files = @api.generate_files
-          files.map(&:services).flatten.map { |s| ServicePresenter.new self, @api, s }
+          service_list = files.map(&:services).flatten
+          mixin_service_names = mixins_model.mixin_services
+          service_list.delete_if { |s| mixin_service_names.include? s.full_name }
+          service_list.map { |s| ServicePresenter.new self, @api, s }
         end
       end
 
@@ -63,17 +67,12 @@ module Gapic
 
       def proto_files
         @proto_files ||= begin
-          files = @api.files
-          files = files.reject { |f| blacklist_protos.include? f.name }
-          files = files.reject { |f| f.messages.empty? && f.enums.empty? }
-          files.map { |f| FilePresenter.new @api, f }
+          @api.files
+              .select { |f| useful_proto_file? f }
+              .map { |f| FilePresenter.new @api, f }
         end
       end
 
-      def address
-        name.split("-").map(&:camelize)
-      end
-
       def name
         gem_config :name
       end
@@ -85,6 +84,7 @@ module Gapic
 
       def title
         gem_config(:title) ||
+          @api.api_metadata.title ||
           namespace.split("::").join(" ")
       end
 
@@ -117,11 +117,29 @@ module Gapic
 
       def description
         gem_config(:description) ||
+          @api.api_metadata.description ||
           "#{name} is the official client library for the #{title} API."
       end
 
+      def gemspec_description
+        description.gsub(/\s+/, " ").strip
+      end
+
+      ##
+      # Generates a description text for README files, accounting for markdown
+      # rendering and properly escaping variables.
+      #
+      # @return [Array<String>] The description text as an array of lines.
+      #
+      def readme_description
+        has_markdown = description.strip.start_with? "#"
+        desc = has_markdown ? description.split("\n") : [description.gsub(/\s+/, " ").strip]
+        Gapic::FormattingUtils.format_doc_lines @api, desc
+      end
+
       def summary
         gem_config(:summary) ||
+          @api.api_metadata.summary ||
           "API Client library for the #{title} API"
       end
 
@@ -143,17 +161,21 @@ module Gapic
       end
 
       def product_documentation_url
-        gem_config :product_documentation_url
+        gem_config(:product_documentation_url) || @api.api_metadata.documentation_url
       end
 
       def api_id
-        raw_id = gem_config :api_id
+        raw_id = gem_config(:api_id) || @api.api_metadata.name
         return nil unless raw_id
         raw_id.include?(".") ? raw_id : "#{raw_id}.googleapis.com"
       end
 
       def api_shortname
-        gem_config :api_shortname
+        gem_config(:api_shortname) || @api.api_metadata.short_name
+      end
+
+      def doc_tag_prefix
+        @api.api_metadata.doc_tag_prefix || api_shortname || api_id&.split(".")&.first
       end
 
       def issue_tracker_url
@@ -185,8 +207,38 @@ module Gapic
       ##
       # @return [Boolean]
       #
+      def rest_numeric_enums?
+        gem_config(:rest_numeric_enums) || false
+      end
+
+      ##
+      # @return [Boolean] Whether the generation of REST clients is requested
+      #    and can be done because at least one method has rest bindings.
+      #
       def generate_rest_clients?
-        @api.generate_rest_clients?
+        @api.generate_rest_clients? && packages.any? { |package| !package.first_service_with_rest.nil? }
+      end
+
+      ##
+      # @return [Boolean] Whether generation of gRPC clients is requested.
+      #
+      def generate_grpc_clients?
+        @api.generate_grpc_clients?
+      end
+
+      ##
+      # @return [:grpc] If gRPC is the default transport
+      # @return [:rest] if REST is the default transport
+      #
+      def default_transport
+        @api.default_transport
+      end
+
+      ##
+      # @return [String] Pretty name of the default transport
+      #
+      def default_transport_name
+        @api.default_transport == :grpc ? "gRPC" : "REST"
       end
 
       def entrypoint_require
@@ -204,11 +256,15 @@ module Gapic
 
       def dependencies
         @dependencies ||= begin
-          deps = { "gapic-common" => [">= 0.7", "< 2.a"] }
-          deps["grpc-google-iam-v1"] = [">= 0.6.10", "< 2.a"] if iam_dependency?
+          deps = { "gapic-common" => "~> 1.0" }
+          deps["grpc-google-iam-v1"] = "~> 1.11" if iam_dependency?
           extra_deps = gem_config_dependencies
-          deps.merge! extra_deps if extra_deps
           deps.merge! mixins_model.dependencies if mixins_model.mixins?
+          # extra deps should be last, overriding mixins or defaults
+          deps.merge! extra_deps if extra_deps
+          # google-iam-v1 is a superset of grpc-google-iam-v1, so if both are
+          # listed, use only google-iam-v1.
+          deps.delete "grpc-google-iam-v1" if deps.include? "google-iam-v1"
           deps
         end
       end
@@ -253,14 +309,13 @@ module Gapic
       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.
+      # Whether the "Enabling Logging" section of the readme should appear.
+      # This is true if there is a quick-start service displayed in the readme.
       #
       # @return [Boolean]
       #
-      def show_grpc_logging_docs?
-        packages? && quick_start_service.usable_service_presenter.is_a?(ServicePresenter)
+      def show_logging_docs?
+        packages? && !quick_start_service.usable_service_presenter.nil?
       end
 
       ##
@@ -293,35 +348,54 @@ module Gapic
       ##
       # There is a special case (from PoV of generator parameters)
       # in gem dependencies where a dependency needs to be an array of strings
-      # e.g. ">= 1.6", "< 2.a"
+      # e.g. `">= 1.6", "< 2.a"``
       # Rather than creating a special generator param case for this I will special-case it here.
-      # '|' is the separator.
-      # The above would be represented as ">= 1.6|< 2.a"
+      # Supported separators are `|` and `+`. The latter is preferred.
+      # Spaces in the version requirements are optional.
+      # The above would be represented as `">=1.6+<2.a"`
       #
       # @return [Hash<String, String>, Hash{String=>Array<String>}, nil]
       def gem_config_dependencies
         return unless gem_config :extra_dependencies
-        gem_config(:extra_dependencies).map do |dep_name, dep_versions|
+        gem_config(:extra_dependencies).transform_values do |dep_versions|
           if dep_versions.include? "|"
-            [dep_name, dep_versions.split("|")]
+            dep_versions.split("|").map { |dep_version| check_dep_version dep_version }
+          elsif dep_versions.include? "+"
+            dep_versions.split("+").map { |dep_version| check_dep_version dep_version }
           else
-            [dep_name, dep_versions]
+            check_dep_version dep_versions
           end
-        end.to_h
+        end
+      end
+
+      def check_dep_version dep_version
+        match = /([>=<~]+)\s*(\d+(?:\.\w+)+)/.match dep_version
+        raise "Bad syntax for extra_dependency: #{dep_version}" unless match
+        "#{match[1]} #{match[2]}"
       end
 
-      def blacklist_protos
-        blacklist = gem_config :blacklist
+      def denylist_protos
+        denylist = gem_config(:denylist) || gem_config(:blacklist)
 
-        return default_blacklist_protos if blacklist.nil?
-        return default_blacklist_protos if blacklist[:protos].nil?
+        return default_denylist_protos if denylist.nil?
+        return default_denylist_protos if denylist[:protos].nil?
 
-        default_blacklist_protos[:protos]
+        default_denylist_protos[:protos]
       end
 
-      def default_blacklist_protos
+      def default_denylist_protos
         ["google/api/http.proto", "google/protobuf/descriptor.proto"]
       end
+
+      def mixin_paths
+        mixins_model.mixins.map(&:require_str)
+      end
+
+      def useful_proto_file? file
+        return false if file.messages.empty? && file.enums.empty?
+        return false if denylist_protos.include? file.name
+        mixin_paths.none? { |m| file.name.start_with? m }
+      end
     end
   end
 end

data/lib/gapic/presenters/message_presenter.rb

@@ -26,9 +26,17 @@ module Gapic
     class MessagePresenter
       include Gapic::Helpers::NamespaceHelper
 
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param api [Gapic::Schema::Api]
+      # @param message [Gapic::Schema::Message]
+      #
       def initialize api, message
         @api = api
         @message = message
+        @type = "message"
       end
 
       def name
@@ -63,6 +71,13 @@ module Gapic
         @nested_messages ||= @message.nested_messages.map { |m| MessagePresenter.new @api, m }
       end
 
+      ##
+      # @return [Boolean] Whether the message is marked as deprecated.
+      #
+      def is_deprecated?
+        @message.is_deprecated?
+      end
+
       protected
 
       def message_ruby_type message

data/lib/gapic/presenters/method/http_binding_presenter.rb

@@ -0,0 +1,128 @@
+# 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.
+
+module Gapic
+  module Presenters
+    module Method
+      ##
+      # A presenter for the Http Binding, used to generate code setting up gRPC transcoding
+      #
+      class HttpBindingPresenter
+        extend Forwardable
+
+        def initialize binding
+          @binding = binding
+        end
+
+        ##
+        # Performs a limited URI transcoding to create a string that will interpolate
+        # the values from the request object to create a request URI at runtime.
+        # Currently only supports "value" into "request_object.value"
+        # @param [String] request_obj_name the name of the request object for the interpolation
+        #   defaults to "request_pb"
+        # @return [String] A string to interpolate values from the request object into URI
+        #
+        def uri_for_transcoding
+          return path unless routing_params?
+
+          @binding.routing_params.reduce path do |uri, param|
+            param_esc = Regexp.escape param
+            uri.gsub(/{#{param_esc}[^}]*}/, "{#{param}}")
+          end
+        end
+
+        ##
+        # The strings to initialize the `matches` parameter when initializing a
+        # grpc transcoder binding. The `matches` parameter is an array of arrays,
+        # so every string here is in a ruby array syntax. All strings except for the
+        # last one have a comma at the end.
+        #
+        # @return [Array<String>]
+        #
+        def routing_params_transcoder_matches_strings
+          return [] if routing_params_with_regexes.empty?
+          match_init_strings = routing_params_with_regexes.map do |name, regex, preserve_slashes|
+            "[\"#{name}\", %r{#{regex}}, #{preserve_slashes}],"
+          end
+          match_init_strings << match_init_strings.pop.chop # remove the trailing comma for the last element
+          match_init_strings
+        end
+
+        ##
+        # The strings to initialize the `bindings` parameter when initializing a
+        # gapic http binding. The `bindings` parameter is an array of FieldBinding objects,
+        # All strings except for the last one have a comma at the end.
+        #
+        # @return [Array<String>]
+        #
+        def routing_params_transcoder_field_binding_strings
+          return [] if routing_params_with_regexes.empty?
+          match_init_strings = routing_params_with_regexes.map do |name, regex, preserve_slashes|
+            "Gapic::Rest::GrpcTranscoder::HttpBinding::FieldBinding" \
+              ".new(\"#{name}\", %r{#{regex}}, #{preserve_slashes}),"
+          end
+          match_init_strings << match_init_strings.pop.chop # remove the trailing comma for the last element
+          match_init_strings
+        end
+
+        # @!method verb?
+        #   @return [Boolean]
+        #     Whether a http verb is present for this binding.
+        # @!method verb
+        #   @return [String]
+        #     The http verb for this binding.
+        # @!method path?
+        #   @return [Boolean]
+        #     Whether a binding path is present and non-empty.
+        # @!method path
+        #   @return [String]
+        #     A binding path or an empty string if not present.
+        # @!method routing_params?
+        #   @return [Boolean]
+        #     Whether any routing params are present for this bindings.
+        # @!method body?
+        #   @return [Boolean]
+        #     Whether the binding has a `body` specified.
+        # @!method body
+        #   @return [String]
+        #     The `body` specified for this binding
+        #     or an empty string if not specified.
+        def_delegators :@binding, :verb?, :verb, :path?, :path, :routing_params?, :body?, :body
+
+        private
+
+        ##
+        # The segment key names, the regexes for their patterns (including
+        # the regexes for `*` patterns implied for the named segments without
+        # pattern explicitly specified), and whether the slash `/` symbols in
+        # the segment variable should be preserved (as opposed to percent-escaped).
+        #
+        # These are used to initialize the grpc transcoder `matches` binding parameter.
+        #
+        # @return [Array<Array<String|Boolean>>]
+        #
+        def routing_params_with_regexes
+          @routing_params_with_regexes ||= begin
+            @binding.routing_params_with_patterns.map do |name, pattern|
+              path_pattern = PathPattern.parse pattern
+              [name, path_pattern.to_field_regex_str, path_pattern.ends_with_double_star_pattern?]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/presenters/method/rest_pagination_info.rb

@@ -109,7 +109,7 @@ module Gapic
         def request_page_token_field
           # Has a String page_token field which specifies the actual (next) page to retrieve.
           @request_page_token_field ||= @request.fields.find do |f|
-            f.name == "page_token" && f.type == Google::Protobuf::FieldDescriptorProto::Type::TYPE_STRING
+            f.name == "page_token" && f.type == :TYPE_STRING
           end
         end
 
@@ -125,10 +125,7 @@ module Gapic
 
               # Has the int32 page_size or int32 max_results field
               # which defines the maximum number of paginated resources to return in the response.
-              page_size_types = [
-                Google::Protobuf::FieldDescriptorProto::Type::TYPE_UINT32,
-                Google::Protobuf::FieldDescriptorProto::Type::TYPE_INT32
-              ]
+              page_size_types = [:TYPE_UINT32, :TYPE_INT32]
 
               field = @request.fields.find do |f|
                 page_size_names.include?(f.name) && page_size_types.include?(f.type)
@@ -156,7 +153,7 @@ module Gapic
         def response_next_page_token_field
           # Has the string next_page_token field to be used in the next request as page_token to retrieve the next page.
           @response_next_page_token_field ||= @response.fields.find do |f|
-            f.name == "next_page_token" && f.type == Google::Protobuf::FieldDescriptorProto::Type::TYPE_STRING
+            f.name == "next_page_token" && f.type == :TYPE_STRING
           end
         end
 
@@ -169,8 +166,7 @@ module Gapic
           @response_results_field ||= begin
             map_fields = @response.fields.find_all(&:map?)
             repeated_fields = @response.fields.find_all do |f|
-              !f.map? &&
-                f.label == Google::Protobuf::FieldDescriptorProto::Label::LABEL_REPEATED
+              !f.map? && f.label == :LABEL_REPEATED
             end
 
             if map_fields.count == 1
@@ -187,6 +183,26 @@ module Gapic
           end
         end
 
+        # @private
+        FIELD_TYPE_MAPPING = {
+          TYPE_DOUBLE: "::Float",
+          TYPE_FLOAT: "::Float",
+          TYPE_INT64: "::Integer",
+          TYPE_UINT64: "::Integer",
+          TYPE_INT32: "::Integer",
+          TYPE_FIXED64: "::Integer",
+          TYPE_FIXED32: "::Integer",
+          TYPE_BOOL: "::Boolean",
+          TYPE_STRING: "::String",
+          TYPE_BYTES: "::String",
+          TYPE_UINT32: "::Integer",
+          TYPE_SFIXED32: "::Integer",
+          TYPE_SFIXED64: "::Integer",
+          TYPE_SINT32: "::Integer",
+          TYPE_SINT64: "::Integer"
+        }.freeze
+        private_constant :FIELD_TYPE_MAPPING
+
         ##
         # A helper to get a Ruby doc-type for a paginated element.
         #
@@ -201,14 +217,7 @@ module Gapic
             # TODO: handle when arg message is nil and enum is the type
             message_ruby_type field.enum
           else
-            case field.type
-            when 1, 2                              then "::Float"
-            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
-            when 9, 12                             then "::String"
-            when 8                                 then "::Boolean"
-            else
-              "::Object"
-            end
+            FIELD_TYPE_MAPPING[field.type] || "::Object"
           end
         end