graphql.proto

Package: graphql.gloo.solo.io

Types:

Source File: github.com/solo-io/gloo/projects/gloo/api/v1/enterprise/options/graphql/v1beta1/graphql.proto

RequestTemplate

Defines a configuration for generating outgoing requests for a resolver.

"headers": map<string, string>
"queryParams": map<string, string>
"body": .google.protobuf.Value

Field Type Description
headers map<string, string> Use this attribute to set request headers to your REST service. It consists of a map of strings to templated value strings. The string key determines the name of the resulting header, the value provided will be the value. The least needed here is the “:method” and “:path” headers. for example, if a header is an authorization token, taken from the graphql args, we can use the following configuration: headers: Authorization: “Bearer {$args.token}”.
queryParams map<string, string> Use this attribute to set query parameters to your REST service. It consists of a map of strings to templated value strings. 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. for example, if a query parameter is an id, taken from the graphql parent object, we can use the following configuration: queryParams: id: “{$parent.id}”.
body .google.protobuf.Value Used to construct the outgoing body to the upstream from the graphql value providers. All string values can be templated strings.

ResponseTemplate

"resultRoot": string
"setters": map<string, string>

Field Type Description
resultRoot string Sets the “root” of the upstream response to be turned into a graphql type by the graphql server. For example, if the graphql type is: type Simple { name String } and the upstream response is {"data": {"simple": {"name": "simple name"}}}, the graphql server will not be able to marshal the upstream response into the Simple graphql type because it does not know where the relevant data is. If we set result_root to “data.simple”, we can give the graphql server a hint of where to look in the upstream response for the relevant data that graphql type wants.
setters map<string, string> Field-specific mapping for a graphql field to a JSON path in the upstream response. For example, if the graphql type is: type Person { firstname String lastname String fullname String } and the upstream response is {"firstname": "Joe", "details": {"lastname": "Smith"}}, the graphql server will not be able to marshal the upstream response into the Person graphql type because of the nested lastname field. We can use a simple setter here: setters: lastname: ‘{$body.details.lastname}’ fullname: ‘{$body.details.firstname} {$body.details.lastname}’ and the graphql server will be able to extract data for a field given the path to the relevant data in the upstream JSON response. We do not need to have a setter for the firstname field because the JSON response has that field in a position the graphql server can understand automatically. So far only the $body keyword is supported, but in the future we may add support for others such as $headers.

GrpcRequestTemplate

Defines a configuration for generating outgoing requests for a resolver.

"outgoingMessageJson": .google.protobuf.Value
"serviceName": string
"methodName": string
"requestMetadata": map<string, string>

Field Type Description
outgoingMessageJson .google.protobuf.Value 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.

RESTResolver

control-plane API

"upstreamRef": .core.solo.io.ResourceRef
"request": .graphql.gloo.solo.io.RequestTemplate
"response": .graphql.gloo.solo.io.ResponseTemplate
"spanName": string
"timeout": .google.protobuf.Duration

Field Type Description
upstreamRef .core.solo.io.ResourceRef
request .graphql.gloo.solo.io.RequestTemplate configuration used to compose the outgoing request to a REST API.
response .graphql.gloo.solo.io.ResponseTemplate configuration used to modify the response from the REST API before being handled by the graphql server.
spanName string
timeout .google.protobuf.Duration The timeout to use for this resolver. If unset, the upstream connection timeout or a default of 1 second will be used.

GrpcDescriptorRegistry

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

"protoDescriptor": string
"protoDescriptorBin": bytes
"protoRefsList": .graphql.gloo.solo.io.GrpcDescriptorRegistry.ProtoRefs

