graphql 2.6.12 → 2.6.13

data/lib/graphql/static_validation/rules/variable_usages_are_allowed.rb

@@ -1,27 +1,79 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
+    #--
+    # @requires_ancestor: GraphQL::StaticValidation::BaseVisitor
     module VariableUsagesAreAllowed
+      # A variable in a fragment. It's checked after the visit, against each operation which uses the fragment.
+      # `list_depth` is the number of list literals around the variable.
+      FragmentVariableUsage = Struct.new(:argument_owner, :arg_node, :variable_name, :list_depth, :path, :checked_variable_types)
+
       def initialize(*)
         super
         # holds { name => ast_node } pairs
         @declared_variables = {}
+        @operation_declared_variables = {}.compare_by_identity #: Hash[GraphQL::Language::Nodes::OperationDefinition, Hash[String, GraphQL::Language::Nodes::VariableDefinition]]
+        @variable_usages_fragment_definition = nil
+        @fragment_variable_usages = nil #: Hash[GraphQL::Language::Nodes::FragmentDefinition, Array[FragmentVariableUsage]]?
+        @reported_fragment_variable_errors = nil #: Hash[GraphQL::Language::Nodes::Argument, Hash[String, bool]]?
+        @allow_legacy_invalid_variable_usages = @schema.allow_legacy_invalid_variable_usages
+        # The arguments and variables which have an error from the legacy check
+        @legacy_errors = nil #: Hash[GraphQL::Language::Nodes::Argument, Hash[String, bool]]?
       end
 
       def on_operation_definition(node, parent)
         @declared_variables = node.variables.each_with_object({}) { |var, memo| memo[var.name] = var }
+        @operation_declared_variables[node] = @declared_variables
         super
       end
 
-      def on_argument(node, parent)
-        node_values = if node.value.is_a?(Array)
-          node.value
-        else
-          [node.value]
+      def on_fragment_definition(node, parent)
+        @variable_usages_fragment_definition = node
+        super
+        @variable_usages_fragment_definition = nil
+      end
+
+      def on_document(node, parent)
+        super
+        # A fragment can come before the operations which use it, and many operations can use it.
+        # So, check its variable usages after the visit, against each operation which uses it.
+        fragment_usages = @fragment_variable_usages
+        return if fragment_usages.nil?
+
+        dependencies = context.dependencies
+        @operation_declared_variables.each do |definition, declared_variables|
+          next if declared_variables.empty?
+
+          variable_types = {} #: Hash[String, untyped]
+          checked_fragments = {}.compare_by_identity
+          dependencies[definition].each do |fragment_definition|
+            next if checked_fragments.key?(fragment_definition)
+            checked_fragments[fragment_definition] = true
+            usages = fragment_usages[fragment_definition]
+            next if usages.nil?
+
+            usages.each do |usage|
+              var_defn_ast = declared_variables[usage.variable_name]
+              # If it's undefined, VariablesAreUsedAndDefined adds an error
+              next if var_defn_ast.nil?
+              var_type = variable_types.fetch(usage.variable_name) { variable_types[usage.variable_name] = usage_variable_type(var_defn_ast) }
+              next if var_type.nil?
+              # The result depends only on the usage and the variable type, so check each pair once.
+              # (`type_from_ast` returns the same object for the same type.)
+              checked = (usage.checked_variable_types ||= {}.compare_by_identity)
+              next if checked.key?(var_type)
+              checked[var_type] = true
+              validate_usage(usage.argument_owner, usage.arg_node, var_defn_ast, usage.list_depth, path: usage.path, var_type: var_type)
+            end
+          end
         end
-        node_values = node_values.select { |value| value.is_a? GraphQL::Language::Nodes::VariableIdentifier }
+      end
+
+      def on_argument(node, parent)
+        variables = variables_in_value(node.value, 0, nil)
 
-        if !node_values.empty?
+        if variables
           argument_owner = case parent
           when GraphQL::Language::Nodes::Field
             context.field_definition
@@ -39,11 +91,38 @@ module GraphQL
             raise("Unexpected argument parent: #{parent}")
           end
 
