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

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 to 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
"required": bool

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.
required bool 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.

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.Path>

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.Path> 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;.

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

Query

NOT IMPLEMENTED When we’ll support prepared queries, this will be the type containing the query.

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

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

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 with in 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

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.

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.

"schema": .solo.io.envoy.config.core.v3.DataSource
"enableIntrospection": bool
"resolutions": []envoy.config.filter.http.graphql.v2.Resolution
"executableSchema": .envoy.config.filter.http.graphql.v2.ExecutableSchema

Field Type Description
schema .solo.io.envoy.config.core.v3.DataSource Deprecated. will be removed when gloo 1.10 is released.
enableIntrospection bool Deprecated. will be removed when gloo 1.10 is released.
resolutions []envoy.config.filter.http.graphql.v2.Resolution Deprecated. will be removed when gloo 1.10 is released.
executableSchema .envoy.config.filter.http.graphql.v2.ExecutableSchema

ExecutableSchema

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

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.

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

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.

Remote

NOT IMPLEMENTED YET! Execute schema by querying a graphql upstream.

"cluster": string

Field Type Description
cluster string Executes a query remotly, as a graphql client.