graphql-http 1.13.0 → 1.15.0

package/README.md

@@ -3,10 +3,12 @@
 
   <h3>graphql-http</h3>
 
-  <h6>Simple, pluggable, zero-dependency, <a href="https://graphql.github.io/graphql-over-http">GraphQL over HTTP Protocol</a> compliant server and client.</h6>
+  <h6>Simple, pluggable, zero-dependency, <a href="https://graphql.github.io/graphql-over-http">GraphQL over HTTP spec</a> compliant server, client and audit suite.</h6>
 
 [![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>Quickly check for compliance? Visit <b>[graphql-http.com](https://graphql-http.com)</b>!</i>
+
 <i>Want a full-featured server? See the <b>[servers section](#servers)</b>!</i>
 
 <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>

package/lib/audits/index.d.mts

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

package/lib/audits/index.d.ts

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

package/lib/audits/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./common"), exports);
 __exportStar(require("./server"), exports);
+__exportStar(require("./render"), exports);

package/lib/audits/index.mjs

@@ -1,2 +1,3 @@
 export * from './common.mjs';
 export * from './server.mjs';
+export * from './render.mjs';

package/lib/audits/render.d.mts

@@ -0,0 +1,8 @@
+import { AuditResult } from './common';
+/**
+ * Renders the provided audit results to well-formatted and valid HTML.
+ *
+ * Do note that the rendered result is not an HTML document, it's rather
+ * just a component with results.
+ */
+export declare function renderAuditResultsToHTML(results: AuditResult[]): Promise<string>;

package/lib/audits/render.d.ts

@@ -0,0 +1,8 @@
+import { AuditResult } from './common';
+/**
+ * Renders the provided audit results to well-formatted and valid HTML.
+ *
+ * Do note that the rendered result is not an HTML document, it's rather
+ * just a component with results.
+ */
+export declare function renderAuditResultsToHTML(results: AuditResult[]): Promise<string>;

package/lib/audits/render.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAuditResultsToHTML = void 0;
+/**
+ * Renders the provided audit results to well-formatted and valid HTML.
+ *
+ * Do note that the rendered result is not an HTML document, it's rather
+ * just a component with results.
+ */
+async function renderAuditResultsToHTML(results) {
+    const grouped = {
+        total: 0,
+        ok: [],
+        warn: [],
+        error: [],
+    };
+    for (const result of results) {
+        grouped.total++;
+        if (result.status === 'ok') {
+            grouped[result.status].push(result);
+        }
+        else {
+            grouped[result.status].push(result);
+        }
+    }
+    let report = '<i>* This report was auto-generated by graphql-http</i>\n';
+    report += '\n';
+    report += '<h1>GraphQL over HTTP audit report</h1>\n';
+    report += '\n';
+    report += '<ul>\n';
+    report += `<li><b>${grouped.total}</b> audits in total</li>\n`;
+    // font-family: monospace helps render native emojis in HTML
+    if (grouped.ok.length) {
+        report += `<li><span style="font-family: monospace">✅</span> <b>${grouped.ok.length}</b> pass</li>\n`;
+    }
+    if (grouped.warn.length) {
+        // TODO: warning sign is rendered as "⚠️" in markdown instead of the emoji
+        report += `<li><span style="font-family: monospace">⚠️</span> <b>${grouped.warn.length}</b> warnings (optional)</li>\n`;
+    }
+    if (grouped.error.length) {
+        report += `<li><span style="font-family: monospace">❌</span> <b>${grouped.error.length}</b> errors (required)</li>\n`;
+    }
+    report += '</ul>\n';
+    report += '\n';
+    if (grouped.ok.length) {
+        report += '<h2>Passing</h2>\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.ok.entries()) {
+            report += `<li><code>${result.id}</code> ${result.name}</li>\n`;
+        }
+        report += '</ol>\n';
+        report += '\n';
+    }
+    if (grouped.warn.length) {
+        report += `<h2>Warnings</h2>\n`;
+        report += 'The server <i>SHOULD</i> support these, but is not required.\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.warn.entries()) {
+            report += await printAuditFail(result);
+        }
+        report += '</ol>\n';
+        report += '\n';
+    }
+    if (grouped.error.length) {
+        report += `<h2>Errors</h2>\n`;
+        report += 'The server <b>MUST</b> support these.\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.error.entries()) {
+            report += await printAuditFail(result);
+        }
+        report += '</ol>\n';
+    }
+    return report;
+}
+exports.renderAuditResultsToHTML = renderAuditResultsToHTML;
+async function printAuditFail(result) {
+    let report = '';
+    report += `<li><code>${result.id}</code> ${result.name}\n`;
+    report += '<details>\n';
+    report += `<summary>${truncate(result.reason)}</summary>\n`;
+    report += '<pre><code class="lang-json">'; // no "\n" because they count in HTML pre tags
+    const res = result.response;
+    const headers = {};
+    for (const [key, val] of res.headers.entries()) {
+        // some headers change on each run, dont report it
+        if (key === 'date') {
+            headers[key] = '<timestamp>';
+        }
+        else if (['cf-ray', 'server-timing'].includes(key)) {
+            headers[key] = '<omitted>';
+        }
+        else {
+            headers[key] = val;
+        }
+    }
+    let text = '', json;
+    try {
+        text = await res.text();
+        json = JSON.parse(text);
+    }
+    catch (_a) {
+        // noop
+    }
+    const stringified = JSON.stringify({
+        status: res.status,
+        statusText: res.statusText,
+        headers,
+        body: json || ((text === null || text === void 0 ? void 0 : text.length) > 5120 ? '<body is too long>' : text) || null,
+    }, (_k, v) => {
+        if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+            // sort object fields for stable stringify
+            const acc = {};
+            return Object.keys(v)
+                .sort()
+                .reverse() // body on bottom
+                .reduce((acc, k) => {
+                acc[k] = v[k];
+                return acc;
+            }, acc);
+        }
+        return v;
+    }, 2);
+    report += stringified + '\n';
+    report += '</code></pre>\n';
+    report += '</details>\n';
+    report += '</li>\n';
+    return report;
+}
+function truncate(str, len = 1024) {
+    if (str.length > len) {
+        return str.substring(0, len) + '...';
+    }
+    return str;
+}

