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

data/lib/graphiti/sideload/belongs_to.rb

@@ -3,40 +3,33 @@ class Graphiti::Sideload::BelongsTo < Graphiti::Sideload
     :belongs_to
   end
 
-  def default_include_resource_ids?
-    linkage_from_foreign_key?
+  def default_render_resource_ids?
+    case parent_resource_class&.belongs_to_resource_ids_by_default
+    when :always then renderable_at_all?
+    when :never then false
+    else resource_ids_from_foreign_key?
+    end
+  end
+
+  def renderable_at_all?
+    readable_guarded? || readable?
   end
 
-  # The parent already carries the foreign key, and for a plain belongs_to
-  # that key *is* the related id, so linkage costs nothing. Anything that can
-  # change which record the relationship resolves to, or what type it carries,
-  # has to load the association instead:
-  #
-  #   - a scope/params block or a base_scope can filter out the record the
-  #     foreign key points at, so the key would claim a relationship the API
-  #     would not actually return
-  #   - a polymorphic target takes its type from the record, not from the
-  #     relationship, so the key alone cannot say what type the id has
-  #   - a remote resource has no local foreign key to read
-  #   - a custom primary_key points the relationship at some other column, so
-  #     the key holds that column's value rather than the related id
-  def linkage_from_foreign_key?
-    # Ask before resolving #resource: an unreadable relationship renders
-    # nothing, and its resource class may not even be inferrable.
-    return false unless readable?
-    return false unless foreign_key_is_related_id?
-    return false if polymorphic_child?
-    return false if self.class.scope_proc || self.class.params_proc
-    return false if @base_scope
-    return false if remote?
-    return false if resource.class.polymorphic.present?
+  def resource_ids_blocker
+    return :unreadable unless renderable_at_all?
+    return :custom_primary_key unless foreign_key_is_related_id?
+    return :polymorphic_child if polymorphic_child?
+    return :scope_block if self.class.scope_proc
+    return :params_block if self.class.params_proc
+    return :base_scope if @base_scope
+    return :remote if remote?
+    return :polymorphic_resource if resource.class.polymorphic.present?
 
-    true
+    nil
   end
 
-  # The foreign key can stand in for the related id only when the two hold the
-  # same value. base_filter matches the key against primary_key, so pointing
-  # that at another column means the key holds that column instead.
+  # base_filter matches the foreign key against primary_key, so a custom
+  # primary_key means the key holds that column's value, not the related id.
   def foreign_key_is_related_id?
     primary_key == :id
   end

data/lib/graphiti/sideload.rb

@@ -20,6 +20,7 @@ module Graphiti
     def initialize(name, opts)
       @name = name
       validate_options!(opts)
+      translate_deprecated_options!(opts)
       @parent_resource_class = opts[:parent_resource]
       @resource_class_name = opts[:resource]
       @primary_key = opts[:primary_key]
@@ -42,7 +43,7 @@ module Graphiti
       @group_name = opts[:group_name]
       @polymorphic_child = opts[:polymorphic_child]
       @parent = opts[:parent]
-      @always_include_resource_ids = opts[:always_include_resource_ids]
+      @render_resource_ids = opts[:resource_ids]
 
       if polymorphic_child?
         parent.resource.polymorphic << resource_class
@@ -110,6 +111,31 @@ module Graphiti
       dynamic_flag?(@readable) || dynamic_flag?(@writable)
     end
 
+    def readable_guarded?
+      dynamic_flag?(@readable)
+    end
+
+    def readable_guard_name
+      @readable.to_sym if @readable.is_a?(Symbol) || @readable.is_a?(String)
+    end
+
+    def non_default_options
+      options = {}
+      options[:as] = association_name if @as
+      options[:primary_key] = primary_key unless primary_key == :id
+      options[:single] = true if single?
+      options[:remote] = @remote if remote?
+      options[:link] = @link unless @link.nil?
+      options[:readable] = @readable unless @readable.nil? || @readable == true
+      options[:writable] = @writable unless @writable.nil? || @writable == true
+      options[:resource_ids] = @render_resource_ids unless @render_resource_ids.nil?
+      options
+    end
+
+    def customized_base_scope?
+      !!@base_scope
+    end
+
     def single?
       !!@single
     end
@@ -122,24 +148,21 @@ module Graphiti
       !!@polymorphic_as
     end
 
-    # False everywhere but a plain belongs_to - see
-    # Sideload::BelongsTo#linkage_from_foreign_key?.
-    def linkage_from_foreign_key?
-      false
+    def resource_ids_from_foreign_key?
+      resource_ids_blocker.nil?
     end
 
