gapic-generator 0.10.1 → 0.11.0

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,12 +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[:generate_yardoc_snippets] ||= false
+        configuration.fetch :generate_yardoc_snippets, true
       end
 
       # Whether to generate gapic metadata (drift manifest) file
@@ -293,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]
@@ -318,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]
@@ -398,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 "."

data/lib/gapic/schema/service_config_parser.rb

@@ -0,0 +1,118 @@
+# 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 "yaml"
+require "google/api/service.pb"
+
+module Gapic
+  module Schema
+    # Contains logic for parsing a subset of service.yaml used
+    # for the service generation
+    module ServiceConfigParser
+      class << self
+        CONFIG_VERSION_KEY = "config_version"
+        NAME_KEY = "name"
+        VERSION_KEY = "version"
+        ID_KEY = "id"
+        TITLE_KEY = "title"
+        APIS_KEY = "apis"
+        HTTP_KEY = "http"
+        HTTP_RULES_KEY = "rules"
+        HTTP_RULES_SELECTOR_KEY = "selector"
+        HTTP_RULES_VERBS_ALLOWED = ["get", "post", "put", "patch", "delete"].freeze
+        HTTP_RULES_BODY_KEY = "body"
+        HTTP_RULES_ADDITIONAL_BINDINGS_KEY = "additional_bindings"
+
+        ##
+        # Returns the parsed Google::Api::Service object.
+        # Only supports a limited subset of fields.
+        #
+        # @return [::Google::Api::Service]
+        #
+        def parse_service_yaml service_yaml_text
+          return nil unless service_yaml_text && !service_yaml_text.empty?
+          service_yaml = YAML.safe_load service_yaml_text
+          service = Google::Api::Service.new
+
+          if service_yaml.key? CONFIG_VERSION_KEY
+            config_ver = Google::Protobuf::UInt32Value.new
+            config_ver.value = service_yaml[CONFIG_VERSION_KEY]
+            service.config_version = config_ver
+          end
+
+          service.name = service_yaml[NAME_KEY] if service_yaml.key? NAME_KEY
+          service.id = service_yaml[ID_KEY] if service_yaml.key? ID_KEY
+          service.title = service_yaml[TITLE_KEY] if service_yaml.key? TITLE_KEY
+
+          service.apis = parse_apis service_yaml[APIS_KEY] if service_yaml.key? APIS_KEY
+          service.http = parse_http service_yaml[HTTP_KEY] if service_yaml.key? HTTP_KEY
+          service
+        end
+
+        private
+
+        # Parses the Apis section of the service yaml
+        # @return [Enumerable<::Google::Protobuf::Api>]
+        def parse_apis apis_yaml
+          apis_yaml.map { |api_yaml| parse_api api_yaml }
+        end
+
+        # Parses a single Api from yaml
+        # only supports a limited amount of fields
+        # @return [::Google::Protobuf::Api]
+        def parse_api api_yaml
+          api = ::Google::Protobuf::Api.new
+          api.name = api_yaml[NAME_KEY] if api_yaml.key? NAME_KEY
+          api.version = api_yaml[VERSION_KEY] if api_yaml.key? VERSION_KEY
+          api
+        end
+
+        # Parses a http section of the service yaml
+        # only supports a limited amount of fields
+        # @return [::Google::Api::Http]
+        def parse_http http_yaml
+          http = Google::Api::Http.new
+
+          if http_yaml.key? HTTP_RULES_KEY
+            http.rules = http_yaml[HTTP_RULES_KEY].map { |rule_yaml| parse_http_rule rule_yaml }
+          end
+
+          http
+        end
+
+        # Parses a single Http rule from yaml
+        # only supports a limited amount of fields
+        # NB: this method is recursive when parsing additional_bindings field
+        # @return [::Google::Api::HttpRule]
+        def parse_http_rule rule_yaml
+          rule = Google::Api::HttpRule.new
+          rule.selector = rule_yaml[HTTP_RULES_SELECTOR_KEY] if rule_yaml.key? HTTP_RULES_SELECTOR_KEY
+          verb_path = HTTP_RULES_VERBS_ALLOWED.find { |verb| rule_yaml[verb] }
+          rule.send "#{verb_path}=", rule_yaml[verb_path] if verb_path
+          rule.body = rule_yaml[HTTP_RULES_BODY_KEY] if rule_yaml.key? HTTP_RULES_BODY_KEY
+
+          if rule_yaml.key? HTTP_RULES_ADDITIONAL_BINDINGS_KEY
+            rule.additional_bindings = rule_yaml[HTTP_RULES_ADDITIONAL_BINDINGS_KEY].map do |binding_yaml|
+              parse_http_rule binding_yaml
+            end
+          end
+
+          rule
+        end
+      end
+    end
+  end
+end

