gapic-generator 0.2.2 → 0.4.0

data/lib/gapic/ruby_info.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright 2020 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
+  ##
+  # Various Ruby language information useful for generators.
+  #
+  module RubyInfo
+    class << self
+      ##
+      # A sorted list of Ruby's keywords.
+      #
+      # @see https://docs.ruby-lang.org/en/2.7.0/keywords_rdoc.html
+      #
+      # @return [Array<String>]
+      #
+      def keywords
+        @keywords ||= [
+          "__ENCODING__",
+          "__LINE__",
+          "__FILE__",
+          "BEGIN",
+          "END",
+          "alias",
+          "and",
+          "begin",
+          "break",
+          "case",
+          "class",
+          "def",
+          "defined?",
+          "do",
+          "else",
+          "elsif",
+          "end",
+          "ensure",
+          "false",
+          "for",
+          "if",
+          "in",
+          "module",
+          "next",
+          "nil",
+          "not",
+          "or",
+          "redo",
+          "rescue",
+          "retry",
+          "return",
+          "self",
+          "super",
+          "then",
+          "true",
+          "undef",
+          "unless",
+          "until",
+          "when",
+          "while",
+          "yield"
+        ].freeze
+      end
+
+      ##
+      # A sorted list of method names that generated code should avoid.
+      # This includes methods of the Object class (including BasicObject and
+      # Kernel), Ruby keywords, and a few special names including "initialize"
+      # and "configure".
+      #
+      # @return [Array<String>]
+      #
+      def excluded_method_names
+        @excluded_method_names ||= begin
+          object_methods = (Object.instance_methods + Object.private_instance_methods).map(&:to_s)
+          other_methods = ["configure", "initialize"]
+          (object_methods + other_methods + keywords).sort.freeze
+        end
+      end
+    end
+  end
+end

data/lib/gapic/schema/api.rb

@@ -51,6 +51,7 @@ module Gapic
           loader.load_file fd, request.file_to_generate.include?(fd.name)
         end
         @files.each { |f| f.parent = self }
+        @resource_types = analyze_resources
       end
 
       def containing_api
@@ -201,7 +202,7 @@ module Gapic
           config = config_file ? YAML.load_file(config_file) : {}
           protoc_options.each do |k, v|
             next if k == "configuration"
-            branch = key_to_str(k).split(".").reverse.inject(v) { |m, s| { str_to_key(s) => m } }
+            branch = parse_key(key_to_str(k)).reverse.inject(v) { |m, s| { str_to_key(s) => m } }
             config = deep_merge config, branch
           end
           config
@@ -224,6 +225,21 @@ module Gapic
         configuration[:generate_path_helpers_output] ||= false
       end
 
+      # Whether the override_proto_namespaces parameter was given in the configuration
+      def override_proto_namespaces_defined?
+        configuration.key? :override_proto_namespaces
+      end
+
+      # Sets the override_proto_namespaces parameter in the configuration
+      def override_proto_namespaces= value
+        configuration[:override_proto_namespaces] = value
+      end
+
+      # Whether namespace overrides apply to proto/grpc class references
+      def override_proto_namespaces?
+        configuration[:override_proto_namespaces] ||= false
+      end
+
       # Raw parsed json of the combined grpc service config files if provided
       # or an empty hash if no config was provided
       def grpc_service_config_raw
@@ -243,8 +259,77 @@ module Gapic
         end
       end
 
+      # Get a resource given its type string
+      def lookup_resource_type resource_type
+        @resource_types[resource_type]
+      end
+
+      # Given a service, find all common services that use it as a delegate.
+      def common_services_for delegate
+        @delegate_to_common ||= begin
+          (configuration[:common_services] || {}).each_with_object({}) do |(c, d), mapping|
+            (mapping[d] ||= []) << c
+          end
+        end
+        all_services = services
+        @delegate_to_common.fetch(delegate.address.join("."), []).map do |addr|
+          addr = addr.split "."
+          all_services.find { |s| s.address == addr }
+        end.compact.uniq
+      end
+
+      # Given a common service, return its delegate.
+      def delegate_service_for common
+        addr = (configuration[:common_services] || {})[common.address.join "."]
+        return nil unless addr
+        addr = addr.split "."
+        services.find { |s| s.address == addr }
+      end
+
       private
 
