lighthouse-graphql 0.2.0 → 0.3.0

data/lib/lighthouse/schema_generator.rb

@@ -43,7 +43,7 @@ module Lighthouse::GraphQL::SchemaGenerator
     uses_cache_control = sdl_string.to_s.gsub(/directive\s+@cacheControl/, '').include?('@cacheControl')
     # The manipulated document — from the schema cache when it is enabled
     # and fresh (see SchemaCache), else built now.
-    document = Lighthouse::GraphQL::SchemaCache.document(sdl_string) { |sdl| manipulate(sdl) }
+    document = build_document(sdl_string)
     impl = default_implementation
     schema = from_document(document, impl, opts)
 
@@ -51,6 +51,7 @@ module Lighthouse::GraphQL::SchemaGenerator
     Lighthouse::GraphQL::GeneratedResolvers.install_dispatcher(schema)
     attach_schema(impl, schema)
     post_process(schema, impl, **opts)
+    schema.trace_with(Lighthouse::Events::ExecutionTrace)
 
     # @cacheControl hints become the response's Cache-Control header,
     # computed per query from the fields it selects.
@@ -104,6 +105,18 @@ module Lighthouse::GraphQL::SchemaGenerator
     Module.new { define_singleton_method(:parse) { |*| document } }
   end
 
+  # The manipulated schema document for the app's SDL, from the schema cache
+  # when it is enabled and fresh. The build events fire around the phases:
+  # RegisterDirectiveNamespaces on every build (the cache key covers the
+  # registered directives), BuildSchemaString and ManipulateAST only when the
+  # document is built, i.e. on a cache miss.
+  def build_document(sdl, force: false)
+    Lighthouse::Events::SchemaBuild.register_directive_namespaces
+    Lighthouse::GraphQL::SchemaCache.document(sdl, force: force, finalize: Lighthouse::Events::SchemaBuild.method(:manipulate_ast)) do |source|
+      manipulate(Lighthouse::Events::SchemaBuild.schema_string(source))
+    end
+  end
+
   # The SDL as the schema is built from it: directive definitions injected
   # (so apps don't hand-declare Lighthouse's directives), then every
   # registered manipulator run (pagination types, whereConditions inputs, ...).
@@ -112,7 +125,7 @@ module Lighthouse::GraphQL::SchemaGenerator
   end
 
   def post_process(schema, _impl, **_opts)
-    root_kinds = { schema.query&.graphql_name => :queries, schema.mutation&.graphql_name => :mutations }.reject { |name, _| name.nil? }
+    root_kinds = root_kinds(schema)
 
     # Inspect types and fields for directives and attach generated resolvers
     schema.types.each_value do |type|
@@ -124,10 +137,22 @@ module Lighthouse::GraphQL::SchemaGenerator
       type.fields.each_value { |field_def| process_field(type, field_def, root_kinds[type.graphql_name]) }
     end
 
+    # @feature hides a field or type per query, through graphql-ruby's visibility.
+    Lighthouse::GraphQL::FeatureDirective.apply(schema)
+
+    # Every @broadcast must name a field of the Subscription type.
+    Lighthouse::GraphQL::Broadcasting.validate!(schema)
+
     # return schema for convenience
     schema
   end
 
+  # { type name => :queries | :mutations | :subscriptions } for the schema's root types.
+  def root_kinds(schema)
+    { schema.query => :queries, schema.mutation => :mutations, schema.subscription => :subscriptions }
+      .reject { |type, _| type.nil? }.transform_keys(&:graphql_name)
+  end
+
   # A field's generated resolvers, then the runtime hooks that make
   # graphql-ruby reach them.
   def process_field(type, field_def, root_kind)

