lighthouse-graphql 0.1.0

data/docs/relationships.md

@@ -0,0 +1,95 @@
+# Relationships
+
+Just like in Rails, you can resolve associations directly from your schema. Add a
+field named after the association and annotate it with the matching directive.
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :author, class_name: 'User'
+  has_many :comments
+end
+```
+
+```graphql
+type Post {
+  author: User! @belongsTo(relation: "author")
+  comments: [Comment!]! @hasMany
+}
+```
+
+## Avoiding the N+1 problem
+
+Resolving relationships naively triggers one query per parent record. Lighthouse's
+relationship directives load through graphql-ruby's **Dataloader**, batching all
+sibling loads into a single query. Enable it on your schema:
+
+```ruby
+class AppSchema < BaseAppSchema
+  use GraphQL::Dataloader
+end
+```
+
+With the Dataloader in place, a query for 100 posts and their authors issues two
+queries, not 101.
+
+## One-to-many — `@hasMany`
+
+```graphql
+type User {
+  posts: [Post!]! @hasMany
+}
+```
+
+`@hasMany` returns a **connection** type, so it supports pagination arguments and
+`edges { node { ... } }` / `nodes { ... }` selections out of the box. The inverse
+is `@belongsTo`.
+
+## One-to-one — `@hasOne`
+
+```graphql
+type User {
+  profile: Profile @hasOne
+}
+```
+
+## Inverse — `@belongsTo`
+
+```graphql
+type Post {
+  author: User! @belongsTo(relation: "author")
+}
+```
+
+## Many-to-many — `@belongsToMany`
+
+```graphql
+type User {
+  roles: [Role!]! @belongsToMany
+}
+```
+
+## Renaming relations
+
+By default the relation name equals the field name (snake_cased). When they
+differ, pass `relation:`:
+
+```graphql
+type Post {
+  writtenBy: User! @belongsTo(relation: "author")
+}
+```
+
+## Filtering a relationship
+
+Relationship fields accept the same [argument filters](filtering-and-ordering.md)
+and [`@whereConditions`](filtering-and-ordering.md#complex-where-conditions) as
+root queries, so you can scope the related records:
+
+```graphql
+type User {
+  publishedPosts(
+    status: String @eq
+    orderBy: [OrderByClause!] @orderBy
+  ): [Post!]! @hasMany(relation: "posts")
+}
+```

data/lib/lighthouse/config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  # Convenience entrypoint: `Lighthouse.configure { |c| c.resolver_namespaces = [...] }`.
+  def self.configure(&block)
+    Config.configure(&block)
+  end
+
+  module Config
+    class << self
+      attr_writer :sdl_folder, :resolver_namespaces, :on_error,
+                  :authenticated_user, :policy_user, :authorizer
+
+      def sdl_folder
+        @sdl_folder ||= (defined?(Rails) && Rails.respond_to?(:root) ? File.join(Rails.root, 'graphql') : nil)
+      end
+
+      def directive_map
+        @directive_map ||= {}
+      end
+
+      # Namespaces tried (in order) when resolving a class name from a directive
+      # argument, e.g. `@field(resolver: "ContactPerson")` or `@all(model: "X")`.
+      # Keeping this in config means the library holds no app-specific namespace
+      # and can be extracted into a gem as-is.
+      def resolver_namespaces
+        @resolver_namespaces ||= ['App::Graphql']
+      end
+
+      # Hook invoked when a directive/resolver swallows an error. Defaults to
+      # re-raising in test (so failures surface) and logging otherwise. Override
+      # via `Lighthouse.configure { |c| c.on_error = ->(e, ctx) { ... } }`.
+      def on_error
+        @on_error ||= default_on_error
+      end
+
+      def handle_error(error, context = nil)
+        on_error.call(error, context)
+      end
+
+      # --- Authorization seams (used by @guard / @can) -------------------------
+      # The library stays framework-agnostic: how to read the authenticated user
+      # and how to check an ability are both configurable. The defaults work with
+      # a `current_user`/`pundit_user` context and Pundit.
+
+      # Returns the authenticated user from the GraphQL context (nil if none).
+      def authenticated_user
+        @authenticated_user ||= ->(ctx) { ctx && (ctx[:current_user] || ctx['current_user']) }
+      end
+
+      # The "user" object passed to the authorizer (e.g. Pundit's user context).
+      # Defaults to ctx[:pundit_user], falling back to the authenticated user.
+      def policy_user
+        @policy_user ||= lambda do |ctx|
+          (ctx && (ctx[:pundit_user] || ctx['pundit_user'])) || authenticated_user.call(ctx)
+        end
+      end
+
+      # Checks an ability: `->(user, record, ability) { true/false }`.
+      # Defaults to Pundit: `Pundit.policy!(user, record).<ability>?`.
+      def authorizer
+        @authorizer ||= default_authorizer
+      end
+
+      def configure
+        yield(self) if block_given?
+      end
+
+      def [](k)
+        public_send(k)
+      end
+
+      def reset!
+        @sdl_folder = nil
+        @resolver_namespaces = nil
+        @on_error = nil
+        @directive_map = nil
+        @authenticated_user = nil
+        @policy_user = nil
+        @authorizer = nil
+      end
+
+      private
+
+      def default_authorizer
+        lambda do |user, record, ability|
+          unless defined?(::Pundit)
+            raise 'Lighthouse: configure `Config.authorizer` to use @can (Pundit not detected).'
+          end
+
+          ::Pundit.policy!(user, record).public_send("#{ability}?")
+        end
+      end
+
+      def default_on_error
+        lambda do |error, _context|
+          if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.test?
+            raise error
+          elsif defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.warn("[Lighthouse] #{error.class}: #{error.message}")
+          else
+            warn("[Lighthouse] #{error.class}: #{error.message}")
+          end
+        end
+      end
+    end
+  end
+
+  module GraphQL
+    Config = Lighthouse::Config unless const_defined?(:Config, false)
+  end
+end

data/lib/lighthouse/contracts/arg_builder.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+module Lighthouse
+  module Contracts
+    # A directive on a field ARGUMENT that composes a constraint onto an
+    # ActiveRecord relation at resolve time, e.g. @eq, @neq, @in, @notIn, @like,
+    # @where, @orderBy. These compose in SDL argument order via the
+    # ArgBuilderPipeline.
+    #
+    # Implementors provide `#handle_builder(relation, value)` returning a relation.
+    module ArgBuilder
+      include Directive
+    end
+  end
+end

