lighthouse-graphql 0.4.0 → 0.5.0

data/docs/resolvers.md

@@ -10,30 +10,39 @@ interchangeable. Each kind has its own contract and its own folder:
 | Resolver | `app/graphql/resolvers` · `Resolvers::` | `Resolvers::BaseResolver` (a `GraphQL::Schema::Resolver`) | `Query` fields |
 | Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (a `GraphQL::Schema::Mutation`) | `Mutation` fields |
 | Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `Subscriptions::BaseSubscription` (a `GraphQL::Schema::Subscription`) | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
+| Type | `app/graphql/types` · `Types::` | `Types::BaseObject` (a `GraphQL::Schema::Object`) including `Lighthouse::GraphQL::Type`, named `<Type>Type` | Fields of other types, through its methods ([type classes](#type-classes)); unions, interfaces and scalars too ([types.md](types.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
-Validators (`app/graphql/validators`) are the fourth kind. They are covered in
+Validators (`app/graphql/validators`) are one more kind. They are covered in
 [validation.md](validation.md).
 
 ## Base classes
 
-As in any graphql-ruby app, each of the first three kinds has a base class in its
-namespace, and every class of the kind inherits from it:
+As in any graphql-ruby app, each kind of class has a base class in its namespace,
+and every class of the kind inherits from it. graphql-ruby's `graphql:install`,
+which `rails g lighthouse:install` runs, writes `Resolvers::BaseResolver`,
+`Mutations::BaseMutation` and the `Types::Base*` classes; Lighthouse adds
+`Subscriptions::BaseSubscription`, which graphql-ruby has none of, and makes the
+mutation base a plain `GraphQL::Schema::Mutation`, as the SDL declares a mutation's
+arguments ([generators.md](generators.md)):
 
 ```ruby
-# app/graphql/resolvers/base_resolver.rb
+# app/graphql/resolvers/base_resolver.rb          (graphql-ruby's)
 module Resolvers
   class BaseResolver < GraphQL::Schema::Resolver
   end
 end
 
-# app/graphql/mutations/base_mutation.rb
+# app/graphql/mutations/base_mutation.rb          (graphql-ruby's, made a Mutation)
 module Mutations
   class BaseMutation < GraphQL::Schema::Mutation
+    argument_class Types::BaseArgument
+    field_class Types::BaseField
+    object_class Types::BaseObject
   end
 end
 
-# app/graphql/subscriptions/base_subscription.rb
+# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's)
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
     include Lighthouse::GraphQL::Subscription
@@ -43,11 +52,8 @@ end
 
 What every class of a kind shares goes in its base, once: a concern (as
 `BaseSubscription` includes Lighthouse's, see [subscriptions.md](subscriptions.md)),
-a helper, graphql-ruby settings such as `argument_class Types::BaseArgument`.
-`rails g lighthouse:install` writes the three, and the class generators write the
-one they need when it is missing. graphql-ruby's own `graphql:install` writes
-`Resolvers::BaseResolver` and `Mutations::BaseMutation` too, and Lighthouse keeps
-whatever is already there: an existing base is never replaced.
+a helper, graphql-ruby settings such as `argument_class Types::BaseArgument`. An
+existing base is never replaced.
 
 ### Handing the bases to the schema
 
@@ -61,8 +67,13 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
     base_types: {
       resolver: Resolvers::BaseResolver,
       mutation: Mutations::BaseMutation,
-      subscription: Subscriptions::BaseSubscription
-      # object: Types::BaseObject, ... (graphql-ruby's, for the SDL's types)
+      subscription: Subscriptions::BaseSubscription,
+      object: Types::BaseObject,
+      interface: Types::BaseInterface,
+      union: Types::BaseUnion,
+      scalar: Types::BaseScalar,
+      enum: Types::BaseEnum,
+      input_object: Types::BaseInputObject
     }
   }
 )
@@ -78,6 +89,10 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   (`GraphQL::Schema::Resolver`, `GraphQL::Schema::Mutation`, which
   `RelayClassicMutation` is, `GraphQL::Schema::Subscription`), or the schema does not
   build. graphql-ruby never sees these three keys.
+- The others are graphql-ruby's: it builds the SDL's types of each kind from them.
+  A [type class](#type-classes) (one including `Lighthouse::GraphQL::Type`) that
+  does not inherit from its kind's raises `Lighthouse::DefinitionError` when the
+  schema is built.
 
 `rails g lighthouse:install` writes the schema class with them. Without them,
 Lighthouse requires only the graphql-ruby class (`GraphQL::Schema::Resolver`, …),
@@ -174,7 +189,233 @@ type Query {
 ```
 
 Besides graphql-ruby resolver classes, `@field` also accepts a plain callable:
-anything with `call(object, args, context)`.
+anything with `call(object, args, context)`, and `call(object, args, context,
+resolve_info)` when it takes a fourth argument.
+
+A method after `@` (PHP Lighthouse's `Class@method`) replaces `call`, or `resolve` on
+a resolver class (whose `authorized?` still runs). One class can then hold several
+fields' resolvers:
+
+```graphql
+type Query {
+  counts: Counts! @field(resolver: "Statistics@counts")
+  latest: [Post!]! @field(resolver: "Statistics@latest")
+}
+```
+
+```ruby
+class Resolvers::Statistics
+  def self.counts(_root, _args, _context) = { posts: Post.count, users: User.count }
+  def self.latest(_root, _args, _context) = Post.order(created_at: :desc).limit(5)
+end
+```
+
+### ResolveInfo
+
+What PHP Lighthouse hands a resolver as `$resolveInfo`. A `Resolvers::` or
+`Mutations::` class, a class `@field` names and a type class's methods read it as
+`resolve_info`:
+
+| | |
+| --- | --- |
+| `field_name`, `field`, `return_type` | the field being resolved |
+| `parent_type` | the type it belongs to |
+| `object`, `arguments`, `context` | what it resolves with |
+| `path` | `["posts", 0, "author"]` |
+| `lookahead` | graphql-ruby's [`Lookahead`](https://graphql-ruby.org/queries/lookahead.html): what the client selects below the field (`lookahead.selects?(:author)`) |
+| `enhance_builder(relation, scopes: [])` | `relation` with the field's query directives applied |
+
+`enhance_builder` lets a class build the query no directive could, and still honour
+what the field declares: its `@builder` classes, and the argument directives the
+client used (`@eq`, `@where`, `@in`, `@like`, `@orderBy`, `@whereConditions`, ...),
+as `@all` and `@paginate` apply them. `scopes:` adds model scopes.
+
+```graphql
+type Query {
+  myPosts(title: String @like, orderBy: [PostOrderByClause!] @orderBy): [Post!]! @guard
+}
+```
+
+```ruby
+class Resolvers::MyPosts < Resolvers::BaseResolver
+  def resolve(**)
+    resolve_info.enhance_builder(context[:current_user].posts, scopes: [:recent])
+  end
+end
+```
+
+### Fields of other types
+
+A field of any other type resolves with the default reader: `Post.commentsCount`
+reads `post.comments_count`. When its value takes more than reading an attribute
+or calling a method ([`@method`](directives.md#method)), name a class with
+`@field`. The class is a resolver like the ones above, and its `object` is the
+**parent**: the record the field belongs to (PHP Lighthouse's `$root`). It
+resolves wherever the type appears in a response: in a list, under a
+relationship, or under another class's result.
+
+```graphql
+type Post {
+  tagsCount: Int! @field(resolver: "Posts::TagsCount")
+  excerpt(length: Int = 80): String @field(resolver: "Posts::Excerpt")
+}
+```
+
+```ruby
+# app/graphql/resolvers/posts/tags_count.rb
+module Resolvers
+  module Posts
+    class TagsCount < BaseResolver
+      def resolve
+        dataload_association(object, :tags).size
+      end
+    end
+  end
+end
+
+# app/graphql/resolvers/posts/excerpt.rb
+module Resolvers
+  module Posts
+    class Excerpt < BaseResolver
+      def resolve(length:)
+        object.body&.truncate(length, separator: ' ')
+      end
+    end
+  end
+end
+```
+
+```graphql
+{
+  posts(first: 10) { data { title tagsCount excerpt(length: 40) } }
+}
+```
+
+The field's arguments arrive as keyword arguments, with the SDL's default when the
+client leaves one out, as on a root field. The class runs once per parent, so load
+anything beyond the parent's own columns through graphql-ruby's dataloader
+(`dataload_association`, `dataload_record`, or a `GraphQL::Dataloader::Source` of
+your own). Then listing ten posts runs one query for their tags, not ten.
+
+A field can also resolve with a method of its type's class, as in a graphql-ruby
+app. See [type classes](#type-classes), next: they suit a field that only the type
+needs, and a class named by `@field` suits one with its own logic, its own
+arguments, or that you want to find in the schema.
+
+On these types the name is looked up in the resolvers namespace first, a nested
+name too, so `Posts::TagsCount` is `Resolvers::Posts::TagsCount`, kept in
+`app/graphql/resolvers/posts/`. A folder per type keeps these classes apart from
+the `Query` ones. Name it in the plural (`Posts`): a `Resolvers::Post` module would
+hide the `Post` model from code written inside `module Resolvers`. When the
+resolvers namespace has no such class, the name is looked up in
+[`resolver_namespaces`](configuration.md#resolver_namespaces), and a full name
+(`Resolvers::Posts::TagsCount`) works as well. The schema's `base_types` are not
+enforced here, but inheriting from `Resolvers::BaseResolver` still gives the class
+what every resolver shares.
+
+### Type classes
+
+graphql-ruby keeps the Ruby side of each object type in `app/graphql/types`:
+`Types::PostType`, inheriting from `Types::BaseObject`, as `rails g graphql:object
+Post` writes it. Lighthouse keeps that structure. A type class that includes `Lighthouse::GraphQL::Type` is handed to
+Lighthouse: the SDL still declares the type and its fields, and the class says how
+the fields with no resolving directive resolve. A field calls the method of its
+snake_case name, when the class defines it. Fields it does not define are read off
+the object, as before, and fields with a resolving directive keep it.
+
+That makes a type that is not a model as easy to resolve as a model's: the parent
+returns any object (a Hash, a Struct, a client's response), and the type's class
+reads or computes each field from it.
+
+```graphql
+type Post {
+  title: String!
+  readingTime: ReadingTime!
+}
+
+type ReadingTime {
+  words: Int!
+  minutes(wordsPerMinute: Int = 200): Int!
+}
+```
+
+```ruby
+# app/graphql/types/post_type.rb
+module Types
+  class PostType < BaseObject
+    include Lighthouse::GraphQL::Type
+
+    def reading_time
+      { words: object.body.to_s.split.size }
+    end
+  end
+end
+
+# app/graphql/types/reading_time_type.rb
+module Types
+  class ReadingTimeType < BaseObject
+    include Lighthouse::GraphQL::Type
+
+    def minutes(words_per_minute:)
+      [(object[:words] / words_per_minute.to_f).ceil, 1].max
+    end
+  end
+end
+```
+
+`Post.title` is the model's column. `Post.readingTime` calls
+`Types::PostType#reading_time`. `ReadingTime.words` is read off the Hash it
+returns, and `ReadingTime.minutes` calls `Types::ReadingTimeType#minutes`.
+
+As in graphql-ruby, the class is instantiated per parent, so a method has:
+
+- `object`: the parent, here the post;
+- `context`: the query's context;
+- the field's arguments, as snake_case keywords, with the SDL's default when the
+  client leaves one out;
+- graphql-ruby's `dataload`, `dataload_record` and `dataload_association`, to load
+  anything beyond the parent's own columns without N+1.
+
+Wrapping directives (`@guard`, `@can*`, `@cache`) on the field run around the
+method. A method every `GraphQL::Schema::Object` has (`object`, `context`) never
+resolves a field.
+
+#### The model
+
+The type's model is the SDL's to say, as in PHP Lighthouse: a type named after its
+model needs nothing, and [`@model`](directives.md#model) maps one that is not:
+
+```graphql
+type Article @model(class: "Post") {
+  title: String!
+  headline: String!
+}
+```
+
+`Types::ArticleType`'s methods then only ever run on a `Post`: a parent of another
+class (a Hash a resolver returned by mistake, another model) is reported through
+[`on_error`](configuration.md#on_error), which raises in test, and the field
+resolves to `null`. `@model` also gives `@all`, `@find`, `@paginate`, `@create`... on
+fields returning `Article` their model, and resolves a `Post` in a union or
+interface to `Article` ([types.md](types.md#the-default)).
+
+#### Opting in
+
+The class is the type's name plus `Type`, looked up in `namespaces[:types]`
+(default `['Types']`) when the schema is built. Only a class that includes
+`Lighthouse::GraphQL::Type` counts: any other `Types::PostType`, such as the ones
+a graphql-ruby app already has, is left alone, and its methods resolve nothing.
+Include the concern in `Types::BaseObject` to hand every type class over at once.
+
+A class that includes the concern must inherit from the schema's
+`base_types[:object]` when one is given, or the schema does not build. The concern
+also hands over the classes of unions, interfaces and scalars, which pick the type
+of a union's values or coerce a scalar's: see [types.md](types.md). It is not the schema's type: it only lends its
+methods. Fields are declared in the SDL, so `field` declarations in it are ignored,
+and graphql-ruby's type-level `authorized?` does not run; authorize with
+[`@can*`](authorization.md). `Query`, `Mutation` and `Subscription` fields resolve
+with their own classes, [by convention](#resolution-by-convention), not with a type
+class.
 
 ### `@spread` and `@inject`
 
@@ -240,16 +481,14 @@ bin/rails generate lighthouse:mutation PublishPost     # app/graphql/mutations/p
 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
+bin/rails generate graphql:object Post                 # a type class: then include Lighthouse::GraphQL::Type
 ```
 
-Each one writes the class with its contract, into the first namespace configured
-for its kind (or `--namespace=…`). A resolver, mutation or subscription inherits
-from the namespace's base class, which is written first when it is missing.
-Namespaced names nest modules: `lighthouse:mutation Blog::Publish` writes
-`Mutations::Blog::Publish < BaseMutation`. These
-generators do not collide with graphql-ruby's `graphql:*` generators. A
-`lighthouse:mutation` and a `graphql:mutation` of the same name target the same
-file, and Rails asks before overwriting it.
+Each writes the class with its contract, into the first namespace configured for its
+kind (or `--namespace=…`), inheriting from the namespace's base class. Type classes
+come from graphql-ruby's own `graphql:object`, `graphql:scalar`, `graphql:union` and
+`graphql:interface`. [generators.md](generators.md) has what each generator writes,
+and which of graphql-ruby's fit a Lighthouse app.
 
 ## Changing the namespaces
 

data/docs/security.md

@@ -208,3 +208,20 @@ GraphQL::Analysis.analyze_query(query, [GraphQL::Analysis::QueryComplexity]).fir
 `QueryComplexity` logs a warning unless the schema chooses an algorithm with
 `AppSchema.complexity_cost_calculation_mode(:future)`. `max_complexity` and
 `query_complexity` always use the `:future` algorithm.
+
+## Rate limiting
+
+[`@throttle`](directives.md#throttle) caps how often one client may call a field —
+a login, a search, an expensive mutation:
+
+```graphql
+type Mutation {
+  login(email: String!, password: String!): User @throttle(maxAttempts: 5, decayMinutes: 1)
+}
+```
+
+Attempts are counted in [`cache_store`](configuration.md#cache_store), so use a store
+the app servers share (Redis, Solid Cache) in production; `:null_store` counts
+nothing. A client is the signed-in user, else the `:remote_ip` the controller concern
+puts in the context (override `graphql_context` to set another). A refused call never
+reaches `@guard` or the resolver.

data/docs/types.md

@@ -0,0 +1,219 @@
+# Unions, Interfaces and Scalars
+
+The SDL declares every type. Object types resolve their fields through
+directives, the default reader, or a [type class](resolvers.md#type-classes).
+Three more kinds need Ruby to say how their values work:
+
+- a **union** or an **interface** needs to know which object type each value is;
+- a custom **scalar** needs to know how to read its values from a query and write
+  them to a response.
+
+Lighthouse answers both as [PHP Lighthouse](https://lighthouse-php.com/master/the-basics/types.html)
+does by default, and lets you take over with a class, in graphql-ruby's
+`app/graphql/types` structure, or with a directive.
+
+## Unions and interfaces
+
+```graphql
+type Query {
+  search(term: String!): [SearchResult!]!
+  latestActivity: [Authored!]!
+}
+
+union SearchResult = Post | User
+
+interface Authored {
+  id: ID!
+  author: User!
+}
+
+type Post implements Authored { id: ID! title: String! author: User! }
+type Comment implements Authored { id: ID! body: String! author: User! }
+```
+
+A resolver returns records, of any of the types:
+
+```ruby
+class Resolvers::Search < Resolvers::BaseResolver
+  def resolve(term:)
+    Post.where('title LIKE ?', "%#{term}%").to_a + User.where('name LIKE ?', "%#{term}%").to_a
+  end
+end
+```
+
+```graphql
+{
+  search(term: "Grace") {
+    __typename
+    ... on Post { title }
+    ... on User { name }
+  }
+}
+```
+
+### The default
+
+Each value resolves to the first of these that is one of the union's (or the
+interface's) types:
+
+1. a Hash's `__typename` (`{ __typename: 'Movie', title: 'Heat' }`);
+2. the type named after the value's class (a `Post` record is a `Post`), or after
+   one of its superclasses, so an `Admin < User` STI record is a `User` when no
+   `Admin` type exists;
+3. the type whose [`@model`](directives.md#model) names the value's model. With
+   `type Article @model(class: "Post")`, a `Post` record is an `Article`.
+
+Most schemas need nothing else.
+
+### A type class
+
+When the default is not enough, say when the values are Hashes from a search
+service rather than records, write the union's class as graphql-ruby does
+(`rails g graphql:union SearchResult`),
+`Types::<Name>Type` including `Lighthouse::GraphQL::Type`, with `resolve_type`.
+It returns a type name, or a type class, which stands for the SDL type of its
+`graphql_name`:
+
+```ruby
+# app/graphql/types/search_result_type.rb
+module Types
+  class SearchResultType < BaseUnion
+    include Lighthouse::GraphQL::Type
+
+    def self.resolve_type(object, context)
+      return unless object.is_a?(Hash)
+
+      object['index'] == 'users' ? Types::UserType : 'Post'
+    end
+  end
+end
+```
+
+An interface's goes in graphql-ruby's `definition_methods`:
+
+```ruby
+# app/graphql/types/authored_type.rb
+module Types
+  module AuthoredType
+    include BaseInterface
+    include Lighthouse::GraphQL::Type
+
+    definition_methods do
+      def resolve_type(object, context)
+        object['index'] == 'comments' ? 'Comment' : 'Post' if object.is_a?(Hash)
+      end
+    end
+  end
+end
+```
+
+`nil` leaves the value to the default, so the class only handles the cases that
+need it. The SDL still declares the members: `possible_types` in the class are
+ignored.
+
+### `@union` and `@interface`
+
+PHP Lighthouse's directives name the class in the schema instead. It has
+`resolve_type(object, context)` or `call(object, context)`, and is looked up in the
+types namespace (nested names too), then as written:
+
+```graphql
+union SearchResult @union(resolveType: "SearchResultResolver") = Post | User
+interface Authored @interface(resolveType: "AuthoredResolver") { id: ID! }
+```
+
+The directive comes first, then the type class, then the default.
+
+### When nothing resolves a value
+
+A value no step resolves, or one resolved to a type the union or interface does
+not include, raises `Lighthouse::DefinitionError`. It is a server bug, not a client
+error, and the message names the ways out:
+
+```text
+Lighthouse could not tell the type of a Tag in the union SearchResult (Post | User):
+name a type after its class, map one to it with @model(class: "Tag"), or resolve
+it in Types::SearchResultType.resolve_type or with @union(resolveType:).
+```
+
+A `@union` or `@interface` naming no class, or a type class of another kind than
+its SDL type (a union class for an interface), fails when the schema is built.
+
+## Scalars
+
+```graphql
+"An ISO 8601 date and time."
+scalar DateTime
+
+type Post {
+  createdAt: DateTime!
+}
+
+type Query {
+  latestActivity(since: DateTime): [Authored!]!
+}
+```
+
+Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`,
+`Types::<Name>Type` including `Lighthouse::GraphQL::Type`:
+
+```ruby
+# app/graphql/types/date_time_type.rb
+module Types
+  class DateTimeType < BaseScalar
+    include Lighthouse::GraphQL::Type
+
+    def self.coerce_input(value, context)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      raise GraphQL::CoercionError, "#{value.inspect} is not an ISO 8601 date and time"
+    end
+
+    def self.coerce_result(value, context)
+      value.utc.iso8601
+    end
+  end
+end
+```
+
+- `coerce_input` reads an argument or variable. The resolver gets its result, here a
+  `Time`. Raising `GraphQL::CoercionError` (or returning `nil`) makes the argument
+  invalid, and the client gets the message.
+- `coerce_result` writes a value a field returns, here `Post#created_at`.
+
+`@scalar(class:)`, PHP Lighthouse's directive, names the class in the schema
+instead, looked up in the types namespace, then as written:
+
+```graphql
+scalar Money @scalar(class: "Money::GraphQLScalar")
+```
+
+A scalar with neither passes its values through unchanged. A `@scalar` naming no
+class with `coerce_input` and `coerce_result` fails when the schema is built.
+
+## Opting in, and base classes
+
+Only a class including `Lighthouse::GraphQL::Type` counts: any other
+`Types::SearchResultType` or `Types::DateTimeType`, such as the ones a graphql-ruby
+app already has, is left alone. The concern can be included in a subclass of
+`GraphQL::Schema::Object`, `Union` or `Scalar`, or in a module including
+`GraphQL::Schema::Interface`.
+
+The classes are looked up in [`namespaces[:types]`](configuration.md#namespaces)
+(default `['Types']`). When the schema's `base_types` name a base for a kind,
+graphql-ruby builds the SDL's types of that kind from it, and a type class of that
+kind must inherit from it, or the schema does not build:
+
+```ruby
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    base_types: {
+      object: Types::BaseObject,
+      union: Types::BaseUnion,
+      interface: Types::BaseInterface,
+      scalar: Types::BaseScalar
+      # resolver:, mutation:, subscription: (resolvers.md#handing-the-bases-to-the-schema)
+    }
+  }
+)
+```

data/docs/uploads.md

@@ -0,0 +1,80 @@
+# File Uploads
+
+Clients send files with the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec),
+which Apollo Upload Client, urql and most GraphQL clients speak: a multipart form with
+the operation as JSON, a map of where each file goes, and the files.
+`Lighthouse::GraphQL::Controller` reads it, so the endpoint needs nothing more.
+
+## The `Upload` scalar
+
+Declare it, and use it for arguments:
+
+```graphql
+"A file sent with a multipart request."
+scalar Upload
+
+type Mutation {
+  updateAvatar(avatar: Upload!): User! @update @inject(context: "current_user.id", name: "id")
+}
+```
+
+Lighthouse reads its values itself (`Lighthouse::GraphQL::Upload`): the resolver gets
+the uploaded file, an `ActionDispatch::Http::UploadedFile`. A value that is not a file
+makes the argument invalid. `Upload` is for arguments only, never a field's result.
+
+An ActiveStorage attachment takes the file as it is: with `has_one_attached :avatar`
+on `User`, the mutation above attaches it.
+
+## `@upload`
+
+`@upload` stores the file first, and passes along what was stored instead:
+
+```graphql
+type Mutation {
+  updateAvatar(avatar: Upload! @upload(path: "avatars")): User!
+    @guard
+    @update
+    @inject(context: "current_user.id", name: "id")
+}
+```
+
+By default the file becomes an ActiveStorage blob: on the service `disk:` names (the
+default service without it), with its key under `path:`. The argument then holds the
+blob's **signed id**, which an attachment attribute attaches (`user.avatar = signed_id`)
+and `ActiveStorage::Blob.find_signed` finds. Lists of files are stored one by one.
+
+`@upload` runs once `@guard`, the `@can*` family and `@validator` have let the call
+through, so a refused call stores nothing.
+
+To store files elsewhere, give [`upload_store`](configuration.md#upload_store) an
+object with `call(file, disk:, path:, public:)`; the argument holds what it returns:
+
+```ruby
+Lighthouse.configure do |config|
+  config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }   # returns the key
+end
+```
+
+## The request
+
+```shell
+curl localhost:3000/graphql \
+  -H 'Authorization: Bearer <token>' \
+  -F operations='{ "query": "mutation($avatar: Upload!) { updateAvatar(avatar: $avatar) { avatarUrl } }", "variables": { "avatar": null } }' \
+  -F map='{ "0": ["variables.avatar"] }' \
+  -F 0=@me.png
+```
+
+A batch sends an array as `operations`, and maps files to `"0.variables.avatar"`,
+`"1.variables.files.0"`, and so on.
+
+In a request spec:
+
+```ruby
+avatar = Rack::Test::UploadedFile.new('spec/fixtures/me.png', 'image/png')
+post '/graphql', params: {
+  operations: { query: mutation, variables: { avatar: nil } }.to_json,
+  map: { '0' => ['variables.avatar'] }.to_json,
+  '0' => avatar
+}
+```