@alxia/graphql 0.8.3 → 0.9.1
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 +38 -1
- package/dist/body-refusal.d.ts +3 -2
- package/dist/body-refusal.d.ts.map +1 -1
- package/dist/document-cache.d.ts +39 -0
- package/dist/document-cache.d.ts.map +1 -0
- package/dist/endpoint.d.ts +5 -0
- package/dist/endpoint.d.ts.map +1 -0
- package/dist/graphql.d.ts +31 -0
- package/dist/graphql.d.ts.map +1 -1
- package/dist/handler.d.ts +1 -1
- package/dist/handler.d.ts.map +1 -1
- package/dist/index.js +284 -15
- package/dist/index.js.map +10 -6
- package/dist/nesting.d.ts +18 -0
- package/dist/nesting.d.ts.map +1 -0
- package/dist/parse-limits.d.ts +50 -0
- package/dist/parse-limits.d.ts.map +1 -0
- package/docs/README.md +1 -1
- package/docs/guide/endpoint.md +4 -0
- package/docs/guide/production.md +115 -14
- package/docs/guide/websockets.md +14 -1
- package/docs/roadmap.md +22 -2
- package/docs/troubleshooting.md +148 -7
- package/package.json +1 -1
package/docs/troubleshooting.md
CHANGED
|
@@ -23,6 +23,7 @@ symptom.
|
|
|
23
23
|
**Startup**
|
|
24
24
|
|
|
25
25
|
- [`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)
|
|
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)
|
|
27
28
|
|
|
28
29
|
**Responses**
|
|
@@ -34,6 +35,9 @@ symptom.
|
|
|
34
35
|
- [`405 {"errors":[{"message":"Can only perform a mutation operation from a POST request."}]}`](#405-errorsmessagecan-only-perform-a-mutation-operation-from-a-post-request)
|
|
35
36
|
- [`406` with an empty body](#406-with-an-empty-body)
|
|
36
37
|
- [`413 {"error":"content_too_large", …}`](#413-errorcontent_too_large--on-post-graphql)
|
|
38
|
+
- [`Syntax Error: Document contains more than 15000 tokens. Parsing aborted.`](#syntax-error-document-contains-more-than-15000-tokens-parsing-aborted)
|
|
39
|
+
- [`Syntax Error: Document is nested more than 1000 levels deep. Parsing aborted.`](#syntax-error-document-is-nested-more-than-1000-levels-deep-parsing-aborted)
|
|
40
|
+
- [`Syntax Error: Document is nested too deeply to parse.`](#syntax-error-document-is-nested-too-deeply-to-parse)
|
|
37
41
|
- [`{"errors":[{"message":"Must provide query string."}]}`](#errorsmessagemust-provide-query-string)
|
|
38
42
|
- [`4406 Subprotocol not acceptable`](#4406-subprotocol-not-acceptable)
|
|
39
43
|
|
|
@@ -270,8 +274,120 @@ ping in a loop.
|
|
|
270
274
|
graphql(app, { schema, ws: { keepAlive: 30_000 } });
|
|
271
275
|
```
|
|
272
276
|
|
|
277
|
+
### `TypeError: POST /graphql: bodyLimit must be a whole number of bytes, 0 or more; got -1`
|
|
278
|
+
|
|
279
|
+
**When:** declaring `graphql(app, { bodyLimit })` with a negative number, a
|
|
280
|
+
fraction, `NaN`, `Infinity` or a string; the message names the route (the
|
|
281
|
+
endpoint's `path`) and the value given.
|
|
282
|
+
|
|
283
|
+
**Why:** `bodyLimit` is a count of bytes, checked by core where the `POST`
|
|
284
|
+
is declared.
|
|
285
|
+
|
|
286
|
+
**Fix:** a whole number of bytes, 0 or more:
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### `TypeError: graphql(app, { maxTokens }): maxTokens is the most tokens a document may hold, a positive whole number, or false for none; got …`
|
|
293
|
+
|
|
294
|
+
**When:** declaring `graphql(app, { maxTokens })` with `0`, a negative number,
|
|
295
|
+
a fraction, `NaN` or a string; the message names the value given.
|
|
296
|
+
|
|
297
|
+
**Why:** `maxTokens` is a count of tokens.
|
|
298
|
+
|
|
299
|
+
**Fix:** a positive whole number, or `false` for no cap:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
graphql(app, { schema, maxTokens: 30_000 });
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
### `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 …`
|
|
306
|
+
|
|
307
|
+
**When:** declaring `graphql()` with both `parseCache` and Yoga's
|
|
308
|
+
`parserAndValidationCache`, or with a `parseCache.maxBytes`, `max` or `ttl`
|
|
309
|
+
that is not a positive whole number, or with a `parseCache` that is neither
|
|
310
|
+
an object nor `false` (`true`, `null`, a number, a string).
|
|
311
|
+
|
|
312
|
+
**Why:** `parseCache` sizes alxia's bounded cache and
|
|
313
|
+
`parserAndValidationCache` replaces it with yours, so the two cannot both
|
|
314
|
+
apply.
|
|
315
|
+
|
|
316
|
+
**Fix:** give one:
|
|
317
|
+
|
|
318
|
+
```ts
|
|
319
|
+
graphql(app, { schema, parseCache: { maxBytes: 16 * 1024 * 1024 } });
|
|
320
|
+
```
|
|
321
|
+
|
|
273
322
|
## Responses
|
|
274
323
|
|
|
324
|
+
### `Syntax Error: Document contains more than 15000 tokens. Parsing aborted.`
|
|
325
|
+
|
|
326
|
+
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
|
|
327
|
+
`application/graphql-response+json`, 200 under `application/json`) and this
|
|
328
|
+
message. graphql 16 words it `more that`, 17 `more than`.
|
|
329
|
+
|
|
330
|
+
**Why:** a document may hold 15 000 tokens by default (`maxTokens`),
|
|
331
|
+
so that no request makes the server parse and keep an unbounded one. A
|
|
332
|
+
generated query or a screen with many inlined fragments can pass it; a
|
|
333
|
+
client that worked before is refused.
|
|
334
|
+
|
|
335
|
+
**Fix:** raise the limit to what your largest real query needs, or turn it
|
|
336
|
+
off. Persisted operations keep clients from sending large documents at all
|
|
337
|
+
([Persisted operations](guide/production.md#persisted-operations-briefly)):
|
|
338
|
+
|
|
339
|
+
```ts
|
|
340
|
+
graphql(app, { schema, maxTokens: 30_000 }); // or false
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
### `Syntax Error: Document is nested more than 1000 levels deep. Parsing aborted.`
|
|
344
|
+
|
|
345
|
+
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
|
|
346
|
+
`application/graphql-response+json`, 200 under `application/json`) and this
|
|
347
|
+
message. A document that overflowed the stack anyway has
|
|
348
|
+
[its own entry](#syntax-error-document-is-nested-too-deeply-to-parse).
|
|
349
|
+
|
|
350
|
+
**Why:** a document may nest 1 000 levels of `{`, `(` and `[` by default
|
|
351
|
+
(`maxNesting`). graphql-js parses by recursion and overflows the stack a few
|
|
352
|
+
thousand levels down, under `maxTokens`; without the limit that was a 500
|
|
353
|
+
`Unexpected error.`, logged. A real query nests a dozen levels, so this is
|
|
354
|
+
a hostile or generated document.
|
|
355
|
+
|
|
356
|
+
**Fix:** if a generated query really nests deeper, raise the limit, within
|
|
357
|
+
what your runtime's stack parses (several thousand levels: about 10 000 on
|
|
358
|
+
Bun's main thread, fewer in a Worker), or turn it off:
|
|
359
|
+
|
|
360
|
+
```ts
|
|
361
|
+
graphql(app, { schema, maxNesting: 2_000 }); // or false
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### `Syntax Error: Document is nested too deeply to parse.`
|
|
365
|
+
|
|
366
|
+
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` and this message.
|
|
367
|
+
|
|
368
|
+
**Why:** graphql-js parsed the document by recursion and the call stack
|
|
369
|
+
overflowed, either because `maxNesting` is `false` or raised past what the
|
|
370
|
+
runtime parses. The stack is smaller in a Worker or under load than on Bun's
|
|
371
|
+
main thread, so the depth that fails varies. The overflow is refused as any
|
|
372
|
+
unparsable document is, never a 500.
|
|
373
|
+
|
|
374
|
+
**Fix:** a real query nests a dozen levels; look for a hostile or generated
|
|
375
|
+
document. If it is legitimate, keep the limit (the default is 1 000) or set
|
|
376
|
+
one your runtime parses:
|
|
377
|
+
|
|
378
|
+
```ts
|
|
379
|
+
graphql(app, { schema, maxNesting: 500 });
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### `TypeError: graphql(app, { maxNesting }): maxNesting is the most levels of { ( [ a document may nest, a positive whole number, or false for none; got …`
|
|
383
|
+
|
|
384
|
+
**When:** declaring `graphql(app, { maxNesting })` with `0`, a negative number,
|
|
385
|
+
a fraction, `NaN` or a string.
|
|
386
|
+
|
|
387
|
+
**Why:** `maxNesting` is a count of nesting levels.
|
|
388
|
+
|
|
389
|
+
**Fix:** a positive whole number, or `false` for no limit.
|
|
390
|
+
|
|
275
391
|
### `200 {"errors":[{"message":"Unexpected error.", … "code":"INTERNAL_SERVER_ERROR"}}]}`
|
|
276
392
|
|
|
277
393
|
**When:** a resolver throws an `Error`, or rejects.
|
|
@@ -296,19 +412,25 @@ throw createGraphQLError('Admins only', {
|
|
|
296
412
|
|
|
297
413
|
### `413 {"error":"content_too_large", …}` on `POST /graphql`
|
|
298
414
|
|
|
299
|
-
**When:** the body of a `POST` is larger than
|
|
300
|
-
|
|
415
|
+
**When:** the body of a `POST` is larger than its limit, with a
|
|
416
|
+
`Content-Length` or chunked. The limit is **1 MiB** unless the `bodyLimit`
|
|
417
|
+
option or a `bodyLimit()` declared before `graphql(...)` gives another.
|
|
301
418
|
|
|
302
419
|
**Why:** core counts the bytes as they arrive and fails the read past the
|
|
303
420
|
limit; the endpoint answers it as any route does, in the app's error format
|
|
304
|
-
(`application/problem+json` under `errors: 'problem'`).
|
|
421
|
+
(`application/problem+json` under `errors: 'problem'`). The 413 carries the
|
|
422
|
+
headers Yoga's plugins set (`Cache-Control: no-store`…), and nothing is
|
|
423
|
+
logged, whatever the content type (JSON, form-urlencoded,
|
|
424
|
+
`application/graphql`). The body is read by the endpoint, after the
|
|
425
|
+
middlewares declared before it: they still run for an oversized body, even
|
|
426
|
+
when `bodyLimit()` stands above them. Put the costly ones (a session lookup,
|
|
427
|
+
a database call) late.
|
|
305
428
|
|
|
306
|
-
**Fix:** a client sends less, or the
|
|
429
|
+
**Fix:** a client sends less, or the endpoint takes a larger limit, for an
|
|
430
|
+
upload by `multipart` for example:
|
|
307
431
|
|
|
308
432
|
```ts
|
|
309
|
-
|
|
310
|
-
.bodyLimit(512 * 1024) // before graphql(...)
|
|
311
|
-
.plugin((app) => graphql(app, { schema }));
|
|
433
|
+
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
312
434
|
```
|
|
313
435
|
|
|
314
436
|
### `403 Required CSRF header(s) not present` from the test client
|
|
@@ -581,6 +703,25 @@ const defaultPolicy = defineMiddleware(async (ctx, next) =>
|
|
|
581
703
|
app.use(defaultPolicy); // before the endpoint, so it wraps it
|
|
582
704
|
```
|
|
583
705
|
|
|
706
|
+
### The heap grows with distinct queries
|
|
707
|
+
|
|
708
|
+
**When:** a server that receives many different large queries, such as
|
|
709
|
+
generated ones or ones built with inline values, holds more and more memory.
|
|
710
|
+
|
|
711
|
+
**Why:** Yoga's own parse cache keeps up to 1 024 documents, whatever their
|
|
712
|
+
size, for an hour. `graphql()` replaces it with a cache bounded by weight
|
|
713
|
+
(`parseCache`, 64 MiB by default) unless the app gives Yoga's
|
|
714
|
+
`parserAndValidationCache`: then that cache is the app's to bound. Giving
|
|
715
|
+
Yoga's `parserAndValidationCache` in any form, `{ validationCache: false }`
|
|
716
|
+
included, brings back Yoga's unbounded least-recently-used cache.
|
|
717
|
+
|
|
718
|
+
**Fix:** lower `parseCache.maxBytes`, send variables instead of inline
|
|
719
|
+
values so the documents repeat, or bound your own cache:
|
|
720
|
+
|
|
721
|
+
```ts
|
|
722
|
+
graphql(app, { schema, parseCache: { maxBytes: 16 * 1024 * 1024 } });
|
|
723
|
+
```
|
|
724
|
+
|
|
584
725
|
### GraphiQL is served in production
|
|
585
726
|
|
|
586
727
|
**When:** a browser opening the production endpoint gets GraphiQL.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/graphql",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.1",
|
|
4
4
|
"description": "GraphQL for alxia with GraphQL Yoga: its plugins, subscriptions over SSE or WebSocket (graphql-ws) and GraphiQL, behind the app's hooks, its resolvers reading the app's typed context",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|