graphql.proto

Package : envoy.config.filter.http.graphql.v2

Top

graphql.proto

Table of Contents

AbstractTypeResolver

CacheControl

Field Type Label Description
maxAge google.protobuf.UInt32Value number of seconds to cache result for. the max_age used for a single graphql request is the minimum of all fields requested.
default max_age rules work as follows: - root fields (i.e. Query, Mutation, Subscription) default to 0s - non-root, non-scalar fields (i.e. object, interface, or union; or a list of those types) default to 0s - all other fields inherit the max_age from their parent.
scope envoy.config.filter.http.graphql.v2.CacheControl.CacheControlScope provide controls to which users can access cached content
inheritMaxAge bool whether or not to inherit the caching configuration of any parent fields

ExecutableSchema

Field Type Label Description
schemaDefinition envoy.config.core.v3.DataSource Schema to use in string format.
executor envoy.config.filter.http.graphql.v2.Executor how to execute the schema
extensions []envoy.config.filter.http.graphql.v2.ExecutableSchema.ExtensionsEntry repeated Schema extensions
logRequestResponseInfo bool Logs request / response sensitive information By default, this is false so no request or response sensitive information is logged.

ExecutableSchema.ExtensionsEntry

Field Type Label Description
key string
value google.protobuf.Any

Executor

Field Type Label Description
local envoy.config.filter.http.graphql.v2.Executor.Local
remote envoy.config.filter.http.graphql.v2.Executor.Remote

Executor.Local

