fastify 2.10.0 → 2.13.0

package/docs/Hooks.md

@@ -7,14 +7,14 @@ Hooks are registered with the `fastify.addHook` method and allow you to listen t
 By using hooks you can interact directly with the lifecycle of Fastify. There are Request/Reply hooks and application hooks:
 
 - [Request/Reply Hooks](#requestreply-hooks)
-  - [onRequest](#onRequest)
-  - [preParsing](#preParsing)
-  - [preValidation](#preValidation)
-  - [preHandler](#preHandler)
-  - [preSerialization](#preSerialization)
-  - [onError](#onError)
-  - [onSend](#onSend)
-  - [onResponse](#onResponse)
+  - [onRequest](#onrequest)
+  - [preParsing](#preparsing)
+  - [preValidation](#prevalidation)
+  - [preHandler](#prehandler)
+  - [preSerialization](#preserialization)
+  - [onError](#onerror)
+  - [onSend](#onsend)
+  - [onResponse](#onresponse)
 - [Application Hooks](#application-hooks)
   - [onClose](#onclose)
   - [onRoute](#onroute)
@@ -44,15 +44,11 @@ Or `async/await`:
 fastify.addHook('onRequest', async (request, reply) => {
   // Some code
   await asyncMethod()
-  // Error occurred
-  if (err) {
-    throw new Error('Some errors occurred.')
-  }
   return
 })
 ```
 
-**Notice:** in the [onRequest](#onRequest) hook, `request.body` will always be `null`, because the body parsing happens before the [preHandler](#preHandler) hook.
+**Notice:** in the [onRequest](#onRequest) hook, `request.body` will always be `null`, because the body parsing happens before the [preValidation](#preValidation) hook.
 
 ### preParsing
 ```js
@@ -66,13 +62,12 @@ Or `async/await`:
 fastify.addHook('preParsing', async (request, reply) => {
   // Some code
   await asyncMethod()
-  // Error occurred
-  if (err) {
-    throw new Error('Some errors occurred.')
-  }
   return
 })
 ```
+
+**Notice:** in the [preParsing](#preParsing) hook, `request.body` will always be `null`, because the body parsing happens before the [preValidation](#preValidation) hook.
+
 ### preValidation
 ```js
 fastify.addHook('preValidation', (request, reply, done) => {
@@ -85,14 +80,9 @@ Or `async/await`:
 fastify.addHook('preValidation', async (request, reply) => {
   // Some code
   await asyncMethod()
-  // Error occurred
-  if (err) {
-    throw new Error('Some errors occurred.')
-  }
   return
 })
 ```
-**Notice:** in the [preValidation](#preValidation) hook, `request.body` will always be `null`, because the body parsing happens before the [preHandler](#preHandler) hook.
 
 ### preHandler
 ```js
@@ -106,10 +96,6 @@ Or `async/await`:
 fastify.addHook('preHandler', async (request, reply) => {
   // Some code
   await asyncMethod()
-  // Error occurred
-  if (err) {
-    throw new Error('Some errors occurred.')
-  }
   return
 })
 ```
@@ -198,10 +184,6 @@ Or `async/await`:
 fastify.addHook('onResponse', async (request, reply) => {
   // Some code
   await asyncMethod()
-  // Error occurred
-  if (err) {
-    throw new Error('Some errors occurred.')
-  }
   return
 })
 ```
@@ -228,7 +210,23 @@ fastify.addHook('preHandler', (request, reply, done) => {
 *The error will be handled by [`Reply`](https://github.com/fastify/fastify/blob/master/docs/Reply.md#errors).*
 
 ### Respond to a request from a hook
-If needed, you can respond to a request before you reach the route handler, for example when implementing an authentication hook. If you are using `onRequest` or `preHandler` use `reply.send`; if you are using a middleware, use `res.end`.
+
+If needed, you can respond to a request before you reach the route handler,
+for example when implementing an authentication hook.
+Replying from an hook implies that the hook chain is __stopped__ and
+the rest of hooks and the handlers are not executed. If the hook is
+using the callback approach, i.e. it is not an `async` function or it
+returns a `Promise`, it is as simple as calling `reply.send()` and avoiding
+calling the callback. If the hook is `async`, `reply.send()` __must__ be
+called _before_ the function returns or the promise resolves, otherwise the
+request will proceed. When `reply.send()` is called outside of the
+promise chain, it is important to `return reply` otherwise the request
+will be executed twice.
+
+It is important to __not mix callbacks and `async`/`Promise`__, otherwise
+the hook chain will be executed twice.
+
+If you are using `onRequest` or `preHandler` use `reply.send`; if you are using a middleware, use `res.end`.
 
 ```js
 fastify.addHook('onRequest', (request, reply, done) => {
@@ -237,7 +235,9 @@ fastify.addHook('onRequest', (request, reply, done) => {
 
 // Works with async functions too
 fastify.addHook('preHandler', async (request, reply) => {
+  await something()
   reply.send({ hello: 'world' })
+  return reply // optional in this case, but it is a good practice
 })
 ```
 
@@ -250,6 +250,26 @@ fastify.addHook('onRequest', (request, reply, done) => {
 })
 ```
 
+If you are sending a response without `await` on it, make sure to always
+`return reply`:
+
+```js
+fastify.addHook('preHandler', async (request, reply) => {
+  setImmediate(() => { reply.send('hello') })
+
+  // This is needed to signal the handler to wait for a response
+  // to be sent outside of the promise chain
+  return reply
+})
+
+fastify.addHook('preHandler', async (request, reply) => {
+  // the fastify-static plugin will send a file asynchronously,
+  // so we should return reply
+  reply.sendFile('myfile')
+  return reply
+})
+```
+
 ## Application Hooks
 
 You can hook into the application-lifecycle as well. It's important to note that these hooks aren't fully encapsulated. The `this` inside the hooks are encapsulated but the handlers can respond to an event outside the encapsulation boundaries.
@@ -280,9 +300,24 @@ fastify.addHook('onRoute', (routeOptions) => {
   routeOptions.url
   routeOptions.bodyLimit
   routeOptions.logLevel
+  routeOptions.logSerializers
   routeOptions.prefix
 })
 ```
+
+If you are authoring a plugin and you need to customize application routes, like modifying the options or adding new route hooks, this is the right place.
+
+```js
+fastify.addHook('onRoute', (routeOptions) => {
+  function onPreSerialization(request, reply, payload, done) {
+    // Your code
+    done(null, payload)
+  }
+  // preSerialization can be an array or undefined
+  routeOptions.preSerialization = [...(routeOptions.preSerialization || []), onPreSerialization]
+})
+```
+
 <a name="on-register"></a>
 ### onRegister
 Triggered when a new plugin is registered and a new encapsulation context is created. The hook will be executed **before** the registered code.<br/>
@@ -298,19 +333,22 @@ fastify.register(async (instance, opts) => {
   instance.register(async (instance, opts) => {
     instance.data.push('world')
     console.log(instance.data) // ['hello', 'world']
-  })
-})
+  }, { prefix: '/hola' })
+}, { prefix: '/ciao' })
 
 fastify.register(async (instance, opts) => {
   console.log(instance.data) // []
-})
+}, { prefix: '/hello' })
 
-fastify.addHook('onRegister', (instance) => {
+fastify.addHook('onRegister', (instance, opts) => {
   // Create a new array from the old one
   // but without keeping the reference
   // allowing the user to have encapsulated
   // instances of the `data` property
   instance.data = instance.data.slice()
+
+  // the options of the new registered instance
+  console.log(opts.prefix)
 })
 ```
 
@@ -362,7 +400,7 @@ fastify.addHook('preHandler', (request, reply, done) => {
 
 fastify.addHook('preSerialization', (request, reply, payload, done) => {
   // Your code
-  done()
+  done(null, payload)
 })
 
 fastify.route({
@@ -396,7 +434,7 @@ fastify.route({
   //   done()
   // }],
   preSerialization: (request, reply, payload, done) => {
-    // Manipulate the payload
+    // This hook will always be executed after the shared `preSerialization` hooks
     done(null, payload)
   },
   handler: function (request, reply) {

package/docs/Plugins-Guide.md

@@ -11,6 +11,7 @@ Fastify was built from the beginning to be an extremely modular system. We built
 - [Hooks](#hooks)
 - [Middlewares](#middlewares)
 - [How to handle encapsulation and distribution](#distribution)
+- [ESM support](#esm-support)
 - [Handle errors](#handle-errors)
 - [Let's start!](#start)
 
@@ -92,7 +93,7 @@ fastify.register((instance, opts, done) => {
 Inside the second register call `instance.util` will throw an error, because `util` exists only inside the first register context.<br>
 Let's step back for a moment and dig deeper into this: every time you use the `register` API, a new context is created which avoids the negative situations mentioned above.
 
-Do note that encapsulation applies to the ancestors and siblings, but not the children. 
+Do note that encapsulation applies to the ancestors and siblings, but not the children.
 ```js
 fastify.register((instance, opts, done) => {
   instance.decorate('util', (a, b) => a + b)
@@ -180,7 +181,7 @@ We've seen how to extend server functionality and how to handle the encapsulatio
 ## Hooks
 You just built an amazing utility, but now you need to execute that for every request, this is what you will likely do:
 ```js
-fastify.decorate('util', (request, key, value) => { request.key = value })
+fastify.decorate('util', (request, key, value) => { request[key] = value })
 
 fastify.get('/plugin1', (request, reply) => {
   fastify.util(request, 'timestamp', new Date())
@@ -293,6 +294,22 @@ fastify.register(require('your-plugin'), parent => {
 ```
 In the above example, the `parent` variable of the function passed in as the second argument of `register` is a copy of the **external fastify instance** that the plugin was registered at. This means that we are able to access any variables that were injected by preceding plugins in the order of declaration.
 
+<a name="esm-support"></a>
+## ESM support
+
+ESM is supported as well from [Node.js `v13.3.0`](https://nodejs.org/api/esm.html) and above! Just export your plugin as ESM module and you are good to go!
+
+```js
+// plugin.mjs
+async function plugin (fastify, opts) {
+  fastify.get('/', async (req, reply) => {
+    return { hello: 'world' }
+  })
+}
+
+export default plugin
+```
+
 <a name="handle-errors"></a>
 ## Handle errors
 It can happen that one of your plugins fails during startup. Maybe you expect it and you have a custom logic that will be triggered in that case. How can you implement this?

package/docs/Plugins.md

@@ -16,6 +16,7 @@ fastify.register(plugin, [options])
 The optional `options` parameter for `fastify.register` supports a predefined set of options that Fastify itself will use, except when the plugin has been wrapped with [fastify-plugin](https://github.com/fastify/fastify-plugin). This options object will also be passed to the plugin upon invocation, regardless of whether or not the plugin has been wrapped. The currently supported list of Fastify specific options is:
 
 + [`logLevel`](https://github.com/fastify/fastify/blob/master/docs/Routes.md#custom-log-level)
++ [`logSerializers`](https://github.com/fastify/fastify/blob/master/docs/Routes.md#custom-log-serializer)
 + [`prefix`](https://github.com/fastify/fastify/blob/master/docs/Plugins.md#route-prefixing-options)
 
 **Note: Those options will be ignored when used with fastify-plugin**
@@ -97,6 +98,32 @@ await fastify.ready()
 
 await fastify.listen(3000)
 ```
+
+<a name="esm-support"></a>
+#### ESM support
+
+ESM is supported as well from [Node.js `v13.3.0`](https://nodejs.org/api/esm.html) and above!
+
+```js
+// main.mjs
+import Fastify from 'fastify'
+const fastify = Fastify()
+
+fastify.register(import('./plugin.mjs'))
+
+fastify.listen(3000, console.log)
+
+
+// plugin.mjs
+async function plugin (fastify, opts) {
+  fastify.get('/', async (req, reply) => {
+    return { hello: 'world' }
+  })
+}
+
+export default plugin
+```
+
 <a name="create-plugin"></a>
 ### Create a plugin
 Creating a plugin is very easy, you just need to create a function that takes three parameters, the `fastify` instance, an `options` object and the `done` callback.<br>

package/docs/Recommendations.md

@@ -0,0 +1,159 @@
+<h1 align="center">Fastify</h1>
+
+## Recommendations
+
+This document contains a set recommendations, or best practices, when using
+Fastify.
+
+* [Use A Reverse Proxy](#reverseproxy)
+
+## Use A Reverse Proxy
+<a id="reverseproxy"></a>
+
+Node.js is an early adopter of frameworks shipping with an easy to use web
+server within the standard library. Previously, with languages like PHP or
+Python, one would need either a web server with specific support for the
+language or the ability to setup some sort of [CGI gateway][cgi] that works
+with the language. With Node.js, one can simply write an application that
+_directly_ handles HTTP requests. As a result, the temptation is to write
+applications that handle requests for multiple domains, listen on multiple
+ports (i.e. HTTP _and_ HTTPS), and various other scenarios and combinations
+thereof. Further, the temptation is to then expose these applications directly
+to the Internet to handle requests.
+
+The Fastify team **strongly** considers this to be an anti-pattern and extremely
+bad practice:
+
+1. It adds unnecessary complexity to the application by diluting its focus.
+2. It prevents [horizontal scalability][scale-horiz].
+
+See [Why should I use a Reverse Proxy if Node.js is Production Ready?][why-use]
+for a more thorough discussion of why one should opt to use a reverse proxy.
+
+For a concrete example, consider the situation where:
+
+1. The app needs multiple instances to handle load.
+1. The app needs TLS termination.
+1. The app needs to redirect HTTP requests to HTTPS.
+1. The app needs to serve multiple domains.
+1. The app needs to serve static resources, e.g. jpeg files.
+
+There are many reverse proxy solutions available, and your environment may
+dictate the solution to use, e.g. AWS or GCP. But given the above, we could use
+[HAProxy][haproxy] to solve these requirements:
+
+```conf
+# The global section defines base HAProxy (engine) instance configuration.
+global
+  log /dev/log syslog
+  maxconn 4096
+  chroot /var/lib/haproxy
+  user haproxy
+  group haproxy
+
+  # Set some baseline TLS options.
+  tune.ssl.default-dh-param 2048
+  ssl-default-bind-options no-sslv3 no-tlsv10 no-tlsv11
+  ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS
+  ssl-default-server-options no-sslv3 no-tlsv10 no-tlsv11
+  ssl-default-server-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS
+
+# Each defaults section defines options that will apply to each subsequent
+# subsection until another defaults section is encountered.
+defaults
+  log   global
+  mode  http
+  option        httplog
+  option        dontlognull
+  retries       3
+  option redispatch
+  maxconn       2000
+  timeout connect 5000
+  timeout client 50000
+  timeout server 50000
+
+  # Enable content compression for specific content types.
+  compression algo gzip
+  compression type text/html text/plain text/css application/javascript
+
+# A "frontend" section defines a public listener, i.e. an "http server"
+# as far as clients are concerned.
+frontend proxy
+  # The IP address here would be the _public_ IP address of the server.
+  # Here, we use a private address as an example.
+  bind 10.0.0.10:80
+  # This redirect rule will redirect all traffic that is not TLS traffic
+  # to the same incoming request URL on the HTTPS port.
+  redirect scheme https code 308 if !{ ssl_fc }
+  # Technically this use_backend directive is useless since we are simply
+  # redirecting all traffic to this frontend to the HTTPS frontend. It is
+  # merely included here for completeness sake.
+  use_backend default-server
+
+# This frontend defines our primary, TLS only, listener. It is here where
+# we will define the TLS certificates to expose and how to direct incoming
+# requests.
+frontend proxy-ssl
+  # The `/etc/haproxy/certs` directory in this example contains a set of
+  # certificate PEM files that are named for the domains the certificates are
+  # issued for. When HAProxy starts, it will read this directory, load all of
+  # the certificates it finds here, and use SNI matching to apply the correct
+  # certificate to the connection.
+  bind 10.0.0.10:443 ssl crt /etc/haproxy/certs
+
+  # Here we define rule pairs to handle static resources. Any incoming request
+  # that has a path starting with `/static`, e.g.
+  # `https://one.example.com/static/foo.jpeg`, will be redirected to the
+  # static resources server.
+  acl is_static path -i -m beg /static
+  use_backend static-backend if is_static
+
+  # Here we define rule pairs to direct requests to appropriate Node.js
+  # servers based on the requested domain. The `acl` line is used to match
+  # the incoming hostname and define a boolean indicating if it is a match.
+  # The `use_backend` line is used to direct the traffic if the boolean is
+  # true.
+  acl example1 hdr_sub(Host) one.example.com
+  use_backend example1-backend if example1
+
+  acl example2 hdr_sub(Host) two.example.com
+  use_backend example2-backend if example2
+
+  # Finally, we have a fallback redirect if none of the requested hosts
+  # match the above rules.
+  default_backend default-server
+
+# A "backend" is used to tell HAProxy where to request information for the
+# proxied request. These sections are where we will define where our Node.js
+# apps live and any other servers for things like static assets.
+backend default-server
+  # In this example we are defaulting unmatched domain requests to a single
+  # backend server for all requests. Notice that the backend server does not
+  # have to be serving TLS requests. This is called "TLS termination": the TLS
+  # connection is "terminated" at the reverse proxy.
+  # It is possible to also proxy to backend servers that are themselves serving
+  # requests over TLS, but that is outside the scope of this example.
+  server server1 10.10.10.2:80
+
+# This backend configuration will serve requests for `https://one.example.com`
+# by proxying requests to three backend servers in a round-robin manner.
+backend example1-backend
+  server example1-1 10.10.11.2:80
+  server example1-2 10.10.11.2:80
+  server example2-2 10.10.11.3:80
+
+# This one serves requests for `https://two.example.com`
+backend example2-backend
+  server example2-1 10.10.12.2:80
+  server example2-2 10.10.12.2:80
+  server example2-3 10.10.12.3:80
+
+# This backend handles the static resources requests.
+backend static-backend
+  server static-server1 10.10.9.2:80
+```
+
+[cgi]: https://en.wikipedia.org/wiki/Common_Gateway_Interface
+[scale-horiz]: https://en.wikipedia.org/wiki/Scalability#Horizontal
+[why-use]: https://web.archive.org/web/20190821102906/https://medium.com/intrinsic/why-should-i-use-a-reverse-proxy-if-node-js-is-production-ready-5a079408b2ca
+[haproxy]: https://www.haproxy.org/

package/docs/Reply.md

@@ -122,12 +122,29 @@ reply.getHeader('x-foo') // undefined
 Returns a boolean indicating if the specified header has been set.
 
 <a name="redirect"></a>
-### .redirect(dest)
+### .redirect([code ,] dest)
 Redirects a request to the specified url, the status code is optional, default to `302` (if status code is not already set by calling `code`).
+
+Example (no `reply.code()` call) sets status code to `302` and redirects to `/home`
 ```js
 reply.redirect('/home')
 ```
 
+Example (no `reply.code()` call) sets status code to `303` and redirects to `/home`
+```js
+reply.redirect(303, '/home')
+```
+
+Example (`reply.code()` call) sets status code to `303` and redirects to `/home`
+```js
+reply.code(303).redirect('/home')
+```
+
+Example (`reply.code()` call) sets status code to `302` and redirects to `/home`
+```js
+reply.code(303).redirect(302, '/home')
+```
+
 <a name="call-not-found"></a>
 ### .callNotFound()
 Invokes the custom not found handler.
@@ -321,7 +338,7 @@ fastify.get('/async-await', options, async function (request, reply) {
 })
 ```
 
-Rejected promises default to a `500` HTTP status code. Reject the promise, or `throw` in an `async function`, with an object that has `statusCode` (or `status`) and `message` properties to modify the reply.
+Rejected promises default to a `500` HTTP status code. Reject the promise, or `throw` in an `async function`, with an _Error_ object that has `statusCode` (or `status`) and `message` properties to modify the reply. Throwing plain objects is not supported, it must be an instance of _Error_, see:
 
 ```js
 fastify.get('/teapot', async function (request, reply) => {

package/docs/Routes.md

@@ -1,14 +1,34 @@
 <h1 align="center">Fastify</h1>
 
 ## Routes
-You have two ways to declare a route with Fastify, the shorthand method and the full declaration. Let's start with the second one:
+
+The routes methods will configure the endpoints of your application. 
+You have two ways to declare a route with Fastify, the shorthand method and the full declaration.
+
+- [Full Declaration](#full-declaration)
+- [Route Options](#options)
+- [Shorthand Declaration](#shorthand-declaration)
+- [URL Parameters](#url-building)
+- [Use `async`/`await`](#async-await)
+- [Promise resolution](#promise-resolution)
+- [Route Prefixing](#route-prefixing)
+- Logs
+  - [Custom Log Level](#custom-log-level)
+  - [Custom Log Serializer](#custom-log-serializer)
+- [Route handler configuration](#routes-config)
+- [Route's Versioning](#version)
+
 <a name="full-declaration"></a>
 ### Full declaration
+
 ```js
 fastify.route(options)
 ```
-* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`, `'POST'`, `'PUT'` and `'OPTIONS'`. It could also be an array of methods.
 
+<a name="options"></a>
+### Routes option
+
+* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`, `'POST'`, `'PUT'` and `'OPTIONS'`. It could also be an array of methods.
 * `url`: the path of the url to match this route (alias: `path`).
 * `schema`: an object containing the schemas for the request and response.
 They need to be in
@@ -23,14 +43,18 @@ They need to be in
   * `response`: filter and generate a schema for the response, setting a
     schema allows us to have 10-20% more throughput.
 * `attachValidation`: attach `validationError` to request, if there is a schema validation error, instead of sending the error to the error handler.
-* `onRequest(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) as soon that a request is received, it could also be an array of functions.
-* `preValidation(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called after the shared `preValidation` hooks, useful if you need to perform authentication at route level for example, it could also be an array of functions.
-* `preHandler(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called just before the request handler, it could also be an array of functions.
-* `preSerialization(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called just before the serialization, it could also be an array of functions.
+* `onRequest(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#onrequest) as soon that a request is received, it could also be an array of functions.
+* `preParsing(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#preparsing) called before parsing the request, it could also be an array of functions.
+* `preValidation(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#prevalidation) called after the shared `preValidation` hooks, useful if you need to perform authentication at route level for example, it could also be an array of functions.
+* `preHandler(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#prehandler) called just before the request handler, it could also be an array of functions.
+* `preSerialization(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#preserialization) called just before the serialization, it could also be an array of functions.
+* `onSend(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called right before a response is sent, it could also be an array of functions.
+* `onResponse(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#onresponse) called when a response has been sent, so you will not be able to send more data to the client. It could also be an array of functions.
 * `handler(request, reply)`: the function that will handle this request.
 * `schemaCompiler(schema)`: the function that build the schema for the validations. See [here](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md#schema-compiler)
 * `bodyLimit`: prevents the default JSON body parser from parsing request bodies larger than this number of bytes. Must be an integer. You may also set this option globally when first creating the Fastify instance with `fastify(options)`. Defaults to `1048576` (1 MiB).
 * `logLevel`: set log level for this route. See below.
+* `logSerializers`: set serializers to log for this route.
 * `config`: object used to store custom configuration.
 * `version`: a [semver](http://semver.org/) compatible string that defined the version of the endpoint. [Example](https://github.com/fastify/fastify/blob/master/docs/Routes.md#version).
 * `prefixTrailingSlash`: string used to determine how to handle passing `/` as a route with a prefix.
@@ -237,6 +261,7 @@ fastify.register(require('./routes/v2/users'), { prefix: '/v2' })
 
 fastify.listen(3000)
 ```
+
 ```js
 // routes/v1/users.js
 module.exports = function (fastify, opts, done) {
@@ -244,6 +269,7 @@ module.exports = function (fastify, opts, done) {
   done()
 }
 ```
+
 ```js
 // routes/v2/users.js
 module.exports = function (fastify, opts, done) {
@@ -286,6 +312,7 @@ fastify.register(require('./routes/events'), { logLevel: 'debug' })
 
 fastify.listen(3000)
 ```
+
 Or you can directly pass it to a route:
 ```js
 fastify.get('/', { logLevel: 'warn' }, (request, reply) => {
@@ -294,6 +321,65 @@ fastify.get('/', { logLevel: 'warn' }, (request, reply) => {
 ```
 *Remember that the custom log level is applied only to the routes, and not to the global Fastify Logger, accessible with `fastify.log`*
 
+<a name="custom-log-serializer"></a>
+### Custom Log Serializer
+
+In some context, you may need to log a large object but it could be a waste of resources for some routes. In this case, you can define some [`serializer`](https://github.com/pinojs/pino/blob/master/docs/api.md#bindingsserializers-object) and attach them in the right context!
+
+```js
+const fastify = require('fastify')({ logger: true })
+
+fastify.register(require('./routes/user'), { 
+  logSerializers: {
+    user: (value) => `My serializer one - ${value.name}`
+  } 
+})
+fastify.register(require('./routes/events'), {
+  logSerializers: {
+    user: (value) => `My serializer two - ${value.name} ${value.surname}`
+  }
+})
+
+fastify.listen(3000)
+```
+
+You can inherit serializers by context:
+
+```js
+const fastify = Fastify({ 
+  logger: {
+    level: 'info',
+    serializers: {
+      user (req) {
+        return {
+          method: req.method,
+          url: req.url,
+          headers: req.headers,
+          hostname: req.hostname,
+          remoteAddress: req.ip,
+          remotePort: req.connection.remotePort
+        }
+      }
+    }
+  } 
+})
+
+fastify.register(context1, { 
+  logSerializers: {
+    user: value => `My serializer father - ${value}`
+  } 
+})
+
+async function context1 (fastify, opts) {
+  fastify.get('/', (req, reply) => {
+    req.log.info({ user: 'call father serializer', key: 'another key' })
+    // shows: { user: 'My serializer father - call father  serializer', key: 'another key' }
+    reply.send({})
+  })
+}
+
+fastify.listen(3000)
+```
 
 <a name="routes-config"></a>
 ### Config
@@ -315,10 +401,12 @@ fastify.listen(3000)
 
 <a name="version"></a>
 ### Version
+
 #### Default
 If needed you can provide a version option, which will allow you to declare multiple versions of the same route. The versioning should follow the [semver](http://semver.org/) specification.<br/>
 Fastify will automatically detect the `Accept-Version` header and route the request accordingly (advanced ranges and pre-releases currently are not supported).<br/>
 *Be aware that using this feature will cause a degradation of the overall performances of the router.*
+
 ```js
 fastify.route({
   method: 'GET',
@@ -339,7 +427,9 @@ fastify.inject({
   // { hello: 'world' }
 })
 ```
+
 If you declare multiple versions with the same major or minor, Fastify will always choose the highest compatible with the `Accept-Version` header value.<br/>
 If the request will not have the `Accept-Version` header, a 404 error will be returned.
+
 #### Custom
 It's possible to define a custom versioning logic. This can be done through the [`versioning`](https://github.com/fastify/fastify/blob/master/docs/Server.md#versioning) configuration, when creating a fastify server instance.