-    # nil at either of the first two levels means "not specified" rather
-    # than "false".
-    def always_include_resource_ids?
-      return !!@always_include_resource_ids unless @always_include_resource_ids.nil?
+    def resource_ids_blocker
+      :no_foreign_key_on_parent
+    end
 
-      configured = parent_resource_class&.always_include_resource_ids_by_default
-      return !!configured unless configured.nil?
+    def render_resource_ids?
+      return !!@render_resource_ids unless @render_resource_ids.nil?
 
-      default_include_resource_ids?
+      default_render_resource_ids?
     end
 
-    def default_include_resource_ids?
+    def default_render_resource_ids?
       false
     end
 
@@ -434,6 +457,18 @@ module Graphiti
       false
     end
 
+    def translate_deprecated_options!(opts)
+      return unless opts.key?(:always_include_resource_ids)
+
+      Graphiti::DEPRECATOR.deprecation_warning(
+        :always_include_resource_ids,
+        "Use :resource_ids instead (#{opts[:parent_resource]&.name}##{@name})"
+      )
+
+      value = opts.delete(:always_include_resource_ids)
+      opts[:resource_ids] = value unless opts.key?(:resource_ids)
+    end
+
     def validate_options!(opts)
       if opts[:remote]
         if opts[:resource]

data/lib/graphiti/spec_helpers/matchers.rb

