lighthouse-graphql 0.2.1 → 0.4.0

data/docs/getting-started.md

@@ -75,16 +75,44 @@ argument (the `@eq` makes `id` a filter). Lighthouse infers the model from the
 field's return type name (`User`), or you can be explicit with
 `@all(model: "User")`.
 
-## 2. Provide your base types
+## 2. Provide your base classes
 
-Lighthouse builds on graphql-ruby, so you supply the base classes it should use
-for objects, interfaces, etc. — exactly the place to mix in Apollo Federation or
-any custom field/argument behavior.
+Lighthouse builds on graphql-ruby, and follows its convention: each kind of class
+inherits from a base class in its own namespace, where what they all share goes
+once. `rails g lighthouse:install` writes the bases of the classes that resolve
+root fields:
 
 ```ruby
-# app/graphql/base_object.rb
-class BaseObject < GraphQL::Schema::Object
-  # include ApolloFederation::Object   # if you use federation
+# app/graphql/resolvers/base_resolver.rb       — Query fields (Resolvers::LatestPosts)
+module Resolvers
+  class BaseResolver < GraphQL::Schema::Resolver
+  end
+end
+
+# app/graphql/mutations/base_mutation.rb       — Mutation fields (Mutations::PublishPost)
+module Mutations
+  class BaseMutation < GraphQL::Schema::Mutation
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb — Subscription fields
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+The SDL's types can have graphql-ruby base classes too, as `graphql:install`
+writes them: the place to mix in Apollo Federation or custom field and argument
+behavior.
+
+```ruby
+# app/graphql/types/base_object.rb
+module Types
+  class BaseObject < GraphQL::Schema::Object
+    # include ApolloFederation::Object   # if you use federation
+  end
 end
 ```
 
@@ -98,13 +126,22 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   sdl_folder: Rails.root.join('graphql').to_s,
   options: {
     base_types: {
-      object: BaseObject,
+      resolver: Resolvers::BaseResolver,
+      mutation: Mutations::BaseMutation,
+      subscription: Subscriptions::BaseSubscription,
+      object: Types::BaseObject,
       # interface:, union:, enum:, input_object:, scalar: ...
     }
   }
 )
 ```
 
