@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.
@@ -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 the `bodyLimit` declared
300
- before `graphql(...)`, with a `Content-Length` or chunked.
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 route takes a larger limit:
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
- alxia()
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.8.3",
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",