lighthouse-graphql 0.3.0 → 0.5.0

data/docs/resolvers.md

@@ -1,4 +1,4 @@
-# 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
@@ -7,17 +7,101 @@ 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 |
-| Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `GraphQL::Schema::Subscription` | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
+| 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)) |
+| Type | `app/graphql/types` · `Types::` | `Types::BaseObject` (a `GraphQL::Schema::Object`) including `Lighthouse::GraphQL::Type`, named `<Type>Type` | Fields of other types, through its methods ([type classes](#type-classes)); unions, interfaces and scalars too ([types.md](types.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
-Validators (`app/graphql/validators`) are the fourth kind. They are covered in
+Validators (`app/graphql/validators`) are one more 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 kind of class has a base class in its namespace,
+and every class of the kind inherits from it. graphql-ruby's `graphql:install`,
+which `rails g lighthouse:install` runs, writes `Resolvers::BaseResolver`,
+`Mutations::BaseMutation` and the `Types::Base*` classes; Lighthouse adds
+`Subscriptions::BaseSubscription`, which graphql-ruby has none of, and makes the
+mutation base a plain `GraphQL::Schema::Mutation`, as the SDL declares a mutation's
+arguments ([generators.md](generators.md)):
+
+```ruby
+# app/graphql/resolvers/base_resolver.rb          (graphql-ruby's)
+module Resolvers
+  class BaseResolver < GraphQL::Schema::Resolver
+  end
+end
+
+# app/graphql/mutations/base_mutation.rb          (graphql-ruby's, made a Mutation)
+module Mutations
+  class BaseMutation < GraphQL::Schema::Mutation
+    argument_class Types::BaseArgument
+    field_class Types::BaseField
+    object_class Types::BaseObject
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's)
+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`. 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,
+      interface: Types::BaseInterface,
+      union: Types::BaseUnion,
+      scalar: Types::BaseScalar,
+      enum: Types::BaseEnum,
+      input_object: Types::BaseInputObject
+    }
+  }
+)
+```
+
+- 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.
+- The others are graphql-ruby's: it builds the SDL's types of each kind from them.
+  A [type class](#type-classes) (one including `Lighthouse::GraphQL::Type`) that
+  does not inherit from its kind's raises `Lighthouse::DefinitionError` when the
+  schema is built.
+
+`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:
@@ -40,9 +124,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
@@ -51,7 +135,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
@@ -68,7 +152,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
@@ -78,8 +162,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`,
@@ -95,17 +179,243 @@ 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
 }
 ```
 
 Besides graphql-ruby resolver classes, `@field` also accepts a plain callable:
