gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/schema/wrappers.rb

@@ -16,6 +16,9 @@
 
 require "gapic/formatting_utils"
 require "gapic/path_pattern"
+require "gapic/schema/proto_tools"
+
+require "google/cloud/tools/snippetgen/configlanguage/v1/snippet_config_language_pb"
 
 module Gapic
   module Schema
@@ -98,6 +101,7 @@ module Gapic
         @descriptor = descriptor
         @address = address
         @docs = docs
+        @options_extensions = nil
       end
 
       # Returns the "root" of this schema.
@@ -118,18 +122,51 @@ module Gapic
       # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
       #   cross-references, and render them simply as text. This can be used if
       #   it is known that the targets are not present in the current library.
+      # @param transport [:rest,:grpc] The transport for client classes.
+      #   Optional; falls back to the default transport if not given.
       # @return [String]
       #
-      def docs_leading_comments disable_xrefs: false
+      def docs_leading_comments disable_xrefs: false, transport: nil
         return nil if @docs.nil?
         return nil if @docs.leading_comments.empty?
 
+        transport ||= containing_api.default_transport
         lines = @docs.leading_comments.each_line.to_a
-        lines.map! { |line| line.start_with?(" ") ? line[1..-1] : line }
-        lines = FormattingUtils.format_doc_lines containing_api, lines, disable_xrefs: disable_xrefs
+        lines.map! { |line| line.start_with?(" ") ? line[1..] : line }
+        lines = FormattingUtils.format_doc_lines containing_api, lines,
+                                                 disable_xrefs: disable_xrefs,
+                                                 transport: transport
         lines.join
       end
 
+      ##
+      # Return the options. This method must be overridden by a subclass.
+      #
+      def options
+        raise UnimplementedError
+      end
+
+      ##
+      # Return a configuration of supported option extensions.
+      # This method should be overridden by a subclass.
+      #
+      def option_extension_names
+        {}
+      end
+
+      ##
+      # Return the value of the named option, or nil if not found.
+      #
+      def option_named name
+        return nil unless options
+        result = options[name]
+        return result unless result.nil?
+        name = option_extension_names.keys.find { |key| key.end_with? ".#{name}" } unless name.include? "."
+        return nil unless name
+        @options_extensions ||= ProtoTools.parse_options_extensions options, option_extension_names
+        @options_extensions[name]
+      end
+
       # @!method path
       #   @return [Array<Integer>]
       #     Identifies which part of the FileDescriptorProto was defined at
@@ -249,16 +286,34 @@ module Gapic
         @methods.each { |m| m.parent = self }
       end
 
+      OPTION_EXTENSION_NAMES = {
+        "google.api.default_host" => [1049, :string],
+        "google.api.oauth_scopes" => [1050, :string],
+        "google.api.api_version" => [525_000_001, :string]
+      }.freeze
+
+      ##
+      # Return a configuration of supported option extensions.
+      #
+      def option_extension_names
+        OPTION_EXTENSION_NAMES
+      end
+
       # @return [String] The hostname for this service
       #   (e.g. "foo.googleapis.com"). This should be specified with no
       #   prefix.
       def host
-        options[:".google.api.default_host"] if options
+        option_named "google.api.default_host"
       end
 
       # @return [Array<String>] The OAuth scopes information for the client.
       def scopes
-        String(options[:".google.api.oauth_scopes"]).split "," if options
+        String(option_named("google.api.oauth_scopes")).split ","
+      end
+
+      # @return [String] The API version for this service.
+      def api_version
+        option_named "google.api.api_version"
       end
 
       # @return [String] Ruby Package
@@ -269,9 +324,9 @@ module Gapic
       end
 
       # @return [Boolean] True if this service is marked as deprecated, false
-      # otherwise.
+      #   otherwise.
       def is_deprecated?
-        options[:deprecated] if options
+        option_named "deprecated"
       end
 
       # @return [Array<Google::Api::ResourceDescriptor>] A representation of the resource.
@@ -283,6 +338,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
@@ -322,12 +386,28 @@ module Gapic
         @output = output
       end
 
+      OPTION_EXTENSION_NAMES = {
+        "google.api.method_signature" => [1050, :string, :repeated],
+        "google.api.http" => [72_295_728, ::Google::Api::HttpRule],
+        "google.api.routing" => [72_295_729, ::Google::Api::RoutingRule],
+        "google.cloud.operation_polling_method" => [1250, :bool],
+        "google.cloud.operation_service" => [1249, :string],
+        "google.longrunning.operation_info" => [1049, ::Google::Longrunning::OperationInfo]
+      }.freeze
+
+      ##
+      # Return a configuration of supported option extensions.
+      #
+      def option_extension_names
+        OPTION_EXTENSION_NAMES
+      end
+
       # @return [Array<Array<String>>] The parameter lists
       #   defined for this method. See `google/api/client.proto`.
       def signatures
         return [] if options.nil?
 