data/lib/lighthouse/contracts/arg_manipulator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+module Lighthouse
+  module Contracts
+    # A directive on a field ARGUMENT that mutates the schema AST before build,
+    # e.g. @whereConditions / @whereHasConditions generating input/enum types and
+    # swapping the `_` placeholder argument type.
+    #
+    # Implementors provide (at the class level)
+    # `manipulate_argument_definition(manipulation_context, parent, field, arg, directive)`.
+    module ArgManipulator
+      include Directive
+    end
+  end
+end

data/lib/lighthouse/contracts/directive.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  # Contracts are duck-typed marker modules that mirror the PHP Lighthouse
+  # directive interfaces. A directive class includes whichever contracts it
+  # fulfils; the DirectiveRegistry and SchemaGenerator detect capabilities via
+  # `klass.include?(Contracts::X)` and invoke the corresponding hook.
+  module Contracts
+    # Base marker. Every Lighthouse directive class includes this.
+    #
+    # Implementors are expected to expose (at the class level):
+    #   - `directive_name` -> String   the SDL name without the leading '@'
+    #   - `definition`     -> String?  the SDL `directive @name(...) on ...` line
+    module Directive
+    end
+  end
+end

data/lib/lighthouse/contracts/field_manipulator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+module Lighthouse
+  module Contracts
+    # A directive that mutates the schema AST before it is built, e.g. @paginate
+    # and the relationship directives injecting Connection/Paginator types, or
+    # @orderBy generating its column enum.
+    #
+    # Implementors provide (at the class level)
+    # `manipulate_field_definition(manipulation_context, parent, field, directive)`.
+    module FieldManipulator
+      include Directive
+    end
+  end
+end