+      # Does a pre-analysis of all resources defined in the job. This has
+      # two effects:
+      # * Side effect: each resource has its parent_resources field set.
+      # * A mapping from resource type to resource wrapper is returned.
+      def analyze_resources
+        # In order to set parent_resources, we first populate a mapping from
+        # parsed pattern to resource mapping (in the patterns variable). This
+        # is done in one pass along with populating the resource type mapping.
+        # Then, we go through all resources again, get its expected parent
+        # patterns, and anything that shows up in the patterns mapping is taken
+        # to be a parent.
+        types = {}
+        patterns = {}
+        @files.each do |file|
+          file.resources.each { |resource| populate_resource_lookups resource, types, patterns }
+          file.messages.each { |message| populate_message_resource_lookups message, types, patterns }
+        end
+        types.each do |_type, resource|
+          parents = resource.parsed_parent_patterns
+                            .map { |pat| patterns[pat] }
+                            .compact.uniq
+          resource.parent_resources.replace parents
+        end
+        types
+      end
+
+      def populate_resource_lookups resource, types, patterns
+        types[resource.type] = resource
+        resource.parsed_patterns.each do |pat|
+          patterns[pat] = resource
+        end
+      end
+
+      def populate_message_resource_lookups message, types, patterns
+        populate_resource_lookups message.resource, types, patterns if message.resource
+        message.nested_messages.each do |nested|
+          populate_message_resource_lookups nested, types, patterns
+        end
+      end
+
+      # Parse a comma-delimited list of equals-delimited lists of strings, while
+      # mapping backslash-escaped commas and equal signs to literal characters.
       def parse_parameter str
         str.scan(/\\.|,|=|[^\\,=]+/)
            .each_with_object([[String.new]]) do |tok, arr|
@@ -261,6 +346,22 @@ module Gapic
            end
       end
 
+      # split the string on periods, but map backslash-escaped periods to
+      # literal periods.
+      def parse_key str
+        str.scan(/\.|\\.|[^\.\\]+/)
+           .each_with_object([String.new]) do |tok, arr|
+             if tok == "."
+               arr.append String.new
+             elsif tok.start_with? "\\"
+               arr.last << tok[1]
+             else
+               arr.last << tok
+             end
+             arr
+           end
+      end
+
       def str_to_key str
         str = str.to_s
         str.start_with?(":") ? str[1..-1].to_sym : str

data/lib/gapic/schema/loader.rb

@@ -64,9 +64,13 @@ module Gapic
           load_service registry, s, address, docs, [6, i]
         end
 
+        # Load top-level resources
+        resource_descriptors = file_descriptor.options[:".google.api.resource_definition"] if file_descriptor.options
+        resources = Array(resource_descriptors).map { |descriptor| Resource.new descriptor }
+
         # Construct and return the file.
         File.new file_descriptor, address, docs[path], messages, enums,
-                 services, file_to_generate, registry
+                 services, resources, file_to_generate, registry
       end
 
       # Updates the fields of a message and it's nested messages.
@@ -158,9 +162,12 @@ module Gapic
           load_field registry, e, address, docs, path + [6, i]
         end
 
+        resource_descriptor = descriptor.options[:".google.api.resource"] if descriptor.options
+        resource = resource_descriptor ? Resource.new(resource_descriptor) : nil
+
         # Construct, cache, and return.
         msg = Message.new(descriptor, address, docs[path], fields, extensions,
-                          nested_messages, nested_enums)
+                          resource, nested_messages, nested_enums)
         @prior_messages << msg
         add_to_registry registry, address, msg
       end

data/lib/gapic/schema/wrappers.rb

@@ -357,16 +357,19 @@ module Gapic
     # Wrapper for a protobuf file.
     #
     # @!attribute [r] messages
-    #   @ return [Enumerable<Message>] The top level messages contained in
+    #   @return [Enumerable<Message>] The top level messages contained in
     #     this file.
     # @!attribute [r] enums
