graphiti 2.0.0.beta.4 → 2.0.0.beta.6

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/rails/rake_helpers.rb

@@ -0,0 +1,42 @@
+require "graphiti/rails/test_helpers"
+
+module Graphiti
+  module Rails
+    # Rake's `namespace` takes a block, and a block does not open a new definee,
+    # so helpers defined inside one are defined on Object and turn up in every
+    # request spec in the host app. They live here to stay off that namespace.
+    module RakeHelpers
+      extend TestHelpers
+
+      module_function
+
+      # ::Rails throughout, because bare Rails resolves to Graphiti::Rails here.
+      def session
+        @session ||= ActionDispatch::Integration::Session.new(::Rails.application)
+      end
+
+      def setup_rails!
+        ::Rails.application.eager_load!
+        ::Rails.application.config.cache_classes = true
+        ::Rails.application.config.action_controller.perform_caching = false
+      end
+
+      def make_request(path, debug = false)
+        if path.split("/").length == 2
+          path = "#{ApplicationResource.endpoint_namespace}#{path}"
+        end
+        path << if path.include?("?")
+          "&cache=bust"
+        else
+          "?cache=bust"
+        end
+        path = "#{path}&debug=true" if debug
+        handle_request_exceptions do
+          headers = {Authorization: ENV["AUTHORIZATION_HEADER"]}.compact
+          session.get(path.to_s, headers: headers)
+        end
+        JSON.parse(session.response.body)
+      end
+    end
+  end
+end

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/polymorphism.rb

@@ -8,6 +8,8 @@ module Graphiti
       end
 
       def serializer_for(model)
+        return super unless self.class.polymorphic?
+
         if polymorphic_child?
           serializer
         else
@@ -17,10 +19,14 @@ module Graphiti
       end
 
       def associate_all(*args)
+        return super unless self.class.polymorphic?
+
         _associate(:associate_all, *args)
       end
 
       def associate(*args)
+        return super unless self.class.polymorphic?
+
         _associate(:associate, *args)
       end
 
@@ -34,6 +40,8 @@ module Graphiti
 
       module ClassMethods
         def inherited(klass)
+          return super unless polymorphic?
+
           klass.type = nil
           klass.model = klass.infer_model
           klass.endpoint = klass.infer_endpoint
@@ -42,6 +50,8 @@ module Graphiti
         end
 
         def sideload(name)
+          return super unless polymorphic?
+
           if (split_on = name.to_s.split(/^on__/)).length > 1
             on_type, name = split_on[1].split("--").map(&:to_sym)
           end

data/lib/graphiti/schema.rb

@@ -251,7 +251,7 @@ module Graphiti
             schema[:guard] = true
           end
 
-          if config.always_include_resource_ids?
+          if config.render_resource_ids?
             schema[:linkage] = true
           end