graphql-http 1.6.1 → 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,6 +719,23 @@ 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.
@@ -743,6 +744,14 @@ Check the [docs folder](docs/) out for [TypeDoc](https://typedoc.org) generated
 
 Inspect audits of other implementations in the [implementations folder](implementations/). Adding your implementation is very welcome!
 
-## [Want to help?](CONTRIBUTING.md)
+## 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/server.js

@@ -87,24 +87,27 @@ function serverAudits(opts) {
                 throw 'Body is not UTF-8 encoded';
             }
         }),
-        (0, utils_1.audit)('MUST accept only utf-8 charset', async () => {
+        (0, utils_1.audit)('MUST accept utf-8 encoding', async () => {
             const url = new URL(opts.url);
             url.searchParams.set('query', '{ __typename }');
             const res = await fetchFn(url.toString(), {
                 headers: {
-                    accept: 'application/graphql-response+json; charset=iso-8859-1',
+                    'content-type': 'application/json; charset=utf-8',
                 },
             });
-            // application/json is 200 + errors
-            const contentType = res.headers.get('content-type') || '';
-            if (contentType.includes('application/json')) {
-                (0, utils_1.assert)(`Content-Type ${contentType} status code`, res.status).toBe(200);
-                (0, utils_1.assert)('Execution result', await (0, utils_1.assertBodyAsExecutionResult)(res)).toHaveProperty('errors');
-                return;
-            }
-            // other content-types must be 4xx
-            (0, utils_1.assert)(`Content-Type ${contentType} status code`, res.status).toBeGreaterThanOrEqual(400);
-            (0, utils_1.assert)(`Content-Type ${contentType} status code`, res.status).toBeLessThanOrEqual(499);
+            (0, utils_1.assert)('Status code', res.status).toBe(200);
+            (0, utils_1.assert)('Content-Type header', res.headers.get('content-type')).toContain('utf-8');
+        }),
+        (0, utils_1.audit)('MUST assume utf-8 if encoding is unspecified', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    'content-type': 'application/json',
+                },
+            });
+            (0, utils_1.assert)('Status code', res.status).toBe(200);
+            (0, utils_1.assert)('Content-Type header', res.headers.get('content-type')).toContain('utf-8');
         }),
         // Request
         (0, utils_1.audit)('MUST accept POST requests', async () => {

package/lib/audits/server.mjs

@@ -84,24 +84,27 @@ export function serverAudits(opts) {
                 throw 'Body is not UTF-8 encoded';
             }
         }),
