lighthouse-graphql 0.1.1 → 0.2.1

data/lib/generators/lighthouse/install/install_generator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'lighthouse-graphql'
+
+# `rails generate lighthouse:install` — sets a Rails app up for Lighthouse:
+# the initializer, a starter SDL file, the schema class, a controller and
+# its route, plus the graphql-config file IDEs read. Rerunning it skips the
+# route, SDL and .gitignore entries that are already in place.
+#
+# It coexists with graphql-ruby's `graphql:install`, which writes the same
+# controller path and route: an existing schema class or controller is kept
+# (pass --force to replace it) instead of overwritten, so an app already
+# serving a graphql-ruby schema keeps doing so until it is pointed at ours.
+class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
+  CONTROLLER = 'app/controllers/graphql_controller.rb'
+
+  source_root File.expand_path('templates', __dir__)
+
+  desc 'Install Lighthouse: initializer, starter schema, schema class, controller, route and IDE config.'
+
+  class_option :schema, type: :string, default: 'AppSchema',
+                        desc: 'Name of the schema constant to generate'
+  class_option :sdl_folder, type: :string, default: 'graphql',
+                            desc: 'Folder, relative to the app root, holding the *.graphql files'
+  class_option :skip_controller, type: :boolean, default: false,
+                                 desc: 'Skip the GraphqlController and its route'
+  class_option :skip_ide, type: :boolean, default: false,
+                          desc: 'Skip graphql.config.yml and the .gitignore entries for the IDE helper files'
+
+  def create_initializer
+    template 'initializer.rb.tt', 'config/initializers/lighthouse.rb'
+  end
+
+  def create_starter_schema
+    if Dir[File.join(destination_root, sdl_folder, '**', '*.graphql')].any?
+      say_status :skip, "#{sdl_folder}/ already has .graphql files", :yellow
+      return
+    end
+
+    template 'schema.graphql.tt', File.join(sdl_folder, 'schema.graphql')
+  end
+
+  def create_schema_class
+    path = File.join('app/graphql', "#{schema_name.underscore}.rb")
+    return if keep_existing?(path)
+
+    template 'schema.rb.tt', path
+  end
+
+  def create_controller
+    return if options[:skip_controller]
+    return if (@kept_controller = keep_existing?(CONTROLLER))
+
+    template 'graphql_controller.rb.tt', CONTROLLER
+  end
+
+  def add_route
+    return if options[:skip_controller]
+
+    routes = File.join(destination_root, 'config/routes.rb')
+    return unless File.exist?(routes)
+    return if File.read(routes).include?('graphql#execute')
+
+    # Byte-identical to graphql-ruby's install route, so whichever generator
+    # runs second finds it in place and does not add it again.
+    route 'post "/graphql", to: "graphql#execute"'
+  end
+
+  def create_ide_config
+    return if options[:skip_ide]
+
+    template 'graphql.config.yml.tt', 'graphql.config.yml'
+
+    gitignore = File.join(destination_root, '.gitignore')
+    return unless File.exist?(gitignore)
+
+    entries = ide_helper_files.map { |file| "/#{file}" } - File.read(gitignore).lines.map(&:strip)
+    return if entries.empty?
+
+    append_to_file '.gitignore', "\n# Lighthouse IDE helper output (bin/rails lighthouse:ide_helper)\n#{entries.join("\n")}\n"
+  end
+
+  def show_next_steps
+    serve =
+      if @kept_controller
+        "Serve it: #{CONTROLLER} was kept — have it call #{schema_name}.execute(...) to serve Lighthouse's schema."
+      else
+        'Query it:  POST /graphql  {"query": "{ users { data { id name } paginatorInfo { total } } }"}'
+      end
+
+    say <<~MSG
+
+      Lighthouse is installed. Next steps:
+        1. Describe your API in #{sdl_folder}/*.graphql (the starter schema assumes a User model).
+        2. Generate the IDE helper files:  bin/rails lighthouse:ide_helper
+        3. #{serve}
+    MSG
+  end
+
+  private
+
+  # Files another generator may own (graphql-ruby's install writes the same
+  # controller) are left alone unless --force is given.
+  def keep_existing?(path)
+    return false if options[:force] || !File.exist?(File.join(destination_root, path))
+
+    say_status :skip, "#{path} already exists (pass --force to replace it)", :yellow
+    true
+  end
+
+  def schema_name
+    options[:schema].camelize
+  end
+
+  def sdl_folder
+    options[:sdl_folder].delete_suffix('/')
+  end
+
+  def default_sdl_folder?
+    sdl_folder == 'graphql'
+  end
+
+  def ide_helper_files
+    [Lighthouse::IdeHelper::DIRECTIVES_FILE, Lighthouse::IdeHelper::PROGRAMMATIC_TYPES_FILE]
+  end
+end

