graphiti 2.0.0.beta.5 → 2.0.0.beta.7

data/lib/graphiti/audit/report.rb

@@ -0,0 +1,226 @@
+module Graphiti
+  class Audit
+    class Report
+      ANSI = {red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, bold: 1, dim: 2}.freeze
+
+      ISSUE_HEADINGS = {
+        broken_relationship: "raised while being inspected",
+        missing_association_method: "will raise when the relationship is included: the model has no association method",
+        missing_guard_method: "will raise whenever the resource renders: the readable guard is not defined",
+        missing_sideload_filter: "will raise when the relationship is included: the related resource is missing the filter"
+      }.freeze
+
+      CHECKLIST = {
+        broken_relationship: ["all relationships inspectable", "relationship", "raised while being inspected"],
+        missing_association_method: ["all association methods defined", "association method", "missing"],
+        missing_guard_method: ["all readable guards defined", "readable guard", "missing"],
+        missing_sideload_filter: ["all sideload filters declared", "sideload filter", "missing"],
+        loads_on_every_render: ["all id-rendering loads preloaded", "relationship", "loading ids without preloading"]
+      }.freeze
+
+      Cell = Struct.new(:raw, :painted) do
+        def pad_to(width)
+          painted + " " * (width - raw.length)
+        end
+      end
+
+      def initialize(rows, color: $stdout.tty?)
+        @rows = rows
+        @color = color
+      end
+
+      def to_s
+        return "graphiti: no relationships found.\n" if @rows.empty?
+
+        (body + [summary]).join("\n")
+      end
+
+      private
+
+      def body
+        [""] + issue_sections + loading_section + would_load_section + checks_section
+      end
+
+      def issue_sections
+        row_finding_pairs = @rows.flat_map do |row|
+          row.findings.map { |finding| [row, finding] }
+        end
+
+        row_finding_pairs
+          .group_by { |_, finding| finding.check }
+          .sort_by { |check, _| ISSUE_HEADINGS.keys.index(check) || ISSUE_HEADINGS.size }
+          .flat_map { |check, group| issue_section(check, group) }
+      end
+
+      def issue_section(check, group)
+        findings = group.map(&:last)
+        label = findings.first.error? ? "ERROR" : "WARNING"
+        color = findings.first.error? ? :red : :yellow
+        fixes = findings.filter_map(&:remedy).uniq
+
+        section_heading(label, color, ISSUE_HEADINGS.fetch(check, check.to_s.tr("_", " "))) +
+          lines_grouped_by_resource(group.map { |row, finding| [row, finding.message] }) +
+          (fixes.size == 1 ? [fix_line(fixes.first), ""] : [])
+      end
+
+      def loading_section
+        rows = @rows.select { |row| loads_without_preload?(row) }
+        return [] if rows.empty?
+
+        section_heading("WARNING", :yellow, "rendering resource ids by loading an association the base_scope does not preload") +
+          lines_grouped_by_resource(rows.map { |row| [row, nil] }) +
+          ["  #{paint("That is a query per record rendered.", :dim)}",
+            fix_line("preload the association in base_scope, or drop `resource_ids`"),
+            "  #{paint("See www.graphiti.dev/concepts/relationships#customizing-relationships", :dim)}",
+            ""]
+      end
+
+      def loads_without_preload?(row)
+        row.resource_ids_source == :load && row.preloaded == false
+      end
+
+      def would_load_section
+        rows = @rows.select(&:would_start_loading?)
+        return [] if rows.empty?
+
+        verb = rows.size == 1 ? "renders" : "render"
+
+        section_heading("FYI", :blue, "#{count(rows.size, "belongs_to relationship")} #{verb} no resource ids") +
+          lines_grouped_by_resource(rows.map { |row| [row, nil] }) +
+          ["  #{paint("Nothing to fix. A request that includes the relationship still gets its ids.", :dim)}",
+            "",
+            "  #{paint("To render ids on every response, opt in:", :dim)}",
+            ""] +
+          opt_in_lines +
+          ["",
+            "  #{paint("Either would load the association on every render. That potential performance cost is why ids are opt-in.", :dim)}",
+            "  #{paint("Preloading the association in base_scope keeps that load cheap.", :dim)}",
+            "  #{paint("See www.graphiti.dev/concepts/relationships#belongs-to-resource-ids", :dim)}",
+            ""]
+      end
+
+      def checks_section
+        failure_counts = @rows.flat_map(&:findings).map(&:check).tally
+        loading = @rows.count { |row| loads_without_preload?(row) }
+        failure_counts[:loads_on_every_render] = loading if loading > 0
+
+        no_loads = @rows.none? { |row| row.resource_ids_source == :load }
+
+        lines = CHECKLIST.filter_map do |check, (passed, failure_noun, failure_suffix)|
+          if (failures = failure_counts[check])
+            "  #{paint("✗", :red)} #{count(failures, failure_noun)} #{failure_suffix}"
+          elsif check == :loads_on_every_render && no_loads
+            nil
+          else
+            "  #{paint("✓", :green)} #{passed}"
+          end
+        end
+
+        [paint("checks", :bold), ""] + lines + [""]
+      end
+
+      def section_heading(label, color, heading)
+        ["#{paint(label, color, :bold)} #{paint(heading, :bold)}", ""]
+      end
+
+      def fix_line(text)
+        "  #{paint("fix:", :green)} #{text}"
+      end
+
+      def lines_grouped_by_resource(pairs)
+        width = pairs.map { |row, _| declaration_cell(row).raw.length }.max
+
+        pairs.group_by { |row, _| row.resource }.sort_by { |resource, _| resource }.flat_map do |resource, group|
+          ["  #{paint(resource, :bold)}"] +
+            group.sort_by { |row, _| row.relationship.to_s }.map { |row, note|
+              declaration = declaration_cell(row)
+              note ? "    #{declaration.pad_to(width)}  #{note}" : "    #{declaration.painted}"
+            } +
+            [""]
+        end
+      end
+
+      def opt_in_lines
+        options = [
+          [[["resource_ids: ", :cyan], ["true", :yellow]], "on one relationship"],
+          [[["self.belongs_to_resource_ids_by_default = ", nil], [":always", :cyan]], "across the whole API"]
+        ]
+
+        rows = options.map do |parts, scope|
+          [cell(parts), cell([[scope, :dim]])]
+        end
+
+        aligned(rows, "    ")
+      end
+
+      def declaration_cell(row)
+        cell(declaration_parts(row))
+      end
+
+      def declaration_parts(row)
+        parts = [[row.type.to_s, :blue], [" ", nil], [":#{row.relationship}", :cyan]]
+
+        row.options.each do |key, value|
+          parts << [", ", nil] << ["#{key}: ", :cyan] << option_part(value)
+        end
+
+        parts
+      end
+
+      def option_part(value)
+        case value
+        when "..." then ["{ ... }", :dim]
+        when true, false then [value.inspect, :yellow]
+        when Symbol then [value.inspect, :cyan]
+        when String then [value.inspect, :green]
+        else [value.inspect, nil]
+        end
+      end
+
+      def cell(parts)
+        Cell.new(
+          parts.map { |text, _| text }.join,
+          parts.map { |text, style| paint(text, style) }.join
+        )
+      end
+
+      def aligned(rows, indent)
+        widths = rows.transpose.map { |column| column.map { |cell| cell.raw.length }.max }
+
+        rows.map do |cells|
+          line = cells.each_with_index.map { |cell, index|
+            index == cells.size - 1 ? cell.painted : cell.pad_to(widths[index])
+          }.join("  ")
+          indent + line
+        end
+      end
+
+      def summary
+        errors = @rows.count(&:error?)
+        loading = @rows.count { |row| loads_without_preload?(row) }
+        no_ids = @rows.count(&:would_start_loading?)
+
+        counts = [
+          count(@rows.group_by(&:resource).size, "resource"),
+          count(@rows.size, "relationship"),
+          paint(count(errors, "error"), errors > 0 ? :red : nil)
+        ]
+        counts << paint("#{loading} loading ids without preloading", :yellow) if loading > 0
+        counts << "#{no_ids} without resource ids" if no_ids > 0
+
+        "graphiti: #{counts.join(", ")}."
+      end
+
+      def count(number, noun)
+        "#{number} #{noun}#{"s" unless number == 1}"
+      end
+
+      def paint(text, *styles)
+        styles = styles.compact
+        return text unless @color && styles.any?
+
+        "\e[#{styles.map { |style| ANSI.fetch(style) }.join(";")}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/graphiti/audit.rb