-          node_values.each do |node_value|
-            var_defn_ast = @declared_variables[node_value.name]
-            # Might be undefined :(
-            # VariablesAreUsedAndDefined can't finalize its search until the end of the document.
-            var_defn_ast && argument_owner && validate_usage(argument_owner, node, var_defn_ast)
+          if (fragment_definition = @variable_usages_fragment_definition)
+            if argument_owner
+              usages = ((@fragment_variable_usages ||= {}.compare_by_identity)[fragment_definition] ||= [])
+              path = context.path
+              variables.each do |(variable, list_depth)|
+                usages << FragmentVariableUsage.new(argument_owner, node, variable.name, list_depth, path)
+                # Previous versions checked a fragment against the last operation before it
+                if @allow_legacy_invalid_variable_usages != false && (var_defn_ast = @declared_variables[variable.name])
+                  add_legacy_error(argument_owner, node, var_defn_ast, list_depth)
+                end
+              end
+            end
+          elsif argument_owner
+            variables.each do |(variable, list_depth)|
+              var_defn_ast = @declared_variables[variable.name]
+              # Might be undefined :(
+              # VariablesAreUsedAndDefined can't finalize its search until the end of the document.
+              next if var_defn_ast.nil?
+
+              legacy_reported = false
+              if @allow_legacy_invalid_variable_usages != false
+                # The legacy check is the same, except for a `= null` default or a variable in a nested or mixed list
+                if var_defn_ast.default_value.is_a?(GraphQL::Language::Nodes::NullValue) ||
+                    list_depth > 1 ||
+                    (list_depth == 1 && depth_of_array(node.value) != 1)
+                  add_legacy_error(argument_owner, node, var_defn_ast, list_depth)
+                else
+                  legacy_reported = true
+                end
+              end
+              validate_usage(argument_owner, node, var_defn_ast, list_depth, legacy_reported: legacy_reported)
+            end
           end
         end
         super
@@ -51,21 +130,76 @@ module GraphQL
 
       private
 
-      def validate_usage(argument_owner, arg_node, ast_var)
-        var_type = context.schema.type_from_ast(ast_var.type, context: context)
-        if var_type.nil?
-          return
+      # Variables inside input objects are found when their own arguments are visited.
+      #: (untyped value, Integer list_depth, Array[[GraphQL::Language::Nodes::VariableIdentifier, Integer]]? variables) -> Array[[GraphQL::Language::Nodes::VariableIdentifier, Integer]]?
+      def variables_in_value(value, list_depth, variables)
+        case value
+        when GraphQL::Language::Nodes::VariableIdentifier
+          (variables ||= []) << [value, list_depth]
+        when Array
+          value.each { |item| variables = variables_in_value(item, list_depth + 1, variables) }
         end
-        if !ast_var.default_value.nil?
+        variables
+      end
+
+      #: (GraphQL::Language::Nodes::VariableDefinition ast_var, ?legacy: bool) -> untyped
+      def usage_variable_type(ast_var, legacy: false)
+        var_type = context.schema.type_from_ast(ast_var.type, context: context)
+        return nil if var_type.nil?
+        default_value = ast_var.default_value
+        # An explicit `= null` default doesn't make the variable non-null (but previous versions treated it as non-null)
+        if !default_value.nil? && (legacy || !default_value.is_a?(GraphQL::Language::Nodes::NullValue))
           unless var_type.kind.non_null?
             # If the value is required, but the argument is not,
-            # and yet there's a non-nil default, then we impliclty
+            # and yet there's a non-null default, then we impliclty
             # make the argument also a required type.
             var_type = var_type.to_non_null_type
           end
         end
+        var_type
+      end
+
+      # `legacy_reported:` is true when the legacy check has the same result, so an error isn't a legacy invalid usage.
+      #: (untyped argument_owner, GraphQL::Language::Nodes::Argument arg_node, GraphQL::Language::Nodes::VariableDefinition ast_var, Integer list_depth, ?path: Array[String]?, ?var_type: untyped, ?legacy_reported: bool) -> void
+      def validate_usage(argument_owner, arg_node, ast_var, list_depth, path: nil, var_type: usage_variable_type(ast_var), legacy_reported: false)
+        return if var_type.nil?
 
         arg_defn = @types.argument(argument_owner, arg_node.name)
