lighthouse-graphql 0.1.1 → 0.2.0

data/lib/lighthouse/nested_mutations.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+# Nested mutations — PHP Lighthouse's nested arg resolvers, over ActiveRecord.
+#
+# An input field named after an association of the model being saved (or an
+# argument with @create/@update/@upsert/@delete(relation:)) carries operations
+# on that association instead of an attribute:
+#
+#   belongsTo / morphTo            connect, create, update, upsert, disconnect, delete
+#   hasOne / morphOne              create, update, upsert, delete
+#   hasMany / morphMany            create, update, upsert, connect, disconnect, delete
+#   belongsToMany / morphToMany    sync, syncWithoutDetaching, create, update, upsert,
+#                                  delete, connect, disconnect
+#
+# Each record is saved once: attributes are assigned, belongsTo/morphTo
+# operations set its foreign keys, it is saved, then the operations on
+# associations that point back at it run. Errors are keyed by the full
+# GraphQL path of the input (`input.author.create.name`).
+#
+# As in PHP Lighthouse, `update`, `upsert`, `delete` and `disconnect` find
+# records by primary key in the whole table, not only among the parent's
+# current children — an `update` re-parents the record it finds. Authorize
+# the mutation field accordingly.
+module Lighthouse::GraphQL::NestedMutations
+  MISSING_PRIMARY_KEY = 'Missing primary key for update.'
+  MISSING_IDENTIFYING_COLUMNS = 'All configured identifying columns must be present and non-null for upsert.'
+
+  # Argument directives that make an argument a nested operation, by the
+  # operation they stand for.
+  ARGUMENT_DIRECTIVES = {
+    'create' => 'create', 'createMany' => 'create',
+    'update' => 'update', 'updateMany' => 'update',
+    'upsert' => 'upsert', 'upsertMany' => 'upsert',
+    'delete' => 'delete'
+  }.freeze
+
+  OPERATIONS = {
+    belongs_to: %w[create connect update upsert disconnect delete],
+    morph_to: %w[connect disconnect delete],
+    has_one: %w[create update upsert delete],
+    has_many: %w[create update upsert connect disconnect delete],
+    many_to_many: %w[sync syncWithoutDetaching create update upsert delete connect disconnect]
+  }.freeze
+
+  # The PHP Lighthouse relation kind an association stands for, a key of OPERATIONS.
+  def self.kind(reflection)
+    case reflection.macro
+    when :belongs_to then reflection.polymorphic? ? :morph_to : :belongs_to
+    when :has_one then one_to_one_kind(reflection)
+    when :has_many then reflection.through_reflection? ? :many_to_many : :has_many
+    when :has_and_belongs_to_many then :many_to_many
+    end
+  end
+
+  def self.one_to_one_kind(reflection)
+    return :has_one unless reflection.through_reflection?
+
+    raise Lighthouse::DefinitionError, "#{reflection.name}: nested mutations on has_one :through are not supported."
+  end
+  private_class_method :one_to_one_kind
+
+  # One level of input: the argument values (snake_case symbol keys), the
+  # GraphQL argument definitions they were given against, and their GraphQL path.
+  Input = Struct.new(:args, :argument_defs, :path)
+
+  # A nested operation's value, the argument it was given as, and — for an
+  # @upsert(identifyingColumns:) argument — the columns that identify records.
+  Operation = Struct.new(:value, :argument, :path, :identifying) do
+    def plain
+      Lighthouse::Support::Arguments.plain(value)
+    end
+
+    def input(value = self.value, path = self.path)
+      Input.new(Lighthouse::Support::Arguments.shallow(value), argument.type.unwrap.arguments, path)
+    end
+
+    # A list's items (a single object counts as a list of one).
+    def inputs
+      return [input] unless value.is_a?(Array)
+
+      value.each_with_index.map { |item, index| input(item, path + [index.to_s]) }
+    end
+
+    def truthy?
+      value && value != false
+    end
+  end
+
+  # A record's input split into attributes and association operations.
+  class Partition
+    attr_reader :attributes, :paths, :operations
+
+    def initialize(paths)
+      @attributes = {}
+      @paths = paths
+      @operations = {} # reflection => { "create" => Operation, ... }
+    end
+
+    def add(reflection, operations)
+      (@operations[reflection] ||= {}).merge!(operations)
+    end
+
+    def take_key(model)
+      key = ['id', model.primary_key].uniq.find { |k| @attributes.key?(k) }
+      key && [key, @attributes[key]]
+    end
+  end
+
+  # Sets a child's foreign key (and morph type) to its hasOne/hasMany owner.
+  HasLink = Struct.new(:owner, :reflection) do
+    def before_save(child)
+      child[reflection.foreign_key] = owner[reflection.active_record_primary_key]
+      child[reflection.type] = owner.class.polymorphic_name if reflection.type
+    end
+
+    def after_save(_child); end
+  end
+
+  # Attaches a saved child to a many-to-many owner, keeping existing links.
+  AttachLink = Struct.new(:pivot) do
+    def before_save(_child); end
+
+    def after_save(child)
+      pivot.attach(child.id)
+    end
+  end
+
+  # The join records of a belongsToMany / morphToMany association:
+  # has_many :through (whose join model may carry pivot columns) or
+  # has_and_belongs_to_many.
+  class Pivot
+    def initialize(owner, reflection)
+      @owner = owner
+      @reflection = reflection
+      @through = reflection.through_reflection?
+      return unless @through && !reflection.source_reflection.belongs_to?
+
+      raise Lighthouse::DefinitionError,
+            "#{owner.class}##{reflection.name} goes through #{reflection.through_reflection.name} to a " \
+            "#{reflection.source_reflection.macro}; nested mutations need a join model that belongs_to #{reflection.klass}."
+    end
+
+    def ids
+      (@through ? joins.where(source_type_condition).pluck(source_key) : @owner.public_send(@reflection.name).pluck(@reflection.klass.primary_key))
+        .map(&:to_s)
+    end
+
+    # Attach `id` unless attached already; with pivot values, set them either way.
+    def attach(id, pivot = {})
+      if @through
+        join = joins.find_or_initialize_by(source_type_condition.merge(source_key => id))
+        join.assign_attributes(pivot)
+        join.save! if join.new_record? || join.changed?
+      else
+        unless pivot.empty?
+          raise ::GraphQL::ExecutionError,
+                "Pivot values need a has_many :through association; #{@owner.class}##{@reflection.name} is " \
+                'has_and_belongs_to_many.'
+        end
+        @owner.public_send(@reflection.name) << @reflection.klass.find(id) unless ids.include?(id.to_s)
+      end
+    end
+
+    def detach(ids)
+      if @through
+        joins.where(source_type_condition.merge(source_key => ids)).destroy_all
+      else
+        @owner.public_send(@reflection.name).delete(*@reflection.klass.where(@reflection.klass.primary_key => ids).to_a)
+      end
+    end
+
+    def sync(pairs, detaching:)
+      wanted = pairs.map { |id, _| id.to_s }
+      stale = ids - wanted
+      detach(stale) if detaching && stale.any?
+      pairs.each { |id, pivot| attach(id, pivot) }
+    end
+
+    def reset
+      @owner.association(@reflection.name).reset
+      @owner.association(@reflection.through_reflection.name).reset if @through
+    end
+
+    private
+
+    def joins
+      @owner.public_send(@reflection.through_reflection.name)
+    end
+
+    def source_key
+      @reflection.source_reflection.foreign_key
+    end
+
+    # A join model pointing at the related record polymorphically
+    # (`source_type:`) also stores its type.
+    def source_type_condition
+      source = @reflection.source_reflection
+      return {} unless source.polymorphic? && @reflection.options[:source_type]
+
+      { source.foreign_type => @reflection.options[:source_type].to_s.constantize.polymorphic_name }
+    end
+  end
+end
+
+# The executor and its parts open the namespace above compactly, so they load after it.
+require_relative 'nested_mutations/partitioner'
+require_relative 'nested_mutations/belongs_to_operations'
+require_relative 'nested_mutations/has_operations'
+require_relative 'nested_mutations/many_to_many_operations'
+require_relative 'nested_mutations/executor'

