fastify 3.26.0 → 4.0.0-alpha.1

package/README.md

@@ -1,5 +1,4 @@
-<div align="center">
-  <a href="https://fastify.io/">
+<div align="center"> <a href="https://fastify.io/">
     <img src="https://github.com/fastify/graphics/raw/HEAD/fastify-landscape-outlined.svg" width="650" height="auto"/>
   </a>
 </div>
@@ -45,6 +44,8 @@ How can you efficiently handle the resources of your server, knowing that you ar
 
 Enter Fastify. Fastify is a web framework highly focused on providing the best developer experience with the least overhead and a powerful plugin architecture. It is inspired by Hapi and Express and as far as we know, it is one of the fastest web frameworks in town.
 
+This branch refers to the upcoming Fastify v4 release. Check out the [v3.x](https://github.com/fastify/fastify/tree/v3.x) branch for v3.
+
 ### Quick start
 
 Create a folder and make it your current working directory:
@@ -88,11 +89,11 @@ If installing in an existing project, then Fastify can be installed into the pro
 
 Install with npm:
 ```sh
-npm i fastify --save
+npm i fastify@next --save
 ```
 Install with yarn:
 ```sh
-yarn add fastify
+yarn add fastify@next
 ```
 
 ### Example

package/build/build-error-serializer.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const FJS = require('fast-json-stringify')
+const path = require('path')
+const fs = require('fs')
+
+const debugCompiled = FJS({
+  type: 'object',
+  properties: {
+    statusCode: { type: 'number' },
+    code: { type: 'string' },
+    error: { type: 'string' },
+    message: { type: 'string' }
+  }
+}, { debugMode: true })
+
+const file = path.join(__dirname, '..', 'lib', 'error-serializer.js')
+const rawString = debugCompiled.toString()
+
+const moduleCode = `// This file is autogenerated by build/build-error-serializer.js, do not edit
+/* istanbul ignore file */
+module.exports = $main
+${rawString.slice(5)}
+`
+
+fs.writeFileSync(file, moduleCode)
+console.log(`Saved ${file} file successfully`)

package/build/build-validation.js

@@ -1,20 +1,30 @@
 'use strict'
 
-const Ajv = require('ajv')
+const AjvStandaloneCompiler = require('@fastify/ajv-compiler/standalone')
+const { _ } = require('ajv')
 const fs = require('fs')
 const path = require('path')
-const pack = require('ajv-pack')
 
-const ajv = new Ajv({
-  sourceCode: true, // this option is required by ajv-pack
-  removeAdditional: true,
-  useDefaults: true,
-  coerceTypes: true
+const factory = AjvStandaloneCompiler({
+  readMode: false,
+  storeFunction (routeOpts, schemaValidationCode) {
+    const moduleCode = `// This file is autogenerated by ${__filename.replace(__dirname, 'build')}, do not edit
+/* istanbul ignore file */
+${schemaValidationCode}
+
+module.exports.defaultInitOptions = ${JSON.stringify(defaultInitOptions)}
+`
+
+    const file = path.join(__dirname, '..', 'lib', 'configValidator.js')
+    fs.writeFileSync(file, moduleCode)
+    console.log(`Saved ${file} file successfully`)
+  }
 })
 
 const defaultInitOptions = {
   connectionTimeout: 0, // 0 sec
-  keepAliveTimeout: 5000, // 5 sec
+  keepAliveTimeout: 72000, // 72 seconds
+  forceCloseConnections: false, // keep-alive connections
   maxRequestsPerSocket: 0, // no limit
   requestTimeout: 0, // no limit
   bodyLimit: 1024 * 1024, // 1 MiB
@@ -28,27 +38,17 @@ const defaultInitOptions = {
   pluginTimeout: 10000,
   requestIdHeader: 'request-id',
   requestIdLogLabel: 'reqId',
-  http2SessionTimeout: 5000
+  http2SessionTimeout: 72000, // 72 seconds
+  exposeHeadRoutes: true
 }
 
-function customRule0 (schemaParamValue, validatedParamValue, validationSchemaObject, currentDataPath, validatedParamObject, validatedParam) {
-  validatedParamObject[validatedParam] = schemaParamValue
-  return true
-}
-
-// We add a keyword that allow us to set default values
-ajv.addKeyword('setDefaultValue', {
-  modifying: true,
-  validate: customRule0,
-  errors: false
-})
-
 const schema = {
   type: 'object',
   additionalProperties: false,
   properties: {
     connectionTimeout: { type: 'integer', default: defaultInitOptions.connectionTimeout },
     keepAliveTimeout: { type: 'integer', default: defaultInitOptions.keepAliveTimeout },
+    forceCloseConnections: { type: 'boolean', default: defaultInitOptions.forceCloseConnections },
     maxRequestsPerSocket: { type: 'integer', default: defaultInitOptions.maxRequestsPerSocket, nullable: true },
     requestTimeout: { type: 'integer', default: defaultInitOptions.requestTimeout },
     bodyLimit: { type: 'integer', default: defaultInitOptions.bodyLimit },
@@ -86,6 +86,7 @@ const schema = {
     requestIdHeader: { type: 'string', default: defaultInitOptions.requestIdHeader },
     requestIdLogLabel: { type: 'string', default: defaultInitOptions.requestIdLogLabel },
     http2SessionTimeout: { type: 'integer', default: defaultInitOptions.http2SessionTimeout },
+    exposeHeadRoutes: { type: 'boolean', default: defaultInitOptions.exposeHeadRoutes },
     // deprecated style of passing the versioning constraint
     versioning: {
       type: 'object',
@@ -113,18 +114,31 @@ const schema = {
   }
 }
 
-const validate = ajv.compile(schema)
-
-const moduleCode = `// This file is autogenerated by ${__filename.replace(__dirname, 'build')}, do not edit
-/* istanbul ignore file */
-// constant needed for customRule0 to work
-const self = {}
-
-${pack(ajv, validate)}
-
-${customRule0.toString()}
-
-module.exports.defaultInitOptions = ${JSON.stringify(defaultInitOptions)}
-`
+const compiler = factory({}, {
+  customOptions: {
+    code: {
+      source: true,
+      lines: true,
+      optimize: 3
+    },
+    removeAdditional: true,
+    useDefaults: true,
+    coerceTypes: true,
+    keywords: [
+      {
+        keyword: 'setDefaultValue',
+        $data: true,
+        // error: false,
+        modifying: true,
+        valid: true,
+        code (keywordCxt) {
+          const { gen, it, schemaValue } = keywordCxt
+          const logicCode = gen.assign(_`${it.parentData}[${it.parentDataProperty}]`, schemaValue)
+          return logicCode
+        }
+      }
+    ]
+  }
+})
 
-fs.writeFileSync(path.join(__dirname, '..', 'lib', 'configValidator.js'), moduleCode)
+compiler({ schema })

package/docs/Guides/Ecosystem.md

@@ -59,7 +59,7 @@ section.
 - [`fastify-http-proxy`](https://github.com/fastify/fastify-http-proxy) Proxy
   your HTTP requests to another server, with hooks.
 - [`fastify-jwt`](https://github.com/fastify/fastify-jwt) JWT utils for Fastify,
-  internally uses [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken).
+  internally uses [fast-jwt](https://github.com/nearform/fast-jwt).
 - [`fastify-leveldb`](https://github.com/fastify/fastify-leveldb) Plugin to
   share a common LevelDB connection across Fastify.
 - [`fastify-mongodb`](https://github.com/fastify/fastify-mongodb) Fastify
@@ -130,6 +130,7 @@ section.
 - [`@immobiliarelabs/fastify-metrics`](https://github.com/immobiliare/fastify-metrics)
   Minimalistic and opinionated plugin that collects usage/process metrics and
   dispatches to [statsd](https://github.com/statsd/statsd).
+- [`@immobiliarelabs/fastify-sentry`](https://github.com/immobiliare/fastify-sentry) Sentry errors handler that just works! Install, add your DSN and you're good to go!
 - [`@mgcrea/fastify-graceful-exit`](https://github.com/mgcrea/fastify-graceful-exit)
   A plugin to close the server gracefully
 - [`@mgcrea/fastify-request-logger`](https://github.com/mgcrea/fastify-request-logger)

package/docs/Guides/Prototype-Poisoning.md

@@ -117,7 +117,7 @@ an `id` ), and then pass it to our validation library, anything passed through
 via `__proto__` would sneak in undetected.
 
 ### Oh joi!
-<a id="pp-oh-joi">
+<a id="pp-oh-joi"></a>
 
 The first question is, of course, why does the validation module **joi** ignore
 the prototype and let potentially harmful data through? We asked ourselves the
@@ -383,9 +383,9 @@ Because this work is important, I decided to try and make it not just
 financially sustainable but to grow and expand it. There is so much to improve.
 This is exactly what motivates me to implement the new [commercial licensing
 plan](https://web.archive.org/web/20190201220503/https://hueniverse.com/on-hapi-licensing-a-preview-f982662ee898)
-coming in March. You can ready more about it
+coming in March. You can read more about it
 [here](https://web.archive.org/web/20190201220503/https://hueniverse.com/on-hapi-licensing-a-preview-f982662ee898).
 
 Of all the time consuming things, security is at the very top. I hope this story
-successful conveyed not just the technical details, but also the human drama and
+successfully conveyed not just the technical details, but also the human drama and
 what it takes to keep the web secure.

package/docs/Migration-Guide-V4.md

@@ -0,0 +1,12 @@
+# V4 Migration Guide
+
+This guide is intended to help with migration from Fastify v3 to v4.
+
+Before migrating to v4, please ensure that you have fixed all deprecation warningx from v3.
+All v3 deprecations have been removed and they will no longer work after upgrading.
+
+## Breaking Changes
+
+### Deprecation of `app.use()`
+
+Starting this version of Fastify, we have deprecated the use of `app.use()`. We have decided not to support the use of middlewares. Both [`middie`](https://github.com/fastify/middie) and [`fastify-express`](https://github.com/fastify/fastify-express) will still be there and maintained. Use Fastify's [hooks](./Hooks.md) instead.

package/docs/Reference/ContentTypeParser.md

@@ -2,7 +2,10 @@
 
 ## `Content-Type` Parser
 Natively, Fastify only supports `'application/json'` and `'text/plain'` content
-types. The default charset is `utf-8`. If you need to support different content
+types. If the content type is not one of these, a `FST_ERR_CTP_INVALID_MEDIA_TYPE` 
+error will be thrown.
+
+The default charset is `utf-8`. If you need to support different content
 types, you can use the `addContentTypeParser` API. *The default JSON and/or
 plain text parser can be changed or removed.*
 
@@ -18,6 +21,9 @@ available only in that scope and its children.
 Fastify automatically adds the parsed request payload to the [Fastify
 request](./Request.md) object which you can access with `request.body`.
 
+Note that for `GET` and `HEAD` requests the payload is never parsed. For `OPTIONS` and `DELETE` requests the payload is only parsed if 
+the content type is given in the content-type header. If it is not given, the [catch-all](#catch-all) parser is not executed as with `POST`, `PUT` and `PATCH`, but the payload is simply not parsed.
+
 ### Usage
 ```js
 fastify.addContentTypeParser('application/jsoff', function (request, payload, done) {
@@ -87,6 +93,7 @@ if (!fastify.hasContentTypeParser('application/jsoff')){
 }
 ```
 
+=======
 #### removeContentTypeParser
 
 With `removeContentTypeParser` a single or an array of content types can be

package/docs/Reference/Errors.md

@@ -56,9 +56,19 @@ From the [Hooks documentation](./Hooks.md#manage-errors-from-a-hook):
 > `done()` and Fastify will automatically close the request and send the
 > appropriate error code to the user.
 
-If you have defined a custom error handler for using `setErrorHandler` the error
-will be routed there. otherwise, it will be routed to Fastify’s generic error
-handler.
+When a custom error handler has been defined through
+[`setErrorHandler`](./Server.md#seterrorhandler), the custom error handler will
+receive the error passed to the `done()` callback (or through other supported
+automatic error handling mechanisms). If `setErrorHandler` has been used
+multiple times to define multiple handlers, the error will be routed to the most
+precedent handler defined within the error [encapsulation context](./Encapsulation.md).
+Error handlers are fully encapsulated, so a `setErrorHandler` call within a
+plugin will limit the error handler to that plugin's context.
+
+The root error handler is Fastify's generic error handler. This error handler
+will use the headers and status code in the `Error` object, if they exist. The
+headers and status code will not be automatically set if a custom error handler
+is provided.
 
 Some things to consider in your custom error handler:
 
@@ -70,13 +80,12 @@ Some things to consider in your custom error handler:
     headers (no serialization)
 
 - You can throw a new error in your custom error handler
-  - errors (new error or the received error parameter re-thrown) - will trigger
-    the `onError` lifecycle hook and send the error to the user
+	- errors (new error or the received error parameter re-thrown) - will call the parent `errorHandler`.
+  - `onError` hook will be triggered once only for the first error being thrown.
   - an error will not be triggered twice from a lifecycle hook - Fastify
     internally monitors the error invocation to avoid infinite loops for errors
     thrown in the reply phases of the lifecycle. (those after the route handler)
 
-
 ### Fastify Error Codes
 <a id="fastify-error-codes"></a>
 
@@ -85,6 +94,12 @@ Some things to consider in your custom error handler:
 
 The router received an invalid url.
 
+<a name="FST_ERR_DUPLICATED_ROUTE"></a>
+#### FST_ERR_DUPLICATED_ROUTE
+
+The HTTP method already has a registered controller for that URL
+
+<a name="FST_ERR_CTP_ALREADY_PRESENT"></a>
 #### FST_ERR_CTP_ALREADY_PRESENT
 <a id="FST_ERR_CTP_ALREADY_PRESENT"></a>
 
@@ -199,3 +214,33 @@ You cannot use `send` inside the `onError` hook.
 <a id="FST_ERR_SEND_UNDEFINED_ERR"></a>
 
 Undefined error has occurred.
+
+<a name="FST_ERR_PLUGIN_NOT_VALID"></a>
+#### FST_ERR_PLUGIN_NOT_VALID
+
+Plugin must be a function or a promise.
+
+<a name="FST_ERR_PLUGIN_TIMEOUT"></a>
+#### FST_ERR_PLUGIN_TIMEOUT
+
+Plugin did not start in time. Default timeout (in millis): `10000`
+
+<a name="FST_ERR_HOOK_TIMEOUT"></a>
+#### FST_ERR_HOOK_TIMEOUT
+
+A callback for a hook timed out
+
+<a name="FST_ERR_ROOT_PLG_BOOTED"></a>
+#### FST_ERR_ROOT_PLG_BOOTED
+
+Root plugin has already booted (mapped directly from `avvio`)
+
+<a name="FST_ERR_PARENT_PLUGIN_BOOTED"></a>
+#### FST_ERR_PARENT_PLUGIN_BOOTED
+
+Impossible to load plugin because the parent (mapped directly from `avvio`)
+
+<a name="FST_ERR_PLUGIN_CALLBACK_NOT_FN"></a>
+#### FST_ERR_PLUGIN_CALLBACK_NOT_FN
+
+Callback for a hook is not a function (mapped directly from `avvio`)

package/docs/Reference/Hooks.md

@@ -65,7 +65,7 @@ fastify.addHook('onRequest', async (request, reply) => {
 ```
 
 **Notice:** in the [onRequest](#onrequest) hook, `request.body` will always be
-`null`, because the body parsing happens before the
+`undefined`, because the body parsing happens before the
 [preValidation](#prevalidation) hook.
 
 ### preParsing
@@ -95,7 +95,7 @@ fastify.addHook('preParsing', async (request, reply, payload) => {
 ```
 
 **Notice:** in the [preParsing](#preparsing) hook, `request.body` will always be
-`null`, because the body parsing happens before the
+`undefined`, because the body parsing happens before the
 [preValidation](#prevalidation) hook.
 
 **Notice:** you should also add a `receivedEncodedLength` property to the
@@ -103,10 +103,6 @@ returned stream. This property is used to correctly match the request payload
 with the `Content-Length` header value. Ideally, this property should be updated
 on each received chunk.
 
-**Notice**: The old syntaxes `function(request, reply, done)` and `async
-function(request, reply)` for the parser are still supported but they are
-deprecated.
-
 ### preValidation
 
 If you are using the `preValidation` hook, you can change the payload before it
@@ -322,7 +318,7 @@ fastify.addHook('onRequest', (request, reply, done) => {
 fastify.addHook('preHandler', async (request, reply) => {
   await something()
   reply.send({ hello: 'world' })
-  return reply // optional in this case, but it is a good practice
+  return reply // mandatory, so the request is not executed further
 })
 ```
 
@@ -419,6 +415,7 @@ fastify.addHook('onClose', async (instance) => {
 Triggered when a new route is registered. Listeners are passed a `routeOptions`
 object as the sole parameter. The interface is synchronous, and, as such, the
 listeners are not passed a callback. This hook is encapsulated.
+
 ```js
 fastify.addHook('onRoute', (routeOptions) => {
   //Some code

package/docs/Reference/LTS.md

@@ -48,6 +48,7 @@ A "month" is defined as 30 consecutive days.
 | 1.0.0   | 2018-03-06   | 2019-09-01      | 6, 8, 9, 10, 11      |
 | 2.0.0   | 2019-02-25   | 2021-01-31      | 6, 8, 10, 12, 14     |
 | 3.0.0   | 2020-07-07   | TBD             | 10, 12, 14, 16       |
+| 4.0.0   | TBD          | TBD             | 14, 16               |
 
 ### CI tested operating systems
 <a id="supported-os"></a>
@@ -60,10 +61,10 @@ YAML workflow labels below:
 
 | OS      | YAML Workflow Label    | Package Manager           | Node.js      |
 |---------|------------------------|---------------------------|--------------|
-| Linux   | `ubuntu-latest`        | npm                       | 10,12,14,16  |
-| Linux   | `ubuntu-18.04`         | yarn,pnpm                 | 10,12        |
-| Windows | `windows-latest`       | npm                       | 10,12,14,16  |
-| MacOS   | `macos-latest`         | npm                       | 10,12,14,16  |
+| Linux   | `ubuntu-latest`        | npm                       | 14,16        |
+| Linux   | `ubuntu-18.04`         | yarn,pnpm                 | 14,16        |
+| Windows | `windows-latest`       | npm                       | 14,16        |
+| MacOS   | `macos-latest`         | npm                       | 14,16        |
 
 Using [yarn](https://yarnpkg.com/) might require passing the `--ignore-engines`
 flag.

package/docs/Reference/Reply.md

@@ -59,12 +59,10 @@ object that exposes the following functions and properties:
   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.
+- `.hijack()` - interrupt the normal request lifecycle.
 - `.raw` - The
   [`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
   from Node core.
-- `.res` *(deprecated, use `.raw` instead)* - The
-  [`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
-  from Node core.
 - `.log` - The logger instance of the incoming request.
 - `.request` - The incoming request.
 - `.context` - Access the [Request's context](./Request.md) property.
@@ -125,6 +123,8 @@ fastify.get('/', async function (req, rep) {
 Sets a response header. If the value is omitted or undefined, it is coerced to
 `''`.
 
+> Note: the header's value must be properly encoded using [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or similar modules such as [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid characters will result in a 500 `TypeError` response.
+
 For more information, see
 [`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_response_setheader_name_value).
 
@@ -205,6 +205,8 @@ Returns a boolean indicating if the specified header has been set.
 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`).
 
+> Note: the input URL must be properly encoded using [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or similar modules such as [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid URLs will result in a 500 `TypeError` response.
+
 Example (no `reply.code()` call) sets status code to `302` and redirects to
 `/home`
 ```js
@@ -315,39 +317,38 @@ Another example of the misuse of `Reply.raw` is explained in
 
 As the name suggests, `.sent` is a property to indicate if a response has been
 sent via `reply.send()`.
+It will also be `true` in case `reply.hijack()` was used.
 
 In case a route handler is defined as an async function or it returns a promise,
-it is possible to set `reply.sent = true` to indicate that the automatic
+it is possible to call `reply.hijack()` to indicate that the automatic
 invocation of `reply.send()` once the handler promise resolve should be skipped.
-By setting `reply.sent = true`, an application claims full responsibility for
+By calling `reply.hijack()`, an application claims full responsibility for
 the low-level request and response. Moreover, hooks will not be invoked.
 
-As an example:
+*Modifying the `.sent` property directly is deprecated. Please use the aformentioned
+`.hijack()` method to achieve the same effect.*
+
+<a name="hijack"></a>
+### .hijack()
+Sometimes you might need to halt the execution of the normal request lifecycle and
+handle sending the response manually.
+
+To achieve this, Fastify provides the `reply.hijack()` method that can be called
+during the request lifecycle (At any point before `reply.send()` is called), and
+allows you to prevent Fastify from sending the response, and from running the
+remaining hooks (and user handler if the reply was hijacked before).
 
 ```js
 app.get('/', (req, reply) => {
-  reply.sent = true
+  reply.hijack()
   reply.raw.end('hello world')
 
   return Promise.resolve('this will be skipped')
 })
 ```
 
-If the handler rejects, the error will be logged.
-
-### .hijack()
-<a id="hijack"></a>
-
-Sometimes you might need to halt the execution of the normal request lifecycle
-and handle sending the response manually.
-
-To achieve this, Fastify provides the `reply.hijack()` method that can be called
-during the request lifecycle (At any point before `reply.send()` is called), and
-allows you to prevent Fastify from sending the response, and from running the
-remaining hooks (and user handler if the reply was hijacked before).
-
-NB (*): If `reply.raw` is used to send a response back to the user, `onResponse`
-hooks will still be executed
+If `reply.raw` is used to send a response back to the user, the `onResponse`
+hooks will still be executed.
 
 ### .send(data)
 <a id="send"></a>

package/docs/Reference/Request.md

@@ -12,10 +12,8 @@ Request is a core Fastify object containing the following fields:
 - `params` - the params matching the URL
 - [`headers`](#headers) - the headers getter and setter
 - `raw` - the incoming HTTP request from Node core
-- `req` *(deprecated, use `.raw` instead)* - the incoming HTTP request from Node
-  core
 - `server` - The Fastify server instance, scoped to the current [encapsulation
-  context](./Encapsulation.md)
+>>>>>>> main:docs/Reference/Request.md
 - `id` - the request ID
 - `log` - the logger instance of the incoming request
 - `ip` - the IP address of the incoming request

package/docs/Reference/Routes.md

@@ -32,7 +32,7 @@ fastify.route(options)
 ### Routes options
 <a id="options"></a>
 
-* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`,
+*`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
@@ -54,6 +54,7 @@ fastify.route(options)
   option, make sure to define it before the `GET` route.
 * `attachValidation`: attach `validationError` to request, if there is a schema
   validation error, instead of sending the error to the error handler.
+  The default [error format](https://ajv.js.org/api.html#error-objects) is the Ajv one.
 * `onRequest(request, reply, done)`: a [function](./Hooks.md#onrequest) as soon
   that a request is received, it could also be an array of functions.
 * `preParsing(request, reply, done)`: a [function](./Hooks.md#preparsing) called
@@ -280,11 +281,14 @@ As you can see, we are not calling `reply.send` to send back the data to the
 user. You just need to return the body and you are done!
 
 If you need it you can also send back the data to the user with `reply.send`.
+In this case do not forget to `return reply` or `await reply` in your `async`
+handler or you will introduce a race condition in certain situations.
+
 ```js
 fastify.get('/', options, async function (request, reply) {
   var data = await getData()
   var processed = await processData(data)
-  reply.send(processed)
+  return reply.send(processed)
 })
 ```
 
@@ -316,24 +320,27 @@ fastify.get('/', options, async function (request, reply) {
   first one that happens takes precedence, the second value will be discarded,
   and a *warn* log will also be emitted because you tried to send a response
   twice.
+* Calling `reply.send()` outside of the promise is possible, but requires
+  special attention. For more details read
+  [promise-resolution](#promise-resolution).
 * You cannot return `undefined`. For more details read
   [promise-resolution](#promise-resolution).
 
 ### Promise resolution
 <a id="promise-resolution"></a>
 
-If your handler is an `async` function or returns a promise, you should be aware
-of a special behavior that is necessary to support the callback and promise
-control-flow. If the handler's promise is resolved with `undefined`, it will be
-ignored causing the request to hang and an *error* log to be emitted.
+If your handler is an `async` function or returns a promise, you should be aware of
+a special behaviour which is necessary to support the callback and promise
+control-flow. When the handler's promise is resolved, the reply will be
+automatically sent with its value unless you explicitly await or return `reply`
+in your handler.
 
-1. If you want to use `async/await` or promises but return a value with
-   `reply.send`:
-    - **Do not** `return` any value.
+1. If you want to use `async/await` or promises but respond a value with `reply.send`:
+    - **Do** `return reply` / `await reply`.
     - **Do not** forget to call `reply.send`.
 2. If you want to use `async/await` or promises:
     - **Do not** use `reply.send`.
-    - **Do not** return `undefined`.
+    - **Do** return the value that you want to send.
 
 In this way, we can support both `callback-style` and `async-await`, with the
 minimum trade-off. In spite of so much freedom we highly recommend to go with