@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.
Files changed (74) hide show
  1. package/README.md +60 -62
  2. package/dist/endpoint.d.ts +14 -2
  3. package/dist/endpoint.d.ts.map +1 -1
  4. package/dist/executor.d.ts +20 -37
  5. package/dist/executor.d.ts.map +1 -1
  6. package/dist/explorer.d.ts +24 -0
  7. package/dist/explorer.d.ts.map +1 -0
  8. package/dist/graphql.d.ts +32 -95
  9. package/dist/graphql.d.ts.map +1 -1
  10. package/dist/handler.d.ts +7 -34
  11. package/dist/handler.d.ts.map +1 -1
  12. package/dist/index.d.ts +3 -4
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +301 -1011
  15. package/dist/index.js.map +14 -23
  16. package/dist/once-per-request.d.ts +5 -0
  17. package/dist/once-per-request.d.ts.map +1 -1
  18. package/dist/operation.d.ts +2 -7
  19. package/dist/operation.d.ts.map +1 -1
  20. package/dist/options.d.ts +38 -0
  21. package/dist/options.d.ts.map +1 -0
  22. package/dist/removed.d.ts +14 -0
  23. package/dist/removed.d.ts.map +1 -0
  24. package/dist/sandbox.d.ts +3 -17
  25. package/dist/sandbox.d.ts.map +1 -1
  26. package/dist/testing/client.d.ts +9 -7
  27. package/dist/testing/client.d.ts.map +1 -1
  28. package/dist/testing/index.js +5 -1
  29. package/dist/testing/index.js.map +3 -3
  30. package/dist/ws.d.ts +18 -30
  31. package/dist/ws.d.ts.map +1 -1
  32. package/docs/README.md +3 -2
  33. package/docs/guide/context.md +40 -32
  34. package/docs/guide/endpoint.md +42 -27
  35. package/docs/guide/executor.md +23 -8
  36. package/docs/guide/ide.md +27 -64
  37. package/docs/guide/{yoga.md → plugins.md} +87 -72
  38. package/docs/guide/production.md +115 -196
  39. package/docs/guide/testing.md +24 -24
  40. package/docs/guide/websockets.md +21 -14
  41. package/docs/migrating-to-graxia.md +283 -0
  42. package/docs/roadmap.md +7 -11
  43. package/docs/troubleshooting.md +231 -248
  44. package/package.json +15 -22
  45. package/dist/body-refusal.d.ts +0 -25
  46. package/dist/body-refusal.d.ts.map +0 -1
  47. package/dist/document-cache.d.ts +0 -39
  48. package/dist/document-cache.d.ts.map +0 -1
  49. package/dist/field-rate-limit/count.d.ts +0 -28
  50. package/dist/field-rate-limit/count.d.ts.map +0 -1
  51. package/dist/field-rate-limit/from-store.d.ts +0 -21
  52. package/dist/field-rate-limit/from-store.d.ts.map +0 -1
  53. package/dist/field-rate-limit/index.d.ts +0 -5
  54. package/dist/field-rate-limit/index.d.ts.map +0 -1
  55. package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
  56. package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
  57. package/dist/field-rate-limit/plugin.d.ts +0 -28
  58. package/dist/field-rate-limit/plugin.d.ts.map +0 -1
  59. package/dist/field-rate-limit/types.d.ts +0 -60
  60. package/dist/field-rate-limit/types.d.ts.map +0 -1
  61. package/dist/nesting.d.ts +0 -18
  62. package/dist/nesting.d.ts.map +0 -1
  63. package/dist/parse-limits.d.ts +0 -50
  64. package/dist/parse-limits.d.ts.map +0 -1
  65. package/dist/same-origin/index.d.ts +0 -2
  66. package/dist/same-origin/index.d.ts.map +0 -1
  67. package/dist/same-origin/same-origin.d.ts +0 -30
  68. package/dist/same-origin/same-origin.d.ts.map +0 -1
  69. package/dist/ws-operations.d.ts +0 -31
  70. package/dist/ws-operations.d.ts.map +0 -1
  71. package/dist/ws-server.d.ts +0 -32
  72. package/dist/ws-server.d.ts.map +0 -1
  73. package/dist/yoga.d.ts +0 -12
  74. package/dist/yoga.d.ts.map +0 -1
