graphql-http 1.4.0 → 1.5.0

package/lib/audits/server.mjs

@@ -0,0 +1,395 @@
+/**
+ *
+ * audit/server
+ *
+ */
+import { assert, audit, extendedTypeof } from './utils.mjs';
+/**
+ * List of server audits required to check GraphQL over HTTP spec conformance.
+ *
+ * @category Audits
+ */
+export function serverAudits(opts) {
+    const fetchFn = (opts.fetchFn || fetch);
+    return [
+        // Media Types
+        audit('MUST accept application/graphql-response+json and match the content-type', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    accept: 'application/graphql-response+json',
+                },
+            });
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('application/graphql-response+json');
+        }),
+        audit('MUST accept application/json and match the content-type', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    accept: 'application/json',
+                },
+            });
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('application/json');
+        }),
+        audit('MUST accept */* and use application/graphql-response+json for the content-type', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    accept: '*/*',
+                },
+            });
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('application/graphql-response+json');
+        }),
+        audit('MUST assume application/graphql-response+json content-type when accept is missing', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString());
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('application/graphql-response+json');
+        }),
+        audit('MUST use utf-8 charset in response', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString());
+            assert('Status code', res.status).toBe(200);
+            assert('Content-Type header', res.headers.get('content-type')).toContain('charset=utf-8');
+        }),
+        audit('MUST accept only utf-8 charset', 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',
+                },
+            });
+            assert('Status code', res.status).toBe(406);
+            assert('Accept header', res.headers.get('accept')).toContain('charset=utf-8');
+        }),
+        // Request
+        audit('MUST accept POST requests', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ query: '{ __typename }' }),
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        audit('MAY accept application/x-www-form-urlencoded formatted GET requests', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ __typename }');
+            const res = await fetchFn(url.toString());
+            assert('Status code', res.status).toBe(200);
+        }),
+        // Request GET
+        audit('MUST NOT allow executing mutations on GET requests', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', 'mutation { __typename }');
+            const res = await fetchFn(url.toString(), {
+                headers: {
+                    accept: 'application/graphql-response+json',
+                },
+            });
+            assert('Status code', res.status).toBe(405);
+        }),
+        // Request POST
+        audit('SHOULD respond with 4xx status code if content-type is not supplied on POST requests', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+            });
+            assert('Status code', res.status).toBeGreaterThanOrEqual(400);
+            assert('Status code', res.status).toBeLessThanOrEqual(599);
+        }),
+        audit('MUST accept application/json POST requests', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ query: '{ __typename }' }),
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        audit('MUST require a request body on POST', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        // Request Parameters
+        audit('MUST require the {query} parameter', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({ notquery: '{ __typename }' }),
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        ...[{ obj: 'ect' }, 0, false, ['array']].map((invalid) => audit(`MUST NOT allow ${extendedTypeof(invalid)} for the {query} parameter`, async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: invalid,
+                }),
+            });
+            assert('Status code', res.status).toBe(400);
+        })),
+        audit('MUST accept a string for the {query} parameter', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: '{ __typename }',
+                }),
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        ...[{ obj: 'ect' }, 0, false, ['array']].map((invalid) => audit(`MUST NOT allow ${extendedTypeof(invalid)} for the {operationName} parameter`, async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    operationName: invalid,
+                    query: '{ __typename }',
+                }),
+            });
+            assert('Status code', res.status).toBe(400);
+        })),
+        audit('MUST accept a string for the {operationName} parameter', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    operationName: 'Query',
+                    query: 'query Query { __typename }',
+                }),
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        ...['string', 0, false, ['array']].map((invalid) => audit(`MUST NOT allow ${extendedTypeof(invalid)} for the {variables} parameter`, async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: '{ __typename }',
+                    variables: invalid,
+                }),
+            });
+            assert('Status code', res.status).toBe(400);
+        })),
+        audit('MUST accept a map for the {variables} parameter', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: 'query Type($name: String!) { __type(name: $name) { name } }',
+                    variables: { name: 'sometype' },
+                }),
+            });
+            assert('Status code', res.status).toBe(200);
+            const result = (await res.json());
+            assert('Execution result', result).notToHaveProperty('errors');
+        }),
+        audit('MUST accept a URL-encoded JSON string for the {variables} parameter in GETs', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', 'query Type($name: String!) { __type(name: $name) { name } }');
+            url.searchParams.set('variables', JSON.stringify({ name: 'sometype' }));
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+            });
+            assert('Status code', res.status).toBe(200);
+            const result = (await res.json());
+            assert('Execution result', result).notToHaveProperty('errors');
+        }),
+        ...['string', 0, false, ['array']].map((invalid) => audit(`MUST NOT allow ${extendedTypeof(invalid)} for the {extensions} parameter`, async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: '{ __typename }',
+                    extensions: invalid,
+                }),
+            });
+            assert('Status code', res.status).toBe(400);
+        })),
+        audit('MUST accept a map for the {extensions} parameter', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: JSON.stringify({
+                    query: '{ __typename }',
+                    extensions: { some: 'value' },
+                }),
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        // TODO: audit('MUST accept a map for the {extensions} parameter'),
+        // Response application/json
+        audit('SHOULD use 200 status code on JSON parsing failure when accepting application/json', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                },
+                body: '{ "not a JSON',
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        audit('SHOULD use 200 status code if parameters are invalid when accepting application/json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('qeury' /* typo */, '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/json' },
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        audit('SHOULD use 200 status code on document parsing failure when accepting application/json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/json' },
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        audit('SHOULD use 200 status code on document validation failure when accepting application/json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ 8f31403dfe404bccbb0e835f2629c6a7 }'); // making sure the field doesnt exist
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/json' },
+            });
+            assert('Status code', res.status).toBe(200);
+        }),
+        // Response application/graphql-response+json
+        audit('MUST use 4xx or 5xx status codes on JSON parsing failure when accepting application/graphql-response+json', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: '{ "not a JSON',
+            });
+            assert('Status code', res.status).toBeGreaterThanOrEqual(400);
+            assert('Status code', res.status).toBeLessThanOrEqual(599);
+        }),
+        audit('SHOULD use 400 status code on JSON parsing failure when accepting application/graphql-response+json', async () => {
+            const res = await fetchFn(opts.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/graphql-response+json',
+                },
+                body: '{ "not a JSON',
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        audit('MUST use 4xx or 5xx status codes if parameters are invalid when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('qeury' /* typo */, '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBeGreaterThanOrEqual(400);
+            assert('Status code', res.status).toBeLessThanOrEqual(599);
+        }),
+        audit('SHOULD use 400 status code if parameters are invalid when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('qeury' /* typo */, '{ __typename }');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        audit('MUST use 4xx or 5xx status codes on document parsing failure when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBeGreaterThanOrEqual(400);
+            assert('Status code', res.status).toBeLessThanOrEqual(599);
+        }),
+        audit('SHOULD use 400 status code on document parsing failure when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{');
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        audit('MUST use 4xx or 5xx status codes on document validation failure when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ 8f31403dfe404bccbb0e835f2629c6a7 }'); // making sure the field doesnt exist
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBeGreaterThanOrEqual(400);
+            assert('Status code', res.status).toBeLessThanOrEqual(599);
+        }),
+        audit('SHOULD use 400 status code on document validation failure when accepting application/graphql-response+json', async () => {
+            const url = new URL(opts.url);
+            url.searchParams.set('query', '{ 8f31403dfe404bccbb0e835f2629c6a7 }'); // making sure the field doesnt exist
+            const res = await fetchFn(url.toString(), {
+                method: 'GET',
+                headers: { accept: 'application/graphql-response+json' },
+            });
+            assert('Status code', res.status).toBe(400);
+        }),
+        // TODO: how to make an unauthorized request?
+        // https://graphql.github.io/graphql-over-http/draft/#sel-EANNNDTAAEVBAAqqc
+        // audit('SHOULD use 401 or 403 status codes when the request is not permitted')
+    ];
+}
+/**
+ * Performs the full list of server audits required for GraphQL over HTTP spec conformance.
+ *
+ * Please consult the `AuditResult` for more information.
+ *
+ * @category Audits
+ */
+export async function auditServer(opts) {
+    const audits = serverAudits(opts);
+    // audit tests will throw only on fatal errors, tests are contained within the AuditResult
+    return await Promise.all(audits.map(({ fn }) => fn()));
+}