data/lib/lighthouse/contracts/field_middleware.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+module Lighthouse
+  module Contracts
+    # A directive that wraps an existing field resolver, e.g. @auth wrapping the
+    # underlying resolver to enforce authentication.
+    #
+    # Implementors provide `#wrap_resolver(next_resolver)` returning a new
+    # `#call(obj, args, ctx)` lambda that may invoke `next_resolver`.
+    module FieldMiddleware
+      include Directive
+    end
+  end
+end

data/lib/lighthouse/contracts/field_resolver.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'directive'
+
+module Lighthouse
+  module Contracts
+    # A directive that provides the runtime resolver for a field, e.g. @all,
+    # @find, @paginate, @hasMany, @belongsTo, @field, @auth, @aggregate.
+    #
+    # During the resolution phase the SchemaGenerator instantiates the directive
+    # and installs its resolver onto the field. Legacy resolvers fulfil this via
+    # `#define_resolver(target_type)`; clean directives implement `#resolve_field`
+    # returning a `#call(obj, args, ctx)` lambda.
+    module FieldResolver
+      include Directive
+    end
+  end
+end

data/lib/lighthouse/dataloader_sources/association_loader.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  module GraphQL
+    module DataloaderSources
+      class AssociationLoader < ::GraphQL::Dataloader::Source
+        def initialize(model_class, association_name)
+          @model_class = model_class
+          @association_name = association_name.to_s
+        end
+
+        # keys: array of parent objects
+        def fetch(keys)
+          keys.map do |parent|
+            if parent.respond_to?(@association_name)
+              parent.public_send(@association_name)
+            else
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lighthouse/dataloader_sources/model_loader.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  module GraphQL
+    module DataloaderSources
+      class ModelLoader < ::GraphQL::Dataloader::Source
+        def initialize(model_class)
+          @model_class = model_class
+        end
+
+        # keys are ids
+        def fetch(keys)
+          records = @model_class.where(id: keys).index_by(&:id)
+          keys.map { |k| records[k] }
+        end
+      end
+    end
+  end
+end

