lighthouse-graphql 0.2.0 → 0.3.0

data/docs/events.md

@@ -0,0 +1,201 @@
+# Events
+
+Lighthouse dispatches events as a request goes by and as the schema is built, so
+an app can hook into them without patching either. They mirror
+[PHP Lighthouse's events](https://lighthouse-php.com/master/api-reference/events.html),
+adapted to Ruby: a listener is a block or anything that responds to `call(event)`.
+
+```ruby
+# config/initializers/lighthouse.rb
+Lighthouse::Events.listen(Lighthouse::Events::StartExecution) do |event|
+  Rails.logger.info("GraphQL #{event.operation_name} at #{event.moment}")
+end
+```
+
+## Listening
+
+```ruby
+listener = Lighthouse::Events.listen(Lighthouse::Events::EndExecution) { |event| Metrics.record(event.result) }
+Lighthouse::Events.listen(Lighthouse::Events::EndRequest, AuditLog)   # anything with #call
+Lighthouse::Events.forget(listener)                                    # stop listening
+```
+
+- Listeners run in registration order. A listener on an event class also hears
+  its subclasses, so one on `Lighthouse::Events::Event` hears everything.
+- `Lighthouse::Events.dispatch(event)` returns the non-nil values the listeners
+  returned. Some events give them a meaning (below); for the others they are
+  ignored, so a listener's last expression does no harm.
+- Register in an initializer. Specs can call `Lighthouse::Events.reset!` to drop
+  every listener.
+
+### ActiveSupport::Notifications
+
+Every dispatch is also instrumented as `<event name>.lighthouse`, with the event
+as the `:event` payload, so Rails tooling observes them with no listener of ours:
+
+```ruby
+ActiveSupport::Notifications.subscribe('end_execution.lighthouse') do |*, payload|
+  Rails.logger.info(payload[:event].result['errors'])
+end
+```
+
+The name is the class name underscored: `start_request.lighthouse`,
+`build_schema_string.lighthouse`, ...
+
+## Request lifecycle
+
+In the order they happen. Events with a `moment` carry the `Time` they were
+created at (UTC).
+
+| Event | When | Readers |
+| --- | --- | --- |
+| `StartRequest` | The controller action begins | `request`, `moment` |
+| `StartOperationOrOperations` | The operation(s) were read, before they run | `operation_or_operations` |
+| `StartExecution` | A query is about to run (once per operation of a batch) | `schema`, `query`, `variables`, `operation_name`, `context`, `moment` |
+| `BuildExtensionsResponse` | A query ran | `result`, `query_complexity` |
+| `ManipulateResult` | Before the result is returned | `result` (+ writer) |
+| `EndExecution` | The result is final | `result`, `moment` |
+| `EndOperationOrOperations` | The operation(s) ran | `result_or_results` |
+| `EndRequest` | The response is rendered | `response`, `moment` |
+
+`StartRequest` and `EndRequest` are dispatched by `execute`, the action of the
+`Lighthouse::GraphQL::Controller` concern that `rails g lighthouse:install`
+generates a controller with ([getting-started.md](getting-started.md)):
+the first thing it does, and right after it renders. An action of your own gets
+them by wrapping its body in `lighthouse_request`, which dispatches them once
+however it nests:
+
+```ruby
+def search
+  lighthouse_request do
+    render json: Lighthouse::GraphQL::PersistedQueries.execute(AppSchema, query: params[:q])
+  end
+end
+```
+
+Without the concern, dispatch them yourself:
+`Lighthouse::Events.dispatch(Lighthouse::Events::StartRequest.new(request))`, and
+`EndRequest.new(response)` after rendering.
+
+`StartOperationOrOperations` and `EndOperationOrOperations` are dispatched by
+`Lighthouse::GraphQL::PersistedQueries.execute`, which the generated controller
+calls. The first carries a Hash (`query`, `variables`, `operation_name`,
+`extensions`), as the request named them. For a batch, run the operations through
+`PersistedQueries.multiplex(schema, operations, context: ...)` instead (the concern does for a JSON array body): it takes
+an Array of such Hashes (each may also carry its own `context`), dispatches the
+Arrays, and answers one result per operation. Operations that run straight on
+`schema.execute` or `schema.multiplex` fire only the execution events below.
+
+### Execution events
+
+`StartExecution`, `BuildExtensionsResponse`, `ManipulateResult` and
+`EndExecution` come from a graphql-ruby trace Lighthouse installs on every schema
+it builds, so they fire however the query was started: the controller,
+`schema.execute` in a job, or a spec. A multiplex fires them once per query.
+With no listener, and no `ActiveSupport::Notifications` subscriber, they cost
+one lookup per request.
+
+`StartExecution#query` is the parsed `GraphQL::Language::Nodes::Document`.
+
+**`BuildExtensionsResponse`**: return an `ExtensionsResponse` (or an Array of
+them) to add to the result's `extensions`:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::BuildExtensionsResponse) do |event|
+  Lighthouse::Events::ExtensionsResponse.new('queries', Query.count_for(event.result))
+end
+# => { "data" => {...}, "extensions" => { "queries" => 3 } }
+```
+
+`query_complexity` is `nil`: Lighthouse does not compute it for you.
+
+**`ManipulateResult`**: change `event.result` (the Hash with `data`, `errors` and
+`extensions`) in place, or assign a new Hash to `event.result=`:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::ManipulateResult) do |event|
+  event.result['extensions'] = (event.result['extensions'] || {}).merge('served_by' => Socket.gethostname)
+  nil
+end
+```
+
+Both also fire for a query that fails validation; the result then holds `errors`
+and no `data`.
+
+## Schema build events
+
+These fire while the schema is built, once per build. Listen from an initializer
+that runs before the schema is first used (the schema constant autoloads when
+something first refers to it).
+
+**`RegisterDirectiveNamespaces`**: return a namespace (a `Module`, or its name)
+or an Array of them. Every directive class under them (a constant that responds
+to `directive_name`: a field resolver or an argument builder) is registered, as
+if with `Lighthouse::DirectiveRegistry.register`:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::RegisterDirectiveNamespaces) do
+  %w[App::Graphql::Directives MyEngine::Directives]
+end
+```
+
+A name that is no constant fails the build with `Lighthouse::DefinitionError`.
+It fires before the directive definitions are injected, on every build,
+schema cache or not.
+
+**`BuildSchemaString`**: return SDL to append to the app's schema, before the
+manipulation phase (so it can use any directive):
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::BuildSchemaString) do |event|
+  'extend type Query { version: String @field(resolver: "Version") }'
+end
+```
+
+**`ManipulateAST`**: the document after manipulation, right before the schema
+is built from it. graphql-ruby's nodes are immutable, so replace the document:
+`event.document_ast = GraphQL.parse(...)`.
+
+With [`schema_cache`](performance.md#schema-cache) on, these two fire only when the document
+is actually built, on a cache miss, and the cache holds what they made. The cache
+key does not cover them: after you change what a listener adds, run
+`bin/rails lighthouse:clear_cache`.
+
+## `ValidateSchema`
+
+`bin/rails lighthouse:validate_schema` (`SCHEMA=AppSchema` names another schema)
+dispatches `ValidateSchema` with the schema, then has graphql-ruby build and print
+every type. A listener that raises, or a schema graphql-ruby rejects, aborts the
+task with a message, so it can run in CI:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::ValidateSchema) do |event|
+  raise 'The schema has no mutations' unless event.schema.mutation
+end
+```
+
+## Dispatching your own: `@event`
+
+The [`@event`](directives.md#event) directive dispatches an event of yours once a
+field has resolved:
+
+```graphql
+type Mutation {
+  publishPost(id: ID!): Post! @update @event(dispatch: "PostPublished")
+}
+```
+
+```ruby
+# app/events/post_published.rb
+class PostPublished
+  attr_reader :post
+
+  def initialize(post) = @post = post
+end
+
+Lighthouse::Events.listen(PostPublished) { |event| Mailer.published(event.post).deliver_later }
+```
+
+Any class works as an event. Lighthouse looks the name up in
+`Config.namespaces[:events]` (default `['Events']`, so `Events::PostPublished`,
+then `::PostPublished`).

data/docs/getting-started.md

@@ -119,22 +119,51 @@ end
 
 ## 4. Serve it
 
-A standard graphql-ruby controller:
+`rails g lighthouse:install` writes the controller. It includes
+`Lighthouse::GraphQL::Controller`, a concern that serves the schema:
 
 ```ruby
 class GraphqlController < ApplicationController
