graphql 1.13.0 → 1.13.24

data/lib/graphql/schema/validator/required_validator.rb

@@ -14,7 +14,7 @@ module GraphQL
       #     argument :ingredient_id, ID, required: true
       #     argument :cups, Integer, required: false
       #     argument :tablespoons, Integer, required: false
-      #     argument :teaspoons, Integer, required: true
+      #     argument :teaspoons, Integer, required: false
       #     validates required: { one_of: [:cups, :tablespoons, :teaspoons] }
       #   end
       #
@@ -28,11 +28,23 @@ module GraphQL
       #    validates required: { one_of: [:node_id, [:object_type, :object_id]] }
       #  end
       #
+      # @example require _some_ value for an argument, even if it's null
+      #   field :update_settings, AccountSettings do
+      #     # `required: :nullable` means this argument must be given, but may be `null`
+      #     argument :age, Integer, required: :nullable
+      #   end
+      #
       class RequiredValidator < Validator
         # @param one_of [Symbol, Array<Symbol>] An argument, or a list of arguments, that represents a valid set of inputs for this field
         # @param message [String]
-        def initialize(one_of:, message: "%{validated} has the wrong arguments", **default_options)
-          @one_of = one_of
+        def initialize(one_of: nil, argument: nil, message: "%{validated} has the wrong arguments", **default_options)
+          @one_of = if one_of
+            one_of
+          elsif argument
+            [argument]
+          else
+            raise ArgumentError, "`one_of:` or `argument:` must be given in `validates required: {...}`"
+          end
           @message = message
           super(**default_options)
         end
@@ -40,19 +52,21 @@ module GraphQL
         def validate(_object, _context, value)
           matched_conditions = 0
 
-          @one_of.each do |one_of_condition|
-            case one_of_condition
-            when Symbol
-              if value.key?(one_of_condition)
-                matched_conditions += 1
-              end
-            when Array
-              if one_of_condition.all? { |k| value.key?(k) }
-                matched_conditions += 1
-                break
+          if !value.nil?
+            @one_of.each do |one_of_condition|
+              case one_of_condition
+              when Symbol
+                if value.key?(one_of_condition)
+                  matched_conditions += 1
+                end
+              when Array
+                if one_of_condition.all? { |k| value.key?(k) }
+                  matched_conditions += 1
+                  break
+                end
+              else
+                raise ArgumentError, "Unknown one_of condition: #{one_of_condition.inspect}"
               end
-            else
-              raise ArgumentError, "Unknown one_of condition: #{one_of_condition.inspect}"
             end
           end
 

data/lib/graphql/schema/validator.rb

@@ -48,16 +48,13 @@ module GraphQL
           EMPTY_ARRAY
         else
           validates_hash = validates_hash.dup
-          allow_null = validates_hash.delete(:allow_null)
-          allow_blank = validates_hash.delete(:allow_blank)
 
-          # This could be {...}.compact on Ruby 2.4+
           default_options = {}
-          if !allow_null.nil?
-            default_options[:allow_null] = allow_null
+          if validates_hash[:allow_null]
+            default_options[:allow_null] = validates_hash.delete(:allow_null)
           end
-          if !allow_blank.nil?
-            default_options[:allow_blank] = allow_blank
+          if validates_hash[:allow_blank]
+            default_options[:allow_blank] = validates_hash.delete(:allow_blank)
           end
 
           # allow_nil or allow_blank are the _only_ validations:

data/lib/graphql/schema/warden.rb

@@ -78,6 +78,8 @@ module GraphQL
           def visible_type?(type, ctx); type.visible?(ctx); end
           def visible_enum_value?(ev, ctx); ev.visible?(ctx); end
           def visible_type_membership?(tm, ctx); tm.visible?(ctx); end
+          def interface_type_memberships(obj_t, ctx); obj_t.interface_type_memberships; end
+          def arguments(owner, ctx); owner.arguments(ctx); end
         end
       end
 
@@ -172,8 +174,8 @@ module GraphQL
 
       # @param argument_owner [GraphQL::Field, GraphQL::InputObjectType]
       # @return [Array<GraphQL::Argument>] Visible arguments on `argument_owner`
-      def arguments(argument_owner)
-        @visible_arguments ||= read_through { |o| o.arguments(@context).each_value.select { |a| visible_argument?(a) } }
+      def arguments(argument_owner, ctx = nil)
+        @visible_arguments ||= read_through { |o| o.arguments(@context).each_value.select { |a| visible_argument?(a, @context) } }
         @visible_arguments[argument_owner]
       end
 
