AbsintheAPQ (absinthe_apq v0.1.0)

Copy Markdown View Source

Apollo Automatic Persisted Queries (APQ) for Absinthe and Absinthe.Plug.

A client sends the SHA-256 hash of a query instead of the query text. When the server knows the hash, it runs the stored query. When it does not, it answers with a PersistedQueryNotFound error, and the client sends the hash and the query text once, so the server can store them.

The parts:

The rules the library follows, with their sources, are in the protocol notes.

Telemetry

Every event name starts with :absinthe_apq. The metadata of every event has the :hash that the request sent, except [:absinthe_apq, :invalid_request], whose hash may be missing or malformed, and [:absinthe_apq, :not_supported].

  • [:absinthe_apq, :hit]: a hash-only request found its query in the cache. Measurements: %{query_bytes: integer}.
  • [:absinthe_apq, :miss]: a hash-only request did not find its query, and gets the PersistedQueryNotFound error. Measurements: %{}.
  • [:absinthe_apq, :store]: a query and its hash were stored, after the query passed validation. Measurements: %{query_bytes: integer}.
  • [:absinthe_apq, :hash_mismatch]: the query text does not hash to the hash the request sent. Measurements: %{query_bytes: integer}.
  • [:absinthe_apq, :query_too_large]: the query is larger than :max_query_bytes, so it runs but is not stored. Measurements: %{query_bytes: integer}. Metadata also has :max_query_bytes.
  • [:absinthe_apq, :invalid_request]: the persistedQuery extension has an unsupported version or a malformed hash. Measurements: %{}. Metadata: %{reason: :unsupported_version | :invalid_hash}.
  • [:absinthe_apq, :not_supported]: the provider runs with enabled: false, and the request gets the PersistedQueryNotSupported error. Measurements: %{}.
  • [:absinthe_apq, :cache_error]: the cache returned an error, or an entry whose query does not hash to its key. Measurements: %{}. Metadata also has :operation (:get or :put) and :reason: the error the cache returned, {:exception, exception}, {:exit, reason}, {:throw, value}, {:invalid_return, value}, or :stored_query_hash_mismatch. A failed :get answers the request with PersistedQueryNotFound; a failed :put still runs the query.

Summary

Functions

An Absinthe.Plug :before_send hook for the HTTP side of APQ errors.

Returns the SHA-256 hash of query as 64 lowercase hexadecimal characters.

Functions

before_send(conn, blueprint)

@spec before_send(Plug.Conn.t(), Absinthe.Blueprint.t()) :: Plug.Conn.t()

An Absinthe.Plug :before_send hook for the HTTP side of APQ errors.

Absinthe.Plug sends every executed result with status 200, and a document provider cannot reach the connection. Add this hook to answer APQ errors the way Apollo Server and Apollo Router do:

  • every APQ error gets cache-control: private, no-cache, must-revalidate, so a CDN does not keep a PersistedQueryNotFound answer for a hash that is stored a moment later;
  • a hash mismatch, an unsupported version and a malformed hash get status 400. PersistedQueryNotFound and PersistedQueryNotSupported keep status 200, which the protocol requires.

In a batched request the status stays 200, because the other results in the batch are not errors.

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

If you already have a :before_send hook, call this function from it.

hash(query)

@spec hash(String.t()) :: String.t()

Returns the SHA-256 hash of query as 64 lowercase hexadecimal characters.

This is the hash an APQ client sends in extensions.persistedQuery.sha256Hash.

iex> AbsintheAPQ.hash("{__typename}")
"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"