data/lib/gapic/schema/wrappers.rb

@@ -283,6 +283,15 @@ module Gapic
         @resources ||= Gapic::ResourceLookup.for_service self
       end
 
+      # @return [String] The full name for this service
+      #   (e.g. `google.example.Service`).
+      #   Useful when matching against other pieces of information
+      #   which also reference full proto name, e.g. Service Config
+      #   or Grpc Service Config
+      def full_name
+        @address.join "."
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the service.
       # @!method options
@@ -343,7 +352,7 @@ module Gapic
       end
 
       # @return [Boolean] True if this method is marked as deprecated, false
-      # otherwise.
+      #   otherwise.
       def is_deprecated?
         options[:deprecated] if options
       end
@@ -354,6 +363,35 @@ module Gapic
         options[:".google.api.http"] if options
       end
 
+      # @return [Google::Api::RoutingRule] The Routing bindings for this method. See
+      #   `google/api/routing.proto`.
+      def routing
+        options[:".google.api.routing"] if options
+      end
+
+      # @return [String] The full name for this method
+      #   (e.g. `google.example.Service.Rpc`).
+      #   Useful when matching against other pieces of information
+      #   which also reference full proto name.
+      def full_name
+        @address.join "."
+      end
+
+      # Nonstandard LRO annotation.
+      # @return [String] Name of the nonstandard LRO service
+      #   that should be used for polling the operation object
+      #   that this method returns
+      def operation_service
+        options[:".google.cloud.operation_service"] if options
+      end
+
+      # Nonstandard LRO annotation.
+      # @return [Boolean] Whether this method is a polling method
+      #   for a nonstandard LRO service
+      def polling_method
+        options[:".google.cloud.operation_polling_method"] if options
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the method.
       # @!method options
@@ -576,6 +614,14 @@ module Gapic
         descriptor.options&.map_entry
       end
 
+      # @return [String] The full name for this message
+      #   (e.g. `google.example.Message`).
+      #   Useful when matching against other pieces of information
+      #   which also reference full proto name.
+      def full_name
+        @address.join "."
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the message.
       # @!method oneof_decl
@@ -682,6 +728,83 @@ module Gapic
         []
       end
 
