lighthouse-graphql 0.5.0 → 0.7.0

data/lib/lighthouse/directive_resolvers/builder_applier.rb

@@ -2,8 +2,11 @@
 
 require_relative 'base'
 
-# The field-level query directives, in SDL order: @builder classes, and
-# @whereAuth, which keeps the records the signed-in user owns. @builder on an
+# The field-level query directives, in SDL order, as PHP Lighthouse's field
+# builder directives: @builder classes, @whereAuth, which keeps the records the
+# signed-in user owns, and the registry's FieldBuilder directives (@orderBy on a
+# field). They apply after the argument directives (apply_where_filters), so
+# a builder's order breaks the ties of the client's orderBy. @builder on an
 # argument is applied with the other argument directives (apply_argument).
 #
 # A builder is `class:` and `method:` (default `call`), or PHP Lighthouse's
@@ -52,15 +55,27 @@ class Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier
   def self.apply(relation, field_def_ast_node, args, ctx, resolver_instance)
     return relation unless field_def_ast_node&.directives
 
-    field_def_ast_node.directives.each do |directive_node|
+    registry = Lighthouse::DirectiveRegistry.default
+    field_def_ast_node.directives.reduce(relation) do |acc, directive_node|
       case directive_node.name
-      when 'builder' then relation = apply_directive(relation, directive_node, args, ctx, resolver_instance)
-      when 'whereAuth' then relation = where_auth(relation, directive_node, ctx)
+      when 'builder' then apply_directive(acc, directive_node, args, ctx, resolver_instance)
+      when 'whereAuth' then where_auth(acc, directive_node, ctx)
+      else field_builder(registry, acc, field_def_ast_node, directive_node)
       end
     end
+  end
 
-    relation
+  # Does the field carry a query directive of its own?
+  def self.any?(field_def_ast_node)
+    registry = Lighthouse::DirectiveRegistry.default
+    (field_def_ast_node&.directives || []).any? { |d| DEFINITIONS.key?(d.name) || registry.field_builder_class(d.name) }
+  end
+
+  def self.field_builder(registry, relation, field_def_ast_node, directive_node)
+    builder_class = registry.field_builder_class(directive_node.name)
+    builder_class ? builder_class.new(field_def_ast_node, directive_node).handle_field_builder(relation) : relation
   end
+  private_class_method :field_builder
 
   # The records whose `relation:` links them to the signed-in user; none for a guest.
   def self.where_auth(relation, directive_node, ctx)

data/lib/lighthouse/directive_resolvers/cache_resolvers.rb

@@ -3,7 +3,7 @@
 require_relative 'base'
 
 module Lighthouse::GraphQL::DirectiveResolvers
-  # @cache — keep a field's resolved value in Config.cache_store (Rails.cache).
+  # @cache — keep a field's resolved value in Rails.cache (Caching.store).
   #
   # The key covers the parent type and its key (the field marked @cacheKey,
   # else the first `ID` field; none on Query/Mutation), the field, and its

data/lib/lighthouse/directive_resolvers/count_resolver.rb

@@ -43,7 +43,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::CountDirectiveResolver < Lighthou
 
     args_h = arguments.respond_to?(:to_h) ? arguments.to_h : {}
     relation = apply_scopes(relation)
-    relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, @field_def.ast_node, args_h, ctx, self)
     relation = apply_where_filters(relation, args_h, ctx)
     relation.count
   end

data/lib/lighthouse/directive_resolvers/first_resolver.rb

@@ -14,7 +14,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::FirstDirectiveResolver < Lighthou
     method_name = "resolve_field_#{@field_def.name}"
     model_name_static = directive_arg('model') || field_type_name
     resolver_instance = self
-    field_ast_node = @field_def.ast_node
 
     resolver = lambda do |_obj, arguments, ctx|
       model_class = resolver_instance.constantize_model(model_name_static)
@@ -22,7 +21,6 @@ class Lighthouse::GraphQL::DirectiveResolvers::FirstDirectiveResolver < Lighthou
 
       args_h = arguments.respond_to?(:to_h) ? arguments.to_h : {}
       relation = resolver_instance.apply_scopes(model_class.all)
