fastify 3.24.0 → 3.25.2

package/docs/Guides/Write-Plugin.md

@@ -0,0 +1,102 @@
+<h1 align="center">Fastify</h1>
+
+# How to write a good plugin
+First, thank you for deciding to write a plugin for Fastify. Fastify is a
+minimal framework and plugins are its strength, so thank you.
+
+The core principles of Fastify are performance, low overhead, and providing a
+good experience to our users. When writing a plugin, it is important to keep
+these principles in mind. Therefore, in this document, we will analyze what
+characterizes a quality plugin.
+
+*Need some inspiration? You can use the label ["plugin
+suggestion"](https://github.com/fastify/fastify/issues?q=is%3Aissue+is%3Aopen+label%3A%22plugin+suggestion%22)
+in our issue tracker!*
+
+## Code
+Fastify uses different techniques to optimize its code, many of them are
+documented in our Guides. We highly recommend you read [the hitchhiker's guide
+to plugins](./Plugins-Guide.md) to discover all the APIs you can use to build
+your plugin and learn how to use them.
+
+Do you have a question or need some advice? We are more than happy to help you!
+Just open an issue in our [help repository](https://github.com/fastify/help).
+
+Once you submit a plugin to our [ecosystem list](./Ecosystem.md), we will review
+your code and help you improve it if necessary.
+
+## Documentation
+Documentation is extremely important. If your plugin is not well documented we
+will not accept it to the ecosystem list. Lack of quality documentation makes it
+more difficult for people to use your plugin, and will likely result in it going
+unused.
+
+If you want to see some good examples on how to document a plugin take a look
+at:
+- [`fastify-caching`](https://github.com/fastify/fastify-caching)
+- [`fastify-compress`](https://github.com/fastify/fastify-compress)
+- [`fastify-cookie`](https://github.com/fastify/fastify-cookie)
+- [`point-of-view`](https://github.com/fastify/point-of-view)
+- [`under-pressure`](https://github.com/fastify/under-pressure)
+
+## License
+You can license your plugin as you prefer, we do not enforce any kind of
+license.
+
+We prefer the [MIT license](https://choosealicense.com/licenses/mit/) because we
+think it allows more people to use the code freely. For a list of alternative
+licenses see the [OSI list](https://opensource.org/licenses) or GitHub's
+[choosealicense.com](https://choosealicense.com/).
+
+## Examples
+Always put an example file in your repository. Examples are very helpful for
+users and give a very fast way to test your plugin. Your users will be grateful.
+
+## Test
+It is extremely important that a plugin is thoroughly tested to verify that is
+working properly.
+
+A plugin without tests will not be accepted to the ecosystem list. A lack of
+tests does not inspire trust nor guarantee that the code will continue to work
+among different versions of its dependencies.
+
+We do not enforce any testing library. We use [`tap`](https://www.node-tap.org/)
+since it offers out-of-the-box parallel testing and code coverage, but it is up
+to you to choose your library of preference.
+
+## Code Linter
+It is not mandatory, but we highly recommend you use a code linter in your
+plugin. It will ensure a consistent code style and help you to avoid many
+errors.
+
+We use [`standard`](https://standardjs.com/) since it works without the need to
+configure it and is very easy to integrate into a test suite.
+
+## Continuous Integration
+It is not mandatory, but if you release your code as open source, it helps to
+use Continuous Integration to ensure contributions do not break your plugin and
+to show that the plugin works as intended. Both
+[CircleCI](https://circleci.com/) and [GitHub
+Actions](https://github.com/features/actions) are free for open source projects
+and easy to set up.
+
+In addition, you can enable services like [Dependabot](https://dependabot.com/)
+or [Snyk](https://snyk.io/), which will help you keep your dependencies up to
+date and discover if a new release of Fastify has some issues with your plugin.
+
+## Let's start!
+Awesome, now you know everything you need to know about how to write a good
+plugin for Fastify! After you have built one (or more!) let us know! 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 examples, 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-multipart`](https://github.com/fastify/fastify-multipart) Multipart
+  support for Fastify.
+- [`fastify-helmet`](https://github.com/fastify/fastify-helmet) Important
+  security headers for Fastify.

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

@@ -1,13 +1,22 @@
 <h1 align="center">Fastify</h1>
 
 ## `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, you can use the `addContentTypeParser` API. *The default JSON and/or plain text parser can be changed or removed.*
+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, you can use the `addContentTypeParser` API. *The default JSON and/or
+plain text parser can be changed or removed.*
 
-*Note: If you decide to specify your own content type with the `Content-Type` header, UTF-8 will not be the default. Be sure to include UTF-8 like this `text/html; charset=utf-8`.*
+*Note: If you decide to specify your own content type with the `Content-Type`
+header, UTF-8 will not be the default. Be sure to include UTF-8 like this
+`text/html; charset=utf-8`.*
 
-As with the other APIs, `addContentTypeParser` is encapsulated in the scope in which it is declared. This means that if you declare it in the root scope it will be available everywhere, while if you declare it inside a plugin it will be available only in that scope and its children.
+As with the other APIs, `addContentTypeParser` is encapsulated in the scope in
+which it is declared. This means that if you declare it in the root scope it
+will be available everywhere, while if you declare it inside a plugin it will be
+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`.
+Fastify automatically adds the parsed request payload to the [Fastify
+request](./Request.md) object which you can access with `request.body`.
 
 ### Usage
 ```js
@@ -31,7 +40,7 @@ fastify.addContentTypeParser('application/jsoff', async function (request, paylo
   return res
 })
 
-// Handle all content types that matches RegExp 
+// Handle all content types that matches RegExp
 fastify.addContentTypeParser(/^image\/.*/, function (request, payload, done) {
   imageParser(payload, function (err, body) {
     done(err, body)
@@ -42,25 +51,31 @@ fastify.addContentTypeParser(/^image\/.*/, function (request, payload, done) {
 fastify.addContentTypeParser('text/json', { parseAs: 'string' }, fastify.getDefaultJsonParser('ignore', 'ignore'))
 ```
 
-Fastify first tries to match a content-type parser with a `string` value before trying to find a matching `RegExp`.
-If you provide overlapping content types, Fastify tries to find a matching content type by starting with the last one passed and ending with the first one.
-So if you want to specify a general content type more precisely, first specify the general content type and then the more specific one, like in the example below.
+Fastify first tries to match a content-type parser with a `string` value before
+trying to find a matching `RegExp`. If you provide overlapping content types,
+Fastify tries to find a matching content type by starting with the last one
+passed and ending with the first one. So if you want to specify a general
+content type more precisely, first specify the general content type and then the
+more specific one, like in the example below.
 
 ```js
 // Here only the second content type parser is called because its value also matches the first one
 fastify.addContentTypeParser('application/vnd.custom+xml', (request, body, done) => {} )
 fastify.addContentTypeParser('application/vnd.custom', (request, body, done) => {} )
 
-// Here the desired behavior is achieved because fastify first tries to match the `application/vnd.custom+xml` content type parser 
+// Here the desired behavior is achieved because fastify first tries to match the `application/vnd.custom+xml` content type parser
 fastify.addContentTypeParser('application/vnd.custom', (request, body, done) => {} )
 fastify.addContentTypeParser('application/vnd.custom+xml', (request, body, done) => {} )
 ```
 
-Besides the `addContentTypeParser` API there are further APIs that can be used. These are `hasContentTypeParser`, `removeContentTypeParser` and `removeAllContentTypeParsers`.
+Besides the `addContentTypeParser` API there are further APIs that can be used.
+These are `hasContentTypeParser`, `removeContentTypeParser` and
+`removeAllContentTypeParsers`.
 
 #### hasContentTypeParser
 
-You can use the `hasContentTypeParser` API to find if a specific content type parser already exists.
+You can use the `hasContentTypeParser` API to find if a specific content type
+parser already exists.
 
 ```js
 if (!fastify.hasContentTypeParser('application/jsoff')){
@@ -74,8 +89,8 @@ if (!fastify.hasContentTypeParser('application/jsoff')){
 
 #### removeContentTypeParser
 
-With `removeContentTypeParser` a single or an array of content types can be removed. The method supports `string` and
-`RegExp` content types.
+With `removeContentTypeParser` a single or an array of content types can be
+removed. The method supports `string` and `RegExp` content types.
 
 ```js
 fastify.addContentTypeParser('text/xml', function (request, payload, done) {
@@ -90,11 +105,15 @@ fastify.removeContentTypeParser(['application/json', 'text/plain'])
 
 #### removeAllContentTypeParsers
 
-In the example from just above, it is noticeable that we need to specify each content type that we want to remove.
-To solve this problem Fastify provides the `removeAllContentTypeParsers` API. This can be used to remove all currently existing content type parsers.
-In the example below we achieve exactly the same as in the example above except that we do not need to specify each content type to delete.
-Just like `removeContentTypeParser`, this API supports encapsulation. The API is especially useful if you want to register a 
-[catch-all content type parser](#Catch-All) that should be executed for every content type and the built-in parsers should be ignored as well.
+In the example from just above, it is noticeable that we need to specify each
+content type that we want to remove. To solve this problem Fastify provides the
+`removeAllContentTypeParsers` API. This can be used to remove all currently
+existing content type parsers. In the example below we achieve exactly the same
+as in the example above except that we do not need to specify each content type
+to delete. Just like `removeContentTypeParser`, this API supports encapsulation.
+The API is especially useful if you want to register a [catch-all content type
+parser](#catch-all) that should be executed for every content type and the
+built-in parsers should be ignored as well.
 
 ```js
 fastify.removeAllContentTypeParsers()
@@ -106,10 +125,18 @@ fastify.addContentTypeParser('text/xml', function (request, payload, done) {
 })
 ```
 
-**Notice**: The old syntaxes `function(req, done)` and `async function(req)` for the parser are still supported but they are deprecated.
+**Notice**: The old syntaxes `function(req, done)` and `async function(req)` for
+the parser are still supported but they are deprecated.
 
 #### Body Parser
-You can parse the body of a request in two ways. The first one is shown above: you add a custom content type parser and handle the request stream. In the second one, you should pass a `parseAs` option to the `addContentTypeParser` API, where you declare how you want to get the body. It could be of type `'string'` or `'buffer'`. If you use the `parseAs` option, Fastify will internally handle the stream and perform some checks, such as the [maximum size](Server.md#factory-body-limit) of the body and the content length. If the limit is exceeded the custom parser will not be invoked.
+You can parse the body of a request in two ways. The first one is shown above:
+you add a custom content type parser and handle the request stream. In the
+second one, you should pass a `parseAs` option to the `addContentTypeParser`
+API, where you declare how you want to get the body. It could be of type
+`'string'` or `'buffer'`. If you use the `parseAs` option, Fastify will
+internally handle the stream and perform some checks, such as the [maximum
+size](./Server.md#factory-body-limit) of the body and the content length. If the
+limit is exceeded the custom parser will not be invoked.
 ```js
 fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
   try {
@@ -122,14 +149,20 @@ fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function
 })
 ```
 
-See [`example/parser.js`](../examples/parser.js) for an example.
+See
+[`example/parser.js`](https://github.com/fastify/fastify/blob/main/examples/parser.js)
+for an example.
 
 ##### Custom Parser Options
-+ `parseAs` (string): Either `'string'` or `'buffer'` to designate how the incoming data should be collected. Default: `'buffer'`.
-+ `bodyLimit` (number): The maximum payload size, in bytes, that the custom parser will accept. Defaults to the global body limit passed to the [`Fastify factory function`](Server.md#bodylimit).
++ `parseAs` (string): Either `'string'` or `'buffer'` to designate how the
+  incoming data should be collected. Default: `'buffer'`.
++ `bodyLimit` (number): The maximum payload size, in bytes, that the custom
+  parser will accept. Defaults to the global body limit passed to the [`Fastify
+  factory function`](./Server.md#bodylimit).
 
 #### Catch-All
-There are some cases where you need to catch all requests regardless of their content type. With Fastify, you can just use the `'*'` content type.
+There are some cases where you need to catch all requests regardless of their
+content type. With Fastify, you can just use the `'*'` content type.
 ```js
 fastify.addContentTypeParser('*', function (request, payload, done) {
   var data = ''
@@ -140,9 +173,11 @@ fastify.addContentTypeParser('*', function (request, payload, done) {
 })
 ```
 
-Using this, all requests that do not have a corresponding content type parser will be handled by the specified function.
+Using this, all requests that do not have a corresponding content type parser
+will be handled by the specified function.
 
-This is also useful for piping the request stream. You can define a content parser like:
+This is also useful for piping the request stream. You can define a content
+parser like:
 
 ```js
 fastify.addContentTypeParser('*', function (request, payload, done) {
@@ -158,7 +193,8 @@ app.post('/hello', (request, reply) => {
 })
 ```
 
-Here is a complete example that logs incoming [json line](https://jsonlines.org/) objects:
+Here is a complete example that logs incoming [json
+line](https://jsonlines.org/) objects:
 
 ```js
 const split2 = require('split2')
@@ -177,10 +213,12 @@ fastify.route({
 })
  ```
 
-For piping file uploads you may want to check out [this plugin](https://github.com/fastify/fastify-multipart).
+For piping file uploads you may want to check out [this
+plugin](https://github.com/fastify/fastify-multipart).
 
-If you really want the content type parser to be executed on all content types and not only on those that don't have a 
-specific one, you should call the `removeAllContentTypeParsers` method first.
+If you really want the content type parser to be executed on all content types
+and not only on those that don't have a specific one, you should call the
+`removeAllContentTypeParsers` method first.
 
 ```js
 // Without this call, the request body with the content type application/json would be processed by the built in json parser

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

@@ -2,20 +2,19 @@
 
 ## Decorators
 
-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 *synchronous*. Attempting to define a decoration
-asynchronously could result in the Fastify instance booting before the
-decoration completes 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 the handling of server, request, and reply objects. This is
+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 *synchronous*. Attempting to define a decoration asynchronously
+could result in the Fastify instance booting before the decoration completes 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 the handling of 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:
@@ -36,8 +35,8 @@ fastify.get('/', function (req, reply) {
 })
 ```
 
-Since the above example mutates the request object after it has already
-been instantiated, the JavaScript engine must deoptimize access to the request
+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
@@ -55,22 +54,26 @@ fastify.get('/', (req, reply) => {
 })
 ```
 
-Note that it is important to keep the initial shape of a decorated field as close as possible to the value intended to be set dynamically in the future. Initialize a decorator as a `''` if the intended value is a string, and as `null` if it will be an object or a function.
+Note that it is important to keep the initial shape of a decorated field as
+close as possible to the value intended to be set dynamically in the future.
+Initialize a decorator as a `''` if the intended value is a string, and as
+`null` if it will be an object or a function.
 
-Remember this example works only with value types as reference types will be shared amongst all requests.
-See [decorateRequest](#decorate-request).
+Remember this example works only with value types as reference types will be
+shared amongst all requests. See [decorateRequest](#decorate-request).
 
-See
-[JavaScript engine fundamentals: Shapes and Inline Caches](https://mathiasbynens.be/notes/shapes-ics)
-for more information on this topic.
+See [JavaScript engine fundamentals: Shapes and Inline
+Caches](https://mathiasbynens.be/notes/shapes-ics) for more information on this
+topic.
 
 ### Usage
-<a name="usage"></a>
+<a id="usage"></a>
 
 #### `decorate(name, value, [dependencies])`
-<a name="decorate"></a>
+<a id="decorate"></a>
 
-This method is used to customize the Fastify [server](Server.md) instance.
+This method is used to customize the Fastify [server](./Server.md)
+instance.
 
 For example, to attach a new method to the server instance:
 
@@ -89,8 +92,7 @@ fastify.decorate('conf', {
 })
 ```
 
-To access decorated properties, use the name provided to the
-decoration API:
+To access decorated properties, use the name provided to the decoration API:
 
 ```js
 fastify.utility()
@@ -98,7 +100,8 @@ fastify.utility()
 console.log(fastify.conf.db)
 ```
 
-The decorated [Fastify server](Server.md) is bound to `this` in route [route](Routes.md) handlers:
+The decorated [Fastify server](./Server.md) is bound to `this` in
+route [route](./Routes.md) handlers:
 
 ```js
 fastify.decorate('db', new DbConnection())
@@ -121,11 +124,11 @@ Note: using an arrow function will break the binding of `this` to the
 `FastifyInstance`.
 
 If a dependency is not satisfied, the `decorate` method will throw an exception.
-The dependency check is performed before the server instance is booted. Thus,
-it cannot occur during runtime.
+The dependency check is performed before the server instance is booted. Thus, it
+cannot occur during runtime.
 
 #### `decorateReply(name, value, [dependencies])`
-<a name="decorate-reply"></a>
+<a id="decorate-reply"></a>
 
 As the name suggests, this API is used to add new methods/properties to the core
 `Reply` object:
@@ -145,10 +148,11 @@ Note: using `decorateReply` will emit a warning if used with a reference type:
 // Don't do this
 fastify.decorateReply('foo', { bar: 'fizz'})
 ```
-In this example, the reference of the object is shared with all the requests: **any
-mutation will impact all requests, potentially creating security vulnerabilities or memory leaks**. 
-To achieve proper encapsulation across requests configure a new value for each incoming request
-in the [`'onRequest'` hook](Hooks.md#onrequest). Example:
+In this example, the reference of the object is shared with all the requests:
+**any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**. To achieve proper encapsulation across
+requests configure a new value for each incoming request in the [`'onRequest'`
+hook](./Hooks.md#onrequest). Example:
 
 ```js
 const fp = require('fastify-plugin')
@@ -157,7 +161,7 @@ async function myPlugin (app) {
   app.decorateRequest('foo', null)
   app.addHook('onRequest', async (req, reply) => {
     req.foo = { bar: 42 }
-  }) 
+  })
 }
 
 module.exports = fp(myPlugin)
@@ -166,7 +170,7 @@ module.exports = fp(myPlugin)
 See [`decorate`](#decorate) for information about the `dependencies` parameter.
 
 #### `decorateRequest(name, value, [dependencies])`
-<a name="decorate-request"></a>
+<a id="decorate-request"></a>
 
 As above with [`decorateReply`](#decorate-reply), this API is used add new
 methods/properties to the core `Request` object:
@@ -186,11 +190,12 @@ Note: using `decorateRequest` will emit a warning if used with a reference type:
 // Don't do this
 fastify.decorateRequest('foo', { bar: 'fizz'})
 ```
-In this example, the reference of the object is shared with all the requests: **any
-mutation will impact all requests, potentially creating security vulnerabilities or memory leaks**.
+In this example, the reference of the object is shared with all the requests:
+**any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**.
 
-To achieve proper encapsulation across requests configure a new value for each incoming request
-in the [`'onRequest'` hook](Hooks.md#onrequest). Example:
+To achieve proper encapsulation across requests configure a new value for each
+incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest). Example:
 
 ```js
 const fp = require('fastify-plugin')
@@ -199,7 +204,7 @@ async function myPlugin (app) {
   app.decorateRequest('foo', null)
   app.addHook('onRequest', async (req, reply) => {
     req.foo = { bar: 42 }
-  }) 
+  })
 }
 
 module.exports = fp(myPlugin)
@@ -208,7 +213,7 @@ module.exports = fp(myPlugin)
 See [`decorate`](#decorate) for information about the `dependencies` parameter.
 
 #### `hasDecorator(name)`
-<a name="has-decorator"></a>
+<a id="has-decorator"></a>
 
 Used to check for the existence of a server instance decoration:
 
@@ -217,7 +222,7 @@ fastify.hasDecorator('utility')
 ```
 
 #### hasRequestDecorator
-<a name="has-request-decorator"></a>
+<a id="has-request-decorator"></a>
 
 Used to check for the existence of a Request decoration:
 
@@ -226,7 +231,7 @@ fastify.hasRequestDecorator('utility')
 ```
 
 #### hasReplyDecorator
-<a name="has-reply-decorator"></a>
+<a id="has-reply-decorator"></a>
 
 Used to check for the existence of a Reply decoration:
 
@@ -235,7 +240,7 @@ fastify.hasReplyDecorator('utility')
 ```
 
 ### Decorators and Encapsulation
-<a name="decorators-encapsulation"></a>
+<a id="decorators-encapsulation"></a>
 
 Defining a decorator (using `decorate`, `decorateRequest`, or `decorateReply`)
 with the same name more than once in the same **encapsulated** context will
@@ -290,7 +295,7 @@ server.listen(3000)
 ```
 
 ### Getters and Setters
-<a name="getters-setters"></a>
+<a id="getters-setters"></a>
 
 Decorators accept special "getter/setter" objects. These objects have functions
 named `getter` and `setter` (though the `setter` function is optional). This

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

@@ -1,7 +1,7 @@
 <h1 align="center">Fastify</h1>
 
-<a id="encapsulation"></a>
 ## Encapsulation
+<a id="encapsulation"></a>
 
 A fundamental feature of Fastify is the "encapsulation context." The
 encapsulation context governs which [decorators](./Decorators.md), registered
@@ -9,7 +9,7 @@ encapsulation context governs which [decorators](./Decorators.md), registered
 [routes](./Routes.md). A visual representation of the encapsulation context
 is shown in the following figure:
 
-![Figure 1](./resources/encapsulation_context.svg)
+![Figure 1](../resources/encapsulation_context.svg)
 
 In the above figure, there are several entities:
 
@@ -122,8 +122,8 @@ To see this, start the server and issue requests:
 
 [bearer]: https://github.com/fastify/fastify-bearer-auth
 
-<a id="shared-context"></a>
 ## Sharing Between Contexts
+<a id="shared-context"></a>
 
 Notice that each context in the prior example inherits _only_ from the parent
 contexts. Parent contexts cannot access any entities within their descendent