gapic-generator 0.9.1 → 0.11.0

data/lib/gapic/presenters/service_presenter.rb

@@ -36,6 +36,7 @@ module Gapic
         @service = service
         @parent_service = parent_service
         @rest = ServiceRestPresenter.new self, api
+        @nonstandard_lro = api.nonstandard_lro_model_for service.full_name
       end
 
       def gem
@@ -50,6 +51,13 @@ module Gapic
         PackagePresenter.new @gem_presenter, @api, @service.parent.package
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def is_deprecated?
+        @service.is_deprecated?
+      end
+
       ##
       # @return [Enumerable<Gapic::Presenters::MethodPresenter>]
       #
@@ -252,6 +260,34 @@ module Gapic
         @references ||= @service.resources.map { |resource| ResourcePresenter.new resource }.sort_by(&:name)
       end
 
+      ##
+      # Deduplicate resource presenters by combining resources with the same
+      # name. If multiple resources have the same name (though possibly
+      # different namespaces, e.g. `location.googleapis.com/Location` vs
+      # `documentai.googleapis.com/Location`), this combines (and dedups) their
+      # patterns into a single resource presenter.
+      #
+      # Used for generating path helpers while avoiding duplicate method names.
+      #
+      def deduped_references
+        @deduped_references ||= begin
+          hash = {}
+          references.each do |resource|
+            if hash.key? resource.name
+              existing = hash[resource.name]
+              resource.patterns.each do |pat|
+                unless existing.patterns.any? { |epat| epat.pattern_template == pat.pattern_template }
+                  existing.patterns << pat
+                end
+              end
+            else
+              hash[resource.name] = resource.dup
+            end
+          end
+          hash.values
+        end
+      end
+
       def paths?
         references.any?
       end
@@ -315,18 +351,44 @@ module Gapic
         "#{ActiveSupport::Inflector.underscore name}_stub"
       end
 
+      ##
+      # Whether an AIP-151 LRO subclient needs to be generated for this service
+      #
+      # @return [Boolean]
       def lro?
         methods.find(&:lro?)
       end
 
+      ##
+      # A variable name used for the AIP-151 LRO subclients
+      #
+      # @return [String]
       def lro_client_var
         "operations_client"
       end
 
+      ##
+      # An instance variable name used for the AIP-151 LRO subclients
+      #
+      # @return [String]
       def lro_client_ivar
         "@#{lro_client_var}"
       end
 
+      ##
+      # A presenter for the LRO subclient if needed
+      #
+      # @return [Gapic::Presenters::Service::LroClientPresenter, nil]
+      def lro_client_presenter
+        return nil unless lro?
+        Gapic::Presenters::Service::LroClientPresenter.new service: "google.longrunning.operations",
+                                                           client_class_name: "Operations",
+                                                           client_class_docname: operations_name_full,
+                                                           client_var_name: lro_client_var,
+                                                           require_str: operations_file_path,
+                                                           service_description: "long-running operations"
+      end
+
       def operations_name
         "Operations"
       end
@@ -361,8 +423,8 @@ module Gapic
         @api.grpc_service_config.service_level_configs[grpc_full_name]
       end
 
-      def service_config_presenter
-        ServiceConfigPresenter.new grpc_service_config
+      def grpc_service_config_presenter
+        GrpcServiceConfigPresenter.new grpc_service_config
       end
 
       ##
@@ -373,8 +435,12 @@ module Gapic
         @service.name
       end
 
+      ##
+      # The full proto name for this service
+      #
+      # @return [String]
       def grpc_full_name
-        @service.address.join "."
+        @service.full_name
       end
 
       ##
@@ -423,8 +489,175 @@ module Gapic
         result || methods.find { |meth| !meth.client_streaming? }
       end
 