-        audit('MUST accept only utf-8 charset', async () => {
+        audit('MUST accept utf-8 encoding', async () => {
             const url = new URL(opts.url);
             url.searchParams.set('query', '{ __typename }');
             const res = await fetchFn(url.toString(), {
                 headers: {
-                    accept: 'application/graphql-response+json; charset=iso-8859-1',
+                    'content-type': 'application/json; charset=utf-8',
                 },
             });
-            // application/json is 200 + errors
-            const contentType = res.headers.get('content-type') || '';
-            if (contentType.includes('application/json')) {
-                assert(`Content-Type ${contentType} status code`, res.status).toBe(200);
-                assert('Execution result', await assertBodyAsExecutionResult(res)).toHaveProperty('errors');
-                return;
-            }
-            // other content-types must be 4xx
-            assert(`Content-Type ${contentType} status code`, res.status).toBeGreaterThanOrEqual(400);
-            assert(`Content-Type ${contentType} status code`, res.status).toBeLessThanOrEqual(499);
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('utf-8');
+        }),
+        audit('MUST assume utf-8 if encoding is unspecified', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    'content-type': 'application/json',
+                },
+            });
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('utf-8');
         }),
         // Request
         audit('MUST accept POST requests', async () => {

package/lib/audits/utils.d.mts

@@ -3,7 +3,7 @@
  * audit/utils
  *
  */
-import { ExecutionResult } from 'graphql';
+import type { ExecutionResult } from 'graphql';
 import { Audit, AuditName } from './common';
 export * from '../utils';
 /**

package/lib/audits/utils.d.ts

@@ -3,7 +3,7 @@
  * audit/utils
  *
  */
-import { ExecutionResult } from 'graphql';
+import type { ExecutionResult } from 'graphql';
 import { Audit, AuditName } from './common';
 export * from '../utils';
 /**

package/lib/handler.d.mts

@@ -8,27 +8,25 @@ import { RequestParams } from './common';
 /**
  * The incoming request headers the implementing server should provide.
  *
- * @category Common
+ * @category Server
  */
-export interface RequestHeaders {
-    accept?: string | undefined;
-    allow?: string | undefined;
-    'content-type'?: string | undefined;
+export declare type RequestHeaders = {
     /**
      * Always an array in Node. Duplicates are added to it.
-     * Not necessarily true for other environments, make sure
-     * to check the type during runtime.
+     * Not necessarily true for other environments.
      */
     'set-cookie'?: string | string[] | undefined;
     [key: string]: string | string[] | undefined;
-}
+} | {
+    get: (key: string) => string | null;
+};
 /**
  * Server agnostic request interface containing the raw request
  * which is server dependant.
  *
- * @category Common
+ * @category Server
  */
-export interface Request<RawRequest, Context> {
+export interface Request<Raw, Context> {
     readonly method: string;
     readonly url: string;
     readonly headers: RequestHeaders;
@@ -45,7 +43,7 @@ export interface Request<RawRequest, Context> {
      * For example: `express.Request` when using Express, or maybe
      * `http.IncomingMessage` when just using Node with `http.createServer`.
      */
-    readonly raw: RawRequest;
+    readonly raw: Raw;
     /**
      * Context value about the incoming request, you're free to pass any information here.
      */
@@ -54,7 +52,7 @@ export interface Request<RawRequest, Context> {
 /**
  * The response headers that get returned from graphql-http.
  *
- * @category Common
+ * @category Server
  */
 export declare type ResponseHeaders = {
     accept?: string;
@@ -65,14 +63,14 @@ export declare type ResponseHeaders = {
  * Server agnostic response body returned from `graphql-http` needing
  * to be coerced to the server implementation in use.
  *
- * @category Common
+ * @category Server
  */
 export declare type ResponseBody = string;
 /**
  * Server agnostic response options (ex. status and headers) returned from
  * `graphql-http` needing to be coerced to the server implementation in use.
  *
- * @category Common
+ * @category Server
  */
 export interface ResponseInit {
     readonly status: number;
@@ -83,13 +81,13 @@ export interface ResponseInit {
  * Server agnostic response returned from `graphql-http` containing the
  * body and init options needing to be coerced to the server implementation in use.
  *
- * @category Common
+ * @category Server
  */
 export declare type Response = readonly [body: ResponseBody | null, init: ResponseInit];
 /**
  * Checks whether the passed value is the `graphql-http` server agnostic response.
  *
- * @category Common
+ * @category Server
  */
 export declare function isResponse(val: unknown): val is Response;
 /**
@@ -102,9 +100,13 @@ export declare function isResponse(val: unknown): val is Response;
  *
  * @category Server
  */
-export declare type ExecutionContext = object | symbol | number | string | boolean | undefined | null;
+export declare type OperationContext = Record<PropertyKey, unknown> | symbol | number | string | boolean | undefined | null;
+/** @category Server */
+export declare type OperationArgs<Context extends OperationContext = undefined> = ExecutionArgs & {
+    contextValue?: Context;
+};
 /** @category Server */
-export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
+export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown, Context extends OperationContext = undefined> {
     /**
      * The GraphQL schema on which the operations will
      * be executed and validated against.
@@ -121,13 +123,13 @@ export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    schema?: GraphQLSchema | ((req: Request<RawRequest, Context>, args: Omit<ExecutionArgs, 'schema'>) => Promise<GraphQLSchema | Response> | GraphQLSchema | Response);
+    schema?: GraphQLSchema | ((req: Request<RequestRaw, RequestContext>, args: Omit<OperationArgs<Context>, 'schema'>) => Promise<GraphQLSchema | Response> | GraphQLSchema | Response);
     /**
      * A value which is provided to every resolver and holds
      * important contextual information like the currently
      * logged in user, or access to a database.
      */
-    context?: ExecutionContext | ((req: Request<RawRequest, Context>, args: ExecutionArgs) => Promise<ExecutionContext | Response> | ExecutionContext | Response);
+    context?: Context | ((req: Request<RequestRaw, RequestContext>, params: RequestParams) => Promise<Context | Response> | Context | Response);
     /**
      * A custom GraphQL validate function allowing you to apply your
      * own validation rules.
@@ -176,7 +178,7 @@ export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    onSubscribe?: (req: Request<RawRequest, Context>, params: RequestParams) => Promise<ExecutionResult | ExecutionArgs | readonly GraphQLError[] | Response | void> | ExecutionResult | ExecutionArgs | readonly GraphQLError[] | Response | void;
+    onSubscribe?: (req: Request<RequestRaw, RequestContext>, params: RequestParams) => Promise<ExecutionResult | OperationArgs<Context> | readonly GraphQLError[] | Response | void> | ExecutionResult | OperationArgs<Context> | readonly GraphQLError[] | Response | void;
     /**
      * Executed after the operation call resolves.
      *
@@ -190,7 +192,7 @@ export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    onOperation?: (req: Request<RawRequest, Context>, args: ExecutionArgs, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
+    onOperation?: (req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
 }
 /**
  * The ready-to-use handler. Simply plug it in your favourite HTTP framework
@@ -202,7 +204,7 @@ export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
  *
  * @category Server
  */
-export declare type Handler<RawRequest = unknown, Context = unknown> = (req: Request<RawRequest, Context>) => Promise<Response>;
+export declare type Handler<RequestRaw = unknown, RequestContext = unknown> = (req: Request<RequestRaw, RequestContext>) => Promise<Response>;
 /**
  * Makes a GraphQL over HTTP Protocol compliant server handler. The handler can
  * be used with your favourite server library.
@@ -258,7 +260,7 @@ export declare type Handler<RawRequest = unknown, Context = unknown> = (req: Req
  *
  * @category Server
  */
-export declare function createHandler<RawRequest = unknown, Context = unknown>(options: HandlerOptions<RawRequest, Context>): Handler<RawRequest, Context>;
+export declare function createHandler<RequestRaw = unknown, RequestContext = unknown, Context extends OperationContext = undefined>(options: HandlerOptions<RequestRaw, RequestContext, Context>): Handler<RequestRaw, RequestContext>;
 /**
  * Request's Media-Type that the server accepts.
  *