@graphql-ez/plugin-automatic-persisted-queries#

This plugin implements configurable Apollo style Automatic Persisted Queries, with compatibility for apollo-client.

https://www.apollographql.com/docs/apollo-server/performance/apq/

Usage#

import { ezAutomaticPersistedQueries } from '@graphql-ez/plugin-automatic-persisted-queries'; const ezApp = CreateApp({ ez: { plugins: [ // ... ezAutomaticPersistedQueries({ // options }), ], }, // ... });

We provide reasonable defaults for all options, and the implementation is compatible with apollo-client without additional configuration.

Options#

export interface AutomaticPersistedQueryOptions { /** * The query hash algorithm */ hashAlgorithm?: HashAlgorithm; /** * The protocol version */ version?: number; /** * Retrieve the persisted query data from a request. */ resolvePersistedQuery?: (opts: Readonly<ProcessRequestOptions>) => PersistedQuery | undefined; /** * Specify whether the persisted queries should be disabled for the current request. By default all requests * following the APQ protocol are accepted. If false is returned, a PersistedQueryNotSupportedError is * sent to the client. */ disableIf?: (context: DisableContext) => boolean; /** * Storage for persisted queries. */ store?: PersistedQueryStore; }

resolvePersistedQuery(opts: ReadOnly<ProcessRequestOptions>): PersistedQuery | undefined#

If you wish to customize the extension extraction from your HTTP request, override this function. If resolvePersistedQuery is not set, the default behavior is to look for thepersistedQuery extension in the request body.

Advanced usage only

disableIf(context: DisableContext): boolean#

Disable the plugin per request based on context. If this function returns true, the client should switch to making normal non-persistent calls, per protocol.

Example#

// Disable if we have issues connecting to the backend store. import { PersistedQueryStore, ezAutomaticPersistedQueries } from '@graphql-ez/plugin-automatic-persisted-queries'; import IORedis from 'ioredis'; const HASH_KEY = 'apq-store'; const redis = new IORedis(); let isDisabled = true; redis.on('connect', () => { isDisabled = false; }); redis.on('close', () => { isDisabled = true; }); redis.on('error', () => { isDisabled = true; }); export const store: PersistedQueryStore = { set: async (key, query) => { await redis.hset(HASH_KEY, key, query); }, get: async key => { const [err, val] = await redis.hget(HASH_KEY, key); if (err) throw err; return val; }, clear: async () => { await redis.del(HASH_KEY); }, }; const ezApp = CreateApp({ ez: { plugins: [ // ... ezAutomaticPersistedQueries({ store, disbleIf: () => isDisabled, }), ], }, // ... });

store#

The store that maps query hashes to query documents. If unspecified, we provide an in-memory LRU cache capped at 1000 elements with a ttl of an hour to prevent DoS attacks on the storage of hashes & queries.

Here's an example of a naive, unbounded in-memory store:

import { PersistedQueryStore } from '@graphql-ez/plugin-automatic-persisted-queries'; // You can implement `data` in any custom way, and even fetch it from a remote store. const data = new Map<string, string>(); export const myStore: PersistedQueryStore = { put: async (key, query) => { data.set(key, query); }, get: async key => data.get(key), clear: () => { data.clear(); }, };

You can use the utility function createLRUStore to create a cache for your own purposes.

import { PersistedQueryStore, createLRUStore } from '@graphql-ez/plugin-automatic-persisted-queries'; /** Create an LRU based store with a max of 100 items and a ttl of 1 minute */ const smallStore = createLRUStore(100, 60000);

hashAlgorithm#

The algorithm used to hash query text. Possible values are sha256, sha512, sha1, md5.

Default sha256

version#

The current protocol version. The version field of the persistedQuery extension must match this value, otherwise an error with message PersistedQueryInvalidVersion will be raised.

Default: 1