+`object:` and the other SDL kinds go to graphql-ruby, which builds the SDL's types
+from them. `resolver:`, `mutation:` and `subscription:` are Lighthouse's: every
+class a `Query`, `Mutation` or `Subscription` field resolves to must inherit from
+its kind's base, and a `Subscription` field with no class of its own resolves with
+the subscription base. See [resolvers.md](resolvers.md#base-classes).
+
 `get_schema` returns a `GraphQL::Schema` subclass you can use directly, or
 subclass further (e.g. to add federation, tracing, a Dataloader):
 
@@ -119,22 +156,51 @@ end
 
 ## 4. Serve it
 
-A standard graphql-ruby controller:
+`rails g lighthouse:install` writes the controller. It includes
+`Lighthouse::GraphQL::Controller`, a concern that serves the schema:
 
 ```ruby
 class GraphqlController < ApplicationController
-  def execute
-    result = AppSchema.execute(
-      params[:query],
-      variables: params[:variables],
-      context: { current_user: current_user },
-      operation_name: params[:operationName]
-    )
-    render json: result
+  include Lighthouse::GraphQL::Controller
+
+  lighthouse_schema AppSchema   # or 'AppSchema', or a block: lighthouse_schema { AppSchema }
+
+  private
+
+  # What @guard and the @can* directives read. Defaults to
+  # { current_user: current_user } when the controller has a current_user.
+  def graphql_context = { current_user: current_user }
+end
+```
+
+Route to it (`post '/graphql', to: 'graphql#execute'`, plus a `get` for
+[persisted queries](performance.md#persisted-queries) if you use them). Its
+`execute` action:
+
+- dispatches the [`StartRequest` and `EndRequest` events](events.md);
+- reads `variables` (a JSON string, as a GET carries it, or parameters);
+- runs the operation through `PersistedQueries.execute`, so
+  [Automatic Persisted Queries](performance.md#persisted-queries) work once
+  `config.persisted_queries` is on, and a JSON array body runs as a batch;
+- sets the `Cache-Control` header the selected fields'
+  [`@cacheControl`](caching.md) hints allow;
+- renders the JSON; in development an error renders as JSON with its backtrace.
+
+The hooks `graphql_context`, `graphql_schema` and `graphql_variables(param)` are
+private methods you can override. A controller with an action of its own wraps it
+in `lighthouse_request { ... }` to keep the request events:
+
+```ruby
+def search
+  lighthouse_request do
+    render json: Lighthouse::GraphQL::PersistedQueries.execute(AppSchema, query: params[:q], context: graphql_context)
   end
 end
 ```
 
+Not on the concern? Plain graphql-ruby works too:
+`render json: AppSchema.execute(params[:query], variables: params[:variables], context: { current_user: current_user })`.
+
 ## 5. Configure (optional)
 
 Create an initializer to wire app-specific settings. This is also the single
@@ -218,18 +284,19 @@ type User {
 }
 ```
 
-## Custom queries and mutations
+## Custom resolvers and mutations
 
 When a field needs Ruby, write a graphql-ruby resolver or mutation class named
-after it — `Query.latestPosts` resolves to `Queries::LatestPosts`
-(`app/graphql/queries/latest_posts.rb`), `Mutation.publishPost` to
-`Mutations::PublishPost`. `bin/rails generate lighthouse:query LatestPosts`
-scaffolds one. See [resolvers.md](resolvers.md).
+after it — `Query.latestPosts` resolves to `Resolvers::LatestPosts`
+(`app/graphql/resolvers/latest_posts.rb`, a `Resolvers::BaseResolver`),
+`Mutation.publishPost` to `Mutations::PublishPost` (a `Mutations::BaseMutation`).
+`bin/rails generate lighthouse:query LatestPosts` scaffolds one. See
+[resolvers.md](resolvers.md).
 
 ## Next steps
 
 - [Directives reference](directives.md) — the full vocabulary.
-- [Queries, mutations & builders](resolvers.md), [Mutations](mutations.md),
+- [Resolvers, mutations & builders](resolvers.md), [Mutations](mutations.md),
   [Validation](validation.md), [Caching](caching.md).
 - [Relationships](relationships.md) — wiring associations.
 - [Filtering & ordering](filtering-and-ordering.md) — query constraints.

data/docs/motivation.md

@@ -151,8 +151,9 @@ Schema-first doesn't mean schema-only. When a field does something no directive
 describes, write Ruby, using graphql-ruby's own classes:
 
 - A `Query` or `Mutation` field without a resolving directive resolves by convention to
-  `Queries::FieldName` (a `GraphQL::Schema::Resolver`) or `Mutations::FieldName` (a
-  `GraphQL::Schema::Mutation`). See [Queries, Mutations and Builders](resolvers.md).
+  `Resolvers::FieldName` (a `Resolvers::BaseResolver`) or `Mutations::FieldName` (a
+  `Mutations::BaseMutation`), under the base classes graphql-ruby's convention gives
+  each kind. See [Resolvers, Mutations and Builders](resolvers.md).
 - `@builder` classes adjust a query; `@validator` contracts check arguments.
 - Your own directives plug in through the registry, with the same contracts as the
   built-in ones. See [Custom Directives](custom-directives.md).

data/docs/mutations.md

@@ -96,6 +96,21 @@ Without a filter argument, it refuses to run, since it would delete every row:
 abort the destroy is reported next to the data:
 `Could not modify model Post with ID 1.`
 
+### `@forceDelete` and `@restore`
+
+`@forceDelete` permanently removes soft deleted models and `@restore` un-deletes
+them. They work very much like `@delete` (required filter arguments, the models
+returned, `model:` and `scopes:`), but also find the models the soft-delete
+strategy hides. See [Soft deletes & global
+scopes](directives.md#soft-deletes-global-scopes).
+
+```graphql
+type Mutation {
+  forceDeletePost(id: ID! @whereKey): Post @forceDelete
+  restorePost(id: ID! @whereKey): Post @restore
+}
+```
+
 ## Validation errors
 
 When a model does not save, the mutation fails with PHP Lighthouse's error

data/docs/resolvers.md

@@ -1,22 +1,92 @@
-# Queries, Mutations and Builders
+# Resolvers, Mutations and Builders
 
 Most fields need no Ruby: a directive (`@all`, `@find`, `@paginate`, `@create`,
 …) or the default attribute reader resolves them. For the rest, Lighthouse looks
-up a class by name. There are three kinds of class, and they are not
+up a class by name. There are several kinds of class, and they are not
 interchangeable. Each kind has its own contract and its own folder:
 
 | Kind | Folder / namespace | Contract | Used by |
 | --- | --- | --- | --- |
-| Query | `app/graphql/queries` · `Queries::` | `GraphQL::Schema::Resolver` | `Query` fields |
-| Mutation | `app/graphql/mutations` · `Mutations::` | `GraphQL::Schema::Mutation` | `Mutation` fields |
+| Resolver | `app/graphql/resolvers` · `Resolvers::` | `Resolvers::BaseResolver` (a `GraphQL::Schema::Resolver`) | `Query` fields |
+| Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (a `GraphQL::Schema::Mutation`) | `Mutation` fields |
+| Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `Subscriptions::BaseSubscription` (a `GraphQL::Schema::Subscription`) | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
 Validators (`app/graphql/validators`) are the fourth kind. They are covered in
 [validation.md](validation.md).
 
-## Queries and mutations: graphql-ruby's contract
+## Base classes
 
-A query or mutation class is a plain graphql-ruby
+As in any graphql-ruby app, each of the first three kinds has a base class in its
+namespace, and every class of the kind inherits from it:
+
+```ruby
+# app/graphql/resolvers/base_resolver.rb
+module Resolvers
+  class BaseResolver < GraphQL::Schema::Resolver
+  end
+end
+
+# app/graphql/mutations/base_mutation.rb
+module Mutations
+  class BaseMutation < GraphQL::Schema::Mutation
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+What every class of a kind shares goes in its base, once: a concern (as
+`BaseSubscription` includes Lighthouse's, see [subscriptions.md](subscriptions.md)),
+a helper, graphql-ruby settings such as `argument_class Types::BaseArgument`.
+`rails g lighthouse:install` writes the three, and the class generators write the
+one they need when it is missing. graphql-ruby's own `graphql:install` writes
+`Resolvers::BaseResolver` and `Mutations::BaseMutation` too, and Lighthouse keeps
+whatever is already there: an existing base is never replaced.
+
+### Handing the bases to the schema
+
+Name the bases in `base_types`, beside graphql-ruby's own base types, and the
+schema holds every class to them:
+
+```ruby
+# app/graphql/app_schema.rb
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    base_types: {
+      resolver: Resolvers::BaseResolver,
+      mutation: Mutations::BaseMutation,
+      subscription: Subscriptions::BaseSubscription
+      # object: Types::BaseObject, ... (graphql-ruby's, for the SDL's types)
+    }
+  }
+)
+```
+
+- A class a `Query`, `Mutation` or `Subscription` field resolves to, by convention
+  or through `@subscription(class:)`, that does not inherit from its kind's base
+  raises `Lighthouse::DefinitionError` when the field is first used (`…so it must
+  inherit from Resolvers::BaseResolver…`). No class misses what the base shares.
+- A `Subscription` field with no class of its own resolves with the subscription
+  base, so its concern and settings apply there too.
+- A base must be a subclass of the graphql-ruby class of its kind
+  (`GraphQL::Schema::Resolver`, `GraphQL::Schema::Mutation`, which
+  `RelayClassicMutation` is, `GraphQL::Schema::Subscription`), or the schema does not
+  build. graphql-ruby never sees these three keys.
+
+`rails g lighthouse:install` writes the schema class with them. Without them,
+Lighthouse requires only the graphql-ruby class (`GraphQL::Schema::Resolver`, …),
+and a `Subscription` field with no class resolves with a built-in subscription that
+includes the concern.
+
+## Resolvers and mutations: graphql-ruby's contract
+
+A resolver or mutation class is a plain graphql-ruby
 [resolver](https://graphql-ruby.org/fields/resolvers.html) or
 [mutation](https://graphql-ruby.org/mutations/mutation_classes.html), so everything
 you know from graphql-ruby applies:
@@ -39,9 +109,9 @@ type Mutation {
 ```
 
 ```ruby
-# app/graphql/queries/latest_posts.rb
-module Queries
-  class LatestPosts < GraphQL::Schema::Resolver
+# app/graphql/resolvers/latest_posts.rb
+module Resolvers
+  class LatestPosts < BaseResolver
     def resolve(limit: 10)
       Post.order(created_at: :desc).limit(limit)
     end
@@ -50,7 +120,7 @@ end
 
 # app/graphql/mutations/publish_post.rb
 module Mutations
-  class PublishPost < GraphQL::Schema::Mutation
+  class PublishPost < BaseMutation
     def authorized?(id:)
       context[:current_user]&.admin? || raise(GraphQL::ExecutionError, 'Admins only.')
     end
@@ -67,7 +137,7 @@ end
 A field on `Query` or `Mutation` with **no resolving directive** resolves to the
 class named after it, as in PHP Lighthouse:
 
-- `Query.latestPosts` resolves to `Queries::LatestPosts`;
+- `Query.latestPosts` resolves to `Resolvers::LatestPosts`;
 - `Mutation.publishPost` resolves to `Mutations::PublishPost`.
 
 The class is looked up on each call, so code reloading works. Classes found by
@@ -77,8 +147,8 @@ field with no class is reported through [`on_error`](configuration.md#on_error):
 it raises in test and logs elsewhere. Lighthouse never falls back to a top-level
 constant, so a `post` field is never mistaken for the `Post` model.
 
-graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` generates
-`Mutations::BaseMutation` from) works too, as long as the SDL field takes the
+graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` makes
+`Mutations::BaseMutation` inherit from) works too, as long as the SDL field takes the
 `input:` argument it expects.
 
 Wrapping directives (`@guard`, the `@can*` family, `@validator`, `@cache`,
@@ -94,12 +164,12 @@ type Mutation {
 ### Naming a class explicitly
 
 `@field(resolver:)` points a field at a class by name. On `Query` and `Mutation`
-the name is looked up in the queries and mutations namespaces; on any other type,
+the name is looked up in the resolvers and mutations namespaces; on any other type,
 in [`resolver_namespaces`](configuration.md#resolver_namespaces).
 
 ```graphql
 type Query {
-  feed: [Post!]! @field(resolver: "Feeds::Home")   # Queries::Feeds::Home
+  feed: [Post!]! @field(resolver: "Feeds::Home")   # Resolvers::Feeds::Home
 }
 ```
 
@@ -165,15 +235,18 @@ end
 ## Generators
 
 ```shell
-bin/rails generate lighthouse:query LatestPosts        # app/graphql/queries/latest_posts.rb
+bin/rails generate lighthouse:query LatestPosts        # app/graphql/resolvers/latest_posts.rb
 bin/rails generate lighthouse:mutation PublishPost     # app/graphql/mutations/publish_post.rb
+bin/rails generate lighthouse:subscription PostUpdated # app/graphql/subscriptions/post_updated.rb
 bin/rails generate lighthouse:builder Published        # app/graphql/builders/published.rb
 bin/rails generate lighthouse:validator CreatePostInput # app/graphql/validators/create_post_input_validator.rb
 ```
 
 Each one writes the class with its contract, into the first namespace configured
-for its kind (or `--namespace=…`). Namespaced names nest modules:
-`lighthouse:mutation Blog::Publish` writes `Mutations::Blog::Publish`. These
+for its kind (or `--namespace=…`). A resolver, mutation or subscription inherits
+from the namespace's base class, which is written first when it is missing.
+Namespaced names nest modules: `lighthouse:mutation Blog::Publish` writes
+`Mutations::Blog::Publish < BaseMutation`. These
 generators do not collide with graphql-ruby's `graphql:*` generators. A
 `lighthouse:mutation` and a `graphql:mutation` of the same name target the same
 file, and Rails asks before overwriting it.
@@ -182,8 +255,11 @@ file, and Rails asks before overwriting it.
 
 ```ruby
 Lighthouse.configure do |config|
-  config.namespaces = { queries: ['Api::Queries'], mutations: ['Api::Mutations'] }
+  config.namespaces = { queries: ['Api::Resolvers'], mutations: ['Api::Mutations'] }
 end
 ```
 
 Kinds you leave out keep their defaults. Each kind takes a list, tried in order.
+The `queries` kind is the classes of `Query` fields. Before 0.4.0 it defaulted to
+`Queries`; an app keeping its classes in `app/graphql/queries` sets
+`config.namespaces = { queries: ['Queries'] }`.

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.