lighthouse-graphql 0.4.0 → 0.5.0

data/lib/lighthouse/resolver_dispatch.rb

@@ -4,7 +4,12 @@
 # namespaces follow graphql-ruby's contract — GraphQL::Schema::Resolver and
 # GraphQL::Schema::Mutation: `resolve(**args)` with `object` and `context`,
 # plus `ready?` / `authorized?` — exactly as in a graphql-ruby schema.
-# @field also accepts a plain callable, `call(object, args, context)`.
+# @field also accepts a plain callable, `call(object, args, context)`, which
+# gets the ResolveInfo as a fourth argument when it takes one.
+#
+# `method:` is the method after `@` in `@field(resolver: "Class@method")`: it
+# replaces `resolve` (keeping `ready?` / `authorized?`) on a resolver class, and
+# `call` on a plain class, as a class method or else an instance method.
 module Lighthouse::GraphQL::ResolverDispatch
   module_function
 
@@ -12,15 +17,35 @@ module Lighthouse::GraphQL::ResolverDispatch
     klass.is_a?(Class) && klass < ::GraphQL::Schema::Resolver
   end
 
-  def call(klass, field_def, obj, args, ctx)
-    if graphql_resolver?(klass)
-      kwargs = Lighthouse::Support::Arguments.prepare(field_def, args, ctx)
-      klass.new(object: obj, context: ctx, field: field_def).resolve_with_support(**kwargs)
-    elsif klass.respond_to?(:call)
-      klass.call(obj, args, ctx)
-    else
-      instance = klass.new
-      instance.respond_to?(:call) ? instance.call(obj, args, ctx) : instance.resolve(obj, args, ctx)
-    end
+  # `info`: the ResolveInfo of the field being resolved, which carries its
+  # object, arguments and context.
+  def call(klass, info, method: nil)
+    return call_resolver(klass, info, method) if graphql_resolver?(klass)
+
+    receiver = callable_receiver(klass, method || :call)
+    callable = receiver.method(method || (receiver.respond_to?(:call) ? :call : :resolve))
+    args = [info.object, info.arguments, info.context]
+    takes_info?(receiver, callable) ? callable.call(*args, info) : callable.call(*args)
+  end
+
+  def call_resolver(klass, info, method)
+    kwargs = Lighthouse::Support::Arguments.prepare(info.field, info.arguments, info.context)
+    instance = Lighthouse::GraphQL::ResolveInfo.attach(klass.new(object: info.object, context: info.context, field: info.field), info)
+    instance.define_singleton_method(:resolve) { |**values| public_send(method, **values) } if method
+    instance.resolve_with_support(**kwargs)
+  end
+
+  # The class itself when it answers `name` as a class method, else an instance.
+  def callable_receiver(klass, name)
+    klass.respond_to?(name) ? klass : klass.new
+  end
+
+  POSITIONAL = %i[req opt].freeze
+
+  # Does the callable take a fourth argument? A lambda's own parameters count,
+  # not Proc#call's (*args).
+  def takes_info?(receiver, callable)
+    params = receiver.is_a?(Proc) && callable.name == :call ? receiver.parameters : callable.parameters
+    params.any? { |type, _| type == :rest } || params.count { |type, _| POSITIONAL.include?(type) } >= 4
   end
 end

