lighthouse-graphql 0.3.0 → 0.4.0

data/docs/security.md

@@ -0,0 +1,210 @@
+# Query Complexity & Depth
+
+A single GraphQL request can ask for a lot: a page of 1,000 posts, each with
+its 1,000 comments, each with its author. graphql-ruby can refuse such a query
+**before it runs**. It scores the query from the fields it selects, then
+compares the score with a limit you set. Lighthouse doesn't add a scorer of its
+own. It gives your SDL's fields their cost, and graphql-ruby's analyzers
+(`GraphQL::Analysis::MaxQueryComplexity`, `MaxQueryDepth`) do the rest. PHP
+Lighthouse works the same way on top of webonyx's validation rules.
+
+## Setting the limits
+
+The limits are graphql-ruby's own schema settings. Set them on the schema
+Lighthouse builds:
+
+```ruby
+# app/graphql/app_schema.rb
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(options: { using: { GraphQL::Dataloader => {} } })
+
+AppSchema.max_complexity(300)   # refuse queries that score over 300
+AppSchema.max_depth(12)         # refuse queries nested deeper than 12 fields
+AppSchema.disable_introspection_entry_points if Rails.env.production?
+```
+
+You can also set them on a base schema class you hand to `get_schema` with
+`options: { base_schema: MyBaseSchema }`.
+
+A query over the limit isn't executed. Its response holds only the error:
+
+```json
+{ "errors": [{ "message": "Query has complexity of 3001, which exceeds max complexity of 300" }] }
+```
+
+To give one request a different limit, pass it to `execute`:
+`AppSchema.execute(query, max_complexity: 1000)`.
+
+## How a query is scored
+
+Each selected field adds its cost, and a field's cost includes the cost of the
+fields selected inside it (its *child complexity*). By default, graphql-ruby
+counts **1 per field**:
+
+```graphql
+{ posts { id title author { name } } }   # posts 1 + id 1 + title 1 + author 1 + name 1 = 5
+```
+
+Lighthouse changes that default in three places:
+
+| Field | Cost |
+| --- | --- |
+| Paginated: `@paginate`, or `@hasMany` / `@belongsToMany` / `@morphMany` / `@morphToMany` given `type:` | `1 + child complexity × first` |
+| Carrying `@complexity` | `1 + child complexity × first`, or the `complexity` of the analyzer it names (below) |
+| Resolved by a `GraphQL::Schema::Resolver` class, by convention (`Query.search` → `Resolvers::Search`) or through `@field` | the `complexity` that class declares (default: `1 + child complexity`) |
+
+Paginated fields scale by `first`, which already holds the page size when the
+client leaves it out (the directive's `defaultCount`, else
+`pagination_default_count`). That way, asking for 1,000 items costs 1,000 times
+as much as asking for one:
+
+```graphql
+{ posts(first: 100) { data { id title } } }   # 1 + (data 1 + id 1 + title 1) × 100 = 301
+```
+
+For a connection (`type: CONNECTION`) the same rule applies, multiplying
+everything under `edges` and `pageInfo`, as PHP Lighthouse does. It replaces
+graphql-ruby's own connection scaling, which knows nothing about `defaultCount`.
+
+## `@complexity`
+
+Customize a field's cost, or attach a graphql-ruby analyzer to the schema.
+
+```graphql
+type Query {
+  "1 + child complexity × first, as on a paginated field."
+  search(first: Int, term: String!): [Post!]! @complexity
+
+  "What Analyzers::PostsComplexity says."
+  posts(includeFullText: Boolean): [Post!]! @all @complexity(resolver: "PostsComplexity")
+}
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `resolver: String` | A `GraphQL::Analysis::Analyzer` subclass, looked up in `namespaces[:analyzers]` (`Analyzers::PostsComplexity`). A name containing `::` is taken as written. |
+
+Without `resolver:`, the field costs `1 + child complexity × first` (`first` is 1
+when the field has no such argument).
+
+### The analyzer
+
+`resolver:` names a graphql-ruby analyzer, written as graphql-ruby's
+[analysis guide](https://graphql-ruby.org/queries/ast_analysis.html) writes it.
+Lighthouse installs it on the schema, as `query_analyzer Analyzers::PostsComplexity`
+would, once however many fields name it. Like every graphql-ruby analyzer, it
+runs on **every query**, not only those that select the field:
+
+```ruby
+# app/graphql/analyzers/agent_bot_analyzer.rb
+class Analyzers::AgentBotAnalyzer < GraphQL::Analysis::Analyzer
+  def analyze? = subject.context[:current_user].is_a?(AgentBot)
+
+  def on_enter_field(node, _parent, visitor)
+    @refused = true if visitor.parent_type_definition == visitor.query.schema.mutation
+  end
+
+  def result
+    GraphQL::AnalysisError.new('Bots may not run mutations') if @refused
+  end
+end
+```
+
+A field naming a plain analyzer costs what a bare `@complexity` gives. An
+analyzer that can't be found, or a class that isn't a
+`GraphQL::Analysis::Analyzer`, stops the schema from building
+(`Lighthouse::DefinitionError`).
+
+### Giving the field its cost: `Lighthouse::GraphQL::ComplexityAnalyzer`
+
+Include the concern, and the analyzer's `complexity` becomes the cost of the
+fields naming it. It's the `complexity` graphql-ruby gives a field or a
+`GraphQL::Schema::Resolver`: a number, added to the cost of the field's
+selection, or a proc called with the query's context, the field's arguments
+(snake_case Symbol keys) and the child complexity, returning the whole cost.
+
+As with resolvers and mutations, the concern goes once in a base class, and each
+analyzer that prices a field inherits from it:
+
+```ruby
+# app/graphql/analyzers/base_complexity.rb
+class Analyzers::BaseComplexity < GraphQL::Analysis::QueryComplexity
+  include Lighthouse::GraphQL::ComplexityAnalyzer
+end
+
+# app/graphql/analyzers/posts_complexity.rb
+class Analyzers::PostsComplexity < Analyzers::BaseComplexity
+  complexity ->(_context, args, child_complexity) { child_complexity * (args[:include_full_text] ? 3 : 2) }
+end
+```
+
+`complexity 5` gives a fixed cost: 5 plus the selection's. A subclass inherits
+its superclass's `complexity`. Without one, the field costs what a bare
+`@complexity` gives. The cost wins over the pagination default.
+
+The class is still an analyzer. With a `result` of its own, it runs on every
+query like any other, so one class can price a field and act on the whole query,
+for example refusing a guest's query over a smaller budget:
+
+```ruby
+class Analyzers::PostsComplexity < Analyzers::BaseComplexity
+  complexity 10
+
+  def result
+    cost = max_possible_complexity
+    return if query.context[:current_user] || cost <= 200
+
+    GraphQL::AnalysisError.new("Guests may run queries up to 200, this one costs #{cost}")
+  end
+end
+```
+
+Without a `result` of its own, it only gives costs, and graphql-ruby skips it
+during analysis.
+
+## Resolver classes declare their own cost
+
+A root field without a resolving directive resolves to a
+`GraphQL::Schema::Resolver` by convention (see [resolvers.md](resolvers.md)).
+That class's `complexity` applies, exactly as with graphql-ruby's
+`field :search, resolver: Resolvers::Search`:
+
+```ruby
+class Resolvers::Search < Resolvers::BaseResolver
+  complexity ->(_ctx, args, child_complexity) { args[:limit] * child_complexity }
+
+  def resolve(term:, limit:) = Post.search(term).limit(limit)
+end
+```
+
+The same goes for a class named by `@field(resolver:)`, and for a mutation
+class. An explicit `@complexity` on the field takes precedence over the class.
+
+## Reading the score
+
+`BuildExtensionsResponse` carries the score as `query_complexity`. It's the same
+number `max_complexity` is checked against, so you can report it to clients or
+to your metrics:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::BuildExtensionsResponse) do |event|
+  Lighthouse::Events::ExtensionsResponse.new('complexity', event.query_complexity)
+end
+# => { "data" => {...}, "extensions" => { "complexity" => 301 } }
+```
+
+The query is scored only while something listens to that event, and a query
+that failed validation is never scored (`query_complexity` is `nil`). A query
+refused for going over `max_complexity` still carries its score, so you can log
+what was refused. See
+[events.md](events.md#execution-events).
+
+To score a query yourself, run graphql-ruby's analyzer:
+
+```ruby
+query = GraphQL::Query.new(AppSchema, '{ posts(first: 10) { data { id } } }')
+GraphQL::Analysis.analyze_query(query, [GraphQL::Analysis::QueryComplexity]).first # => 21
+```
+
+`QueryComplexity` logs a warning unless the schema chooses an algorithm with
+`AppSchema.complexity_cost_calculation_mode(:future)`. `max_complexity` and
+`query_complexity` always use the `:future` algorithm.

data/docs/subscriptions.md

@@ -6,9 +6,12 @@ happens. Lighthouse builds on [graphql-ruby's subscriptions](https://graphql-rub
 and keeps the shape of [PHP Lighthouse's](https://lighthouse-php.com/master/subscriptions/getting-started.html):
 
 - a `Subscription` field is declared in the SDL, and **resolves by convention** to a class;
-- that class is a plain graphql-ruby [`GraphQL::Schema::Subscription`](https://graphql-ruby.org/subscriptions/subscription_classes.html),
-  as a query is a `GraphQL::Schema::Resolver` and a mutation a `GraphQL::Schema::Mutation`
-  (see [resolvers.md](resolvers.md));
+- that class inherits from `Subscriptions::BaseSubscription`, a graphql-ruby
+  [`GraphQL::Schema::Subscription`](https://graphql-ruby.org/subscriptions/subscription_classes.html),
+  as a `Query` field's class is a `Resolvers::BaseResolver` and a mutation's a
+  `Mutations::BaseMutation` (see [resolvers.md](resolvers.md#base-classes)). The base
+  includes [Lighthouse's concern](#the-subscription-concern): PHP
+  Lighthouse's model, one topic per field and a `filter?`;
 - a mutation announces what it did with [`@broadcast`](#broadcast-from-a-mutation).
 
 ```graphql
@@ -23,10 +26,10 @@ type Mutation {
 
 ```ruby
 # app/graphql/subscriptions/post_updated.rb  (rails generate lighthouse:subscription PostUpdated)
-class Subscriptions::PostUpdated < GraphQL::Schema::Subscription
-  # Runs for each update: skip the subscribers who may not see this post.
-  def update(**)
-    object.published? || object.author == context[:current_user] ? object : NO_UPDATE
+class Subscriptions::PostUpdated < Subscriptions::BaseSubscription
+  # For each broadcast: skip the subscribers who may not see this post.
+  def filter?(post, **)
+    post.published? || post.author == context[:current_user]
   end
 end
 ```
@@ -94,12 +97,14 @@ type Subscription {
 }
 ```
 
-For anything more, write the class (a field with no class of its own behaves like
-the concern's field-wide topic with no `filter?`). `Subscription.postUpdated` resolves to
+For anything more, write the class. (A field with no class of its own resolves with
+the schema's `base_types[:subscription]`, else with a built-in class that includes
+the concern: one topic for the field, no `filter?`.) `Subscription.postUpdated` resolves to
 `Subscriptions::PostUpdated`, looked up in `Config.namespaces[:subscriptions]`
 (default `['Subscriptions']`) each time it is needed, so code reloading works.
 `rails generate lighthouse:subscription PostUpdated` writes it. It inherits from
-`GraphQL::Schema::Subscription`: anything you know from graphql-ruby applies.
+`Subscriptions::BaseSubscription`, a `GraphQL::Schema::Subscription`: anything you
+know from graphql-ruby applies.
 
 Like a query or a mutation class, it declares neither the arguments nor the return
 type: the SDL does. The field's arguments arrive as `snake_case` keywords.
@@ -109,7 +114,10 @@ type: the SDL does. The field's arguments arrive as `snake_case` keywords.
 graphql-ruby calls the class twice in a subscription's life: once for the
 **subscription request** (the client's `subscription { ... }`), and then once for
 **each update** (`@broadcast`, or `schema.subscriptions.trigger`). All hooks are
-optional.
+optional. These are graphql-ruby's own; the concern `BaseSubscription` includes
+implements `authorized?` and `update` with PHP Lighthouse's hooks
+([below](#the-subscription-concern)), and a class that defines them itself
+keeps graphql-ruby's behavior.
 
 | Hook | Called | Default |
 | --- | --- | --- |
@@ -135,7 +143,7 @@ optional.
   field comes back `null`, with no error.
 
 ```ruby
-class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
+class Subscriptions::OrderShipped < Subscriptions::BaseSubscription
   def authorized?(**)
     raise GraphQL::ExecutionError, 'Sign in to follow your orders.' unless context[:current_user]
 
@@ -145,8 +153,6 @@ class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
   def update(**)
     object.user_id == context[:current_user].id ? object : NO_UPDATE
   end
-
-  def self.trigger_arguments(_order, _context) = {}
 end
 ```
 
@@ -164,22 +170,32 @@ If you know PHP Lighthouse's `GraphQLSubscription`, this is where its methods we
 One real difference is the **topic**. PHP Lighthouse puts every subscriber of a
 field on one topic and `filter` decides who is updated. graphql-ruby's default
 topic includes the arguments, so a trigger reaches only the subscribers whose
-arguments *equal* its own. That is why `@broadcast` asks a plain class for its
-`trigger_arguments`; see [below](#topics-trigger-arguments-and-filtering).
+arguments *equal* its own. The concern in `BaseSubscription` takes PHP Lighthouse's
+topic; a class that keeps graphql-ruby's gives `@broadcast` its `trigger_arguments`.
+See [below](#topics-trigger-arguments-and-filtering).
 
-## Lighthouse's subscription concern
+## The subscription concern
 
-If you prefer PHP Lighthouse's model, with one topic per field, `filter?` to narrow
-it and `resolve_payload` for the result, include `Lighthouse::GraphQL::Subscription`
-in the class, as `include Lighthouse::GraphQL::Controller` gives a controller its
-`execute`. The class is still a plain `GraphQL::Schema::Subscription`, and declares
-its arguments as one would in graphql-ruby (or leaves them to the SDL).
-`rails generate lighthouse:subscription PostUpdated --lighthouse` writes it:
+`Lighthouse::GraphQL::Subscription` is PHP Lighthouse's model: one topic per field,
+`filter?` to narrow it and `resolve_payload` for the result. It is included once, in
+the base every subscription inherits from, as graphql-ruby's convention puts what
+all classes of a kind share in their base:
 
 ```ruby
-class Subscriptions::PostUpdated < GraphQL::Schema::Subscription
-  include Lighthouse::GraphQL::Subscription
+# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install)
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+A subscription is still a plain `GraphQL::Schema::Subscription`, and declares its
+arguments as one would in graphql-ruby (or leaves them to the SDL).
+`rails generate lighthouse:subscription PostUpdated` writes one with the hooks:
 
+```ruby
+class Subscriptions::PostUpdated < Subscriptions::BaseSubscription
   def filter?(post, author: nil)
     author.nil? || post.author_id.to_s == author.to_s
   end
@@ -205,17 +221,19 @@ optional.
   [broadcast section](#topics-trigger-arguments-and-filtering) explain.
 - Including it in a class that is not a `GraphQL::Schema::Subscription` raises a
   `Lighthouse::DefinitionError`.
+- To keep graphql-ruby's model for every subscription, leave the `include` out of
+  `BaseSubscription`; the generator then writes classes with `authorized?` and
+  `update` instead.
 - **Precedence.** The concern sits between your class and
-  `GraphQL::Schema::Subscription`, so what the class defines itself wins. A class
+  `GraphQL::Schema::Subscription` (it is in the base), so what the class defines
+  itself wins. A class
   with its own `update` (or `authorized?`) is called instead of the concern's, and
   its `filter?`, `resolve_payload` (or `authorize?`) are not, unless it calls
   `super`. `subscribe`, `unsubscribe`, `subscription_scope` and `ready?` are
   untouched, and combine freely with the hooks.
 
 ```ruby
-class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
-  include Lighthouse::GraphQL::Subscription
-
+class Subscriptions::OrderShipped < Subscriptions::BaseSubscription
   def authorize?(**)
     context[:current_user].present?
   end
@@ -251,8 +269,9 @@ type Subscription {
 
 The name is looked up in `Config.namespaces[:subscriptions]` like the conventional
 one, so `class: "PostUpdated"` finds `Subscriptions::PostUpdated`, and a name with
-`::` is used as it is. A class that does not exist, or is not a
-`GraphQL::Schema::Subscription`, raises `Lighthouse::DefinitionError`.
+`::` is used as it is. A class that does not exist, is not a
+`GraphQL::Schema::Subscription`, or does not inherit from the schema's
+`base_types[:subscription]` raises `Lighthouse::DefinitionError`.
 `@guard`, `@can*` and the other wrapping directives work on a subscription field
 as on any other.
 
@@ -303,7 +322,8 @@ arguments (a Hash, `{}` by default) for the `root` a mutation returned, and
 `subscription_scope` (graphql-ruby's way to give each tenant or user their own
 stream).
 
-With a plain `GraphQL::Schema::Subscription`:
+When the topic includes the arguments (a class with `topic_by :arguments`, or under
+a base that does not include the concern):
 
 - **A field without arguments works out of the box.** Every subscriber's arguments
   are `{}`, and so is the trigger's.
@@ -317,7 +337,9 @@ With a plain `GraphQL::Schema::Subscription`:
   ```
 
   ```ruby
-  class Subscriptions::MessagePosted < GraphQL::Schema::Subscription
+  class Subscriptions::MessagePosted < Subscriptions::BaseSubscription
+    topic_by :arguments
+
     # The subscribers of `messagePosted(room: "<id>")`.
     def self.trigger_arguments(message, _context) = { room: message.room_id.to_s }
   end
@@ -336,11 +358,11 @@ With a plain `GraphQL::Schema::Subscription`:
   those subscribers are updated, so give such a class a `trigger_arguments` too if
   subscribers pass the argument.
 - **To have one trigger reach subscribers with different arguments** (the argument
-  is a filter, not an identity), give the class one topic per field, as
-  graphql-ruby documents, and let `update` return `NO_UPDATE`:
+  is a filter, not an identity) without the concern, give the class one topic per
+  field, as graphql-ruby documents, and let `update` return `NO_UPDATE`:
 
   ```ruby
-  class Subscriptions::PostPublished < GraphQL::Schema::Subscription
+  class Subscriptions::PostPublished < Subscriptions::BaseSubscription # a base without the concern
     def self.topic_for(field:, scope:, **)
       GraphQL::Subscriptions::Serialize.dump_recursive([scope, field.graphql_name])
     end
@@ -417,7 +439,8 @@ the repository's own specs do, in `spec/support/in_memory_subscriptions.rb`.
 graphql-ruby also ships `GraphQL::Testing::MockActionCable` for the real
 ActionCable backend.
 
-The repository's `example/` app is a complete setup: plain subscription classes,
+The repository's `example/` app is a complete setup: subscription classes under
+`Subscriptions::BaseSubscription`,
 `GraphqlChannel`, `ApplicationCable::Connection` with token authentication, and
 specs that drive a mutation through `POST /graphql` and watch the update arrive on
 an ActionCable subscriber (`example/spec/subscriptions/delivery_spec.rb`).

data/lib/generators/lighthouse/base_classes.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'lighthouse-graphql'
+
+# The base class graphql-ruby's convention puts in each namespace:
+# Resolvers::BaseResolver, Mutations::BaseMutation and
+# Subscriptions::BaseSubscription. The classes Lighthouse generates inherit from
+# them, so what every class of a kind shares (a concern, graphql-ruby's base type
+# hookups) is written once, in the base. graphql-ruby's `graphql:install` writes
+# the first two the same way.
+#
+# A base that already exists is never replaced, not even with --force: it holds
+# the app's own code, and one written by graphql-ruby works as it is.
+module Lighthouse::Generators::BaseClasses
+  BASES = {
+    queries: {
+      name: 'BaseResolver',
+      source: <<~RUBY
+        # What every class resolving a Query field shares: Lighthouse resolves
+        # Query.latestPosts to Resolvers::LatestPosts by convention, and every such
+        # class inherits from this one. graphql-ruby's `graphql:install` writes the
+        # same class.
+        class BaseResolver < GraphQL::Schema::Resolver
+        end
+      RUBY
+    },
+    mutations: {
+      name: 'BaseMutation',
+      source: <<~RUBY
+        # What every class resolving a Mutation field shares: Lighthouse resolves
+        # Mutation.publishPost to Mutations::PublishPost by convention, and every such
+        # class inherits from this one. The SDL declares the arguments, so it is a
+        # plain GraphQL::Schema::Mutation; the GraphQL::Schema::RelayClassicMutation
+        # graphql-ruby's `graphql:install` writes (one `input:` argument) works too.
+        class BaseMutation < GraphQL::Schema::Mutation
+        end
+      RUBY
+    },
+    subscriptions: {
+      name: 'BaseSubscription',
+      source: <<~RUBY
+        # What every class resolving a Subscription field shares. The concern is PHP
+        # Lighthouse's model: every subscriber of a field gets every broadcast, and the
+        # class's `filter?` decides who receives it. A subclass that defines
+        # graphql-ruby's own `authorized?` or `update` keeps them, and `topic_by
+        # :arguments` brings back graphql-ruby's exact-argument matching.
+        class BaseSubscription < GraphQL::Schema::Subscription
+          include Lighthouse::GraphQL::Subscription
+        end
+      RUBY
+    }
+  }.freeze
+
+  private
+
+  # The base class name for `kind` (`BaseResolver`), or nil for a kind without one.
+  def base_class_name(kind)
+    BASES.dig(kind, :name)
+  end
+
+  # Write the base class of `kind` into `namespace`, unless its file exists.
+  def write_base_class(kind, namespace)
+    base = BASES[kind]
+    return unless base
+
+    path = base_class_path(kind, namespace)
+    if File.exist?(File.join(destination_root, path))
+      say_status :skip, "#{path} already exists", :yellow
+    else
+      create_file path, ruby_source(namespace.split('::'), base[:source])
+    end
+  end
+
+  def base_class_path(kind, namespace)
+    File.join('app/graphql', *namespace.split('::').map(&:underscore), "#{base_class_name(kind).underscore}.rb")
+  end
+
+  # Ruby source defining `body` inside the nested `modules`.
+  def ruby_source(modules, body)
+    lines = ['# frozen_string_literal: true', '']
+    modules.each_with_index { |mod, depth| lines << "#{'  ' * depth}module #{mod}" }
+    body.each_line { |line| lines << (line.strip.empty? ? '' : "#{'  ' * modules.size}#{line.chomp}") }
+    modules.size.times.reverse_each { |depth| lines << "#{'  ' * depth}end" }
+    "#{lines.join("\n")}\n"
+  end
+end

data/lib/generators/lighthouse/class_generator.rb

@@ -2,16 +2,25 @@
 
 require 'rails/generators'
 require 'lighthouse-graphql'
+require_relative 'base_classes'
 
 # Base for the generators that scaffold the classes a schema refers to by
-# name — queries, mutations, builders and validators — each in its own
-# namespace (Config.namespaces) and with its own contract.
+# name — resolvers, mutations, subscriptions, builders and validators — each in
+# its own namespace (Config.namespaces) and with its own contract. A resolver,
+# mutation or subscription inherits from its namespace's base class
+# (Resolvers::BaseResolver, ...), written first when it is missing.
 class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
+  include Lighthouse::Generators::BaseClasses
+
   hide!
 
   class_option :namespace, type: :string,
                            desc: 'Namespace to generate into (default: the first of Config.namespaces for this kind)'
 
+  def create_base_class
+    write_base_class(kind, namespace_name)
+  end
+
   def create_class
     create_file File.join('app/graphql', *modules.map(&:underscore), "#{class_basename.underscore}.rb"), source
   end
@@ -22,7 +31,7 @@ class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
 
   private
 
-  # :queries, :mutations, :builders or :validators.
+  # :queries, :mutations, :subscriptions, :builders or :validators.
   def kind
     raise NotImplementedError
   end
@@ -52,10 +61,12 @@ class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
   end
 
   def source
-    lines = ['# frozen_string_literal: true', '']
-    modules.each_with_index { |mod, depth| lines << "#{'  ' * depth}module #{mod}" }
-    body.each_line { |line| lines << (line.strip.empty? ? '' : "#{'  ' * modules.size}#{line.chomp}") }
-    modules.size.times.reverse_each { |depth| lines << "#{'  ' * depth}end" }
-    "#{lines.join("\n")}\n"
+    ruby_source(modules, body)
+  end
+
+  # The class a generated class inherits from: the namespace's base class,
+  # which Ruby finds from inside the namespace's modules.
+  def superclass_name
+    base_class_name(kind)
   end
 end

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

@@ -2,22 +2,26 @@
 
 require 'rails/generators'
 require 'lighthouse-graphql'
+require_relative '../base_classes'
 
 # `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.
+# the initializer, a starter SDL file, the schema class, the base classes of
+# resolvers, mutations and subscriptions, a controller and its route, plus the
+# graphql-config file IDEs read. Rerunning it skips the route, SDL, base classes
+# 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
+  include Lighthouse::Generators::BaseClasses
+
   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.'
+  desc 'Install Lighthouse: initializer, starter schema, schema class, base classes, controller, route and IDE config.'
 
   class_option :schema, type: :string, default: 'AppSchema',
                         desc: 'Name of the schema constant to generate'
@@ -48,6 +52,12 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     template 'schema.rb.tt', path
   end
 
+  # Resolvers::BaseResolver, Mutations::BaseMutation and Subscriptions::BaseSubscription,
+  # in the namespaces Config.namespaces names first (see BaseClasses).
+  def create_base_classes
+    BASES.each_key { |kind| write_base_class(kind, Lighthouse::Config.namespaces[kind].first) }
+  end
+
   def create_controller
     return if options[:skip_controller]
     return if (@kept_controller = keep_existing?(CONTROLLER))
@@ -93,8 +103,10 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
 
       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}
+        2. Resolve a field in Ruby when a directive is not enough:  bin/rails g lighthouse:query LatestPosts
+           (its class inherits from Resolvers::BaseResolver; mutations and subscriptions have a base too)
+        3. Generate the IDE helper files:  bin/rails lighthouse:ide_helper
+        4. #{serve}
     MSG
   end
 
@@ -113,6 +125,11 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     options[:schema].camelize
   end
 
+  # `Resolvers::BaseResolver`, for the schema class template.
+  def base_class_constant(kind)
+    "#{Lighthouse::Config.namespaces[kind].first}::#{base_class_name(kind)}"
+  end
+
   def sdl_folder
     options[:sdl_folder].delete_suffix('/')
   end

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

@@ -12,15 +12,16 @@ Lighthouse.configure do |config|
 
   # 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
+  # to Resolvers::LatestPosts (a Resolvers::BaseResolver), Mutation.publishPost
+  # to Mutations::PublishPost (a Mutations::BaseMutation). @builder classes
   # come from :builders and @validator contracts from :validators. A Subscription
-  # field resolves to Subscriptions::PostUpdated (a GraphQL::Schema::Subscription),
-  # and @event(dispatch:) classes come from :events. Generate them with
+  # field resolves to Subscriptions::PostUpdated (a Subscriptions::BaseSubscription),
+  # @event(dispatch:) classes come from :events, and the graphql-ruby analyzers
+  # @complexity(resolver:) names from :analyzers. Generate them with
   # `rails g lighthouse:query|mutation|subscription|builder|validator Name`.
   # config.namespaces = {
-  #   queries: ['Queries'], mutations: ['Mutations'], subscriptions: ['Subscriptions'],
-  #   builders: ['Builders'], validators: ['Validators'], events: ['Events']
+  #   queries: ['Resolvers'], mutations: ['Mutations'], subscriptions: ['Subscriptions'],
+  #   builders: ['Builders'], validators: ['Validators'], events: ['Events'], analyzers: ['Analyzers']
   # }
 
   # Namespaces tried, in order, for models (@all(model: "User")) and for