@alxia/graphql 0.16.5 → 0.18.0
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/README.md +60 -62
- package/dist/endpoint.d.ts +14 -2
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/executor.d.ts +20 -37
- package/dist/executor.d.ts.map +1 -1
- package/dist/explorer.d.ts +24 -0
- package/dist/explorer.d.ts.map +1 -0
- package/dist/graphql.d.ts +32 -95
- package/dist/graphql.d.ts.map +1 -1
- package/dist/handler.d.ts +7 -34
- package/dist/handler.d.ts.map +1 -1
- package/dist/index.d.ts +3 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +301 -1011
- package/dist/index.js.map +14 -23
- package/dist/once-per-request.d.ts +5 -0
- package/dist/once-per-request.d.ts.map +1 -1
- package/dist/operation.d.ts +2 -7
- package/dist/operation.d.ts.map +1 -1
- package/dist/options.d.ts +38 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/removed.d.ts +14 -0
- package/dist/removed.d.ts.map +1 -0
- package/dist/sandbox.d.ts +3 -17
- package/dist/sandbox.d.ts.map +1 -1
- package/dist/testing/client.d.ts +9 -7
- package/dist/testing/client.d.ts.map +1 -1
- package/dist/testing/index.js +5 -1
- package/dist/testing/index.js.map +3 -3
- package/dist/ws.d.ts +18 -30
- package/dist/ws.d.ts.map +1 -1
- package/docs/README.md +3 -2
- package/docs/guide/context.md +40 -32
- package/docs/guide/endpoint.md +42 -27
- package/docs/guide/executor.md +23 -8
- package/docs/guide/ide.md +27 -64
- package/docs/guide/{yoga.md → plugins.md} +87 -72
- package/docs/guide/production.md +115 -196
- package/docs/guide/testing.md +24 -24
- package/docs/guide/websockets.md +21 -14
- package/docs/migrating-to-graxia.md +283 -0
- package/docs/roadmap.md +7 -11
- package/docs/troubleshooting.md +231 -248
- package/package.json +15 -22
- package/dist/body-refusal.d.ts +0 -25
- package/dist/body-refusal.d.ts.map +0 -1
- package/dist/document-cache.d.ts +0 -39
- package/dist/document-cache.d.ts.map +0 -1
- package/dist/field-rate-limit/count.d.ts +0 -28
- package/dist/field-rate-limit/count.d.ts.map +0 -1
- package/dist/field-rate-limit/from-store.d.ts +0 -21
- package/dist/field-rate-limit/from-store.d.ts.map +0 -1
- package/dist/field-rate-limit/index.d.ts +0 -5
- package/dist/field-rate-limit/index.d.ts.map +0 -1
- package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
- package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
- package/dist/field-rate-limit/plugin.d.ts +0 -28
- package/dist/field-rate-limit/plugin.d.ts.map +0 -1
- package/dist/field-rate-limit/types.d.ts +0 -60
- package/dist/field-rate-limit/types.d.ts.map +0 -1
- package/dist/nesting.d.ts +0 -18
- package/dist/nesting.d.ts.map +0 -1
- package/dist/parse-limits.d.ts +0 -50
- package/dist/parse-limits.d.ts.map +0 -1
- package/dist/same-origin/index.d.ts +0 -2
- package/dist/same-origin/index.d.ts.map +0 -1
- package/dist/same-origin/same-origin.d.ts +0 -30
- package/dist/same-origin/same-origin.d.ts.map +0 -1
- package/dist/ws-operations.d.ts +0 -31
- package/dist/ws-operations.d.ts.map +0 -1
- package/dist/ws-server.d.ts +0 -32
- package/dist/ws-server.d.ts.map +0 -1
- package/dist/yoga.d.ts +0 -12
- package/dist/yoga.d.ts.map +0 -1
package/docs/troubleshooting.md
CHANGED
|
@@ -3,19 +3,25 @@
|
|
|
3
3
|
Each entry is headed by the text you see: a TypeScript error, an exception
|
|
4
4
|
thrown when the app is built, or a response from the endpoint. Problems that
|
|
5
5
|
show no message, or only the browser's, are under [Traps](#traps), by
|
|
6
|
-
symptom.
|
|
6
|
+
symptom. Coming from the Yoga-based releases, read
|
|
7
|
+
[Migrating to graxia](migrating-to-graxia.md) first.
|
|
7
8
|
|
|
8
9
|
**Install**
|
|
9
10
|
|
|
10
|
-
- [`Cannot find package '
|
|
11
|
-
|
|
11
|
+
- [`Cannot find package '@graxia/core' from '…/@alxia/graphql/dist/index.js'`](#cannot-find-package-graxiacore-from-alxiagraphqldistindexjs)
|
|
12
|
+
|
|
13
|
+
**CSRF**
|
|
14
|
+
|
|
15
|
+
- [`CSRF_HEADER_REQUIRED`](#csrf_header_required)
|
|
16
|
+
- [`sameOrigin` or `renderSandbox` is not exported](#sameorigin-or-rendersandbox-is-not-exported)
|
|
17
|
+
- [`graphql(app, { logging })`, `requestId` or `cors` throws a `TypeError`](#graphqlapp--logging--requestid-or-cors-throws-a-typeerror)
|
|
12
18
|
|
|
13
19
|
**Types**
|
|
14
20
|
|
|
15
21
|
- [`the schema's resolvers read a context the app does not build: missing …`](#the-schemas-resolvers-read-a-context-the-app-does-not-build-missing-)
|
|
16
|
-
- [`Property 'viewer' does not exist on type '{ readonly '~error': "GraphQLContext needs the type of an app: GraphQLContext<typeof app>"; } &
|
|
17
|
-
- [`Property 'viewer' does not exist on type '
|
|
18
|
-
- [`Property 'query' does not exist on type '
|
|
22
|
+
- [`Property 'viewer' does not exist on type '{ readonly '~error': "GraphQLContext needs the type of an app: GraphQLContext<typeof app>"; } & GraphQLWsContext'`](#property-viewer-does-not-exist-on-type--readonly-error-graphqlcontext-needs-the-type-of-an-app-graphqlcontexttypeof-app---graphqlwscontext)
|
|
23
|
+
- [`Property 'viewer' does not exist on type 'CoreContext'`](#property-viewer-does-not-exist-on-type-corecontext)
|
|
24
|
+
- [`Property 'query' does not exist on type 'CoreContext & ServerContext<…>'`](#property-query-does-not-exist-on-type-corecontext--servercontext)
|
|
19
25
|
- [`Type 'true' is not assignable to type 'GraphiQLOptions | GraphiQLOptionsFactory<…> | undefined'`](#type-true-is-not-assignable-to-type-graphiqloptions--graphiqloptionsfactory--undefined)
|
|
20
26
|
- [`'graphqlEndpoint' does not exist in type 'GraphQLOptions<…>'`](#graphqlendpoint-does-not-exist-in-type-graphqloptions)
|
|
21
27
|
- [``Type '"gql"' is not assignable to type '`/${string}`'``](#type-gql-is-not-assignable-to-type-string)
|
|
@@ -23,30 +29,32 @@ symptom.
|
|
|
23
29
|
**Startup**
|
|
24
30
|
|
|
25
31
|
- [`TypeError: GET /graphql is declared twice`](#typeerror-get-graphql-is-declared-twice)
|
|
26
|
-
- [`
|
|
27
|
-
- [`TypeError: graphql(app, { ws: { keepAlive: 0 } }): keepAlive is the milliseconds between pings, a positive number, or false for none`](#typeerror-graphqlapp--ws--keepalive-0---keepalive-is-the-milliseconds-between-pings-a-positive-number-or-false-for-none)
|
|
32
|
+
- [`GraxiaConfigError: limits.bodyBytes must be a positive integer`](#graxiaconfigerror-limitsbodybytes-must-be-a-positive-integer)
|
|
33
|
+
- [`TypeError: graphql(app, { ws: { keepAlive: 0 } }): keepAlive is the milliseconds between pings, a positive number up to 2147483647, or false for none`](#typeerror-graphqlapp--ws--keepalive-0---keepalive-is-the-milliseconds-between-pings-a-positive-number-up-to-2147483647-or-false-for-none)
|
|
28
34
|
|
|
29
35
|
**Responses**
|
|
30
36
|
|
|
31
|
-
- [`x-request-id` echoed, or `Request processed` logged, on Yoga 6](#x-request-id-echoed-or-request-processed-logged-on-yoga-6)
|
|
32
|
-
- [`log.child is not a function`](#logchild-is-not-a-function)
|
|
33
37
|
- [`200 {"errors":[{"message":"Unexpected error.", … "code":"INTERNAL_SERVER_ERROR"}}]}`](#200-errorsmessageunexpected-error--codeinternal_server_error)
|
|
34
|
-
- [`403
|
|
35
|
-
- [`PersistedQueryNotFound` or `
|
|
38
|
+
- [`403 CSRF_HEADER_REQUIRED` from the test client](#403-csrf_header_required-from-the-test-client)
|
|
39
|
+
- [`PersistedQueryNotFound` or `PersistedQueryNotSupported`](#persistedquerynotfound-or-persistedquerynotsupported)
|
|
36
40
|
- [`405 {"error":"method_not_allowed"}` on `OPTIONS /graphql`](#405-errormethod_not_allowed-on-options-graphql)
|
|
37
41
|
- [`405 {"errors":[{"message":"Can only perform a mutation operation from a POST request."}]}`](#405-errorsmessagecan-only-perform-a-mutation-operation-from-a-post-request)
|
|
38
42
|
- [`406` with an empty body](#406-with-an-empty-body)
|
|
39
|
-
- [`413
|
|
40
|
-
- [`
|
|
43
|
+
- [`413 … "code":"BODY_TOO_LARGE"` on `POST /graphql`](#413--codebody_too_large-on-post-graphql)
|
|
44
|
+
- [`415 … "code":"UNSUPPORTED_MEDIA_TYPE"`](#415--codeunsupported_media_type)
|
|
45
|
+
- [`Subscriptions are not supported over this transport (subscriptions.sse is false).`](#subscriptions-are-not-supported-over-this-transport-subscriptionssse-is-false)
|
|
46
|
+
- [`The operation was aborted.` from `graphqlExecutor`](#the-operation-was-aborted-from-graphqlexecutor)
|
|
41
47
|
- [`Syntax Error: Document contains more than 15000 tokens. Parsing aborted.`](#syntax-error-document-contains-more-than-15000-tokens-parsing-aborted)
|
|
42
48
|
- [`Syntax Error: Document is nested more than 1000 levels deep. Parsing aborted.`](#syntax-error-document-is-nested-more-than-1000-levels-deep-parsing-aborted)
|
|
43
49
|
- [`Syntax Error: Document is nested too deeply to parse.`](#syntax-error-document-is-nested-too-deeply-to-parse)
|
|
44
|
-
- [`{"errors":[{"message":"Must provide query string."}]}`](#errorsmessagemust-provide-query-string)
|
|
45
|
-
- [
|
|
50
|
+
- [`{"errors":[{"message":"Must provide a query string."}]}`](#errorsmessagemust-provide-a-query-string)
|
|
51
|
+
- [A WebSocket closes with 4400 after the first message](#a-websocket-closes-with-4400-after-the-first-message)
|
|
52
|
+
- [`The Sec-WebSocket-Protocol header must offer "graphql-transport-ws".`](#the-sec-websocket-protocol-header-must-offer-graphql-transport-ws-400-subprotocol_required)
|
|
46
53
|
|
|
47
54
|
**Traps**
|
|
48
55
|
|
|
49
56
|
- [The endpoint answers without a guard declared after it](#the-endpoint-answers-without-a-guard-declared-after-it)
|
|
57
|
+
- [graxia's parse, validate or resolver spans are missing](#graxias-parse-validate-or-resolver-spans-are-missing)
|
|
50
58
|
- [The logger, CORS or secure headers miss the endpoint](#the-logger-cors-or-secure-headers-miss-the-endpoint)
|
|
51
59
|
- [An anonymous request to a missing path is a 401](#an-anonymous-request-to-a-missing-path-is-a-401)
|
|
52
60
|
- [A WebSocket client cannot connect: `Expected 101 status code`](#a-websocket-client-cannot-connect-expected-101-status-code)
|
|
@@ -57,60 +65,43 @@ symptom.
|
|
|
57
65
|
|
|
58
66
|
## Install
|
|
59
67
|
|
|
60
|
-
### `Cannot find package '
|
|
68
|
+
### `Cannot find package '@graxia/core' from '…/@alxia/graphql/dist/index.js'`
|
|
61
69
|
|
|
62
70
|
**When:** importing `@alxia/graphql`, before any of your code runs. The same
|
|
63
|
-
message names `graphql` when that one is missing; `tsc`
|
|
64
|
-
`TS2307: Cannot find module '
|
|
71
|
+
message names `@graxia/graphiql` or `graphql` when that one is missing; `tsc`
|
|
72
|
+
reports either as `TS2307: Cannot find module '@graxia/core'`.
|
|
65
73
|
|
|
66
|
-
**Why:** `
|
|
67
|
-
dependency, so the app installs them.
|
|
74
|
+
**Why:** `@graxia/core`, `@graxia/graphiql` and `graphql` are peers: the
|
|
75
|
+
package declares no dependency, so the app installs them.
|
|
68
76
|
|
|
69
77
|
**Fix:**
|
|
70
78
|
|
|
71
79
|
```sh
|
|
72
|
-
bun add @alxia/graphql
|
|
80
|
+
bun add @alxia/graphql @graxia/core @graxia/graphiql graphql
|
|
73
81
|
```
|
|
74
82
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
incorrect peer. `bun add graphql-yoga@latest` updates it.
|
|
78
|
-
|
|
79
|
-
### `@alxia/graphql: graphql(app, { ws }) serves GraphQL over WebSocket with the optional peer graphql-ws, which is not installed: bun add graphql-ws`
|
|
80
|
-
|
|
81
|
-
**When:** a client opens a socket on an endpoint mounted with `ws` on. The
|
|
82
|
-
upgrade is answered with a `500`, and the server logs this error; the
|
|
83
|
-
client sees its socket fail to open (`Expected 101 status code` in Bun).
|
|
84
|
-
|
|
85
|
-
**Why:** `graphql-ws` is an optional peer, loaded on the first upgrade: an
|
|
86
|
-
app that leaves `ws` off never needs it, so it is not installed with
|
|
87
|
-
`@alxia/graphql`.
|
|
83
|
+
`@graxia/core` must be 0.10 or later. After a move from Yoga,
|
|
84
|
+
`bun remove graphql-yoga graphql-ws` ([Migrating to graxia](migrating-to-graxia.md)).
|
|
88
85
|
|
|
89
|
-
|
|
86
|
+
## CSRF
|
|
90
87
|
|
|
91
|
-
|
|
92
|
-
bun add graphql-ws
|
|
93
|
-
```
|
|
88
|
+
### `CSRF_HEADER_REQUIRED`
|
|
94
89
|
|
|
95
|
-
|
|
90
|
+
A `GET`, or a `POST` that is not JSON, was answered 403: it carries none of
|
|
91
|
+
the CSRF headers graxia asks for by default. Send one of `x-graphql-csrf`,
|
|
92
|
+
`graphql-require-preflight`, `apollo-require-preflight` or
|
|
93
|
+
`x-apollo-operation-name`, or set `csrf: false` on `graphql()`.
|
|
96
94
|
|
|
97
|
-
### `
|
|
95
|
+
### `sameOrigin` or `renderSandbox` is not exported
|
|
98
96
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
sibling or a CORS-enabled origin), or it is a `POST` that is not
|
|
102
|
-
`application/json`. Name the origin, or send JSON:
|
|
97
|
+
Both were removed with Yoga. The origin check is graxia's `csrf: { sameOrigin: true }`
|
|
98
|
+
(off by default; the CSRF header check is on); the Sandbox page is `ide: 'apollo-sandbox'`.
|
|
103
99
|
|
|
104
|
-
|
|
105
|
-
import { sameOrigin } from '@alxia/graphql';
|
|
100
|
+
### `graphql(app, { logging })`, `requestId` or `cors` throws a `TypeError`
|
|
106
101
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
### `sameOrigin({ allow }): "…" is neither an origin nor a host`
|
|
111
|
-
|
|
112
|
-
An `allow` entry is empty or an origin that does not parse. Give
|
|
113
|
-
`https://app.example.com` or `app.example.com`.
|
|
102
|
+
These options were Yoga's and are gone. Unexpected failures go to
|
|
103
|
+
`onUnexpected` (`console.error`, off in production); log requests with
|
|
104
|
+
`@alxia/logger`; mount `@alxia/cors` on the app before `graphql()`.
|
|
114
105
|
|
|
115
106
|
## Types
|
|
116
107
|
|
|
@@ -137,7 +128,7 @@ middlewares ([The typed context](guide/context.md)):
|
|
|
137
128
|
|
|
138
129
|
```ts
|
|
139
130
|
const base = alxia().use(bearer({ jwt })); // adds user
|
|
140
|
-
const schema = createSchema<GraphQLContext<typeof base>>({ … });
|
|
131
|
+
const schema = createSchema<GraphQLContext<typeof base>>()({ … });
|
|
141
132
|
const app = base.plugin((app) => graphql(app, { schema })); // not alxia().plugin(…)
|
|
142
133
|
```
|
|
143
134
|
|
|
@@ -153,9 +144,9 @@ graphql(app, {
|
|
|
153
144
|
});
|
|
154
145
|
```
|
|
155
146
|
|
|
156
|
-
### `Property 'viewer' does not exist on type '{ readonly '~error': "GraphQLContext needs the type of an app: GraphQLContext<typeof app>"; } &
|
|
147
|
+
### `Property 'viewer' does not exist on type '{ readonly '~error': "GraphQLContext needs the type of an app: GraphQLContext<typeof app>"; } & GraphQLWsContext'`
|
|
157
148
|
|
|
158
|
-
**When:** a resolver of a schema typed `createSchema<GraphQLContext<X
|
|
149
|
+
**When:** a resolver of a schema typed `createSchema<GraphQLContext<X>>()`
|
|
159
150
|
reads a field, and `X` is not an alxia app: a function returning one, a
|
|
160
151
|
schema, a route. Passed to `graphql(app, { schema })` anyway, the schema is
|
|
161
152
|
refused with `missing ~error`.
|
|
@@ -168,32 +159,32 @@ anything else, it is this message, and holds none of the app's fields.
|
|
|
168
159
|
```ts
|
|
169
160
|
const makeApp = () => alxia().decorate({ users });
|
|
170
161
|
const base = makeApp();
|
|
171
|
-
createSchema<GraphQLContext<typeof base>>({ … }); // not GraphQLContext<typeof makeApp>
|
|
162
|
+
createSchema<GraphQLContext<typeof base>>()({ … }); // not GraphQLContext<typeof makeApp>
|
|
172
163
|
```
|
|
173
164
|
|
|
174
|
-
### `Property 'viewer' does not exist on type '
|
|
165
|
+
### `Property 'viewer' does not exist on type 'CoreContext'`
|
|
175
166
|
|
|
176
|
-
**When:** a resolver of a schema created with `createSchema({ … })`, no type
|
|
167
|
+
**When:** a resolver of a schema created with `createSchema()({ … })`, no type
|
|
177
168
|
argument, reads what the app's middlewares add.
|
|
178
169
|
|
|
179
|
-
**Why:** an untyped schema's context is
|
|
170
|
+
**Why:** an untyped schema's context is graxia's alone (`signal`). The field is there at
|
|
180
171
|
runtime; its type is not.
|
|
181
172
|
|
|
182
173
|
**Fix:**
|
|
183
174
|
|
|
184
175
|
```ts
|
|
185
|
-
const schema = createSchema<GraphQLContext<typeof base>>({ … });
|
|
176
|
+
const schema = createSchema<GraphQLContext<typeof base>>()({ … });
|
|
186
177
|
```
|
|
187
178
|
|
|
188
|
-
### `Property 'query' does not exist on type '
|
|
179
|
+
### `Property 'query' does not exist on type 'CoreContext & ServerContext<…>'`
|
|
189
180
|
|
|
190
181
|
**When:** a resolver reads `query`, `headers`, `cookies`, `body`, `reply` or
|
|
191
182
|
`redirect` from its context, as a route handler would.
|
|
192
183
|
|
|
193
184
|
**Why:** those are the route's, and mean nothing to a resolver: the request
|
|
194
185
|
is a GraphQL request, and a resolver answers a field, not the request.
|
|
195
|
-
`params` is there
|
|
196
|
-
|
|
186
|
+
`params` is not there either: graxia no longer spreads the request, its
|
|
187
|
+
params, headers or cookies into the context.
|
|
197
188
|
|
|
198
189
|
**Fix:** read a header or a cookie from `request`, and set them on the
|
|
199
190
|
response with `set`:
|
|
@@ -225,14 +216,14 @@ graphql(app, { schema, ide: false });
|
|
|
225
216
|
|
|
226
217
|
### `'graphqlEndpoint' does not exist in type 'GraphQLOptions<…>'`
|
|
227
218
|
|
|
228
|
-
**When:** passing Yoga's
|
|
219
|
+
**When:** passing `graphqlEndpoint`, Yoga's option.
|
|
229
220
|
|
|
230
221
|
```text
|
|
231
222
|
error TS2353: Object literal may only specify known properties, and 'graphqlEndpoint' does not exist in type 'GraphQLOptions<…>'.
|
|
232
223
|
```
|
|
233
224
|
|
|
234
225
|
**Why:** the endpoint is a route of the app, and its path is joined to the
|
|
235
|
-
app's prefix;
|
|
226
|
+
app's prefix; graxia is told the result.
|
|
236
227
|
|
|
237
228
|
**Fix:**
|
|
238
229
|
|
|
@@ -284,7 +275,7 @@ const fakeViewer = defineMiddleware((_ctx, next) => next({ viewer: { id: 'ada' }
|
|
|
284
275
|
const testApp = base.fork().use(fakeViewer).plugin((app) => graphql(app, { schema }));
|
|
285
276
|
```
|
|
286
277
|
|
|
287
|
-
### `TypeError: graphql(app, { ws: { keepAlive: 0 } }): keepAlive is the milliseconds between pings, a positive number, or false for none`
|
|
278
|
+
### `TypeError: graphql(app, { ws: { keepAlive: 0 } }): keepAlive is the milliseconds between pings, a positive number up to 2147483647, or false for none`
|
|
288
279
|
|
|
289
280
|
**When:** declaring `graphql(app, { ws: { keepAlive } })` with `0`, a
|
|
290
281
|
negative number, `NaN` or `Infinity` — anything but a finite positive number; the message names the value given.
|
|
@@ -298,58 +289,25 @@ ping in a loop.
|
|
|
298
289
|
graphql(app, { schema, ws: { keepAlive: 30_000 } });
|
|
299
290
|
```
|
|
300
291
|
|
|
301
|
-
### `
|
|
292
|
+
### `GraxiaConfigError: limits.bodyBytes must be a positive integer`
|
|
302
293
|
|
|
303
|
-
**When:** declaring `graphql(app, { bodyLimit })`
|
|
304
|
-
fraction, `NaN`, `Infinity` or a string
|
|
305
|
-
endpoint's `path`) and the value given.
|
|
294
|
+
**When:** declaring `graphql(app, { bodyLimit })` (or `limits: { bodyBytes }`)
|
|
295
|
+
with `0`, a negative number, a fraction, `NaN`, `Infinity` or a string.
|
|
306
296
|
|
|
307
|
-
**Why:** `bodyLimit` is a count of bytes
|
|
308
|
-
is declared.
|
|
297
|
+
**Why:** `bodyLimit` is graxia's `limits.bodyBytes`, a count of bytes that
|
|
298
|
+
graxia checks where `graphql()` is declared.
|
|
309
299
|
|
|
310
|
-
**Fix:** a whole number of bytes
|
|
300
|
+
**Fix:** a positive whole number of bytes:
|
|
311
301
|
|
|
312
302
|
```ts
|
|
313
303
|
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
314
304
|
```
|
|
315
305
|
|
|
316
|
-
### `
|
|
317
|
-
|
|
318
|
-
**When:** declaring `graphql(app, { maxTokens })` with `0`, a negative number,
|
|
319
|
-
a fraction, `NaN` or a string; the message names the value given.
|
|
320
|
-
|
|
321
|
-
**Why:** `maxTokens` is a count of tokens.
|
|
322
|
-
|
|
323
|
-
**Fix:** a positive whole number, or `false` for no cap:
|
|
324
|
-
|
|
325
|
-
```ts
|
|
326
|
-
graphql(app, { schema, maxTokens: 30_000 });
|
|
327
|
-
```
|
|
328
|
-
|
|
329
|
-
### `TypeError: graphql(app, { parseCache, parserAndValidationCache }): give one: …`, `parseCache.maxBytes`, `parseCache.max` or `parseCache.ttl … a positive whole number`, or `parseCache is an object of cache sizes …`
|
|
330
|
-
|
|
331
|
-
**When:** declaring `graphql()` with both `parseCache` and Yoga's
|
|
332
|
-
`parserAndValidationCache`, or with a `parseCache.maxBytes`, `max` or `ttl`
|
|
333
|
-
that is not a positive whole number, or with a `parseCache` that is neither
|
|
334
|
-
an object nor `false` (`true`, `null`, a number, a string).
|
|
335
|
-
|
|
336
|
-
**Why:** `parseCache` sizes alxia's bounded cache and
|
|
337
|
-
`parserAndValidationCache` replaces it with yours, so the two cannot both
|
|
338
|
-
apply.
|
|
339
|
-
|
|
340
|
-
**Fix:** give one:
|
|
341
|
-
|
|
342
|
-
```ts
|
|
343
|
-
graphql(app, { schema, parseCache: { maxBytes: 16 * 1024 * 1024 } });
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
## Responses
|
|
347
|
-
|
|
348
|
-
### `graphqlExecutor runs queries and mutations, not a subscription.`
|
|
306
|
+
### `Subscriptions are not supported over this transport (subscriptions.sse is false).`
|
|
349
307
|
|
|
350
308
|
**When:** `graphqlExecutor(...)` is given a document whose operation is a
|
|
351
309
|
subscription; the answer is `{ errors: [{ extensions: { code:
|
|
352
|
-
'SUBSCRIPTION_NOT_SUPPORTED' } }] }
|
|
310
|
+
'SUBSCRIPTION_NOT_SUPPORTED' } }] }`, graxia's refusal.
|
|
353
311
|
|
|
354
312
|
**Why:** the executor answers once, with the endpoint's JSON body. A
|
|
355
313
|
subscription streams.
|
|
@@ -358,7 +316,7 @@ subscription streams.
|
|
|
358
316
|
`ws: true`), and use the executor for queries and mutations
|
|
359
317
|
([guide](guide/executor.md)).
|
|
360
318
|
|
|
361
|
-
### `Too many
|
|
319
|
+
### `Too many requests, try again later.` (`RATE_LIMITED`, 429)
|
|
362
320
|
|
|
363
321
|
**When:** an operation selects a field given to `fieldRateLimit` more often
|
|
364
322
|
than its limit allows; nothing executed. `extensions.retryAfter` and the
|
|
@@ -374,7 +332,7 @@ spent.
|
|
|
374
332
|
**Fix:** wait, or raise the limit. A client that really needs several
|
|
375
333
|
selections sends them over several requests.
|
|
376
334
|
|
|
377
|
-
### `<field> may be selected once per operation
|
|
335
|
+
### `<field> may be selected once per operation.` (`FIELD_SELECTED_ONCE`, 400)
|
|
378
336
|
|
|
379
337
|
**When:** a field declared `{ limit, single: true }` is written more than once
|
|
380
338
|
in the executed operation, with another response key or other arguments;
|
|
@@ -383,53 +341,81 @@ counts once.
|
|
|
383
341
|
|
|
384
342
|
**Fix:** select the field once per operation.
|
|
385
343
|
|
|
386
|
-
### `
|
|
344
|
+
### `GraxiaConfigError: fieldRateLimit: fields must be an object with at least one field name`
|
|
387
345
|
|
|
388
346
|
**When:** `fieldRateLimit` is declared with no `fields`, or with none inside.
|
|
389
347
|
|
|
390
348
|
**Fix:** name the fields to count: `fieldRateLimit({ fields: { signIn: limit } })`.
|
|
391
349
|
|
|
392
|
-
### `
|
|
350
|
+
### `GraxiaConfigError: fieldRateLimit: fields.signIn must be a limit ({ consume }) or { limit, single? }`
|
|
393
351
|
|
|
394
352
|
**When:** a field's value is neither a limit nor `{ limit, single? }`, a
|
|
395
|
-
`RateLimitStore` passed as it is, say.
|
|
353
|
+
`RateLimitStore` passed as it is, say. The name in the message is the field's.
|
|
396
354
|
|
|
397
355
|
**Fix:** adapt the store with `limitFromStore(store, { limit, windowMs })`, or
|
|
398
356
|
give an object with `consume(key, cost)`.
|
|
399
357
|
|
|
400
|
-
### `
|
|
358
|
+
### `GraxiaConfigError: fieldRateLimit: ipv6Prefix must be an integer from 0 to 128`
|
|
401
359
|
|
|
402
360
|
**When:** `ipv6Prefix` is not a whole number from 0 to 128.
|
|
403
361
|
|
|
404
362
|
**Fix:** use `64` for a subscriber's network, or leave it out to count each address.
|
|
405
363
|
|
|
406
|
-
### `
|
|
364
|
+
### `GraxiaConfigError: fieldRateLimit: ipv6Prefix only applies to the default key; reduce the address inside key() instead`
|
|
407
365
|
|
|
408
366
|
**When:** `fieldRateLimit` is given both `ipv6Prefix` and `key`.
|
|
409
367
|
|
|
410
368
|
**Fix:** drop one, or group the address in your own key with `ipv6Network` from `@alxia/rate-limit`.
|
|
411
369
|
|
|
412
|
-
### `
|
|
370
|
+
### `GraxiaConfigError: fieldRateLimit: code must be a non-empty string`
|
|
413
371
|
|
|
414
372
|
**When:** `code` is an empty string or not a string.
|
|
415
373
|
|
|
416
374
|
**Fix:** give the `extensions.code` you want, or leave it out for `RATE_LIMITED`.
|
|
417
375
|
|
|
418
|
-
### `
|
|
376
|
+
### `GraxiaConfigError: limitFromStore: limit must be an integer of 1 or more`
|
|
419
377
|
|
|
420
378
|
**When:** `limitFromStore` is given a `limit` or `windowMs` that is not a whole
|
|
421
|
-
number of 1 or more
|
|
422
|
-
|
|
379
|
+
number of 1 or more (the message names the one at fault).
|
|
380
|
+
|
|
381
|
+
**Fix:** give whole numbers of 1 or more.
|
|
382
|
+
|
|
383
|
+
### `GraxiaConfigError: limitFromStore: no policy; pass { limit, windowMs } or give the store a policy`
|
|
384
|
+
|
|
385
|
+
**When:** the store has no `policy` and `limitFromStore` was not given both
|
|
386
|
+
`limit` and `windowMs`.
|
|
387
|
+
|
|
388
|
+
**Fix:** pass `{ limit, windowMs }`, or use a store that carries its policy.
|
|
389
|
+
|
|
390
|
+
### `GraxiaConfigError: limitFromStore: limit 5 differs from the store policy's limit 3`
|
|
391
|
+
|
|
392
|
+
**When:** the numbers given disagree with the store's own `policy` (`limit` or
|
|
393
|
+
`windowMs`, the message names it and both values).
|
|
394
|
+
|
|
395
|
+
**Fix:** leave the policy out for a store that has one, or give the same numbers.
|
|
396
|
+
|
|
397
|
+
### `The operation was aborted.` from `graphqlExecutor`
|
|
398
|
+
|
|
399
|
+
**When:** a call with a `signal` that aborted (before the call, or while it
|
|
400
|
+
ran) no longer rejects; a spec or a caller that expects a rejection fails.
|
|
401
|
+
|
|
402
|
+
**Why:** the executor resolves `{ errors: [{ extensions: { code: 'OPERATION_ABORTED' } }] }`,
|
|
403
|
+
with no `data`, as the endpoint answers a client that left.
|
|
423
404
|
|
|
424
|
-
**Fix:**
|
|
405
|
+
**Fix:** read the code instead of catching:
|
|
406
|
+
|
|
407
|
+
```ts
|
|
408
|
+
const { errors } = await execute(request, context, { signal });
|
|
409
|
+
if (errors?.[0]?.extensions?.code === 'OPERATION_ABORTED') return;
|
|
410
|
+
```
|
|
425
411
|
|
|
426
412
|
### `Syntax Error: Document contains more than 15000 tokens. Parsing aborted.`
|
|
427
413
|
|
|
428
414
|
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
|
|
429
415
|
`application/graphql-response+json`, 200 under `application/json`) and this
|
|
430
|
-
message.
|
|
416
|
+
message.
|
|
431
417
|
|
|
432
|
-
**Why:** a document may hold 15 000 tokens by default (`
|
|
418
|
+
**Why:** a document may hold 15 000 tokens by default (`limits.tokens`),
|
|
433
419
|
so that no request makes the server parse and keep an unbounded one. A
|
|
434
420
|
generated query or a screen with many inlined fragments can pass it; a
|
|
435
421
|
client that worked before is refused.
|
|
@@ -439,7 +425,7 @@ off. Persisted operations keep clients from sending large documents at all
|
|
|
439
425
|
([Persisted operations](guide/production.md#persisted-operations-briefly)):
|
|
440
426
|
|
|
441
427
|
```ts
|
|
442
|
-
graphql(app, { schema,
|
|
428
|
+
graphql(app, { schema, limits: { tokens: 30_000 } }); // or false
|
|
443
429
|
```
|
|
444
430
|
|
|
445
431
|
### `Syntax Error: Document is nested more than 1000 levels deep. Parsing aborted.`
|
|
@@ -450,8 +436,8 @@ message. A document that overflowed the stack anyway has
|
|
|
450
436
|
[its own entry](#syntax-error-document-is-nested-too-deeply-to-parse).
|
|
451
437
|
|
|
452
438
|
**Why:** a document may nest 1 000 levels of `{`, `(` and `[` by default
|
|
453
|
-
(`
|
|
454
|
-
thousand levels down, under `
|
|
439
|
+
(`limits.nesting`). graphql-js parses by recursion and overflows the stack a few
|
|
440
|
+
thousand levels down, under `limits.tokens`; without the limit that was a 500
|
|
455
441
|
`Unexpected error.`, logged. A real query nests a dozen levels, so this is
|
|
456
442
|
a hostile or generated document.
|
|
457
443
|
|
|
@@ -460,7 +446,7 @@ what your runtime's stack parses (several thousand levels: about 10 000 on
|
|
|
460
446
|
Bun's main thread, fewer in a Worker), or turn it off:
|
|
461
447
|
|
|
462
448
|
```ts
|
|
463
|
-
graphql(app, { schema,
|
|
449
|
+
graphql(app, { schema, limits: { nesting: 2_000 } }); // or false
|
|
464
450
|
```
|
|
465
451
|
|
|
466
452
|
### `Syntax Error: Document is nested too deeply to parse.`
|
|
@@ -468,7 +454,7 @@ graphql(app, { schema, maxNesting: 2_000 }); // or false
|
|
|
468
454
|
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` and this message.
|
|
469
455
|
|
|
470
456
|
**Why:** graphql-js parsed the document by recursion and the call stack
|
|
471
|
-
overflowed, either because `
|
|
457
|
+
overflowed, either because `limits.nesting` is `false` or raised past what the
|
|
472
458
|
runtime parses. The stack is smaller in a Worker or under load than on Bun's
|
|
473
459
|
main thread, so the depth that fails varies. The overflow is refused as any
|
|
474
460
|
unparsable document is, never a 500.
|
|
@@ -478,91 +464,43 @@ document. If it is legitimate, keep the limit (the default is 1 000) or set
|
|
|
478
464
|
one your runtime parses:
|
|
479
465
|
|
|
480
466
|
```ts
|
|
481
|
-
graphql(app, { schema,
|
|
482
|
-
```
|
|
483
|
-
|
|
484
|
-
### `TypeError: graphql(app, { maxNesting }): maxNesting is the most levels of { ( [ a document may nest, a positive whole number, or false for none; got …`
|
|
485
|
-
|
|
486
|
-
**When:** declaring `graphql(app, { maxNesting })` with `0`, a negative number,
|
|
487
|
-
a fraction, `NaN` or a string.
|
|
488
|
-
|
|
489
|
-
**Why:** `maxNesting` is a count of nesting levels.
|
|
490
|
-
|
|
491
|
-
**Fix:** a positive whole number, or `false` for no limit.
|
|
492
|
-
|
|
493
|
-
### `x-request-id` echoed, or `Request processed` logged, on Yoga 6
|
|
494
|
-
|
|
495
|
-
**When:** with `@alxia/graphql` 0.13.0 and below on `graphql-yoga` 6, a request
|
|
496
|
-
carrying `x-request-id: forged` is answered with that header and logged with
|
|
497
|
-
`requestId: "forged"`, and every request logs an INFO `Request processed` line.
|
|
498
|
-
|
|
499
|
-
**Why:** Yoga 6 trusts the incoming header by default and logs at INFO when
|
|
500
|
-
`logging` is not set. Yoga 5 has no request id option, and logs no such line.
|
|
501
|
-
|
|
502
|
-
**Fix:** upgrade `@alxia/graphql`. The endpoint passes `requestId: false` (the
|
|
503
|
-
app issues its own id) and defaults `logging` to `'warn'` on both majors (Yoga 5 ignores `requestId`;
|
|
504
|
-
on either, Yoga's info lines are gone unless asked for). To get Yoga's id
|
|
505
|
-
back, pass `requestId: true` (the header stays untrusted) or an object; to get
|
|
506
|
-
the INFO line, pass `logging: true` or `'info'`.
|
|
507
|
-
|
|
508
|
-
### `log.child is not a function`
|
|
509
|
-
|
|
510
|
-
**When:** every request answers 500 with `TypeError: serverContext.log.child is
|
|
511
|
-
not a function`, on `graphql-yoga` 6, with a custom `logging` such as
|
|
512
|
-
`{ debug() {}, info() {}, warn() {}, error() {} }`.
|
|
513
|
-
|
|
514
|
-
**Why:** Yoga 6 scopes a logger to each request with `log.child(...)`, so a
|
|
515
|
-
custom `logging` must be a `@graphql-hive/logger` `Logger`. Yoga 5 took any
|
|
516
|
-
object with `debug`, `info`, `warn` and `error`. `logging: false`, a level
|
|
517
|
-
and `true` work on both.
|
|
518
|
-
|
|
519
|
-
**Fix:** give a `Logger` (it also works on Yoga 5):
|
|
520
|
-
|
|
521
|
-
```ts
|
|
522
|
-
import { Logger } from '@graphql-hive/logger';
|
|
523
|
-
|
|
524
|
-
graphql(app, { schema, logging: new Logger({ level: 'warn' }) });
|
|
467
|
+
graphql(app, { schema, limits: { nesting: 500 } });
|
|
525
468
|
```
|
|
526
469
|
|
|
527
|
-
Or turn Yoga's logger off: `graphql(app, { schema, logging: false })`.
|
|
528
|
-
|
|
529
470
|
### `200 {"errors":[{"message":"Unexpected error.", … "code":"INTERNAL_SERVER_ERROR"}}]}`
|
|
530
471
|
|
|
531
472
|
**When:** a resolver throws an `Error`, or rejects.
|
|
532
473
|
|
|
533
|
-
**Why:**
|
|
534
|
-
never reaches a client. The
|
|
535
|
-
|
|
474
|
+
**Why:** graxia masks errors by default, so a database message or a stack
|
|
475
|
+
never reaches a client. The error carries a correlation id in
|
|
476
|
+
`extensions.reference`; the original goes to `onUnexpected` (`console.error`
|
|
477
|
+
by default, off in production).
|
|
536
478
|
|
|
537
|
-
**Fix:** throw
|
|
538
|
-
unmasked, with its code
|
|
539
|
-
([Errors](guide/
|
|
479
|
+
**Fix:** throw `exposedError(code, message)` for what the client should read; it passes
|
|
480
|
+
unmasked, with its code
|
|
481
|
+
([Errors](guide/plugins.md#errors)):
|
|
540
482
|
|
|
541
483
|
```ts
|
|
542
|
-
import {
|
|
484
|
+
import { exposedError } from '@graxia/core';
|
|
543
485
|
|
|
544
|
-
throw
|
|
545
|
-
extensions: { code: 'FORBIDDEN', http: { status: 403 } },
|
|
546
|
-
});
|
|
486
|
+
throw exposedError('FORBIDDEN', 'Admins only');
|
|
547
487
|
```
|
|
548
488
|
|
|
549
|
-
`
|
|
489
|
+
`maskErrors: false` (or the deprecated `maskedErrors`) shows every message, for development only.
|
|
550
490
|
|
|
551
|
-
### `413
|
|
491
|
+
### `413 … "code":"BODY_TOO_LARGE"` on `POST /graphql`
|
|
552
492
|
|
|
553
493
|
**When:** the body of a `POST` is larger than its limit, with a
|
|
554
494
|
`Content-Length` or chunked. The limit is **1 MiB** unless the `bodyLimit`
|
|
555
495
|
option or a `bodyLimit()` declared before `graphql(...)` gives another.
|
|
556
496
|
|
|
557
|
-
**Why:**
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
(
|
|
563
|
-
|
|
564
|
-
the content type (JSON, form-urlencoded, `application/graphql`). Put the
|
|
565
|
-
costly middlewares (a session lookup, a database call) after `bodyLimit()`.
|
|
497
|
+
**Why:** the limit is graxia's `limits.bodyBytes`: graxia refuses a declared
|
|
498
|
+
size at once and counts the stream otherwise, and the answer is
|
|
499
|
+
`{"errors":[{"message":"The request body is too large.","extensions":{"code":"BODY_TOO_LARGE","fix":"…"}}]}`
|
|
500
|
+
in graxia's JSON format, whatever the app's `errors` option is, with the
|
|
501
|
+
headers the plugins set. Core's own `bodyLimit()` counter does not run on the
|
|
502
|
+
endpoint (it would make a chunked body past the limit an unreadable `400`).
|
|
503
|
+
Core's counter being off, the middlewares declared after `bodyLimit()` run for an oversized body before graxia answers the 413. Nothing is logged, whatever the content type.
|
|
566
504
|
|
|
567
505
|
**Fix:** a client sends less, or the endpoint takes a larger limit, for an
|
|
568
506
|
upload by `multipart` for example:
|
|
@@ -571,46 +509,65 @@ upload by `multipart` for example:
|
|
|
571
509
|
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
572
510
|
```
|
|
573
511
|
|
|
574
|
-
|
|
512
|
+
A client matches `errors[0].extensions.code`, never the message.
|
|
513
|
+
|
|
514
|
+
### `415 … "code":"UNSUPPORTED_MEDIA_TYPE"`
|
|
515
|
+
|
|
516
|
+
**When:** a `POST` whose `Content-Type` is not `application/json` (UTF-8): a
|
|
517
|
+
form (`application/x-www-form-urlencoded`), `application/graphql`, none at all.
|
|
518
|
+
|
|
519
|
+
**Why:** graxia reads JSON bodies only and refuses the other types before it
|
|
520
|
+
reads the body, whatever its size, so such a body past the limit is a 415, not
|
|
521
|
+
a 413.
|
|
575
522
|
|
|
576
|
-
**
|
|
577
|
-
|
|
523
|
+
**Fix:** send `Content-Type: application/json` with `{"query": …}`. For a file
|
|
524
|
+
upload, enable graxia's `uploads` and send `multipart/form-data`.
|
|
578
525
|
|
|
579
|
-
|
|
580
|
-
and the client sends none of its own: its name is the app's. A JSON `POST`
|
|
581
|
-
passes without it.
|
|
526
|
+
### `403 CSRF_HEADER_REQUIRED` from the test client
|
|
582
527
|
|
|
583
|
-
**
|
|
528
|
+
**When:** `graphqlClient(app, { csrfHeader: false })`, or an app whose
|
|
529
|
+
`csrf.requireHeader` lists a header other than `x-graphql-csrf`, answers a
|
|
530
|
+
`GET` with a 403.
|
|
531
|
+
|
|
532
|
+
**Why:** the client sends `x-graphql-csrf` on a `GET` by default. An app
|
|
533
|
+
that replaced the list does not accept it, and `false` sends none.
|
|
534
|
+
|
|
535
|
+
**Fix:** name the app's header:
|
|
584
536
|
|
|
585
537
|
```ts
|
|
586
|
-
graphqlClient(app, {
|
|
538
|
+
graphqlClient(app, { csrfHeader: 'x-my-app' });
|
|
587
539
|
```
|
|
588
540
|
|
|
589
|
-
### `PersistedQueryNotFound` or `
|
|
541
|
+
### `PersistedQueryNotFound` or `PersistedQueryNotSupported`
|
|
590
542
|
|
|
591
|
-
**When:**
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
543
|
+
**When:** a request that sends a persisted-query hash is answered
|
|
544
|
+
`PersistedQueryNotFound` (`PERSISTED_QUERY_NOT_FOUND`: the hash is unknown and
|
|
545
|
+
no query text came with it) or `PersistedQueryNotSupported`
|
|
546
|
+
(`PERSISTED_QUERY_NOT_SUPPORTED`: `trustedDocuments.apq` is off). Related
|
|
547
|
+
refusals on the same path: `provided sha does not match query`
|
|
548
|
+
(`PROVIDED_SHA_DOESNT_MATCH`), `Persisted document <id> not found.` for a
|
|
549
|
+
`documentId` the manifest lacks (`PERSISTED_QUERY_NOT_FOUND`) and, in `strict`
|
|
550
|
+
mode, `Only persisted documents are allowed.` (`PERSISTED_QUERY_ONLY`) for a
|
|
551
|
+
plain document.
|
|
595
552
|
|
|
596
|
-
**Why:**
|
|
597
|
-
|
|
598
|
-
extension other than `persistedQuery.sha256Hash` (its default, which
|
|
599
|
-
`persisted` sends).
|
|
553
|
+
**Why:** graxia's `trustedDocuments` does not know the hash, and has no
|
|
554
|
+
automatic persisted queries to learn it from.
|
|
600
555
|
|
|
601
|
-
**Fix:**
|
|
602
|
-
`
|
|
556
|
+
**Fix:** send the request again with the query text beside the hash (when
|
|
557
|
+
`apq` is on, the server stores it), put the document in the trusted manifest
|
|
558
|
+
and send its `documentId`, or turn `apq` on. For a plain document in `strict`
|
|
559
|
+
mode, send a `documentId`, or set `trustedDocuments.mode` to `"mixed"`.
|
|
603
560
|
|
|
604
561
|
### `405 {"error":"method_not_allowed"}` on `OPTIONS /graphql`
|
|
605
562
|
|
|
606
563
|
**When:** a browser on another origin calls the endpoint; its preflight
|
|
607
564
|
fails and the console reports a CORS error.
|
|
608
565
|
|
|
609
|
-
**Why:**
|
|
566
|
+
**Why:** graxia has no CORS, and the app answers no `OPTIONS` without a
|
|
610
567
|
CORS middleware.
|
|
611
568
|
|
|
612
569
|
**Fix:** `@alxia/cors`, given to `use` first, for the whole app: it answers a
|
|
613
|
-
preflight itself, before the router's 404 or 405 ([CORS](guide/
|
|
570
|
+
preflight itself, before the router's 404 or 405 ([CORS](guide/plugins.md#cors)):
|
|
614
571
|
|
|
615
572
|
```ts
|
|
616
573
|
import { cors } from '@alxia/cors';
|
|
@@ -623,9 +580,9 @@ const app = alxia()
|
|
|
623
580
|
### `405 {"errors":[{"message":"Can only perform a mutation operation from a POST request."}]}`
|
|
624
581
|
|
|
625
582
|
**When:** a mutation sent as `GET /graphql?query=mutation …`. The body also
|
|
626
|
-
carries `"extensions":{"code":"
|
|
583
|
+
carries `"extensions":{"code":"METHOD_NOT_ALLOWED"}`.
|
|
627
584
|
|
|
628
|
-
**Why:**
|
|
585
|
+
**Why:** graxia refuses mutations over `GET` (`METHOD_NOT_ALLOWED`), which a link or a cache could
|
|
629
586
|
replay.
|
|
630
587
|
|
|
631
588
|
**Fix:** send it as a `POST`:
|
|
@@ -646,7 +603,7 @@ request whose `Accept` allows only `text/html` (no `*/*`, no
|
|
|
646
603
|
page is served — `ide: false`, or `ide: 'apollo-sandbox'` with a `?query=`
|
|
647
604
|
in the URL. A browser sends `*/*` too, and gets JSON there.
|
|
648
605
|
|
|
649
|
-
**Why:** a subscription is a stream of results:
|
|
606
|
+
**Why:** a subscription is a stream of results: graxia sends it only to a
|
|
650
607
|
client that accepts `text/event-stream`, and has no other representation
|
|
651
608
|
to offer. Likewise, a result has no HTML representation: a client asking
|
|
652
609
|
only for HTML, with no IDE page to serve it, gets nothing it accepts.
|
|
@@ -665,14 +622,14 @@ For a client that asks only for HTML, accept `application/json` (or
|
|
|
665
622
|
`*/*`) where no IDE is served, or keep an IDE where one is wanted — see
|
|
666
623
|
[GraphiQL and Apollo Sandbox](guide/ide.md).
|
|
667
624
|
|
|
668
|
-
### `{"errors":[{"message":"Must provide query string."}]}`
|
|
625
|
+
### `{"errors":[{"message":"Must provide a query string."}]}`
|
|
669
626
|
|
|
670
627
|
**When:** a `GET` with no `query` parameter from a client that does not ask
|
|
671
628
|
for HTML — or from a browser when `ide` is `false` — or a `POST` whose JSON
|
|
672
629
|
body has no `query`. The body carries
|
|
673
|
-
`"extensions":{"code":"
|
|
630
|
+
`"extensions":{"code":"QUERY_REQUIRED"}` (400).
|
|
674
631
|
|
|
675
|
-
**Why:** the request reached
|
|
632
|
+
**Why:** the request reached graxia, with nothing to run. A `GET` from a
|
|
676
633
|
browser gets the IDE page instead, unless `ide` is `false`; a client
|
|
677
634
|
asking only for HTML gets a [`406`](#406-with-an-empty-body) where no page is
|
|
678
635
|
served.
|
|
@@ -685,10 +642,21 @@ await app.request(`/graphql?query=${encodeURIComponent('{ me }')}`, {
|
|
|
685
642
|
});
|
|
686
643
|
```
|
|
687
644
|
|
|
688
|
-
###
|
|
645
|
+
### A WebSocket closes with 4400 after the first message
|
|
646
|
+
|
|
647
|
+
**When:** a client sends `connection_init` or any message as a **binary** frame
|
|
648
|
+
(a `Uint8Array`, a `Blob`); the socket closes at once with code `4400`.
|
|
649
|
+
|
|
650
|
+
**Why:** graxia refuses binary frames: `graphql-transport-ws` messages are JSON
|
|
651
|
+
text. Yoga's `graphql-ws` decoded a binary frame; graxia does not.
|
|
689
652
|
|
|
690
|
-
**
|
|
691
|
-
|
|
653
|
+
**Fix:** send the message as a text frame: `socket.send(JSON.stringify(message))`.
|
|
654
|
+
`graphql-ws`'s `createClient` already does.
|
|
655
|
+
|
|
656
|
+
### `The Sec-WebSocket-Protocol header must offer "graphql-transport-ws".` (400, `SUBPROTOCOL_REQUIRED`)
|
|
657
|
+
|
|
658
|
+
**When:** a socket opens on an endpoint with `ws` on and the upgrade is
|
|
659
|
+
refused with a plain HTTP `400` and this code, before any socket exists.
|
|
692
660
|
|
|
693
661
|
**Why:** the client offered no subprotocol, or only one the endpoint does
|
|
694
662
|
not serve. `ws` serves `graphql-transport-ws`, the protocol of
|
|
@@ -731,7 +699,7 @@ const app = base.plugin((app) => graphql(app, { schema }));
|
|
|
731
699
|
`operationName`, and the span of `@alxia/telemetry` is named
|
|
732
700
|
`POST /graphql`.
|
|
733
701
|
|
|
734
|
-
**Why:** an operation is reported only when
|
|
702
|
+
**Why:** an operation is reported only when graxia executes it (graxia's own operation span is off, and its parse, validate and execute spans nest under `@alxia/telemetry`'s span). A request
|
|
735
703
|
refused before that (a syntax error, a document that fails validation) names
|
|
736
704
|
none; an operation over `ws: true` is a line and a span of its own, not
|
|
737
705
|
the upgrade's ([the WebSocket guide](guide/websockets.md#logging-and-tracing));
|
|
@@ -745,6 +713,26 @@ update `@alxia/core`, `@alxia/graphql`, `@alxia/logger` and
|
|
|
745
713
|
`@alxia/telemetry` together. See
|
|
746
714
|
[the endpoint guide](guide/endpoint.md#the-operation-in-the-log-and-the-trace).
|
|
747
715
|
|
|
716
|
+
### graxia's parse, validate or resolver spans are missing
|
|
717
|
+
|
|
718
|
+
**When:** `@alxia/telemetry` shows the operation's span but none of graxia's
|
|
719
|
+
`graphql.parse`, `graphql.validate` or resolver spans, or no host span is
|
|
720
|
+
active when the request arrives.
|
|
721
|
+
|
|
722
|
+
**Why:** `graphql()` sets graxia's `telemetry` to `{ operationSpans: false }`,
|
|
723
|
+
which keeps the parse, validate and execute spans but not the resolver spans
|
|
724
|
+
(a resolver span per field is opt-in), and they exist only under an active
|
|
725
|
+
span: with no `@alxia/telemetry` in front of the endpoint there is no host
|
|
726
|
+
span, and graxia makes its own request and operation spans instead. If you
|
|
727
|
+
passed `telemetry: false`, graxia makes none at all.
|
|
728
|
+
|
|
729
|
+
**Fix:** put `use(telemetry({ … }))` before `graphql()`, pass
|
|
730
|
+
`telemetry: { resolverSpans: true }` for resolver spans (the
|
|
731
|
+
`operationSpans: false` default stays under an object you pass; set
|
|
732
|
+
`operationSpans: true` yourself to bring graxia's operation span back), and
|
|
733
|
+
leave `telemetry: false` out. See
|
|
734
|
+
[graxia's own spans](guide/endpoint.md#graxias-own-spans).
|
|
735
|
+
|
|
748
736
|
### The logger, CORS or secure headers miss the endpoint
|
|
749
737
|
|
|
750
738
|
**When:** `use(logger())`, `use(cors(…))` or `use(secureHeaders())` comes
|
|
@@ -796,21 +784,17 @@ reports the WebSocket connection as failed.
|
|
|
796
784
|
**Why:** `ws` is off, the default: the endpoint serves subscriptions over
|
|
797
785
|
server-sent events, and never upgrades to a WebSocket. With `ws` on, the
|
|
798
786
|
same message means the upgrade was answered otherwise: a guard's `401`, a
|
|
799
|
-
`500` naming
|
|
787
|
+
`500` naming a missing `ws` runtime,
|
|
800
788
|
or a socket `path` other than the one the client opens.
|
|
801
789
|
|
|
802
790
|
**Fix:** serve WebSocket too ([GraphQL over WebSocket](guide/websockets.md)):
|
|
803
791
|
|
|
804
|
-
```sh
|
|
805
|
-
bun add graphql-ws
|
|
806
|
-
```
|
|
807
|
-
|
|
808
792
|
```ts
|
|
809
793
|
graphql(app, { schema, ws: true });
|
|
810
794
|
```
|
|
811
795
|
|
|
812
796
|
Or leave `ws` off, and subscribe over SSE, with `Accept: text/event-stream`
|
|
813
|
-
([Subscriptions](guide/
|
|
797
|
+
([Subscriptions](guide/plugins.md#subscriptions)), GraphiQL's protocol left at
|
|
814
798
|
SSE:
|
|
815
799
|
|
|
816
800
|
```ts
|
|
@@ -823,7 +807,7 @@ graphql(app, { schema, graphiql: { subscriptionsProtocol: 'SSE' } });
|
|
|
823
807
|
for a few seconds, on a real server: the client sees the connection reset at
|
|
824
808
|
8 to 10 seconds, before any event. A spec using `app.request` never shows it.
|
|
825
809
|
|
|
826
|
-
**Why:**
|
|
810
|
+
**Why:** graxia pings an open stream every 12 seconds, but `Bun.serve` closes a
|
|
827
811
|
connection idle for `idleTimeout` seconds, 10 by default, before the first
|
|
828
812
|
ping. `server.timeout(request, 0)` called from a resolver does not change it
|
|
829
813
|
for the stream.
|
|
@@ -847,7 +831,7 @@ reading, or keeps delivering after the viewer's session ended.
|
|
|
847
831
|
and a check done once at connection is never repeated.
|
|
848
832
|
|
|
849
833
|
**Fix:** wrap the source in `boundedStream` with `idleMs`, `totalMs` and a
|
|
850
|
-
`check` ([guide](guide/
|
|
834
|
+
`check` ([guide](guide/plugins.md#bound-a-subscription)). A stream that ends at
|
|
851
835
|
`idleMs` while pings still flow is expected: pings are not events of the
|
|
852
836
|
source.
|
|
853
837
|
|
|
@@ -887,18 +871,15 @@ app.use(defaultPolicy); // before the endpoint, so it wraps it
|
|
|
887
871
|
**When:** a server that receives many different large queries, such as
|
|
888
872
|
generated ones or ones built with inline values, holds more and more memory.
|
|
889
873
|
|
|
890
|
-
**Why:**
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
`parserAndValidationCache`: then that cache is the app's to bound. Giving
|
|
894
|
-
Yoga's `parserAndValidationCache` in any form, `{ validationCache: false }`
|
|
895
|
-
included, brings back Yoga's unbounded least-recently-used cache.
|
|
874
|
+
**Why:** graxia keeps parsed documents in a cache bounded by the number of
|
|
875
|
+
entries (`caches.parse.max`, 1 024 by default) and their age (`ttlMs`), not by
|
|
876
|
+
their size: a few thousand distinct large documents hold a lot of memory.
|
|
896
877
|
|
|
897
|
-
**Fix:** lower `
|
|
898
|
-
|
|
878
|
+
**Fix:** lower `caches.parse.max`, send variables instead of inline values so
|
|
879
|
+
the documents repeat, or turn the cache off:
|
|
899
880
|
|
|
900
881
|
```ts
|
|
901
|
-
graphql(app, { schema,
|
|
882
|
+
graphql(app, { schema, caches: { parse: { max: 256, ttlMs: 10 * 60_000 } } }); // or caches: false
|
|
902
883
|
```
|
|
903
884
|
|
|
904
885
|
### GraphiQL is served in production
|
|
@@ -920,13 +901,15 @@ graphql(app, { schema, ide: false });
|
|
|
920
901
|
### GraphiQL does not open in development, or in a test
|
|
921
902
|
|
|
922
903
|
**When:** a browser's `GET` at the endpoint gets a JSON result, or
|
|
923
|
-
`Must provide query string.`, where GraphiQL used to open.
|
|
904
|
+
`Must provide a query string.`, where GraphiQL used to open.
|
|
924
905
|
|
|
925
|
-
**Why:** without `ide`, GraphiQL is served in the serving app's dev alone
|
|
926
|
-
|
|
906
|
+
**Why:** without `ide`, GraphiQL is served in the serving app's dev alone:
|
|
907
|
+
`alxia({ dev })`, else `NODE_ENV=development`. An explicit `dev: false`
|
|
908
|
+
turns it off even under `NODE_ENV=development`, and `bun test` sets
|
|
909
|
+
`NODE_ENV=test`.
|
|
927
910
|
|
|
928
|
-
**Fix:** run the `dev` script with `NODE_ENV=development
|
|
929
|
-
explicitly where it must open:
|
|
911
|
+
**Fix:** run the `dev` script with `NODE_ENV=development` (or give
|
|
912
|
+
`alxia({ dev: true })`), or give the IDE explicitly where it must open:
|
|
930
913
|
|
|
931
914
|
```ts
|
|
932
915
|
graphql(app, { schema, ide: 'graphiql' });
|