gapic-generator 0.11.0 → 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,22 +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
-        api_id = api_id.downcase.gsub(/[^a-z0-9]/, "")
+        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

@@ -21,12 +21,14 @@ 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/grpc_service_config_presenter"
 require "gapic/presenters/service_rest_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

@@ -21,6 +21,7 @@ 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
@@ -42,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.
@@ -65,6 +67,7 @@ module Gapic
 
         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
 
@@ -92,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
@@ -206,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.
@@ -250,6 +269,16 @@ 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.fetch :generate_standalone_snippets, true
@@ -314,6 +343,20 @@ module Gapic
         @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]
@@ -387,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
@@ -411,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
@@ -481,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

data/lib/gapic/schema/loader.rb

@@ -14,14 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "google/api/annotations.pb"
-require "google/api/client.pb"
-require "google/api/field_behavior.pb"
-require "google/api/resource.pb"
-require "google/api/routing.pb"
-require "google/cloud/extended_operations.pb"
-require "google/longrunning/operations.pb"
-require "google/protobuf/descriptor.pb"
+require "google/api/annotations_pb"
+require "google/api/client_pb"
+require "google/api/field_behavior_pb"
+require "google/api/resource_pb"
+require "google/api/routing_pb"
+require "google/cloud/extended_operations_pb"
+require "google/longrunning/operations_pb"
+require "google/protobuf/descriptor_pb"
+require "gapic/schema/proto_tools"
 require "gapic/schema/wrappers"
 
 module Gapic
@@ -34,6 +35,14 @@ module Gapic
         @prior_enums = []
       end
 
+      FILE_EXTENSION_NAMES = {
+        "google.api.resource_definition" => [1053, ::Google::Api::ResourceDescriptor, :repeated]
+      }.freeze
+
+      MESSAGE_EXTENSION_NAMES = {
+        "google.api.resource" => [1053, ::Google::Api::ResourceDescriptor]
+      }.freeze
+
       # Loads a file.
       #
       # @param file_descriptor [Google::Protobuf::FileDescriptorProto] the
@@ -48,27 +57,28 @@ module Gapic
         registry = {}
 
         # Load the docs.
-        location = file_descriptor.source_code_info.location
-        docs = location.each_with_object({}) { |l, ans| ans[l.path] = l }
+        location = file_descriptor.source_code_info.location || []
+        docs = location.each_with_object({}) { |l, ans| ans[l.path.to_a] = l }
 
         # Load top-level enums.
-        enums = file_descriptor.enum_type.each_with_index.map do |e, i|
+        enums = (file_descriptor.enum_type || []).each_with_index.map do |e, i|
           load_enum registry, e, address, docs, [5, i]
         end
 
         # Load top-level messages.
-        messages = file_descriptor.message_type.each_with_index.map do |m, i|
+        messages = (file_descriptor.message_type || []).each_with_index.map do |m, i|
           load_message registry, m, address, docs, [4, i]
         end
         messages.each(&method(:update_fields!))
 
         # Load services.
-        services = file_descriptor.service.each_with_index.map do |s, i|
+        services = (file_descriptor.service || []).each_with_index.map do |s, i|
           load_service registry, s, address, docs, [6, i]
         end
 
         # Load top-level resources
-        resource_descriptors = file_descriptor.options[:".google.api.resource_definition"] if file_descriptor.options
+        option_extensions = ProtoTools.parse_options_extensions file_descriptor.options, FILE_EXTENSION_NAMES
+        resource_descriptors = option_extensions["google.api.resource_definition"]
         resources = Array(resource_descriptors).map { |descriptor| Resource.new descriptor }
 
         # Construct and return the file.
@@ -76,6 +86,25 @@ module Gapic
                  services, resources, file_to_generate, registry
       end
 
+      ##
+      # Loads snippet configs from the given directory
+      #
+      # @param path [String] Directory to search for snippet config files
+      # @return [Array<
+      #   Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig>]
+      #
+      def load_snippet_configs path
+        return [] unless path
+        Dir.chdir path do
+          Dir.glob("**/*.json").map do |file_path|
+            json = JSON.load_file file_path
+            proto = Google::Cloud::Tools::SnippetGen::ConfigLanguage::V1::SnippetConfig.new underscore_keys json
+            proto.json_representation = json
+            proto
+          end
+        end
+      end
+
       # Updates the fields of a message and it's nested messages.
       #
       # @param message [Message] the message whose fields and nested messages
@@ -105,7 +134,7 @@ module Gapic
         address = address.clone << descriptor.name
 
         # Load Enum Values
-        values = descriptor.value.each_with_index.map do |value, i|
+        values = (descriptor.value || []).each_with_index.map do |value, i|
           load_enum_value registry, value, address, docs, path + [2, i]
         end
 
