graphql 2.5.2 → 2.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cff992b51cd3efae382a362bc5708e8dce5060efb48cf1944560262a59276283
-  data.tar.gz: 206fd93c0504f9072f8af62a18557a9e0380664b1f8836acd38426ee44e9eaf7
+  metadata.gz: d2e4ec1acc9810683bb2628dc5403c74d729742612655f1be275267a89b107b3
+  data.tar.gz: fb092108f803095aea29b325859fc810feaa8e5fdb6c873c431f9824428fbc15
 SHA512:
-  metadata.gz: 293369e23e4baee72a07481b6a6015be003e2557469ab3b30e1ee82d79bfaf6004218a5fe0a85033de8e92b3ae475508bf445e5906ec2a81c4df53c2b25add49
-  data.tar.gz: fafe652c92d2655ad39a16fb61252b33b27eee4e10476a5cc40ab7fd3c1e81a56f9e67b81f6a9ba1da67ba76c7112e756973a236287c634bae9cf66fb7ed3e3e
+  metadata.gz: 603e3da13be680884399546074dae65f44635382e13311758e237f7973bbdd96f4a1a46f6b17476af77d88177f5e82f3c76b227633e2e15a9c909365a818f97e
+  data.tar.gz: d631c5a9e1c91fb815d98e1981641405c344b589c6e823ae5609b25fd819a2d5dc9032f366c94a3da69c56a48aa7d8e9ee082cbfa217807e6cbf313d16cbd598

data/lib/graphql/analysis/query_complexity.rb

@@ -13,7 +13,32 @@ module GraphQL
 
       # Override this method to use the complexity result
       def result
-        max_possible_complexity
+        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
+            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-docs/#{GraphQL::VERSION}/Schema.html#complexity_cost_cacluation_mode-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
+        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:
@@ -44,6 +69,10 @@ module GraphQL
         def own_complexity(child_complexity)
           @field_definition.calculate_complexity(query: @query, nodes: @nodes, child_complexity: child_complexity)
         end
+
+        def composite?
+          !empty?
+        end
       end
 
       def on_enter_field(node, parent, visitor)
@@ -77,16 +106,17 @@ module GraphQL
       private
 
       # @return [Integer]
-      def max_possible_complexity
+      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])
+          total + merged_max_complexity_for_scopes(query, [scopes_stack.first], mode)
         end
       end
 
       # @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)
+      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|
@@ -115,14 +145,20 @@ module GraphQL
           end
 
           # Find the maximum complexity for the scope type among possible lexical branches.
-          complexity = merged_max_complexity(query, all_inner_selections)
+          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
@@ -145,6 +181,50 @@ module GraphQL
           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
@@ -167,7 +247,7 @@ module GraphQL
           end
 
           if composite_scopes