-    #   @ return [Enumerable<Enum>] The top level enums contained in this
+    #   @return [Enumerable<Enum>] The top level enums contained in this
     #     file.
     # @!attribute [r] services
-    #   @ return [Enumerable<Service>] The services contained in this file.
+    #   @return [Enumerable<Service>] The services contained in this file.
+    # @!attribute [r] resources
+    #   @return [Enumerable<Resource>] The top level resources contained in
+    #     this file.
     class File < Proto
       extend Forwardable
-      attr_reader :messages, :enums, :services, :registry
+      attr_reader :messages, :enums, :services, :resources, :registry
 
       # Initializes a message object.
       # @param descriptor [Google::Protobuf::DescriptorProto] the protobuf
@@ -379,20 +382,23 @@ module Gapic
       #   file.
       # @param enums [Enumerable<Enum>] The top level enums of this file.
       # @param services [Enumerable<Service>] The services of this file.
+      # @param resources [Enumerable<Resource>] The resources from this file.
       # @param generate [Boolean] Whether this file should be generated.
       def initialize descriptor, address, docs, messages, enums, services,
-                     generate, registry
+                     resources, generate, registry
         super descriptor, address, docs
         @messages = messages || []
         @enums = enums || []
         @services = services || []
+        @resources = resources || []
         @generate = generate
         @registry = registry
 
         # Apply parent
         @messages.each { |m| m.parent = self }
-        @enums.each    { |m| m.parent = self }
+        @enums.each { |m| m.parent = self }
         @services.each { |m| m.parent = self }
+        @resources.each { |m| m.parent = self }
       end
 
       def containing_file
@@ -413,13 +419,6 @@ module Gapic
         options[:ruby_package] if options
       end
 
-      # @return [Array<Google::Api::ResourceDescriptor>] A representation of the resource.
-      #   This is generally intended to be attached to the "name" field.
-      #   See `google/api/resource.proto`.
-      def resources
-        options[:".google.api.resource_definition"] if options
-      end
-
       # @!method name
       #   @return [String] file name, relative to root of source tree.
       # @!method package
@@ -511,6 +510,8 @@ module Gapic
     #   @ return [Enumerable<Field>] The fields of a message.
     # @!attribute [r] extensions
     #   @ return [Enumerable<Field>] The extensions of a message.
+    # @!attribute [r] resource
+    #   @ return [Resource,nil] A representation of the resource.
     # @!attribute [r] nested_messages
     #   @ return [Enumerable<Message>] The nested message declarations of a
     #      message.
@@ -518,7 +519,7 @@ module Gapic
     #   @ return [Enumerable<Enum>] The nested enum declarations of a message.
     class Message < Proto
       extend Forwardable
-      attr_reader :fields, :extensions, :nested_messages, :nested_enums
+      attr_reader :fields, :extensions, :resource, :nested_messages, :nested_enums
 
       # Initializes a message object.
       # @param descriptor [Google::Protobuf::DescriptorProto] the protobuf
@@ -529,15 +530,17 @@ module Gapic
       #   of the proto. See #docs for more info.
       # @param fields [Enumerable<Field>] The fields of this message.
       # @param extensions [Enumerable<Field>] The extensions of this message.
+      # @param resource [Resource,nil] The resource of this message, or nil if none.
       # @param nested_messages [Enumerable<Message>] The nested message
       #   declarations of this message.
       # @param nested_enums [Enumerable<Enum>] The nested enum declarations
       #   of this message.
-      def initialize descriptor, address, docs, fields, extensions,
+      def initialize descriptor, address, docs, fields, extensions, resource,
                      nested_messages, nested_enums
         super descriptor, address, docs
         @fields = fields || []
         @extensions = extensions || []
+        @resource = resource
         @nested_messages = nested_messages || []
         @nested_enums = nested_enums || []
 
@@ -545,13 +548,7 @@ module Gapic
         @extensions.each      { |x| x.parent = self }
         @nested_messages.each { |m| m.parent = self }
         @nested_enums.each    { |e| e.parent = self }
