lighthouse-graphql 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 844e3fc4942a637b4353427932e031c210ad52d4d425161a58f45e2e36f1d931
-  data.tar.gz: 9b0b05109d1fcac2f330b7266fe91eb502d521dabce399adfd98828137119468
+  metadata.gz: a15bb4d92716a08d5d248c5155b9cf336407a7988fed6e00c825b07bea4a206b
+  data.tar.gz: 421fca84187c5030f38c2cdd07ed26f9909747944f788cfd9662e67b6e322e2d
 SHA512:
-  metadata.gz: ef2d22dd33355e36e3b40725cea55ebf5923a06ea2c94660228d8cc6b3a6e222bd7da6f42f796d52275a2130c1ebd9e54844f85febf31d66a7a4c759d310723e
-  data.tar.gz: 7334b3e2b4ecb745fea9a4f9c08860d8e5c6245654323b0161a0b97c367d8ea022a3b23f7bd7e5bbd8c4e8614939b16e82fa737e9e133e4c5cba555199088c1d
+  metadata.gz: 388112925823baa63d0a7a4436bb1df4511f4a4c13b01001dd72b351156b78982ca4eab136a131c9c25b997915bff26099fa2a485bc4df74bfef390138e37c3a
+  data.tar.gz: e2f90e9654cfcdc2d26e084f68476ac59f56eb708683b3b4817cfc41006843363feb0f9a08b838bdcdd888395bc8f13ae29394d28b0bc37566c26dad63657cac

data/CHANGELOG.md

