lighthouse-graphql 0.2.1 → 0.4.0

data/docs/directives.md

@@ -150,8 +150,9 @@ The relation name defaults to the field name (snake_cased). Override with
 
 Delegate a field to a class — your escape hatch for anything the built-in
 directives don't cover. On `Query` and `Mutation` you usually don't need it:
-a field without a resolving directive resolves to `Queries::<FieldName>` /
-`Mutations::<FieldName>`, graphql-ruby resolver and mutation classes. See
+a field without a resolving directive resolves to `Resolvers::<FieldName>` /
+`Mutations::<FieldName>`, graphql-ruby resolver and mutation classes under
+`Resolvers::BaseResolver` / `Mutations::BaseMutation`. See
 [resolvers.md](resolvers.md).
 
 ```graphql
@@ -318,6 +319,33 @@ type Query {
 }
 ```
 
+### `@convertEmptyStringsToNull`
+
+Replaces incoming empty strings `""` with `null`, before any resolver sees them —
+directive resolvers (`@create`, `@all` filters, …), `@field`, `Resolvers::` /
+`Mutations::` classes and `@validator` alike. On an argument or an input field it
+converts that one input; on a field it converts every input of the field, nested
+input objects and lists included. Non-null inputs (`String!`) pass unchanged when
+the directive is only on the field: placing it on the non-null argument or input
+field itself forces the conversion.
+
+```graphql
+type Mutation {
+  createPost(title: String @convertEmptyStringsToNull, body: String): Post! @create
+  signUp(input: SignUpInput!): User! @create @convertEmptyStringsToNull
+}
+
+input SignUpInput {
+  name: String          # "" becomes null on signUp, but not where no directive applies
+  nickname: String @convertEmptyStringsToNull   # on every field taking SignUpInput
+  email: String!        # unchanged; add the directive here to force it
+}
+```
+
+A directive on an input field applies wherever the input type is used; one on a
+field affects only that field. To enable it for every field, set
+[`convert_empty_strings_to_null`](configuration.md#convert_empty_strings_to_null).
+
 ---
 
 ## Mutation directives
@@ -342,6 +370,197 @@ See [mutations.md](mutations.md).
 
 ---
 
+## Soft deletes & global scopes
+
+Rails has no built-in soft deletes or named global scopes, so these directives
+work with what Rails apps use. Lighthouse detects, per model, in this order:
+
+1. **[paranoia](https://github.com/rubysherpas/paranoia)** (`acts_as_paranoid`):
+   a default scope hides trashed records.
+2. **[discard](https://github.com/jhawthorn/discard)** (`include Discard::Model`):
+   nothing is hidden, unless the model adds `default_scope -> { kept }`.
+3. **A plain `deleted_at` column**, with no gem (a default scope is optional).
+
+An app with its own scheme, or another column, sets
+[`Config.soft_deletes`](configuration.md#soft_deletes). A model that matches none
+of them is an error when a client uses one of these directives on it
+(`Model Widget does not support soft deletes …`).
+
+### `@softDeletes`
+
+Lets clients filter trashed records. It adds the argument
+`trashed: Trashed @trashed` to the field and defines the `Trashed` enum once
+(unless your schema declares its own).
+
+```graphql
+type Query {
+  tasks: [Task!]! @all @softDeletes
+}
+```
+
+becomes
+
+```graphql
+type Query {
+  tasks(trashed: Trashed @trashed): [Task!]! @all
+}
+
+"Specify if you want to include or exclude trashed results from a query."
+enum Trashed {
+  "Only return trashed results."
+  ONLY
+  "Return both trashed and non-trashed results."
+  WITH
+  "Only return non-trashed results."
+  WITHOUT
+}
+```
+
+### `@trashed`
+
+The argument builder `@softDeletes` adds; use it by hand to name the argument
+yourself. It works wherever argument filters do: `@all`, `@paginate`, `@find`,
+`@first`, `@count` and the relationship directives (`@hasMany`, …, including
+paginated ones, which keep batching through the Dataloader).
+
+```graphql
+type Query {
+  flights(trashed: Trashed @trashed, destination: String @eq): [Flight!]! @all
+}
+type Post {
+  comments(trashed: Trashed @trashed): [Comment!]! @hasMany
+}
+```
+
+| Value | Result |
+| --- | --- |
+| `ONLY` | only trashed records |
+| `WITH` | trashed and non-trashed records |
+| `WITHOUT` | only non-trashed records |
+| *(omitted)* | **the model's own behaviour, untouched**: paranoia and a default scope hide trashed records, a bare `deleted_at` column or discard without a default scope show everything |
+
+`ONLY`, `WITH` and `WITHOUT` lift the model's default scope on the soft-delete
+column first, so they behave the same whatever the model does by default. That
+is `unscope(where: column)`, which removes every condition on that column from
+the query, including one added by an argument declared before `trashed`. Avoid a
+separate filter on the soft-delete column itself.
+
+### `@forceDelete`
+
+Permanently removes one or more soft deleted models. It works like
+[`@delete`](mutations.md#delete): the filter arguments (`@whereKey`, `@eq`, …) are
+required (`Would modify all models, use an argument to filter.`), the removed
+models are returned (a list for a list field, else the first or `null`), and
+`model:` and `scopes:` are honoured. It finds trashed models even when the model
+hides them by default, and it removes live ones too. It runs in a transaction
+(`Config.transactional_mutations`).
+
+```graphql
+type Mutation {
+  forceDeletePost(id: ID! @whereKey): Post @forceDelete
+  forceDeletePosts(ids: [ID!]! @whereKey): [Post!]! @forceDelete
+}
+```
+
+paranoia models are removed with `really_destroy!`, discard and `deleted_at`
+models with `destroy`. A model whose callbacks refuse is reported as
+`Could not modify model Post with ID 1.`
+
+### `@restore`
+
+Un-deletes one or more soft deleted models, with the same arguments, guard and
+result as `@forceDelete`: paranoia's `restore`, discard's `undiscard`, or setting
+the `deleted_at` column to `NULL`.
+
+```graphql
+type Mutation {
+  restorePost(id: ID! @whereKey): Post @restore
+}
+```
+
+### `@withoutGlobalScopes`
+
+Omits global scopes from the query when the client passes `true`. Use it on a
+`Boolean` argument; `false` and an omitted argument leave the scopes in place.
+
+```graphql
+type Query {
+  posts(includeUnscheduled: Boolean @withoutGlobalScopes(names: ["scheduled"])): [Post!]! @all
+}
+```
+
+ActiveRecord has one anonymous `default_scope`, not scopes with names, so each
+name is resolved like this (snake_cased; a trailing `Scope` is optional):
+
+1. A model scope **`without_<name>`**, if the model has one. You write it:
+   `scope :without_scheduled, -> { unscope(where: :schedule_at) }`.
+2. Else a **column** of that name: `unscope(where: column)`. Like `@trashed`, this
+   removes every condition on that column from the query, including ones added by
+   earlier arguments.
+3. Else a soft-delete name (`softDeletes`, `SoftDeletingScope`): trashed records
+   are included, as with `trashed: WITH`.
+
+Any other name is an error: `Cannot omit the global scope …`.
+
+---
+
+## Subscriptions
+
+Fields of the `Subscription` type resolve to a `Subscriptions::` class by
+convention, like queries and mutations: a plain graphql-ruby
+`GraphQL::Schema::Subscription` (`authorized?`, `subscribe`, `update`, ...).
+`@subscription` names another one, and `@broadcast` triggers a subscription from
+a mutation. The backend (ActionCable, ...) is the schema's; see
+[subscriptions.md](subscriptions.md).
+
+### `@subscription`
+
+```graphql
+directive @subscription(class: String!) on FIELD_DEFINITION
+```
+
+Names the class a `Subscription` field resolves to, when it does not follow the
+convention (`postUpdated` → `Subscriptions::PostUpdated`). The class inherits from
+`Subscriptions::BaseSubscription`, a `GraphQL::Schema::Subscription` that includes
+`Lighthouse::GraphQL::Subscription` (PHP Lighthouse's `filter?` hooks), and is looked
+up in `Config.namespaces[:subscriptions]`; a name with `::` is used as it is.
+
+```graphql
+type Subscription {
+  postUpdated(author: ID!): Post @subscription(class: "Blog::PostUpdatedSubscription")
+}
+```
+
+### `@broadcast`
+
+```graphql
+directive @broadcast(subscription: String!, shouldQueue: Boolean) repeatable on FIELD_DEFINITION
+```
+
+Once the field has resolved, triggers the `subscription` field of the
+`Subscription` type with the result as its root, so its subscribers are updated,
+each passing through the class's `update` (or `filter?`). The class's
+`self.trigger_arguments(root, context)` says which subscribers' arguments the
+trigger must equal: none are needed for a field without arguments, and a plain
+class with a required argument and no `trigger_arguments` is reported as a
+`Lighthouse::DefinitionError`. A failed mutation, or a `nil` result, broadcasts
+nothing. An unknown subscription name is a
+`Lighthouse::DefinitionError` when the schema is built. `shouldQueue` performs the
+trigger in an ActiveJob; without it, `Config.queue_broadcasts` (default `false`)
+decides.
+
+```graphql
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post! @create @broadcast(subscription: "postCreated")
+  updatePost(input: UpdatePostInput! @spread): Post!
+    @update
+    @broadcast(subscription: "postUpdated", shouldQueue: false)
+    @broadcast(subscription: "postChanged")
+}
+```
+
+---
+
 ## Validation
 
 `@validator` runs a contract (Dry::Validation by default) before a field
@@ -369,6 +588,118 @@ type Query {
 
 ---
 
+## Feature flags
+
+### `@feature`
+
+Include a field or an object type in the schema depending on a feature flag,
+backed by [Flipper](https://www.flippercloud.io/docs) (PHP Lighthouse's
+`@feature` is backed by Laravel Pennant).
+
+```graphql
+type Query {
+  newCheckout: Checkout @feature(name: "new_checkout")
+  legacyCheckout: Checkout @feature(name: "new_checkout", when: INACTIVE)
+}
+
+type Beta @feature(name: "beta") {
+  id: ID!
+}
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `name: String!` | The feature to check. |
+| `when: FeatureState = ACTIVE` | The state the feature must be in for the element to be included: `ACTIVE` or `INACTIVE`. |
+
+Feature flags depend on who asks, while the schema is built once, so the element
+stays in the schema and is hidden **per query**, through graphql-ruby's
+[visibility](https://graphql-ruby.org/authorization/visibility.html). A hidden
+field or type disappears from introspection, and a query selecting it fails
+validation (`Field 'newCheckout' doesn't exist on type 'Query'`). The fields
+returning a hidden type are hidden with it. `to_definition` prints the schema as
+the features stand for no actor.
+
+Each feature is checked at most once per query. By default Flipper is asked
+whether the feature is enabled for the authenticated user (`Flipper.enabled?(:new_checkout, user)`;
+the user answers `flipper_id`, which Flipper's ActiveRecord integration adds to
+models); with no user, the global gate decides. Flipper is optional: add
+`gem "flipper"` to your Gemfile, or configure your own check with
+`feature_checker` and `feature_actor` (see [configuration.md](configuration.md#feature_checker-feature_actor)).
+
+```ruby
+Flipper.enable_actor(:new_checkout, User.find(1))
+
+# schema.execute(query, context: { current_user: user })
+```
+
+---
+
+## Query complexity
+
+### `@complexity`
+
+Customize what a field costs in the query's complexity score, which graphql-ruby
+checks against the schema's `max_complexity` before it runs the query.
+
+```graphql
+type Query {
+  search(first: Int, term: String!): [Post!]! @complexity
+  posts(includeFullText: Boolean): [Post!]! @all @complexity(resolver: "PostsComplexity")
+}
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `resolver: String` | A `GraphQL::Analysis::Analyzer` subclass in `namespaces[:analyzers]` (`Analyzers::PostsComplexity`), installed on the schema. With `Lighthouse::GraphQL::ComplexityAnalyzer` included, its `complexity` (a number, or a proc of `context, args, child_complexity`) is the field's cost. Without it, or without `resolver:`: `1 + child complexity × first`. |
+
+Paginated fields cost `1 + child complexity × first` without the directive, and a
+field resolved by a `GraphQL::Schema::Resolver` class costs what that class
+declares. See [security.md](security.md).
+
+---
+
+## Events
+
+`@event` dispatches an event once the field has resolved. The class is built with
+the resolved value and handed to `Lighthouse::Events.dispatch`; the value is
+returned unchanged, and nothing is dispatched when the field raises. It is
+repeatable: each `@event` dispatches its own. See [events.md](events.md) for
+listening, and for the events Lighthouse itself dispatches.
+
+```graphql
+directive @event(dispatch: String!) repeatable on FIELD_DEFINITION
+```
+
+```graphql
+type Mutation {
+  shipOrder(id: ID!): Order!
+    @update
+    @event(dispatch: "OrderShipped")
+    @event(dispatch: "Billing::InvoiceDue")
+}
+```
+
+```ruby
+class OrderShipped
+  attr_reader :order
+
+  def initialize(order) = @order = order
+end
+
+Lighthouse::Events.listen(OrderShipped) { |event| Mailer.shipped(event.order).deliver_later }
+```
+
+The class is looked up in `Config.namespaces[:events]` (default `['Events']`,
+so `Events::OrderShipped`, then `::OrderShipped`); a name with `::` is used
+as-is. A name that finds no class fails the schema build with
+`Lighthouse::DefinitionError`. `@event` runs inside `@guard`, `@can*`,
+`@validator` and `@cache`: a rejected request, or a cache hit, dispatches
+nothing. (`@canResolved` checks the resolved value, so there the event is
+dispatched before the check.)
+
+---
+
 ## Adding your own
 
 Every directive above is a small class registered with

data/docs/events.md

@@ -0,0 +1,203 @@
+# 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 the query's complexity score, the number graphql-ruby
+checks against `max_complexity` (see [security.md](security.md#reading-the-score)).
+It is `nil` for a query that failed validation.
+
+**`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/federation.md

@@ -13,7 +13,8 @@ Include the federation mixins in the base types you pass to Lighthouse, and make
 your schema a federation schema:
 
 ```ruby
-class BaseObject < GraphQL::Schema::Object
+# app/graphql/types/base_object.rb
+class Types::BaseObject < GraphQL::Schema::Object
   include ApolloFederation::Object
 
   # Default entity resolution: look the record up by id on the model that shares
@@ -29,7 +30,7 @@ end
 
 BaseAppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   sdl_folder: Rails.root.join('graphql').to_s,
-  options: { federation: true, base_types: { object: BaseObject } }
+  options: { federation: true, base_types: { object: Types::BaseObject, resolver: Resolvers::BaseResolver } }
 )
 
 class AppSchema < BaseAppSchema