lighthouse-graphql 0.5.0 → 0.7.0

data/docs/resolvers.md

@@ -8,9 +8,9 @@ interchangeable. Each kind has its own contract and its own folder:
 | Kind | Folder / namespace | Contract | Used by |
 | --- | --- | --- | --- |
 | 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 |
+| Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (graphql-ruby's `GraphQL::Schema::RelayClassicMutation`) | `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)) |
+| Type | `app/graphql/types` · `Types::` | `Types::BaseObject` (a `GraphQL::Schema::Object`) including `Lighthouse::GraphQL::Type`, named `<Type>Type` | Fields of any object type, through its methods ([type classes](#type-classes), [root type classes](#root-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 one more kind. They are covered in
@@ -19,12 +19,13 @@ Validators (`app/graphql/validators`) are one more kind. They are covered in
 ## Base classes
 
 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)):
+and every class of the kind inherits from it. graphql-ruby's `graphql:install`
+writes `Resolvers::BaseResolver`, `Mutations::BaseMutation` and the `Types::Base*`
+classes, and `rails g lighthouse:install` builds on them: it keeps them as
+graphql-ruby wrote them, includes `Lighthouse::GraphQL::Type` in the base object,
+interface, union and scalar, and with `--subscriptions` adds
+`Subscriptions::BaseSubscription`, which graphql-ruby has none of
+([generators.md](generators.md)):
 
 ```ruby
 # app/graphql/resolvers/base_resolver.rb          (graphql-ruby's)
@@ -33,16 +34,17 @@ module Resolvers
   end
 end
 
-# app/graphql/mutations/base_mutation.rb          (graphql-ruby's, made a Mutation)
+# app/graphql/mutations/base_mutation.rb          (graphql-ruby's)
 module Mutations
-  class BaseMutation < GraphQL::Schema::Mutation
+  class BaseMutation < GraphQL::Schema::RelayClassicMutation
     argument_class Types::BaseArgument
     field_class Types::BaseField
+    input_object_class Types::BaseInputObject
     object_class Types::BaseObject
   end
 end
 
-# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's)
+# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's, --subscriptions)
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
     include Lighthouse::GraphQL::Subscription
@@ -62,9 +64,12 @@ schema holds every class to them:
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
   options: {
     base_types: {
+      query_type: Types::QueryType,
+      mutation_type: Types::MutationType,
+      node: Types::NodeType,
       resolver: Resolvers::BaseResolver,
       mutation: Mutations::BaseMutation,
       subscription: Subscriptions::BaseSubscription,
@@ -77,6 +82,8 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
     }
   }
 )
+  use GraphQL::Dataloader
+end
 ```
 
 - A class a `Query`, `Mutation` or `Subscription` field resolves to, by convention
@@ -89,12 +96,17 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   (`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.
+- `query_type:` and `mutation_type:` are the code-first classes the SDL's `Query`
+  and `Mutation` are built on (see [root type classes](#root-type-classes)), and
+  `node:` is the SDL's `Node` interface ([relay.md](relay.md#relay-through-graphql-ruby)).
+  `subscription_type:` does the same for `Subscription`.
 - 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,
+`rails g lighthouse:install` names in the schema class every one graphql-ruby's
+install wrote. 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.
@@ -149,8 +161,9 @@ end
 
 ### Resolution by convention
 
-A field on `Query` or `Mutation` with **no resolving directive** resolves to the
-class named after it, as in PHP Lighthouse:
+A field on `Query` or `Mutation` with **no resolving directive**, and no method of
+its name on the [root type class](#root-type-classes), resolves to the class named
+after it, as in PHP Lighthouse:
 
 - `Query.latestPosts` resolves to `Resolvers::LatestPosts`;
 - `Mutation.publishPost` resolves to `Mutations::PublishPost`.
@@ -162,9 +175,11 @@ 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` makes
-`Mutations::BaseMutation` inherit from) works too, as long as the SDL field takes the
-`input:` argument it expects.
+graphql-ruby's `RelayClassicMutation`, which `Mutations::BaseMutation` inherits from,
+takes a single `input:` argument. A `Mutation` field whose SDL declares its arguments
+one by one calls the class as a plain mutation, with those arguments as keywords
+(`resolve(id:)` above). A field with a single `input:` argument goes through
+`RelayClassicMutation`'s own `input:` handling.
 
 Wrapping directives (`@guard`, the `@can*` family, `@validator`, `@cache`,
 `@clearCache`) are not resolvers, so a field carrying only those still resolves by
@@ -176,6 +191,45 @@ type Mutation {
 }
 ```
 
+### Root type classes
+
+graphql-ruby's install writes `Types::QueryType` and `Types::MutationType`, and the
+schema's `base_types` name them (`query_type:`, `mutation_type:`). The SDL's `Query`
+and `Mutation` are built on them, so they work as in a graphql-ruby app:
+
+- A root field with no resolving directive calls the method of its snake_case name
+  on the class, when the class defines it and includes `Lighthouse::GraphQL::Type`
+  (`Types::BaseObject` does, after `lighthouse:install`). It comes before the
+  conventional class: `Query.latestPosts` calls `Types::QueryType#latest_posts`
+  before `Resolvers::LatestPosts`.
+- The class's own `field`s are the schema's too, beside the SDL's, and resolve as
+  in graphql-ruby: Relay's `node` / `nodes`, and the `field :publish_post, mutation:
+  Mutations::PublishPost` that `rails g graphql:mutation` adds. An SDL field of the
+  same name wins.
+- When the SDL has no `Mutation` type, `Types::MutationType` itself is the root,
+  once it declares a field.
+
+```graphql
+type Query {
+  latestPosts(limit: Int = 10): [Post!]!
+}
+```
+
+```ruby
+# app/graphql/types/query_type.rb
+module Types
+  class QueryType < Types::BaseObject
+    def latest_posts(limit:)
+      Post.order(created_at: :desc).limit(limit)
+    end
+  end
+end
+```
+
+As in a [type class](#type-classes), the method has `object`, `context`, the
+`dataload*` helpers and `resolve_info`, and gets the field's arguments as snake_case
+keywords. `Subscription` fields resolve with their classes, as before.
+
 ### Naming a class explicitly
 
 `@field(resolver:)` points a field at a class by name. On `Query` and `Mutation`
@@ -228,11 +282,11 @@ What PHP Lighthouse hands a resolver as `$resolveInfo`. A `Resolvers::` or
 `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.
+then the field's own `@orderBy(column:)`, as `@all` and `@paginate` apply them. `scopes:` adds model scopes.
 
 ```graphql
 type Query {
-  myPosts(title: String @like, orderBy: [PostOrderByClause!] @orderBy): [Post!]! @guard
+  myPosts(title: String @like, orderBy: _ @orderBy(columns: ["title", "created_at"])): [Post!]! @guard
 }
 ```
 
@@ -317,8 +371,9 @@ what every resolver shares.
 
 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
+Post` writes it. Lighthouse keeps that structure. A type class that includes
+`Lighthouse::GraphQL::Type` is handed to Lighthouse. After `lighthouse:install`,
+`Types::BaseObject` includes it, so every type class does: 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.
@@ -343,8 +398,6 @@ type ReadingTime {
 # 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
@@ -354,8 +407,6 @@ 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
@@ -403,9 +454,11 @@ interface to `Article` ([types.md](types.md#the-default)).
 
 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.
+`Lighthouse::GraphQL::Type` counts: any other `Types::PostType` is left alone, and
+its methods resolve nothing. `lighthouse:install` includes the concern in
+`Types::BaseObject`, `BaseInterface`, `BaseUnion` and `BaseScalar`, which hands every
+type class over at once. In an app that did not run it, include the concern in
+those bases, or in each type class (`include Lighthouse::GraphQL::Type`).
 
 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
@@ -413,9 +466,9 @@ also hands over the classes of unions, interfaces and scalars, which pick the ty
 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.
+[`@can*`](authorization.md). `Query` and `Mutation` are the exception: they are
+built on their [root type classes](#root-type-classes), whose `field`s count.
+`Subscription` fields resolve with their own classes.
 
 ### `@spread` and `@inject`
 
@@ -476,18 +529,18 @@ end
 ## Generators
 
 ```shell
-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
+bin/rails generate graphql:object Post                 # a type class, Lighthouse's through Types::BaseObject
+bin/rails generate graphql:mutation PublishPost        # a code-first mutation, a field of Types::MutationType
 ```
 
-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,
+Each Lighthouse generator writes the class with its contract, into the first
+namespace configured for its kind (or `--namespace=…`). Type classes come from
+graphql-ruby's own `graphql:object`, `graphql:scalar`, `graphql:union` and
+`graphql:interface`. A resolver class has no generator, as in graphql-ruby: write
+it by hand, as above. [generators.md](generators.md) has what each generator writes,
 and which of graphql-ruby's fit a Lighthouse app.
 
 ## Changing the namespaces

data/docs/schema-organisation.md

@@ -0,0 +1,177 @@
+# Schema Organisation
+
+Lighthouse reads your schema from a single entrypoint, `graphql/schema.graphql`
+by default (`config.schema_path`), as PHP Lighthouse does. As the schema grows,
+you split it across files, and the entrypoint imports them.
+
+## Schema imports
+
+```
+graphql/
+|-- schema.graphql
+|-- user.graphql
+```
+
+An import starts with `#import`, followed by the path of the imported file,
+relative to the file the import is in:
+
+```graphql
+type Query {
+  user: User
+}
+
+#import user.graphql
+```
+
+The contents of `user.graphql` are pasted in where the import is:
+
+```graphql
+type Query {
+  user: User
+}
+
+type User {
+  name: String!
+}
+```
+
+An imported file can import others. A file is read once, so importing it twice,
+or importing a file that imports it back, adds nothing more.
+
+Only the entrypoint and the files it imports make up the schema. A `.graphql`
+file in the folder that nothing imports is not part of it. A missing import
+fails the build: "Did not find GraphQL schema import at …".
+
+### Wildcard imports
+
+```
+graphql/
+|-- schema.graphql
+|-- blog/
+    |-- post.graphql
+    |-- category.graphql
+```
+
+To import every file in `blog/` at once, use a glob (Ruby's `Dir.glob`), which
+imports the files in name order:
+
+```graphql
+#import blog/*.graphql
+```
+
+`#import **/*.graphql` imports every file below the entrypoint's folder.
+
+## Type extensions
+
+A type is defined once. Defining it twice is an error that points at
+`extend`. This applies even across files:
+
+```
+Duplicate definition Query found when parsing the schema. Define a type once and add to it from other files with `extend type Query`.
+```
+
+PHP Lighthouse keeps the last definition and drops the earlier one without a
+word. Lighthouse here makes that an error, so a type's fields are never lost.
+
+Say `Post` is defined in `post.graphql`:
+
+```graphql
+type Post {
+  title: String
+  author: User @belongsTo
+}
+```
+
+and `schema.graphql` imports it:
+
+```graphql
+#import post.graphql
+```
+
+To add the queries that fetch posts, you could add them to the `Query` type in
+`schema.graphql`. It is usually better to keep queries next to the type they
+return. Make sure `schema.graphql` defines `Query`, even with no fields:
+
+```graphql
+type Query
+```
+
+Then extend `Query` in `post.graphql`:
+
+```graphql
+type Post {
+  title: String
+  author: User @belongsTo
+}
+
+extend type Query {
+  posts: [Post!]! @paginate
+}
+```
+
+The fields of the `extend type` are merged into the type's definition, and the
+directives on them work as on any field. Besides object types, you can extend
+`input`, `interface`, `enum`, `union` and `scalar` types:
+
+```graphql
+extend input PostFilter { authorId: ID @eq(key: "author_id") }
+extend enum Role { EDITOR }
+extend union SearchResult = Comment
+```
+
+The final schema always has one type per name. An extension of a type that is
+not defined is an error, and so is an extension that redefines a field:
+
+```
+Could not find a base definition User of kind ObjectTypeExtension to extend.
+Duplicate definition title found when merging.
+```
+
+The root types `Query`, `Mutation` and `Subscription` are the exception: an
+`extend type Mutation` with no `type Mutation` anywhere defines it.
+
+## How the schema is built
+
+The build runs these phases in order, as PHP Lighthouse's `ASTBuilder` does:
+
+1. The entrypoint and its imports are read (`Lighthouse::GraphQL::SchemaStitcher`),
+   along with what `BuildSchemaString` listeners add
+   ([events.md](events.md)).
+2. Every type is defined once (`Lighthouse::GraphQL::DocumentAST`).
+3. Type extensions are merged into their types.
+4. Type and field manipulators run: `@hide`/`@show`, `@model`, `@paginate`
+   and the relation directives' `type:`, `@softDeletes`, `@node`.
+5. Argument manipulators run: `@whereConditions`, `@whereHasConditions` and
+   `@orderBy` replace the `_` placeholder with the types they generate
+   ([filtering-and-ordering.md](filtering-and-ordering.md)). An argument still
+   typed `_` after this phase is an error.
+6. `ManipulateAST` listeners see the document.
+
+## IDE support
+
+An IDE reads the `.graphql` files as they are written, so it does not know
+Lighthouse's directives, the types the build generates, or the `_` placeholder.
+Lighthouse writes two files that declare them:
+
+- `schema-directives.graphql`: every directive the schema uses and does not declare.
+- `programmatic-types.graphql`: the generated types (paginators, the `@orderBy`
+  and `@whereConditions` inputs, ...) and `scalar _`.
+
+`graphql.config.yml` (written by `lighthouse:install`) points the GraphQL
+plugins of VS Code and JetBrains IDEs at them, next to every `.graphql` file:
+
+```yaml
+schema:
+  - graphql/**/*.graphql
+  - schema-directives.graphql
+  - programmatic-types.graphql
+```
+
+In development, Lighthouse rewrites both files on boot and on every reload when
+the app has a `graphql.config.yml` (`config.ide_helper`). Elsewhere, run
+`bin/rails lighthouse:ide_helper`. No type is in two of the three sources, because
+graphql-js, which the IDE plugins build the schema with, rejects a type defined
+twice.
+
+The IDE sees the files as one schema, imports or not. Without the generated
+files it reports `Unknown type "_"` and unknown directives.

data/docs/security.md

@@ -10,20 +10,24 @@ 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:
+The limits are graphql-ruby's own schema settings. Set them in the body of the
+schema class, as in any graphql-ruby schema (graphql-ruby's install writes
+`max_depth(15)` there):
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(options: { using: { GraphQL::Dataloader => {} } })
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { object: Types::BaseObject } })
+  use 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?
+  max_complexity(300)   # refuse queries that score over 300
+  max_depth(12)         # refuse queries nested deeper than 12 fields
+  disable_introspection_entry_points if Rails.env.production?
+end
 ```
 
-You can also set them on a base schema class you hand to `get_schema` with
-`options: { base_schema: MyBaseSchema }`.
+A schema assigned to a constant (`AppSchema = get_schema(...)`) takes them as calls
+on it (`AppSchema.max_complexity(300)`). 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:
 
@@ -211,17 +215,61 @@ GraphQL::Analysis.analyze_query(query, [GraphQL::Analysis::QueryComplexity]).fir
 
 ## Rate limiting
 
-[`@throttle`](directives.md#throttle) caps how often one client may call a field —
-a login, a search, an expensive mutation:
+Rails' own [`rate_limit`](https://api.rubyonrails.org/classes/ActionController/RateLimiting/ClassMethods.html)
+limits the endpoint: every operation counts, and past the limit Rails answers 429.
+[`@throttle`](directives.md#throttle) is the same limit on one field — a login, a search,
+an expensive mutation — beside it:
+
+```ruby
+class GraphqlController < ApplicationController
+  include Lighthouse::GraphQL::Controller
+
+  lighthouse_schema AppSchema
+  rate_limit to: 600, within: 1.minute, name: 'endpoint'
+
+  private
+
+  def too_many_requests
+    render json: { errors: [{ message: 'Too many requests. Try again later.' }] }, status: :too_many_requests
+  end
+end
+```
 
 ```graphql
 type Mutation {
-  login(email: String!, password: String!): User @throttle(maxAttempts: 5, decayMinutes: 1)
+  login(email: String!, password: String!): User @throttle(maxAttempts: 5)
+  createTag(name: String!): Tag! @throttle(maxAttempts: 20, by: "current_user.id", with: "too_many_requests") @guard @create
 }
 ```
 
-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.
+`@throttle` counts as `rate_limit` does, under its key (`rate-limit:<scope>:<name>:<by>`):
+
+- **Where.** In the controller's `cache_store`: `config.action_controller.cache_store`,
+  or `Rails.cache` when the app sets none (a controller can set its own with
+  `self.cache_store =`). Use a store the app servers share (Redis, Solid Cache) in
+  production; `:null_store` counts nothing.
+- **Who.** The client's IP, as `rate_limit`'s default. `by:` reads another value off the
+  context, as `@inject` does (`by: "current_user.id"`); when it is `nil`, as for a guest,
+  those calls count together, as in Rails.
+- **What counts together.** Each field counts under its own name (`Query.login`), apart
+  from the endpoint's `rate_limit` (`endpoint`). Give fields, or a field and a
+  controller's `rate_limit`, the same `name:` to count them together; `prefix:` is
+  `rate_limit`'s `scope:` (the controller's path by default).
+- **Past the limit.** As `rate_limit`'s default, `ActionController::TooManyRequests` is
+  raised, and Rails answers the request with a 429 (in development too); on Rails 7.2,
+  which has no such error, `head :too_many_requests`. With `with:`, the controller's
+  method runs instead, as `rate_limit`'s `with:`. If it renders or redirects, the request
+  ends with that response and the operation stops there, as when a `before_action`
+  renders. If it returns, the call goes through. If it raises a `GraphQL::ExecutionError`,
+  only that field fails, and the rest of the operation is answered:
+
+  ```ruby
+  def rate_limited = raise(GraphQL::ExecutionError, 'Too many requests. Try again later.')
+  ```
+
+  Without Action Pack, the field fails (`Rate limit for Query.x exceeded. Try again later.`).
+- **Instrumentation.** Each refused call is a `rate_limit.action_controller` event, with
+  `rate_limit`'s payload (`request`, `count`, `to`, `within`, `by`, `name`, `scope`,
+  `cache_key`).
+
+A refused call never reaches `@guard` or the resolver.

data/docs/subscriptions.md

@@ -38,18 +38,24 @@ end
 
 graphql-ruby delivers subscriptions through a *backend* that stores who subscribed
 and sends the updates: ActionCable (bundled), or a gem such as Pusher or Ably.
-Lighthouse needs none of its own; give the schema one. `get_schema` passes the
-`using:` option to graphql-ruby, as `use` does in a class-based schema:
+Lighthouse needs none of its own; give the schema one with `use`, in the schema
+class body, as in any graphql-ruby schema:
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  options: { using: { GraphQL::Subscriptions::ActionCableSubscriptions => {} } }
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { base_types: { subscription: Subscriptions::BaseSubscription } }   # and the other bases
 )
+  use GraphQL::Dataloader
+  use GraphQL::Subscriptions::ActionCableSubscriptions
+end
 ```
 