data/lib/generators/lighthouse/install/templates/graphql.config.yml.tt

@@ -0,0 +1,8 @@
+# graphql-config, read by the GraphQL plugins for JetBrains IDEs and VS Code.
+# The two generated files describe Lighthouse's directives and the types it
+# generates; refresh them after changing the schema:
+#   bin/rails lighthouse:ide_helper
+schema:
+  - <%= sdl_folder %>/**/*.graphql
+  - <%= Lighthouse::IdeHelper::DIRECTIVES_FILE %>
+  - <%= Lighthouse::IdeHelper::PROGRAMMATIC_TYPES_FILE %>

data/lib/generators/lighthouse/install/templates/graphql_controller.rb.tt

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class GraphqlController < ApplicationController
+  # If this endpoint is called from outside this domain, null the session
+  # instead of failing CSRF verification:
+  # protect_from_forgery with: :null_session
+
+  def execute
+    # PersistedQueries.execute resolves Apollo-style persisted queries when
+    # config.persisted_queries is on, and otherwise runs params[:query] as is.
+    result = Lighthouse::GraphQL::PersistedQueries.execute(
+      <%= schema_name %>,
+      query: params[:query],
+      extensions: params[:extensions],
+      variables: prepare_variables(params[:variables]),
+      operation_name: params[:operationName],
+      context: {
+        # Read by @guard and the @can* directives — see config/initializers/lighthouse.rb.
+        # current_user: current_user
+      }
+    )
+    # The Cache-Control header the selected fields' @cacheControl hints allow
+    # (a no-op when the schema has none).
+    Lighthouse::GraphQL::CacheControl.apply(response, result)
+    render json: result
+  rescue StandardError => e
+    raise e unless Rails.env.development?
+
+    handle_error_in_development(e)
+  end
+
+  private
+
+  # Variables arrive as a JSON string (GET or form posts) or as parameters.
+  def prepare_variables(variables_param)
+    case variables_param
+    when String
+      variables_param.present? ? JSON.parse(variables_param) || {} : {}
+    when Hash
+      variables_param
+    when ActionController::Parameters
+      variables_param.to_unsafe_hash
+    when nil
+      {}
+    else
+      raise ArgumentError, "Unexpected parameter: #{variables_param}"
+    end
+  end
+
+  def handle_error_in_development(error)
+    logger.error(error.message)
+    logger.error(error.backtrace.join("\n"))
+
+    render json: { errors: [{ message: error.message, backtrace: error.backtrace }], data: {} },
+           status: :internal_server_error
+  end
+end

