@alxia/graphql 0.8.3 → 0.9.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 +37 -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/guide/endpoint.md +4 -0
- package/docs/guide/production.md +110 -14
- package/docs/guide/websockets.md +11 -1
- package/docs/roadmap.md +22 -2
- package/docs/troubleshooting.md +127 -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**
|
|
@@ -270,8 +271,102 @@ ping in a loop.
|
|
|
270
271
|
graphql(app, { schema, ws: { keepAlive: 30_000 } });
|
|
271
272
|
```
|
|
272
273
|
|
|
274
|
+
### `TypeError: POST /graphql: bodyLimit must be a whole number of bytes, 0 or more; got -1`
|
|
275
|
+
|
|
276
|
+
**When:** declaring `graphql(app, { bodyLimit })` with a negative number, a
|
|
277
|
+
fraction, `NaN`, `Infinity` or a string; the message names the route (the
|
|
278
|
+
endpoint's `path`) and the value given.
|
|
279
|
+
|
|
280
|
+
**Why:** `bodyLimit` is a count of bytes, checked by core where the `POST`
|
|
281
|
+
is declared.
|
|
282
|
+
|
|
283
|
+
**Fix:** a whole number of bytes, 0 or more:
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### `TypeError: graphql(app, { maxTokens }): maxTokens is the most tokens a document may hold, a positive whole number, or false for none; got …`
|
|
290
|
+
|
|
291
|
+
**When:** declaring `graphql(app, { maxTokens })` with `0`, a negative number,
|
|
292
|
+
a fraction, `NaN` or a string; the message names the value given.
|
|
293
|
+
|
|
294
|
+
**Why:** `maxTokens` is a count of tokens.
|
|
295
|
+
|
|
296
|
+
**Fix:** a positive whole number, or `false` for no cap:
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
graphql(app, { schema, maxTokens: 30_000 });
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### `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 …`
|
|
303
|
+
|
|
304
|
+
**When:** declaring `graphql()` with both `parseCache` and Yoga's
|
|
305
|
+
`parserAndValidationCache`, or with a `parseCache.maxBytes`, `max` or `ttl`
|
|
306
|
+
that is not a positive whole number, or with a `parseCache` that is neither
|
|
307
|
+
an object nor `false` (`true`, `null`, a number, a string).
|
|
308
|
+
|
|
309
|
+
**Why:** `parseCache` sizes alxia's bounded cache and
|
|
310
|
+
`parserAndValidationCache` replaces it with yours, so the two cannot both
|
|
311
|
+
apply.
|
|
312
|
+
|
|
313
|
+
**Fix:** give one:
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
graphql(app, { schema, parseCache: { maxBytes: 16 * 1024 * 1024 } });
|
|
317
|
+
```
|
|
318
|
+
|
|
273
319
|
## Responses
|
|
274
320
|
|
|
321
|
+
### `Syntax Error: Document contains more than 15000 tokens. Parsing aborted.`
|
|
322
|
+
|
|
323
|
+
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
|
|
324
|
+
`application/graphql-response+json`, 200 under `application/json`) and this
|
|
325
|
+
message. graphql 16 words it `more that`, 17 `more than`.
|
|
326
|
+
|
|
327
|
+
**Why:** a document may hold 15 000 tokens by default (`maxTokens`),
|
|
328
|
+
so that no request makes the server parse and keep an unbounded one. A
|
|
329
|
+
generated query or a screen with many inlined fragments can pass it; a
|
|
330
|
+
client that worked before is refused.
|
|
331
|
+
|
|
332
|
+
**Fix:** raise the limit to what your largest real query needs, or turn it
|
|
333
|
+
off. Persisted operations keep clients from sending large documents at all
|
|
334
|
+
([Persisted operations](guide/production.md#persisted-operations-briefly)):
|
|
335
|
+
|
|
336
|
+
```ts
|
|
337
|
+
graphql(app, { schema, maxTokens: 30_000 }); // or false
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### `Syntax Error: Document is nested more than 1000 levels deep. Parsing aborted.`
|
|
341
|
+
|
|
342
|
+
**When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
|
|
343
|
+
`application/graphql-response+json`, 200 under `application/json`) and this
|
|
344
|
+
message. A document that overflowed the stack anyway is worded `Syntax Error:
|
|
345
|
+
Document is nested too deeply to parse.`
|
|
346
|
+
|
|
347
|
+
**Why:** a document may nest 1 000 levels of `{`, `(` and `[` by default
|
|
348
|
+
(`maxNesting`). graphql-js parses by recursion and overflows the stack a few
|
|
349
|
+
thousand levels down, under `maxTokens`; without the limit that was a 500
|
|
350
|
+
`Unexpected error.`, logged. A real query nests a dozen levels, so this is
|
|
351
|
+
a hostile or generated document.
|
|
352
|
+
|
|
353
|
+
**Fix:** if a generated query really nests deeper, raise the limit, within
|
|
354
|
+
what your runtime's stack parses (several thousand levels: about 10 000 on
|
|
355
|
+
Bun's main thread, fewer in a Worker), or turn it off:
|
|
356
|
+
|
|
357
|
+
```ts
|
|
358
|
+
graphql(app, { schema, maxNesting: 2_000 }); // or false
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
### `TypeError: graphql(app, { maxNesting }): maxNesting is the most levels of { ( [ a document may nest, a positive whole number, or false for none; got …`
|
|
362
|
+
|
|
363
|
+
**When:** declaring `graphql(app, { maxNesting })` with `0`, a negative number,
|
|
364
|
+
a fraction, `NaN` or a string.
|
|
365
|
+
|
|
366
|
+
**Why:** `maxNesting` is a count of nesting levels.
|
|
367
|
+
|
|
368
|
+
**Fix:** a positive whole number, or `false` for no limit.
|
|
369
|
+
|
|
275
370
|
### `200 {"errors":[{"message":"Unexpected error.", … "code":"INTERNAL_SERVER_ERROR"}}]}`
|
|
276
371
|
|
|
277
372
|
**When:** a resolver throws an `Error`, or rejects.
|
|
@@ -296,19 +391,25 @@ throw createGraphQLError('Admins only', {
|
|
|
296
391
|
|
|
297
392
|
### `413 {"error":"content_too_large", …}` on `POST /graphql`
|
|
298
393
|
|
|
299
|
-
**When:** the body of a `POST` is larger than
|
|
300
|
-
|
|
394
|
+
**When:** the body of a `POST` is larger than its limit, with a
|
|
395
|
+
`Content-Length` or chunked. The limit is **1 MiB** unless the `bodyLimit`
|
|
396
|
+
option or a `bodyLimit()` declared before `graphql(...)` gives another.
|
|
301
397
|
|
|
302
398
|
**Why:** core counts the bytes as they arrive and fails the read past the
|
|
303
399
|
limit; the endpoint answers it as any route does, in the app's error format
|
|
304
|
-
(`application/problem+json` under `errors: 'problem'`).
|
|
400
|
+
(`application/problem+json` under `errors: 'problem'`). The 413 carries the
|
|
401
|
+
headers Yoga's plugins set (`Cache-Control: no-store`…), and nothing is
|
|
402
|
+
logged, whatever the content type (JSON, form-urlencoded,
|
|
403
|
+
`application/graphql`). The body is read by the endpoint, after the
|
|
404
|
+
middlewares declared before it: they still run for an oversized body, even
|
|
405
|
+
when `bodyLimit()` stands above them. Put the costly ones (a session lookup,
|
|
406
|
+
a database call) late.
|
|
305
407
|
|
|
306
|
-
**Fix:** a client sends less, or the
|
|
408
|
+
**Fix:** a client sends less, or the endpoint takes a larger limit, for an
|
|
409
|
+
upload by `multipart` for example:
|
|
307
410
|
|
|
308
411
|
```ts
|
|
309
|
-
|
|
310
|
-
.bodyLimit(512 * 1024) // before graphql(...)
|
|
311
|
-
.plugin((app) => graphql(app, { schema }));
|
|
412
|
+
graphql(app, { schema, bodyLimit: 5 * 1024 * 1024 });
|
|
312
413
|
```
|
|
313
414
|
|
|
314
415
|
### `403 Required CSRF header(s) not present` from the test client
|
|
@@ -581,6 +682,25 @@ const defaultPolicy = defineMiddleware(async (ctx, next) =>
|
|
|
581
682
|
app.use(defaultPolicy); // before the endpoint, so it wraps it
|
|
582
683
|
```
|
|
583
684
|
|
|
685
|
+
### The heap grows with distinct queries
|
|
686
|
+
|
|
687
|
+
**When:** a server that receives many different large queries, such as
|
|
688
|
+
generated ones or ones built with inline values, holds more and more memory.
|
|
689
|
+
|
|
690
|
+
**Why:** Yoga's own parse cache keeps up to 1 024 documents, whatever their
|
|
691
|
+
size, for an hour. `graphql()` replaces it with a cache bounded by weight
|
|
692
|
+
(`parseCache`, 64 MiB by default) unless the app gives Yoga's
|
|
693
|
+
`parserAndValidationCache`: then that cache is the app's to bound. Giving
|
|
694
|
+
Yoga's `parserAndValidationCache` in any form, `{ validationCache: false }`
|
|
695
|
+
included, brings back Yoga's unbounded least-recently-used cache.
|
|
696
|
+
|
|
697
|
+
**Fix:** lower `parseCache.maxBytes`, send variables instead of inline
|
|
698
|
+
values so the documents repeat, or bound your own cache:
|
|
699
|
+
|
|
700
|
+
```ts
|
|
701
|
+
graphql(app, { schema, parseCache: { maxBytes: 16 * 1024 * 1024 } });
|
|
702
|
+
```
|
|
703
|
+
|
|
584
704
|
### GraphiQL is served in production
|
|
585
705
|
|
|
586
706
|
**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.0",
|
|
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",
|