lighthouse-graphql 0.2.1 → 0.3.0

data/lib/lighthouse/events/lifecycle.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# The events Lighthouse dispatches, in the order a request meets them (see
+# docs/events.md). All inherit Events::Event, so `moment` is there when a
+# class says so.
+module Lighthouse::Events
+  # A request reached the controller. `request` is the Rack/Rails request.
+  class StartRequest < Event
+    attr_reader :request
+
+    def initialize(request)
+      super()
+      @request = request
+    end
+  end
+
+  # The operation(s) of a request were read, before they run: one Hash
+  # (query, variables, operation_name, extensions) or, for a batch, an Array of them.
+  class StartOperationOrOperations < Event
+    attr_reader :operation_or_operations
+
+    def initialize(operation_or_operations)
+      super()
+      @operation_or_operations = operation_or_operations
+    end
+  end
+
+  # The schema is being built from `user_schema`, the SDL of the app. A
+  # listener may return SDL (a String) to append to it.
+  class BuildSchemaString < Event
+    attr_reader :user_schema
+
+    def initialize(user_schema)
+      super()
+      @user_schema = user_schema
+    end
+  end
+
+  # The directive classes are being registered. A listener may return a
+  # namespace (a Module or its name) or an Array of them; every directive class
+  # under them is registered.
+  class RegisterDirectiveNamespaces < Event
+  end
+
+  # The schema document was built and manipulated, before the schema is built
+  # from it. graphql-ruby's nodes are immutable: a listener sets `document_ast`
+  # to the document to build from.
+  class ManipulateAST < Event
+    attr_accessor :document_ast
+
+    def initialize(document_ast)
+      super()
+      @document_ast = document_ast
+    end
+  end
+
+  # A query is about to run. `query` is its parsed GraphQL::Language::Nodes::Document
+  # (nil if it does not parse). Fires once per operation of a multiplex.
+  class StartExecution < Event
+    attr_reader :schema, :query, :variables, :operation_name, :context
+
+    def initialize(schema, query, variables, operation_name, context)
+      super()
+      @schema = schema
+      @query = query
+      @variables = variables
+      @operation_name = operation_name
+      @context = context
+    end
+  end
+
+  # A query ran. A listener may return an Events::ExtensionsResponse (or an
+  # Array of them), which is merged into the result's "extensions".
+  # `query_complexity` is nil unless it was computed.
+  class BuildExtensionsResponse < Event
+    attr_reader :result, :query_complexity
+
+    def initialize(result, query_complexity)
+      super()
+      @result = result
+      @query_complexity = query_complexity
+    end
+  end
+
+  # The result Hash ("data", "errors", "extensions") of a query, before it is
+  # returned. A listener may change it in place, or set `result` to replace it.
+  class ManipulateResult < Event
+    attr_accessor :result
+
+    def initialize(result)
+      super()
+      @result = result
+    end
+  end
+
+  # A query ran and its result is final.
+  class EndExecution < Event
+    attr_reader :result
+
+    def initialize(result)
+      super()
+      @result = result
+    end
+  end
+
+  # The operation(s) ran: the result, or for a batch an Array of results.
+  class EndOperationOrOperations < Event
+    attr_reader :result_or_results
+
+    def initialize(result_or_results)
+      super()
+      @result_or_results = result_or_results
+    end
+  end
+
+  # The response is rendered. `response` is the Rack/Rails response.
+  class EndRequest < Event
+    attr_reader :response
+
+    def initialize(response)
+      super()
+      @response = response
+    end
+  end
+
+  # The schema is being validated (`rake lighthouse:validate_schema`).
+  class ValidateSchema < Event
+    attr_reader :schema
+
+    def initialize(schema)
+      super()
+      @schema = schema
+    end
+  end
+
+  # A key and its content for the "extensions" of a result, as a listener of
+  # BuildExtensionsResponse returns it.
+  class ExtensionsResponse
+    attr_reader :key, :content
+
+    def initialize(key, content)
+      @key = key
+      @content = content
+    end
+  end
+end

