graphql.proto

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

Types:

Source File: github.com/solo-io/gloo/projects/gloo/api/external/envoy/extensions/graphql/graphql.proto

PathSegment

used to reference into json structures by key(s)

"key": string
"index": int
"all": bool

Field Type Description
key string This will extract a key from a Map value. Only one of key, index, or all can be set.
index int Extract element at list. Only one of index, key, or all can be set.
all bool Extracts all elements from a map or a list. Only one of all, key, or index can be set.

Path

"segments": []envoy.config.filter.http.graphql.v2.PathSegment

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

TemplatedPath

"pathTemplate": string
"namedPaths": map<string, .envoy.config.filter.http.graphql.v2.Path>

Field Type 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 map<string, .envoy.config.filter.http.graphql.v2.Path>

ValueProvider

In the future we may add support for regex and subgroups

"providers": map<string, .envoy.config.filter.http.graphql.v2.ValueProvider.Provider>
"providerTemplate": string

Field Type Description
providers map<string, .envoy.config.filter.http.graphql.v2.ValueProvider.Provider> 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.

GraphQLArgExtraction

"argName": string
"path": []envoy.config.filter.http.graphql.v2.PathSegment

Field Type 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 Optional: fetches the value in the argument selected at this key. If the key is invalid, returns the zero-value primitive or null.

GraphQLParentExtraction

Does not do type coercion, but instead if the type does not match the expected primitive type we throw an error. In the future we may add support for type coercion.

"path": []envoy.config.filter.http.graphql.v2.PathSegment

Field Type Description
path []envoy.config.filter.http.graphql.v2.PathSegment 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.

TypedValueProvider

"type": .envoy.config.filter.http.graphql.v2.ValueProvider.TypedValueProvider.Type
"header": string
"value": string

Field Type 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. Only one of header or value can be set.
value string inline value, use as provided rather than extracting from another source. Only one of value or header can be set.

Type

if empty, defaults to string. similar to typeUrl in other envoy config

Name Description
STRING
INT
FLOAT
BOOLEAN

Provider

"graphqlArg": .envoy.config.filter.http.graphql.v2.ValueProvider.GraphQLArgExtraction
"typedProvider": .envoy.config.filter.http.graphql.v2.ValueProvider.TypedValueProvider
"graphqlParent": .envoy.config.filter.http.graphql.v2.ValueProvider.GraphQLParentExtraction

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

JsonValueList

"values": []envoy.config.filter.http.graphql.v2.JsonValue

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

JsonValue

"node": .envoy.config.filter.http.graphql.v2.JsonNode
"valueProvider": .envoy.config.filter.http.graphql.v2.ValueProvider
"list": .envoy.config.filter.http.graphql.v2.JsonValueList

Field Type Description
node .envoy.config.filter.http.graphql.v2.JsonNode Only one of node, valueProvider, or list can be set.
valueProvider .envoy.config.filter.http.graphql.v2.ValueProvider Only one of valueProvider, node, or list can be set.
list .envoy.config.filter.http.graphql.v2.JsonValueList Only one of list, node, or valueProvider can be set.

JsonKeyValue

"key": string
"value": .envoy.config.filter.http.graphql.v2.JsonValue

Field Type 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

Represents a typed JSON structure

"keyValues": []envoy.config.filter.http.graphql.v2.JsonKeyValue

Field Type Description
keyValues []envoy.config.filter.http.graphql.v2.JsonKeyValue 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.

RequestTemplate

Defines a configuration for generating outgoing requests for a resolver.

"headers": map<string, .envoy.config.filter.http.graphql.v2.ValueProvider>
"queryParams": map<string, .envoy.config.filter.http.graphql.v2.ValueProvider>
"outgoingBody": .envoy.config.filter.http.graphql.v2.JsonValue

Field Type Description
headers map<string, .envoy.config.filter.http.graphql.v2.ValueProvider> 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 map<string, .envoy.config.filter.http.graphql.v2.ValueProvider> 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.

ResponseTemplate

Defines a response transformation template. modify JSON response from upstream before it is processed by execution engine.

"resultRoot": []envoy.config.filter.http.graphql.v2.PathSegment
"setters": map<string, .envoy.config.filter.http.graphql.v2.TemplatedPath>

Field Type Description
resultRoot []envoy.config.filter.http.graphql.v2.PathSegment 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 map<string, .envoy.config.filter.http.graphql.v2.TemplatedPath> Example: type Query { getSimple: Simple } 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.

RESTResolver

"serverUri": .solo.io.envoy.config.core.v3.HttpUri
"requestTransform": .envoy.config.filter.http.graphql.v2.RequestTemplate
"preExecutionTransform": .envoy.config.filter.http.graphql.v2.ResponseTemplate
"spanName": string

Field Type Description
serverUri .solo.io.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

GrpcRequestTemplate

Defines a configuration for generating outgoing requests for a resolver.

"outgoingMessageJson": .envoy.config.filter.http.graphql.v2.JsonValue
"serviceName": string
"methodName": string
"requestMetadata": map<string, string>

Field Type 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 map<string, string> in the future, we may want to make this a map<string, ValueProvider> once we know better what the use cases are.

GrpcDescriptorRegistry

Defines a configuration for serializing and deserializing requests for a gRPC resolver. Is a Schema Extension

"protoDescriptors": .solo.io.envoy.config.core.v3.DataSource

Field Type Description
protoDescriptors .solo.io.envoy.config.core.v3.DataSource

GrpcResolver

"serverUri": .solo.io.envoy.config.core.v3.HttpUri
"requestTransform": .envoy.config.filter.http.graphql.v2.GrpcRequestTemplate
"spanName": string

