@alxia/graphql 0.9.0 → 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 CHANGED
@@ -210,6 +210,7 @@ alone: a WebSocket `subscribe` message is bounded by Bun's `maxPayloadLength`
210
210
  graphql(app, {
211
211
  schema,
212
212
  maxTokens: 20_000, // false: no cap
213
+ maxNesting: 2_000, // 1 000 by default; false: no cap
213
214
  parseCache: { maxBytes: 32 * 1024 * 1024, max: 512, ttl: 30 * 60_000 }, // false: no cache
214
215
  bodyLimit: 5 * 1024 * 1024, // 1 MiB by default; a multipart upload needs more
215
216
  });
package/docs/README.md CHANGED
@@ -12,7 +12,7 @@ a realistic example for each.
12
12
  | [The typed context](guide/context.md) | typing a schema with the app's context, reading `user` or a database handle in a resolver, setting a cookie, adding per-request loaders, or reading the `missing …` compile error |
13
13
  | [Yoga's plugins and options](guide/yoga.md) | adding Yoga or Envelop plugins, exposing or masking errors, batching, serving subscriptions, or calling the endpoint from another origin |
14
14
  | [GraphQL over WebSocket](guide/websockets.md) | serving Apollo Client's, urql's or `graphql-ws`'s WebSocket clients with `ws: true`, guarding the upgrade, reading `connectionParams`, the subprotocol, closing the sockets on shutdown, or testing a subscription over a socket |
15
- | [Harden it for production](guide/production.md) | putting a GraphQL API on the internet: rate limiting the endpoint, depth limits, introspection off outside development, masked errors and the errors a client may read, a body limit, CSRF for a cookie session, persisted operations |
15
+ | [Harden it for production](guide/production.md) | putting a GraphQL API on the internet: rate limiting the endpoint, depth limits, the token cap, the nesting cap, the parse cache and the body limit, introspection off outside development, masked errors and the errors a client may read, a body limit, CSRF for a cookie session, persisted operations |
16
16
  | [GraphiQL and Apollo Sandbox](guide/ide.md) | choosing the IDE a browser gets, configuring it, keeping it working under a strict `Content-Security-Policy`, or serving it outside dev with `ide: 'graphiql'` |
17
17
  | [Testing the endpoint](guide/testing.md) | testing a GraphQL app without a server: `graphqlClient`, an auth header, a custom path, `GET`, persisted operations, the CSRF header, a typed document, the HTTP status of a 400 or a 413 |
18
18
  | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message |
@@ -142,7 +142,8 @@ each) sit outside the weight, bounded at roughly 70 KB per document.
142
142
 
143
143
  `maxTokens` does not count comments, yet a
144
144
  parsed document keeps all of them alive: a 750 KB body of `#` lines holds
145
- about 19.6 MB, so it weighs more than the cache keeps and is parsed again
145
+ about 19.6 MB (one `#` per line, `#\n`: each comment becomes a token the
146
+ document keeps), so it weighs more than the cache keeps and is parsed again
146
147
  each time instead of cached.
147
148
 
148
149
  - **`maxTokens`, 15 000 by default** (Apollo Router's own limit). The
@@ -206,7 +207,11 @@ as the bytes arrive:
206
207
  route answers, in the app's error format (`application/problem+json` under
207
208
  `errors: 'problem'`), with a `Content-Length` or without one (a chunked
208
209
  body). It carries the headers Yoga's plugins set, such as a
209
- `Cache-Control: no-store` from an `onResponse` hook. A form-urlencoded or
210
+ `Cache-Control: no-store` from an `onResponse` hook. Headers merge by
211
+ name: `Vary` is merged with the app's own, `Set-Cookie` is appended, and any
212
+ other header Yoga sets overwrites the app's header of the same name (Yoga's
213
+ `Content-Type`, `Content-Length`, `Content-Encoding` and `Transfer-Encoding`
214
+ are never carried). A form-urlencoded or
210
215
  `application/graphql` body past the limit is refused the same way and logs
211
216
  nothing. Whatever else Yoga cannot parse is still its 400, and its
212
217
  parser's own error is never sent (`extensions.originalError` is removed).
@@ -285,7 +290,7 @@ export const persisted: Plugin = usePersistedOperations({
285
290
 
286
291
  ## Together
287
292
 
288
- `maxTokens` and `parseCache` need no line here: their defaults apply. The
293
+ `maxTokens`, `maxNesting` and `parseCache` need no line here: their defaults apply. The
289
294
  `bodyLimit()` below is the app's own and is kept; without it the `POST` takes
290
295
  1 MiB.
291
296
 
@@ -192,7 +192,10 @@ otherwise — and the subscription goes on or completes as over HTTP. A
192
192
  query that does not parse or validate is answered with an `error`
193
193
  message, the protocol's, and the socket stays open. `maxTokens` applies to
194
194
  each operation: a `subscribe` message holding a longer document gets that
195
- `error`, `Document contains more than 15000 tokens`.
195
+ `error`, `Document contains more than 15000 tokens`. `maxNesting` applies to
196
+ each `subscribe` operation the same way: a document nested deeper gets an
197
+ `error` message carrying `GRAPHQL_PARSE_FAILED`, the socket stays open and
198
+ nothing is logged.
196
199
 
197
200
  `bodyLimit` does not reach the socket: a `subscribe` message is bounded by
198
201
  Bun's `maxPayloadLength` (16 MiB by default), not by the 1 MiB a `POST` body
@@ -35,6 +35,9 @@ symptom.
35
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)
36
36
  - [`406` with an empty body](#406-with-an-empty-body)
37
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)
38
41
  - [`{"errors":[{"message":"Must provide query string."}]}`](#errorsmessagemust-provide-query-string)
39
42
  - [`4406 Subprotocol not acceptable`](#4406-subprotocol-not-acceptable)
40
43
 
@@ -341,8 +344,8 @@ graphql(app, { schema, maxTokens: 30_000 }); // or false
341
344
 
342
345
  **When:** a query is answered with `GRAPHQL_PARSE_FAILED` (400 under
343
346
  `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.`
347
+ message. A document that overflowed the stack anyway has
348
+ [its own entry](#syntax-error-document-is-nested-too-deeply-to-parse).
346
349
 
347
350
  **Why:** a document may nest 1 000 levels of `{`, `(` and `[` by default
348
351
  (`maxNesting`). graphql-js parses by recursion and overflows the stack a few
@@ -358,6 +361,24 @@ Bun's main thread, fewer in a Worker), or turn it off:
358
361
  graphql(app, { schema, maxNesting: 2_000 }); // or false
359
362
  ```
360
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
+
361
382
  ### `TypeError: graphql(app, { maxNesting }): maxNesting is the most levels of { ( [ a document may nest, a positive whole number, or false for none; got …`
362
383
 
363
384
  **When:** declaring `graphql(app, { maxNesting })` with `0`, a negative number,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/graphql",
3
- "version": "0.9.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",