data/lib/generators/lighthouse/install/templates/initializer.rb.tt

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Lighthouse configuration. Every option is optional; the defaults are shown.
+# Reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/configuration.md
+Lighthouse.configure do |config|
+  # Folder the *.graphql schema files are loaded from.
+<% if default_sdl_folder? -%>
+  # config.sdl_folder = Rails.root.join('graphql').to_s
+<% else -%>
+  config.sdl_folder = Rails.root.join('<%= sdl_folder %>').to_s
+<% end -%>
+
+  # Where classes named by the schema are looked up, by kind. A Query or Mutation
+  # field without a resolving directive resolves by convention: Query.latestPosts
+  # to Queries::LatestPosts (a GraphQL::Schema::Resolver), Mutation.publishPost
+  # to Mutations::PublishPost (a GraphQL::Schema::Mutation). @builder classes
+  # come from :builders and @validator contracts from :validators. Generate them
+  # with `rails g lighthouse:query|mutation|builder|validator Name`.
+  # config.namespaces = {
+  #   queries: ['Queries'], mutations: ['Mutations'], builders: ['Builders'], validators: ['Validators']
+  # }
+
+  # Namespaces tried, in order, for models (@all(model: "User")) and for
+  # @field(resolver:) on types other than Query and Mutation. Fully-qualified
+  # names (containing `::`) are used as-is.
+  # config.resolver_namespaces = ['App::Graphql']
+
+  # Store for @cache and @clearCache.
+  # config.cache_store = Rails.cache
+
+  # Run @create/@update/@createMany/@updateMany in a database transaction.
+  # config.transactional_mutations = true
+
+  # --- For large schemas and high traffic (all off by default) ---------------
+  # Cache the built schema document in tmp/cache, keyed by the SDL and
+  # everything that shapes it; warm it at deploy with `bin/rails lighthouse:cache`.
+  # config.schema_cache = Rails.env.production?
+
+  # Reload the app (and so the schema) when a .graphql file changes.
+  # config.watch_sdl = Rails.env.development?
+
+  # Automatic Persisted Queries (Apollo's protocol). Add a GET route too, so
+  # hashed queries can be cached by CDNs: get "/graphql", to: "graphql#execute"
+  # config.persisted_queries = true
+  # config.persisted_queries_ttl = 1.week.to_i
+  # A manifest of trusted operations from your client build, served by hash;
+  # with persisted_queries_only, nothing else may run.
+  # config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')
+  # config.persisted_queries_only = Rails.env.production?
+
+  # Called when a directive or resolver swallows an error. The default raises in
+  # test and logs otherwise.
+  # config.on_error = ->(error, _context) { Rails.error.report(error) }
+
+  # Authorization seams used by @guard and the @can* directives (Pundit by default).
+  # config.authenticated_user = ->(ctx) { ctx[:current_user] }
+  # config.policy_user = ->(ctx) { ctx[:pundit_user] || ctx[:current_user] }
+  # config.authorizer = ->(user, record, ability, args = []) { Pundit.policy!(user, record).public_send("#{ability}?", *args) }
+end
+
+# Register app-defined directives and federation reference resolvers inside
+# to_prepare, so they reference reloadable constants and run before the schema
+# is built. See docs/custom-directives.md and docs/federation.md.
+# Rails.application.config.to_prepare do
+#   Lighthouse::DirectiveRegistry.register(Directives::Upcase)
+#   Lighthouse::ReferenceResolver.register('User') { |ref, _ctx| User.find_by(id: ref['id']) }
+# end

data/lib/generators/lighthouse/install/templates/schema.graphql.tt

@@ -0,0 +1,19 @@
+# Starter schema generated by `rails generate lighthouse:install`. It assumes a
+# User model with `name` and `email` columns — replace it with your own types.
+# Directives reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/directives.md
+
+"Indicates what fields are available at the top level of a query operation."
+type Query {
+  "Find a single user by id."
+  user(id: ID! @eq): User @find
+
+  "List users, a page at a time (10 by default; pass first: and page:)."
+  users: [User!]! @paginate(defaultCount: 10)
+}
+
+"Account of a person who uses this application."
+type User {
+  id: ID!
+  name: String
+  email: String
+}

data/lib/generators/lighthouse/install/templates/schema.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Executable schema built by Lighthouse from the SDL in <%= sdl_folder %>/. The
+# Dataloader batches relationship loads (@hasMany, @belongsTo, ...) to avoid N+1.
+<%= schema_name %> = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    using: { GraphQL::Dataloader => {} }
+    # base_types: { object: Types::BaseObject } # your graphql-ruby base classes
+  }
+)

data/lib/generators/lighthouse/mutation_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'class_generator'
+
+# `rails generate lighthouse:mutation PublishPost` — a GraphQL::Schema::Mutation
+# that `Mutation.publishPost` resolves to by convention.
+class Lighthouse::Generators::MutationGenerator < Lighthouse::Generators::ClassGenerator
+  desc 'Generate a mutation class (GraphQL::Schema::Mutation) in app/graphql/mutations.'
+
+  private
+
+  def kind = :mutations
+
+  def body
+    <<~RUBY
+      # Resolves Mutation.#{class_basename.camelize(:lower)}. Keyword arguments are the field's
+      # arguments in snake_case; `object` and `context` are available. Raise
+      # GraphQL::ExecutionError for failures the client should see.
+      class #{class_basename} < GraphQL::Schema::Mutation
+        def resolve(**args)
+          raise NotImplementedError
+        end
+      end
+    RUBY
+  end
+
+  def usage
+    "Mutation.#{class_basename.camelize(:lower)} resolves to #{full_class_name} — add the field to your SDL without a resolving directive."
+  end
+end

