grafserv 0.0.1-0.2 → 0.0.1-0.21

package/CHANGELOG.md

@@ -1,5 +1,225 @@
 # grafserv
 
+## 0.0.1-0.21
+
+### Patch Changes
+
+- Updated dependencies
+  [[`397e8bb40`](https://github.com/benjie/postgraphile-private/commit/397e8bb40fe3783995172356a39ab7cb33e3bd36)]:
+  - grafast@0.0.1-0.19
+
+## 0.0.1-0.20
+
+### Patch Changes
+
+- Updated dependencies
+  [[`4c2b7d1ca`](https://github.com/benjie/postgraphile-private/commit/4c2b7d1ca1afbda1e47da22c346cc3b03d01b7f0),
+  [`c8a56cdc8`](https://github.com/benjie/postgraphile-private/commit/c8a56cdc83390e5735beb9b90f004e7975cab28c)]:
+  - grafast@0.0.1-0.18
+
+## 0.0.1-0.19
+
+### Patch Changes
+
+- Updated dependencies [[`f48860d4f`](undefined)]:
+  - grafast@0.0.1-0.17
+
+## 0.0.1-0.18
+
+### Patch Changes
+
+- Updated dependencies
+  [[`df89aba52`](https://github.com/benjie/postgraphile-private/commit/df89aba524270e52f82987fcc4ab5d78ce180fc5)]:
+  - grafast@0.0.1-0.16
+
+## 0.0.1-0.17
+
+### Patch Changes
+
+- [#210](https://github.com/benjie/postgraphile-private/pull/210)
+  [`b523118fe`](https://github.com/benjie/postgraphile-private/commit/b523118fe6217c027363fea91252a3a1764e17df)
+  Thanks [@benjie](https://github.com/benjie)! - Replace BaseGraphQLContext with
+  Grafast.Context throughout.
+
+- [#210](https://github.com/benjie/postgraphile-private/pull/210)
+  [`461c03b72`](https://github.com/benjie/postgraphile-private/commit/461c03b72477821ec26cbf703011542e453d083c)
+  Thanks [@benjie](https://github.com/benjie)! - Make servers releasable where
+  possible.
+
+- Updated dependencies
+  [[`b523118fe`](https://github.com/benjie/postgraphile-private/commit/b523118fe6217c027363fea91252a3a1764e17df)]:
+  - grafast@0.0.1-0.15
+
+## 0.0.1-0.16
+
+### Patch Changes
+
+- [#207](https://github.com/benjie/postgraphile-private/pull/207)
+  [`c850dd4ec`](https://github.com/benjie/postgraphile-private/commit/c850dd4ec0e42e37122f5bca55a079b53bfd895e)
+  Thanks [@benjie](https://github.com/benjie)! - Rename 'preset.server' to
+  'preset.grafserv'.
+
+- [#207](https://github.com/benjie/postgraphile-private/pull/207)
+  [`afa0ea5f6`](https://github.com/benjie/postgraphile-private/commit/afa0ea5f6c508d9a0ba5946ab153b13ddbd274a0)
+  Thanks [@benjie](https://github.com/benjie)! - Fix bug in subscriptions where
+  termination of underlying stream wouldn't terminate the subscription.
+
+- [#206](https://github.com/benjie/postgraphile-private/pull/206)
+  [`851b78ef2`](https://github.com/benjie/postgraphile-private/commit/851b78ef20d430164507ec9b3f41a5a0b8a18ed7)
+  Thanks [@benjie](https://github.com/benjie)! - Grafserv now masks untrusted
+  errors by default; trusted errors are constructed via GraphQL's GraphQLError
+  or Grafast's SafeError.
+- Updated dependencies
+  [[`d76043453`](https://github.com/benjie/postgraphile-private/commit/d7604345362c58bf7eb43ef1ac1795a2ac22ae79),
+  [`afa0ea5f6`](https://github.com/benjie/postgraphile-private/commit/afa0ea5f6c508d9a0ba5946ab153b13ddbd274a0),
+  [`851b78ef2`](https://github.com/benjie/postgraphile-private/commit/851b78ef20d430164507ec9b3f41a5a0b8a18ed7),
+  [`384b3594f`](https://github.com/benjie/postgraphile-private/commit/384b3594f543d113650c1b6b02b276360dd2d15f)]:
+  - grafast@0.0.1-0.14
+
+## 0.0.1-0.15
+
+### Patch Changes
+
+- Updated dependencies [[`e5b664b6f`](undefined)]:
+  - grafast@0.0.1-0.13
+
+## 0.0.1-0.14
+
+### Patch Changes
+
+- [#200](https://github.com/benjie/postgraphile-private/pull/200)
+  [`1e5671cdb`](https://github.com/benjie/postgraphile-private/commit/1e5671cdbbf9f4600b74c43eaa7e33b7bfd75fb9)
+  Thanks [@benjie](https://github.com/benjie)! - Add support for websocket
+  GraphQL subscriptions (via graphql-ws) to grafserv and PostGraphile (currently
+  supporting Node, Express, Koa and Fastify)
+
+- [#200](https://github.com/benjie/postgraphile-private/pull/200)
+  [`5b634a78e`](https://github.com/benjie/postgraphile-private/commit/5b634a78e51816071447aceb1edfb813d77d563b)
+  Thanks [@benjie](https://github.com/benjie)! - Standardize on `serv.addTo`
+  interface, even for Node
+
+- Updated dependencies
+  [[`4f5d5bec7`](https://github.com/benjie/postgraphile-private/commit/4f5d5bec72f949b17b39cd07acc848ce7a8bfa36),
+  [`e11698473`](https://github.com/benjie/postgraphile-private/commit/e1169847303790570bfafa07eb25d8fce53a0391),
+  [`25f5a6cbf`](https://github.com/benjie/postgraphile-private/commit/25f5a6cbff6cd5a94ebc4f411f7fa89c209fc383)]:
+  - grafast@0.0.1-0.12
+  - ruru@2.0.0-0.10
+
+## 0.0.1-0.13
+
+### Patch Changes
+
+- [`0ab95d0b1`](undefined) - Update sponsors.
+
+- [#195](https://github.com/benjie/postgraphile-private/pull/195)
+  [`752ec9c51`](https://github.com/benjie/postgraphile-private/commit/752ec9c516add7c4617b426e97eccd1d4e5b7833)
+  Thanks [@benjie](https://github.com/benjie)! - Fix handling of HTTP errors and
+  allow for 204 status code responses. Add CORS hack to enable graphql-http
+  auditing.
+- Updated dependencies [[`0ab95d0b1`](undefined),
+  [`4783bdd7c`](https://github.com/benjie/postgraphile-private/commit/4783bdd7cc28ac8b497fdd4d6f1024d80cb432ef),
+  [`652cf1073`](https://github.com/benjie/postgraphile-private/commit/652cf107316ea5832f69c6a55574632187f5c876)]:
+  - grafast@0.0.1-0.11
+  - graphile-config@0.0.1-0.5
+  - ruru@2.0.0-0.9
+
+## 0.0.1-0.12
+
+### Patch Changes
+
+- Updated dependencies
+  [[`842f6ccbb`](https://github.com/benjie/postgraphile-private/commit/842f6ccbb3c9bd0c101c4f4df31c5ed1aea9b2ab)]:
+  - graphile-config@0.0.1-0.4
+  - grafast@0.0.1-0.10
+  - ruru@2.0.0-0.8
+
+## 0.0.1-0.11
+
+### Patch Changes
+
+- [#176](https://github.com/benjie/postgraphile-private/pull/176)
+  [`11d6be65e`](https://github.com/benjie/postgraphile-private/commit/11d6be65e0da489f8ab3e3a8b8db145f8b2147ad)
+  Thanks [@benjie](https://github.com/benjie)! - Fix issue with plugin
+  versioning. Add more TSDoc comments. New getTerminalWidth() helper.
+- Updated dependencies
+  [[`19e2961de`](https://github.com/benjie/postgraphile-private/commit/19e2961de67dc0b9601799bba256e4c4a23cc0cb),
+  [`11d6be65e`](https://github.com/benjie/postgraphile-private/commit/11d6be65e0da489f8ab3e3a8b8db145f8b2147ad)]:
+  - graphile-config@0.0.1-0.3
+  - grafast@0.0.1-0.9
+  - ruru@2.0.0-0.7
+
+## 0.0.1-0.10
+
+### Patch Changes
+
+- Updated dependencies
+  [[`208166269`](https://github.com/benjie/postgraphile-private/commit/208166269177d6e278b056e1c77d26a2d8f59f49)]:
+  - grafast@0.0.1-0.8
+
+## 0.0.1-0.9
+
+### Patch Changes
+
+- Updated dependencies [[`a40fa6966`](undefined),
+  [`8f04af08d`](https://github.com/benjie/postgraphile-private/commit/8f04af08da68baf7b2b4d508eac0d2a57064da7b)]:
+  - ruru@2.0.0-0.6
+  - grafast@0.0.1-0.7
+
+## 0.0.1-0.8
+
+### Patch Changes
+
+- [`c4213e91d`](undefined) - Add pgl.getResolvedPreset() API; fix Ruru
+  respecting graphqlPath setting; replace 'instance' with 'pgl'/'serv' as
+  appropriate; forbid subscriptions on GET
+
+## 0.0.1-0.7
+
+### Patch Changes
+
+- [`9b296ba54`](undefined) - More secure, more compatible, and lots of fixes
+  across the monorepo
+
+- Updated dependencies [[`9b296ba54`](undefined)]:
+  - grafast@0.0.1-0.6
+  - ruru@2.0.0-0.5
+  - graphile-config@0.0.1-0.2
+
+## 0.0.1-0.6
+
+### Patch Changes
+
+- Updated dependencies [[`cd37fd02a`](undefined)]:
+  - grafast@0.0.1-0.5
+
+## 0.0.1-0.5
+
+### Patch Changes
+
+- [`768f32681`](undefined) - Fix peerDependencies ranges
+
+- Updated dependencies [[`768f32681`](undefined)]:
+  - grafast@0.0.1-0.4
+  - ruru@2.0.0-0.4
+
+## 0.0.1-0.4
+
+### Patch Changes
+
+- Updated dependencies [[`0983df3f6`](undefined)]:
+  - ruru@2.0.0-0.3
+
+## 0.0.1-0.3
+
+### Patch Changes
+
+- [`d11c1911c`](undefined) - Fix dependencies
+
+- Updated dependencies [[`d11c1911c`](undefined)]:
+  - grafast@0.0.1-0.3
+  - ruru@2.0.0-0.2
+  - graphile-config@0.0.1-0.1
+
 ## 0.0.1-0.2
 
 ### Patch Changes

package/README.md

@@ -26,17 +26,262 @@ And please give some love to our featured sponsors 🤩:
 <table><tr>
 <td align="center"><a href="https://surge.io/"><img src="https://graphile.org/images/sponsors/surge.png" width="90" height="90" alt="Surge" /><br />Surge</a> *</td>
 <td align="center"><a href="https://www.netflix.com/"><img src="https://graphile.org/images/sponsors/Netflix.png" width="90" height="90" alt="Netflix" /><br />Netflix</a> *</td>
-<td align="center"><a href="https://qwick.com/"><img src="https://graphile.org/images/sponsors/qwick.png" width="90" height="90" alt="Qwick" /><br />Qwick</a> *</td>
 <td align="center"><a href="https://www.the-guild.dev/"><img src="https://graphile.org/images/sponsors/theguild.png" width="90" height="90" alt="The Guild" /><br />The Guild</a> *</td>
+<td align="center"><a href="https://qwick.com/"><img src="https://graphile.org/images/sponsors/qwick.png" width="90" height="90" alt="Qwick" /><br />Qwick</a> *</td>
 </tr><tr>
 <td align="center"><a href="http://chads.website"><img src="https://graphile.org/images/sponsors/chadf.png" width="90" height="90" alt="Chad Furman" /><br />Chad Furman</a> *</td>
-<td align="center"><a href="https://www.fanatics.com/"><img src="https://graphile.org/images/sponsors/fanatics.png" width="90" height="90" alt="Fanatics" /><br />Fanatics</a> *</td>
 <td align="center"><a href="https://dovetailapp.com/"><img src="https://graphile.org/images/sponsors/dovetail.png" width="90" height="90" alt="Dovetail" /><br />Dovetail</a> *</td>
 <td align="center"><a href="https://www.enzuzo.com/"><img src="https://graphile.org/images/sponsors/enzuzo.png" width="90" height="90" alt="Enzuzo" /><br />Enzuzo</a> *</td>
-</tr><tr>
 <td align="center"><a href="https://stellate.co/"><img src="https://graphile.org/images/sponsors/Stellate.png" width="90" height="90" alt="Stellate" /><br />Stellate</a> *</td>
 </tr></table>
 
 <em>\* Sponsors the entire Graphile suite</em>
 
 <!-- SPONSORS_END -->
+
+## Usage
+
+Grafserv supports many different servers, and because each server is different
+each has their own entrypoint, e.g. `grafserv/node` for the Node.js HTTP server
+or `grafserv/express/v4` for Express v4. Generally you import the `grafserv`
+function from the relevant entrypoint for your server of choice and then create
+an instance:
+
+```js
+const serv = grafserv({ schema, preset });
+```
+
+`grafserv` is passed the GraphQL schema to use (if it's available, otherwise
+passing either null or a promise is also acceptable) and a `graphql-config`
+preset - i.e. your configuration.
+
+Calling `grafserv` will return an instance; this instance will have a number of
+helpers on it, including helpers specific to integrating it with your framework
+of choice. For servers that operate on a middleware basis this is typically
+`serv.addTo(app)` (which allows registering multiple route handlers), though
+different servers may have different APIs, such as `serv.createGraphQLHandler()`
+for Lambda and Next.js.
+
+Note: There is little value in Grafserv reimplementing every non-GraphQL concern
+your server may have, so instead it leans on the ecosystem of your chosen server
+to handle things like compression, rate limits, sessions, cookies, etc. For
+example, to compress your responses you'd need to use a module like
+[`compression`](https://expressjs.com/en/resources/middleware/compression.html)
+for Express, [`koa-compress`](https://www.npmjs.com/package/koa-compress) for
+Koa, or [`@fastify/compress`](https://www.npmjs.com/package/@fastify/compress)
+for Fastify.
+
+### serv.release()
+
+Releases any resources created by the instance; no further requests should be
+handled (though currently active requests will be allowed to complete).
+
+// TODO: consider terminating subscriptions or other long-lived things.
+
+### serv.onRelease(cb)
+
+Adds `cb` to the list of callbacks to be called when the server is released;
+useful for releasing resources you created only for the server. Callbacks will
+be called in reverse order that they were added.
+
+### serv.setSchema(newSchema)
+
+Replaces the schema to use for future requests (currently active requests are
+unaffected) - this is primarily used for "watch" mode.
+
+### serv.setPreset(newPreset)
+
+Replaces the config to use for future requests (currently active requests are
+unaffected) - this is primarily used for "watch" mode. Note that certain
+configuration changes might not be reflected by certain servers until a restart.
+
+### serv.getSchema()
+
+Returns either the GraphQL schema that is currently in use, or a promise to the
+same.
+
+### serv.getPreset()
+
+Returns the resolved `graphile-config` preset that is currently in use.
+
+## Servers
+
+### Node HTTP server
+
+```js
+import { createServer } from "node:http";
+import { grafserv } from "grafserv/node";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create a Node HTTP server
+const server = createServer();
+server.on("error", (e) => {
+  console.error(e);
+});
+
+// Create a Grafserv instance
+const serv = grafserv({ schema, preset });
+
+// Mount the request handler into a new HTTP server, and register websockets if
+// desired
+serv.addTo(server).catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+
+// Start the Node server
+server.listen(preset.grafserv.port ?? 5678);
+```
+
+### Express V4
+
+```js
+import { createServer } from "node:http";
+import express from "express";
+import { grafserv } from "grafserv/express/v4";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create an express app
+const app = express();
+// (Add any Express middleware you want here.)
+
+// Create a Node HTTP server, mounting Express into it
+const server = createServer(app);
+server.on("error", (e) => {
+  console.error(e);
+});
+
+// Create a Grafserv instance
+const serv = grafserv({ schema, preset });
+
+// Add the Grafserv instance's route handlers to the Express app, and register
+// websockets if desired
+serv.addTo(app, server).catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+
+// Start the Express server
+server.listen(preset.grafserv.port ?? 5678);
+```
+
+### Koa V2
+
+```js
+import { createServer } from "node:http";
+import Koa from "koa";
+import { grafserv } from "grafserv/koa/v2";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create a Koa app
+const app = new Koa();
+// (Add any Koa middleware you want here.)
+
+// Create a Node HTTP server, mounting Koa into it
+const server = createServer(app);
+server.on("error", (e) => {
+  console.error(e);
+});
+
+// Create a Grafserv instance
+const serv = grafserv({ schema, preset });
+
+// Add the Grafserv instance's route handlers to the Koa app, and register
+// websockets if desired
+serv.addTo(app, server).catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+
+// Start the Koa server
+server.listen(preset.grafserv.port ?? 5678);
+```
+
+### Fastify V4
+
+```js
+import Fastify from "fastify";
+// import websocket from '@fastify/websocket'
+import { grafserv } from "grafserv/fastify/v4";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create a Fastify app
+const app = Fastify({
+  logger: true,
+});
+// (Add any Fastify middleware you want here.)
+// await app.register(websocket);
+
+// Create a Grafserv instance
+const serv = grafserv({ schema, preset });
+
+// Add the Grafserv instance's route handlers to the Fastify app
+serv.addTo(app).catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+
+// Start the Fastify server
+app.listen({ port: preset.grafserv.port ?? 5678 }, (err, address) => {
+  if (err) throw err;
+  console.log(`Server is now listening on ${address}`);
+});
+```
+
+### Next.js API route
+
+**TODO: actually implement this!**
+
+Grafserv handles a number of API routes, so you should define one for each of
+the things you care about. It's critical that you ensure that the paths line up
+with those used in the Graphile config, otherwise the assets will not correctly
+be served/referenced, this may cause issues when communicating between [Ruru][]
+and GraphQL.
+
+```js
+// utils/grafserv.mjs
+import { grafserv } from "grafserv/next/v13";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create a shared Grafserv instance
+export const serv = grafserv({ schema, preset });
+```
+
+```js
+// pages/api/graphql.mjs
+import { serv } from "../../utils/grafserv.mjs";
+
+// Create and export the `/graphql` route handler
+const handler = serv.createGraphQLHandler();
+export default handler;
+```
+
+```js
+// pages/api/ruru.mjs
+import { serv } from "../../utils/grafserv.mjs";
+
+// Create and export the `/ruru` route handler
+const handler = serv.createRuruHandler();
+export default handler;
+```
+
+### Lambda
+
+**TODO: actually implement this!**
+
+```js
+import { grafserv } from "grafserv/lambda";
+import preset from "./graphile.config.mjs";
+import schema from "./schema.mjs";
+
+// Create a Grafserv instance
+const serv = grafserv({ schema, preset });
+
+// Export a lambda handler for GraphQL
+export const handler = serv.createGraphQLHandler();
+```

package/dist/accept.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns a function that returns the (first, if multiple equal matches) type
+ * from mediaTypes that best matches the accept query specified by the given
+ * `acceptHeader`. If no Accept header is present then the first mediaType will
+ * be returned. If no match is possible, `null` will be returned.
+ */
+export declare function makeAcceptMatcher(mediaTypes: string[]): (acceptHeader: string | undefined) => string | null;
+//# sourceMappingURL=accept.d.ts.map

package/dist/accept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accept.d.ts","sourceRoot":"","sources":["../src/accept.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,kBAwBpC,MAAM,GAAG,SAAS,KAC/B,MAAM,GAAG,IAAI,CAmCjB"}