@@ -0,0 +1,231 @@
+module Graphiti
+  # Resources register themselves as they load, so eager load before auditing.
+  class Audit
+    Finding = Struct.new(:severity, :check, :message, :remedy, keyword_init: true) do
+      def error?
+        severity == :error
+      end
+    end
+
+    Row = Struct.new(
+      :resource,
+      :relationship,
+      :type,
+      :target,
+      :resource_ids_source,
+      :resource_ids_source_if_always,
+      :resource_ids_default,
+      :resource_ids_blocker,
+      :preloaded,
+      :options,
+      :findings,
+      keyword_init: true
+    ) do
+      def would_start_loading?
+        return false if resource_ids_default == :never
+
+        resource_ids_source != :load && resource_ids_source_if_always == :load
+      end
+
+      def severity
+        return :error if findings.any?(&:error?)
+        findings.empty? ? :ok : :warning
+      end
+
+      def error?
+        severity == :error
+      end
+    end
+
+    def self.run(resources = nil)
+      new(resources).run
+    end
+
+    def self.findings(resources = nil)
+      run(resources).flat_map(&:findings)
+    end
+
+    def initialize(resources = nil)
+      @resources = resources || Graphiti.resources.reject(&:abstract_class?)
+    end
+
+    def run
+      @resources.sort_by { |resource| resource.name.to_s }.flat_map { |resource| rows_for(resource) }
+    end
+
+    private
+
+    def rows_for(resource_class)
+      model = inferred_model(resource_class)
+
+      resource_class.sideloads.map do |name, sideload|
+        row_for(resource_class, name, sideload, model)
+      end
+    end
+
+    def row_for(resource_class, name, sideload, model)
+      source = resource_ids_source(sideload)
+
+      Row.new(
+        resource: resource_class.name,
+        relationship: name,
+        type: sideload.type,
+        target: target_name(sideload),
+        resource_ids_source: source,
+        resource_ids_source_if_always: resource_ids_source_if_always(resource_class, sideload),
+        resource_ids_default: resource_class.belongs_to_resource_ids_by_default,
+        resource_ids_blocker: sideload.resource_ids_blocker,
+        preloaded: source == :load ? association_preloaded?(resource_class, sideload) : nil,
+        options: declaration_options(sideload),
+        findings: [
+          missing_association_method(sideload, model),
+          missing_guard_method(resource_class, sideload),
+          missing_sideload_filter(sideload)
+        ].compact
+      )
+    rescue => error
+      Row.new(
+        resource: resource_class.name,
+        relationship: name,
+        type: sideload.type,
+        resource_ids_source: :none,
+        options: {},
+        findings: [
+          Finding.new(
+            severity: :error,
+            check: :broken_relationship,
+            message: "#{error.class}: #{error.message.strip.lines.first.to_s.strip}"
+          )
+        ]
+      )
+    end
+
+    def declaration_options(sideload)
+      options = sideload.non_default_options
+      options[:base_scope] = "..." if sideload.customized_base_scope?
+      options[:scope] = "..." if sideload.class.scope_proc
+      options[:params] = "..." if sideload.class.params_proc
+      options
+    end
+
+    def resource_ids_source(sideload)
+      return :none unless sideload.render_resource_ids?
+
+      sideload.resource_ids_blocker.nil? ? :key : :load
+    end
+
+    def resource_ids_source_if_always(resource_class, sideload)
+      original = resource_class.belongs_to_resource_ids_by_default
+      resource_class.belongs_to_resource_ids_by_default = :always
+      resource_ids_source(sideload)
+    ensure
+      resource_class.belongs_to_resource_ids_by_default = original
+    end
+
+    def target_name(sideload)
+      if sideload.type == :polymorphic_belongs_to
+        children = sideload.children.values.filter_map { |child| short_name(child) }
+        return children.empty? ? nil : children.join(", ")
+      end
+
+      sideload.resource.class.name
+    rescue
+      nil
+    end
+
+    def short_name(sideload)
+      sideload.resource.class.name&.split("::")&.last
+    rescue
+      nil
+    end
+
+    def inferred_model(resource_class)
+      model = resource_class.model
+      model.is_a?(Class) ? model : nil
+    rescue Errors::ModelNotFound
+      nil
+    end
+
+    def missing_association_method(sideload, model)
+      return unless model
+      return if sideload.type == :polymorphic_belongs_to
+      return if model.method_defined?(sideload.association_name)
+      return if model.private_method_defined?(sideload.association_name)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_association_method,
+        message: "#{model.name} has no ##{sideload.association_name} method",
+        remedy: "define it, point the relationship at the real association with `as:`, or remove the relationship"
+      )
+    end
+
+    def missing_guard_method(resource_class, sideload)
+      guard = sideload.readable_guard_name
+      return unless guard
+      return if defines?(resource_class, guard)
+      return if defines?(sideload.resource.class, guard)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_guard_method,
+        message: "##{guard} is defined on neither #{resource_class.name} nor its related resource",
+        remedy: "define the guard on either resource"
+      )
+    end
+
+    def defines?(resource_class, method_name)
+      resource_class.method_defined?(method_name) ||
+        resource_class.private_method_defined?(method_name)
+    end
+
+    def missing_sideload_filter(sideload)
+      return if builds_its_own_query?(sideload)
+
+      key = sideload_filter_key(sideload)
+      return unless key
+
+      related = sideload.resource.class
+      return if related.filters.key?(key)
+
+      Finding.new(
+        severity: :error,
+        check: :missing_sideload_filter,
+        message: "#{related.name} is missing `filter #{key.inspect}`",
+        remedy: "declare the filter on the related resource"
+      )
+    end
+
+    def builds_its_own_query?(sideload)
+      sideload.class.params_proc || sideload.class.scope_proc
+    end
+
+    def sideload_filter_key(sideload)
+      case sideload.type
+      when :has_many, :has_one then sideload.foreign_key
+      when :many_to_many then sideload.true_foreign_key
+      when :belongs_to then sideload.primary_key
+      end
+    end
+
+    def association_preloaded?(resource_class, sideload)
+      scope = resource_class.new.base_scope
+      return nil unless scope.respond_to?(:includes_values)
+
+      preloads = [scope.includes_values, scope.preload_values, scope.eager_load_values]
+      association_names(preloads).include?(sideload.association_name.to_sym)
+    rescue
+      nil
+    end
+
+    def association_names(preload_values)
+      Array(preload_values).flat_map do |value|
+        case value
+        when Hash then value.keys.map(&:to_sym)
+        when Array then association_names(value)
+        else [value.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/graphiti/errors.rb

@@ -689,6 +689,53 @@ module Graphiti
       end
     end
 
+    class InvalidBelongsToResourceIds < Base
+      def initialize(resource_class, value)
+        @resource_class = resource_class
+        @value = value
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class.name}: belongs_to_resource_ids_by_default must be one of :foreign_key, :always, or :never. Got #{@value.inspect}.
+
+            :foreign_key - render resource ids wherever the foreign key already holds the related id (default)
+            :always      - render them for every belongs_to, loading the association when the foreign key cannot answer
+            :never       - render none
+
+          To render resource ids for a collection, ask for it one relationship at a time with `resource_ids: true`.
+        MSG
+      end
+    end
+
+    class MissingRelationshipMethod < Base
+      def initialize(resource_class, sideload, model)
+        @resource_class = resource_class
+        @sideload = sideload
+        @model = model
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class.name}: relationship #{@sideload.name.inspect} is declared, but #{@model.class.name} has no ##{@sideload.association_name} method.
+
+          Rendering the relationship reads the association off the model. Define ##{@sideload.association_name} on #{@model.class.name}, point the relationship at the real association with `as:`, or remove the relationship.
+          #{resource_ids_note}
+        MSG
+      end
+
+      private
+
+      def resource_ids_note
+        return "" unless @sideload.render_resource_ids?
+
+        <<~MSG
+
+          resource_ids is set on this relationship, so every render reads the association, not just requests that include it. See www.graphiti.dev/concepts/relationships#customizing-relationships.
+        MSG
+      end
+    end
+
     class MissingDependentFilter < Base
       def initialize(resource, filters)
         @resource = resource