+      # @return [String] The full name for this field
+      #   (e.g. `google.example.Message.field`).
+      #   Useful when matching against other pieces of information
+      #   which also reference full proto name.
+      def full_name
+        @address.join "."
+      end
+
+      # Nonstandard LRO annotation.
+      # This annotation goes on the field of the request message of the method
+      # that intiates a non-standard LRO.
+      #
+      # This annotation contains a field name of the request message
+      # of the LRO polling method. (e.g. `GetRegionOperationRequest`)
+      # (let's call it a 'referenced field')
+      #
+      # When the this method is called, this value should be saved.
+      # Later, when when polling for a nonstandard LRO, this saved value should
+      # be copied to the referenced field.
+      #
+      # This typically would be used for something that a caller method knows,
+      # but an Operation object might not have, e.g. a 'region_id'.
+      #
+      # So if this field is `region_id` and the annotation is
+      # `(google.cloud.operation_request_field) = "region"`, then:
+      #
+      #     `get_region_operation_request.region = this_message.region_id`
+      #
+      # In contrast to the `operation_response_field`, this field
+      # - goes onto the fields of the input message of the method that
+      #   initiates the LRO
+      # - semantically annotates a 'push': the value of this field gets
+      #   'pushed' into every LRO poll request.
+      #
+      # @return [String]
+      def operation_request_field
+        options[:".google.cloud.operation_request_field"] if options
+      end
+
+      # Nonstandard LRO annotation.
+      # This annotation goes on the field of the request message of the method
+      # that polls for a non-standard LRO.
+      #
+      # This annotation contains a field name of the LRO object (typically 'Operation')
+      # (let's call it a 'referenced field')
+      #
+      # When polling for a nonstandard LRO, the value of the field
+      # that this annotation is on should be copied from the referenced field.
+      #
+      # This typically would get used for something that is named differently in the
+      # operation polling request message vs in the Operation object, e.g. operation's name
+      #
+      # So if this field is `operation` and the annotation is
+      # `(google.cloud.operation_response_field) = "name"`, then:
+      #
+      #     `get_region_operation_request.operation = operation.name`
+      #
+      # In contrast to the `operation_request_field`, this field
+      # - goes onto the fields of the LRO polling method's input message
+      # - semantically annotates a 'pull', the value of the referenced field gets
+      #   'pulled' into this one.
+      #
+      # @return [String]
+      def operation_response_field
+        options[:".google.cloud.operation_response_field"] if options
+      end
+
+      # Nonstandard LRO annotation.
+      # This annotation goes on the fields of the nonstandard Operation message
+      # Is value can be either `NAME`, `STATUS`, `ERROR_MESSAGE`, or `ERROR_CODE`
+      # and the field encodes a corresponding aspect of the LRO behaviour.
+      #
+      # @return [Integer]
+      def operation_field
+        options[:".google.cloud.operation_field"] if options
+      end
+
       # Specifically denotes a field as optional. While all fields in protocol
       # buffers are optional, this may be specified for emphasis if
       # appropriate.

data/lib/google/api/auth.pb.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf'
+
+module Google
+  module Api
+    ::Protobuf::Optionable.inject(self) { ::Google::Protobuf::FileOptions }
+
+    ##
+    # Message Classes
+    #
+    class Authentication < ::Protobuf::Message; end
+    class AuthenticationRule < ::Protobuf::Message; end
+    class JwtLocation < ::Protobuf::Message; end
+    class AuthProvider < ::Protobuf::Message; end
+    class OAuthRequirements < ::Protobuf::Message; end
+    class AuthRequirement < ::Protobuf::Message; end
+
+
+    ##
+    # File Options
+    #
+    set_option :java_package, "com.google.api"
+    set_option :java_outer_classname, "AuthProto"
+    set_option :java_multiple_files, true
+    set_option :go_package, "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"
+    set_option :objc_class_prefix, "GAPI"
+
+
+    ##
+    # Message Fields
+    #
+    class Authentication
+      repeated ::Google::Api::AuthenticationRule, :rules, 3
+      repeated ::Google::Api::AuthProvider, :providers, 4
+    end
+
+    class AuthenticationRule
+      optional :string, :selector, 1
+      optional ::Google::Api::OAuthRequirements, :oauth, 2
+      optional :bool, :allow_without_credential, 5
+      repeated ::Google::Api::AuthRequirement, :requirements, 7
+    end
+
+    class JwtLocation
+      optional :string, :header, 1
+      optional :string, :query, 2
+      optional :string, :value_prefix, 3
+    end
+
+    class AuthProvider
+      optional :string, :id, 1
+      optional :string, :issuer, 2
+      optional :string, :jwks_uri, 3
+      optional :string, :audiences, 4
+      optional :string, :authorization_url, 5
+      repeated ::Google::Api::JwtLocation, :jwt_locations, 6
+    end
+
+    class OAuthRequirements
+      optional :string, :canonical_scopes, 1
+    end
+
+    class AuthRequirement
+      optional :string, :provider_id, 1
+      optional :string, :audiences, 2
+    end
+
+  end
+
+end
+

