graphql 1.9.0 → 2.1.1

data/lib/graphql/backtrace.rb

@@ -3,19 +3,19 @@ require "graphql/backtrace/inspect_result"
 require "graphql/backtrace/table"
 require "graphql/backtrace/traced_error"
 require "graphql/backtrace/tracer"
+require "graphql/backtrace/trace"
 module GraphQL
   # Wrap unhandled errors with {TracedError}.
   #
   # {TracedError} provides a GraphQL backtrace with arguments and return values.
   # The underlying error is available as {TracedError#cause}.
   #
-  # WARNING: {.enable} is not threadsafe because {GraphQL::Tracing.install} is not threadsafe.
-  #
   # @example toggling backtrace annotation
-  #   # to enable:
-  #   GraphQL::Backtrace.enable
-  #   # later, to disable:
-  #   GraphQL::Backtrace.disable
+  #   class MySchema < GraphQL::Schema
+  #     if Rails.env.development? || Rails.env.test?
+  #       use GraphQL::Backtrace
+  #     end
+  #   end
   #
   class Backtrace
     include Enumerable
@@ -23,19 +23,8 @@ module GraphQL
 
     def_delegators :to_a, :each, :[]
 
-    def self.enable
-      warn("GraphQL::Backtrace.enable is deprecated, add `use GraphQL::Backtrace` to your schema definition instead.")
-      GraphQL::Tracing.install(Backtrace::Tracer)
-      nil
-    end
-
-    def self.disable
-      GraphQL::Tracing.uninstall(Backtrace::Tracer)
-      nil
-    end
-
     def self.use(schema_defn)
-      schema_defn.tracer(self::Tracer)
+      schema_defn.trace_with(self::Trace)
     end
 
     def initialize(context, value: nil)
@@ -51,5 +40,20 @@ module GraphQL
     def to_a
       @table.to_backtrace
     end
+
+    # Used for internal bookkeeping
+    # @api private
+    class Frame
+      attr_reader :path, :query, :ast_node, :object, :field, :arguments, :parent_frame
+      def initialize(path:, query:, ast_node:, object:, field:, arguments:, parent_frame:)
+        @path = path
+        @query = query
+        @ast_node = ast_node
+        @field = field
+        @object = object
+        @arguments = arguments
+        @parent_frame = parent_frame
+      end
+    end
   end
 end

data/lib/graphql/coercion_error.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 module GraphQL
   class CoercionError < GraphQL::Error
+    # @return [Hash] Optional custom data for error objects which will be added
+    # under the `extensions` key.
+    attr_accessor :extensions
+
+    def initialize(message, extensions: nil)
+      @extensions = extensions
+      super(message)
+    end
   end
 end

data/lib/graphql/dataloader/null_dataloader.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Dataloader
+    # The default implementation of dataloading -- all no-ops.
+    #
+    # The Dataloader interface isn't public, but it enables
+    # simple internal code while adding the option to add Dataloader.
+    class NullDataloader < Dataloader
+      # These are all no-ops because code was
+      # executed sychronously.
+      def run; end
+      def run_isolated; yield; end
+      def yield
+        raise GraphQL::Error, "GraphQL::Dataloader is not running -- add `use GraphQL::Dataloader` to your schema to use Dataloader sources."
+      end
+
+      def append_job
+        yield
+        nil
+      end
+    end
+  end
+end

data/lib/graphql/dataloader/request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+module GraphQL
+  class Dataloader
+    # @see Source#request which returns an instance of this
+    class Request
+      def initialize(source, key)
+        @source = source
+        @key = key
+      end
+
+      # Call this method to cause the current Fiber to wait for the results of this request.
+      #
+      # @return [Object] the object loaded for `key`
+      def load
+        @source.load(@key)
+      end
+    end
+  end
+end

