lighthouse-graphql 0.2.1 → 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/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
@@ -167,6 +168,7 @@ end
 ```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
 ```