lighthouse-graphql 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a15bb4d92716a08d5d248c5155b9cf336407a7988fed6e00c825b07bea4a206b
-  data.tar.gz: 421fca84187c5030f38c2cdd07ed26f9909747944f788cfd9662e67b6e322e2d
+  metadata.gz: da632a31f353bc75d798a228769150a76f8cd3a0e8dce13e8bc19c363641f850
+  data.tar.gz: 6d0e92dc7818bccd89d4d9d1bc2e4905421cedd84190a0d0ae09c8ad31cb546f
 SHA512:
-  metadata.gz: 388112925823baa63d0a7a4436bb1df4511f4a4c13b01001dd72b351156b78982ca4eab136a131c9c25b997915bff26099fa2a485bc4df74bfef390138e37c3a
-  data.tar.gz: e2f90e9654cfcdc2d26e084f68476ac59f56eb708683b3b4817cfc41006843363feb0f9a08b838bdcdd888395bc8f13ae29394d28b0bc37566c26dad63657cac
+  metadata.gz: 30c076b60a32754472f1360eedc72c46b2ee518230d8ce686658f6a436f9a7d74cbcb13c24bf6a1d7dc8c05f29fba8f6ddd0d53e5614ea00ab498753340429c3
+  data.tar.gz: d558ad506a5bfebda1486cf8b62450113d0a1022f0ff458a8b040924aca458189a176cf9dbdcab95f877b571bfc18b1408109b5db36bfc128a6754df55b1bc11

data/CHANGELOG.md

