lighthouse-graphql 0.1.0 → 0.2.0

data/docs/mutations.md

@@ -0,0 +1,260 @@
+# Mutations
+
+Write a mutation as a [class in `app/graphql/mutations`](resolvers.md) when it
+carries business logic. Plain create, update, upsert and delete need no Ruby:
+`@create`, `@createMany`, `@update`, `@updateMany`, `@upsert`, `@upsertMany` and
+`@delete` work on the model a field returns, through ActiveRecord. Nested input
+saves its associations too. The model's validations, callbacks and associations
+behave exactly as they do anywhere else in your app.
+
+```graphql
+type Mutation {
+  createPost(title: String!, body: String): Post! @create
+  updatePost(id: ID!, title: String, body: String): Post! @update
+  createPosts(inputs: [CreatePostInput!]!): [Post!]! @createMany
+  updatePosts(inputs: [UpdatePostInput!]!): [Post!]! @updateMany
+}
+```
+
+## How arguments become attributes
+
+Each argument the client sends becomes one attribute, under its `snake_case`
+name. Arguments the client leaves out are not assigned at all, so `@update` only
+changes what was sent.
+
+- **`@rename(attribute:)`** maps an argument (or input field) to a differently
+  named attribute:
+  ```graphql
+  createPost(title: String!, content: String @rename(attribute: "body")): Post @create
+  ```
+- **`@spread`** merges an input object's fields into the arguments. This is the
+  usual shape for a single `input:` argument:
+  ```graphql
+  createPost(input: CreatePostInput! @spread): Post @create
+  ```
+- **`@inject(context:, name:)`** sets a server-side attribute from the context,
+  so clients cannot choose it:
+  ```graphql
+  createPost(title: String!): Post @create @inject(context: "current_user.id", name: "author_id")
+  ```
+- **`model:`** names the model when it is not the field's return type:
+  `@create(model: "Admin::Post")`.
+
+## The directives
+
+### `@create`
+
+Builds the model from the arguments and saves it.
+
+### `@createMany`
+
+The field takes exactly one argument, a list of input objects. Lighthouse creates
+one model per item.
+
+### `@update`
+
+Finds the model by its primary key and updates it. The key comes from the
+argument named after the primary key (`id`), or the one renamed to it. A missing
+record raises `Couldn't find Post with 'id'=…`, the same wording as Rails.
+
+### `@updateMany`
+
+Like `@createMany`, but each item carries its primary key. Without a key the
+mutation fails with `Missing primary key for update.`
+
+### `@upsert` / `@upsertMany`
+
+Update the model the input identifies, or create it:
+
+- With `identifyingColumns: ["email"]`, the model is matched on those columns.
+  All of them must be given and non-null.
+- Otherwise it is matched on the primary key.
+- When nothing matches, the model is created, with the given id if there is one.
+
+```graphql
+type Mutation {
+  upsertUser(email: String!, name: String!): User @upsert(identifyingColumns: ["email"])
+  upsertPosts(inputs: [UpsertPostInput!]!): [Post!]! @upsertMany
+}
+```
+
+### `@delete`
+
+Destroys the models the field's filter arguments select, running their callbacks,
+and returns them: a list for a list field, else the first or `null`.
+
+```graphql
+type Mutation {
+  deletePost(id: ID! @whereKey): Post @delete
+  deletePosts(ids: [ID!]! @whereKey): [Post!]! @delete
+  deleteDrafts(authorId: ID! @eq): [Post!]! @delete(scopes: ["drafts"])
+}
+```
+
+Without a filter argument, it refuses to run, since it would delete every row:
+`Would modify all models, use an argument to filter.` A model whose callbacks
+abort the destroy is reported next to the data:
+`Could not modify model Post with ID 1.`
+
+## Validation errors
+
+When a model does not save, the mutation fails with PHP Lighthouse's error
+format. Messages are keyed by **argument path**, including the path inside a
+spread input or the index of a list item:
+
+```json
+{
+  "data": { "createPosts": null },
+  "errors": [{
+    "message": "Validation failed for the field [createPosts].",
+    "extensions": {
+      "validation": {
+        "inputs.1.title": ["Title can't be blank"],
+        "inputs.2.title": ["Title can't be blank"]
+      }
+    }
+  }]
+}
+```
+
+Messages are the models' `full_message`s, so they follow your locale files. A
+`:base` error is keyed by the field name. For rules that don't belong to the
+model, add a [`@validator`](validation.md). It runs before the model is saved.
+
+## Transactions
+
+Each mutation field runs in a database transaction. If one item of a
+`@createMany` is invalid, the others are rolled back, and the response lists every
+invalid item, not just the first. To turn this off:
+
+```ruby
+Lighthouse.configure { |config| config.transactional_mutations = false }
+```
+
+## Combining with authorization and cache invalidation
+
+```graphql
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post!
+    @create
+    @guard
+    @canModel(ability: "create")
+    @clearCache(type: "Query", field: "latestPosts")
+
+  updatePost(input: UpdatePostInput! @spread): Post!
+    @update
+    @canFind(ability: "update", find: "input.id")
+    @clearCache(type: "Post", idSource: { argument: "input.id" })
+}
+```
+
+The order you write them in does not matter: authentication runs first, then
+authorization, validation, and the save; `@clearCache` acts once the save has
+succeeded. See [authorization.md](authorization.md) and [caching.md](caching.md).
+
+## Nested mutations
+
+An input field named after one of the model's associations carries **operations**
+on that association, and its type declares which are allowed. This is PHP
+Lighthouse's nested mutation API, run through ActiveRecord:
+
+```graphql
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post @create
+  updatePost(input: UpdatePostInput! @spread): Post @update
+}
+
+input CreatePostInput {
+  title: String!
+  author: AuthorBelongsTo            # Post belongs_to :author
+  comments: CommentsHasMany          # Post has_many :comments
+  tags: TagsBelongsToMany            # Post has_many :tags, through: :taggings
+}
+
+input AuthorBelongsTo { connect: ID create: CreateUserInput update: UpdateUserInput upsert: UpsertUserInput }
+input CommentsHasMany { create: [CreateCommentInput!] connect: [ID!] }
+input TagsBelongsToMany { connect: [ID!] sync: [ID!] create: [CreateTagInput!] }
+```
+
+```graphql
+mutation {
+  createPost(input: {
+    title: "Hello"
+    author: { connect: 1 }
+    comments: { create: [{ body: "First!" }] }
+    tags: { sync: [3, 4] }
+  }) { id author { name } comments { body } tags { name } }
+}
+```
+
+### Operations by association
+
+| Association | Operations |
+| --- | --- |
+| `belongs_to` | `connect: ID`, `create`, `update`, `upsert`, `disconnect: Boolean`, `delete: Boolean` |
+| `belongs_to …, polymorphic: true` | `connect: { type: String!, id: ID! }`, `disconnect`, `delete` |
+| `has_one` (also `as:`) | `create`, `update`, `upsert`, `delete: ID` |
+| `has_many` (also `as:`) | `create`, `update`, `upsert`, `connect: [ID!]`, `disconnect: [ID!]`, `delete: [ID!]` |
+| `has_many :through`, `has_and_belongs_to_many` | `sync`, `syncWithoutDetaching`, `create`, `update`, `upsert`, `connect`, `disconnect: [ID!]`, `delete: [ID!]` |
+
+- `create`, `update` and `upsert` take input objects, or lists of them for
+  collections. Those inputs may nest further operations, to any depth.
+- `null` operations are ignored, and `disconnect`/`delete` only act when `true`.
+- A polymorphic `connect`'s `type` is a model name: `"Task"`, or an enum value
+  such as `TASK`.
+- `has_one` refuses a second `create`: "Cannot create a related model: a Post
+  already exists for this Task. Use upsert to modify the existing model." An
+  `upsert` without an id updates the existing one.
+- Operations run in PHP Lighthouse's fixed order, whatever order the client
+  writes them in.
+
+### Pivot values
+
+For a `has_many :through`, `connect`, `sync` and `syncWithoutDetaching` accept
+inputs with an `id` plus columns of the join model:
+
+```graphql
+input UpdateUserRoles { sync: [RolePivot!] connect: [RolePivot!] }
+input RolePivot { id: ID! expiresAt: String }  # role id + role_assignments.expires_at
+```
+
+`has_and_belongs_to_many` has no join model, so it takes plain ids only.
+
+### When it saves, and what fails
+
+Each record is saved **once**:
+
+1. its attributes are assigned;
+2. `belongs_to` operations set its foreign keys (creating or updating the parent
+   records first);
+3. it is saved;
+4. the operations on associations pointing back at it run.
+
+Validation errors from any level are keyed by their full input path, e.g.
+`input.author.create.name`. The whole mutation is one transaction, so a failure
+anywhere rolls everything back.
+
+### Operations as arguments
+
+`@create`, `@update`, `@upsert` (with optional `identifyingColumns`) and `@delete`
+on an argument or input field, with `relation:`, run that operation on the
+association instead:
+
+```graphql
+input UpdateUserInput {
+  id: ID!
+  newTask: CreateTaskInput @create(relation: "tasks")
+  tasks: [UpsertTaskInput!] @upsert(relation: "tasks", identifyingColumns: ["name"])
+  deleteTasks: [ID!] @delete(relation: "tasks")
+  deleteAvatar: Boolean @delete(relation: "avatar")
+}
+```
+
+### Permissions
+
+As in PHP Lighthouse, nested `update`, `upsert`, `delete` and `disconnect` find
+records by primary key **in the whole table**, not only among the parent's
+current children. A nested `update` of another user's task moves the task to
+this user. Authorize the mutation field accordingly, with `@can*` checks on the
+field or validators that restrict the ids. There is no per-operation permission
+mechanism.

