gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/model/mixins.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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 Model
+    # Aggregated information about the mixin services
+    # that should be referenced from their gems in the
+    # generated client libraries
+    class Mixins
+      # LRO might be specified in the mixins but it is not generated
+      # as a mixin
+      LRO_SERVICE = "google.longrunning.Operations"
+
+      # Locations and Iam are generated as mixins
+      LOCATIONS_SERVICE = "google.cloud.location.Locations"
+      IAM_SERVICE = "google.iam.v1.IAMPolicy"
+
+      # @return [Enumerable<String>] List of services from the Api model
+      attr_accessor :api_services
+
+      ##
+      # @param api_services [Enumerable<String>]
+      #   List of services from the  Api model
+      # @param service_config [Google::Api::Service]
+      #   The service config
+      # @param gem_name [String]
+      #   The name of the gem.
+      def initialize api_services, service_config, gem_name
+        @api_services = api_services
+        @service_config = service_config
+        @gem_name = gem_name
+      end
+
+      # @return [Boolean] Whether there are any mix-in services
+      def mixins?
+        mixin_services.any?
+      end
+
+      # @return [Enumerable<Mixin>]
+      #   List of Mixin objects, providing the information that is needed
+      #   to add the mixin service references to the generated library
+      def mixins
+        @mixins ||= mixin_services.map { |service| create_mixin service }
+      end
+
+      # @return [Enumerable<String>] Full proto names of the mix-in services
+      def mixin_services
+        @mixin_services ||= begin
+          candidates = services_in_config & SERVICE_TO_DEPENDENCY.keys
+          candidates.reject { |name| SERVICE_TO_DEPENDENCY[name].include? @gem_name }
+        end
+      end
+
+      # @return [Hash<String, String>]
+      #   Aggregated dependencies for the mix-in services
+      def dependencies
+        @dependencies ||= mixins.reduce({}) { |deps, mixin| deps.merge mixin.dependency }
+      end
+
+      # Model of a single mixin service
+      # @!attribute [r] service
+      #   Full name of the service
+      #   @return [String]
+      # @!attribute [r] dependency
+      #   Service dependencies, in the
+      #   `{ gem_name => version pattern }` format
+      #   @return [Hash<String, String>]
+      # @!attribute [r] require_str
+      #   Path to `require` the client of the service
+      #   @return [String]
+      # @!attribute [r] require_str_rest
+      #   Path to `require` the REST client of the service
+      #   @return [String]
+      # @!attribute [r] client_class_name
+      #   Full name of the class of the client of the service
+      #   @return [String]
+      # @!attribute [r] client_class_name_rest
+      #   Full name of the class of the REST 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_class_docname_rest
+      #   Name of the REST class as it should appear in the documentation
+      #   @return [String]
+      # @!attribute [r] client_var_name
+      #   Name for the variable for the client of the
+      #   mixin service to use when generating library's service
+      #   @return [String]
+      class Mixin
+        attr_reader :service
+        attr_reader :dependency
+        attr_reader :require_str
+        attr_reader :require_str_rest
+        attr_reader :client_class_name
+        attr_reader :client_class_name_rest
+        attr_reader :client_class_docname
+        attr_reader :client_class_docname_rest
+        attr_reader :client_var_name
+
+        # @param service [String]
+        #   Full name of the service
+        # @param dependency [Hash<String, String>]
+        #   Service dependencies, in the
+        #   `{ gem_name => version pattern }` format
+        # @param require_str [String]
+        #   Path to require the client of the service
+        # @param require_str_rest [String]
+        #   Path to require the REST client of the service
+        # @param client_class_name [String]
+        #   Full name of the class of the client of the service
+        # @param client_class_name_rest [String]
+        #   Full name of the class of the REST client of the service
+        # @param client_var_name [String]
+        #   Name for the variable for the client of the mixin service
+        #   to use when generating library's service
+        def initialize service, dependency, require_str, require_str_rest, client_class_name, client_class_name_rest,
+                       client_var_name
+          @service = service
+          @dependency = dependency
+          @require_str = require_str
+          @require_str_rest = require_str_rest
+          @client_class_name = client_class_name
+          @client_class_name_rest = client_class_name_rest
+          @client_class_docname = client_class_name # For mixins, the doc name should be the full class name
+          @client_class_docname_rest = client_class_name_rest # For mixins, the doc name should be the full class name
+          @client_var_name = client_var_name
+        end
+
+        # @return [String] The description to place in the comments to the
+        #   mixin's attribute in the library services's client class
+        def service_description
+          "mix-in of the #{client_class_name.split('::')[-2]}"
+        end
+      end
+
+      ##
+      # Returns true if the given service address is a mixin.
+      # This just checks the service against a (hard-coded) set of known mixins.
+      # If `gem_name` is provided, services that correspond to that gem_name are not considered mixins.
+      #
+      # @param service_address [String,Array<String>] The address (either array
+      #     or dot-delimited) of the service to check.
+      # @param gem_name [String] The name of the gem.
+      # @return [boolean]
+      #
+      def self.mixin_service_address? service_address, gem_name: nil
+        service_address = service_address.join "." unless service_address.is_a? String
+        MIXIN_GEM_NAMES.include?(service_address) && gem_name != MIXIN_GEM_NAMES[service_address]
+      end
+
+      private
+
+      # @return [Enumerable<String>] Names of all services that are specified
+      #   in the Service Config. These include mixin services, as well as
+      #   some, all, or none of the library's own services
+      def services_in_config
+        return [] unless @service_config&.apis
+        @service_config.apis.map(&:name)
+      end
+
+      MIXIN_GEM_NAMES = {
+        LOCATIONS_SERVICE => "google-cloud-location",
+        IAM_SERVICE => "google-iam-v1",
+        LRO_SERVICE => "google-longrunning-operations"
+      }.freeze
+      private_constant :MIXIN_GEM_NAMES
+
+      # Since mixins are scope-limited to a couple of services, it is easier to
+      # have these in lookup tables than to construct a ServicePresenter
+
+      SERVICE_TO_DEPENDENCY = {
+        LOCATIONS_SERVICE => { "google-cloud-location" => ["~> 1.0"] },
+        IAM_SERVICE => { "google-iam-v1" => ["~> 1.3"] }
+      }.freeze
+      private_constant :SERVICE_TO_DEPENDENCY
+
+      SERVICE_TO_REQUIRE_STR = {
+        LOCATIONS_SERVICE => "google/cloud/location",
+        IAM_SERVICE => "google/iam/v1"
+      }.freeze
+      private_constant :SERVICE_TO_REQUIRE_STR
+
+      SERVICE_TO_REQUIRE_STR_REST = {
+        LOCATIONS_SERVICE => "google/cloud/location/rest",
+        IAM_SERVICE => "google/iam/v1/rest"
+      }.freeze
+      private_constant :SERVICE_TO_REQUIRE_STR_REST
+
+      SERVICE_TO_CLIENT_CLASS_NAME = {
+        LOCATIONS_SERVICE => "Google::Cloud::Location::Locations::Client",
+        IAM_SERVICE => "Google::Iam::V1::IAMPolicy::Client"
+      }.freeze
+      private_constant :SERVICE_TO_CLIENT_CLASS_NAME
+
+      SERVICE_TO_CLIENT_CLASS_NAME_REST = {
+        LOCATIONS_SERVICE => "Google::Cloud::Location::Locations::Rest::Client",
+        IAM_SERVICE => "Google::Iam::V1::IAMPolicy::Rest::Client"
+      }.freeze
+      private_constant :SERVICE_TO_CLIENT_CLASS_NAME_REST
+
+      SERVICE_TO_CLIENT_ATTR_NAME = {
+        LOCATIONS_SERVICE => "location_client",
+        IAM_SERVICE => "iam_policy_client"
+      }.freeze
+      private_constant :SERVICE_TO_CLIENT_ATTR_NAME
+
+      # @param service [String] full grpc name of the service
+      # @raise [ModelError]
+      # @return [Mixin]
+      def create_mixin service
+        unless SERVICE_TO_DEPENDENCY.key?(service) &&
+               SERVICE_TO_REQUIRE_STR.key?(service) &&
+               SERVICE_TO_REQUIRE_STR_REST.key?(service) &&
+               SERVICE_TO_CLIENT_CLASS_NAME.key?(service) &&
+               SERVICE_TO_CLIENT_CLASS_NAME_REST.key?(service) &&
+               SERVICE_TO_CLIENT_ATTR_NAME.key?(service)
+
+          error_text = "A mixin service #{service} is specified in service config, but " \
+                       "the Generator does not know of it."
+          raise ModelError, error_text
+        end
+
+        Mixin.new service,
+                  SERVICE_TO_DEPENDENCY[service],
+                  SERVICE_TO_REQUIRE_STR[service],
+                  SERVICE_TO_REQUIRE_STR_REST[service],
+                  SERVICE_TO_CLIENT_CLASS_NAME[service],
+                  SERVICE_TO_CLIENT_CLASS_NAME_REST[service],
+                  SERVICE_TO_CLIENT_ATTR_NAME[service]
+      end
+    end
+  end
+end

