graphql 0.15.3 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a448fdb0e6f68de9172e04ff16c5bcfe5844f5e
-  data.tar.gz: 02b41b4bedeb44c838fc9d895ac70633c19e617e
+  metadata.gz: f8d3d315c998e0d44c6ebbcd186825a1d7c86639
+  data.tar.gz: adfa16f977635d988505202bee3ea8fe54ede003
 SHA512:
-  metadata.gz: 5663e57b70cc3b3b3e93cdbde3a3b9e14dfa42cff4d2554b47f60187ffb0bba138c5ed8f94bc7a4f84ddc7a6afaff3423a6931aea8946b4e4c823b9024f9d8f2
-  data.tar.gz: 8f65610a1923187c03a52847352ba66ed227094569b8191e8be7238a1ec578860756652195d1d27edb5e07c0bb17c3a273835a111259c65fcee7663706b722ac
+  metadata.gz: 34bad6ba6d2ff0e811b2d9abbddf3e834df69e8fb8d6a1b06581f446b8bffee325717df2731874bcec57581cac8d7808a9c97937d43e1d45386edf41f8824a4f
+  data.tar.gz: e11a5741e64138f68cac3ad51d14243bfa47c8f56b3b03144b685b1d2d71d4fea657221bcdffcfdaef5edd485b7df6262eb018b38ac4dcb0e01b22648c55a080

data/lib/graphql.rb

@@ -31,6 +31,7 @@ end
 
 # Order matters for these:
 
+require "graphql/execution_error"
 require "graphql/define"
 require "graphql/base_type"
 require "graphql/object_type"
@@ -56,13 +57,15 @@ require "graphql/directive"
 
 require "graphql/introspection"
 require "graphql/language"
+require "graphql/analysis"
 require "graphql/schema"
 require "graphql/schema/printer"
 
 # Order does not matter for these:
 
-require "graphql/execution_error"
+require "graphql/analysis_error"
 require "graphql/invalid_null_error"
 require "graphql/query"
+require "graphql/internal_representation"
 require "graphql/static_validation"
 require "graphql/version"

data/lib/graphql/analysis.rb

@@ -0,0 +1,5 @@
+require "graphql/analysis/max_query_complexity"
+require "graphql/analysis/max_query_depth"
+require "graphql/analysis/query_complexity"
+require "graphql/analysis/query_depth"
+require "graphql/analysis/analyze_query"

data/lib/graphql/analysis/analyze_query.rb

@@ -0,0 +1,73 @@
+module GraphQL
+  module Analysis
+    module_function
+    # Visit `query`'s internal representation, calling `analyzers` along the way.
+    #
+    # - First, query analyzers are initialized by calling `.initial_value(query)`, if they respond to that method.
+    # - Then, they receive `.call(memo, visit_type, irep_node)`, where visit type is `:enter` or `:leave`.
+    # - Last, they receive `.final_value(memo)`, if they respond to that method.
+    #
+    # It returns an array of final `memo` values in the order that `analyzers` were passed in.
+    #
+    # @param query [GraphQL::Query]
+    # @param analyzers [Array<#call>] Objects that respond to `#call(memo, visit_type, irep_node)`
+    # @return [Array<Any>] Results from those analyzers
+    def analyze_query(query, analyzers)
+      analyzers_and_values = analyzers.map { |r| initialize_reducer(r, query) }
+
+      irep = query.internal_representation
+
+      irep.each do |name, op_node|
+        reduce_node(op_node, analyzers_and_values)
+      end
+
+      analyzers_and_values.map { |(r, value)| finalize_reducer(r, value) }
+    end
+
+    private
+
+    module_function
+
+    # Enter the node, visit its children, then leave the node.
+    def reduce_node(irep_node, analyzers_and_values)
+      visit_analyzers(:enter, irep_node, analyzers_and_values)
+
+      irep_node.children.each do |name, child_irep_node|
+        reduce_node(child_irep_node, analyzers_and_values)
+      end
+
+      visit_analyzers(:leave, irep_node, analyzers_and_values)
+    end
+
+    def visit_analyzers(visit_type, irep_node, analyzers_and_values)
+      analyzers_and_values.each do |reducer_and_value|
+        reducer = reducer_and_value[0]
+        memo = reducer_and_value[1]
+        next_memo = reducer.call(memo, visit_type, irep_node)
+        reducer_and_value[1] = next_memo
+      end
+    end
+
+    # If the reducer has an `initial_value` method, call it and store
+    # the result as `memo`. Otherwise, use `nil` as memo.
+    # @return [Array<(#call, Any)>] reducer-memo pairs
+    def initialize_reducer(reducer, query)
+      if reducer.respond_to?(:initial_value)
+        [reducer, reducer.initial_value(query)]
+      else
+        [reducer, nil]
+      end
+    end
+
+    # If the reducer accepts `final_value`, send it the last memo value.
+    # Otherwise, use the last value from the traversal.
+    # @return [Any] final memo value
+    def finalize_reducer(reducer, reduced_value)
+      if reducer.respond_to?(:final_value)
+        reducer.final_value(reduced_value)
+      else
+        reduced_value
+      end
+    end
+  end
+end

