GraphQL Proxy Caching Advanced

This plugin provides a reverse GraphQL proxy cache implementation for Kong. It caches response entities based on configuration. It can cache by GraphQL query or vary headers. Cache entities are stored for a configurable period of time, after which subsequent requests to the same resource will re-fetch and re-store the resource. Cache entities can also be forcefully purged via the Admin API prior to their expiration time.

Terminology

• plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
• Service: the Kong entity representing an external upstream API or microservice.
• Route: the Kong entity representing a way to map downstream requests to upstream services.
• upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

Enabling the plugin on a Service

With a database

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=graphql-proxy-cache-advanced"  \
    --data "config.strategy=memory"

Without a database

Configure this plugin on a Service by adding this section do your declarative configuration file:

plugins:
- name: graphql-proxy-cache-advanced
  service: {service}
  config: 
    strategy: memory

In both cases, {service} is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

With a database

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=graphql-proxy-cache-advanced"  \
    --data "config.strategy=memory"

Without a database

Configure this plugin on a Route by adding this section do your declarative configuration file:

plugins:
- name: graphql-proxy-cache-advanced
  route: {route}
  config: 
    strategy: memory

In both cases, {route} is the id or name of the Route that this plugin configuration will target.

Global plugins

• Using a database, all plugins can be configured using the http://kong:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Strategies

GraphQL Proxy Caching Advanced Plugin is designed to support storing GraphQL proxy cache data in different backend formats. Currently the following strategies are provided:

• memory: A lua_shared_dict. Note that the default dictionary, kong_cache, is also used by other plugins and elements of Kong to store unrelated database cache entities. Using this dictionary is an easy way to bootstrap the graphql-proxy-cache-advanced plugin, but it is not recommended for large-scale installations as significant usage will put pressure on other facets of Kong’s database caching operations. It is recommended to define a separate lua_shared_dict via a custom Nginx template at this time.

Cache Key

Kong keys each cache elements based on the GraphQL query that is being send in the HTTP request body. Internally, cache keys are represented as a hexadecimal-encoded MD5 sum of the concatenation of the constituent parts.

key = md5(UUID | headers | body)

Where headers contains the headers defined in vary_headers. vary_headers defaults to NONE.

Kong will return the cache key associated with a given request as the X-Cache-Key response header.

Cache Status

Kong identifies the status of the 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 could not satisfy the request, due to Cache-Control behaviors or reaching its hard-coded cache_ttl threshold.
• Bypass: The request could not be satisfied from cache based on plugin configuration.

Admin API

This plugin provides several endpoints to managed cache entities. These endpoints are assigned to the graphql-proxy-cache-advanced resource.

The following endpoints are provided on the Admin API to examine and purge cache entities:

Retrieve a Cache Entity

Two separate endpoints are available: one to look up a known plugin instance, and another that searches all graphql-proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.

Endpoint

Endpoint

Response

If the cache entity exists

HTTP 200 OK

If the entity with the given key does not exist

HTTP 400 Not Found

Delete Cache Entity

Two separate endpoints are available: one to look up a known plugin instance, and another that searches all graphql-proxy-cache-advanced plugins data stores for the given cache key. Both endpoints have the same return value.

Endpoint

Endpoint

Response

If the cache entity exists

HTTP 204 No Content

If the entity with the given key does not exist

HTTP 400 Not Found

Purge All Cache Entities

Endpoint

Response

HTTP 204 No Content

Note that this endpoint purges all cache entities across all graphql-proxy-cache-advanced plugins.