data/lib/lighthouse/events/schema_build.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# The events of the schema build, as SchemaGenerator.build_document meets them.
+module Lighthouse::Events::SchemaBuild
+  module_function
+
+  # Dispatch RegisterDirectiveNamespaces and register every directive class
+  # under the namespaces the listeners return (a Module, its name, or an
+  # Array of them), in the default registry.
+  def register_directive_namespaces(registry = Lighthouse::DirectiveRegistry.default)
+    namespaces = Lighthouse::Events.dispatch(Lighthouse::Events::RegisterDirectiveNamespaces.new).flatten
+    namespaces = namespaces.select { |namespace| namespace.is_a?(String) || namespace.is_a?(Module) }
+    namespaces.each { |namespace| register_namespace(resolve_namespace(namespace), registry) }
+  end
+
+  # The SDL with what the listeners of BuildSchemaString return appended.
+  def schema_string(sdl)
+    return sdl unless sdl.is_a?(String)
+
+    added = Lighthouse::Events.dispatch(Lighthouse::Events::BuildSchemaString.new(sdl)).flatten.grep(String)
+    added.empty? ? sdl : [sdl, *added].join("\n")
+  end
+
+  # The document the listeners of ManipulateAST leave on the event.
+  def manipulate_ast(document)
+    event = Lighthouse::Events::ManipulateAST.new(document)
+    Lighthouse::Events.dispatch(event)
+    event.document_ast
+  end
+
+  def resolve_namespace(namespace)
+    return namespace if namespace.is_a?(Module)
+
+    Lighthouse::Support::ModelResolver.constantize(namespace, namespaces: []) ||
+      raise(Lighthouse::DefinitionError, "RegisterDirectiveNamespaces: no namespace #{namespace}")
+  end
+
+  def register_namespace(namespace, registry)
+    namespace.constants(false).each do |name|
+      directive = namespace.const_get(name)
+      registry.register(directive) if directive.respond_to?(:directive_name)
+    end
+  end
+end

data/lib/lighthouse/events.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+# A small, framework-agnostic event dispatcher: PHP Lighthouse's events, which
+# let an app hook into the request lifecycle and the schema build without
+# patching either (see docs/events.md).
+#
+#   Lighthouse::Events.listen(Lighthouse::Events::BuildSchemaString) do |event|
+#     'extend type Query { version: String }'
+#   end
+#
+# A listener is anything that responds to `call(event)`. Every dispatch also
+# goes through ActiveSupport::Notifications, as
+# "<event name underscored>.lighthouse" (`start_execution.lighthouse`), with
+# the event as the `:event` payload, so Rails tooling can observe them too.
+module Lighthouse::Events
+  # Base class of the events Lighthouse dispatches; a listener on it hears all
+  # of them. Events that carry a time expose it as `moment`.
+  class Event
+    attr_reader :moment
+
+    def initialize
+      @moment = Time.now.utc
+    end
+  end
+
+  @listeners = [].freeze
+  @mutex = Mutex.new
+
+  class << self
+    # Register a listener (a callable or a block) for `event_class` and its
+    # subclasses. Returns the listener, to hand to `forget`.
+    def listen(event_class, callable = nil, &block)
+      listener = callable || block
+      raise ArgumentError, 'Lighthouse::Events.listen needs a callable or a block' unless listener.respond_to?(:call)
+
+      @mutex.synchronize { @listeners = [*@listeners, [event_class, listener]].freeze }
+      listener
+    end
+
+    # Unregister a listener (the value `listen` returned) from every event.
+    def forget(listener)
+      @mutex.synchronize { @listeners = @listeners.reject { |_, registered| registered.equal?(listener) }.freeze }
+      nil
+    end
+
+    # Drop every listener (between specs).
+    def reset!
+      @mutex.synchronize { @listeners = [].freeze }
+      nil
+    end
+
+    # Call the listeners of the event's class and its ancestors, in
+    # registration order. Returns their non-nil return values; what a
+    # return value means is up to the event.
+    def dispatch(event)
+      ::ActiveSupport::Notifications.instrument(notification_name(event.class), event: event) do
+        @listeners.filter_map { |klass, listener| listener.call(event) if event.is_a?(klass) }
+      end
+    end
+
+    # Whether dispatching an `event_class` event would reach anyone: a
+    # listener, or an ActiveSupport::Notifications subscriber. Hot paths ask
+    # first, to cost nothing when no one listens.
+    def listening?(event_class)
+      @listeners.any? { |klass, _| event_class <= klass } ||
+        ::ActiveSupport::Notifications.notifier.listening?(notification_name(event_class))
+    end
+
+    # The ActiveSupport::Notifications name an event class is instrumented as.
+    def notification_name(event_class)
+      "#{(event_class.name || 'event').demodulize.underscore}.lighthouse"
+    end
+  end
+end