+        error_message = usage_error(arg_defn, var_type, list_depth)
+        return if error_message.nil?
+
+        message_override = nil
+        if @allow_legacy_invalid_variable_usages != false && !legacy_reported
+          # The legacy check already added its error for this argument and variable
+          return if @legacy_errors&.dig(arg_node, ast_var.name)
+
+          if @allow_legacy_invalid_variable_usages == true
+            legacy_handling = @schema.legacy_invalid_variable_usages(context.query, ast_var, arg_node)
+            case legacy_handling
+            when nil
+              return
+            when :return_validation_error
+              # Add the error below
+            when String
+              message_override = legacy_handling
+            else
+              raise GraphQL::Error, "#{@schema}.legacy_invalid_variable_usages returned unexpected value: #{legacy_handling.inspect}. Expected `nil`, String, or `:return_validation_error`."
+            end
+          else
+            context.query.logger.warn <<~WARN
+              GraphQL-Ruby encountered an invalid variable usage in this query: `$#{ast_var.name}` (at #{ast_var.line}:#{ast_var.col}) for argument `#{arg_node.name}` (at #{arg_node.line}:#{arg_node.col}).
+              This will return an error in future GraphQL-Ruby versions, as per the GraphQL specification
+              Learn about migrating here: https://graphql-ruby.org/api-doc/#{GraphQL::VERSION}/GraphQL/Schema.html#allow_legacy_invalid_variable_usages-class_method
+            WARN
+            return
+          end
+        end
+
+        create_error(error_message, wrap_var_type_in_lists(var_type, list_depth), ast_var, arg_defn, arg_node, path, message_override)
+      end
+
+      #: (untyped arg_defn, untyped var_type, Integer list_depth) -> String?
+      def usage_error(arg_defn, var_type, list_depth)
         arg_defn_type = arg_defn.type
 
         # If the argument is non-null, but it was given a default value,
@@ -77,52 +211,43 @@ module GraphQL
         var_inner_type = var_type.unwrap
         arg_inner_type = arg_defn_type.unwrap
 
-        var_type = wrap_var_type_with_depth_of_arg(var_type, arg_node)
+        var_type = wrap_var_type_in_lists(var_type, list_depth)
 
         if var_inner_type != arg_inner_type
-          create_error("Type mismatch", var_type, ast_var, arg_defn, arg_node)
+          "Type mismatch"
         elsif list_dimension(var_type) != list_dimension(arg_defn_type)
-          create_error("List dimension mismatch", var_type, ast_var, arg_defn, arg_node)
+          "List dimension mismatch"
         elsif !non_null_levels_match(arg_defn_type, var_type)
-          create_error("Nullability mismatch", var_type, ast_var, arg_defn, arg_node)
+          "Nullability mismatch"
         end
       end
 
-      def create_error(error_message, var_type, ast_var, arg_defn, arg_node)
-        add_error(GraphQL::StaticValidation::VariableUsagesAreAllowedError.new(
-          "#{error_message} on variable $#{ast_var.name} and argument #{arg_node.name} (#{var_type.to_type_signature} / #{arg_defn.type.to_type_signature})",
-          nodes: arg_node,
-          name: ast_var.name,
-          type: var_type.to_type_signature,
-          argument: arg_node.name,
-          error: error_message
-        ))
-      end
-
-      def wrap_var_type_with_depth_of_arg(var_type, arg_node)
-        arg_node_value = arg_node.value
-        return var_type unless arg_node_value.is_a?(Array)
-        new_var_type = var_type
+      # Add the error which previous versions added for this usage, if any, so that the legacy behavior rejects the same documents.
+      # They didn't check variables in nested lists, used the depth of the whole list value for each variable in it,
+      # and treated a `= null` default as non-null.
+      #: (untyped argument_owner, GraphQL::Language::Nodes::Argument arg_node, GraphQL::Language::Nodes::VariableDefinition ast_var, Integer list_depth) -> void
+      def add_legacy_error(argument_owner, arg_node, ast_var, list_depth)
+        return if list_depth > 1
+        var_type = usage_variable_type(ast_var, legacy: true)
+        return if var_type.nil?
 
-        depth_of_array(arg_node_value).times do
-          # Since the array _is_ present, treat it like a non-null type
-          # (It satisfies a non-null requirement AND a nullable requirement)
-          new_var_type = new_var_type.to_list_type.to_non_null_type
-        end
+        list_depth = depth_of_array(arg_node.value) if list_depth == 1
+        arg_defn = @types.argument(argument_owner, arg_node.name)
+        error_message = usage_error(arg_defn, var_type, list_depth)
+        return if error_message.nil?
 
-        new_var_type
+        ((@legacy_errors ||= {}.compare_by_identity)[arg_node] ||= {})[ast_var.name] = true
+        create_error(error_message, wrap_var_type_in_lists(var_type, list_depth), ast_var, arg_defn, arg_node, nil, nil)
       end
 
-      # @return [Integer] Returns the max depth of `array`, or `0` if it isn't an array at all
-      def depth_of_array(array)
-        case array
-        when Array
+      # The maximum depth of list literals in `value`
+      #: (untyped value) -> Integer
+      def depth_of_array(value)
+        if value.is_a?(Array)
           max_child_depth = 0
-          array.each do |item|
+          value.each do |item|
             item_depth = depth_of_array(item)
-            if item_depth > max_child_depth
-              max_child_depth = item_depth
-            end
+            max_child_depth = item_depth if item_depth > max_child_depth
           end
           1 + max_child_depth
         else
@@ -130,6 +255,37 @@ module GraphQL
         end
       end
 
+      #: (String error_message, untyped var_type, GraphQL::Language::Nodes::VariableDefinition ast_var, untyped arg_defn, GraphQL::Language::Nodes::Argument arg_node, Array[String]? path, String? message_override) -> void
+      def create_error(error_message, var_type, ast_var, arg_defn, arg_node, path, message_override)
+        message = "#{error_message} on variable $#{ast_var.name} and argument #{arg_node.name} (#{var_type.to_type_signature} / #{arg_defn.type.to_type_signature})"
+        if path
+          # Many operations can use one fragment, so add each error only once.
+          reported = (@reported_fragment_variable_errors ||= {}.compare_by_identity)[arg_node] ||= {}
+          return if reported.key?(message)
+          reported[message] = true
+        end
+
+        add_error(GraphQL::StaticValidation::VariableUsagesAreAllowedError.new(
+          message_override || message,
+          nodes: arg_node,
+          name: ast_var.name,
+          type: var_type.to_type_signature,
+          argument: arg_node.name,
+          error: error_message
+        ), path: path)
+      end
+
+      # A variable in list literals is used as a list item, so wrap its type in one list for each list literal.
+      #: (untyped var_type, Integer list_depth) -> untyped
+      def wrap_var_type_in_lists(var_type, list_depth)
+        list_depth.times do
+          # Since the array _is_ present, treat it like a non-null type
+          # (It satisfies a non-null requirement AND a nullable requirement)
+          var_type = var_type.to_list_type.to_non_null_type
+        end
+        var_type
+      end
+
       def list_dimension(type)
         if type.kind.list?
           1 + list_dimension(type.of_type)

data/lib/graphql/static_validation/rules/variable_usages_are_allowed_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     class VariableUsagesAreAllowedError < StaticValidation::Error

data/lib/graphql/static_validation/rules/variables_are_input_types.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
+    #--
+    # @requires_ancestor: GraphQL::StaticValidation::BaseVisitor
     module VariablesAreInputTypes
       def on_variable_definition(node, parent)
         type_name = get_type_name(node.type)

data/lib/graphql/static_validation/rules/variables_are_input_types_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     class VariablesAreInputTypesError < StaticValidation::Error

data/lib/graphql/static_validation/rules/variables_are_used_and_defined.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     # The problem is
@@ -11,6 +12,8 @@ module GraphQL
     #   - re-visiting the AST for each validator
     #   - allowing validators to say `followSpreads: true`
     #
+    #--
+    # @requires_ancestor: GraphQL::StaticValidation::BaseVisitor
     module VariablesAreUsedAndDefined
       class VariableUsage
         attr_accessor :ast_node, :used_by, :declared_by, :path
@@ -89,13 +92,13 @@ module GraphQL
       private
 
       # Follow spreads in `node`, looking them up from `spreads_for_context` and finding their match in `fragment_definitions`.
-      # Use those fragments to update {VariableUsage}s in `parent_variables`.
+      # Use those fragments to update [VariableUsage](rdoc-ref:VariableUsage)s in `parent_variables`.
       # Avoid infinite loops by skipping anything in `visited_fragments`.
       def follow_spreads(node, parent_variables, spreads_for_context, fragment_definitions, visited_fragments)
         spreads = spreads_for_context[node] - visited_fragments
         spreads.each do |spread_name|
-          def_node = nil
-          variables = nil
+          def_node = nil #: untyped
+          variables = nil #: untyped
           # Implement `.find` by hand to avoid Ruby's internal allocations
           fragment_definitions.each do |frag_def_node, vars|
             if frag_def_node.name == spread_name

data/lib/graphql/static_validation/rules/variables_are_used_and_defined_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     class VariablesAreUsedAndDefinedError < StaticValidation::Error

data/lib/graphql/static_validation/validation_context.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     # The validation context gets passed to each validator.
     #
-    # It exposes a {GraphQL::Language::Visitor} where validators may add hooks. ({Language::Visitor#visit} is called in {Validator#validate})
+    # It exposes a [GraphQL::Language::Visitor](rdoc-ref:GraphQL::Language::Visitor) where validators may add hooks. ([Language::Visitor#visit](rdoc-ref:Language::Visitor#visit) is called in [Validator#validate](rdoc-ref:Validator#validate))
     #
     # It provides access to the schema & fragments which validators may read from.
     #
@@ -52,7 +53,7 @@ module GraphQL
 
       def did_you_mean_suggestion(name, options)
         if did_you_mean = schema.did_you_mean
-          suggestions = did_you_mean::SpellChecker.new(dictionary: options).correct(name)
+          suggestions = did_you_mean.const_get(:SpellChecker).new(dictionary: options).correct(name)
           case suggestions.size
           when 0
             ""

data/lib/graphql/static_validation/validation_timeout_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module StaticValidation
     class ValidationTimeoutError < StaticValidation::Error

data/lib/graphql/static_validation/validator.rb

@@ -1,33 +1,52 @@
 # frozen_string_literal: true
+# typed: true
 require "timeout"
 
 module GraphQL
   module StaticValidation
-    # Initialized with a {GraphQL::Schema}, then it can validate {GraphQL::Language::Nodes::Documents}s based on that schema.
+    # Initialized with a [GraphQL::Schema](rdoc-ref:GraphQL::Schema), then it can validate [GraphQL::Language::Nodes::Document](rdoc-ref:GraphQL::Language::Nodes::Document) nodes based on that schema.
     #
-    # By default, it's used by {GraphQL::Query}
+    # By default, it's used by [GraphQL::Query](rdoc-ref:GraphQL::Query)
     #
-    # @example Validate a query
-    #   validator = GraphQL::StaticValidation::Validator.new(schema: MySchema)
-    #   query = GraphQL::Query.new(MySchema, query_string)
-    #   errors = validator.validate(query)[:errors]
+    # **Examples**
     #
+    # **Example: Validate a query**
+    #
+    # ```ruby
+    # validator = GraphQL::StaticValidation::Validator.new(schema: MySchema)
+    # query = GraphQL::Query.new(MySchema, query_string)
+    # errors = validator.validate(query)[:errors]
+    # ```
     class Validator
-      # @param schema [GraphQL::Schema]
-      # @param rules [Array<#validate(context)>] a list of rules to use when validating
+      # **Parameters**
+      #
+      # - `schema` (`GraphQL::Schema`)
+      # - `rules` (`Array<#validate(context)>`) — a list of rules to use when validating
+      #
+      # :call-seq:
+      #   initialize(GraphQL::Schema schema:, Array[#validate(context)] rules:)
       def initialize(schema:, rules: GraphQL::StaticValidation::ALL_RULES)
         @schema = schema
         @rules = rules
       end
 
       # Validate `query` against the schema. Returns an array of message hashes.
-      # @param query [GraphQL::Query]
-      # @param validate [Boolean]
-      # @param timeout [Float] Number of seconds to wait before aborting validation. Any positive number may be used, including Floats to specify fractional seconds.
-      # @param max_errors [Integer] Maximum number of errors before aborting validation. Any positive number will limit the number of errors. Defaults to nil for no limit.
-      # @return [Array<Hash>]
+      #
+      # **Parameters**
+      #
+      # - `query` (`GraphQL::Query`)
+      # - `validate` (`Boolean`)
+      # - `timeout` (`Float`) — Number of seconds to wait before aborting validation. Any positive number may be used, including Floats to specify fractional seconds.
+      # - `max_errors` (`Integer`) — Maximum number of errors before aborting validation. Any positive number will limit the number of errors. Defaults to nil for no limit.
+      #
+      # **Returns**
+      #
+      # - `Array<Hash>`
+      #
+      # :call-seq:
+      #   validate(GraphQL::Query query, bool validate:, Float timeout:, Integer max_errors:) -> Array[Hash]
       def validate(query, validate: true, timeout: nil, max_errors: nil)
-        errors = nil
+        errors = nil #: untyped
         query.current_trace.begin_validate(query, validate)
         query.current_trace.validate(validate: validate, query: query) do
           begin_t = Time.now
@@ -70,8 +89,14 @@ module GraphQL
       end
 
       # Invoked when static validation times out.
-      # @param query [GraphQL::Query]
-      # @param context [GraphQL::StaticValidation::ValidationContext]
+      #
+      # **Parameters**
+      #
+      # - `query` (`GraphQL::Query`)
+      # - `context` (`GraphQL::StaticValidation::ValidationContext`)
+      #
+      # :call-seq:
+      #   handle_timeout(GraphQL::Query query, GraphQL::StaticValidation::ValidationContext context)
       def handle_timeout(query, context)
         context.errors << GraphQL::StaticValidation::ValidationTimeoutError.new(
           "Timeout on validation of query"

data/lib/graphql/static_validation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/static_validation/error"
 require "graphql/static_validation/definition_dependencies"
 require "graphql/static_validation/validator"

data/lib/graphql/string_encoding_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class StringEncodingError < GraphQL::RuntimeTypeError
     attr_reader :string, :field, :path