graphql 2.4.3 → 2.5.3

data/lib/graphql/schema.rb

@@ -7,7 +7,6 @@ require "graphql/schema/find_inherited_value"
 require "graphql/schema/finder"
 require "graphql/schema/introspection_system"
 require "graphql/schema/late_bound_type"
-require "graphql/schema/null_mask"
 require "graphql/schema/timeout"
 require "graphql/schema/type_expression"
 require "graphql/schema/unique_within_type"
@@ -61,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
@@ -73,6 +72,9 @@ module GraphQL
   class Schema
     extend GraphQL::Schema::Member::HasAstNode
     extend GraphQL::Schema::FindInheritedValue
+    extend Autoload
+
+    autoload :BUILT_IN_TYPES, "graphql/schema/built_in_types"
 
     class DuplicateNamesError < GraphQL::Error
       attr_reader :duplicated_name
@@ -109,7 +111,7 @@ module GraphQL
       # @param parser [Object] An object for handling definition string parsing (must respond to `parse`)
       # @param using [Hash] Plugins to attach to the created schema with `use(key, value)`
       # @return [Class] the schema described by `document`
-      def from_definition(definition_or_path, default_resolve: nil, parser: GraphQL.default_parser, using: {})
+      def from_definition(definition_or_path, default_resolve: nil, parser: GraphQL.default_parser, using: {}, base_types: {})
         # If the file ends in `.graphql` or `.graphqls`, treat it like a filepath
         if definition_or_path.end_with?(".graphql") || definition_or_path.end_with?(".graphqls")
           GraphQL::Schema::BuildFromDefinition.from_definition_path(
@@ -118,6 +120,7 @@ module GraphQL
             default_resolve: default_resolve,
             parser: parser,
             using: using,
+            base_types: base_types,
           )
         else
           GraphQL::Schema::BuildFromDefinition.from_definition(
@@ -126,6 +129,7 @@ module GraphQL
             default_resolve: default_resolve,
             parser: parser,
             using: using,
+            base_types: base_types,
           )
         end
       end
@@ -164,9 +168,6 @@ module GraphQL
           mods.each { |mod| new_class.include(mod) }
           new_class.include(DefaultTraceClass)
           trace_mode(:default, new_class)
-          backtrace_class = Class.new(new_class)
-          backtrace_class.include(GraphQL::Backtrace::Trace)
-          trace_mode(:default_backtrace, backtrace_class)
         end
         trace_class_for(:default, build: true)
       end
@@ -213,11 +214,6 @@ module GraphQL
           const_set(:DefaultTrace, Class.new(base_class) do
             include DefaultTraceClass
           end)
-        when :default_backtrace
-          schema_base_class = trace_class_for(:default, build: true)
-          const_set(:DefaultTraceBacktrace, Class.new(schema_base_class) do
-            include(GraphQL::Backtrace::Trace)
-          end)
         else
           # First, see if the superclass has a custom-defined class for this.
           # Then, if it doesn't, use this class's default trace
@@ -233,7 +229,7 @@ module GraphQL
           add_trace_options_for(mode, default_options)
 
           Class.new(base_class) do
-            mods.any? && include(*mods)
+            !mods.empty? && include(*mods)
           end
         end
       end
@@ -253,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))
@@ -261,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
@@ -321,7 +315,7 @@ module GraphQL
       # @param plugin [#use] A Schema plugin
       # @return void
       def use(plugin, **kwargs)
-        if kwargs.any?
+        if !kwargs.empty?
           plugin.use(self, **kwargs)
         else
           plugin.use(self)
@@ -446,7 +440,12 @@ module GraphQL
             raise GraphQL::Error, "Second definition of `query(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@query_object.inspect}"
           elsif use_visibility_profile?
             if block_given?
-              @query_object = lazy_load_block
+              if visibility.preload?
+                @query_object = lazy_load_block.call
+                self.visibility.query_configured(@query_object)
+              else
+                @query_object = lazy_load_block
+              end
             else
               @query_object = new_query_object
               self.visibility.query_configured(@query_object)
@@ -480,7 +479,12 @@ module GraphQL
             raise GraphQL::Error, "Second definition of `mutation(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@mutation_object.inspect}"
           elsif use_visibility_profile?
             if block_given?
-              @mutation_object = lazy_load_block
+              if visibility.preload?
+                @mutation_object = lazy_load_block.call
+                self.visibility.mutation_configured(@mutation_object)
+              else
+                @mutation_object = lazy_load_block
+              end
             else
               @mutation_object = new_mutation_object
               self.visibility.mutation_configured(@mutation_object)
@@ -514,7 +518,12 @@ module GraphQL
             raise GraphQL::Error, "Second definition of `subscription(...)` (#{dup_defn.inspect}) is invalid, already configured with #{@subscription_object.inspect}"
           elsif use_visibility_profile?
             if block_given?
