graphql 1.13.24 → 2.5.11

data/lib/graphql/analysis/query_complexity.rb

@@ -2,85 +2,260 @@
 module GraphQL
   module Analysis
     # Calculate the complexity of a query, using {Field#complexity} values.
-    #
-    # @example Log the complexity of incoming queries
-    #   MySchema.query_analyzers << GraphQL::Analysis::QueryComplexity.new do |query, complexity|
-    #     Rails.logger.info("Complexity: #{complexity}")
-    #   end
-    #
-    class QueryComplexity
-      # @yield [query, complexity] Called for each query analyzed by the schema, before executing it
-      # @yieldparam query [GraphQL::Query] The query that was analyzed
-      # @yieldparam complexity [Numeric] The complexity for this query
-      def initialize(&block)
-        @complexity_handler = block
+    class QueryComplexity < Analyzer
+      # State for the query complexity calculation:
+      # - `complexities_on_type` holds complexity scores for each type
+      def initialize(query)
+        super
+        @skip_introspection_fields = !query.schema.max_complexity_count_introspection_fields
+        @complexities_on_type_by_query = {}
       end
 
-      # State for the query complexity calcuation:
-      # - `target` is passed to handler
-      # - `complexities_on_type` holds complexity scores for each type in an IRep node
-      def initial_value(target)
-        {
-          target: target,
-          complexities_on_type: [TypeComplexity.new],
-        }
-      end
-
-      # Implement the query analyzer API
-      def call(memo, visit_type, irep_node)
-        if irep_node.ast_node.is_a?(GraphQL::Language::Nodes::Field)
-          if visit_type == :enter
-            memo[:complexities_on_type].push(TypeComplexity.new)
+      # Override this method to use the complexity result
+      def result
+        case subject.schema.complexity_cost_calculation_mode_for(subject.context)
+        when :future
+          max_possible_complexity
+        when :legacy
+          max_possible_complexity(mode: :legacy)
+        when :compare
+          future_complexity = max_possible_complexity
+          legacy_complexity = max_possible_complexity(mode: :legacy)
+          if future_complexity != legacy_complexity
+            subject.schema.legacy_complexity_cost_calculation_mismatch(subject, future_complexity, legacy_complexity)
           else
-            type_complexities = memo[:complexities_on_type].pop
-            child_complexity = type_complexities.max_possible_complexity
-            own_complexity = get_complexity(irep_node, child_complexity)
-            memo[:complexities_on_type].last.merge(irep_node.owner_type, own_complexity)
+            future_complexity
           end
