lighthouse-graphql 0.2.1 → 0.3.0

data/lib/lighthouse/directive_resolvers/model_mutation_resolver.rb

@@ -181,34 +181,38 @@ module Lighthouse::GraphQL::DirectiveResolvers
     end
   end
 
-  # @delete — destroy the models the field's argument filters select
-  # (@whereKey, @eq, ...), running their callbacks, and return them: a list
-  # for a list field, else the first or null. Refuses to run without a
-  # filter argument, which would delete every row.
-  class DeleteDirectiveResolver < ModelMutationResolver
-    def self.directive_name = 'delete'
-    def self.definition = "directive @delete(#{ARGUMENTS}, scopes: [String!]) on #{LOCATIONS}"
-
+  # The shared shape of @delete, @forceDelete and @restore: act on each record
+  # the field's argument filters (@whereKey, @eq, ...) select, and return them:
+  # a list for a list field, else the first or null. Refuses to run without a
+  # filter argument, which would modify every row.
+  class ModifyModelsResolver < ModelMutationResolver
     WOULD_MODIFY_ALL = 'Would modify all models, use an argument to filter.'
 
     protected
 
-    # A record whose callbacks refuse the destroy is reported as an error next
-    # to the data, as PHP Lighthouse does; the others are still deleted.
+    # A record whose callbacks refuse the action is reported as an error next
+    # to the data, as PHP Lighthouse does; the others are still modified.
     def mutate(model, _obj, args, ctx)
       args = Lighthouse::Support::Arguments.shallow(args)
       raise ::GraphQL::ExecutionError, WOULD_MODIFY_ALL unless filtered?(args)
 
-      relation = Array(directive_arg('scopes')).reduce(model.all) { |acc, scope| acc.public_send(scope) }
-      records = apply_where_filters(relation, args).to_a
+      records = apply_where_filters(records_of(model), args).to_a
       records.each do |record|
-        next if record.destroy
+        next if modify(record)
 
         ctx.add_error(::GraphQL::ExecutionError.new("Could not modify model #{model.name} with ID #{record.id}."))
       end
       @field_def.type.list? ? records : records.first
     end
 
+    # The relation the filters narrow down: the model's, narrowed by `scopes:`.
+    def records_of(model) = apply_scopes(model.all)
+
+    # Act on one record; false when its callbacks refused.
+    def modify(_record)
+      raise NotImplementedError
+    end
+
     def filtered?(args)
       registry = Lighthouse::DirectiveRegistry.default
       (@field_def.ast_node.arguments || []).any? do |argument|
@@ -216,4 +220,15 @@ module Lighthouse::GraphQL::DirectiveResolvers
       end
     end
   end
+
+  # @delete — destroy the models the field's argument filters select
+  # (@whereKey, @eq, ...), running their callbacks, and return them.
+  class DeleteDirectiveResolver < ModifyModelsResolver
+    def self.directive_name = 'delete'
+    def self.definition = "directive @delete(#{ARGUMENTS}, scopes: [String!]) on #{LOCATIONS}"
+
+    protected
+
+    def modify(record) = record.destroy
+  end
 end