data/lib/google/api/backend.pb.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf'
+
+module Google
+  module Api
+    ::Protobuf::Optionable.inject(self) { ::Google::Protobuf::FileOptions }
+
+    ##
+    # Message Classes
+    #
+    class Backend < ::Protobuf::Message; end
+    class BackendRule < ::Protobuf::Message
+      class PathTranslation < ::Protobuf::Enum
+        define :PATH_TRANSLATION_UNSPECIFIED, 0
+        define :CONSTANT_ADDRESS, 1
+        define :APPEND_PATH_TO_ADDRESS, 2
+      end
+
+    end
+
+
+
+    ##
+    # File Options
+    #
+    set_option :java_package, "com.google.api"
+    set_option :java_outer_classname, "BackendProto"
+    set_option :java_multiple_files, true
+    set_option :go_package, "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"
+    set_option :objc_class_prefix, "GAPI"
+
+
+    ##
+    # Message Fields
+    #
+    class Backend
+      repeated ::Google::Api::BackendRule, :rules, 1
+    end
+
+    class BackendRule
+      optional :string, :selector, 1
+      optional :string, :address, 2
+      optional :double, :deadline, 3
+      optional :double, :min_deadline, 4
+      optional :double, :operation_deadline, 5
+      optional ::Google::Api::BackendRule::PathTranslation, :path_translation, 6
+      optional :string, :jwt_audience, 7
+      optional :bool, :disable_auth, 8
+      optional :string, :protocol, 9
+    end
+
+  end
+
+end
+

data/lib/google/api/billing.pb.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf'
+
+
+##
+# Imports
+#
+require 'google/api/metric.pb'
+
+module Google
+  module Api
+    ::Protobuf::Optionable.inject(self) { ::Google::Protobuf::FileOptions }
+
+    ##
+    # Message Classes
+    #
+    class Billing < ::Protobuf::Message
+      class BillingDestination < ::Protobuf::Message; end
+
+    end
+
+
+
+    ##
+    # File Options
+    #
+    set_option :java_package, "com.google.api"
+    set_option :java_outer_classname, "BillingProto"
+    set_option :java_multiple_files, true
+    set_option :go_package, "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"
+    set_option :objc_class_prefix, "GAPI"
+
+
+    ##
+    # Message Fields
+    #
+    class Billing
+      class BillingDestination
+        optional :string, :monitored_resource, 1
+        repeated :string, :metrics, 2
+      end
+
+      repeated ::Google::Api::Billing::BillingDestination, :consumer_destinations, 8
+    end
+
+  end
+
+end
+

data/lib/google/api/context.pb.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf'
+
+module Google
+  module Api
+    ::Protobuf::Optionable.inject(self) { ::Google::Protobuf::FileOptions }
+
+    ##
+    # Message Classes
+    #
+    class Context < ::Protobuf::Message; end
+    class ContextRule < ::Protobuf::Message; end
+
+
+    ##
+    # File Options
+    #
+    set_option :java_package, "com.google.api"
+    set_option :java_outer_classname, "ContextProto"
+    set_option :java_multiple_files, true
+    set_option :go_package, "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig"
+    set_option :objc_class_prefix, "GAPI"
+
+
+    ##
+    # Message Fields
+    #
+    class Context
+      repeated ::Google::Api::ContextRule, :rules, 1
+    end
+
+    class ContextRule
+      optional :string, :selector, 1
+      repeated :string, :requested, 2
+      repeated :string, :provided, 3
+      repeated :string, :allowed_request_extensions, 4
+      repeated :string, :allowed_response_extensions, 5
+    end
+
+  end
+
+end
+