@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/websockets.md
CHANGED
|
@@ -13,9 +13,9 @@ bun add graphql-ws
|
|
|
13
13
|
```ts
|
|
14
14
|
import { alxia } from '@alxia/core';
|
|
15
15
|
import { graphql } from '@alxia/graphql';
|
|
16
|
-
import { createSchema } from '
|
|
16
|
+
import { createSchema } from '@graxia/core';
|
|
17
17
|
|
|
18
|
-
const schema = createSchema({
|
|
18
|
+
const schema = createSchema()({
|
|
19
19
|
typeDefs: /* GraphQL */ `
|
|
20
20
|
type Query { hello: String! }
|
|
21
21
|
type Subscription { countdown(from: Int!): Int! }
|
|
@@ -57,7 +57,7 @@ of each kind works against one deployment.
|
|
|
57
57
|
graphql(app, { schema, ws: { path: '/graphql/ws', keepAlive: 30_000 } });
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
A socket at a path of its own runs the endpoint's
|
|
60
|
+
A socket at a path of its own runs the endpoint's graxia instance: its plugins are
|
|
61
61
|
set up once, for both. Queries, mutations and subscriptions all run over a
|
|
62
62
|
socket. The socket
|
|
63
63
|
route shows in the route table `listen` prints in dev, as `WS /graphql`.
|
|
@@ -73,7 +73,7 @@ the middlewares add is in every resolver's context, typed as over HTTP:
|
|
|
73
73
|
```ts
|
|
74
74
|
import { alxia, defineMiddleware } from '@alxia/core';
|
|
75
75
|
import { type GraphQLContext, graphql } from '@alxia/graphql';
|
|
76
|
-
import { createSchema } from '
|
|
76
|
+
import { createSchema } from '@graxia/core';
|
|
77
77
|
|
|
78
78
|
// A browser cannot set a header on a WebSocket: the token comes in the URL
|
|
79
79
|
// or a cookie there. A server-side client can send `authorization`.
|
|
@@ -84,7 +84,7 @@ const viewer = defineMiddleware(({ url, reply }, next) => {
|
|
|
84
84
|
|
|
85
85
|
const base = alxia().use(viewer);
|
|
86
86
|
|
|
87
|
-
const schema = createSchema<GraphQLContext<typeof base>>({
|
|
87
|
+
const schema = createSchema<GraphQLContext<typeof base>>()({
|
|
88
88
|
typeDefs: /* GraphQL */ `
|
|
89
89
|
type Query { me: String! }
|
|
90
90
|
type Subscription { countdown(from: Int!): Int! }
|
|
@@ -105,18 +105,19 @@ export const app = base.plugin((app) => graphql(app, { schema, ws: true }));
|
|
|
105
105
|
```
|
|
106
106
|
|
|
107
107
|
The upgrade names `graphql-transport-ws` in its `101` when the client
|
|
108
|
-
offers it; a client that offers only another subprotocol is
|
|
109
|
-
|
|
108
|
+
offers it; a client that offers only another subprotocol is refused before
|
|
109
|
+
the upgrade with an HTTP `400` and `SUBPROTOCOL_REQUIRED`
|
|
110
|
+
([Troubleshooting](../troubleshooting.md#the-sec-websocket-protocol-header-must-offer-graphql-transport-ws-400-subprotocol_required)).
|
|
110
111
|
|
|
111
112
|
## The context of an operation over the socket
|
|
112
113
|
|
|
113
|
-
Each operation runs through
|
|
114
|
-
apply —
|
|
114
|
+
Each operation runs through graxia, as over HTTP: its plugins
|
|
115
|
+
apply — masked errors, depth limits — and its
|
|
115
116
|
`context` option is called. The context holds:
|
|
116
117
|
|
|
117
118
|
- what the upgrade's middlewares added, `set` and `ip` included;
|
|
118
119
|
- `params`: the operation's `query`, `variables`, `operationName`;
|
|
119
|
-
- `request`: the upgrade's URL and headers, as a `POST` — to
|
|
120
|
+
- `request`: the upgrade's URL and headers, as a `POST` — to graxia an
|
|
120
121
|
operation over the socket is one, so a mutation runs — its `signal`
|
|
121
122
|
aborted when the socket closes;
|
|
122
123
|
- `connectionParams`: what the client sent when it connected
|
|
@@ -124,10 +125,10 @@ apply — Envelop's and Yoga's, masked errors, depth limits — and its
|
|
|
124
125
|
|
|
125
126
|
```ts
|
|
126
127
|
import type { GraphQLContext } from '@alxia/graphql';
|
|
127
|
-
import { createSchema } from '
|
|
128
|
+
import { createSchema } from '@graxia/core';
|
|
128
129
|
import type { app } from './app';
|
|
129
130
|
|
|
130
|
-
const schema = createSchema<GraphQLContext<typeof app>>({
|
|
131
|
+
const schema = createSchema<GraphQLContext<typeof app>>()({
|
|
131
132
|
typeDefs: /* GraphQL */ 'type Query { device: String }',
|
|
132
133
|
resolvers: {
|
|
133
134
|
Query: {
|
|
@@ -177,10 +178,16 @@ const app = alxia()
|
|
|
177
178
|
(in `errors[]`), a document that does not validate, a subscription that
|
|
178
179
|
failed. A message that does not parse names no operation, and is not
|
|
179
180
|
told.
|
|
181
|
+
- graxia makes no operation span of its own (`telemetry: { operationSpans:
|
|
182
|
+
false }`), so an operation is one span, `@alxia/telemetry`'s, with graxia's
|
|
183
|
+
parse, validate and execute spans under the upgrade's span; pass `telemetry`
|
|
184
|
+
to `graphql()` to change that.
|
|
180
185
|
- Without either observer, nothing is told, and the operations run as
|
|
181
186
|
they do.
|
|
182
187
|
|
|
183
|
-
`graphql()` tells them with core's `startOperation`,
|
|
188
|
+
`graphql()` tells them with core's `startOperation`, from a graxia plugin on
|
|
189
|
+
`onExecute` and `onSubscribe` (a query or mutation ends with its result, a
|
|
190
|
+
subscription when its `signal` aborts), and they subscribe
|
|
184
191
|
during the upgrade with `onOperation`: no package imports another
|
|
185
192
|
([core's plugin guide](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md)).
|
|
186
193
|
|
|
@@ -304,7 +311,7 @@ test('a subscription over the socket', async () => {
|
|
|
304
311
|
|
|
305
312
|
## See also
|
|
306
313
|
|
|
307
|
-
- [
|
|
314
|
+
- [Plugins and options](plugins.md#subscriptions): subscriptions over
|
|
308
315
|
server-sent events, `createPubSub`.
|
|
309
316
|
- [Mounting the endpoint](endpoint.md#errors-health-and-shutdown): the
|
|
310
317
|
drain, health probes.
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# Migrating to graxia
|
|
2
|
+
|
|
3
|
+
`@alxia/graphql` used to mount GraphQL Yoga. It now runs on
|
|
4
|
+
[graxia](https://github.com/softistx/graxia) (`@graxia/core`): the same
|
|
5
|
+
`graphql(app, options)` call and the same typed context, on a different
|
|
6
|
+
engine. This is a **breaking** release (a `0.x` minor, so `^0.16` does not take it). Plan it as a migration, not a bump: the
|
|
7
|
+
checklist at the end is the order to follow.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
graxia is built for graphql 17 and for a host that owns `Bun.serve`: it ships
|
|
12
|
+
the limits, the caches, the refusal codes, the CSRF check, server-sent events
|
|
13
|
+
and WebSocket itself, so the endpoint no longer depends on Yoga, on the Envelop
|
|
14
|
+
core or on `graphql-ws`. Plugins, errors and the context's shape are graxia's.
|
|
15
|
+
|
|
16
|
+
## graphql 17 first
|
|
17
|
+
|
|
18
|
+
graphql 16 is no longer supported: move to `graphql@^17.1.0` (and any tool that
|
|
19
|
+
pins 16: codegen, a validation-rule package) before anything else.
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
bun add graphql@^17.1.0
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Peers
|
|
26
|
+
|
|
27
|
+
| Before | After |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| `graphql-yoga` | `@graxia/core` `^0.10.0` (0.10 sets the HTTP status from errors again) |
|
|
30
|
+
| `graphql-ws` (for `ws`) | nothing: graxia speaks `graphql-transport-ws` |
|
|
31
|
+
| bundled GraphiQL of Yoga | `@graxia/graphiql` `^0.2.4` (required) |
|
|
32
|
+
| Envelop plugins | not a peer: install `@graxia/envelop` yourself to use Envelop plugins |
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
bun remove graphql-yoga graphql-ws
|
|
36
|
+
bun add @graxia/core @graxia/graphiql graphql
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Schema and context
|
|
40
|
+
|
|
41
|
+
`createSchema` comes from `@graxia/core` and is **curried**: the type argument
|
|
42
|
+
goes on the first call, the schema on the second.
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
// file: src/schema.ts
|
|
46
|
+
import { alxia } from '@alxia/core';
|
|
47
|
+
import type { GraphQLContext } from '@alxia/graphql';
|
|
48
|
+
import { createSchema } from '@graxia/core';
|
|
49
|
+
|
|
50
|
+
const base = alxia().decorate({ greeting: 'hello' });
|
|
51
|
+
|
|
52
|
+
// Before: createSchema<GraphQLContext<typeof base>>({ typeDefs, resolvers })
|
|
53
|
+
export const schema = createSchema<GraphQLContext<typeof base>>()({
|
|
54
|
+
typeDefs: /* GraphQL */ `type Query { hello: String! }`,
|
|
55
|
+
resolvers: { Query: { hello: (_, __, { greeting }) => greeting } },
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`resolvers` takes one map or an array of maps, as Yoga's `resolvers: [a, b]`
|
|
60
|
+
did: graxia merges them per type and field, and each map stays checked, so no
|
|
61
|
+
cast is needed. A field defined twice **throws** a `GraxiaConfigError` naming
|
|
62
|
+
`Type.field` at schema build: the order of the maps never decides a conflict
|
|
63
|
+
(Yoga's tools let the last one win). `freshPerMutation` takes the same array
|
|
64
|
+
and returns an array, each map wrapped on its own.
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
// file: src/schema-maps.ts
|
|
68
|
+
import { createSchema } from '@graxia/core';
|
|
69
|
+
|
|
70
|
+
export const schema = createSchema()({
|
|
71
|
+
typeDefs: /* GraphQL */ `type Query { a: String b: String }`,
|
|
72
|
+
resolvers: [{ Query: { a: () => 'A' } }, { Query: { b: () => 'B' } }],
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
What a resolver reads changes:
|
|
77
|
+
|
|
78
|
+
- `GraphQLContext` is graxia's `CoreContext` (`signal`, the request's abort
|
|
79
|
+
signal), the app's context, the WebSocket's `connectionParams`, and the
|
|
80
|
+
`context` option's values. Yoga's `request`, `params` and the headers it
|
|
81
|
+
spread into the context are gone: read what the app needs from a middleware
|
|
82
|
+
and the app's context.
|
|
83
|
+
- The `context` option now receives graxia's `{ request, serverContext, signal }`,
|
|
84
|
+
and the app's own values live in `serverContext`. Annotate it, since an
|
|
85
|
+
unannotated argument does not infer:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
// file: src/schema-context.ts
|
|
89
|
+
import { alxia } from '@alxia/core';
|
|
90
|
+
import type { ServerContext } from '@alxia/graphql';
|
|
91
|
+
import { graphql } from '@alxia/graphql';
|
|
92
|
+
import { createSchema } from '@graxia/core';
|
|
93
|
+
|
|
94
|
+
const base = alxia().decorate({ name: 'ada' });
|
|
95
|
+
const schema = createSchema()({
|
|
96
|
+
typeDefs: /* GraphQL */ `type Query { hello: String! }`,
|
|
97
|
+
resolvers: { Query: { hello: () => 'world' } },
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
export const app = base.plugin((app) =>
|
|
101
|
+
graphql(app, {
|
|
102
|
+
schema,
|
|
103
|
+
// Before: context: ({ name }) => ({ shout: name.toUpperCase() })
|
|
104
|
+
context: ({ serverContext }: { serverContext: ServerContext<(typeof base)['~context']> }) => ({
|
|
105
|
+
shout: serverContext.name.toUpperCase(),
|
|
106
|
+
}),
|
|
107
|
+
}),
|
|
108
|
+
);
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
See [The typed context](guide/context.md).
|
|
112
|
+
|
|
113
|
+
## Plugins
|
|
114
|
+
|
|
115
|
+
Yoga plugins no longer run. Write a graxia plugin with `definePlugin`
|
|
116
|
+
(`onContext`, `onParse`, `onValidate` with `addRule`, `onExecute`,
|
|
117
|
+
`onResultChunk`…), and wrap an Envelop plugin with `fromEnvelop`:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
// file: src/plugins.ts
|
|
121
|
+
import { fromEnvelop } from '@graxia/envelop';
|
|
122
|
+
import { useDepthLimit } from '@envelop/depth-limit';
|
|
123
|
+
|
|
124
|
+
// Before: plugins: [useDepthLimit({ maxDepth: 8 })]
|
|
125
|
+
export const plugins = [fromEnvelop([useDepthLimit({ maxDepth: 8 })])];
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Janus.** `useJanus()` was a Yoga plugin. Use `@softistx/janus-graphql`
|
|
129
|
+
`>=0.36.0` and its `/graxia` entry, `janusGraxia(options)`, in `plugins`.
|
|
130
|
+
`fromEnvelop` refuses the old plugin at boot, since it relies on Yoga's
|
|
131
|
+
`onResponse` hook; wrapping it is not a way around.
|
|
132
|
+
|
|
133
|
+
<!-- Temporary, until nxgt-janus#1003 is released -->
|
|
134
|
+
`@softistx/janus-graphql` 0.36.0 still declares `@graxia/core ^0.9.0`; expect a
|
|
135
|
+
peer warning until its next release.
|
|
136
|
+
|
|
137
|
+
```diff
|
|
138
|
+
-import { useJanus } from '@softistx/janus-graphql';
|
|
139
|
+
+import { janusGraxia } from '@softistx/janus-graphql/graxia';
|
|
140
|
+
-plugins: [useJanus(options)],
|
|
141
|
+
+plugins: [janusGraxia(options)],
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Many Yoga plugins have a graxia option now: depth, aliases and cost limits
|
|
145
|
+
(`limits`), persisted operations (`trustedDocuments`), response masking
|
|
146
|
+
(`maskErrors`), CORS stays in `@alxia/cors`. See
|
|
147
|
+
[Plugins and options](guide/plugins.md).
|
|
148
|
+
|
|
149
|
+
## Traps in graxia plugins
|
|
150
|
+
|
|
151
|
+
- **Refuse with `respond`, never `throw`.** In `onRequest` and `onParams`,
|
|
152
|
+
`respond(new Response(null, { status: 401 }))` answers; a `throw` is an
|
|
153
|
+
unexpected failure and answers 500. `onResponse` has no `respond`: it
|
|
154
|
+
replaces the response with `setResponse`.
|
|
155
|
+
- **Per-operation checks go in `onParams`.** `onRequest` runs for every
|
|
156
|
+
request that reaches the endpoint, the GraphiQL page's `GET` included, so a
|
|
157
|
+
check there blocks the IDE too.
|
|
158
|
+
- **An after-hook's `result` can be `undefined`.** The function an `onExecute`
|
|
159
|
+
hook returns receives `{ result, setResult }` with `result` typed
|
|
160
|
+
`ExecutionOutput | undefined`: test it before reading it.
|
|
161
|
+
- **`exactOptionalPropertyTypes` and `ResponseInit`.** `headers: undefined` is
|
|
162
|
+
refused, so build the init conditionally:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
// file: src/refuse.ts
|
|
166
|
+
export const refuse = (headers?: Headers): Response =>
|
|
167
|
+
new Response(null, { status: 401, ...(headers ? { headers } : {}) });
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Options
|
|
171
|
+
|
|
172
|
+
| Option | Now |
|
|
173
|
+
| --- | --- |
|
|
174
|
+
| `maxTokens`, `maxNesting` | `limits: { tokens, nesting }`; the old names still work, marked `@deprecated`, and are removed in the next minor. A bad value is no longer rejected at declaration. |
|
|
175
|
+
| `parseCache` | `caches: { parse: { maxBytes, max, ttlMs } }` or `caches: false`; the old name still maps (`maxBytes`, `max`, `ttl`). |
|
|
176
|
+
| `maskedErrors` | `maskErrors` (the old name still maps, deprecated). Masking is on by default. |
|
|
177
|
+
| `bodyLimit` | still `bodyLimit`, graxia's `limits.bodyBytes`; `0` or a fraction is a `GraxiaConfigError`, also when it comes from an earlier `bodyLimit()` of the app. |
|
|
178
|
+
| `batching` | `batching: true` is 10 operations, or `{ limit }`. |
|
|
179
|
+
| `graphqlEndpoint` | `path`, as before. |
|
|
180
|
+
| `logging`, `requestId`, `cors` | removed, they throw a `TypeError` naming the fix: `onUnexpected` and `@alxia/logger`, graxia's own `x-request-id`, `@alxia/cors`. |
|
|
181
|
+
| `sameOrigin()`, `renderSandbox` | removed with no shim: `csrf: { sameOrigin: true }` and `ide: 'apollo-sandbox'`. |
|
|
182
|
+
| `fieldRateLimit`, `limitFromStore` | unchanged names, now graxia plugins. |
|
|
183
|
+
|
|
184
|
+
## CSRF and client headers
|
|
185
|
+
|
|
186
|
+
graxia's CSRF check is **on by default**. A `GET`, or a `POST` that is not
|
|
187
|
+
`application/json`, is answered `403 CSRF_HEADER_REQUIRED` unless it carries one
|
|
188
|
+
of `x-graphql-csrf`, `graphql-require-preflight`, `apollo-require-preflight` or
|
|
189
|
+
`x-apollo-operation-name`. A JSON `POST` passes. Apollo Client and urql send
|
|
190
|
+
`x-apollo-operation-name` or can be given a header; a hand-written `GET` client
|
|
191
|
+
needs `x-graphql-csrf: 1`. `csrf: { sameOrigin: true }` adds a check of the
|
|
192
|
+
`Origin`; `csrf: false` turns it all off.
|
|
193
|
+
|
|
194
|
+
## WebSocket
|
|
195
|
+
|
|
196
|
+
`ws: true` (or `{ path?, keepAlive? }`) is unchanged, and graxia serves
|
|
197
|
+
`graphql-transport-ws` itself: remove `graphql-ws` from the server's
|
|
198
|
+
dependencies (clients keep theirs). Subscriptions are also served over
|
|
199
|
+
server-sent events by default, with a keep-alive every 12 seconds. A client
|
|
200
|
+
that offers no subprotocol now gets an HTTP 400 at the upgrade. See
|
|
201
|
+
[GraphQL over WebSocket](guide/websockets.md). Two more differences:
|
|
202
|
+
|
|
203
|
+
- `ws: { keepAlive: 0 }` now throws a `TypeError`: write `keepAlive: false` for
|
|
204
|
+
no pings ([troubleshooting](troubleshooting.md#typeerror-graphqlapp--ws--keepalive-0---keepalive-is-the-milliseconds-between-pings-a-positive-number-up-to-2147483647-or-false-for-none)).
|
|
205
|
+
- A binary frame is refused: the socket closes with `4400`, so send text
|
|
206
|
+
frames ([troubleshooting](troubleshooting.md#a-websocket-closes-with-4400-after-the-first-message)).
|
|
207
|
+
|
|
208
|
+
## IDE
|
|
209
|
+
|
|
210
|
+
GraphiQL comes from `@graxia/graphiql`, a required peer; `ide`, `graphiql` and
|
|
211
|
+
`sandbox` keep their names, and `ide: 'apollo-sandbox'` replaces
|
|
212
|
+
`renderSandbox`. See [GraphiQL and Apollo Sandbox](guide/ide.md).
|
|
213
|
+
|
|
214
|
+
## Errors and refusal codes
|
|
215
|
+
|
|
216
|
+
- Errors are always masked. Throw `exposedError(code, message)` from
|
|
217
|
+
`@graxia/core` (or a `GraphQLError`) for what a client may read.
|
|
218
|
+
- `extensions.http.status` and `extensions.http.headers` on an error set the
|
|
219
|
+
HTTP response again, as under Yoga (`@graxia/core` 0.10, graxia#147), for a
|
|
220
|
+
single operation answered as plain JSON; a subscription that fails before
|
|
221
|
+
its first event is not covered yet (graxia#150)
|
|
222
|
+
<!-- Temporary, until graxia#150 -->. `errorHttp: false` turns it off:
|
|
223
|
+
the media type decides and `extensions` are untouched. The app's layers still
|
|
224
|
+
answer an auth error before.
|
|
225
|
+
- Server code reading `error.extensions['http']` needs index access once
|
|
226
|
+
Yoga's `http` augmentation is gone (with `noPropertyAccessFromIndexSignature`).
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
// file: src/error-http.ts
|
|
230
|
+
import { type ErrorHttp, exposedError } from '@graxia/core';
|
|
231
|
+
|
|
232
|
+
export const taken = () =>
|
|
233
|
+
exposedError('CONFLICT', 'Email taken.', {
|
|
234
|
+
extensions: { http: { status: 409 } satisfies ErrorHttp },
|
|
235
|
+
}); // HTTP 409; http is stripped from the response
|
|
236
|
+
```
|
|
237
|
+
- A refusal has a code: `BODY_TOO_LARGE` (413), `UNSUPPORTED_MEDIA_TYPE` (415),
|
|
238
|
+
`QUERY_REQUIRED` (400), `METHOD_NOT_ALLOWED` (405, a mutation over `GET`),
|
|
239
|
+
`NOT_ACCEPTABLE` (406), `CSRF_HEADER_REQUIRED` (403). Yoga's `BAD_REQUEST`
|
|
240
|
+
and its messages are gone: match the code, never the message. The type is
|
|
241
|
+
`GraxiaErrorCode`.
|
|
242
|
+
|
|
243
|
+
See [Troubleshooting](troubleshooting.md).
|
|
244
|
+
|
|
245
|
+
## Executor and the test client
|
|
246
|
+
|
|
247
|
+
`graphqlExecutor(options)` and `graphqlClient(app)` keep their signatures. The
|
|
248
|
+
executor runs the same graxia as the route, with the CSRF check off (there is
|
|
249
|
+
no browser request to forge); a subscription is still answered
|
|
250
|
+
`SUBSCRIPTION_NOT_SUPPORTED` ([troubleshooting](troubleshooting.md#subscriptions-are-not-supported-over-this-transport-subscriptionssse-is-false)). A call whose `signal` is aborted does not reject:
|
|
251
|
+
it resolves to `{ errors: [{ message: 'The operation was aborted.', extensions: { code: 'OPERATION_ABORTED' } }] }`
|
|
252
|
+
with no `data` ([troubleshooting](troubleshooting.md#the-operation-was-aborted-from-graphqlexecutor)). See [Running operations in process](guide/executor.md)
|
|
253
|
+
and [Testing the endpoint](guide/testing.md). The executor holds a graxia instance: `await executor.dispose()` when done.
|
|
254
|
+
|
|
255
|
+
## What stays the same
|
|
256
|
+
|
|
257
|
+
`graphql(app, options)` and its place in the chain, `path` under the app's
|
|
258
|
+
prefix, `GraphQLContext<typeof app>`, `oncePerRequest`, `freshPerMutation`,
|
|
259
|
+
`boundedStream`, `fieldRateLimit`, `health()` probes and the graceful shutdown,
|
|
260
|
+
`bodyLimit` and its 1 MiB default, and the telemetry through
|
|
261
|
+
`@alxia/telemetry`.
|
|
262
|
+
|
|
263
|
+
## Checklist
|
|
264
|
+
|
|
265
|
+
1. Move to `graphql@^17.1.0`.
|
|
266
|
+
2. Swap the peers: remove `graphql-yoga` and `graphql-ws`, add `@graxia/core`,
|
|
267
|
+
`@graxia/graphiql`; add `@graxia/envelop` only to use Envelop plugins.
|
|
268
|
+
3. Import `createSchema` from `@graxia/core` and curry it: `createSchema<Ctx>()({ … })`;
|
|
269
|
+
pass several resolver maps as an array, not a cast.
|
|
270
|
+
4. Annotate the `context` option's argument with `ServerContext`, and read the
|
|
271
|
+
app's values from `serverContext`.
|
|
272
|
+
5. Rewrite each Yoga plugin (`definePlugin`) or wrap it (`fromEnvelop`).
|
|
273
|
+
6. Rename `maxTokens`, `maxNesting`, `parseCache` and `maskedErrors` to
|
|
274
|
+
`limits`, `caches` and `maskErrors`.
|
|
275
|
+
7. Replace `sameOrigin()`, `renderSandbox`, `logging`, `requestId` and `cors`.
|
|
276
|
+
8. Send a CSRF header from every client that uses `GET` or a non-JSON `POST`.
|
|
277
|
+
9. Match refusals by their code, not by Yoga's messages.
|
|
278
|
+
10. Write `ws: { keepAlive: false }` instead of `keepAlive: 0`, send text frames
|
|
279
|
+
over WebSocket, and read `OPERATION_ABORTED` from an aborted executor call.
|
|
280
|
+
11. Call `await executor.dispose()` when a `graphqlExecutor` is done (a spec's
|
|
281
|
+
`afterAll`, a job's shutdown).
|
|
282
|
+
12. Run the app's specs, then `graphqlClient` against a few refusals (an
|
|
283
|
+
oversized body, a mutation over `GET`, a missing header).
|
package/docs/roadmap.md
CHANGED
|
@@ -11,13 +11,8 @@ Nothing in progress.
|
|
|
11
11
|
|
|
12
12
|
## Next
|
|
13
13
|
|
|
14
|
-
Nothing scheduled yet.
|
|
15
|
-
|
|
16
14
|
## Later
|
|
17
15
|
|
|
18
|
-
- **Weighing validation results.** Yoga keeps the validation errors of a
|
|
19
|
-
cached document (up to about 100) outside the parse cache's weight, at
|
|
20
|
-
roughly 70 KB per document; the weight could count them.
|
|
21
16
|
- **A configurable WebSocket message limit.** A `subscribe` message over the
|
|
22
17
|
socket is bounded by Bun's `maxPayloadLength` (16 MiB by default), not by
|
|
23
18
|
`bodyLimit`. A `ws` option would set the limit the way `bodyLimit` does
|
|
@@ -27,11 +22,13 @@ Nothing scheduled yet.
|
|
|
27
22
|
|
|
28
23
|
### Unreleased
|
|
29
24
|
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
- **
|
|
34
|
-
- **`
|
|
25
|
+
- **graxia 0.10.** `@graxia/core` `^0.10.0` (and `@graxia/graphiql` `^0.2.4`) is the peer floor: an error's `extensions.http.status` and headers set the HTTP response again, as under Yoga, and `errorHttp: false` turns it off. `freshPerMutation` takes the array of resolver maps `createSchema` accepts and returns it as an array. A field defined twice across maps throws (graxia's rule, not last wins). The migration guide covers `janusGraxia` and `extensions['http']`.
|
|
26
|
+
- **Runs on graxia.** `@alxia/graphql` serves the endpoint with `@graxia/core` (0.10) instead of graphql-yoga: graxia's plugins (and Envelop's through `@graxia/envelop`), limits, caches, refusal codes, CSRF check, server-sent events and WebSocket, and `@graxia/graphiql` for the IDE. A breaking release: see [Migrating to graxia](migrating-to-graxia.md).
|
|
27
|
+
- **Two temporary workarounds dropped.** graxia 0.8.0 ships `telemetry.operationSpans: false` (graxia#137) and hands a plugin the `serverContext` at validation (graxia#135), so `graphql()` sets `telemetry: { operationSpans: false }` and a validation failure over a socket reaches its observers natively; a throwing subscription source is seen by `onResultChunk` too (graxia#136).
|
|
28
|
+
- **Body limit and refusal codes from graxia.** `bodyLimit` is graxia's `limits.bodyBytes`: a body past it is a `413` with `extensions.code: 'BODY_TOO_LARGE'`, a form or `application/graphql` body a `415 UNSUPPORTED_MEDIA_TYPE`, and every refusal graxia builds has a stable code (`GraxiaErrorCode` is re-exported as a type); `@graxia/core` `^0.9.0` was the peer floor (now `^0.10.0`) ([guide](guide/production.md#cap-what-a-request-costs)).
|
|
29
|
+
- **`sameOrigin()` removed.** The Yoga-era plugin is gone with no shim: a cookie-authenticated endpoint uses graxia's `csrf: { sameOrigin: true }` (a foreign `Origin` is refused), beside the CSRF header check that is on by default ([guide](guide/production.md#csrf-for-a-cookie-authenticated-api)).
|
|
30
|
+
- **`fieldRateLimit`.** A graxia plugin that counts every selection of chosen fields (aliases and fragments expanded) and consumes that cost on a limit keyed by the client, answering a 429 `RATE_LIMITED` (or the `code` you pass) with `retryAfter`, the client grouped by its IPv6 network under `ipv6Prefix`; `limitFromStore` adapts an `@alxia/rate-limit` store, `single` refuses a field written twice ([guide](guide/production.md#count-a-field-not-a-request)).
|
|
31
|
+
- **`graphqlExecutor(options)`.** A query or a mutation run in process through the same graxia setup as `graphql()` (plugins, token and nesting limits, parse cache, error masking), with a server context the caller gives, for an MCP tool or a job ([guide](guide/executor.md)).
|
|
35
32
|
|
|
36
33
|
### 0.9.2
|
|
37
34
|
|
|
@@ -121,6 +118,5 @@ Nothing scheduled yet.
|
|
|
121
118
|
default, or Apollo Sandbox pointed at the address it was opened at —
|
|
122
119
|
`https` behind a proxy that terminates TLS — each with
|
|
123
120
|
a `Content-Security-Policy` that lets it load; `ide: false` turns it off.
|
|
124
|
-
`renderSandbox` and `SANDBOX_POLICY` serve the Sandbox page anywhere else.
|
|
125
121
|
- **CORS left to the app.** Yoga's own CORS is off, so `@alxia/cors`
|
|
126
122
|
answers for the whole app, the endpoint included.
|