data/lib/graphiti/query.rb

@@ -4,8 +4,15 @@ module Graphiti
   class Query
     attr_reader :resource, :association_name, :params, :action
 
-    # TODO: make the trailing optionals keywords once the satellite gems are rolled in - see Runner#query for the nil-padding this forces
-    def initialize(resource, params, association_name = nil, nested_include = nil, parents = [], action = nil)
+    def initialize(resource, params, *positional, association_name: nil, nested_include: nil, parents: [], action: nil)
+      if positional.any?
+        Graphiti::DEPRECATOR.warn("Passing Query.new trailing arguments positionally is deprecated. Use association_name:/nested_include:/parents:/action: keywords.")
+        association_name ||= positional[0]
+        nested_include ||= positional[1]
+        parents = positional[2] if positional.length > 2
+        action ||= positional[3]
+      end
+
       @resource = resource
       @association_name = association_name
       @params = params
@@ -21,6 +28,13 @@ module Graphiti
       !!@association_name
     end
 
+    # Concurrent::Map because sideload scopes resolve on pool threads
+    def entity_map
+      return root.entity_map unless root == self
+
+      @entity_map ||= Concurrent::Map.new
+    end
+
     def top_level?
       !association?
     end
@@ -110,9 +124,10 @@ module Graphiti
             relationship_name = sideload ? sideload.name : key
             hash[relationship_name] = Query.new sl_resource,
               @params,