data/lib/lighthouse/directive_resolvers/soft_delete_resolvers.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'model_mutation_resolver'
+
+module Lighthouse::GraphQL::DirectiveResolvers
+  # The shape of @forceDelete and @restore: like @delete, they act on the
+  # records the field's filter arguments select — trashed ones included, which
+  # the model's default behaviour may hide — and return them. The model must
+  # support soft deletes (see Support::SoftDeletes).
+  class TrashedModelsResolver < ModifyModelsResolver
+    DOCUMENTED_ARGUMENTS = <<~GRAPHQL.chomp
+      "Specify the class name of the model to use. This is only needed when the default model detection does not work."
+      model: String
+      "Apply scopes to the underlying query."
+      scopes: [String!]
+    GRAPHQL
+
+    protected
+
+    def records_of(model)
+      Lighthouse::Support::SoftDeletes.require_support!(model)
+      apply_scopes(Lighthouse::Support::SoftDeletes.with_trashed(model.all))
+    end
+  end
+
+  # @forceDelete — permanently remove the soft-deleted (or any) models the
+  # field's filter arguments select, running their callbacks.
+  class ForceDeleteDirectiveResolver < TrashedModelsResolver
+    def self.directive_name = 'forceDelete'
+
+    def self.definition
+      <<~GRAPHQL.chomp
+        """
+        Permanently remove one or more soft deleted models.
+        """
+        directive @forceDelete(
+        #{DOCUMENTED_ARGUMENTS.gsub(/^/, '  ')}
+        ) on FIELD_DEFINITION
+      GRAPHQL
+    end
+
+    protected
+
+    def modify(record) = Lighthouse::Support::SoftDeletes.force_delete(record)
+  end
+
+  # @restore — un-delete the soft-deleted models the field's filter arguments select.
+  class RestoreDirectiveResolver < TrashedModelsResolver
+    def self.directive_name = 'restore'
+
+    def self.definition
+      <<~GRAPHQL.chomp
+        """
+        Un-delete one or more soft deleted models.
+        """
+        directive @restore(
+        #{DOCUMENTED_ARGUMENTS.gsub(/^/, '  ')}
+        ) on FIELD_DEFINITION
+      GRAPHQL
+    end
+
+    protected
+
+    def modify(record) = Lighthouse::Support::SoftDeletes.restore(record)
+  end
+end