+      ##
+      # Returns this service presenter if there is a grpc client. Otherwise,
+      # returns the corresponding rest service presenter if there isn't a grpc
+      # client but there is a rest client. Otherwise, returns nil if there is
+      # neither client.
+      #
+      # @return [ServicePresenter,ServiceRestPresenter,nil]
+      #
+      def usable_service_presenter
+        if @api.generate_grpc_clients?
+          self
+        elsif @api.generate_rest_clients? && methods_rest_bindings?
+          rest
+        end
+      end
+
+      ##
+      # Whether there are mixin services that should be referenced
+      # in the client for this service
+      #
+      # @return [Boolean]
+      #
+      def mixins?
+        @gem_presenter.mixins?
+      end
+
+      ##
+      # The mixin services that should be referenced
+      # in the client for this service
+      #
+      # @return [Enumerable<Gapic::Model::Mixins::Mixin>]
+      #
+      def mixins
+        @gem_presenter.mixins_model.mixins
+      end
+
+      ##
+      # Name of the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_name
+        "NonstandardLro"
+      end
+
+      ##
+      # Full name of the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_name_full
+        fix_namespace @api, "#{service_name_full}::#{nonstandard_lro_name}"
+      end
+
+      ##
+      # Full file path to the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_file_path
+        "#{nonstandard_lro_require}.rb"
+      end
+
+      ##
+      # File name of the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_file_name
+        nonstandard_lro_file_path.split("/").last
+      end
+
+      ##
+      # The require string for the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_require
+        ruby_file_path @api, "#{service_name_full}::#{nonstandard_lro_name}"
+      end
+
+      ##
+      # Nonstandard lro model for this service
+      #
+      # @return [Gapic::Model::Service::NonstandardLro, Gapic::Model::Service::NoLro]
+      def nonstandard_lro
+        @nonstandard_lro
+      end
+
+      ##
+      # The Ruby name for the polling method of the nonstandard LRO provided by this service
+      #
+      # @return [String]
+      def nonstandard_lro_polling_method_name
+        return unless nonstandard_lro_provider?
+        methods.find { |m| m.grpc_method_name == nonstandard_lro.polling_method_name }.name
+      end
+
+      ##
+      # Whether this service is a provider of the nonstandard LRO functionality
+      #
+      # @return [Boolean]
+      def nonstandard_lro_provider?
+        @nonstandard_lro.nonstandard_lro?
+      end
+
+      ##
+      # Whether one or more methods of this service use the nonstandard LRO functionality
+      #
+      # @return [Boolean]
+      def nonstandard_lro_consumer?
+        methods.find(&:nonstandard_lro?) || false
+      end
+
+      ##
+      # The client presenters of the nonstandard LROs that are used by the methods of this service
+      #
+      # @return [Enumerable<Gapic::Presenters::Service::LroClientPresenter>]
+      def nonstandard_lros
+        return [] unless nonstandard_lro_consumer?
+        nonstandard_lros_models.map do |lro|
+          lro_wrapper = @api.lookup lro.service_full_name
+          lro_service = ServicePresenter.new(@gem_presenter, @api, lro_wrapper).usable_service_presenter
+
+          service_description = "long-running operations via #{lro_service.name}"
+          Gapic::Presenters::Service::LroClientPresenter.new service: lro.service_full_name,
+                                                             client_class_name: lro_service.client_name_full,
+                                                             client_class_docname: lro_service.client_name_full,
+                                                             client_var_name: lro_service.service_directory_name,
+                                                             require_str: lro_service.service_require,
+                                                             service_description: service_description,
+                                                             helper_type: lro_service.nonstandard_lro_name_full
+        end
+      end
+
+      ##
+      # Whether there are any subclients to generate with this service.
+      # Subclients are the clients to other services (e.g. an LRO provider service).
+      #
+      # @return [Boolean]
+      def subclients?
+        subclients.any?
+      end
+
+      ##
+      # Subclients for this service
+      # Subclients are the clients to other services (e.g. an LRO provider service).
+      #
+      # The following is typically generated for a subclient:
+      # - a require statement for the subclient's class
+      # - a class-level variable in the host service's client
+      # - a code to initialize this variable with a subclient's class instance in the host service's constructor
+      #
+      # @return [Enumerable<Gapic::Presenters::Service::LroClientPresenter, Gapic::Model::Mixins::Mixin>]
+      def subclients
+        ([] << lro_client_presenter << mixins << nonstandard_lros).flatten.compact
+      end
+
       private
 
+      ##
+      # The nonstandard LRO models for the nonstandard LROs that are used by the methods of this service
+      #
+      # @return [Enumerable<Gapic::Model::Method::Lro>]
+      def nonstandard_lros_models
+        return [] unless nonstandard_lro_consumer?
+        methods.select(&:nonstandard_lro?).map(&:lro).uniq(&:service_full_name)
+      end
+
       def default_config key
         return unless @service.parent.parent.configuration[:defaults]
         return unless @service.parent.parent.configuration[:defaults][:service]

data/lib/gapic/presenters/service_rest_presenter.rb

@@ -37,12 +37,69 @@ module Gapic
       end
 
       ##
+      # Ruby name of this service
+      #
+      # @return [String]
+      #
+      def name
+        main_service.name
+      end
+
+      ##
+      # Full Ruby name of this service
+      #
       # @return [String]
       #
       def service_name_full
         fix_namespace api, "#{main_service.service_name_full}::Rest"
       end
 
+      ##
+      # Require path for this service
+      #
+      # @return [String]
+      #
+      def service_require
+        ruby_file_path @api, service_name_full
+      end
+
+      ##
+      # Folder name for this service
+      #
+      # @return [String]
+      #
+      def service_directory_name
+        service_require.split("/")[-2]
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_name
+        "ServiceStub"
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_name_full
+        fix_namespace api, "#{service_name_full}::#{service_stub_name}"
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_require
+        ruby_file_path api, service_stub_name_full
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_file_path
+        "#{service_stub_require}.rb"
+      end
+
       ##
       # @return [String]
       #
