gapic-generator 0.8.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c8a401f416529802324b86833c5c3a9fcef01afd699439053ce868a7862c5c8
-  data.tar.gz: 6f794cc05eb33a4c201bdcc62dc62524406ae2fb003f0b2d9c536482517a4109
+  metadata.gz: 8fa15ffab6c84ed42f1e5801ba4481fa755040e69ead95a652a2ab7e611c44e6
+  data.tar.gz: 8290eb8ae3394afe98876ae03b0ca74b6ef51ca4af9d74537b177c472a44402f
 SHA512:
-  metadata.gz: 536731d9a866b0c58540b6eb6f62469eef75f10f82a9fba3c45e0e5a2c5d08b7f5b97b0b385b3e6063e418e0faba687faf45c44cc700ab69da554c9d28a46049
-  data.tar.gz: c1b99ad4ebfae8c4085522924ba4fd11f1a2628b67d64dfc549f22df40aadf5d79ae127bcac73ca5fe2795937f29556b6f656d5b86c66aaef43c78ec644b6772
+  metadata.gz: 6a3d25f24e6c43fd8b52b8ade6b520109b854660ea1d5aa9bdf8afa14802be85de8d47357deb9a5039a34c0e3b466d4228d05da5d5dbb78981065c46270ff682
+  data.tar.gz: 31c64a0bccabf7a9077c720185b425ac77e443b17cc86ea78ae222e82d0b3237a607ca744ee3488aede394dcf1446dd5da4ad58cb2be3c8a76942905a6e34b7f

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Release History for gapic-generator
 
+### 0.10.1 / 2021-08-27
+
+* New: Compute REST libraries are now generated with LRO wrappers
+* Fixed: Rubocop is disabled for sample tests in generated versioned libraries
+
+### 0.10.0 / 2021-08-09
+
+* New: Enabled per-RPC configuration for generated REST libraries
+* New: Generated docs include the deprecated YARD tag for deprecated protos
+* New: Scopes can be passed to self-signed JWTs
+* Fixed: Generated gRPC clients honor the client-default timeout config
+* Fixed: Generated docs now use YARD example tags for inline samples related to configuration
+* Fixed: Generated REST clients now require google/cloud/errors
+* Generated libraries now require gapic-common 0.7.0 or later
+
+### 0.9.2 / 2021-07-27
+
+* REST libraries are now generated with pagination hepers
+* REST libraries are now generated with correct examples in README.md and other documentation files
+* It is now possible to generate inline snippets in yardocs
+* Fixed the require path in the generated standalone snippets so it reflects the recommended require root rather than the service-specific require path.
+* Prevent "duplicate" resources (with the same name but different namespaces) from producing duplicate helper methods.
+
+### 0.9.1 / 2021-07-07
+
+* Detect multiple resource parents for patterns used by multiple resources
+
+### 0.9.0 / 2021-06-29
+
+* Support for configuring the service/method used for the quickstart example
+* Allow generation of libraries with no custom env prefix
+* Add service override setting to the repo metadata
+* Wrapper gem dependencies on pre-GA versioned gems now allow both 0.x and 1.x versions
+* Scoped some String and Hash references to the global scope to avoid name collisions
+* Reformat some config code to avoid rubocop indentation churn
+* Bazel: Replace monolith deps with rules_gapic
+
 ### 0.8.0 / 2021-06-16
 
 * Initial implementation of standalone snippet generation.

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.8.0"
+    VERSION = "0.10.1"
   end
 end

data/lib/gapic/generators/default_generator.rb