package/lib/audits/render.mjs

@@ -0,0 +1,130 @@
+/**
+ * Renders the provided audit results to well-formatted and valid HTML.
+ *
+ * Do note that the rendered result is not an HTML document, it's rather
+ * just a component with results.
+ */
+export async function renderAuditResultsToHTML(results) {
+    const grouped = {
+        total: 0,
+        ok: [],
+        warn: [],
+        error: [],
+    };
+    for (const result of results) {
+        grouped.total++;
+        if (result.status === 'ok') {
+            grouped[result.status].push(result);
+        }
+        else {
+            grouped[result.status].push(result);
+        }
+    }
+    let report = '<i>* This report was auto-generated by graphql-http</i>\n';
+    report += '\n';
+    report += '<h1>GraphQL over HTTP audit report</h1>\n';
+    report += '\n';
+    report += '<ul>\n';
+    report += `<li><b>${grouped.total}</b> audits in total</li>\n`;
+    // font-family: monospace helps render native emojis in HTML
+    if (grouped.ok.length) {
+        report += `<li><span style="font-family: monospace">✅</span> <b>${grouped.ok.length}</b> pass</li>\n`;
+    }
+    if (grouped.warn.length) {
+        // TODO: warning sign is rendered as "⚠️" in markdown instead of the emoji
+        report += `<li><span style="font-family: monospace">⚠️</span> <b>${grouped.warn.length}</b> warnings (optional)</li>\n`;
+    }
+    if (grouped.error.length) {
+        report += `<li><span style="font-family: monospace">❌</span> <b>${grouped.error.length}</b> errors (required)</li>\n`;
+    }
+    report += '</ul>\n';
+    report += '\n';
+    if (grouped.ok.length) {
+        report += '<h2>Passing</h2>\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.ok.entries()) {
+            report += `<li><code>${result.id}</code> ${result.name}</li>\n`;
+        }
+        report += '</ol>\n';
+        report += '\n';
+    }
+    if (grouped.warn.length) {
+        report += `<h2>Warnings</h2>\n`;
+        report += 'The server <i>SHOULD</i> support these, but is not required.\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.warn.entries()) {
+            report += await printAuditFail(result);
+        }
+        report += '</ol>\n';
+        report += '\n';
+    }
+    if (grouped.error.length) {
+        report += `<h2>Errors</h2>\n`;
+        report += 'The server <b>MUST</b> support these.\n';
+        report += '<ol>\n';
+        for (const [, result] of grouped.error.entries()) {
+            report += await printAuditFail(result);
+        }
+        report += '</ol>\n';
+    }
+    return report;
+}
+async function printAuditFail(result) {
+    let report = '';
+    report += `<li><code>${result.id}</code> ${result.name}\n`;
+    report += '<details>\n';
+    report += `<summary>${truncate(result.reason)}</summary>\n`;
+    report += '<pre><code class="lang-json">'; // no "\n" because they count in HTML pre tags
+    const res = result.response;
+    const headers = {};
+    for (const [key, val] of res.headers.entries()) {
+        // some headers change on each run, dont report it
+        if (key === 'date') {
+            headers[key] = '<timestamp>';
+        }
+        else if (['cf-ray', 'server-timing'].includes(key)) {
+            headers[key] = '<omitted>';
+        }
+        else {
+            headers[key] = val;
+        }
+    }
+    let text = '', json;
+    try {
+        text = await res.text();
+        json = JSON.parse(text);
+    }
+    catch (_a) {
+        // noop
+    }
+    const stringified = JSON.stringify({
+        status: res.status,
+        statusText: res.statusText,
+        headers,
+        body: json || ((text === null || text === void 0 ? void 0 : text.length) > 5120 ? '<body is too long>' : text) || null,
+    }, (_k, v) => {
+        if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+            // sort object fields for stable stringify
+            const acc = {};
+            return Object.keys(v)
+                .sort()
+                .reverse() // body on bottom
+                .reduce((acc, k) => {
+                acc[k] = v[k];
+                return acc;
+            }, acc);
+        }
+        return v;
+    }, 2);
+    report += stringified + '\n';
+    report += '</code></pre>\n';
+    report += '</details>\n';
+    report += '</li>\n';
+    return report;
+}
+function truncate(str, len = 1024) {
+    if (str.length > len) {
+        return str.substring(0, len) + '...';
+    }
+    return str;
+}

