graphiti 2.0.0.beta.9 → 2.0.0.beta.11

data/lib/graphiti/resource/configuration.rb

@@ -4,16 +4,76 @@ 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 = [:literal, :null, :rejected].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},
+          relationship_placeholders: {default: false, note: "render placeholders for relationships with no ids and no link"},
+          belongs_to_resource_ids_by_default: {
+            default: :foreign_key,
+            values: BELONGS_TO_RESOURCE_IDS_MODES,
+            invalid: ->(klass, value) { Errors::InvalidBelongsToResourceIds.new(klass, value) }
+          }
+        },
+        filters: {
+          filter_blanks_treated_as: {
+            default: :literal,
+            values: BLANK_MODES,
+            invalid: ->(klass, value) { Errors::InvalidFilterBlanks.new(klass, :filter_blanks_treated_as, 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 +155,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 +195,52 @@ module Graphiti
       end
 
       class_methods do
+        # Deprecated. Both folded into filter_blanks_treated_as. Remove in 3.0.
+        def filters_accept_nil_by_default
+          filter_blanks_treated_as == :null
+        end
+
+        def filters_accept_nil_by_default=(val)
+          self.filter_blanks_treated_as = val ? :null : :literal
+        end
+
+        def filters_deny_empty_by_default
+          filter_blanks_treated_as == :rejected
+        end
+
+        def filters_deny_empty_by_default=(val)
+          self.filter_blanks_treated_as = val ? :rejected : :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 +297,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 +416,20 @@ module Graphiti
         self.class.default_filters
       end
     end
+
+    blanks_msg = "Use `self.filter_blanks_treated_as` (:literal, :null, or :rejected)"
+    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: :rejected.")
+            return :rejected if opts[:deny_empty]
+          end
+
+          if opts.key?(:allow_nil)
+            DEPRECATOR.warn("The allow_nil: filter option is deprecated. Use blanks: :null.")
+            return opts[:allow_nil] ? :null : :literal
+          end
+
+          blanks = opts.fetch(:blanks, filter_blanks_treated_as)
+          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,36 @@ module Graphiti
     end
 
     class_methods do
+      # Deprecated. Folded into relationship_links. Remove in 3.0.
+      def autolink
+        relationship_links != false
+      end
+
+      # true cannot express :on_demand, so it leaves an inherited on-demand mode alone.
+      def autolink=(val)
+        return if val && relationship_links == :on_demand
+
+        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 +127,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

@@ -59,6 +59,9 @@ module Graphiti
       @query = query
       @opts = opts
 
+      @resolved_sideload_proxies = {}
+      @resolved_sideload_proxies_lock = Mutex.new
+
       @object = @resource.around_scoping(@object, @query.hash) { |scope|
         apply_scoping(scope, opts)
       }
@@ -67,7 +70,7 @@ module Graphiti
     def resolve(&blk)
       # The caller blocks on .value! either way, so concurrency only benefits parallel sideloads
       # See https://github.com/graphiti-api/graphiti/issues/505
-      if self.class.resolve_synchronously? || !applicable_sideloads?
+      if self.class.resolve_synchronously? || !overlapping_sideloads?
         sync_resolve(&blk)
       else
         future_resolve(&blk).value!
@@ -140,9 +143,6 @@ module Graphiti
 
     private
 
-    # Synchronous counterpart to #future_resolve, used when concurrency is off.
-    # Resolves the resource and its sideloads inline without any promise
-    # machinery. See #resolve.
     def sync_resolve(&blk)
       return [] if @query.zero_results?
 
@@ -151,14 +151,15 @@ module Graphiti
       resolved
     end
 
-    # Synchronous counterpart to #future_resolve_sideloads, used when
-    # concurrency is off. Resolves each sideload inline. See #resolve_sideloads.
     def sync_resolve_sideloads(results)
       return if results == []
 
-      each_applicable_sideload do |sideload, sideload_query|
+      reset_captured_sideload_proxies
+      each_applicable_sideload do |name, sideload, sideload_query|
         Graphiti.config.before_sideload&.call(Graphiti.context)
-        sideload.resolve(results, sideload_query, @resource)
+        sideload.sync_resolve(results, sideload_query, @resource) do |proxy|
+          capture_sideload_proxy(name, proxy)
+        end
       end
     end
 
@@ -176,7 +177,7 @@ module Graphiti
       assign_serializer(resolved)
       yield resolved if block_given?
       @opts[:after_resolve]&.call(resolved)
-      resolved
+      @resolved_records = resolved
     end
 
     # Must run before sideloads assign, so every include path populates the
@@ -198,6 +199,8 @@ module Graphiti
 
     # A customized sideload can load a record another path would not, so it keeps its own instances.
     def deduplicable?
+      return false unless @query.repeated_resource_classes.include?(@resource.class)
+
       sideload = @opts[:sideload]
       return true unless sideload
 
@@ -207,9 +210,15 @@ module Graphiti
         sideload.primary_key == :id
     end
 
-    # Nothing to post to the pool means the future would wrap work already done.
-    def applicable_sideloads?
-      each_applicable_sideload { return true }
+    # One sideload has nothing to run beside it, so the pool would hand the work
+    # to another thread and wait for it. A chain is one at every level. A
+    # polymorphic sideload counts as its children, which do run beside each other.
+    def overlapping_sideloads?
+      found = 0
+      each_applicable_sideload do |_, sideload, _|
+        found += sideload.respond_to?(:children) ? sideload.children.size : 1
+        return true if found > 1
+      end
       false
     end
 
@@ -218,18 +227,34 @@ module Graphiti
         sideload = @resource.class.sideload(name)
         next if sideload.nil? || sideload.shared_remote?
 
-        yield sideload, sideload_query
+        yield name, sideload, sideload_query
+      end
+    end
+
+    # The write path resolves sideloads twice on one scope, which would double every proxy in the cache key.
+    def reset_captured_sideload_proxies
+      @resolved_sideload_proxies_lock.synchronize { @resolved_sideload_proxies.clear }
+    end
+
+    # A proxy built while resolving is already resolved all the way down.
+    def capture_sideload_proxy(name, proxy)
+      @resolved_sideload_proxies_lock.synchronize do
+        captured = (@resolved_sideload_proxies[name] ||= [])
+        captured << proxy unless proxy.nil? || proxy == []
       end
     end
 
     def future_resolve_sideloads(results)
       return Concurrent::Promises.fulfilled_future(nil, self.class.global_thread_pool_executor) if results == []
 
+      reset_captured_sideload_proxies
       sideload_promises = []
-      each_applicable_sideload do |sideload, sideload_query|
+      each_applicable_sideload do |name, sideload, sideload_query|
         promise = future_with_context(results, sideload_query, @resource) do |parent_results, future_query, parent_resource|
           Graphiti.config.before_sideload&.call(Graphiti.context)
-          sideload.future_resolve(parent_results, future_query, parent_resource)
+          sideload.future_resolve(parent_results, future_query, parent_resource) do |proxy|
+            capture_sideload_proxy(name, proxy)
+          end
         end
         sideload_promises << promise.flat
       end
@@ -257,15 +282,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 +305,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|
@@ -316,15 +386,19 @@ module Graphiti
 
     def sideload_resource_proxies
       @sideload_resource_proxies ||= begin
-        @object = @resource.before_resolve(@object, @query)
-        results = @resource.resolve(@object)
+        # Reached after the response resolved, where resolving again re-applies before_resolve to a mutated scope.
+        results = @resolved_records
+        if results.nil?
+          @object = @resource.before_resolve(@object, @query)
+          results = @resource.resolve(@object)
+        end
 
         [].tap do |proxies|
-          unless @query.sideloads.empty?
-            @query.sideloads.each_pair do |name, q|
-              sideload = @resource.class.sideload(name)
-              next if sideload.nil? || sideload.shared_remote?
-
+          each_applicable_sideload do |name, sideload, q|
+            captured = @resolved_sideload_proxies[name]
+            if captured
+              proxies.concat(captured)
+            else
               proxies << sideload.build_resource_proxy(results, q, parent_resource)
             end
           end

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] == :null
       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] == :rejected
 
       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