data/lib/graphql/dataloader/request_all.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+module GraphQL
+  class Dataloader
+    # @see Source#request_all which returns an instance of this.
+    class RequestAll < Request
+      def initialize(source, keys)
+        @source = source
+        @keys = keys
+      end
+
+      # Call this method to cause the current Fiber to wait for the results of this request.
+      #
+      # @return [Array<Object>] One object for each of `keys`
+      def load
+        @source.load_all(@keys)
+      end
+    end
+  end
+end

data/lib/graphql/dataloader/source.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class Dataloader
+    class Source
+      # Called by {Dataloader} to prepare the {Source}'s internal state
+      # @api private
+      def setup(dataloader)
+        # These keys have been requested but haven't been fetched yet
+        @pending = {}
+        # These keys have been passed to `fetch` but haven't been finished yet
+        @fetching = {}
+        # { key => result }
+        @results = {}
+        @dataloader = dataloader
+      end
+
+      attr_reader :dataloader
+
+      # @return [Dataloader::Request] a pending request for a value from `key`. Call `.load` on that object to wait for the result.
+      def request(value)
+        res_key = result_key_for(value)
+        if !@results.key?(res_key)
+          @pending[res_key] ||= value
+        end
+        Dataloader::Request.new(self, value)
+      end
+
+      # Implement this method to return a stable identifier if different
+      # key objects should load the same data value.
+      #
+      # @param value [Object] A value passed to `.request` or `.load`, for which a value will be loaded
+      # @return [Object] The key for tracking this pending data
+      def result_key_for(value)
+        value
+      end
+
+      # @return [Dataloader::Request] a pending request for a values from `keys`. Call `.load` on that object to wait for the results.
+      def request_all(values)
+        values.each do |v|
+          res_key = result_key_for(v)
+          if !@results.key?(res_key)
+            @pending[res_key] ||= v
+          end
+        end
+        Dataloader::RequestAll.new(self, values)
+      end
+
+      # @param value [Object] A loading value which will be passed to {#fetch} if it isn't already in the internal cache.
+      # @return [Object] The result from {#fetch} for `key`. If `key` hasn't been loaded yet, the Fiber will yield until it's loaded.
+      def load(value)
+        result_key = result_key_for(value)
+        if @results.key?(result_key)
+          result_for(result_key)
+        else
+          @pending[result_key] ||= value
+          sync([result_key])
+          result_for(result_key)
+        end
+      end
+
+      # @param values [Array<Object>] Loading keys which will be passed to `#fetch` (or read from the internal cache).
+      # @return [Object] The result from {#fetch} for `keys`. If `keys` haven't been loaded yet, the Fiber will yield until they're loaded.
+      def load_all(values)
+        result_keys = []
+        pending_keys = []
+        values.each { |v|
+          k = result_key_for(v)
+          result_keys << k
+          if !@results.key?(k)
+            @pending[k] ||= v
+            pending_keys << k
+          end
+        }
+
+        if pending_keys.any?
+          sync(pending_keys)
+        end
+
+        result_keys.map { |k| result_for(k) }
+      end
+
+      # Subclasses must implement this method to return a value for each of `keys`
+      # @param keys [Array<Object>] keys passed to {#load}, {#load_all}, {#request}, or {#request_all}
+      # @return [Array<Object>] A loaded value for each of `keys`. The array must match one-for-one to the list of `keys`.
+      def fetch(keys)
+        # somehow retrieve these from the backend
+        raise "Implement `#{self.class}#fetch(#{keys.inspect}) to return a record for each of the keys"
+      end
+
+      # Wait for a batch, if there's anything to batch.
+      # Then run the batch and update the cache.
+      # @return [void]
+      def sync(pending_result_keys)
+        @dataloader.yield
+        iterations = 0
+        while pending_result_keys.any? { |key| !@results.key?(key) }
+          iterations += 1
+          if iterations > 1000
+            raise "#{self.class}#sync tried 1000 times to load pending keys (#{pending_result_keys}), but they still weren't loaded. There is likely a circular dependency."
+          end
+          @dataloader.yield
+        end
+        nil
+      end
+
+      # @return [Boolean] True if this source has any pending requests for data.
+      def pending?
+        !@pending.empty?
+      end
+
+      # Add these key-value pairs to this source's cache
+      # (future loads will use these merged values).
+      # @param new_results [Hash<Object => Object>] key-value pairs to cache in this source
+      # @return [void]
+      def merge(new_results)
+        new_results.each do |new_k, new_v|
+          key = result_key_for(new_k)
+          @results[key] = new_v
+        end
+        nil
+      end
+
+      # Called by {GraphQL::Dataloader} to resolve and pending requests to this source.
+      # @api private
+      # @return [void]
+      def run_pending_keys
+        if !@fetching.empty?
+          @fetching.each_key { |k| @pending.delete(k) }
+        end
+        return if @pending.empty?
+        fetch_h = @pending
+        @pending = {}
+        @fetching.merge!(fetch_h)
+        results = fetch(fetch_h.values)
+        fetch_h.each_with_index do |(key, _value), idx|
+          @results[key] = results[idx]
+        end
+        nil
+      rescue StandardError => error
+        fetch_h.each_key { |key| @results[key] = error }
+      ensure
+        fetch_h && fetch_h.each_key { |k| @fetching.delete(k) }
+      end
+
+      # These arguments are given to `dataloader.with(source_class, ...)`. The object
+      # returned from this method is used to de-duplicate batch loads under the hood
+      # by using it as a Hash key.
+      #
+      # By default, the arguments are all put in an Array. To customize how this source's
+      # batches are merged, override this method to return something else.
+      #
+      # For example, if you pass `ActiveRecord::Relation`s to `.with(...)`, you could override
+      # this method to call `.to_sql` on them, thus merging `.load(...)` calls when they apply
+      # to equivalent relations.
+      #
+      # @param batch_args [Array<Object>]
+      # @param batch_kwargs [Hash]
+      # @return [Object]
+      def self.batch_key_for(*batch_args, **batch_kwargs)
+        [*batch_args, **batch_kwargs]
+      end
+
+      # Clear any already-loaded objects for this source
+      # @return [void]
+      def clear_cache
+        @results.clear
+        nil
+      end
+
+      attr_reader :pending
+
+      private
+
+      # Reads and returns the result for the key from the internal cache, or raises an error if the result was an error
+      # @param key [Object] key passed to {#load} or {#load_all}
+      # @return [Object] The result from {#fetch} for `key`.
+      # @api private
+      def result_for(key)
+        if !@results.key?(key)
+          raise GraphQL::InvariantError, <<-ERR
+Fetching result for a key on #{self.class} that hasn't been loaded yet (#{key.inspect}, loaded: #{@results.keys})
+
+This key should have been loaded already. This is a bug in GraphQL::Dataloader, please report it on GitHub: https://github.com/rmosolgo/graphql-ruby/issues/new.
+ERR
+        end
+        result = @results[key]
+
+        raise result if result.class <= StandardError
+
+        result
+      end
+    end
+  end
+end