data/lib/lighthouse/subscription.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+
+# PHP Lighthouse's subscription model, as a concern a plain graphql-ruby
+# subscription includes. The class is written as graphql-ruby's guide has it,
+# and gains the hooks of PHP Lighthouse's GraphQLSubscription, as
+# `include Lighthouse::GraphQL::Controller` gives a controller its `execute`:
+#
+#   class Subscriptions::PostUpdated < GraphQL::Schema::Subscription
+#     include Lighthouse::GraphQL::Subscription
+#
+#     argument :author_id, ID, required: false
+#
+#     def filter?(post, author_id: nil) = author_id.nil? || post.author_id.to_s == author_id
+#   end
+#
+#   PHP Lighthouse                    here                                  graphql-ruby
+#   authorize(Subscriber, Request)    authorize?(**args)                    authorized? (initial request only)
+#   filter(Subscriber, $root)         filter?(root, **args)                 update returns NO_UPDATE when false
+#   resolve($root, $args, ...)        resolve_payload(root, **args)         update's return value
+#   encodeTopic / decodeTopic         self.topic_for(arguments:, field:, scope:)
+#
+# `object`, `context` and `field` are available in every hook, and `context`
+# is the subscriber's: graphql-ruby stores it with the subscription and
+# replays it for each update, so `context[:current_user]` is the subscriber.
+#
+# Precedence: the concern sits between the class and GraphQL::Schema::Subscription,
+# so a class that defines `update` or `authorized?` itself wins, and its
+# `filter?`, `resolve_payload` or `authorize?` are not called unless it calls
+# `super`. Everything else graphql-ruby offers (`subscribe`, `unsubscribe`,
+# `subscription_scope`, `ready?`) is untouched.
+#
+# Unlike a plain subscription, every subscriber of the field shares one topic
+# (the field name and its scope, not its arguments), which is PHP Lighthouse's
+# model: a trigger reaches all of them and `filter?` decides who gets it, from
+# the subscriber's own arguments. `topic_by :arguments` turns graphql-ruby's
+# exact-argument matching back on.
+module Lighthouse::GraphQL::Subscription
+  extend ActiveSupport::Concern
+
+  included do
+    unless self < ::GraphQL::Schema::Subscription
+      raise Lighthouse::DefinitionError,
+            "#{self} includes Lighthouse::GraphQL::Subscription, which is for subclasses of GraphQL::Schema::Subscription " \
+            '(class Subscriptions::PostUpdated < GraphQL::Schema::Subscription).'
+    end
+
+    class_attribute :lighthouse_topic_by, instance_accessor: false, instance_predicate: false, default: :field
+  end
+
+  class_methods do
+    # :field (the default) or :arguments. See `topic_for`. Inherited by subclasses.
+    def topic_by(mode = nil)
+      return lighthouse_topic_by unless mode
+
+      raise ArgumentError, "topic_by takes :field or :arguments, not #{mode.inspect}" unless %i[field arguments].include?(mode)
+
+      self.lighthouse_topic_by = mode
+    end
+
+    # The stream a subscription belongs to, and the one a trigger addresses.
+    # Only the scope and the field by default: every subscriber is updated, and
+    # `filter?` narrows it down. With `topic_by :arguments` it is
+    # graphql-ruby's: the trigger's arguments must equal the subscriber's.
+    def topic_for(arguments:, field:, scope:)
+      return super if topic_by == :arguments
+
+      ::GraphQL::Subscriptions::Serialize.dump_recursive([scope, field.graphql_name])
+    end
+
+    # The arguments @broadcast triggers this subscription with, for the
+    # `root` a mutation returned. Matter only with `topic_by :arguments`,
+    # where they must equal the subscribers' arguments.
+    def trigger_arguments(_root, _context)
+      {}
+    end
+
+    # The `scope:` @broadcast triggers this subscription with. Needed when the
+    # class declares `subscription_scope`.
+    def trigger_scope(_root, _context)
+      nil
+    end
+  end
+
+  # May this client subscribe? Return false (or raise a GraphQL::ExecutionError)
+  # to refuse. Called once, with the subscription request, not for each update.
+  def authorize?(**_args)
+    true
+  end
+
+  # Should this subscriber receive the broadcast of `root`? `args` are the
+  # arguments the client subscribed with; `context` is theirs.
+  def filter?(_root, **_args)
+    true
+  end
+
+  # The value an update resolves the field with; the broadcast root by default.
+  def resolve_payload(root, **_args)
+    root
+  end
+
+  def authorized?(**args)
+    return super if context.query.subscription_update? || authorize?(**args)
+
+    [false, Lighthouse::AuthorizationError.new('Unauthorized subscription request.')]
+  end
+
+  def update(**args)
+    filter?(object, **args) ? resolve_payload(object, **args) : ::GraphQL::Schema::Subscription::NO_UPDATE
+  end
+end
+
+# What a Subscription field with no class of its own resolves to: graphql-ruby's
+# subscription with the concern, so every subscriber gets every broadcast
+# unchanged.
+Lighthouse::GraphQL::Subscription::Default = Class.new(GraphQL::Schema::Subscription) do
+  include Lighthouse::GraphQL::Subscription
+end