data/lib/lighthouse/feature_directive.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# @feature — include a field or an object type in the schema depending on a
+# feature flag (PHP Lighthouse's Laravel Pennant integration, here backed by
+# Flipper).
+#
+# Flags are per request and per actor while the schema is built once, so the
+# element is not removed from the schema: it is hidden through graphql-ruby's
+# per-query visibility. Its `visible?(context)` answers whether the flag's
+# state matches `when` (ACTIVE by default). A hidden field disappears from
+# introspection and a query selecting it fails validation, as if the SDL did
+# not declare it; the fields returning a hidden type are hidden with it.
+#
+# The state is read through Config.feature_checker for the actor of
+# Config.feature_actor, at most once per feature and query (memoized in the
+# query's context), however many times graphql-ruby asks.
+#
+# Printing the schema (`to_definition`) is a query of its own: it shows the
+# features as they stand with no actor. Only graphql-ruby's own null context
+# (preloading a visibility profile) hides nothing.
+module Lighthouse::GraphQL::FeatureDirective
+  # Arguments with a default are nullable, not `Type! = default` as in PHP: graphql-ruby
+  # 2.5 does not fill in a directive argument's default, so a non-null one would be
+  # refused wherever it is left out. Left out or null, it takes its default.
+  DEFINITION = 'directive @feature(name: String!, when: FeatureState = ACTIVE) on FIELD_DEFINITION | OBJECT'
+
+  TYPE_DEFINITIONS = {
+    'FeatureState' => <<~GRAPHQL.chomp
+      "Options for the `when` argument of `@feature`."
+      enum FeatureState {
+        "Indicates an active feature."
+        ACTIVE
+        "Indicates an inactive feature."
+        INACTIVE
+      }
+    GRAPHQL
+  }.freeze
+
+  STATES = %w[ACTIVE INACTIVE].freeze
+  CONTEXT_KEY = :lighthouse_features
+
+  module_function
+
+  # Config.feature_checker's default: ask Flipper.
+  def default_checker
+    lambda do |name, actor, _context|
+      raise 'Lighthouse: configure `Config.feature_checker` to use @feature (Flipper not detected).' unless defined?(::Flipper)
+
+      ::Flipper.enabled?(name.to_sym, actor)
+    end
+  end
+
+  # Hide the types and fields of the schema that carry @feature.
+  def apply(schema)
+    used = false
+    schema.types.each_value do |type|
+      next unless type.kind.object? || type.kind.interface?
+
+      used |= hide_type(type)
+      type.fields.each_value { |field| used |= hide_field(type, field) }
+    end
+    silence_visibility_warning(schema) if used
+    schema
+  end
+
+  # Is the feature's state the one @feature asks for, in this query?
+  def visible?(name, state, context)
+    return true if context.nil? || context.is_a?(::GraphQL::Query::NullContext)
+
+    active = features(context).fetch(name) do
+      features(context)[name] = check(name, context)
+    end
+    (state == 'ACTIVE') == active
+  end
+
+  def check(name, context)
+    actor = Lighthouse::Config.feature_actor.call(context)
+    Lighthouse::Config.feature_checker.call(name, actor, context) ? true : false
+  end
+
+  def features(context)
+    context[CONTEXT_KEY] ||= {}
+  end
+
+  def hide_type(type)
+    feature = requirement(type, type.graphql_name)
+    return false unless feature
+
+    name, state = feature
+    original = type.method(:visible?)
+    type.define_singleton_method(:visible?) do |context|
+      original.call(context) && Lighthouse::GraphQL::FeatureDirective.visible?(name, state, context)
+    end
+    true
+  end
+
+  def hide_field(type, field)
+    feature = requirement(field, "#{type.graphql_name}.#{field.name}")
+    return false unless feature
+
+    name, state = feature
+    original = field.method(:visible?)
+    field.define_singleton_method(:visible?) do |context|
+      original.call(context) && Lighthouse::GraphQL::FeatureDirective.visible?(name, state, context)
+    end
+    true
+  end
+
+  # [feature name, required state] from the member's @feature, or nil.
+  def requirement(member, path)
+    node = member.ast_node&.directives&.find { |directive| directive.name == 'feature' }
+    return unless node
+
+    name = Lighthouse::Support::DirectiveArgs.literal(node, 'name').to_s
+    raise Lighthouse::DefinitionError, "@feature on #{path} needs a feature `name`" if name.strip.empty?
+
+    [name, required_state(node, path)]
+  end
+
+  def required_state(node, path)
+    state = Lighthouse::Support::DirectiveArgs.literal(node, 'when') || 'ACTIVE'
+    return state if STATES.include?(state)
+
+    raise Lighthouse::DefinitionError, "@feature on #{path}: `when` must be ACTIVE or INACTIVE, got #{state}"
+  end
+
+  # graphql-ruby 2.6 warns, once per query, when a member is hidden and the
+  # schema configured neither Visibility nor Warden. @feature is configured
+  # on purpose: keep the schema on the default (Warden) unless it chose.
+  def silence_visibility_warning(schema)
+    chosen = [::GraphQL::Schema::Warden, (::GraphQL::Schema::Visibility if defined?(::GraphQL::Schema::Visibility))]
+    return if schema.plugins.any? { |(plugin, _options)| chosen.include?(plugin) }
+    return unless ::GraphQL::Schema::Warden.respond_to?(:use)
+
+    schema.use(::GraphQL::Schema::Warden)
+  end
+end