@@ -95,38 +152,88 @@ module Gapic
       ##
       # @return [String]
       #
-      def transcoding_helper_name
-        "GrpcTranscoding"
+      def test_client_file_path
+        main_service.service_file_path.sub ".rb", "_test.rb"
       end
 
       ##
       # @return [String]
       #
-      def transcoding_helper_name_full
-        fix_namespace api, "#{service_name_full}::#{transcoding_helper_name}"
+      def credentials_class_xref
+        main_service.credentials_class_xref
       end
 
       ##
       # @return [String]
       #
-      def transcoding_helper_require
-        ruby_file_path api, transcoding_helper_name_full
+      def configure_client_call
+        "#{client_name_full}.configure"
       end
 
       ##
+      # Name of the nonstandard LRO module
+      #
       # @return [String]
       #
-      def transcoding_helper_file_path
-        "#{transcoding_helper_require}.rb"
+      def nonstandard_lro_name
+        "NonstandardLro"
       end
 
       ##
+      # Full name of the nonstandard LRO module
+      #
       # @return [String]
       #
-      def test_client_file_path
-        main_service.service_file_path.sub ".rb", "_test.rb"
+      def nonstandard_lro_name_full
+        fix_namespace @api, "#{service_name_full}::#{nonstandard_lro_name}"
       end
 
+      ##
+      # Full file path to the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_file_path
+        "#{nonstandard_lro_require}.rb"
+      end
+
+      ##
+      # File name of the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_file_name
+        nonstandard_lro_file_path.split("/").last
+      end
+
+      ##
+      # The require string for the nonstandard LRO module
+      #
+      # @return [String]
+      #
+      def nonstandard_lro_require
+        ruby_file_path @api, "#{service_name_full}::#{nonstandard_lro_name}"
+      end
+
+      ##
+      # The method to use for quick start samples. Normally this is simply the
+      # first non-client-streaming method defined, but it can be overridden via
+      # a gem config.
+      #
+      # @return [Gapic::Presenters::MethodRestPresenter] if there is a method
+      #     appropriatke for quick start
+      # @return [nil] if there is no method appropriate for quick start
+      #
+      def quick_start_method
+        main_service.quick_start_method&.rest
+      end
+
+      ##
+      # @return [Enumerable<Gapic::Presenters::MethodPresenter>]
+      #
+      def methods
+        main_service.methods
+      end
 
       private
 

data/lib/gapic/presenters/snippet_presenter.rb

@@ -52,7 +52,7 @@ module Gapic
       end
 
       def require_path
-        @method_presenter.service.service_require
+        @method_presenter.service.package.package_require
       end
 
       def client_type
@@ -94,6 +94,7 @@ module Gapic
           api_id ||= final_name
           api_version = "v0"
         end
+        api_id = api_id.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"

data/lib/gapic/presenters.rb

@@ -14,6 +14,7 @@
 # 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"
@@ -25,8 +26,9 @@ 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_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/schema/api.rb

@@ -20,6 +20,7 @@ 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"
 
 module Gapic
   module Schema
@@ -60,6 +61,7 @@ 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
@@ -114,14 +116,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
@@ -247,7 +252,12 @@ module Gapic
 
       # 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.fetch :generate_yardoc_snippets, true
       end
 
       # Whether to generate gapic metadata (drift manifest) file
@@ -288,6 +298,22 @@ 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
+
       # Get a resource given its type string
       def lookup_resource_type resource_type
         @resource_types[resource_type]
@@ -313,6 +339,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]
@@ -323,7 +364,7 @@ module Gapic
 
       ##
       # An override for the wrapper gem name in the configuration
-      # @return [String, Nil]
+      # @return [String, nil]
       def wrapper_gem_name_override
         return nil unless wrapper_gem_name_override?
         return nil if configuration[:overrides][:wrapper_gem_name].nil?
@@ -393,6 +434,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]

data/lib/gapic/schema/loader.rb

@@ -18,6 +18,8 @@ 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/wrappers"
@@ -36,8 +38,9 @@ module Gapic
       #
       # @param file_descriptor [Google::Protobuf::FileDescriptorProto] the
       #   descriptor of the proto file.
-      # @oaram file_to_generate [Boolean] Whether this file is to be
+      # @param file_to_generate [Boolean] Whether this file is to be
       #   generated.
+      # @return [Gapic::Schema::File]
       def load_file file_descriptor, file_to_generate
         # Setup.
         address = file_descriptor.package.split "."