data/lib/lighthouse/support/soft_deletes.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Soft deletes behind one seam, for @softDeletes / @trashed, @restore,
+# @forceDelete and @withoutGlobalScopes. Rails has no built-in soft deletes, so
+# the model's strategy is detected, in this order:
+#
+# - paranoia (`acts_as_paranoid`): a default scope hides trashed records.
+# - discard (`include Discard::Model`): nothing is hidden unless the model
+#   adds `default_scope -> { kept }`.
+# - a plain `deleted_at` column (Column), with no gem.
+#
+# `Config.soft_deletes` replaces the detection with an adapter of the app's
+# own: any object answering `soft_deletes?(model)`, `only_trashed(relation)`,
+# `with_trashed(relation)`, `without_trashed(relation)`, `restore(record)` and
+# `force_delete(record)` (the last two answering whether they succeeded).
+# `Column.new(:archived_at)` is a ready-made one for another column name.
+module Lighthouse::Support::SoftDeletes
+  module_function
+
+  # The adapter in use: Config.soft_deletes, else the detecting one.
+  def adapter
+    Lighthouse::Config.soft_deletes || (@default ||= Lighthouse::Support::SoftDeletes::Auto.new)
+  end
+
+  def supported?(model)
+    adapter.soft_deletes?(model)
+  end
+
+  # A client-facing error: the schema asks for soft deletes on a model without them.
+  def require_support!(model)
+    return if supported?(model)
+
+    raise ::GraphQL::ExecutionError,
+          "Model #{model.name} does not support soft deletes (no paranoia, discard or deleted_at column; see Config.soft_deletes)."
+  end
+
+  def only_trashed(relation)
+    require_support!(relation.klass)
+    adapter.only_trashed(relation)
+  end
+
+  def with_trashed(relation)
+    require_support!(relation.klass)
+    adapter.with_trashed(relation)
+  end
+
+  def without_trashed(relation)
+    require_support!(relation.klass)
+    adapter.without_trashed(relation)
+  end
+
+  # The relation for a `Trashed` enum value: ONLY, WITH or WITHOUT.
+  def filter(relation, trashed)
+    case trashed.to_s.upcase
+    when 'ONLY' then only_trashed(relation)
+    when 'WITH' then with_trashed(relation)
+    when 'WITHOUT' then without_trashed(relation)
+    else raise ::GraphQL::ExecutionError, "Unknown trashed value #{trashed.inspect}, expected ONLY, WITH or WITHOUT."
+    end
+  end
+
+  def restore(record)
+    require_support!(record.class)
+    adapter.restore(record)
+  end
+
+  def force_delete(record)
+    require_support!(record.class)
+    adapter.force_delete(record)
+  end
+
+  # paranoia: `with_deleted` / `only_deleted` / `#restore` / `#really_destroy!`.
+  class Paranoia
+    def soft_deletes?(model)
+      return false unless defined?(::Paranoia)
+
+      model.respond_to?(:paranoid?) && model.paranoid?
+    end
+
+    def only_trashed(relation) = relation.only_deleted
+    def with_trashed(relation) = relation.with_deleted
+
+    def without_trashed(relation)
+      model = relation.klass
+      relation.with_deleted.where(model.paranoia_column => model.paranoia_sentinel_value)
+    end
+
+    def restore(record) = record.restore
+
+    def force_delete(record) = record.really_destroy!
+  end
+
+  # discard: `kept` / `discarded` scopes, `#undiscard`; `#destroy` really deletes.
+  class Discard
+    def soft_deletes?(model)
+      return false unless defined?(::Discard::Model)
+
+      model.include?(::Discard::Model)
+    end
+
+    def only_trashed(relation) = with_trashed(relation).discarded
+    def with_trashed(relation) = relation.unscope(where: relation.klass.discard_column)
+    def without_trashed(relation) = with_trashed(relation).kept
+
+    def restore(record) = record.undiscard
+
+    def force_delete(record) = record.destroy
+  end
+
+  # A nullable timestamp column (`deleted_at` by default) and no gem. It marks
+  # trashed records with a value and may or may not be hidden by a default scope:
+  # every filter unscopes the column first, so both work. Restoring sets it to
+  # null (skipping callbacks and validations); force deleting is `#destroy`.
+  class Column
+    DEFAULT_COLUMN = 'deleted_at'
+
+    def initialize(column = DEFAULT_COLUMN)
+      @column = column.to_s
+    end
+
+    def soft_deletes?(model)
+      model.respond_to?(:column_names) && model.table_exists? && model.column_names.include?(@column)
+    rescue ::ActiveRecord::ActiveRecordError
+      false
+    end
+
+    def only_trashed(relation) = with_trashed(relation).where.not(@column => nil)
+    def with_trashed(relation) = relation.unscope(where: @column)
+    def without_trashed(relation) = with_trashed(relation).where(@column => nil)
+
+    def restore(record)
+      record.update_columns(@column => nil) # rubocop:disable Rails/SkipsModelValidations -- a trashed record may no longer validate.
+    end
+
+    def force_delete(record) = record.destroy
+  end
+
+  # The default adapter: asks each strategy, in order, whether the model uses it.
+  class Auto
+    def initialize(strategies = nil)
+      @strategies = strategies || [Paranoia.new, Discard.new, Column.new]
+    end
+
+    def soft_deletes?(model)
+      !strategy(model).nil?
+    end
+
+    def only_trashed(relation) = strategy!(relation.klass).only_trashed(relation)
+    def with_trashed(relation) = strategy!(relation.klass).with_trashed(relation)
+    def without_trashed(relation) = strategy!(relation.klass).without_trashed(relation)
+    def restore(record) = strategy!(record.class).restore(record)
+    def force_delete(record) = strategy!(record.class).force_delete(record)
+
+    private
+
+    def strategy(model)
+      @strategies.find { |strategy| strategy.soft_deletes?(model) }
+    end
+
+    def strategy!(model)
+      strategy(model) || raise(::GraphQL::ExecutionError, "Model #{model.name} does not support soft deletes.")
+    end
+  end
+end