data/lib/lighthouse/directive_resolvers/subscription_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+# Resolves a field of the Subscription root type, with @subscription(class:)
+# or, without the directive, by convention: `Subscription.postUpdated`
+# resolves to `Subscriptions::PostUpdated`, looked up in
+# Config.namespaces[:subscriptions] at call time so code reloading keeps
+# working. The class is a GraphQL::Schema::Subscription, which may include
+# Lighthouse::GraphQL::Subscription for PHP Lighthouse's hooks. A field
+# with no class still works: it is a Lighthouse::GraphQL::Subscription::Default
+# whose update is the broadcast root, which is all `@broadcast` needs.
+#
+# graphql-ruby registers a subscription through the class its field was
+# built from, which a field built from SDL has not. The field is therefore
+# told which class it stands for: its `resolver` (read by graphql-ruby to build
+# the topic, and to know the subscription instance wrote itself) and its
+# `subscription_scope` answer for the class. The class is instantiated for
+# each request, so its hooks (`subscribe`, `update`, ...) run as usual.
+class Lighthouse::GraphQL::DirectiveResolvers::SubscriptionDirectiveResolver < Lighthouse::GraphQL::DirectiveResolvers::BaseDirectiveResolver
+  def self.directive_name = 'subscription'
+  def self.definition = 'directive @subscription(class: String!) on FIELD_DEFINITION'
+
+  def define_resolver(target_type_class)
+    unless @opts[:root_kind] == :subscriptions
+      raise Lighthouse::DefinitionError, "@subscription is for fields of the Subscription type, not #{location}."
+    end
+
+    me = self
+    @field_def.define_singleton_method(:resolver) { me.subscription_class }
+    @field_def.define_singleton_method(:subscription_scope) { me.subscription_class.subscription_scope }
+
+    install(target_type_class, lambda do |obj, args, ctx|
+      Lighthouse::GraphQL::ResolverDispatch.call(me.subscription_class, me.field_def, obj, args, ctx)
+    end)
+  end
+
+  attr_reader :field_def
+
+  # The class this field stands for: the one @subscription names, else the
+  # conventional one, else the default.
+  def subscription_class
+    klass = find_class
+    return Lighthouse::GraphQL::Subscription::Default unless klass
+
+    unless klass.is_a?(Class) && klass < ::GraphQL::Schema::Subscription
+      raise Lighthouse::DefinitionError, "#{klass} resolves #{location}, so it must inherit from GraphQL::Schema::Subscription."
+    end
+
+    klass
+  end
+
+  private
+
+  def find_class
+    namespaces = Lighthouse::Config.namespaces[:subscriptions]
+    named = directive_arg('class') if @directive_node
+    klass = Lighthouse::Support::ModelResolver.constantize(named || @field_def.name.to_s.camelize, namespaces: namespaces, fallback: false)
+    return klass if klass || named.nil?
+
+    expected = Array(namespaces).map { |ns| "#{ns}::#{named}" }.join(' or ')
+    raise Lighthouse::DefinitionError, "@subscription(class: #{named.inspect}) on #{location}: no such class (looked for #{expected})."
+  end
+
+  def location
+    "#{@type_def.graphql_name}.#{@field_def.name}"
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Lighthouse::GraphQL::Directives::Arguments
+  # @trashed — filter soft-deleted records by the `Trashed` enum the client
+  # passes: ONLY the trashed ones, WITH them, or WITHOUT them. When the client
+  # omits the argument, the model's own default behaviour is untouched
+  # (paranoia hides trashed records, discard shows everything). The model's
+  # soft-delete strategy decides what "trashed" is (see Support::SoftDeletes).
+  #
+  # Usually added by @softDeletes: `tasks: [Task!]! @all @softDeletes`.
+  class Trashed < Base
+    def self.directive_name = 'trashed'
+
+    def self.definition
+      <<~GRAPHQL.chomp
+        """
+        Allows to filter if trashed elements should be fetched.
+        """
+        directive @trashed on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+      GRAPHQL
+    end
+
+    def handle_builder(relation, value)
+      return relation if value.nil?
+
+      Lighthouse::Support::SoftDeletes.filter(relation, value)
+    end
+  end
+
+  # @withoutGlobalScopes(names: [...]) — on a Boolean argument: when the client
+  # passes `true`, omit the named global scopes from the query.
+  #
+  # Rails has one anonymous `default_scope`, so each name is resolved as:
+  #
+  # 1. an app-defined scope `without_<name>` (the name in snake_case) on the
+  #    model, e.g. `scope :without_scheduled, -> { unscope(where: :schedule_at) }`;
+  # 2. else a column of that name: `unscope(where: column)`. This removes every
+  #    condition on that column in the relation, including ones added earlier
+  #    by other arguments;
+  # 3. else a soft-delete name (`softDeletes`, `SoftDeletingScope`): trashed
+  #    records are included (see Support::SoftDeletes).
+  #
+  # A name matching none of them is an error. A trailing `Scope` is optional in
+  # the name (`ScheduledScope` finds `without_scheduled` too).
+  class WithoutGlobalScopes < Base
+    SOFT_DELETE_NAMES = %w[soft_deletes soft_delete soft_deleting].freeze
+
+    def self.directive_name = 'withoutGlobalScopes'
+
+    def self.definition
+      <<~GRAPHQL.chomp
+        """
+        Omit any number of global scopes from the query builder.
+
+        This directive should be used on arguments of type `Boolean`.
+        The scopes will be removed only if `true` is passed by the client.
+        """
+        directive @withoutGlobalScopes(
+          "The names of the global scopes to omit."
+          names: [String!]!
+        ) on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
+      GRAPHQL
+    end
+
+    def handle_builder(relation, value)
+      return relation unless value == true
+
+      Array(Lighthouse::Support::DirectiveArgs.literal(@directive_node, 'names')).reduce(relation) do |acc, name|
+        without_scope(acc, name)
+      end
+    end
+
+    private
+
+    def without_scope(relation, name)
+      candidates = candidate_names(name)
+      omit_by_scope(relation, candidates) || omit_by_column(relation, candidates) || omit_trashed(relation, candidates) ||
+        raise(::GraphQL::ExecutionError, unknown_scope(relation, name, candidates.first))
+    end
+
+    def omit_by_scope(relation, candidates)
+      scope = candidates.map { |candidate| "without_#{candidate}" }.find { |method| relation.respond_to?(method) }
+      scope && (relation.public_send(scope) || relation)
+    end
+
+    def omit_by_column(relation, candidates)
+      column = candidates.find { |candidate| column?(relation, candidate) }
+      column && relation.unscope(where: column)
+    end
+
+    def omit_trashed(relation, candidates)
+      Lighthouse::Support::SoftDeletes.with_trashed(relation) if candidates.intersect?(SOFT_DELETE_NAMES)
+    end
+
+    def unknown_scope(relation, name, candidate)
+      "Cannot omit the global scope #{name}: #{relation.klass.name} has no without_#{candidate} scope or #{candidate} column."
+    end
+
+    def candidate_names(name)
+      snake = Lighthouse::Support::Naming.attribute(name)
+      [snake, snake.delete_suffix('_scope')].uniq
+    end
+
+    def column?(relation, name)
+      relation.klass.column_names.include?(name)
+    rescue ::ActiveRecord::ActiveRecordError
+      false
+    end
+  end
+end