data/lib/graphql/analysis/max_query_complexity.rb

@@ -0,0 +1,25 @@
+require_relative "./query_complexity"
+module GraphQL
+  module Analysis
+    # Used under the hood to implement complexity validation,
+    # see {Schema#max_complexity} and {Query#max_complexity}
+    #
+    # @example Assert max complexity of 10
+    #   # DON'T actually do this, graphql-ruby
+    #   # Does this for you based on your `max_complexity` setting
+    #   MySchema.query_analyzers << GraphQL::Analysis::MaxQueryComplexity.new(10)
+    #
+    class MaxQueryComplexity < GraphQL::Analysis::QueryComplexity
+      def initialize(max_complexity)
+        disallow_excessive_complexity = -> (query, complexity) {
+          if complexity > max_complexity
+            GraphQL::AnalysisError.new("Query has complexity of #{complexity}, which exceeds max complexity of #{max_complexity}")
+          else
+            nil
+          end
+        }
+        super(&disallow_excessive_complexity)
+      end
+    end
+  end
+end

data/lib/graphql/analysis/max_query_depth.rb

@@ -0,0 +1,25 @@
+require_relative "./query_depth"
+module GraphQL
+  module Analysis
+    # Used under the hood to implement depth validation,
+    # see {Schema#max_depth} and {Query#max_depth}
+    #
+    # @example Assert max depth of 10
+    #   # DON'T actually do this, graphql-ruby
+    #   # Does this for you based on your `max_depth` setting
+    #   MySchema.query_analyzers << GraphQL::Analysis::MaxQueryDepth.new(10)
+    #
+    class MaxQueryDepth < GraphQL::Analysis::QueryDepth
+      def initialize(max_depth)
+        disallow_excessive_depth = -> (query, depth) {
+          if depth > max_depth
+            GraphQL::AnalysisError.new("Query has depth of #{depth}, which exceeds max depth of #{max_depth}")
+          else
+            nil
+          end
+        }
+        super(&disallow_excessive_depth)
+      end
+    end
+  end
+end

data/lib/graphql/analysis/query_complexity.rb