-              @subscription_object = lazy_load_block
+              if visibility.preload?
+                @subscription_object = lazy_load_block.call
+                visibility.subscription_configured(@subscription_object)
+              else
+                @subscription_object = lazy_load_block
+              end
             else
               @subscription_object = new_subscription_object
               self.visibility.subscription_configured(@subscription_object)
@@ -676,7 +685,7 @@ module GraphQL
           # and generally speaking, we won't inherit any values.
           # So optimize the most common case -- don't create a duplicate Hash.
           inherited_value = find_inherited_value(:references_to, EMPTY_HASH)
-          if inherited_value.any?
+          if !inherited_value.empty?
             inherited_value.merge(own_references_to)
           else
             own_references_to
@@ -812,13 +821,13 @@ module GraphQL
 
       attr_writer :validate_timeout
 
-      def validate_timeout(new_validate_timeout = nil)
-        if new_validate_timeout
+      def validate_timeout(new_validate_timeout = NOT_CONFIGURED)
+        if !NOT_CONFIGURED.equal?(new_validate_timeout)
           @validate_timeout = new_validate_timeout
         elsif defined?(@validate_timeout)
           @validate_timeout
         else
-          find_inherited_value(:validate_timeout)
+          find_inherited_value(:validate_timeout) || 3
         end
       end
 
@@ -962,7 +971,7 @@ module GraphQL
       # @param new_extra_types [Module] Type definitions to include in printing and introspection, even though they aren't referenced in the schema
       # @return [Array<Module>] Type definitions added to this schema
       def extra_types(*new_extra_types)
-        if new_extra_types.any?
+        if !new_extra_types.empty?
           new_extra_types = new_extra_types.flatten
           @own_extra_types ||= []
           @own_extra_types.concat(new_extra_types)
@@ -987,10 +996,10 @@ module GraphQL
       # @param new_orphan_types [Array<Class<GraphQL::Schema::Object>>] Object types to register as implementations of interfaces in the schema.
       # @return [Array<Class<GraphQL::Schema::Object>>] All previously-registered orphan types for this schema
       def orphan_types(*new_orphan_types)
-        if new_orphan_types.any?
+        if !new_orphan_types.empty?
           new_orphan_types = new_orphan_types.flatten
           non_object_types = new_orphan_types.reject { |ot| ot.is_a?(Class) && ot < GraphQL::Schema::Object }
-          if non_object_types.any?
+          if !non_object_types.empty?
             raise ArgumentError, <<~ERR
               Only object type classes should be added as `orphan_types(...)`.
 
@@ -1007,7 +1016,7 @@ module GraphQL
 
         inherited_ot = find_inherited_value(:orphan_types, nil)
         if inherited_ot
-          if own_orphan_types.any?
+          if !own_orphan_types.empty?
             inherited_ot + own_orphan_types
           else
             inherited_ot
@@ -1055,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
@@ -1100,6 +1121,9 @@ module GraphQL
         }
       end
 
+      # @api private
+      attr_accessor :using_backtrace
+
       # @api private
       def handle_or_reraise(context, err)
         handler = Execution::Errors.find_handler_for(self, err.class)
@@ -1113,6 +1137,10 @@ module GraphQL
           end
           handler[:handler].call(err, obj, args, context, field)
         else
+          if (context[:backtrace] || using_backtrace) && !err.is_a?(GraphQL::ExecutionError)
+            err = GraphQL::Backtrace::TracedError.new(err, context)
+          end
+
           raise err
         end
       end
@@ -1147,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
@@ -1202,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)
@@ -1279,10 +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
-          ctx.errors << type_error
+          execution_error = GraphQL::ExecutionError.new(type_error.message, ast_node: type_error.ast_node)
+          execution_error.path = context[:current_path]
+
+          context.errors << execution_error
         when GraphQL::UnresolvedTypeError, GraphQL::StringEncodingError, GraphQL::IntegerEncodingError
           raise type_error
         when GraphQL::IntegerDecodingError
@@ -1290,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
@@ -1317,12 +1348,12 @@ module GraphQL
       # Add several directives at once
       # @param new_directives [Class]
       def directives(*new_directives)
-        if new_directives.any?
+        if !new_directives.empty?
           new_directives.flatten.each { |d| directive(d) }
         end
 
         inherited_dirs = find_inherited_value(:directives, default_directives)
-        if own_directives.any?
+        if !own_directives.empty?
           inherited_dirs.merge(own_directives)
         else
           inherited_dirs
@@ -1350,6 +1381,16 @@ module GraphQL
         }.freeze
       end
 
+      # @return [GraphQL::Tracing::DetailedTrace] if it has been configured for this schema
+      attr_accessor :detailed_trace
+
+      # @param query [GraphQL::Query, GraphQL::Execution::Multiplex] Called with a multiplex when multiple queries are executed at once (with {.multiplex})
+      # @return [Boolean] When `true`, save a detailed trace for this query.
+      # @see Tracing::DetailedTrace DetailedTrace saves traces when this method returns true
+      def detailed_trace?(query)
+        raise "#{self} must implement `def.detailed_trace?(query)` to use DetailedTrace. Implement this method in your schema definition."
+      end
+
       def tracer(new_tracer, silence_deprecation_warning: false)
         if !silence_deprecation_warning
           warn("`Schema.tracer(#{new_tracer.inspect})` is deprecated; use module-based `trace_with` instead. See: https://graphql-ruby.org/queries/tracing.html")
