gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/presenters/service_presenter.rb

@@ -30,12 +30,23 @@ module Gapic
       # @return [Gapic::Presenters::ServiceRestPresenter]
       attr_reader :rest
 
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param gem_presenter [Gapic::Presenters::GemPresenter]
+      # @param api [Gapic::Schema::Api]
+      # @param service [Gapic::Presenters::ServicePresenter]
+      # @param parent_service [Gapic::Presenters::ServicePresenter]
+      #
       def initialize gem_presenter, api, service, parent_service: nil
         @gem_presenter = gem_presenter
         @api = api
         @service = service
         @parent_service = parent_service
         @rest = ServiceRestPresenter.new self, api
+        @nonstandard_lro = api.nonstandard_lro_model_for service.full_name
+        @type = "service"
       end
 
       def gem
@@ -50,8 +61,12 @@ module Gapic
         PackagePresenter.new @gem_presenter, @api, @service.parent.package
       end
 
+      def special_compute_behavior?
+        address[0] == "google" && address[1] == "cloud" && address[2] == "compute" && !address[3].to_s.empty?
+      end
+
       ##
-      # @return [Boolean]
+      # @return [Boolean] Whether the service is marked as deprecated.
       #
       def is_deprecated?
         @service.is_deprecated?
@@ -64,6 +79,17 @@ module Gapic
         @methods ||= @service.methods.map { |m| MethodPresenter.new self, @api, m }
       end
 
+      ##
+      # @return [Boolean] Whether this service autogenerates UUID fields.
+      #
+      def autogenerates_uuid?
+        @methods.any? { |method| method.auto_populated_fields.length.positive? }
+      end
+
+      ##
+      # The address of this service split into an array
+      #
+      # @return [Array<String>]
       def address
         @service.address
       end
@@ -97,8 +123,15 @@ module Gapic
         ActiveSupport::Inflector.camelize @service.address[-2]
       end
 
-      def doc_description disable_xrefs: false
-        @service.docs_leading_comments disable_xrefs: disable_xrefs
+      ##
+      # The description as it should appear in YARD docs.
+      #
+      # @param transport [:grpc,:rest] Whether xref links should go to REST or
+      #   gRPC client classes. Uses the default transport if not provided.
+      # @return [String]
+      #
+      def doc_description disable_xrefs: false, transport: nil
+        @service.docs_leading_comments disable_xrefs: disable_xrefs, transport: transport
       end
 
       def name
@@ -208,15 +241,36 @@ module Gapic
           "localhost"
       end
 
+      ##
+      # Returns a template for the endpoint, with the universe domain component
+      # of the url replaced with the string `$UNIVERSE_DOMAIN$`.
+      #
+      # @return [String]
+      #
+      def client_endpoint_template
+        client_endpoint&.sub(/.googleapis.com$/, ".$UNIVERSE_DOMAIN$")
+      end
+
       def generic_endpoint?
         gem.generic_endpoint?
       end
 
+      # @return [String] The api_version for this service, or empty if not defined.
+      def api_version
+        @service.api_version.to_s
+      end
+
       def client_scopes
-        common_service_delegate&.client_scopes ||
-          @service.scopes ||
-          default_config(:oauth_scopes) ||
-          []
+        scopes = Array(common_service_delegate&.client_scopes)
+        return scopes unless scopes.empty?
+
+        scopes = Array(@service.scopes)
+        return scopes unless scopes.empty?
+
+        scopes = Array(default_config(:oauth_scopes))
+        return scopes unless scopes.empty?
+
+        []
       end
 
       def credentials_name
@@ -311,14 +365,36 @@ module Gapic
         ruby_file_path @api, "#{service_name_full}::#{paths_name}"
       end
 
+      ##
+      # @return [Boolean] Whether the generation of REST clients is requested
+      #    and can be done because at least one method has rest bindings.
+      #
       def generate_rest_clients?
-        @api.generate_rest_clients?
+        @api.generate_rest_clients? && methods_rest_bindings?
       end
 
+      ##
+      # @return [Boolean] Whether the generation of gRPC clients is requested
+      #
       def generate_grpc_clients?
         @api.generate_grpc_clients?
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def supports_multiple_transports?
+        generate_rest_clients? && generate_grpc_clients?
+      end
+
+      def client_suffix_for_default_transport
+        if @api.default_transport == :grpc
+          "#{module_name}::#{client_name}"
+        else
+          "#{module_name}::Rest::#{client_name}"
+        end
+      end
+
       ##
       # @return [Boolean] whether this service contains any methods with REST bindings
       #
@@ -328,10 +404,10 @@ module Gapic
 
       ##
       # @return [Enumerable<Gapic::Presenters::MethodPresenter>]
-      #   List of mods for which REST bindings are present and REST methods can be generated
+      #   List of methods for which REST bindings are present and REST methods can be generated
       #
       def methods_rest_bindings
-        methods.select { |method| method.rest.path? && method.rest.verb? }
+        methods.select(&:can_generate_rest?)
       end
 
       def test_client_file_path