data/lib/lighthouse/directive_resolvers/aggregate_resolver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'builder_applier'
+
+module Lighthouse
+  module GraphQL
+    module DirectiveResolvers
+      class AggregateDirectiveResolver < BaseDirectiveResolver
+        def define_resolver(target_type_class)
+          field_name = @field_def.name
+          method_name = "resolve_field_#{field_name}"
+
+          model_name = extract_directive_arg('model')
+          relation_name = extract_directive_arg('relation')
+          column_name = extract_directive_arg('column')
+          function_name = extract_directive_arg('function')
+          resolver_instance = self
+          field_ast_node = @field_def.ast_node
+
+          resolver_lambda = lambda do |obj, args, ctx|
+            relation = if model_name
+              model_class = resolver_instance.send(:constantize_model, model_name)
+              model_class ? model_class.all : nil
+            elsif relation_name && obj.respond_to?(relation_name)
+              obj.public_send(relation_name)
+            else
+              nil
+            end
+
+            return nil unless relation
+
+            relation = DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args, ctx, resolver_instance)
+            resolver_instance.send(:compute_aggregation, relation, column_name, function_name)
+          end
+
+          target_type_class.define_singleton_method(method_name, &resolver_lambda)
+          @field_def.resolve_proc = resolver_lambda if @field_def.respond_to?(:resolve_proc=)
+        end
+
+        private
+
+        def extract_directive_arg(name)
+          arg = @directive_node.arguments&.find { |a| a.name == name }
+          return nil unless arg
+          v = arg.value.respond_to?(:value) ? arg.value.value : arg.value
+          v.is_a?(::GraphQL::Language::Nodes::Enum) ? v.name : v
+        end
+
+        def compute_aggregation(relation, column, function_name)
+          return nil unless relation.respond_to?(:any?)
+          column = column.to_s
+          case function_name.to_s.upcase
+          when 'SUM'
+            relation.sum(column)
+          when 'AVG'
+            relation.average(column)&.to_f
+          when 'MIN'
+            relation.minimum(column)
+          when 'MAX'
+            relation.maximum(column)
+          when 'COUNT'
+            relation.count
+          else
+            nil
+          end
+        rescue StandardError
+          nil
+        end
+
+        def set_resolve_proc(method_name)
+          if @field_def.respond_to?(:resolve_proc=)
+            @field_def.resolve_proc = ->(obj, arguments, ctx) do
+              target_type_class = self.class
+              if target_type_class.respond_to?(method_name)
+                target_type_class.public_send(method_name, obj, arguments, ctx)
+              else
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lighthouse/directive_resolvers/all_resolver.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'builder_applier'
+
+module Lighthouse
+  module GraphQL
+    module DirectiveResolvers
+      class AllDirectiveResolver < BaseDirectiveResolver
+        def define_resolver(target_type_class)
+          field_name = @field_def.name
+
+          resolver_instance = self
+          field_ast_node = @field_def.ast_node
+
+          method_name = "resolve_field_#{field_name}"
+
+          model_name_static = extract_model_name || @field_def.type.unwrap.name
+          model_class_static = constantize_model(model_name_static)
+
+          target_type_class.define_singleton_method(method_name) do |_obj, arguments, ctx|
+            model_class = model_class_static
+            return [] unless model_class
+
+            # apply simple pagination args if present
+            args = arguments.respond_to?(:to_h) ? arguments.to_h : {}
+            relation = model_class.all
+
+            relation = DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args, ctx, resolver_instance)
+
+            relation = resolver_instance.apply_where_filters(relation, args)
+            relation = relation.limit(args[:first]) if args[:first]
+            relation = relation.offset(args[:offset]) if args[:offset]
+            relation
+          end
+
+          if @field_def.respond_to?(:resolve_proc=)
+            @field_def.resolve_proc = ->(_obj, arguments, ctx) do
+              model_class = model_class_static
+              if model_class.nil?
+                []
+              else
+                args = arguments.respond_to?(:to_h) ? arguments.to_h : {}
+                relation = model_class.all
+
+                relation = DirectiveResolvers::BuilderApplier.apply(relation, field_ast_node, args, ctx, resolver_instance)
+
+                relation = resolver_instance.apply_where_filters(relation, args)
+                relation = relation.limit(args[:first]) if args[:first]
+                relation = relation.offset(args[:offset]) if args[:offset]
+                relation
+              end
+            end
+          end
+        end
+
+        private
+
+        def extract_model_name
+          arg = @directive_node.arguments&.find { |a| a.name == 'model' }
+          return nil unless arg
+          arg.value.respond_to?(:value) ? arg.value.value : arg.value
+        end
+
+        def constantize_model(name)
+          return nil unless name
+          name = name.to_s.split('::').last
+          Object.const_get(name) rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/lighthouse/directive_resolvers/auth_resolver.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  module GraphQL
+    module DirectiveResolvers
+      class AuthDirectiveResolver < BaseDirectiveResolver
+        def define_resolver(target_type_class)
+          field_name = @field_def.name
+          method_name = "resolve_field_#{field_name}"
+
+          original_singleton =
+            if target_type_class.respond_to?(method_name)
+              target_type_class.method(method_name)
+            end
+
+          original_proc =
+            if @field_def.respond_to?(:resolve_proc)
+              @field_def.resolve_proc
+            end
+
+          wrapper = lambda do |obj, arguments, ctx|
+            user = ctx && (ctx[:current_user] || ctx['current_user'])
+            raise(::GraphQL::ExecutionError, 'Unauthenticated.') unless user
+
+            if original_singleton
+              original_singleton.call(obj, arguments, ctx)
+            elsif original_proc
+              original_proc.call(obj, arguments, ctx)
+            elsif obj.respond_to?(field_name)
+              obj.public_send(field_name)
+            else
+              snake = field_name.to_s.underscore
+              obj.respond_to?(snake) ? obj.public_send(snake) : nil
+            end
+          end
+
+          target_type_class.define_singleton_method(method_name, &wrapper)
+          @field_def.resolve_proc = wrapper if @field_def.respond_to?(:resolve_proc=)
+        end
+      end
+    end
+  end
+end
+