data/lib/generators/lighthouse/query_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'class_generator'
+
+# `rails generate lighthouse:query LatestPosts` — a GraphQL::Schema::Resolver
+# that `Query.latestPosts` resolves to by convention.
+class Lighthouse::Generators::QueryGenerator < Lighthouse::Generators::ClassGenerator
+  desc 'Generate a query class (GraphQL::Schema::Resolver) in app/graphql/queries.'
+
+  private
+
+  def kind = :queries
+
+  def body
+    <<~RUBY
+      # Resolves Query.#{class_basename.camelize(:lower)}. Keyword arguments are the field's
+      # arguments in snake_case; `object` and `context` are available.
+      class #{class_basename} < GraphQL::Schema::Resolver
+        def resolve(**args)
+          raise NotImplementedError
+        end
+      end
+    RUBY
+  end
+
+  def usage
+    "Query.#{class_basename.camelize(:lower)} resolves to #{full_class_name} — add the field to your SDL without a resolving directive."
+  end
+end

data/lib/generators/lighthouse/validator_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'class_generator'
+
+# `rails generate lighthouse:validator CreatePostInput` — a
+# Dry::Validation::Contract for @validator. Name it after an input type
+# (CreatePostInputValidator) or a field (Mutation::CreatePostValidator).
+class Lighthouse::Generators::ValidatorGenerator < Lighthouse::Generators::ClassGenerator
+  desc 'Generate a validator (Dry::Validation::Contract) for @validator in app/graphql/validators.'
+
+  private
+
+  def kind = :validators
+
+  def class_basename
+    base = super
+    base.end_with?('Validator') ? base : "#{base}Validator"
+  end
+
+  def body
+    <<~RUBY
+      # Arguments arrive with snake_case keys. Remove `option :graphql_context`
+      # if the rules don't need the GraphQL context.
+      class #{class_basename} < Dry::Validation::Contract
+        option :graphql_context, optional: true
+
+        params do
+        end
+      end
+    RUBY
+  end
+
+  def usage
+    'Needs the dry-validation gem. Add @validator to the input type or field it is named after.'
+  end
+end

data/lib/lighthouse/cache_control.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# @cacheControl — compute the HTTP Cache-Control header a response may carry
+# from the fields a query selects, as PHP Lighthouse (after Apollo) does:
+#
+# - max-age is the lowest maxAge among the contributing fields; 0 means
+#   `no-cache`.
+# - The response is `private` if any selected field's scope is PRIVATE.
+# - Defaults: a root field is maxAge 0 and PRIVATE; any other field returning
+#   an object, interface or union is maxAge 0 unless its type carries
+#   @cacheControl; scalar fields inherit their parent and do not contribute.
+#   A directive on the field wins over one on its type, and its omitted
+#   arguments take the directive defaults (maxAge 0, PUBLIC).
+# - `inheritMaxAge: true` uses the parent field's maxAge.
+# - A mutation is never cacheable.
+#
+# The schema runs Analyzer on every query when its SDL uses @cacheControl;
+# read the result with CacheControl.header(result) and set it on the
+# response (see `apply`).
+module Lighthouse::GraphQL::CacheControl
+  DEFINITION = 'directive @cacheControl(maxAge: Int! = 0, scope: CacheControlScope! = PUBLIC, ' \
+               'inheritMaxAge: Boolean! = false) on FIELD_DEFINITION | OBJECT | INTERFACE | UNION'
+
+  TYPE_DEFINITIONS = {
+    'CacheControlScope' => <<~GRAPHQL.chomp
+      "Who a cached response may be shared with."
+      enum CacheControlScope {
+        "The same for every user: shared caches (CDNs, proxies) may store it."
+        PUBLIC
+        "Specific to the user: only the user's own client may store it."
+        PRIVATE
+      }
+    GRAPHQL
+  }.freeze
+
+  CONTEXT_KEY = :lighthouse_cache_control
+
+  module_function
+
+  # The Cache-Control value for an executed query (a GraphQL::Query::Result
+  # or GraphQL::Query), or nil when the schema does not use @cacheControl.
+  def header(result)
+    query = result.respond_to?(:query) ? result.query : result
+    query.respond_to?(:context) ? query.context[CONTEXT_KEY] : nil
+  end
+
+  # Set the header on a Rails (or Rack) response; a no-op without one.
+  def apply(response, result)
+    value = header(result)
+    response.headers['Cache-Control'] = value if value
+    value
+  end
+
+  def to_header(max_age, private_scope)
+    visibility = private_scope ? 'private' : 'public'
+    max_age.positive? ? "max-age=#{max_age}, #{visibility}" : "no-cache#{', private' if private_scope}"
+  end
+
+  class Analyzer < ::GraphQL::Analysis::Analyzer
+    def initialize(subject)
+      super
+      @parents = []
+      @max_age = nil
+      @private = false
+    end
+
+    def on_enter_field(node, _parent, visitor)
+      field = visitor.field_definition
+      return @parents.push(@parents.last) if field.nil? || visitor.skipping?
+
+      max_age, scope = hint_for(field)
+      unless max_age.nil?
+        @max_age = [@max_age, max_age].compact.min
+        @private ||= scope == 'PRIVATE'
+      end
+      @parents.push(max_age.nil? ? @parents.last : max_age)
+      node
+    end
+
+    def on_leave_field(_node, _parent, _visitor)
+      @parents.pop
+    end
+
+    def result
+      value =
+        if query.mutation?
+          'no-cache'
+        else
+          Lighthouse::GraphQL::CacheControl.to_header(@max_age || 0, @private)
+        end
+      query.context[CONTEXT_KEY] = value
+    end
+
+    private
+
+    def root?
+      @parents.empty?
+    end
+
+    # [maxAge, scope] the field contributes, or [nil, nil] to inherit.
+    def hint_for(field)
+      directive = cache_control(field.ast_node)
+      return from_directive(directive) if directive
+      return [0, 'PRIVATE'] if root?
+
+      return_type = field.type.unwrap
+      return [nil, nil] if return_type.kind.leaf?
+
+      type_directive = cache_control(return_type.ast_node)
+      type_directive ? from_directive(type_directive) : [0, 'PUBLIC']
+    end
+
+    def from_directive(directive)
+      scope = Lighthouse::Support::DirectiveArgs.literal(directive, 'scope') || 'PUBLIC'
+      if Lighthouse::Support::DirectiveArgs.literal(directive, 'inheritMaxAge')
+        [@parents.last || 0, scope]
+      else
+        [Lighthouse::Support::DirectiveArgs.literal(directive, 'maxAge') || 0, scope]
+      end
+    end
+
+    def cache_control(ast_node)
+      ast_node&.directives&.find { |d| d.name == 'cacheControl' }
+    end
+  end
+end