@@ -350,18 +426,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
@@ -384,7 +486,7 @@ module Gapic
 
       def lro_service
         lro = @service.parent.parent.files.find { |file| file.name == "google/longrunning/operations.proto" }
-        return ServicePresenter.new @gem_presenter, @api, lro.services.first, parent_service: self unless lro.nil?
+        ServicePresenter.new @gem_presenter, @api, lro.services.first, parent_service: self unless lro.nil?
       end
 
       def config_channel_args
@@ -396,8 +498,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
 
       ##
@@ -408,8 +510,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
 
       ##
@@ -428,22 +534,12 @@ module Gapic
               # their names are returned together in an array.
               # For Ruby currently we have 1:1 proto to code
               # correspondence for methods, so our generation is easier
-              rpcs:       methods.map { |m| [m.grpc_method_name, m.drift_manifest] }.to_h
+              rpcs:       methods.to_h { |m| [m.grpc_method_name, m.drift_manifest] }
             }
           }
         }
       end
 
-      ##
-      # How comments in the generated libraries refer to the GRPC client
-      # if no REST code is generated, this should just be "client",
-      # if REST code is generated, this should be disambiguated into the "GRPC client"
-      #
-      # @return [String]
-      def grpc_client_designation
-        generate_rest_clients? ? "GRPC client" : "client"
-      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
@@ -467,13 +563,251 @@ module Gapic
       # @return [ServicePresenter,ServiceRestPresenter,nil]
       #
       def usable_service_presenter
-        if @api.generate_grpc_clients?
+        if generate_grpc_clients?
           self
-        elsif @api.generate_rest_clients? && methods_rest_bindings?
+        elsif generate_rest_clients?
           rest
         end
       end
 
+      ##
+      # Whether this service presenter is a mixin inside a host service's gem
+      # (and not in its own gem)
+      #
+      # @return [Boolean]
+      #
+      def is_hosted_mixin?
+        Gapic::Model::Mixins.mixin_service_address? address, gem_name: @gem_presenter.name
+      end
+
+      ##
+      # Whether this service presenter is a mixin inside it's own gem
+      # (and not in another service's gem)
+      #
+      # @return [Boolean]
+      #
+      def is_main_mixin_service?
+        Gapic::Model::Mixins.mixin_service_address?(address) &&
+          !Gapic::Model::Mixins.mixin_service_address?(address, gem_name: @gem_presenter.name)
+      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 models for the mixins
+      #
+      # @return [Enumerable<::Gapic::Model::Mixins::Mixin>]
+      #
+      def mixin_models
+        @gem_presenter.mixins_model.mixins
+      end
+
+      ##
+      # Whether there are mixin services that this package has http binding overrides for.
+      #
+      # @return [Boolean]
+      #
+      def mixin_binding_overrides?
+        mixin_presenters.any? { |mixin| !mixin.bindings_override.empty? }
+      end
+
+      ##
+      # Whether config for this service should include the `bindings_override` field.
+      # This field is needed:
+      #   * if a service is a mixin in it's own package, e.g. `google.Cloud.Location`
+      #   * if a service hosts a mixin and has bindings overrides for it
+      # but the generated Operations clients should not have it since override for
+      # their bindings are generated instead of set during runtime.
+      #
+      # GRPC clients should not have this for now, since the overrides are not currently used.
+      #
+      def mixin_should_generate_override_config?
+        false
+      end
+
+      ##
+      # The mixin services that should be referenced
+      # in the client for this service
+      #
+      # @return [Enumerable<Gapic::Presenters::Service::MixinClientPresenter>]
+      #
+      def mixin_presenters
+        return [] unless mixins?
+        mixin_models.map do |model|
+          # we don't have mixin's descriptors loaded, so instead of starting with descriptor's methods
+          # and looking up the override, we'll start with overrides and see if any fit the mixin's namespace
+          bindings_override = begin
+            if @api.service_config&.http.nil?
+              {}
+            else
+              service_http_rules = @api.service_config.http.rules.select do |http_rule|
+                http_rule.selector.include? model.service
+              end
+
+              service_http_rules.to_h do |http_rule|
+                bindings = Gapic::Model::Method::HttpAnnotation.new(http_rule).bindings.map do |binding|
+                  Gapic::Presenters::Method::HttpBindingPresenter.new binding
+                end
+                [http_rule.selector, bindings]
+              end
+            end
+          end
+
+          Gapic::Presenters::Service::MixinClientPresenter.new service: model.service,
+                                                               client_class_name: model.client_class_name,
+                                                               client_class_docname: model.client_class_docname,
+                                                               client_var_name: model.client_var_name,
+                                                               require_str: model.require_str,
+                                                               service_description: model.service_description,
+                                                               bindings_override: bindings_override
+        end
+      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
+
+          service_description = "long-running operations via #{lro_service.name}"
+          client_var_name = ruby_file_path_for_namespace 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: client_var_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, mixin_presenters, nonstandard_lros].flatten.compact
+      end
+
+      def lro_subclients
+        [lro_client_presenter, 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
+
       private
 
       def default_config key