package/lib/handler.d.mts

@@ -3,7 +3,7 @@
  * handler
  *
  */
-import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError } from 'graphql';
+import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, ValidationRule, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError } from 'graphql';
 import { RequestParams } from './common';
 /**
  * The incoming request headers the implementing server should provide.
@@ -137,6 +137,19 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
      * Will not be used when implementing a custom `onSubscribe`.
      */
     validate?: typeof graphqlValidate;
+    /**
+     * The validation rules for running GraphQL validate.
+     *
+     * When providing an array, the rules will be APPENDED to the default
+     * `specifiedRules` array provided by the graphql-js module.
+     *
+     * Alternatively, providing a function instead will OVERWRITE the defaults
+     * and use exclusively the rules returned by the function. The third (last)
+     * argument of the function are the default `specifiedRules` array provided
+     * by the graphql-js module, you're free to prepend/append the defaults to
+     * your rule set, or omit them altogether.
+     */
+    validationRules?: readonly ValidationRule[] | ((req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, specifiedRules: readonly ValidationRule[]) => Promise<readonly ValidationRule[]> | readonly ValidationRule[]);
     /**
      * Is the `execute` function from GraphQL which is
      * used to execute the query and mutation operations.

package/lib/handler.d.ts

@@ -3,7 +3,7 @@
  * handler
  *
  */