data/lib/lighthouse/pagination.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+# Runtime side of pagination — @paginate, and @hasMany / @belongsToMany /
+# @morphMany / @morphToMany with `type:` — as PHP Lighthouse does it:
+#
+#   PAGINATOR   first/page → { paginatorInfo: PaginatorInfo!, data }
+#   SIMPLE      first/page → { paginatorInfo: SimplePaginatorInfo!, data } (no total)
+#   CONNECTION  first/after → { pageInfo: PageInfo!, edges { cursor node } }
+#
+# Cursors are base64 of the 1-based position, PHP Lighthouse's format. The
+# schema side (types, arguments) is Directives::PaginationManipulator.
+#
+# A page reads its rows and total from a list: a RelationList queries one
+# relation (or array), a BatchedList loads them through the Dataloader for
+# every parent of a paginated relation at once.
+module Lighthouse::GraphQL::Pagination
+  TYPES = %w[PAGINATOR SIMPLE CONNECTION].freeze
+
+  module_function
+
+  # `relation`: a relation, an array or a list (BatchedList).
+  # `limits`: { default_count:, max_count: } — max_count may be :unlimited.
+  def paginate(relation, type, args, limits = {})
+    first = args[:first] || limits[:default_count] || Lighthouse::Config.pagination_default_count
+    validate!(first, limits.fetch(:max_count) { Lighthouse::Config.pagination_max_count })
+
+    list = relation.is_a?(List) ? relation : RelationList.new(relation)
+    case type
+    when 'SIMPLE' then simple(list, first, page(args))
+    when 'CONNECTION' then connection(list, first, offset_after(args[:after]))
+    else paginator(list, first, page(args))
+    end
+  end
+
+  # Where a page's rows and total come from.
+  module List; end
+
+  class RelationList
+    include List
+
+    def initialize(relation)
+      @relation = relation
+    end
+
+    def window(offset, limit) = Lighthouse::GraphQL::Pagination.window(@relation, offset, limit)
+    def count = Lighthouse::GraphQL::Pagination.count(@relation)
+  end
+
+  # One parent's page of a relation batched with its siblings' (RelationBatch).
+  class BatchedList
+    include List
+
+    def initialize(batch, owner, dataloader)
+      @batch = batch
+      @owner = owner
+      @dataloader = dataloader
+    end
+
+    def window(offset, limit)
+      return [] if limit.zero?
+
+      @dataloader.with(Lighthouse::GraphQL::DataloaderSources::RelationPageLoader, @batch, offset, limit).load(@owner)
+    end
+
+    def count
+      @dataloader.with(Lighthouse::GraphQL::DataloaderSources::RelationCountLoader, @batch).load(@owner)
+    end
+  end
+
+  def validate!(first, max_count)
+    raise ::GraphQL::ExecutionError, 'Pagination requires the `first` argument.' if first.nil?
+    raise ::GraphQL::ExecutionError, "Requested pagination amount must be non-negative, got #{first}." if first.negative?
+    return if max_count.nil? || max_count == :unlimited || first <= max_count
+
+    raise ::GraphQL::ExecutionError,
+          "Maximum number of #{max_count} requested items exceeded, got #{first}. Fetch smaller chunks."
+  end
+
+  def page(args)
+    [args[:page] || 1, 1].max
+  end
+
+  def paginator(list, per_page, page)
+    Paginator.new(list, per_page, page)
+  end
+
+  # Fetches one extra row to tell whether there is a next page, instead of counting.
+  def simple(list, per_page, page)
+    rows = list.window((page - 1) * per_page, per_page + 1)
+    items = rows.first(per_page)
+    {
+      'paginatorInfo' => item_range(items, page, per_page).merge('hasMorePages' => rows.size > per_page),
+      'data' => items
+    }
+  end
+
+  def connection(list, first, offset)
+    Connection.new(list, first, offset)
+  end
+
+  # A page whose total is only counted when the client selects
+  # paginatorInfo / pageInfo, so a query for `data` alone costs one query.
+  # Marshals with the total resolved, so @cache can store it.
+  class LazyPage
+    def initialize(list, items)
+      super()
+      @list = list
+      @items = items
+    end
+
+    def marshal_dump
+      [info, @items]
+    end
+
+    def marshal_load((info, items))
+      @info = info
+      @items = items
+    end
+
+    private
+
+    def total
+      @total ||= @list.count
+    end
+  end
+
+  class Paginator < LazyPage
+    def initialize(list, per_page, page)
+      super(list, list.window((page - 1) * per_page, per_page))
+      @per_page = per_page
+      @page = page
+    end
+
+    def data = @items
+
+    def paginatorInfo = info # rubocop:disable Naming/MethodName -- the GraphQL field's name, which the default resolver reads
+
+    def info
+      @info ||= begin
+        last_page = @per_page.zero? ? 0 : [(total.to_f / @per_page).ceil, 1].max
+        Lighthouse::GraphQL::Pagination.item_range(@items, @page, @per_page)
+                                       .merge('hasMorePages' => @page < last_page, 'lastPage' => last_page, 'total' => total)
+      end
+    end
+  end
+
+  class Connection < LazyPage
+    def initialize(list, first, offset)
+      super(list, list.window(offset, first))
+      @first = first
+      @offset = offset
+    end
+
+    def edges
+      @items.each_with_index.map { |node, i| { 'cursor' => Lighthouse::GraphQL::Pagination.encode_cursor(@offset + i + 1), 'node' => node } }
+    end
+
+    def pageInfo = info # rubocop:disable Naming/MethodName -- the GraphQL field's name, which the default resolver reads
+
+    def info
+      @info ||= {
+        'hasNextPage' => @offset + @items.size < total,
+        'hasPreviousPage' => @offset.positive?,
+        'startCursor' => @items.empty? ? nil : Lighthouse::GraphQL::Pagination.encode_cursor(@offset + 1),
+        'endCursor' => @items.empty? ? nil : Lighthouse::GraphQL::Pagination.encode_cursor(@offset + @items.size),
+        'total' => total,
+        'count' => @items.size,
+        'currentPage' => @first.zero? ? 1 : (@offset / @first) + 1,
+        'lastPage' => @first.zero? ? 0 : [(total.to_f / @first).ceil, 1].max
+      }
+    end
+
+    def marshal_dump
+      [info, @items, @offset]
+    end
+
+    def marshal_load((info, items, offset))
+      super([info, items])
+      @offset = offset
+    end
+  end
+
+  def item_range(items, page, per_page)
+    first_item = items.empty? ? nil : ((page - 1) * per_page) + 1
+    {
+      'count' => items.size,
+      'currentPage' => page,
+      'firstItem' => first_item,
+      'lastItem' => first_item && (first_item + items.size - 1),
+      'perPage' => per_page
+    }
+  end
+
+  def window(relation, offset, limit)
+    return [] if limit.zero?
+    return Array(relation)[offset, limit] || [] unless relation.respond_to?(:offset)
+
+    relation.offset(offset).limit(limit).to_a
+  end
+
+  def count(relation)
+    return Array(relation).size unless relation.respond_to?(:unscope)
+
+    relation.unscope(:order, :limit, :offset).count
+  end
+
+  def encode_cursor(position)
+    Base64.strict_encode64(position.to_s)
+  end
+
+  # The number of items the `after` cursor points past (0 for none or garbage).
+  def offset_after(cursor)
+    return 0 if cursor.blank?
+
+    Integer(Base64.strict_decode64(cursor), 10)
+  rescue ArgumentError
+    0
+  end
+end

