gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/presenters/snippet_presenter.rb

@@ -15,6 +15,17 @@
 # limitations under the License.
 
 require "active_support/inflector"
+require "google/cloud/tools/snippetgen/configlanguage/v1/snippet_config_language_pb"
+require "gapic/presenters/snippet/client_call_presenter"
+require "gapic/presenters/snippet/client_initialization_presenter"
+require "gapic/presenters/snippet/declaration_presenter"
+require "gapic/presenters/snippet/expression_presenter"
+require "gapic/presenters/snippet/iteration_presenter"
+require "gapic/presenters/snippet/parameter_presenter"
+require "gapic/presenters/snippet/request_initialization_presenters"
+require "gapic/presenters/snippet/response_handling_presenters"
+require "gapic/presenters/snippet/statement_presenter"
+require "gapic/presenters/snippet/type_presenter"
 
 module Gapic
   module Presenters
@@ -22,17 +33,27 @@ module Gapic
     # A presenter for snippets.
     #
     class SnippetPresenter
-      def initialize method_presenter, api
+      def initialize method_presenter, api, config: nil, transport: nil
         @method_presenter = method_presenter
         @api = api
+        @config = config
+        @transport = transport || @api.default_transport
+        analyze_config
+      end
+
+      attr_reader :config
+      attr_reader :transport
+
+      def config?
+        !config.nil?
       end
 
       def client_streaming?
         @method_presenter.client_streaming?
       end
 
-      def bidi_streaming?
-        @method_presenter.client_streaming? && @method_presenter.server_streaming?
+      def server_streaming?
+        @method_presenter.server_streaming?
       end
 
       def response_kind
@@ -48,7 +69,7 @@ module Gapic
       end
 
       def snippet_file_path
-        "#{@method_presenter.service.service_require.split('/').last}/#{@method_presenter.name}.rb"
+        "#{@method_presenter.service.service_require.split('/').last}/#{snippet_method_name}.rb"
       end
 
       def require_path
@@ -56,7 +77,13 @@ module Gapic
       end
 
       def client_type
-        @method_presenter.service.client_name_full.sub(/^::/, "")
+        service = @method_presenter.service
+        service = service.rest if transport == :rest
+        service.client_name_full.sub(/^::/, "")
+      end
+
+      def service_name_short
+        @method_presenter.service.module_name
       end
 
       def request_type
@@ -82,21 +109,184 @@ module Gapic
         @method_presenter.name
       end
 
+      def snippet_method_name
+        config? ? "#{method_name}_#{snake_config_id}" : method_name
+      end
+
+      def snippet_name
+        @config&.metadata&.snippet_name ||
+          "Snippet for the #{method_name} call in the #{service_name_short} service"
+      end
+
+      def description
+        @config&.metadata&.snippet_description ||
+          "This is an auto-generated example demonstrating basic usage of #{client_type}##{method_name}."
+      end
+
+      def disclaimer
+        "This snippet has been automatically generated and should be regarded as a code template only. " \
+          "It will require modifications to work:\n" \
+          "- It may require correct/in-range values for request initialization.\n" \
+          "- It may require specifying regional endpoints when creating the service client as shown in https://cloud.google.com/ruby/docs/reference."
+      end
+
+      def snippet_method_parameters
+        @snippet_method_parameters ||= begin
+          parameters_proto = @config&.signature&.parameters
+          if parameters_proto
+            parameters_json = @config.json_representation["signature"]["parameters"]
+            parameters_proto.each_with_index.map do |param_proto, index|
+              ParameterPresenter.new param_proto, parameters_json[index]
+            end
+          else
+            []
+          end
+        end
+      end
+
+      def snippet_method_parameters_render
+        return "" if snippet_method_parameters.empty?
+        names = snippet_method_parameters.map { |param| "#{param.name}:" }.join ", "
+        "(#{names})"
+      end
+
+      attr_reader :client_initialization
+      attr_reader :request_initialization
+      attr_reader :client_call
+      attr_reader :response_handling
+      attr_reader :final_statements
+
       def region_tag
         gem_presenter = @method_presenter.service.gem
-        api_id = gem_presenter.api_shortname || gem_presenter.api_id&.split(".")&.first
+        prefix = gem_presenter.doc_tag_prefix
         names = gem_presenter.name.split "-"
         final_name = names.pop
         if final_name =~ /^v\d/
           api_version = final_name
-          api_id ||= names.last
+          prefix ||= names.last
         else
-          api_id ||= final_name
+          prefix ||= final_name
           api_version = "v0"
         end
+        prefix = prefix.downcase.gsub(/[^a-z0-9]/, "")
         service_name = @method_presenter.service.module_name
         method_name = @method_presenter.method.name
