zuplo 6.71.21 → 6.71.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/articles/graphql-caching.mdx +96 -0
- package/docs/articles/graphql-security.mdx +137 -126
- package/docs/articles/graphql-support.mdx +107 -0
- package/docs/articles/graphql.mdx +20 -0
- package/docs/dev-portal/zudoku/components/landing-page.mdx +7 -7
- package/docs/dev-portal/zudoku/components/link.mdx +5 -5
- package/docs/dev-portal/zudoku/configuration/footer.mdx +2 -2
- package/docs/dev-portal/zudoku/configuration/overview.md +1 -1
- package/docs/dev-portal/zudoku/guides/redirects.md +2 -2
- package/docs/policies/_index.md +2 -1
- package/docs/policies/graphql-analytics-outbound/doc.md +10 -6
- package/docs/policies/graphql-analytics-outbound/schema.json +5 -4
- package/docs/policies/graphql-cache-inbound/doc.md +137 -0
- package/docs/policies/graphql-cache-inbound/intro.md +15 -0
- package/docs/policies/graphql-cache-inbound/schema.json +74 -0
- package/package.json +4 -4
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Cache GraphQL responses with Zuplo
|
|
3
|
+
sidebar_label: Cache responses
|
|
4
|
+
description:
|
|
5
|
+
Serve repeated GraphQL queries from the edge with the GraphQL Cache policy to
|
|
6
|
+
cut latency and reduce load on your origin.
|
|
7
|
+
tags:
|
|
8
|
+
- caching
|
|
9
|
+
- backends
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
GraphQL clients send queries as POST request bodies, so a normal CDN — which
|
|
13
|
+
keys on the URL — can't cache them. The
|
|
14
|
+
[`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx) policy solves
|
|
15
|
+
this: it parses each query, normalizes it into a canonical form, and caches the
|
|
16
|
+
response in a [ZoneCache](../programmable-api/zone-cache.mdx) at the edge. Two
|
|
17
|
+
requests that are semantically identical share a cache entry even when their
|
|
18
|
+
bodies differ byte-for-byte.
|
|
19
|
+
|
|
20
|
+
Only `query` operations are cached. Mutations, subscriptions, malformed
|
|
21
|
+
documents, and responses that contain GraphQL `errors` are always forwarded to
|
|
22
|
+
your origin untouched.
|
|
23
|
+
|
|
24
|
+
## Add the cache policy
|
|
25
|
+
|
|
26
|
+
Add `graphql-cache-inbound` to the inbound policies of your GraphQL route.
|
|
27
|
+
|
|
28
|
+
<Stepper>
|
|
29
|
+
|
|
30
|
+
1. **Open `policies.json`**
|
|
31
|
+
|
|
32
|
+
In the Zuplo Portal, open the **Code** tab and add the policy definition:
|
|
33
|
+
|
|
34
|
+
```json title="config/policies.json"
|
|
35
|
+
{
|
|
36
|
+
"name": "graphql-cache",
|
|
37
|
+
"policyType": "graphql-cache-inbound",
|
|
38
|
+
"handler": {
|
|
39
|
+
"export": "GraphQLCacheInboundPolicy",
|
|
40
|
+
"module": "$import(@zuplo/graphql)",
|
|
41
|
+
"options": {
|
|
42
|
+
"cacheName": "graphql-responses",
|
|
43
|
+
"ttlSeconds": 60
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
2. **Attach it to your GraphQL route**
|
|
50
|
+
|
|
51
|
+
Add `"graphql-cache"` to the route's inbound policies in `routes.oas.json`,
|
|
52
|
+
ahead of any policy that rewrites the request.
|
|
53
|
+
|
|
54
|
+
3. **Verify the cache is working**
|
|
55
|
+
|
|
56
|
+
Send the same query twice and inspect the response headers. The policy adds
|
|
57
|
+
`x-cache: MISS` on the first request and `x-cache: HIT` on the second. The
|
|
58
|
+
`x-cache-key` header (first 8 characters of the cache key) confirms two
|
|
59
|
+
requests resolve to the same entry.
|
|
60
|
+
|
|
61
|
+
</Stepper>
|
|
62
|
+
|
|
63
|
+
## Cache authenticated traffic safely
|
|
64
|
+
|
|
65
|
+
By default, requests that carry an `authorization` or `cookie` header are
|
|
66
|
+
**not** cached — otherwise the first user's response would be served to
|
|
67
|
+
everyone. To cache per-user, list the headers that make a response user-specific
|
|
68
|
+
in `cacheKeyHeaders`. Each distinct value gets its own entry:
|
|
69
|
+
|
|
70
|
+
```json title="config/policies.json"
|
|
71
|
+
{
|
|
72
|
+
"options": {
|
|
73
|
+
"ttlSeconds": 30,
|
|
74
|
+
"cacheKeyHeaders": ["authorization"]
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
:::caution
|
|
80
|
+
|
|
81
|
+
Setting `cacheKeyHeaders` to an empty array `[]` caches a single response and
|
|
82
|
+
shares it across all callers. Only do this when the response genuinely doesn't
|
|
83
|
+
depend on who is calling — otherwise one caller's data leaks to others.
|
|
84
|
+
|
|
85
|
+
:::
|
|
86
|
+
|
|
87
|
+
See the [GraphQL Cache policy reference](../policies/graphql-cache-inbound.mdx)
|
|
88
|
+
for the full option matrix, including how credentialed requests fail safe.
|
|
89
|
+
|
|
90
|
+
## Next steps
|
|
91
|
+
|
|
92
|
+
- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
|
|
93
|
+
introspection controls
|
|
94
|
+
- [GraphQL on Zuplo](./graphql.mdx) — set up the endpoint and Dev Portal docs
|
|
95
|
+
- [GraphQL analytics](../analytics/tabs/graphql.md) — watch hit rates and
|
|
96
|
+
latency once traffic flows
|
|
@@ -2,179 +2,190 @@
|
|
|
2
2
|
title: Secure your GraphQL API with Zuplo
|
|
3
3
|
sidebar_label: Secure your GraphQL API
|
|
4
4
|
description:
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
Protect your GraphQL API from denial-of-service attacks and schema discovery
|
|
6
|
+
using Zuplo's GraphQL security policies.
|
|
7
7
|
tags:
|
|
8
8
|
- authentication
|
|
9
9
|
- backends
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
GraphQL gives clients enormous flexibility over what they ask for — which is
|
|
13
|
+
also what makes it easy to abuse. A single request can nest arbitrarily deep,
|
|
14
|
+
fan out into thousands of resolver calls, or map your entire schema through
|
|
15
|
+
introspection. Zuplo ships three policies that close these gaps at the edge,
|
|
16
|
+
before a malicious request ever reaches your origin:
|
|
13
17
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
[GraphQL Disable Introspection](/docs/policies/graphql-disable-introspection-inbound).
|
|
18
|
+
| Risk | Policy |
|
|
19
|
+
| ------------------- | ------------------------------------------------------------------------------------------------ |
|
|
20
|
+
| Deep / costly query | [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx) |
|
|
21
|
+
| Schema discovery | [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) |
|
|
22
|
+
| Schema over-sharing | [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) |
|
|
20
23
|
|
|
21
|
-
|
|
24
|
+
This guide explains each risk and shows the policy configuration that addresses
|
|
25
|
+
it. It assumes you've already
|
|
26
|
+
[added a GraphQL endpoint to your gateway](./graphql.mdx).
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
## Understand the risks
|
|
24
29
|
|
|
25
|
-
|
|
26
|
-
potentially overwhelm your server, resulting in a Denial of Service (DoS)
|
|
27
|
-
attack. This is because deeply nested queries can cause the server to process a
|
|
28
|
-
huge amount of data and operations. While this might be a planned attack, it
|
|
29
|
-
could also be a mistake by a client who is unaware of the query depth limit.
|
|
30
|
+
### Deeply nested or expensive queries
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
Without limits, a client can send a deeply nested query that forces your server
|
|
33
|
+
to resolve a huge graph of data, or a flat-but-expensive query that triggers
|
|
34
|
+
thousands of resolver calls. Either can exhaust resources and cause a
|
|
35
|
+
denial-of-service — whether the client is a deliberate attacker or simply
|
|
36
|
+
unaware of the cost of their query.
|
|
32
37
|
|
|
33
|
-
|
|
34
|
-
force your server to execute resource-intensive operations, potentially slowing
|
|
35
|
-
down the system or causing a DoS.
|
|
38
|
+
### Introspection
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
GraphQL lets clients introspect your schema with `__schema` and `__type`
|
|
41
|
+
queries. This is invaluable during development, but in production it hands
|
|
42
|
+
potential attackers a complete map of your types, fields, and relationships.
|
|
38
43
|
|
|
39
|
-
|
|
40
|
-
during development, it can expose detailed schema information to potential
|
|
41
|
-
attackers in production.
|
|
44
|
+
## Limit query depth and complexity
|
|
42
45
|
|
|
43
|
-
|
|
46
|
+
The
|
|
47
|
+
[`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx)
|
|
48
|
+
policy guards against expensive queries in two complementary ways. You can use
|
|
49
|
+
either or both.
|
|
44
50
|
|
|
45
|
-
###
|
|
51
|
+
### Depth limit
|
|
46
52
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
urlRewriteHandler to rewrite the request to your GraphQL API. For this example
|
|
50
|
-
let's assume your GraphQL API is hosted at `https://api.example.com/graphql`.
|
|
53
|
+
A depth limit caps how many levels a query can nest. It needs no schema and is
|
|
54
|
+
the simplest first line of defense. Add it under `useDepthLimit`:
|
|
51
55
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
```json
|
|
56
|
+
```json title="config/policies.json"
|
|
55
57
|
{
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
"
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
"
|
|
64
|
-
"options": {
|
|
65
|
-
"rewritePattern": "https://api.example.com/graphql"
|
|
66
|
-
}
|
|
67
|
-
},
|
|
68
|
-
"policies": {
|
|
69
|
-
"inbound": [
|
|
70
|
-
"graphql-complexity-limit-policy",
|
|
71
|
-
"graphql-disable-introspection-policy"
|
|
72
|
-
]
|
|
58
|
+
"name": "graphql-complexity-limit-policy",
|
|
59
|
+
"policyType": "graphql-complexity-limit-inbound",
|
|
60
|
+
"handler": {
|
|
61
|
+
"export": "GraphQLComplexityLimitInboundPolicy",
|
|
62
|
+
"module": "$import(@zuplo/graphql)",
|
|
63
|
+
"options": {
|
|
64
|
+
"useDepthLimit": {
|
|
65
|
+
"depthLimit": 20
|
|
73
66
|
}
|
|
74
|
-
}
|
|
75
|
-
"operationId": "52bdf225-eaa7-441c-afb9-b7df046a142e"
|
|
67
|
+
}
|
|
76
68
|
}
|
|
77
69
|
}
|
|
78
70
|
```
|
|
79
71
|
|
|
80
|
-
|
|
81
|
-
to protect your GraphQL API. These policies can be configured for Zuplo. We'll
|
|
82
|
-
create the configuration for the three policies `graphql-depth-limit`,
|
|
83
|
-
`graphql-complexity-points` and `graphql-disable-introspection-policy` next.
|
|
72
|
+
### Complexity limit
|
|
84
73
|
|
|
85
|
-
|
|
74
|
+
A complexity limit scores each query against your schema and rejects queries
|
|
75
|
+
above a threshold, catching expensive queries that aren't necessarily deep.
|
|
76
|
+
Because it scores against the schema, it needs your GraphQL endpoint URL for
|
|
77
|
+
introspection. Combine it with the depth limit:
|
|
86
78
|
|
|
87
|
-
|
|
88
|
-
[detailed policy documentation](/docs/policies/graphql-complexity-limit-inbound)
|
|
89
|
-
for more information.
|
|
90
|
-
|
|
91
|
-
Add this into your `config/policies.json`
|
|
92
|
-
|
|
93
|
-
```json
|
|
79
|
+
```json title="config/policies.json"
|
|
94
80
|
{
|
|
95
|
-
"
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
"
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
81
|
+
"name": "graphql-complexity-limit-policy",
|
|
82
|
+
"policyType": "graphql-complexity-limit-inbound",
|
|
83
|
+
"handler": {
|
|
84
|
+
"export": "GraphQLComplexityLimitInboundPolicy",
|
|
85
|
+
"module": "$import(@zuplo/graphql)",
|
|
86
|
+
"options": {
|
|
87
|
+
"useDepthLimit": {
|
|
88
|
+
"depthLimit": 20
|
|
89
|
+
},
|
|
90
|
+
"useComplexityLimit": {
|
|
91
|
+
"complexityLimit": 50,
|
|
92
|
+
"endpointUrl": "https://api.example.com/graphql"
|
|
107
93
|
}
|
|
108
94
|
}
|
|
109
|
-
|
|
95
|
+
}
|
|
110
96
|
}
|
|
111
97
|
```
|
|
112
98
|
|
|
113
|
-
|
|
114
|
-
|
|
99
|
+
A query that exceeds either limit is rejected with a `400` and a GraphQL error;
|
|
100
|
+
requests within the limits pass through. See the
|
|
101
|
+
[policy reference](../policies/graphql-complexity-limit-inbound.mdx) for the
|
|
102
|
+
full option set.
|
|
115
103
|
|
|
116
|
-
|
|
104
|
+
## Disable introspection in production
|
|
117
105
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
your
|
|
106
|
+
The
|
|
107
|
+
[`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx)
|
|
108
|
+
policy blocks any query containing `__schema` or `__type` with a `403`, hiding
|
|
109
|
+
your schema from clients. It takes no options:
|
|
122
110
|
|
|
123
|
-
```json
|
|
111
|
+
```json title="config/policies.json"
|
|
124
112
|
{
|
|
125
|
-
"
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
113
|
+
"name": "graphql-disable-introspection-policy",
|
|
114
|
+
"policyType": "graphql-disable-introspection-inbound",
|
|
115
|
+
"handler": {
|
|
116
|
+
"export": "GraphQLDisableIntrospectionInboundPolicy",
|
|
117
|
+
"module": "$import(@zuplo/graphql)",
|
|
118
|
+
"options": {}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Expose a partial schema instead
|
|
124
|
+
|
|
125
|
+
Disabling introspection entirely isn't always what you want. If you need clients
|
|
126
|
+
(or [MCP-connected AI agents](../mcp-server/graphql.mdx)) to introspect part of
|
|
127
|
+
your schema while keeping sensitive types and fields hidden, use the outbound
|
|
128
|
+
[`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx)
|
|
129
|
+
policy. It strips chosen types and fields from introspection responses:
|
|
130
|
+
|
|
131
|
+
```json title="config/policies.json"
|
|
132
|
+
{
|
|
133
|
+
"name": "graphql-introspection-filter-policy",
|
|
134
|
+
"policyType": "graphql-introspection-filter-outbound",
|
|
135
|
+
"handler": {
|
|
136
|
+
"export": "GraphQLIntrospectionFilterOutboundPolicy",
|
|
137
|
+
"module": "$import(@zuplo/graphql)",
|
|
138
|
+
"options": {
|
|
139
|
+
"excludeTypes": ["AdminUser"],
|
|
140
|
+
"excludeTypeFields": {
|
|
141
|
+
"User": ["password", "ssn"],
|
|
142
|
+
"Query": ["adminUsers"]
|
|
141
143
|
}
|
|
142
144
|
}
|
|
143
|
-
|
|
145
|
+
}
|
|
144
146
|
}
|
|
145
147
|
```
|
|
146
148
|
|
|
147
|
-
|
|
148
|
-
by sending overly complicated queries.
|
|
149
|
-
|
|
150
|
-
### c. GraphQL Disable Introspection
|
|
149
|
+
## Attach the policies to your route
|
|
151
150
|
|
|
152
|
-
|
|
151
|
+
Add the inbound policies to your GraphQL route in `routes.oas.json`. The
|
|
152
|
+
outbound filter policy goes in the `outbound` array:
|
|
153
153
|
|
|
154
|
-
```json
|
|
154
|
+
```json title="config/routes.oas.json"
|
|
155
155
|
{
|
|
156
|
-
"
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
156
|
+
"post": {
|
|
157
|
+
"summary": "GraphQL Endpoint",
|
|
158
|
+
"x-graphql": true,
|
|
159
|
+
"x-zuplo-route": {
|
|
160
|
+
"corsPolicy": "none",
|
|
160
161
|
"handler": {
|
|
161
|
-
"export": "
|
|
162
|
-
"module": "$import(@zuplo/
|
|
163
|
-
"options": {
|
|
162
|
+
"export": "urlRewriteHandler",
|
|
163
|
+
"module": "$import(@zuplo/runtime)",
|
|
164
|
+
"options": {
|
|
165
|
+
"rewritePattern": "https://api.example.com/graphql"
|
|
166
|
+
}
|
|
167
|
+
},
|
|
168
|
+
"policies": {
|
|
169
|
+
"inbound": [
|
|
170
|
+
"graphql-complexity-limit-policy",
|
|
171
|
+
"graphql-disable-introspection-policy"
|
|
172
|
+
]
|
|
164
173
|
}
|
|
165
|
-
}
|
|
166
|
-
|
|
174
|
+
},
|
|
175
|
+
"operationId": "graphql-secure"
|
|
176
|
+
}
|
|
167
177
|
}
|
|
168
178
|
```
|
|
169
179
|
|
|
170
|
-
|
|
171
|
-
|
|
180
|
+
## Example repository
|
|
181
|
+
|
|
182
|
+
For a complete, runnable setup, see the
|
|
183
|
+
[GraphQL API with Zuplo example repository](https://github.com/zuplo/zuplo-graphql-example).
|
|
172
184
|
|
|
173
|
-
##
|
|
185
|
+
## Next steps
|
|
174
186
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
to dive deeper.
|
|
187
|
+
- [Cache GraphQL responses](./graphql-caching.mdx) — cut latency with edge
|
|
188
|
+
caching
|
|
189
|
+
- [Test GraphQL queries](./testing-graphql.mdx) — verify your secured endpoint
|
|
190
|
+
- [GraphQL analytics](../analytics/tabs/graphql.md) — surface errors and monitor
|
|
191
|
+
traffic
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: GraphQL support on Zuplo
|
|
3
|
+
sidebar_label: Overview
|
|
4
|
+
description:
|
|
5
|
+
Everything Zuplo supports for GraphQL APIs — proxying, security, caching,
|
|
6
|
+
analytics, Dev Portal docs, and MCP — with links to each guide and policy.
|
|
7
|
+
tags:
|
|
8
|
+
- backends
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
Zuplo treats GraphQL as a first-class backend. Proxy your existing GraphQL
|
|
12
|
+
server through the gateway, then layer on security, caching, analytics, and
|
|
13
|
+
documentation using policies built for the GraphQL request shape — where every
|
|
14
|
+
operation is a `POST` to a single URL, so URL-based gateway features don't
|
|
15
|
+
apply.
|
|
16
|
+
|
|
17
|
+
This page summarizes what Zuplo supports for GraphQL and links to each guide and
|
|
18
|
+
policy reference.
|
|
19
|
+
|
|
20
|
+
:::tip{title="New here?"}
|
|
21
|
+
|
|
22
|
+
Start with [Set up an endpoint](./graphql.mdx) to proxy your GraphQL API through
|
|
23
|
+
the gateway, then come back to layer on the capabilities below.
|
|
24
|
+
|
|
25
|
+
:::
|
|
26
|
+
|
|
27
|
+
## Connect and route
|
|
28
|
+
|
|
29
|
+
Proxy any GraphQL server through a `POST /graphql` route using the
|
|
30
|
+
[URL Rewrite handler](../handlers/url-rewrite.mdx). The Route Designer ships a
|
|
31
|
+
**GraphQL Endpoint** template, and the `x-graphql` route extension marks a route
|
|
32
|
+
as GraphQL so the gateway and Dev Portal treat it accordingly.
|
|
33
|
+
|
|
34
|
+
- [Set up an endpoint](./graphql.mdx) — add or mark a GraphQL route
|
|
35
|
+
|
|
36
|
+
## Secure the endpoint
|
|
37
|
+
|
|
38
|
+
GraphQL's flexibility is also its attack surface: a single request can nest
|
|
39
|
+
arbitrarily deep, fan out into thousands of resolver calls, or map your whole
|
|
40
|
+
schema through introspection. Zuplo closes these gaps at the edge.
|
|
41
|
+
|
|
42
|
+
| Risk | What Zuplo does |
|
|
43
|
+
| ------------------- | ------------------------------------------------ |
|
|
44
|
+
| Deep / costly query | Reject queries over a depth or complexity score |
|
|
45
|
+
| Schema discovery | Block introspection in production |
|
|
46
|
+
| Schema over-sharing | Strip chosen types and fields from introspection |
|
|
47
|
+
|
|
48
|
+
- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
|
|
49
|
+
introspection controls
|
|
50
|
+
|
|
51
|
+
## Accelerate with caching
|
|
52
|
+
|
|
53
|
+
A normal CDN keys on the URL, so it can't cache GraphQL queries sent as request
|
|
54
|
+
bodies. The GraphQL cache parses each query, normalizes it into a canonical
|
|
55
|
+
form, and serves semantically identical queries from one edge cache entry.
|
|
56
|
+
|
|
57
|
+
- [Cache GraphQL responses](./graphql-caching.mdx) — serve repeated queries from
|
|
58
|
+
the edge
|
|
59
|
+
|
|
60
|
+
## Observe traffic
|
|
61
|
+
|
|
62
|
+
Report GraphQL operations and their errors to analytics, even when the upstream
|
|
63
|
+
returns errors inside a `200` response. The GraphQL analytics dashboard surfaces
|
|
64
|
+
operation volume, latency, and error classes once traffic flows.
|
|
65
|
+
|
|
66
|
+
- [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operations,
|
|
67
|
+
latency, and errors
|
|
68
|
+
|
|
69
|
+
## Document in the Dev Portal
|
|
70
|
+
|
|
71
|
+
The `@zudoku/plugin-graphql` package renders a browsable type reference and an
|
|
72
|
+
interactive playground in your Dev Portal, generated from your schema or a live
|
|
73
|
+
endpoint. Register one instance per API.
|
|
74
|
+
|
|
75
|
+
- [Document the API in your Dev Portal](./graphql.mdx#document-the-api-in-your-dev-portal)
|
|
76
|
+
— add the GraphQL plugin
|
|
77
|
+
|
|
78
|
+
## Expose GraphQL to AI agents
|
|
79
|
+
|
|
80
|
+
Turn GraphQL queries into MCP tools so AI agents can call your API through the
|
|
81
|
+
Model Context Protocol, with the same policies and auth applied.
|
|
82
|
+
|
|
83
|
+
- [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose queries as
|
|
84
|
+
MCP tools
|
|
85
|
+
|
|
86
|
+
## Policies at a glance
|
|
87
|
+
|
|
88
|
+
Every GraphQL-aware policy Zuplo ships, with its direction and purpose:
|
|
89
|
+
|
|
90
|
+
| Policy | Direction | Purpose |
|
|
91
|
+
| ------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------- |
|
|
92
|
+
| [`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx) | Inbound | Cache repeated queries at the edge |
|
|
93
|
+
| [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx) | Inbound | Reject queries that are too deep or too expensive |
|
|
94
|
+
| [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) | Inbound | Block schema introspection in production |
|
|
95
|
+
| [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) | Outbound | Hide chosen types and fields from introspection |
|
|
96
|
+
| [`graphql-analytics-outbound`](../policies/graphql-analytics-outbound.mdx) | Outbound | Report operations and errors to analytics |
|
|
97
|
+
|
|
98
|
+
## Next steps
|
|
99
|
+
|
|
100
|
+
- [Set up an endpoint](./graphql.mdx) — proxy your GraphQL API through the
|
|
101
|
+
gateway
|
|
102
|
+
- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
|
|
103
|
+
introspection controls
|
|
104
|
+
- [Cache GraphQL responses](./graphql-caching.mdx) — cut latency with edge
|
|
105
|
+
caching
|
|
106
|
+
- [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose queries to
|
|
107
|
+
AI agents
|
|
@@ -18,6 +18,7 @@ your schema in the Dev Portal. This guide walks you through setting it up.
|
|
|
18
18
|
Rewrite handler
|
|
19
19
|
- [ ] Tag the route with the `x-graphql` extension
|
|
20
20
|
- [ ] Surface failed operations with the `graphql-analytics-outbound` policy
|
|
21
|
+
- [ ] Add caching and security policies to protect and accelerate the endpoint
|
|
21
22
|
- [ ] Add the `graphqlPlugin` to the Developer Portal
|
|
22
23
|
|
|
23
24
|
:::
|
|
@@ -111,6 +112,23 @@ To fine-tune analytics, see the
|
|
|
111
112
|
[GraphQL Analytics policy reference](../policies/graphql-analytics-outbound.mdx)
|
|
112
113
|
for the full set of options.
|
|
113
114
|
|
|
115
|
+
## Protect and accelerate the endpoint
|
|
116
|
+
|
|
117
|
+
Once requests are flowing, attach GraphQL-aware policies to the route. Zuplo
|
|
118
|
+
ships a set built specifically for the GraphQL request shape:
|
|
119
|
+
|
|
120
|
+
| Goal | Policy |
|
|
121
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
122
|
+
| Cache repeated queries at the edge | [`graphql-cache-inbound`](../policies/graphql-cache-inbound.mdx) |
|
|
123
|
+
| Block deep or expensive queries | [`graphql-complexity-limit-inbound`](../policies/graphql-complexity-limit-inbound.mdx) |
|
|
124
|
+
| Disable schema introspection in production | [`graphql-disable-introspection-inbound`](../policies/graphql-disable-introspection-inbound.mdx) |
|
|
125
|
+
| Hide sensitive types from introspection | [`graphql-introspection-filter-outbound`](../policies/graphql-introspection-filter-outbound.mdx) |
|
|
126
|
+
| Report failed operations to analytics | [`graphql-analytics-outbound`](../policies/graphql-analytics-outbound.mdx) |
|
|
127
|
+
|
|
128
|
+
See [Secure your GraphQL API](./graphql-security.mdx) for the complexity and
|
|
129
|
+
introspection policies, and [Cache GraphQL responses](./graphql-caching.mdx) to
|
|
130
|
+
serve identical queries from the edge.
|
|
131
|
+
|
|
114
132
|
## Document the API in your Dev Portal
|
|
115
133
|
|
|
116
134
|
The `@zudoku/plugin-graphql` package renders a browsable type reference and a
|
|
@@ -161,6 +179,8 @@ the playground is pointed at the right endpoint.
|
|
|
161
179
|
|
|
162
180
|
- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
|
|
163
181
|
introspection policies
|
|
182
|
+
- [Cache GraphQL responses](./graphql-caching.mdx) — serve repeated queries from
|
|
183
|
+
the edge
|
|
164
184
|
- [Testing GraphQL queries](./testing-graphql.mdx) — test the endpoint from the
|
|
165
185
|
Zuplo Portal or external tools
|
|
166
186
|
- [GraphQL analytics](../analytics/tabs/graphql.md) — monitor operation volume,
|
|
@@ -56,8 +56,8 @@ page for product-focused portals. The previews on this page are presented in a
|
|
|
56
56
|
title="Build with our API"
|
|
57
57
|
description="Everything you need to integrate payments, webhooks, and more — in minutes, not days."
|
|
58
58
|
actions={[
|
|
59
|
-
{ label: "Get started", href: "/
|
|
60
|
-
{ label: "API Reference", href: "/
|
|
59
|
+
{ label: "Get started", href: "/getting-started" },
|
|
60
|
+
{ label: "API Reference", href: "/", variant: "outline" },
|
|
61
61
|
]}
|
|
62
62
|
features={[
|
|
63
63
|
{
|
|
@@ -121,7 +121,7 @@ front.
|
|
|
121
121
|
title="Ship anywhere in the whole universe"
|
|
122
122
|
description="Create and manage shipments, track packages in real-time, and integrate with multiple carriers through a single interface."
|
|
123
123
|
actions={[
|
|
124
|
-
{ label: "Get started", href: "/
|
|
124
|
+
{ label: "Get started", href: "/getting-started" },
|
|
125
125
|
{ label: "View on GitHub", href: "https://github.com/zuplo/zudoku", variant: "outline" },
|
|
126
126
|
]}
|
|
127
127
|
aside={
|
|
@@ -183,25 +183,25 @@ routes visitors to the right section quickly.
|
|
|
183
183
|
icon: <RocketIcon />,
|
|
184
184
|
title: "Getting Started",
|
|
185
185
|
description: "Set up your account and make your first request.",
|
|
186
|
-
href: "/
|
|
186
|
+
href: "/getting-started",
|
|
187
187
|
},
|
|
188
188
|
{
|
|
189
189
|
icon: <BookOpenIcon />,
|
|
190
190
|
title: "Guides",
|
|
191
191
|
description: "Step-by-step tutorials for common use cases.",
|
|
192
|
-
href: "/
|
|
192
|
+
href: "/",
|
|
193
193
|
},
|
|
194
194
|
{
|
|
195
195
|
icon: <CodeIcon />,
|
|
196
196
|
title: "API Reference",
|
|
197
197
|
description: "Complete reference for every endpoint and type.",
|
|
198
|
-
href: "/
|
|
198
|
+
href: "/",
|
|
199
199
|
},
|
|
200
200
|
{
|
|
201
201
|
icon: <WebhookIcon />,
|
|
202
202
|
title: "Webhooks",
|
|
203
203
|
description: "Listen to events and build real-time integrations.",
|
|
204
|
-
href: "/
|
|
204
|
+
href: "/",
|
|
205
205
|
},
|
|
206
206
|
]}
|
|
207
207
|
/>
|
|
@@ -17,7 +17,7 @@ import { Link } from "zudoku/components";
|
|
|
17
17
|
### Basic Internal Link
|
|
18
18
|
|
|
19
19
|
```tsx
|
|
20
|
-
<Link to="/
|
|
20
|
+
<Link to="/getting-started">Get Started</Link>
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
### Link with State
|
|
@@ -39,7 +39,7 @@ import { Link } from "zudoku/components";
|
|
|
39
39
|
### External Link Behavior
|
|
40
40
|
|
|
41
41
|
```tsx
|
|
42
|
-
<Link to="/
|
|
42
|
+
<Link to="/" reloadDocument>
|
|
43
43
|
Full Page Reload
|
|
44
44
|
</Link>
|
|
45
45
|
```
|
|
@@ -53,7 +53,7 @@ function Navigation() {
|
|
|
53
53
|
return (
|
|
54
54
|
<nav>
|
|
55
55
|
<Link to="/">Home</Link>
|
|
56
|
-
<Link to="/
|
|
56
|
+
<Link to="/">Documentation</Link>
|
|
57
57
|
<Link to="/api">API Reference</Link>
|
|
58
58
|
<Link to="/blog">Blog</Link>
|
|
59
59
|
</nav>
|
|
@@ -69,7 +69,7 @@ function Breadcrumbs({ path }) {
|
|
|
69
69
|
<div className="breadcrumbs">
|
|
70
70
|
<Link to="/">Home</Link>
|
|
71
71
|
<span>/</span>
|
|
72
|
-
<Link to="/
|
|
72
|
+
<Link to="/">Docs</Link>
|
|
73
73
|
<span>/</span>
|
|
74
74
|
<span>{path}</span>
|
|
75
75
|
</div>
|
|
@@ -134,7 +134,7 @@ function ConditionalLink({ to, disabled, children }) {
|
|
|
134
134
|
### Hash Links
|
|
135
135
|
|
|
136
136
|
```tsx
|
|
137
|
-
<Link to="/
|
|
137
|
+
<Link to="/api#authentication">Authentication Section</Link>
|
|
138
138
|
```
|
|
139
139
|
|
|
140
140
|
## Advanced Usage
|
|
@@ -59,7 +59,7 @@ footer: {
|
|
|
59
59
|
links: [
|
|
60
60
|
{ label: "Features", href: "/features" },
|
|
61
61
|
{ label: "Pricing", href: "/pricing" },
|
|
62
|
-
{ label: "Documentation", href: "/
|
|
62
|
+
{ label: "Documentation", href: "/" },
|
|
63
63
|
{ label: "GitHub", href: "https://github.com/org/repo" }, // Auto-detected as external
|
|
64
64
|
],
|
|
65
65
|
},
|
|
@@ -184,7 +184,7 @@ footer: {
|
|
|
184
184
|
links: [
|
|
185
185
|
{ label: "Features", href: "/features" },
|
|
186
186
|
{ label: "Pricing", href: "/pricing" },
|
|
187
|
-
{ label: "Documentation", href: "/
|
|
187
|
+
{ label: "Documentation", href: "/" }
|
|
188
188
|
]
|
|
189
189
|
},
|
|
190
190
|
{
|
|
@@ -46,7 +46,7 @@ const config: ZudokuConfig = {
|
|
|
46
46
|
},
|
|
47
47
|
{ type: "link", to: "api", label: "API Reference" },
|
|
48
48
|
],
|
|
49
|
-
redirects: [{ from: "/", to: "/
|
|
49
|
+
redirects: [{ from: "/", to: "/introduction" }],
|
|
50
50
|
apis: {
|
|
51
51
|
type: "file",
|
|
52
52
|
input: "./apis/openapi.yaml",
|
|
@@ -85,7 +85,7 @@ signal a permanent move; the JavaScript redirect used on generic static hosts is
|
|
|
85
85
|
The most common use of redirects is setting a landing page for the root path of your portal:
|
|
86
86
|
|
|
87
87
|
```ts
|
|
88
|
-
redirects: [{ from: "/", to: "/
|
|
88
|
+
redirects: [{ from: "/", to: "/introduction" }];
|
|
89
89
|
```
|
|
90
90
|
|
|
91
91
|
This sends visitors who arrive at your portal's root URL to your introduction page.
|
|
@@ -98,7 +98,7 @@ external links continue to work:
|
|
|
98
98
|
```ts
|
|
99
99
|
redirects: [
|
|
100
100
|
{ from: "/api/authentication", to: "/guides/auth-overview" },
|
|
101
|
-
{ from: "/api/getting-started", to: "/
|
|
101
|
+
{ from: "/api/getting-started", to: "/quickstart" },
|
|
102
102
|
{ from: "/reference", to: "/api" },
|
|
103
103
|
];
|
|
104
104
|
```
|
package/docs/policies/_index.md
CHANGED
|
@@ -43,7 +43,8 @@
|
|
|
43
43
|
| formdata-to-json-inbound | Form Data to JSON | Converts form data in the incoming request to JSON. | api-gateway |
|
|
44
44
|
| galileo-tracing-inbound | Galileo Tracing | Galileo Tracing Inbound Policy | ai-gateway |
|
|
45
45
|
| geo-filter-inbound | Geo-location filtering | Block requests based on geo-location parameters: country, region code, and ASN | api-gateway |
|
|
46
|
-
| graphql-analytics-outbound | GraphQL Analytics | Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type. Each error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response.
|
|
46
|
+
| graphql-analytics-outbound | GraphQL Analytics | Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type. Each error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. The policy reads up to `maxScanBytes` of the body (128 KiB by default, 5 MiB maximum), scanning it for the `errors` token; a response larger than that is treated as error-free. When the token is found and the body fits, it is parsed and its errors reported. The response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing. | api-gateway |
|
|
47
|
+
| graphql-cache-inbound | GraphQL Cache | Caches GraphQL query responses at the edge so identical queries are served without a round-trip to the origin. Unlike CDN caching that keys on the raw request body, this policy parses the GraphQL document and normalizes it before hashing: insignificant whitespace, field formatting, and fragment layout are collapsed, and variable object keys are sorted. Two requests that are semantically identical therefore share a cache entry even when their bodies differ byte-for-byte. There is no query size or nesting-depth limit. Only `query` operations are cached. Mutations, subscriptions, malformed documents, and non-JSON bodies are forwarded to the origin untouched. Cache hits and misses are reported on the `x-cache` response header, with a short key fingerprint on `x-cache-key`. To avoid serving one user's data to another, requests carrying an `authorization` or `cookie` header are not cached by default. Use `cacheKeyHeaders` to opt into caching them: each listed header's value is included in the cache key, so distinct credentials get distinct cache entries. | api-gateway |
|
|
47
48
|
| graphql-complexity-limit-inbound | GraphQL Complexity Limit | Policy that limits the complexity and depth of GraphQL queries to prevent abuse. Protects your GraphQL API from expensive queries that could cause performance issues or denial of service attacks. | api-gateway |
|
|
48
49
|
| graphql-disable-introspection-inbound | GraphQL Disable Introspection | Policy that disables GraphQL introspection queries in production. Introspection allows clients to discover the schema, which can be a security risk as it exposes your entire API structure. | api-gateway |
|
|
49
50
|
| graphql-introspection-filter-outbound | GraphQL Introspection Filter | Filters GraphQL introspection responses to exclude specific types and fields. This policy intercepts GraphQL introspection query responses and removes configured types and fields from the schema. Useful for hiding internal types or sensitive fields from the public schema. | api-gateway |
|
|
@@ -41,10 +41,13 @@ result in the batch.
|
|
|
41
41
|
## What is inspected
|
|
42
42
|
|
|
43
43
|
Only responses with a JSON content type (`application/json` or any `+json` type
|
|
44
|
-
such as `application/graphql-response+json`) are read
|
|
45
|
-
`
|
|
46
|
-
|
|
47
|
-
|
|
44
|
+
such as `application/graphql-response+json`) are read. The policy reads up to
|
|
45
|
+
`maxScanBytes` of the body (128 KiB by default, 5 MiB maximum) and scans it for
|
|
46
|
+
the `errors` token; a response larger than that — by `Content-Length` when the
|
|
47
|
+
header is present, or measured while reading when it is absent — is treated as
|
|
48
|
+
error-free, so any errors it carries go unreported. Raise `maxScanBytes` if your
|
|
49
|
+
GraphQL responses are larger. Everything else passes through without the body
|
|
50
|
+
being touched.
|
|
48
51
|
|
|
49
52
|
## Logging
|
|
50
53
|
|
|
@@ -63,8 +66,9 @@ alert on it.
|
|
|
63
66
|
`resolver`
|
|
64
67
|
- `logErrors`: Also log a structured warning per errored response. **Default:**
|
|
65
68
|
`false`
|
|
66
|
-
- `
|
|
67
|
-
|
|
69
|
+
- `maxScanBytes`: How many bytes of the response body to read and scan for the
|
|
70
|
+
`errors` token. A larger response is treated as error-free. Capped at 5 MiB.
|
|
71
|
+
**Default:** `131072` (128 KiB)
|
|
68
72
|
|
|
69
73
|
## Usage
|
|
70
74
|
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"isHidden": false,
|
|
12
12
|
"requiresAI": false,
|
|
13
13
|
"products": ["api-gateway"],
|
|
14
|
-
"description": "Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.\n\nEach error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response.
|
|
14
|
+
"description": "Reports GraphQL errors returned in response bodies to Zuplo's GraphQL analytics. GraphQL servers following the standard Apollo / graphql-yoga pattern return `200 OK` with an `errors[]` array in the body when an operation fails, which HTTP-level analytics alone report as a success — add this policy to a GraphQL route and failed operations show up as failures on the GraphQL dashboard, classified by error type.\n\nEach error in `errors[]` is classified from its `extensions.code` following the Apollo Server conventions (`GRAPHQL_PARSE_FAILED` → `syntax`, `GRAPHQL_VALIDATION_FAILED` → `validation`, `UNAUTHENTICATED` / `FORBIDDEN` → `auth`, timeout codes → `timeout`); custom codes can be mapped with `errorCodeClassification`, and anything unrecognized falls back to `defaultErrorClass` (`resolver`). Optionally set `logErrors` to also write a structured warning per errored response. The policy reads up to `maxScanBytes` of the body (128 KiB by default, 5 MiB maximum), scanning it for the `errors` token; a response larger than that is treated as error-free. When the token is found and the body fits, it is parsed and its errors reported.\n\nThe response always passes through unchanged — the body is read from a clone, and any internal failure is swallowed so reporting can never break the request. The route must be marked `x-graphql: true` in `routes.oas.json` (which enables GraphQL analytics for the route); without the marker the policy logs a warning and does nothing.",
|
|
15
15
|
"deprecatedMessage": "",
|
|
16
16
|
"required": ["handler"],
|
|
17
17
|
"properties": {
|
|
@@ -64,12 +64,13 @@
|
|
|
64
64
|
"default": false,
|
|
65
65
|
"description": "When `true`, also write a structured warning to the request log (message, `extensions.code`, and path of each error — capped at the first 10) whenever a response contains GraphQL errors."
|
|
66
66
|
},
|
|
67
|
-
"
|
|
67
|
+
"maxScanBytes": {
|
|
68
68
|
"type": "integer",
|
|
69
69
|
"minimum": 1,
|
|
70
|
-
"
|
|
70
|
+
"maximum": 5242880,
|
|
71
|
+
"default": 131072,
|
|
71
72
|
"x-show-example": false,
|
|
72
|
-
"description": "
|
|
73
|
+
"description": "How many bytes of the response body the policy reads to look for GraphQL errors. The body is read and scanned for the `errors` token up to this limit; a body larger than the limit — by `Content-Length`, or measured while reading when the header is absent — is treated as error-free, so any errors it carries go unreported. The default of 128 KiB suits the common case, where servers emit `errors` near the front of the body. Raise it (up to the 5 MiB maximum) to detect errors in larger responses, at the cost of reading more of every response. When the token is found and the body fits within the limit, the body is parsed and its errors are reported."
|
|
73
74
|
}
|
|
74
75
|
}
|
|
75
76
|
}
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
The GraphQL Cache policy stores successful GraphQL query responses in a
|
|
2
|
+
[ZoneCache](https://zuplo.com/docs/articles/zonecache) and serves later,
|
|
3
|
+
identical queries directly from the edge.
|
|
4
|
+
|
|
5
|
+
### How caching works
|
|
6
|
+
|
|
7
|
+
For every inbound request the policy:
|
|
8
|
+
|
|
9
|
+
1. Reads the request body and parses it as GraphQL JSON
|
|
10
|
+
(`{ "query": "...", "variables": { ... }, "operationName": "..." }`).
|
|
11
|
+
2. Parses the query and re-prints it, producing a canonical form that ignores
|
|
12
|
+
insignificant whitespace, field formatting, and fragment layout.
|
|
13
|
+
3. Canonicalizes the `variables` by recursively sorting object keys.
|
|
14
|
+
4. Hashes the normalized query, canonicalized variables, and `operationName`
|
|
15
|
+
(SHA-256) into a cache key. `operationName` is included because a document
|
|
16
|
+
with multiple operations returns a different response depending on which
|
|
17
|
+
operation the client selects.
|
|
18
|
+
|
|
19
|
+
On a **hit**, the cached response is returned immediately. On a **miss**, the
|
|
20
|
+
request is forwarded to the origin and a successful response is stored for
|
|
21
|
+
future requests.
|
|
22
|
+
|
|
23
|
+
Every response served or stored by the policy carries two headers:
|
|
24
|
+
|
|
25
|
+
- **`x-cache`** — `HIT` when served from cache, `MISS` when fetched from the
|
|
26
|
+
origin.
|
|
27
|
+
- **`x-cache-key`** — the first 8 characters of the cache key, useful for
|
|
28
|
+
confirming that two requests resolve to the same entry.
|
|
29
|
+
|
|
30
|
+
Both headers are added to `access-control-expose-headers` so browsers can read
|
|
31
|
+
them, without overwriting any value an upstream CORS policy already set.
|
|
32
|
+
|
|
33
|
+
### What is and isn't cached
|
|
34
|
+
|
|
35
|
+
- Only `query` operations are cached. **Mutations** and **subscriptions** are
|
|
36
|
+
forwarded to the origin and never cached. In a multi-operation document the
|
|
37
|
+
operation selected by `operationName` is the one that decides this.
|
|
38
|
+
- **Malformed** GraphQL and **non-JSON** bodies are forwarded untouched so the
|
|
39
|
+
origin can return a proper error. Documents with multiple operations but no
|
|
40
|
+
`operationName` (or an `operationName` that matches none) are also forwarded.
|
|
41
|
+
- Only `200` responses are cached, and only when the body is a successful
|
|
42
|
+
GraphQL result. Because GraphQL returns execution errors with a `200` status
|
|
43
|
+
and an `errors` array, responses carrying a non-empty `errors` array — and
|
|
44
|
+
non-JSON `200` bodies — are **not** cached.
|
|
45
|
+
|
|
46
|
+
### Options
|
|
47
|
+
|
|
48
|
+
- **`cacheName`** - The name of the cache used to store responses. Defaults to
|
|
49
|
+
`graphql-responses`. Routes that share a name share a cache; use distinct
|
|
50
|
+
names to isolate caches per route or per upstream.
|
|
51
|
+
- **`ttlSeconds`** - How long, in seconds, a cached response is served before it
|
|
52
|
+
is considered stale and the next request is forwarded to the origin to refresh
|
|
53
|
+
the entry. Defaults to `60`.
|
|
54
|
+
- **`cacheKeyHeaders`** - Request header names whose values are included in the
|
|
55
|
+
cache key (matched case-insensitively), and the control for how credentialed
|
|
56
|
+
requests are cached. See
|
|
57
|
+
[Authentication and per-user caching](#authentication-and-per-user-caching)
|
|
58
|
+
below. Defaults to omitted.
|
|
59
|
+
|
|
60
|
+
### Authentication and per-user caching
|
|
61
|
+
|
|
62
|
+
A response cache keyed only on the query would serve the first user's response
|
|
63
|
+
to everyone. To prevent that, the policy **does not cache requests that carry an
|
|
64
|
+
`authorization` or `cookie` header** by default — those requests are forwarded
|
|
65
|
+
to the origin every time.
|
|
66
|
+
|
|
67
|
+
To cache authenticated traffic safely, list the headers that make a response
|
|
68
|
+
user-specific in `cacheKeyHeaders`. Each listed header's value becomes part of
|
|
69
|
+
the cache key, so every distinct value (for example, every bearer token) gets
|
|
70
|
+
its own cache entry:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"name": "graphql-cache",
|
|
75
|
+
"policyType": "graphql-cache-inbound",
|
|
76
|
+
"handler": {
|
|
77
|
+
"export": "GraphQLCacheInboundPolicy",
|
|
78
|
+
"module": "$import(@zuplo/graphql)",
|
|
79
|
+
"options": {
|
|
80
|
+
"ttlSeconds": 30,
|
|
81
|
+
"cacheKeyHeaders": ["authorization"]
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
If a request still carries an `authorization` or `cookie` header that is **not**
|
|
88
|
+
in `cacheKeyHeaders`, it is left uncached — so partially configuring the
|
|
89
|
+
allowlist fails safe rather than leaking across users.
|
|
90
|
+
|
|
91
|
+
#### Caching credentialed requests as a single shared entry
|
|
92
|
+
|
|
93
|
+
Sometimes a request must carry `authorization` (or `cookie`) to be authorized,
|
|
94
|
+
but the response is identical for everyone allowed through — the credential
|
|
95
|
+
gates access without changing the data. In that case, set `cacheKeyHeaders` to
|
|
96
|
+
an **empty array** to cache one response and share it across all callers:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"name": "graphql-cache",
|
|
101
|
+
"policyType": "graphql-cache-inbound",
|
|
102
|
+
"handler": {
|
|
103
|
+
"export": "GraphQLCacheInboundPolicy",
|
|
104
|
+
"module": "$import(@zuplo/graphql)",
|
|
105
|
+
"options": {
|
|
106
|
+
"cacheKeyHeaders": []
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
This is distinct from omitting the option: omitting it keeps the safe default
|
|
113
|
+
(credentialed requests are not cached), whereas `[]` is an explicit assertion
|
|
114
|
+
that the response does not depend on the caller. **Only use `[]` when that is
|
|
115
|
+
true** — otherwise one caller's response will be served to others.
|
|
116
|
+
|
|
117
|
+
Response cookies are never shared. `Set-Cookie` (along with `Set-Cookie2` and
|
|
118
|
+
`Clear-Site-Data`) is stripped from the stored entry, so a cookie an origin sets
|
|
119
|
+
on one caller's response is never replayed to another from cache. The caller
|
|
120
|
+
whose request reached the origin still receives the original `Set-Cookie`.
|
|
121
|
+
|
|
122
|
+
### Example
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"name": "graphql-cache",
|
|
127
|
+
"policyType": "graphql-cache-inbound",
|
|
128
|
+
"handler": {
|
|
129
|
+
"export": "GraphQLCacheInboundPolicy",
|
|
130
|
+
"module": "$import(@zuplo/graphql)",
|
|
131
|
+
"options": {
|
|
132
|
+
"cacheName": "graphql-responses",
|
|
133
|
+
"ttlSeconds": 60
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
This policy caches GraphQL query responses at the edge so identical queries are
|
|
2
|
+
served without a round-trip to your origin.
|
|
3
|
+
|
|
4
|
+
Unlike CDN caching that keys on the raw request body, this policy parses each
|
|
5
|
+
GraphQL document and normalizes it before building a cache key. Insignificant
|
|
6
|
+
whitespace, field formatting, and fragment layout are collapsed, and variable
|
|
7
|
+
object keys are sorted. As a result, two requests that are semantically
|
|
8
|
+
identical share a cache entry even when their bodies differ byte-for-byte — and
|
|
9
|
+
there is no query size or nesting-depth limit.
|
|
10
|
+
|
|
11
|
+
Only `query` operations are cached. Mutations, subscriptions, malformed
|
|
12
|
+
documents, and non-GraphQL bodies are always forwarded to the origin untouched.
|
|
13
|
+
To avoid serving one user's data to another, requests carrying an
|
|
14
|
+
`authorization` or `cookie` header are not cached unless you opt in with the
|
|
15
|
+
`cacheKeyHeaders` option.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft-07/schema",
|
|
3
|
+
"$id": "https://cdn.zuplo.com/policies/graphql/schemas/graphql-cache-inbound.json",
|
|
4
|
+
"type": "object",
|
|
5
|
+
"title": "GraphQL Cache",
|
|
6
|
+
"isDeprecated": false,
|
|
7
|
+
"isPaidAddOn": false,
|
|
8
|
+
"isEnterprise": false,
|
|
9
|
+
"isInternal": false,
|
|
10
|
+
"isBeta": false,
|
|
11
|
+
"isHidden": false,
|
|
12
|
+
"requiresAI": false,
|
|
13
|
+
"products": ["api-gateway"],
|
|
14
|
+
"description": "Caches GraphQL query responses at the edge so identical queries are served without a round-trip to the origin.\n\nUnlike CDN caching that keys on the raw request body, this policy parses the GraphQL document and normalizes it before hashing: insignificant whitespace, field formatting, and fragment layout are collapsed, and variable object keys are sorted. Two requests that are semantically identical therefore share a cache entry even when their bodies differ byte-for-byte. There is no query size or nesting-depth limit.\n\nOnly `query` operations are cached. Mutations, subscriptions, malformed documents, and non-JSON bodies are forwarded to the origin untouched. Cache hits and misses are reported on the `x-cache` response header, with a short key fingerprint on `x-cache-key`.\n\nTo avoid serving one user's data to another, requests carrying an `authorization` or `cookie` header are not cached by default. Use `cacheKeyHeaders` to opt into caching them: each listed header's value is included in the cache key, so distinct credentials get distinct cache entries.",
|
|
15
|
+
"deprecatedMessage": "",
|
|
16
|
+
"required": ["handler"],
|
|
17
|
+
"properties": {
|
|
18
|
+
"handler": {
|
|
19
|
+
"type": "object",
|
|
20
|
+
"default": {},
|
|
21
|
+
"required": ["export", "module", "options"],
|
|
22
|
+
"properties": {
|
|
23
|
+
"export": {
|
|
24
|
+
"const": "GraphQLCacheInboundPolicy",
|
|
25
|
+
"description": "The name of the exported type"
|
|
26
|
+
},
|
|
27
|
+
"module": {
|
|
28
|
+
"const": "$import(@zuplo/graphql)",
|
|
29
|
+
"description": "The module containing the policy"
|
|
30
|
+
},
|
|
31
|
+
"options": {
|
|
32
|
+
"title": "GraphQLCacheInboundPolicyOptions",
|
|
33
|
+
"type": "object",
|
|
34
|
+
"description": "The options for this policy.",
|
|
35
|
+
"required": [],
|
|
36
|
+
"additionalProperties": false,
|
|
37
|
+
"properties": {
|
|
38
|
+
"cacheName": {
|
|
39
|
+
"type": "string",
|
|
40
|
+
"default": "graphql-responses",
|
|
41
|
+
"examples": ["graphql-responses"],
|
|
42
|
+
"description": "The name of the cache used to store responses. Routes that share a name share a cache; use distinct names to isolate caches per route or per upstream."
|
|
43
|
+
},
|
|
44
|
+
"ttlSeconds": {
|
|
45
|
+
"type": "number",
|
|
46
|
+
"default": 60,
|
|
47
|
+
"examples": [60],
|
|
48
|
+
"description": "How long, in seconds, a cached response is served before it is considered stale and the next request is forwarded to the origin to refresh the entry."
|
|
49
|
+
},
|
|
50
|
+
"cacheKeyHeaders": {
|
|
51
|
+
"type": "array",
|
|
52
|
+
"items": {
|
|
53
|
+
"type": "string"
|
|
54
|
+
},
|
|
55
|
+
"examples": [["authorization"]],
|
|
56
|
+
"description": "Request header names whose values are included in the cache key (matched case-insensitively), and the control for how credentialed requests are cached. Omit this option (the default) and requests carrying an `authorization` or `cookie` header are not cached, to avoid serving one user's response to another. List those headers to cache such requests keyed per value, so each distinct value gets its own entry (a credential header you don't list still blocks caching, so a partial list fails safe). Set it to an empty array `[]` to cache a single response shared across all callers — only do this when the response does not depend on who is calling, as it disables the per-user safety check."
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
"examples": [
|
|
62
|
+
{
|
|
63
|
+
"export": "GraphQLCacheInboundPolicy",
|
|
64
|
+
"module": "$import(@zuplo/graphql)",
|
|
65
|
+
"options": {
|
|
66
|
+
"cacheKeyHeaders": ["authorization"],
|
|
67
|
+
"cacheName": "graphql-responses",
|
|
68
|
+
"ttlSeconds": 60
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "zuplo",
|
|
3
|
-
"version": "6.71.
|
|
3
|
+
"version": "6.71.22",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "The programmable API Gateway",
|
|
6
6
|
"author": "Zuplo, Inc.",
|
|
@@ -19,9 +19,9 @@
|
|
|
19
19
|
"zuplo": "zuplo.js"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@zuplo/cli": "6.71.
|
|
23
|
-
"@zuplo/core": "6.71.
|
|
24
|
-
"@zuplo/runtime": "6.71.
|
|
22
|
+
"@zuplo/cli": "6.71.22",
|
|
23
|
+
"@zuplo/core": "6.71.22",
|
|
24
|
+
"@zuplo/runtime": "6.71.22",
|
|
25
25
|
"@zuplo/test": "1.4.0"
|
|
26
26
|
}
|
|
27
27
|
}
|