fastify 2.12.1 → 2.14.1

package/.dependabot/config.yml

@@ -0,0 +1,28 @@
+version: 1
+update_configs:
+  - package_manager: "javascript"
+    directory: "/"
+    update_schedule: "daily"
+    ignored_updates:
+      - match:
+          dependency_name: "autocannon"
+      - match:
+          dependency_name: "boom"
+      - match:
+          dependency_name: "joi"
+      - match:
+          dependency_name: "@types/*"
+      - match:
+          dependency_name: "semver"
+      - match:
+          dependency_name: "tap"
+      - match:
+          dependency_name: "tap-mocha-reporter"
+      - match:
+          dependency_name: "@typescript-eslint/eslint-plugin"
+      - match:
+          dependency_name: "lolex"
+      - match:
+          dependency_name: "pino"
+      - match:
+          dependency_name: "fast-json-stringify"

package/README.md

@@ -16,7 +16,7 @@
 <div align="center">
 
 [![NPM version](https://img.shields.io/npm/v/fastify.svg?style=flat)](https://www.npmjs.com/package/fastify)
-[![NPM downloads](https://img.shields.io/npm/dm/fastify.svg?style=flat)](https://www.npmjs.com/package/fastify) [![Gitter](https://badges.gitter.im/gitterHQ/gitter.svg)](https://gitter.im/fastify)
+[![NPM downloads](https://img.shields.io/npm/dm/fastify.svg?style=flat)](https://www.npmjs.com/package/fastify)
 [![Security Responsible
 Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md)
 
@@ -29,8 +29,47 @@ 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.
 
+### Quick start
+
+Create a folder and make it your current working directory:
+
+```
+mkdir my-app
+cd my-app
+```
+
+Generate a fastify project with `npm init`:
+
+```sh
+npm init fastify
+```
+
+Install dependencies:
+
+```js
+npm install
+```
+
+To start the app in dev mode:
+
+```sh
+npm run dev
+```
+
+For production mode:
+
+```sh
+npm start
+```
+
+Under the hood `npm init` downloads and runs [Fastify Create](https://github.com/fastify/create-fastify),
+which in turn uses the generate functionality of [Fastify CLI](https://github.com/fastify/fastify-cli).
+
+
 ### Install
 
+If installing in an existing project, then Fastify can be installed into the project as a dependency:
+
 Install with npm:
 ```
 npm i fastify --save
@@ -80,29 +119,6 @@ fastify.listen(3000, (err, address) => {
 
 Do you want to know more? Head to the <a href="https://github.com/fastify/fastify/blob/master/docs/Getting-Started.md"><code><b>Getting Started</b></code></a>.
 
-### Quick start with Fastify CLI
-
-Good tools make API development quicker and easier to maintain than doing everything manually.
-
-The [Fastify CLI](https://github.com/fastify/fastify-cli) is a command line interface tool that can create new projects, manage plugins, and perform a variety of development tasks testing and running the application.
-
-The goal in this guide is to build and run a simple Fastify project, using the [Fastify CLI](https://github.com/fastify/fastify-cli), while adhering to the Style Guide recommendations that benefit every Fastify project.
-
-### Example
-
-Open a terminal window.
-
-```
-npm install fastify-cli --global
-```
-
-Generate a new project and default app by running the following command:
-
-```
-fastify generate
-```
-
-For more information, see the [Fastify CLI documentation](https://github.com/fastify/fastify-cli).
 
 ### Fastify v1.x
 
@@ -176,8 +192,8 @@ matters to you.
 - [Live Examples](https://github.com/fastify/example) - Multirepo with a broad set of real working examples.
 
 ## Support
-- [Fastify help](https://github.com/fastify/help)
-- [Gitter Chat](https://gitter.im/fastify)
+Please visit [Fastify help](https://github.com/fastify/help) to view prior
+support issues and to ask new support questions.
 
 ## Team
 
@@ -191,6 +207,7 @@ Team members are listed in alphabetical order.
 ### Fastify Core team
 * [__Tommaso Allevi__](https://github.com/allevo), <https://twitter.com/allevitommaso>, <https://www.npmjs.com/~allevo>
 * [__Ethan Arrowood__](https://github.com/Ethan-Arrowood/), <https://twitter.com/arrowoodtech>, <https://www.npmjs.com/~ethan_arrowood>
+* [__David Mark Clements__](https://github.com/davidmarkclements), <https://twitter.com/davidmarkclem>, <https://www.npmjs.com/~davidmarkclements>
 * [__Matteo Collina__](https://github.com/mcollina), <https://twitter.com/matteocollina>, <https://www.npmjs.com/~matteo.collina>
 * [__Tomas Della Vedova__](https://github.com/delvedor), <https://twitter.com/delvedor>, <https://www.npmjs.com/~delvedor>
 * [__Dustin Deus__](https://github.com/StarpTech), <https://twitter.com/dustindeus>, <https://www.npmjs.com/~starptech>

package/docs/Decorators.md

@@ -2,22 +2,81 @@
 
 ## Decorators
 
-If you need to add functionality to the Fastify instance, the `decorate` API is what you want.
+The decorators API allows customization of the core Fastify objects, such as
+the server instance itself and any request and reply objects used during the
+HTTP request lifecycle. The decorators API can be used to attach any type of
+property to the core objects, e.g. functions, plain objects, or native types.
+
+This API is a *synchronous* API. Attempting to define a decoration
+asynchronously could result in the Fastify instance booting prior to the
+decoration completing its initialization. To avoid this issue, and register an
+asynchronous decoration, the `register` API, in combination with
+`fastify-plugin`, must be used instead. To learn more, see the
+[Plugins](Plugins.md) documentation.
+
+Decorating core objects with this API allows the underlying JavaScript engine
+to optimize handling of the server, request, and reply objects. This is
+accomplished by defining the shape of all such object instances before they are
+instantiated and used. As an example, the following is not recommended because
+it will change the shape of objects during their lifecycle:
 
-The API allows you to add new properties to the Fastify instance. Possible values are not restricted by type and could be functions, objects or strings, for example.
+```js
+// Bad example! Continue reading.
+
+// Attach a user property to the incoming request before the request
+// handler is invoked.
+fastify.addHook('preHandler', function (req, reply, done) {
+  req.user = 'Bob Dylan'
+  done()
+})
+
+// Use the attached user property in the request handler.
+fastify.get('/', function (req, reply) {
+  reply.send(`Hello, ${req.user}`)
+})
+```
+
+Since the above example mutates the request object after it has already
+been instantiated, the JavaScript engine must deoptimize access to the request
+object. By using the decoration API this deoptimization is avoided:
+
+```js
+// Decorate request with a 'user' property
+fastify.decorateRequest('user', '')
+
+// Update our property
+fastify.addHook('preHandler', (req, reply, done) => {
+  req.user = 'Bob Dylan'
+  done()
+})
+// And finally access it
+fastify.get('/', (req, reply) => {
+  reply.send(`Hello, ${req.user}!`)
+})
+```
+
+See
+[JavaScript engine fundamentals: Shapes and Inline Caches](https://web.archive.org/web/20200201163000/https://mathiasbynens.be/notes/shapes-ics)
+for more information on this topic.
 
-<a name="usage"></a>
 ### Usage
+<a name="usage"></a>
+
+#### `decorate(name, value, [dependencies])`
 <a name="decorate"></a>
-**decorate**
-Just call the `decorate` API and pass the name of the new property and its value.
+
+This method is used to customize the Fastify [server](Server.md) instance.
+
+For example, to attach a new method to the server instance:
+
 ```js
-fastify.decorate('utility', () => {
+fastify.decorate('utility', function () {
   // Something very useful
 })
 ```
 
-As mentioned above, you can also decorate the instance with non-function values:
+As mentioned above, non-function values can be attached:
+
 ```js
 fastify.decorate('conf', {
   db: 'some.db',
@@ -25,39 +84,95 @@ fastify.decorate('conf', {
 })
 ```
 
-Once the instance was decorated, you can access the new value by using the name you passed as a parameter:
+To access decorated properties, simply use the name provided to the
+decoration API:
+
 ```js
 fastify.utility()
 
 console.log(fastify.conf.db)
 ```
 
+The `dependencies` parameter is an optional list of decorators that the
+decorator being defined relies upon. This list is simply a list of string names
+of other decorators. In the following example, the "utility" decorator depends
+upon "greet" and "log" decorators:
+
+```js
+fastify.decorate('utility', fn, ['greet', 'log'])
+```
+
+If a dependency is not satisfied, the `decorate` method will throw an exception.
+The dependency check is peformed before the server instance is booted. Thus,
+it cannot occur during runtime.
+
+#### `decorateReply(name, value, [dependencies])`
 <a name="decorate-reply"></a>
-**decorateReply**
-As the name suggests, this API can be used to add new methods to the `Reply` core object. Just call the `decorateReply` API and pass the name of the new property and its value:
+
+As the name suggests, this API is used to add new methods/properties to the core
+`Reply` object:
+
 ```js
 fastify.decorateReply('utility', function () {
   // Something very useful
 })
 ```
 
-Note: using an arrow function will break the binding of `this` to the Fastify `Reply` instance.
+Note: using an arrow function will break the binding of `this` to the Fastify
+`Reply` instance.
 
+See [`decorate`](#decorate) for information about the `dependencies` parameter.
+
+#### `decorateRequest(name, value, [dependencies])`
 <a name="decorate-request"></a>
-**decorateRequest**
-As above, this API is needed if you want to add new methods to the `Request` core object. Just call the `decorateRequest` API and pass the name of the new property and its value:
+
+As above with [`decorateReply`](#decorate-reply), this API is used add new
+methods/properties to the core `Request` object:
+
 ```js
 fastify.decorateRequest('utility', function () {
   // something very useful
 })
 ```
 
-Note: using an arrow function will break the binding of `this` to the Fastify `Request` instance.
+Note: using an arrow function will break the binding of `this` to the Fastify
+`Request` instance.
+
+See [`decorate`](#decorate) for information about the `dependencies` parameter.
+
+#### `hasDecorator(name)`
+<a name="has-decorator"></a>
+
+Used to check for the existence of a server instance decoration:
+
+```js
+fastify.hasDecorator('utility')
+```
+
+#### hasRequestDecorator
+<a name="has-request-decorator"></a>
+
+Used to check for the existence of a Request decoration:
+
+```js
+fastify.hasRequestDecorator('utility')
+```
+
+#### hasReplyDecorator
+<a name="has-reply-decorator"></a>
+
+Used to check for the existence of a Reply decoration:
+
+```js
+fastify.hasReplyDecorator('utility')
+```
 
+### Decorators and Encapsulation
 <a name="decorators-encapsulation"></a>
-#### Decorators and Encapsulation
 
-If you define a decorator (using `decorate`, `decorateRequest` or `decorateReply`) with the same name more than once in the same **encapsulated** plugin, Fastify will throw an exception.
+Defining a decorator (using `decorate`, `decorateRequest` or `decorateReply`)
+with the same name more than once in the same **encapsulated** context will
+throw an exception.
 
 As an example, the following will throw:
 
@@ -107,10 +222,12 @@ server.register(async function (server, opts) {
 server.listen(3000)
 ```
 
+### Getters and Setters
 <a name="getters-setters"></a>
-#### Getters and Setters
 
-Decorators accept special "getter/setter" objects. These objects have functions named `getter` and `setter` (though, the `setter` function is optional). This allows defining properties via decorators. For example:
+Decorators accept special "getter/setter" objects. These objects have functions
+named `getter` and `setter` (though, the `setter` function is optional). This
+allows defining properties via decorators. For example:
 
 ```js
 fastify.decorate('foo', {
@@ -120,64 +237,8 @@ fastify.decorate('foo', {
 })
 ```
 
-Will define the `foo` property on the *Fastify* instance:
+Will define the `foo` property on the Fastify instance:
 
 ```js
 console.log(fastify.foo) // 'a getter'
 ```
-
-<a name="usage_notes"></a>
-#### Usage Notes
-`decorateReply` and `decorateRequest` are used to modify the `Reply` and `Request` constructors respectively by adding methods or properties. To update these properties you should directly access the desired property of the `Reply` or `Request` object.
-
-As an example let's add a user property to the `Request` object:
-
-```js
-// Decorate request with a 'user' property
-fastify.decorateRequest('user', '')
-
-// Update our property
-fastify.addHook('preHandler', (req, reply, done) => {
-  req.user = 'Bob Dylan'
-  done()
-})
-// And finally access it
-fastify.get('/', (req, reply) => {
-  reply.send(`Hello ${req.user}!`)
-})
-```
-Note: The usage of `decorateReply` and `decorateRequest` is optional in this case but will allow Fastify to optimize for performance.
-
-<a name="sync-async"></a>
-#### Sync and Async
-`decorate` is a *synchronous* API. If you need to add a decorator that has an *asynchronous* bootstrap, Fastify could boot up before your decorator is ready. To avoid this issue, you must use the `register` API in combination with `fastify-plugin`. To learn more, check out the [Plugins](https://github.com/fastify/fastify/blob/master/docs/Plugins.md) documentation as well.
-
-<a name="dependencies"></a>
-#### Dependencies
-If your decorator depends on another decorator, you can easily declare the other decorator as a dependency. You just need to add an array of strings (representing the names of the decorators on which yours depends) as the third parameter:
-```js
-fastify.decorate('utility', fn, ['greet', 'log'])
-```
-
-If a dependency is not satisfied, `decorate` will throw an exception, but don't worry: the dependency check is executed before the server boots up, so it won't ever happen at runtime.
-
-<a name="has-decorator"></a>
-#### hasDecorator
-You can check for the presence of a decorator with the `hasDecorator` API:
-```js
-fastify.hasDecorator('utility')
-```
-
-<a name="has-request-decorator"></a>
-#### hasRequestDecorator
-You can check for the presence of a Request decorator with the `hasRequestDecorator` API:
-```js
-fastify.hasRequestDecorator('utility')
-```
-
-<a name="has-reply-decorator"></a>
-#### hasReplyDecorator
-You can check for the presence of a Reply decorator with the `hasReplyDecorator` API:
-```js
-fastify.hasReplyDecorator('utility')
-```

package/docs/Ecosystem.md

@@ -76,6 +76,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-file-upload`](https://github.com/huangang/fastify-file-upload) Fastify plugin for uploading files.
 - [`fastify-firebase-auth`](https://github.com/oxsav/fastify-firebase-auth) Firebase Authentication for Fastify supporting all of the methods relating to the authentication API.
 - [`fastify-firestore`](https://github.com/now-ims/fastify-firestore) Fastify plugin for [Google Cloud Firestore](https://cloud.google.com/nodejs/docs/reference/firestore/0.13.x/).
+- [`fastify-gcloud-trace`](https://github.com/mkinoshi/fastify-gcloud-trace) [Google Cloud Trace API](https://cloud.google.com/trace/docs/reference) Connector for Fastify.
 - [`fastify-google-cloud-storage`](https://github.com/carlozamagni/fastify-google-cloud-storage) Fastify plugin that exposes a GCP Cloud Storage client instance.
 - [`fastify-gql`](https://github.com/mcollina/fastify-gql) A GraphQL server implementation for Fastify with caching and [`graphql-jit`](https://github.com/ruiaraujo/graphql-jit).
 - [`fastify-graceful-shutdown`](https://github.com/hemerajs/fastify-graceful-shutdown) Shutdown Fastify gracefully and asynchronously.
@@ -94,6 +95,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-loader`](https://github.com/TheNoim/fastify-loader) Load routes from a directory and inject the fastify instance in each file.
 - [`fastify-lured`](https://github.com/lependu/fastify-lured) Plugin to load lua scripts with [fastify-redis](https://github.com/fastify/fastify-redis) and [lured](https://github.com/enobufs/lured).
 - [`fastify-markdown`](https://github.com/freezestudio/fastify-markdown) Plugin to markdown support.
+- [`fastify-method-override`](https://github.com/corsicanec82/fastify-method-override) Plugin for Fastify, which allows use HTTP verbs, such as DELETE, PATCH, HEAD, PUT, OPTIONS in case the client doesn't support them.
 - [`fastify-metrics`](https://gitlab.com/m03geek/fastify-metrics) Plugin for exporting [Prometheus](https://prometheus.io) metrics.
 - [`fastify-mongo-memory`](https://github.com/chapuletta/fastify-mongo-memory) Fastify MongoDB in Memory Plugin for testing support.
 - [`fastify-mongoose-api`](https://github.com/jeka-kiselyov/fastify-mongoose-api) Fastify plugin to create REST API methods based on Mongoose MongoDB models.
@@ -108,6 +110,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-openapi-glue`](https://github.com/seriousme/fastify-openapi-glue) Glue for Open Api specifications in Fastify, autogenerates routes based on an Open Api Specification
 - [`fastify-oracle`](https://github.com/cemremengu/fastify-oracle) Attaches an [`oracledb`](https://github.com/oracle/node-oracledb) connection pool to a Fastify server instance.
 - [`fastify-orientdb`](https://github.com/mahmed8003/fastify-orientdb) Fastify OrientDB connection plugin, with which you can share the OrientDB connection across every part of your server.
+- [`fastify-qrcode`](https://github.com/chonla/fastify-qrcode) This plugin utilizes [qrcode](https://github.com/soldair/node-qrcode) to generate QR Code.
 - [`fastify-qs`](https://github.com/webdevium/fastify-qs) A plugin for Fastify that adds support for parsing URL query parameters with [qs](https://github.com/ljharb/qs).
 - [`fastify-rbac`](https://gitlab.com/m03geek/fastify-rbac) Fastify role-based access control plugin.
 - [`fastify-register-routes`](https://github.com/israeleriston/fastify-register-routes) Plugin to automatically load routes from a specified path and optionally limit loaded file names by a regular expression.

package/docs/Errors.md

@@ -16,6 +16,11 @@ If routes are declared as `async` though - the error will safely be caught by th
 <a name="fastify-error-codes"></a>
 ### Fastify Error Codes
 
+<a name="FST_ERR_BAD_URL"></a>
+#### FST_ERR_BAD_URL
+
+The router received an invalid url.
+
 <a name="FST_ERR_CTP_ALREADY_PRESENT"></a>
 #### FST_ERR_CTP_ALREADY_PRESENT
 

package/docs/Hooks.md

@@ -15,6 +15,8 @@ By using hooks you can interact directly with the lifecycle of Fastify. There ar
   - [onError](#onerror)
   - [onSend](#onsend)
   - [onResponse](#onresponse)
+  - [Manage Errors from a hook](#manage-errors-from-a-hook)
+  - [Respond to a request from a hook](#respond-to-a-request-from-a-hook)
 - [Application Hooks](#application-hooks)
   - [onClose](#onclose)
   - [onRoute](#onroute)
@@ -206,9 +208,15 @@ fastify.addHook('preHandler', (request, reply, done) => {
   done(new Error('Some error'))
 })
 ```
-
 *The error will be handled by [`Reply`](https://github.com/fastify/fastify/blob/master/docs/Reply.md#errors).*
 
+Or if you're using `async/await` you can just throw an error:
+```js
+fastify.addHook('onResponse', async (request, reply) => {
+  throw new Error('Some error')
+})
+```
+
 ### Respond to a request from a hook
 
 If needed, you can respond to a request before you reach the route handler,

package/docs/LTS.md

@@ -31,18 +31,21 @@ A "month" is to be a period of 30 consecutive days.
 
 ### Schedule
 
-| Version | Release Date | End Of LTS Date | Node.js         |
-| :------ | :----------- | :-------------- | :-------------- |
-| 1.0.0   | 2018-03-06   | 2019-09-01      | 6, 8, 9, 10, 11 |
-| 2.0.0   | 2019-02-25   | TBD             | 6, 8, 10, 11    |
+| Version | Release Date | End Of LTS Date | Node.js              |
+| :------ | :----------- | :-------------- | :------------------- |
+| 1.0.0   | 2018-03-06   | 2019-09-01      | 6, 8, 9, 10, 11      |
+| 2.0.0   | 2019-02-25   | TBD             | 6, 8, 10, 11, 12, 13 |
 
 <a name="supported-os"></a>
 
 ### CI tested operating systems
 
-| CI             | OS      | Version                | Package Manager           | Node.js   |
-|----------------|---------|------------------------|---------------------------|-----------|
-| Github Actions | Linux   | Ubuntu 16.04           | npm                       | 6,8,10,12 |
-| Github Actions | Linux   | Ubuntu 16.04           | yarn,pnpm                 | 8,10      |
-| Github Actions | Windows | Windows Server 2016 R2 | npm                       | 6,8,10,12 |
-| Github Actions | MacOS   | macOS X Mojave 10.14   | npm                       | 6,8,10,12 |
+| OS      | Version                | Package Manager           | Node.js   |
+|---------|------------------------|---------------------------|-----------|
+| Linux   | Ubuntu 16.04           | npm                       | 6,8,10,12 |
+| Linux   | Ubuntu 16.04           | pnpm                      | 8,10,12   |
+| Linux   | Ubuntu 16.04           | yarn                      | 8,10,12   |
+| Windows | Windows Server 2016 R2 | npm                       | 6,8,10,12 |
+| MacOS   | macOS X Mojave 10.14   | npm                       | 6,8,10,12 |
+
+Using yarn might require passing the `--ignore-engines` flag.

package/docs/Logging.md

@@ -101,7 +101,7 @@ const fastify = require('fastify')({
   }
 });
 ```
-**Note**: The body not can serialize inside `req` method, because the request is serialized when we create the child logger. At that time, the body is not parsed yet.
+**Note**: The body cannot be serialized inside `req` method because the request is serialized when we create the child logger. At that time, the body is not yet parsed.
 
 See an approach to log `req.body`
 

package/docs/Middleware.md

@@ -32,7 +32,7 @@ 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").
+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)

package/docs/Recommendations.md

@@ -67,6 +67,10 @@ defaults
   option        dontlognull
   retries       3
   option redispatch
+  # The following option make haproxy close connections to backend servers
+  # instead of keeping them open. This can alleviate unexpected connection
+  # reset errors in the Node process.
+  option http-server-close
   maxconn       2000
   timeout connect 5000
   timeout client 50000

package/docs/Reply.md

@@ -147,7 +147,8 @@ reply.code(303).redirect(302, '/home')
 
 <a name="call-not-found"></a>
 ### .callNotFound()
-Invokes the custom not found handler.
+Invokes the custom not found handler. Note that it will only call `preHandler` hook specified in [`setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#set-not-found-handler).
+
 ```js
 reply.callNotFound()
 ```
@@ -338,7 +339,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

@@ -154,28 +154,28 @@ To register a **parametric** path, use the *colon* before the parameter name. Fo
 
 ```js
 // parametric
-fastify.get('/example/:userId', (request, reply) => {}))
-fastify.get('/example/:userId/:secretToken', (request, reply) => {}))
+fastify.get('/example/:userId', (request, reply) => {})
+fastify.get('/example/:userId/:secretToken', (request, reply) => {})
 
 // wildcard
-fastify.get('/example/*', (request, reply) => {}))
+fastify.get('/example/*', (request, reply) => {})
 ```
 
 Regular expression routes are supported as well, but pay attention, RegExp are very expensive in term of performance!
 ```js
 // parametric with regexp
-fastify.get('/example/:file(^\\d+).png', (request, reply) => {}))
+fastify.get('/example/:file(^\\d+).png', (request, reply) => {})
 ```
 
 It's possible to define more than one parameter within the same couple of slash ("/"). Such as:
 ```js
-fastify.get('/example/near/:lat-:lng/radius/:r', (request, reply) => {}))
+fastify.get('/example/near/:lat-:lng/radius/:r', (request, reply) => {})
 ```
 *Remember in this case to use the dash ("-") as parameters separator.*
 
 Finally it's possible to have multiple parameters with RegExp.
 ```js
-fastify.get('/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', (request, reply) => {}))
+fastify.get('/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', (request, reply) => {})
 ```
 In this case as parameter separator it's possible to use whatever character is not matched by the regular expression.
 

package/docs/Server.md

@@ -418,6 +418,30 @@ Set a default
 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
@@ -696,6 +720,8 @@ This property can be used to set the schema compiler, it is a shortcut for the `
 
 You can also register a [`preValidation`](https://www.fastify.io/docs/latest/Hooks/#route-hooks) and [preHandler](https://www.fastify.io/docs/latest/Hooks/#route-hooks) hook for the 404 handler.
 
+_Note: The `preValidation` hook registered using this method will run for a route that Fastify does not recognize and **not** when a route handler manually calls [`reply.callNotFound`](https://github.com/fastify/fastify/blob/master/docs/Reply.md#call-not-found)_. In which case only preHandler will be run.
+
 ```js
 fastify.setNotFoundHandler({
   preValidation: (req, reply, done) => {