data/lib/lighthouse/tasks/lighthouse.rake

@@ -18,6 +18,16 @@ namespace :lighthouse do
     puts "Cleared #{Lighthouse::GraphQL::SchemaCache.directory}"
   end
 
+  desc 'Build the schema, dispatch the ValidateSchema event and check graphql-ruby accepts it (SCHEMA=AppSchema)'
+  task validate_schema: :environment do
+    schema = Object.const_get(ENV.fetch('SCHEMA', 'AppSchema'))
+    Lighthouse::Events.dispatch(Lighthouse::Events::ValidateSchema.new(schema))
+    schema.to_definition # builds every type: unresolvable references and duplicate names raise
+    puts "#{schema} is valid."
+  rescue StandardError => e
+    abort("#{schema || 'Schema'} is invalid: #{e.message}")
+  end
+
   namespace :persisted_queries do
     desc 'Validate every operation of the persisted query manifest against the schema (SCHEMA=AppSchema)'
     task verify: :environment do

data/sig/lighthouse/controller.rbs

@@ -0,0 +1,30 @@
+# The Rails controller concern that serves a schema. See docs/getting-started.md.
+module Lighthouse
+  module GraphQL
+    module Controller
+      module ClassMethods
+        # The schema `execute` runs: a schema class, its name (constantized per
+        # request) or a block (evaluated in the controller, per request).
+        def lighthouse_schema: (?(Class | String | Symbol)? schema) ?{ () -> untyped } -> untyped
+      end
+
+      # The action: dispatches StartRequest, runs the operation (or a batch),
+      # sets Cache-Control, renders JSON, dispatches EndRequest.
+      def execute: () -> untyped
+
+      private
+
+      # Dispatch StartRequest, yield, dispatch EndRequest; only the outermost call does.
+      def lighthouse_request: [T] () { () -> T } -> T
+
+      # The operation's context; { current_user: current_user } when the controller has one.
+      def graphql_context: () -> Hash[Symbol, untyped]
+
+      # The schema class `lighthouse_schema` names.
+      def graphql_schema: () -> untyped
+
+      # The `variables` parameter as a Hash: from a JSON String, a Hash or parameters.
+      def graphql_variables: (untyped param) -> Hash[String, untyped]
+    end
+  end
+end

