fastify 3.26.0 → 4.0.0-alpha.1

package/docs/Reference/Server.md

@@ -13,6 +13,7 @@ describes the properties available in that options object.
   - [`https`](#https)
   - [`connectionTimeout`](#connectiontimeout)
   - [`keepAliveTimeout`](#keepalivetimeout)
+  - [`forceCloseConnections`](#forcecloseconnections)
   - [`maxRequestsPerSocket`](#maxrequestspersocket)
   - [`requestTimeout`](#requesttimeout)
   - [`ignoreTrailingSlash`](#ignoretrailingslash)
@@ -46,6 +47,7 @@ describes the properties available in that options object.
     - [after](#after)
     - [ready](#ready)
     - [listen](#listen)
+    - [addresses](#addresses)
     - [getDefaultRoute](#getdefaultroute)
     - [setDefaultRoute](#setdefaultroute)
     - [routing](#routing)
@@ -76,6 +78,9 @@ describes the properties available in that options object.
     - [printRoutes](#printroutes)
     - [printPlugins](#printplugins)
     - [addContentTypeParser](#addcontenttypeparser)
+    - [hasContentTypeParser](#hasContentTypeParser)
+    - [removeContentTypeParser](#removeContentTypeParser)
+    - [removeAllContentTypeParsers](#removeAllContentTypeParsers)
     - [getDefaultJsonParser](#getdefaultjsonparser)
     - [defaultTextParser](#defaulttextparser)
     - [errorHandler](#errorhandler)
@@ -122,7 +127,20 @@ property](https://nodejs.org/api/http.html#http_server_keepalivetimeout) to
 understand the effect of this option. This option only applies when HTTP/1 is in
 use. Also, when `serverFactory` option is specified, this option is ignored.
 
-+ Default: `5000` (5 seconds)
++ Default: `72000` (72 seconds)
+
+### `forceCloseConnections`
+<a id="forcecloseconnections"></a>
+
+When set to `true` requests with the header `connection: keep-alive` will be
+tracked by the server. Upon [`close`](#close), the server will iterate the
+current persistent connections and [destroy their
+sockets](https://nodejs.org/dist/latest-v16.x/docs/api/net.html#socketdestroyerror).
+This means the server will shutdown immediately instead of waiting for existing
+persistent connections to timeout first. Important: connections are not
+inspected to determine if requests have been completed.
+
++ Default: `false`
 
 ### `maxRequestsPerSocket`
 <a id="factory-max-requests-per-socket"></a>
@@ -536,7 +554,7 @@ Automatically creates a sibling `HEAD` route for each `GET` route defined. If
 you want a custom `HEAD` handler without disabling this option, make sure to
 define it before the `GET` route.
 
-+ Default: `false`
++ Default: `true`
 
 ### `constraints`
 <a id="constraints"></a>
@@ -582,28 +600,14 @@ the incoming request as usual.
 ### `ajv`
 <a id="factory-ajv"></a>
 
-Configure the Ajv v6 instance used by Fastify without providing a custom one.
-
-+ Default:
-
-```js
-{
-  customOptions: {
-    removeAdditional: true,
-    useDefaults: true,
-    coerceTypes: true,
-    allErrors: false,
-    nullable: true
-  },
-  plugins: []
-}
-```
+Configure the Ajv v8 instance used by Fastify without providing a custom one.
+The default configuration is explained in the [#schema-validator](Validation-and-Serialization.md#schema-validator) section.
 
 ```js
 const fastify = require('fastify')({
   ajv: {
     customOptions: {
-      nullable: false // Refer to [ajv options](https://github.com/ajv-validator/ajv/tree/v6#options)
+      removeAdditional: 'all' // Refer to [ajv options](https://ajv.js.org/#options)
     },
     plugins: [
       require('ajv-merge-patch'),
@@ -636,7 +640,7 @@ const fastify = require('fastify')({
 Set a default
 [timeout](https://nodejs.org/api/http2.html#http2_http2session_settimeout_msecs_callback)
 to every incoming HTTP/2 session. The session will be closed on the timeout.
-Default: `5000` ms.
+Default: `72000` ms.
 
 Note that this is needed to offer the graceful "close" experience when using
 HTTP/2. The low default has been chosen to mitigate denial of service attacks.
@@ -817,14 +821,25 @@ fastify.ready().then(() => {
 <a id="listen"></a>
 
 Starts the server on the given port after all the plugins are loaded, internally
-waits for the `.ready()` event. The callback is the same as the Node core. By
-default, the server will listen on the address resolved by `localhost` when no
-specific address is provided (`127.0.0.1` or `::1` depending on the operating
-system). If listening on any available interface is desired, then specifying
-`0.0.0.0` for the address will listen on all IPv4 addresses. Using `::` for the
-address will listen on all IPv6 addresses and, depending on OS, may also listen
-on all IPv4 addresses. Be careful when deciding to listen on all interfaces; it
-comes with inherent [security
+waits for the `.ready()` event. The callback is the same as the Node core.
+
+By default, the server will listen on the address(es) resolved by `localhost` when no
+specific address is provided. If listening on any available interface is desired,
+then specifying `0.0.0.0` for the address will listen on all IPv4 addresses.
+
+ Host          | IPv4 | IPv6
+ --------------|------|-------
+ `::`            | ✅<sup>*</sup> | ✅
+ `::` + [`ipv6Only`](https://nodejs.org/api/net.html#serverlistenoptions-callback) | 🚫 | ✅
+ `0.0.0.0`       | ✅ | 🚫
+ `localhost`     | ✅ | ✅
+ `127.0.0.1`     | ✅ | 🚫
+ `::1`           | 🚫 | ✅
+
+<sup>*</sup> Using `::` for the address will listen on all IPv6 addresses and, depending on OS,
+may also listen on [all IPv4 addresses](https://nodejs.org/api/net.html#serverlistenport-host-backlog-callback).
+
+Be careful when deciding to listen on all interfaces; it comes with inherent [security
 risks](https://web.archive.org/web/20170831174611/https://snyk.io/blog/mongodb-hack-and-secure-defaults/).
 
 ```js
@@ -933,6 +948,24 @@ fastify.listen({
 }, (err) => {})
 ```
 
+#### addresses
+<a id="addresses"></a>
+
+This method returns an array of addresses that the server is listening on.
+If you call it before `listen()` is called or after the `close()` function,
+it will return an empty array.
+
+```js
+await fastify.listen(8080)
+const addresses = fastify.addresses()
+// [
+//   { port: 8080, family: 'IPv6', address: '::1' },
+//   { port: 8080, family: 'IPv4', address: '127.0.0.1' }
+// ]
+```
+
+Note that the array contains the `fastify.server.address()` too.
+
 #### getDefaultRoute
 <a id="getDefaultRoute"></a>
 
@@ -1171,8 +1204,10 @@ unknown to Fastify. See [issue
 #2446](https://github.com/fastify/fastify/issues/2446) for an example of what
 this property helps to resolve.
 
-Another use case is to tweak all the schemas processing. Doing so it is possible
-to use Ajv v8, instead of the default v6! We will see an example of this later.
+Another use case is to tweak all the schemas processing.
+Doing so it is possible to use Ajv v8 JTD or Standalone feature. To use such
+as JTD or the Standalone mode, refers to the
+[`@fastify/ajv-compiler` documentation](https://github.com/fastify/ajv-compiler#usage).
 
 ```js
 const fastify = Fastify({
@@ -1247,39 +1282,6 @@ const fastify = Fastify({
 });
 ```
 
-##### Ajv 8 as default schema validator
-
-Ajv 8 is the evolution of Ajv 6, and it has a lot of improvements and new
-features. To use the new Ajv 8 features such as JTD or the Standalone mode,
-refer to the [`@fastify/ajv-compiler`
-documentation](https://github.com/fastify/ajv-compiler#usage).
-
-To use Ajv 8 as default schema validator, you can use the following code:
-
-```js
-const AjvCompiler = require('@fastify/ajv-compiler') // It must be the v2.x.x version
-
-// Note that the `format` schema's keyword is no longer supported on Ajv 8 by default.
-// So you need to add it manually.
-const ajvFormats = require('ajv-formats')
-
-const app = fastify({
-  ajv: {
-    customOptions: {
-      validateFormats: true
-    },
-    plugins: [ajvFormats]
-  },
-  schemaController: {
-    compilersFactory: {
-      buildValidator: AjvCompiler()
-    }
-  }
-})
-
-// Done! You can now use Ajv 8 options and keywords in your schemas!
-```
-
 #### setNotFoundHandler
 <a id="set-not-found-handler"></a>
 
@@ -1465,6 +1467,39 @@ content types, e.g. `text/json, application/vnd.oasis.opendocument.text`.
 fastify.addContentTypeParser('text/json', { asString: true }, fastify.getDefaultJsonParser('ignore', 'ignore'))
 ```
 
+#### hasContentTypeParser
+<a id="hasContentTypeParser"></a>
+
+`fastify.hasContentTypeParser(contentType)` is used to check whether there is a content type parser in the current 
+context for the specified content type.
+
+```js
+fastify.hasContentTypeParser('text/json')
+
+fastify.hasContentTypeParser(/^.+\/json$/)
+```
+
+#### removeContentTypeParser
+<a id="removeContentTypeParser"></a>
+
+`fastify.removeContentTypeParser(contentType)` is used to remove content type parsers in the current context. This
+method allows for example to remove the both built-in parsers for `application/json` and `text/plain`.
+
+```js
+fastify.removeContentTypeParser('application/json')
+
+fastify.removeContentTypeParser(['application/json', 'text/plain'])
+```
+
+#### removeAllContentTypeParsers
+<a id="removeAllContentTypeParsers"></a>
+
+The `fastify.removeAllContentTypeParsers()` method allows all content type parsers in the current context to be removed.
+A use case of this method is the implementation of catch-all content type parser. Before adding this parser with
+`fastify.addContentTypeParser()` one could call the `removeAllContentTypeParsers` method.
+
+For more details about the usage of the different content type parser APIs see [here](./ContentTypeParser.md#usage).
+
 #### getDefaultJsonParser
 <a id="getDefaultJsonParser"></a>
 

package/docs/Reference/TypeScript.md

@@ -399,7 +399,7 @@ const todo = {
     done: { type: 'boolean' },
   },
   required: ['name'],
-} as const;
+} as const; // don't forget to use const !
 ```
 
 With the provided type `FromSchema` you can build a type from your schema and
@@ -487,6 +487,7 @@ Fastify Plugin in a TypeScript Project.
    import fp from 'fastify-plugin'
 
    // using declaration merging, add your plugin props to the appropriate fastify interfaces
+   // if prop type is defined here, the value will be typechecked when you call decorate{,Request,Reply}
    declare module 'fastify' {
      interface FastifyRequest {
        myPluginProp: string
@@ -877,26 +878,23 @@ server.get('/', async (request, reply) => {
 
 ###### Example 5: Specifying logger types
 
-Fastify uses [Pino](https://getpino.io/#/) logging library under the hood. Some
-of it's properties can be configured via `logger` field when constructing
-Fastify's instance. If properties you need aren't exposed, it's also possible to
-pass a preconfigured external instance of Pino (or any other compatible logger)
-to Fastify via the same field. This allows creating custom serializers as well,
-see the [Logging](./Logging.md) documentation for more info.
-
-To use an external instance of Pino, add `@types/pino` to devDependencies and
-pass the instance to `logger` field:
+Fastify uses [Pino](https://getpino.io/#/) logging library under the hood. Since
+`pino@7`, all of it's properties can be configured via `logger` field when
+constructing Fastify's instance. If properties you need aren't exposed, please
+open an Issue to [`Pino`](https://github.com/pinojs/pino/issues) or pass a
+preconfigured external instance of Pino (or any other compatible logger) as
+temporary fix to Fastify via the same field. This allows creating custom
+serializers as well, see the [Logging](Logging.md) documentation for more info.
 
 ```typescript
 import fastify from 'fastify'
-import pino from 'pino'
 
 const server = fastify({
-  logger: pino({
+  logger: {
     level: 'info',
     redact: ['x-userinfo'],
     messageKey: 'message'
-  })
+  }
 })
 
 server.get('/', async (request, reply) => {

package/docs/Reference/Validation-and-Serialization.md

@@ -4,7 +4,12 @@
 Fastify uses a schema-based approach, and even if it is not mandatory we
 recommend using [JSON Schema](https://json-schema.org/) to validate your routes
 and serialize your outputs. Internally, Fastify compiles the schema into a
-highly performant function.
+highly performant function. 
+
+Validation will only be attempted if the content type is `application-json`,
+as described in the documentation for the [content type parser](./ContentTypeParser.md).
+
+All the examples in this section are using the [JSON Schema Draft 7](https://json-schema.org/specification-links.html#draft-7) specification.
 
 > ## ⚠  Security Notice
 > Treat the schema definition as application code. Validation and serialization
@@ -23,8 +28,7 @@ highly performant function.
 ### Core concepts
 The validation and the serialization tasks are processed by two different, and
 customizable, actors:
-- [Ajv v6](https://www.npmjs.com/package/ajv/v/6.12.6) for the validation of a
-  request
+- [Ajv v8](https://www.npmjs.com/package/ajv) for the validation of a request
 - [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) for
   the serialization of a response's body
 
@@ -143,10 +147,11 @@ fastify.register((instance, opts, done) => {
 
 
 ### Validation
-The route validation internally relies upon [Ajv
-v6](https://www.npmjs.com/package/ajv/v/6.12.6) which is a high-performance JSON
-Schema validator. Validating the input is very easy: just add the fields that
-you need inside the route schema, and you are done!
+The route validation internally relies upon
+[Ajv v8](https://www.npmjs.com/package/ajv) which is a high-performance
+JSON Schema validator.
+Validating the input is very easy: just add the fields that you need
+inside the route schema, and you are done!
 
 The supported validations are:
 - `body`: validates the body of the request if it is a POST, PUT, or PATCH
@@ -229,15 +234,13 @@ const schema = {
 fastify.post('/the/url', { schema }, handler)
 ```
 
-*Note that Ajv will try to
-[coerce](https://github.com/epoberezkin/ajv#coercing-data-types) the values to
+*Note that Ajv will try to [coerce](https://ajv.js.org/coercion.html) the values to
 the types specified in your schema `type` keywords, both to pass the validation
 and to use the correctly typed data afterwards.*
 
-The Ajv default configuration in Fastify doesn't support coercing array
-parameters in querystring. However, Fastify allows
-[`customOptions`](./Server.md#ajv) in Ajv instance. The `coerceTypes: 'array'`
-will coerce one parameter to a single element in array. Example:
+The Ajv default configuration in Fastify supports coercing array
+parameters in `querystring`.  
+Example:
 
 ```js
 const opts = {
@@ -255,7 +258,7 @@ const opts = {
 }
 
 fastify.get('/', opts, (request, reply) => {
-  reply.send({ params: request.query })
+  reply.send({ params: request.query }) // echo the querystring
 })
 
 fastify.listen(3000, (err) => {
@@ -263,29 +266,6 @@ fastify.listen(3000, (err) => {
 })
 ```
 
-Using Fastify defaults the following request will result in `400` status code:
-
-```sh
-curl -X GET "http://localhost:3000/?ids=1
-
-{"statusCode":400,"error":"Bad Request","message":"querystring/hello should be array"}
-```
-
-Using `coerceTypes` as 'array' will fix it:
-
-```js
-const ajv = new Ajv({
-  removeAdditional: true,
-  useDefaults: true,
-  coerceTypes: 'array', // This line
-  allErrors: true
-})
-
-fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
-  return ajv.compile(schema)
-})
-```
-
 ```sh
 curl -X GET "http://localhost:3000/?ids=1
 
@@ -339,8 +319,8 @@ For further information see [here](https://ajv.js.org/coercion.html)
 #### Ajv Plugins
 <a id="ajv-plugins"></a>
 
-You can provide a list of plugins you want to use with the default `ajv`
-instance. Note that the plugin must be **compatible with Ajv v6**.
+You can provide a list of plugins you want to use with the default `ajv` instance.  
+Note that the plugin must be **compatible with the Ajv version shipped within Fastify**.
 
 > Refer to [`ajv options`](./Server.md#ajv) to check plugins format
 
@@ -409,16 +389,16 @@ body, URL  parameters, headers, and query string. The default
 [ajv](https://ajv.js.org/) validation interface. Fastify uses it internally to
 speed the validation up.
 
-Fastify's [baseline ajv
-configuration](https://github.com/epoberezkin/ajv#options-to-modify-validated-data)
-is:
+Fastify's [baseline ajv configuration](https://github.com/fastify/ajv-compiler#ajv-configuration) is:
 
 ```js
 {
-  removeAdditional: true, // remove additional properties
-  useDefaults: true, // replace missing properties and items with the values from corresponding default keyword
   coerceTypes: true, // change data type of data to match type keyword
-  nullable: true     // support keyword "nullable" from Open API 3 specification.
+  useDefaults: true, // replace missing properties and items with the values from corresponding default keyword
+  removeAdditional: true, // remove additional properties
+  // Explicitly set allErrors to `false`.
+  // When set to `true`, a DoS attack is possible.
+  allErrors: false
 }
 ```
 
@@ -432,11 +412,9 @@ your own instance and override the existing one like:
 const fastify = require('fastify')()
 const Ajv = require('ajv')
 const ajv = new Ajv({
-  // the fastify defaults (if needed)
-  removeAdditional: true,
+  removeAdditional: 'all',
   useDefaults: true,
-  coerceTypes: true,
-  nullable: true,
+  coerceTypes: 'array',
   // any other options
   // ...
 })
@@ -457,7 +435,7 @@ almost any Javascript validation library ([joi](https://github.com/hapijs/joi/),
 [yup](https://github.com/jquense/yup/), ...) or a custom one:
 
 ```js
-const Joi = require('@hapi/joi')
+const Joi = require('joi')
 
 fastify.post('/the/url', {
   schema: {
@@ -509,8 +487,8 @@ fastify.post('/the/url', {
 
 Fastify's validation error messages are tightly coupled to the default
 validation engine: errors returned from `ajv` are eventually run through the
-`schemaErrorsText` function which is responsible for building human-friendly
-error messages. However, the `schemaErrorsText` function is written with `ajv`
+`schemaErrorFormatter` function which is responsible for building human-friendly
+error messages. However, the `schemaErrorFormatter` function is written with `ajv`
 in mind : as a result, you may run into odd or incomplete error messages when
 using other validation libraries.
 
@@ -526,9 +504,9 @@ To circumvent this issue, you have 2 main options :
 To help you in writing a custom `errorHandler`, Fastify adds 2 properties to all
 validation errors:
 
-* validation: the content of the `error` property of the object returned by the
+* `validation`: the content of the `error` property of the object returned by the
   validation function (returned by your custom `schemaCompiler`)
-* validationContext: the 'context' (body, params, query, headers) where the
+* `validationContext`: the 'context' (body, params, query, headers) where the
   validation error occurred
 
 A very contrived example of such a custom `errorHandler` handling validation