@@ -0,0 +1,122 @@
+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::AnalysisQueryComplexity.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
+      end
+
+      # State for the query complexity calcuation:
+      # - `query` is needed for variables, then passed to handler
+      # - `complexities_on_type` holds complexity scores for each type in an IRep node
+      def initial_value(query)
+        {
+          query: query,
+          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)
+          else
+            type_complexities = memo[:complexities_on_type].pop
+            own_complexity = if GraphQL::Query::DirectiveResolution.include_node?(irep_node, memo[:query])
+              child_complexity = type_complexities.max_possible_complexity
+              get_complexity(irep_node, memo[:query], child_complexity)
+            else
+              0
+            end
+            memo[:complexities_on_type].last.merge(irep_node.on_types, own_complexity)
+          end
+        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].pop.max_possible_complexity
+        @complexity_handler.call(reduced_value[:query], total_complexity)
+      end
+
+      private
+
+      # Get a complexity value for a field,
+      # by getting the number or calling its proc
+      def get_complexity(irep_node, query, child_complexity)
+        field_defn = irep_node.definition
+        defined_complexity = field_defn.complexity
+        case defined_complexity
+        when Proc
+          args = query.arguments_for(irep_node)
+          defined_complexity.call(query.context, args, child_complexity)
+        when Numeric
+          defined_complexity + (child_complexity || 0)
+        else
+          raise("Invalid complexity: #{defined_complexity.inspect} on #{field_defn.name}")
+        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 { |h, k| h[k] = 0 }
+        end
+
+        # Return the max possible complexity for types in this selection
+        def max_possible_complexity
+          max_complexity = 0
+
+          @types.each do |type_defn, own_complexity|
+            type_complexity = @types.reduce(0) do |memo, (other_type, other_complexity)|
+              if types_overlap?(type_defn, other_type)
+                memo + other_complexity
+              else
+                memo
+              end
+            end
+
+            if type_complexity > max_complexity
+              max_complexity = type_complexity
+            end
+          end
+          max_complexity
+        end
+
+        # Store the complexity score for each of `types`
+        def merge(types, complexity)
+          types.each { |t| @types[t] += complexity }
+        end
+
+        private
+        # True if:
+        # - type_1 is type_2
+        # - type_1 is a member of type_2's possible types
+        def types_overlap?(type_1, type_2)
+          if type_1 == type_2
+            true
+          elsif type_2.kind.union?
+            type_2.include?(type_1)
+          elsif type_1.kind.object? && type_2.kind.interface?
+            type_1.interfaces.include?(type_2)
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/analysis/query_depth.rb

@@ -0,0 +1,54 @@
+module GraphQL
+  module Analysis
+    # A query reducer for measuring the depth of a given query.
+    #
+    # @example Logging the depth of a query
+    #   Schema.query_analyzers << GraphQL::Analysis::QueryDepth.new { |depth|  puts "GraphQL query depth: #{depth}" }
+    #   Schema.execute(query_str)
+    #   # GraphQL query depth: 8
+    #
+    class QueryDepth
+      def initialize(&block)
+        @depth_handler = block
+      end
+
+      def initial_value(query)
+        {
+          max_depth: 0,
+          current_depth: 0,
+          skip_current_scope: false,
+          query: query,
+        }
+      end
+
+      def call(memo, visit_type, irep_node)
+        if irep_node.ast_node.is_a?(GraphQL::Language::Nodes::Field)
+          if visit_type == :enter
+            if GraphQL::Schema::DYNAMIC_FIELDS.include?(irep_node.definition.name)
+              # Don't validate introspection fields
+              memo[:skip_current_scope] = true
+            elsif memo[:skip_current_scope]
+              # we're inside an introspection query
+            elsif GraphQL::Query::DirectiveResolution.include_node?(irep_node, memo[:query])
+              memo[:current_depth] += 1
+            end
+          else
+            if GraphQL::Schema::DYNAMIC_FIELDS.include?(irep_node.definition.name)
+              memo[:skip_current_scope] = false
+            elsif GraphQL::Query::DirectiveResolution.include_node?(irep_node, memo[:query])
+              if memo[:max_depth] < memo[:current_depth]
+                memo[:max_depth] = memo[:current_depth]
+              end
+              memo[:current_depth] -= 1
+            end
+          end
+        end
+        memo
+      end
+
+      def final_value(memo)
+        @depth_handler.call(memo[:query], memo[:max_depth])
+      end
+    end
+  end
+end

data/lib/graphql/analysis_error.rb

@@ -0,0 +1,4 @@
+module GraphQL
+  class AnalysisError < GraphQL::ExecutionError
+  end
+end

data/lib/graphql/base_type.rb

@@ -89,6 +89,13 @@ module GraphQL
       coerce_non_null_input(value)
     end
 