data/lib/lighthouse/directives/registry.rb

@@ -56,16 +56,18 @@ class Lighthouse::DirectiveRegistry
 
   # Application order for wrapping/resolution directives on a field. Lower is
   # applied first (innermost, closest to the data); higher is applied last
-  # (outermost, so it executes first). From the outside in: authentication,
+  # (outermost, so it executes first). From the outside in: empty strings
+  # converted to null (so everything below sees the converted arguments), authentication,
   # authorization, argument validation, then @cache (so a cache hit is still
   # authorized and validated), @clearCache (which acts once the resolver
-  # succeeded), and finally the data resolver (0).
+  # succeeded), @event and @broadcast (likewise), and finally the data resolver (0).
   RESOLUTION_ORDER = {
+    'convertEmptyStringsToNull' => 6,
     'guard' => 5, 'auth' => 5,
     'canFind' => 4, 'canModel' => 4, 'canQuery' => 4, 'canResolved' => 4, 'canRoot' => 4,
     'validator' => 3,
     'cache' => 2,
-    'clearCache' => 1
+    'clearCache' => 1, 'event' => 1, 'broadcast' => 1
   }.freeze
 
   def resolution_order(name)
@@ -173,14 +175,16 @@ class Lighthouse::DirectiveRegistry
     CreateDirectiveResolver CreateManyDirectiveResolver
     UpdateDirectiveResolver UpdateManyDirectiveResolver
     UpsertDirectiveResolver UpsertManyDirectiveResolver DeleteDirectiveResolver
+    ForceDeleteDirectiveResolver RestoreDirectiveResolver
     CanFindDirectiveResolver CanModelDirectiveResolver CanQueryDirectiveResolver
     CanResolvedDirectiveResolver CanRootDirectiveResolver
-    CacheDirectiveResolver ClearCacheDirectiveResolver
-    ValidatorDirectiveResolver
+    CacheDirectiveResolver ClearCacheDirectiveResolver EventDirectiveResolver
+    ValidatorDirectiveResolver ConvertEmptyStringsToNullDirectiveResolver
+    SubscriptionDirectiveResolver BroadcastDirectiveResolver
   ].freeze
 
   # Argument-builder filter/sort directives.