data/lib/gapic/model/model_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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 Model
+    ##
+    # Represents an error due to inconsistency in the Model
+    # that the Generator is attempting to Generate
+    #
+    class ModelError < StandardError
+    end
+  end
+end

data/lib/gapic/model/service/nonstandard_lro_provider.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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 Model
+    ##
+    # Service-level models
+    #
+    module Service
+      ##
+      # Nonstandard (AIP-151 nonconforming) long-running operation service-level model
+      # for the services that are LRO providers (contain polling methods for long-running operations)
+      #
+      # @!attribute [r] service_full_name
+      #   @return [String] Full grpc name of this service. E.g. `google.example.LroProvider`.
+      #
+      # @!attribute [r] polling_method_name
+      #   @return [String] Name of the method that is used to poll for LROs. E.g. `Poll`
+      #
+      # @!attribute [r] lro_object_full_name
+      #   @return [String] Full grpc name of the object that is returned by the polling method.
+      #   E.g. `google.cloud.compute.v1.Operation`
+      #
+      # @!attribute [r] operation_status_field
+      #   @return [String] In the Operation message for this service, the name of the `status` field.
+      #   The `status` field signals that the operation has finished. It should either contain symbols, and
+      #   be set to `:DONE` when finished or contain a boolean and be set to `true` when finished.
+      #
+      # @!attribute [r] operation_name_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `name` field.
+      #
+      # @!attribute [r] operation_err_code_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `error code` field.
+      #
+      # @!attribute [r] operation_err_msg_field
+      #   @return [String, nil] In the Operation message for this service, the name of the `error message` field.
+      #
+      # @!attribute [r] operation_response_fields
+      #   @return [Hash<String, String>] The map of the fields that need to be copied from the
+      #   long-running operation object that the polling method returns to the polling request.
+      #   The format is `name of the operation object field` -> `name of the polling request field` (`from -> to`).
+      #   E.g. `{"foo" => "bar"}` means that when constructing a polling request,
+      #   the following assignment should be carried out:
+      #   `lro_polling_request.bar = operation_object.foo`.
+      #
+      class NonstandardLroProvider
+        attr_reader :service_full_name
+        attr_reader :polling_method_name
+        attr_reader :lro_object_full_name
+        attr_reader :operation_status_field
+        attr_reader :operation_name_field
+        attr_reader :operation_err_code_field
+        attr_reader :operation_err_msg_field
+        attr_reader :operation_response_fields
+
+        ##
+        # @return [Boolean] Whether this is a model for a nonstandard LRO provider service
+        #
+        def nonstandard_lro?
+          true
+        end
+
+        ##
+        # @param service_full_name [String]
+        #   Full grpc name of this service. E.g. `google.example.LroProvider`.
+        #
+        # @param polling_method_name [String]
+        #   Name of the method that is used to poll for LROs. E.g. `Poll`
+        #
+        # @param lro_object_full_name
+        #   Full grpc name of the object that is returned by the polling method.
+        #   E.g. `google.cloud.compute.v1.Operation`
+        #
+        # @param operation_status_field [String]
+        #   In the Operation message for this service, the name of the `status` field.
+        #   The `status` field signals that the operation has finished. It should either contain symbols, and
+        #   be set to `:DONE` when finished or contain a boolean and be set to `true` when finished.
+        #
+        # @param operation_name_field [String, nil]
+        #   In the Operation message for this service, the name of the `name` field.
+        #
+        # @param operation_err_code_field [String, nil]
+        #   In the Operation message for this service, the name of the `error code` field.
+        #
+        # @param operation_err_msg_field [String, nil]
+        #   In the Operation message for this service, the name of the `error message` field.
+        #
+        # @param operation_response_fields [Hash<String, String>]
+        #   The map of the fields that need to be copied from the
+        #   long-running operation object that the polling method returns to the polling request.
+        #   The format is `name of the operation object field` -> `name of the polling request field` (`from -> to`).
+        #   E.g. `{"foo" => "bar"}` means that when constructing a polling request,
+        #   the following assignment should be carried out:
+        #   `lro_polling_request.bar = operation_object.foo`.
+        #
+        def initialize service_full_name,
+                       polling_method_name,
+                       lro_object_full_name,
+                       operation_status_field,
+                       operation_name_field,
+                       operation_err_code_field,
+                       operation_err_msg_field,
+                       operation_response_fields
+          @service_full_name = service_full_name
+          @polling_method_name = polling_method_name
+          @lro_object_full_name = lro_object_full_name
+          @operation_status_field = operation_status_field
+          @operation_name_field = operation_name_field
+          @operation_err_code_field = operation_err_code_field
+          @operation_err_msg_field = operation_err_msg_field
+          @operation_response_fields = operation_response_fields
+        end
+      end
+
+      ##
+      # Service does not provide nonstandard LRO polling capabilities
+      #
+      class NoNonstandardLro
+        include Singleton
+
+        ##
+        # @return [Boolean] Whether this is a model for a nonstandard LRO provider service
+        #
+        def nonstandard_lro?
+          false
+        end
+      end
+
+      class << self
+        ##
+        # Parses the service proto information to determine, whether it is
+        # a provider for nonstandard long-running operations polling
+        #
+        # @param service [Gapic::Schema::Service]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @return [NonstandardLroProvider, nil]
+        def parse_nonstandard_lro service
+          polling_method = find_polling_method service
+          return unless polling_method
+
+          # There should not be any methods that have the `operation_service` annotation
+          # in the LRO provider service.
+          # In theory there is nothing wrong with one LRO polling service using another
+          # LRO polling service, in practice there is potential for service intialization cycles
+          # Until we have a real usecase it's safer to assume an error in proto.
+          nonstandard_lro_candidates = service.methods.find_all do |m|
+            !m.operation_service.nil? && !m.operation_service.empty?
+          end
+
+          if nonstandard_lro_candidates.length.positive?
+            ops_service_method = nonstandard_lro_candidates[0]
+            error_text = "A service `#{service.name}` has a method annotated " \
+                         "with `polling_method` (`#{polling_method.name}`), and also a method annotated " \
+                         "with `operation_service` (`#{ops_service_method.name}`). " \
+                         "This means a grpc service tries to be a client " \
+                         "and a provider of the nonstandard LRO at the same time. " \
+                         "This is not supported."
+            raise ModelError, error_text
+          end
+
+          lro_object_full_name = polling_method.output.full_name
+
+          status_field = find_status_field service, polling_method
+          operation_status_field = status_field.name
+
+          operation_name_field = name_of_operation_field polling_method, ::Google::Cloud::OperationResponseMapping::NAME
+          operation_err_code_field = name_of_operation_field polling_method,
+                                                             ::Google::Cloud::OperationResponseMapping::ERROR_CODE
+          operation_err_msg_field = name_of_operation_field polling_method,
+                                                            ::Google::Cloud::OperationResponseMapping::ERROR_MESSAGE
+
+          # optionally, there might be fields in the polling method's input object
+          # that should be filled with information from the LRO object
+          ops_response_fields = polling_method.input.fields.find_all do |f|
+            !f.operation_response_field.nil? && !f.operation_response_field.empty?
+          end
+
+          operation_response_fields = ops_response_fields.to_h do |field|
+            [field.name, field.operation_response_field]
+          end
+
+          NonstandardLroProvider.new service.full_name,
+                                     polling_method.name,
+                                     lro_object_full_name,
+                                     operation_status_field,
+                                     operation_name_field,
+                                     operation_err_code_field,
+                                     operation_err_msg_field,
+                                     operation_response_fields
+        end
+
+        private
+
+        ##
+        # Returns a name of the polling method's output object (presumed to be LRO object)'s field
+        # that is marked with a given `operation_response_field` annotation,
+        # or nil if no such field exists.
+        #
+        # @param polling_method [Gapic::Schema::Method] the polling method
+        # @param ops_response_field [Integer] the value of the `operation_response_field` annotation
+        #
+        # @return [String]
+        #
+        def name_of_operation_field polling_method, ops_response_field
+          name_candidate = polling_method.output.fields.find do |f|
+            f.operation_field == ops_response_field
+          end
+          name_candidate&.name
+        end
+
+        ##
+        # If this service is provider for a nonstandard LRO,
+        # find the polling method.
+        # Otherwise returns nil.
+        #
+        # @param service [Gapic::Schema::Service]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Schema::Method, nil]
+        #
+        def find_polling_method service
+          # On a LRO service, one method should be marked as 'polling'
+          polling_method_candidates = service.methods.find_all do |m|
+            !m.polling_method.nil? && m.polling_method
+          end
+          if polling_method_candidates.length > 1
+            error_text = "A service #{service.name} has more than one method annotated " \
+                         "with `operation_polling_method`. This should not happen."
+            raise ModelError, error_text
+          end
+
+          return unless polling_method_candidates.length == 1
+
+          polling_method_candidates[0]
+        end
+
+        ##
+        # Find the `status` field in the LRO message that this service provides a
+        # polling functionality for
+        #
+        # @param service [Gapic::Schema::Service]
+        # @param polling_method [Gapic::Schema::Method]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Schema::Field]
+        #
+        def find_status_field service, polling_method
+          # The output of the polling method is an Operation, which should have at least
+          # a Status field
+          status_candidates = polling_method.output.fields.find_all do |f|
+            f.operation_field == ::Google::Cloud::OperationResponseMapping::STATUS
+          end
+
+          if status_candidates.length > 1
+            error_text = "A nonstandard LRO provider service `#{service.name}`'s " \
+                         "polling method `#{polling_method.name}`'s output message " \
+                         "`#{polling_method.output.name}` has more than one field annotated " \
+                         "with `google.cloud.operation_field = STATUS`. This is not supported."
+            raise ModelError, error_text
+          end
+
+          if status_candidates.empty?
+            error_text = "A nonstandard LRO provider service `#{service.name}`'s " \
+                         "polling method `#{polling_method.name}`'s output message " \
+                         "`#{polling_method.output.name}` does not have any fields annotated " \
+                         "with `google.cloud.operation_field = STATUS`. This is not supported."
+            raise ModelError, error_text
+          end
+
+          status_candidates[0]
+        end
+      end
+    end
+  end
+end

data/lib/gapic/model.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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/model/method/http_annotation"
+require "gapic/model/method/lro"
+require "gapic/model/method/routing"
+require "gapic/model/mixins"
+require "gapic/model/model_error"
+require "gapic/model/service/nonstandard_lro_provider"