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