-      relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args_h, ctx, resolver_instance)
       relation = resolver_instance.apply_where_filters(relation, args_h, ctx)
       relation.first
     end

data/lib/lighthouse/directive_resolvers/global_id_resolver.rb

@@ -51,7 +51,9 @@ class Lighthouse::GraphQL::DirectiveResolvers::GlobalIdDirectiveResolver < Light
 
     install(target_type_class, lambda do |obj, args, ctx|
       id = inner.call(obj, args, ctx)
-      id.nil? ? nil : Lighthouse::Config.global_id.encode(type_name, id)
+      next if id.nil?
+
+      Lighthouse::GraphQL::GlobalId.encode_field(target_type_class, obj, id, ctx) || Lighthouse::Config.global_id.encode(type_name, id)
     end)
   end
 end

data/lib/lighthouse/directive_resolvers/paginate_resolver.rb

@@ -72,10 +72,9 @@ class Lighthouse::GraphQL::DirectiveResolvers::PaginateDirectiveResolver < Light
 
   public
 
-  # `scopes:`, @builder and the argument filters, on one relation or a RelationBatch.
+  # `scopes:`, the argument filters and @builder, on one relation or a RelationBatch.
   def decorate_relation(relation, args, ctx)
-    relation = Lighthouse::GraphQL::DirectiveResolvers::BuilderApplier.apply(apply_scopes(relation), @field_def.ast_node, args, ctx, self)
-    apply_where_filters(relation, args, ctx)
+    apply_where_filters(apply_scopes(relation), args, ctx)
   end
 
   protected

data/lib/lighthouse/directive_resolvers/throttle_resolver.rb

@@ -1,17 +1,35 @@
 # frozen_string_literal: true
 
+require 'active_support/duration'
+require 'active_support/notifications'
 require_relative 'base'
 
-# @throttle — rate-limit a field per client, as PHP Lighthouse's directive (and
-# Laravel's ThrottleRequests): at most `maxAttempts` calls every `decayMinutes`,
-# counted in Config.cache_store. A client is the signed-in user, else the
-# context's :remote_ip (Lighthouse::GraphQL::Controller sets it), else "guest".
-# Past the limit the field fails with "Rate limit for Query.x exceeded. Try
-# again later." Outermost: refused calls never reach @guard or the resolver.
+# @throttle — Rails' `rate_limit` on one field: at most `maxAttempts` calls (its
+# to:) every `decayMinutes` (its within:), counted as ActionController::RateLimiting
+# counts them, with its options:
+#
+#   by:      who the client is, as rate_limit's by: a path in the context, as
+#            @inject's ("current_user.id"); the client's IP by default.
+#   with:    a method of the controller to call past the limit, as rate_limit's
+#            with:. One that renders or redirects ends the request with its
+#            response, as a before_action that renders does; one that returns lets
+#            the call through. Without it, rate_limit's default: raise
+#            ActionController::TooManyRequests, which Rails answers with a 429
+#            (`head :too_many_requests` on a Rails without it, 7.2). Without Action
+#            Pack at all, the field fails: "Rate limit for Query.x exceeded. Try again later."
+#   name:    as rate_limit's: the field by default (Query.x). Fields, and the
+#            controller's own `rate_limit`, of the same name count together.
+#   prefix:  as rate_limit's scope: the controller's path by default.
+#
+# The count lives in the controller's cache_store (config.action_controller.cache_store,
+# Rails.cache unless set), under rate_limit's key, and a refused call is instrumented
+# as rate_limit's (rate_limit.action_controller). The controller concern puts the
+# controller in the context (:lighthouse_controller); outside one, the count lives in
+# Rails.cache, with no scope. Outermost: refused calls never reach @guard or the resolver.
 #
 #   type Mutation {
 #     login(email: String!, password: String!): User @throttle(maxAttempts: 5)
-#     search(term: String!): [Post!]! @throttle(name: "search", maxAttempts: 30, decayMinutes: 0.5)
+#     search(term: String!): [Post!]! @throttle(maxAttempts: 30, decayMinutes: 0.5, by: "current_user.id")
 #   }
 class Lighthouse::GraphQL::DirectiveResolvers::ThrottleDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
   def self.directive_name = 'throttle'