@@ -231,6 +233,13 @@ module GraphQL
         visible?(type_membership)
       end
 
+      def interface_type_memberships(obj_type, _ctx = nil)
+        @type_memberships ||= read_through do |obj_t|
+          obj_t.interface_type_memberships
+        end
+        @type_memberships[obj_type]
+      end
+
       private
 
       def visible_and_reachable_type?(type_defn)

data/lib/graphql/schema.rb

@@ -161,7 +161,7 @@ module GraphQL
     include LazyHandlingMethods
     extend LazyHandlingMethods
 
-    accepts_definitions \
+    deprecated_accepts_definitions \
       :query_execution_strategy, :mutation_execution_strategy, :subscription_execution_strategy,
       :validate_timeout, :validate_max_errors, :max_depth, :max_complexity, :default_max_page_size,
       :orphan_types, :resolve_type, :type_error, :parse_error,
@@ -502,7 +502,7 @@ module GraphQL
     # @param field_name [String]
     # @return [GraphQL::Field, nil] The field named `field_name` on `parent_type`
     # @see [GraphQL::Schema::Warden] Restricted access to members of a schema
-    def get_field(parent_type, field_name)
+    def get_field(parent_type, field_name, _context = GraphQL::Query::NullContext)
       with_definition_error_check do
         parent_type_name = case parent_type
         when GraphQL::BaseType, Class, Module
@@ -845,7 +845,7 @@ module GraphQL
       # - Cause the Schema instance to be created, if it hasn't been created yet
       # - Delegate to that instance
       # Eventually, the methods will be moved into this class, removing the need for the singleton.
-      def_delegators :graphql_definition,
+      def_delegators :deprecated_graphql_definition,
         # Execution
         :execution_strategy_for_operation,
         # Configuration
@@ -854,6 +854,10 @@ module GraphQL
         :id_from_object=, :object_from_id=,
         :remove_handler
 
+      def deprecated_graphql_definition
+        graphql_definition(silence_deprecation_warning: true)
+      end
+
       # @return [GraphQL::Subscriptions]
       attr_accessor :subscriptions
 
@@ -888,6 +892,17 @@ module GraphQL
         GraphQL::Language::DocumentFromSchemaDefinition.new(self).document
       end
 
+      # @return [String, nil]
+      def description(new_description = nil)
+        if new_description
+          @description = new_description
+        elsif defined?(@description)
+          @description
+        else
+          find_inherited_value(:description, nil)
+        end
+      end
+
       def find(path)
         if !@finder
           @find_cache = {}
@@ -896,8 +911,15 @@ module GraphQL
         @find_cache[path] ||= @finder.find(path)
       end
 
-      def graphql_definition
-        @graphql_definition ||= to_graphql
+      def graphql_definition(silence_deprecation_warning: false)
+        @graphql_definition ||= begin
+          unless silence_deprecation_warning
+            message = "Legacy `.graphql_definition` objects are deprecated and will be removed in GraphQL-Ruby 2.0. Use a class-based definition instead."
+            caller_message = "\n\nCalled on #{self.inspect} from:\n #{caller(1, 25).map { |l| "  #{l}" }.join("\n")}"
+            GraphQL::Deprecation.warn(message + caller_message)
+          end
+          to_graphql(silence_deprecation_warning: silence_deprecation_warning)
+        end
       end
 
       def default_filter
@@ -929,19 +951,20 @@ module GraphQL
         find_inherited_value(:plugins, EMPTY_ARRAY) + own_plugins
       end
 
+      prepend Schema::Member::CachedGraphQLDefinition::DeprecatedToGraphQL
       def to_graphql
         schema_defn = self.new
         schema_defn.raise_definition_error = true
-        schema_defn.query = query && query.graphql_definition
-        schema_defn.mutation = mutation && mutation.graphql_definition
-        schema_defn.subscription = subscription && subscription.graphql_definition
+        schema_defn.query = query && query.graphql_definition(silence_deprecation_warning: true)
+        schema_defn.mutation = mutation && mutation.graphql_definition(silence_deprecation_warning: true)
+        schema_defn.subscription = subscription && subscription.graphql_definition(silence_deprecation_warning: true)
         schema_defn.validate_timeout = validate_timeout
         schema_defn.validate_max_errors = validate_max_errors
         schema_defn.max_complexity = max_complexity
         schema_defn.error_bubbling = error_bubbling
         schema_defn.max_depth = max_depth
         schema_defn.default_max_page_size = default_max_page_size