data/lib/lighthouse/scalar_coercion.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# How the values of an SDL scalar (`scalar DateTime`) are read from a query and
+# written to a response, as a graphql-ruby scalar class does it with
+# `coerce_input(value, context)` and `coerce_result(value, context)`. The class
+# is, in order:
+#
+# 1. the one `@scalar(class: "Name")` on the scalar names, looked up in
+#    Config.namespaces[:types] (nested names too) and then as written. PHP
+#    Lighthouse's directive.
+# 2. Its type class, Types::<Name>Type including Lighthouse::GraphQL::Type: a
+#    GraphQL::Schema::Scalar, as graphql-ruby's `rails g graphql:scalar` writes it.
+# 3. Lighthouse's own, for `scalar Upload` (Lighthouse::GraphQL::Upload).
+#
+# A scalar with none passes its values through unchanged. A class raising
+# GraphQL::CoercionError from coerce_input (or returning nil for a value) makes
+# the argument invalid, with that message, as in graphql-ruby.
+module Lighthouse::GraphQL::ScalarCoercion
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    The class that reads and writes this scalar's values: coerce_input(value, context) and
+    coerce_result(value, context), as a GraphQL::Schema::Scalar.
+    """
+    directive @scalar(class: String!) on SCALAR
+  GRAPHQL
+
+  module_function
+
+  # Give every SDL scalar that has a class its coercion. The class is looked up
+  # again on each value, so code reloading keeps working; `bases` is the
+  # schema's base_types[:scalar], which a type class must inherit from.
+  def apply(schema, base = nil)
+    schema.types.each_value do |type|
+      next unless type.kind.scalar? && type.ast_node
+
+      klass = class_for(type, base)
+      install(type, klass) if klass
+    end
+  end
+
+  # Scalars Lighthouse brings a class for, when nothing else names one.
+  BUILT_IN = { 'Upload' => 'Lighthouse::GraphQL::Upload' }.freeze
+
+  def class_for(scalar_type, base = nil)
+    directive_class(scalar_type) || type_class(scalar_type, base) || BUILT_IN[scalar_type.graphql_name]&.constantize
+  end
+
+  def directive_class(scalar_type)
+    directive = (scalar_type.ast_node.directives || []).find { |d| d.name == 'scalar' }
+    name = directive && Lighthouse::Support::DirectiveArgs.literal(directive, 'class')
+    return unless name
+
+    klass = Lighthouse::Support::ModelResolver.constantize(name, namespaces: Lighthouse::Config.namespaces[:types], nested: true)
+    return klass if klass.respond_to?(:coerce_input) && klass.respond_to?(:coerce_result)
+
+    raise Lighthouse::DefinitionError,
+          "@scalar(class: #{name.inspect}) on #{scalar_type.graphql_name} names no class with coerce_input(value, context) " \
+          'and coerce_result(value, context).'
+  end
+
+  def type_class(scalar_type, base)
+    klass = Lighthouse::GraphQL::Type.class_for(scalar_type.graphql_name, :scalar)
+    Lighthouse::GraphQL::ResolverBases.check!(klass, base, "the #{scalar_type.graphql_name} scalar") if klass
+    klass
+  end
+
+  def install(scalar_type, klass)
+    current = -> { klass.name ? klass.name.constantize : klass }
+    scalar_type.define_singleton_method(:coerce_input) { |value, ctx| current.call.coerce_input(value, ctx) }
+    scalar_type.define_singleton_method(:coerce_result) { |value, ctx| current.call.coerce_result(value, ctx) }
+  end
+end

data/lib/lighthouse/schema_cache.rb

@@ -72,7 +72,8 @@ module Lighthouse::GraphQL::SchemaCache
       registry.directive_definitions.sort,
       registry.type_definitions.sort,
       manipulators,
-      Lighthouse::Config.pagination_default_count
+      Lighthouse::Config.pagination_default_count,
+      Lighthouse::Support::Environment.current # @hide / @show
     ].inspect
   end
 

data/lib/lighthouse/schema_generator.rb

@@ -15,8 +15,8 @@ module Lighthouse::GraphQL::SchemaGenerator
       obj.respond_to?(field_name) ? obj.public_send(field_name) : nil
     end
 
-    def resolve_type(_abstract_type, _obj, _ctx)
-      nil
+    def resolve_type(abstract_type, obj, ctx)
+      Lighthouse::GraphQL::TypeResolution.resolve(ctx.respond_to?(:schema) && ctx.schema ? ctx.schema : schema, abstract_type, obj, ctx)
     end
 
     def coerce_input(_type, value, _ctx)
@@ -139,7 +139,9 @@ module Lighthouse::GraphQL::SchemaGenerator
       # Apply object-level federation directives to generated types so the
       # Apollo Federation helper can detect entities and add _entities.
       Lighthouse::GraphQL::FederationDirectives.apply(type)
-      type.fields.each_value { |field_def| process_field(type, field_def, root_kinds[type.graphql_name], bases) }
+      root_kind = root_kinds[type.graphql_name]
+      type_class = root_kind ? nil : Lighthouse::GraphQL::DirectiveResolvers::TypeMethodResolver.type_class(type.graphql_name, bases)
+      type.fields.each_value { |field_def| process_field(type, field_def, root_kind, bases, type_class) }
     end
 
     # @complexity, and paginated fields, give graphql-ruby's complexity analysis their cost.
@@ -151,6 +153,9 @@ module Lighthouse::GraphQL::SchemaGenerator
     # Every @broadcast must name a field of the Subscription type.
     Lighthouse::GraphQL::Broadcasting.validate!(schema)
 
+    # Unions, interfaces and scalars get the classes that resolve and coerce them.
+    Lighthouse::GraphQL::Type.apply(schema, bases.fetch(:types, {}))
+
     # return schema for convenience
     schema
   end
@@ -163,10 +168,11 @@ module Lighthouse::GraphQL::SchemaGenerator
 
   # A field's generated resolvers, then the runtime hooks that make
   # graphql-ruby reach them.
-  def process_field(type, field_def, root_kind, bases = {})
+  def process_field(type, field_def, root_kind, bases = {}, type_class = nil)
     return unless field_def.ast_node
 
-    apply_field_resolvers(type, field_def, field_def.ast_node.directives || [], root_kind, bases)
+    # Installed in resolution order (see FieldResolverStack).
+    Lighthouse::GraphQL::FieldResolverStack.apply(type, field_def, root_kind, bases: bases, type_class: type_class)
     Lighthouse::GraphQL::GeneratedResolvers.route_runtime_resolver(type, field_def)
     ensure_connection_extension(field_def)
   end
@@ -187,11 +193,6 @@ module Lighthouse::GraphQL::SchemaGenerator
     # ignore failures during post-processing
   end
 
-  # A field's resolvers, installed in resolution order (see FieldResolverStack).
-  def apply_field_resolvers(type, field_def, directives, root_kind, bases = {})
-    Lighthouse::GraphQL::FieldResolverStack.apply(type, field_def, directives, root_kind, bases: bases)
-  end
-
   # Scan SDL string for list-typed fields that carry relationship directives
   # and produce Connection/Edge types where missing. This is a lightweight
   # transformation that mirrors Lighthouse behavior: clients can declare

data/lib/lighthouse/schema_implementation.rb

@@ -27,14 +27,10 @@ class SchemaImplementation
     read_attribute(obj, field_name)
   end
 
-  def resolve_type(abstract_type, _obj, _ctx)
-    # Try to resolve to a Ruby type class under Types::<Name>Type
-    type_name = abstract_type.respond_to?(:name) ? abstract_type.name : abstract_type.to_s
-    begin
-      Object.const_get("Types::#{type_name}Type")
-    rescue StandardError
-      nil
-    end
+  # The object type of a union's or interface's value (see TypeResolution).
+  def resolve_type(abstract_type, obj, ctx)
+    schema = ctx.respond_to?(:schema) && ctx.schema ? ctx.schema : @schema
+    Lighthouse::GraphQL::TypeResolution.resolve(schema, abstract_type, obj, ctx)
   end
 
   def coerce_input(_type, value, _ctx)

data/lib/lighthouse/support/environment.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# The application's environment, for @hide and @show: Rails.env, else
+# RAILS_ENV or RACK_ENV, else "development".
+module Lighthouse::Support::Environment
+  module_function
+
+  def current
+    return Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env)
+
+    ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+  end
+end

data/lib/lighthouse/support/model_resolver.rb

@@ -26,14 +26,16 @@ module Lighthouse::Support::ModelResolver
   # `namespaces:` overrides the configured resolver_namespaces, e.g. with
   # Config.namespaces[:builders] to look a builder class up.
   # `fallback: false` skips the bare name, so `Resolvers::User` is never
-  # mistaken for the `User` model.
-  def constantize(name, namespaces: self.namespaces, fallback: true)
+  # mistaken for the `User` model. `nested: true` tries the namespaces before a
+  # name that already contains `::` too, so `Feeds::Home` is found as
+  # `Resolvers::Feeds::Home`; otherwise such a name is used as-is.
+  def constantize(name, namespaces: self.namespaces, fallback: true, nested: false)
     return nil unless name
 
     raw = name.to_s.strip
     return nil if raw.empty?
 
-    candidates_for(raw, namespaces, fallback: fallback).each do |candidate|
+    candidates_for(raw, namespaces, fallback: fallback, nested: nested).each do |candidate|
       klass = try_constantize(candidate)
       return klass if klass
     end
@@ -41,8 +43,8 @@ module Lighthouse::Support::ModelResolver
     nil
   end
 
-  def candidates_for(raw, namespaces = self.namespaces, fallback: true)
-    if raw.include?('::')
+  def candidates_for(raw, namespaces = self.namespaces, fallback: true, nested: false)
+    if raw.include?('::') && !nested
       [raw]
     else
       Array(namespaces).map { |ns| "#{ns}::#{raw}" } + (fallback ? [raw] : [])

data/lib/lighthouse/support/preload.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Eager loading for @with and @lazyLoad: ActiveRecord's preloader, over records
+# of any classes, with relation names as PHP Lighthouse writes them
+# ("comments.author" is comments, and each comment's author).
+module Lighthouse::Support::Preload
+  module_function
+
+  # ["comments.author", "tags"] -> [{ comments: :author }, :tags]
+  def associations(names)
+    Array(names).map do |name|
+      *path, last = name.to_s.split('.').map(&:to_sym)
+      path.reverse.reduce(last) { |nested, segment| { segment => nested } }
+    end
+  end
+
+  # Load `associations` into `records`, grouped by class; a class that has no
+  # such association is left alone. `scopes` (model scope names) narrow the
+  # loaded records, as Laravel's constrained eager loads do.
+  def records(records, associations, scopes = [])
+    records.grep(::ActiveRecord::Base).group_by(&:class).each do |klass, group|
+      own = associations.select { |association| klass.reflect_on_association(root(association)) }
+      own.each { |association| preload(klass, group, association, scopes) }
+    end
+    records
+  end
+
+  def root(association)
+    association.is_a?(Hash) ? association.keys.first : association
+  end
+
+  def preload(klass, records, association, scopes)
+    scope = scoped(klass, association, scopes)
+    preloader = ::ActiveRecord::Associations::Preloader
+    if preloader.method_defined?(:call)
+      preloader.new(records: records, associations: association, scope: scope).call # Rails >= 7
+    else
+      preloader.new.preload(records, association, scope)                             # Rails 6
+    end
+  end
+
+  # The scopes applied to the association's model, or nil for none.
+  def scoped(klass, association, scopes)
+    return if scopes.blank?
+
+    target = klass.reflect_on_association(root(association)).klass
+    scopes.reduce(target.all) { |relation, scope| relation.public_send(scope) }
+  end
+end

data/lib/lighthouse/type.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+# Hands a graphql-ruby type class to Lighthouse, as `include
+# Lighthouse::GraphQL::Subscription` does a subscription. The class keeps
+# graphql-ruby's folder structure and naming (app/graphql/types/post_type.rb,
+# Types::PostType for the SDL's Post type) and base classes, and does for the
+# SDL type of its name what it does in a graphql-ruby schema:
+#
+#   class Types::PostType < Types::BaseObject              # an object type
+#     include Lighthouse::GraphQL::Type
+#
+#     def reading_time = { words: object.body.to_s.split.size }
+#   end
+#
+#   class Types::SearchResultType < Types::BaseUnion       # a union
+#     include Lighthouse::GraphQL::Type
+#
+#     def self.resolve_type(object, context) = object.is_a?(Post) ? 'Post' : 'User'
+#   end
+#
+#   module Types::NamedType                                 # an interface
+#     include Types::BaseInterface
+#     include Lighthouse::GraphQL::Type
+#
+#     definition_methods do
+#       def resolve_type(object, context) = ...
+#     end
+#   end
+#
+#   class Types::DateTimeType < Types::BaseScalar           # a scalar
+#     include Lighthouse::GraphQL::Type
+#
+#     def self.coerce_input(value, context) = Time.iso8601(value)
+#     def self.coerce_result(value, context) = value.iso8601
+#   end
+#
+# An object type's methods resolve its fields that have no resolving
+# directive, with graphql-ruby's `object` (the parent), `context`, the
+# `dataload*` helpers, and the field's arguments as snake_case keywords. A
+# union's or interface's `resolve_type` picks the object type of a value (a
+# type name, or a type class such as Types::PostType). A scalar's
+# `coerce_input` / `coerce_result` convert its values. The SDL still declares
+# the types and their fields: the class only lends its behaviour, so `field`
+# declarations in it are ignored, and an object type's `authorized?` does not run.
+#
+# The model an object type resolves is the SDL's to say, with @model(class:).
+#
+# A Types::<Name>Type that does not include the concern is not Lighthouse's,
+# and is left alone.
+module Lighthouse::GraphQL::Type
+  extend ActiveSupport::Concern
+
+  # The kinds of graphql-ruby class the concern can be included in.
+  KINDS = {
+    object: ::GraphQL::Schema::Object,
+    union: ::GraphQL::Schema::Union,
+    scalar: ::GraphQL::Schema::Scalar,
+    interface: ::GraphQL::Schema::Interface
+  }.freeze
+
+  # :object, :union, :scalar or :interface for a graphql-ruby type class or
+  # interface module; nil for anything else.
+  def self.kind_of(mod)
+    return :interface if !mod.is_a?(Class) && mod.is_a?(Module) && mod.include?(KINDS[:interface])
+    return unless mod.is_a?(Class)
+
+    %i[object union scalar].find { |kind| mod < KINDS[kind] }
+  end
+
+  # The class of the SDL type `type_name` (`Types::PostType` for `Post`) in
+  # Config.namespaces[:types], when it includes the concern; nil otherwise. The
+  # class must be of the same `kind` as the SDL type.
+  def self.class_for(type_name, kind)
+    klass = Lighthouse::Support::ModelResolver.constantize("#{type_name}Type", namespaces: Lighthouse::Config.namespaces[:types],
+                                                                               fallback: false)
+    return unless klass.is_a?(Module) && klass.include?(self) && kind_of(klass)
+    return klass if kind_of(klass) == kind
+
+    raise Lighthouse::DefinitionError, "#{klass} is a type class of kind #{kind_of(klass)}, but #{type_name} is of kind #{kind} in the schema."
+  end
+
+  # What the SDL's types take from their classes and directives, once the
+  # schema is built: every @model names a model (ModelDirective), every @union /
+  # @interface class exists and every type class matches its kind and base
+  # (TypeResolution), and every scalar with a class reads and writes its values
+  # through it (ScalarCoercion). `bases`: the schema's base_types, by kind.
+  def self.apply(schema, bases = {})
+    Lighthouse::GraphQL::Directives::ModelDirective.validate!(schema)
+    Lighthouse::GraphQL::TypeResolution.validate!(schema, bases)
+    Lighthouse::GraphQL::ScalarCoercion.apply(schema, bases[:scalar])
+    Lighthouse::GraphQL::EnumDirective.apply(schema)
+  end
+
+  included do
+    unless Lighthouse::GraphQL::Type.kind_of(self)
+      raise Lighthouse::DefinitionError,
+            "#{self} includes Lighthouse::GraphQL::Type, which is for graphql-ruby types: a subclass of GraphQL::Schema::Object, " \
+            'Union or Scalar, or a module including GraphQL::Schema::Interface (class Types::PostType < Types::BaseObject).'
+    end
+  end
+end

data/lib/lighthouse/type_resolution.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Which object type a value of a union or interface is: graphql-ruby asks the
+# schema (its `resolve_type`) each time a field returns one. In order:
+#
+# 1. `@union(resolveType: "Name")` / `@interface(resolveType: "Name")` on the
+#    SDL type names a class, looked up in Config.namespaces[:types] (nested
+#    names too) and then as written, with `resolve_type(object, context)` or
+#    `call(object, context)`. PHP Lighthouse's directives.
+# 2. Its type class, Types::<Name>Type including Lighthouse::GraphQL::Type: a
+#    union's `self.resolve_type(object, context)`, or an interface's
+#    `definition_methods { def resolve_type(object, context) }`, as in graphql-ruby.
+# 3. The default, as PHP Lighthouse's: a Hash's `__typename`; else the type
+#    named after the object's class, or one of its superclasses (STI); else the
+#    type whose @model names the object's model (`type Article @model(class: "Post")`).
+#
+# A class returns a type name, the SDL type, or a type class (Types::PostType),
+# which stands for the SDL type of its graphql_name; or, as graphql-ruby allows,
+# [type, value] to resolve the type's fields on `value`. nil falls through to the
+# next step. A value no step resolves, or one resolved to a type the union or
+# interface does not include, raises Lighthouse::DefinitionError.
+module Lighthouse::GraphQL::TypeResolution
+  DEFINITIONS = {
+    'union' => <<~GRAPHQL.chomp,
+      """
+      The class that picks the object type of this union's values: `resolve_type(object, context)`
+      or `call(object, context)`, returning a type name or a type class.
+      """
+      directive @union(resolveType: String!) on UNION
+    GRAPHQL
+    'interface' => <<~GRAPHQL.chomp
+      """
+      The class that picks the object type of this interface's values: `resolve_type(object, context)`
+      or `call(object, context)`, returning a type name or a type class.
+      """
+      directive @interface(resolveType: String!) on INTERFACE
+    GRAPHQL
+  }.freeze
+
+  DIRECTIVES = DEFINITIONS.keys.freeze
+
+  module_function
+
+  # The object type, or [object type, value] when a class answered with a
+  # value to resolve the fields on instead of `object` (as graphql-ruby allows).
+  def resolve(schema, abstract_type, object, context)
+    answer = custom(abstract_type, object, context)
+    answer, value = answer if answer.is_a?(Array) && answer.size == 2
+    type = type_named(schema, answer) || default(schema, abstract_type, object)
+    unless type && schema.possible_types(abstract_type).include?(type)
+      raise Lighthouse::DefinitionError, unresolved_message(schema, abstract_type, object, type)
+    end
+
+    value.nil? ? type : [type, value]
+  end
+
+  # What the directive's class or the type class says, or nil.
+  def custom(abstract_type, object, context)
+    resolver = directive_class(abstract_type) || type_class(abstract_type)
+    return unless resolver
+
+    resolver.respond_to?(:resolve_type) ? resolver.resolve_type(object, context) : resolver.call(object, context)
+  end
+
+  def default(schema, abstract_type, object)
+    candidates = schema.possible_types(abstract_type)
+    by_name = candidates.index_by(&:graphql_name)
+
+    typename = typename_of(object)
+    return by_name[typename] if typename
+
+    class_chain(object.class).each { |name| return by_name[name] if by_name.key?(name) }
+    candidates.find { |type| model_of(type)&.then { |model| object.is_a?(model) } }
+  end
+
+  # Fail at build time, not on the first query: every class a @union /
+  # @interface names exists and answers, and every type class matches its kind.
+  # `bases`: the schema's base_types, by kind, that type classes inherit from.
+  def validate!(schema, bases = {})
+    schema.types.each_value do |type|
+      next unless type.kind.union? || type.kind.interface?
+
+      directive_class(type)
+      kind = type.kind.union? ? :union : :interface
+      klass = Lighthouse::GraphQL::Type.class_for(type.graphql_name, kind)
+      Lighthouse::GraphQL::ResolverBases.check!(klass, bases[kind], "the #{type.graphql_name} #{kind}") if klass
+    end
+  end
+
+  # The SDL type a resolver's answer stands for: a name, a type, or a type class.
+  def type_named(schema, answer)
+    return if answer.nil?
+
+    schema.get_type(answer.respond_to?(:graphql_name) ? answer.graphql_name : answer.to_s)
+  end
+
+  def directive_class(abstract_type)
+    directive, name = resolve_type_directive(abstract_type)
+    return unless name
+
+    klass = Lighthouse::Support::ModelResolver.constantize(name, namespaces: Lighthouse::Config.namespaces[:types], nested: true)
+    return klass if klass.respond_to?(:resolve_type) || klass.respond_to?(:call)
+
+    raise Lighthouse::DefinitionError,
+          "@#{directive.name}(resolveType: #{name.inspect}) on #{abstract_type.graphql_name} names no class with resolve_type(object, context) " \
+          'or call(object, context).'
+  end
+
+  # The @union / @interface on the type and the class name it gives, or nil.
+  def resolve_type_directive(abstract_type)
+    directive = (abstract_type.ast_node&.directives || []).find { |d| DIRECTIVES.include?(d.name) }
+    [directive, Lighthouse::Support::DirectiveArgs.literal(directive, 'resolveType')] if directive
+  end
+
+  def type_class(abstract_type)
+    kind = abstract_type.kind.union? ? :union : :interface
+    klass = Lighthouse::GraphQL::Type.class_for(abstract_type.graphql_name, kind)
+    klass if klass.respond_to?(:resolve_type)
+  end
+
+  def typename_of(object)
+    return unless object.is_a?(Hash)
+
+    (object['__typename'] || object[:__typename])&.to_s
+  end
+
+  # Admin, User, ApplicationRecord, ... for an Admin < User record.
+  def class_chain(klass)
+    names = []
+    while klass
+      names << klass.name.demodulize if klass.name
+      klass = klass.superclass
+    end
+    names
+  end
+
+  def model_of(type)
+    Lighthouse::GraphQL::Directives::ModelDirective.declared_model(type)
+  end
+
+  def unresolved_message(schema, abstract_type, object, type)
+    possible = schema.possible_types(abstract_type).map(&:graphql_name).join(' | ')
+    kind = abstract_type.kind.union? ? 'union' : 'interface'
+    return "#{abstract_type.graphql_name} resolved a #{object.class} to #{type.graphql_name}, which is not one of its types (#{possible})." if type
+
+    "Lighthouse could not tell the type of a #{object.class} in the #{kind} #{abstract_type.graphql_name} (#{possible}): " \
+      "name a type after its class, map one to it with @model(class: \"#{object.class}\"), or resolve it in " \
+      "Types::#{abstract_type.graphql_name}Type.resolve_type or with @#{kind}(resolveType:)."
+  end
+end

data/lib/lighthouse/upload.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# The `Upload` scalar: a file a client sends with a multipart request (the
+# GraphQL multipart request specification, MultipartRequest). `scalar Upload`
+# in the SDL reads its values through it unless the SDL or a type class names
+# another class. The resolver gets the uploaded file (an
+# ActionDispatch::Http::UploadedFile in Rails): attach it to a model
+# (`avatar: Upload` with @create on a model with has_one_attached :avatar), or
+# store it with @upload.
+class Lighthouse::GraphQL::Upload < GraphQL::Schema::Scalar
+  graphql_name 'Upload'
+
+  def self.coerce_input(value, _context)
+    return value if file?(value)
+
+    raise ::GraphQL::CoercionError, 'Could not get uploaded file, be sure to conform to the GraphQL multipart request specification.'
+  end
+
+  def self.coerce_result(_value, _context)
+    raise ::GraphQL::Error, 'The Upload scalar can only be used as an argument, not returned.'
+  end
+
+  def self.file?(value)
+    value.respond_to?(:read) && (value.respond_to?(:original_filename) || value.respond_to?(:path))
+  end
+end

data/lib/lighthouse/upload_store.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+# Where @upload puts a file, by default: an ActiveStorage blob, on the service
+# `disk` names (the default service without it), its key under `path`. The
+# argument then holds the blob's signed id, which a has_one_attached /
+# has_many_attached attribute attaches, and which ActiveStorage::Blob.find_signed
+# finds. Config.upload_store takes another `call(file, disk:, path:, public:)`.
+module Lighthouse::GraphQL::UploadStore
+  module_function
+
+  def call(file, disk: nil, path: nil, public: false) # rubocop:disable Lint/UnusedMethodArgument -- public is the service's setting
+    unless defined?(::ActiveStorage::Blob)
+      raise Lighthouse::DefinitionError,
+            '@upload stores files with ActiveStorage: install it (bin/rails active_storage:install), or set Config.upload_store.'
+    end
+
+    attributes = { io: file, filename: filename(file), content_type: file.try(:content_type), key: key(path) }
+    attributes[:service_name] = disk if disk
+    ::ActiveStorage::Blob.create_and_upload!(**attributes.compact).signed_id
+  end
+
+  def filename(file)
+    file.respond_to?(:original_filename) ? file.original_filename : File.basename(file.path)
+  end
+
+  def key(path)
+    prefix = path.to_s.delete_prefix('/').delete_suffix('/')
+    prefix.empty? ? nil : "#{prefix}/#{SecureRandom.base36(28)}"
+  end
+end

data/sig/lighthouse/directives.rbs

@@ -104,8 +104,9 @@ module Lighthouse
         # 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
+        # `ctx`: the query's context, which @builder on an argument receives.
+        def apply_where_filters: (relation relation, untyped args, ?context? ctx) -> relation
+        def apply_arg_builders: (relation relation, arguments args_h, ?context? ctx) -> relation
         def extract_relation_name_from_directive: (untyped arg_node) -> String?
         def constantize_model: (String? name) -> Class?
         def apply_scopes: (relation relation) -> relation