fastify 3.27.4 → 4.0.0-alpha.3

package/docs/Reference/Server.md

@@ -47,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)
@@ -126,7 +127,7 @@ 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>
@@ -352,7 +353,7 @@ fastify.get('/', (req, reply) => {
   reply.send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 Internally Fastify uses the API of Node core HTTP server, so if you are using a
@@ -513,7 +514,8 @@ derive <code>request.hostname</code> and <code>request.protocol</code>**
 
 The maximum amount of time in *milliseconds* in which a plugin can load. If not,
 [`ready`](#ready) will complete with an `Error` with code
-`'ERR_AVVIO_PLUGIN_TIMEOUT'`.
+`'ERR_AVVIO_PLUGIN_TIMEOUT'`. When set to `0`, disables this check. This controls 
+[avvio](https://www.npmjs.com/package/avvio) 's `timeout` parameter.
 
 + Default: `10000`
 
@@ -553,7 +555,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>
@@ -599,28 +601,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'),
@@ -653,7 +641,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.
@@ -833,41 +821,40 @@ fastify.ready().then(() => {
 #### listen
 <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
+Starts the server and internally waits for the `.ready()` event. The
+signature is `.listen([options][, callback])`. Both the `options` object and the
+`callback` parameters follow the [Node.js
+core][https://nodejs.org/api/net.html#serverlistenoptions-callback] parameter
+definitions.
+
+By default, the server will listen on the address(es) resolved by `localhost` when no
+specific host 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.
+The following table details the possible values for `host` when targeting
+`localhost`, and what the result of those values for `host` will be.
+
+ 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
-fastify.listen(3000, (err, address) => {
-  if (err) {
-    fastify.log.error(err)
-    process.exit(1)
-  }
-})
-```
-
-Specifying an address is also supported:
-
-```js
-fastify.listen(3000, '127.0.0.1', (err, address) => {
-  if (err) {
-    fastify.log.error(err)
-    process.exit(1)
-  }
-})
-```
-
-Specifying a backlog queue size is also supported:
+The default is to listen on `port: 0` (which picks the first available open
+port) and `host: 'localhost'`:
 
 ```js
-fastify.listen(3000, '127.0.0.1', 511, (err, address) => {
+fastify.listen((err, address) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -875,12 +862,10 @@ fastify.listen(3000, '127.0.0.1', 511, (err, address) => {
 })
 ```
 
-Specifying options is also supported; the object is same as
-[options](https://nodejs.org/api/net.html#net_server_listen_options_callback) in
-the Node.js server listen:
+Specifying an address is also supported:
 
 ```js
-fastify.listen({ port: 3000, host: '127.0.0.1', backlog: 511 }, (err) => {
+fastify.listen({ port: 3000, host: '127.0.0.1' }, (err, address) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -891,29 +876,7 @@ fastify.listen({ port: 3000, host: '127.0.0.1', backlog: 511 }, (err) => {
 If no callback is provided a Promise is returned:
 
 ```js
-fastify.listen(3000)
-  .then((address) => console.log(`server listening on ${address}`))
-  .catch(err => {
-    console.log('Error starting server:', err)
-    process.exit(1)
-  })
-```
-
-Specifying an address without a callback is also supported:
-
-```js
-fastify.listen(3000, '127.0.0.1')
-  .then((address) => console.log(`server listening on ${address}`))
-  .catch(err => {
-    console.log('Error starting server:', err)
-    process.exit(1)
-  })
-```
-
-Specifying options without a callback is also supported:
-
-```js
-fastify.listen({ port: 3000, host: '127.0.0.1', backlog: 511 })
+fastify.listen({ port: 3000 })
   .then((address) => console.log(`server listening on ${address}`))
   .catch(err => {
     console.log('Error starting server:', err)
@@ -926,7 +889,7 @@ to listen on `0.0.0.0` because they do not default to exposing mapped ports to
 `localhost`:
 
 ```js
-fastify.listen(3000, '0.0.0.0', (err, address) => {
+fastify.listen({ port: 3000, host: '0.0.0.0' }, (err, address) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -935,7 +898,7 @@ fastify.listen(3000, '0.0.0.0', (err, address) => {
 ```
 
 If the `port` is omitted (or is set to zero), a random available port is
-automatically chosen (later available via `fastify.server.address().port`).
+automatically chosen (available via `fastify.server.address().port`).
 
 The default options of listen are:
 
@@ -950,6 +913,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({ port: 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>
 
@@ -1188,8 +1169,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({
@@ -1264,39 +1247,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>
 
@@ -1485,7 +1435,7 @@ fastify.addContentTypeParser('text/json', { asString: true }, fastify.getDefault
 #### hasContentTypeParser
 <a id="hasContentTypeParser"></a>
 
-`fastify.hasContentTypeParser(contentType)` is used to check whether there is a content type parser in the current 
+`fastify.hasContentTypeParser(contentType)` is used to check whether there is a content type parser in the current
 context for the specified content type.
 
 ```js
@@ -1629,7 +1579,7 @@ fastify.register(async (instance, opts) => {
 })
 
 // Start listening.
-fastify.listen(3000, (err) => {
+fastify.listen({ port: 3000 }, (err) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)

package/docs/Reference/TypeScript.md

@@ -72,7 +72,7 @@ in a blank http Fastify server.
      return 'pong\n'
    })
 
-   server.listen(8080, (err, address) => {
+   server.listen({ port: 8080 }, (err, address) => {
      if (err) {
        console.error(err)
        process.exit(1)
@@ -360,7 +360,7 @@ into TypeScript interfaces!
      }
    })
 
-   server.listen(8080, (err, address) => {
+   server.listen({ port: 8080 }, (err, address) => {
      if (err) {
        console.error(err)
        process.exit(0)
@@ -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
@@ -680,21 +681,21 @@ There are a couple supported import methods with the Fastify type system.
      import fastify from 'fastify'
 
      const f = fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
    - Gain access to types with destructuring:
      ```typescript
      import fastify, { FastifyInstance } from 'fastify'
 
      const f: FastifyInstance = fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
    - Destructuring also works for the main API method:
      ```typescript
      import { fastify, FastifyInstance } from 'fastify'
 
      const f: FastifyInstance = fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
 2. `import * as Fastify from 'fastify'`
    - Types are resolved and accessible using dot notation
@@ -705,7 +706,7 @@ There are a couple supported import methods with the Fastify type system.
      import * as Fastify from 'fastify'
 
      const f: Fastify.FastifyInstance = Fastify.fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
 3. `const fastify = require('fastify')`
    - This syntax is valid and will import fastify as expected; however, types
@@ -715,14 +716,14 @@ There are a couple supported import methods with the Fastify type system.
      const fastify = require('fastify')
 
      const f = fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
    - Destructuring is supported and will resolve types properly
      ```typescript
      const { fastify } = require('fastify')
 
      const f = fastify()
-     f.listen(8080, () => { console.log('running') })
+     f.listen({ port: 8080 }, () => { console.log('running') })
      ```
 
 #### Generics
@@ -824,7 +825,7 @@ a more detailed http server walkthrough.
      return { hello: 'world' }
    })
 
-   server.listen(8080, (err, address) => {
+   server.listen({ port: 8080 }, (err, address) => {
      if (err) {
        console.error(err)
        process.exit(0)
@@ -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,11 +4,13 @@
 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
 > features dynamically evaluate code with `new Function()`, which is not safe to
@@ -26,8 +28,7 @@ as described in the documentation for the [content type parser](./ContentTypePar
 ### 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
 
@@ -146,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
@@ -232,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 = {
@@ -258,37 +258,14 @@ const opts = {
 }
 
 fastify.get('/', opts, (request, reply) => {
-  reply.send({ params: request.query })
+  reply.send({ params: request.query }) // echo the querystring
 })
 
-fastify.listen(3000, (err) => {
+fastify.listen({ port: 3000 }, (err) => {
   if (err) throw 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
 
@@ -342,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
 
@@ -412,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
 }
 ```
 
@@ -435,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
   // ...
 })
@@ -460,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: {
@@ -512,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.
 
@@ -529,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