fastify 3.24.0 → 3.25.2

package/docs/{Logging.md → Reference/Logging.md}

@@ -2,35 +2,63 @@
 
 ## Logging
 
-Logging is disabled by default, and you can enable it by passing
-`{ logger: true }` or `{ logger: { level: 'info' } }` when you create
-a fastify instance. Note that if the logger is disabled, it is impossible to
-enable it at runtime. We use
-[abstract-logging](https://www.npmjs.com/package/abstract-logging) for
-this purpose.
+### Enable logging
+Logging is disabled by default, and you can enable it by passing `{ logger: true
+}` or `{ logger: { level: 'info' } }` when you create a Fastify instance. Note
+that if the logger is disabled, it is impossible to enable it at runtime. We use
+[abstract-logging](https://www.npmjs.com/package/abstract-logging) for this
+purpose.
 
-As Fastify is focused on performance, it uses [pino](https://github.com/pinojs/pino) as its logger, with the default log level, when enabled, set to `'info'`.
+As Fastify is focused on performance, it uses
+[pino](https://github.com/pinojs/pino) as its logger, with the default log
+level, when enabled, set to `'info'`.
 
-Enabling the logger is extremely easy:
+Enabling the production JSON logger:
 
 ```js
 const fastify = require('fastify')({
   logger: true
 })
+```
+
+Enabling the logger with appropriate configuration for both local development
+and production environment requires bit more configuration:
+```js
+const fastify = require('fastify')({
+  logger: {
+      prettyPrint:
+        environment === 'development'
+          ? {
+              translateTime: 'HH:MM:ss Z',
+              ignore: 'pid,hostname'
+            }
+          : false
+    }
+})
+```
+⚠️ `pino-pretty` needs to be installed as a dev dependency, it is not included
+by default for performance reasons.
 
+### Usage
+You can use the logger like this in your route handlers:
+
+```js
 fastify.get('/', options, function (request, reply) {
   request.log.info('Some info about the current request')
   reply.send({ hello: 'world' })
 })
 ```
 
-You can trigger new logs outside route handlers by using the Pino instance from the Fastify instance:
+You can trigger new logs outside route handlers by using the Pino instance from
+the Fastify instance:
 ```js
 fastify.log.info('Something important happened!');
 ```
 
-If you want to pass some options to the logger, just pass them to Fastify.
-You can find all available options in the [Pino documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#pinooptions-stream). If you want to specify a file destination, use:
+If you want to pass some options to the logger, just pass them to Fastify. You
+can find all available options in the [Pino
+documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#pinooptions-stream).
+If you want to specify a file destination, use:
 
 ```js
 const fastify = require('fastify')({
@@ -46,7 +74,8 @@ fastify.get('/', options, function (request, reply) {
 })
 ```
 
-If you want to pass a custom stream to the Pino instance, just add a stream field to the logger object.
+If you want to pass a custom stream to the Pino instance, just add a stream
+field to the logger object.
 
 ```js
 const split = require('split2')
@@ -60,12 +89,19 @@ const fastify = require('fastify')({
 })
 ```
 
-<a name="logging-request-id"></a>
+<a id="logging-request-id"></a>
 
-By default, Fastify adds an ID to every request for easier tracking. If the "request-id" header is present its value is used, otherwise a new incremental ID is generated. See Fastify Factory [`requestIdHeader`](Server.md#factory-request-id-header) and Fastify Factory [`genReqId`](Server.md#genreqid) for customization options.
+By default, Fastify adds an ID to every request for easier tracking. If the
+"request-id" header is present its value is used, otherwise a new incremental ID
+is generated. See Fastify Factory
+[`requestIdHeader`](./Server.md#factory-request-id-header) and Fastify Factory
+[`genReqId`](./Server.md#genreqid) for customization options.
 
-The default logger is configured with a set of standard serializers that serialize objects with `req`, `res`, and `err` properties. The object received by `req` is the Fastify [`Request`](Request.md) object, while the object received by `res` is the Fastify [`Reply`](Reply.md) object.
-This behaviour can be customized by specifying custom serializers.
+The default logger is configured with a set of standard serializers that
+serialize objects with `req`, `res`, and `err` properties. The object received
+by `req` is the Fastify [`Request`](./Request.md) object, while the object
+received by `res` is the Fastify [`Reply`](./Reply.md) object. This behaviour
+can be customized by specifying custom serializers.
 ```js
 const fastify = require('fastify')({
   logger: {
@@ -77,7 +113,8 @@ const fastify = require('fastify')({
   }
 })
 ```
-For example, the response payload and headers could be logged using the approach below (even if it is *not recommended*):
+For example, the response payload and headers could be logged using the approach
+below (even if it is *not recommended*):
 
 ```js
 const fastify = require('fastify')({
@@ -94,8 +131,8 @@ const fastify = require('fastify')({
         return {
           method: request.method,
           url: request.url,
-          path: request.path,
-          parameters: request.parameters,
+          path: request.routerPath,
+          parameters: request.params,
           // Including the headers in the log could be in violation
           // of privacy laws, e.g. GDPR. You should use the "redact" option to
           // remove sensitive fields. It could also leak authentication data in
@@ -107,7 +144,9 @@ const fastify = require('fastify')({
   }
 });
 ```
-**Note**: The body cannot be serialized inside a `req` method because the request is serialized when we create the child logger. At that time, the body is not yet parsed.
+**Note**: The body cannot be serialized inside a `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`
 
@@ -123,9 +162,10 @@ app.addHook('preHandler', function (req, reply, done) {
 
 *Any logger other than Pino will ignore this option.*
 
-You can also supply your own logger instance. Instead of passing configuration options, pass the instance.
-The logger you supply must conform to the Pino interface; that is, it must have the following methods:
-`info`, `error`, `debug`, `fatal`, `warn`, `trace`, `child`.
+You can also supply your own logger instance. Instead of passing configuration
+options, pass the instance. The logger you supply must conform to the Pino
+interface; that is, it must have the following methods: `info`, `error`,
+`debug`, `fatal`, `warn`, `trace`, `child`.
 
 Example:
 
@@ -141,14 +181,14 @@ fastify.get('/', function (request, reply) {
 })
 ```
 
-*The logger instance for the current request is available in every part of the [lifecycle](Lifecycle.md).*
+*The logger instance for the current request is available in every part of the
+[lifecycle](./Lifecycle.md).*
 
 ## Log Redaction
 
-[Pino](https://getpino.io) supports low-overhead log redaction for
-obscuring values of specific properties in recorded logs.
-As an example, we might want to log all the HTTP headers minus the
-`Authorization` header for security concerns:
+[Pino](https://getpino.io) supports low-overhead log redaction for obscuring
+values of specific properties in recorded logs. As an example, we might want to
+log all the HTTP headers minus the `Authorization` header for security concerns:
 
 ```js
 const fastify = Fastify({

package/docs/Reference/Middleware.md

@@ -0,0 +1,78 @@
+<h1 align="center">Fastify</h1>
+
+## Middleware
+
+Starting with Fastify v3.0.0, middleware is not supported out of the box and
+requires an external plugin such as
+[`fastify-express`](https://github.com/fastify/fastify-express) or
+[`middie`](https://github.com/fastify/middie).
+
+
+An example of registering the
+[`fastify-express`](https://github.com/fastify/fastify-express) plugin to `use`
+Express middleware:
+
+```js
+await fastify.register(require('fastify-express'))
+fastify.use(require('cors')())
+fastify.use(require('dns-prefetch-control')())
+fastify.use(require('frameguard')())
+fastify.use(require('hsts')())
+fastify.use(require('ienoopen')())
+fastify.use(require('x-xss-protection')())
+```
+
+You can also use [`middie`](https://github.com/fastify/middie), which provides
+support for simple Express-style middleware but with improved performance:
+
+```js
+await fastify.register(require('middie'))
+fastify.use(require('cors')())
+```
+
+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](../Guides/Plugins-Guide.md).
+
+Fastify middleware 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 that already has the
+[Request](./Request.md#request) and [Reply](./Reply.md#reply) Fastify instances.
+For more information, see [Hooks](./Hooks.md#hooks).
+
+#### Restrict middleware execution to certain paths
+<a id="restrict-usage"></a>
+
+If you need to only run middleware under certain paths, just pass the path as
+the first parameter to `use` and you are done!
+
+*Note that this does not support routes with parameters, (e.g.
+`/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')))
+```
+
+### Alternatives
+
+Fastify offers some alternatives to the most commonly used middleware, such as
+[`fastify-helmet`](https://github.com/fastify/fastify-helmet) in case of
+[`helmet`](https://github.com/helmetjs/helmet),
+[`fastify-cors`](https://github.com/fastify/fastify-cors) for
+[`cors`](https://github.com/expressjs/cors), and
+[`fastify-static`](https://github.com/fastify/fastify-static) for
+[`serve-static`](https://github.com/expressjs/serve-static).

package/docs/{Plugins.md → Reference/Plugins.md}

@@ -1,27 +1,42 @@
 <h1 align="center">Fastify</h1>
 
 ## Plugins
-Fastify allows the user to extend its functionalities with plugins.
-A plugin can be a set of routes, a server [decorator](Decorators.md), or whatever. The API that you will need to use one or more plugins, is `register`.<br>
-
-By default, `register` creates a *new scope*, this means that if you make some changes to the Fastify instance (via `decorate`), this change will not be reflected by the current context ancestors, but only to its sons. This feature allows us to achieve plugin *encapsulation* and *inheritance*, in this way we create a *direct acyclic graph* (DAG) and we will not have issues caused by cross dependencies.
-
-You already see in the [getting started](Getting-Started.md#register) section how using this API is pretty straightforward.
+Fastify allows the user to extend its functionalities with plugins. A plugin can
+be a set of routes, a server [decorator](./Decorators.md), or whatever. The API
+that you will need to use one or more plugins, is `register`.
+
+By default, `register` creates a *new scope*, this means that if you make some
+changes to the Fastify instance (via `decorate`), this change will not be
+reflected by the current context ancestors, but only to its descendants. This
+feature allows us to achieve plugin *encapsulation* and *inheritance*, in this
+way we create a *direct acyclic graph* (DAG) and we will not have issues caused
+by cross dependencies.
+
+You already see in the [getting started](../Guides/Getting-Started.md#your-first-plugin)
+section how using this API is pretty straightforward.
 ```
 fastify.register(plugin, [options])
 ```
 
-<a name="plugin-options"></a>
 ### 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:
+<a id="plugin-options"></a>
+
+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`](Routes.md#custom-log-level)
-+ [`logSerializers`](Routes.md#custom-log-serializer)
-+ [`prefix`](Plugins.md#route-prefixing-options)
++ [`logLevel`](./Routes.md#custom-log-level)
++ [`logSerializers`](./Routes.md#custom-log-serializer)
++ [`prefix`](#route-prefixing-option)
 
 **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:
+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
 fastify.register(require('fastify-foo'), {
@@ -33,7 +48,8 @@ fastify.register(require('fastify-foo'), {
 })
 ```
 
-If collisions are not a concern, the plugin may simply accept the options object as-is:
+If collisions are not a concern, the plugin may simply accept the options object
+as-is:
 
 ```js
 fastify.register(require('fastify-foo'), {
@@ -43,7 +59,9 @@ fastify.register(require('fastify-foo'), {
 })
 ```
 
-The `options` parameter can also be a `Function` that will be evaluated at the time the plugin is registered while giving access to the Fastify instance via the first positional argument:
+The `options` parameter can also be a `Function` that will be evaluated at the
+time the plugin is registered while giving access to the Fastify instance via
+the first positional argument:
 
 ```js
 const fp = require('fastify-plugin')
@@ -58,19 +76,40 @@ fastify.register(fp((fastify, opts, done) => {
 fastify.register(require('fastify-foo'), parent => parent.foo_bar)
 ```
 
-The Fastify instance passed on to the function is the latest state of the **external Fastify instance** the plugin was declared on, allowing access to variables injected via [`decorate`](Decorators.md) by preceding plugins according to the **order of registration**. This is useful in case a plugin depends on changes made to the Fastify instance by a preceding plugin i.e. utilizing an existing database connection to wrap around it.
+The Fastify instance passed on to the function is the latest state of the
+**external Fastify instance** the plugin was declared on, allowing access to
+variables injected via [`decorate`](./Decorators.md) by preceding plugins
+according to the **order of registration**. This is useful in case a plugin
+depends on changes made to the Fastify instance by a preceding plugin i.e.
+utilizing an existing database connection to wrap around it.
 
-Keep in mind that the Fastify instance passed on to the function is the same as the one that will be passed into the plugin, a copy of the external Fastify instance rather than a reference. Any usage of the instance will behave the same as it would if called within the plugins function i.e. if `decorate` is called, the decorated variables will be available within the plugins function unless it was wrapped with [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
+Keep in mind that the Fastify instance passed on to the function is the same as
+the one that will be passed into the plugin, a copy of the external Fastify
+instance rather than a reference. Any usage of the instance will behave the same
+as it would if called within the plugins function i.e. if `decorate` is called,
+the decorated variables will be available within the plugins function unless it
+was wrapped with [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
 
-<a name="route-prefixing-option"></a>
 #### Route Prefixing option
-If you pass an option with the key `prefix` with a `string` value, Fastify will use it to prefix all the routes inside the register, for more info check [here](Routes.md#route-prefixing).<br>
-Be aware that if you use [`fastify-plugin`](https://github.com/fastify/fastify-plugin) this option will not work.
+<a id="route-prefixing-option"></a>
+
+If you pass an option with the key `prefix` with a `string` value, Fastify will
+use it to prefix all the routes inside the register, for more info check
+[here](./Routes.md#route-prefixing).
+
+Be aware that if you use
+[`fastify-plugin`](https://github.com/fastify/fastify-plugin) this option will
+not work.
 
-<a name="error-handling"></a>
 #### Error handling
-The error handling is done by [avvio](https://github.com/mcollina/avvio#error-handling).<br>
-As a general rule, it is highly recommended that you handle your errors in the next `after` or `ready` block, otherwise you will get them inside the `listen` callback.
+<a id="error-handling"></a>
+
+The error handling is done by
+[avvio](https://github.com/mcollina/avvio#error-handling).
+
+As a general rule, it is highly recommended that you handle your errors in the
+next `after` or `ready` block, otherwise you will get them inside the `listen`
+callback.
 
 ```js
 fastify.register(require('my-plugin'))
@@ -90,8 +129,8 @@ fastify.listen(3000, (err, address) => {
 })
 ```
 
-<a name="async-await"></a>
 ### async/await
+<a id="async-await"></a>
 
 *async/await* is supported by `after`, `ready` and `listen`, as well as
 `fastify` being a [Thenable](https://promisesaplus.com/).
@@ -106,10 +145,11 @@ await fastify.ready()
 await fastify.listen(3000)
 ```
 
-<a name="esm-support"></a>
 #### ESM support
+<a id="esm-support"></a>
 
-ESM is supported as well from [Node.js `v13.3.0`](https://nodejs.org/api/esm.html) and above!
+ESM is supported as well from [Node.js
+`v13.3.0`](https://nodejs.org/api/esm.html) and above!
 
 ```js
 // main.mjs
@@ -131,9 +171,13 @@ async function plugin (fastify, opts) {
 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>
+<a id="create-plugin"></a>
+
+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.
+
 Example:
 ```js
 module.exports = function (fastify, opts, done) {
@@ -156,19 +200,28 @@ module.exports = function (fastify, opts, done) {
   done()
 }
 ```
-Sometimes, you will need to know when the server is about to close, for example, because you must close a connection to a database. To know when this is going to happen, you can use the [`'onClose'`](Hooks.md#on-close) hook.
+Sometimes, you will need to know when the server is about to close, for example,
+because you must close a connection to a database. To know when this is going to
+happen, you can use the [`'onClose'`](./Hooks.md#on-close) hook.
 
-Do not forget that `register` will always create a new Fastify scope, if you do not need that, read the following section.
+Do not forget that `register` will always create a new Fastify scope, if you do
+not need that, read the following section.
 
-<a name="handle-scope"></a>
 ### Handle the scope
-If you are using `register` only for extending the functionality of the server with  [`decorate`](Decorators.md), it is your responsibility to tell Fastify not to create a new scope. Otherwise, your changes will not be accessible by the user in the upper scope.
+<a id="handle-scope"></a>
+
+If you are using `register` only for extending the functionality of the server
+with  [`decorate`](./Decorators.md), it is your responsibility to tell Fastify
+not to create a new scope. Otherwise, your changes will not be accessible by the
+user in the upper scope.
 
 You have two ways to tell Fastify to avoid the creation of a new context:
 - Use the [`fastify-plugin`](https://github.com/fastify/fastify-plugin) module
 - Use the `'skip-override'` hidden property
 
-We recommend using the `fastify-plugin` module, because it solves this problem for you, and you can pass a version range of Fastify as a parameter that your plugin will support.
+We recommend using the `fastify-plugin` module, because it solves this problem
+for you, and you can pass a version range of Fastify as a parameter that your
+plugin will support.
 ```js
 const fp = require('fastify-plugin')
 
@@ -177,9 +230,13 @@ module.exports = fp(function (fastify, opts, done) {
   done()
 }, '0.x')
 ```
-Check the [`fastify-plugin`](https://github.com/fastify/fastify-plugin) documentation to learn more about how to use this module.
+Check the [`fastify-plugin`](https://github.com/fastify/fastify-plugin)
+documentation to learn more about how to use this module.
 
-If you do not use the `fastify-plugin` module, you can use the `'skip-override'` hidden property, but we do not recommend it. If in the future the Fastify API changes it will be your responsibility to update the module, while if you use `fastify-plugin`, you can be sure about backward compatibility.
+If you do not use the `fastify-plugin` module, you can use the `'skip-override'`
+hidden property, but we do not recommend it. If in the future the Fastify API
+changes it will be your responsibility to update the module, while if you use
+`fastify-plugin`, you can be sure about backward compatibility.
 ```js
 function yourPlugin (fastify, opts, done) {
   fastify.decorate('utility', () => {})