@@ -60,7 +60,7 @@ module Gapic
             files << g("service/paths.erb",                  "lib/#{service.paths_file_path}",                   service: service) if service.paths?
             files << g("service/operations.erb",             "lib/#{service.operations_file_path}",              service: service) if service.lro? && !@api.generate_rest_clients?
             files << g("service/rest/client.erb",            "lib/#{service.rest.client_file_path}",             service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
-            files << g("service/rest/grpc_transcoding.erb",  "lib/#{service.rest.transcoding_helper_file_path}", service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
+            files << g("service/rest/service_stub.erb",      "lib/#{service.rest.service_stub_file_path}",       service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
             files << g("service/rest/test/client.erb",       "test/#{service.rest.test_client_file_path}",       service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
             files << g("service/test/client.erb",            "test/#{service.test_client_file_path}",            service: service) unless @api.generate_rest_clients?
             files << g("service/test/client_paths.erb",      "test/#{service.test_paths_file_path}",             service: service) if service.paths?

data/lib/gapic/generators/default_generator_parameters.rb

@@ -24,7 +24,9 @@ module Gapic
         ":gem.:free_tier",
         ":gem.:yard_strict",
         ":gem.:generic_endpoint",
-        ":generate_metadata"
+        ":generate_metadata",
+        ":generate_standalone_snippets",
+        ":generate_yardoc_snippets"
       ].freeze
 
       STRING_PARAMETERS = [

data/lib/gapic/presenters/gem_presenter.rb

@@ -127,11 +127,7 @@ module Gapic
       end
 
       def env_prefix
-        prefix = gem_config(:env_prefix) || begin
-          segs = name.split("-").reverse
-          segs.find { |seg| seg !~ /^v\d/ } || segs.first || "UNKNOWN"
-        end
-        prefix.upcase
+        gem_config(:env_prefix)&.upcase
       end
 
       def iam_dependency?
@@ -196,7 +192,7 @@ 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
@@ -231,6 +227,29 @@ module Gapic
         JSON.pretty_generate first_package_drift_manifest
       end
 
+      ##
+      # The service to use for quick start samples. Normally this is simply the
+      # {#first_non_common_service}, but it can be overridden via a gem config.
+      #
+      # @return [Gapic::Presenters::ServicePresenter]
+      #
+      def quick_start_service
+        preferred_service = gem_config :quick_start_service
+        result = services.find { |svc| svc.name == preferred_service } if preferred_service
+        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
+
       private
 
       def gem_config key

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

@@ -0,0 +1,246 @@
+# 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 Presenters
+    module Method
+      ##
+      # Pagination info determined from the proto method
+      #
+      class RestPaginationInfo
+        include Gapic::Helpers::NamespaceHelper
+        ##
+        # @param proto_method [Gapic::Schema::Method] the method to derive pagination info from
+        # @param api [Gapic::Schema::Api]
+        #
+        def initialize proto_method, api
+          @api = api
+          @request = proto_method.input
+          @response = proto_method.output
+          @server_streaming = proto_method.server_streaming
+        end
+
+        ##
+        # Whether the method should be generated as paged
+        #
+        # @return [Boolean]
+        def paged?
+          !server_streaming? && paged_request? && paged_response?
+        end
+
+        ##
+        # Name of the request's field used for page size
+        # For Regapic can be either `page_size` or `max_results`
+        #
+        # @return [String, nil]
+        def request_page_size_name
+          request_page_size_field&.name
+        end
+
+        ##
+        # Name of the repeated field in the response message
+        # For REST gapics can be either a vanilla repeated field or a map
+        #
+        # @return [String, nil]
+        def response_repeated_field_name
+          response_results_field&.name
+        end
+
+        ##
+        # Whether the repeated field in the response message is a map
+        #
+        # @return [Boolean, nil]
+        def repeated_field_is_a_map?
+          response_results_field&.map?
+        end
+
+        ##
+        # Proto type of the repeated field in the response message
+        #
+        # @return [String, nil]
+        def paged_element_doc_type
+          return nil if response_results_field.nil?
+          field_paginated_elem_doc_type response_results_field
+        end
+
+        private
+
+        # Whether the underlying proto rpc is a server streaming rpc
+        # @return [Boolean]
+        attr_accessor :server_streaming
+
+        ##
+        # Whether the underlying proto rpc is a server streaming rpc
+        #
+        # @return [Boolean]
+        def server_streaming?
+          @server_streaming
+        end
+
+        ##
+        # Whether the request message for the REGAPIC rpc satisfies the criteria
+        # for the rpc to be classified and implemented as paged
+        #
+        # @return [Boolean]
+        def paged_request?
+          # Has a String page_token field which specifies the actual (next) page to retrieve.
+          # Has an int32 page_size or int32 max_results field
+          # which defines the maximum number of paginated resources to return in the response.
+          !request_page_token_field.nil? && !request_page_size_field.nil?
+        end
+
+        ##
+        # The field in the request that holds a page_token
+        #
+        # @return[Gapic::Schema::Field, nil]
+        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
+          end
+        end
+
+        ##
+        # The field in the request that holds a page_size
+        # For Regapic can have a name of either `page_size` or `max_results`
+        #
+        # @return[Gapic::Schema::Field, nil]
+        def request_page_size_field
+          @request_page_size_field ||=
+            begin
+              page_size_names = ["page_size", "max_results"]
+
+              # 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
+              ]
+
+              field = @request.fields.find do |f|
+                page_size_names.include?(f.name) && page_size_types.include?(f.type)
+              end
+
+              field
+            end
+        end
+
+        ##
+        # Whether the response message for the REGAPIC rpc satisfies the criteria
+        # for the rpc to be classified and implemented as paged
+        #
+        # @return [Boolean]
+        def paged_response?
+          # Has the string next_page_token field to be used in the next request as page_token to retrieve the next page.
+          # Has only one repeated or map<string, ?> field containing a list of paginated resources.
+          !response_next_page_token_field.nil? && !response_results_field.nil?
+        end
+
+        ##
+        # The field in the response that holds a next page_token
+        #
+        # @return[Gapic::Schema::Field, nil]
+        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
+          end
+        end
+
+        ##
+        # The field in the response that holds the results
+        # For Regapic can be either a vanilla repeated field or a map
+        #
+        # @return [Gapic::Schema::Field, nil]
+        def response_results_field
+          @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
+            end
+
+            if map_fields.count == 1
+              # If the response message has only one map<string, ?> field
+              # treat it as the one with paginated resources (i.e. ignore the repeated fields if any).
+              map_fields.first
+            elsif repeated_fields.count == 1 && map_fields.empty?
+              # If the response message contains only one repeated field,
+              # treat that field as the one containing the paginated resources.
+              repeated_fields.first
+            end
+            # If the response message contains more than one repeated field or does not have repeated fields at all
+            # but has more than one map<string, ?> field, do not generate any paginated methods for such rpc.
+          end
+        end
+
+        ##
+        # A helper to get a Ruby doc-type for a paginated element.
+        #
+        # @param field [Gapic::Schema::Field]
+        #
+        # @return [String]
+        def field_paginated_elem_doc_type field
+          return field_paginated_elem_map_type field if field.map?
+          if field.message?
+            message_ruby_type field.message
+          elsif field.enum?
+            # 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
+          end
+        end
+
+        ##
+        # A helper to get a Ruby doc-type for a proto map's paginated element.
+        #
+        # @param field [Gapic::Schema::Field]
+        #
+        # @return [String]
+        def field_paginated_elem_map_type field
+          key_field = field.map_key_field
+          value_field = field.map_val_field
+
+          if key_field && value_field
+            key_type = field_paginated_elem_doc_type key_field
+            value_type = field_paginated_elem_doc_type value_field
+            "#{key_type}, #{value_type}"
+          else
+            class_name
+          end
+        end
+
+        ##
+        # A helper to get a Ruby type for a proto message.
+        #
+        # @param message [Gapic::Schema::Message]
+        #
+        # @return [String]
+        def message_ruby_type message
+          ruby_namespace @api, message.address.join(".")
+        end
+      end
+    end
+  end
+end

data/lib/gapic/presenters/method_presenter.rb

@@ -40,7 +40,7 @@ module Gapic
         @service_presenter = service_presenter
         @api = api
         @method = method
-        @rest = MethodRestPresenter.new self
+        @rest = MethodRestPresenter.new self, api
       end
 
       ##
@@ -54,6 +54,10 @@ module Gapic
         SnippetPresenter.new self, @api
       end
 
+      def generate_yardoc_snippets?
+        @api.generate_yardoc_snippets?
+      end
+
       def name
         @name ||= begin
           candidate = ActiveSupport::Inflector.underscore @method.name
@@ -93,6 +97,13 @@ module Gapic
         ret
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def is_deprecated?
+        @method.is_deprecated?
+      end
+
       def arguments
         arguments = @method.input.fields.reject(&:output_only?)
         arguments.map { |arg| FieldPresenter.new @api, @method.input, arg }
@@ -175,7 +186,7 @@ module Gapic
       def lro?
         return paged_response_type == "::Google::Longrunning::Operation" if paged?
 
-        message_ruby_type(@method.output) == "::Google::Longrunning::Operation"
+        return_type == "::Google::Longrunning::Operation"
       end
 
       def client_streaming?
@@ -232,6 +243,10 @@ module Gapic
         end
       end
 
+      def service_config_presenter
+        ServiceConfigPresenter.new grpc_service_config
+      end
+
       def grpc_method_name
         @method.name
       end

data/lib/gapic/presenters/method_rest_presenter.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/presenters/method/rest_pagination_info"
 require "gapic/uri_template"
 
 module Gapic
@@ -22,9 +23,19 @@ module Gapic
     # A presenter for rpc methods (REST submethods)
     #
     class MethodRestPresenter
-      def initialize main_method
+      # @return [Gapic::Presenters::Method::RestPaginationInfo]
+      attr_reader :pagination
+
+      ##
+      # @param main_method [Gapic::Presenters::MethodPresenter] the main presenter for this method.
+      # @param api [Gapic::Schema::Api]
+      #
+      def initialize main_method, api
+        @api = api
         @main_method = main_method
         @proto_method = main_method.method
+
+        @pagination = Gapic::Presenters::Method::RestPaginationInfo.new @proto_method, api
       end
 
       ##
@@ -187,7 +198,69 @@ module Gapic
       #
       # @return [String]
       def transcoding_helper_name
-        "transcode_#{@main_method.name}"
+        "transcode_#{name}_request"
+      end
+
+      ##
+      # Method name
+      #
+      # @return [String]
+      #
+      def name
+        @main_method.name
+      end
+
+      ##
+      # Full class name of the request type
+      #
+      # @return [String]
+      #
+      def request_type
+        @main_method.request_type
+      end
+
+      ##
+      # Full class name of the raw return type of the RPC
+      #
+      # @return [String]
+      #
+      def return_type
+        @main_method.return_type
+      end
+
+      ##
+      # Full class name of the return type of the method
+      # (including LRO and Paged cases)
+      #
+      # @return [String]
+      #
+      def doc_response_type
+        return "::Gapic::Rest::PagedEnumerable<#{pagination.paged_element_doc_type}>" if paged?
+        return "::Gapic::Rest::BaseOperation" if lro?
+        return_type
+      end
+
+      ##
+      # Whether the REGAPIC method should be rendered as paged
+      #
+      # @return [Boolean]
+      #
+      def paged?
+        @pagination.paged?
+      end
+
+      ##
+      # Whether the REGAPIC method should be rendered as LRO
+      # [TODO (virost, 2021-08) Update this when DiReGapic LRO annotations are added to the Compute protos]
+      #
+      # @return [Boolean]
+      #
+      def lro?
+        return_type == "::Google::Cloud::Compute::V1::Operation" &&
+          @main_method.service.name != "ZoneOperations" &&
+          @main_method.service.name != "RegionOperations" &&
+          @main_method.service.name != "GlobalOperations" &&
+          @main_method.service.name != "GlobalOrganizationOperations"
       end
     end
   end