data/lib/graphql/dataloader.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "graphql/dataloader/null_dataloader"
+require "graphql/dataloader/request"
+require "graphql/dataloader/request_all"
+require "graphql/dataloader/source"
+
+module GraphQL
+  # This plugin supports Fiber-based concurrency, along with {GraphQL::Dataloader::Source}.
+  #
+  # @example Installing Dataloader
+  #
+  #   class MySchema < GraphQL::Schema
+  #     use GraphQL::Dataloader
+  #   end
+  #
+  # @example Waiting for batch-loaded data in a GraphQL field
+  #
+  #   field :team, Types::Team, null: true
+  #
+  #   def team
+  #     dataloader.with(Sources::Record, Team).load(object.team_id)
+  #   end
+  #
+  class Dataloader
+    class << self
+      attr_accessor :default_nonblocking
+    end
+
+    AsyncDataloader = Class.new(self) { self.default_nonblocking = true }
+
+    def self.use(schema, nonblocking: nil)
+      schema.dataloader_class = if nonblocking
+        AsyncDataloader
+      else
+        self
+      end
+    end
+
+    # Call the block with a Dataloader instance,
+    # then run all enqueued jobs and return the result of the block.
+    def self.with_dataloading(&block)
+      dataloader = self.new
+      result = nil
+      dataloader.append_job {
+        result = block.call(dataloader)
+      }
+      dataloader.run
+      result
+    end
+
+    def initialize(nonblocking: self.class.default_nonblocking)
+      @source_cache = Hash.new { |h, k| h[k] = {} }
+      @pending_jobs = []
+      if !nonblocking.nil?
+        @nonblocking = nonblocking
+      end
+    end
+
+    def nonblocking?
+      @nonblocking
+    end
+
+    # Get a Source instance from this dataloader, for calling `.load(...)` or `.request(...)` on.
+    #
+    # @param source_class [Class<GraphQL::Dataloader::Source]
+    # @param batch_parameters [Array<Object>]
+    # @return [GraphQL::Dataloader::Source] An instance of {source_class}, initialized with `self, *batch_parameters`,
+    #   and cached for the lifetime of this {Multiplex}.
+    if RUBY_VERSION < "3" || RUBY_ENGINE != "ruby" # truffle-ruby wasn't doing well with the implementation below
+      def with(source_class, *batch_args)
+        batch_key = source_class.batch_key_for(*batch_args)
+        @source_cache[source_class][batch_key] ||= begin
+          source = source_class.new(*batch_args)
+          source.setup(self)
+          source
+        end
+      end
+    else
+      def with(source_class, *batch_args, **batch_kwargs)
+        batch_key = source_class.batch_key_for(*batch_args, **batch_kwargs)
+        @source_cache[source_class][batch_key] ||= begin
+          source = source_class.new(*batch_args, **batch_kwargs)
+          source.setup(self)
+          source
+        end
+      end
+    end
+    # Tell the dataloader that this fiber is waiting for data.
+    #
+    # Dataloader will resume the fiber after the requested data has been loaded (by another Fiber).
+    #
+    # @return [void]
+    def yield
+      Fiber.yield
+      nil
+    end
+
+    # @api private Nothing to see here
+    def append_job(&job)
+      # Given a block, queue it up to be worked through when `#run` is called.
+      # (If the dataloader is already running, than a Fiber will pick this up later.)
+      @pending_jobs.push(job)
+      nil
+    end
+
+    # Clear any already-loaded objects from {Source} caches
+    # @return [void]
+    def clear_cache
+      @source_cache.each do |_source_class, batched_sources|
+        batched_sources.each_value(&:clear_cache)
+      end
+      nil
+    end
+
+    # Use a self-contained queue for the work in the block.
+    def run_isolated
+      prev_queue = @pending_jobs
+      prev_pending_keys = {}
+      @source_cache.each do |source_class, batched_sources|
+        batched_sources.each do |batch_args, batched_source_instance|
+          if batched_source_instance.pending?
+            prev_pending_keys[batched_source_instance] = batched_source_instance.pending.dup
+            batched_source_instance.pending.clear
+          end
+        end
+      end
+
+      @pending_jobs = []
+      res = nil
+      # Make sure the block is inside a Fiber, so it can `Fiber.yield`
+      append_job {
+        res = yield
+      }
+      run
+      res
+    ensure
+      @pending_jobs = prev_queue
+      prev_pending_keys.each do |source_instance, pending|
+        source_instance.pending.merge!(pending)
+      end
+    end
+
+    # @api private Move along, move along
+    def run
+      if @nonblocking && !Fiber.scheduler
+        raise "`nonblocking: true` requires `Fiber.scheduler`, assign one with `Fiber.set_scheduler(...)` before executing GraphQL."
+      end
+      # At a high level, the algorithm is:
+      #
+      #  A) Inside Fibers, run jobs from the queue one-by-one
+      #    - When one of the jobs yields to the dataloader (`Fiber.yield`), then that fiber will pause
+      #    - In that case, if there are still pending jobs, a new Fiber will be created to run jobs
+      #    - Continue until all jobs have been _started_ by a Fiber. (Any number of those Fibers may be waiting to be resumed, after their data is loaded)
+      #  B) Once all known jobs have been run until they are complete or paused for data, run all pending data sources.
+      #    - Similarly, create a Fiber to consume pending sources and tell them to load their data.
+      #    - If one of those Fibers pauses, then create a new Fiber to continue working through remaining pending sources.
+      #    - When a source causes another source to become pending, run the newly-pending source _first_, since it's a dependency of the previous one.
+      #  C) After all pending sources have been completely loaded (there are no more pending sources), resume any Fibers that were waiting for data.
+      #    - Those Fibers assume that source caches will have been populated with the data they were waiting for.
+      #    - Those Fibers may request data from a source again, in which case they will yeilded and be added to a new pending fiber list.
+      #  D) Once all pending fibers have been resumed once, return to `A` above.
+      #
+      # For whatever reason, the best implementation I could find was to order the steps `[D, A, B, C]`, with a special case for skipping `D`
+      # on the first pass. I just couldn't find a better way to write the loops in a way that was DRY and easy to read.
+      #
+      pending_fibers = []
+      next_fibers = []
+      pending_source_fibers = []
+      next_source_fibers = []
+      first_pass = true
+
+      while first_pass || (f = pending_fibers.shift)
+        if first_pass
+          first_pass = false
+        else
+          # These fibers were previously waiting for sources to load data,
+          # resume them. (They might wait again, in which case, re-enqueue them.)
+          resume(f)
+          if f.alive?
+            next_fibers << f
+          end
+        end
+
+        while @pending_jobs.any?
+          # Create a Fiber to consume jobs until one of the jobs yields
+          # or jobs run out
+          f = spawn_fiber {
+            while (job = @pending_jobs.shift)
+              job.call
+            end
+          }
+          resume(f)
+          # In this case, the job yielded. Queue it up to run again after
+          # we load whatever it's waiting for.
+          if f.alive?
+            next_fibers << f
+          end
+        end
+
+        if pending_fibers.empty?
+          # Now, run all Sources which have become pending _before_ resuming GraphQL execution.
+          # Sources might queue up other Sources, which is fine -- those will also run before resuming execution.
+          #
+          # This is where an evented approach would be even better -- can we tell which
+          # fibers are ready to continue, and continue execution there?
+          #
+          if (first_source_fiber = create_source_fiber)
+            pending_source_fibers << first_source_fiber
+          end
+
+          while pending_source_fibers.any?
+            while (outer_source_fiber = pending_source_fibers.pop)
+              resume(outer_source_fiber)
+              if outer_source_fiber.alive?
+                next_source_fibers << outer_source_fiber
+              end
+              if (next_source_fiber = create_source_fiber)
+                pending_source_fibers << next_source_fiber
+              end
+            end
+            join_queues(pending_source_fibers, next_source_fibers)
+            next_source_fibers.clear
+          end
+          # Move newly-enqueued Fibers on to the list to be resumed.
+          # Clear out the list of next-round Fibers, so that
+          # any Fibers that pause can be put on it.
+          join_queues(pending_fibers, next_fibers)
+          next_fibers.clear
+        end
+      end
+
+      if @pending_jobs.any?
+        raise "Invariant: #{@pending_jobs.size} pending jobs"
+      elsif pending_fibers.any?
+        raise "Invariant: #{pending_fibers.size} pending fibers"
+      elsif next_fibers.any?
+        raise "Invariant: #{next_fibers.size} next fibers"
+      end
+      nil
+    end
+
+    def join_queues(previous_queue, next_queue)
+      if @nonblocking
+        Fiber.scheduler.run
+        next_queue.select!(&:alive?)
+      end
+      previous_queue.concat(next_queue)
+    end
+
+    private
+
+    # If there are pending sources, return a fiber for running them.
+    # Otherwise, return `nil`.
+    #
+    # @return [Fiber, nil]
+    def create_source_fiber
+      pending_sources = nil
+      @source_cache.each_value do |source_by_batch_params|
+        source_by_batch_params.each_value do |source|
+          if source.pending?
+            pending_sources ||= []
+            pending_sources << source
+          end
+        end
+      end
+
+      if pending_sources
+        # By passing the whole array into this Fiber, it's possible that we set ourselves up for a bunch of no-ops.
+        # For example, if you have sources `[a, b, c]`, and `a` is loaded, then `b` yields to wait for `d`, then
+        # the next fiber would be dispatched with `[c, d]`. It would fulfill `c`, then `d`, then eventually
+        # the previous fiber would start up again. `c` would no longer be pending, but it would still receive `.run_pending_keys`.
+        # That method is short-circuited since it isn't pending any more, but it's still a waste.
+        #
+        # This design could probably be improved by maintaining a `@pending_sources` queue which is shared by the fibers,
+        # similar to `@pending_jobs`. That way, when a fiber is resumed, it would never pick up work that was finished by a different fiber.
+        source_fiber = spawn_fiber do
+          pending_sources.each(&:run_pending_keys)
+        end
+      end
+
+      source_fiber
+    end
+
+    def resume(fiber)
+      fiber.resume
+    rescue UncaughtThrowError => e
+      throw e.tag, e.value
+    end
+
+    # Copies the thread local vars into the fiber thread local vars. Many
+    # gems (such as RequestStore, MiniRacer, etc.) rely on thread local vars
+    # to keep track of execution context, and without this they do not
+    # behave as expected.
+    #
+    # @see https://github.com/rmosolgo/graphql-ruby/issues/3449
+    def spawn_fiber
+      fiber_locals = {}
+
+      Thread.current.keys.each do |fiber_var_key|
+        # This variable should be fresh in each new fiber
+        if fiber_var_key != :__graphql_runtime_info
+          fiber_locals[fiber_var_key] = Thread.current[fiber_var_key]
+        end
+      end
+
+      if @nonblocking
+        Fiber.new(blocking: false) do
+          fiber_locals.each { |k, v| Thread.current[k] = v }
+          yield
+        end
+      else
+        Fiber.new do
+          fiber_locals.each { |k, v| Thread.current[k] = v }
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/graphql/date_encoding_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module GraphQL
+  # This error is raised when `Types::ISO8601Date` is asked to return a value
+  # that cannot be parsed to a Ruby Date.
+  #
+  # @see GraphQL::Types::ISO8601Date which raises this error
+  class DateEncodingError < GraphQL::RuntimeTypeError
+    # The value which couldn't be encoded
+    attr_reader :date_value
+
+    def initialize(value)
+      @date_value = value
+      super("Date cannot be parsed: #{value}. \nDate must be be able to be parsed as a Ruby Date object.")
+    end
+  end
+end

data/lib/graphql/deprecation.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Deprecation
+    def self.warn(message)
+      Kernel.warn(message)
+    end
+  end
+end

data/lib/graphql/dig.rb

@@ -2,7 +2,7 @@
 module GraphQL
   module Dig
     # implemented using the old activesupport #dig instead of the ruby built-in
-    # so we can use some of the magic in Schema::InputObject and Query::Arguments
+    # so we can use some of the magic in Schema::InputObject and Interpreter::Arguments
     # to handle stringified/symbolized keys.
     #
     # @param args [Array<[String, Symbol>] Retrieves the value object corresponding to the each key objects repeatedly