@@ -0,0 +1,196 @@
+module Graphiti
+  module SpecHelpers
+    # Assertions against a resource's DSL. The schema specs cannot cover
+    # adapter-dependent options (primary key, foreign key, and so on) because
+    # the schema does not carry them; these read the resource config directly.
+    module Matchers
+      class BaseMatcher
+        GRAPHITI_OPTS = [].freeze
+        GRAPHITI_CONFIG_KEY = ""
+        EXPECTED_ACTION = ""
+
+        def description
+          "#{self.class::EXPECTED_ACTION} #{target}"
+        end
+
+        def failure_message
+          "expected that #{resource.class} would #{self.class::EXPECTED_ACTION} #{target}\n#{@opt_failures.join("\n")}"
+        end
+
+        def failure_message_when_negated
+          "expected that #{resource.class} would not #{self.class::EXPECTED_ACTION} #{target}"
+        end
+
+        def opt_failure_message(opt, expected, actual)
+          "expected that #{opt} would be #{expected}, was #{actual}"
+        end
+
+        def does_not_match?(resource)
+          !matches?(resource)
+        end
+
+        def matches?(resource)
+          @resource = resource
+
+          expected? && expected_opts?
+        end
+
+        def with_options(opts)
+          @opts = opts
+          self
+        end
+
+        private
+
+        def actual_opts
+          self.class::GRAPHITI_OPTS & opts.keys
+        end
+
+        def config
+          @config ||= resource.class.config[self.class::GRAPHITI_CONFIG_KEY][target]
+        end
+
+        def expected_opts?
+          return false unless config
+
+          actual_opts.map { |opt| assert_opt(opt) }.all?(true)
+        end
+      end
+
+      class RelationMatcher < BaseMatcher
+        GRAPHITI_OPTS = %i[primary_key foreign_key resource readable writable link single].freeze
+        GRAPHITI_CONFIG_KEY = :sideloads
+        EXPECTED_ACTION = ""
+
+        def initialize(target)
+          @target = target
+          @opts = {}
+          @opt_failures = []
+        end
+
+        private
+
+        attr_reader :target, :opts, :resource
+
+        def assert_opt(opt)
+          asserted_opt = opt == :resource ? :resource_class : opt
+          return true if config.send(asserted_opt) == opts[opt]
+
+          @opt_failures << opt_failure_message(opt, opts[opt], config.send(asserted_opt))
+          false
+        end
+
+        def expected?
+          config && config.type == relation_name
+        end
+
+        # BelongsToMatcher -> :belongs_to, matching Sideload#type.
+        def relation_name
+          self.class.name.demodulize.gsub("Matcher", "").underscore.to_sym
+        end
+      end
+
+      class BelongsToMatcher < RelationMatcher
+        EXPECTED_ACTION = "belong to"
+      end
+
+      class HasManyMatcher < RelationMatcher
+        EXPECTED_ACTION = "have many"
+      end
+
+      class HasOneMatcher < RelationMatcher
+        EXPECTED_ACTION = "have one"
+      end
+
+      class ResourceDSLMatcher < BaseMatcher
+        def initialize(target, type)
+          @target = target
+          @type = type
+          @opts = {}
+          @opt_failures = []
+        end
+
+        private
+
+        attr_reader :target, :type, :opts, :resource
+
+        def expected?
+          config && assert_type
+        end
+
+        def assert_type
+          return true if config[:type] == type
+
+          @opt_failures << opt_failure_message("type", type, config[:type])
+          false
+        end
+
+        def assert_opt(opt)
+          return true if config[opt] == opts[opt]
+
+          @opt_failures << opt_failure_message(opt, opts[opt], config[opt])
+          false
+        end
+      end
+
+      class ExposeAttributeMatcher < ResourceDSLMatcher
+        GRAPHITI_OPTS = %i[writable readable sortable filterable].freeze
+        GRAPHITI_CONFIG_KEY = :attributes
+        EXPECTED_ACTION = "expose"
+      end
+
+      class FilterAttributeMatcher < ResourceDSLMatcher
+        GRAPHITI_OPTS = %i[allow deny single required allow_nil deny_empty].freeze
+        GRAPHITI_CONFIG_KEY = :filters
+        EXPECTED_ACTION = "filter"
+      end
+
+      # @param [Symbol] relation
+      #
+      # @example expect(subject).to belong_to_resource(:user)
+      # @example expect(subject).to belong_to_resource(:user).with_options(foreign_key: :user_id, resource: UserResource)
+      # @example expect(subject).not_to belong_to_resource(:user)
+      def belong_to_resource(relation)
+        BelongsToMatcher.new(relation)
+      end
+
+      # @param [Symbol] relation
+      #
+      # @example expect(subject).to have_many_resources(:posts)
+      # @example expect(subject).to have_many_resources(:posts).with_options(foreign_key: :post_id, resource: PostResource)
+      # @example expect(subject).not_to have_many_resources(:posts)
+      def have_many_resources(relation)
+        HasManyMatcher.new(relation)
+      end
+
+      # @param [Symbol] relation
+      #
+      # @example expect(subject).to have_one_resource(:post)
+      # @example expect(subject).to have_one_resource(:post).with_options(foreign_key: :post_id, resource: PostResource)
+      # @example expect(subject).not_to have_one_resource(:post)
+      def have_one_resource(relation)
+        HasOneMatcher.new(relation)
+      end
+
+      # @param [Symbol] attribute
+      # @param [Symbol] type
+      #
+      # @example expect(subject).to expose_attribute(:name, :string)
+      # @example expect(subject).to expose_attribute(:name, :string).with_options(writable: false)
+      # @example expect(subject).not_to expose_attribute(:name, :string)
+      def expose_attribute(attribute, type)
+        ExposeAttributeMatcher.new(attribute, type)
+      end
+
+      # @param [Symbol] attribute
+      # @param [Symbol] type
+      #
+      # @example expect(subject).to filter_attribute(:name, :string)
+      # @example expect(subject).to filter_attribute(:name, :string).with_options(allow_nil: false)
+      # @example expect(subject).not_to filter_attribute(:name, :string)
+      def filter_attribute(attribute, type)
+        FilterAttributeMatcher.new(attribute, type)
+      end
+    end
+  end
+end

data/lib/graphiti/spec_helpers/rspec.rb

@@ -120,6 +120,7 @@ module Graphiti
 
         ::RSpec.configure do |rspec|
           rspec.include_context "graphiti resource testing", type: :resource
+          rspec.include Graphiti::SpecHelpers::Matchers, type: :resource
         end
       end
 

data/lib/graphiti/spec_helpers.rb

@@ -11,6 +11,7 @@ require "graphiti/spec_helpers/helpers"
 require "graphiti/spec_helpers/node"
 require "graphiti/spec_helpers/errors_proxy"
 require "graphiti/spec_helpers/errors"
+require "graphiti/spec_helpers/matchers"
 
 module Graphiti
   module SpecHelpers

data/lib/graphiti/util/serializer_relationships.rb

@@ -68,9 +68,9 @@ module Graphiti
           # sideload can resolve it to something the foreign key alone would
           # not predict, so the loaded records win. Only the un-included case
           # is worth short-circuiting.
-          if sideload_ref.linkage_from_foreign_key? &&
+          if sideload_ref.resource_ids_from_foreign_key? &&
               !self_ref.send(:included_anywhere?, @proxy.query.include_hash, sideload_ref.name)
-            linkage always: sideload_ref.always_include_resource_ids? do
+            linkage always: sideload_ref.render_resource_ids? do
               foreign_key = @object.public_send(sideload_ref.foreign_key)
 
               unless foreign_key.nil?
