lighthouse-graphql 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd6b5839f6520df6489135c1a37382ce4f7889d136140f652443ad5a3cd1a81
-  data.tar.gz: 60fdb10b55abe72a1dc3df89705b904b424344e5bffa611e695a46fa8767ddc7
+  metadata.gz: da632a31f353bc75d798a228769150a76f8cd3a0e8dce13e8bc19c363641f850
+  data.tar.gz: 6d0e92dc7818bccd89d4d9d1bc2e4905421cedd84190a0d0ae09c8ad31cb546f
 SHA512:
-  metadata.gz: 0f2aff4008f41238a6ebca9c598add10069e7f0c4c8c5578bc1041f3da50f36b859b9ce1c91a29576442562a42afca20845b8fb3704b19d374570381a3588262
-  data.tar.gz: b985fc24dfb2d0196c96f84cb0423d0b21e38659a0bc1cd4db13dc3818a8939fd2340006d85605cb5a50fde37f638d177ba90bf5af26e2cc3b9a3a0c2043986a
+  metadata.gz: 30c076b60a32754472f1360eedc72c46b2ee518230d8ce686658f6a436f9a7d74cbcb13c24bf6a1d7dc8c05f29fba8f6ddd0d53e5614ea00ab498753340429c3
+  data.tar.gz: d558ad506a5bfebda1486cf8b62450113d0a1022f0ff458a8b040924aca458189a176cf9dbdcab95f877b571bfc18b1408109b5db36bfc128a6754df55b1bc11

data/CHANGELOG.md

