gapic-generator 0.9.1 → 0.11.0

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

@@ -32,6 +32,15 @@ module Gapic
       # @return [Gapic::Presenters::MethodRestPresenter]
       attr_accessor :rest
 
+      # @return [Gapic::Model::Method::Routing]
+      attr_accessor :routing
+
+      # @return [Gapic::Model::Method::HttpAnnotation]
+      attr_accessor :http
+
+      # @return [Gapic::Model::Method::AipLro, Gapic::Model::Method::NonStandardLro, Gapic::Model::Method::NoLro]
+      attr_accessor :lro
+
       ##
       # @param service_presenter [Gapic::Presenters::ServicePresenter]
       # @param api [Gapic::Schema::Api]
@@ -40,7 +49,11 @@ module Gapic
         @service_presenter = service_presenter
         @api = api
         @method = method
-        @rest = MethodRestPresenter.new self
+        @http = Gapic::Model::Method::HttpAnnotation.new @method
+        @routing = Gapic::Model::Method::Routing.new @method.routing, http
+        @lro = Gapic::Model::Method.parse_lro @method, api
+
+        @rest = MethodRestPresenter.new self, api
       end
 
       ##
@@ -50,10 +63,17 @@ module Gapic
         @service_presenter
       end
 
+      ##
+      # @return [Gapic::Presenters::SnippetPresenter]
+      #
       def snippet
         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 +113,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 }
@@ -172,10 +199,34 @@ module Gapic
         sample_configs.map { |sample_config| SamplePresenter.new @api, sample_config }
       end
 
+      ##
+      # Whether this method uses standard (AIP-151) LROs
+      #
+      # @return [Boolean]
+      #
       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
+
+      ##
+      # Whether this method uses nonstandard LROs
+      #
+      # @return [Boolean]
+      #
+      def nonstandard_lro?
+        @lro.nonstandard_lro?
+      end
+
+      ##
+      # The presenter for the nonstandard LRO client of the kind this method uses
+      #
+      # @return [Gapic::Presenters::Service::LroClientPresenter, nil]
+      #
+      def nonstandard_lro_client
+        return unless nonstandard_lro?
+        service.nonstandard_lros.find { |model| model.service == @lro.service_full_name }
       end
 
       def client_streaming?
@@ -222,7 +273,7 @@ module Gapic
       # @return [Boolean] Whether any routing params are present
       #
       def routing_params?
-        rest.routing_params?
+        @routing.routing_params?
       end
 
       def grpc_service_config
@@ -232,8 +283,8 @@ module Gapic
         end
       end
 
-      def service_config_presenter
-        ServiceConfigPresenter.new grpc_service_config
+      def grpc_service_config_presenter
+        GrpcServiceConfigPresenter.new grpc_service_config
       end
 
       def grpc_method_name

data/lib/gapic/presenters/method_rest_presenter.rb

@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "gapic/uri_template"
+require "gapic/presenters/method/rest_pagination_info"
 
 module Gapic
   module Presenters
@@ -22,68 +22,62 @@ 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
+        @http = main_method.http
+
+        @pagination = Gapic::Presenters::Method::RestPaginationInfo.new @proto_method, api
       end
 
       ##
       # @return [Boolean] Whether a http verb is present for this method
       #
       def verb?
-        !verb.nil?
+        @http.verb?
       end
 
       ##
       # @return [Symbol] a http verb for this method
       #
       def verb
-        return nil if @proto_method.http.nil?
-
-        method = {
-          get:    @proto_method.http.get,
-          post:   @proto_method.http.post,
-          put:    @proto_method.http.put,
-          patch:  @proto_method.http.patch,
-          delete: @proto_method.http.delete
-        }.find { |_, value| !value.empty? }
-
-        method[0] unless method.nil?
+        @http.verb
       end
 
       ##
       # @return [Boolean] Whether a method path is present and non-empty
       #
       def path?
-        !path.empty?
-      end
-
-      ##
-      # @return [String] A method path or an empty string if not present
-      #
-      def path
-        return "" if @proto_method.http.nil?
-
-        verb_path = [
-          @proto_method.http.get, @proto_method.http.post, @proto_method.http.put,
-          @proto_method.http.patch, @proto_method.http.delete
-        ].find { |x| !x.empty? }
-
-        verb_path || @proto_method.http.custom&.path || ""
+        @http.path?
       end
 
       ##
       # @return [Boolean] Whether any routing params are present
       #
       def routing_params?
-        routing_params.any?
+        @http.routing_params?
       end
 
       ##
       # @return [Array<String>] The segment key names.
       #
       def routing_params
