gapic-generator 0.11.0 → 0.45.1

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

@@ -14,11 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/presenters/service/sub_client_presenter"
+
 module Gapic
   module Presenters
     module Service
       ##
-      # Presenter for the generation of the client for nonstandard LROs
+      # @private
+      # Presenter for the generation of the sub-client for LRO
+      # inside a host service's client class
       #
       # @!attribute [r] service
       #   Full name of the service providing the nonstandard LRO functionality
@@ -43,13 +47,7 @@ module Gapic
       #   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
+      class LroClientPresenter < SubClientPresenter
         attr_reader :helper_type
 
         ##
@@ -76,12 +74,14 @@ module Gapic
                        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
+          super(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

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Copyright 2022 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.
+
+require "gapic/presenters/service/sub_client_presenter"
+
+module Gapic
+  module Presenters
+    module Service
+      ##
+      # @private
+      # Presenter for the generation of the sub-client for mixins
+      # inside a host service's client class
+      #
+      # @!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] bindings_override
+      #   Override of Http bindings for the methods of the mixin service
+      #     methods are specified by their full name, e.g. `google.cloud.location.Locations.ListLocations`
+      #   @return [Hash{String, Array<::Gapic::Model::Method::HttpAnnotation::HttpBinding>}]
+      #
+      class MixinClientPresenter < SubClientPresenter
+        attr_reader :bindings_override
+
+        ##
+        # @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
+        #
+        def initialize service:,
+                       client_class_name:,
+                       client_class_docname:,
+                       client_var_name:,
+                       require_str:,
+                       service_description:,
+                       bindings_override:
+          super(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
+              )
+
+          @bindings_override = bindings_override
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Copyright 2022 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
+      ##
+      # @private
+      # Base class for the presenter for the generation of the clients
+      # for sub-services (mixins, lros) inside a host service's client class
+      #
+      # @!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]
+      #
+      class SubClientPresenter
+        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
+
+        ##
+        # @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
+        #
+        def initialize service:,
+                       client_class_name:,
+                       client_class_docname:,
+                       client_var_name:,
+                       require_str:,
+                       service_description:
+          @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
+        end
+      end
+    end
+  end
+end

data/lib/gapic/presenters/service_presenter.rb

@@ -30,6 +30,15 @@ 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
@@ -37,6 +46,7 @@ module Gapic
         @parent_service = parent_service
         @rest = ServiceRestPresenter.new self, api
         @nonstandard_lro = api.nonstandard_lro_model_for service.full_name
+        @type = "service"
       end
 
       def gem
@@ -51,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?
@@ -65,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
@@ -98,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
@@ -209,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
@@ -312,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
       #
@@ -329,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
@@ -411,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
@@ -459,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
@@ -498,13 +563,34 @@ 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
@@ -515,14 +601,74 @@ module Gapic
         @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::Model::Mixins::Mixin>]
+      # @return [Enumerable<Gapic::Presenters::Service::MixinClientPresenter>]
       #
-      def mixins
-        @gem_presenter.mixins_model.mixins
+      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
 
       ##
@@ -611,13 +757,14 @@ module Gapic
         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
+          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: lro_service.service_directory_name,
+                                                             client_var_name: client_var_name,
                                                              require_str: lro_service.service_require,
                                                              service_description: service_description,
                                                              helper_type: lro_service.nonstandard_lro_name_full
@@ -644,12 +791,15 @@ module Gapic
       #
       # @return [Enumerable<Gapic::Presenters::Service::LroClientPresenter, Gapic::Model::Mixins::Mixin>]
       def subclients
-        ([] << lro_client_presenter << mixins << nonstandard_lros).flatten.compact
+        [lro_client_presenter, mixin_presenters, nonstandard_lros].flatten.compact
       end
 
-      private
+      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>]
@@ -658,6 +808,8 @@ module Gapic
         methods.select(&:nonstandard_lro?).map(&:lro).uniq(&:service_full_name)
       end
 
+      private
+
       def default_config key
         return unless @service.parent.parent.configuration[:defaults]
         return unless @service.parent.parent.configuration[:defaults][:service]