@@ -6,6 +6,122 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-18
+
+Lighthouse now uses what the Rails app and graphql-ruby already have instead of settings and
+files of its own: the app's cache, its controllers' rate limiting, its ActiveStorage, and
+everything graphql-ruby's `graphql:install` writes, which `lighthouse:install` now builds on.
+Several defaults change.
+
+**Upgrading from 0.5:**
+
+1. Remove `config.cache_store =` and `config.upload_store =` from
+   `config/initializers/lighthouse.rb`. Configure the app's `config.cache_store` instead, and
+   `config.action_controller.cache_store` if rate limits should be counted somewhere else.
+2. `@throttle` counts per IP now. Add `by: "current_user.id"` where a field counted per user.
+3. Past a `@throttle` limit the request is answered with a 429, as Rails' `rate_limit` answers it.
+   To fail only the field, as before, give `with:` a controller method that raises a
+   `GraphQL::ExecutionError`.
+4. `@upload` checks `public:` against the ActiveStorage service. On a public service, add
+   `public: true`. Where `public: true` meets a private service, name a public one with `disk:`.
+5. `rails g lighthouse:query` and `lighthouse:mutation` are gone. Resolve a root field with a
+   method of `Types::QueryType` / `MutationType`, with `rails g graphql:mutation`, or with a
+   `Resolvers::` / `Mutations::` class written by hand, which convention still finds. An app
+   installed with 0.5 keeps working as it is: `AppSchema = get_schema(...)` is still supported.
+
+### Added
+
+- `@throttle(by:)`: who the client is, as `rate_limit`'s `by:`. It is a path in the context, read
+  as `@inject` reads one (`by: "current_user.id"`).
+- `@throttle(with:)`: a controller method to call past the limit, as `rate_limit`'s `with:`. One
+  that renders or redirects ends the request with its response, as a `before_action` that renders
+  does. One that returns lets the call through, and one that raises a `GraphQL::ExecutionError`
+  fails only the field.
+- `@throttle` refusals are instrumented as `rate_limit.action_controller`, with `rate_limit`'s
+  payload (`request`, `count`, `to`, `within`, `by`, `name`, `scope`, `cache_key`).
+- `base_types` takes graphql-ruby's code-first root types and Node interface. The SDL's root type
+  of a kind is built on `query_type:` / `mutation_type:` / `subscription_type:` (`Types::QueryType`),
+  so the `field`s the class declares (graphql-ruby's Relay `node` and `nodes`, what
+  `graphql:mutation` adds to `Types::MutationType`) are the schema's too, beside the SDL's, and
+  resolve as in graphql-ruby. With no such root type in the SDL, the class is the root. `node:`
+  (`Types::NodeType`) is the SDL's `Node` interface, which `@node` types implement, so
+  graphql-ruby's Relay and `@node` share one `Node`.
+- A root field with no resolving directive resolves with the method of its name on the root type
+  class, when the class includes `Lighthouse::GraphQL::Type` (`Query.latestPosts` →
+  `Types::QueryType#latest_posts`), before the conventional `Resolvers::` / `Mutations::` class.
+- A schema that implements graphql-ruby's `id_from_object` / `object_from_id` has one kind of
+  global id: `@globalId` encodes an object's own id with `id_from_object`, and decodes an
+  argument with `object_from_id`.
+- `lighthouse:install --subscriptions` writes `Subscriptions::BaseSubscription` and names it in
+  `base_types`; without it, the install writes no subscription base.
+
+### Changed
+
+- `@cache`, `@clearCache` and Automatic Persisted Queries use the app's `Rails.cache`
+  (`config.cache_store`), as PHP Lighthouse uses Laravel's cache. Outside Rails they use an
+  in-memory store.
+- `@throttle` is Rails' `rate_limit` on one field, and counts as it does:
+  - It counts in the controller's `cache_store` (`config.action_controller.cache_store`,
+    `Rails.cache` unless set), under `rate_limit`'s key, `rate-limit:<scope>:<name>:<by>`.
+    Counts kept under the old `lighthouse:throttle:` keys start over.
+  - `name:` is `rate_limit`'s. Each field counts under its own name (`Query.x`) by default, apart
+    from the controller's `rate_limit`, or together with it when both use the same name.
+    `prefix:` is `rate_limit`'s `scope:`, the controller's path by default.
+  - The client is its IP, as `rate_limit`'s default `by:`, no longer the signed-in user.
+  - Past the limit it does what `rate_limit` does by default: it raises
+    `ActionController::TooManyRequests`, which Rails answers with a 429
+    (`head :too_many_requests` on Rails 7.2). The field used to fail on its own, with the rest of
+    the operation answered; that remains the behavior without Action Pack.
+- `lighthouse:install` builds on graphql-ruby's `graphql:install`, run with whichever of its
+  options the app chose (`--relay`, `--batch`, `--skip-mutation-root-type`, `--schema`,
+  `--directory`, `--api`), or run first with its defaults when the app has none. It writes no
+  schema class of its own: graphql-ruby's `class AppSchema < GraphQL::Schema` becomes
+  `class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: ... })`,
+  naming every class graphql-ruby wrote, and keeps the rest of the class (`use
+  GraphQL::Dataloader`, `max_depth`, `id_from_object`, ...). It takes out what Lighthouse replaces:
+  the `query(...)` / `mutation(...)` root types the SDL's are built on, the `resolve_type` stub,
+  and the example `test_field`. Its base object, interface, union and scalar include
+  `Lighthouse::GraphQL::Type`, so every type class is Lighthouse's without an `include` of its
+  own. With `--batch`, the schema uses `GraphQL::Dataloader` too. Its `Mutations::BaseMutation`, a
+  `RelayClassicMutation`, is kept; graphql-ruby's controller, unchanged since its install, becomes
+  one with `Lighthouse::GraphQL::Controller`. `Types::QueryType` and `MutationType` are kept.
+- An SDL Mutation field that declares its arguments one by one resolves by convention to a
+  `GraphQL::Schema::RelayClassicMutation` subclass as to a plain mutation, its arguments as
+  keywords. It used to fail looking for `input:`.
+- A subscriptions backend the app's schema class `use`s in its body
+  (`use GraphQL::Subscriptions::ActionCableSubscriptions`) delivers the SDL's Subscription fields.
+  graphql-ruby adds its subscription extension only to a root type of the class's own.
+- `Lighthouse::GraphQL::Controller` puts the controller in the context (`:lighthouse_controller`)
+  for `@throttle`. In development, an error Rails answers with a status of its own
+  (`config.action_dispatch.rescue_responses`, such as a 429 or a 404) now gets that status, as in
+  production, instead of being rendered as a JSON 500.
+- `@upload` stores files on the app's ActiveStorage only, with PHP Lighthouse's rules. `disk:`
+  names a service of `config/storage.yml` (`config.active_storage.service` without it), and
+  `path:` starts the blob's key. ActiveStorage sets visibility per service, so `public:` must now
+  agree with the service's: `public: true` on a private service, or the default `false` on a
+  public one, fails instead of being ignored. An unknown service, or a value that is not a file,
+  fails naming the argument. The file is rewound before it is stored, so a `@validator` may read
+  it first.
+- The `Upload` scalar's errors are PHP Lighthouse's: a value that is not a file names the GraphQL
+  multipart request specification and what was sent instead.
+
+### Removed
+
+- `Config.cache_store`: configure the app's `config.cache_store` instead, and
+  `config.action_controller.cache_store` (or a controller's `self.cache_store =`) for `@throttle`.
+  `Config.persisted_queries_store` stays, defaulting to `Rails.cache`.
+- `Config.upload_store`: to store files elsewhere, declare an ActiveStorage service and name it
+  with `@upload(disk:)`, as a Laravel app declares a disk.
+- `rails g lighthouse:query` and `lighthouse:mutation`: graphql-ruby has no resolver generator,
+  and `graphql:mutation` works in a Lighthouse app now. See Upgrading.
+
+### Fixed
+
+- On graphql-ruby 2.5, a schema using `@limit`, `@bind` or `@upload` without one of their optional
+  arguments did not build (`Expected value to not be null`): graphql 2.5 does not apply the default
+  of a non-null directive argument. Those arguments (`builder`, `column`, `with`, `optional`,
+  `path`, `public`) are nullable now, with the same defaults.
+
 ## [0.5.0] - 2026-10-18
 
 ### Added
@@ -461,7 +577,8 @@ had been running inside a private monorepo as a path gem before being extracted.
 - Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
   `on_error`, and `DirectiveRegistry.register` for app-defined directives.
 
-[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.1...v0.3.0

data/README.md

@@ -72,18 +72,22 @@ It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 On graphql 2.5, keep the `json` gem below 3: graphql 2.5 calls `JSON.generate`
 with an option json 3 removed (graphql 2.6 no longer does).
 
-Then let the generator set the app up:
+Then let the generators set the app up:
 
 ```shell
+bin/rails generate graphql:install      # graphql-ruby's, with the options you choose (optional)
 bin/rails generate lighthouse:install
 ```
 
-It runs graphql-ruby's own `graphql:install` for the base classes every graphql-ruby
-app has, then writes Lighthouse's on top: the initializer, a starter schema in
-`graphql/schema.graphql`, the `AppSchema` class built from it, a `GraphqlController`
-with its `POST /graphql` route, and a `graphql.config.yml` for your IDE. Run
+`lighthouse:install` builds on graphql-ruby's own install, and runs `graphql:install`
+with its defaults when the app has none. It adapts what graphql-ruby wrote: the
+schema class becomes Lighthouse's, built from the SDL on graphql-ruby's root types
+and base classes, and the rest of its body stays; the base object, interface, union
+and scalar include `Lighthouse::GraphQL::Type`; the controller serves the schema
+through `Lighthouse::GraphQL::Controller`. It adds the initializer, a starter schema
+in `graphql/schema.graphql` and a `graphql.config.yml` for your IDE. Run
 `bin/rails generate lighthouse:install --help` for its options (`--schema`,
-`--sdl-folder`, `--skip-controller`, `--skip-ide`), and see
+`--sdl-folder`, `--subscriptions`, `--skip-controller`, `--skip-ide`), and see
 [docs/generators.md](docs/generators.md) for every generator, graphql-ruby's included.
 
 ### IDE support
@@ -123,22 +127,26 @@ Prefer to wire it by hand? These are the steps the generator performs.
    }
    ```
 
-2. **Build the schema** (typically in `app/graphql/your_schema.rb`):
+2. **Build the schema**: graphql-ruby's schema class (`app/graphql/app_schema.rb`),
+   inheriting from the schema Lighthouse builds instead of `GraphQL::Schema`:
 
    ```ruby