+    # Types with fields may override this
+    # @param name [String] field name to lookup for this type
+    # @return [GraphQL::Field, nil]
+    def get_field(name)
+      nil
+    end
+
     # During schema definition, types can be defined inside procs or as strings.
     # This function converts it to a type instance
     # @return [GraphQL::BaseType]

data/lib/graphql/define/assign_object_field.rb

@@ -2,7 +2,7 @@ module GraphQL
   module Define
     # Turn field configs into a {GraphQL::Field} and attach it to a {GraphQL::ObjectType} or {GraphQL::InterfaceType}
     module AssignObjectField
-      def self.call(fields_type, name, type = nil, desc = nil, field: nil, deprecation_reason: nil, property: nil, &block)
+      def self.call(fields_type, name, type = nil, desc = nil, field: nil, deprecation_reason: nil, property: nil, complexity: nil, &block)
         if block_given?
           field = GraphQL::Field.define(&block)
         else
@@ -11,6 +11,7 @@ module GraphQL
         type && field.type = type
         desc && field.description = desc
         property && field.property = property
+        complexity && field.complexity = complexity
         deprecation_reason && field.deprecation_reason = deprecation_reason
         field.name ||= name.to_s
         fields_type.fields[name.to_s] = field

data/lib/graphql/field.rb

@@ -3,7 +3,6 @@ module GraphQL
   #
   # They're usually created with the `field` helper. If you create it by hand, make sure {#name} is a String.
   #
-  #
   # @example creating a field
   #   GraphQL::ObjectType.define do
   #     field :name, types.String, "The name of this thing "
@@ -38,20 +37,43 @@ module GraphQL
   #     field :name, field: name_field
   #   end
   #
+  # @example Custom complexity values
+  #   # Complexity can be a number or a proc.
+  #
+  #   # Complexity can be defined with a keyword:
+  #   field :expensive_calculation, !types.Int, complexity: 10
+  #
+  #   # Or inside the block:
+  #   field :expensive_calculation_2, !types.Int do
+  #     complexity -> (ctx, args, child_complexity) { ctx[:current_user].staff? ? 0 : 10 }
+  #   end
+  #
+  # @example Calculating the complexity of a list field
+  #   field :items, types[ItemType] do
+  #     argument :limit, !types.Int
+  #     # Mulitply the child complexity by the possible items on the list
+  #     complexity -> (ctx, args, child_complexity) { child_complexity * args[:limit] }
+  #   end
+  #
   class Field
     include GraphQL::Define::InstanceDefinable
-    accepts_definitions :name, :description, :resolve, :type, :property, :deprecation_reason, argument: GraphQL::Define::AssignArgument
+    accepts_definitions :name, :description, :resolve, :type, :property, :deprecation_reason, :complexity, argument: GraphQL::Define::AssignArgument
 
     attr_accessor :deprecation_reason, :name, :description, :property
+
     attr_reader :resolve_proc
 
     # @return [String] The name of this field on its {GraphQL::ObjectType} (or {GraphQL::InterfaceType})
     attr_reader :name
 
-    # @return [Hash<String, GraphQL::Argument>] Map String argument names to their {GraphQL::Argument} implementations
+    # @return [Hash<String => GraphQL::Argument>] Map String argument names to their {GraphQL::Argument} implementations
     attr_accessor :arguments
 
+    # @return [Numeric, Proc] The complexity for this field (default: 1), as a constant or a proc like `-> (query_ctx, args, child_complexity) { } # Numeric`
+    attr_accessor :complexity
+
     def initialize
+      @complexity = 1
       @arguments = {}
       @resolve_proc = build_default_resolver
     end

data/lib/graphql/input_object_type.rb

@@ -14,7 +14,7 @@ module GraphQL
       argument: GraphQL::Define::AssignArgument
     )
 
-    # @return [Hash<String, GraphQL::Argument>] Map String argument names to their {GraphQL::Argument} implementations
+    # @return [Hash<String => GraphQL::Argument>] Map String argument names to their {GraphQL::Argument} implementations
     attr_accessor :arguments
 
     alias :input_fields :arguments