-  ARG_BUILDERS = %i[Eq Neq In NotIn Like Where WhereKey OrderBy].freeze
+  ARG_BUILDERS = %i[Eq Neq In NotIn Like Where WhereKey OrderBy Trashed WithoutGlobalScopes].freeze
 
   # Read by other directives rather than resolving anything themselves.
   PASSIVE_DEFINITIONS = {
@@ -198,6 +202,7 @@ class Lighthouse::DirectiveRegistry
     # SDL manipulators run in registration order during the manipulation phase.
     register_manipulator(Lighthouse::GraphQL::Directives::PaginationManipulator)
     register_manipulator(Lighthouse::GraphQL::Directives::WhereConditionsDirective)
+    register_manipulator(Lighthouse::GraphQL::Directives::SoftDeletesDirective)
 
     register_default_definitions
     self
@@ -212,9 +217,12 @@ class Lighthouse::DirectiveRegistry
     PASSIVE_DEFINITIONS.each { |name, definition| register_definition(name, definition) }
     register_definition('cacheControl', Lighthouse::GraphQL::CacheControl::DEFINITION)
     Lighthouse::GraphQL::CacheControl::TYPE_DEFINITIONS.each { |name, sdl| register_type_definition(name, sdl) }
+    register_definition('feature', Lighthouse::GraphQL::FeatureDirective::DEFINITION)
+    Lighthouse::GraphQL::FeatureDirective::TYPE_DEFINITIONS.each { |name, sdl| register_type_definition(name, sdl) }
     Lighthouse::GraphQL::Directives::WhereConditionsDirective::DEFINITIONS.each do |name, definition|
       register_definition(name, definition)
     end
+    Lighthouse::GraphQL::Directives::SoftDeletesDirective::DEFINITIONS.each { |name, definition| register_definition(name, definition) }
   end
 
   def safe_definition(klass)

data/lib/lighthouse/directives/soft_deletes_directive.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Schema side of @softDeletes, as PHP Lighthouse does it: a field carrying it
+# gains the `trashed` argument (see Arguments::Trashed for what it does), and
+# the directive is consumed.
+#
+#   tasks: [Task!]! @all @softDeletes   ->   tasks(trashed: Trashed @trashed): [Task!]! @all
+#
+# The `Trashed` enum is added once whenever a `@trashed` argument is in the
+# schema (generated here or written by hand), unless the app declares its own.
+class Lighthouse::GraphQL::Directives::SoftDeletesDirective
+  DEFINITIONS = {
+    'softDeletes' => <<~GRAPHQL.chomp
+      """
+      Allows to filter if trashed elements should be fetched.
+      This manipulates the schema by adding the argument
+      `trashed: Trashed @trashed` to the field.
+      """
+      directive @softDeletes on FIELD_DEFINITION
+    GRAPHQL
+  }.freeze
+
+  TRASHED_ENUM = <<~GRAPHQL.chomp
+    "Specify if you want to include or exclude trashed results from a query."
+    enum Trashed {
+      "Only return trashed results."
+      ONLY
+      "Return both trashed and non-trashed results."
+      WITH
+      "Only return non-trashed results."
+      WITHOUT
+    }
+  GRAPHQL
+
+  ARGUMENT = %(type T { f("Specify if you want to include or exclude trashed results from a query." trashed: Trashed @trashed): Int })
+
+  FIELD_DEFINITIONS = [
+    ::GraphQL::Language::Nodes::ObjectTypeDefinition,
+    ::GraphQL::Language::Nodes::ObjectTypeExtension,
+    ::GraphQL::Language::Nodes::InterfaceTypeDefinition,
+    ::GraphQL::Language::Nodes::InterfaceTypeExtension
+  ].freeze
+
+  INPUT_DEFINITIONS = [
+    ::GraphQL::Language::Nodes::InputObjectTypeDefinition,
+    ::GraphQL::Language::Nodes::InputObjectTypeExtension
+  ].freeze
+
+  # The directives' own definitions are in every injected SDL; usage is what counts.
+  DECLARATION = /directive\s+@(softDeletes|trashed)\b/
+  USAGE = /@(softDeletes|trashed)\b/
+
+  def self.manipulate(sdl)
+    return sdl unless sdl.is_a?(String) && sdl.gsub(DECLARATION, '').match?(USAGE)
+
+    document = parse(sdl)
+    document ? new(document).manipulate(sdl) : sdl
+  end
+
+  def self.parse(sdl)
+    ::GraphQL::Language::Parser.parse(sdl)
+  rescue ::GraphQL::ParseError => e
+    warn("Lighthouse soft deletes: parse failed: #{e.message}")
+    nil
+  end
+  private_class_method :parse
+
+  def initialize(document)
+    @document = document
+    @rewritten = false
+    @trashed = false
+  end
+
+  # The SDL with the `trashed` arguments added and `Trashed` defined. Left
+  # untouched when there is nothing to rewrite.
+  def manipulate(sdl)
+    definitions = @document.definitions.map { |definition| rewrite(definition) }
+    printed = @rewritten ? ::GraphQL::Language::Printer.new.print(@document.merge(definitions: definitions)) : sdl
+    @trashed && !enum_declared? ? "#{printed}\n\n#{TRASHED_ENUM}" : printed
+  end
+
+  private
+
+  def rewrite(definition)
+    if FIELD_DEFINITIONS.any? { |kind| definition.is_a?(kind) }
+      definition.merge(fields: definition.fields.map { |field| soft_delete(field) })
+    else
+      note_input_arguments(definition)
+      definition
+    end
+  end
+
+  # A hand-written @trashed on an input field needs the enum too.
+  def note_input_arguments(definition)
+    return unless INPUT_DEFINITIONS.any? { |kind| definition.is_a?(kind) }
+
+    @trashed = true if definition.fields.any? { |field| trashed?(field) }
+  end
+
+  def soft_delete(field)
+    if field.directives.any? { |directive| directive.name == 'softDeletes' }
+      @rewritten = true
+      field = field.merge(arguments: with_trashed_argument(field.arguments),
+                          directives: field.directives.reject { |directive| directive.name == 'softDeletes' })
+    end
+    @trashed ||= field.arguments.any? { |argument| trashed?(argument) }
+    field
+  end
+
+  def with_trashed_argument(arguments)
+    return arguments if arguments.any? { |argument| argument.name == 'trashed' }
+
+    arguments + ::GraphQL::Language::Parser.parse(ARGUMENT).definitions.first.fields.first.arguments
+  end
+
+  def trashed?(node)
+    node.directives.any? { |directive| directive.name == 'trashed' }
+  end
+
+  def enum_declared?
+    @document.definitions.any? { |definition| definition.is_a?(::GraphQL::Language::Nodes::EnumTypeDefinition) && definition.name == 'Trashed' }
+  end
+end

data/lib/lighthouse/events/execution_trace.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# The graphql-ruby trace module SchemaGenerator.build installs on every schema,
+# dispatching the execution events (StartExecution, BuildExtensionsResponse,
+# ManipulateResult, EndExecution) around each query of a multiplex. A query
+# runs through a multiplex even on its own. With nothing listening it adds one
+# lookup per request.
+module Lighthouse::Events::ExecutionTrace
+  EVENTS = [
+    Lighthouse::Events::StartExecution, Lighthouse::Events::BuildExtensionsResponse,
+    Lighthouse::Events::ManipulateResult, Lighthouse::Events::EndExecution
+  ].freeze
+
+  def execute_multiplex(multiplex:)
+    return super unless EVENTS.any? { |event| Lighthouse::Events.listening?(event) }
+
+    multiplex.queries.each { |query| Lighthouse::Events::ExecutionTrace.start(multiplex.schema, query) }
+    results = super
+    multiplex.queries.each { |query| Lighthouse::Events::ExecutionTrace.finish(query) }
+    results
+  end
+
+  class << self
+    def start(schema, query)
+      Lighthouse::Events.dispatch(
+        Lighthouse::Events::StartExecution.new(schema, query.document, query.provided_variables, query.operation_name, query.context)
+      )
+    end
+
+    # The query's result Hash is final but for the listeners: they add
+    # extensions and may change it in place before the response is built.
+    def finish(query)
+      result = query.result_values
+      return unless result.is_a?(Hash)
+
+      merge_extensions(result, Lighthouse::Events.dispatch(Lighthouse::Events::BuildExtensionsResponse.new(result, nil)))
+      manipulate = Lighthouse::Events::ManipulateResult.new(result)
+      Lighthouse::Events.dispatch(manipulate)
+      result.replace(manipulate.result) unless manipulate.result.equal?(result)
+      Lighthouse::Events.dispatch(Lighthouse::Events::EndExecution.new(result))
+    end
+
+    def merge_extensions(result, responses)
+      responses = responses.flatten.grep(Lighthouse::Events::ExtensionsResponse)
+      return if responses.empty?
+
+      extensions = (result['extensions'] ||= {})
+      responses.each { |response| extensions[response.key.to_s] = response.content }
+    end
+  end
+end