feat(server): Audits and test function (#4)

Author: enisdenjo

README.md

@@ -709,6 +709,32 @@ console.log('Listening to port 4000');
 
 </details>
 
+<details id="audit-jest">
+<summary><a href="#audit-jest">🔗</a> Audit for servers usage in <a href="https://jestjs.io">Jest</a> environment</summary>
+
+```js
+import { fetch } from '@whatwg-node/fetch';
+import { serverAudits } from 'graphql-http';
+
+for (const audit of serverAudits({
+  url: 'http://localhost:4000/graphql',
+  fetchFn: fetch,
+})) {
+  test(audit.name, async () => {
+    const result = await audit.fn();
+    if (result.status === 'error') {
+      throw result.reason;
+    }
+    if (result.status === 'warn') {
+      console.warn(result.reason); // or throw if you want full compliance (warnings are not requirements)
+    }
+    // result.status === 'ok'
+  });
+}
+```
+
+</details>
+
 ## [Documentation](docs/)
 
 Check the [docs folder](docs/) out for [TypeDoc](https://typedoc.org) generated documentation.

docs/README.md

@@ -10,6 +10,9 @@ graphql-http
 
 ### Interfaces
 
+- [Audit](interfaces/Audit.md)
+- [AuditFail](interfaces/AuditFail.md)
+- [AuditOk](interfaces/AuditOk.md)
 - [Client](interfaces/Client.md)
 - [ClientOptions](interfaces/ClientOptions.md)
 - [HandlerOptions](interfaces/HandlerOptions.md)
@@ -18,11 +21,15 @@ graphql-http
 - [RequestParams](interfaces/RequestParams.md)
 - [ResponseInit](interfaces/ResponseInit.md)
 - [ResponseLike](interfaces/ResponseLike.md)
+- [ServerAuditOptions](interfaces/ServerAuditOptions.md)
 - [Sink](interfaces/Sink.md)
 
 ### Type Aliases
 
 - [AcceptableMediaType](README.md#acceptablemediatype)
+- [AuditName](README.md#auditname)
+- [AuditRequirement](README.md#auditrequirement)
+- [AuditResult](README.md#auditresult)
 - [ExecutionContext](README.md#executioncontext)
 - [Handler](README.md#handler)
 - [Response](README.md#response)
@@ -31,11 +38,75 @@ graphql-http
 
 ### Functions
 
+- [auditServer](README.md#auditserver)
 - [createClient](README.md#createclient)
 - [createHandler](README.md#createhandler)
 - [getAcceptableMediaType](README.md#getacceptablemediatype)
 - [isResponse](README.md#isresponse)
 - [makeResponse](README.md#makeresponse)
+- [serverAudits](README.md#serveraudits)
+
+## Audits
+
+### AuditName
+
+Ƭ **AuditName**: \`${AuditRequirement} ${string}\`
+
+Audit name starting with the audit requirement level.
+
+___
+
+### AuditRequirement
+
+Ƭ **AuditRequirement**: ``"MUST"`` \| ``"SHOULD"`` \| ``"MAY"``
+
+Audit requirement levels as per [RFC2119](https://www.rfc-editor.org/rfc/rfc2119).
+
+___
+
+### AuditResult
+
+Ƭ **AuditResult**: [`AuditOk`](interfaces/AuditOk.md) \| [`AuditFail`](interfaces/AuditFail.md)
+
+Result of the performed audit. See `AuditOk` and `AuditFail` for more information.
+
+___
+
+### auditServer
+
+▸ **auditServer**(`opts`): `Promise`<[`AuditResult`](README.md#auditresult)[]\>
+
+Performs the full list of server audits required for GraphQL over HTTP spec conformance.
+
+Please consult the `AuditResult` for more information.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `opts` | [`ServerAuditOptions`](interfaces/ServerAuditOptions.md) |
+
+#### Returns
+
+`Promise`<[`AuditResult`](README.md#auditresult)[]\>
+
+___
+
+### serverAudits
+
+▸ **serverAudits**(`opts`): [`Audit`](interfaces/Audit.md)[]
+
+List of server audits required to check GraphQL over HTTP spec conformance.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `opts` | [`ServerAuditOptions`](interfaces/ServerAuditOptions.md) |
+
+#### Returns
+
+[`Audit`](interfaces/Audit.md)[]
 
 ## Client
 

docs/interfaces/Audit.md

@@ -0,0 +1,34 @@
+[graphql-http](../README.md) / Audit
+
+# Interface: Audit
+
+Actual audit test returning an result.
+
+The test function will throw only if the error is fatal.
+
+## Table of contents
+
+### Properties
+
+- [fn](Audit.md#fn)
+- [name](Audit.md#name)
+
+## Properties
+
+### fn
+
+• **fn**: () => `Promise`<[`AuditResult`](../README.md#auditresult)\>
+
+#### Type declaration
+
+▸ (): `Promise`<[`AuditResult`](../README.md#auditresult)\>
+
+##### Returns
+
+`Promise`<[`AuditResult`](../README.md#auditresult)\>
+
+___
+
+### name
+
+• **name**: \`MUST ${string}\` \| \`SHOULD ${string}\` \| \`MAY ${string}\`

docs/interfaces/AuditFail.md

@@ -0,0 +1,36 @@
+[graphql-http](../README.md) / AuditFail
+
+# Interface: AuditFail
+
+Indicates that the audit failed.
+
+If the status is `warn`, the audit is not a requirement but rather a recommendation.
+
+On the other hand, if the status is `error`, the audit is a requirement and the source
+is therefore not compliant.
+
+## Table of contents
+
+### Properties
+
+- [name](AuditFail.md#name)
+- [reason](AuditFail.md#reason)
+- [status](AuditFail.md#status)
+
+## Properties
+
+### name
+
+• **name**: \`MUST ${string}\` \| \`SHOULD ${string}\` \| \`MAY ${string}\`
+
+___
+
+### reason
+
+• **reason**: `string`
+
+___
+
+### status
+
+• **status**: ``"warn"`` \| ``"error"``

docs/interfaces/AuditOk.md

@@ -0,0 +1,24 @@
+[graphql-http](../README.md) / AuditOk
+
+# Interface: AuditOk
+
+Indicates that the audit was successful.
+
+## Table of contents
+
+### Properties
+
+- [name](AuditOk.md#name)
+- [status](AuditOk.md#status)
+
+## Properties
+
+### name
+
+• **name**: \`MUST ${string}\` \| \`SHOULD ${string}\` \| \`MAY ${string}\`
+
+___
+
+### status
+
+• **status**: ``"ok"``

docs/interfaces/ServerAuditOptions.md

@@ -0,0 +1,34 @@
+[graphql-http](../README.md) / ServerAuditOptions
+
+# Interface: ServerAuditOptions
+
+Options for server audits required to check GraphQL over HTTP spec conformance.
+
+## Table of contents
+
+### Properties
+
+- [fetchFn](ServerAuditOptions.md#fetchfn)
+- [url](ServerAuditOptions.md#url)
+
+## Properties
+
+### fetchFn
+
+• `Optional` **fetchFn**: `unknown`
+
+The Fetch function to use.
+
+For NodeJS environments consider using [`@whatwg-node/fetch`](https://github.com/ardatan/whatwg-node/tree/master/packages/fetch).
+
+**`Default`**
+
+global.fetch
+
+___
+
+### url
+
+• **url**: `string`
+
+The URL of the GraphQL server for the audit.