– GraphQL Conductor

Trusted Documents

This plugin allows you to define a list of trusted GraphQL documents that can be executed by the gateway (also called Persisted Operations).

For additional information, please refer to Trusted Documents.

Configuration

Examples

This example is using a local file called trusted_documents.json as a store, using the Key->Value map format. The protocol exposed is based on HTTP POST, using the documentId parameter from the request body.

YAML

type: "trusted_documents"
enabled: true
config:
  protocols:
    - type: "document_id"
      field_name: "documentId"
  store:
    source: "file"
    path: "trusted_documents.json"
    format: "json_key_value"

JSON

{
  "type": "trusted_documents",
  "enabled": true,
  "config": {
    "protocols": [
      {
        "type": "document_id",
        "field_name": "documentId"
      }
    ],
    "store": {
      "source": "file",
      "path": "trusted_documents.json",
      "format": "json_key_value"
    }
  }
}

Reference

allow_untrusted

boolean

optional

By default, this plugin does not allow untrusted operations to be executed. This is a security measure to prevent accidental exposure of operations that are not persisted.

protocols

array

required

A list of protocols to be exposed by this plugin. Each protocol defines how to obtain the document ID from the incoming request. You can specify multiple kinds of protocols, if needed.

The following options are valid for this field:

apollo_manifest_extensions

This protocol is based on Apollo's Persisted Query Extensions. The GraphQL operation key is sent over POST and contains extensions field with the GraphQL document hash.

Example: POST /graphql {"extensions": {"persistedQuery": {"version": 1, "sha256Hash": "123"}}

type

literal: apollo_manifest_extensions

required

document_id

This protocol is based on a POST request with a JSON body containing a field with the document ID. By default, the field name is documentId.

Example: POST /graphql {"documentId": "123", "variables": {"code": "AF"}, "operationName": "test"}

field_name

string

default: "documentId"

The name of the JSON field containing the document ID in the incoming request.

type

literal: document_id

required

http_get

This protocol is based on a HTTP GET request. You can customize where to fetch each one of the parameters from. Each request parameter can be obtained from a different source: query, path, or header. By defualt, all parameters are obtained from the query string.

Unlike other protocols, this protocol does not support sending GraphQL mutations.

Example: GET /graphql?documentId=123&variables=%7B%22code%22%3A%22AF%22%7D&operationName=test

document_id_from

default:

{
  "source": "search_query",
  "name": "documentId"
}

Instructions for fetching the document ID parameter from the incoming HTTP request.

The following options are valid for this field:

search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

name

string

required

The name of the HTTP query parameter.

source

literal: search_query

required

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

position

integer

required

The numeric value specific the location of the argument (starting from 0).

source

literal: path

required

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

name

string

required

The name of the HTTP header.

source

literal: header

required

operation_name_from

default:

{
  "source": "search_query",
  "name": "operationName"
}

Instructions for fetching the operationName parameter from the incoming HTTP request.

The following options are valid for this field:

search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

name

string

required

The name of the HTTP query parameter.

source

literal: search_query

required

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

position

integer

required

The numeric value specific the location of the argument (starting from 0).

source

literal: path

required

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

name

string

required

The name of the HTTP header.

source

literal: header

required

type

literal: http_get

required

variables_from

default:

{
  "source": "search_query",
  "name": "variables"
}

Instructions for fetching the variables parameter from the incoming HTTP request. GraphQL variables must be passed as a JSON-encoded string.

The following options are valid for this field:

search_query

Instructs the plugin to extract this parameter from the query string of the HTTP request.

name

string

required

The name of the HTTP query parameter.

source

literal: search_query

required

path

Instructs the plugin to extract this parameter from the path of the HTTP request.

position

integer

required

The numeric value specific the location of the argument (starting from 0).

source

literal: path

required

header

Instructs the plugin to extract this parameter from a header in the HTTP request.

name

string

required

The name of the HTTP header.

source

literal: header

required

store

required

The store defines the source of trusted documents. The store contents is a list of hashes and GraphQL documents that are allowed to be executed.

The following options are valid for this field:

file

File-based store configuration. The path specified is relative to the location of the root configuration file. The file contents are loaded into memory on startup. The file is not reloaded automatically. The file format is specified by the format field, based on the structure of your file.

format

required

The format and the expected structure of the loaded store file.

The following options are valid for this field:

apollo_persisted_query_manifest

JSON file formated based on Apollo Persisted Query Manifest.

json_key_value

A simple JSON map of key-value pairs.

Example: {"key1": "query { __typename }"}

path

string

required

A path to a local file on the file-system. Relative to the location of the root configuration file.

source

literal: file

required

Disable Introspection HTTP GET