-        "#{api_id}_#{api_version}_generated_#{service_name}_#{method_name}_sync"
+        type = config? ? "config" : "generated"
+        config_id = config? ? "#{@config.metadata.config_id}_" : ""
+        "#{prefix}_#{api_version}_#{type}_#{service_name}_#{method_name}_#{config_id}sync"
+      end
+
+      private
+
+      def analyze_config
+        snippet_proto, snippet_json = snippet_proto_info
+        call_proto, call_json = call_proto_info snippet_proto, snippet_json
+        @client_initialization = build_client_initialization_presenter snippet_proto, snippet_json
+        @request_initialization = build_request_initialization_presenter call_proto, call_json
+        @response_handling = build_response_handling_presenter call_proto, call_json
+        @client_call = build_client_call_presenter call_proto, call_json,
+                                                   @request_initialization.request_name,
+                                                   @response_handling.response_name
+        @final_statements = build_final_statements snippet_proto, snippet_json
+      end
+
+      def snippet_proto_info
+        [@config&.snippet, @config&.json_representation&.fetch("snippet", nil)]
+      end
+
+      def call_proto_info snippet_proto, snippet_json
+        if snippet_proto&.standard
+          [snippet_proto.standard, snippet_json["standard"]]
+        elsif snippet_proto&.paginated
+          [snippet_proto.paginated, snippet_json["paginated"]]
+        elsif snippet_proto&.lro
+          [snippet_proto.lro, snippet_json["lro"]]
+        elsif snippet_proto&.server_streaming
+          [snippet_proto.server_streaming, snippet_json["serverStreaming"]]
+        elsif snippet_proto&.client_streaming
+          [snippet_proto.client_streaming, snippet_json["clientStreaming"]]
+        elsif snippet_proto&.bidi_streaming
+          [snippet_proto.bidi_streaming, snippet_json["bidiStreaming"]]
+        else
+          [nil, nil]
+        end
+      end
+
+      def build_client_initialization_presenter snippet_proto, snippet_json
+        ClientInitializationPresenter.new snippet_proto&.service_client_initialization,
+                                          snippet_json&.fetch("serviceClientInitialization", nil),
+                                          phase1: !config?, client_type: client_type
+      end
+
+      def build_request_initialization_presenter call_proto, call_json
+        phase1 = !config?
+        request_init_proto = call_proto&.request_initialization
+        request_init_json = call_json&.fetch "requestInitialization", nil
+        if client_streaming?
+          request_name = phase1 ? "input" : call_proto.client_stream_name
+          StreamingRequestInitializationPresenter.new request_init_proto, request_init_json,
+                                                      request_name: request_name, request_type: request_type,
+                                                      phase1: phase1
+        else
+          SimpleRequestInitializationPresenter.new request_init_proto, request_init_json,
+                                                   request_type: request_type, phase1: phase1
+        end
+      end
+
+      def build_response_handling_presenter call_proto, call_json
+        phase1 = !config?
+        case response_kind
+        when :paged
+          PaginatedResponseHandlingPresenter.new call_proto&.paginated_handling,
+                                                 call_json&.fetch("paginatedHandling", nil),
+                                                 paged_response_type: paged_response_type, phase1: phase1
+        when :lro
+          LroResponseHandlingPresenter.new call_proto&.lro_handling,
+                                           call_json&.fetch("lroHandling", nil),
+                                           phase1: phase1
+        when :streaming
+          response_name = phase1 ? "output" : call_proto&.server_stream_name
+          response_name = nil if response_name == ""
+          StreamingResponseHandlingPresenter.new call_proto&.response_handling,
+                                                 call_json&.fetch("responseHandling", nil),
+                                                 response_name: response_name, base_response_type: base_response_type,
+                                                 phase1: phase1
+        else
+          SimpleResponseHandlingPresenter.new call_proto&.response_handling,
+                                              call_json&.fetch("responseHandling", nil),
+                                              response_type: return_type, phase1: phase1
+        end
+      end
+
+      def build_client_call_presenter call_proto, call_json, request_name, response_name
+        phase1 = !config?
+        if response_kind == :paged
+          ClientCallPresenter.new call_proto&.paginated_call, call_json&.fetch("paginatedCall", nil),
+                                  method_name: method_name, request_name: request_name, response_name: response_name,
+                                  client_streaming: client_streaming?, server_streaming: server_streaming?,
+                                  phase1: phase1
+        elsif client_streaming? || server_streaming?
+          ClientCallPresenter.new call_proto&.initialization_call, call_json&.fetch("initializationCall", nil),
+                                  method_name: method_name, request_name: request_name, response_name: response_name,
+                                  client_streaming: client_streaming?, server_streaming: server_streaming?,
+                                  phase1: phase1
+        else
+          ClientCallPresenter.new call_proto&.call, call_json&.fetch("call", nil),
+                                  method_name: method_name, request_name: request_name, response_name: response_name,
+                                  client_streaming: false, server_streaming: false, phase1: phase1
+        end
+      end
+
+      def build_final_statements snippet_proto, snippet_json
+        return [] unless snippet_proto&.final_statements
+        snippet_proto.final_statements.each_with_index.map do |statement_proto, index|
+          statement_json = snippet_json["finalStatements"][index]
+          StatementPresenter.new statement_proto, statement_json
+        end
+      end
+
+      def snake_config_id
+        ActiveSupport::Inflector.underscore @config.metadata.config_id
       end
     end
   end