data/lib/lighthouse/field_resolver_stack.rb

@@ -15,6 +15,7 @@ module Lighthouse::GraphQL::FieldResolverStack
     steps = directive_steps(type, field_def, directives, opts)
     steps << convention_step(type, field_def, root_kind) if root_kind && !resolving_directive?(directives)
     steps << validator_step(type, field_def, opts) if input_validation?(field_def, directives)
+    steps << empty_strings_step(type, field_def, opts) if empty_string_conversion?(field_def, directives)
 
     steps.each_with_index.sort_by { |(order, _), index| [order, index] }.each { |(_, step), _| step.call }
   end
@@ -38,8 +39,14 @@ module Lighthouse::GraphQL::FieldResolverStack
   end
 
   def convention_step(type, field_def, root_kind)
-    resolver = Lighthouse::GraphQL::DirectiveResolvers::ConventionResolver
-    [0, -> { resolver.new(field_def, type, root_kind).define_resolver(type) }]
+    resolvers = Lighthouse::GraphQL::DirectiveResolvers
+    resolver =
+      if root_kind == :subscriptions
+        resolvers::SubscriptionDirectiveResolver.new(field_def, type, nil, root_kind: root_kind)
+      else
+        resolvers::ConventionResolver.new(field_def, type, root_kind)
+      end
+    [0, -> { resolver.define_resolver(type) }]
   end
 
   # An explicit @validator on the field already validates its arguments.
@@ -53,4 +60,17 @@ module Lighthouse::GraphQL::FieldResolverStack
     [Lighthouse::DirectiveRegistry.default.resolution_order('validator'),
      -> { resolver.new(field_def, type, nil, opts).define_resolver(type) }]
   end