@@ -19,17 +37,21 @@ class Lighthouse::GraphQL::DirectiveResolvers::ThrottleDirectiveResolver < Light
   def self.definition
     <<~GRAPHQL.chomp
       """
-      Sets rate limit to access the field. Does the same as ThrottleRequests Laravel Middleware.
+      Sets rate limit to access the field, as Rails' rate_limit does for an action.
       """
       directive @throttle(
-        "A name shared by the fields that count together. Defaults to the field."
+        "As rate_limit's name: fields, and the controller's own rate_limit, of the same name count together. Defaults to the field."
         name: String
         "Maximum number of attempts in a specified time interval."
         maxAttempts: Int = 60
         "Time in minutes to reset attempts."
         decayMinutes: Float = 1.0
-        "Prefix to distinguish several field groups."
+        "As rate_limit's scope: what the count is shared across. Defaults to the controller's path."
         prefix: String
+        "As rate_limit's by: who the client is, a path in the context (\\"current_user.id\\"). Defaults to the client's IP."
+        by: String
+        "As rate_limit's with: the controller's method to call past the limit. Defaults to rate_limit's: a 429."
+        with: String
       ) on FIELD_DEFINITION
     GRAPHQL
   end
@@ -38,22 +60,24 @@ class Lighthouse::GraphQL::DirectiveResolvers::ThrottleDirectiveResolver < Light
     me = self
     inner = capture_inner(target_type_class)
     location = "#{target_type_class.graphql_name}.#{@field_def.name}"
-    bucket = "#{directive_arg('prefix')}#{directive_arg('name') || location}"
-    max_attempts = directive_arg('maxAttempts') || 60
-    decay = ((directive_arg('decayMinutes') || 1.0) * 60).ceil
+    limit = {
+      to: directive_arg('maxAttempts') || 60, within: ActiveSupport::Duration.build(((directive_arg('decayMinutes') || 1.0) * 60).ceil),
+      by: directive_arg('by'), with: directive_arg('with'), name: directive_arg('name') || location, scope: directive_arg('prefix')
+    }
 
     install(target_type_class, lambda do |obj, args, ctx|
-      me.hit!(bucket, ctx, max_attempts, decay, location)
+      me.hit!(limit, ctx, location)
       inner.call(obj, args, ctx)
     end)
   end
 
-  def hit!(bucket, ctx, max_attempts, decay, location)
-    key = "lighthouse:throttle:#{bucket}:#{client(ctx)}"
-    store = Lighthouse::GraphQL::Caching.store
-    self.class.warn_null_store(location) if store.is_a?(::ActiveSupport::Cache::NullStore)
-    attempts = store.increment(key, 1, expires_in: decay) || (store.write(key, 1, expires_in: decay) && 1)
-    raise ::GraphQL::ExecutionError, "Rate limit for #{location} exceeded. Try again later." if attempts > max_attempts
+  # ActionController::RateLimiting#rate_limiting, for one call of the field.
+  def hit!(limit, ctx, location)
+    controller = ctx[:lighthouse_controller]
+    key = { scope: limit[:scope] || controller&.controller_path, name: limit[:name], by: client(limit, ctx) }
+    cache_key = ['rate-limit', *key.values].compact.join(':')
+    count = increment(store(controller), cache_key, limit[:within], location)
+    refuse(controller, limit, location, key.merge(count: count, cache_key: cache_key)) if count && count > limit[:to]
   end
 
   # A :null_store keeps no count, so the limit never applies: say so, once per field.
@@ -61,17 +85,52 @@ class Lighthouse::GraphQL::DirectiveResolvers::ThrottleDirectiveResolver < Light
     @warned ||= Set.new
     return unless @warned.add?(location)
 
-    message = "Lighthouse: @throttle on #{location} counts nothing, as the cache store is a :null_store. Set Config.cache_store."
+    message = "Lighthouse: @throttle on #{location} counts nothing, as the cache store is a :null_store. " \
+              'Set config.action_controller.cache_store (or config.cache_store), as for Rails\' rate_limit.'
     defined?(Rails) && Rails.logger ? Rails.logger.warn(message) : warn(message)
   end
 
   private
 
