@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.
- package/README.md +60 -62
- package/dist/endpoint.d.ts +14 -2
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/executor.d.ts +20 -37
- package/dist/executor.d.ts.map +1 -1
- package/dist/explorer.d.ts +24 -0
- package/dist/explorer.d.ts.map +1 -0
- package/dist/graphql.d.ts +32 -95
- package/dist/graphql.d.ts.map +1 -1
- package/dist/handler.d.ts +7 -34
- package/dist/handler.d.ts.map +1 -1
- package/dist/index.d.ts +3 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +301 -1011
- package/dist/index.js.map +14 -23
- package/dist/once-per-request.d.ts +5 -0
- package/dist/once-per-request.d.ts.map +1 -1
- package/dist/operation.d.ts +2 -7
- package/dist/operation.d.ts.map +1 -1
- package/dist/options.d.ts +38 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/removed.d.ts +14 -0
- package/dist/removed.d.ts.map +1 -0
- package/dist/sandbox.d.ts +3 -17
- package/dist/sandbox.d.ts.map +1 -1
- package/dist/testing/client.d.ts +9 -7
- package/dist/testing/client.d.ts.map +1 -1
- package/dist/testing/index.js +5 -1
- package/dist/testing/index.js.map +3 -3
- package/dist/ws.d.ts +18 -30
- package/dist/ws.d.ts.map +1 -1
- package/docs/README.md +3 -2
- package/docs/guide/context.md +40 -32
- package/docs/guide/endpoint.md +42 -27
- package/docs/guide/executor.md +23 -8
- package/docs/guide/ide.md +27 -64
- package/docs/guide/{yoga.md → plugins.md} +87 -72
- package/docs/guide/production.md +115 -196
- package/docs/guide/testing.md +24 -24
- package/docs/guide/websockets.md +21 -14
- package/docs/migrating-to-graxia.md +283 -0
- package/docs/roadmap.md +7 -11
- package/docs/troubleshooting.md +231 -248
- package/package.json +15 -22
- package/dist/body-refusal.d.ts +0 -25
- package/dist/body-refusal.d.ts.map +0 -1
- package/dist/document-cache.d.ts +0 -39
- package/dist/document-cache.d.ts.map +0 -1
- package/dist/field-rate-limit/count.d.ts +0 -28
- package/dist/field-rate-limit/count.d.ts.map +0 -1
- package/dist/field-rate-limit/from-store.d.ts +0 -21
- package/dist/field-rate-limit/from-store.d.ts.map +0 -1
- package/dist/field-rate-limit/index.d.ts +0 -5
- package/dist/field-rate-limit/index.d.ts.map +0 -1
- package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
- package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
- package/dist/field-rate-limit/plugin.d.ts +0 -28
- package/dist/field-rate-limit/plugin.d.ts.map +0 -1
- package/dist/field-rate-limit/types.d.ts +0 -60
- package/dist/field-rate-limit/types.d.ts.map +0 -1
- package/dist/nesting.d.ts +0 -18
- package/dist/nesting.d.ts.map +0 -1
- package/dist/parse-limits.d.ts +0 -50
- package/dist/parse-limits.d.ts.map +0 -1
- package/dist/same-origin/index.d.ts +0 -2
- package/dist/same-origin/index.d.ts.map +0 -1
- package/dist/same-origin/same-origin.d.ts +0 -30
- package/dist/same-origin/same-origin.d.ts.map +0 -1
- package/dist/ws-operations.d.ts +0 -31
- package/dist/ws-operations.d.ts.map +0 -1
- package/dist/ws-server.d.ts +0 -32
- package/dist/ws-server.d.ts.map +0 -1
- package/dist/yoga.d.ts +0 -12
- package/dist/yoga.d.ts.map +0 -1
package/docs/guide/endpoint.md
CHANGED
|
@@ -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 '
|
|
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
|
|
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` |
|
|
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,
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
|
|
|
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
|
-
|
|
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](
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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;
|
|
240
|
-
|
|
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 '
|
|
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
|
|
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
|
-
- [
|
|
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`
|
package/docs/guide/executor.md
CHANGED
|
@@ -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
|
|
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.
|
|
40
|
-
|
|
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`, `
|
|
45
|
-
`
|
|
46
|
-
|
|
47
|
-
|
|
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: [
|
|
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 —
|
|
4
|
-
|
|
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 '
|
|
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) |
|
|
33
|
-
| `'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
|
|
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
|
|
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
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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 '
|
|
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
|
|
91
|
-
browser
|
|
92
|
-
|
|
93
|
-
|
|
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
|
|
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 `
|
|
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.
|