data/sig/lighthouse/directives.rbs

@@ -0,0 +1,158 @@
+# The extension points for custom directives: the contracts a directive class
+# includes, the registry it is registered in, and the base classes it can
+# subclass. See docs/custom-directives.md.
+module Lighthouse
+  # What the registry asks a self-describing directive class: its SDL name
+  # (without the @) and its `directive @name(...) on ...` definition.
+  interface _DirectiveClass
+    def directive_name: () -> String
+    def definition: () -> String?
+  end
+
+  # Marker modules: the registry detects a class's capabilities by which of
+  # them it includes. Only FieldResolver and ArgBuilder change how a class is
+  # registered; the others document intent.
+  module Contracts
+    module Directive
+    end
+
+    # Its instances, built with (field_def, type_def, directive_node, opts),
+    # install the field's resolver in `define_resolver(target_type)`.
+    module FieldResolver
+      include Directive
+    end
+
+    # Its instances, built with (arg_node, directive_node), answer
+    # `handle_builder(relation, value)` with the constrained relation.
+    module ArgBuilder
+      include Directive
+    end
+
+    module FieldMiddleware
+      include Directive
+    end
+
+    module FieldManipulator
+      include Directive
+    end
+
+    module ArgManipulator
+      include Directive
+    end
+  end
+
+  class DirectiveRegistry
+    RESOLUTION_ORDER: Hash[String, Integer]
+    NAMED_RESOLVERS: Hash[String, Symbol]
+    SELF_DESCRIBING_RESOLVERS: Array[Symbol]
+    ARG_BUILDERS: Array[Symbol]
+    PASSIVE_DEFINITIONS: Hash[String, String]
+
+    def self.default: () -> DirectiveRegistry
+
+    # register(MyDirective) when the class answers `directive_name`, else
+    # register('name', MyDirective).
+    def self.register: (Class | String | Symbol name_or_klass, ?Class? klass) -> DirectiveRegistry
+
+    def initialize: () -> void
+    def register: (Class | String | Symbol name_or_klass, ?Class? klass) -> self
+    def register_defaults: () -> self
+    def register_definition: (String | Symbol name, String definition) -> self
+    def register_type_definition: (String | Symbol name, String definition) -> self
+    def register_manipulator: (_SdlManipulator manipulator) -> self
+
+    def resolution_class: (String | Symbol name) -> Class?
+    def resolution_order: (String | Symbol name) -> Integer
+    def wrapper?: (String | Symbol name) -> bool
+    def resolution_names: () -> Array[String]
+    def arg_builder_class: (String | Symbol name) -> Class?
+    def arg_builder_names: () -> Array[String]
+
+    # { "name" => "directive @name(...) on ..." }
+    def directive_definitions: () -> Hash[String, String]
+    # { "Name" => "enum Name { ... }" }
+    def type_definitions: () -> Hash[String, String]
+
+    attr_reader sdl_manipulators: Array[_SdlManipulator]
+    def manipulate_sdl: (String sdl) -> String
+  end
+
+  # Writes the SDL an IDE needs next to the app's own: `bin/rails lighthouse:ide_helper`.
+  module IdeHelper
+    DIRECTIVES_FILE: String
+    PROGRAMMATIC_TYPES_FILE: String
+
+    # Writes both files into `output_dir` and returns their paths.
+    def self?.write: (output_dir: path, ?sdl_folder: path?, ?registry: DirectiveRegistry) -> Array[String]
+    def self?.directives_sdl: (?String sdl, ?registry: DirectiveRegistry) -> String
+    def self?.programmatic_types_sdl: (String sdl, ?registry: DirectiveRegistry) -> String
+  end
+
+  module GraphQL
+    module DirectiveResolvers
+      # The base of the built-in field directives, and of a custom one:
+      # subclass it and implement `define_resolver`.
+      class BaseDirectiveResolver
+        # graphql-ruby's field and type definitions, and the directive's AST node.
+        @field_def: untyped
+        @type_def: untyped
+        @directive_node: untyped
+        @opts: Hash[Symbol, untyped]
+
+        def initialize: (untyped field_def, untyped type_def, untyped directive_node, ?Hash[Symbol, untyped] opts) -> void
+
+        # Install the field's resolver on `target_type_class` (a graphql-ruby type class).
+        def define_resolver: (untyped target_type_class) -> untyped
+
+        def apply_where_filters: (relation relation, untyped args) -> relation
+        def apply_arg_builders: (relation relation, arguments args_h) -> relation
+        def extract_relation_name_from_directive: (untyped arg_node) -> String?
+        def constantize_model: (String? name) -> Class?
+        def apply_scopes: (relation relation) -> relation
+
+        # The literal value of an argument of this directive.
+        def directive_arg: (String name) -> untyped
+        def resolver_method_name: () -> String
+        # The field's resolver so far, for a directive that wraps it.
+        def capture_inner: (untyped target_type_class) -> untyped
+        def install: (untyped target_type_class, untyped callable) -> untyped
+        # The model the directive acts on; raises DefinitionError when there is none.
+        def model_class: () -> Class
+      end
+
+      # Applies the field's @builder directives, in SDL order, to its relation.
+      class BuilderApplier
+        DEFINITION: String
+
+        def self.apply: (relation relation, untyped field_def_ast_node, arguments args, context ctx, untyped resolver_instance) -> relation
+        def self.apply_directive: (relation relation, untyped directive_node, arguments args, context ctx, untyped resolver_instance) -> relation
+        def self.extract_directive_arg: (untyped directive_node, String name) -> untyped
+      end
+    end
+
+    module Directives
+      module Arguments
+        # The base of the argument filters (@eq, @in, @orderBy, ...), and of a
+        # custom one: subclass it and implement `handle_builder`.
+        class Base
+          include Contracts::ArgBuilder
+
+          # graphql-ruby's AST nodes for the argument and the directive on it.
+          @arg_node: untyped
+          @directive_node: untyped
+
+          def initialize: (untyped arg_node, untyped directive_node) -> void
+
+          # Constrain the relation by the value the client gave the argument.
+          def handle_builder: (relation relation, untyped value) -> relation
+
+          private
+
+          # The directive's `key:`, else the argument's name in snake_case.
+          def column: () -> String
+          def arel_column: (relation relation) -> untyped
+        end
+      end
+    end
+  end
+end