-      end
-
-      # @return [Google::Api::ResourceDescriptor] A representation of the resource.
-      #   This is generally intended to be attached to the "name" field.
-      #   See `google/api/resource.proto`.
-      def resource
-        options[:".google.api.resource"] if options
+        @resource.parent = self if @resource
       end
 
       # @return [Boolean] whether this type is a map entry
@@ -736,5 +733,95 @@ module Gapic
         :options
       )
     end
+
+    # Wrapper for a protobuf Resource.
+    #
+    # Unlike most wrappers, this does not subclass the {Proto} wrapper because
+    # it does not use the fields exposed by that wrapper (`address`, `docs`,
+    # etc.) This is here principally to augment the resource definition with
+    # information about resource parent-child relationships.
+    #
+    # Resource parentage is defined implicitly by path patterns. The algorithm
+    # is as follows:
+    # * If the final segment of a pattern is an ID segment (i.e. `*` or some
+    #   `{name}`) then remove it and the previous segment (which we assume to
+    #   be the corresponding collection identifier, as described in AIP-122.)
+    #   The resulting pattern is what we expect a parent to have.
+    # * If the final segment is static, then assume the pattern represents a
+    #   singleton resource (AIP-156) and remove only that one segment. The
+    #   resulting pattern is what we expect a parent to have.
+    #
+    # The {Resource#parsed_parent_patterns} method returns the set of patterns
+    # we expect of parents. It is then possible to search for resources with
+    # those patterns to determine what the parents are.
+    #
+    # @!attribute [rw] parent
+    #   @return [Gapic::Schema::File,Gapic::Schema::Message] The parent object.
+    # @!attribute [r] descriptor
+    #   @return [Array<Gapic::Schema::ResourceDescriptor>] The resource
+    #     descriptor.
+    # @!attribute [r] parsed_patterns
+    #   @return [Array<Array<String>>] The normalized, segmented forms of the
+    #     patterns. Normalized means all ID segments are replaced by asterisks
+    #     to remove non-structural differences due to different names being
+    #     used. Segmented means simply split on slashes.
+    #     For example, if a pattern is `"projects/{project}""`, the
+    #     corresponding parsed pattern would be `["projects", "*"]`.
+    # @!attribute [r] parent_resources
+    #   @return [Array<Gapic::Schema::Resource>] Parent resources
+    class Resource
+      extend Forwardable
+      attr_reader :descriptor, :parsed_patterns, :parent_resources
+      attr_accessor :parent
+
+      # Initializes a resource object.
+      # @param descriptor [Google::Protobuf::ResourceDescriptor] the protobuf
+      #   representation of this resource.
+      def initialize descriptor
+        @parent = nil
+        @descriptor = descriptor
+        @parsed_patterns = descriptor.pattern.map do |pattern|
+          pattern.split("/").map do |segment|
+            segment =~ %r{\{[^/\}]+(=[^\}]+)?\}} ? "*" : segment
+          end.freeze
+        end.freeze
+        @parent_resources = []
+      end
+
+      # Returns the "root" of this schema.
+      # @return [Gapic::Schema::Api]
+      def containing_api
+        parent&.containing_api
+      end
+
+      # Returns the file containing this proto entity
+      # @return [Gapic::Schema::File]
+      def containing_file
+        parent&.containing_file
+      end
+
+      # Returns parsed patterns for the expected parents.
+      # @return [Array<Array<String>>]
+      def parsed_parent_patterns
+        @parsed_patterns.map do |pat|
+          parent = pat.last =~ /^\*\*?$/ ? pat[0...-2] : pat[0...-1]
+          parent.empty? ? nil : parent
+        end.compact.uniq
+      end
+
+      # @!method type
+      #   @return [String] the resource type string.
+      # @!method pattern
+      #   @return [Array<String>] the set of patterns.
+      # @!method name_field
+      #   @return [String] the field on the resource that designates the
+      #     resource name field. If omitted, this is assumed to be "name".
+      def_delegators(
+        :descriptor,
+        :type,
+        :pattern,
+        :name_field
+      )
+    end
   end
 end