@@ -1367,14 +1408,22 @@ module GraphQL
         find_inherited_value(:tracers, EMPTY_ARRAY) + own_tracers
       end
 
-      # Mix `trace_mod` into this schema's `Trace` class so that its methods
-      # will be called at runtime.
+      # Mix `trace_mod` into this schema's `Trace` class so that its methods will be called at runtime.
+      #
+      # You can attach a module to run in only _some_ circumstances by using `mode:`. When a module is added with `mode:`,
+      # it will only run for queries with a matching `context[:trace_mode]`.
+      #
+      # Any custom trace modes _also_ include the default `trace_with ...` modules (that is, those added _without_ any particular `mode: ...` configuration).
+      #
+      # @example Adding a trace in a special mode
+      #   # only runs when `query.context[:trace_mode]` is `:special`
+      #   trace_with SpecialTrace, mode: :special
       #
       # @param trace_mod [Module] A module that implements tracing methods
       # @param mode [Symbol] Trace module will only be used for this trade mode
       # @param options [Hash] Keywords that will be passed to the tracing class during `#initialize`
       # @return [void]
-      # @see GraphQL::Tracing::Trace for available tracing methods
+      # @see GraphQL::Tracing::Trace Tracing::Trace for available tracing methods
       def trace_with(trace_mod, mode: :default, **options)
         if mode.is_a?(Array)
           mode.each { |m| trace_with(trace_mod, mode: m, **options) }
@@ -1424,29 +1473,36 @@ module GraphQL
       #
       # If no `mode:` is given, then {default_trace_mode} will be used.
       #
+      # If this schema is using {Tracing::DetailedTrace} and {.detailed_trace?} returns `true`, then
+      # DetailedTrace's mode will override the passed-in `mode`.
+      #
       # @param mode [Symbol] Trace modules for this trade mode will be included
       # @param options [Hash] Keywords that will be passed to the tracing class during `#initialize`
       # @return [Tracing::Trace]
       def new_trace(mode: nil, **options)
-        target = options[:query] || options[:multiplex]
-        mode ||= target && target.context[:trace_mode]
-
-        trace_mode = if mode
-          mode
-        elsif target && target.context[:backtrace]
-          if default_trace_mode != :default
-            raise ArgumentError, "Can't use `context[:backtrace]` with a custom default trace mode (`#{dm.inspect}`)"
-          else
-            own_trace_modes[:default_backtrace] ||= build_trace_mode(:default_backtrace)
-            options_trace_mode = :default
-            :default_backtrace
+        should_sample = if detailed_trace
+          if (query = options[:query])
+            detailed_trace?(query)
+          elsif (multiplex = options[:multiplex])
+            if multiplex.queries.length == 1
+              detailed_trace?(multiplex.queries.first)
+            else
+              detailed_trace?(multiplex)
+            end
           end
         else
-          default_trace_mode
+          false
         end
 
-        options_trace_mode ||= trace_mode
-        base_trace_options = trace_options_for(options_trace_mode)
+        if should_sample
+          mode = detailed_trace.trace_mode
+        else
+          target = options[:query] || options[:multiplex]
+          mode ||= target && target.context[:trace_mode]
+        end
+
+        trace_mode = mode || default_trace_mode
+        base_trace_options = trace_options_for(trace_mode)
         trace_options = base_trace_options.merge(options)
         trace_class_for_mode = trace_class_for(trace_mode, build: true)
         trace_class_for_mode.new(**trace_options)
@@ -1521,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)
@@ -1586,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
@@ -1624,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)
@@ -1787,3 +1996,6 @@ module GraphQL
     end
   end
 end
+
+require "graphql/schema/loader"
+require "graphql/schema/printer"

data/lib/graphql/static_validation/all_rules.rb

@@ -34,7 +34,7 @@ module GraphQL
       GraphQL::StaticValidation::VariableUsagesAreAllowed,
       GraphQL::StaticValidation::MutationRootExists,
       GraphQL::StaticValidation::QueryRootExists,
-      GraphQL::StaticValidation::SubscriptionRootExists,
+      GraphQL::StaticValidation::SubscriptionRootExistsAndSingleSubscriptionSelection,
       GraphQL::StaticValidation::InputObjectNamesAreUnique,
       GraphQL::StaticValidation::OneOfInputObjectsAreValid,
     ]

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

@@ -16,7 +16,7 @@ module GraphQL
 
       def validate_arguments(node)
         argument_defns = node.arguments
-        if argument_defns.any?
+        if !argument_defns.empty?
           args_by_name = Hash.new { |h, k| h[k] = [] }
           argument_defns.each { |a| args_by_name[a.name] << a }
           args_by_name.each do |name, defns|

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.any? && 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