-        schema_defn.orphan_types = orphan_types.map(&:graphql_definition)
+        schema_defn.orphan_types = orphan_types.map { |t| t.graphql_definition(silence_deprecation_warning: true) }
         schema_defn.disable_introspection_entry_points = disable_introspection_entry_points?
         schema_defn.disable_schema_introspection_entry_point = disable_schema_introspection_entry_point?
         schema_defn.disable_type_introspection_entry_point = disable_type_introspection_entry_point?
@@ -1235,7 +1258,7 @@ module GraphQL
         when Module
           type_or_name
         else
-          raise ArgumentError, "unexpected field owner for #{field_name.inspect}: #{type_or_name.inspect} (#{type_or_name.class})"
+          raise GraphQL::InvariantError, "Unexpected field owner for #{field_name.inspect}: #{type_or_name.inspect} (#{type_or_name.class})"
         end
 
         if parent_type.kind.fields? && (field = parent_type.get_field(field_name, context))
@@ -1707,6 +1730,7 @@ module GraphQL
           {
             backtrace: ctx[:backtrace],
             tracers: ctx[:tracers],
+            dataloader: ctx[:dataloader],
           }
         else
           {}

data/lib/graphql/static_validation/all_rules.rb

@@ -33,6 +33,7 @@ module GraphQL
       GraphQL::StaticValidation::VariablesAreUsedAndDefined,
       GraphQL::StaticValidation::VariableUsagesAreAllowed,
       GraphQL::StaticValidation::MutationRootExists,
+      GraphQL::StaticValidation::QueryRootExists,
       GraphQL::StaticValidation::SubscriptionRootExists,
       GraphQL::StaticValidation::InputObjectNamesAreUnique,
     ]

data/lib/graphql/static_validation/base_visitor.rb

@@ -110,7 +110,7 @@ module GraphQL
         end
 
         def on_directive(node, parent)
-          directive_defn = @schema.directives[node.name]
+          directive_defn = @context.schema_directives[node.name]
           @directive_definitions.push(directive_defn)
           super
           @directive_definitions.pop

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

@@ -59,7 +59,7 @@ module GraphQL
             end
           end
         when GraphQL::Language::Nodes::Directive
-          context.schema.directives[parent.name]
+          context.schema_directives[parent.name]
         when GraphQL::Language::Nodes::Field
           context.field_definition
         else

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

@@ -5,7 +5,7 @@ module GraphQL
       include GraphQL::Language
 
       def on_directive(node, parent)
-        validate_location(node, parent, context.schema.directives)
+        validate_location(node, parent, context.schema_directives)
         super
       end
 

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

@@ -50,15 +50,15 @@ module GraphQL
         @arg_conflicts = nil
 
         yield
-
-        field_conflicts.each_value { |error| add_error(error) }
-        arg_conflicts.each_value { |error| add_error(error) }
+        # 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) }
       end
 
       def conflicts_within_selection_set(node, parent_type)
         return if parent_type.nil?
 
-        fields, fragment_spreads = fields_and_fragments_from_selection(node, owner_type: parent_type, parents: [])
+        fields, fragment_spreads = fields_and_fragments_from_selection(node, owner_type: parent_type, parents: nil)
 
         # (A) Find find all conflicts "within" the fields of this selection set.
         find_conflicts_within(fields)
@@ -198,10 +198,14 @@ module GraphQL
         response_keys.each do |key, fields|
           next if fields.size < 2
           # find conflicts within nodes
-          for i in 0..fields.size - 1
-            for j in i + 1..fields.size - 1
+          i = 0
+          while i < fields.size
+            j = i + 1
+            while j < fields.size
               find_conflict(key, fields[i], fields[j])
+              j += 1
             end
+            i += 1
           end
         end
       end
@@ -243,7 +247,9 @@ module GraphQL
       end
 
       def find_conflicts_between_sub_selection_sets(field1, field2, mutually_exclusive:)
-        return if field1.definition.nil? || field2.definition.nil?
+        return if field1.definition.nil? ||
+          field2.definition.nil? ||
+          (field1.node.selections.empty? && field2.node.selections.empty?)
 
         return_type1 = field1.definition.type.unwrap
         return_type2 = field2.definition.type.unwrap