-        Gapic::UriTemplate.parse_arguments path
+        @http.routing_params
+      end
+
+      ##
+      # @return [Boolean] Whether method has body specified in proto
+      #
+      def body?
+        @http.body?
       end
 
       ##
@@ -103,15 +97,6 @@ module Gapic
         end
       end
 
-      ##
-      # @return [Boolean] Whether method has body specified in proto
-      #
-      def body?
-        return false if @proto_method.http.nil?
-
-        !@proto_method.http.body.empty?
-      end
-
       ##
       # Name of the variable to use for storing the body result of the transcoding call
       # Normally "body" but use "_body" for discarding the result for
@@ -121,13 +106,6 @@ module Gapic
         body? ? "body" : "_body"
       end
 
-      ##
-      # @return [String] A body specified for the given method in proto or an empty string if not specified
-      #
-      def body
-        @proto_method.http&.body || ""
-      end
-
       ##
       # @return [Boolean] True if body contains full request object (`*` in the annotation), false otherwise
       #
@@ -187,7 +165,80 @@ 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::GenericLRO::Operation" if nonstandard_lro?
+        return_type
+      end
+
+      ##
+      # Whether the REGAPIC method should be rendered as paged
+      #
+      # @return [Boolean]
+      #
+      def paged?
+        @pagination.paged?
+      end
+
+      ##
+      # Whether this method uses nonstandard LROs
+      #
+      # @return [Boolean]
+      #
+      def nonstandard_lro?
+        @main_method.nonstandard_lro?
+      end
+
+      private
+
+      ##
+      # @return [String] A method path or an empty string if not present
+      #
+      def path
+        @http.path
+      end
+
+      ##
+      # @return [String] A body specified for the given method in proto or an empty string if not specified
+      #
+      def body
+        @http.body
       end
     end
   end

data/lib/gapic/presenters/resource_presenter.rb

@@ -33,6 +33,10 @@ module Gapic
         @patterns.filter!(&:useful_for_helpers?)
       end
 
+      def dup
+        ResourcePresenter.new @resource
+      end
+
       def name
         @resource.type.split("/").delete_if(&:empty?).last
       end
@@ -62,6 +66,10 @@ module Gapic
         attr_reader :pattern
         attr_reader :path_string
 
+        def pattern_template
+          @parsed_pattern.template
+        end
+
         def useful_for_helpers?
           !@parsed_pattern.positional_segments? && !@parsed_pattern.nontrivial_pattern_segments?
         end

data/lib/gapic/presenters/service/lro_client_presenter.rb

@@ -0,0 +1,90 @@
+# 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 Service
+      ##
+      # Presenter for the generation of the client for nonstandard LROs
+      #
+      # @!attribute [r] service
+      #   Full name of the service providing the nonstandard LRO functionality
+      #   @return [String]
+      # @!attribute [r] client_class_name
+      #   Full name of the class of the 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_var_name
+      #   Name for the variable for the client of the service
+      #   @return [String]
+      # @!attribute [r] require_str
+      #   Path to `require` the client of the service
+      #   @return [String]
+      # @!attribute [r] service_description
+      #   The description to place in the comments to this client's
+      #   attribute in the library services's client class
+      #   @return [String]
+      # @!attribute [r] helper_type
+      #   The type of a helper generated for this service if any
+      #   @return [String. nil]
+      #
+      class LroClientPresenter
+        attr_reader :service
+        attr_reader :client_class_name
+        attr_reader :client_class_docname
+        attr_reader :client_var_name
+        attr_reader :require_str
+        attr_reader :service_description
+        attr_reader :helper_type
+
+        ##
+        # @param service [String]
+        #   Full name of the service providing the nonstandard LRO functionality
+        # @param client_class_name [String]
+        #   Full name of the class of the client of the service
+        # @param client_class_docname [String]
+        #   Name of the class as it should appear in the documentation
+        # @param client_var_name [String]
+        #   Name for the variable for the client of the service
+        # @param require_str [String]
+        #   Path to `require` the client of the service
+        # @param service_description [String]
+        #   The description to place in the comments to this client's
+        #   attribute in the library services's client class
+        # @param helper_type [String, nil]
+        #   The type of a helper generated for this service if any
+        #
+        def initialize service:,
+                       client_class_name:,
+                       client_class_docname:,
+                       client_var_name:,
+                       require_str:,
+                       service_description:,
+                       helper_type: nil
+          @service = service
+          @client_class_name = client_class_name
+          @client_class_docname = client_class_docname
+          @client_var_name = client_var_name
+          @require_str = require_str
+          @service_description = service_description
+          @helper_type = helper_type
+        end
+      end
+    end
+  end
+end