fastify 3.27.2 → 4.0.0-alpha.1

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>
@@ -553,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>
@@ -599,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'),
@@ -653,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.
@@ -834,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
@@ -950,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>
 
@@ -1188,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({
@@ -1264,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>
 

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

@@ -9,6 +9,8 @@ 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,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) => {
@@ -266,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
 
@@ -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

package/docs/Type-Providers.md

@@ -0,0 +1,257 @@
+<h1 align="center">Fastify</h1>
+
+## Type Providers
+
+Type Providers are a TypeScript only feature that enables Fastify to statically infer type information directly from inline JSON Schema. They are an alternative to specifying generic arguments on routes; and can greatly reduce the need to keep associated types for each schema defined in your project.
+
+### Providers
+
+Type Providers are offered as additional packages you will need to install into your project. Each provider uses a different inference library under the hood; allowing you to select the library most appropriate for your needs. Type Provider packages follow a `fastify-type-provider-{provider-name}` naming convention. 
+
+The following inference packages are supported:
+
+- `json-schema-to-ts` - [github](https://github.com/ThomasAribart/json-schema-to-ts)
+- `typebox` - [github](https://github.com/sinclairzx81/typebox)
+
+### Json Schema to Ts
+
+The following sets up a `json-schema-to-ts` Type Provider
+
+```bash
+$ npm install fastify-type-provider-json-schema-to-ts --save
+```
+
+```typescript
+import { JsonSchemaToTsTypeProvider } from 'fastify-type-provider-json-schema-to-ts'
+
+import fastify from 'fastify'
+
+const server = fastify().withTypeProvider<JsonSchemaToTsTypeProvider>()
+
+server.get('/route', {
+    schema: {
+        querystring: {
+            type: 'object',
+            properties: {
+                foo: { type: 'number' },
+                bar: { type: 'string' },
+            },
+            required: ['foo', 'bar']
+        }
+    } as const // don't forget to use const !
+
+}, (request, reply) => {
+
+    // type Query = { foo: number, bar: string }
+
+    const { foo, bar } = request.query // type safe!
+})
+```
+
+### TypeBox
+
+The following sets up a TypeBox Type Provider
+
+```bash
+$ npm install fastify-type-provider-typebox --save
+```
+
+```typescript
+import { TypeBoxTypeProvider, Type } from 'fastify-type-provider-typebox'
+
+import fastify from 'fastify'
+
+const server = fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+server.get('/route', {
+    schema: {
+        querystring: Type.Object({
+            foo: Type.Number(),
+            bar: Type.String()
+        })
+    }
+}, (request, reply) => {
+
+    // type Query = { foo: number, bar: string }
+
+    const { foo, bar } = request.query // type safe!
+})
+```
+
+TypeBox uses the properties `kind` and `modifier` internally. These properties are not strictly valid JSON schema which will cause `AJV@7` and newer versions to throw an invalid schema error. To remove the error it's either necessary to omit the properties by using [`Type.Strict()`](https://github.com/sinclairzx81/typebox#strict) or use the AJV options for adding custom keywords.
+
+See also the [TypeBox documentation](https://github.com/sinclairzx81/typebox#validation) on how to set up AJV to work with TypeBox.
+
+### Scoped Type-Provider
+
+The provider types don't propagate globally. In encapsulated usage, one can remap the context to use one or more providers (for example, `typebox` and `json-schema-to-ts` can be used in the same application).
+
+Example:
+
+```ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { Type } from '@sinclair/typebox'
+
+const fastify = Fastify()
+
+function pluginWithTypebox(fastify: FastifyInstance, _opts, done): void {
+  fastify.withTypeProvider<TypeBoxTypeProvider>()
+    .get('/', {
+      schema: {
+        body: Type.Object({
+          x: Type.String(),
+          y: Type.Number(),
+          z: Type.Boolean()
+        })
+      }
+    }, (req) => {
+        const { x, y, z } = req.body // type safe
+    });
+  done()
+}
+
+function pluginWithJsonSchema(fastify: FastifyInstance, _opts, done): void {
+  fastify.withTypeProvider<JsonSchemaToTsProvider>()
+    .get('/', {
+      schema: {
+        body: {
+          type: 'object',
+          properties: {
+            x: { type: 'string' },
+            y: { type: 'number' },
+            z: { type: 'boolean' }
+          },
+        } as const
+      }
+    }, (req) => {
+      const { x, y, z } = req.body // type safe
+    });
+  done()
+}
+
+fastify.register(pluginWithJsonSchema)
+fastify.register(pluginWithTypebox)
+```
+
+It's also important to mention that once the types don't propagate globally, _currently_ is not possible to avoid multiple registrations on routes when dealing with several scopes, see bellow:
+
+```ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { Type } from '@sinclair/typebox'
+
+const server = Fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+server.register(plugin1) // wrong
+server.register(plugin2) // correct
+
+function plugin1(fastify: FastifyInstance, _opts, done): void {
+  fastify.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // it doesn't works! in a new scope needs to call `withTypeProvider` again
+    const { x, y, z } = req.body
+  });
+  done()
+}
+
+function plugin2(fastify: FastifyInstance, _opts, done): void {
+  const server = fastify.withTypeProvider<TypeBoxTypeProvider>()
+
+  server.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // works
+    const { x, y, z } = req.body
+  });
+  done()
+}
+```
+
+### Type Definition of FastifyInstance + TypeProvider
+
+When working with modules one has to make use of `FastifyInstance` with Type Provider generics. See the example below:
+
+```ts
+// index.ts
+import Fastify from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+import { registerRoutes } from './routes'
+
+const server = Fastify({
+    ajv: {
+        customOptions: {
+            strict: 'log',
+            keywords: ['kind', 'modifier'],
+        },
+    },
+}).withTypeProvider<TypeBoxTypeProvider>()
+
+registerRoutes(server)
+
+server.listen(3000)
+```
+
+```ts
+// routes.ts
+import { Type } from '@sinclair/typebox'
+import {
+  FastifyInstance,
+  FastifyLoggerInstance,
+  RawReplyDefaultExpression,
+  RawRequestDefaultExpression,
+  RawServerDefault
+} from 'fastify'
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
+
+type FastifyTypebox = FastifyInstance<
+  RawServerDefault,
+  RawRequestDefaultExpression<RawServerDefault>,
+  RawReplyDefaultExpression<RawServerDefault>,
+  FastifyLoggerInstance,
+  TypeBoxTypeProvider
+>;
+
+export function registerRoutes(fastify: FastifyTypebox): void {
+  fastify.get('/', {
+    schema: {
+      body: Type.Object({
+        x: Type.String(),
+        y: Type.Number(),
+        z: Type.Boolean()
+      })
+    }
+  }, (req) => {
+    // works
+    const { x, y, z } = req.body
+  });
+}
+```

package/examples/hooks.js

@@ -37,7 +37,7 @@ fastify
     console.log('onRequest')
     done()
   })
-  .addHook('preParsing', function (request, reply, done) {
+  .addHook('preParsing', function (request, reply, payload, done) {
     console.log('preParsing')
     done()
   })

package/examples/simple-stream.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const fastify = require('../fastify')({
+  logger: false
+})
+
+const Readable = require('stream').Readable
+
+fastify
+  .get('/', function (req, reply) {
+    const stream = Readable.from(['hello world'])
+    reply.send(stream)
+  })
+
+fastify.listen(3000, (err, address) => {
+  if (err) throw err
+  fastify.log.info(`server listening on ${address}`)
+})