feat: Added response validation.

Author: Shogun

package.json

@@ -14,7 +14,6 @@
   },
   "author": "Shogun <shogun@cowtech.it>",
   "license": "ISC",
-  "private": false,
   "files": [
     "lib",
     "types",
@@ -35,22 +34,25 @@
     "postpublish": "git push origin && git push origin -f --tags"
   },
   "dependencies": {
+    "ajv": "^6.10.2",
     "fastify-plugin": "^1.6.0",
     "http-errors": "^1.7.3",
     "http-status-codes": "^1.4.0",
     "lodash.get": "^4.4.2",
+    "lodash.upperfirst": "^4.3.1",
     "statuses": "^1.5.0"
   },
   "devDependencies": {
     "@cowtech/tslint-config": "^5.13.0",
     "@types/http-errors": "^1.6.2",
     "@types/jest": "^24.0.23",
     "@types/lodash.get": "^4.4.6",
+    "@types/lodash.upperfirst": "^4.3.6",
     "@types/node": "^12.12.8",
     "@types/statuses": "^1.5.0",
-    "ajv": "^6.10.2",
     "fastify": "^2.10.0",
     "jest": "^24.9.0",
+    "jest-additional-expectations": "^0.1.0",
     "prettier": "^1.19.1",
     "ts-jest": "^24.1.0",
     "tslint": "^5.20.1",

src/index.ts

@@ -1,21 +1,18 @@
+import Ajv from 'ajv'
 import { FastifyError, FastifyInstance, FastifyReply, FastifyRequest, RegisterOptions } from 'fastify'
 import fastifyPlugin from 'fastify-plugin'
 import { IncomingMessage, Server, ServerResponse } from 'http'
 import createError, { HttpError, InternalServerError, NotFound } from 'http-errors'
-import { BAD_REQUEST, INTERNAL_SERVER_ERROR } from 'http-status-codes'
+import { BAD_REQUEST, INTERNAL_SERVER_ERROR, UNSUPPORTED_MEDIA_TYPE } from 'http-status-codes'
+import upperFirst from 'lodash.upperfirst'
 import statuses from 'statuses'
-import { addAdditionalProperties, GenericObject, NodeError, serializeError } from './properties'
-import { convertValidationErrors, RequestSection } from './validation'
+import { FastifyDecoratedRequest, GenericObject, NodeError, RequestSection } from './interfaces'
+import { addAdditionalProperties, serializeError } from './properties'
+import { addResponseValidation, convertValidationErrors, validationMessagesFormatters } from './validation'
 
-export { addAdditionalProperties, GenericObject } from './properties'
-export { convertValidationErrors, niceJoin, validationMessages, validationMessagesFormatters } from './validation'
-
-export interface FastifyDecoratedRequest extends FastifyRequest {
-  errorProperties?: {
-    hideUnhandledErrors?: boolean
-    convertValidationErrors?: boolean
-  }
-}
+export * from './interfaces'
+export { addAdditionalProperties } from './properties'
+export { convertValidationErrors, niceJoin, validationMessagesFormatters } from './validation'
 
 export function handleNotFoundError(request: FastifyRequest, reply: FastifyReply<unknown>): void {
   handleErrors(new NotFound('Not found.'), request, reply)
@@ -44,9 +41,11 @@ export function handleErrors(
   reply: FastifyReply<unknown>
 ): void {
   // It is a generic error, handle it
+  const code = (error as NodeError).code
+
   if (!('statusCode' in (error as HttpError))) {
-    // If it is a validation error, convert errors to human friendly format
     if ('validation' in error && request.errorProperties?.convertValidationErrors) {
+      // If it is a validation error, convert errors to human friendly format
       error = handleValidationError(error, request)
     } else if (request.errorProperties?.hideUnhandledErrors) {
       // It is requested to hide the error, just log it and then create a generic one
@@ -57,6 +56,12 @@ export function handleErrors(
       error = Object.assign(new InternalServerError(error.message), serializeError(error))
       Object.defineProperty(error, 'stack', { enumerable: true })
     }
+  } else if (code === 'INVALID_CONTENT_TYPE' || code === 'FST_ERR_CTP_INVALID_MEDIA_TYPE') {
+    error = createError(UNSUPPORTED_MEDIA_TYPE, upperFirst(validationMessagesFormatters.contentType()))
+  } else if (code === 'FST_ERR_CTP_EMPTY_JSON_BODY') {
+    error = createError(BAD_REQUEST, upperFirst(validationMessagesFormatters.jsonEmpty()))
+  } else if (code === 'MALFORMED_JSON' || error.message === 'Invalid JSON' || error.stack!.includes('at JSON.parse')) {
+    error = createError(BAD_REQUEST, upperFirst(validationMessagesFormatters.json()))
   }
 
   // Get the status code
@@ -91,13 +96,31 @@ export default fastifyPlugin(
     options: RegisterOptions<S, I, R>,
     done: () => void
   ): void {
-    const hideUnhandledErrors = options.hideUnhandledErrors ?? process.env.NODE_ENV === 'production'
+    const isProduction = process.env.NODE_ENV === 'production'
+    const hideUnhandledErrors = options.hideUnhandledErrors ?? isProduction
     const convertValidationErrors = options.convertValidationErrors ?? true
+    const convertResponsesValidationErrors = options.convertResponsesValidationErrors ?? !isProduction
 
     instance.decorateRequest('errorProperties', { hideUnhandledErrors, convertValidationErrors })
     instance.setErrorHandler(handleErrors)
     instance.setNotFoundHandler(handleNotFoundError)
 
+    if (convertResponsesValidationErrors) {
+      instance.decorate(
+        'responseValidatorSchemaCompiler',
+        new Ajv({
+          // The fastify defaults, with the exception of removeAdditional and coerceTypes, which have been reversed
+          removeAdditional: false,
+          useDefaults: true,
+          coerceTypes: false,
+          allErrors: true,
+          nullable: true
+        })
+      )
+
+      instance.addHook('onRoute', addResponseValidation)
+    }
+
     done()
   },
   { name: 'fastify-errors-properties' }

src/interfaces.ts

@@ -0,0 +1,37 @@
+import { Ajv, ValidateFunction } from 'ajv'
+import { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { ServerResponse } from 'http'
+
+export type GenericObject = { [key: string]: any }
+export type NodeError = NodeJS.ErrnoException
+
+export type RequestSection = 'params' | 'query' | 'querystring' | 'headers' | 'body' | 'response'
+
+export interface ResponseSchemas {
+  [key: string]: ValidateFunction
+}
+
+export interface FastifyDecoratedInstance extends FastifyInstance {
+  responseValidatorSchemaCompiler: Ajv
+}
+
+export interface FastifyDecoratedRequest extends FastifyRequest {
+  errorProperties?: {
+    hideUnhandledErrors?: boolean
+    convertValidationErrors?: boolean
+  }
+}
+
+export interface FastifyDecoratedReply extends FastifyReply<ServerResponse> {
+  originalResponse?: {
+    statusCode: number
+    payload: any
+  }
+}
+export interface Validations {
+  [key: string]: {
+    [key: string]: string
+  }
+}
+
+export type ValidationFormatter = (...args: Array<any>) => string

src/properties.ts

@@ -1,7 +1,6 @@
-const processRoot = process.cwd()
+import { GenericObject, NodeError } from './interfaces'
 
-export type GenericObject = { [key: string]: any }
-export type NodeError = NodeJS.ErrnoException
+const processRoot = process.cwd()
 
 export function addAdditionalProperties(target: GenericObject, source: GenericObject): void {
   for (const v in source) {

src/validation.ts

@@ -1,16 +1,16 @@
-import { ValidationResult } from 'fastify'
+import { FastifyInstance, FastifyRequest, RouteOptions, ValidationResult } from 'fastify'
+import createError from 'http-errors'
+import { INTERNAL_SERVER_ERROR } from 'http-status-codes'
+import {
+  FastifyDecoratedInstance,
+  FastifyDecoratedReply,
+  RequestSection,
+  ResponseSchemas,
+  ValidationFormatter,
+  Validations
+} from './interfaces'
 import get = require('lodash.get')
 
-export type RequestSection = 'params' | 'query' | 'querystring' | 'headers' | 'body'
-
-export interface Validations {
-  [key: string]: {
-    [key: string]: string
-  }
-}
-
-export type validationFormatter = (...args: Array<any>) => string
-
 export function niceJoin(array: Array<string>, lastSeparator: string = ' and ', separator: string = ', '): string {
   switch (array.length) {
     case 0:
@@ -24,7 +24,37 @@ export function niceJoin(array: Array<string>, lastSeparator: string = ' and ',
   }
 }
 
-export const validationMessagesFormatters: { [key: string]: validationFormatter } = {
+export const validationMessagesFormatters: { [key: string]: ValidationFormatter } = {
+  contentType: () =>
+    'only JSON payloads are accepted. Please set the "Content-Type" header to start with "application/json"',
+  json: () => 'the body payload is not a valid JSON',
+  jsonEmpty: () => 'the JSON body payload cannot be empty if the "Content-Type" header is set',
+  missing: () => 'must be present',
+  unknown: () => 'is not a valid property',
+  uuid: () => 'must be a valid GUID (UUID v4)',
+  timestamp: () => 'must be a valid ISO 8601 / RFC 3339 timestamp (example: 2018-07-06T12:34:56Z)',
+  date: () => 'must be a valid ISO 8601 / RFC 3339 date (example: 2018-07-06)',
+  time: () => 'must be a valid ISO 8601 / RFC 3339 time (example: 12:34:56)',
+  hostname: () => 'must be a valid hostname',
+  ipv4: () => 'must be a valid IPv4',
+  ipv6: () => 'must be a valid IPv6',
+  paramType: (type: string) => {
+    switch (type) {
+      case 'integer':
+        return 'must be a valid integer number'
+      case 'number':
+        return 'must be a valid number'
+      case 'boolean':
+        return 'must be a valid boolean (true or false)'
+      case 'object':
+        return 'must be a object'
+      case 'array':
+        return 'must be an array'
+      default:
+        return 'must be a string'
+    }
+  },
+  presentString: () => 'must be a non empty string',
   minimum: (min: number) => `must be a number greater than or equal to ${min}`,
   maximum: (max: number) => `must be a number less than or equal to ${max}`,
   minimumProperties(min: number): string {
@@ -47,31 +77,8 @@ export const validationMessagesFormatters: { [key: string]: validationFormatter
   pattern: (pattern: string) => `must match pattern "${pattern.replace(/\(\?\:/g, '(')}"`,
   invalidResponseCode: (code: number) => `This endpoint cannot respond with HTTP status ${code}.`,
   invalidResponse: (code: number) =>
-    `The response returned from the endpoint violates its specification for the HTTP status ${code}.`
-}
-
-export const validationMessages: { [key: string]: string } = {
-  contentType: 'only JSON payloads are accepted. Please set the "Content-Type" header to start with "application/json"',
-  json: 'the body payload is not a valid JSON',
-  jsonEmpty: 'the JSON body payload cannot be empty if the "Content-Type" header is set',
-  missing: 'must be present',
-  unknown: 'is not a valid property',
-  emptyObject: 'cannot be a empty object',
-  uuid: 'must be a valid GUID (UUID v4)',
-  timestamp: 'must be a valid ISO 8601 / RFC 3339 timestamp (example: 2018-07-06T12:34:56Z)',
-  date: 'must be a valid ISO 8601 / RFC 3339 date (example: 2018-07-06)',
-  time: 'must be a valid ISO 8601 / RFC 3339 time (example: 12:34:56)',
-  hostname: 'must be a valid hostname',
-  ip: 'must be a valid IPv4 or IPv6',
-  ipv4: 'must be a valid IPv4',
-  ipv6: 'must be a valid IPv6',
-  integer: 'must be a valid integer number',
-  number: 'must be a valid number',
-  boolean: 'must be a valid boolean (true or false)',
-  object: 'must be a object',
-  array: 'must be an array',
-  string: 'must be a string',
-  presentString: 'must be a non empty string'
+    `The response returned from the endpoint violates its specification for the HTTP status ${code}.`,
+  invalidFormat: (format: string) => `must match format "${format}" (format)`
 }
 
 export function convertValidationErrors(
@@ -105,15 +112,15 @@ export function convertValidationErrors(
       case 'required':
       case 'dependencies':
         key = e.params.missingProperty
-        message = validationMessages.missing
+        message = validationMessagesFormatters.missing()
         break
       case 'additionalProperties':
         key = e.params.additionalProperty
 
-        message = validationMessages.unknown
+        message = validationMessagesFormatters.unknown()
         break
       case 'type':
-        message = validationMessages[e.params.type]
+        message = validationMessagesFormatters.paramType(e.params.type)
         break
       case 'minProperties':
         message = validationMessagesFormatters.minimumProperties(e.params.limit)
@@ -141,7 +148,7 @@ export function convertValidationErrors(
         const value = get(data, key) as string
 
         if (pattern === '.+' && !value) {
-          message = validationMessages.presentString
+          message = validationMessagesFormatters.presentString()
         } else {
           message = validationMessagesFormatters.pattern(e.params.pattern)
         }
@@ -155,9 +162,7 @@ export function convertValidationErrors(
           reason = 'timestamp'
         }
 
-        message = validationMessagesFormatters[reason]
-          ? validationMessagesFormatters[reason](reason)
-          : validationMessages[reason]
+        message = (validationMessagesFormatters[reason] || validationMessagesFormatters.invalidFormat)(reason)
 
         break
     }
@@ -187,3 +192,51 @@ export function convertValidationErrors(
 
   return { [section]: errors }
 }
+
+export function addResponseValidation(this: FastifyDecoratedInstance, route: RouteOptions): void {
+  if (!route.schema?.response) {
+    return
+  }
+
+  const validators = Object.entries(route.schema.response).reduce<ResponseSchemas>(
+    (accu: ResponseSchemas, [code, schema]: [string, object]) => {
+      accu[code] = this.responseValidatorSchemaCompiler.compile(schema)
+
+      return accu
+    },
+    {} as ResponseSchemas
+  )
+
+  // Note that this hook is not called for non JSON payloads therefore validation is not possible in such cases
+  route.preSerialization = async function(
+    this: FastifyInstance,
+    _request: FastifyRequest,
+    reply: FastifyDecoratedReply,
+    payload: any
+  ): Promise<any> {
+    const statusCode = reply.res.statusCode
+
+    // Never validate error 500
+    if (statusCode === 500) {
+      return payload
+    }
+
+    // No validator, it means the HTTP status is not allowed
+    const validator = validators[statusCode]
+
+    if (!validator) {
+      throw createError(INTERNAL_SERVER_ERROR, validationMessagesFormatters.invalidResponseCode(statusCode))
+    }
+
+    // Now validate the payload
+    const valid = validator(payload)
+
+    if (!valid) {
+      throw createError(INTERNAL_SERVER_ERROR, validationMessagesFormatters.invalidResponse(statusCode), {
+        failedValidations: convertValidationErrors('response', payload, validator.errors as Array<ValidationResult>)
+      })
+    }
+
+    return payload
+  }
+}