fastify 2.10.0 → 2.13.0

package/docs/Server.md

@@ -75,7 +75,7 @@ Defines the maximum payload, in bytes, the server is allowed to accept.
 
 Defines what action the framework must take when parsing a JSON object
 with `__proto__`. This functionality is provided by
-[bourne](https://github.com/hapijs/bourne).
+[secure-json-parse](https://github.com/fastify/secure-json-parse).
 See https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061
 for more details about prototype poisoning attacks.
 
@@ -83,6 +83,19 @@ Possible values are `'error'`, `'remove'` and `'ignore'`.
 
 + Default: `'error'`
 
+<a name="factory-on-constructor-poisoning"></a>
+### `onConstructorPoisoning`
+
+Defines what action the framework must take when parsing a JSON object
+with `constructor`. This functionality is provided by
+[secure-json-parse](https://github.com/fastify/secure-json-parse).
+See https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061
+for more details about prototype poisoning attacks.
+
+Possible values are `'error'`, `'remove'` and `'ignore'`.
+
++ Default: `'ignore'`
+
 <a name="factory-logger"></a>
 ### `logger`
 
@@ -156,7 +169,7 @@ fastify.addHook('onRequest', (req, reply, done) => {
 })
 
 fastify.addHook('onResponse', (req, reply, done) => {
-  req.log.info({ url: req.req.originalUrl, statusCode: res.res.statusCode }, 'request completed')
+  req.log.info({ url: req.req.originalUrl, statusCode: reply.res.statusCode }, 'request completed')
   done()
 })
 ```
@@ -223,7 +236,7 @@ Defines the label used for the request identifier when logging the request.
 
 Function for generating the request id. It will receive the incoming request as a parameter.
 
-+ Default: `value of 'request-id' if provided or monotonically increasing integers`
++ Default: `value of 'request-id' header if provided or monotonically increasing integers`
 
 Especially in distributed systems, you may want to override the default id generation behaviour as shown below. For generating `UUID`s you may want to checkout [hyperid](https://github.com/mcollina/hyperid)
 
@@ -234,7 +247,7 @@ const fastify = require('fastify')({
 })
 ```
 
-**Note: genReqId will _not_ be called if the 'request-id' header is available.**
+**Note: genReqId will _not_ be called if the header set in <code>[requestIdHeader](#requestidheader)</code> is available (defaults to 'request-id').**
 
 <a name="factory-trust-proxy"></a>
 ### `trustProxy`
@@ -360,6 +373,75 @@ If `false`, the server routes the incoming request as usual.
 
 + Default: `true`
 
+<a name="factory-ajv"></a>
+### `ajv`
+
+Configure the ajv instance used by Fastify without providing a custom one.
+
++ Default:
+
+```js
+{
+  customOptions: {
+    removeAdditional: true,
+    useDefaults: true,
+    coerceTypes: true,
+    allErrors: true,
+    nullable: true
+  },
+  plugins: []
+}
+```
+
+```js
+const fastify = require('fastify')({
+  ajv: {
+    customOptions: {
+      nullable: false // Refer to [ajv options](https://ajv.js.org/#options)
+    },
+    plugins: [
+      require('ajv-merge-patch')
+      [require('ajv-keywords'), 'instanceof'];
+      // Usage: [plugin, pluginOptions] - Plugin with options
+      // Usage: plugin - Plugin without options
+    ]
+  }
+})
+```
+
+<a name="http2-session-timeout"></a>
+### `http2SessionTimeout`
+
+Set a default
+[timeout](https://nodejs.org/api/http2.html#http2_http2session_settimeout_msecs_callback) to every incoming http2 session. The session will be closed on the timeout. Default: `5000` ms.
+
+Note that this is needed to offer the graceful "close" experience when
+using http2. Node core defaults this to `0`.
+
+<a name="framework-errors"></a>
+### `frameworkErrors`
+
++ Default: `null`
+
+Fastify provides default error handlers for the most common use cases.
+Using this option it is possible to override one or more of those handlers with custom code.
+
+*Note: Only `FST_ERR_BAD_URL` is implemented at the moment.*
+
+```js
+const fastify = require('fastify')({
+  frameworkErrors: function (error, req, res) {
+    if (error instanceof FST_ERR_BAD_URL) {
+      res.code(400)
+      return res.send("Provided url is not valid")
+    } else {
+      res.send(err)
+    }
+  }
+})
+```
+
+
 ## Instance
 
 ### Server Methods

package/docs/Serverless.md

@@ -98,7 +98,7 @@ Unlike AWS Lambda or Google Cloud Functions, Google Cloud Run is a serverless **
 
 *Follow the steps below to deploy to Google Cloud Run if you are already familiar with gcloud or just follow their [quickstart](https://cloud.google.com/run/docs/quickstarts/build-and-deploy)*.
 
-### Adjust Fastfiy server
+### Adjust Fastify server
 
 In order for Fastify to properly listen for requests within the container, be sure to set the correct port and address:
 

package/docs/Testing.md

@@ -14,12 +14,26 @@ fastify.inject({
   url: String,
   query: Object,
   payload: Object,
-  headers: Object
+  headers: Object,
+  cookies: Object
 }, (error, response) => {
   // your tests
 })
 ```
 
+`.inject` methods can also be chained by omitting the callback function:
+
+```js
+fastify
+  .inject()
+  .get('/')
+  .headers({ foo: 'bar' })
+  .query({ foo: 'bar' })
+  .end((err, res) => { // the .end call will trigger the request
+    console.log(res.payload)
+  })
+```
+
 or in the promisified version
 
 ```js
@@ -29,7 +43,8 @@ fastify
     url: String,
     query: Object,
     payload: Object,
-    headers: Object
+    headers: Object,
+    cookies: Object
   })
   .then(response => {
     // your tests
@@ -89,7 +104,7 @@ tap.test('GET `/` route', t => {
     t.error(err)
     t.strictEqual(response.statusCode, 200)
     t.strictEqual(response.headers['content-type'], 'application/json; charset=utf-8')
-    t.deepEqual(JSON.parse(response.payload), { hello: 'world' })
+    t.deepEqual(response.json(), { hello: 'world' })
   })
 })
 ```

package/docs/TypeScript.md

@@ -21,6 +21,7 @@ import { Server, IncomingMessage, ServerResponse } from 'http'
 // Create a http server. We pass the relevant typings for our http version used.
 // By passing types we get correctly typed access to the underlying http objects in routes.
 // If using http2 we'd pass <http2.Http2Server, http2.Http2ServerRequest, http2.Http2ServerResponse>
+// For https pass http2.Http2SecureServer or http.SecureServer instead of Server.
 const server: fastify.FastifyInstance<Server, IncomingMessage, ServerResponse> = fastify({})
 
 const opts: fastify.RouteShorthandOptions = {
@@ -109,8 +110,8 @@ const opts: fastify.RouteShorthandOptions = {
 server.get<Query, Params, Headers, Body>('/ping/:bar', opts, (request, reply) => {
   console.log(request.query) // this is of type Query!
   console.log(request.params) // this is of type Params!
-  console.log(request.body) // this is of type Body!
   console.log(request.headers) // this is of type Headers!
+  console.log(request.body) // this is of type Body!
   reply.code(200).send({ pong: 'it worked!' })
 })
 ```
@@ -142,8 +143,8 @@ const opts: fastify.RouteShorthandOptions = {
 server.get<fastify.DefaultQuery, Params, unknown>('/ping/:bar', opts, (request, reply) => {
   console.log(request.query) // this is of type fastify.DefaultQuery!
   console.log(request.params) // this is of type Params!
-  console.log(request.body) // this is of type unknown!
-  console.log(request.headers) // this is of type fastify.DefaultHeader because typescript will use the default type value!
+  console.log(request.headers) // this is of type unknown!
+  console.log(request.body) // this is of type fastify.DefaultBody because typescript will use the default type value!
   reply.code(200).send({ pong: 'it worked!' })
 })
 
@@ -154,8 +155,8 @@ server.get<fastify.DefaultQuery, Params, unknown>('/ping/:bar', opts, (request,
 server.get<unknown, Params, unknown, unknown>('/ping/:bar', opts, (request, reply) => {
   console.log(request.query) // this is of type unknown!
   console.log(request.params) // this is of type Params!
-  console.log(request.body) // this is of type unknown!
   console.log(request.headers) // this is of type unknown!
+  console.log(request.body) // this is of type unknown!
   reply.code(200).send({ pong: 'it worked!' })
 })
 ```
@@ -189,8 +190,8 @@ application.
 ## Contributing
 TypeScript related changes can be considered to fall into one of two categories:
 
-* Core - The typings bundled with fastify
-* Plugins - Fastify ecosystem plugins
+* [`Core`](#core-types) - The typings bundled with fastify
+* [`Plugins`](#plugin-types) - Fastify ecosystem plugins
 
 Make sure to read our [`CONTRIBUTING.md`](https://github.com/fastify/fastify/blob/master/CONTRIBUTING.md) file before getting started to make sure things go smoothly!
 
@@ -215,29 +216,46 @@ Some types might not be available yet, so don't be shy about contributing.
 ### Authoring Plugin Types
 Typings for many plugins that extend the `FastifyRequest`, `FastifyReply` or `FastifyInstance` objects can be achieved as shown below.
 
-This code shows the typings for the `fastify-static` plugin.
+This code shows the typings for the [`fastify-static`](https://github.com/fastify/fastify-static) plugin.
 
 ```ts
+/// <reference types="node" />
+
 // require fastify typings
-import fastify = require("fastify");
-// require necessary http typings
+import * as fastify from 'fastify';
+
+// require necessary http, http2, https typings
 import { Server, IncomingMessage, ServerResponse } from "http";
+import { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse } from "http2";
+import * as https from "https";
+
+type HttpServer = Server | Http2Server | Http2SecureServer | https.Server;
+type HttpRequest = IncomingMessage | Http2ServerRequest;
+type HttpResponse = ServerResponse | Http2ServerResponse;
 
 // extend fastify typings
 declare module "fastify" {
-    interface FastifyReply<HttpResponse> {
-        sendFile(filename: string): FastifyReply<HttpResponse>;
-    }
+  interface FastifyReply<HttpResponse> {
+    sendFile(filename: string): FastifyReply<HttpResponse>;
+  }
 }
 
 // declare plugin type using fastify.Plugin
-declare const fastifyStatic: fastify.Plugin<Server, IncomingMessage, ServerResponse, {
+declare function fastifyStatic(): fastify.Plugin<
+  Server,
+  IncomingMessage,
+  ServerResponse,
+  {
     root: string;
     prefix?: string;
     serve?: boolean;
     decorateReply?: boolean;
     schemaHide?: boolean;
     setHeaders?: (...args: any[]) => void;
+    redirect?: boolean;
+    wildcard?: boolean | string;
+
+    // Passed on to `send`
     acceptRanges?: boolean;
     cacheControl?: boolean;
     dotfiles?: boolean;
@@ -247,7 +265,12 @@ declare const fastifyStatic: fastify.Plugin<Server, IncomingMessage, ServerRespo
     index?: string[];
     lastModified?: boolean;
     maxAge?: string | number;
-}>;
+  }
+>;
+
+declare namespace fastifyStatic {
+  interface FastifyStaticOptions {}
+}
 
 // export plugin type
 export = fastifyStatic;

package/docs/Validation-and-Serialization.md

@@ -50,11 +50,26 @@ const bodyJsonSchema = {
   }
 }
 
+const queryStringJsonSchema = {
+  type: 'object',
+  required: ['name'],
+  properties: {
+    name: { type: 'string' },
+    excitement: { type: 'integer' }
+  }
+}
+
+/* If you don't need required query strings,
+ * A short hand syntax is also there:
+
 const queryStringJsonSchema = {
   name: { type: 'string' },
   excitement: { type: 'integer' }
 }
 
+*/
+
+
 const paramsJsonSchema = {
   type: 'object',
   properties: {
@@ -240,6 +255,77 @@ This example will returns:
 | /sub  | one, two        |
 | /deep | one, two, three |
 
+<a name="ajv-plugins"></a>
+#### Ajv Plugins
+
+You can provide a list of plugins you want to use with Ajv:
+
+> Refer to [`ajv options`](https://github.com/fastify/fastify/blob/master/docs/Server.md#factory-ajv) to check plugins format
+
+```js
+const fastify = require('fastify')({
+  ajv: {
+    plugins: [
+      require('ajv-merge-patch')
+    ]
+  }
+})
+
+fastify.route({
+  method: 'POST',
+  url: '/',
+  schema: {
+    body: {
+      $patch: {
+        source: {
+          type: 'object',
+          properties: {
+            q: {
+              type: 'string'
+            }
+          }
+        },
+        with: [
+          {
+            op: 'add',
+            path: '/properties/q',
+            value: { type: 'number' }
+          }
+        ]
+      }
+    }
+  },
+  handler (req, reply) {
+    reply.send({ ok: 1 })
+  }
+})
+
+fastify.route({
+  method: 'POST',
+  url: '/',
+  schema: {
+    body: {
+      $merge: {
+        source: {
+          type: 'object',
+          properties: {
+            q: {
+              type: 'string'
+            }
+          }
+        },
+        with: {
+          required: ['q']
+        }
+      }
+    }
+  },
+  handler (req, reply) {
+    reply.send({ ok: 1 })
+  }
+})
+```
+
 <a name="schema-compiler"></a>
 #### Schema Compiler
 
@@ -257,7 +343,9 @@ Fastify's [baseline ajv configuration](https://github.com/epoberezkin/ajv#option
 }
 ```
 
-This baseline configuration cannot be modified. If you want to change or set additional config options, you will need to create your own instance and override the existing one like:
+This baseline configuration can be modified by providing [`ajv.customOptions`](https://github.com/fastify/fastify/blob/master/docs/Server.md#factory-ajv) to your Fastify factory.
+
+If you want to change or set additional config options, you will need to create your own instance and override the existing one like:
 
 ```js
 const fastify = require('fastify')()
@@ -282,24 +370,136 @@ fastify.schemaCompiler = function (schema) { return ajv.compile(schema) })
 ```
 _**Note:** If you use a custom instance of any validator (even Ajv), you have to add schemas to the validator instead of fastify, since fastify's default validator is no longer used, and fastify's `addSchema` method has no idea what validator you are using._
 
-But maybe you want to change the validation library. Perhaps you like `Joi`. In this case, you can use it to validate the url parameters, body, and query string!
+<a name="using-other-validation-libraries"></a>
+#### Using other validation libraries
+
+The `schemaCompiler` function makes it easy to substitute `ajv` with almost any Javascript validation library ([joi](https://github.com/hapijs/joi/), [yup](https://github.com/jquense/yup/), ...).
+
+However, in order to make your chosen validation engine play well with Fastify's request/response pipeline, the function returned by your `schemaCompiler` function should return an object with either :
+
+* in case of validation failure: an `error` property, filled with an instance of `Error` or a string that describes the validation error
+* in case of validation success: an `value` property, filled with the coerced value that passed the validation
+
+The examples below are therefore equivalent:
+
+```js
+const joi = require('joi')
+
+// Validation options to match ajv's baseline options used in Fastify
+const joiOptions = {
+  abortEarly: false, // return all errors
+  convert: true, // change data type of data to match type keyword
+  allowUnknown : false, // remove additional properties
+  noDefaults: false
+}
+
+const joiBodySchema = joi.object().keys({
+  age: joi.number().integer().required(),
+  sub: joi.object().keys({
+    name: joi.string().required()
+  }).required()
+})
+
+const joiSchemaCompiler = schema => data => {
+  // joi `validate` function returns an object with an error property (if validation failed) and a value property (always present, coerced value if validation was successful)
+  const { error, value } = joiSchema.validate(data, joiOptions)
+  if (error) {
+    return { error }
+  } else {
+    return { value }
+  }
+}
+
+// or more simply...
+const joiSchemaCompiler = schema => data => joiSchema.validate(data, joiOptions)
+
+fastify.post('/the/url', {
+  schema: {
+    body: joiBodySchema
+  },
+  schemaCompiler: joiSchemaCompiler
+}, handler)
+```
 
 ```js
-const Joi = require('joi')
+const yup = require('yup')
+
+// Validation options to match ajv's baseline options used in Fastify
+const yupOptions = {
+  strict: false,
+  abortEarly: false, // return all errors
+  stripUnknown: true, // remove additional properties
+  recursive: true
+}
+
+const yupBodySchema = yup.object({
+  age: yup.number().integer().required(),
+  sub: yup.object().shape({
+    name: yup.string().required()
+  }).required()
+})
+
+const yupSchemaCompiler = schema => data => {
+  // with option strict = false, yup `validateSync` function returns the coerced value if validation was successful, or throws if validation failed
+  try {
+    const result = schema.validateSync(data, yupOptions)
+    return { value: result }
+  } catch (e) {
+    return { error: e }
+  }
+}
 
 fastify.post('/the/url', {
   schema: {
-    body: Joi.object().keys({
-      hello: Joi.string().required()
-    }).required()
+    body: yupBodySchema
   },
-  schemaCompiler: schema => data => Joi.validate(data, schema)
+  schemaCompiler: yupSchemaCompiler
 }, handler)
 ```
 
-In that case the function returned by `schemaCompiler` returns an object like:
-* `error`: filled with an instance of `Error` or a string that describes the validation error
-* `value`: the coerced value that passed the validation
+##### Validation messages with other validation libraries
+
+Fastify's validation error messages are tightly coupled to the default validation engine: errors returned from `ajv` are eventually run through the `schemaErrorsText` function which is responsible for building human-friendly error messages. However, the `schemaErrorsText` function is written with `ajv` in mind : as a result, you may run into odd or incomplete error messages when using other validation librairies.
+
+To circumvent this issue, you have 2 main options :
+
+1. make sure your validation function (returned by your custom `schemaCompiler`) returns errors in the exact same structure and format as `ajv` (although this could prove to be difficult and tricky due to differences between validation engines)
+2. or use a custom `errorHandler` to intercept and format your 'custom' validation errors
+
+To help you in writing a custom `errorHandler`, Fastify adds 2 properties to all validation errors:
+
+* validation: the content of the `error` property of the object returned by the validation function (returned by your custom `schemaCompiler`)
+* validationContext: the 'context' (body, params, query, headers) where the validation error occurred
+
+A very contrived example of such a custom `errorHandler` handling validation errors is shown below:
+
+```js
+const errorHandler = (error, request, reply) => {
+
+  const statusCode = error.statusCode
+  let response
+
+  const { validation, validationContext } = error
+
+  // check if we have a validation error
+  if (validation) {
+    response = {
+      message: `A validation error occured when validating the ${validationContext}...`, // validationContext will be 'body' or 'params' or 'headers' or 'query'
+      errors: validation // this is the result of your validation library...
+    }
+  } else {
+    response = {
+      message: 'An error occurred...'
+    }
+  }
+
+  // any additional work here, eg. log error
+  // ...
+
+  reply.status(statusCode).send(response)
+
+}
+```
 
 <a name="schema-resolver"></a>
 #### Schema Resolver
@@ -427,10 +627,10 @@ const schema = {
 and fail to satisfy it, the route will immediately return a response with the following payload
 
 ```js
-{ 
+{
   "statusCode": 400,
   "error": "Bad Request",
-  "message": "body should have required property 'name'" 
+  "message": "body should have required property 'name'"
 }
 ```
 
@@ -452,7 +652,8 @@ You can also use [setErrorHandler](https://www.fastify.io/docs/latest/Server/#se
 ```js
 fastify.setErrorHandler(function (error, request, reply) {
   if (error.validation) {
-     reply.status(422).send(new Error('validation failed'))
+     // error.validationContext can be on of [body, params, querystring, headers]
+     reply.status(422).send(new Error(`validation failed of the ${error.validationContext}`))
   }
 })
 ```