-   require 'lighthouse-graphql'
-
-   AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-     sdl_folder: Rails.root.join('graphql').to_s,
+   class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
      options: {
-       base_types: {
-         resolver: Resolvers::BaseResolver,              # graphql-ruby's base classes, which
-         mutation: Mutations::BaseMutation,              # rails g lighthouse:install has graphql-ruby write
-         subscription: Subscriptions::BaseSubscription
-         # object: Types::BaseObject, ...
+       base_types: {                                     # the classes graphql-ruby's install writes
+         query_type: Types::QueryType,
+         mutation_type: Types::MutationType,
+         node: Types::NodeType,
+         resolver: Resolvers::BaseResolver,
+         mutation: Mutations::BaseMutation,
+         object: Types::BaseObject
+         # interface: Types::BaseInterface, union:, scalar:, enum:, input_object: ...
        }
      }
    )
+     use GraphQL::Dataloader   # Lighthouse batches relationships through it
+     max_depth(15)
+   end
    ```
 
 3. **Execute** it from your controller exactly like any graphql-ruby schema:

data/docs/caching.md

@@ -41,9 +41,10 @@ such as a Relay connection object, is reported through
 [`on_error`](configuration.md#on_error) and returned uncached. So cache list
 fields, not connection fields.
 
-The store is [`Config.cache_store`](configuration.md#cache_store), `Rails.cache`
-by default. Note that Rails uses a `:null_store` in development and test unless
-you enable caching (`bin/rails dev:cache`).
+The store is your app's cache, `Rails.cache` (`config.cache_store`), as PHP
+Lighthouse uses Laravel's: Lighthouse keeps no store of its own. Note that Rails
+uses a `:null_store` in development and test unless you enable caching
+(`bin/rails dev:cache`).
 
 A cached value is still authorized and validated on every request: `@cache` runs
 inside `@guard`, `@can*` and `@validator`, never around them.

data/docs/configuration.md

@@ -70,15 +70,6 @@ reporter in production:
 config.on_error = ->(error, _ctx) { Sentry.capture_exception(error) }
 ```
 