data/sig/lighthouse/events.rbs

@@ -0,0 +1,122 @@
+# The events Lighthouse dispatches and the dispatcher an app listens through.
+# See docs/events.md.
+module Lighthouse
+  module Events
+    # Anything that responds to `call(event)`; what it returns means something
+    # to some events (BuildSchemaString, RegisterDirectiveNamespaces,
+    # BuildExtensionsResponse), and is ignored by the rest.
+    interface _Listener
+      def call: (untyped event) -> untyped
+    end
+
+    # Register a listener (a callable or a block) for an event class and its
+    # subclasses; answers the listener, for `forget`.
+    def self.listen: (Class event_class, ?_Listener? callable) ?{ (untyped event) -> untyped } -> _Listener
+
+    def self.forget: (_Listener listener) -> nil
+    def self.reset!: () -> nil
+
+    # Call the listeners of the event's class and ancestors in registration
+    # order; answers their non-nil return values.
+    def self.dispatch: (untyped event) -> Array[untyped]
+
+    # Whether dispatching an `event_class` event would reach a listener or an
+    # ActiveSupport::Notifications subscriber.
+    def self.listening?: (Class event_class) -> bool
+
+    # The ActiveSupport::Notifications name an event class is instrumented as.
+    def self.notification_name: (Class event_class) -> String
+
+    # The base of the events; a listener on it hears all of them.
+    class Event
+      attr_reader moment: Time
+
+      def initialize: () -> void
+    end
+
+    class StartRequest < Event
+      attr_reader request: untyped
+
+      def initialize: (untyped request) -> void
+    end
+
+    class StartOperationOrOperations < Event
+      attr_reader operation_or_operations: Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]]
+
+      def initialize: (Hash[Symbol, untyped] | Array[Hash[Symbol, untyped]] operation_or_operations) -> void
+    end
+
+    # A listener may answer SDL (a String) to append to the user schema.
+    class BuildSchemaString < Event
+      attr_reader user_schema: String
+
+      def initialize: (String user_schema) -> void
+    end
+
+    # A listener may answer a namespace (a Module or its name), or an Array of them.
+    class RegisterDirectiveNamespaces < Event
+    end
+
+    class ManipulateAST < Event
+      attr_accessor document_ast: untyped
+
+      def initialize: (untyped document_ast) -> void
+    end
+
+    class StartExecution < Event
+      attr_reader schema: untyped
+      attr_reader query: untyped
+      attr_reader variables: Hash[String, untyped]?
+      attr_reader operation_name: String?
+      attr_reader context: untyped
+
+      def initialize: (untyped schema, untyped query, Hash[String, untyped]? variables, String? operation_name, untyped context) -> void
+    end
+
+    # A listener may answer an ExtensionsResponse, or an Array of them.
+    class BuildExtensionsResponse < Event
+      attr_reader result: Hash[String, untyped]
+      attr_reader query_complexity: Integer?
+
+      def initialize: (Hash[String, untyped] result, Integer? query_complexity) -> void
+    end
+
+    class ManipulateResult < Event
+      attr_accessor result: Hash[String, untyped]
+
+      def initialize: (Hash[String, untyped] result) -> void
+    end
+
+    class EndExecution < Event
+      attr_reader result: Hash[String, untyped]
+
+      def initialize: (Hash[String, untyped] result) -> void
+    end
+
+    class EndOperationOrOperations < Event
+      attr_reader result_or_results: untyped
+
+      def initialize: (untyped result_or_results) -> void
+    end
+
+    class EndRequest < Event
+      attr_reader response: untyped
+
+      def initialize: (untyped response) -> void
+    end
+
+    class ValidateSchema < Event
+      attr_reader schema: untyped
+
+      def initialize: (untyped schema) -> void
+    end
+
+    # A key and content merged into the "extensions" of a result.
+    class ExtensionsResponse
+      attr_reader key: String | Symbol
+      attr_reader content: untyped
+
+      def initialize: (String | Symbol key, untyped content) -> void
+    end
+  end
+end