lighthouse-graphql 0.1.1 → 0.2.1

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

@@ -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.