-              key,
-              sub_hash,
-              query_parents, :all
+              association_name: key,
+              nested_include: sub_hash,
+              parents: query_parents,
+              action: :all
           else
             handle_missing_sideload(key)
           end
@@ -124,6 +139,10 @@ module Graphiti
       @parents ||= []
     end
 
+    def root
+      parents.first || self
+    end
+
     def fields
       @fields ||= begin
         hash = parse_fieldset(@params[:fields] || {})

data/lib/graphiti/request_validators/validator.rb

@@ -11,10 +11,12 @@ module Graphiti
       end
 
       def validate
+        validate_page
+
         # Right now, all requests - even reads - go through the validator
         # In the future these should have their own validation logic, but
         # for now we can just bypass
-        return true unless @params.has_key?(:data)
+        return errors.blank? unless @params.has_key?(:data)
 
         resource = @root_resource
         if @params[:data].has_key?(:type)
@@ -47,6 +49,13 @@ module Graphiti
 
       private
 
+      def validate_page
+        page = @params[:page]
+        return if page.nil? || page.respond_to?(:each_pair)
+
+        @errors.add(:page, :invalid, message: "must be an object")
+      end
+
       def process_relationships(resource, relationships, payload_path)
         relationships.each_key do |name|
           unless resource.class.sideload(name.to_sym)