Field Type Description
protoDescriptor string Supplies the filename of :ref:the proto descriptor set <config_grpc_json_generate_proto_descriptor_set> for the gRPC services. Only one of protoDescriptor, protoDescriptorBin, or protoRefsList can be set.
protoDescriptorBin bytes Supplies the binary content of :ref:the proto descriptor set <config_grpc_json_generate_proto_descriptor_set> for the gRPC services. Note: in yaml, this must be provided as a base64 standard encoded string; yaml cannot handle binary bytes. Only one of protoDescriptorBin, protoDescriptor, or protoRefsList can be set.
protoRefsList .graphql.gloo.solo.io.GrpcDescriptorRegistry.ProtoRefs Allows the user to put proto descriptor set binary content in configmaps; The descriptor set binary content in these config maps must be base64 encoded Generating the proto descriptor binary and base64 encoding it can be done using the following command `protoc ./your-proto-here.proto –proto_path . –descriptor_set_out="/dev/stdout" –include_imports

ProtoRefs

"configMapRefs": []core.solo.io.ResourceRef

Field Type Description
configMapRefs []core.solo.io.ResourceRef List of references to config maps that contain proto data for this resolver. For each of the config maps referenced here, they must contain keys in their data map with valid base64 encoded proto descriptor set binaries as the values. Also they must be in a namespace watched by gloo edge.

GrpcResolver

control-plane API

"upstreamRef": .core.solo.io.ResourceRef
"requestTransform": .graphql.gloo.solo.io.GrpcRequestTemplate
"spanName": string
"timeout": .google.protobuf.Duration

Field Type Description
upstreamRef .core.solo.io.ResourceRef
requestTransform .graphql.gloo.solo.io.GrpcRequestTemplate configuration used to compose the outgoing request to a REST API.
spanName string
timeout .google.protobuf.Duration The timeout to use for this resolver. If unset, the upstream connection timeout or a default of 1 second will be used.

StitchedSchema

"subschemas": []graphql.gloo.solo.io.StitchedSchema.SubschemaConfig

Field Type Description
subschemas []graphql.gloo.solo.io.StitchedSchema.SubschemaConfig List of GraphQLApis that compose this stitched GraphQL schema.

SubschemaConfig

"name": string
"namespace": string
"typeMerge": map<string, .graphql.gloo.solo.io.StitchedSchema.SubschemaConfig.TypeMergeConfig>

Field Type Description
name string name of the GraphQLApi subschema.
namespace string namespace of the GraphQLApi subschema.
typeMerge map<string, .graphql.gloo.solo.io.StitchedSchema.SubschemaConfig.TypeMergeConfig> Type merge configuration for this subschema. Let’s say this subschema is a Users service schema and provides the User type (with a query to fetch a user given the username) gql type Query { GetUser(username: String): User } type User { username: String firstName: String lastName: String } and another subschema, e.g. Reviews schema, may have a partial User type: gql type Review { author: User } type User { username: String } We want to provide the relevant information from this Users service schema, so that another API that can give us a partial User type (with the username) will then be able to have access to the full user type. With the correct type merging config under the Users subschema, e.g.: yaml type_merge: User: selection_set: '{ username }' query_name: 'GetUser' args: username: username the stitched schema will now be able to provide the full user type to all types that require it. In this case, we can now get the first name of an author from the Review.author field even though the Reviews schema does not provide the full User type.

TypeMergeConfig

"selectionSet": string
"queryName": string
"args": map<string, string>

Field Type Description
selectionSet string This specifies one or more key fields required from other services to perform this query. Query planning will automatically resolve these fields from other subschemas in dependency order. This is a graphql selection set specified as a string e.g. ‘{ username }’.
queryName string specifies the root field from this subschema used to request the local type.
args map<string, string>

MockResolver

"syncResponse": .google.protobuf.Value
"asyncResponse": .graphql.gloo.solo.io.MockResolver.AsyncResponse
"errorResponse": string

Field Type Description
syncResponse .google.protobuf.Value The JSON response from the resolver that will be “responded” immediately. Only one of syncResponse, asyncResponse, or errorResponse can be set.
asyncResponse .graphql.gloo.solo.io.MockResolver.AsyncResponse Used to create a asynchronous JSON response from the Mock resolver. Only one of asyncResponse, syncResponse, or errorResponse can be set.
errorResponse string Responds as an error with the given message. This can be any string message. Only one of errorResponse, syncResponse, or asyncResponse can be set.

AsyncResponse

"response": .google.protobuf.Value
"delay": .google.protobuf.Duration

Field Type Description
response .google.protobuf.Value The response from the resolver as a JSON.
delay .google.protobuf.Duration The delay time before this response is sent back to the graphql server.

Resolution

Define a named resolver which can be then matched to a field using the resolve directive. 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.

"restResolver": .graphql.gloo.solo.io.RESTResolver
"grpcResolver": .graphql.gloo.solo.io.GrpcResolver
"mockResolver": .graphql.gloo.solo.io.MockResolver
"statPrefix": .google.protobuf.StringValue

Field Type Description
restResolver .graphql.gloo.solo.io.RESTResolver REST resolver used to translate and send graphql requests to a REST upstream. Only one of restResolver, grpcResolver, or mockResolver can be set.
grpcResolver .graphql.gloo.solo.io.GrpcResolver gRPC resolver used to translate and send graphql requests to a gRPC upstream. Only one of grpcResolver, restResolver, or mockResolver can be set.
mockResolver .graphql.gloo.solo.io.MockResolver Resolver used to mock responses from an upstream. This resolver does not make a call out to an upstream, but can mock responses either synchronously or with a delay. Additionally, can be used to mock errors from an upstream. Only one of mockResolver, restResolver, or grpcResolver can be set.
statPrefix .google.protobuf.StringValue The stats prefix which will be used for this resolver. If empty, will generate a stats prefix ${RESOLVER_NAME}.

GraphQLApi

Enterprise-Only: THIS FEATURE IS IN TECH PREVIEW. APIs are versioned as alpha and subject to change. User-facing CR config for resolving client requests to graphql schemas. 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. Note: while users can provide this configuration manually, the eventual UX will be to generate the Executable Schema CRs from other sources and just have users configure the routes to point to these schema CRs.

"namespacedStatuses": .core.solo.io.NamespacedStatuses
"metadata": .core.solo.io.Metadata
"executableSchema": .graphql.gloo.solo.io.ExecutableSchema
"stitchedSchema": .graphql.gloo.solo.io.StitchedSchema
"statPrefix": .google.protobuf.StringValue
"persistedQueryCacheConfig": .graphql.gloo.solo.io.PersistedQueryCacheConfig
"allowedQueryHashes": []string
"options": .graphql.gloo.solo.io.GraphQLApi.GraphQLApiOptions

Field Type Description
namespacedStatuses .core.solo.io.NamespacedStatuses NamespacedStatuses indicates the validation status of this resource. NamespacedStatuses is read-only by clients, and set by gloo during validation.
metadata .core.solo.io.Metadata Metadata contains the object metadata for this resource.
executableSchema .graphql.gloo.solo.io.ExecutableSchema An Executable Schema represents a single upstream, which could be a locally resolved schema, or a remotely resolved schema. Only one of executableSchema or stitchedSchema can be set.
stitchedSchema .graphql.gloo.solo.io.StitchedSchema A stitched schema represents the product of stitching multiple graphql subschemas together. Only one of stitchedSchema or executableSchema can be set.
statPrefix .google.protobuf.StringValue The stats prefix which will be used for this route config. If empty, will generate a stats prefix ${GRAPHQLAPI_REF}.
persistedQueryCacheConfig .graphql.gloo.solo.io.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).
options .graphql.gloo.solo.io.GraphQLApi.GraphQLApiOptions Options that apply to this GraphQLApi.

GraphQLApiOptions

"logSensitiveInfo": bool

Field Type Description
logSensitiveInfo bool If true, includes information about request and response in the gateway-proxy debug and trace logs. This is useful when debugging but is not recommended for security and performance reasons in production scenarios. Defaults to false.

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": string
"executor": .graphql.gloo.solo.io.Executor
"grpcDescriptorRegistry": .graphql.gloo.solo.io.GrpcDescriptorRegistry

Field Type Description
schemaDefinition string The following directives are supported: - @resolve(name: string) - @cacheControl(maxAge: uint32, inheritMaxAge: bool, scope: unset/public/private) Define named resolvers on the Executor.Local.resolutions message, and reference them here using @resolve: gql type Query { author: String @resolve(name: "authorResolver") } Further, fields/types can be annotated with the @cacheControl directive, e.g. gql type Query @cacheControl(maxAge: 60) { author: String @resolve(name: “authorResolver”) @cacheControl(maxAge: 90, scope: private) } ``` Any type-level cache control defaults are overridden by field settings, if provided. The most restrictive cache control setting (smallest maxAge and scope) across all fields in an entire query will be returned to the client in the Cache-Control header with appropriate max-age and scope (unset, public, or private) directives.
executor .graphql.gloo.solo.io.Executor how to execute the schema.
grpcDescriptorRegistry .graphql.gloo.solo.io.GrpcDescriptorRegistry Schema extensions.