@@ -6,6 +6,102 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-17
+
+### Added
+
+- `@complexity` sets what a field costs in graphql-ruby's query complexity analysis, so
+  `AppSchema.max_complexity(n)` refuses expensive queries before they run. A bare `@complexity`
+  costs `1 + child complexity × first`. `@complexity(resolver: "Name")` names a
+  `GraphQL::Analysis::Analyzer` subclass in the new `analyzers` namespace (`Analyzers::Name`),
+  which Lighthouse installs on the schema. Including `Lighthouse::GraphQL::ComplexityAnalyzer`
+  gives the analyzer a `complexity` (a number, or a proc of `context, args, child_complexity`,
+  as graphql-ruby's) that is the cost of the fields naming it.
+- A root field resolved by a `GraphQL::Schema::Resolver` class, by convention or through `@field`,
+  takes the `complexity` that class declares, as graphql-ruby's `field ..., resolver:` does.
+- `BuildExtensionsResponse#query_complexity` holds the query's complexity score while something
+  listens to the event. It used to be `nil`.
+- `docs/security.md`: query complexity, depth and introspection limits.
+- graphql-ruby's base classes: `rails g lighthouse:install` writes `Resolvers::BaseResolver`,
+  `Mutations::BaseMutation` and `Subscriptions::BaseSubscription` (which includes
+  `Lighthouse::GraphQL::Subscription`), and `lighthouse:query`, `:mutation` and `:subscription`
+  write the one they need when it is missing. Generated classes inherit from them. An existing
+  base, such as the ones graphql-ruby's `graphql:install` writes, is never replaced.
+- `get_schema`'s `base_types` takes `resolver:`, `mutation:` and `subscription:` beside
+  graphql-ruby's own keys. Every class a `Query`, `Mutation` or `Subscription` field resolves to
+  must then inherit from its kind's base (`Lighthouse::DefinitionError` otherwise), and a
+  `Subscription` field with no class of its own resolves with the subscription base. The
+  generated schema class names the three.
+
+### Changed
+
+- The classes of `Query` fields are looked up in `Resolvers` (`app/graphql/resolvers`), graphql-ruby's
+  convention, instead of `Queries`: `Query.latestPosts` resolves to `Resolvers::LatestPosts`, and
+  `lighthouse:query` writes there. To keep `app/graphql/queries`, set
+  `config.namespaces = { queries: ['Queries'] }`.
+- `lighthouse:subscription` no longer takes `--lighthouse`. The class inherits from
+  `Subscriptions::BaseSubscription`, which includes the concern, and gets its hooks; under a base
+  without the concern, it gets graphql-ruby's `authorized?` and `update`.
+
+- Paginated fields (`@paginate`, and relationship directives given `type:`) cost
+  `1 + child complexity × first` in the complexity score. A page of 1,000 items now scores
+  1,000 times one item's cost; before, a paginator scored the same whatever `first` was.
+  A schema that already sets `max_complexity` may need a higher limit.
+
+## [0.3.0] - 2026-10-17
+
+### Added
+
+- `Lighthouse::GraphQL::Controller`, a Rails controller concern: `include` it, name the schema
+  with `lighthouse_schema AppSchema`, and its `execute` action runs the operation through
+  persisted queries, batches a JSON array body, reads the variables, sets the Cache-Control
+  header and renders the result. Its private hooks (`graphql_context`, `graphql_variables`,
+  `graphql_schema`) adjust it, and `lighthouse_request { }` gives an action of your own the
+  request events. The generated `GraphqlController` and the example app now use it.
+- Events, as PHP Lighthouse dispatches them (`docs/events.md`): `Lighthouse::Events.listen`
+  for `StartRequest`, `StartOperationOrOperations`, `BuildSchemaString` (its listeners return SDL to add),
+  `RegisterDirectiveNamespaces` (its listeners return namespaces of directive classes to register), `ManipulateAST`,
+  `StartExecution`, `BuildExtensionsResponse` (its listeners return an `ExtensionsResponse` for the result's
+  `extensions`), `ManipulateResult`, `EndExecution`, `EndOperationOrOperations`, `EndRequest`
+  and `ValidateSchema`. Each one is also instrumented through `ActiveSupport::Notifications`
+  as `<event>.lighthouse`.
+- `@event(dispatch:)` dispatches an event class, constructed with the field's resolved value,
+  once the field resolves. Event classes are looked up in `Config.namespaces[:events]` (`Events`).
+- `PersistedQueries.multiplex` runs a batch of operations.
+- `bin/rails lighthouse:validate_schema` dispatches `ValidateSchema` and builds every type.
+- `@feature(name:, when:)` shows a field or object type only while a feature flag is in that
+  state, checked per query through graphql-ruby's visibility. It uses Flipper by default;
+  `Config.feature_checker` and `Config.feature_actor` change that.
+- `@convertEmptyStringsToNull` on an argument, input field or field, or on every field with
+  `Config.convert_empty_strings_to_null`, turns incoming `""` into `null`.
+- Soft deletes: `@softDeletes` adds a `trashed: Trashed @trashed` argument (`ONLY`, `WITH`,
+  `WITHOUT`), and `@restore` and `@forceDelete` restore or permanently delete the soft-deleted models
+  their filters select. They work with paranoia, discard or a plain `deleted_at` column,
+  detected per model, or with an adapter set in `Config.soft_deletes`.
+- `@withoutGlobalScopes(names:)` lifts a model's default scope conditions when the client passes
+  `true`. Each name is a `without_<name>` scope or a column.
+- Subscriptions (`docs/subscriptions.md`), on graphql-ruby's subscriptions: `Subscription`
+  fields resolve to plain `GraphQL::Schema::Subscription` classes in `Subscriptions::` by convention,
+  or to the class `@subscription(class:)` names, or work with no class at all.
+  `@broadcast(subscription:, shouldQueue:)` triggers a subscription once a mutation succeeds,
+  inline or in an ActiveJob (`Config.queue_broadcasts`, `Config.broadcast_queue`), with the class's
+  `self.trigger_arguments(root, context)` and `trigger_scope`; a plain class with required arguments
+  and no `trigger_arguments` (which could never reach a subscriber) is reported as a
+  `Lighthouse::DefinitionError`. The optional concern `Lighthouse::GraphQL::Subscription` adds PHP
+  Lighthouse's `authorize?`, `filter?` and `resolve_payload` hooks. `rails generate lighthouse:subscription`
+  writes a `GraphQL::Schema::Subscription` (`--lighthouse` to include the concern). The example app
+  has real ActionCable subscriptions (`GraphqlChannel`) with channel and end-to-end delivery specs.
+- The initializer `rails generate lighthouse:install` writes lists the new settings, and
+  `docs/custom-directives.md` shows registering a namespace of directives through
+  `RegisterDirectiveNamespaces`.
+
+### Fixed
+
+- Schemas using `@cacheControl` (or `@feature`) build on graphql 2.5 again. Their arguments
+  with a default are now nullable (`maxAge: Int = 0`, not `Int! = 0`), because graphql 2.5 does not
+  fill in a directive argument's default and so refused every usage that left one out. CI now
+  also runs the suite on graphql 2.5.
+
 ## [0.2.1] - 2026-10-17
 
 ### Added
@@ -228,7 +324,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.2.1...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.4.0...HEAD
+[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
 [0.2.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.0...v0.1.1

data/README.md

@@ -41,6 +41,13 @@ and falls back to a sensible default reader for plain fields. You write Ruby onl
 for the genuinely custom parts (`@field(resolver: "...")`), and your schema stays
 the single source of truth. [Motivation](docs/motivation.md) explains the idea in depth.
 
+The same directives reach the rest of an API, too:
+- real-time updates: `Subscription` fields on graphql-ruby's subscriptions, triggered
+  by a mutation's `@broadcast`;
+- soft deletes (`@softDeletes`, `@restore`, `@forceDelete`) and feature flags (`@feature`);
+- request lifecycle [events](docs/events.md);
+- a controller concern that serves the schema in a few lines.
+
 ### Inspirations
 
 - **[Lighthouse (PHP)](https://lighthouse-php.com)** — the directive vocabulary,
@@ -62,6 +69,8 @@ gem 'lighthouse-graphql'
 
 It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 `apollo-federation` in your app (it is an optional, app-provided dependency).
+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:
 
@@ -118,7 +127,14 @@ Prefer to wire it by hand? These are the steps the generator performs.
 
    AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
      sdl_folder: Rails.root.join('graphql').to_s,
-     options: { base_types: { object: BaseObject } } # your graphql-ruby base classes
+     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, ...
+       }
+     }
    )
    ```
 
@@ -134,7 +150,8 @@ including base types and configuration.
 ### Example app
 
 [`example/`](example) is a small blog API built with Lighthouse on Rails 8.1. It shows
-the schema, the generated `Queries::`/`Mutations::`/`Builders::`/`Validators::` classes,
+the schema, the generated `Resolvers::`/`Mutations::`/`Subscriptions::`/`Builders::`/`Validators::` classes
+under graphql-ruby's base classes,
 Pundit policies and the opt-in performance features working together, and its specs
 are the library's end-to-end suite. See [example/README.md](example/README.md).
 
@@ -152,11 +169,13 @@ or as Markdown in [`docs/`](docs):
 | [Directives reference](docs/directives.md) | Every built-in directive, grouped by purpose |
 | [Relationships](docs/relationships.md) | `@hasMany`, `@belongsTo`, `@belongsToMany`, `@hasOne`, the `@morph*` variants, batching and `type:` pagination |
 | [Filtering & ordering](docs/filtering-and-ordering.md) | `@eq`/`@where`/`@in`/`@like`, `@whereConditions`, `@orderBy` |
-| [Queries, mutations & builders](docs/resolvers.md) | `Queries::` / `Mutations::` classes (graphql-ruby's contract), builders, generators |
+| [Resolvers, mutations & builders](docs/resolvers.md) | `Resolvers::` / `Mutations::` classes and their base classes (graphql-ruby's contract), builders, generators |
 | [Mutations](docs/mutations.md) | `@create`, `@update`, `@upsert`, `@delete` (and `*Many`), nested mutations on every kind of association, `@spread`, `@inject` |
 | [Validation](docs/validation.md) | Model validations, `@validator` with Dry::Validation contracts |
 | [Authentication & authorization](docs/authorization.md) | `@guard`, `@canFind` / `@canModel` / `@canQuery` / `@canResolved` / `@canRoot` (Pundit by default) |
 | [Performance at scale](docs/performance.md) | Opt-in schema cache, SDL reloading in development, persisted queries (APQ) and trusted-document allowlists |
+| [Events](docs/events.md) | Request, schema-build and execution events, `@event`, the controller concern |
+| [Subscriptions](docs/subscriptions.md) | `Subscription` fields, `@subscription`, `@broadcast`, filtering and queued broadcasts |
 | [Caching](docs/caching.md) | `@cache`, `@cacheKey`, `@clearCache` (Rails.cache), `@cacheControl` (HTTP) |
 | [Apollo Federation](docs/federation.md) | `@key`, `resolve_reference`, the `ReferenceResolver` registry |
 | [Custom directives](docs/custom-directives.md) | The contracts, the registry, writing your own directive |

data/docs/best-practices.md

@@ -44,12 +44,22 @@ Use `@guard` and the `@can*` directives on fields that require them. They wrap t
 resolver, so the check runs before any data is loaded (only `@canResolved`, which
 needs the result, runs after — keep it to fields that don't write).
 
-## Keep queries, mutations and builders apart
-
-A custom `Query` field is a `GraphQL::Schema::Resolver` in `app/graphql/queries`,
-a `Mutation` field a `GraphQL::Schema::Mutation` in `app/graphql/mutations`, and a
-query refinement a builder in `app/graphql/builders`. They have different jobs and
-contracts; don't fold them into one "resolvers" folder. See [resolvers.md](resolvers.md).
+## Keep resolvers, mutations and builders apart
+
+A custom `Query` field is a `Resolvers::BaseResolver` in `app/graphql/resolvers`, a
+`Mutation` field a `Mutations::BaseMutation` in `app/graphql/mutations`, and a query
+refinement a builder in `app/graphql/builders`. They have different jobs and
+contracts; keep each kind in its own folder. See [resolvers.md](resolvers.md).
+
+## Share through the base classes
+
+What every resolver, mutation or subscription needs (a concern, a helper,
+graphql-ruby's `argument_class`) goes in `Resolvers::BaseResolver`,
+`Mutations::BaseMutation` or `Subscriptions::BaseSubscription`, once, as in any
+graphql-ruby app. Name them in the schema's `base_types` (`resolver:`, `mutation:`,
+`subscription:`), and a class that forgets to inherit from its base is refused
+instead of quietly missing what it shares. See
+[resolvers.md](resolvers.md#base-classes).
 
 ## Validate in the model first
 

data/docs/caching.md

@@ -99,7 +99,7 @@ Each cached read costs one `read_multi` for the tokens.
 ## `@cacheControl`
 
 ```graphql
-directive @cacheControl(maxAge: Int! = 0, scope: CacheControlScope! = PUBLIC, inheritMaxAge: Boolean! = false)
+directive @cacheControl(maxAge: Int = 0, scope: CacheControlScope = PUBLIC, inheritMaxAge: Boolean = false)
   on FIELD_DEFINITION | OBJECT | INTERFACE | UNION
 ```
 

data/docs/configuration.md

@@ -10,8 +10,8 @@ require 'lighthouse-graphql'
 
 Lighthouse.configure do |config|
   config.sdl_folder = Rails.root.join('graphql').to_s
-  config.namespaces = { queries: ['Queries'], mutations: ['Mutations'] }
-  config.resolver_namespaces = ['App::Graphql', 'Resolvers']
+  config.namespaces = { queries: ['Resolvers'], mutations: ['Mutations'] }
+  config.resolver_namespaces = ['App::Graphql']
   config.on_error = ->(error, _context) { Rails.error.report(error) }
 end
 ```
@@ -31,13 +31,16 @@ different contracts, so they live apart ([resolvers.md](resolvers.md)):
 
 | Kind | Default | Holds |
 | --- | --- | --- |
-| `queries` | `['Queries']` | `GraphQL::Schema::Resolver` classes for `Query` fields |
-| `mutations` | `['Mutations']` | `GraphQL::Schema::Mutation` classes for `Mutation` fields |
+| `queries` | `['Resolvers']` | `Resolvers::BaseResolver` classes (a `GraphQL::Schema::Resolver`) for `Query` fields. `['Queries']` before 0.4.0 |
+| `mutations` | `['Mutations']` | `Mutations::BaseMutation` classes (a `GraphQL::Schema::Mutation`) for `Mutation` fields |
 | `builders` | `['Builders']` | `@builder` classes |
 | `validators` | `['Validators']` | `@validator` contracts |
+| `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)) |
 
 ```ruby
-config.namespaces = { queries: ['Api::Queries'] }   # the other kinds keep their defaults
+config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep their defaults
 ```
 
 ### `resolver_namespaces`
@@ -100,17 +103,83 @@ config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')  #
 config.persisted_queries_only = Rails.env.production?  # run nothing else
 ```
 
+### `convert_empty_strings_to_null`
+
+Makes every field behave as if it carried
+[`@convertEmptyStringsToNull`](directives.md#convertemptystringstonull): empty
+strings sent for nullable inputs arrive as `nil`, non-null inputs unchanged.
+Defaults to `false`. It is read when the schema is built, so set it in the
+initializer.
+
+```ruby
+config.convert_empty_strings_to_null = true
+```
+
+### `queue_broadcasts`, `broadcast_queue`
+
+Whether [`@broadcast`](directives.md#broadcast) triggers its subscription in an
+ActiveJob (`Lighthouse::GraphQL::BroadcastJob`, needs the `activejob` gem)
+instead of inside the mutation's request, and the queue it goes to. A directive's
+`shouldQueue:` overrides `queue_broadcasts`. Defaults: `false`, and `nil` (the
+default queue of ActiveJob). See [subscriptions.md](subscriptions.md#queueing).
+
+```ruby
+config.queue_broadcasts = true
+config.broadcast_queue = :subscriptions
+```
+
 ### `transactional_mutations`
 
 Whether `@create` / `@update` / `@createMany` / `@updateMany` run in a database
 transaction. Defaults to `true`.
 
+### `soft_deletes`
+
+What "trashed" means, for `@softDeletes`, `@trashed`, `@restore`, `@forceDelete`
+and `@withoutGlobalScopes`. By default each model is inspected: paranoia
+(`acts_as_paranoid`), then discard (`Discard::Model`), then a `deleted_at` column.
+Set it for another column, or a scheme of your own:
+
+```ruby
+# Another column, for models without a gem:
+config.soft_deletes = Lighthouse::Support::SoftDeletes::Column.new(:archived_at)
+
+# Any object answering these (relations in, relations out; records in, truthy out):
+class SoftDeleteAdapter
+  def soft_deletes?(model) = model.include?(Archivable)
+  def only_trashed(relation) = relation.unscope(where: :archived_at).where.not(archived_at: nil)
+  def with_trashed(relation) = relation.unscope(where: :archived_at)
+  def without_trashed(relation) = relation.unscope(where: :archived_at).where(archived_at: nil)
+  def restore(record) = record.unarchive
+  def force_delete(record) = record.destroy
+end
+config.soft_deletes = SoftDeleteAdapter.new
+```
+
+See [Soft deletes & global scopes](directives.md#soft-deletes-global-scopes).
+
 ### `authenticated_user`, `policy_user`, `authorizer`
 
 The authentication and authorization seams behind `@guard` and the `@can*`
 family. The authorizer is `->(user, record, ability, args = [])`, Pundit by
 default. See [authorization.md](authorization.md#configuration).
 
+### `feature_checker`, `feature_actor`
+
+The seams behind [`@feature`](directives.md#feature). The checker is
+`->(name, actor, ctx) { true/false }`, called with the feature's name as written
+in the SDL; by default it asks Flipper, `Flipper.enabled?(name.to_sym, actor)`,
+and raises a clear error when Flipper is not loaded. The actor is
+`->(ctx) { actor }`; by default it is the authenticated user (a Flipper actor
+answers `flipper_id`), and `nil` checks the feature globally.
+
+```ruby
+Lighthouse.configure do |config|
+  config.feature_actor = ->(ctx) { ctx[:current_account] }
+  config.feature_checker = ->(name, account, _ctx) { account&.features&.include?(name) }
+end
+```
+
 ## Extending the registry
 
 Register app-defined directives (see [custom-directives.md](custom-directives.md))

data/docs/custom-directives.md

@@ -109,7 +109,17 @@ Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::StartsWith)
 Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::UpcaseDirective)
 ```
 
-It is now usable in your SDL — no other changes:
+To register every directive in a namespace at once, as PHP Lighthouse locates
+directives by namespace, listen to the
+[`RegisterDirectiveNamespaces`](events.md) event. Each class there with a
+`directive_name` that is a resolver or an argument builder gets registered when
+the schema is built:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::RegisterDirectiveNamespaces) { 'App::Graphql::Directives' }
+```
+
+Either way, it is now usable in your SDL — no other changes:
 
 ```graphql
 type Query {