@@ -323,6 +329,7 @@ module GraphQL
         if node.selections.empty?
           NO_SELECTIONS
         else
+          parents ||= []
           fields, fragment_spreads = find_fields_and_fragments(node.selections, owner_type: owner_type, parents: parents, fields: [], fragment_spreads: [])
           response_keys = fields.group_by { |f| f.node.alias || f.node.name }
           [response_keys, fragment_spreads]

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module GraphQL
+  module StaticValidation
+    module QueryRootExists
+      def on_operation_definition(node, _parent)
+        if (node.operation_type == 'query' || node.operation_type.nil?) && context.warden.root_type_for_operation("query").nil?
+          add_error(GraphQL::StaticValidation::QueryRootExistsError.new(
+            'Schema is not configured for queries',
+            nodes: node
+          ))
+        else
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module GraphQL
+  module StaticValidation
+    class QueryRootExistsError < StaticValidation::Error
+
+      def initialize(message, path: nil, nodes: [])
+        super(message, path: path, nodes: nodes)
+      end
+
+      # A hash representation of this Message
+      def to_h
+        extensions = {
+          "code" => code,
+        }
+
+        super.merge({
+          "extensions" => extensions
+        })
+      end
+
+      def code
+        "missingQueryConfiguration"
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module GraphQL
       end
 
       def on_directive(node, _parent)
-        directive_defn = context.schema.directives[node.name]
+        directive_defn = context.schema_directives[node.name]
         assert_required_args(node, directive_defn)
         super
       end
@@ -16,6 +16,8 @@ module GraphQL
       private
 
       def assert_required_args(ast_node, defn)
+        args = defn.arguments(context.query.context)
+        return if args.empty?
         present_argument_names = ast_node.arguments.map(&:name)
         required_argument_names = context.warden.arguments(defn)
           .select { |a| a.type.kind.non_null? && !a.default_value? && context.warden.get_argument(defn, a.name) }

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

@@ -40,7 +40,7 @@ module GraphQL
               nodes: [used_directives[directive_name], ast_directive],
               directive: directive_name,
             ))
-          else
+          elsif !((dir_defn = context.schema_directives[directive_name]) && dir_defn.repeatable?)
             used_directives[directive_name] = ast_directive
           end
         end

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

@@ -68,6 +68,12 @@ module GraphQL
         arg_defn = context.warden.get_argument(argument_owner, arg_node.name)
         arg_defn_type = arg_defn.type
 
+        # If the argument is non-null, but it was given a default value,
+        # then treat it as nullable in practice, see https://github.com/rmosolgo/graphql-ruby/issues/3793
+        if arg_defn_type.non_null? && arg_defn.default_value?
+          arg_defn_type = arg_defn_type.of_type
+        end
+
         var_inner_type = var_type.unwrap
         arg_inner_type = arg_defn_type.unwrap
 

data/lib/graphql/static_validation/validation_context.rb

@@ -44,6 +44,10 @@ module GraphQL
       def too_many_errors?
         @errors.length >= @max_errors
       end
+
+      def schema_directives
+        @schema_directives ||= schema.directives
+      end
     end
   end
 end

data/lib/graphql/string_type.rb

@@ -1,2 +1,2 @@
 # frozen_string_literal: true
-GraphQL::STRING_TYPE = GraphQL::Types::String.graphql_definition
+GraphQL::STRING_TYPE = GraphQL::Types::String.graphql_definition(silence_deprecation_warning: true)

data/lib/graphql/subscriptions/action_cable_subscriptions.rb

@@ -216,6 +216,8 @@ module GraphQL
       # The channel was closed, forget about it.
       def delete_subscription(subscription_id)
         query = @subscriptions.delete(subscription_id)
+        # In case this came from the server, tell the client to unsubscribe:
+        @action_cable.server.broadcast(stream_subscription_name(subscription_id), { more: false })
         # This can be `nil` when `.trigger` happens inside an unsubscribed ActionCable channel,
         # see https://github.com/rmosolgo/graphql-ruby/issues/2478
         if query

data/lib/graphql/subscriptions/serialize.rb

@@ -71,9 +71,17 @@ module GraphQL
               when SYMBOL_KEY
                 value[SYMBOL_KEY].to_sym
               when TIMESTAMP_KEY
-                timestamp_class_name, timestamp_s = value[TIMESTAMP_KEY]
+                timestamp_class_name, *timestamp_args = value[TIMESTAMP_KEY]
                 timestamp_class = Object.const_get(timestamp_class_name)