data/lib/lighthouse/persisted_queries.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+# Automatic Persisted Queries, compatible with Apollo's protocol (as PHP
+# Lighthouse supports them), plus a manifest of trusted operations.
+#
+# APQ: a client sends `extensions: { persistedQuery: { version: 1,
+# sha256Hash } }` without the query. A known hash is served from
+# Config.persisted_queries_store; an unknown one answers
+# PersistedQueryNotFound, and the client retries with the query and the
+# hash, which registers it. Requests shrink to a hash, and fit in a GET —
+# which CDNs can cache (see @cacheControl).
+#
+# Manifest: `Config.persisted_queries_manifest` points at a JSON file of
+# operations — Apollo's persisted query manifest
+# (`{ "operations": [{ "id": sha256, "body": query }] }`) or a plain
+# `{ sha256 => query }` object — generated by your client build. Its
+# operations are served from memory, never evicted. With
+# `persisted_queries_only`, nothing else runs: an allowlist ("trusted
+# documents"), so arbitrary queries cannot reach the API.
+#
+# Off by default. Run operations through `PersistedQueries.execute` (the
+# generated controller does).
+module Lighthouse::GraphQL::PersistedQueries
+  HASH = /\A\h{64}\z/
+
+  # A request the persisted-query protocol rejects, rendered as a GraphQL
+  # response with Apollo's error codes.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code)
+      super(message)
+      @code = code
+    end
+
+    def to_h
+      { 'errors' => [{ 'message' => message, 'extensions' => { 'code' => code } }] }
+    end
+  end
+
+  NOT_FOUND = %w[PersistedQueryNotFound PERSISTED_QUERY_NOT_FOUND].freeze
+  NOT_SUPPORTED = %w[PersistedQueryNotSupported PERSISTED_QUERY_NOT_SUPPORTED].freeze
+  HASH_MISMATCH = ['provided sha does not match query', 'INTERNAL_SERVER_ERROR'].freeze
+  NOT_IN_LIST = ['Only persisted queries are allowed.', 'PERSISTED_QUERY_NOT_IN_LIST'].freeze
+
+  module_function
+
+  # `schema.execute` with the query the request names; a protocol error
+  # comes back as a ready-to-render { "errors" => [...] } Hash.
+  def execute(schema, query:, extensions: nil, **options)
+    schema.execute(resolve(query, extensions), **options)
+  rescue Error => e
+    e.to_h
+  end
+
+  # The query text to run for a request's `query` and `extensions`.
+  def resolve(query, extensions)
+    persisted = persisted_query(extensions)
+    query = nil if query.respond_to?(:empty?) && query.empty?
+    return unpersisted(query) unless persisted
+
+    hash = supported_hash(persisted)
+    query ? register_from_request(query, hash) : lookup(hash)
+  end
+
+  # The hash a `persistedQuery` extension names, provided persisted queries
+  # are on and it speaks the one protocol version there is.
+  def supported_hash(persisted)
+    raise Error.new(*NOT_SUPPORTED) unless enabled?
+
+    hash = persisted['sha256Hash'].to_s
+    raise Error.new(*NOT_SUPPORTED) unless persisted['version'].to_i == 1 && hash.match?(HASH)
+
+    hash
+  end
+
+  def enabled?
+    Lighthouse::Config.persisted_queries
+  end
+
+  def digest(query)
+    Digest::SHA256.hexdigest(query)
+  end
+
+  # Store a query ahead of time (e.g. from a deploy task). Returns its hash.
+  def register(query)
+    digest(query).tap { |hash| store.write(key(hash), query, expires_in: Lighthouse::Config.persisted_queries_ttl) }
+  end
+
+  def lookup(hash)
+    manifest[hash] || (!only? && store.read(key(hash))) || raise(Error.new(*NOT_FOUND))
+  end
+
+  # The manifest's operations by hash, reloaded when the file changes.
+  def manifest
+    path = Lighthouse::Config.persisted_queries_manifest
+    return {} unless path
+
+    mtime = File.mtime(path.to_s)
+    return @manifest if @manifest_source == [path.to_s, mtime]
+
+    @manifest = load_manifest(path.to_s)
+    @manifest_source = [path.to_s, mtime]
+    @manifest
+  end
+
+  def load_manifest(path)
+    data = JSON.parse(File.read(path))
+    operations = data.is_a?(Hash) && data['operations'].is_a?(Array) ? data['operations'].to_h { |op| [op['id'], op['body']] } : data
+    operations.each do |hash, body|
+      next if digest(body.to_s) == hash
+
+      raise Lighthouse::DefinitionError, "#{path}: operation #{hash} is not the SHA-256 of its body."
+    end
+    operations
+  end
+
+  def store
+    Lighthouse::Config.persisted_queries_store
+  end
+
+  def key(hash)
+    "lighthouse:apq:#{hash}"
+  end
+
+  def only?
+    Lighthouse::Config.persisted_queries_only
+  end
+
+  def persisted_query(extensions)
+    extensions = extensions_hash(extensions)
+    return nil unless extensions.respond_to?(:to_h)
+
+    persisted = extensions.to_h.transform_keys(&:to_s)['persistedQuery']
+    persisted&.to_h&.transform_keys(&:to_s)
+  rescue JSON::ParserError
+    nil
+  end
+
+  # `extensions` as the request carries it — a JSON string (GET) or
+  # ActionController::Parameters — made a plain Hash where possible. Malformed
+  # JSON raises JSON::ParserError, which persisted_query treats as "none".
+  def extensions_hash(extensions)
+    extensions = JSON.parse(extensions) if extensions.is_a?(String) && !extensions.empty?
+    extensions.respond_to?(:to_unsafe_h) ? extensions.to_unsafe_h : extensions
+  end
+
+  # A plain query: allowed, unless only the manifest's operations may run.
+  def unpersisted(query)
+    return query unless only?
+    raise Error.new(*NOT_IN_LIST) unless query && manifest.key?(digest(query))
+
+    query
+  end
+
+  def register_from_request(query, hash)
+    raise Error.new(*HASH_MISMATCH) unless digest(query) == hash
+    return query if manifest.key?(hash)
+    raise Error.new(*NOT_IN_LIST) if only?
+
+    store.write(key(hash), query, expires_in: Lighthouse::Config.persisted_queries_ttl)
+    query
+  end
+end

data/lib/lighthouse/railtie.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Hooks Lighthouse into a Rails host: exposes the `lighthouse:*` rake tasks,
+# and — with `config.watch_sdl` — reloads the app when a .graphql file changes.
+# Generators (`rails g lighthouse:install`) are found through lib/generators.
+class Lighthouse::Railtie < Rails::Railtie
+  rake_tasks do
+    load File.expand_path('tasks/lighthouse.rake', __dir__)
+  end
+
+  # After config/initializers (where Lighthouse.configure sets watch_sdl) and
+  # before Rails builds its file watcher from config.watchable_dirs.
+  initializer 'lighthouse.watch_sdl', after: :load_config_initializers, before: :set_clear_dependencies_hook do |app|
+    Lighthouse::Railtie.watch_sdl(app.config)
+  end
+
+  # Rails' reloader then treats a .graphql edit like a Ruby one: the app's
+  # constants — the schema among them — are reloaded on the next request.
+  def self.watch_sdl(config)
+    folder = Lighthouse::Config.sdl_folder
+    return false unless Lighthouse::Config.watch_sdl && folder
+
+    config.watchable_dirs[folder.to_s] = %w[graphql graphqls]
+    true
+  end
+end