graphql-http 1.6.0 → 1.7.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Denis Badurina
+Copyright (c) GraphQL Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,10 +5,12 @@
 
   <h6>Simple, pluggable, zero-dependency, <a href="https://graphql.github.io/graphql-over-http">GraphQL over HTTP Protocol</a> compliant server and client.</h6>
 
-[![Continuous integration](https://github.com/enisdenjo/graphql-http/workflows/Continuous%20integration/badge.svg)](https://github.com/enisdenjo/graphql-http/actions?query=workflow%3A%22Continuous+integration%22) [![graphql-http](https://img.shields.io/npm/v/graphql-http.svg?label=graphql-http&logo=npm)](https://www.npmjs.com/package/graphql-http)
+[![Continuous integration](https://github.com/graphql/graphql-http/workflows/Continuous%20integration/badge.svg)](https://github.com/graphql/graphql-http/actions?query=workflow%3A%22Continuous+integration%22) [![graphql-http](https://img.shields.io/npm/v/graphql-http.svg?label=graphql-http&logo=npm)](https://www.npmjs.com/package/graphql-http)
 
 <i>Need subscriptions? Try <b>[graphql-ws](https://github.com/enisdenjo/graphql-ws)</b> or <b>[graphql-sse](https://github.com/enisdenjo/graphql-sse)</b> instead!</i>
 
+<i>Want a full-featured server? See the <b>[servers section](#servers)</b></i>!
+
   <br />
 </div>
 
@@ -51,34 +53,18 @@ const schema = new GraphQLSchema({
 
 ```js
 import http from 'http';
-import { createHandler } from 'graphql-http';
+import { createHandler } from 'graphql-http/lib/use/node';
 import { schema } from './previous-step';
 
-// Create the GraphQL over HTTP handler
+// Create the GraphQL over HTTP Node request handler
 const handler = createHandler({ schema });
 
-// Create a HTTP server using the handler on `/graphql`
-const server = http.createServer(async (req, res) => {
-  if (!req.url.startsWith('/graphql')) {
-    return res.writeHead(404).end();
-  }
-
-  try {
-    const [body, init] = await handler({
-      url: req.url,
-      method: req.method,
-      headers: req.headers,
-      body: () =>
-        new Promise((resolve) => {
-          let body = '';
-          req.on('data', (chunk) => (body += chunk));
-          req.on('end', () => resolve(body));
-        }),
-      raw: req,
-    });
-    res.writeHead(init.status, init.statusText, init.headers).end(body);
-  } catch (err) {
-    res.writeHead(500).end(err.message);
+// Create a HTTP server using the listner on `/graphql`
+const server = http.createServer((req, res) => {
+  if (req.url.startsWith('/graphql')) {
+    handler(req, res);
+  } else {
+    res.writeHead(404).end();
   }
 });
 
@@ -98,10 +84,10 @@ $ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
 ```js
 import fs from 'fs';
 import http2 from 'http2';
-import { createHandler } from 'graphql-http';
+import { createHandler } from 'graphql-http/lib/use/node';
 import { schema } from './previous-step';
 
-// Create the GraphQL over HTTP handler
+// Create the GraphQL over HTTP Node request handler
 const handler = createHandler({ schema });
 
 // Create a HTTP/2 server using the handler on `/graphql`
@@ -110,27 +96,11 @@ const server = http2.createSecureServer(
     key: fs.readFileSync('localhost-privkey.pem'),
     cert: fs.readFileSync('localhost-cert.pem'),
   },
-  async (req, res) => {
-    if (!req.url.startsWith('/graphql')) {
-      return res.writeHead(404).end();
-    }
-
-    try {
-      const [body, init] = await handler({
-        url: req.url,
-        method: req.method,
-        headers: req.headers,
-        body: () =>
-          new Promise((resolve) => {
-            let body = '';
-            req.on('data', (chunk) => (body += chunk));
-            req.on('end', () => resolve(body));
-          }),
-        raw: req,
-      });
-      res.writeHead(init.status, init.statusText, init.headers).end(body);
-    } catch (err) {
-      res.writeHead(500).end(err.message);
+  (req, res) => {
+    if (req.url.startsWith('/graphql')) {
+      handler(req, res);
+    } else {
+      res.writeHead(404).end();
     }
   },
 );
@@ -143,35 +113,15 @@ console.log('Listening to port 4000');
 
 ```js
 import express from 'express'; // yarn add express
-import { createHandler } from 'graphql-http';
+import { createHandler } from 'graphql-http/lib/use/express';
 import { schema } from './previous-step';
 
-// Create the GraphQL over HTTP handler
-const handler = createHandler({ schema });
-
-// Create an express app serving all methods on `/graphql`
+// Create a express instance serving all methods on `/graphql`
+// where the GraphQL over HTTP express request handler is
 const app = express();
-app.use('/graphql', async (req, res) => {
-  try {
-    const [body, init] = await handler({
-      url: req.url,
-      method: req.method,
-      headers: req.headers,
-      body: () =>
-        new Promise((resolve) => {
-          let body = '';
-          req.on('data', (chunk) => (body += chunk));
-          req.on('end', () => resolve(body));
-        }),
-      raw: req,
-    });
-    res.writeHead(init.status, init.statusText, init.headers).end(body);
-  } catch (err) {
-    res.writeHead(500).end(err.message);
-  }
-});
+app.all('/graphql', createHandler({ schema }));
 
-app.listen(4000);
+app.listen({ port: 4000 });
 console.log('Listening to port 4000');
 ```
 
@@ -179,30 +129,15 @@ console.log('Listening to port 4000');
 
 ```js
 import Fastify from 'fastify'; // yarn add fastify
-import { createHandler } from 'graphql-http';
+import { createHandler } from 'graphql-http/lib/use/fastify';
 import { schema } from './previous-step';
 
-// Create the GraphQL over HTTP handler
-const handler = createHandler({ schema });
-
 // Create a fastify instance serving all methods on `/graphql`
+// where the GraphQL over HTTP fastify request handler is
 const fastify = Fastify();
-fastify.all('/graphql', async (req, res) => {
-  try {
-    const [body, init] = await handler({
-      url: req.url,
-      method: req.method,
-      headers: req.headers,
-      body: req.body, // fastify reads the body for you
-      raw: req,
-    });
-    res.writeHead(init.status, init.statusText, init.headers).end(body);
-  } catch (err) {
-    res.writeHead(500).end(err.message);
-  }
-});
+fastify.all('/graphql', createHandler({ schema }));
 
-fastify.listen(4000);
+fastify.listen({ port: 4000 });
 console.log('Listening to port 4000');
 ```
 
@@ -210,37 +145,49 @@ console.log('Listening to port 4000');
 
 ```ts
 import { serve } from 'https://deno.land/std@0.151.0/http/server.ts';
-import { createHandler } from 'https://esm.sh/graphql-http';
+import { createHandler } from 'https://esm.sh/graphql-http/lib/use/fetch';
 import { schema } from './previous-step';
 
-// Create the GraphQL over HTTP handler
-const handler = createHandler<Request>({ schema });
+// Create the GraphQL over HTTP native fetch handler
+const handler = createHandler({ schema });
 
 // Start serving on `/graphql` using the handler
 await serve(
-  async (req: Request) => {
+  (req: Request) => {
     const [path, _search] = req.url.split('?');
-    if (!path.endsWith('/graphql')) {
-      return new Response(null, { status: 404, statusText: 'Not Found' });
+    if (path.endsWith('/graphql')) {
+      return handler(req);
+    } else {
+      return new Response(null, { status: 404 });
     }
-
-    const headers: Record<string, string> = {};
-    req.headers.forEach((value, key) => (headers[key] = value));
-    const [body, init] = await handler({
-      url: req.url,
-      method: req.method,
-      headers,
-      body: () => req.text(),
-      raw: req,
-    });
-    return new Response(body, init);
   },
   {
-    port: 4000,
+    port: 4000, // Listening to port 4000
   },
 );
+```
+
+##### With [`Bun`](https://bun.sh/)
 
-// Listening to port 4000
+```js
+import { createHandler } from 'graphql-http/lib/use/fetch'; // bun install graphql-http
+import { schema } from './previous-step';
+
+// Create the GraphQL over HTTP native fetch handler
+const handler = createHandler({ schema });
+
+// Start serving on `/graphql` using the handler
+export default {
+  port: 4000, // Listening to port 4000
+  fetch(req) {
+    const [path, _search] = req.url.split('?');
+    if (path.endsWith('/graphql')) {
+      return handler(req);
+    } else {
+      return new Response(null, { status: 404 });
+    }
+  },
+};
 ```
 
 #### Use the client
@@ -555,7 +502,7 @@ const client = createClient({
 <summary><a href="#deno-client">🔗</a> Client usage in Deno</summary>
 
 ```js
-import { createClient } from 'graphql-http';
+import { createClient } from 'https://esm.sh/graphql-http';
 
 const client = createClient({
   url: 'http://deno.earth:4000/graphql',
@@ -566,6 +513,43 @@ const client = createClient({
 
 </details>
 
+<details id="bun-client">
+<summary><a href="#bun-client">🔗</a> Client usage in Bun</summary>
+
+```js
+import { createClient } from 'graphql-http'; // bun install graphql-http
+
+const client = createClient({
+  url: 'http://bun.bread:4000/graphql',
+});
+
+// consider other recipes for usage inspiration
+```
+
+</details>
+
+<details id="migrating-express-grpahql">
+<summary><a href="#migrating-express-grpahql">🔗</a> Server handler migration from <a href="https://github.com/graphql/express-graphql">express-graphql</a></summary>
+
+```diff
+import express from 'express';
+import { schema } from './my-graphql-schema';
+
+-import { graphqlHTTP } from 'express-graphql';
++import { createHandler } from 'graphql-http/lib/use/express';
+
+const app = express();
+
+app.use(
+  '/graphql',
+-  graphqlHTTP({ schema }),
++  createHandler({ schema }),
+);
+
+app.listen(4000);
+```
+
+</details>
 <details id="auth">
 <summary><a href="#auth">🔗</a> Server handler usage with authentication</summary>
 
@@ -735,10 +719,39 @@ for (const audit of serverAudits({
 
 </details>
 
+## Only [GraphQL over HTTP](https://graphql.github.io/graphql-over-http/)
+
+This is the official [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/) reference implementation and as such follows the specification strictly without any additional features (like file uploads, @stream/@defer directives and subscriptions).
+
+Having said this, graphql-http is mostly aimed for library authors and simple server setups, where the requirements are exact to what the aforementioned spec offers.
+
+## [Servers](/implementations)
+
+If you want a feature-full server with bleeding edge technologies, you're recommended to use one of the following.
+
+| Name                                                           | Audit                                                              |
+| -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [graphql-yoga](https://www.the-guild.dev/graphql/yoga-server)  | [✅ Fully compliant](/implementations/graphql-yoga/README.md)      |
+| [apollo-server](https://www.the-guild.dev/graphql/yoga-server) | [⚠️ Partially compliant](/implementations/apollo-server/README.md) |
+| [mercurius](https://mercurius.dev)                             | [⚠️ Partially compliant](/implementations/mercurius/README.md)     |
+| [graphql-helix](https://www.graphql-helix.com/)                | [⚠️ Partially compliant](/implementations/graphql-helix/README.md) |
+
 ## [Documentation](docs/)
 
 Check the [docs folder](docs/) out for [TypeDoc](https://typedoc.org) generated documentation.
 
-## [Want to help?](CONTRIBUTING.md)
+## [Audits](implementations/)
+
+Inspect audits of other implementations in the [implementations folder](implementations/). Adding your implementation is very welcome!
+
+## Want to help?
+
+File a bug, contribute with code, or improve documentation? Read up on our guidelines below and drive development with `yarn test --watch` away!
+
+This repository is managed by EasyCLA. Project participants must sign the free [GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](http://individual-spec-membership.graphql.org/) or their [employers](http://corporate-spec-membership.graphql.org/).
+
+To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.
+
+You can find [detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). If you have issues, please email [operations@graphql.org](mailto:operations@graphql.org).
 
-File a bug, contribute with code, or improve documentation? Read up on our guidelines for [contributing](CONTRIBUTING.md) and drive development with `yarn test --watch` away!
+If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the [GraphQL Foundation](https://foundation.graphql.org/join).

package/lib/audits/common.d.mts

@@ -0,0 +1,58 @@
+/**
+ *
+ * audit/common
+ *
+ */
+/**
+ * Audit requirement levels as per [RFC2119](https://www.rfc-editor.org/rfc/rfc2119).
+ *
+ * @category Audits
+ */
+export declare type AuditRequirement = 'MUST' | 'SHOULD' | 'MAY';
+/**
+ * Audit name starting with the audit requirement level.
+ *
+ * @category Audits
+ */
+export declare type AuditName = `${AuditRequirement} ${string}`;
+/**
+ * Actual audit test returning an result.
+ *
+ * The test function will throw only if the error is fatal.
+ *
+ * @category Audits
+ */
+export interface Audit {
+    name: AuditName;
+    fn: () => Promise<AuditResult>;
+}
+/**
+ * Indicates that the audit was successful.
+ *
+ * @category Audits
+ */
+export interface AuditOk {
+    name: AuditName;
+    status: 'ok';
+}
+/**
+ * Indicates that the audit failed.
+ *
+ * If the status is `warn`, the audit is not a requirement but rather a recommendation.
+ *
+ * On the other hand, if the status is `error`, the audit is a requirement and the source
+ * is therefore not compliant.
+ *
+ * @category Audits
+ */
+export interface AuditFail {
+    name: AuditName;
+    status: 'warn' | 'error';
+    reason: string;
+}
+/**
+ * Result of the performed audit. See `AuditOk` and `AuditFail` for more information.
+ *
+ * @category Audits
+ */
+export declare type AuditResult = AuditOk | AuditFail;

package/lib/audits/index.d.mts

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './server';

package/lib/audits/server.d.mts

@@ -0,0 +1,39 @@
+/**
+ *
+ * audit/server
+ *
+ */
+import { Audit, AuditResult } from './common';
+/**
+ * Options for server audits required to check GraphQL over HTTP spec conformance.
+ *
+ * @category Audits
+ */
+export interface ServerAuditOptions {
+    /**
+     * The URL of the GraphQL server for the audit.
+     */
+    url: string;
+    /**
+     * The Fetch function to use.
+     *
+     * For NodeJS environments consider using [`@whatwg-node/fetch`](https://github.com/ardatan/whatwg-node/tree/master/packages/fetch).
+     *
+     * @default global.fetch
+     */
+    fetchFn?: unknown;
+}
+/**
+ * List of server audits required to check GraphQL over HTTP spec conformance.
+ *
+ * @category Audits
+ */
+export declare function serverAudits(opts: ServerAuditOptions): Audit[];
+/**
+ * Performs the full list of server audits required for GraphQL over HTTP spec conformance.
+ *
+ * Please consult the `AuditResult` for more information.
+ *
+ * @category Audits
+ */
+export declare function auditServer(opts: ServerAuditOptions): Promise<AuditResult[]>;