-            child_complexity = merged_max_complexity_for_scopes(query, 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.

data/lib/graphql/current.rb

@@ -22,7 +22,7 @@ module GraphQL
   #   ]
   #
   module Current
-    # @return [String, nil] Comma-joined operation names for the currently-running {Multiplex}. `nil` if all operations are anonymous.
+    # @return [String, nil] Comma-joined operation names for the currently-running {Execution::Multiplex}. `nil` if all operations are anonymous.
     def self.operation_name
       if (m = Fiber[:__graphql_current_multiplex])
         m.context[:__graphql_current_operation_name] ||= begin

data/lib/graphql/dig.rb

@@ -5,7 +5,8 @@ module GraphQL
     # 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
+    # @param own_key [String, Symbol] A key to retrieve
+    # @param rest_keys [Array<[String, Symbol>] Retrieves the value object corresponding to the each key objects repeatedly
     # @return [Object]
     def dig(own_key, *rest_keys)
       val = self[own_key]

data/lib/graphql/execution/interpreter/runtime.rb

@@ -475,9 +475,10 @@ module GraphQL
             if is_non_null
               set_result(selection_result, result_name, nil, false, is_non_null) do
                 # When this comes from a list item, use the parent object:
-                parent_type = selection_result.is_a?(GraphQLResultArray) ? selection_result.graphql_parent.graphql_result_type : selection_result.graphql_result_type
+                is_from_array = selection_result.is_a?(GraphQLResultArray)
+                parent_type = is_from_array ? selection_result.graphql_parent.graphql_result_type : selection_result.graphql_result_type
                 # This block is called if `result_name` is not dead. (Maybe a previous invalid nil caused it be marked dead.)
-                err = parent_type::InvalidNullError.new(parent_type, field, ast_node)
+                err = parent_type::InvalidNullError.new(parent_type, field, ast_node, is_from_array: is_from_array)
                 schema.type_error(err, context)
               end
             else

data/lib/graphql/execution/multiplex.rb

@@ -36,6 +36,11 @@ module GraphQL
         @tracers = schema.tracers + (context[:tracers] || [])
         @max_complexity = max_complexity
         @current_trace = context[:trace] ||= schema.new_trace(multiplex: self)
+        @logger = nil
+      end
+
+      def logger
+        @logger ||= @schema.logger_for(context)
       end
     end
   end

data/lib/graphql/invalid_null_error.rb

@@ -12,11 +12,24 @@ module GraphQL
     # @return [GraphQL::Language::Nodes::Field] the field where the error occurred
     attr_reader :ast_node
 
-    def initialize(parent_type, field, ast_node)
+    # @return [Boolean] indicates an array result caused the error
+    attr_reader :is_from_array
+
+    def initialize(parent_type, field, ast_node, is_from_array: false)
       @parent_type = parent_type
       @field = field
       @ast_node = ast_node
-      super("Cannot return null for non-nullable field #{@parent_type.graphql_name}.#{@field.graphql_name}")
+      @is_from_array = is_from_array
+
+      # For List elements, identify the non-null error is for an
+      # element and the required element type so it's not ambiguous
+      # whether it was caused by a null instead of the list or a
+      # null element.
+      if @is_from_array
+        super("Cannot return null for non-nullable element of type '#{@field.type.of_type.of_type.to_type_signature}' for #{@parent_type.graphql_name}.#{@field.graphql_name}")
+      else
+        super("Cannot return null for non-nullable field #{@parent_type.graphql_name}.#{@field.graphql_name}")
+      end
     end
 
     class << self

data/lib/graphql/query/context.rb

@@ -59,6 +59,7 @@ module GraphQL
         @scoped_context = ScopedContext.new(self)
       end
 
+      # Modify this hash to return extensions to client.
       # @return [Hash] A hash that will be added verbatim to the result hash, as `"extensions" => { ... }`
       def response_extensions
         namespace(:__query_result_extensions__)

data/lib/graphql/query.rb

@@ -50,7 +50,7 @@ module GraphQL
     # @return [GraphQL::StaticValidation::Validator] if present, the query will validate with these rules.
     attr_reader :static_validator
 
-    # @param new_validate [GraphQL::StaticValidation::Validator] if present, the query will validate with these rules. This can't be reasssigned after validation.
+    # @param new_validator [GraphQL::StaticValidation::Validator] if present, the query will validate with these rules. This can't be reasssigned after validation.
     def static_validator=(new_validator)
       if defined?(@validation_pipeline) && @validation_pipeline && @validation_pipeline.has_validated?
         raise ArgumentError, "Can't reassign Query#static_validator= after validation has run, remove this assignment."
@@ -172,13 +172,7 @@ module GraphQL
       @result_values = nil
       @executed = false
 
-      @logger = if context && context[:logger] == false
-        Logger.new(IO::NULL)
-      elsif context && (l = context[:logger])
-        l
-      else
-        schema.default_logger
-      end
+      @logger = schema.logger_for(context)
     end
 
     # If a document was provided to `GraphQL::Schema#execute` instead of the raw query string, we will need to get it from the document
@@ -288,7 +282,7 @@ module GraphQL
     # @param ast_node [GraphQL::Language::Nodes::AbstractNode]
     # @param definition [GraphQL::Schema::Field]
     # @param parent_object [GraphQL::Schema::Object]
-    # @return Hash{Symbol => Object}
+    # @return [Hash{Symbol => Object}]
     def arguments_for(ast_node, definition, parent_object: nil)
       arguments_cache.fetch(ast_node, definition, parent_object)
     end

data/lib/graphql/schema/always_visible.rb

@@ -3,6 +3,7 @@ module GraphQL
   class Schema
     module AlwaysVisible
       def self.use(schema, **opts)
+        schema.use(GraphQL::Schema::Visibility, profiles: { nil => {} })
         schema.extend(self)
       end
 

data/lib/graphql/schema/list.rb

@@ -4,7 +4,7 @@ module GraphQL
   class Schema
     # Represents a list type in the schema.
     # Wraps a {Schema::Member} as a list type.
-    # @see {Schema::Member::TypeSystemHelpers#to_list_type}
+    # @see Schema::Member::TypeSystemHelpers#to_list_type Create a list type from another GraphQL type
     class List < GraphQL::Schema::Wrapper
       include Schema::Member::ValidatesInput
 

data/lib/graphql/schema/member/has_dataloader.rb

@@ -3,6 +3,8 @@
 module GraphQL
   class Schema
     class Member
+      # @api public
+      # Shared methods for working with {Dataloader} inside GraphQL runtime objects.
       module HasDataloader
         # @return [GraphQL::Dataloader] The dataloader for the currently-running query
         def dataloader
@@ -37,7 +39,7 @@ module GraphQL
           source.load(find_by_value)
         end
 
-        # Look up an associated record using a Rails association.
+        # Look up an associated record using a Rails association (via {Dataloader::ActiveRecordAssociationSource})
         # @param association_name [Symbol] A `belongs_to` or `has_one` association. (If a `has_many` association is named here, it will be selected without pagination.)
         # @param record [ActiveRecord::Base] The object that the association belongs to.
         # @param scope [ActiveRecord::Relation] A scope to look up the associated record in
@@ -45,7 +47,7 @@ module GraphQL
         # @example Looking up a belongs_to on the current object
         #    dataload_association(:parent) # Equivalent to `object.parent`, but dataloaded
         # @example Looking up an associated record on some other object
-        #    dataload_association(:post, comment) # Equivalent to `comment.post`, but dataloaded
+        #    dataload_association(comment, :post) # Equivalent to `comment.post`, but dataloaded
         def dataload_association(record = object, association_name, scope: nil)
           source = if scope
             dataloader.with(Dataloader::ActiveRecordAssociationSource, association_name, scope)

data/lib/graphql/schema/visibility/profile.rb

@@ -281,9 +281,11 @@ module GraphQL
 
         def non_duplicate_items(definitions, visibility_cache)
           non_dups = []
+          names = Set.new
           definitions.each do |defn|
             if visibility_cache[defn]
-              if (dup_defn = non_dups.find { |d| d.graphql_name == defn.graphql_name })
+              if !names.add?(defn.graphql_name)
+                dup_defn = non_dups.find { |d| d.graphql_name == defn.graphql_name }
                 raise_duplicate_definition(dup_defn, defn)
               end
               non_dups << defn

data/lib/graphql/schema/visibility.rb

@@ -148,23 +148,22 @@ module GraphQL
 
       attr_reader :cached_profiles
 
-      def profile_for(context, visibility_profile = context[:visibility_profile])
+      def profile_for(context)
         if !@profiles.empty?
-          if visibility_profile.nil?
-            if @dynamic
-              if context.is_a?(Query::NullContext)
-                top_level_profile
-              else
-                @schema.visibility_profile_class.new(context: context, schema: @schema)
-              end
-            elsif !@profiles.empty?
-              raise ArgumentError, "#{@schema} expects a visibility profile, but `visibility_profile:` wasn't passed. Provide a `visibility_profile:` value or add `dynamic: true` to your visibility configuration."
-            end
-          elsif !@profiles.include?(visibility_profile)
-            raise ArgumentError, "`#{visibility_profile.inspect}` isn't allowed for `visibility_profile:` (must be one of #{@profiles.keys.map(&:inspect).join(", ")}). Or, add `#{visibility_profile.inspect}` to the list of profiles in the schema definition."
-          else
+          visibility_profile = context[:visibility_profile]
+          if @profiles.include?(visibility_profile)
             profile_ctx = @profiles[visibility_profile]
             @cached_profiles[visibility_profile] ||= @schema.visibility_profile_class.new(name: visibility_profile, context: profile_ctx, schema: @schema)
+          elsif @dynamic
+            if context.is_a?(Query::NullContext)
+              top_level_profile
+            else
+              @schema.visibility_profile_class.new(context: context, schema: @schema)
+            end
+          elsif !context.key?(:visibility_profile)
+            raise ArgumentError, "#{@schema} expects a visibility profile, but `visibility_profile:` wasn't passed. Provide a `visibility_profile:` value or add `dynamic: true` to your visibility configuration."
+          else
+            raise ArgumentError, "`#{visibility_profile.inspect}` isn't allowed for `visibility_profile:` (must be one of #{@profiles.keys.map(&:inspect).join(", ")}). Or, add `#{visibility_profile.inspect}` to the list of profiles in the schema definition."
           end
         elsif context.is_a?(Query::NullContext)
           top_level_profile

data/lib/graphql/schema.rb

@@ -60,7 +60,7 @@ module GraphQL
   # Any undiscoverable types may be provided with the `types` configuration.
   #
   # Schemas can restrict large incoming queries with `max_depth` and `max_complexity` configurations.
-  # (These configurations can be overridden by specific calls to {Schema#execute})
+  # (These configurations can be overridden by specific calls to {Schema.execute})
   #
   # @example defining a schema
   #   class MySchema < GraphQL::Schema
@@ -249,7 +249,7 @@ module GraphQL
 
 
       # Returns the JSON response of {Introspection::INTROSPECTION_QUERY}.
-      # @see {#as_json}
+      # @see #as_json Return a Hash representation of the schema
       # @return [String]
       def to_json(**args)
         JSON.pretty_generate(as_json(**args))
@@ -257,8 +257,6 @@ module GraphQL
 
       # Return the Hash response of {Introspection::INTROSPECTION_QUERY}.
       # @param context [Hash]
-      # @param only [<#call(member, ctx)>]
-      # @param except [<#call(member, ctx)>]
       # @param include_deprecated_args [Boolean] If true, deprecated arguments will be included in the JSON response
       # @param include_schema_description [Boolean] If true, the schema's description will be queried and included in the response
       # @param include_is_repeatable [Boolean] If true, `isRepeatable: true|false` will be included with the schema's directives
@@ -1066,6 +1064,18 @@ module GraphQL
         end
       end
 
+      # @param context [GraphQL::Query::Context, nil]
+      # @return [Logger] A logger to use for this context configuration, falling back to {.default_logger}
+      def logger_for(context)
+        if context && context[:logger] == false
+          Logger.new(IO::NULL)
+        elsif context && (l = context[:logger])
+          l
+        else
+          default_logger
+        end
+      end
+
       # @param new_context_class [Class<GraphQL::Query::Context>] A subclass to use when executing queries
       def context_class(new_context_class = nil)
         if new_context_class
@@ -1165,7 +1175,7 @@ module GraphQL
       # GraphQL-Ruby calls this method during execution when it needs the application to determine the type to use for an object.
       #
       # Usually, this object was returned from a field whose return type is an {GraphQL::Schema::Interface} or a {GraphQL::Schema::Union}.
-      # But this method is called in other cases, too -- for example, when {GraphQL::Schema::Argument.loads} cases an object to be directly loaded from the database.
+      # But this method is called in other cases, too -- for example, when {GraphQL::Schema::Argument#loads} cases an object to be directly loaded from the database.
       #
       # @example Returning a GraphQL type based on the object's class name
       #   class MySchema < GraphQL::Schema
@@ -1220,7 +1230,7 @@ module GraphQL
 
       # Return a stable ID string for `object` so that it can be refetched later, using {.object_from_id}.
       #
-      # {GlobalID}(https://github.com/rails/globalid) and {SQIDs}(https://sqids.org/ruby) can both be used to create IDs.
+      # [GlobalID](https://github.com/rails/globalid) and [SQIDs](https://sqids.org/ruby) can both be used to create IDs.
       #
       # @example Using Rails's GlobalID to generate IDs
       #   def self.id_from_object(application_object, graphql_type, context)
@@ -1297,13 +1307,13 @@ module GraphQL
       # @return [void]
       # @raise [GraphQL::ExecutionError] to return this error to the client
       # @raise [GraphQL::Error] to crash the query and raise a developer-facing error
-      def type_error(type_error, ctx)
+      def type_error(type_error, context)
         case type_error
         when GraphQL::InvalidNullError
           execution_error = GraphQL::ExecutionError.new(type_error.message, ast_node: type_error.ast_node)
-          execution_error.path = ctx[:current_path]
+          execution_error.path = context[:current_path]
 
-          ctx.errors << execution_error
+          context.errors << execution_error
         when GraphQL::UnresolvedTypeError, GraphQL::StringEncodingError, GraphQL::IntegerEncodingError
           raise type_error
         when GraphQL::IntegerDecodingError
@@ -1311,7 +1321,7 @@ module GraphQL
         end
       end
 
-      # A function to call when {#execute} receives an invalid query string
+      # A function to call when {.execute} receives an invalid query string
       #
       # The default is to add the error to `context.errors`
       # @param parse_err [GraphQL::ParseError] The error encountered during parsing
@@ -1567,7 +1577,8 @@ module GraphQL
       # @see {Query#initialize} for query keyword arguments
       # @see {Execution::Multiplex#run_all} for multiplex keyword arguments
       # @param queries [Array<Hash>] Keyword arguments for each query
-      # @param context [Hash] Multiplex-level context
+      # @option kwargs [Hash] :context ({}) Multiplex-level context
+      # @option kwargs [nil, Integer] :max_complexity (nil)
       # @return [Array<GraphQL::Query::Result>] One result for each query in the input
       def multiplex(queries, **kwargs)
         GraphQL::Execution::Interpreter.run_all(self, queries, **kwargs)
@@ -1632,7 +1643,7 @@ module GraphQL
         end
       end
 
-      # @return [Symbol, nil] The method name to lazily resolve `obj`, or nil if `obj`'s class wasn't registered with {#lazy_resolve}.
+      # @return [Symbol, nil] The method name to lazily resolve `obj`, or nil if `obj`'s class wasn't registered with {.lazy_resolve}.
       def lazy_method_name(obj)
         lazy_methods.get(obj)
       end
@@ -1670,6 +1681,158 @@ module GraphQL
         end
       end
 
+
+      # This setting controls how GraphQL-Ruby handles empty selections on Union types.
+      #
+      # To opt into future, spec-compliant behavior where these selections are rejected, set this to `false`.
+      #
+      # If you need to support previous, non-spec behavior which allowed selecting union fields
+      # but *not* selecting any fields on that union, set this to `true` to continue allowing that behavior.
+      #
+      # If this is `true`, then {.legacy_invalid_empty_selections_on_union} will be called with {Query} objects
+      # with that kind of selections. You must implement that method
+      # @param new_value [Boolean]
+      # @return [true, false, nil]
+      def allow_legacy_invalid_empty_selections_on_union(new_value = NOT_CONFIGURED)
+        if NOT_CONFIGURED.equal?(new_value)
+          @allow_legacy_invalid_empty_selections_on_union
+        else
+          @allow_legacy_invalid_empty_selections_on_union = new_value
+        end
+      end
+
+      # This method is called during validation when a previously-allowed, but non-spec
+      # query is encountered where a union field has no child selections on it.
+      #
+      # You should implement this method to log the violation so that you can contact clients
+      # and notify them about changing their queries. Then return a suitable value to
+      # tell GraphQL-Ruby how to continue.
+      # @param query [GraphQL::Query]
+      # @return [:return_validation_error] Let GraphQL-Ruby return the (new) normal validation error for this query
+      # @return [String] A validation error to return for this query
+      # @return [nil] Don't send the client an error, continue the legacy behavior (allow this query to execute)
+      def legacy_invalid_empty_selections_on_union(query)
+        raise "Implement `def self.legacy_invalid_empty_selections_on_union(query)` to handle this scenario"
+      end
+
+      # This setting controls how GraphQL-Ruby handles overlapping selections on scalar types when the types
+      # don't match.
+      #
+      # When set to `false`, GraphQL-Ruby will reject those queries with a validation error (as per the GraphQL spec).
+      #
+      # When set to `true`, GraphQL-Ruby will call {.legacy_invalid_return_type_conflicts} when the scenario is encountered.
+      #
+      # @param new_value [Boolean] `true` permits the legacy behavior, `false` rejects it.
+      # @return [true, false, nil]
+      def allow_legacy_invalid_return_type_conflicts(new_value = NOT_CONFIGURED)
+        if NOT_CONFIGURED.equal?(new_value)
+          @allow_legacy_invalid_return_type_conflicts
+        else
+          @allow_legacy_invalid_return_type_conflicts = new_value
+        end
+      end
+
+      # This method is called when the query contains fields which don't contain matching scalar types.
+      # This was previously allowed by GraphQL-Ruby but it's a violation of the GraphQL spec.
+      #
+      # You should implement this method to log the violation so that you observe usage of these fields.
+      # Fixing this scenario might mean adding new fields, and telling clients to use those fields.
+      # (Changing the field return type would be a breaking change, but if it works for your client use cases,
+      # that might work, too.)
+      #
+      # @param query [GraphQL::Query]
+      # @param type1 [Module] A GraphQL type definition
+      # @param type2 [Module] A GraphQL type definition
+      # @param node1 [GraphQL::Language::Nodes::Field] This node is recognized as conflicting. You might call `.line` and `.col` for custom error reporting.
+      # @param node2 [GraphQL::Language::Nodes::Field] The other node recognized as conflicting.
+      # @return [:return_validation_error] Let GraphQL-Ruby return the (new) normal validation error for this query
+      # @return [String] A validation error to return for this query
+      # @return [nil] Don't send the client an error, continue the legacy behavior (allow this query to execute)
+      def legacy_invalid_return_type_conflicts(query, type1, type2, node1, node2)
+        raise "Implement #{self}.legacy_invalid_return_type_conflicts to handle this invalid selection"
+      end
+
+      # The legacy complexity implementation included several bugs:
+      #
+      # - In some cases, it used the lexically _last_ field to determine a cost, instead of calculating the maximum among selections
+      # - In some cases, it called field complexity hooks repeatedly (when it should have only called them once)
+      #
+      # The future implementation may produce higher total complexity scores, so it's not active by default yet. You can opt into
+      # the future default behavior by configuring `:future` here. Or, you can choose a mode for each query with {.complexity_cost_calculation_mode_for}.
+      #
+      # The legacy mode is currently maintained alongside the future one, but it will be removed in a future GraphQL-Ruby version.
+      #
+      # If you choose `:compare`, you must also implement {.legacy_complexity_cost_calculation_mismatch} to handle the input somehow.
+      #
+      # @example Opting into the future calculation mode
+      #   complexity_cost_calculation_mode(:future)
+      #
+      # @example Choosing the legacy mode (which will work until that mode is removed...)
+      #   complexity_cost_calculation_mode(:legacy)
+      #
+      # @example Run both modes for every query, call {.legacy_complexity_cost_calculation_mismatch} when they don't match:
+      #   complexity_cost_calculation_mode(:compare)
+      def complexity_cost_calculation_mode(new_mode = NOT_CONFIGURED)
+        if NOT_CONFIGURED.equal?(new_mode)
+          @complexity_cost_calculation_mode
+        else
+          @complexity_cost_calculation_mode = new_mode
+        end
+      end
+
+      # Implement this method to produce a per-query complexity cost calculation mode. (Technically, it's per-multiplex.)
+      #
+      # This is a way to check the compatibility of queries coming to your API without adding overhead of running `:compare`
+      # for every query. You could sample traffic, turn it off/on with feature flags, or anything else.
+      #
+      # @example Sampling traffic
+      #   def self.complexity_cost_calculation_mode_for(_context)
+      #     if rand < 0.1 # 10% of the time
+      #       :compare
+      #     else
+      #       :legacy
+      #     end
+      #   end
+      #
+      # @example Using a feature flag to manage future mode
+      #   def complexity_cost_calculation_mode_for(context)
+      #     current_user = context[:current_user]
+      #     if Flipper.enabled?(:future_complexity_cost, current_user)
+      #       :future
+      #     elsif rand < 0.5 # 50%
+      #       :compare
+      #     else
+      #       :legacy
+      #     end
+      #   end
+      #
+      # @param multiplex_context [Hash] The context for the currently-running {Execution::Multiplex} (which contains one or more queries)
+      # @return [:future] Use the new calculation algorithm -- may be higher than `:legacy`
+      # @return [:legacy] Use the legacy calculation algorithm, warts and all
+      # @return [:compare] Run both algorithms and call {.legacy_complexity_cost_calculation_mismatch} if they don't match
+      def complexity_cost_calculation_mode_for(multiplex_context)
+        complexity_cost_calculation_mode
+      end
+
+      # Implement this method in your schema to handle mismatches when `:compare` is used.
+      #
+      # @example Logging the mismatch
+      #   def self.legacy_cost_calculation_mismatch(multiplex, future_cost, legacy_cost)
+      #     client_id = multiplex.context[:api_client].id
+      #     operation_names = multiplex.queries.map { |q| q.selected_operation_name || "anonymous" }.join(", ")
+      #     Stats.increment(:complexity_mismatch, tags: { client: client_id, ops: operation_names })
+      #     legacy_cost
+      #   end
+      # @see Query::Context#add_error Adding an error to the response to notify the client
+      # @see Query::Context#response_extensions Adding key-value pairs to the response `"extensions" => { ... }`
+      # @param multiplex [GraphQL::Execution::Multiplex]
+      # @param future_complexity_cost [Integer]
+      # @param legacy_complexity_cost [Integer]
+      # @return [Integer] the cost to use for this query (probably one of `future_complexity_cost` or `legacy_complexity_cost`)
+      def legacy_complexity_cost_calculation_mismatch(multiplex, future_complexity_cost, legacy_complexity_cost)
+        raise "Implement #{self}.legacy_complexity_cost(multiplex, future_complexity_cost, legacy_complexity_cost) to handle this mismatch (#{future_complexity_cost} vs. #{legacy_complexity_cost}) and return a value to use"
+      end
+
       private
 
       def add_trace_options_for(mode, new_options)

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

@@ -25,22 +25,56 @@ module GraphQL
       def validate_field_selections(ast_node, resolved_type)
         msg = if resolved_type.nil?
           nil
-        elsif !ast_node.selections.empty? && resolved_type.kind.leaf?
-          selection_strs = ast_node.selections.map do |n|
-            case n
-            when GraphQL::Language::Nodes::InlineFragment
-              "\"... on #{n.type.name} { ... }\""
-            when GraphQL::Language::Nodes::Field
-              "\"#{n.name}\""
-            when GraphQL::Language::Nodes::FragmentSpread
-              "\"#{n.name}\""
+        elsif resolved_type.kind.leaf?
+          if !ast_node.selections.empty?
+            selection_strs = ast_node.selections.map do |n|
+              case n
+              when GraphQL::Language::Nodes::InlineFragment
+                "\"... on #{n.type.name} { ... }\""
+              when GraphQL::Language::Nodes::Field
+                "\"#{n.name}\""
+              when GraphQL::Language::Nodes::FragmentSpread
+                "\"#{n.name}\""
+              else
+                raise "Invariant: unexpected selection node: #{n}"
+              end
+            end
+            "Selections can't be made on #{resolved_type.kind.name.sub("_", " ").downcase}s (%{node_name} returns #{resolved_type.graphql_name} but has selections [#{selection_strs.join(", ")}])"
+          else
+            nil
+          end
+        elsif ast_node.selections.empty?
+          return_validation_error = true
+          legacy_invalid_empty_selection_result = nil
+          if !resolved_type.kind.fields?
+            case @schema.allow_legacy_invalid_empty_selections_on_union
+            when true
+              legacy_invalid_empty_selection_result = @schema.legacy_invalid_empty_selections_on_union(@context.query)
+              case legacy_invalid_empty_selection_result
+              when :return_validation_error
+                # keep `return_validation_error = true`
+              when String
+                return_validation_error = false
+                # the string is returned below
+              when nil
+                # No error:
+                return_validation_error = false
+                legacy_invalid_empty_selection_result = nil
+              else
+                raise GraphQL::InvariantError, "Unexpected return value from legacy_invalid_empty_selections_on_union, must be `:return_validation_error`, String, or nil (got: #{legacy_invalid_empty_selection_result.inspect})"
+              end
+            when false
+              # pass -- error below
             else
-              raise "Invariant: unexpected selection node: #{n}"
+              return_validation_error = false
+              @context.query.logger.warn("Unions require selections but #{ast_node.alias || ast_node.name} (#{resolved_type.graphql_name}) doesn't have any. This will fail with a validation error on a future GraphQL-Ruby version. More info: https://graphql-ruby.org/api-doc/#{GraphQL::VERSION}/GraphQL/Schema.html#allow_legacy_invalid_empty_selections_on_union-class_method")
             end
           end
-          "Selections can't be made on #{resolved_type.kind.name.sub("_", " ").downcase}s (%{node_name} returns #{resolved_type.graphql_name} but has selections [#{selection_strs.join(", ")}])"
-        elsif resolved_type.kind.fields? && ast_node.selections.empty?
-          "Field must have selections (%{node_name} returns #{resolved_type.graphql_name} but has no selections. Did you mean '#{ast_node.name} { ... }'?)"
+          if return_validation_error
+            "Field must have selections (%{node_name} returns #{resolved_type.graphql_name} but has no selections. Did you mean '#{ast_node.name} { ... }'?)"
+          else
+            legacy_invalid_empty_selection_result
+          end
         else
           nil
         end

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

@@ -33,26 +33,19 @@ module GraphQL
 
       private
 
-      def field_conflicts
-        @field_conflicts ||= Hash.new do |errors, field|
-          errors[field] = GraphQL::StaticValidation::FieldsWillMergeError.new(kind: :field, field_name: field)
-        end
-      end
-
-      def arg_conflicts
-        @arg_conflicts ||= Hash.new do |errors, field|
-          errors[field] = GraphQL::StaticValidation::FieldsWillMergeError.new(kind: :argument, field_name: field)
+      def conflicts
+        @conflicts ||= Hash.new do |h, error_type|
+          h[error_type] = Hash.new do |h2, field_name|
+            h2[field_name] = GraphQL::StaticValidation::FieldsWillMergeError.new(kind: error_type, field_name: field_name)
+          end
         end
       end
 
       def setting_errors
-        @field_conflicts = nil
-        @arg_conflicts = nil
-
+        @conflicts = nil
         yield
         # don't initialize these if they weren't initialized in the block:
-        @field_conflicts && @field_conflicts.each_value { |error| add_error(error) }
-        @arg_conflicts && @arg_conflicts.each_value { |error| add_error(error) }
+        @conflicts&.each_value { |error_type| error_type.each_value { |error| add_error(error) } }
       end
 
       def conflicts_within_selection_set(node, parent_type)
@@ -222,7 +215,7 @@ module GraphQL
 
         if !are_mutually_exclusive
           if node1.name != node2.name
-            conflict = field_conflicts[response_key]
+            conflict = conflicts[:field][response_key]
 
             conflict.add_conflict(node1, node1.name)
             conflict.add_conflict(node2, node2.name)
@@ -231,7 +224,7 @@ module GraphQL
           end
 
           if !same_arguments?(node1, node2)
-            conflict = arg_conflicts[response_key]
+            conflict = conflicts[:argument][response_key]
 
             conflict.add_conflict(node1, GraphQL::Language.serialize(serialize_field_args(node1)))
             conflict.add_conflict(node2, GraphQL::Language.serialize(serialize_field_args(node2)))
@@ -240,6 +233,49 @@ module GraphQL
           end
         end
 
+        if !conflicts[:field].key?(response_key) &&
+            (t1 = field1.definition&.type) &&
+            (t2 = field2.definition&.type) &&
+            return_types_conflict?(t1, t2)
+
+          return_error = nil
+          message_override = nil
+          case @schema.allow_legacy_invalid_return_type_conflicts
+          when false
+            return_error = true
+          when true
+            legacy_handling = @schema.legacy_invalid_return_type_conflicts(@context.query, t1, t2, node1, node2)
+            case legacy_handling
+            when nil
+              return_error = false
+            when :return_validation_error
+              return_error = true
+            when String
+              return_error = true
+              message_override = legacy_handling
+            else
+              raise GraphQL::Error, "#{@schema}.legacy_invalid_scalar_conflicts returned unexpected value: #{legacy_handling.inspect}. Expected `nil`, String, or `:return_validation_error`."
+            end
+          else
+            return_error = false
+            @context.query.logger.warn <<~WARN
+              GraphQL-Ruby encountered mismatched types in this query: `#{t1.to_type_signature}` (at #{node1.line}:#{node1.col}) vs. `#{t2.to_type_signature}` (at #{node2.line}:#{node2.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_return_type_conflicts-class_method
+            WARN
+          end
+
+          if return_error
+            conflict = conflicts[:return_type][response_key]
+            if message_override
+              conflict.message = message_override
+            end
+            conflict.add_conflict(node1, "`#{t1.to_type_signature}`")
+            conflict.add_conflict(node2, "`#{t2.to_type_signature}`")
+            @conflict_count += 1
+          end
+        end
+
         find_conflicts_between_sub_selection_sets(
           field1,
           field2,
@@ -247,6 +283,32 @@ module GraphQL
         )
       end
 
+      def return_types_conflict?(type1, type2)
+        if type1.list?
+          if type2.list?
+            return_types_conflict?(type1.of_type, type2.of_type)
+          else
+            true
+          end
+        elsif type2.list?
+          true
+        elsif type1.non_null?
+          if type2.non_null?
+            return_types_conflict?(type1.of_type, type2.of_type)
+          else
+            true
+          end
+        elsif type2.non_null?
+          true
+        elsif type1.kind.leaf? && type2.kind.leaf?
+          type1 != type2
+        else
+          # One or more of these are composite types,
+          # their selections will be validated later on.
+          false
+        end
+      end
+
       def find_conflicts_between_sub_selection_sets(field1, field2, mutually_exclusive:)
         return if field1.definition.nil? ||
           field2.definition.nil? ||

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

@@ -14,9 +14,11 @@ module GraphQL
       end
 
       def message
-        "Field '#{field_name}' has #{kind == :argument ? 'an' : 'a'} #{kind} conflict: #{conflicts}?"
+        @message || "Field '#{field_name}' has #{kind == :argument ? 'an' : 'a'} #{kind} conflict: #{conflicts}?"
       end
 
+      attr_writer :message
+
       def path
         []
       end
@@ -26,7 +28,13 @@ module GraphQL
       end
 
       def add_conflict(node, conflict_str)
-        return if nodes.include?(node)
+        # Can't use `.include?` here because AST nodes implement `#==`
+        # based on string value, not including location. But sometimes,
+        # identical nodes conflict because of their differing return types.
+        if nodes.any? { |n| n == node && n.line == node.line && n.col == node.col }
+          # already have an error for this node
+          return
+        end
 
         @nodes << node
         @conflicts << conflict_str

data/lib/graphql/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module GraphQL
-  VERSION = "2.5.2"
+  VERSION = "2.5.3"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: graphql
 version: !ruby/object:Gem::Version
-  version: 2.5.2
+  version: 2.5.3
 platform: ruby
 authors:
 - Robert Mosolgo
 bindir: bin
 cert_chain: []
-date: 2025-04-08 00:00:00.000000000 Z
+date: 2025-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64