@@ -81,7 +81,7 @@ module Graphiti
               end
             end
           else
-            linkage always: sideload_ref.always_include_resource_ids?
+            linkage always: sideload_ref.render_resource_ids?
           end
 
           if link_ref
@@ -107,8 +107,31 @@ module Graphiti
 
       def data_proc
         sideload_ref = @sideload
+        resource_class_ref = @resource_class
         ->(_) {
-          if (records = @object.public_send(sideload_ref.association_name))
+          begin
+            records = @object.public_send(sideload_ref.association_name)
+          rescue NoMethodError => error
+            # #receiver raises ArgumentError when the error was built by hand
+            # rather than raised by a failed call, and a hand-built one can
+            # still carry a matching #name.
+            receiver = begin
+              error.receiver
+            rescue ArgumentError
+              nil
+            end
+
+            raise unless error.name == sideload_ref.association_name &&
+              receiver.equal?(@object)
+
+            # A private method exists, so "has no such method" would be a lie.
+            raise if @object.respond_to?(sideload_ref.association_name, true)
+
+            raise Errors::MissingRelationshipMethod
+              .new(resource_class_ref, sideload_ref, @object)
+          end
+
+          if records
             if records.respond_to?(:to_ary)
               records.each { |r| sideload_ref.resource.decorate_record(r) }
             else

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "2.0.0.beta.4"
+  VERSION = "2.0.0.beta.6"
 end

data/lib/graphiti.rb

@@ -166,6 +166,8 @@ require "graphiti/configuration"
 require "graphiti/context"
 require "graphiti/errors"
 require "graphiti/types"
+require "graphiti/audit"
+require "graphiti/audit/report"
 require "graphiti/schema"
 require "graphiti/schema_diff"
 require "graphiti/adapters/abstract"

data/lib/tasks/graphiti.rake

@@ -1,52 +1,36 @@
-namespace :graphiti do
-  include Graphiti::Rails::TestHelpers
-
-  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
+require "graphiti/rails/rake_helpers"
 
-  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
+namespace :graphiti do
+  helpers = Graphiti::Rails::RakeHelpers
 
   desc "Execute request without web server."
   task :request, [:path, :debug] => [:environment] do |_, args|
-    setup_rails!
+    helpers.setup_rails!
     Graphiti.logger = Graphiti.stdout_logger
     Graphiti::Debugger.preserve = true
     require "pp"
     path, debug = args[:path], args[:debug]
     puts "Graphiti Request: #{path}"
-    json = make_request(path, debug)
+    json = helpers.make_request(path, debug)
     pp json
     Graphiti::Debugger.flush if debug
   end
 
+  desc "Audit every relationship: what will raise, what loads to render ids, which render no ids, and which checks passed."
+  task audit: [:environment] do
+    helpers.setup_rails!
+    rows = Graphiti::Audit.run
+    puts Graphiti::Audit::Report.new(rows).to_s
+
+    exit 1 if rows.any?(&:error?)
+  end
+
   desc "Execute benchmark without web server."
   task :benchmark, [:path, :requests] => [:environment] do |_, args|
-    setup_rails!
+    helpers.setup_rails!
     took = Benchmark.ms {
       args[:requests].to_i.times do
-        make_request(args[:path])
+        helpers.make_request(args[:path])
       end
     }
     puts "Took: #{(took / args[:requests].to_f).round(2)}ms"

data/website/docusaurus.config.js

@@ -1,16 +1,41 @@
 // @ts-check
 const {themes} = require('prism-react-renderer');
 
+const codeBlockTheme = (theme, backgroundColor) => ({
+  ...theme,
+  plain: {...theme.plain, backgroundColor},
+});
+
+// Docusaurus prepends baseUrl to navbar and Link hrefs, but not to raw HTML
+// like announcementBar content, so that markup has to build its own absolute
+// paths. Always has a trailing slash.
+const baseUrl = process.env.DOCS_BASE_URL || '/';
+
+// The theme's strikethrough and underline on diff lines are inline styles, so
+// CSS cannot undo them. Colour and the +/- signs already carry it.
+const withoutDiffDecoration = (theme) => ({
+  ...theme,
+  styles: theme.styles.map(({types, style}) =>
+    types.some((type) => type === 'inserted' || type === 'deleted')
+      ? {types, style: {...style, textDecorationLine: undefined}}
+      : {types, style}
+  ),
+});
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Graphiti',
   tagline: 'Stylish Graph APIs',
   favicon: 'img/favicon.ico',
 
-  url: 'https://www.graphiti.dev',
-  // Project pages serve this repo under /graphiti/ until the domain moves
-  // here from graphiti-api.github.io, so the deploy sets DOCS_BASE_URL.
-  baseUrl: process.env.DOCS_BASE_URL || '/',
+  // Apex, matching the CNAME. This feeds canonical tags and sitemap.xml, so it
+  // has to agree with the host actually serving the site or the two split
+  // search ranking between them.
+  url: 'https://graphiti.dev',
+  // graphiti.dev resolves to this repo, so the site serves from the root.
+  // DOCS_BASE_URL still overrides it for a build served from the project-pages
+  // path, which is what /graphiti/ was during the beta.
+  baseUrl,
   organizationName: 'graphiti-api',
   projectName: 'graphiti',
 
@@ -75,7 +100,7 @@ const config = {
           {from: ['/cookbooks/customizing-sideloads'], to: '/topics/customizing-sideloads'},
           {from: ['/cookbooks/hopping-relationships'], to: '/topics/hopping-relationships'},
 
-          {from: ['/js/introduction'], to: '/js'},
+          {from: ['/js/introduction'], to: '/js/'},
           {
             from: [
               '/js/reads/index',
@@ -100,11 +125,24 @@ const config = {
             to: '/js/writes',
           },
         ],
+
+        // The 2.0 docs were staged under /graphiti/ for the whole beta, so
+        // those URLs are in the wild. createRedirects sees every generated
+        // route, which the static /1.13/ tree is not: that one is by hand.
+        createRedirects(existingPath) {
+          return [`/graphiti${existingPath}`];
+        },
       },
     ],
   ],
 
   themeConfig: {
+    announcementBar: {
+      // Changing the id un-dismisses the bar for everyone who has closed it.
+      id: 'graphiti-2-0-beta',
+      content: `Graphiti 2.0 is in beta, and the docs have been reorganized to describe it. <a href="${baseUrl}1.13/">Docs for 1.x</a>.`,
+      isCloseable: true,
+    },
     colorMode: {
       // Dark for a first-time visitor. Flip respectPrefersColorScheme to true
       // to follow the OS setting instead, in which case defaultMode only
@@ -122,19 +160,37 @@ const config = {
           position: 'right',
           // 1.x stays as the original Jekyll site, frozen under /1.13.
           //
-          // target '_self' is required. Without it the router treats this as
-          // an in-app route, finds no match, and renders the 404 page even
-          // though the file is served fine.
+          // The pathname:// prefix is required. It is Docusaurus' escape hatch
+          // for a path that is served statically but is not an app route:
+          // without it the link renders as a react-router push, which finds no
+          // match and shows the 404 page even though the file is served fine.
+          // The prefix is stripped before baseUrl is applied, and it also makes
+          // the link count as external, hence target '_self' to keep it from
+          // opening in a new tab.
           dropdownItemsAfter: [
-            {href: '/1.13/', label: '1.x', target: '_self'},
+            {href: 'pathname:///1.13/', label: '1.x', target: '_self'},
           ],
         },
         {href: 'https://github.com/graphiti-api/graphiti', label: 'GitHub', position: 'right'},
         {href: 'https://discord.gg/wgqkMBsSRV', label: 'Discord', position: 'right'},
       ],
     },
-    footer: {style: 'dark', copyright: `Graphiti is released under the MIT license.`},
-    prism: {theme: themes.github, darkTheme: themes.dracula, additionalLanguages: ['ruby', 'bash', 'json', 'http']},
+    footer: {
+      style: 'dark',
+      copyright: [
+        'Originally created by <a href="https://github.com/richmolj">Lee Richmond</a>,',
+        '<a href="https://github.com/wadetandy">Wade Tandy</a>, and',
+        '<a href="https://github.com/wagenet">Peter Wagenet</a>.',
+        'Maintained by <a href="https://github.com/jkeen">Jeff Keen</a>',
+        'with <a href="https://github.com/graphiti-api/graphiti/graphs/contributors">many contributors</a>.',
+        '<br />Graphiti is released under the MIT license.',
+      ].join(' '),
+    },
+    prism: {
+      theme: withoutDiffDecoration(themes.oneLight),
+      darkTheme: withoutDiffDecoration(codeBlockTheme(themes.oneDark, '#21252b')),
+      additionalLanguages: ['ruby', 'bash', 'json', 'http', 'diff'],
+    },
   },
 };