Field Type Label Description
resolutions []envoy.config.filter.http.graphql.v2.Resolution repeated The resolver map to use to resolve the schema.
enableIntrospection bool Do we enable introspection for the schema? general recommendation is to disable this for production and hence it defaults to false.
maxDepth uint32 The max amount of nesting a query can be executed against this schema. e.g. the following query has these depths: query { # Depth: 0 me { # Depth: 1 friends { # Depth: 2 friends # Depth: 3 } } } If the max_depth is set to 2, then the query at depth 3 will recieve an error as a response. By default max_depth is 0, which is unbounded query depth.

Executor.Remote

Field Type Label Description
serverUri envoy.config.core.v3.HttpUri Server URI of the remote graphql cluster.
request envoy.config.filter.http.graphql.v2.Executor.Remote.RemoteSchemaRequest
spanName string

Executor.Remote.Extraction

Field Type Label Description
value string Set the extraction type to use a static value.
header string Set the extraction type to use a header value. Specify the name of the header to extract the value from on the original request.
dynamicMetadata envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction.DynamicMetadataExtraction Set the extraction type to use a dynamic metadata value.

Executor.Remote.Extraction.DynamicMetadataExtraction

Field Type Label Description
metadataNamespace string The namespace that the dynamic metadata is stored in.
key string The key in the namespace that the dynamic metadata is stored under.

Executor.Remote.RemoteSchemaRequest

Field Type Label Description
headers []envoy.config.filter.http.graphql.v2.Executor.Remote.RemoteSchemaRequest.HeadersEntry repeated Map of headers to header value which will be included in the request to the remote graphql server.
queryParams []envoy.config.filter.http.graphql.v2.Executor.Remote.RemoteSchemaRequest.QueryParamsEntry repeated Query params to set on the request to the remote graphql server.

Executor.Remote.RemoteSchemaRequest.HeadersEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction

Executor.Remote.RemoteSchemaRequest.QueryParamsEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction

GraphQLConfig

GraphQLRouteConfig

Field Type Label Description
executableSchema envoy.config.filter.http.graphql.v2.ExecutableSchema In the future, we will support persistent queries, this will be a map of query id to query. map<string, Query> presistent_queries = 3; when we support persistent queries, we may want to use them exclusivly, for predictable operations. (i.e. no surprise mega query from a client). bool only_persistent_queries = 4;
statPrefix string The stats prefix which will be used for this route config.
persistedQueryCacheConfig envoy.config.filter.http.graphql.v2.PersistedQueryCacheConfig Configuration settings for persisted query cache
allowedQueryHashes []string repeated Safelist: only allow queries to be executed that match these sha256 hashes. The hash can be computed from the query string or provided (i.e. persisted queries).

GrpcDescriptorRegistry

Field Type Label Description
protoDescriptors envoy.config.core.v3.DataSource

GrpcRequestTemplate

Field Type Label Description
outgoingMessageJson envoy.config.filter.http.graphql.v2.JsonValue json representation of outgoing gRPC message to be sent to gRPC service
serviceName string request has shape matching service with name registered in registry is the full_name(), e.g. main.Bookstore
methodName string make request to method with this name on the grpc service defined above is just the name(), e.g. GetBook
requestMetadata []envoy.config.filter.http.graphql.v2.GrpcRequestTemplate.RequestMetadataEntry repeated in the future, we may want to make this a map<string, ValueProvider> once we know better what the use cases are

GrpcRequestTemplate.RequestMetadataEntry

Field Type Label Description
key string
value string

GrpcResolver

Field Type Label Description
serverUri envoy.config.core.v3.HttpUri
requestTransform envoy.config.filter.http.graphql.v2.GrpcRequestTemplate configuration used to compose the outgoing request to a gRPC endpoint
spanName string pre-execution engine transformations
Request flow: GraphQL request -> request_transform (instantiate gRPC request) -> gRPC API resp -> pre_execution_transform -> execution engine -> complete GraphQL field response
ResponseTemplate pre_execution_transform = 3;

JsonKeyValue

Field Type Label Description
key string PARTIALLY IMPLEMENTED if empty, the value will be parsed as json and replace the entire previously-parsed json value –> this part is only needed for gRPC and thus not implemented yet
value envoy.config.filter.http.graphql.v2.JsonValue

JsonNode

Field Type Label Description
keyValues []envoy.config.filter.http.graphql.v2.JsonKeyValue repeated if keys repeat, the latest one replaces any earlier values associated with that key.
repeated list, rather than a map, to have ordering to allow for merge semantics within the data plane, for example: - gRPC input uses special empty string for input key to set entire body - gRPC wants to replace a certain field in parsed body from GraphQL arg

JsonValue

Field Type Label Description
node envoy.config.filter.http.graphql.v2.JsonNode
valueProvider envoy.config.filter.http.graphql.v2.ValueProvider
list envoy.config.filter.http.graphql.v2.JsonValueList

JsonValueList

Field Type Label Description
values []envoy.config.filter.http.graphql.v2.JsonValue repeated

Path

Field Type Label Description
segments []envoy.config.filter.http.graphql.v2.PathSegment repeated

PathSegment

Field Type Label Description
key string This will extract a key from a Map value.
index uint32 Extract element at list
all bool Extracts all elements from a map or a list

PersistedQueryCacheConfig

Field Type Label Description
cacheSize uint32 The unit is number of queries to store, default to 1000.

QueryMatcher

Field Type Label Description
fieldMatcher envoy.config.filter.http.graphql.v2.QueryMatcher.FieldMatcher

QueryMatcher.FieldMatcher

Field Type Label Description
type string Object type. For example, Query.
field string Field within the object.

RESTResolver

Field Type Label Description
serverUri envoy.config.core.v3.HttpUri
requestTransform envoy.config.filter.http.graphql.v2.RequestTemplate configuration used to compose the outgoing request to a REST API
preExecutionTransform envoy.config.filter.http.graphql.v2.ResponseTemplate pre-execution engine transformations
Request flow: GraphQL request -> request_transform (instantiate REST request) -> REST API resp -> pre_execution_transform -> execution engine -> complete GraphQL field response
spanName string

RequestTemplate

Field Type Label Description
headers []envoy.config.filter.http.graphql.v2.RequestTemplate.HeadersEntry repeated Use this attribute to set request headers to your REST service. It consists of a map of strings to value providers. The string key determines the name of the resulting header, the value provided will be the value.
at least need “:method” and “:path”
queryParams []envoy.config.filter.http.graphql.v2.RequestTemplate.QueryParamsEntry repeated Use this attribute to set query parameters to your REST service. It consists of a map of strings to value providers. The string key determines the name of the query param, the provided value will be the value. This value is appended to any value set to the :path header in headers.
Interpolation is done in envoy rather than the control plane to prevent escaped character issues. Additionally, we may be providing values not known until the request is being executed (e.g., graphql parent info).
outgoingBody envoy.config.filter.http.graphql.v2.JsonValue implementation specific, gRPC will want gRPC message and struct to instantiate

RequestTemplate.HeadersEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.ValueProvider

RequestTemplate.QueryParamsEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.ValueProvider

Resolution

Field Type Label Description
matcher envoy.config.filter.http.graphql.v2.QueryMatcher Match an object type and field
resolver envoy.config.core.v3.TypedExtensionConfig The resolver to use
statPrefix string The stats prefix which will be used for this resolver
cacheControl envoy.config.filter.http.graphql.v2.CacheControl caching configuration, defaults to no caching

ResponseTemplate

Field Type Label Description
resultRoot []envoy.config.filter.http.graphql.v2.PathSegment repeated In cases where the data to populate the graphql type is not in the root object of the result, use result root to specify the path of the response we should use as the root. If {“a”: {“b”: [1,2,3]}} is the response from the api, setting resultroot as a.b will pass on [1,2,3] to the execution engine rather than the whole api response
setters []envoy.config.filter.http.graphql.v2.ResponseTemplate.SettersEntry repeated Example: type Query { getSimple: Simple }<br>type Simple { name String address String }
if we do getsimple and the response we get back from the upstream is {"data": { "people": { "name": "John Doe", "details": { "address": "123 Turnip Rd" } } } } the following response transform would let the graphql execution engine correctly marshal the upstream resposne into the expected graphql response: responseTransform: result_root: segments: - key: data - key: people setters: address: segments: - key: details - key: addressyaml

ResponseTemplate.SettersEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.TemplatedPath

StaticResolver

Field Type Label Description
syncResponse string Responds synchronously (on the same dispatch loop as the resolve call)
asyncResponse envoy.config.filter.http.graphql.v2.StaticResolver.AsyncResponse Responds asynchronously after delay_ms
errorResponse string Responds as an error with the given message

StaticResolver.AsyncResponse

Field Type Label Description
response string
delayMs uint32

TemplatedPath

Field Type Label Description
pathTemplate string If non-empty, Inserts named paths into a template string. For example, if the template is ‘/api/{apiVersionPath}/pet/{petIdPath}’ and we have two named paths defined in named_paths, apiVersionPath and petIdPath, with extracted values ‘v2’ and ‘123’ respectively, the final resulting value will be ‘/api/v2/pet/123’ Use {PATH_NAME} as the interpolation notation (even repeated) regardless of the type of the provided value. If an undefined PATH_NAME is used in the template, this will nack during configuration. If this is empty, only the value of the first provider will be used as the resulting value.
namedPaths []envoy.config.filter.http.graphql.v2.TemplatedPath.NamedPathsEntry repeated

TemplatedPath.NamedPathsEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.Path

ValueProvider

Field Type Label Description
providers []envoy.config.filter.http.graphql.v2.ValueProvider.ProvidersEntry repeated Map of provider name to provider definition. The name will be used to insert the provider value in the provider_template.
providerTemplate string If non-empty, Inserts named providers into a template string. For example, if the provider_template is ‘/api/{apiVersionProvider}/pet/{petIdProvider}’ and we have two named providers defined in providers, apiVersionProvider and petIdProvider, with extracted values ‘v2’ and ‘123’ respectively, the final resulting value will be ‘/api/v2/pet/123’ Use {PROVIDER_NAME} as the interpolation notation (even repeated) regardless of the type of the provided value. If an undefined PROVIDER_NAME is used in the provider_template, this will nack during configuration. If this is empty, only the value of the first provider will be used as the resulting value.

ValueProvider.GraphQLArgExtraction

Field Type Label Description
argName string The argument name to fetch. The argument value fetched will have a type from the schema that we validate in envoy. If the name is invalid, returns the zero-value primitive or null.
path []envoy.config.filter.http.graphql.v2.PathSegment repeated Optional: fetches the value in the argument selected at this key. If the key is invalid, returns the zero-value primitive or null.
If this is set to true, then a schema error will be returned to user when the graphql arg is not found. Defaults to false, so schema error will not be returned to user when the graphql arg is not found. bool required = 3;

ValueProvider.GraphQLParentExtraction

Field Type Label Description
path []envoy.config.filter.http.graphql.v2.PathSegment repeated Fetches the value in the graphql parent at this key. The value will always be accepted since the parent object is not strongly-typed. If the key is invalid, returns null.

ValueProvider.Provider

Field Type Label Description
graphqlArg envoy.config.filter.http.graphql.v2.ValueProvider.GraphQLArgExtraction type inferred from schema, no need to provide it.
typedProvider envoy.config.filter.http.graphql.v2.ValueProvider.TypedValueProvider
graphqlParent envoy.config.filter.http.graphql.v2.ValueProvider.GraphQLParentExtraction Fetch value from the graphql_parent of the current field.

ValueProvider.ProvidersEntry

Field Type Label Description
key string
value envoy.config.filter.http.graphql.v2.ValueProvider.Provider

ValueProvider.TypedValueProvider

Field Type Label Description
type envoy.config.filter.http.graphql.v2.ValueProvider.TypedValueProvider.Type Type that the value will be coerced into. For example if the extracted value is “9”, and type is INT, this value will be cast to an int type.
header string Fetches the request/response header's value. If not found, uses empty string
value string inline value, use as provided rather than extracting from another source

CacheControl.CacheControlScope

Name Number Description
UNSET 0
PUBLIC 1 Responses for requests with Authorization header fields must not be stored in a shared cache. But the public directive will cause such responses to be stored in a shared cache.
In general, when pages are under Basic Auth or Digest Auth, the browser sends requests with the Authorization header. That means the response is access-controlled for restricted users (who have accounts), and it's fundamentally not shared-cacheable, even if it has max-age.
You can use the public directive to unlock that restriction.
PRIVATE 2 You should add the private directive for user-personalized content — in particular, responses received after login, and sessions managed via cookies.
If you forget to add private to a response with personalized content, then that response can be stored in a shared cache and end up being reused for multiple users, which can cause personal information to leak.

ValueProvider.TypedValueProvider.Type

Name Number Description
STRING 0
INT 1
FLOAT 2
BOOLEAN 3