@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 +1 -0
- package/docs/README.md +1 -1
- package/docs/guide/production.md +8 -3
- package/docs/guide/websockets.md +4 -1
- package/docs/troubleshooting.md +23 -2
- package/package.json +1 -1
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 |
|
package/docs/guide/production.md
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
|
package/docs/guide/websockets.md
CHANGED
|
@@ -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
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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
|
|
345
|
-
|
|
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.
|
|
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",
|