-  def client(ctx)
-    user = Lighthouse::Support::Authorization.authenticated_user(ctx)
-    return "user:#{user.respond_to?(:id) ? user.id : user}" if user
+  # rate_limit's by: the value at `by`'s path in the context, else the client's IP.
+  def client(limit, ctx)
+    limit[:by] ? Lighthouse::Support::Arguments.dig(ctx, limit[:by]).first : ctx[:remote_ip]
+  end
+
+  # Where rate_limit counts: the controller's cache_store; Rails.cache outside one.
+  def store(controller)
+    controller.respond_to?(:cache_store) ? controller.cache_store : Lighthouse::GraphQL::Caching.store
+  end
+
+  # The count after this call. A store whose increment does not create the key
+  # (ActiveSupport before 7.1) starts it with a write.
+  def increment(store, key, within, location)
+    self.class.warn_null_store(location) if store.is_a?(::ActiveSupport::Cache::NullStore)
+    store.increment(key, 1, expires_in: within) || (store.write(key, 1, expires_in: within) && 1)
+  end
+
+  # Past the limit: instrumented as rate_limit's, around `with`, after which a
+  # response `with` performed ends the request, as a before_action's would.
+  def refuse(controller, limit, location, counted)
+    payload = { request: controller&.request, to: limit[:to], within: limit[:within], **counted }
+    ActiveSupport::Notifications.instrument('rate_limit.action_controller', payload) { limited(controller, limit[:with], location) }
+    raise Lighthouse::GraphQL::Controller::Performed if controller&.performed?
+  end
+
+  # The controller's `with` method, else rate_limit's default `with`.
+  def limited(controller, with, location)
+    return call_with(controller, with, location) if with && controller
+    raise ::ActionController::TooManyRequests if defined?(::ActionController::TooManyRequests)
+    return controller.head(:too_many_requests) if controller
+
+    raise ::GraphQL::ExecutionError, "Rate limit for #{location} exceeded. Try again later."
+  end
+
+  def call_with(controller, with, location)
+    unless controller.respond_to?(with, true)
+      raise Lighthouse::DefinitionError, "@throttle(with: \"#{with}\") on #{location}: #{controller.class} has no method #{with}."
+    end
 
-    ip = ctx.respond_to?(:[]) ? ctx[:remote_ip] : nil
-    ip ? "ip:#{ip}" : 'guest'
+    controller.send(with)
   end
 end

data/lib/lighthouse/directive_resolvers/type_method_resolver.rb

@@ -10,15 +10,18 @@ require_relative 'base'
 # `object` (the parent), `context`, the `dataload*` helpers, and the field's
 # arguments as snake_case keywords. A field with a resolving directive never
 # reaches it, and one whose name the class does not define is read off the
-# object as before. Not a directive: FieldResolverStack installs it on types
-# other than the root ones.
+# object as before. Not a directive: FieldResolverStack installs it, on the
+# root types too (Types::QueryType#latest_posts for Query.latestPosts, before
+# the conventional Resolvers::LatestPosts).
 class Lighthouse::GraphQL::DirectiveResolvers::TypeMethodResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
   # The class of the SDL type `type_name` (`Types::PostType` for `Post`) in
   # Config.namespaces[:types], when it includes Lighthouse::GraphQL::Type; nil
   # otherwise, so a type class that does not opt in is left alone. It must
   # inherit from the schema's base_types[:object] (in `bases`, ResolverBases)
-  # when one is given.
-  def self.type_class(type_name, bases = {})
+  # when one is given. A root type's class is the one it is built on (RootTypes).
+  def self.type_class(type_name, bases = {}, root_kind = nil)
+    return Lighthouse::GraphQL::RootTypes.type_class(root_kind, bases[:roots]) if root_kind
+
     klass = lookup(type_name)
     return unless klass
 
@@ -38,9 +41,12 @@ class Lighthouse::GraphQL::DirectiveResolvers::TypeMethodResolver < Lighthouse::
     name if klass.public_method_defined?(name) && !::GraphQL::Schema::Object.public_method_defined?(name)
   end
 
-  def initialize(field_def, type_def, method_name)
+  # `root_class`: the root type class the type is built on (RootTypes), used as
+  # it is; any other class is looked up by the type's name on each call.
+  def initialize(field_def, type_def, method_name, root_class = nil)
     super(field_def, type_def, nil)
     @method_name = method_name