-  def execute
-    result = AppSchema.execute(
-      params[:query],
-      variables: params[:variables],
-      context: { current_user: current_user },
-      operation_name: params[:operationName]
-    )
-    render json: result
+  include Lighthouse::GraphQL::Controller
+
+  lighthouse_schema AppSchema   # or 'AppSchema', or a block: lighthouse_schema { AppSchema }
+
+  private
+
+  # What @guard and the @can* directives read. Defaults to
+  # { current_user: current_user } when the controller has a current_user.
+  def graphql_context = { current_user: current_user }
+end
+```
+
+Route to it (`post '/graphql', to: 'graphql#execute'`, plus a `get` for
+[persisted queries](performance.md#persisted-queries) if you use them). Its
+`execute` action:
+
+- dispatches the [`StartRequest` and `EndRequest` events](events.md);
+- reads `variables` (a JSON string, as a GET carries it, or parameters);
+- runs the operation through `PersistedQueries.execute`, so
+  [Automatic Persisted Queries](performance.md#persisted-queries) work once
+  `config.persisted_queries` is on, and a JSON array body runs as a batch;
+- sets the `Cache-Control` header the selected fields'
+  [`@cacheControl`](caching.md) hints allow;
+- renders the JSON; in development an error renders as JSON with its backtrace.
+
+The hooks `graphql_context`, `graphql_schema` and `graphql_variables(param)` are
+private methods you can override. A controller with an action of its own wraps it
+in `lighthouse_request { ... }` to keep the request events:
+
+```ruby
+def search
+  lighthouse_request do
+    render json: Lighthouse::GraphQL::PersistedQueries.execute(AppSchema, query: params[:q], context: graphql_context)
   end
 end
 ```
 
+Not on the concern? Plain graphql-ruby works too:
+`render json: AppSchema.execute(params[:query], variables: params[:variables], context: { current_user: current_user })`.
+
 ## 5. Configure (optional)
 
 Create an initializer to wire app-specific settings. This is also the single

data/docs/motivation.md

@@ -0,0 +1,184 @@
+# Motivation
+
+Lighthouse GraphQL Rails brings the ideas of [Lighthouse](https://lighthouse-php.com),
+the GraphQL framework for Laravel, to Ruby on Rails. This page explains those ideas:
+why the schema comes first, why behaviour lives in directives, and why that works so
+well on top of an opinionated model layer like Active Record.
+
+## Where it comes from
+
+Lighthouse ([nuwave/lighthouse](https://github.com/nuwave/lighthouse)) changed how many
+Laravel teams build GraphQL APIs. Instead of a resolver class for every field, you write
+the schema in GraphQL's own language and attach **directives** that say what a field
+does: `@paginate` it, follow a `@hasMany` relationship, `@create` a model, check a policy
+with `@canFind`. Lighthouse reads those directives and generates efficient queries against
+Eloquent, Laravel's ORM.
+
+The idea does not depend on PHP. It depends on two things: a schema written first, and a
+model layer with strong conventions. Rails has the second in Active Record, and
+[graphql-ruby](https://graphql-ruby.org) gives Ruby a mature GraphQL engine to build the
+first on. Lighthouse GraphQL Rails puts them together. It keeps Lighthouse's directive
+names, arguments and error formats wherever they make sense, so its documentation, its
+examples and the experience of Laravel teams carry over.
+
+## The problem with writing every resolver
+
+Most GraphQL fields in a Rails app do one of a handful of things: list records, find one,
+paginate, follow an association, filter and sort, read an attribute, or create, update
+and delete a record. Written by hand, each of these is a resolver. Each resolver is a
+place where:
+
+- **the API's shape hides in Ruby.** To know what `posts` accepts and returns, you read
+  a type class, its fields, their resolver methods and the scopes they call.
+- **N+1 queries creep in.** Every association needs its own batch loader, and every
+  paginated association needs a separate count, page and cursor logic.
+- **the same decisions are made again**, slightly differently each time: how pages are
+  numbered, what a cursor contains, how validation errors are reported, which filter
+  arguments are allowed.
+
+With [graphql-ruby](https://graphql-ruby.org) alone, a list of published posts with their
+author and comments, filterable by author, looks roughly like this:
+
+```ruby
+class Types::PostType < Types::BaseObject
+  field :id, ID, null: false
+  field :title, String, null: false
+  field :author, Types::UserType, null: false
+  field :comments, Types::CommentType.connection_type, null: false
+
+  def author
+    dataloader.with(Sources::RecordById, User).load(object.author_id)
+  end
+
+  def comments
+    object.comments.order(:created_at) # one query per post
+  end
+end
+
+class Types::QueryType < Types::BaseObject
+  field :posts, Types::PostType.connection_type, null: false do
+    argument :author_id, ID, required: false
+  end
+
+  def posts(author_id: nil)
+    scope = Post.published.order(created_at: :desc)
+    author_id ? scope.where(author_id: author_id) : scope
+  end
+end
+```
+
+…plus the `Sources::RecordById` batch loader, and more code to batch the comments. With
+Lighthouse, it is the schema:
+
+```graphql
+type Query {
+  posts(authorId: ID @eq): [Post!]! @paginate(type: CONNECTION) @builder(class: "Published")
+}
+
+type Post {
+  id: ID!
+  title: String!
+  author: User! @belongsTo
+  comments: [Comment!]! @hasMany(type: CONNECTION, scopes: ["chronological"])
+}
+```
+
+The `author` of every post loads in one query, and so does every post's page of
+comments, with one more for their totals if the client asks for `pageInfo { total }`. This isn't a
+special case: it is how every relationship directive works.
+
+## Why the schema comes first
+
+In a schema-first API, the `.graphql` files *are* the API's definition, not something
+generated from Ruby classes:
+
+- **It is a contract you can read.** Frontend developers, mobile developers and reviewers
+  read the same SDL that clients query. A pull request that changes the API shows the
+  change in the schema diff.
+- **It is designed before it is implemented.** You can agree on the types and fields
+  first, as a team, and the server follows the design rather than leaking its internals.
+- **Tools understand it directly.** IDE plugins, code generators and schema registries
+  read SDL. Lighthouse's `lighthouse:ide_helper` task adds its directives and generated
+  types so editors validate and autocomplete the schema.
+- **It says what each field does.** `posts: [Post!]! @paginate @guard @cacheControl(maxAge: 60)`
+  tells a reader, without opening any Ruby, that the field is paginated, requires a
+  signed-in user and can be cached for a minute.
+
+## Why directives
+
+Directives are a small vocabulary that composes. Each one does one job, and a field
+combines them:
+
+```graphql
+type Mutation {
+  updatePost(input: UpdatePostInput! @spread): Post!
+    @guard                                        # require a user
+    @canFind(ability: "update", find: "input.id") # PostPolicy#update?
+    @update                                       # save through Active Record, in a transaction
+    @clearCache(type: "Post", idSource: { argument: "input.id" })
+}
+```
+
+Because the behaviour is declared, Lighthouse controls the order it runs in
+(authentication, then authorization, then validation, then the save, then cache
+invalidation) and handles the details the same way everywhere: pagination types and
+cursors, validation errors keyed by argument path, `Cache-Control` headers. That
+consistency is what a hand-written resolver per field rarely achieves.
+
+## Why it fits Active Record
+
+A directive can only be this short if something else knows the details. In Lighthouse,
+that is the model layer. Active Record is opinionated, and every convention it imposes is
+information Lighthouse can use:
+
+| Active Record already knows | So Lighthouse can |
+| --- | --- |
+| Associations, their foreign keys, `:through` and polymorphic links | Resolve `@hasMany`, `@belongsTo`, `@belongsToMany` and `@morph*` from the name alone, batch them, and paginate many parents in one query |
+| Scopes | Narrow any query with `scopes: ["published"]` |
+| Validations | Report a failed `@create` or `@update` by argument path, with the model's own messages and locale |
+| Transactions and callbacks | Run nested mutations (create a post, attach tags, add comments) atomically, with your callbacks |
+| Naming conventions (`Post`, `posts`, `author_id`) | Map `Post` to its model, `authorId` to `author_id`, and a field to its association, with no configuration |
+
+The schema says **what** the API offers; the models already say **how** the data
+behaves. Nothing is described twice, and your domain logic stays where Rails puts it,
+in models, scopes, validations and policies, instead of moving into GraphQL resolvers.
+That is the same reason Lighthouse works so well on Eloquent: both are opinionated
+Active Record ORMs, and conventions are what make a declarative layer on top possible.
+
+## Ruby where there is real logic
+
+Schema-first doesn't mean schema-only. When a field does something no directive
+describes, write Ruby, using graphql-ruby's own classes:
+
+- A `Query` or `Mutation` field without a resolving directive resolves by convention to
+  `Queries::FieldName` (a `GraphQL::Schema::Resolver`) or `Mutations::FieldName` (a
+  `GraphQL::Schema::Mutation`). See [Queries, Mutations and Builders](resolvers.md).
+- `@builder` classes adjust a query; `@validator` contracts check arguments.
+- Your own directives plug in through the registry, with the same contracts as the
+  built-in ones. See [Custom Directives](custom-directives.md).
+
+Lighthouse is built on graphql-ruby, not instead of it: its Dataloader, its execution
+engine and its classes are all there when you need them.
+
+## From small apps to large ones
+
+The same schema serves a side project and a busy API. When it grows, opt-in features keep
+it fast without changing the schema: a cached schema build for quick boots, Apollo's
+persisted queries for CDN caching, and an allowlist of trusted operations. They are all
+off by default. See [Performance at scale](performance.md).
+
+## When something else fits better
+
+Lighthouse is at its best when the API is close to your models. Consider plain
+graphql-ruby, or using Lighthouse only for part of the schema, when:
+
+- the API is mostly computed, aggregated or fetched from other services, rather than read
+  from and written to your database;
+- your team prefers to define the schema in Ruby and generate the SDL from it
+  (code-first);
+- types differ so much from your tables that most fields would need their own resolver.
+
+Both approaches run on graphql-ruby, and a Lighthouse schema can call graphql-ruby
+classes anywhere, so you can start with directives and write Ruby where it pays off.
+
+Ready to try it? Continue with [Getting Started](getting-started.md).

data/docs/mutations.md

@@ -96,6 +96,21 @@ Without a filter argument, it refuses to run, since it would delete every row:
 abort the destroy is reported next to the data:
 `Could not modify model Post with ID 1.`
 
+### `@forceDelete` and `@restore`
+
+`@forceDelete` permanently removes soft deleted models and `@restore` un-deletes
+them. They work very much like `@delete` (required filter arguments, the models
+returned, `model:` and `scopes:`), but also find the models the soft-delete
+strategy hides. See [Soft deletes & global
+scopes](directives.md#soft-deletes-global-scopes).
+
+```graphql
+type Mutation {
+  forceDeletePost(id: ID! @whereKey): Post @forceDelete
+  restorePost(id: ID! @whereKey): Post @restore
+}
+```
+
 ## Validation errors
 
 When a model does not save, the mutation fails with PHP Lighthouse's error

data/docs/resolvers.md

@@ -2,13 +2,14 @@
 
 Most fields need no Ruby: a directive (`@all`, `@find`, `@paginate`, `@create`,
 …) or the default attribute reader resolves them. For the rest, Lighthouse looks
-up a class by name. There are three kinds of class, and they are not
+up a class by name. There are several kinds of class, and they are not
 interchangeable. Each kind has its own contract and its own folder:
 
 | Kind | Folder / namespace | Contract | Used by |
 | --- | --- | --- | --- |
 | Query | `app/graphql/queries` · `Queries::` | `GraphQL::Schema::Resolver` | `Query` fields |
 | Mutation | `app/graphql/mutations` · `Mutations::` | `GraphQL::Schema::Mutation` | `Mutation` fields |
+| Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `GraphQL::Schema::Subscription` | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
 Validators (`app/graphql/validators`) are the fourth kind. They are covered in
@@ -152,11 +153,22 @@ are looked up in the builders namespace only. Raising a `GraphQL::ExecutionError
 from a builder (e.g. a tenancy check) always reaches the client; it never falls
 back to the unscoped relation.
 
+The gem ships RBS signatures in `sig/`, so with Steep (or anything that reads
+`rbs collection`) a builder can be checked against `Lighthouse::_Builder`:
+
+```rbs
+# sig/builders/published.rbs
+class Builders::Published
+  extend Lighthouse::_Builder
+end
+```
+
 ## Generators
 
 ```shell
 bin/rails generate lighthouse:query LatestPosts        # app/graphql/queries/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
 ```