GraphQL Proxy Caching Advanced

The GrapQL Proxy Cache Advanced plugin provides a reverse GraphQL proxy cache implementation for Kong Gateway. It caches response entities by GraphQL query or Vary headers.

The GraphQL Proxy Caching Advanced plugin stores cache data in one of two ways, defined via the config.strategy parameter:

• redis: A Redis database.

• memory: A shared dictionary defined in config.memory.dictionary_name.

  The default dictionary, kong_db_cache, is also used by other plugins and elements of Kong Gateway to store unrelated database cache entities. Using the kong_db_cache dictionary is an easy way to bootstrap and test the plugin, but we don’t recommend using it for large-scale installations as significant usage will put pressure on other facets of Kong Gateway’s database caching operations. In production, we recommend defining a custom lua_shared_dict via a custom Nginx template.

Cache entities are stored for a configurable period of time, after which subsequent requests to the same resource will fetch and store the resource again.

In Traditional mode, cache entities can also be forcefully purged via the Admin API prior to their expiration time.

In serverless gateways, only the memory strategy is supported.

Cache key

Kong Gateway assigns a key to each cache element based on the GraphQL query sent in the HTTP request body. It returns the cache key associated with a given request in the X-Cache-Key response header.

Internally, cache keys are represented as a hexadecimal-encoded MD5 sum of the concatenation of the constituent parts:

key = md5(UUID | headers | body)

headers contains the headers defined in config.vary_headers, which defaults to none.

Cache status

Kong Gateway identifies the status of a request’s proxy cache behavior via the X-Cache-Status header. There are several possible values for this header:

• Miss: The request could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.
• Hit: The request was satisfied and served from cache.
• Refresh: The resource was found in cache, but couldn’t satisfy the request, due to Cache-Control behaviors or from reaching its hardcoded config.cache_ttl threshold.
• Bypass: The request couldn’t be satisfied from cache based on plugin configuration.

The GraphQL Proxy Caching Advanced plugin exposes several /graphql-proxy-cache-advanced endpoints for cache management through the Kong Admin API.

You can use the Admin API to:

• Look up cache entities
• Delete cache entities
• Purge all caches

To access these endpoints, enable the plugin first. The GraphQL Proxy Caching Advanced caching endpoints will appear once the plugin has been enabled.

This plugin’s API endpoints are not available in hybrid mode. The data that this API targets is located on the Data Planes, and Data Planes can’t use the Kong Admin API.