+
+  # Without @convertEmptyStringsToNull on the field itself, an argument or input
+  # type that carries it (or Config.convert_empty_strings_to_null) still converts.
+  def empty_string_conversion?(field_def, directives)
+    directives.none? { |d| d.name == 'convertEmptyStringsToNull' } &&
+      Lighthouse::GraphQL::DirectiveResolvers::ConvertEmptyStringsToNullDirectiveResolver.implicit?(field_def)
+  end
+
+  def empty_strings_step(type, field_def, opts)
+    resolver = Lighthouse::GraphQL::DirectiveResolvers::ConvertEmptyStringsToNullDirectiveResolver
+    [Lighthouse::DirectiveRegistry.default.resolution_order(resolver.directive_name),
+     -> { resolver.new(field_def, type, nil, opts).define_resolver(type) }]
+  end
 end

data/lib/lighthouse/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module GraphQL
-    VERSION = '0.2.1'
+    VERSION = '0.3.0'
   end
 end

data/lib/lighthouse/namespaces.rb

@@ -6,6 +6,7 @@
 # here, first.
 module Lighthouse
   module Contracts; end
+  module Events; end
   module Generators; end
   module Support; end
   module WhereConditions; end

data/lib/lighthouse/persisted_queries/batch.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# A batch of operations (a JSON array in the request) run in one go through
+# `schema.multiplex`: the query each operation (a Hash of query, extensions,
+# variables, operation_name and context) names, resolved as PersistedQueries.execute
+# does. Answers one result per operation, in order; an operation the protocol
+# rejects gets its ready-to-render error Hash. Dispatches the Operation(s)
+# events with the Arrays of operations and results.
+module Lighthouse::GraphQL::PersistedQueries::Batch
+  module_function
+
+  def run(schema, operations, **options)
+    operations = operations.map { |operation| operation.to_h.symbolize_keys }
+    Lighthouse::Events.dispatch(Lighthouse::Events::StartOperationOrOperations.new(operations))
+    rejected = {}
+    queries = operations.each_with_index.filter_map { |operation, index| query(operation, index, rejected) }
+    ran = schema.multiplex(queries, **options).to_a
+    results = operations.each_index.map { |index| rejected.fetch(index) { ran.shift } }
+    Lighthouse::Events.dispatch(Lighthouse::Events::EndOperationOrOperations.new(results))
+    results
+  end
+
+  # One operation as `schema.multiplex` takes it; a rejected one is noted
+  # under its index instead.
+  def query(operation, index, rejected)
+    {
+      query: Lighthouse::GraphQL::PersistedQueries.resolve(operation[:query], operation[:extensions]),
+      variables: operation[:variables] || {}, operation_name: operation[:operation_name], context: operation[:context] || {}
+    }
+  rescue Lighthouse::GraphQL::PersistedQueries::Error => e
+    rejected[index] = e.to_h
+    nil
+  end
+end

data/lib/lighthouse/persisted_queries.rb

@@ -49,11 +49,24 @@ module Lighthouse::GraphQL::PersistedQueries
   module_function
 
   # `schema.execute` with the query the request names; a protocol error
-  # comes back as a ready-to-render { "errors" => [...] } Hash.
+  # comes back as a ready-to-render { "errors" => [...] } Hash. Dispatches
+  # StartOperationOrOperations before and EndOperationOrOperations after.
   def execute(schema, query:, extensions: nil, **options)
-    schema.execute(resolve(query, extensions), **options)
-  rescue Error => e
-    e.to_h
+    operation = { query: query, variables: options[:variables], operation_name: options[:operation_name], extensions: extensions }
+    Lighthouse::Events.dispatch(Lighthouse::Events::StartOperationOrOperations.new(operation))
+    result =
+      begin
+        schema.execute(resolve(query, extensions), **options)
+      rescue Error => e
+        e.to_h
+      end
+    Lighthouse::Events.dispatch(Lighthouse::Events::EndOperationOrOperations.new(result))
+    result
+  end
+
+  # A batch (a JSON array in the request) through `schema.multiplex`; see Batch.
+  def multiplex(schema, operations, **options)
+    Lighthouse::GraphQL::PersistedQueries::Batch.run(schema, operations, **options)
   end
 
   # The query text to run for a request's `query` and `extensions`.