-                timestamp_class.strptime(timestamp_s, TIMESTAMP_FORMAT)
+                if defined?(ActiveSupport::TimeWithZone) && timestamp_class <= ActiveSupport::TimeWithZone
+                  zone_name, timestamp_s = timestamp_args
+                  zone = ActiveSupport::TimeZone[zone_name]
+                  raise "Zone #{zone_name} not found, unable to deserialize" unless zone
+                  zone.strptime(timestamp_s, TIMESTAMP_FORMAT)
+                else
+                  timestamp_s = timestamp_args.first
+                  timestamp_class.strptime(timestamp_s, TIMESTAMP_FORMAT)
+                end
               when OPEN_STRUCT_KEY
                 ostruct_values = load_value(value[OPEN_STRUCT_KEY])
                 OpenStruct.new(ostruct_values)
@@ -123,6 +131,18 @@ module GraphQL
             { SYMBOL_KEY => obj.to_s }
           elsif obj.respond_to?(:to_gid_param)
             {GLOBALID_KEY => obj.to_gid_param}
+          elsif defined?(ActiveSupport::TimeWithZone) && obj.is_a?(ActiveSupport::TimeWithZone) && obj.class.name != Time.name
+            # This handles a case where Rails prior to 7 would
+            # make the class ActiveSupport::TimeWithZone return "Time" for
+            # its name. In Rails 7, it will now return "ActiveSupport::TimeWithZone",
+            # which happens to be incompatible with expectations we have
+            # with what a Time class supports ( notably, strptime in `load_value` ).
+            #
+            # This now passes along the name of the zone, such that a future deserialization
+            # of this string will use the correct time zone from the ActiveSupport TimeZone
+            # list to produce the time.
+            #
+            { TIMESTAMP_KEY => [obj.class.name, obj.time_zone.name, obj.strftime(TIMESTAMP_FORMAT)] }
           elsif obj.is_a?(Date) || obj.is_a?(Time)
             # DateTime extends Date; for TimeWithZone, call `.utc` first.
             { TIMESTAMP_KEY => [obj.class.name, obj.strftime(TIMESTAMP_FORMAT)] }

data/lib/graphql/tracing/active_support_notifications_tracing.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'graphql/tracing/notifications_tracing'
+
 module GraphQL
   module Tracing
     # This implementation forwards events to ActiveSupport::Notifications
@@ -8,27 +10,11 @@ module GraphQL
     # @see KEYS for event names
     module ActiveSupportNotificationsTracing
       # A cache of frequently-used keys to avoid needless string allocations
-      KEYS = {
-        "lex" => "lex.graphql",
-        "parse" => "parse.graphql",
-        "validate" => "validate.graphql",
-        "analyze_multiplex" => "analyze_multiplex.graphql",
-        "analyze_query" => "analyze_query.graphql",
-        "execute_query" => "execute_query.graphql",
-        "execute_query_lazy" => "execute_query_lazy.graphql",
-        "execute_field" => "execute_field.graphql",
-        "execute_field_lazy" => "execute_field_lazy.graphql",
-        "authorized" => "authorized.graphql",
-        "authorized_lazy" => "authorized_lazy.graphql",
-        "resolve_type" => "resolve_type.graphql",
-        "resolve_type_lazy" => "resolve_type.graphql",
-      }
+      KEYS = NotificationsTracing::KEYS
+      NOTIFICATIONS_ENGINE = NotificationsTracing.new(ActiveSupport::Notifications) if defined?(ActiveSupport::Notifications)
 
-      def self.trace(key, metadata)
-        prefixed_key = KEYS[key] || "#{key}.graphql"
-        ActiveSupport::Notifications.instrument(prefixed_key, metadata) do
-          yield
-        end
+      def self.trace(key, metadata, &blk)
+        NOTIFICATIONS_ENGINE.trace(key, metadata, &blk)
       end
     end
   end

data/lib/graphql/tracing/data_dog_tracing.rb

@@ -15,17 +15,23 @@ module GraphQL
       }
 
       def platform_trace(platform_key, key, data)
-        tracer.trace(platform_key, service: service_name) do |span|
-          span.span_type = 'custom'
+        tracer.trace(platform_key, service: options[:service], type: 'custom') do |span|
+          span.set_tag('component', 'graphql')
+          span.set_tag('operation', key)
 
           if key == 'execute_multiplex'
             operations = data[:multiplex].queries.map(&:selected_operation_name).join(', ')