-Options of the backend go in the hash (`{ ActionCableSubscriptions => { namespace: 'my-app' } }`).
-Assign the schema to a constant: a [queued](#queueing) broadcast finds it by name.
+Options of the backend go after it (`use GraphQL::Subscriptions::ActionCableSubscriptions, namespace: 'my-app'`).
+A schema assigned to a constant instead (`AppSchema = get_schema(...)`) takes the
+backend through the `using:` option, as `use` does:
+`options: { using: { GraphQL::Subscriptions::ActionCableSubscriptions => {} } }`.
+Either way the schema has a name, which a [queued](#queueing) broadcast finds it by.
 
 Then add the channel graphql-ruby documents, which runs the operation and keeps
 the client's subscription ids ([the full example](https://graphql-ruby.org/subscriptions/action_cable_implementation.html)):
@@ -182,7 +188,7 @@ the base every subscription inherits from, as graphql-ruby's convention puts wha
 all classes of a kind share in their base:
 
 ```ruby
-# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install)
+# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install --subscriptions)
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
     include Lighthouse::GraphQL::Subscription
@@ -411,8 +417,9 @@ end
 
 The job carries the schema's name, the subscription's name, the trigger arguments,
 the scope and the root; an Active Record model is serialized with GlobalID, any
-other root must be something ActiveJob can serialize. A schema built by
-`get_schema` and assigned to a constant (`AppSchema = ...`) has the name; an
+other root must be something ActiveJob can serialize. A schema class
+(`class AppSchema < ...get_schema(...)`), or a schema assigned to a constant
+(`AppSchema = ...`), has the name; an
 anonymous one raises `Lighthouse::DefinitionError` when a queued broadcast needs
 it. The `activejob` gem is optional: nothing loads it unless a broadcast is queued.