-import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError } from 'graphql';
+import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, ValidationRule, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError } from 'graphql';
 import { RequestParams } from './common';
 /**
  * The incoming request headers the implementing server should provide.
@@ -137,6 +137,19 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
      * Will not be used when implementing a custom `onSubscribe`.
      */
     validate?: typeof graphqlValidate;
+    /**
+     * The validation rules for running GraphQL validate.
+     *
+     * When providing an array, the rules will be APPENDED to the default
+     * `specifiedRules` array provided by the graphql-js module.
+     *
+     * Alternatively, providing a function instead will OVERWRITE the defaults
+     * and use exclusively the rules returned by the function. The third (last)
+     * argument of the function are the default `specifiedRules` array provided
+     * by the graphql-js module, you're free to prepend/append the defaults to
+     * your rule set, or omit them altogether.
+     */
+    validationRules?: readonly ValidationRule[] | ((req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, specifiedRules: readonly ValidationRule[]) => Promise<readonly ValidationRule[]> | readonly ValidationRule[]);
     /**
      * Is the `execute` function from GraphQL which is
      * used to execute the query and mutation operations.

package/lib/handler.js

@@ -76,7 +76,7 @@ exports.isResponse = isResponse;
  * @category Server
  */
 function createHandler(options) {
-    const { schema, context, validate = graphql_1.validate, execute = graphql_1.execute, parse = graphql_1.parse, getOperationAST = graphql_1.getOperationAST, rootValue, onSubscribe, onOperation, } = options;
+    const { schema, context, validate = graphql_1.validate, validationRules = [], execute = graphql_1.execute, parse = graphql_1.parse, getOperationAST = graphql_1.getOperationAST, rootValue, onSubscribe, onOperation, } = options;
     return async function handler(req) {
         var _a, _b;
         const method = req.method;
@@ -226,7 +226,14 @@ function createHandler(options) {
             else {
                 args = Object.assign(Object.assign({}, argsWithoutSchema), { schema });
             }
-            const validationErrs = validate(args.schema, args.document);
+            let rules = graphql_1.specifiedRules;
+            if (typeof validationRules === 'function') {
+                rules = await validationRules(req, args, graphql_1.specifiedRules);
+            }
+            else {
+                rules = [...rules, ...validationRules];
+            }
+            const validationErrs = validate(args.schema, args.document, rules);
             if (validationErrs.length) {
                 return makeResponse(validationErrs, acceptedMediaType);
             }

package/lib/handler.mjs

@@ -3,7 +3,7 @@
  * handler
  *
  */
-import { validate as graphqlValidate, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError, } from 'graphql';
+import { validate as graphqlValidate, specifiedRules, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError, } from 'graphql';
 import { areGraphQLErrors, isAsyncIterable, isExecutionResult, isGraphQLError, isObject, } from './utils.mjs';
 /**
  * Checks whether the passed value is the `graphql-http` server agnostic response.
@@ -72,7 +72,7 @@ export function isResponse(val) {
  * @category Server
  */
 export function createHandler(options) {
-    const { schema, context, validate = graphqlValidate, execute = graphqlExecute, parse = graphqlParse, getOperationAST = graphqlGetOperationAST, rootValue, onSubscribe, onOperation, } = options;
+    const { schema, context, validate = graphqlValidate, validationRules = [], execute = graphqlExecute, parse = graphqlParse, getOperationAST = graphqlGetOperationAST, rootValue, onSubscribe, onOperation, } = options;
     return async function handler(req) {
         var _a, _b;
         const method = req.method;
@@ -222,7 +222,14 @@ export function createHandler(options) {
             else {
                 args = Object.assign(Object.assign({}, argsWithoutSchema), { schema });
             }
-            const validationErrs = validate(args.schema, args.document);
+            let rules = specifiedRules;
+            if (typeof validationRules === 'function') {
+                rules = await validationRules(req, args, specifiedRules);
+            }
+            else {
+                rules = [...rules, ...validationRules];
+            }
+            const validationErrs = validate(args.schema, args.document, rules);
             if (validationErrs.length) {
                 return makeResponse(validationErrs, acceptedMediaType);
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphql-http",
-  "version": "1.13.0",
-  "description": "Simple, pluggable, zero-dependency, GraphQL over HTTP Protocol compliant server and client",
+  "version": "1.15.0",
+  "description": "Simple, pluggable, zero-dependency, GraphQL over HTTP spec compliant server, client and audit suite.",
   "keywords": [
     "graphql",
     "client",
@@ -24,7 +24,7 @@
   "engines": {
     "node": ">=12"
   },
-  "packageManager": "yarn@3.3.1",
+  "packageManager": "yarn@3.4.1",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
   "browser": "umd/graphql-http.js",
@@ -84,7 +84,7 @@
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "build:esm": "tsc -b tsconfig.esm.json && node scripts/esm-post-process.mjs",
     "build:cjs": "tsc -b tsconfig.cjs.json",
-    "build:umd": "rollup --bundleConfigAsCjs --config rollup.config.ts --configPlugin typescript && gzip umd/graphql-http.min.js -c > umd/graphql-http.min.js.gz",
+    "build:umd": "rollup --configPlugin typescript --config rollup.config.ts",
     "build": "yarn build:esm && yarn build:cjs && yarn build:umd",
     "release": "semantic-release"
   },
@@ -106,33 +106,36 @@
     "@rollup/plugin-typescript": "^11.0.0",
     "@semantic-release/changelog": "^6.0.2",
     "@semantic-release/git": "^10.0.1",
-    "@types/eslint": "^8.4.10",
-    "@types/express": "^4.17.16",
+    "@types/eslint": "^8.21.0",
+    "@types/express": "^4.17.17",
     "@types/glob": "^8.0.1",
+    "@types/html-validator": "^5.0.3",
     "@types/jest": "^29.4.0",
     "@types/koa": "^2.13.5",
     "@types/koa-mount": "^4.0.2",
-    "@typescript-eslint/eslint-plugin": "^5.49.0",
-    "@typescript-eslint/parser": "^5.49.0",
-    "@whatwg-node/fetch": "^0.6.2",
-    "babel-jest": "^29.4.0",
-    "eslint": "^8.32.0",
+    "@typescript-eslint/eslint-plugin": "^5.51.0",
+    "@typescript-eslint/parser": "^5.51.0",
+    "@whatwg-node/fetch": "^0.8.1",
+    "babel-jest": "^29.4.2",
+    "eslint": "^8.34.0",
     "eslint-config-prettier": "^8.6.0",
     "express": "^4.18.2",
-    "fastify": "^4.12.0",
+    "fastify": "^4.13.0",
     "graphql": "^16.6.0",
-    "jest": "^29.4.0",
-    "jest-jasmine2": "^29.4.0",
+    "html-validator": "^6.0.1",
+    "jest": "^29.4.2",
+    "jest-jasmine2": "^29.4.2",
     "koa": "^2.14.1",
     "koa-mount": "^4.0.0",
     "node-fetch": "^3.3.0",
-    "prettier": "^2.8.3",
-    "rollup": "^3.11.0",
+    "prettier": "^2.8.4",
+    "rollup": "^3.15.0",
+    "rollup-plugin-gzip": "^3.1.0",
     "semantic-release": "^20.1.0",
-    "tslib": "^2.4.1",
-    "typedoc": "^0.23.24",
+    "tslib": "^2.5.0",
+    "typedoc": "^0.23.25",
     "typedoc-plugin-markdown": "^3.14.0",
-    "typescript": "^4.9.4"
+    "typescript": "^4.9.5"
   },
   "resolutions": {
     "npm/libnpmversion": "^3.0.6"