-            span.resource = operations unless operations.empty?
 
-            # For top span of query, set the analytics sample rate tag, if available.
-            if analytics_enabled?
-              Datadog::Contrib::Analytics.set_sample_rate(span, analytics_sample_rate)
+            resource = if operations.empty?
+              first_query = data[:multiplex].queries.first
+              fallback_transaction_name(first_query && first_query.context)
+            else
+              operations
             end
+            span.resource = resource if resource
+
+            # [Deprecated] will be removed in the future
+            span.set_metric('_dd1.sr.eausr', analytics_sample_rate) if analytics_enabled?
           end
 
           if key == 'execute_query'
@@ -34,26 +40,29 @@ module GraphQL
             span.set_tag(:query_string, data[:query].query_string)
           end
 
+          prepare_span(key, data, span)
+
           yield
         end
       end
 
-      def service_name
-        options.fetch(:service, 'ruby-graphql')
+      # Implement this method in a subclass to apply custom tags to datadog spans
+      # @param key [String] The event being traced
+      # @param data [Hash] The runtime data for this event (@see GraphQL::Tracing for keys for each event)
+      # @param span [Datadog::Tracing::SpanOperation] The datadog span for this event
+      def prepare_span(key, data, span)
       end
 
       def tracer
-        options.fetch(:tracer, Datadog.tracer)
-      end
+        default_tracer = defined?(Datadog::Tracing) ? Datadog::Tracing : Datadog.tracer
 
-      def analytics_available?
-        defined?(Datadog::Contrib::Analytics) \
-          && Datadog::Contrib::Analytics.respond_to?(:enabled?) \
-          && Datadog::Contrib::Analytics.respond_to?(:set_sample_rate)
+        # [Deprecated] options[:tracer] will be removed in the future
+        options.fetch(:tracer, default_tracer)
       end
 
       def analytics_enabled?
-        analytics_available? && Datadog::Contrib::Analytics.enabled?(options.fetch(:analytics_enabled, false))
+        # [Deprecated] options[:analytics_enabled] will be removed in the future
+        options.fetch(:analytics_enabled, false)
       end
 
       def analytics_sample_rate

data/lib/graphql/tracing/notifications_tracing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    # This implementation forwards events to a notification handler (i.e.
+    # ActiveSupport::Notifications or Dry::Monitor::Notifications)
+    # with a `graphql` suffix.
+    #
+    # @see KEYS for event names
+    class NotificationsTracing
+      # A cache of frequently-used keys to avoid needless string allocations
+      KEYS = {
+        "lex" => "lex.graphql",
+        "parse" => "parse.graphql",
+        "validate" => "validate.graphql",
+        "analyze_multiplex" => "analyze_multiplex.graphql",
+        "analyze_query" => "analyze_query.graphql",
+        "execute_query" => "execute_query.graphql",
+        "execute_query_lazy" => "execute_query_lazy.graphql",
+        "execute_field" => "execute_field.graphql",
+        "execute_field_lazy" => "execute_field_lazy.graphql",
+        "authorized" => "authorized.graphql",
+        "authorized_lazy" => "authorized_lazy.graphql",
+        "resolve_type" => "resolve_type.graphql",
+        "resolve_type_lazy" => "resolve_type.graphql",
+      }
+
+      MAX_KEYS_SIZE = 100
+
+      # Initialize a new NotificationsTracing instance
+      #
+      # @param [Object] notifications_engine The notifications engine to use
+      def initialize(notifications_engine)
+        @notifications_engine = notifications_engine
+      end
+
+      # Sends a GraphQL tracing event to the notification handler
+      #
+      # @example
+      # . notifications_engine = Dry::Monitor::Notifications.new(:graphql)
+      # . tracer = GraphQL::Tracing::NotificationsTracing.new(notifications_engine)
+      # . tracer.trace("lex") { ... }
+      #
+      # @param [string] key The key for the event
+      # @param [Hash] metadata The metadata for the event
+      # @yield The block to execute for the event
+      def trace(key, metadata, &blk)
+        prefixed_key = KEYS[key] || "#{key}.graphql"
+
+        # Cache the new keys while making sure not to induce a memory leak
+        if KEYS.size < MAX_KEYS_SIZE
+          KEYS[key] ||= prefixed_key
+        end
+
+        @notifications_engine.instrument(prefixed_key, metadata, &blk)
+      end
+    end
+  end
+end