-        Array(options[:".google.api.method_signature"]).map do |sig|
+        Array(option_named("google.api.method_signature")).map do |sig|
           String(sig).split ","
         end
       end
@@ -339,19 +419,48 @@ module Gapic
       #   Required for methods that return `google.longrunning.Operation`;
       #   invalid otherwise.
       def operation_info
-        options[:".google.longrunning.operation_info"] if options
+        option_named "google.longrunning.operation_info"
       end
 
       # @return [Boolean] True if this method is marked as deprecated, false
-      # otherwise.
+      #   otherwise.
       def is_deprecated?
-        options[:deprecated] if options
+        option_named("deprecated") == true
       end
 
       # @return [Google::Api::HttpRule] The HTTP bindings for this method. See
       #   `google/api/http.proto`.
       def http
-        options[:".google.api.http"] if options
+        option_named "google.api.http"
+      end
+
+      # @return [Google::Api::RoutingRule] The Routing bindings for this method. See
+      #   `google/api/routing.proto`.
+      def routing
+        option_named "google.api.routing"
+      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
+        option_named "google.cloud.operation_service"
+      end
+
+      # Nonstandard LRO annotation.
+      # @return [Boolean] Whether this method is a polling method
+      #   for a nonstandard LRO service
+      def polling_method
+        option_named "google.cloud.operation_polling_method"
       end
 
       # @!method name
@@ -441,7 +550,7 @@ module Gapic
 
       # @return [String] Ruby Package
       def ruby_package
-        options[:ruby_package] if options
+        option_named "ruby_package"
       end
 
       # @!method name
@@ -488,6 +597,12 @@ module Gapic
         @values.each { |v| v.parent = self }
       end
 
+      # @return [Boolean] True if this enum is marked as deprecated, false
+      #   otherwise.
+      def is_deprecated?
+        option_named "deprecated"
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the Enum.
       # @!method options
@@ -571,11 +686,36 @@ module Gapic
         @resource.parent = self if @resource
       end
 
+      OPTION_EXTENSION_NAMES = {
+        "google.api.resource" => [1053, ::Google::Api::ResourceDescriptor]
+      }.freeze
+
+      ##
+      # Return a configuration of supported option extensions.
+      #
+      def option_extension_names
+        OPTION_EXTENSION_NAMES
+      end
+
       # @return [Boolean] whether this type is a map entry
       def map_entry?
         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
+
+      # @return [Boolean] True if this message is marked as deprecated, false
+      #   otherwise.
+      def is_deprecated?
+        option_named "deprecated"
+      end
+
       # @!method name
       #   @return [String] the unqualified name of the message.
       # @!method oneof_decl
@@ -621,6 +761,22 @@ module Gapic
         super descriptor, address, docs
         @message = message
         @enum = enum
+        @oneof_siblings = nil
+      end
+
+      OPTION_EXTENSION_NAMES = {
+        "google.api.field_behavior" => [1052, :enum, :repeated],
+        "google.api.resource_reference" => [1055, ::Google::Api::ResourceReference],
+        "google.cloud.operation_field" => [1149, :enum],
+        "google.cloud.operation_request_field" => [1150, :string],
+        "google.cloud.operation_response_field" => [1151, :string]
+      }.freeze
+
+      ##
+      # Return a configuration of supported option extensions.
+      #
+      def option_extension_names
+        OPTION_EXTENSION_NAMES
       end
 
       # Whether this field is a message.
@@ -634,7 +790,7 @@ module Gapic
       # Whether this field is a repeated field.
       # @return [Boolean]
       def repeated?
-        label == Google::Protobuf::FieldDescriptorProto::Label::LABEL_REPEATED
+        label == :LABEL_REPEATED
       end
 
       # Whether this field is an enum.
@@ -670,23 +826,98 @@ module Gapic
       # @return [String] A reference to another resource message or resource
       #   definition. See `google/api/resource.proto`.
       def resource_reference
-        options[:".google.api.resource_reference"] if options
+        option_named "google.api.resource_reference"
       end
 
       # @return [Array<Google::Api::FieldBehavior>] A designation of a
       #   specific field behavior (required, output only, etc.) in protobuf
       #   messages.
       def field_behavior
-        return options[:".google.api.field_behavior"] if options
+        option_named("google.api.field_behavior") || []
+      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
+        option_named "google.cloud.operation_request_field"
+      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
+        option_named "google.cloud.operation_response_field"
+      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
+        option_named "google.cloud.operation_field"
       end
 
       # Specifically denotes a field as optional. While all fields in protocol
       # buffers are optional, this may be specified for emphasis if
       # appropriate.
       def optional?
-        field_behavior.include? Google::Api::FieldBehavior::OPTIONAL
+        field_behavior&.include? Google::Api::FieldBehavior::OPTIONAL
       end
 
       # Denotes a field as a part of oneof.