data/docs/performance.md

@@ -0,0 +1,138 @@
+# Performance at scale
+
+A Rails process is long-lived: it builds the schema once at boot (before forking,
+with Puma's `preload_app!`) and reuses it for every request. So PHP Lighthouse's
+per-request schema and query caches mostly solve a problem Rails does not have.
+Large schemas and high traffic still benefit from three options. **All are off
+by default**; enable the ones your app needs.
+
+| Option | What it does | Turn it on when |
+| --- | --- | --- |
+| [`schema_cache`](#schema-cache) | Caches the built schema document in `tmp/cache` | The schema is large and boot time matters (autoscaling, serverless, CI) |
+| [`watch_sdl`](#reloading-the-sdl-in-development) | Reloads the app when a `.graphql` file changes | Developing; typically `Rails.env.development?` |
+| [`persisted_queries`](#persisted-queries) | Apollo's Automatic Persisted Queries, optionally an allowlist | Large queries, CDN caching of `GET`s, locking the API down to known operations |
+
+## Schema cache
+
+```ruby
+Lighthouse.configure { |config| config.schema_cache = Rails.env.production? }
+```
+
+Building a schema parses the SDL, injects directive definitions, runs the
+manipulators (pagination types, `whereConditions` inputs, …), parses the result
+and builds the executable schema. The cache stores the parsed, manipulated
+document, so a boot skips everything up to that last step.
+
+Measured on synthetic schemas (one machine; orders of magnitude, not promises):
+
+| Schema | Without cache | Cached boot |
+| --- | --- | --- |
+| 150 models (≈1,000 types) | 260 ms | 145 ms |
+| 600 models (≈4,300 types) | 1,060 ms | 560 ms |
+
+It works the way Bootsnap does: a content-addressed file in
+`tmp/cache/lighthouse` (`config.schema_cache_path` to move it).
+
+- **The key.** It covers the SDL, the Lighthouse, graphql-ruby and Ruby versions,
+  the registered directive and type definitions, the manipulators' source and the
+  configuration they read. Change any of them and the next boot rebuilds, so a
+  stale schema cannot be served and there is nothing to clear by hand.
+- **Writes.** They are atomic, so concurrent boots never read half a file. Only
+  the current entry is kept.
+- **Errors.** An unreadable file is a cache miss, never an error.
+
+To ship a warm cache, build it where the release is built (e.g. a Docker image
+layer):
+
+```shell
+bin/rails lighthouse:cache        # writes tmp/cache/lighthouse/schema-<key>.bin
+bin/rails lighthouse:clear_cache  # deletes it (never required: keys change on their own)
+```
+
+Unlike PHP Lighthouse's `lighthouse:cache`, forgetting to run it is harmless:
+the first boot writes the cache.
+
+## Reloading the SDL in development
+
+```ruby
+Lighthouse.configure { |config| config.watch_sdl = Rails.env.development? }
+```
+
+Rails' reloader watches Ruby files, not `.graphql` ones, so without this an SDL
+edit only shows up after restarting the server. With it, the SDL folder joins
+`config.watchable_dirs`, and an edit reloads the app, and with it the schema, on
+the next request, like a Ruby change. This relies on the schema constant living
+in an autoloaded file, as the generated `app/graphql/app_schema.rb` does.
+
+## Persisted queries
+
+```ruby
+Lighthouse.configure do |config|
+  config.persisted_queries = true
+  config.persisted_queries_ttl = 1.week.to_i   # optional; default: until the store evicts
+end
+```
+
+This is the [Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
+protocol, as Apollo Client (`createPersistedQueryLink`), urql and PHP
+Lighthouse speak it:
+
+1. The client sends `extensions: { persistedQuery: { version: 1, sha256Hash } }`
+   without the query.
+2. A known hash runs. An unknown one answers `PersistedQueryNotFound`, and the
+   client retries with the query, which is checked against the hash and stored
+   in `config.persisted_queries_store` (default: `Rails.cache`).
+3. With the feature off, clients get `PersistedQueryNotSupported` and simply
+   keep sending queries.
+
+The generated controller runs requests through
+`Lighthouse::GraphQL::PersistedQueries.execute`. A hash fits in a URL, so add a
+`GET` route and CDNs can cache responses under the `Cache-Control` header that
+[`@cacheControl`](caching.md#cachecontrol) computes. Rack's ETag middleware adds
+an `ETag` too:
+
+```ruby
+# config/routes.rb
+post "/graphql", to: "graphql#execute"
+get  "/graphql", to: "graphql#execute"
+```
+
+Parsing and validating a query costs well under a millisecond, so this is about
+bandwidth, CDN caching and control, not CPU.
+
+### Trusted documents: a manifest and an allowlist
+
+Large APIs often accept only the operations their own clients ship. Point
+Lighthouse at a manifest generated by the client build, either Apollo's
+persisted query manifest
+(`{ "operations": [{ "id": "<sha256>", "body": "query …" }] }`) or a plain
+`{ "<sha256>": "query …" }` object:
+
+```ruby
+config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')
+config.persisted_queries_only = Rails.env.production?
+```
+
+- The manifest's operations are served from memory, so a cache eviction can
+  never drop them. The file is reloaded when it changes, and an id that is not
+  the SHA-256 of its body is rejected.
+- With `persisted_queries_only`, nothing else runs, and arbitrary queries get
+  `Only persisted queries are allowed.` (`PERSISTED_QUERY_NOT_IN_LIST`).
+
+Check in CI that a schema change does not break an operation already shipped to
+clients:
+
+```shell
+bin/rails lighthouse:persisted_queries:verify SCHEMA=AppSchema
+```
+
+## What is deliberately not cached
+
+- **Query ASTs and validation results.** PHP Lighthouse caches them because PHP
+  starts from scratch on every request. Here, parsing and validating a sizeable
+  query takes about 0.2 ms and 0.6 ms. A shared store (Redis, Memcached) costs a
+  network round trip, which is more than parsing, and validation can depend on
+  the request's context, which a cache keyed by query text would skip.
+- **Compiled Ruby.** Your app's code, and Lighthouse's, are already compiled
+  and cached by Bootsnap (instruction sequences) and YJIT. The SDL is not Ruby,
+  so there is nothing for them to compile.

data/docs/relationships.md

@@ -12,27 +12,47 @@ end
 
 ```graphql
 type Post {
-  author: User! @belongsTo(relation: "author")
+  author: User! @belongsTo
   comments: [Comment!]! @hasMany
 }
 ```
 
+| Directive | ActiveRecord association |
+| --- | --- |
+| `@belongsTo` | `belongs_to` |
+| `@hasOne` | `has_one` |
+| `@hasMany` | `has_many` |
+| `@belongsToMany` | `has_many :through`, `has_and_belongs_to_many` |
+| `@morphTo` | `belongs_to …, polymorphic: true` |
+| `@morphOne` / `@morphMany` | `has_one` / `has_many …, as:` |
+| `@morphToMany` | `has_many :through` a polymorphic join |
+
+The `morph*` names are PHP Lighthouse's. ActiveRecord resolves polymorphic
+associations the same way as any other, so they behave exactly like their
+non-polymorphic counterparts. Use whichever reads better.
+
 ## Avoiding the N+1 problem
 
-Resolving relationships naively triggers one query per parent record. Lighthouse's
-relationship directives load through graphql-ruby's **Dataloader**, batching all
-sibling loads into a single query. Enable it on your schema:
+The relationship directives load through graphql-ruby's **Dataloader** and
+ActiveRecord's preloader, one query per association per batch. Enable the
+Dataloader on your schema (the install generator does):
 
 ```ruby
-class AppSchema < BaseAppSchema
-  use GraphQL::Dataloader
-end
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { using: { GraphQL::Dataloader => {} } }
+)
 ```
 
-With the Dataloader in place, a query for 100 posts and their authors issues two
-queries, not 101.
+A query for 100 posts and their authors then issues two queries, not 101. A
+many-to-many or `:through` association adds one query for the join table. Without
+the Dataloader, the directives still work, but they load one parent at a time.
+
+A field with `scopes:` or a filter argument the client supplied runs its own query
+per parent, because each parent's query differs.
+
+## Lists, and paginating them
 
-## One-to-many — `@hasMany`
+Collection directives return a **plain list**, as in PHP Lighthouse:
 
 ```graphql
 type User {
@@ -40,38 +60,59 @@ type User {
 }
 ```
 
-`@hasMany` returns a **connection** type, so it supports pagination arguments and
-`edges { node { ... } }` / `nodes { ... }` selections out of the box. The inverse
-is `@belongsTo`.
+```graphql
+{ user(id: 1) { posts { title } } }
+```
 
-## One-to-one — `@hasOne`
+To paginate, pass `type:`, which takes the same values as
+[`@paginate`](directives.md#paginate): `PAGINATOR`, `SIMPLE` or `CONNECTION`.
+Lighthouse rewrites the field and adds the pagination arguments:
 
 ```graphql
 type User {
-  profile: Profile @hasOne
+  posts: [Post!]! @hasMany(type: PAGINATOR, defaultCount: 10)
+  feed: [Post!]! @hasMany(relation: "posts", type: CONNECTION)
 }
 ```
 
-## Inverse — `@belongsTo`
-
 ```graphql
-type Post {
-  author: User! @belongsTo(relation: "author")
+{
+  user(id: 1) {
+    posts(first: 5, page: 2) { paginatorInfo { total lastPage } data { title } }
+    feed(first: 5, after: "NQ==") { pageInfo { hasNextPage endCursor } edges { node { title } } }
+  }
 }
 ```
 
-## Many-to-many — `@belongsToMany`
+`defaultCount` and `maxCount` work as on `@paginate`.
 
-```graphql
-type User {
-  roles: [Role!]! @belongsToMany
-}
-```
+### Paginating many parents at once
+
+With the Dataloader, a paginated relation loads the pages of **every parent** of
+a level together, as PHP Lighthouse does: `{ users { posts(first: 5) { … } } }`
+costs one query for the pages, plus one for the totals if the client selects
+`paginatorInfo` or `pageInfo` — however many users there are. The same goes for
+`@paginate` on a nested field.
+
+- **Pages.** A window function numbers each parent's rows in the field's order
+  (`@orderBy`, else the primary key), and one query keeps the rows of the
+  requested page: `ROW_NUMBER() OVER (PARTITION BY posts.user_id ORDER BY …)`.
+  PHP Lighthouse uses a `UNION ALL` of one query per parent instead; a window
+  function keeps the SQL the same size for 3 parents or 3,000.
+- **Totals.** One `GROUP BY` counts every parent's related records, with the same
+  scopes and filters as the page. The count only runs when a total is asked for,
+  and never for `SIMPLE`, which fetches one extra row instead.
+
+This needs window functions: PostgreSQL, MySQL 8+, MariaDB 10.2+ or SQLite 3.25+.
+A relation falls back to one query per parent on other databases, without the
+Dataloader, and when its rows can't be numbered per parent: a composite key, an
+association scope that reads the owner (`has_many :x, ->(owner) { … }`), or
+`DISTINCT`. The pages are the same either way.
 
 ## Renaming relations
 
-By default the relation name equals the field name (snake_cased). When they
-differ, pass `relation:`:
+By default the relation name is the field name, snake_cased. When they differ,
+pass `relation:`:
 
 ```graphql
 type Post {
@@ -79,17 +120,23 @@ type Post {
 }
 ```
 
-## Filtering a relationship
+## Scopes and filters
 
-Relationship fields accept the same [argument filters](filtering-and-ordering.md)
-and [`@whereConditions`](filtering-and-ordering.md#complex-where-conditions) as
-root queries, so you can scope the related records:
+`scopes:` applies model scopes to the association. Relationship fields also
+accept the same [argument filters](filtering-and-ordering.md) and
+[`@whereConditions`](filtering-and-ordering.md#complex-where-conditions) as root
+queries:
 
 ```graphql
 type User {
   publishedPosts(
-    status: String @eq
+    title: String @like
     orderBy: [OrderByClause!] @orderBy
-  ): [Post!]! @hasMany(relation: "posts")
+  ): [Post!]! @hasMany(relation: "posts", scopes: ["published"])
 }
 ```
+
+## Writing relationships
+
+Creating, connecting, syncing or deleting related records from a mutation's input
+is covered by [nested mutations](mutations.md#nested-mutations).