data/lib/lighthouse/caching.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'securerandom'
+
+# Keys and invalidation for @cache / @clearCache over Config.cache_store
+# (Rails.cache by default).
+#
+# PHP Lighthouse invalidates with cache tags, which Rails cache stores do not
+# have (and `delete_matched` is not universal). Instead every entry key embeds
+# four version tokens — the type, the type + parent id, the type + field, and
+# the type + parent id + field — and @clearCache replaces the matching token.
+# Old entries are never read again and expire on their own. A token that
+# was evicted is re-created with a fresh value, so eviction only ever causes
+# misses, never stale reads.
+module Lighthouse::GraphQL::Caching
+  PREFIX = 'lighthouse'
+
+  module_function
+
+  def store
+    Lighthouse::Config.cache_store
+  end
+
+  def entry_key(type, id, field, args, user_key)
+    tokens = versions(version_keys(type, id, field))
+    [PREFIX, type, id, field, digest(args), user_key, *tokens].join(':')
+  end
+
+  # @clearCache: invalidate everything cached for `type`, narrowed to one
+  # parent `id` and/or one `field` when given.
+  def clear(type, id: nil, field: nil)
+    key = version_key(type, id, field)
+    store.write(key, SecureRandom.hex(8))
+  end
+
+  def version_keys(type, id, field)
+    [version_key(type, nil, nil), version_key(type, id, nil), version_key(type, nil, field), version_key(type, id, field)]
+      .uniq
+  end
+
+  def version_key(type, id, field)
+    [PREFIX, 'version', type, id, field].join(':')
+  end
+
+  def versions(keys)
+    found = store.read_multi(*keys)
+    keys.map do |key|
+      found[key] || begin
+        store.write(key, SecureRandom.hex(8), unless_exist: true)
+        store.read(key)
+      end
+    end
+  end
+
+  def digest(args)
+    Digest::SHA256.hexdigest(JSON.generate(canonical(Lighthouse::Support::Arguments.plain(args))))[0, 32]
+  end
+
+  def canonical(value)
+    case value
+    when Hash then value.map { |k, v| [k.to_s, canonical(v)] }.sort_by(&:first)
+    when Array then value.map { |v| canonical(v) }
+    else value
+    end
+  end
+end