AbsintheAPQ.DocumentProvider (absinthe_apq v0.1.0)

Copy Markdown View Source

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.