graphql-http 0.1.0 → 1.0.0

package/lib/handler.d.ts

@@ -0,0 +1,155 @@
+/**
+ *
+ * handler
+ *
+ */
+import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, execute as graphqlExecute } from 'graphql';
+import { Request, RequestParams, Response } from './common';
+/**
+ * A concrete GraphQL execution context value type.
+ *
+ * Mainly used because TypeScript collapes unions
+ * with `any` or `unknown` to `any` or `unknown`. So,
+ * we use a custom type to allow definitions such as
+ * the `context` server option.
+ *
+ * @category Server
+ */
+export declare type ExecutionContext = object | symbol | number | string | boolean | undefined | null;
+/** @category Server */
+export interface HandlerOptions<RawRequest = unknown> {
+    /**
+     * The GraphQL schema on which the operations will
+     * be executed and validated against.
+     *
+     * If a function is provided, it will be called on every
+     * operation request allowing you to manipulate schema
+     * dynamically.
+     *
+     * If the schema is left undefined, you're trusted to
+     * provide one in the returned `ExecutionArgs` from the
+     * `onSubscribe` callback.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    schema?: GraphQLSchema | ((req: Request<RawRequest>, args: Omit<ExecutionArgs, '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>, args: ExecutionArgs) => Promise<ExecutionContext | Response> | ExecutionContext | Response);
+    /**
+     * A custom GraphQL validate function allowing you to apply your
+     * own validation rules.
+     */
+    validate?: typeof graphqlValidate;
+    /**
+     * Is the `execute` function from GraphQL which is
+     * used to execute the query and mutation operations.
+     */
+    execute?: typeof graphqlExecute;
+    /**
+     * The subscribe callback executed right after processing the request
+     * before proceeding with the GraphQL operation execution.
+     *
+     * If you return `ExecutionArgs` from the callback, it will be used instead of
+     * trying to build one internally. In this case, you are responsible for providing
+     * a ready set of arguments which will be directly plugged in the operation execution.
+     *
+     * Omitting the fields `contextValue` from the returned `ExecutionArgs` will use the
+     * provided `context` option, if available.
+     *
+     * Useful for preparing the execution arguments following a custom logic. A typical
+     * use-case is persisted queries. You can identify the query from the request parameters
+     * and supply the appropriate GraphQL operation execution arguments.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    onSubscribe?: (req: Request<RawRequest>, params: RequestParams) => Promise<ExecutionArgs | Response | void> | ExecutionArgs | Response | void;
+    /**
+     * Executed after the operation call resolves.
+     *
+     * The `OperationResult` argument is the result of operation
+     * execution. It can be an iterator or already a value.
+     *
+     * Use this callback to listen for GraphQL operations and
+     * execution result manipulation.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    onOperation?: (req: Request<RawRequest>, args: ExecutionArgs, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
+}
+/**
+ * The ready-to-use handler. Simply plug it in your favourite HTTP framework
+ * and enjoy.
+ *
+ * Errors thrown from **any** of the provided options or callbacks (or even due to
+ * library misuse or potential bugs) will reject the handler's promise. They are
+ * considered internal errors and you should take care of them accordingly.
+ *
+ * @category Server
+ */
+export declare type Handler<RawRequest = unknown> = (req: Request<RawRequest>) => Promise<Response>;
+/**
+ * Makes a GraphQL over HTTP Protocol compliant server handler. The handler can
+ * be used with your favourite server library.
+ *
+ * Beware that the handler resolves only after the whole operation completes.
+ *
+ * Errors thrown from **any** of the provided options or callbacks (or even due to
+ * library misuse or potential bugs) will reject the handler's promise. They are
+ * considered internal errors and you should take care of them accordingly.
+ *
+ * For production environments, its recommended not to transmit the exact internal
+ * error details to the client, but instead report to an error logging tool or simply
+ * the console.
+ *
+ * Simple example usage with Node:
+ *
+ * ```js
+ * import http from 'http';
+ * import { createHandler } from 'graphql-http';
+ * import { schema } from './my-graphql-schema';
+ *
+ * // Create the GraphQL over HTTP 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: await 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) {
+ *     // BEWARE not to transmit the exact internal error message in production environments
+ *     res.writeHead(500).end(err.message);
+ *   }
+ * });
+ *
+ * server.listen(4000);
+ * console.log('Listening to port 4000');
+ * ```
+ *
+ * @category Server
+ */
+export declare function createHandler<RawRequest = unknown>(options: HandlerOptions<RawRequest>): Handler<RawRequest>;

package/lib/handler.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ *
+ * handler
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = void 0;
+const graphql_1 = require("graphql");
+const common_1 = require("./common");
+/**
+ * Makes a GraphQL over HTTP Protocol compliant server handler. The handler can
+ * be used with your favourite server library.
+ *
+ * Beware that the handler resolves only after the whole operation completes.
+ *
+ * Errors thrown from **any** of the provided options or callbacks (or even due to
+ * library misuse or potential bugs) will reject the handler's promise. They are
+ * considered internal errors and you should take care of them accordingly.
+ *
+ * For production environments, its recommended not to transmit the exact internal
+ * error details to the client, but instead report to an error logging tool or simply
+ * the console.
+ *
+ * Simple example usage with Node:
+ *
+ * ```js
+ * import http from 'http';
+ * import { createHandler } from 'graphql-http';
+ * import { schema } from './my-graphql-schema';
+ *
+ * // Create the GraphQL over HTTP 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: await 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) {
+ *     // BEWARE not to transmit the exact internal error message in production environments
+ *     res.writeHead(500).end(err.message);
+ *   }
+ * });
+ *
+ * server.listen(4000);
+ * console.log('Listening to port 4000');
+ * ```
+ *
+ * @category Server
+ */
+function createHandler(options) {
+    const { schema, context, validate = graphql_1.validate, execute = graphql_1.execute, onSubscribe, onOperation, } = options;
+    return async function handler(req) {
+        var _a, _b;
+        const method = req.method;
+        if (method !== 'GET' && method !== 'POST') {
+            return [
+                null,
+                {
+                    status: 405,
+                    statusText: 'Method Not Allowed',
+                    headers: {
+                        allow: 'GET, POST',
+                    },
+                },
+            ];
+        }
+        let acceptedMediaType;
+        const accepts = (req.headers.accept || '*/*')
+            .replace(/\s/g, '')
+            .toLowerCase()
+            .split(',');
+        for (const accept of accepts) {
+            // accept-charset became obsolete, shouldnt be used (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Charset)
+            // TODO: handle the weight parameter "q"
+            const [mediaType, ...params] = accept.split(';');
+            const charset = (params === null || params === void 0 ? void 0 : params.find((param) => param.includes('charset='))) || 'charset=utf8'; // utf-8 is assumed when not specified;
+            if (mediaType === 'application/json' && charset === 'charset=utf8') {
+                acceptedMediaType = 'application/json';
+                break;
+            }
+            if ((mediaType === 'application/graphql+json' ||
+                mediaType === 'application/*' ||
+                mediaType === '*/*') &&
+                charset === 'charset=utf8') {
+                acceptedMediaType = 'application/graphql+json';
+                break;
+            }
+        }
+        if (!acceptedMediaType) {
+            return [
+                null,
+                {
+                    status: 406,
+                    statusText: 'Not Acceptable',
+                    headers: {
+                        accept: 'application/graphql+json; charset=utf-8, application/json; charset=utf-8',
+                    },
+                },
+            ];
+        }
+        // TODO: should graphql-http care about content-encoding? I'd say unzipping should happen before handler is reached
+        const [mediaType, charset = 'charset=utf-8', // utf-8 is assumed when not specified. this parameter is either "charset" or "boundary" (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length)
+        ] = (req.headers['content-type'] || '')
+            .replace(/\s/g, '')
+            .toLowerCase()
+            .split(';');
+        let params;
+        try {
+            const partParams = {};
+            switch (true) {
+                case method === 'GET': {
+                    // TODO: what if content-type is specified and is not application/x-www-form-urlencoded?
+                    try {
+                        const url = new URL(req.url || '', 'http://localhost/');
+                        partParams.operationName =
+                            (_a = url.searchParams.get('operationName')) !== null && _a !== void 0 ? _a : undefined;
+                        partParams.query = (_b = url.searchParams.get('query')) !== null && _b !== void 0 ? _b : undefined;
+                        const variables = url.searchParams.get('variables');
+                        if (variables)
+                            partParams.variables = JSON.parse(variables);
+                        const extensions = url.searchParams.get('extensions');
+                        if (extensions)
+                            partParams.extensions = JSON.parse(extensions);
+                    }
+                    catch (_c) {
+                        throw new Error('Unparsable URL');
+                    }
+                    break;
+                }
+                case method === 'POST' &&
+                    mediaType === 'application/json' &&
+                    charset === 'charset=utf-8':
+                    {
+                        if (!req.body) {
+                            throw new Error('Missing body');
+                        }
+                        try {
+                            const data = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+                            partParams.operationName = data.operationName;
+                            partParams.query = data.query;
+                            partParams.variables = data.variables;
+                            partParams.extensions = data.extensions;
+                        }
+                        catch (_d) {
+                            throw new Error('Unparsable JSON body');
+                        }
+                        break;
+                    }
+                default: // graphql-http doesnt support any other content type
+                    return [
+                        null,
+                        {
+                            status: 415,
+                            statusText: 'Unsupported Media Type',
+                        },
+                    ];
+            }
+            if (!partParams.query)
+                throw new Error('Missing query');
+            if (partParams.variables != null &&
+                (typeof partParams.variables !== 'object' ||
+                    Array.isArray(partParams.variables))) {
+                throw new Error('Invalid variables');
+            }
+            if (partParams.extensions != null &&
+                (typeof partParams.extensions !== 'object' ||
+                    Array.isArray(partParams.extensions))) {
+                throw new Error('Invalid extensions');
+            }
+            // request parameters are checked and now complete
+            params = partParams;
+        }
+        catch (err) {
+            return [
+                err.message,
+                {
+                    status: acceptedMediaType === 'application/json' ? 200 : 400,
+                    statusText: 'Bad Request',
+                },
+            ];
+        }
+        let args;
+        const maybeResOrExecArgs = await (onSubscribe === null || onSubscribe === void 0 ? void 0 : onSubscribe(req, params));
+        if ((0, common_1.isResponse)(maybeResOrExecArgs))
+            return maybeResOrExecArgs;
+        else if (maybeResOrExecArgs)
+            args = maybeResOrExecArgs;
+        else {
+            if (!schema)
+                throw new Error('The GraphQL schema is not provided');
+            const { operationName, query, variables } = params;
+            let document;
+            try {
+                document = (0, graphql_1.parse)(query);
+            }
+            catch (_e) {
+                return [
+                    'GraphQL query syntax error',
+                    {
+                        status: acceptedMediaType === 'application/json' ? 200 : 400,
+                        statusText: 'Bad Request',
+                    },
+                ];
+            }
+            const argsWithoutSchema = {
+                operationName,
+                document,
+                variableValues: variables,
+            };
+            if (typeof schema === 'function') {
+                const resOrSchema = await schema(req, argsWithoutSchema);
+                if ((0, common_1.isResponse)(resOrSchema))
+                    return resOrSchema;
+                args = Object.assign(Object.assign({}, argsWithoutSchema), { schema: resOrSchema });
+            }
+            else {
+                args = Object.assign(Object.assign({}, argsWithoutSchema), { schema });
+            }
+        }
+        let operation;
+        try {
+            const ast = (0, graphql_1.getOperationAST)(args.document, args.operationName);
+            if (!ast)
+                throw null;
+            operation = ast.operation;
+        }
+        catch (_f) {
+            return [
+                'Unable to detect operation AST',
+                {
+                    status: acceptedMediaType === 'application/json' ? 200 : 400,
+                    statusText: 'Bad Request',
+                },
+            ];
+        }
+        if (operation === 'subscription') {
+            return [
+                'Subscriptions are not supported',
+                {
+                    status: 400,
+                    statusText: 'Bad Request',
+                },
+            ];
+        }
+        // mutations cannot happen over GETs
+        // https://graphql.github.io/graphql-over-http/draft/#sel-CALFJRPAAELBAAxwP
+        if (operation === 'mutation' && method === 'GET') {
+            return [
+                'Cannot perform mutations over GET',
+                {
+                    status: 405,
+                    statusText: 'Method Not Allowed',
+                    headers: {
+                        allow: 'POST',
+                    },
+                },
+            ];
+        }
+        if (!('contextValue' in args)) {
+            args.contextValue =
+                typeof context === 'function' ? await context(req, args) : context;
+        }
+        const validationErrs = validate(args.schema, args.document);
+        if (validationErrs.length) {
+            return [
+                JSON.stringify({ errors: validationErrs }),
+                {
+                    status: acceptedMediaType === 'application/json' ? 200 : 400,
+                    statusText: 'Bad Request',
+                    headers: {
+                        'content-type': acceptedMediaType === 'application/json'
+                            ? 'application/json; charset=utf-8'
+                            : 'application/graphql+json; charset=utf-8',
+                    },
+                },
+            ];
+        }
+        let result = await execute(args);
+        const maybeResOrResult = await (onOperation === null || onOperation === void 0 ? void 0 : onOperation(req, args, result));
+        if ((0, common_1.isResponse)(maybeResOrResult))
+            return maybeResOrResult;
+        else if (maybeResOrResult)
+            result = maybeResOrResult;
+        return [
+            JSON.stringify(result),
+            {
+                status: 200,
+                statusText: 'OK',
+                headers: {
+                    'content-type': acceptedMediaType === 'application/json'
+                        ? 'application/json; charset=utf-8'
+                        : 'application/graphql+json; charset=utf-8',
+                },
+            },
+        ];
+    };
+}
+exports.createHandler = createHandler;