+    @root_class = root_class
   end
 
   def define_resolver(target_type_class)
@@ -59,7 +65,7 @@ class Lighthouse::GraphQL::DirectiveResolvers::TypeMethodResolver < Lighthouse::
   # it no longer defines the method, the field is read as before. A parent that
   # is not a record of the type's @model is reported, and the field resolves to nil.
   def resolve_with_type(inner, obj, args, ctx)
-    klass = self.class.lookup(@type_def.graphql_name)
+    klass = @root_class || self.class.lookup(@type_def.graphql_name)
     return inner.call(obj, args, ctx) unless klass&.public_method_defined?(@method_name)
 
     model = Lighthouse::GraphQL::Directives::ModelDirective.declared_model(@type_def)

data/lib/lighthouse/directives/arguments/more_filters.rb

@@ -174,7 +174,7 @@ module Lighthouse::GraphQL::Directives::Arguments
           Typically, this option should only be used for root fields,
           as it may cause wrong results with batched relation queries.
           """
-          builder: Boolean! = false
+          builder: Boolean = false
         ) on ARGUMENT_DEFINITION | FIELD_DEFINITION
       GRAPHQL
     end

data/lib/lighthouse/directives/arguments/order_by.rb

@@ -2,47 +2,211 @@
 
 require_relative 'base'
 
-# @orderBy — sort the result by one or more columns.
+# @orderBy, as PHP Lighthouse's: on an argument, the client orders the result
+# by one or more clauses; on a field, the result is always in that order.
 #
-# The client value is a list of clauses, each `{ column:, order: }`
-# (also accepts `{ field:, direction: }`). Clauses apply in order, so
-# `[{column: NAME, order: ASC}, {column: AGE, order: DESC}]` sorts by
-# name then age.
+#   type Query {
+#     posts(orderBy: _ @orderBy(columns: ["posted_at", "title"])): [Post!]! @all
+#     users(orderBy: _ @orderBy(relations: [{ relation: "posts" }])): [User!]! @all
+#     latestPosts: [Post!]! @all @orderBy(column: "posted_at", direction: DESC)
+#   }
+#
+#   { posts(orderBy: [{ column: POSTED_AT, order: DESC }, { column: TITLE, order: ASC }]) { title } }
+#   { users(orderBy: [{ posts: { aggregate: COUNT }, order: DESC }]) { name } }
+#
+# An argument written with the `_` placeholder gets the types generated for
+# it (Query.posts(orderBy:) -> [QueryPostsOrderByOrderByClause!]):
+#
+# - no `columns:` / `columnsEnum:` / `relations:`: the shared OrderByClause, any column;
+# - `columns:` / `columnsEnum:`: <QualifiedArgType>OrderByClause, its column one of the enum;
+# - `relations:`: <QualifiedArgType>RelationOrderByClause, whose clauses name
+#   either a column or a relation's aggregate (COUNT, or AVG/MIN/MAX/SUM of a column).
+#
+# A relation's aggregate is computed per record in a LEFT JOIN on a grouped
+# subquery, so records without related ones are ordered too (a COUNT of 0).
 class Lighthouse::GraphQL::Directives::Arguments::OrderBy < Lighthouse::GraphQL::Directives::Arguments::Base
+  include Lighthouse::Contracts::ArgManipulator
+  include Lighthouse::Contracts::FieldBuilder
+
+  # The Arel node of each OrderByRelation*AggregateFunction value (Arel::Nodes::<name>).
+  AGGREGATES = { 'count' => :Count, 'avg' => :Avg, 'min' => :Min, 'max' => :Max, 'sum' => :Sum }.freeze
+
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    Sort a result list by one or more given columns.
+    """
+    directive @orderBy(
+      """
+      Restrict the allowed column names to a well-defined list.
+      This improves introspection capabilities and security.
+      Mutually exclusive with `columnsEnum`.
+      Only used when the directive is added on an argument.
+      """
+      columns: [String!]
+
+      """
+      Use an existing enumeration type to restrict the allowed columns to a predefined list.
+      This allows you to re-use the same enum for multiple fields.
+      Mutually exclusive with `columns`.
+      Only used when the directive is added on an argument.
+      """
+      columnsEnum: String
+
+      """
+      Allow clients to sort by aggregates on relations.
+      Only used when the directive is added on an argument.
+      """
+      relations: [OrderByRelation!]
+
+      """
+      The database column for which the order by clause will be applied on.
+      Only used when the directive is added on a field.
+      """
+      column: String
+
+      """
+      The direction of the order by clause.
+      Only used when the directive is added on a field.
+      """
+      direction: OrderByDirection = ASC
+    ) on ARGUMENT_DEFINITION | FIELD_DEFINITION
+  GRAPHQL
+
+  TYPE_DEFINITIONS = {
+    'OrderByDirection' => <<~GRAPHQL.chomp,
+      """
+      Options for the `direction` argument of `@orderBy`.
+      """
+      enum OrderByDirection {
+        """
+        Sort in ascending order.
+        """
+        ASC
+
+        """
+        Sort in descending order.
+        """
+        DESC
+      }
+    GRAPHQL
+    'OrderByRelation' => <<~GRAPHQL.chomp
+      """
+      Options for the `relations` argument of `@orderBy`.
+      """
+      input OrderByRelation {
+        """
+        Name of the relation.
+        """
+        relation: String!
+
+        """
+        Restrict the allowed column names to a well-defined list.
+        This improves introspection capabilities and security.
+        Mutually exclusive with `columnsEnum`.
+        """
+        columns: [String!]
+
+        """
+        Use an existing enumeration type to restrict the allowed columns to a predefined list.
+        This allows you to re-use the same enum for multiple fields.
+        Mutually exclusive with `columns`.
+        """
+        columnsEnum: String
+      }
+    GRAPHQL
+  }.freeze
+
   def self.directive_name = 'orderBy'
