@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
@@ -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 'graphql-yoga';
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 Yoga: its plugins are
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 'graphql-yoga';
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 closed with
109
- `4406 Subprotocol not acceptable` ([Troubleshooting](../troubleshooting.md#4406-subprotocol-not-acceptable)).
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 Yoga's envelop, as over HTTP: its plugins
114
- apply — Envelop's and Yoga's, masked errors, depth limits — and its
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 Yoga an
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 'graphql-yoga';
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`, and they subscribe
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
- - [Yoga's plugins and options](yoga.md#subscriptions): subscriptions over
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
- - **`sameOrigin`.** A Yoga plugin for a cookie-authenticated endpoint: a foreign `Origin` (`null` included) and a non-JSON `POST` are answered 403 `FORBIDDEN` before anything is parsed; `allow`, `json` and `refuse` tune it ([guide](guide/production.md#csrf-for-a-cookie-authenticated-api)).
31
- - **`fieldRateLimit`.** A Yoga 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)).
32
- - **`graphqlExecutor(options)`.** A query or a mutation run in process through the same Yoga 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)).
33
- - **A client's `x-request-id` is never believed on Yoga 6.** The endpoint turns Yoga's request id off (`requestId: false`), so the header is neither echoed nor logged; an app that turns it on keeps `trustHeader: false`. Yoga 6's per-request "Request processed" INFO line is off by default too: `logging` defaults to `'warn'` ([troubleshooting](troubleshooting.md#x-request-id-echoed-or-request-processed-logged-on-yoga-6)).
34
- - **`graphql-yoga` 6 accepted as a peer.** The range is `^5.16.0 || ^6.0.0`; CI runs the specs on both majors. A custom `logging` on Yoga 6 must be a `@graphql-hive/logger` `Logger` ([troubleshooting](troubleshooting.md#logchild-is-not-a-function)).
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.