@@ -6,6 +6,259 @@ 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
+
+- `Lighthouse::GraphQL::Type`, a concern that hands a graphql-ruby type class to Lighthouse, in
+  graphql-ruby's `app/graphql/types` structure. A field of an object type with no resolving
+  directive resolves with the method of its snake_case name on `Types::<Type>Type`, when that class
+  includes the concern and defines it (`Post.readingTime` → `Types::PostType#reading_time`). As in
+  graphql-ruby, the method has `object` (the parent), `context`, the `dataload*` helpers, and the
+  field's arguments as keywords. The SDL still declares the fields; the ones the class does not
+  define are read off the object as before. A type class that does not include the concern is left
+  alone. The class is looked up in the new `types` namespace (default `['Types']`), and must inherit
+  from `base_types[:object]` when one is given.
+- `@model(class:)`, as PHP Lighthouse's: maps an object type to the ActiveRecord model of another
+  name. Every directive taking `model:` (`@all`, `@find`, `@paginate`, `@create`, `@update`, the
+  `@can*` family...) on a field returning the type gets it, unless it names its own; unions,
+  interfaces and `@node` resolve the model's records to the type; the schema does not build unless
+  it is a model; and a type class's methods only run on its records (another parent is reported
+  through `on_error`).
+- Unions and interfaces resolve each value to its object type as PHP Lighthouse does: a Hash's
+  `__typename`, else the type named after the value's class or a superclass (STI), else the type
+  whose `@model` names its model. A union's type class (`Types::SearchResultType` including the
+  concern) can take over with graphql-ruby's `self.resolve_type(object, context)`, an interface's
+  with `definition_methods { def resolve_type }`, and `@union(resolveType:)` /
+  `@interface(resolveType:)` name a class in the SDL. A value nothing resolves, or one resolved
+  outside the union, raises `Lighthouse::DefinitionError` naming the ways out.
+- Custom scalars read and write their values through their class: `Types::DateTimeType` (a
+  `GraphQL::Schema::Scalar` including the concern), or the class `@scalar(class:)` names, with
+  graphql-ruby's `coerce_input` / `coerce_result`. A `GraphQL::CoercionError` makes the argument
+  invalid with its message. A scalar with no class passes its values through, as before.
+- `@method` passes the field's arguments to the method: as snake_case keywords when it takes
+  keywords, otherwise positionally in SDL order, as PHP Lighthouse does.
+- `base_types[:union]`, `[:interface]` and `[:scalar]`, like `[:object]`, are the bases the type
+  classes of their kind must inherit from.
+- `docs/types.md`: unions, interfaces and scalars.
+- `@field(resolver: "Class@method")`, as PHP Lighthouse's: the method replaces `call` on a plain
+  class (as a class method, else an instance method), or `resolve` on a resolver class, whose
+  `ready?` / `authorized?` still run.
+- `ResolveInfo`, PHP Lighthouse's `$resolveInfo`: `resolve_info` in `Resolvers::` / `Mutations::`
+  classes, classes `@field` names and type class methods, and a fourth argument for a plain callable
+  that takes one. It has the field, its parent type, object, arguments, context and path, and
+  `enhance_builder(relation, scopes: [])`, which applies the field's `@builder` classes and argument
+  directives (`@eq`, `@where`, `@orderBy`, `@whereConditions`, ...) to a query the class builds.
+- `@with(relation:, scopes:)` and `@withCount(relation:, scopes:)` eager-load a relation, or its
+  count (kept on the parent as `<relation>_count`), before the field resolves; `@lazyLoad(relations:)`
+  eager-loads relations of the records a field returns. All three load across every parent in the
+  response at once, through the Dataloader, and take nested relations (`"posts.comments"`).
+- Relay global object identification: `@globalId` encodes a field (base64 of `Type:id`) and decodes
+  an argument or input field (`decode: ARRAY | TYPE | ID`); `@node` makes a type implement `Node` and
+  adds `Query.node(id:)`, which finds the record through the type's model or `@node(resolver:)`. The
+  new `global_id` setting takes your own encoder. `docs/relay.md`.
+- A union's or interface's class may answer `[type, value]`, as graphql-ruby allows.
+- File uploads: the `Upload` scalar (Lighthouse's own for `scalar Upload`), the GraphQL multipart
+  request specification in `Lighthouse::GraphQL::Controller`, and `@upload(disk:, path:)`, which
+  stores the file through the new `upload_store` setting (an ActiveStorage blob by default) and
+  passes its signed id. `docs/uploads.md`.
+- Filters: `@whereNull`, `@whereNotNull`, `@whereBetween`, `@whereNotBetween`, `@whereJsonContains`
+  (PostgreSQL, MySQL, SQLite), `@scope`, `@nest` (the filters of an input's fields) and `@limit`
+  (a LIMIT, or a per-parent cut of a relation's records); `@whereAuth(relation:)` keeps the
+  signed-in user's records.
+- Argument directives: `@trim`, `@drop`, `@hash` (BCrypt) and `@bind(class:)`, which replaces an id
+  with its record(s) or fails validation. Rewriting ones (`@globalId`, `@trim`, `@drop`) run before
+  `@guard`, `@can*` and `@validator`; effectful ones (`@hash`, `@bind`, `@upload`) after them.
+- `@builder` on an argument or input field, as PHP Lighthouse's: the method gets the argument's
+  value whenever the client sends it, `null` included. `method: "Class@method"` names the builder
+  without `class:`, and `value:` on a field passes a fixed value in place of the arguments.
+- `@limit(builder: true)` puts the LIMIT on the field's query; `@limit` must be on an `Int` argument,
+  and is accepted on the field itself, as PHP Lighthouse allows.
+- `@hasManyThrough` and `@hasOneThrough`, PHP Lighthouse's names, as aliases of `@hasMany` and
+  `@hasOne`, which resolve `has_many` / `has_one :through`.
+- `ResolveInfo#lookahead`: graphql-ruby's Lookahead for a field resolved by a class (a `Resolvers::`
+  class, `@field`, a type class method). It never reaches the arguments, so `@cache` keys are unchanged.
+- `@throttle` logs a warning when the cache store is a `:null_store`, which counts nothing.
+- `@enum(value:)` for an enum value's internal value; `@namespaced` to group fields; `@throttle` to
+  rate-limit a field per user or IP (the controller concern now puts `:remote_ip` in the context);
+  `@async` to run a mutation in an ActiveJob and answer `true`; `@hide(env:)` / `@show(env:)` to leave
+  fields out by environment (the schema cache key now includes it).
+
+### Changed
+
+- Generators build on graphql-ruby's instead of copying them. `lighthouse:install` runs
+  `graphql:install --no-relay --skip-graphiql --skip-query-logs` for the base classes every
+  graphql-ruby app has (`Types::Base*`, `Resolvers::BaseResolver`, `Mutations::BaseMutation`), then
+  replaces what it wrote that an SDL-first app does differently: the schema class (built from the
+  SDL, naming every base in `base_types`), the controller, no `Types::QueryType` /
+  `MutationType`, and a `BaseMutation` that is a `GraphQL::Schema::Mutation`. It writes
+  `Subscriptions::BaseSubscription` itself, graphql-ruby having none. Files the app had are kept.
+- `docs/generators.md`: every generator, and which of graphql-ruby's fit a Lighthouse app
+  (`graphql:object`, `:scalar`, `:union`, `:interface` for type classes; `graphql:mutation` and
+  `graphql:detailed_trace` not as they are).
+
+- `@field(resolver:)` on a field of a type other than `Query` and `Mutation` looks the class up in
+  the resolvers namespace first, nested names included: `@field(resolver: "Posts::TagsCount")`
+  resolves to `Resolvers::Posts::TagsCount`. Then it tries `resolver_namespaces`, as before, so
+  full names and classes outside `Resolvers::` resolve as they did. A class `Resolvers::X` now
+  wins over one that `resolver_namespaces` would find for the same name.
+
+### Fixed
+
+- A wrapping directive (`@globalId`, `@guard`, `@cache`, ...) on a field of a type whose objects are
+  Hashes read nothing: the wrapped default reader only called methods. It now reads the Hash's
+  keys, as the default reader does.
+
+- A field returning a union or an interface no longer raises `undefined method 'resolve_type' for
+  an instance of Proc`. Lighthouse's field dispatcher replaced the schema's default resolve with a
+  Proc, which graphql-ruby also asks for `resolve_type` and scalar coercion; it now hands both on.
+
+- `@field(resolver:)` on a `Query` or `Mutation` field finds a nested name in the resolvers /
+  mutations namespaces, as documented: `"Feeds::Home"` resolves to `Resolvers::Feeds::Home`,
+  then to `Feeds::Home`. It used to try only `Feeds::Home`, so the field resolved to `null`.
+  The field's `complexity` is looked up the same way.
+
+### Documentation
+
+- `docs/resolvers.md`: fields of types other than `Query` and `Mutation` resolved with `@field`,
+  whose class receives the parent record as `object`. The example app resolves `Post.tagsCount`
+  (batched through the dataloader), `Post.excerpt(length:)` and `Query.popularTags` this way.
+  It resolves `Post.readingTime` and the `ReadingTime` type, which is not a model, with
+  `Types::PostType` and `Types::ReadingTimeType`, `Query.search` (a union of `Post` and `User`)
+  and `Query.latestActivity` (an `Authored` interface) by the default, `DateTime` with
+  `Types::DateTimeType`, and `Post.summary(words:)` with `@method`. `Tag` is a Relay node with
+  global ids; `User.latestPostTitle` uses `@with`, `Tag.usage` `@withCount`, `User.posts`
+  `@lazyLoad`, `Query.counts` `@field(resolver: "Statistics@counts")`, and `Query.myPosts`
+  `resolve_info.enhance_builder`. `Mutation.updateAvatar` takes a multipart upload with `@upload`
+  (the example now loads ActiveStorage). `Mutation.schedulePublish` is `@async` on Solid Queue,
+  `Query.searchPosts` is `@throttle`d, and `Query.posts` filters `metadata` with `@whereJsonContains`;
+  the example's suite runs on PostgreSQL and MySQL too (`DATABASE_URL`, a new CI job), with Redis.
+
+### Removed
+
+- `rails g lighthouse:type`: it was graphql-ruby's `graphql:object` (and `:scalar`, `:union`,
+  `:interface`) with an `include`. Generate the class with graphql-ruby, then add
+  `include Lighthouse::GraphQL::Type`.
+- `lighthouse:query` and `lighthouse:mutation` no longer write `Resolvers::BaseResolver` /
+  `Mutations::BaseMutation` when they are missing: graphql-ruby's install writes them, which
+  `lighthouse:install` runs. They say so instead.
+
 ## [0.4.0] - 2026-10-17
 
 ### Added
@@ -324,7 +577,9 @@ 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.4.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
 [0.2.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.0...v0.2.1

data/README.md

@@ -72,16 +72,23 @@ 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 creates the initializer, a starter schema in `graphql/schema.graphql`, the
-`AppSchema` class, a `GraphqlController` with its `POST /graphql` route, 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`).
+`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`, `--subscriptions`, `--skip-controller`, `--skip-ide`), and see
+[docs/generators.md](docs/generators.md) for every generator, graphql-ruby's included.
 
 ### IDE support
 
@@ -120,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 writes
-         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

@@ -38,6 +38,7 @@ different contracts, so they live apart ([resolvers.md](resolvers.md)):
 | `events` | `['Events']` | Classes `@event(dispatch:)` names ([events.md](events.md)) |
 | `subscriptions` | `['Subscriptions']` | `Subscriptions::BaseSubscription` classes (a `GraphQL::Schema::Subscription`; the base includes `Lighthouse::GraphQL::Subscription`) for `Subscription` fields, and `@subscription(class:)` ([subscriptions.md](subscriptions.md)) |
 | `analyzers` | `['Analyzers']` | `GraphQL::Analysis::Analyzer` classes (optionally including `Lighthouse::GraphQL::ComplexityAnalyzer`) that `@complexity(resolver:)` names ([security.md](security.md)) |
+| `types` | `['Types']` | `Types::<Name>Type` classes including `Lighthouse::GraphQL::Type`: an object type's, whose methods resolve the fields of the SDL type `<Name>` ([resolvers.md](resolvers.md#type-classes)); a union's or interface's, which picks its values' types; a scalar's, which coerces its values ([types.md](types.md)). Also where `@union`, `@interface` and `@scalar` look classes up |
 
 ```ruby
 config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep their defaults
@@ -47,8 +48,9 @@ config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep the
 
 An ordered list of namespaces tried for **models** named by a directive
 (`@all(model: "User")`) and for `@field(resolver:)` on types other than `Query`
-and `Mutation`. Fully-qualified names (containing `::`) are used as-is. Defaults
-to `['App::Graphql']`.
+and `Mutation`, after the resolvers namespace
+([resolvers.md](resolvers.md#fields-of-other-types)). Fully-qualified names
+(containing `::`) are used as-is. Defaults to `['App::Graphql']`.
 
 ```ruby
 config.resolver_namespaces = ['App::Graphql', 'Resolvers']
@@ -68,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
@@ -97,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
@@ -115,6 +108,17 @@ initializer.
 config.convert_empty_strings_to_null = true
 ```
 
+### `global_id`
+
+Encodes and decodes Relay global ids for [`@globalId` and `@node`](relay.md): any
+object with `encode(type, id)` returning the global id, and `decode(global_id)`
+returning `[type, id]`. Defaults to `Lighthouse::GraphQL::GlobalId`, the base64 of
+`Type:id`, as PHP Lighthouse's.
+
+```ruby
+config.global_id = SignedGlobalIds
+```
+
 ### `queue_broadcasts`, `broadcast_queue`
 
 Whether [`@broadcast`](directives.md#broadcast) triggers its subscription in an