fastify 2.7.1 → 2.11.0

package/docs/Middleware.md

@@ -0,0 +1,59 @@
+<h1 align="center">Fastify</h1>
+
+## Middleware
+
+Fastify provides an asynchronous [middleware engine](https://github.com/fastify/middie) out-of-the-box, which is compatible with [Express](https://expressjs.com/) and [Restify](http://restify.com/) middleware.
+
+*For help with understanding when middleware is executed, take a look at the [lifecycle](https://github.com/fastify/fastify/blob/master/docs/Lifecycle.md) page.*
+
+Fastify middleware don't support the full syntax `middleware(err, req, res, next)`, because error handling is done inside Fastify.
+Furthermore, methods added by Express and Restify to the enhanced versions of `req` and `res` are not supported in Fastify middlewares.
+
+Also, if you are using middleware that bundles different, smaller middleware, such as [*helmet*](https://helmetjs.github.io/), we recommend using the single modules for better performance.
+
+```js
+fastify.use(require('cors')())
+fastify.use(require('dns-prefetch-control')())
+fastify.use(require('frameguard')())
+fastify.use(require('hide-powered-by')())
+fastify.use(require('hsts')())
+fastify.use(require('ienoopen')())
+fastify.use(require('x-xss-protection')())
+```
+
+or, in the specific case of *helmet*, you can use the [*fastify-helmet*](https://github.com/fastify/fastify-helmet) [plugin](Plugins.md), which is an optimized helmet integration for fastify:
+
+```js
+const fastify = require('fastify')()
+const helmet = require('fastify-helmet')
+
+fastify.register(helmet)
+```
+
+Remember that middleware can be encapsulated, this means that you can decide where your middleware should run by using `register` as explained in the [plugins guide](https://github.com/fastify/fastify/blob/master/docs/Plugins-Guide.md).
+
+Fastify middleware also do not expose the `send` method or other methods specific to the Fastify [Reply]('./Reply.md' "Reply") instance. This is because Fastify wraps the incoming `req` and `res` Node instances using the [Request](./Request.md "Request") and [Reply](./Reply.md "Reply") objects internally, but this is done after the middleware phase. If you need to create middleware, you have to use the Node `req` and `res` instances. Otherwise, you can use the `preHandler` hook which already has the [Request](./Request.md "Request") and [Reply](./Reply.md "Reply") Fastify instances. For more information, see [Hooks](./Hooks.md "Hooks").
+
+<a name="restrict-usage"></a>
+#### Restrict middleware execution to a certain path(s)
+If you need to run a middleware only under certain path(s), just pass the path as first parameter to `use` and you are done!
+
+*Note that this does not support routes with parameters, (eg: `/user/:id/comments`) and wildcards are not supported in multiple paths.*
+
+```js
+const path = require('path')
+const serveStatic = require('serve-static')
+
+// Single path
+fastify.use('/css', serveStatic(path.join(__dirname, '/assets')))
+
+// Wildcard path
+fastify.use('/css/*', serveStatic(path.join(__dirname, '/assets')))
+
+// Multiple paths
+fastify.use(['/css', '/js'], serveStatic(path.join(__dirname, '/assets')))
+```
+
+<a name="express-middleware"></a>
+#### Express middleware compatibility
+Express modifies the prototype of the node core Request and Response objects heavily so Fastify cannot guarantee full middleware compatibility. Express specific functionality such as `res.sendFile()`, `res.send()` or `express.Router()` instances will not work with Fastify. For example, [cors](https://github.com/expressjs/cors) is compatible while [passport](https://github.com/jaredhanson/passport) is not.

package/docs/Plugins-Guide.md

@@ -16,30 +16,29 @@ Fastify was built from the beginning to be an extremely modular system. We built
 
 <a name="register"></a>
 ## Register
-As in JavaScript everything is an object, in Fastify everything is a plugin.<br>
-Your routes, your utilities and so on are all plugins. To add a new plugin, whatever its functionality is, in Fastify you have a nice and unique api to use: [`register`](https://github.com/fastify/fastify/blob/master/docs/Plugins.md).
+As with JavaScript, where everything is an object, in Fastify everything is a plugin.<br>
+Your routes, your utilities and so on are all plugins. To add a new plugin, whatever its functionality may be, in Fastify you have a nice and unique API: [`register`](https://github.com/fastify/fastify/blob/master/docs/Plugins.md).
 ```js
 fastify.register(
   require('./my-plugin'),
   { options }
 )
 ```
-`register` creates a new Fastify context, this means that if you do any change to the Fastify instance, those changes will not be reflected in the context's ancestors. In other words, encapsulation!
-
+`register` creates a new Fastify context, which means that if you perform any changes on the Fastify instance, those changes will not be reflected in the context's ancestors. In other words, encapsulation!
 
 *Why is encapsulation important?*<br>
-Well, let's say you are creating a new disruptive startup, what do you do? You create an api server with all your stuff, everything in the same place, a monolith!<br>
-Ok, you are growing very fast and you want to change your architecture and try microservices. Usually this implies a huge amount of work, because of cross dependencies and the lack of separation of concerns.<br>
-Fastify helps you a lot in this direction, because thanks to the encapsulation model it will completely avoid cross dependencies, and will help you structure your code in cohesive blocks.
+Well, let's say you are creating a new disruptive startup, what do you do? You create an API server with all your stuff, everything in the same place, a monolith!<br>
+Ok, you are growing very fast and you want to change your architecture and try microservices. Usually, this implies a huge amount of work, because of cross dependencies and a lack of separation of concerns in the codebase.<br>
+Fastify helps you in that regard. Thanks to the encapsulation model it will completely avoid cross dependencies, and will help you structure your code into cohesive blocks.
 
 *Let's return to how to correctly use `register`.*<br>
 As you probably know, the required plugins must expose a single function with the following signature
 ```js
 module.exports = function (fastify, options, done) {}
 ```
-Where `fastify` is (pretty obvious) the encapsulated Fastify instance, `options` is the options object and `done` is the function you **must** call when your plugin is ready.
+Where `fastify` is the encapsulated Fastify instance, `options` is the options object and `done` is the function you **must** call when your plugin is ready.
 
-Fastify's plugin model is fully reentrant and graph-based, it handles without any kind of problem asynchronous code and it guarantees the load order of the plugins, even the close order! *How?* Glad you asked, checkout [`avvio`](https://github.com/mcollina/avvio)! Fastify starts loading the plugin __after__ `.listen()`, `.inject()` or `.ready()` are called.
+Fastify's plugin model is fully reentrant and graph-based, it handles asynchronous code without any problems and it enforces both the load and close order of plugins. *How?* Glad you asked, check out [`avvio`](https://github.com/mcollina/avvio)! Fastify starts loading the plugin __after__ `.listen()`, `.inject()` or `.ready()` are called.
 
 Inside a plugin you can do whatever you want, register routes, utilities (we'll see this in a moment) and do nested registers, just remember to call `done` when everything is set up!
 ```js
@@ -52,11 +51,11 @@ module.exports = function (fastify, options, done) {
 }
 ```
 
-Well, now you know how to use the `register` api and how it works, but how do we add new functionality to Fastify and even better, share them with other developers?
+Well, now you know how to use the `register` API and how it works, but how do we add new functionality to Fastify and even better, share them with other developers?
 
 <a name="decorators"></a>
 ## Decorators
-Okay, let's say that you wrote an utility that is so good that you decided to make it available along all your code. How would you do it? Probably something like the following:
+Okay, let's say that you wrote a utility that is so good that you decided to make it available along with all your code. How would you do it? Probably something like the following:
 ```js
 // your-awesome-utility.js
 module.exports = function (a, b) {
@@ -65,40 +64,42 @@ module.exports = function (a, b) {
 ```
 ```js
 const util = require('./your-awesome-utility')
-console.log(util('that is ', ' awesome'))
+console.log(util('that is ', 'awesome'))
 ```
-And now you will import your utility in every file you need it. (And don't forget that you will probably also need it in your test).
+And now you will import your utility in every file you need it in. (And don't forget that you will probably also need it in your tests).
 
-Fastify offers you a way nicer and elegant way to do this, *decorators*.
-Create a decorator is extremely easy, just use the [`decorate`](https://github.com/fastify/fastify/blob/master/docs/Decorators.md) api:
+Fastify offers you a more elegant and comfortable way to do this, *decorators*.
+Creating a decorator is extremely easy, just use the [`decorate`](https://github.com/fastify/fastify/blob/master/docs/Decorators.md) API:
 ```js
 fastify.decorate('util', (a, b) => a + b)
 ```
-Now you can access your utility just by doing `fastify.util` whenever you need it, even inside your test.<br>
-And here's starts the magic; do you remember that few lines above we talked about encapsulation? Well, using `register` and `decorate` in conjunction enable exactly that, let me show you an example to clarify this:
+Now you can access your utility just by calling `fastify.util` whenever you need it - even inside your test.<br>
+And here starts the magic; do you remember how just now we were talking about encapsulation? Well, using `register` and `decorate` in conjunction enable exactly that, let me show you an example to clarify this:
 ```js
 fastify.register((instance, opts, done) => {
   instance.decorate('util', (a, b) => a + b)
-  console.log(instance.util('that is ', ' awesome'))
+  console.log(instance.util('that is ', 'awesome'))
 
   done()
 })
 
 fastify.register((instance, opts, done) => {
-  console.log(instance.util('that is ', ' awesome')) // this will throw an error
+  console.log(instance.util('that is ', 'awesome')) // This will throw an error
 
   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 get deeper on this: when using the `register` api you will create a new context every time and this avoids situations like the one mentioned few line above. But pay attention, the encapsulation works only for the ancestors and the brothers, but not for the sons.
+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. 
 ```js
 fastify.register((instance, opts, done) => {
   instance.decorate('util', (a, b) => a + b)
-  console.log(instance.util('that is ', ' awesome'))
+  console.log(instance.util('that is ', 'awesome'))
 
   fastify.register((instance, opts, done) => {
-    console.log(instance.util('that is ', ' awesome')) // this will not throw an error
+    console.log(instance.util('that is ', 'awesome')) // This will not throw an error
     done()
   })
 
@@ -106,14 +107,14 @@ fastify.register((instance, opts, done) => {
 })
 
 fastify.register((instance, opts, done) => {
-  console.log(instance.util('that is ', ' awesome')) // this will throw an error
+  console.log(instance.util('that is ', 'awesome')) // This will throw an error
 
   done()
 })
 ```
-*Take home message: if you need that an utility is available in every part of your application, pay attention that is declared at the root scope of your application. Otherwise you can use `fastify-plugin` utility as described [here](#distribution).*
+*Take home message: if you need an utility which is available in every part of your application, take care that it's declared in the root scope of your application. If that's not an option you can use the `fastify-plugin` utility as described [here](#distribution).*
 
-`decorate` is not the unique api that you can use to extend the server functionalities, you can also use `decorateRequest` and `decorateReply`.
+`decorate` is not the only API that you can use to extend the server functionality, you can also use `decorateRequest` and `decorateReply`.
 
 *`decorateRequest` and `decorateReply`? Why do we need them if we already have `decorate`?*<br>
 Good question, we added them to make Fastify more developer-friendly. Let's see an example:
@@ -128,10 +129,10 @@ fastify.get('/html', (request, reply) => {
     .send(fastify.html({ hello: 'world' }))
 })
 ```
-It works, but it can be way better!
+It works, but it could be way better!
 ```js
 fastify.decorateReply('html', function (payload) {
-  this.type('text/html') // this is the 'Reply' object
+  this.type('text/html') // This is the 'Reply' object
   this.send(generateHtml(payload))
 })
 
@@ -161,7 +162,7 @@ fastify.decorateRequest('setHeader', function (header) {
   this.isHappy = this.headers[header]
 })
 
-fastify.decorateRequest('isHappy', false) // this will be added to the Request object prototype, yay speed!
+fastify.decorateRequest('isHappy', false) // This will be added to the Request object prototype, yay speed!
 
 fastify.addHook('preHandler', (request, reply, done) => {
   request.setHeader('happy')
@@ -173,7 +174,7 @@ fastify.get('/happiness', (request, reply) => {
 })
 ```
 
-We've seen how to extend server functionality and how handle the encapsulation system, but what if you need to add a function that must be executed every time that the server "[emits](https://github.com/fastify/fastify/blob/master/docs/Lifecycle.md)" an event?
+We've seen how to extend server functionality and how to handle the encapsulation system, but what if you need to add a function that must be executed every time when the server "[emits](https://github.com/fastify/fastify/blob/master/docs/Lifecycle.md)" an event?
 
 <a name="hooks"></a>
 ## Hooks
@@ -191,9 +192,9 @@ fastify.get('/plugin2', (request, reply) => {
   reply.send(request)
 })
 ```
-I think we all agree that this is terrible. Code repeat, awful readability and it cannot scale.
+I think we all agree that this is terrible. Repeated code, awful readability and it cannot scale.
 
-So what can you do to avoid this annoying issue? Yes, you are right, use an [hook](https://github.com/fastify/fastify/blob/master/docs/Hooks.md)!<br>
+So what can you do to avoid this annoying issue? Yes, you are right, use a [hook](https://github.com/fastify/fastify/blob/master/docs/Hooks.md)!<br>
 ```js
 fastify.decorate('util', (request, key, value) => { request[key] = value })
 
@@ -210,8 +211,8 @@ fastify.get('/plugin2', (request, reply) => {
   reply.send(request)
 })
 ```
-Now for every request you will run your utility, it is obvious that you can register as many hooks as you need.<br>
-It can happen that you want a hook that must be executed just for a subset of routes, how can you do that?  Yep, encapsulation!
+Now for every request, you will run your utility. Obviously you can register as many hooks as you need.<br>
+Sometimes you want a hook that should be executed for just a subset of routes, how can you do that? Yep, encapsulation!
 
 ```js
 fastify.register((instance, opts, done) => {
@@ -235,13 +236,13 @@ fastify.get('/plugin2', (request, reply) => {
 ```
 Now your hook will run just for the first route!
 
-As you probably noticed at this time, `request` and `reply` are not the standard Nodejs *request* and *response* objects, but Fastify's objects.<br>
+As you probably noticed by now, `request` and `reply` are not the standard Nodejs *request* and *response* objects, but Fastify's objects.<br>
 
-<a name="middlewares"></a>
-## Middlewares
-Fastify [supports](https://github.com/fastify/fastify/blob/master/docs/Middlewares.md) out of the box Express/Restify/Connect middlewares, this means that you can just drop-in your old code and it will work! *(faster, by the way)*<br>
-Let's say that you are arriving from Express, and you already have some Middleware that does exactly what you need, and you don't want to redo all the work.
-How we can do that? Checkout our middlewares engine, [middie](https://github.com/fastify/middie).
+<a name="middleware"></a>
+## Middleware
+Fastify [supports](https://github.com/fastify/fastify/blob/master/docs/Middleware.md) Express/Restify/Connect middleware out-of-the-box, which means that you can just drop-in your old code and it will work! *(faster, by the way)*<br>
+Let's say that you are arriving from Express, and you already have some Middleware which does exactly what you need, and you don't want to redo all the work.
+How we can do that? Check out our middleware engine, [middie](https://github.com/fastify/middie).
 ```js
 const yourMiddleware = require('your-middleware')
 fastify.use(yourMiddleware)
@@ -249,13 +250,12 @@ fastify.use(yourMiddleware)
 
 <a name="distribution"></a>
 ## How to handle encapsulation and distribution
-Perfect, now you know (almost) all the tools that you can use to extend Fastify. But probably there is something you noted when trying out your code.<br>
-How can you distribute your code?
+Perfect, now you know (almost) all of the tools that you can use to extend Fastify. But chances are that you came across one big issue: how is distribution handled?
 
-The preferred way to distribute a utility is to wrap all your code inside a `register`, in this way your plugin can support an asynchronous bootstrap *(since `decorate` is a synchronous api)*, in the case of a database connection for example.
+The preferred way to distribute a utility is to wrap all your code inside a `register`, in this way your plugin can support asynchronous bootstrapping *(since `decorate` is a synchronous API)*, in the case of a database connection for example.
 
-*Wait, what? Didn't you tell me that `register` creates an encapsulation and that what I create inside there will not be available outside?*<br>
-Yes, I said that. But what I didn't tell you, is that you can tell to Fastify to avoid this behavior, with the [`fastify-plugin`](https://github.com/fastify/fastify-plugin) module.
+*Wait, what? Didn't you tell me that `register` creates an encapsulation and that the stuff I create inside will not be available outside?*<br>
+Yes, I said that. But what I didn't tell you, is that you can tell to Fastify to avoid this behaviour, with the [`fastify-plugin`](https://github.com/fastify/fastify-plugin) module.
 ```js
 const fp = require('fastify-plugin')
 const dbClient = require('db-client')
@@ -269,7 +269,7 @@ function dbPlugin (fastify, opts, done) {
 
 module.exports = fp(dbPlugin)
 ```
-You can also tell to `fastify-plugin` to check the installed version of Fastify, in case of you need a specific api.
+You can also tell `fastify-plugin` to check the installed version of Fastify, in case you need a specific API.
 
 As we mentioned earlier, Fastify starts loading its plugins __after__ `.listen()`, `.inject()` or `.ready()` are called and as such, __after__ they have been declared. This means that, even though the plugin may inject variables to the external fastify instance via [`decorate`](https://github.com/fastify/fastify/blob/master/docs/Decorators.md), the decorated variables will not be accessible before calling `.listen()`, `.inject()` or `.ready()`.
 
@@ -295,14 +295,14 @@ In the above example, the `parent` variable of the function passed in as the sec
 
 <a name="handle-errors"></a>
 ## Handle errors
-It can happen that one of your plugins could fail during the startup. Maybe you expect it and you have a custom logic that will be triggered in that case. How can you do this?
-The `after` api is what you need. `after` simply registers a callback that will be executed just after a register, and it can take up to three parameters.<br>
-The callback changes based on the parameters your are giving:
+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?
+The `after` API is what you need. `after` simply registers a callback that will be executed just after a register, and it can take up to three parameters.<br>
+The callback changes based on the parameters you are giving:
 
 1. If no parameter is given to the callback and there is an error, that error will be passed to the next error handler.
 1. If one parameter is given to the callback, that parameter will be the error object.
 1. If two parameters are given to the callback, the first will be the error object, the second will be the done callback.
-1. If three parameters are given to the callback, the first will be the error object, the second will be the top level context unless you have specified both server and override, in that case the context will be what the override returns, and the third the done callback.
+1. If three parameters are given to the callback, the first will be the error object, the second will be the top-level context unless you have specified both server and override, in that case, the context will be what the override returns, and the third the done callback.
 
 Let's see how to use it:
 ```js
@@ -317,14 +317,14 @@ fastify
 ## Let's start!
 Awesome, now you know everything you need to know about Fastify and its plugin system to start building your first plugin, and please if you do, tell us! We will add it to the [*ecosystem*](https://github.com/fastify/fastify#ecosystem) section of our documentation!
 
-If you want to see some real world example, checkout:
+If you want to see some real-world example, check out:
 - [`point-of-view`](https://github.com/fastify/point-of-view)
 Templates rendering (*ejs, pug, handlebars, marko*) plugin support for Fastify.
 - [`fastify-mongodb`](https://github.com/fastify/fastify-mongodb)
-Fastify MongoDB connection plugin, with this you can share the same MongoDb connection pool in every part of your server.
+Fastify MongoDB connection plugin, with this you can share the same MongoDB connection pool in every part of your server.
 - [`fastify-multipart`](https://github.com/fastify/fastify-multipart)
 Multipart support for Fastify
 - [`fastify-helmet`](https://github.com/fastify/fastify-helmet) Important security headers for Fastify
 
 
-*Do you feel it's missing something here? Let us know! :)*
+*Do you feel like something is missing here? Let us know! :)*

package/docs/Plugins.md

@@ -16,8 +16,11 @@ 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**
+
 It is possible that Fastify will directly support other options in the future. Thus, to avoid collisions, a plugin should consider namespacing its options. For example, a plugin `foo` might be registered like so:
 
 ```js

package/docs/Reply.md

@@ -4,7 +4,9 @@
 - [Reply](#reply)
   - [Introduction](#introduction)
   - [.code(statusCode)](#codestatuscode)
+  - [.statusCode](#statusCode)
   - [.header(key, value)](#headerkey-value)
+  - [.headers(object)](#headersobject)
   - [.getHeader(key)](#getheaderkey)
   - [.removeHeader(key)](#removeheaderkey)
   - [.hasHeader(key)](#hasheaderkey)
@@ -22,7 +24,8 @@
     - [Errors](#errors)
     - [Type of the final payload](#type-of-the-final-payload)
     - [Async-Await and Promises](#async-await-and-promises)
-  
+  - [.then](#then)
+
 <a name="introduction"></a>
 ### Introduction
 The second parameter of the handler function is `Reply`.
@@ -31,7 +34,9 @@ and properties:
 
 - `.code(statusCode)` - Sets the status code.
 - `.status(statusCode)` - An alias for `.code(statusCode)`.
+- `.statusCode` - Read and set the HTTP status code.
 - `.header(name, value)` - Sets a response header.
+- `.headers(object)` - Sets all the keys of the object as a response headers.
 - `.getHeader(name)` - Retrieve value of already set header.
 - `.removeHeader(key)` - Remove the value of a previously set header.
 - `.hasHeader(name)` - Determine if a header has been set.
@@ -43,7 +48,8 @@ and properties:
 - `.send(payload)` - Sends the payload to the user, could be a plain text, a buffer, JSON, stream, or an Error object.
 - `.sent` - A boolean value that you can use if you need to know if `send` has already been called.
 - `.res` - The [`http.ServerResponse`](https://nodejs.org/dist/latest/docs/api/http.html#http_class_http_serverresponse) from Node core.
-- `.log` - the logger instance of the incoming request
+- `.log` - The logger instance of the incoming request.
+- `.request` - The incoming request.
 
 ```js
 fastify.get('/', options, function (request, reply) {
@@ -67,6 +73,15 @@ fastify.get('/', {config: {foo: 'bar'}}, function (request, reply) {
 ### .code(statusCode)
 If not set via `reply.code`, the resulting `statusCode` will be `200`.
 
+<a name="statusCode"></a>
+### .statusCode
+This property reads and sets the HTTP status code. It is an alias for `reply.code()` when used as a setter.
+```js
+if (reply.statusCode >= 299) {
+  reply.statusCode = 500
+}
+```
+
 <a name="header"></a>
 ### .header(key, value)
 Sets a response header. If the value is omitted or undefined it is coerced
@@ -74,6 +89,16 @@ to `''`.
 
 For more information, see [`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest/docs/api/http.html#http_response_setheader_name_value).
 
+<a name="headers"></a>
+### .headers(object)
+Sets all the keys of the object as response headers. [`.header`](#headerkey-value) will be called under the hood.
+```js
+reply.headers({
+  'x-foo': 'foo',
+  'x-bar': 'bar'
+})
+```
+
 <a name="getHeader"></a>
 ### .getHeader(key)
 Retrieves the value of a previously set header.
@@ -224,11 +249,12 @@ If you pass to *send* an object that is an instance of *Error*, Fastify will aut
 ```js
 {
   error: String        // the http error message
+  code: String         // the Fastify error code
   message: String      // the user error message
   statusCode: Number   // the http status code
 }
 ```
-You can add some custom property to the Error object, such as `statusCode` and `headers`, that will be used to enhance the http response.<br>
+You can add some custom property to the Error object, such as `headers`, that will be used to enhance the http response.<br>
 *Note: If you are passing an error to `send` and the statusCode is less than 400, Fastify will automatically set it at 500.*
 
 Tip: you can simplify errors by using the [`http-errors`](https://npm.im/http-errors) module or [`fastify-sensible`](https://github.com/fastify/fastify-sensible) plugin to generate errors:
@@ -307,3 +333,21 @@ fastify.get('/teapot', async function (request, reply) => {
 ```
 
 If you want to know more please review [Routes#async-await](https://github.com/fastify/fastify/blob/master/docs/Routes.md#async-await).
+
+<a name="then"></a>
+### .then(fullfilled, rejected)
+
+As the name suggests, a `Reply` object can be awaited upon, i.e. `await reply` will wait until the reply is sent.
+The `await` syntax calls the `reply.then()`.
+
+`reply.then(fullfilled, rejected)` accepts two parameters:
+
+- `fullfilled` will be called when a response has been fully sent,
+- `rejected` will be called if the underlying stream had an error, e.g.
+the socket has been destroyed.
+
+For more details, see:
+
+- https://github.com/fastify/fastify/issues/1864 for the discussion about this feature
+- https://promisesaplus.com/ for the definition of thenables
+- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then for the signature