data/lib/lighthouse/directive_resolvers/base.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Lighthouse
+  module GraphQL
+    module DirectiveResolvers
+      class BaseDirectiveResolver
+        def initialize(field_def, type_def, directive_node, opts = {})
+          @field_def = field_def
+          @type_def = type_def
+          @directive_node = directive_node
+          @opts = opts
+        end
+
+        def define_resolver(target_type_class)
+          raise NotImplementedError
+        end
+
+        def apply_where_filters(relation, args)
+          return relation unless relation.respond_to?(:where)
+
+          args_h = args.respond_to?(:to_h) ? args.to_h : (args || {})
+
+          where_condition = args_h[:where] || args_h['where']
+          relation = DirectiveResolvers::WhereConditionsApplier.apply(relation, where_condition) if where_condition
+
+          @field_def.ast_node.arguments.each do |arg_node|
+            next unless arg_node.directives.any? { |dir| dir.name == 'whereHasConditions' }
+
+            arg_value = Lighthouse::Support::Naming.fetch_arg(args_h, arg_node.name)
+            next unless arg_value
+
+            relation_name = extract_relation_name_from_directive(arg_node) || Lighthouse::Support::Naming.derive_relation_name(arg_node.name)
+            relation = DirectiveResolvers::WhereConditionsApplier.apply_has_argument(relation, arg_node.name, arg_value, relation_name)
+          end
+
+          apply_arg_builders(relation, args_h)
+        rescue ::GraphQL::ExecutionError
+          raise
+        rescue StandardError => e
+          Lighthouse::Config.handle_error(e)
+          relation
+        end
+
+        # Compose argument-builder directives (@eq, @neq, @in, @notIn, @like,
+        # @where, @orderBy) onto the relation, in SDL argument order, for each
+        # field argument that carries one and that the client supplied a value
+        # for.
+        def apply_arg_builders(relation, args_h)
+          return relation unless relation.respond_to?(:where)
+          return relation unless @field_def.ast_node
+
+          registry = Lighthouse::DirectiveRegistry.default
+
+          (@field_def.ast_node.arguments || []).each do |arg_node|
+            (arg_node.directives || []).each do |dnode|
+              builder_class = registry.arg_builder_class(dnode.name)
+              next unless builder_class
+
+              value = Lighthouse::Support::Naming.fetch_arg(args_h, arg_node.name)
+              next if value.nil?
+
+              relation = builder_class.new(arg_node, dnode).handle_builder(relation, value)
+            end
+          end
+
+          relation
+        rescue ::GraphQL::ExecutionError
+          raise
+        rescue StandardError => e
+          Lighthouse::Config.handle_error(e)
+          relation
+        end
+
+        def extract_relation_name_from_directive(arg_node)
+          directive = arg_node.directives.find { |dir| dir.name == 'whereHasConditions' }
+          return nil unless directive
+
+          relation_arg = directive.arguments.find { |arg| arg.name == 'relation' }
+          return nil unless relation_arg
+
+          relation_arg.value.respond_to?(:value) ? relation_arg.value.value : relation_arg.value
+        rescue StandardError
+          nil
+        end
+
+        def constantize_model(name)
+          Lighthouse::Support::ModelResolver.constantize(name)
+        end
+      end
+    end
+  end
+end