data/lib/gapic/presenters.rb

@@ -14,19 +14,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/model"
 require "gapic/presenters/enum_presenter"
 require "gapic/presenters/enum_value_presenter"
 require "gapic/presenters/field_presenter"
 require "gapic/presenters/file_presenter"
 require "gapic/presenters/gem_presenter"
 require "gapic/presenters/message_presenter"
+require "gapic/presenters/method/http_binding_presenter"
 require "gapic/presenters/method_presenter"
 require "gapic/presenters/method_rest_presenter"
 require "gapic/presenters/package_presenter"
 require "gapic/presenters/resource_presenter"
 require "gapic/presenters/sample_presenter"
+require "gapic/presenters/service/lro_client_presenter"
+require "gapic/presenters/service/mixin_client_presenter"
 require "gapic/presenters/service_presenter"
-require "gapic/presenters/service_config_presenter"
+require "gapic/presenters/grpc_service_config_presenter"
 require "gapic/presenters/service_rest_presenter"
 require "gapic/presenters/snippet_presenter"
 

data/lib/gapic/runner.rb

@@ -17,7 +17,7 @@
 require "gapic/generator"
 require "gapic/schema"
 require "gapic/schema/request_param_parser"
-require "google/protobuf/compiler/plugin.pb"
+require "google/protobuf/compiler/plugin_pb"
 
 module Gapic
   # TODO: Enter docs

data/lib/gapic/schema/api.rb

@@ -20,6 +20,8 @@ require "gapic/generators/default_generator_parameters"
 require "gapic/schema/loader"
 require "gapic/schema/request_param_parser"
 require "gapic/grpc_service_config/parser"
+require "gapic/schema/service_config_parser"
+require "gapic/model/api_metadata"
 
 module Gapic
   module Schema
@@ -41,6 +43,7 @@ module Gapic
     class Api
       attr_accessor :request
       attr_accessor :files
+      attr_reader :snippet_configs
 
       # Initializes an API object with the file descriptors that represent the
       # API.
@@ -60,9 +63,11 @@ module Gapic
         @files.each { |f| f.parent = self }
         @configuration = configuration
         @resource_types = analyze_resources
+        @nonstandard_lro_services = analyze_nonstandard_lros
 
         parameter_schema ||= Gapic::Generators::DefaultGeneratorParameters.default_schema
         @protoc_parameters = parse_parameter request.parameter, parameter_schema, error_output
+        @snippet_configs = loader.load_snippet_configs self.configuration[:snippet_configs_path]
         sanity_checks error_output
       end
 
@@ -90,7 +95,7 @@ module Gapic
       end
 
       def overrides_of key
-        configuration&.fetch(:overrides, nil)&.fetch(key, nil) || {}
+        configuration&.dig(:overrides, key) || {}
       end
 
       def fix_file_path str
@@ -114,14 +119,17 @@ module Gapic
         configuration[:overrides][:service].fetch str, str
       end
 
+      # @return [Enumerable<Gapic::Schema::File>]
       def generate_files
         @files.select(&:generate?)
       end
 
+      # @return [Enumerable<Gapic::Schema::Service>]
       def services
         @files.map(&:services).flatten
       end
 
+      # @return [Enumerable<Gapic::Schema::Message>]
       def messages
         @files.map(&:messages).flatten
       end
@@ -201,6 +209,22 @@ module Gapic
         end
       end
 
+      # Return all snippet configs for the given method address. Returns the
+      # empty array if there are no snippet configs.
+      # @param address [String] Method address in the form
+      #   `proto.package.v1.ServiceName.MethodName`
+      # @return [Array<
+      #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
+      def snippet_configs_for address
+        address = address.join "." if address.is_a? ::Array
+        @snippet_configs.find_all do |config|
+          rpc = config.rpc
+          rpc.api_version.any? do |vers|
+            address == "#{rpc.proto_package}.#{vers}.#{rpc.service_name}.#{rpc.rpc_name}"
+          end
+        end
+      end
+
       # Structured Hash representation of the configuration file.
       # @return [Hash]
       #   A Hash of the configuration values.
@@ -245,14 +269,24 @@ module Gapic
         configuration[:transports].include? "grpc"
       end
 
