gapic-generator 0.1.7 → 0.3.1

data/lib/gapic/resource_lookup.rb

@@ -26,57 +26,42 @@ module Gapic
 
     # @private
     def lookup!
-      resources = @api.files.flat_map { |file| lookup_file_resource_descriptors file }
-      resources.compact.uniq
-    end
-
-    # @private
-    def lookup_file_resource_descriptors file
       resources = []
-      resources += file.resources.select { |resource| service_resource_types.include? resource.type }
-      resources += file.messages.flat_map { |message| lookup_message_resources_descriptors message }
-      resources
-    end
-
-    # @private
-    def service_resource_types
-      @service_resource_types ||= begin
-        @service.methods.flat_map do |method|
-          message_resource_types method.input
-        end.uniq
+      @service.methods.each do |method|
+        resources.concat resources_for_message(method.input)
+        resources.concat resources_for_message(method.output) if @api.generate_path_helpers_output?
       end
+      resources.uniq
     end
 
     # @private
-    def message_resource_types message, seen_messages = []
-      return [] if seen_messages.include? message
+    def resources_for_message message, seen_messages = []
+      resources = []
+      return resources if seen_messages.include? message
       seen_messages << message
-      resource_types = []
-      resource_types << message.resource.type if message.resource
-      resource_types += message.nested_messages.map do |nested_message|
-        message_resource_types nested_message, seen_messages
+      resources << message.resource if message.resource
+      message.nested_messages.each do |nested_message|
+        resources.concat resources_for_message(nested_message, seen_messages)
       end
       message.fields.each do |field|
-        resource_types << field.resource_reference.type if field.resource_reference
-        resource_types += message_resource_types field.message, seen_messages if field.message?
+        resources.concat resources_for_reference(field.resource_reference) if field.resource_reference
+        resources.concat resources_for_message(field.message, seen_messages) if field.message?
       end
-      resource_types.flatten
+      resources
     end
 
     # @private
-    def lookup_message_resources_descriptors message
-      resources = []
-
-      # We don't expect service_resource_types to iclude nil, so we can use message.resource&.type
-      resources << message.resource if service_resource_types.include? message.resource&.type
-
-      if message.nested_messages
-        resources += message.nested_messages.flat_map do |nested_message|
-          lookup_message_resources_descriptors nested_message
-        end
+    # Given a reference (either a type or child type), return the corresponding
+    # resources.
+    def resources_for_reference reference
+      if (type = reference.type) && !type.empty?
+        Array(@api.lookup_resource_type(type))
+      elsif (child_type = reference.child_type) && !child_type.empty?
+        child_resource = @api.lookup_resource_type child_type
+        child_resource ? child_resource.parent_resources : []
+      else
+        []
       end
-
-      resources
     end
 
     # Lookup all resources for a given service.

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
@@ -208,6 +209,22 @@ module Gapic
         end
       end
 
+      # Whether the generate_path_helpers_output parameter was given in the configuration
+      def generate_path_helpers_output_defined?
+        configuration.key? :generate_path_helpers_output
+      end
+
+      # Sets the generate_path_helpers_output parameter in the configuration
+      def generate_path_helpers_output= value
+        configuration[:generate_path_helpers_output] = value
+      end
+
+      # Whether to generate path helpers for output as well as input messages
+      def generate_path_helpers_output?
+        # if not set in configuration, false by default
+        configuration[:generate_path_helpers_output] ||= 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
@@ -227,8 +244,53 @@ module Gapic
         end
       end
 
+      # Get a resource given its type string
+      def lookup_resource_type resource_type
+        @resource_types[resource_type]
+      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
+
       def parse_parameter str
         str.scan(/\\.|,|=|[^\\,=]+/)
            .each_with_object([[String.new]]) do |tok, arr|

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

@@ -107,14 +107,21 @@ module Gapic
         parent&.containing_file
       end
 
+      ##
       # Gets the cleaned up leading comments documentation
-      def docs_leading_comments
+      #
+      # @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.
+      # @return [String]
+      #
+      def docs_leading_comments disable_xrefs: false
         return nil if @docs.nil?
         return nil if @docs.leading_comments.empty?
 
         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
+        lines = FormattingUtils.format_doc_lines containing_api, lines, disable_xrefs: disable_xrefs
         lines.join
       end
 
@@ -350,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
@@ -372,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
@@ -406,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
@@ -504,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.
@@ -511,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
@@ -522,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 || []
 
@@ -538,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
@@ -729,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

data/templates/default/gem/entrypoint.erb

@@ -0,0 +1,8 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+# This gem does not autoload during Bundler.require. To load this gem,
+# issue explicit require statements for the packages desired, e.g.:
+<%- gem.packages.each do |package| -%>
+# require "<%= package.package_require %>"
+<%- end -%>

data/templates/default/gem/gemspec.erb

@@ -25,7 +25,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "gapic-common", "~> 0.2"
   <%- if gem.iam_dependency? -%>
-  gem.add_dependency "grpc-google-iam-v1", "~> 0.6.9"
+  gem.add_dependency "grpc-google-iam-v1", ">= 0.6.10", "< 2.0"
   <%- end -%>
 
   gem.add_development_dependency "google-style", "~> 1.24.0"

data/templates/default/gem/readme.erb

@@ -1,9 +1,9 @@
-# <%= gem.title %>
-
-<%= gem.description %>
+# Ruby Client for the <%= gem.title %> API
 
 <%= gem.summary %>
 
+<%= gem.description %>
+
 <%= gem.homepage %>
 
 ## Installation
@@ -12,6 +12,20 @@
 $ gem install <%= gem.name %>
 ```
 
+## Quick Start
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+<%- service = gem.packages.first&.services.first -%>
+<%- method = service&.methods.first -%>
+<%- if service && method -%>
+
+client = <%= service.create_client_call %>
+request = my_create_request
+response = client.<%= method.name %> request
+<%- end -%>
+```
+
 ## Supported Ruby Versions
 
 This library is supported on Ruby 2.4+.