data/lib/lighthouse/rb_lighthouse.rb

@@ -28,6 +28,7 @@ require_relative 'namespaces'
   support/authorization
   support/arguments
   support/batching
+  support/soft_deletes
   where_conditions/operator_map
   contracts/directive
   contracts/field_resolver
@@ -39,19 +40,29 @@ require_relative 'namespaces'
   generated_resolvers
   federation_directives
   field_resolver_stack
+  events
+  events/lifecycle
+  events/execution_trace
+  events/schema_build
   schema_generator
   schema_cache
   persisted_queries
+  persisted_queries/batch
+  controller
   schema_factory
   schema_implementation
   resolver_dispatch
   caching
   cache_control
+  feature_directive
+  broadcasting
+  subscription
   pagination
   relation_batch
   nested_mutations
   directives/pagination_manipulator
   directives/where_conditions_directive
+  directives/soft_deletes_directive
   directive_resolvers/aggregate_resolver
   directive_resolvers/field_resolver
   directive_resolvers/where_conditions_applier
@@ -70,11 +81,17 @@ require_relative 'namespaces'
   directive_resolvers/can_resolvers
   directive_resolvers/convention_resolver
   directive_resolvers/model_mutation_resolver
+  directive_resolvers/soft_delete_resolvers
   directive_resolvers/cache_resolvers
   directive_resolvers/validator_resolver
+  directive_resolvers/subscription_resolver
+  directive_resolvers/broadcast_resolver
+  directive_resolvers/event_resolver
+  directive_resolvers/convert_empty_strings_resolver
   directives/arguments/base
   directives/arguments/filters
   directives/arguments/order_by
+  directives/arguments/soft_deletes
   directives/registry
   dataloader_sources/association_loader
   dataloader_sources/model_loader
@@ -87,6 +104,9 @@ rescue LoadError => e
   warn("Lighthouse: could not require #{rel}: #{e.message}")
 end
 
+# The activejob gem is optional: the job that queues @broadcast loads on first use.
+Lighthouse::GraphQL.autoload(:BroadcastJob, File.expand_path('broadcast_job.rb', __dir__))
+
 require_relative 'railtie' if defined?(Rails::Railtie)
 
 module Lighthouse::GraphQL::RbLightHouse

data/lib/lighthouse/schema_cache.rb

@@ -40,15 +40,22 @@ module Lighthouse::GraphQL::SchemaCache
 
   # The parsed document for `sdl` after manipulation. `build` turns the SDL
   # into the manipulated SDL string; it only runs on a cache miss.
-  # `force:` caches even when the cache is off (warm!).
-  def document(sdl, force: false, &build)
-    return parse(yield(sdl)) unless force || enabled?
+  # `force:` caches even when the cache is off (warm!). `finalize:` (a callable
+  # taking and returning the document) runs on the parsed document of a miss,
+  # before it is cached.
+  def document(sdl, force: false, finalize: nil, &build)
+    return built(sdl, finalize, &build) unless force || enabled?
 
     path = File.join(directory.to_s, "#{PREFIX}#{key(sdl)}.bin")
     cached = read(path)
     return cached if cached
 
-    parse(yield(sdl)).tap { |document| write(path, document) }
+    built(sdl, finalize, &build).tap { |document| write(path, document) }
+  end
+
+  def built(sdl, finalize)
+    document = parse(yield(sdl))
+    finalize ? finalize.call(document) : document
   end
 
   def key(sdl)
@@ -73,7 +80,7 @@ module Lighthouse::GraphQL::SchemaCache
   # and return the cache file's path.
   def warm!(sdl = nil)
     sdl ||= Lighthouse::GraphQL::SDLLoader.load_from_folder(Lighthouse::Config.sdl_folder.to_s)
-    document(sdl, force: true) { |source| Lighthouse::GraphQL::SchemaGenerator.manipulate(source) }
+    Lighthouse::GraphQL::SchemaGenerator.build_document(sdl, force: true)
     File.join(directory.to_s, "#{PREFIX}#{key(sdl)}.bin")
   end