+      ##
+      # The default transport, used when choosing which client class a docs
+      # xref should link to.
+      #
+      # @return [:grpc,:rest]
+      #
+      def default_transport
+        generate_grpc_clients? ? :grpc : :rest
+      end
+
       # Whether to generate standalone snippets
       def generate_standalone_snippets?
-        configuration[:generate_standalone_snippets] ||= false
+        configuration.fetch :generate_standalone_snippets, true
       end
 
       # Whether to generate inline documentation snippets
       def generate_yardoc_snippets?
-        configuration[:generate_yardoc_snippets] ||= false
+        configuration.fetch :generate_yardoc_snippets, true
       end
 
       # Whether to generate gapic metadata (drift manifest) file
@@ -293,6 +327,36 @@ module Gapic
         @grpc_service_config ||= Gapic::GrpcServiceConfig::Parser.parse grpc_service_config_raw
       end
 
+      # Raw text of the service.yaml if given as a parameter
+      # or nil if no parameter given
+      # @return [String]
+      def service_config_raw
+        @service_config_raw ||= begin
+          filename = protoc_options[:service_yaml]
+          ::File.read filename if filename
+        end
+      end
+
+      # Parsed service config
+      # @return [Google::Api::Service]
+      def service_config
+        @service_config ||= Gapic::Schema::ServiceConfigParser.parse_service_yaml service_config_raw
+      end
+
+      # Parsed API Metadata model
+      # @return [Gapic::Model::ApiMetadata]
+      def api_metadata
+        @api_metadata ||= begin
+          api_metadata = Gapic::Model::ApiMetadata.new
+          Gapic::Schema::ServiceConfigParser.parse_api_metadata service_config_raw, api_metadata
+          api_metadata.standardize_names!
+          api_metadata.standardize_title! gem_name: configuration.fetch(:gem, nil)&.fetch(:name, "")
+          api_metadata.standardize_descriptions!
+          api_metadata.standardize_auto_populated_fields! @service_config
+          api_metadata
+        end
+      end
+
       # Get a resource given its type string
       def lookup_resource_type resource_type
         @resource_types[resource_type]
@@ -318,6 +382,21 @@ module Gapic
         services.find { |s| s.address == addr }
       end
 
+      ##
+      # Returns a model for the nonstandard LRO for a given service
+      # The `analyze_nonstandard_lros` method fills in the model cache
+      #
+      # @param service_full_name [String]
+      #
+      # @return [Gapic::Model::Service::NonstandardLroProvider, Gapic::Model::Service::NoNonstandardLro]
+      def nonstandard_lro_model_for service_full_name
+        if @nonstandard_lro_services.key? service_full_name
+          @nonstandard_lro_services[service_full_name]
+        else
+          Gapic::Model::Service::NoNonstandardLro.instance
+        end
+      end
+
       ##
       # Whether configuration has an override for the wrapper gem name
       # @return [Boolean]
@@ -351,6 +430,9 @@ module Gapic
           output.puts "WARNING: configured common service #{k} is not present" unless addrs.include? k
           output.puts "WARNING: configured common service delegate #{v} is not present" unless addrs.include? v
         end
+        # TODO: Sanity check snippet configs to ensure that the type of call
+        # (e.g. streaming, lro, etc) matches the rpc type. Warn and remove any
+        # noncomplying snippet configs to prevent crashes when rendering.
       end
 
       # Does a pre-analysis of all resources defined in the job. This has
@@ -375,7 +457,7 @@ module Gapic
           file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
           file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
         end
-        types.each do |_type, resource|
+        types.each_value do |resource|
           parents = resource.parsed_parent_patterns
                             .flat_map { |pat| Array(patterns[pat]) }
                             .uniq
@@ -398,6 +480,24 @@ module Gapic
         end
       end
 
+      ##
+      # Does a pre-analysis of the nonstandard LRO for every service.
+      # For the services that provide nonstandard LRO functionality, cashes a model for the future use
+      #
+      # @return [Hash<String, Gapic::Model::Service::NonstandardLroProvider>]
+      def analyze_nonstandard_lros
+        service_registry = {}
+
+        @files.each do |file|
+          file.services.each do |service|
+            nonstandard_lro = Gapic::Model::Service.parse_nonstandard_lro service
+            service_registry[service.full_name] = nonstandard_lro if nonstandard_lro
+          end
+        end
+
+        service_registry
+      end
+
       # Parse a comma-delimited list of equals-delimited lists of strings, while
       # mapping backslash-escaped commas and equal signs to literal characters.
       # @param str [String]
@@ -427,7 +527,7 @@ module Gapic
 
       def str_to_key str
         str = str.to_s
-        str.start_with?(":") ? str[1..-1].to_sym : str
+        str.start_with?(":") ? str[1..].to_sym : str
       end
 
       def key_to_str key