Executor

"local": .graphql.gloo.solo.io.Executor.Local
"remote": .graphql.gloo.solo.io.Executor.Remote

Field Type Description
local .graphql.gloo.solo.io.Executor.Local Only one of local or remote can be set.
remote .graphql.gloo.solo.io.Executor.Remote Only one of remote or local can be set.

Local

Execute schema using resolvers.

"resolutions": map<string, .graphql.gloo.solo.io.Resolution>
"enableIntrospection": bool
"options": .graphql.gloo.solo.io.Executor.Local.LocalExecutorOptions

Field Type Description
resolutions map<string, .graphql.gloo.solo.io.Resolution> Mapping of resolver name to resolver definition. The names are used to reference the resolver in the graphql schema. For example, a resolver with name “authorResolver” can be defined as yaml authorResolver: restResolver: upstreamRef: ... request: ... response: ... and referenced in the graphql schema as gql type Query { author: String @resolve(name: "authorResolver") } .
enableIntrospection bool Do we enable introspection for the schema? general recommendation is to disable this for production and hence it defaults to false.
options .graphql.gloo.solo.io.Executor.Local.LocalExecutorOptions Options that apply to this local executable schema.

LocalExecutorOptions

"maxDepth": .google.protobuf.UInt32Value

Field Type Description
maxDepth .google.protobuf.UInt32Value Max GraphQL operation (query/mutation/subscription) depth. This sets a limitation on the max nesting on a query that runs against this schema. any GraphQL operation that runs past the max_depth will add an error message to the response and will return as null. As as simple example, if the schema is gql type Query { employee: Employee } type Employee { manager: Employee name: String } and we set a max_depth of 3 and we run a query gql query { # query depth : 0 employee { # query depth : 1 manager { # query depth : 2 name # query depth : 3 manager { # query depth : 3 name # query depth : 4 } } } } the graphql server will respond with a response: ```json { “data” : { “employee” : { “manager” : { “name” : “Manager 1”, “manager” : { “name” : null }}}}, “errors”: [ {“message”: “field ‘name’ exceeds the max operation depth of 3 for this schema”} ] } If not configured, or the value is 0, the query depth will be unbounded.

Remote

"upstreamRef": .core.solo.io.ResourceRef
"headers": map<string, string>
"queryParams": map<string, string>
"spanName": string

Field Type Description
upstreamRef .core.solo.io.ResourceRef
headers map<string, string> map of header name to extraction type: e.g. ‘:path’: ‘/hard/coded/path’ ‘:method’: ‘{$headers.method}’ ‘:key’: ‘{$metadata.io.solo.transformation:endpoint_url}’.
queryParams map<string, string> map of query parameter name to extraction type: e.g. ‘query’: ‘{$metadata.$KEY_NAME:$KEY_VALUE}’.
spanName string