data/lib/graphiti/resource/configuration.rb

@@ -6,6 +6,16 @@ module Graphiti
       DEFAULT_MAX_PAGE_SIZE = 1_000
 
       module Overrides
+        BELONGS_TO_RESOURCE_IDS_VALUES = [:foreign_key, :always, :never].freeze
+
+        def belongs_to_resource_ids_by_default=(val)
+          unless BELONGS_TO_RESOURCE_IDS_VALUES.include?(val)
+            raise Errors::InvalidBelongsToResourceIds.new(self, val)
+          end
+
+          super
+        end
+
         def serializer=(val)
           if val
             if super(Class.new(val))
@@ -21,6 +31,10 @@ module Graphiti
           send(:prepend, Polymorphism)
         end
 
+        def polymorphic?
+          polymorphic.present?
+        end
+
         def type=(val)
           val = val&.to_sym
           if (val = super)
@@ -90,7 +104,7 @@ module Graphiti
           :attributes_schema_by_default,
           :relationships_readable_by_default,
           :relationships_writable_by_default,
-          :always_include_resource_ids_by_default,
+          :belongs_to_resource_ids_by_default,
           :filters_accept_nil_by_default,
           :filters_deny_empty_by_default,
           :graphql_entrypoint,
@@ -116,6 +130,7 @@ module Graphiti
           default(klass, :attributes_schema_by_default, true)
           default(klass, :relationships_readable_by_default, true)
           default(klass, :relationships_writable_by_default, true)
+          default(klass, :belongs_to_resource_ids_by_default, :foreign_key)
           default(klass, :filters_accept_nil_by_default, false)
           default(klass, :filters_deny_empty_by_default, false)
 

data/lib/graphiti/resource/interface.rb

@@ -17,7 +17,7 @@ module Graphiti
 
         # @api private
         def _all(params, opts, base_scope)
-          runner = Runner.new(self, params, opts.delete(:query), :all)
+          runner = Runner.new(self, params, query: opts.delete(:query), action: :all)
           opts[:params] = params
           runner.proxy(base_scope, opts.merge(caching_options))
         end
@@ -36,7 +36,7 @@ module Graphiti
           params[:filter] ||= {}
           params[:filter][:id] = id if id
 
-          runner = Runner.new(self, params, nil, :find)
+          runner = Runner.new(self, params, action: :find)
 
           find_options = {
             single: true,
@@ -56,7 +56,7 @@ module Graphiti
         # Wrap models fetched outside graphiti so they render like any other proxy
         def wrap(models, base_scope = nil)
           validate_wrap_models!(models)
-          runner = Runner.new(self, {}, nil, :find)
+          runner = Runner.new(self, {}, action: :find)
           runner.proxy(base_scope, bypass_required_filters: true).tap do |proxy|
             proxy.data = models
           end