-### `cache_store`
-
-The store behind [`@cache` / `@clearCache`](caching.md). Defaults to
-`Rails.cache` (an in-memory store outside Rails).
-
-```ruby
-config.cache_store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV['REDIS_URL'])
-```
-
 ### `pagination_default_count`, `pagination_max_count`
 
 Defaults for paginated fields: the `first` used when a client leaves it out (so
@@ -99,7 +90,7 @@ Options for large schemas and high traffic, all off by default. See
 config.schema_cache = Rails.env.production?            # cache the built schema in tmp/cache
 config.watch_sdl = Rails.env.development?              # reload when a .graphql file changes
 config.persisted_queries = true                        # Apollo's Automatic Persisted Queries
-config.persisted_queries_store = Rails.cache           # where APQ keeps queries (default: cache_store)
+config.persisted_queries_store = Rails.cache           # where APQ keeps queries (default: Rails.cache)
 config.persisted_queries_ttl = 1.week.to_i             # how long they live there
 config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')  # trusted operations
 config.persisted_queries_only = Rails.env.production?  # run nothing else
@@ -128,17 +119,6 @@ returning `[type, id]`. Defaults to `Lighthouse::GraphQL::GlobalId`, the base64
 config.global_id = SignedGlobalIds
 ```
 
-### `upload_store`
-
-Stores the file an [`@upload`](uploads.md) argument carries: any object with
-`call(file, disk:, path:, public:)`, whose return value the argument then holds.
-Defaults to `Lighthouse::GraphQL::UploadStore`, which makes an ActiveStorage blob and
-returns its signed id.
-
-```ruby
-config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }
-```
-
 ### `queue_broadcasts`, `broadcast_queue`
 
 Whether [`@broadcast`](directives.md#broadcast) triggers its subscription in an

data/docs/directives.md

@@ -283,16 +283,23 @@ type PostQueries {
 
 ### `@throttle`
 
-Rate-limits a field per client: at most `maxAttempts` calls every `decayMinutes`
-(default 60 a minute), counted in [`cache_store`](configuration.md#cache_store). A
-client is the signed-in user, else the context's `:remote_ip`, which the controller
-concern sets. Past the limit the field fails with `Rate limit for Query.x exceeded.
-Try again later.` before anything else runs. `name:` makes fields count together,
-`prefix:` separates groups.
+Rails' `rate_limit` on one field: at most `maxAttempts` calls (its `to:`) every
+`decayMinutes` (its `within:`, default 60 a minute), counted before anything else runs.
+It takes `rate_limit`'s options, and counts as `rate_limit` does: in the controller's
+`cache_store`, under the same key, and instrumented as `rate_limit.action_controller`.
+See [security.md](security.md#rate-limiting).
+
+| Argument | `rate_limit`'s | Default |
+| --- | --- | --- |
+| `by:` | `by:`, who the client is: a path in the context, as [`@inject`](resolvers.md#spread-and-inject)'s (`"current_user.id"`) | the client's IP |
+| `with:` | `with:`, the controller's method to call past the limit | `rate_limit`'s: a 429 (it raises `ActionController::TooManyRequests`) |
+| `name:` | `name:`; fields, and the controller's own `rate_limit`, of the same name count together | the field (`Query.x`) |
+| `prefix:` | `scope:` | the controller's path |
 
 ```graphql
 type Mutation {
   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
 }
 ```
 
@@ -584,7 +591,7 @@ order the SDL lists them:
 | `@drop` | nothing: the argument is removed |
 | `@hash` | the value hashed with BCrypt (the `bcrypt` gem, as `has_secure_password`) |
 | `@bind(class:, column: "id", with: [], optional: false)` | the model record(s) the value identifies, eager-loading `with`; or what a class's `call(value, context)` returns |
-| `@upload(disk:, path: "/")` | what [`upload_store`](configuration.md#upload_store) answers for the uploaded file: the signed id of an ActiveStorage blob, by default ([uploads.md](uploads.md)) |
+| `@upload(disk:, path: "/", public: false)` | the signed id of the ActiveStorage blob the file was stored as, on the app's service `disk` names ([uploads.md](uploads.md)) |
 
 ```graphql
 type Mutation {

data/docs/generators.md

@@ -2,51 +2,51 @@
 
 Lighthouse builds on graphql-ruby, and so do its generators: it writes only what
 graphql-ruby has no generator for, or what an SDL-first schema needs differently.
-Every graphql-ruby app's base classes (`Types::BaseObject`, `Resolvers::BaseResolver`,
-`Mutations::BaseMutation`, ...) come from graphql-ruby's own `graphql:install`.
+Every graphql-ruby app's schema class and base classes (`Types::BaseObject`,
+`Resolvers::BaseResolver`, `Mutations::BaseMutation`, ...) come from graphql-ruby's
+own `graphql:install`, and `lighthouse:install` builds on them.
 
 ## `lighthouse:install`
 
 ```shell
+bin/rails generate graphql:install     # graphql-ruby's, with the options you choose
 bin/rails generate lighthouse:install
 ```
 
