@alxia/graphql 0.16.5 → 0.18.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.
Files changed (74) hide show
  1. package/README.md +60 -62
  2. package/dist/endpoint.d.ts +14 -2
  3. package/dist/endpoint.d.ts.map +1 -1
  4. package/dist/executor.d.ts +20 -37
  5. package/dist/executor.d.ts.map +1 -1
  6. package/dist/explorer.d.ts +24 -0
  7. package/dist/explorer.d.ts.map +1 -0
  8. package/dist/graphql.d.ts +32 -95
  9. package/dist/graphql.d.ts.map +1 -1
  10. package/dist/handler.d.ts +7 -34
  11. package/dist/handler.d.ts.map +1 -1
  12. package/dist/index.d.ts +3 -4
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +301 -1011
  15. package/dist/index.js.map +14 -23
  16. package/dist/once-per-request.d.ts +5 -0
  17. package/dist/once-per-request.d.ts.map +1 -1
  18. package/dist/operation.d.ts +2 -7
  19. package/dist/operation.d.ts.map +1 -1
  20. package/dist/options.d.ts +38 -0
  21. package/dist/options.d.ts.map +1 -0
  22. package/dist/removed.d.ts +14 -0
  23. package/dist/removed.d.ts.map +1 -0
  24. package/dist/sandbox.d.ts +3 -17
  25. package/dist/sandbox.d.ts.map +1 -1
  26. package/dist/testing/client.d.ts +9 -7
  27. package/dist/testing/client.d.ts.map +1 -1
  28. package/dist/testing/index.js +5 -1
  29. package/dist/testing/index.js.map +3 -3
  30. package/dist/ws.d.ts +18 -30
  31. package/dist/ws.d.ts.map +1 -1
  32. package/docs/README.md +3 -2
  33. package/docs/guide/context.md +40 -32
  34. package/docs/guide/endpoint.md +42 -27
  35. package/docs/guide/executor.md +23 -8
  36. package/docs/guide/ide.md +27 -64
  37. package/docs/guide/{yoga.md → plugins.md} +87 -72
  38. package/docs/guide/production.md +115 -196
  39. package/docs/guide/testing.md +24 -24
  40. package/docs/guide/websockets.md +21 -14
  41. package/docs/migrating-to-graxia.md +283 -0
  42. package/docs/roadmap.md +7 -11
  43. package/docs/troubleshooting.md +231 -248
  44. package/package.json +15 -22
  45. package/dist/body-refusal.d.ts +0 -25
  46. package/dist/body-refusal.d.ts.map +0 -1
  47. package/dist/document-cache.d.ts +0 -39
  48. package/dist/document-cache.d.ts.map +0 -1
  49. package/dist/field-rate-limit/count.d.ts +0 -28
  50. package/dist/field-rate-limit/count.d.ts.map +0 -1
  51. package/dist/field-rate-limit/from-store.d.ts +0 -21
  52. package/dist/field-rate-limit/from-store.d.ts.map +0 -1
  53. package/dist/field-rate-limit/index.d.ts +0 -5
  54. package/dist/field-rate-limit/index.d.ts.map +0 -1
  55. package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
  56. package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
  57. package/dist/field-rate-limit/plugin.d.ts +0 -28
  58. package/dist/field-rate-limit/plugin.d.ts.map +0 -1
  59. package/dist/field-rate-limit/types.d.ts +0 -60
  60. package/dist/field-rate-limit/types.d.ts.map +0 -1
  61. package/dist/nesting.d.ts +0 -18
  62. package/dist/nesting.d.ts.map +0 -1
  63. package/dist/parse-limits.d.ts +0 -50
  64. package/dist/parse-limits.d.ts.map +0 -1
  65. package/dist/same-origin/index.d.ts +0 -2
  66. package/dist/same-origin/index.d.ts.map +0 -1
  67. package/dist/same-origin/same-origin.d.ts +0 -30
  68. package/dist/same-origin/same-origin.d.ts.map +0 -1
  69. package/dist/ws-operations.d.ts +0 -31
  70. package/dist/ws-operations.d.ts.map +0 -1
  71. package/dist/ws-server.d.ts +0 -32
  72. package/dist/ws-server.d.ts.map +0 -1
  73. package/dist/yoga.d.ts +0 -12
  74. package/dist/yoga.d.ts.map +0 -1