package/lib/audits/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ *
+ * audit/utils
+ *
+ */
+import { Audit, AuditName } from './common';
+export * from '../utils';
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+export declare function audit(name: AuditName, fn: () => Promise<void>): Audit;
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+export declare function assert<T = unknown>(name: string, actual: T): {
+    toBe: (expected: T) => void;
+    toBeLessThanOrEqual: (expected: T extends number ? T : never) => void;
+    toBeGreaterThanOrEqual: (expected: T extends number ? T : never) => void;
+    toContain: (expected: T extends (infer U)[] ? U : T extends string ? T : never) => void;
+    notToHaveProperty: (prop: T extends Record<any, any> ? PropertyKey : never) => void;
+};

package/lib/audits/utils.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ *
+ * audit/utils
+ *
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assert = exports.audit = void 0;
+__exportStar(require("../utils"), exports);
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+function audit(name, fn) {
+    return {
+        name,
+        fn: async () => {
+            try {
+                await fn();
+                return {
+                    name,
+                    status: 'ok',
+                };
+            }
+            catch (errOrReason) {
+                if (typeof errOrReason !== 'string') {
+                    // anything thrown that is not an assertion string is considered fatal
+                    throw errOrReason;
+                }
+                return {
+                    name,
+                    status: name.startsWith('MUST')
+                        ? // only failing MUSTs are considered errors
+                            'error'
+                        : // everything else is optional and considered a warning
+                            'warn',
+                    reason: errOrReason,
+                };
+            }
+        },
+    };
+}
+exports.audit = audit;
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+function assert(name, actual) {
+    return {
+        toBe: (expected) => {
+            if (actual !== expected) {
+                throw `${name} ${actual} is not ${expected}`;
+            }
+        },
+        toBeLessThanOrEqual: (expected) => {
+            if (!(actual <= expected)) {
+                throw `${name} ${actual} is not less than or equal to ${expected}`;
+            }
+        },
+        toBeGreaterThanOrEqual: (expected) => {
+            if (!(actual >= expected)) {
+                throw `${name} ${actual} is not greater than or equal to ${expected}`;
+            }
+        },
+        toContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (!actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} does not contain ${JSON.stringify(expected)}`;
+            }
+        },
+        notToHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (prop in actual) {
+                throw `${name} ${JSON.stringify(actual)} does have a property '${String(prop)}'`;
+            }
+        },
+    };
+}
+exports.assert = assert;

package/lib/audits/utils.mjs

@@ -0,0 +1,81 @@
+/**
+ *
+ * audit/utils
+ *
+ */
+export * from '../utils.mjs';
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+export function audit(name, fn) {
+    return {
+        name,
+        fn: async () => {
+            try {
+                await fn();
+                return {
+                    name,
+                    status: 'ok',
+                };
+            }
+            catch (errOrReason) {
+                if (typeof errOrReason !== 'string') {
+                    // anything thrown that is not an assertion string is considered fatal
+                    throw errOrReason;
+                }
+                return {
+                    name,
+                    status: name.startsWith('MUST')
+                        ? // only failing MUSTs are considered errors
+                            'error'
+                        : // everything else is optional and considered a warning
+                            'warn',
+                    reason: errOrReason,
+                };
+            }
+        },
+    };
+}
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+export function assert(name, actual) {
+    return {
+        toBe: (expected) => {
+            if (actual !== expected) {
+                throw `${name} ${actual} is not ${expected}`;
+            }
+        },
+        toBeLessThanOrEqual: (expected) => {
+            if (!(actual <= expected)) {
+                throw `${name} ${actual} is not less than or equal to ${expected}`;
+            }
+        },
+        toBeGreaterThanOrEqual: (expected) => {
+            if (!(actual >= expected)) {
+                throw `${name} ${actual} is not greater than or equal to ${expected}`;
+            }
+        },
+        toContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (!actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} does not contain ${JSON.stringify(expected)}`;
+            }
+        },
+        notToHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (prop in actual) {
+                throw `${name} ${JSON.stringify(actual)} does have a property '${String(prop)}'`;
+            }
+        },
+    };
+}

package/lib/handler.d.ts

@@ -238,7 +238,7 @@ export declare type Handler<RawRequest = unknown, Context = unknown> = (req: Req
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/handler.js

@@ -55,7 +55,7 @@ exports.isResponse = isResponse;
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/handler.mjs

@@ -51,7 +51,7 @@ export function isResponse(val) {
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './common';
 export * from './handler';
 export * from './client';
+export * from './audits';

package/lib/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./common"), exports);
 __exportStar(require("./handler"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./audits"), exports);

package/lib/index.mjs

@@ -1,3 +1,4 @@
 export * from './common.mjs';
 export * from './handler.mjs';
 export * from './client.mjs';
+export * from './audits.mjs';

package/lib/utils.d.ts

@@ -5,6 +5,8 @@
  */
 import type { ExecutionResult, GraphQLError } from 'graphql';
 /** @private */
+export declare function extendedTypeof(val: unknown): 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'array' | 'null';
+/** @private */
 export declare function isObject(val: unknown): val is Record<PropertyKey, any>;
 /** @private */
 export declare function areGraphQLErrors(obj: unknown): obj is readonly GraphQLError[];