Persisted Operations | GraphQL Yoga v3

GraphQL Yoga v3 documentation (superseded by v5): Persisted operations is a mechanism for preventing the execution of arbitrary GraphQL operation documents.

Persisted operations is a mechanism for preventing the execution of arbitrary GraphQL operation documents. By default, the persisted operations plugin follows the the APQ Specification for SENDING hashes to the server.

However, you can customize the protocol to comply to other implementations e.g. used by Relay persisted queries.

change this behavior by overriding the getPersistedOperationKey option to support Relay’s specification for example.

Quick Start

Persisted operations requires installing a separate package.

npm i @graphql-yoga/plugin-persisted-operations

yarn add @graphql-yoga/plugin-persisted-operations

pnpm add @graphql-yoga/plugin-persisted-operations

bun add @graphql-yoga/plugin-persisted-operations

Persisted operation setup

import { createServer } from 'node:http'
import { createSchema, createYoga } from 'graphql-yoga'
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations'

const store = {
  ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38: '{__typename}'
}

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String!
      }
    `
  }),
  plugins: [
    usePersistedOperations({
      getPersistedOperation(sha256Hash: string) {
        return store[sha256Hash]
      }
    })
  ]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Start your yoga server and send the following request.

Execute persisted GraphQL operation

curl -X POST -H 'Content-Type: application/json' http://localhost:4000/graphql \
  -d '{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}}'

{"data":{"__typename":"Query"}}

As you can see, the persisted operations plugin is able to execute the operation without the need to send the full operation document.

If you now sent a normal GraphQL operation that is not within the store, it will be rejected.

Arbitary GraphQL operation

curl -X POST -H 'Content-Type: application/json' http://localhost:4000/graphql \
  -d '{"query": "{__typename}"}'

{"errors":[{"message":"PersistedQueryOnly"}]}

Extracting client operations

The recommended way of extracting the persisted operations from your client is to use GraphQL Code Generator.

For people not using the client-preset the is also the standalone graphql-codegen-persisted-query-ids plugin for extracting a map of persisted query ids and their corresponding GraphQL documents from your application/client-code in a JSON file.

Example map extracted by GraphQL Code Generator

{
  "ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38": "{__typename}",
  "c7a30a69b731d1af42a4ba02f2fa7a5771b6c44dcafb7c3e5fa4232c012bf5e7": "mutation {__typename}"
}

This map can then be used to persist the GraphQL documents in the server.

Use JSON file from filesystem as the persisted operation store

import { readFileSync } from 'node:fs'
import { createServer } from 'node:http'
import { createSchema, createYoga } from 'graphql-yoga'
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations'

const persistedOperations = JSON.parse(readFileSync('./persistedOperations.json', 'utf-8'))

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String!
      }
    `
  }),
  plugins: [
    usePersistedOperations({
      getPersistedOperation(key: string) {
        return persistedOperations[key]
      }
    })
  ]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Sending the hash from the client

The persisted operations plugin follows the the APQ Specification of Apollo for SENDING hashes to the server.

GraphQL clients such Apollo Client and Urql support that out of the box. Check the corresponding documentation for more information.

Using parsed GraphQL documents as AST

You can reduce the amount of work the server has to do by using the parsed GraphQL documents as AST.

Use parsed GraphQL documents as AST

import { parse } from 'graphql'
import {
  PersistedOperationType,
  usePersistedOperations
} from '@graphql-yoga/plugin-persisted-operations'

const persistedOperations = {
  'my-key': parse(/* GraphQL */ `
    query {
      __typename
    }
  `)
}

const plugin = usePersistedOperations({
  getPersistedOperation(key: string) {
    return persistedOperations[key]
  }
})

Skipping validation of persisted operations

If you validate your persisted operations while building your store, we recommend to skip the validation on the server. So this will reduce the work done by the server and the latency of the requests.

Validate persisted operations

const plugin = usePersistedOperations({
  //...
  skipDocumentValidation: true
})

Using AST and skipping validations will reduce the amount of work the server has to do, so the requests will have less latency.

Allowing arbitrary GraphQL operations

Sometimes it is handy to allow non-persisted operations aside from the persisted ones. E.g. you want to allow developers to execute arbitrary GraphQL operations on your production server.

This can be achieved using the allowArbitraryOperations option.

Allow arbitrary GraphQL operations

const plugin = usePersistedOperations({
  allowArbitraryOperations: request =>
    request.headers.request.headers.get('x-allow-arbitrary-operations') === 'true'
})

Use this option with caution!

Using Relay’s Persisted Queries Specification

If you are using Relay’s Persisted Queries specification, you can configure the plugin like below;

Relay Persisted Queries example

import { createYoga, createSchema } from 'graphql-yoga'
import { createServer } from 'node:http'
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations'

const store = {
  ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38:
    '{__typename}'
}

const yoga = createYoga({
    schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String!
      }
    `
  }),
  plugins: [
    usePersistedOperations({
      extractPersistedOperationId(params: GraphqlParams & { doc_id?: unknown }) {
        return typeof params.doc_id === 'string' ? params.doc_id : null
      }
      getPersistedOperation(key: string) {
        return store[key]
      },
    }),
  ],
})

const server = createServer(yoga)
server.listen(4000, () => {
    console.info('Server is running on http://localhost:4000/graphql')
})

Using an external Persisted Operation Store

As a project grows the amount of GraphQL Clients and GraphQL Operations can grow a lot. At some point it might become impractible to store all persisted operations in memory.

In such a scenario you can use an external persisted operation store.

You can return a Promise from the getPersistedOperation function and call any database or external service to retrieve the persisted operation.

Use external persisted operation store

import { createServer } from 'node:http'
import { createYoga } from 'graphql-yoga'
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations'

const yoga = createYoga({
  plugins: [
    usePersistedOperations({
      async getPersistedOperation(key: string) {
        return await fetch(`https://localhost:9999/document/${key}`).then(res => res.json())
      }
    })
  ]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Customize errors

This plugin can throw three different types of errors::

PersistedOperationNotFound: The persisted operation cannot be found.
PersistedOperationKeyNotFound: The persistence key cannot be extracted from the request.
PersistedOperationOnly: An arbitrary operation is rejected because only persisted operations are allowed.

Each error can be customized to change the HTTP status or add a translation message ID, for example.

Customize errors

import { createServer } from 'node:http'
import { createYoga } from 'graphql-yoga'
import { usePersistedOperations } from '@graphql-yoga/plugin-persisted-operations'
import { CustomErrorClass } from './custom-error-class'

const yoga = createYoga({
  plugins: [
    usePersistedOperations({
      customErrors: {
        // You can change the error message
        notFound: 'Not Found',
        // Or customize the error with a GraphqlError options object, allowing you to add extensions
        keyNotFound: {
          message: 'Key Not Found',
          extensions: {
            http: {
              status: 404
            }
          }
        },
        // Or customize with a factory function allowing you to use your own error class or format
        persistedQueryOnly: () => {
          return new CustomErrorClass('Only Persisted Operations are allowed')
        }
      }
    })
  ]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})