-It runs graphql-ruby's install first
-(`graphql:install --no-relay --skip-graphiql --skip-query-logs`), which writes:
+It works on what graphql-ruby's `graphql:install` wrote, with whichever of its
+options the app chose (`--relay`, the default, `--batch`, `--skip-mutation-root-type`,
+`--schema`, `--directory`, `--api`, ...). When the app has no graphql-ruby schema
+class yet, it runs `graphql:install` first, with graphql-ruby's defaults (and
+`--api` when `config.api_only = true`). Then it adapts what graphql-ruby wrote:
 
-- `app/graphql/types/base_*.rb`: `BaseObject`, `BaseField`, `BaseArgument`,
-  `BaseInterface`, `BaseUnion`, `BaseScalar`, `BaseEnum`, `BaseInputObject`;
-- `app/graphql/resolvers/base_resolver.rb` and `app/graphql/mutations/base_mutation.rb`;
-- its schema class, `Types::QueryType`, `Types::MutationType` and controller, and the
-  `POST /graphql` route.
+| File | What Lighthouse does |
+| --- | --- |
+| `app/graphql/app_schema.rb` | `class AppSchema < GraphQL::Schema` becomes `class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { ... } })`, naming every class graphql-ruby wrote. The rest of the class stays, but the `query(...)` / `mutation(...)` lines (the SDL's root types are built on those classes) and the `resolve_type` stub (Lighthouse resolves types). With `--batch`, `use GraphQL::Dataloader` goes beside `use GraphQL::Batch`, as Lighthouse's directives batch through the Dataloader |
+| `app/graphql/types/query_type.rb`, `mutation_type.rb` | The example `test_field` goes. Relay's `node` / `nodes` stay: the SDL's `Query` is built on `Types::QueryType`, so its `field`s are the schema's too |
+| `app/graphql/types/base_object.rb`, `base_interface.rb`, `base_union.rb`, `base_scalar.rb` | `include Lighthouse::GraphQL::Type`: every type class inheriting from them is Lighthouse's, `Types::QueryType` and `Types::NodeType` included |
+| `app/graphql/mutations/base_mutation.rb` | Kept as graphql-ruby wrote it, a `RelayClassicMutation` (see [resolvers.md](resolvers.md#resolution-by-convention)) |
+| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` (`lighthouse_schema AppSchema`), when it is still as graphql-ruby wrote it. One the app changed is kept, and the install says how to serve the schema |
 
-Then Lighthouse puts its own on top of what graphql-ruby wrote in that run:
+And it adds Lighthouse's own:
 
-| File | What Lighthouse does |
+| File | What it is |
 | --- | --- |
-| `app/graphql/app_schema.rb` | Replaced by the schema built from the SDL, naming every base class in `base_types` |
-| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` |
-| `app/graphql/types/query_type.rb`, `mutation_type.rb` | Removed: the SDL declares the root types |
-| `app/graphql/mutations/base_mutation.rb` | Made a `GraphQL::Schema::Mutation`: the SDL declares a mutation's arguments, where graphql-ruby's `RelayClassicMutation` takes a single `input:` |
-| `app/graphql/subscriptions/base_subscription.rb` | Written: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
-| `config/initializers/lighthouse.rb` | Written: every [configuration](configuration.md) option, commented out |
+| `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out |
 | `graphql/schema.graphql` | A starter schema, unless the folder holds `.graphql` files already |
 | `graphql.config.yml` | IDE configuration, and `.gitignore` entries for the [IDE helper](getting-started.md#ide-support) files |
+| `app/graphql/subscriptions/base_subscription.rb` | With `--subscriptions` only: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
+| `config/routes.rb` | `post "/graphql", to: "graphql#execute"`, when missing |
 
 | Option | Effect |
 | --- | --- |
-| `--schema=ApiSchema` | Name of the schema constant (default `AppSchema`) |
+| `--schema=ApiSchema` | Which graphql-ruby schema class to adopt, and its name when `graphql:install` has to run |
 | `--sdl-folder=app/schema` | Where the `.graphql` files live (default `graphql`); sets `config.sdl_folder` |
-| `--skip-controller` | No controller or route (graphql-ruby's are removed too) — for apps that serve GraphQL themselves |
+| `--subscriptions` | Write `Subscriptions::BaseSubscription` and name it in `base_types` |
+| `--skip-controller` | Leave graphql-ruby's controller as it is, and add no route — for apps that serve GraphQL themselves |
 | `--skip-ide` | No `graphql.config.yml` or `.gitignore` entries |
-| `--force` | Replace a schema class or controller the app had before |
 
-Rerunning it is safe: a file the app has is kept, and the route and `.gitignore`
-entries are added once. In an app that already had a graphql-ruby schema class or
-controller, those are kept (Lighthouse replaces only what graphql-ruby wrote in the
-same run), and graphql-ruby's install points that schema at the root types it
-wrote: have the controller call `AppSchema.execute(...)` to serve Lighthouse's
-schema, or pass `--force`.
+Rerunning it changes nothing: a schema class that is Lighthouse's already, a file
+the app has, the route and the `.gitignore` entries are left as they are.
 
 ## Lighthouse's generators
 
@@ -56,27 +56,29 @@ schema. Each writes into the first namespace configured for its kind (or
 
 | Generator | Writes |
 | --- | --- |
-| `lighthouse:query LatestPosts` | `Resolvers::LatestPosts < BaseResolver`, which `Query.latestPosts` resolves to by convention |
-| `lighthouse:mutation PublishPost` | `Mutations::PublishPost < BaseMutation`, for `Mutation.publishPost` |
 | `lighthouse:subscription PostUpdated` | `Subscriptions::PostUpdated < BaseSubscription`, with its hooks (and the base, when missing) |
 | `lighthouse:builder Published` | `Builders::Published`, for `@builder(class: "Published")` |
 | `lighthouse:validator CreatePostInput` | `Validators::CreatePostInputValidator`, a `Dry::Validation::Contract` |
 
-The class's arguments and return type are the SDL's, so it declares neither. When
-the base class is missing (an app that never ran an install, or a namespace of its
-own such as `Api::Resolvers`), the generator says so: `lighthouse:install` writes it
-through graphql-ruby, or write `Api::Resolvers::BaseResolver` yourself.
+A subscription's arguments and return type are the SDL's, so the class declares
+neither. When `Subscriptions::BaseSubscription` is missing, `lighthouse:subscription`
+writes it.
+
+A resolver or mutation class has no Lighthouse generator: write a
+`Resolvers::BaseResolver` subclass by hand (see [resolvers.md](resolvers.md)), add a
+method to `Types::QueryType`, or run graphql-ruby's `graphql:mutation`.
 
 ## graphql-ruby's generators in a Lighthouse app
 
 | Generator | In a Lighthouse app |
 | --- | --- |
-| `graphql:install` | Run by `lighthouse:install`. On its own, it writes a code-first schema, root types and a `RelayClassicMutation` base: run `lighthouse:install` instead |
-| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): add `include Lighthouse::GraphQL::Type`, then methods. The `field` lines it writes (from the model's columns, when there is one) are ignored, as the SDL declares the fields: delete them |
-| `graphql:scalar DateTime` | **Use it** for a [scalar](types.md#scalars): add `include Lighthouse::GraphQL::Type`; its `coerce_input` / `coerce_result` are the ones Lighthouse calls |
-| `graphql:union SearchResult`, `graphql:interface Authored` | **Use them** when the [default resolution](types.md#the-default) is not enough: add `include Lighthouse::GraphQL::Type` and a `resolve_type`. Its `possible_types` and `field` lines are ignored |
+| `graphql:install` | The base `lighthouse:install` builds on: run it first with the options you want, or let `lighthouse:install` run it with its defaults |
+| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): it inherits from `Types::BaseObject`, so it is Lighthouse's; add methods. The `field` lines it writes (from the model's columns, when there is one) are ignored, as the SDL declares the fields: delete them |
+| `graphql:scalar DateTime` | **Use it** for a [scalar](types.md#scalars): its `coerce_input` / `coerce_result` are the ones Lighthouse calls |
+| `graphql:union SearchResult`, `graphql:interface Authored` | **Use them** when the [default resolution](types.md#the-default) is not enough: add a `resolve_type`. Their `possible_types` and `field` lines are ignored |
 | `graphql:enum`, `graphql:input` | Not needed: the SDL declares enums and inputs ([`@enum`](directives.md#enum) gives a value an internal one) |
-| `graphql:mutation`, `graphql:mutation_create` / `_update` / `_delete` | **Not ready**: they add a field to `Types::MutationType`, which a Lighthouse app has none of (they write it again), and write a `RelayClassicMutation` taking `input:`. Use `lighthouse:mutation`, or [`@create`, `@update`, `@delete`](mutations.md) |
-| `graphql:relay` | Not needed: [`@node`, `@globalId`](relay.md) and `@paginate(type: CONNECTION)` |
+| `graphql:mutation PublishPost` | **Use it** for a code-first mutation: it writes `Mutations::PublishPost` and adds `field :publish_post, mutation: Mutations::PublishPost` to `Types::MutationType`, which the SDL's `Mutation` is built on. The class declares its own arguments and fields, as in graphql-ruby |
+| `graphql:mutation_create` / `_update` / `_delete` | Code-first mutations like `graphql:mutation`'s, whose payload and input are code-first types (`Types::PostType`, `Types::PostInputType`). For a type the SDL declares, use [`@create`, `@update`, `@delete`](mutations.md) |
+| `graphql:relay` | Run by `graphql:install` (`--relay` is its default). On an app installed with `--no-relay`, it adds `Types::NodeType`, `node` / `nodes` and the schema's `id_from_object` / `object_from_id`: add `node: Types::NodeType` to `base_types` by hand. See [relay.md](relay.md#relay-through-graphql-ruby) |
 | `graphql:loader` | A GraphQL::Batch loader, which your own resolver classes may use; Lighthouse's directives batch through graphql-ruby's Dataloader instead |
-| `graphql:detailed_trace` | **Not ready**: it edits a `class AppSchema < GraphQL::Schema`, which Lighthouse's `AppSchema = get_schema(...)` is not. Add its migration and `AppSchema.use(GraphQL::Tracing::DetailedTrace)` by hand |
+| `graphql:detailed_trace` | **Not ready**: it looks for `class AppSchema < GraphQL::Schema`, which a Lighthouse schema class (`< Lighthouse::GraphQL::RbLightHouse.get_schema(...)`) does not match, and stops. Add `use GraphQL::Tracing::DetailedTrace` and `def self.detailed_trace?(query)` to the class body by hand, with graphql-ruby's migration (or `redis:`) |