@@ -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 'graphql-yoga' from '…/@alxia/graphql/dist/index.js'`](#cannot-find-package-graphql-yoga-from-alxiagraphqldistindexjs)
11
- - [`@alxia/graphql: graphql(app, { ws }) serves GraphQL over WebSocket with the optional peer graphql-ws, which is not installed: bun add graphql-ws`](#alxiagraphql-graphqlapp--ws--serves-graphql-over-websocket-with-the-optional-peer-graphql-ws-which-is-not-installed-bun-add-graphql-ws)
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>"; } & YogaInitialContext'`](#property-viewer-does-not-exist-on-type--readonly-error-graphqlcontext-needs-the-type-of-an-app-graphqlcontexttypeof-app---yogainitialcontext)
17
- - [`Property 'viewer' does not exist on type 'YogaInitialContext'`](#property-viewer-does-not-exist-on-type-yogainitialcontext)
18
- - [`Property 'query' does not exist on type 'YogaInitialContext & ServerContext<…>'`](#property-query-does-not-exist-on-type-yogainitialcontext--servercontext)
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
- - [`TypeError: POST /graphql: bodyLimit must be a whole number of bytes, 0 or more; got -1`](#typeerror-post-graphql-bodylimit-must-be-a-whole-number-of-bytes-0-or-more-got--1)
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 Required CSRF header(s) not present` from the test client](#403-required-csrf-headers-not-present-from-the-test-client)
35
- - [`PersistedQueryNotFound` or `PersistedQueryOnly`](#persistedquerynotfound-or-persistedqueryonly)
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 {"error":"content_too_large", …}`](#413-errorcontent_too_large--on-post-graphql)
40
- - [`graphqlExecutor runs queries and mutations, not a subscription.`](#graphqlexecutor-runs-queries-and-mutations-not-a-subscription)
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
- - [`4406 Subprotocol not acceptable`](#4406-subprotocol-not-acceptable)
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 'graphql-yoga' from '…/@alxia/graphql/dist/index.js'`
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` reports either as
64
- `TS2307: Cannot find module 'graphql-yoga'`.
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:** `graphql-yoga` and `graphql` are peers: the package declares no
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 graphql-yoga graphql
80
+ bun add @alxia/graphql @graxia/core @graxia/graphiql graphql
73
81
  ```
74
82
 
75
- With `graphql` 17, `graphql-yoga` must be 5.22 or later: an older Yoga
76
- declares `graphql ^15.2.0 || ^16.0.0`, and `bun install` warns about an
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
- **Fix:**
86
+ ## CSRF
90
87
 
91
- ```sh
92
- bun add graphql-ws
93
- ```
88
+ ### `CSRF_HEADER_REQUIRED`
94
89
 
95
- ## Same origin
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
- ### `Cross-origin requests are not allowed`
95
+ ### `sameOrigin` or `renderSandbox` is not exported
98
96
 
99
- A request was answered 403 `FORBIDDEN` by `sameOrigin`. Its `Origin` is not the
100
- endpoint's host (behind a proxy that rewrites the host, or from a trusted
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
- ```ts
105
- import { sameOrigin } from '@alxia/graphql';
100
+ ### `graphql(app, { logging })`, `requestId` or `cors` throws a `TypeError`
106
101
 
107
- sameOrigin({ allow: ['https://app.example.com'] }); // or { json: false }
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>"; } & YogaInitialContext'`
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 'YogaInitialContext'`
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 Yoga's alone. The field is there at
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 'YogaInitialContext & ServerContext<…>'`
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, but it is Yoga's: the GraphQL `query`, `variables` and
196
- `operationName`.
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 `graphqlEndpoint`.
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; Yoga is told the result.
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
- ### `TypeError: POST /graphql: bodyLimit must be a whole number of bytes, 0 or more; got -1`
292
+ ### `GraxiaConfigError: limits.bodyBytes must be a positive integer`
302
293
 
303
- **When:** declaring `graphql(app, { bodyLimit })` with a negative number, a
304
- fraction, `NaN`, `Infinity` or a string; the message names the route (the
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, checked by core where the `POST`
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, 0 or more:
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
- ### `TypeError: graphql(app, { maxTokens }): maxTokens is the most tokens a document may hold, a positive whole number, or false for none; got …`
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 attempts, try again later` (`RATE_LIMITED`, 429)
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` (`FIELD_SELECTED_ONCE`, 400)
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
- ### `TypeError: fieldRateLimit({ fields }): fields maps each field name to count to its limit, and holds at least one`
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
- ### `TypeError: fieldRateLimit({ fields: { signIn } }): a limit has a consume(key, cost) method, or is { limit, single? }`
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
- ### `TypeError: fieldRateLimit: ipv6Prefix must be a whole number from 0 to 128`
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
- ### `TypeError: fieldRateLimit: ipv6Prefix applies to the default key, and a key of your own was given`
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
- ### `TypeError: fieldRateLimit: code is a non-empty string`
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
- ### `TypeError: limitFromStore: limit must be a whole number of 1 or more` and `… differs from the store's policy …`
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, none with a store that has no policy, or numbers that
422
- differ from the store's own `policy`.
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:** give whole numbers, or leave the policy out for a store that has one.
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. graphql 16 words it `more that`, 17 `more than`.
416
+ message.
431
417
 
432
- **Why:** a document may hold 15 000 tokens by default (`maxTokens`),
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, maxTokens: 30_000 }); // or false
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
- (`maxNesting`). graphql-js parses by recursion and overflows the stack a few
454
- thousand levels down, under `maxTokens`; without the limit that was a 500
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, maxNesting: 2_000 }); // or false
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 `maxNesting` is `false` or raised past what the
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, maxNesting: 500 });
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:** Yoga masks errors by default, so a database message or a stack
534
- never reaches a client. The original error is logged by Yoga's logger,
535
- unless `logging` is `false`.
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 a `GraphQLError` for what the client should read; it passes
538
- unmasked, with its code and status
539
- ([Errors](guide/yoga.md#errors)):
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 { createGraphQLError } from 'graphql-yoga';
484
+ import { exposedError } from '@graxia/core';
543
485
 
544
- throw createGraphQLError('Admins only', {
545
- extensions: { code: 'FORBIDDEN', http: { status: 403 } },
546
- });
486
+ throw exposedError('FORBIDDEN', 'Admins only');
547
487
  ```
548
488
 
549
- `maskedErrors: false` shows every message, for development only.
489
+ `maskErrors: false` (or the deprecated `maskedErrors`) shows every message, for development only.
550
490
 
551
- ### `413 {"error":"content_too_large", …}` on `POST /graphql`
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:** a declared `Content-Length` over the limit is refused by core where
558
- `bodyLimit()` stands, before Yoga runs: the middlewares declared before it
559
- run, the ones after it do not, and the 413 carries no header Yoga's plugins
560
- set. A chunked body is counted as it arrives and the read fails past the
561
- limit; the endpoint answers it as any route does, in the app's error format
562
- (`application/problem+json` under `errors: 'problem'`), with the headers
563
- Yoga's plugins set (`Cache-Control: no-store`…). Nothing is logged, whatever
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
- ### `403 Required CSRF header(s) not present` from the test client
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
- **When:** `graphqlClient(app).query(…, { method: 'GET' })` on an app with
577
- Yoga's `useCSRFPrevention`.
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
- **Why:** a `GET` has no `Content-Type`, so the plugin asks for its header,
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
- **Fix:** the app's header, in the client's `headers`:
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, { headers: { 'x-csrf': '1' } });
538
+ graphqlClient(app, { csrfHeader: 'x-my-app' });
587
539
  ```
588
540
 
589
- ### `PersistedQueryNotFound` or `PersistedQueryOnly`
541
+ ### `PersistedQueryNotFound` or `PersistedQueryNotSupported`
590
542
 
591
- **When:** `query({ persisted: hash })` answers `PersistedQueryNotFound`
592
- (`PERSISTED_QUERY_NOT_IN_LIST`), or a call with a document answers
593
- `PersistedQueryOnly` (`CANNOT_SEND_PQ_ID_AND_BODY`); `PersistedQueryKeyNotFound`
594
- when no id was found.
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:** the app's `usePersistedOperations` does not know the hash, refuses
597
- every document (`allowArbitraryOperations: false`), or reads the id from an
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:** register the hash, send no document, or send the app's own extension:
602
- `query({ extensions: { documentId } })`.
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:** Yoga's CORS is off, and the app answers no `OPTIONS` without a
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/yoga.md#cors)):
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":"BAD_REQUEST"}`.
583
+ carries `"extensions":{"code":"METHOD_NOT_ALLOWED"}`.
627
584
 
628
- **Why:** Yoga refuses mutations over `GET`, which a link or a cache could
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: Yoga sends it only to a
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":"BAD_REQUEST"}`.
630
+ `"extensions":{"code":"QUERY_REQUIRED"}` (400).
674
631
 
675
- **Why:** the request reached Yoga, with nothing to run. A `GET` from a
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
- ### `4406 Subprotocol not acceptable`
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
- **When:** a socket opens on an endpoint with `ws` on, then closes at once
691
- with this code and reason.
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 Yoga executes it. A request
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 [the missing peer](#alxiagraphql-graphqlapp--ws--serves-graphql-over-websocket-with-the-optional-peer-graphql-ws-which-is-not-installed-bun-add-graphql-ws),
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/yoga.md#subscriptions)), GraphiQL's protocol left at
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:** Yoga pings an open stream every 12 seconds, but `Bun.serve` closes a
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/yoga.md#bound-a-subscription)). A stream that ends at
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:** Yoga's own parse cache keeps up to 1 024 documents, whatever their
891
- size, for an hour. `graphql()` replaces it with a cache bounded by weight
892
- (`parseCache`, 64 MiB by default) unless the app gives Yoga's
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 `parseCache.maxBytes`, send variables instead of inline
898
- values so the documents repeat, or bound your own cache:
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, parseCache: { maxBytes: 16 * 1024 * 1024 } });
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
- on only under `NODE_ENV=development`; `bun test` sets `NODE_ENV=test`.
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`, or give the IDE
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' });