gapic-generator 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61762b2051b75312bfc67ef070e136d8cf95cad1635e1b22270ed8a5b6cfbc99
-  data.tar.gz: cd867c0065831c6b5252dc0b5097417f24a74716f4e15cd243a1371ac80e5a5d
+  metadata.gz: 36abe40caa29f9c1368fc86632e1c57703d98346ab5dd70ad1a87ba7e73b277c
+  data.tar.gz: 60479a28e6d38873d21f06200f554e874ae2df926929e6eaef0a33e9b3099de5
 SHA512:
-  metadata.gz: b8c833fe9bbb2d35c8fb0e7b307e1f0aeb0f5774fe0f174e2505bc0460fcc13ae06bf6e2761fe1e00d7e44079327fbc761f7423b72c51e58ef23c4f4220edebb
-  data.tar.gz: 89e7871eac1c9e01d870c2e367e67e16ac5c49580259d828c922324250a88955da88014496a8da7ff22964e18941046153158df4d8a023a7fb9a158a86c06cea
+  metadata.gz: 970f3a69d280a1cdad3bd53554d48d89524528ae65033e9a469ce4be3ccd9da83d8bd1bb4a28a6d45d9989456398b8421876eaaa39e1eaf179e28573b6ded107
+  data.tar.gz: 41b9678039126730f3295f63cdd20d298516060b3965091888c47cec944863f7dba01d7d5254327c13477053bdcc4425e500a42cf63e620befda2addb0e85c7b

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Release History for gapic-generator
 
+### 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

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.9.1"
+    VERSION = "0.10.0"
   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

@@ -192,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
@@ -239,6 +239,17 @@ 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
+
       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?

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,54 @@ 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_type
+      end
+
+      ##
+      # Whether the REGAPIC method should be rendered as paged
+      #
+      # @return [Boolean]
+      #
+      def paged?
+        @pagination.paged?
       end
     end
   end