@@ -6,9 +6,9 @@ it answers, which middlewares run before it, and how to test it.
6
6
  ```ts
7
7
  import { alxia } from '@alxia/core';
8
8
  import { graphql } from '@alxia/graphql';
9
- import { createSchema } from 'graphql-yoga';
9
+ import { createSchema } from '@graxia/core';
10
10
 
11
- const schema = createSchema({
11
+ const schema = createSchema()({
12
12
  typeDefs: /* GraphQL */ `type Query { hello: String! }`,
13
13
  resolvers: { Query: { hello: () => 'world' } },
14
14
  });
@@ -49,20 +49,18 @@ routes on `base` and returns it.
49
49
 
50
50
  | Option | Type | Default | Effect |
51
51
  | --- | --- | --- | --- |
52
- | `schema` | `GraphQLSchemaWithContext<SchemaCtx>` | — | The schema, from Yoga's `createSchema` or any tool that types its context. Its context is checked against the app's: see [The typed context](context.md). |
52
+ | `schema` | `GraphQLSchemaWithContext<SchemaCtx>` | — | The schema, from graxia's `createSchema` (`@graxia/core`) or any tool that types its context. Its context is checked against the app's: see [The typed context](context.md). |
53
53
  | `path` | `` `/${string}` `` | `'/graphql'` | Where the endpoint is, under the app's prefix. |
54
54
  | `ide` | `'graphiql' \| 'apollo-sandbox' \| false` | GraphiQL in dev (`isDev`), none otherwise | What a browser gets at the endpoint: see [GraphiQL and Apollo Sandbox](ide.md). |
55
- | `graphiql` | Yoga's `GraphiQLOptions` | Yoga's | GraphiQL's options, when `ide` is `'graphiql'`. |
55
+ | `graphiql` | `GraphiQLOptions` of `@graxia/graphiql` | graxia's | GraphiQL's options, when `ide` is `'graphiql'`. |
56
56
  | `sandbox` | `SandboxOptions` | — | Apollo Sandbox's options, when `ide` is `'apollo-sandbox'`. |
57
- | `ws` | `boolean \| { path?, keepAlive? }` | `false` | GraphQL over WebSocket too, with the optional peer `graphql-ws`: see [GraphQL over WebSocket](websockets.md). |
58
- | `maxTokens` | `number \| false` | `15_000` | The most tokens a document may hold; a longer one is refused as `GRAPHQL_PARSE_FAILED`. `false` for no cap. Anything but a positive whole number throws where `graphql()` is declared: see [Cap what a request costs](production.md#cap-what-a-request-costs). |
59
- | `maxNesting` | `number \| false` | `1_000` | The most levels of `{`, `(` and `[` a document may nest; a deeper one is refused as `GRAPHQL_PARSE_FAILED` before the parser recurses into it, instead of overflowing the stack as a 500. `false` for no limit. Anything but a positive whole number throws where `graphql()` is declared: see [Cap what a request costs](production.md#cap-what-a-request-costs). |
60
- | `parseCache` | `false \| { maxBytes?, max?, ttl? }` | 64 MiB, 1 024 documents, 3 600 000 ms | The cache of parsed documents, one per endpoint, bounded by estimated bytes. `false` parses every request. Cannot be given with Yoga's `parserAndValidationCache`, which replaces it. |
61
- | `bodyLimit` | `number` | the app's earlier `bodyLimit()`, else `1_048_576` (1 MiB) | The most bytes a `POST` body may hold; past it core answers a 413, in the app's error format. A whole number of bytes, else core's `TypeError` where `graphql()` is declared. A `multipart` upload needs a larger one: see [Cap what a request costs](production.md#cap-what-a-request-costs). |
62
- | `cors` | Yoga's `cors` | `false` | Yoga's own CORS. Off: use `@alxia/cors` for the whole app instead ([Yoga's plugins and options](yoga.md#cors)). |
63
- | `logging` | Yoga's `logging` | `'warn'` | Yoga's info lines (on Yoga 6, one "Request processed" per request) are off unless you pass `true` or `'info'`: see [troubleshooting](../troubleshooting.md#x-request-id-echoed-or-request-processed-logged-on-yoga-6). |
64
- | `requestId` | Yoga 6's `requestId` | `false` | Off, so a client's `x-request-id` is never echoed or logged; `true` or an object keeps `trustHeader: false` unless you set it. Yoga 5 ignores it: see [troubleshooting](../troubleshooting.md#x-request-id-echoed-or-request-processed-logged-on-yoga-6). |
65
- | every other Yoga option | | Yoga's | `plugins`, `context`, `maskedErrors`, `batching`… passed to `createYoga` as they are: see [Yoga's plugins and options](yoga.md). On Yoga 6 a custom `logging` must be a `@graphql-hive/logger` `Logger`: see [`log.child is not a function`](../troubleshooting.md#logchild-is-not-a-function). |
57
+ | `ws` | `boolean \| { path?, keepAlive? }` | `false` | GraphQL over WebSocket too, served by graxia, no extra install: see [GraphQL over WebSocket](websockets.md). |
58
+ | `limits` | `{ tokens?, nesting?, bodyBytes? }` | `tokens: 15_000`, `nesting: 1_000` | `tokens` is the most tokens a document may hold and `nesting` the most levels of `{`, `(` and `[`; a longer or deeper one is refused as `GRAPHQL_PARSE_FAILED` before the parser recurses into it. `false` for no cap. Replaces `maxTokens` and `maxNesting`, which still work but are deprecated; a bad value is not rejected where `graphql()` is declared: see [Cap what a request costs](production.md#cap-what-a-request-costs). |
59
+ | `caches` | `false \| { parse?: { maxBytes?, max?, ttlMs? } \| false }` | `parse: { maxBytes: 64 MiB, max: 1_024 }` | The cache of parsed documents, bounded by the estimated bytes of its sources (`maxBytes`), its entries and their age. `false` parses every request. Replaces `parseCache`, which still maps (`maxBytes`, `max`, `ttl`). |
60
+ | `bodyLimit` | `number` | the app's earlier `bodyLimit()`, else `1_048_576` (1 MiB) | The most bytes a `POST` body may hold: graxia's `limits.bodyBytes`. Past it graxia answers `413` with `extensions.code: 'BODY_TOO_LARGE'`, whether the size is declared or counted. A positive whole number of bytes, else a `GraxiaConfigError` (it extends `Error`) with the message `limits.bodyBytes must be a positive integer`, thrown where `graphql()` is declared, before any route. A `multipart` upload needs a larger one: see [Cap what a request costs](production.md#cap-what-a-request-costs). |
61
+ | `cors`, `logging`, `requestId` | removed | — | Throw a `TypeError` naming the fix: `@alxia/cors` for CORS, graxia's `onUnexpected` and `@alxia/logger` for logs, graxia's `x-request-id` for the id: see [troubleshooting](../troubleshooting.md#graphqlapp--logging--requestid-or-cors-throws-a-typeerror). |
62
+ | `telemetry` | graxia's `telemetry` option | `{ operationSpans: false }` | graxia makes no operation span of its own, so `@alxia/telemetry`'s is the operation's only one; graxia's parse, validate and execute spans nest under it. `false` turns graxia's telemetry off altogether: see [graxia's own spans](#graxias-own-spans). |
63
+ | every other option | | graxia's | `plugins`, `context`, `maskErrors`, `batching`… given to graxia's `createGraxia`, which this package wraps: see [Plugins and options](plugins.md). |
66
64
 
67
65
  `graphqlEndpoint` is not an option: `path` sets it.
68
66
 
@@ -141,7 +139,7 @@ What the middlewares added is in each resolver's context: that is the next page,
141
139
 
142
140
  ## What it answers
143
141
 
144
- Yoga answers the request; the package passes its status, headers and body
142
+ graxia answers the request; the package passes its status, headers and body
145
143
  through as the route's reply, and adds a `Content-Security-Policy` to an
146
144
  IDE page ([GraphiQL and Apollo Sandbox](ide.md)).
147
145
 
@@ -149,9 +147,9 @@ IDE page ([GraphiQL and Apollo Sandbox](ide.md)).
149
147
  | --- | --- |
150
148
  | `POST` with `{"query": …}` | `200` and `{"data": …}`, with `errors` beside it when a resolver failed |
151
149
  | `GET ?query=…` | the same, for a query; a mutation is a `405` |
152
- | `POST` a subscription with `Accept: text/event-stream` | `200`, a `text/event-stream` of results ([subscriptions](yoga.md#subscriptions)) |
150
+ | `POST` a subscription with `Accept: text/event-stream` | `200`, a `text/event-stream` of results ([subscriptions](plugins.md#subscriptions)) |
153
151
  | a WebSocket upgrade offering `graphql-transport-ws`, `ws` on | `101`, then queries, mutations and subscriptions over the socket ([GraphQL over WebSocket](websockets.md)); with `ws` off, no `101` |
154
- | `GET` from a browser (`Accept: text/html`), no `query` | the IDE page; with `ide: false`, a GraphQL answer (`Must provide query string.`) |
152
+ | `GET` from a browser (`Accept: text/html`), no `query` | the IDE page; with `ide: false`, a GraphQL answer (`Must provide a query string.`) |
155
153
  | a middleware replied first | that middleware's reply, such as a `401` |
156
154
 
157
155
  ```text
@@ -166,9 +164,9 @@ the replies of the middlewares before them — a guard's `401`, say.
166
164
  ## The operation in the log and the trace
167
165
 
168
166
  Every call is a `POST /graphql`, so the route alone cannot tell `GetNotes`
169
- from `AddNote`. For each operation Yoga executes or subscribes to,
167
+ from `AddNote`. For each operation graxia executes or subscribes to,
170
168
  `graphql()` reports its type and name to the middlewares around it
171
- (`reportOperation` of `@alxia/core`, a Yoga plugin it adds after yours),
169
+ (`reportOperation` of `@alxia/core`, a graxia plugin it adds after yours),
172
170
  and no package imports another: `@alxia/logger` adds `operationName` and
173
171
  `operationType` to the request's line, and `@alxia/telemetry` names its
174
172
  span `query GetNotes` with `graphql.operation.name` and
@@ -196,15 +194,32 @@ const app = alxia()
196
194
  own, told to the observers around the upgrade
197
195
  ([WebSocket guide](websockets.md#logging-and-tracing)).
198
196
 
197
+ ### graxia's own spans
198
+
199
+ `graphql()` sets graxia's `telemetry` to `{ operationSpans: false }`, over
200
+ HTTP and over a WebSocket alike. graxia then makes no request or operation
201
+ span of its own, so `@alxia/telemetry`'s span is the operation's only one,
202
+ and its step spans (`graphql.parse`, `graphql.validate`, `graphql.execute`)
203
+ are children of that span, which is active when the request arrives. With
204
+ no span active (no `@alxia/telemetry` in front), graxia spans the request
205
+ and the operation itself, as usual. Pass `telemetry: { resolverSpans: true }`
206
+ (or any other graxia telemetry option) to add resolver spans: the
207
+ `operationSpans: false` default stays under the object you pass, and
208
+ `operationSpans: true` brings graxia's operation span back (and doubles
209
+ `@alxia/telemetry`'s). `telemetry: false` turns graxia's telemetry off
210
+ altogether, step spans included. See graxia's telemetry guide for the options.
211
+
199
212
  ## Errors, health and shutdown
200
213
 
201
214
  **GraphQL errors stay GraphQL's.** A resolver that throws, a query that
202
- does not validate, is an entry of `errors[]` in Yoga's answer — inside a
215
+ does not validate, is an entry of `errors[]` in graxia's answer — inside a
203
216
  `200`, as the GraphQL over HTTP specification has it — whatever
204
217
  `@alxia/core`'s `errors` option says. `alxia({ errors: 'problem' })`
205
218
  applies to the HTTP layer around the endpoint: `@alxia/jwt`'s 401 before
206
- it, a body past its `bodyLimit` (413), a middleware's 500, a `PUT` at its
207
- path (405) — each an `application/problem+json` problem
219
+ it, a middleware's 500, a `PUT` at its
220
+ path (405) — each an `application/problem+json` problem. A refusal graxia
221
+ builds (a body past `bodyLimit` is `413 BODY_TOO_LARGE`) keeps graxia's JSON
222
+ format and its `extensions.code`
208
223
  ([core's errors guide](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/errors.md#graphql)).
209
224
 
210
225
  ```text
@@ -236,22 +251,22 @@ app.listen({ port: 4000 }); // SIGTERM: /ready 503, queries answered, subscripti
236
251
 
237
252
  The endpoint runs in process through `app.fetch`, like every alxia route:
238
253
  no server, no port. `graphqlClient` from `@alxia/graphql/testing` sends the
239
- operation and reads the answer; `logging: false` keeps Yoga's logger quiet
240
- in the test output.
254
+ operation and reads the answer; graxia writes nothing to the console for a request, and
255
+ reports unexpected failures through `onUnexpected`.
241
256
 
242
257
  ```ts
243
258
  import { describe, expect, test } from 'bun:test';
244
259
  import { alxia } from '@alxia/core';
245
260
  import { graphql } from '@alxia/graphql';
246
261
  import { graphqlClient } from '@alxia/graphql/testing';
247
- import { createSchema } from 'graphql-yoga';
262
+ import { createSchema } from '@graxia/core';
248
263
 
249
- const schema = createSchema({
264
+ const schema = createSchema()({
250
265
  typeDefs: /* GraphQL */ `type Query { hello(name: String!): String! }`,
251
266
  resolvers: { Query: { hello: (_, { name }: { name: string }) => `hello ${name}` } },
252
267
  });
253
268
 
254
- const app = alxia().plugin((app) => graphql(app, { schema, logging: false }));
269
+ const app = alxia().plugin((app) => graphql(app, { schema }));
255
270
 
256
271
  describe('graphql', () => {
257
272
  test('hello', async () => {
@@ -271,7 +286,7 @@ Headers, a custom path, typed documents and the HTTP status are in
271
286
 
272
287
  - [The typed context](context.md): what a resolver reads, and the compile
273
288
  error when the app does not build it.
274
- - [Yoga's plugins and options](yoga.md): plugins, errors, subscriptions,
289
+ - [Plugins and options](plugins.md): plugins, errors, subscriptions,
275
290
  CORS.
276
291
  - [GraphiQL and Apollo Sandbox](ide.md): the page a browser gets.
277
292
  - [GraphQL over WebSocket](websockets.md): `ws`, for `graphql-ws`
@@ -3,7 +3,7 @@
3
3
  `graphqlExecutor(options)` runs a query or a mutation inside the process,
4
4
  without a route or a socket. Use it when the caller is not a browser: an MCP
5
5
  tool that serves GraphQL to a model, a background job, a script. It builds the
6
- same Yoga as `graphql()` from the same options, so the plugins, the token and
6
+ same graxia as `graphql()` from the same options, so the plugins, the token and
7
7
  nesting limits, the parse cache and the masking of errors apply as they do on
8
8
  the route. The server context is the one you pass.
9
9
 
@@ -36,15 +36,28 @@ const { data, errors } = await execute(
36
36
  | `call.signal` | an `AbortSignal` that stops the operation |
37
37
 
38
38
  It answers `{ data?, errors? }`, plain JSON as the endpoint's body would be:
39
- a GraphQL error is in `errors`, not thrown. A rejected `signal` rejects the
40
- promise.
39
+ a GraphQL error is in `errors`, not thrown. An aborted `signal` does not reject: see below.
40
+
41
+ ## Aborting
42
+
43
+ An aborted `signal`, before the call or while the operation runs, resolves to
44
+ `{ errors: [{ message: 'The operation was aborted.', extensions: { code: 'OPERATION_ABORTED' } }] }`
45
+ with no `data`. It never rejects, and `context.signal` aborts so a resolver
46
+ can stop its work. Errors come back as plain objects, not `GraphQLError`
47
+ instances.
48
+
49
+ ```ts
50
+ const result = await execute({ query }, context, { signal: AbortSignal.timeout(2_000) });
51
+ if (result.errors?.[0]?.extensions?.code === 'OPERATION_ABORTED') retryLater();
52
+ ```
41
53
 
42
54
  ## Its options
43
55
 
44
- `schema`, `plugins`, `maskedErrors` (on by default), `maxTokens` (15 000),
45
- `maxNesting` (1 000), `parseCache` (64 MiB, 1 024 documents, one hour; `false`
46
- for none), `logging` and Yoga's other options. Not `path`, `ide`, `ws`, `bodyLimit` or
47
- `cors`: they belong to a route.
56
+ `schema`, `plugins`, `maskErrors` (on by default), `limits` (`tokens` 15 000,
57
+ `nesting` 1 000), `caches` (`parse`: 1 024 documents; `false` for none) and
58
+ graxia's other options. Not `path`, `ide`, `ws`, `bodyLimit`, `csrf` or `cors`:
59
+ they belong to a route. CSRF is off for the executor, since there is no
60
+ browser request to forge, while the route has it on by default.
48
61
 
49
62
  ## What it does not do
50
63
 
@@ -56,5 +69,7 @@ for none), `logging` and Yoga's other options. Not `path`, `ide`, `ws`, `bodyLim
56
69
  - It runs queries and mutations. A subscription is answered with an error
57
70
  whose code is `SUBSCRIPTION_NOT_SUPPORTED`.
58
71
  - Its parse cache is its own, apart from the route's.
72
+ - It holds a graxia instance: `await executor.dispose()` when you are done
73
+ (a test's `afterAll`, a job's shutdown). A call after it rejects.
59
74
 
60
- See also: [Yoga's plugins and options](yoga.md), [the typed context](context.md).
75
+ See also: [Plugins and options](plugins.md), [the typed context](context.md).
package/docs/guide/ide.md CHANGED
@@ -1,16 +1,14 @@
1
1
  # GraphiQL and Apollo Sandbox
2
2
 
3
- This page covers what a browser gets when it opens the endpoint — Yoga's
4
- GraphiQL, Apollo Sandbox, or nothing — their options, the
5
- `Content-Security-Policy` each loads under, and `renderSandbox` for serving
6
- the Sandbox yourself.
3
+ This page covers what a browser gets when it opens the endpoint — GraphiQL, Apollo Sandbox, or nothing — their options, the
4
+ `Content-Security-Policy` each loads under.
7
5
 
8
6
  ```ts
9
7
  import { alxia } from '@alxia/core';
10
8
  import { graphql } from '@alxia/graphql';
11
- import { createSchema } from 'graphql-yoga';
9
+ import { createSchema } from '@graxia/core';
12
10
 
13
- const schema = createSchema({
11
+ const schema = createSchema()({
14
12
  typeDefs: /* GraphQL */ `type Query { hello: String! }`,
15
13
  resolvers: { Query: { hello: () => 'world' } },
16
14
  });
@@ -29,8 +27,8 @@ const app = alxia().plugin((app) =>
29
27
 
30
28
  | `ide` | A browser's `GET` at the endpoint gets | Options |
31
29
  | --- | --- | --- |
32
- | not given (default) | Yoga's GraphiQL in the serving app's dev — `alxia({ dev })`, else `NODE_ENV=development` — and no page elsewhere | `graphiql` |
33
- | `'graphiql'` | Yoga's GraphiQL, in every mode | `graphiql` |
30
+ | not given (default) | GraphiQL in the serving app's dev — `alxia({ dev })`, else `NODE_ENV=development` — and no page elsewhere | `graphiql` |
31
+ | `'graphiql'` | GraphiQL, in every mode | `graphiql` |
34
32
  | `'apollo-sandbox'` | [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox), embedded | `sandbox` |
35
33
  | `false` | no page: the request is answered as a GraphQL request | — |
36
34
 
@@ -50,9 +48,17 @@ guard's reply. By default the IDE is off outside dev; give `ide:
50
48
  'graphiql'` only where you mean to publish it. Before 0.5, GraphiQL was
51
49
  on in every mode.
52
50
 
51
+ The default follows the app's own dev flag, the one `isDev(ctx)` reads
52
+ (`alxia({ dev })`, else `NODE_ENV=development`), not `NODE_ENV` alone, and it
53
+ is read for each request: `alxia({ dev: false })` serves no page under
54
+ `NODE_ENV=development`, and `alxia({ dev: true })` serves it under
55
+ `NODE_ENV=production`. Apollo Sandbox, chosen with `ide: 'apollo-sandbox'`,
56
+ is served in every mode, like `ide: 'graphiql'`; pick it with a condition of
57
+ your own to keep it out of production.
58
+
53
59
  ## GraphiQL
54
60
 
55
- The default, in dev. `graphiql` takes Yoga's `GraphiQLOptions` — not `true` or
61
+ The default, in dev. `graphiql` takes `@graxia/graphiql`'s `GraphiQLOptions` — not `true` or
56
62
  `false`, which `ide` decides:
57
63
 
58
64
  ```ts
@@ -66,48 +72,39 @@ graphql(app, {
66
72
  });
67
73
  ```
68
74
 
69
- Its other options — `subscriptionsProtocol`, `credentials`,
70
- `additionalHeaders`… — are listed in
71
- [Yoga's GraphiQL documentation](https://the-guild.dev/graphql/yoga-server/docs/features/graphiql).
75
+ Its other options are listed in the `@graxia/graphiql` documentation.
72
76
 
73
- The page loads GraphiQL from one pinned folder on `unpkg.com`,
74
- `https://unpkg.com/@graphql-yoga/graphiql@<version>/`, the version the
75
- installed Yoga names. Yoga's response has no `Content-Security-Policy`, so
76
- the package adds one that lets that folder alone load — its scripts,
77
- styles and fonts, and the Monaco workers the page fetches — and no one
78
- frame the page:
77
+ The page serves GraphiQL's script and stylesheet itself, from the endpoint
78
+ (`?graphiql-asset=<file>`): nothing loads from a third-party host. The
79
+ response carries a strict `Content-Security-Policy` that lets those files
80
+ alone load, runs no worker and lets no one frame the page:
79
81
 
80
82
  ```text
81
- default-src 'self'; script-src 'self' 'unsafe-inline' https://unpkg.com/@graphql-yoga/graphiql@<version>/; style-src 'self' 'unsafe-inline' https://unpkg.com/@graphql-yoga/graphiql@<version>/; img-src 'self' data: https:; font-src 'self' data: https://unpkg.com/@graphql-yoga/graphiql@<version>/; worker-src 'self' blob:; connect-src 'self' https://unpkg.com/@graphql-yoga/graphiql@<version>/; frame-ancestors 'none'
83
+ default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; worker-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'
82
84
  ```
83
85
 
84
- A page of your own (`renderGraphiQL`) that names no such folder gets
85
- `'self'` alone.
86
-
87
86
  ## Apollo Sandbox
88
87
 
89
88
  `ide: 'apollo-sandbox'` serves a page embedding Apollo Sandbox, pointed at
90
- the endpoint: the route as served, prefixes included, resolved in the
91
- browser against the address the page was opened at. Behind a proxy that
92
- terminates TLS, the Sandbox asks over `https` as the browser did, with no
93
- option and no `X-Forwarded-Proto`. `sandbox` takes `SandboxOptions`:
89
+ the endpoint: the page's own address without its query, read by the
90
+ browser, prefixes included. Behind a proxy that terminates TLS, the Sandbox
91
+ asks over `https` as the browser did, with no option and no
92
+ `X-Forwarded-Proto`. `sandbox` takes `SandboxOptions`:
94
93
 
95
94
  ```ts
96
95
  interface SandboxOptions {
97
96
  readonly title?: string;
98
97
  readonly initialDocument?: string;
99
98
  readonly initialHeaders?: Readonly<Record<string, string>>;
100
- readonly pollForSchemaUpdates?: boolean;
101
99
  readonly includeCookies?: boolean;
102
100
  }
103
101
  ```
104
102
 
105
103
  | Option | Type | Default | Effect |
106
104
  | --- | --- | --- | --- |
107
- | `title` | `string` | `'Sandbox Explorer'` | The page's `<title>`. |
105
+ | `title` | `string` | `'Apollo Sandbox'` | The page's `<title>`. |
108
106
  | `initialDocument` | `string` | none | The operation the Sandbox opens with. |
109
107
  | `initialHeaders` | `Record<string, string>` | none | Headers every operation sends, shown and editable in the Sandbox. |
110
- | `pollForSchemaUpdates` | `boolean` | `true` | Whether the Sandbox polls the schema as it changes. |
111
108
  | `includeCookies` | `boolean` | `true` | Whether operations send the browser's cookies, such as a session cookie. |
112
109
 
113
110
  ```ts
@@ -128,7 +125,7 @@ into the page's HTML and script, so a title or document from configuration
128
125
  cannot break out of it.
129
126
 
130
127
  The page loads the Sandbox's script from Apollo's CDN and frames
131
- `sandbox.embed.apollographql.com`; it is sent with `SANDBOX_POLICY`:
128
+ `sandbox.embed.apollographql.com`; it is sent with `sandboxContentSecurityPolicy()` from `@graxia/graphiql`:
132
129
 
133
130
  ```text
134
131
  default-src 'self'; script-src 'self' 'unsafe-inline' https://embeddable-sandbox.cdn.apollographql.com; style-src 'self' 'unsafe-inline'; frame-src https://sandbox.embed.apollographql.com; img-src 'self' data: https:; connect-src 'self'
@@ -157,40 +154,6 @@ const app = alxia()
157
154
  .plugin((app) => graphql(app, { schema }));
158
155
  ```
159
156
 
160
- ## `renderSandbox`
161
-
162
- ```ts no-check
163
- function renderSandbox(endpoint: string, options?: SandboxOptions): string;
164
- const SANDBOX_POLICY: string;
165
- ```
166
-
167
- The page `ide: 'apollo-sandbox'` serves, as an HTML string, for a Sandbox
168
- you serve yourself: at another path than the endpoint, or pointed at
169
- another server. `endpoint` is a URL, or a path the page resolves in the
170
- browser against its own address — so `'/graphql'` is asked over `https`
171
- when the page was opened over `https`, proxy or not. Send it with
172
- `SANDBOX_POLICY`:
173
-
174
- ```ts
175
- import { alxia } from '@alxia/core';
176
- import { graphql, renderSandbox, SANDBOX_POLICY } from '@alxia/graphql';
177
-
178
- const app = alxia()
179
- .plugin((app) => graphql(app, { schema, ide: false }))
180
- .get('/explorer', ({ reply }) =>
181
- reply(200, renderSandbox('/graphql', { title: 'Users API' }), {
182
- headers: {
183
- 'content-type': 'text/html;charset=utf-8',
184
- 'content-security-policy': SANDBOX_POLICY,
185
- },
186
- }),
187
- );
188
- ```
189
-
190
- Pass the path the browser sees when a proxy serves the app under one of its
191
- own — `renderSandbox('/v1/graphql')` — and a full URL for an endpoint on
192
- another server: `renderSandbox('https://api.example.com/graphql')`.
193
-
194
157
  ## See also
195
158
 
196
159
  - [Mounting the endpoint](endpoint.md): which middlewares run before the page.