-  def self.definition = 'directive @orderBy(columns: [String!], relations: [String!]) on ARGUMENT_DEFINITION | FIELD_DEFINITION'
+
+  def self.definition = DEFINITION
+
+  def self.type_definitions = TYPE_DEFINITIONS
+
+  # --- Schema: the argument's types (Lighthouse::OrderBy::Types) ------------
+
+  def manipulate_arg_definition(document_ast, field, type)
+    Lighthouse::OrderBy::Types.new(document_ast, @directive_node, @arg_node, field, type).argument
+  end
+
+  # --- Runtime --------------------------------------------------------------
 
   def handle_builder(relation, value)
-    normalize(value).reduce(relation) do |rel, clause|
-      col = Lighthouse::Support::Naming.column(clause[:column], rel)
-      next rel if col.blank?
+    Array(value).each_with_index.reduce(relation) { |ordered, (clause, index)| order_by(ordered, symbolized(clause), index) }
+  end
 
-      direction = clause[:order].to_s.downcase == 'desc' ? :desc : :asc
-      rel.order(col => direction)
-    end
+  # On a field: `column:` in `direction:`.
+  def handle_field_builder(relation)
+    column = Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'column')
+    return relation unless column
+
+    direction = Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'direction').to_s.casecmp?('DESC') ? :desc : :asc
+    relation.order(column_attribute(relation, column).public_send(direction))
   end
 
   private
 
-  def normalize(value)
-    list = value.is_a?(Array) ? value : [value]
-    list.filter_map { |item| clause(item) }
+  def relations
+    @relations ||= Array(Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'relations')).map { |relation| relation.transform_keys(&:to_s) }
   end
 
-  # One `{ column:, order: }` clause, or nil when the item names no column.
-  def clause(item)
-    symbolized = symbolized_hash(item)
-    return nil unless symbolized
+  def order_by(relation, clause, index)
+    direction = clause[:order].to_s.casecmp?('DESC') ? :desc : :asc
+    aggregated = clause.except(:column, :order).compact
+    unless clause[:column].nil? ^ aggregated.empty?
+      raise ::GraphQL::ExecutionError, "An order by clause takes exactly one of: column, #{relations.pluck('relation').join(', ')}."
+    end
+    return relation.order(column_attribute(relation, clause[:column]).public_send(direction)) if clause[:column]
+
+    relation_name, aggregate = aggregated.first
+    order_by_aggregate(relation, relation_name, symbolized(aggregate), direction, index)
+  end
 