+        when nil
+          subject.logger.warn <<~GRAPHQL
+            GraphQL-Ruby's complexity cost system is getting some "breaking fixes" in a future version. See the migration notes at https://graphql-ruby.org/api-doc/#{GraphQL::VERSION}/GraphQL/Schema.html#complexity_cost_calculation_mode_for-class_method
+
+            To opt into the future behavior, configure your schema (#{subject.schema.name ? subject.schema.name : subject.schema.ancestors}) with:
+
+              complexity_cost_calculation_mode(:future) # or `:legacy`, `:compare`
+
+          GRAPHQL
+          max_possible_complexity(mode: :legacy)
+        else
+          raise ArgumentError, "Expected `:future`, `:legacy`, `:compare`, or `nil` from `#{query.schema}.complexity_cost_calculation_mode_for` but got: #{query.schema.complexity_cost_calculation_mode.inspect}"
+        end
+      end
+
+      # ScopedTypeComplexity models a tree of GraphQL types mapped to inner selections, ie:
+      # Hash<GraphQL::BaseType, Hash<String, ScopedTypeComplexity>>
+      class ScopedTypeComplexity < Hash
+        # A proc for defaulting empty namespace requests as a new scope hash.
+        DEFAULT_PROC = ->(h, k) { h[k] = {} }
+
+        attr_reader :field_definition, :response_path, :query
+
+        # @param parent_type [Class] The owner of `field_definition`
+        # @param field_definition [GraphQL::Field, GraphQL::Schema::Field] Used for getting the `.complexity` configuration
+        # @param query [GraphQL::Query] Used for `query.possible_types`
+        # @param response_path [Array<String>] The path to the response key for the field
+        # @return [Hash<GraphQL::BaseType, Hash<String, ScopedTypeComplexity>>]
+        def initialize(parent_type, field_definition, query, response_path)
+          super(&DEFAULT_PROC)
+          @parent_type = parent_type
+          @field_definition = field_definition
+          @query = query
+          @response_path = response_path
+          @nodes = []
+        end
+
+        # @return [Array<GraphQL::Language::Nodes::Field>]
+        attr_reader :nodes
+
+        def own_complexity(child_complexity)
+          @field_definition.calculate_complexity(query: @query, nodes: @nodes, child_complexity: child_complexity)
+        end
+
+        def composite?
+          !empty?
         end
-        memo
       end
 
-      # Send the query and complexity to the block
-      # @return [Object, GraphQL::AnalysisError] Whatever the handler returns
-      def final_value(reduced_value)
-        total_complexity = reduced_value[:complexities_on_type].last.max_possible_complexity
-        @complexity_handler.call(reduced_value[:target], total_complexity)
+      def on_enter_field(node, parent, visitor)
+        # We don't want to visit fragment definitions,
+        # we'll visit them when we hit the spreads instead
+        return if visitor.visiting_fragment_definition?
+        return if visitor.skipping?
+        return if @skip_introspection_fields && visitor.field_definition.introspection?
+        parent_type = visitor.parent_type_definition
+        field_key = node.alias || node.name
+
+        # Find or create a complexity scope stack for this query.
+        scopes_stack = @complexities_on_type_by_query[visitor.query] ||= [ScopedTypeComplexity.new(nil, nil, query, visitor.response_path)]
+
+        # Find or create the complexity costing node for this field.
+        scope = scopes_stack.last[parent_type][field_key] ||= ScopedTypeComplexity.new(parent_type, visitor.field_definition, visitor.query, visitor.response_path)
+        scope.nodes.push(node)
+        scopes_stack.push(scope)
+      end
+
+      def on_leave_field(node, parent, visitor)
+        # We don't want to visit fragment definitions,
+        # we'll visit them when we hit the spreads instead
+        return if visitor.visiting_fragment_definition?
+        return if visitor.skipping?
+        return if @skip_introspection_fields && visitor.field_definition.introspection?
+        scopes_stack = @complexities_on_type_by_query[visitor.query]
+        scopes_stack.pop
       end
 
       private
 
-      # Get a complexity value for a field,
-      # by getting the number or calling its proc
-      def get_complexity(irep_node, child_complexity)
-        field_defn = irep_node.definition
-        defined_complexity = field_defn.complexity
-        case defined_complexity
-        when Proc
-          defined_complexity.call(irep_node.query.context, irep_node.arguments, child_complexity)
-        when Numeric
-          defined_complexity + (child_complexity || 0)
-        else
-          raise("Invalid complexity: #{defined_complexity.inspect} on #{field_defn.name}")
+      # @return [Integer]
+      def max_possible_complexity(mode: :future)
+        @complexities_on_type_by_query.reduce(0) do |total, (query, scopes_stack)|
+          total + merged_max_complexity_for_scopes(query, [scopes_stack.first], mode)
         end
       end
 
-      # Selections on an object may apply differently depending on what is _actually_ returned by the resolve function.
-      # Find the maximum possible complexity among those combinations.
-      class TypeComplexity
-        def initialize
-          @types = Hash.new(0)
+      # @param query [GraphQL::Query] Used for `query.possible_types`
+      # @param scopes [Array<ScopedTypeComplexity>] Array of scoped type complexities
+      # @param mode [:future, :legacy]
+      # @return [Integer]
+      def merged_max_complexity_for_scopes(query, scopes, mode)
+        # Aggregate a set of all possible scope types encountered (scope keys).
+        # Use a hash, but ignore the values; it's just a fast way to work with the keys.
+        possible_scope_types = scopes.each_with_object({}) do |scope, memo|
+          memo.merge!(scope)
         end
 
-        # Return the max possible complexity for types in this selection
-        def max_possible_complexity
-          @types.each_value.max || 0
+        # Expand abstract scope types into their concrete implementations;
+        # overlapping abstracts coalesce through their intersecting types.
+        possible_scope_types.keys.each do |possible_scope_type|
+          next unless possible_scope_type.kind.abstract?
+
+          query.types.possible_types(possible_scope_type).each do |impl_type|
+            possible_scope_types[impl_type] ||= true
+          end
+          possible_scope_types.delete(possible_scope_type)
         end
 
-        # Store the complexity for the branch on `type_defn`.
-        # Later we will see if this is the max complexity among branches.
-        def merge(type_defn, complexity)
-          @types[type_defn] += complexity
+        # Aggregate the lexical selections that may apply to each possible type,
+        # and then return the maximum cost among possible typed selections.
+        possible_scope_types.each_key.reduce(0) do |max, possible_scope_type|
+          # Collect inner selections from all scopes that intersect with this possible type.
+          all_inner_selections = scopes.each_with_object([]) do |scope, memo|
+            scope.each do |scope_type, inner_selections|
+              memo << inner_selections if types_intersect?(query, scope_type, possible_scope_type)
+            end
+          end
+
+          # Find the maximum complexity for the scope type among possible lexical branches.
+          complexity = case mode
+          when :legacy
+            legacy_merged_max_complexity(query, all_inner_selections)
+          when :future
+            merged_max_complexity(query, all_inner_selections)
+          else
+            raise ArgumentError, "Expected :legacy or :future, not: #{mode.inspect}"
+          end
+          complexity > max ? complexity : max
+        end
+      end
+
+      def types_intersect?(query, a, b)
+        return true if a == b
+        a_types = query.types.possible_types(a)
+        query.types.possible_types(b).any? { |t| a_types.include?(t) }
+      end
+
+      # A hook which is called whenever a field's max complexity is calculated.
+      # Override this method to capture individual field complexity details.
+      #
+      # @param scoped_type_complexity [ScopedTypeComplexity]
+      # @param max_complexity [Numeric] Field's maximum complexity including child complexity
+      # @param child_complexity [Numeric, nil] Field's child complexity
+      def field_complexity(scoped_type_complexity, max_complexity:, child_complexity: nil)
+      end
+
+      # @param inner_selections [Array<Hash<String, ScopedTypeComplexity>>] Field selections for a scope
+      # @return [Integer] Total complexity value for all these selections in the parent scope
+      def merged_max_complexity(query, inner_selections)
+        # Aggregate a set of all unique field selection keys across all scopes.
+        # Use a hash, but ignore the values; it's just a fast way to work with the keys.
+        unique_field_keys = inner_selections.each_with_object({}) do |inner_selection, memo|
+          memo.merge!(inner_selection)
+        end
+
+        # Add up the total cost for each unique field name's coalesced selections
+        unique_field_keys.each_key.reduce(0) do |total, field_key|
+          # Collect all child scopes for this field key;
+          # all keys come with at least one scope.
+          child_scopes = inner_selections.filter_map { _1[field_key] }
+
+          # Compute maximum possible cost of child selections;
+          # composites merge their maximums, while leaf scopes are always zero.
+          # FieldsWillMerge validation assures all scopes are uniformly composite or leaf.
+          maximum_children_cost = if child_scopes.any?(&:composite?)
+            merged_max_complexity_for_scopes(query, child_scopes, :future)
+          else
+            0
+          end
+
+          # Identify the maximum cost and scope among possibilities
+          maximum_cost = 0
+          maximum_scope = child_scopes.reduce(child_scopes.last) do |max_scope, possible_scope|
+            scope_cost = possible_scope.own_complexity(maximum_children_cost)
+            if scope_cost > maximum_cost
+              maximum_cost = scope_cost
+              possible_scope
+            else
+              max_scope
+            end
+          end
+
+          field_complexity(
+            maximum_scope,
+            max_complexity: maximum_cost,
+            child_complexity: maximum_children_cost,
+          )
+
+          total + maximum_cost
+        end
+      end
+
+      def legacy_merged_max_complexity(query, inner_selections)
+        # Aggregate a set of all unique field selection keys across all scopes.
+        # Use a hash, but ignore the values; it's just a fast way to work with the keys.
+        unique_field_keys = inner_selections.each_with_object({}) do |inner_selection, memo|
+          memo.merge!(inner_selection)
+        end
+
+        # Add up the total cost for each unique field name's coalesced selections
+        unique_field_keys.each_key.reduce(0) do |total, field_key|
+          composite_scopes = nil
+          field_cost = 0
+
+          # Collect composite selection scopes for further aggregation,
+          # leaf selections report their costs directly.
+          inner_selections.each do |inner_selection|
+            child_scope = inner_selection[field_key]
+            next unless child_scope
+
+            # Empty child scopes are leaf nodes with zero child complexity.
+            if child_scope.empty?
+              field_cost = child_scope.own_complexity(0)
+              field_complexity(child_scope, max_complexity: field_cost, child_complexity: nil)
+            else
+              composite_scopes ||= []
+              composite_scopes << child_scope
+            end
+          end
+
+          if composite_scopes
+            child_complexity = merged_max_complexity_for_scopes(query, composite_scopes, :legacy)
+
+            # This is the last composite scope visited; assume it's representative (for backwards compatibility).
+            # Note: it would be more correct to score each composite scope and use the maximum possibility.
+            field_cost = composite_scopes.last.own_complexity(child_complexity)
+            field_complexity(composite_scopes.last, max_complexity: field_cost, child_complexity: child_complexity)
+          end
+
+          total + field_cost
         end
       end
     end

data/lib/graphql/analysis/query_depth.rb

@@ -3,40 +3,55 @@ module GraphQL
   module Analysis
     # A query reducer for measuring the depth of a given query.
     #
+    # See https://graphql-ruby.org/queries/ast_analysis.html for more examples.
+    #
     # @example Logging the depth of a query
-    #   Schema.query_analyzers << GraphQL::Analysis::QueryDepth.new { |query, depth|  puts "GraphQL query depth: #{depth}" }
+    #   class LogQueryDepth < GraphQL::Analysis::QueryDepth
+    #     def result
+    #       log("GraphQL query depth: #{@max_depth}")
+    #     end
+    #   end
+    #
+    #   # In your Schema file:
+    #
+    #   class MySchema < GraphQL::Schema
+    #     query_analyzer LogQueryDepth
+    #   end
+    #
+    #   # When you run the query, the depth will get logged:
+    #
     #   Schema.execute(query_str)
     #   # GraphQL query depth: 8
     #
-    class QueryDepth
-      def initialize(&block)
-        @depth_handler = block
+    class QueryDepth < Analyzer
+      def initialize(query)
+        @max_depth = 0
+        @current_depth = 0
+        @count_introspection_fields = query.schema.count_introspection_fields
+        super
       end
 
-      def initial_value(query)
-        {
-          max_depth: 0,
-          current_depth: 0,
-          query: query,
-        }
+      def on_enter_field(node, parent, visitor)
+        return if visitor.skipping? ||
+          visitor.visiting_fragment_definition? ||
+            (@count_introspection_fields == false && visitor.field_definition.introspection?)
+
+        @current_depth += 1
       end
 
-      def call(memo, visit_type, irep_node)
-        if irep_node.ast_node.is_a?(GraphQL::Language::Nodes::Field)
-          if visit_type == :enter
-            memo[:current_depth] += 1
-          else
-            if memo[:max_depth] < memo[:current_depth]
-              memo[:max_depth] = memo[:current_depth]
-            end
-            memo[:current_depth] -= 1
-          end
+      def on_leave_field(node, parent, visitor)
+        return if visitor.skipping? ||
+          visitor.visiting_fragment_definition? ||
+          (@count_introspection_fields == false && visitor.field_definition.introspection?)
+
+        if @max_depth < @current_depth
+          @max_depth = @current_depth
         end
-        memo
+        @current_depth -= 1
       end
 
-      def final_value(memo)
-        @depth_handler.call(memo[:query], memo[:max_depth])
+      def result
+        @max_depth
       end
     end
   end

data/lib/graphql/analysis/visitor.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+module GraphQL
+  module Analysis
+    # Depth first traversal through a query AST, calling AST analyzers
+    # along the way.
+    #
+    # The visitor is a special case of GraphQL::Language::StaticVisitor, visiting
+    # only the selected operation, providing helpers for common use cases such
+    # as skipped fields and visiting fragment spreads.
+    #
+    # @see {GraphQL::Analysis::Analyzer} AST Analyzers for queries
+    class Visitor < GraphQL::Language::StaticVisitor
+      def initialize(query:, analyzers:, timeout:)
+        @analyzers = analyzers
+        @path = []
+        @object_types = []
+        @directives = []
+        @field_definitions = []
+        @argument_definitions = []
+        @directive_definitions = []
+        @rescued_errors = []
+        @query = query
+        @schema = query.schema
+        @types = query.types
+        @response_path = []
+        @skip_stack = [false]
+        @timeout_time = if timeout
+          Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second) + timeout
+        else
+          Float::INFINITY
+        end
+        super(query.selected_operation)
+      end
+
+      # @return [GraphQL::Query] the query being visited
+      attr_reader :query
+
+      # @return [Array<GraphQL::ObjectType>] Types whose scope we've entered
+      attr_reader :object_types
+
+      # @return [Array<GraphQL::AnalysisError]
+      attr_reader :rescued_errors
+
+      def visit
+        return unless @document
+        super
+      end
+
+      # Visit Helpers
+
+      # @return [GraphQL::Execution::Interpreter::Arguments] Arguments for this node, merging default values, literal values and query variables
+      # @see {GraphQL::Query#arguments_for}
+      def arguments_for(ast_node, field_definition)
+        @query.arguments_for(ast_node, field_definition)
+      end
+
+      # @return [Boolean] If the visitor is currently inside a fragment definition
+      def visiting_fragment_definition?
+        @in_fragment_def
+      end
+
+      # @return [Boolean] If the current node should be skipped because of a skip or include directive
+      def skipping?
+        @skipping
+      end
+
+      # @return [Array<String>] The path to the response key for the current field
+      def response_path
+        @response_path.dup
+      end
+
+      # rubocop:disable Development/NoEvalCop This eval takes static inputs at load-time
+      # Visitor Hooks
+      [
+        :operation_definition, :fragment_definition,
+        :inline_fragment, :field, :directive, :argument, :fragment_spread
+      ].each do |node_type|
+        module_eval <<-RUBY, __FILE__, __LINE__
+        def call_on_enter_#{node_type}(node, parent)
+          @analyzers.each do |a|
+            a.on_enter_#{node_type}(node, parent, self)
+          rescue AnalysisError => err
+            @rescued_errors << err
+          end
+        end
+
+        def call_on_leave_#{node_type}(node, parent)
+          @analyzers.each do |a|
+            a.on_leave_#{node_type}(node, parent, self)
+          rescue AnalysisError => err
+            @rescued_errors << err
+          end
+        end
+
+        RUBY
+      end
+      # rubocop:enable Development/NoEvalCop
+
+      def on_operation_definition(node, parent)
+        check_timeout
+        object_type = @schema.root_type_for_operation(node.operation_type)
+        @object_types.push(object_type)
+        @path.push("#{node.operation_type}#{node.name ? " #{node.name}" : ""}")
+        call_on_enter_operation_definition(node, parent)
+        super
+        call_on_leave_operation_definition(node, parent)
+        @object_types.pop
+        @path.pop
+      end
+
+      def on_inline_fragment(node, parent)
+        check_timeout
+        object_type = if node.type
+          @types.type(node.type.name)
+        else
+          @object_types.last
+        end
+        @object_types.push(object_type)
+        @path.push("...#{node.type ? " on #{node.type.name}" : ""}")
+        @skipping = @skip_stack.last || skip?(node)
+        @skip_stack << @skipping
+        call_on_enter_inline_fragment(node, parent)
+        super
+        @skipping = @skip_stack.pop
+        call_on_leave_inline_fragment(node, parent)
+        @object_types.pop
+        @path.pop
+      end
+
+      def on_field(node, parent)
+        check_timeout
+        @response_path.push(node.alias || node.name)
+        parent_type = @object_types.last
+        # This could be nil if the previous field wasn't found:
+        field_definition = parent_type && @types.field(parent_type, node.name)
+        @field_definitions.push(field_definition)
+        if !field_definition.nil?
+          next_object_type = field_definition.type.unwrap
+          @object_types.push(next_object_type)
+        else
+          @object_types.push(nil)
+        end
+        @path.push(node.alias || node.name)
+
+        @skipping = @skip_stack.last || skip?(node)
+        @skip_stack << @skipping
+
+        call_on_enter_field(node, parent)
+        super
+        @skipping = @skip_stack.pop
+        call_on_leave_field(node, parent)
+        @response_path.pop
+        @field_definitions.pop
+        @object_types.pop
+        @path.pop
+      end
+
+      def on_directive(node, parent)
+        check_timeout
+        directive_defn = @schema.directives[node.name]
+        @directive_definitions.push(directive_defn)
+        call_on_enter_directive(node, parent)
+        super
+        call_on_leave_directive(node, parent)
+        @directive_definitions.pop
+      end
+
+      def on_argument(node, parent)
+        check_timeout
+        argument_defn = if (arg = @argument_definitions.last)
+          arg_type = arg.type.unwrap
+          if arg_type.kind.input_object?
+            @types.argument(arg_type, node.name)
+          else
+            nil
+          end
+        elsif (directive_defn = @directive_definitions.last)
+          @types.argument(directive_defn, node.name)
+        elsif (field_defn = @field_definitions.last)
+          @types.argument(field_defn, node.name)
+        else
+          nil
+        end
+
+        @argument_definitions.push(argument_defn)
+        @path.push(node.name)
+        call_on_enter_argument(node, parent)
+        super
+        call_on_leave_argument(node, parent)
+        @argument_definitions.pop
+        @path.pop
+      end
+
+      def on_fragment_spread(node, parent)
+        check_timeout
+        @path.push("... #{node.name}")
+        @skipping = @skip_stack.last || skip?(node)
+        @skip_stack << @skipping
+
+        call_on_enter_fragment_spread(node, parent)
+        enter_fragment_spread_inline(node)
+        super
+        @skipping = @skip_stack.pop
+        leave_fragment_spread_inline(node)
+        call_on_leave_fragment_spread(node, parent)
+        @path.pop
+      end
+
+      # @return [GraphQL::BaseType] The current object type
+      def type_definition
+        @object_types.last
+      end
+
+      # @return [GraphQL::BaseType] The type which the current type came from
+      def parent_type_definition
+        @object_types[-2]
+      end
+
+      # @return [GraphQL::Field, nil] The most-recently-entered GraphQL::Field, if currently inside one
+      def field_definition
+        @field_definitions.last
+      end
+
+      # @return [GraphQL::Field, nil] The GraphQL field which returned the object that the current field belongs to
+      def previous_field_definition
+        @field_definitions[-2]
+      end
+
+      # @return [GraphQL::Directive, nil] The most-recently-entered GraphQL::Directive, if currently inside one
+      def directive_definition
+        @directive_definitions.last
+      end
+
+      # @return [GraphQL::Argument, nil] The most-recently-entered GraphQL::Argument, if currently inside one
+      def argument_definition
+        @argument_definitions.last
+      end
+
+      # @return [GraphQL::Argument, nil] The previous GraphQL argument
+      def previous_argument_definition
+        @argument_definitions[-2]
+      end
+
+      private
+
+      # Visit a fragment spread inline instead of visiting the definition
+      # by itself.
+      def enter_fragment_spread_inline(fragment_spread)
+        fragment_def = query.fragments[fragment_spread.name]
+
+        object_type = if fragment_def.type
+          @types.type(fragment_def.type.name)
+        else
+          object_types.last
+        end
+
+        object_types << object_type
+
+        on_fragment_definition_children(fragment_def)
+      end
+
+      # Visit a fragment spread inline instead of visiting the definition
+      # by itself.
+      def leave_fragment_spread_inline(_fragment_spread)
+        object_types.pop
+      end
+
+      def skip?(ast_node)
+        dir = ast_node.directives
+        !dir.empty? && !GraphQL::Execution::DirectiveChecks.include?(dir, query)
+      end
+
+      def check_timeout
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second) > @timeout_time
+          raise GraphQL::Analysis::TimeoutError
+        end
+      end
+    end
+  end
+end