@@ -695,14 +926,14 @@ module Gapic
       # but since the indexes in the message's oneof table start with 0 as well
       # we need this to determine whether the field is a part of the oneof
       def oneof?
-        @descriptor.field? :oneof_index
+        @descriptor.has_oneof_index?
       end
 
       # Denotes a field as required. This indicates that the field **must** be
       # provided as part of the request, and failure to do so will cause an
       # error (usually `INVALID_ARGUMENT`).
       def required?
-        field_behavior.include? Google::Api::FieldBehavior::REQUIRED
+        field_behavior&.include? Google::Api::FieldBehavior::REQUIRED
       end
 
       # Denotes a field as output only. This indicates that the field is
@@ -710,21 +941,56 @@ module Gapic
       # nothing (the server *must* ignore it and *must not* throw an error as
       # a result of the field's presence).
       def output_only?
-        field_behavior.include? Google::Api::FieldBehavior::OUTPUT_ONLY
+        field_behavior&.include? Google::Api::FieldBehavior::OUTPUT_ONLY
       end
 
       # Denotes a field as input only. This indicates that the field is
       # provided in requests, and the corresponding field is not included in
       # output.
       def input_only?
-        field_behavior.include? Google::Api::FieldBehavior::INPUT_ONLY
+        field_behavior&.include? Google::Api::FieldBehavior::INPUT_ONLY
       end
 
       # Denotes a field as immutable. This indicates that the field may be set
       # once in a request to create a resource, but may not be changed
       # thereafter.
       def immutable?
-        field_behavior.include? Google::Api::FieldBehavior::IMMUTABLE
+        field_behavior&.include? Google::Api::FieldBehavior::IMMUTABLE
+      end
+
+      # Denotes a field as proto3 optional
+      def proto3_optional?
+        @descriptor.proto3_optional
+      end
+
+      # @return [Boolean] True if this field is marked as deprecated, false
+      #   otherwise.
+      def is_deprecated?
+        option_named "deprecated"
+      end
+
+      # @private
+      # Populate the oneof_siblings array. This is nil if this field is not part
+      # of a oneof, otherwise it's an array of fields that are members of the
+      # oneof, with the first element being the current field.
+      def populate_oneof_siblings! all_fields
+        return unless oneof?
+        @oneof_siblings = [self]
+        all_fields.each do |field|
+          @oneof_siblings << field if field != self && field.oneof? && field.oneof_index == oneof_index
+        end
+      end
+
+      # @private
+      # Override this to add a note related to oneofs being mutually exclusive.
+      def docs_leading_comments disable_xrefs: false, transport: nil
+        str = super
+        return str unless @oneof_siblings && @oneof_siblings.size > 1
+        siblings = @oneof_siblings.map { |field| "`#{field.name}`" }.join ", "
+        note = "Note: The following fields are mutually exclusive: " \
+               "#{siblings}. If a field in that set is populated, all other " \
+               "fields in the set will automatically be cleared."
+        str ? "#{str.strip}\n\n#{note}" : note
       end
 
       # @!method name
@@ -774,8 +1040,7 @@ module Gapic
         :default_value,
         :oneof_index,
         :json_name,
-        :options,
-        :proto3_optional?
+        :options
       )
     end
 
@@ -868,3 +1133,22 @@ module Gapic
     end
   end
 end
+
+module Google
+  module Cloud
+    module Tools
+      module SnippetGen
+        module ConfigLanguage
+          module V1
+            ##
+            # Additions to the SnippetConfig message
+            #
+            class SnippetConfig
+              attr_accessor :json_representation
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/uri_template/parser.rb

@@ -14,15 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/path_pattern"
+
 module Gapic
   module UriTemplate
     # A URI template parser.
     # see https://tools.ietf.org/html/rfc6570 URI Template
-    #
-    # @!attribute [r] path_pattern
-    #   @return [String] The path pattern to be parsed.
-    # @!attribute [r] segments
-    #   @return [Array<Segment|String>] The segments of the parsed path pattern.
     module Parser
       # @private
       # `/(?<positional>\*\*?)|{(?<name>[^\/]+?)(?:=(?<template>.+?))?}/`
@@ -30,14 +27,25 @@ module Gapic
         (?<positional>\*\*?)
         |
         {(?<name>[^/]+?)(?:=(?<template>.+?))?}
-      }x.freeze
+      }x
 
+      ##
+      # Parses the arguments out of URI template
+      # with their corresponding patterns
+      #
+      # @param [String] The uri template to be parsed.
+      # @return [Array<Array<String>] The arguments and their corresponding patterns
+      #
       def self.parse_arguments uri_template
         arguments = []
 
         while (match = URI_TEMPLATE.match uri_template)
           # The String before the match needs to be added to the segments
-          arguments << match[:name] if match[:name]
+          if match[:name]
+            name = match[:name]
+            template = match[:template] || ""
+            arguments << [name, template]
+          end
           uri_template = match.post_match
         end