graphiti 2.0.0.beta.9 → 2.0.0.beta.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a61d00c6968d2dc24afb8986d7b3b6051394ea73ac5d5a8104f1296f650fef47
-  data.tar.gz: bf367c2e3ff33e4240a3f11e3fbae780c75b7f727863e61fc0c546ae9cdfb5fe
+  metadata.gz: b1e331ab2dea47987ea47260eb0890c9a953d3435bba2e7ef37cbfbbc83fe5ab
+  data.tar.gz: 13a7483ead9f4ad5ed69390ff6a4a122a819813c2147c0a56dceebdfebc57e17
 SHA512:
-  metadata.gz: 4bb22545b0a2b590fb07a237857407a5a50ac2423dd33a5621af164d93b4d36237f54339fb083895e6d349ae64da3cf9cc2e24c363f63478cea691622f130331
-  data.tar.gz: 9da999b97fa15b04ca97420d6a6942c5d32b70bd0e8f27e33e01b8861cdd0206342d6afd11db15eb0c1d445beda4ce1f6a5ff5cceffcb54d5917e3a185cdc16a
+  metadata.gz: cca252389b52b5a2983407b4eff7cf7fe8b49759b478228f9d78303522bc40f2948a1784d6c863373f10521dc80b61d35f201009e830d8a968cc989b37d2ad81
+  data.tar.gz: 3fdfda722d09ddea6c366ca4102258bdea6d36c923be729ae141063e7e62b43ae0730f30a6422ae4448f858a5c1d4269f80180279d7939ce050c88008613cedb

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 graphiti changelog
 