-    col = symbolized[:column] || symbolized[:field]
-    return nil if col.nil?
+  # LEFT JOIN (SELECT owner.id, AGGREGATE(related.column) FROM owner LEFT JOIN related ... GROUP BY owner.id)
+  # and ORDER BY the aggregate.
+  def order_by_aggregate(relation, relation_name, aggregate, direction, index)
+    owner = relation.klass
+    reflection = reflection(owner, relation_name)
+    key = owner.arel_table[owner.primary_key]
+    table = ::Arel::Table.new("lighthouse_order_#{index}_#{reflection.name}")
+    totals = owner.unscoped.left_joins(reflection.name).group(key)
+                  .select(key.as('lighthouse_key'), aggregate_node(reflection.klass, aggregate).as('lighthouse_aggregate'))
+
+    relation.joins(left_join(owner, totals, table, key)).order(table[:lighthouse_aggregate].public_send(direction))
+  end
+
+  def left_join(owner, totals, table, key)
+    subquery = ::Arel::Nodes::TableAlias.new(::Arel::Nodes::Grouping.new(totals.arel), table.name)
+    owner.arel_table.join(subquery, ::Arel::Nodes::OuterJoin).on(table[:lighthouse_key].eq(key)).join_sources
+  end
+
+  def aggregate_node(related, aggregate)
+    function = aggregate[:aggregate].to_s.downcase
+    ::Arel::Nodes.const_get(AGGREGATES.fetch(function)).new([aggregated_attribute(related, function, aggregate[:column])])
+  end
+
+  # COUNT counts the related records (their primary key); the other aggregates need a column.
+  def aggregated_attribute(related, function, column)
+    return column_attribute(related.all, column, as: function == 'count' ? :sort : :numeric) if column
+    raise ::GraphQL::ExecutionError, "Ordering by the #{function.upcase} of a relation needs a column." unless function == 'count'
+
+    related.arel_table[related.primary_key]
+  end
+
+  def reflection(owner, name)
+    candidates = [name.to_s, name.to_s.camelize(:lower), name.to_s.underscore].uniq
+    configured = relations.pluck('relation')
+    found = candidates.find { |candidate| configured.include?(candidate) } || name.to_s
+    owner.reflect_on_association(found.to_sym) || owner.reflect_on_association(found.underscore.to_sym) ||
+      raise(Lighthouse::DefinitionError, "@orderBy(relations:): #{owner.name} has no relation #{found}")
+  end
 
-    { column: col, order: symbolized[:order] || symbolized[:direction] || 'ASC' }
+  # A JSON path orders by its JSON value; an aggregate takes it as a number.
+  def column_attribute(relation, column, as: :sort)
+    Lighthouse::WhereConditions::Columns.attribute(relation.klass, column, as: as)
   end
 
-  # The item as a symbol-keyed hash, or nil when it is not hash-like.
-  def symbolized_hash(item)
-    hash = item.respond_to?(:to_h) ? item.to_h : item
-    hash.transform_keys { |k| k.to_s.to_sym } if hash.is_a?(Hash)
+  def symbolized(value)
+    hash = value.respond_to?(:to_h) ? value.to_h : value
+    hash.is_a?(Hash) ? hash.transform_keys { |key| key.to_s.underscore.to_sym } : {}
   end
 end

data/lib/lighthouse/directives/arguments/where_conditions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'where_conditions_base'
+
+# @whereConditions: the client's conditions on the field's records.
+#
+#   people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+#   { people(where: { column: AGE, operator: GT, value: 37 }) { name } }
+class Lighthouse::GraphQL::Directives::Arguments::WhereConditions < Lighthouse::GraphQL::Directives::Arguments::WhereConditionsBase
+  SUFFIX = 'WhereConditions'
+  DESCRIPTION = 'Filter results by field conditions.'
+
+  DEFINITION = <<~GRAPHQL.chomp
+    """
+    Add a dynamically client-controlled WHERE condition to a fields query.
+    """
+    directive @whereConditions(
+    #{COLUMN_ARGUMENTS.gsub(/^/, '  ')}
+    ) on ARGUMENT_DEFINITION
+  GRAPHQL
+
+  def self.directive_name = 'whereConditions'
+
+  def self.definition = DEFINITION
+end