# `AbsintheAPQ.DocumentProvider`
[🔗](https://github.com/koode/absinthe_apq/blob/v0.1.0/lib/absinthe_apq/document_provider.ex#L1)

An `Absinthe.Plug.DocumentProvider` for Apollo Automatic Persisted Queries.

Put it before `Absinthe.Plug.DocumentProvider.Default`, so requests without the
`persistedQuery` extension still work:

    forward "/graphql", Absinthe.Plug,
      schema: MyAppWeb.Schema,
      document_providers: [AbsintheAPQ.DocumentProvider, Absinthe.Plug.DocumentProvider.Default]

To pass options, give a `{module, options}` tuple, which `Absinthe.Plug` supports for
every document provider:

    document_providers: [
      {AbsintheAPQ.DocumentProvider, max_query_bytes: 65_536},
      Absinthe.Plug.DocumentProvider.Default
    ]

`Absinthe.Plug` does not validate document provider options when it starts, so this
module checks them on each request and raises an `ArgumentError` for an unknown
option. To build the options at runtime, use the `{module, function}` form of
`:document_providers`, which `Absinthe.Plug` calls with its config on every request.

## Options

  * `:cache`: the `AbsintheAPQ.Cache` module, or a `{module, options}` tuple whose
    options are passed to its callbacks. Defaults to `AbsintheAPQ.Cache.ETS`, the
    store started with its default name.
  * `:enabled`: when `false`, every request with the `persistedQuery` extension gets
    the `PersistedQueryNotSupported` error (`PERSISTED_QUERY_NOT_SUPPORTED`), which
    makes Apollo Client stop sending hashes for the rest of the session and send full
    queries instead. Use it to turn APQ off while clients still send hashes: without
    this provider, a hash-only request gets `Absinthe.Plug`'s
    "No query document supplied" error, which Apollo Client does not retry. Defaults
    to `true`.
  * `:max_query_bytes`: the largest query, in bytes, that is stored. A larger query
    with a correct hash still runs, but is not stored, so its hash-only requests keep
    missing. Defaults to `32_768`.

## What it does with a request

  * No `persistedQuery` extension: `{:cont, request}`, so the next document provider
    handles the request.
  * Hash only, stored: runs the stored query.
  * Hash only, not stored, or the cache fails: the `PersistedQueryNotFound` error
    (`extensions.code` `PERSISTED_QUERY_NOT_FOUND`). Apollo Client then sends the
    hash and the query.
  * Hash and query: when the query hashes to the hash, runs the query, and stores it
    once it has passed validation. Otherwise the error
    `provided sha does not match query` (`PERSISTED_QUERY_HASH_MISMATCH`).
  * Any `persistedQuery` extension when `enabled: false`: the
    `PersistedQueryNotSupported` error (`PERSISTED_QUERY_NOT_SUPPORTED`).
  * A `version` other than `1`: the error `Unsupported persisted query version`
    (`PERSISTED_QUERY_UNSUPPORTED_VERSION`).
  * A `sha256Hash` that is not 64 lowercase hexadecimal characters: the error
    `PERSISTED_QUERY_INVALID_HASH`.

The extensions may be a decoded map (a JSON `POST` body) or a JSON string (the
`extensions` parameter of a `GET` request).

Subscriptions over `Absinthe.Phoenix` sockets do not go through document providers,
so APQ does not apply to them.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