+# [2.0.0-beta.10](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.9...v2.0.0-beta.10) (2026-08-24)
+
+
+### Bug Fixes
+
+* apply sideloads at definition once setup! has run ([39ef393](https://github.com/graphiti-api/graphiti/commit/39ef39383520816319282854c0ae99677bcd5127)), closes [#524](https://github.com/graphiti-api/graphiti/issues/524)
+* give client-caused errors real detail and stop 500ing on bad query params ([35acc3e](https://github.com/graphiti-api/graphiti/commit/35acc3e6c78f68eeeb05728ea16264b136455c30)), closes [#531](https://github.com/graphiti-api/graphiti/issues/531)
+* let an abstract resource declare relationships ([6036392](https://github.com/graphiti-api/graphiti/commit/6036392ebd611c7ed492beb3fe5754433eac9ffd)), closes [#453](https://github.com/graphiti-api/graphiti/issues/453)
+* reject a non-object data payload instead of raising TypeError ([51603b8](https://github.com/graphiti-api/graphiti/commit/51603b854270715b80a75d9aa05a4020e6bbdce5))
+* Update some missing sections and terms after renames, register unsupported pagination error ([39cff19](https://github.com/graphiti-api/graphiti/commit/39cff19f6f1f73126514c8b18234a18ad5eb7379))
+
+
+### Features
+
+* carry CurrentAttributes into concurrent sideloads ([7092096](https://github.com/graphiti-api/graphiti/commit/7092096f6d99ad277cc56817c616d946f655d55b))
+* fold allow_nil and deny_empty into one blanks: filter option ([a108403](https://github.com/graphiti-api/graphiti/commit/a108403e5cd87fd2fdf177da30c4c4f97b9fe750))
+* move link rendering onto the resource as page_links and relationship_links ([57878d1](https://github.com/graphiti-api/graphiti/commit/57878d14fdfc4741e8d418c8edbc4a8687335843))
+* move typecast_reads onto the resource and let the railtie own Rails config ([236e970](https://github.com/graphiti-api/graphiti/commit/236e9706d7d8f08e9640c5c22ac596e2f7466849))
+* one link mode per relationship, cascading from relationship_links ([f0e1da1](https://github.com/graphiti-api/graphiti/commit/f0e1da1e13a8d12b47458495b378779f5687ffe2))
+* point connection pool timeouts at the sizing formula and add an audit task to check ([6e017c6](https://github.com/graphiti-api/graphiti/commit/6e017c60fd45338e4e6c8527adebfd46be4bfd8d))
+* split validate_endpoints into validate_requests and validate_links ([100a370](https://github.com/graphiti-api/graphiti/commit/100a370deec6a0e6ae165bdf77e50b6b14d068d3))
+
 # [2.0.0-beta.9](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.8...v2.0.0-beta.9) (2026-08-22)
 
 

data/lib/generators/graphiti/generator_mixin.rb

@@ -33,6 +33,30 @@ module Graphiti
       methods.any? { |m| actions.include?(m) }
     end
 
+    def resource_setting_groups
+      name_width = Graphiti::Resource::SETTINGS.keys.map(&:length).max
+      assignments = Graphiti::Resource::SETTINGS.to_h do |name, setting|
+        value = setting[:format] || setting[:default].inspect
+        [name, "self.#{name.to_s.ljust(name_width)} = #{value}"]
+      end
+      hint_column = assignments.values.map(&:length).max + 2
+
+      Graphiti::Resource::SETTING_GROUPS.transform_values do |settings|
+        settings.map do |name, setting|
+          hint = resource_setting_hint(setting)
+          hint ? "#{assignments[name].ljust(hint_column)}# #{hint}" : assignments[name]
+        end
+      end
+    end
+
+    def resource_setting_hint(setting)
+      return setting[:note] if setting[:note]
+      return unless setting[:values]
+
+      setting[:values].map(&:inspect)
+        .to_sentence(two_words_connector: " or ", last_word_connector: ", or ")
+    end
+
     def graphiti_config
       File.exist?(".graphiticfg.yml") ? YAML.load_file(".graphiticfg.yml") : {}
     end

data/lib/generators/graphiti/templates/application_resource.rb.erb

@@ -14,21 +14,14 @@ class ApplicationResource < Graphiti::Resource
   self.endpoint_namespace = '<%= api_namespace %>'
   <%- unless omit_comments? -%>
 
-  # Defaults every Resource inherits. These are already the values shown;
-  # uncomment to change them API-wide, or set them on individual Resources.
-  # See https://graphiti.dev/concepts/resources
-  #
-  # self.attributes_readable_by_default     = true
-  # self.attributes_writable_by_default     = true
-  # self.attributes_sortable_by_default     = true
-  # self.attributes_filterable_by_default   = true
-  # self.attributes_schema_by_default       = true
-  # self.relationships_readable_by_default  = true
-  # self.relationships_writable_by_default  = true
-  # self.belongs_to_resource_ids_by_default = :foreign_key
-  # self.filters_accept_nil_by_default      = false
-  # self.filters_deny_empty_by_default      = false
-  # self.default_page_size                  = 20
-  # self.max_page_size                      = 1_000
+  # Defaults every Resource inherits. Uncomment to change them API-wide, or set
+  # them on individual Resources. See https://graphiti.dev/concepts/resources
+  <%- resource_setting_groups.each_pair do |group, lines| -%>
+
+  # <%= group.to_s.humanize %>
+    <%- lines.each do |line| -%>
+  # <%= line %>
+    <%- end -%>
+  <%- end -%>
   <%- end -%>
 end

data/lib/graphiti/configuration.rb

@@ -24,10 +24,6 @@ module Graphiti
 
     attr_accessor :respond_to
     attr_accessor :context_for_endpoint
-    attr_accessor :links_on_demand
-    attr_accessor :pagination_links_on_demand
-    attr_accessor :pagination_links
-    attr_accessor :typecast_reads
     attr_accessor :raise_on_missing_sidepost
     attr_accessor :before_sideload
 
@@ -44,32 +40,12 @@ module Graphiti
       @concurrency = false
       @concurrency_max_threads = 4
       @respond_to = [:json, :jsonapi, :xml]
-      @links_on_demand = false
-      @pagination_links_on_demand = false
-      @pagination_links = false
-      @typecast_reads = true
       @raise_on_missing_sidepost = true
       @cache_rendering = false
       self.debug = ENV.fetch("GRAPHITI_DEBUG", true)
       self.debug_models = ENV.fetch("GRAPHITI_DEBUG_MODELS", false)
 
       @uri_decoder = infer_uri_decoder
-
-      # FIXME: Don't duplicate the Railtie's initializer
-      if defined?(::Rails.root) && (root = ::Rails.root)
-        config_file = root.join(".graphiticfg.yml")
-        if config_file.exist?
-          cfg = YAML.load_file(config_file)
-          @schema_path = root.join("public#{cfg["namespace"]}/schema.json")
-        else
-          @schema_path = root.join("public/schema.json")
-        end
-
-        if (logger = ::Rails.logger)
-          self.debug = logger.debug? && debug
-          Graphiti.logger = logger
-        end
-      end
     end
 
     def cache_rendering?
@@ -111,6 +87,48 @@ module Graphiti
       send(:"#{key}=", original)
     end
 
+    def typecast_reads
+      Resource.typecast_reads
+    end
+
+    def typecast_reads=(val)
+      Resource.typecast_reads = val
+    end
+
+    def links_on_demand
+      Resource.relationship_links == :on_demand
+    end
+
+    def links_on_demand=(val)
+      if val
+        Resource.relationship_links = :on_demand
+      elsif Resource.relationship_links == :on_demand
+        Resource.relationship_links = true
+      end
+    end
+
+    def pagination_links
+      Resource.page_links == true
+    end
+
+    def pagination_links=(val)
+      return if Resource.page_links == :on_demand
+
+      Resource.page_links = !!val
+    end
+
+    def pagination_links_on_demand
+      Resource.page_links == :on_demand
+    end
+
+    def pagination_links_on_demand=(val)
+      if val
+        Resource.page_links = :on_demand
+      elsif Resource.page_links == :on_demand
+        Resource.page_links = false
+      end
+    end
+
     def uri_decoder=(decoder)
       unless decoder.respond_to?(:call)
         raise "uri_decoder must respond to `call`."
@@ -141,4 +159,17 @@ module Graphiti
 
   msg = "Use `config.graphiti.respond_to_formats`"
   DEPRECATOR.deprecate_methods(Configuration, respond_to: msg, "respond_to=": msg)
+
+  relationship_msg = "Set `self.relationship_links` (true, false, or :on_demand) on your resource"
+  pagination_msg = "Set `self.page_links` (true, false, or :on_demand) on your resource"
+  typecast_msg = "Set `self.typecast_reads` on your resource"
+  DEPRECATOR.deprecate_methods(Configuration,
+    typecast_reads: typecast_msg,
+    "typecast_reads=": typecast_msg,
+    links_on_demand: relationship_msg,
+    "links_on_demand=": relationship_msg,
+    pagination_links: pagination_msg,
+    "pagination_links=": pagination_msg,
+    pagination_links_on_demand: pagination_msg,
+    "pagination_links_on_demand=": pagination_msg)
 end

data/lib/graphiti/delegates/pagination.rb

@@ -6,7 +6,7 @@ module Graphiti
       end
 
       def links?
-        @proxy.query.pagination_links? && @proxy.data.present?
+        @proxy.query.page_links? && @proxy.data.present?
       end
 
       def links
@@ -104,7 +104,7 @@ module Graphiti
 
       def page_size
         @page_size ||= (page_param[:size] ||
-                        @proxy.resource.default_page_size ||
+                        @proxy.resource.page_default_size ||
                         Graphiti::Scoping::Paginate::DEFAULT_PAGE_SIZE).to_i
       end
 

data/lib/graphiti/errors.rb

@@ -221,7 +221,7 @@ module Graphiti
 
           Make sure the endpoint "#{@sideload.resource.endpoint[:full_path]}" exists with action #{@action.inspect}, or customize the endpoint for #{@sideload.resource.class.name}.
 
-          If you do not wish to generate a link, pass link: false or set self.autolink = false.
+          If you do not wish to generate a link, pass link: false or set self.relationship_links = false. To keep the link and stop checking it, set self.validate_links = false.
         MSG
       end
     end
@@ -255,6 +255,8 @@ module Graphiti
           Graphiti.config.context_for_endpoint must be set to enable link generation:
 
           Graphiti.config.context_for_endpoint = ->(path, action) { ... }
+
+          Or set self.validate_links = false to render links without checking them.
         MSG
       end
     end
@@ -445,9 +447,9 @@ module Graphiti
 
           secondary_endpoint '/my_url', [:index, :update]
 
-          Or disable endpoint validation for this resource:
+          Or disable request validation for this resource:
 
-          self.validate_endpoints = false
+          self.validate_requests = false
 
           See https://graphiti.dev/concepts/links for more information.
 
@@ -708,6 +710,36 @@ module Graphiti
       end
     end
 
+    class InvalidFilterBlanks < Base
+      def initialize(resource_class, attribute, value)
+        @resource_class = resource_class
+        @attribute = attribute
+        @value = value
+      end
+
+      def message
+        <<~MSG
+          #{@resource_class.name}: #{@attribute} must be one of :as_literal, :as_nil, or :reject. Got #{@value.inspect}.
+
+            :as_literal - "null" and "" reach the filter as strings (default)
+            :as_nil     - "null" becomes nil, so the filter can query for NULL
+            :reject     - a blank value raises InvalidFilterValue
+        MSG
+      end
+    end
+
+    class InvalidLinkRendering < Base
+      def initialize(resource_class, attribute, value)
+        @resource_class = resource_class
+        @attribute = attribute
+        @value = value
+      end
+
+      def message
+        "#{@resource_class.name}: #{@attribute} must be true, false, or :on_demand. Got #{@value.inspect}."
+      end
+    end
+
     class UnselectedForeignKey < Base
       def initialize(resource_class, sideload, model)
         @resource_class = resource_class

data/lib/graphiti/query.rb

@@ -2,6 +2,9 @@ require "digest"
 
 module Graphiti
   class Query
+    TRUTHY_LINKS = [true, "true"].freeze
+    LINKLESS_FORMATS = [:json, :xml, "json", "xml"].freeze
+
     attr_reader :resource, :association_name, :params, :action
 
     def initialize(resource, params, *positional, association_name: nil, nested_include: nil, parents: [], action: nil)
@@ -40,25 +43,39 @@ module Graphiti
       !association?
     end
 
-    def links?
-      return false if [:json, :xml, "json", "xml"].include?(params[:format])
-      if Graphiti.config.links_on_demand
-        [true, "true"].include?(@params[:links])
-      else
-        true
-      end
+    def links_requested?
+      return @links_requested if defined?(@links_requested)
+
+      @links_requested = TRUTHY_LINKS.include?(@params[:links])
+    end
+
+    def suppress_links?
+      return @suppress_links if defined?(@suppress_links)
+
+      @suppress_links = LINKLESS_FORMATS.include?(params[:format])
     end
 
-    def pagination_links?
+    def render_link?(mode)
+      return false if suppress_links?
+
+      (mode == :on_demand) ? links_requested? : mode == true
+    end
+
+    def page_links?
       if action == :find
         false
-      elsif Graphiti.config.pagination_links_on_demand
-        [true, "true"].include?(@params[:pagination_links])
+      elsif @resource.page_links == :on_demand
+        page_links_requested?
       else
-        Graphiti.config.pagination_links
+        @resource.page_links
       end
     end
 
+    def page_links_requested?
+      [@params[:page_links], @params[:pagination_links]]
+        .any? { |value| [true, "true"].include?(value) }
+    end
+
     def debug_requested?
       !!@params[:debug]
     end
@@ -267,8 +284,8 @@ module Graphiti
     def query_cache_key
       attrs = {extra_fields: extra_fields,
                fields: fields,
-               links: links?,
-               pagination_links: pagination_links?,
+               links: suppress_links? ? :none : links_requested?,
+               page_links: page_links?,
                format: params[:format]}
 
       Digest::SHA1.hexdigest(attrs.to_s)
@@ -387,5 +404,9 @@ module Graphiti
         action
       end
     end
+
+    alias_method :pagination_links?, :page_links?
+    DEPRECATOR.deprecate_methods(self,
+      pagination_links?: "Use `page_links?`")
   end
 end

data/lib/graphiti/rails/controller.rb

@@ -30,14 +30,34 @@ module Graphiti
 
         register_exception Graphiti::Errors::InvalidRequest,
           status: 400, handler: Graphiti::Rails::InvalidRequestHandler
-        register_exception Graphiti::Errors::ConflictRequest,
-          status: 409, handler: Graphiti::Rails::ConflictRequestHandler
-        register_exception Graphiti::Errors::RecordNotFound,
-          status: 404, handler: Graphiti::Rails::ExceptionHandler
         register_exception Graphiti::Errors::RemoteWrite,
-          status: 400, handler: Graphiti::Rails::ExceptionHandler
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
         register_exception Graphiti::Errors::SingularSideload,
-          status: 400, handler: Graphiti::Rails::ExceptionHandler
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::InvalidInclude,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::UnsupportedSort,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::UnsupportedOperator,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::InvalidFilterValue,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::RequiredFilter,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::UnsupportedPageSize,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::UnsupportedBeforeCursor,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::UnsupportedPagination,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+        register_exception Graphiti::Errors::FilterGroupMissingRequiredFilters,
+          status: 400, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+
+        register_exception Graphiti::Errors::RecordNotFound,
+          status: 404, detail: :exception, handler: Graphiti::Rails::ExceptionHandler
+
+        register_exception Graphiti::Errors::ConflictRequest,
+          status: 409, handler: Graphiti::Rails::ConflictRequestHandler
       end
     end
   end

data/lib/graphiti/rails/rake_helpers.rb

@@ -21,6 +21,23 @@ module Graphiti
         ::Rails.application.config.action_controller.perform_caching = false
       end
 
+      # The pool and RAILS_MAX_THREADS are read from this environment, and production may size both differently.
+      def connection_pool_advisory
+        return unless defined?(ActiveRecord::Base)
+
+        pool = ActiveRecord::Base.connection_db_config.pool
+        threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+        sideload_threads = Graphiti.config.concurrency_max_threads
+        needed = threads + sideload_threads + 1
+        return if pool.nil? || pool >= needed
+
+        "WARNING database.yml pool is #{pool} in this environment. With concurrency on (the production default), " \
+          "each sideload holds its own connection, so pool should be at least " \
+          "web threads (#{threads}) + concurrency_max_threads (#{sideload_threads}) + 1 = #{needed}. " \
+          "If production sizes these differently, check the numbers there. " \
+          "See graphiti.dev/concepts/resources#concurrency-pool-sizing."
+      end
+
       def make_request(path, debug = false)
         if path.split("/").length == 2
           path = "#{ApplicationResource.endpoint_namespace}#{path}"

data/lib/graphiti/request_validators/update_validator.rb

@@ -2,7 +2,7 @@ module Graphiti
   module RequestValidators
     class UpdateValidator < Validator
       def validate
-        if required_payload? && payload_matches_endpoint?
+        if validate_data_shape && required_payload? && payload_matches_endpoint?
           super
         else
           false

data/lib/graphiti/request_validators/validator.rb

@@ -17,6 +17,7 @@ module Graphiti
         # In the future these should have their own validation logic, but
         # for now we can just bypass
         return errors.blank? unless @params.has_key?(:data)
+        return false unless validate_data_shape
 
         resource = @root_resource
         if @params[:data].has_key?(:type)
@@ -56,6 +57,14 @@ module Graphiti
         @errors.add(:page, :invalid, message: "must be an object")
       end
 
+      def validate_data_shape
+        data = @params[:data]
+        return true if data.nil? || data.respond_to?(:each_pair)
+
+        @errors.add(:data, :invalid, message: "must be an object")
+        false
+      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

@@ -4,16 +4,75 @@ module Graphiti
       extend ActiveSupport::Concern
 
       DEFAULT_MAX_PAGE_SIZE = 1_000
+      LINK_MODES = [true, false, :on_demand].freeze
+      BELONGS_TO_RESOURCE_IDS_MODES = [:foreign_key, :always, :never].freeze
+      BLANK_MODES = [:as_literal, :as_nil, :reject].freeze
+
+      # Grouped for the ApplicationResource the install generator writes.
+      SETTING_GROUPS = { # :nodoc:
+        attributes: {
+          attributes_readable_by_default: {default: true},
+          attributes_writable_by_default: {default: true},
+          attributes_sortable_by_default: {default: true},
+          attributes_filterable_by_default: {default: true},
+          attributes_schema_by_default: {default: true},
+          typecast_reads: {default: true}
+        },
+        relationships: {
+          relationships_readable_by_default: {default: true},
+          relationships_writable_by_default: {default: true},
+          belongs_to_resource_ids_by_default: {
+            default: :foreign_key,
+            values: BELONGS_TO_RESOURCE_IDS_MODES,
+            invalid: ->(klass, value) { Errors::InvalidBelongsToResourceIds.new(klass, value) }
+          }
+        },
+        filters: {
+          filters_blanks_by_default: {
+            default: :as_literal,
+            values: BLANK_MODES,
+            invalid: ->(klass, value) { Errors::InvalidFilterBlanks.new(klass, :filters_blanks_by_default, value) }
+          }
+        },
+        sorting: {
+          default_sort: {default: nil, note: "per resource, e.g. [{id: :desc}]"}
+        },
+        pagination: {
+          page_default_size: {default: nil, note: "unset falls back to 20"},
+          page_max_size: {default: DEFAULT_MAX_PAGE_SIZE, format: "1_000"},
+          page_cursors: {default: false, note: "render cursors for pagination"},
+          page_links: {
+            default: false,
+            values: LINK_MODES,
+            invalid: ->(klass, value) { Errors::InvalidLinkRendering.new(klass, :page_links, value) }
+          }
+        },
+        endpoints: {
+          validate_requests: {default: true, note: "refuse requests to undeclared endpoints"}
+        },
+        links: {
+          relationship_links: {
+            default: true,
+            values: LINK_MODES,
+            invalid: ->(klass, value) { Errors::InvalidLinkRendering.new(klass, :relationship_links, value) }
+          },
+          validate_links: {default: true, note: "refuse to render links to unroutable endpoints"}
+        }
+      }.freeze
+
+      SETTINGS = SETTING_GROUPS.values.reduce(:merge).freeze # :nodoc:
 
       module Overrides
-        BELONGS_TO_RESOURCE_IDS_VALUES = [:foreign_key, :always, :never].freeze
+        SETTINGS.each_pair do |name, setting|
+          next unless setting[:values]
 
-        def belongs_to_resource_ids_by_default=(val)
-          unless BELONGS_TO_RESOURCE_IDS_VALUES.include?(val)
-            raise Errors::InvalidBelongsToResourceIds.new(self, val)
-          end
+          define_method(:"#{name}=") do |val|
+            unless setting[:values].include?(val)
+              raise setting[:invalid].call(self, val)
+            end
 
-          super
+            super(val)
+          end
         end
 
         def serializer=(val)
@@ -95,51 +154,37 @@ module Graphiti
           :polymorphic,
           :polymorphic_child,
           :serializer,
-          :default_page_size,
-          :default_sort,
-          :max_page_size,
-          :attributes_readable_by_default,
-          :attributes_writable_by_default,
-          :attributes_sortable_by_default,
-          :attributes_filterable_by_default,
-          :attributes_schema_by_default,
-          :relationships_readable_by_default,
-          :relationships_writable_by_default,
-          :belongs_to_resource_ids_by_default,
-          :filters_accept_nil_by_default,
-          :filters_deny_empty_by_default,
           :graphql_entrypoint,
-          :cursor_paginatable
+          *SETTINGS.keys
 
         class << self
           prepend Overrides
         end
 
+        SETTINGS.each_pair do |name, setting|
+          public_send(:"#{name}=", setting[:default])
+        end
+
         def self.inherited(klass)
           super
           klass.config = Util::Hash.deep_dup(config)
           klass.adapter ||= Adapters::Abstract
-          klass.max_page_size ||= DEFAULT_MAX_PAGE_SIZE
           # re-assigning causes a new Class.new
           klass.serializer = (klass.serializer || klass.infer_serializer_superclass)
           klass.type ||= klass.infer_type
           klass.graphql_entrypoint = klass.type.to_s.pluralize.to_sym
-          default(klass, :attributes_readable_by_default, true)
-          default(klass, :attributes_writable_by_default, true)
-          default(klass, :attributes_sortable_by_default, true)
-          default(klass, :attributes_filterable_by_default, true)
-          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)
-
           unless klass.config[:attributes][:id]
             klass.attribute :id, :integer_id
           end
           klass.stat total: [:count]
 
+          # An abstract parent has no serializer for its sideloads, so the subclass applies them here.
+          if abstract_class?
+            klass.config[:sideloads].each_pair do |name, sideload|
+              klass.apply_sideload_to_serializer(name) if klass.eagerly_apply_sideload?(sideload)
+            end
+          end
+
           if defined?(::Rails) && ::Rails.env.development?
             # Avoid adding dupe resources when re-autoloading
             Graphiti.resources.reject! { |r| r.name == klass.name }
@@ -149,6 +194,52 @@ module Graphiti
       end
 
       class_methods do
+        # Deprecated. Both folded into filters_blanks_by_default. Remove in 3.0.
+        def filters_accept_nil_by_default
+          filters_blanks_by_default == :as_nil
+        end
+
+        def filters_accept_nil_by_default=(val)
+          self.filters_blanks_by_default = val ? :as_nil : :as_literal
+        end
+
+        def filters_deny_empty_by_default
+          filters_blanks_by_default == :reject
+        end
+
+        def filters_deny_empty_by_default=(val)
+          self.filters_blanks_by_default = val ? :reject : :as_literal
+        end
+
+        # Deprecated. Renamed to the page_ family. Remove in 3.0.
+        def default_page_size
+          page_default_size
+        end
+
+        def default_page_size=(val)
+          self.page_default_size = val
+        end
+
+        def max_page_size
+          page_max_size
+        end
+
+        def max_page_size=(val)
+          self.page_max_size = val
+        end
+
+        def cursor_paginatable
+          page_cursors
+        end
+
+        def cursor_paginatable=(val)
+          self.page_cursors = val
+        end
+
+        def cursor_paginatable?
+          !!page_cursors
+        end
+
         def get_attr!(name, flag, opts = {})
           opts[:raise_error] = true
           get_attr(name, flag, opts)
@@ -205,14 +296,6 @@ module Graphiti
           serializer_class
         end
 
-        def default(object, attr, value)
-          prior = object.send(attr)
-          unless prior || prior == false
-            object.send(:"#{attr}=", value)
-          end
-        end
-        private :default
-
         def config
           @config ||=
             {
@@ -332,5 +415,20 @@ module Graphiti
         self.class.default_filters
       end
     end
+
+    blanks_msg = "Use `self.filters_blanks_by_default` (:as_literal, :as_nil, or :reject)"
+    page_msg = "Use `self.page_default_size`, `self.page_max_size` and `self.page_cursors`"
+    DEPRECATOR.deprecate_methods(Configuration::ClassMethods,
+      filters_accept_nil_by_default: blanks_msg,
+      "filters_accept_nil_by_default=": blanks_msg,
+      filters_deny_empty_by_default: blanks_msg,
+      "filters_deny_empty_by_default=": blanks_msg,
+      default_page_size: page_msg,
+      "default_page_size=": page_msg,
+      max_page_size: page_msg,
+      "max_page_size=": page_msg,
+      cursor_paginatable: page_msg,
+      "cursor_paginatable=": page_msg,
+      cursor_paginatable?: page_msg)
   end
 end

data/lib/graphiti/resource/dsl.rb

@@ -40,8 +40,7 @@ module Graphiti
               required: required,
               schema: schema,
               operators: operators.to_hash,
-              allow_nil: opts.fetch(:allow_nil, filters_accept_nil_by_default),
-              deny_empty: opts.fetch(:deny_empty, filters_deny_empty_by_default)
+              blanks: blanks_for(name, opts)
             }
           elsif (type = args[0])
             attribute name, type, only: [:filterable], allow: opts[:allow]
@@ -206,6 +205,26 @@ module Graphiti
           end
         end
         private :relationship_option
+
+        def blanks_for(name, opts)
+          if opts.key?(:deny_empty)
+            DEPRECATOR.warn("The deny_empty: filter option is deprecated. Use blanks: :reject.")
+            return :reject if opts[:deny_empty]
+          end
+
+          if opts.key?(:allow_nil)
+            DEPRECATOR.warn("The allow_nil: filter option is deprecated. Use blanks: :as_nil.")
+            return opts[:allow_nil] ? :as_nil : :as_literal
+          end
+
+          blanks = opts.fetch(:blanks, filters_blanks_by_default)
+          unless Resource::BLANK_MODES.include?(blanks)
+            raise Errors::InvalidFilterBlanks.new(self, name, blanks)
+          end
+
+          blanks
+        end
+        private :blanks_for
       end
     end
   end

data/lib/graphiti/resource/interface.rb

@@ -80,7 +80,7 @@ module Graphiti
         end
 
         def validate_request!(params)
-          return if Graphiti.context[:graphql] || !validate_endpoints?
+          return if Graphiti.context[:graphql] || !validate_requests?
 
           if context&.respond_to?(:request)
             path = context.request.env["PATH_INFO"]

data/lib/graphiti/resource/links.rb

@@ -25,12 +25,8 @@ module Graphiti
       class_attribute :endpoint,
         :base_url,
         :endpoint_namespace,
-        :secondary_endpoints,
-        :autolink,
-        :validate_endpoints
+        :secondary_endpoints
       self.secondary_endpoints = []
-      self.autolink = true
-      self.validate_endpoints = true
 
       class << self
         prepend Overrides
@@ -38,6 +34,33 @@ module Graphiti
     end
 
     class_methods do
+      # Deprecated. Folded into relationship_links. Remove in 3.0.
+      def autolink
+        relationship_links != false
+      end
+
+      def autolink=(val)
+        self.relationship_links = val ? true : false
+      end
+
+      def autolink?
+        autolink
+      end
+
+      # Deprecated. Split into validate_requests and validate_links. Remove in 3.0.
+      def validate_endpoints
+        validate_requests && validate_links
+      end
+
+      def validate_endpoints=(val)
+        self.validate_requests = val
+        self.validate_links = val
+      end
+
+      def validate_endpoints?
+        validate_endpoints
+      end
+
       def infer_endpoint
         return unless name
 
@@ -101,4 +124,12 @@ module Graphiti
       end
     end
   end
+
+  msg = "Use `self.relationship_links` (true, false, or :on_demand)"
+  endpoints_msg = "Use `self.validate_requests` for inbound requests, `self.validate_links` for rendered links"
+  DEPRECATOR.deprecate_methods(Links::ClassMethods,
+    autolink: msg, "autolink=": msg, autolink?: msg,
+    validate_endpoints: endpoints_msg,
+    "validate_endpoints=": endpoints_msg,
+    validate_endpoints?: endpoints_msg)
 end

data/lib/graphiti/resource/remote.rb

@@ -6,7 +6,8 @@ module Graphiti
       included do
         self.adapter = Graphiti::Adapters::GraphitiAPI
         self.model = OpenStruct
-        self.validate_endpoints = false
+        self.validate_requests = false
+        self.validate_links = false
 
         class_attribute :timeout,
           :open_timeout

data/lib/graphiti/resource/sideloading.rb

@@ -126,11 +126,11 @@ module Graphiti
         end
 
         # If eager loading, ensure routes are loaded first, then apply
-        # This happens in Railtie
+        # This happens in Railtie. Setup runs once, so classes redefined by a reload apply at definition.
         def eagerly_apply_sideload?(sideload)
           # TODO: Maybe handle this in the Rails integration
           if defined?(::Rails) && (app = ::Rails.application)
-            app.config.eager_load ? false : true
+            app.config.eager_load ? Graphiti.setup? : true
           else
             sideload.resource_class_loaded?
           end

data/lib/graphiti/schema.rb

@@ -111,8 +111,8 @@ module Graphiti
           config[:default_sort] = default_sort
         end
 
-        if r.default_page_size
-          config[:default_page_size] = r.default_page_size
+        if r.page_default_size
+          config[:default_page_size] = r.page_default_size
         end
 
         if r.polymorphic? && !r.polymorphic_child?

data/lib/graphiti/scope.rb

@@ -257,15 +257,21 @@ module Graphiti
           end
         end
 
+      current_attributes = current_attributes_snapshot
+
       Concurrent::Promises.future_on(
-        self.class.global_thread_pool_executor, Thread.current.object_id, thread_storage, fiber_storage, *args
-      ) do |thread_id, thread_storage, fiber_storage, *args|
+        self.class.global_thread_pool_executor, Thread.current.object_id, thread_storage, fiber_storage, current_attributes, *args
+      ) do |thread_id, thread_storage, fiber_storage, current_attributes, *args|
         self.class.marking_pool_thread do
           wrap_in_rails_executor do
             with_thread_locals(thread_storage) do
               with_fiber_locals(fiber_storage) do
-                Graphiti.broadcast(:global_thread_pool_task_run, self.class.global_thread_pool_stats) do
-                  yield(*args)
+                with_current_attributes(current_attributes) do
+                  with_connection_pool_hint do
+                    Graphiti.broadcast(:global_thread_pool_task_run, self.class.global_thread_pool_stats) do
+                      yield(*args)
+                    end
+                  end
                 end
               end
             end
@@ -274,6 +280,45 @@ module Graphiti
       end
     end
 
+    def current_attributes_snapshot
+      return unless defined?(ActiveSupport::CurrentAttributes)
+
+      snapshot = {}
+      klasses = ActiveSupport::CurrentAttributes.subclasses
+      while (klass = klasses.shift)
+        klasses.concat(klass.subclasses)
+        attributes = klass.attributes
+        snapshot[klass] = attributes.dup if attributes.any?
+      end
+      snapshot
+    end
+
+    # Restored inside the Rails executor, whose entry hands the pool thread a
+    # fresh Current. Restoring through set scopes the values to the block.
+    def with_current_attributes(snapshot, &block)
+      return yield if snapshot.nil? || snapshot.empty?
+
+      klass, attributes = snapshot.first
+      rest = snapshot.except(klass)
+      klass.set(attributes) { with_current_attributes(rest, &block) }
+    end
+
+    # A timeout inside a sideload task nearly always means database.yml's pool
+    # was not sized for the sideload threads, and the bare error does not say so.
+    def with_connection_pool_hint
+      yield
+    rescue => error
+      raise unless defined?(ActiveRecord::ConnectionTimeoutError) && error.is_a?(ActiveRecord::ConnectionTimeoutError)
+
+      hinted = error.exception(<<~MSG.strip)
+        #{error.message}
+
+        Raised while resolving a sideload concurrently. Each concurrent sideload holds its own database connection, so `pool` in database.yml must be at least web threads + concurrency_max_threads (#{Graphiti.config.concurrency_max_threads}) + 1. See graphiti.dev/concepts/resources#concurrency-pool-sizing.
+      MSG
+      hinted.set_backtrace(error.backtrace)
+      raise hinted
+    end
+
     def with_thread_locals(thread_locals)
       new_thread_locals = []
       thread_locals.each do |key, value|

data/lib/graphiti/scoping/filter.rb

@@ -62,7 +62,7 @@ module Graphiti
             value = parse_string_value(filter.values[0], value)
           end
 
-          check_deny_empty_filters!(resource, filter, value)
+          check_blank_filters!(resource, filter, value)
           value = parse_string_null(filter.values[0], value)
           validate_singular(resource, filter, value)
           value = coerce_types(filter.values[0], param_name.to_sym, value)
@@ -209,15 +209,15 @@ module Graphiti
     end
 
     def parse_string_null(filter, value)
-      return value unless filter[:allow_nil]
+      return value unless filter[:blanks] == :as_nil
       return value.map { |item| (item == "null") ? nil : item } if value.is_a?(Array)
       return if value == "null"
 
       value
     end
 
-    def check_deny_empty_filters!(resource, filter, value)
-      return unless filter.values[0][:deny_empty]
+    def check_blank_filters!(resource, filter, value)
+      return unless filter.values[0][:blanks] == :reject
 
       if value.nil? || value.empty? || value == "null"
         raise Errors::InvalidFilterValue.new(resource, filter, "(empty)")

data/lib/graphiti/scoping/paginate.rb

@@ -4,9 +4,9 @@ module Graphiti
     PARAMS = [:number, :size, :offset, :before, :after]
 
     def apply
-      if size > resource.max_page_size
+      if size > resource.page_max_size
         raise Graphiti::Errors::UnsupportedPageSize
-          .new(size, resource.max_page_size)
+          .new(size, resource.page_max_size)
       elsif requested? && @opts[:sideload_parent_length].to_i > 1
         raise Graphiti::Errors::UnsupportedPagination
       else
@@ -100,7 +100,7 @@ module Graphiti
     end
 
     def size
-      (page_param[:size] || resource.default_page_size || DEFAULT_PAGE_SIZE).to_i
+      (page_param[:size] || resource.page_default_size || DEFAULT_PAGE_SIZE).to_i
     end
   end
 end

data/lib/graphiti/serializer.rb

@@ -1,5 +1,7 @@
 module Graphiti
   class Serializer < JSONAPI::Serializable::Resource
+    UNREQUESTED_LINKS = [false, nil, "false"].freeze
+
     include Graphiti::Extensions::BooleanAttribute
     include Graphiti::Extensions::ExtraAttribute
     include Graphiti::SerializableHash
@@ -59,7 +61,7 @@ module Graphiti
       starting_offset = 0
       page_param = @proxy.query.pagination
       if (page_number = page_param[:number])
-        page_size = page_param[:size] || @resource.default_page_size
+        page_size = page_param[:size] || @resource.page_default_size
         starting_offset = (page_number - 1) * page_size
       end
 
@@ -100,17 +102,21 @@ module Graphiti
       hash[:links] = @resource.links(@object) if @resource.links?
     end
 
+    # A relationship whose only content would be an unrequested on-demand link
+    # serializes as an empty stub, which JSON:API forbids.
     def strip_relationships!(hash)
-      hash[:relationships]&.select! do |name, payload|
-        payload.key?(:data)
+      hash[:relationships]&.reject! do |name, payload|
+        next false if payload.key?(:data) || payload.key?(:links)
+
+        self.class.relationship_sideloads[name]&.link_mode == :on_demand
       end
     end
 
     def strip_relationships?
-      return false unless Graphiti.config.links_on_demand
-      params = Graphiti.context[:object]&.params || {}
+      context = Graphiti.context[:object]
+      params = context.params if context.respond_to?(:params)
 
-      [false, nil, "false"].include?(params[:links])
+      UNREQUESTED_LINKS.include?(params && params[:links])
     end
   end
 end

data/lib/graphiti/sideload.rb

@@ -31,6 +31,9 @@ module Graphiti
       @writable = opts[:writable]
       @as = opts[:as]
       @link = opts[:link]
+      unless @link.nil? || Resource::LINK_MODES.include?(@link)
+        raise Errors::InvalidLinkRendering.new(@parent_resource_class, :"#{name} link", @link)
+      end
       @single = opts[:single]
       @remote = opts[:remote]
       apply_belongs_to_many_filter if type == :many_to_many
@@ -84,7 +87,8 @@ module Graphiti
         self.adapter = Graphiti::Adapters::GraphitiAPI
         self.model = OpenStruct
         self.remote = remote_url
-        self.validate_endpoints = false
+        self.validate_requests = false
+        self.validate_links = false
       }
       name = "#{parent_resource_class.name}.#{@name}.remote"
       klass.class_eval("def self.name;'#{name}';end", __FILE__, __LINE__)
@@ -166,14 +170,16 @@ module Graphiti
       false
     end
 
-    def link?
-      return true if link_proc
+    # A custom link block means the author wants the link, so a false default does not silence it.
+    def link_mode
+      return @link unless @link.nil?
 
-      if @link.nil?
-        !!@parent_resource_class.autolink
-      else
-        !!@link
-      end
+      default = @parent_resource_class.relationship_links
+      (link_proc && default == false) ? true : default
+    end
+
+    def link?
+      link_mode != false
     end
 
     def link_filter(parents)

data/lib/graphiti/spec_helpers/matchers.rb

@@ -140,7 +140,7 @@ module Graphiti
       end
 
       class FilterAttributeMatcher < ResourceDSLMatcher
-        GRAPHITI_OPTS = %i[allow deny single required allow_nil deny_empty].freeze
+        GRAPHITI_OPTS = %i[allow deny single required blanks].freeze
         GRAPHITI_CONFIG_KEY = :filters
         EXPECTED_ACTION = "filter"
       end
@@ -186,7 +186,7 @@ module Graphiti
       # @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).to filter_attribute(:name, :string).with_options(blanks: :as_nil)
       # @example expect(subject).not_to filter_attribute(:name, :string)
       def filter_attribute(attribute, type)
         FilterAttributeMatcher.new(attribute, type)

data/lib/graphiti/spec_helpers/rspec.rb

@@ -39,14 +39,17 @@ resource_testing = proc do
   let(:params) { {} }
 
   around do |e|
-    original = Graphiti::Resource.validate_endpoints
-    Graphiti::Resource.validate_endpoints = false
+    original_requests = Graphiti::Resource.validate_requests
+    original_links = Graphiti::Resource.validate_links
+    Graphiti::Resource.validate_requests = false
+    Graphiti::Resource.validate_links = false
 
     Graphiti.with_context graphiti_context do
       e.run
     end
   ensure
-    Graphiti::Resource.validate_endpoints = original
+    Graphiti::Resource.validate_requests = original_requests
+    Graphiti::Resource.validate_links = original_links
   end
 
   def graphiti_context

data/lib/graphiti/util/link.rb

@@ -47,7 +47,7 @@ module Graphiti
       end
 
       def on_demand_links(url)
-        return url unless Graphiti.config.links_on_demand
+        return url unless @sideload.resource.relationship_links == :on_demand
         return unless url
 
         url << if url.include?("?")

data/lib/graphiti/util/serializer_attributes.rb

@@ -30,7 +30,7 @@ module Graphiti
         @serializer.send(:"#{applied_method}=", [@name] | existing)
 
         @serializer.meta do
-          if !!@resource.try(:cursor_paginatable?) && !Graphiti.context[:graphql]
+          if !!@resource.try(:page_cursors?) && !Graphiti.context[:graphql]
             {cursor: cursor}
           end
         end
@@ -121,10 +121,11 @@ module Graphiti
 
       def default_proc
         name_ref = @name
+        resource_ref = @resource
         typecast_ref = typecast(Graphiti::Types[@attr[:type]][:read])
         ->(_) {
           val = @object.send(name_ref)
-          if Graphiti.config.typecast_reads
+          if resource_ref.typecast_reads
             typecast_ref.call(val)
           else
             val
@@ -133,10 +134,11 @@ module Graphiti
       end
 
       def wrap_proc(inner)
+        resource_ref = @resource
         typecast_ref = typecast(Graphiti::Types[@attr[:type]][:read])
         ->(serializer_instance = nil) {
           val = serializer_instance.instance_eval(&inner)
-          if Graphiti.config.typecast_reads
+          if resource_ref.typecast_reads
             typecast_ref.call(val)
           else
             val

data/lib/graphiti/util/serializer_relationships.rb

@@ -8,6 +8,8 @@ module Graphiti
       end
 
       def apply
+        return unless @serializer
+
         @sideloads.each_pair do |name, sideload|
           if apply?(sideload)
             SerializerRelationship
@@ -55,7 +57,6 @@ module Graphiti
       private
 
       def block
-        link_ref = link?
         sideload_ref = @sideload
         resource_class_ref = @resource_class
         data_proc_ref = data_proc
@@ -93,13 +94,11 @@ module Graphiti
             linkage always: sideload_ref.render_resource_ids?
           end
 
-          if link_ref
-            if @proxy.query.links?
-              self_ref.send(:validate_link!) unless self_ref.send(:eagerly_validate_links?)
+          if @proxy.query.render_link?(sideload_ref.link_mode) && self_ref.send(:linkable?)
+            self_ref.send(:validate_link!) unless self_ref.send(:eagerly_validate_links?)
 
-              link(:related) do
-                ::Graphiti::Util::Link.new(sideload_ref, @object).generate
-              end
+            link(:related) do
+              ::Graphiti::Util::Link.new(sideload_ref, @object).generate
             end
           end
         end
@@ -162,8 +161,8 @@ module Graphiti
       end
 
       def validate_link!
-        return unless link?
-        return unless @resource_class.validate_endpoints?
+        return unless @sideload.link? && linkable?
+        return unless @resource_class.validate_links?
         return if @sideload.link_proc
 
         unless Graphiti.config.context_for_endpoint
@@ -192,14 +191,16 @@ module Graphiti
         self.class.validated_link_cache << cache_key
       end
 
-      def link?
-        return true if @sideload.link_proc
+      # Checked lazily so a sideload with no endpoint only raises when a link is actually wanted.
+      def linkable?
+        return @linkable if defined?(@linkable)
 
-        if @sideload.respond_to?(:children)
-          @sideload.link? &&
-            @sideload.children.values.all? { |c| !c.resource.endpoint.nil? }
+        @linkable = if @sideload.link_proc
+          true
+        elsif @sideload.respond_to?(:children)
+          @sideload.children.values.all? { |c| !c.resource.endpoint.nil? }
         else
-          !!(@sideload.link? && @sideload.resource.endpoint)
+          !@sideload.resource.endpoint.nil?
         end
       end
     end

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "2.0.0.beta.9"
+  VERSION = "2.0.0.beta.10"
 end

data/lib/graphiti.rb

@@ -149,6 +149,11 @@ module Graphiti
     resources.each do |r|
       r.apply_sideloads_to_serializer
     end
+    @setup = true
+  end
+
+  def self.setup?
+    !!@setup
   end
 
   def self.cache=(val)

data/lib/tasks/graphiti.rake

@@ -22,6 +22,10 @@ namespace :graphiti do
     rows = Graphiti::Audit.run
     puts Graphiti::Audit::Report.new(rows)
 
+    if (advisory = helpers.connection_pool_advisory)
+      puts advisory
+    end
+
     exit 1 if rows.any?(&:error?)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.9
+  version: 2.0.0.beta.10
 platform: ruby
 authors:
 - Lee Richmond