-anything with `call(object, args, context)`.
+anything with `call(object, args, context)`, and `call(object, args, context,
+resolve_info)` when it takes a fourth argument.
+
+A method after `@` (PHP Lighthouse's `Class@method`) replaces `call`, or `resolve` on
+a resolver class (whose `authorized?` still runs). One class can then hold several
+fields' resolvers:
+
+```graphql
+type Query {
+  counts: Counts! @field(resolver: "Statistics@counts")
+  latest: [Post!]! @field(resolver: "Statistics@latest")
+}
+```
+
+```ruby
+class Resolvers::Statistics
+  def self.counts(_root, _args, _context) = { posts: Post.count, users: User.count }
+  def self.latest(_root, _args, _context) = Post.order(created_at: :desc).limit(5)
+end
+```
+
+### ResolveInfo
+
+What PHP Lighthouse hands a resolver as `$resolveInfo`. A `Resolvers::` or
+`Mutations::` class, a class `@field` names and a type class's methods read it as
+`resolve_info`:
+
+| | |
+| --- | --- |
+| `field_name`, `field`, `return_type` | the field being resolved |
+| `parent_type` | the type it belongs to |
+| `object`, `arguments`, `context` | what it resolves with |
+| `path` | `["posts", 0, "author"]` |
+| `lookahead` | graphql-ruby's [`Lookahead`](https://graphql-ruby.org/queries/lookahead.html): what the client selects below the field (`lookahead.selects?(:author)`) |
+| `enhance_builder(relation, scopes: [])` | `relation` with the field's query directives applied |
+
+`enhance_builder` lets a class build the query no directive could, and still honour
+what the field declares: its `@builder` classes, and the argument directives the
+client used (`@eq`, `@where`, `@in`, `@like`, `@orderBy`, `@whereConditions`, ...),
+as `@all` and `@paginate` apply them. `scopes:` adds model scopes.
+
+```graphql
+type Query {
+  myPosts(title: String @like, orderBy: [PostOrderByClause!] @orderBy): [Post!]! @guard
+}
+```
+
+```ruby
+class Resolvers::MyPosts < Resolvers::BaseResolver
+  def resolve(**)
+    resolve_info.enhance_builder(context[:current_user].posts, scopes: [:recent])
+  end
+end
+```
+
+### Fields of other types
+
+A field of any other type resolves with the default reader: `Post.commentsCount`
+reads `post.comments_count`. When its value takes more than reading an attribute
+or calling a method ([`@method`](directives.md#method)), name a class with
+`@field`. The class is a resolver like the ones above, and its `object` is the
+**parent**: the record the field belongs to (PHP Lighthouse's `$root`). It
+resolves wherever the type appears in a response: in a list, under a
+relationship, or under another class's result.
+
+```graphql
+type Post {
+  tagsCount: Int! @field(resolver: "Posts::TagsCount")
+  excerpt(length: Int = 80): String @field(resolver: "Posts::Excerpt")
+}
+```
+
+```ruby
+# app/graphql/resolvers/posts/tags_count.rb
+module Resolvers
+  module Posts
+    class TagsCount < BaseResolver
+      def resolve
+        dataload_association(object, :tags).size
+      end
+    end
+  end
+end
+
+# app/graphql/resolvers/posts/excerpt.rb
+module Resolvers
+  module Posts
+    class Excerpt < BaseResolver
+      def resolve(length:)
+        object.body&.truncate(length, separator: ' ')
+      end
+    end
+  end
+end
+```
+
+```graphql
+{
+  posts(first: 10) { data { title tagsCount excerpt(length: 40) } }
+}
+```
+
+The field's arguments arrive as keyword arguments, with the SDL's default when the
+client leaves one out, as on a root field. The class runs once per parent, so load
+anything beyond the parent's own columns through graphql-ruby's dataloader
+(`dataload_association`, `dataload_record`, or a `GraphQL::Dataloader::Source` of
+your own). Then listing ten posts runs one query for their tags, not ten.
+
+A field can also resolve with a method of its type's class, as in a graphql-ruby
+app. See [type classes](#type-classes), next: they suit a field that only the type
+needs, and a class named by `@field` suits one with its own logic, its own
+arguments, or that you want to find in the schema.
+
+On these types the name is looked up in the resolvers namespace first, a nested
+name too, so `Posts::TagsCount` is `Resolvers::Posts::TagsCount`, kept in
+`app/graphql/resolvers/posts/`. A folder per type keeps these classes apart from
+the `Query` ones. Name it in the plural (`Posts`): a `Resolvers::Post` module would
+hide the `Post` model from code written inside `module Resolvers`. When the
+resolvers namespace has no such class, the name is looked up in
+[`resolver_namespaces`](configuration.md#resolver_namespaces), and a full name
+(`Resolvers::Posts::TagsCount`) works as well. The schema's `base_types` are not
+enforced here, but inheriting from `Resolvers::BaseResolver` still gives the class
+what every resolver shares.
+
+### Type classes
+
+graphql-ruby keeps the Ruby side of each object type in `app/graphql/types`:
+`Types::PostType`, inheriting from `Types::BaseObject`, as `rails g graphql:object
+Post` writes it. Lighthouse keeps that structure. A type class that includes `Lighthouse::GraphQL::Type` is handed to
+Lighthouse: the SDL still declares the type and its fields, and the class says how
+the fields with no resolving directive resolve. A field calls the method of its
+snake_case name, when the class defines it. Fields it does not define are read off
+the object, as before, and fields with a resolving directive keep it.
+
+That makes a type that is not a model as easy to resolve as a model's: the parent
+returns any object (a Hash, a Struct, a client's response), and the type's class
+reads or computes each field from it.
+
+```graphql
+type Post {
+  title: String!
+  readingTime: ReadingTime!
+}
+
+type ReadingTime {
+  words: Int!
+  minutes(wordsPerMinute: Int = 200): Int!
+}
+```
+
+```ruby
+# app/graphql/types/post_type.rb
+module Types
+  class PostType < BaseObject
+    include Lighthouse::GraphQL::Type
+
+    def reading_time
+      { words: object.body.to_s.split.size }
+    end
+  end
+end
+
+# app/graphql/types/reading_time_type.rb
+module Types
+  class ReadingTimeType < BaseObject
+    include Lighthouse::GraphQL::Type
+
+    def minutes(words_per_minute:)
+      [(object[:words] / words_per_minute.to_f).ceil, 1].max
+    end
+  end
+end
+```
+
+`Post.title` is the model's column. `Post.readingTime` calls
+`Types::PostType#reading_time`. `ReadingTime.words` is read off the Hash it
+returns, and `ReadingTime.minutes` calls `Types::ReadingTimeType#minutes`.
+
+As in graphql-ruby, the class is instantiated per parent, so a method has:
+
+- `object`: the parent, here the post;
+- `context`: the query's context;
+- the field's arguments, as snake_case keywords, with the SDL's default when the
+  client leaves one out;
+- graphql-ruby's `dataload`, `dataload_record` and `dataload_association`, to load
+  anything beyond the parent's own columns without N+1.
+
+Wrapping directives (`@guard`, `@can*`, `@cache`) on the field run around the
+method. A method every `GraphQL::Schema::Object` has (`object`, `context`) never
+resolves a field.
+
+#### The model
+
+The type's model is the SDL's to say, as in PHP Lighthouse: a type named after its
+model needs nothing, and [`@model`](directives.md#model) maps one that is not:
+
+```graphql
+type Article @model(class: "Post") {
+  title: String!
+  headline: String!
+}
+```
+
+`Types::ArticleType`'s methods then only ever run on a `Post`: a parent of another
+class (a Hash a resolver returned by mistake, another model) is reported through
+[`on_error`](configuration.md#on_error), which raises in test, and the field
+resolves to `null`. `@model` also gives `@all`, `@find`, `@paginate`, `@create`... on
+fields returning `Article` their model, and resolves a `Post` in a union or
+interface to `Article` ([types.md](types.md#the-default)).
+
+#### Opting in
+
+The class is the type's name plus `Type`, looked up in `namespaces[:types]`
+(default `['Types']`) when the schema is built. Only a class that includes
+`Lighthouse::GraphQL::Type` counts: any other `Types::PostType`, such as the ones
+a graphql-ruby app already has, is left alone, and its methods resolve nothing.
+Include the concern in `Types::BaseObject` to hand every type class over at once.
+
+A class that includes the concern must inherit from the schema's
+`base_types[:object]` when one is given, or the schema does not build. The concern
+also hands over the classes of unions, interfaces and scalars, which pick the type
+of a union's values or coerce a scalar's: see [types.md](types.md). It is not the schema's type: it only lends its
+methods. Fields are declared in the SDL, so `field` declarations in it are ignored,
+and graphql-ruby's type-level `authorized?` does not run; authorize with
+[`@can*`](authorization.md). `Query`, `Mutation` and `Subscription` fields resolve
+with their own classes, [by convention](#resolution-by-convention), not with a type
+class.
 
 ### `@spread` and `@inject`
 
@@ -166,26 +476,29 @@ 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
+bin/rails generate graphql:object Post                 # a type class: then include Lighthouse::GraphQL::Type
 ```
 
-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
-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.
+Each writes the class with its contract, into the first namespace configured for its
+kind (or `--namespace=…`), inheriting from the namespace's base class. Type classes
+come from graphql-ruby's own `graphql:object`, `graphql:scalar`, `graphql:union` and
+`graphql:interface`. [generators.md](generators.md) has what each generator writes,
+and which of graphql-ruby's fit a Lighthouse app.
 
 ## Changing the namespaces
 
 ```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,227 @@
+# 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.
+
+## Rate limiting
+
+[`@throttle`](directives.md#throttle) caps how often one client may call a field —
+a login, a search, an expensive mutation:
+
+```graphql
+type Mutation {
+  login(email: String!, password: String!): User @throttle(maxAttempts: 5, decayMinutes: 1)
+}
+```
+
+Attempts are counted in [`cache_store`](configuration.md#cache_store), so use a store
+the app servers share (Redis, Solid Cache) in production; `:null_store` counts
+nothing. A client is the signed-in user, else the `:remote_ip` the controller concern
+puts in the context (override `graphql_context` to set another). A refused call never
+reaches `@guard` or the resolver.