Field Type Description
serverUri .solo.io.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;.

StaticResolver

Only meant for integration testing

"syncResponse": string
"asyncResponse": .envoy.config.filter.http.graphql.v2.StaticResolver.AsyncResponse
"errorResponse": string

Field Type Description
syncResponse string Responds synchronously (on the same dispatch loop as the resolve call). Only one of syncResponse, asyncResponse, or errorResponse can be set.
asyncResponse .envoy.config.filter.http.graphql.v2.StaticResolver.AsyncResponse Responds asynchronously after delay_ms. Only one of asyncResponse, syncResponse, or errorResponse can be set.
errorResponse string Only one of errorResponse, syncResponse, or asyncResponse can be set.

AsyncResponse

"response": string
"delayMs": int

Field Type Description
response string
delayMs int

AbstractTypeResolver

NOT IMPLEMENTED Resolve an abstract type (union or interface) to a real type. When implemented, this message will be a field in the Resolution message.


Field Type Description

QueryMatcher

"fieldMatcher": .envoy.config.filter.http.graphql.v2.QueryMatcher.FieldMatcher

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

FieldMatcher

"type": string
"field": string

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

Resolution

This is the resolver map for the schema. For each Type.Field, we can define a resolver. if a field does not have resolver, the default resolver will be used. the default resolver takes the field with the same name from the parent, and uses that value to resolve the field. if a field with the same name does not exist in the parent, null will be used.

"matcher": .envoy.config.filter.http.graphql.v2.QueryMatcher
"resolver": .solo.io.envoy.config.core.v3.TypedExtensionConfig
"statPrefix": string
"cacheControl": .envoy.config.filter.http.graphql.v2.CacheControl

Field Type Description
matcher .envoy.config.filter.http.graphql.v2.QueryMatcher Match an object type and field.
resolver .solo.io.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.

CacheControl

Resolvers for scalar, non-root fields rarely fetch data and instead usually populate data via the parent argument. Consequently, these fields inherit their default maxAge from their parent to reduce schema clutter.

TODO: Talk with product – apollo does not do this, but we could factor in upstream Cache-Control header response into our inheritance model.

"maxAge": .google.protobuf.UInt32Value
"scope": .envoy.config.filter.http.graphql.v2.CacheControl.CacheControlScope
"inheritMaxAge": bool

Field Type 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.

CacheControlScope

Name Description
UNSET
PUBLIC 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 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.

GraphQLConfig

Filter Listener config. Empty as the filter must be configured on the route level.


Field Type Description

GraphQLRouteConfig

Filter Route config. Routes that have this config will execute graphql queries, and will not make it to the router filter. i.e. this filter will terminate the request for these routes.

"executableSchema": .envoy.config.filter.http.graphql.v2.ExecutableSchema
"statPrefix": string
"persistedQueryCacheConfig": .envoy.config.filter.http.graphql.v2.PersistedQueryCacheConfig
"allowedQueryHashes": []string

Field Type Description
executableSchema .envoy.config.filter.http.graphql.v2.ExecutableSchema
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 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).

PersistedQueryCacheConfig

This message specifies Persisted Query Cache configuration.

"cacheSize": int

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

ExecutableSchema

"schemaDefinition": .solo.io.envoy.config.core.v3.DataSource
"executor": .envoy.config.filter.http.graphql.v2.Executor
"extensions": map<string, .google.protobuf.Any>
"logRequestResponseInfo": bool

Field Type Description
schemaDefinition .solo.io.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 map<string, .google.protobuf.Any> Schema extensions.
logRequestResponseInfo bool Logs request / response sensitive information By default, this is false so no request or response sensitive information is logged.

Executor

"local": .envoy.config.filter.http.graphql.v2.Executor.Local
"remote": .envoy.config.filter.http.graphql.v2.Executor.Remote

Field Type Description
local .envoy.config.filter.http.graphql.v2.Executor.Local Only one of local or remote can be set.
remote .envoy.config.filter.http.graphql.v2.Executor.Remote Only one of remote or local can be set.

Local

Execute schema using resolvers.

"resolutions": []envoy.config.filter.http.graphql.v2.Resolution
"enableIntrospection": bool
"maxDepth": int

Field Type Description
resolutions []envoy.config.filter.http.graphql.v2.Resolution 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 int 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 receive an error as a response. The max_depth value of 0 (set by default) will allow an unbounded query depth.

Remote

Execute schema by querying a graphql upstream.

"serverUri": .solo.io.envoy.config.core.v3.HttpUri
"request": .envoy.config.filter.http.graphql.v2.Executor.Remote.RemoteSchemaRequest
"spanName": string

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

Extraction

"value": string
"header": string
"dynamicMetadata": .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction.DynamicMetadataExtraction

Field Type Description
value string Set the extraction type to use a static value. Only one of value, header, or dynamicMetadata can be set.
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. Only one of header, value, or dynamicMetadata can be set.
dynamicMetadata .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction.DynamicMetadataExtraction Set the extraction type to use a dynamic metadata value. Only one of dynamicMetadata, value, or header can be set.

DynamicMetadataExtraction

"metadataNamespace": string
"key": string

Field Type 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.

RemoteSchemaRequest

"headers": map<string, .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction>
"queryParams": map<string, .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction>

Field Type Description
headers map<string, .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction> Map of headers to header value which will be included in the request to the remote graphql server.
queryParams map<string, .envoy.config.filter.http.graphql.v2.Executor.Remote.Extraction> Query params to set on the request to the remote graphql server.