@@ -152,20 +181,22 @@ module Gapic
         address = address.clone << descriptor.name
 
         # Load Children
-        nested_messages = descriptor.nested_type.each_with_index.map do |m, i|
+        nested_messages = (descriptor.nested_type || []).each_with_index.map do |m, i|
           load_message registry, m, address, docs, path + [3, i]
         end
-        nested_enums = descriptor.enum_type.each_with_index.map do |e, i|
+        nested_enums = (descriptor.enum_type || []).each_with_index.map do |e, i|
           load_enum registry, e, address, docs, path + [4, i]
         end
-        fields = descriptor.field.each_with_index.map do |f, i|
+        fields = (descriptor.field || []).each_with_index.map do |f, i|
           load_field registry, f, address, docs, path + [2, i]
         end
-        extensions = descriptor.extension.each_with_index.map do |e, i|
+        fields.each { |field| field.populate_oneof_siblings! fields }
+        extensions = (descriptor.extension || []).each_with_index.map do |e, i|
           load_field registry, e, address, docs, path + [6, i]
         end
 
-        resource_descriptor = descriptor.options[:".google.api.resource"] if descriptor.options
+        option_extensions = ProtoTools.parse_options_extensions descriptor.options, MESSAGE_EXTENSION_NAMES
+        resource_descriptor = option_extensions["google.api.resource"]
         resource = resource_descriptor ? Resource.new(resource_descriptor) : nil
 
         # Construct, cache, and return.
@@ -212,7 +243,7 @@ module Gapic
         address = address.clone << descriptor.name
 
         # Load children
-        methods = descriptor.method.each_with_index.map do |m, i|
+        methods = (descriptor["method"] || descriptor.method || []).each_with_index.map do |m, i|
           load_method registry, m, address, docs, path + [2, i]
         end
 
@@ -262,6 +293,20 @@ module Gapic
 
       private
 
+      ##
+      # Transforms all keys in the given hash to snake case.
+      #
+      def underscore_keys input
+        case input
+        when Hash
+          input.to_h { |key, value| [ActiveSupport::Inflector.underscore(key), underscore_keys(value)] }
+        when Array
+          input.map { |elem| underscore_keys elem }
+        else
+          input
+        end
+      end
+
       def add_to_registry registry, address, obj
         registry[address.join(".")] = obj
         obj
@@ -269,7 +314,7 @@ module Gapic
 
       def cached_obj collection, type_name
         # Remove leading dot.
-        type_name = type_name[1..-1] if type_name && type_name[0] == "."
+        type_name = type_name[1..] if type_name && type_name[0] == "."
 
         # Create an address from the type & check cache.
         collection.find { |m| m.address == type_name.split(".") }

data/lib/gapic/schema/parameter_schema.rb

@@ -43,10 +43,10 @@ module Gapic
       # @param map_params_list [Array<String>]
       # @return Gapic::Schema::ParameterSchema
       def self.create bool_params_list: [], string_params_list: [], array_params_list: [], map_params_list: []
-        bool_params = bool_params_list.map { |val| [val, val] }.to_h
-        string_params = string_params_list.map { |val| [val, val] }.to_h
-        array_params = array_params_list.map { |val| [val, val] }.to_h
-        map_params = map_params_list.map { |val| [val, val] }.to_h
+        bool_params = bool_params_list.to_h { |val| [val, val] }
+        string_params = string_params_list.to_h { |val| [val, val] }
+        array_params = array_params_list.to_h { |val| [val, val] }
+        map_params = map_params_list.to_h { |val| [val, val] }
 
         ParameterSchema.new bool_params, string_params, array_params, map_params
       end
@@ -58,16 +58,16 @@ module Gapic
       # @param map_aliases [Hash{String => String}]
       # @return Gapic::Schema::ParameterSchema
       def extend_with_aliases bool_aliases: {}, string_aliases: {}, array_aliases: {}, map_aliases: {}
-        bool_params = @bool_params
+        bool_params = @bool_params.dup
         bool_aliases.each { |param_alias, param| bool_params[param_alias] = param if bool_params.key? param }
 
-        string_params = @string_params
+        string_params = @string_params.dup
         string_aliases.each { |param_alias, param| string_params[param_alias] = param if string_params.key? param }
 
-        array_params = @array_params
+        array_params = @array_params.dup
         array_aliases.each { |param_alias, param| array_params[param_alias] = param if array_params.key? param }
 
-        map_params = @map_params
+        map_params = @map_params.dup
         map_aliases.each { |param_alias, param| map_params[param_alias] = param if map_params.key? param }
 
         ParameterSchema.new bool_params, string_params, array_params, map_params