fastify 3.27.3 → 4.0.0-alpha.2

package/.taprc

@@ -4,3 +4,6 @@ flow: false
 check-coverage: true
 coverage: true
 node-arg: --allow-natives-syntax
+
+files:
+  - 'test/**/*.test.js'

package/README.md

@@ -1,5 +1,4 @@
-<div align="center">
-  <a href="https://fastify.io/">
+<div align="center"> <a href="https://fastify.io/">
     <img src="https://github.com/fastify/graphics/raw/HEAD/fastify-landscape-outlined.svg" width="650" height="auto"/>
   </a>
 </div>
@@ -10,7 +9,6 @@
 [![Package Manager CI](https://github.com/fastify/fastify/workflows/package-manager-ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/package-manager-ci.yml)
 [![Web SIte](https://github.com/fastify/fastify/workflows/website/badge.svg)](https://github.com/fastify/fastify/actions/workflows/website.yml)
 [![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify/badge.svg)](https://snyk.io/test/github/fastify/fastify)
-[![Coverage Status](https://coveralls.io/repos/github/fastify/fastify/badge.svg?branch=main)](https://coveralls.io/github/fastify/fastify?branch=main)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 
 </div>
@@ -45,6 +43,8 @@ How can you efficiently handle the resources of your server, knowing that you ar
 
 Enter Fastify. Fastify is a web framework highly focused on providing the best developer experience with the least overhead and a powerful plugin architecture. It is inspired by Hapi and Express and as far as we know, it is one of the fastest web frameworks in town.
 
+This branch refers to the upcoming Fastify v4 release. Check out the [v3.x](https://github.com/fastify/fastify/tree/v3.x) branch for v3.
+
 ### Quick start
 
 Create a folder and make it your current working directory:
@@ -88,11 +88,11 @@ If installing in an existing project, then Fastify can be installed into the pro
 
 Install with npm:
 ```sh
-npm i fastify --save
+npm i fastify@next --save
 ```
 Install with yarn:
 ```sh
-yarn add fastify
+yarn add fastify@next
 ```
 
 ### Example
@@ -116,7 +116,7 @@ fastify.get('/', (request, reply) => {
 })
 
 // Run the server!
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) throw err
   // Server is now listening on ${address}
 })
@@ -140,7 +140,7 @@ fastify.get('/', async (request, reply) => {
   return { hello: 'world' }
 })
 
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) throw err
   // Server is now listening on ${address}
 })

package/build/build-error-serializer.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const FJS = require('fast-json-stringify')
+const path = require('path')
+const fs = require('fs')
+
+const debugCompiled = FJS({
+  type: 'object',
+  properties: {
+    statusCode: { type: 'number' },
+    code: { type: 'string' },
+    error: { type: 'string' },
+    message: { type: 'string' }
+  }
+}, { debugMode: true })
+
+const file = path.join(__dirname, '..', 'lib', 'error-serializer.js')
+const rawString = debugCompiled.toString()
+
+const moduleCode = `// This file is autogenerated by build/build-error-serializer.js, do not edit
+/* istanbul ignore file */
+module.exports = $main
+${rawString.slice(5)}
+`
+
+fs.writeFileSync(file, moduleCode)
+console.log(`Saved ${file} file successfully`)

package/build/build-validation.js

@@ -1,20 +1,29 @@
 'use strict'
 
-const Ajv = require('ajv')
+const AjvStandaloneCompiler = require('@fastify/ajv-compiler/standalone')
+const { _ } = require('ajv')
 const fs = require('fs')
 const path = require('path')
-const pack = require('ajv-pack')
 
-const ajv = new Ajv({
-  sourceCode: true, // this option is required by ajv-pack
-  removeAdditional: true,
-  useDefaults: true,
-  coerceTypes: true
+const factory = AjvStandaloneCompiler({
+  readMode: false,
+  storeFunction (routeOpts, schemaValidationCode) {
+    const moduleCode = `// This file is autogenerated by ${__filename.replace(__dirname, 'build')}, do not edit
+/* istanbul ignore file */
+${schemaValidationCode}
+
+module.exports.defaultInitOptions = ${JSON.stringify(defaultInitOptions)}
+`
+
+    const file = path.join(__dirname, '..', 'lib', 'configValidator.js')
+    fs.writeFileSync(file, moduleCode)
+    console.log(`Saved ${file} file successfully`)
+  }
 })
 
 const defaultInitOptions = {
   connectionTimeout: 0, // 0 sec
-  keepAliveTimeout: 5000, // 5 sec
+  keepAliveTimeout: 72000, // 72 seconds
   forceCloseConnections: false, // keep-alive connections
   maxRequestsPerSocket: 0, // no limit
   requestTimeout: 0, // no limit
@@ -29,21 +38,10 @@ const defaultInitOptions = {
   pluginTimeout: 10000,
   requestIdHeader: 'request-id',
   requestIdLogLabel: 'reqId',
-  http2SessionTimeout: 5000
+  http2SessionTimeout: 72000, // 72 seconds
+  exposeHeadRoutes: true
 }
 
-function customRule0 (schemaParamValue, validatedParamValue, validationSchemaObject, currentDataPath, validatedParamObject, validatedParam) {
-  validatedParamObject[validatedParam] = schemaParamValue
-  return true
-}
-
-// We add a keyword that allow us to set default values
-ajv.addKeyword('setDefaultValue', {
-  modifying: true,
-  validate: customRule0,
-  errors: false
-})
-
 const schema = {
   type: 'object',
   additionalProperties: false,
@@ -88,6 +86,7 @@ const schema = {
     requestIdHeader: { type: 'string', default: defaultInitOptions.requestIdHeader },
     requestIdLogLabel: { type: 'string', default: defaultInitOptions.requestIdLogLabel },
     http2SessionTimeout: { type: 'integer', default: defaultInitOptions.http2SessionTimeout },
+    exposeHeadRoutes: { type: 'boolean', default: defaultInitOptions.exposeHeadRoutes },
     // deprecated style of passing the versioning constraint
     versioning: {
       type: 'object',
@@ -115,18 +114,31 @@ const schema = {
   }
 }
 
-const validate = ajv.compile(schema)
-
-const moduleCode = `// This file is autogenerated by ${__filename.replace(__dirname, 'build')}, do not edit
-/* istanbul ignore file */
-// constant needed for customRule0 to work
-const self = {}
-
-${pack(ajv, validate)}
-
-${customRule0.toString()}
-
-module.exports.defaultInitOptions = ${JSON.stringify(defaultInitOptions)}
-`
+const compiler = factory({}, {
+  customOptions: {
+    code: {
+      source: true,
+      lines: true,
+      optimize: 3
+    },
+    removeAdditional: true,
+    useDefaults: true,
+    coerceTypes: true,
+    keywords: [
+      {
+        keyword: 'setDefaultValue',
+        $data: true,
+        // error: false,
+        modifying: true,
+        valid: true,
+        code (keywordCxt) {
+          const { gen, it, schemaValue } = keywordCxt
+          const logicCode = gen.assign(_`${it.parentData}[${it.parentDataProperty}]`, schemaValue)
+          return logicCode
+        }
+      }
+    ]
+  }
+})
 
-fs.writeFileSync(path.join(__dirname, '..', 'lib', 'configValidator.js'), moduleCode)
+compiler({ schema })

package/docs/Guides/Database.md

@@ -0,0 +1,320 @@
+<h1 align="center">Fastify</h1>
+
+## Database
+
+Fastify's ecosystem provides a handful of 
+plugins for connecting to various database engines. 
+This guide covers engines that have Fastify 
+plugins maintained within the Fastify organization.
+
+> If a plugin for your database of choice does not exist 
+> you can still use the database as Fastify is database agnostic. 
+> By following the examples of the database plugins listed in this guide, 
+> a plugin can be written for the missing database engine. 
+
+> If you would like to write your own Fastify plugin 
+> please take a look at the [plugins guide](./Plugins-Guide.md)
+
+### [MySQL](https://github.com/fastify/fastify-mysql)
+
+Install the plugin by running `npm i fastify-mysql --save`.
+
+*Usage:*
+
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-mysql'), {
+  connectionString: 'mysql://root@localhost/mysql'
+})
+
+fastify.get('/user/:id', function(req, reply) {
+  fastify.mysql.query(
+    'SELECT id, username, hash, salt FROM users WHERE id=?', [req.params.id],
+    function onResult (err, result) {
+      reply.send(err || result)
+    }
+  )
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### [Postgres](https://github.com/fastify/fastify-postgres)
+Install the plugin by running `npm i pg fastify-postgres --save`.
+
+*Example*:
+
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-postgres'), {
+  connectionString: 'postgres://postgres@localhost/postgres'
+})
+
+fastify.get('/user/:id', function (req, reply) {
+  fastify.pg.query(
+    'SELECT id, username, hash, salt FROM users WHERE id=$1', [req.params.id],
+    function onResult (err, result) {
+      reply.send(err || result)
+    }
+  )
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### [Redis](https://github.com/fastify/fastify-redis)
+Install the plugin by running `npm i fastify-redis --save`
+
+*Usage:*
+
+```javascript
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-redis'), { host: '127.0.0.1' })
+// or
+fastify.register(require('fastify-redis'), { url: 'redis://127.0.0.1', /* other redis options */ })
+
+fastify.get('/foo', function (req, reply) {
+  const { redis } = fastify
+  redis.get(req.query.key, (err, val) => {
+    reply.send(err || val)
+  })
+})
+
+fastify.post('/foo', function (req, reply) {
+  const { redis } = fastify
+  redis.set(req.body.key, req.body.value, (err) => {
+    reply.send(err || { status: 'ok' })
+  })
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+By default `fastify-redis` doesn't close 
+the client connection when Fastify server shuts down. 
+To opt-in to this behavior, register the client like so:
+
+```javascript
+fastify.register(require('fastify-redis'), {
+  client: redis,
+  closeClient: true
+})
+```
+
+### [Mongo](https://github.com/fastify/fastify-mongodb)
+Install the plugin by running `npm i fastify-mongodb --save`
+
+*Usage:*
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-mongodb'), {
+  // force to close the mongodb connection when app stopped
+  // the default value is false
+  forceClose: true,
+  
+  url: 'mongodb://mongo/mydb'
+})
+
+fastify.get('/user/:id', function (req, reply) {
+  // Or this.mongo.client.db('mydb').collection('users')
+  const users = this.mongo.db.collection('users')
+
+  // if the id is an ObjectId format, you need to create a new ObjectId
+  const id = this.mongo.ObjectId(req.params.id)
+  users.findOne({ id }, (err, user) => {
+    if (err) {
+      reply.send(err)
+      return
+    }
+    reply.send(user)
+  })
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+})
+```
+
+### [LevelDB](https://github.com/fastify/fastify-leveldb)
+Install the plugin by running `https://github.com/fastify/fastify-leveldb`
+
+*Usage:*
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(
+  require('fastify-leveldb'),
+  { name: 'db' }
+)
+
+fastify.get('/foo', async function (req, reply) {
+  const val = await this.level.db.get(req.query.key)
+  return val
+})
+
+fastify.post('/foo', async function (req, reply) {
+  await this.level.db.put(req.body.key, req.body.value)
+  return { status: 'ok' }
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### Writing plugin for a database library
+We could write a plugin for a database 
+library too (e.g. Knex, Prisma, or TypeORM). 
+We will use [Knex](https://knexjs.org/) in our example.
+
+```javascript
+'use strict'
+
+const fp = require('fastify-plugin')
+const knex = require('knex')
+
+function knexPlugin(fastify, options, done) {
+  if(!fastify.knex) {
+    const knex = knex(options)
+    fastify.decorate('knex', knex)
+
+    fastify.addHook('onClose', (fastify, done) => {
+      if (fastify.knex === knex) {
+        fastify.knex.destroy(done)
+      }
+    })
+  }
+
+  done()
+}
+
+export default fp(plugin, { name: 'fastify-knex-example' })
+```
+
+### Writing a plugin for a database engine
+
+In this example, we will create a basic Fastify MySQL plugin from scratch (it is
+a stripped-down example, please use the official plugin in production).
+
+```javascript
+const fp = require('fp')
+const mysql = require('mysql2/promise')
+
+function fastifyMysql(fastify, options, done) {
+  const connection = mysql.createConnection(options)
+
+  if (!fastify.mysql) {
+    fastify.decorate('mysql', connection)
+  }
+
+  fastify.addHook('onClose', (fastify, done) => connection.end().then(done).catch(done))
+
+  done()
+}
+
+export default fp(fastifyMysql, { name: 'fastify-mysql-example' })
+```
+
+### Migrations
+
+Database schema migrations are an integral part of database management and
+development. Migrations provide a repeatable and testable way to modify a
+database's schema and to prevent data loss.
+
+As stated at the beginning of the guide, Fastify is database agnostic and any
+NodeJS database migration tool can be used with it. We will give an example of
+using [Postgrator](https://www.npmjs.com/package/postgrator) which has support
+for Postgres, MySQL and SQL Server. For MongoDB migrations, please check
+[migrate-mongo](https://www.npmjs.com/package/migrate-mongo).
+
+#### [Postgrator](https://www.npmjs.com/package/postgrator)
+
+Postgrator is NodeJS SQL migration tool that uses a directory of SQL scripts to
+alter the database schema. Each file an migrations folder need to follow the
+pattern: ` [version].[action].[optional-description].sql`.
+
+**version:** must be an incrementing number (e.g. `001` or a timestamp).
+
+**action:** should be `do` or `undo`. `do` implements the version, `undo`
+reverts it. Think about it like `up` and `down` in other migration tools.
+
+**optional-description** describes which changes migration makes. Although
+optional, it should be used for all migrations as it makes it easier for
+everyone to know which changes are made in a migration.
+
+In our example we are going to have a single migration that creates a `users`
+table and we are going to use `Postgrator` to run the migration.
+
+> Run `npm install pg postgrator` to install dependencies needed for the
+> example.
+
+```sql
+// 001.do.create-users-table.sql
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY NOT NULL,
+  created_at DATE NOT NULL DEFAULT CURRENT_DATE,
+  firstName TEXT NOT NULL,
+  lastName TEXT NOT NULL
+);
+```
+```javascript
+const pg = require('pg')
+const Postgrator = require('postgrator')
+const path = require('path')
+
+async function migrate() {
+  const client = new pg.Client({
+    host: 'localhost',
+    port: 5432,
+    database: 'example', 
+    user: 'example',
+    password: 'example',
+  });
+
+  try {
+    const postgrator = new Postgrator({
+      migrationPattern: path.join(__dirname, '/migrations/*'),
+      driver: 'pg',
+      database: 'example',
+      schemaTable: 'migrations',
+      currentSchema: 'public', // Postgres and MS SQL Server only
+      execQuery: (query) => client.query(query),
+    });
+
+    const result = await postgrator.migrate()
+
+    if (result.length === 0) {
+      console.log(
+        'No migrations run for schema "public". Already at the latest one.'
+      )
+    }
+
+    console.log('Migration done.')
+
+    process.exitCode = 0
+  } catch(err) {
+    console.error(error)
+    process.exitCode = 1
+  }
+  
+  await client.end()
+}
+
+migrate()
+```

package/docs/Guides/Getting-Started.md

@@ -45,7 +45,7 @@ fastify.get('/', function (request, reply) {
 })
 
 // Run the server!
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -76,7 +76,7 @@ fastify.get('/', async (request, reply) => {
 
 const start = async () => {
   try {
-    await fastify.listen(3000)
+    await fastify.listen({ port: 3000 })
   } catch (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -102,7 +102,7 @@ above, and more!
 > `0.0.0.0` like so:
 >
 > ```js
-> fastify.listen(3000, '0.0.0.0', function (err, address) {
+> fastify.listen({ port: 3000, host: '0.0.0.0' }, function (err, address) {
 >   if (err) {
 >     fastify.log.error(err)
 >     process.exit(1)
@@ -139,7 +139,7 @@ const fastify = Fastify({
 
 fastify.register(firstRoute)
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -156,7 +156,7 @@ const fastify = require('fastify')({
 
 fastify.register(require('./our-first-route'))
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -214,7 +214,7 @@ const fastify = Fastify({
 fastify.register(dbConnector)
 fastify.register(firstRoute)
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -232,7 +232,7 @@ const fastify = require('fastify')({
 fastify.register(require('./our-db-connector'))
 fastify.register(require('./our-first-route'))
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)

package/docs/Guides/Plugins-Guide.md

@@ -401,7 +401,7 @@ const fastify = Fastify()
 
 ///...
 
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)

package/docs/Guides/Serverless.md

@@ -52,7 +52,7 @@ function init() {
 
 if (require.main === module) {
   // called directly i.e. "node app"
-  init().listen(3000, (err) => {
+  init().listen({ port: 3000 }, (err) => {
     if (err) console.error(err);
     console.log('server listening on 3000');
   });
@@ -277,11 +277,11 @@ async function start() {
   const port = process.env.PORT || 3000
 
   // You must listen on all IPV4 addresses in Cloud Run
-  const address = IS_GOOGLE_CLOUD_RUN ? "0.0.0.0" : undefined
+  const host = IS_GOOGLE_CLOUD_RUN ? "0.0.0.0" : undefined
 
   try {
     const server = build()
-    const address = await server.listen(port, address)
+    const address = await server.listen({ port, host })
     console.log(`Listening on ${address}`)
   } catch (err) {
     console.error(err)

package/docs/Guides/Testing.md

@@ -47,7 +47,7 @@ const server = require('./app')({
   }
 })
 
-server.listen(3000, (err, address) => {
+server.listen({ port: 3000 }, (err, address) => {
   if (err) {
     server.log.error(err)
     process.exit(1)
@@ -255,7 +255,7 @@ tap.test('GET `/` route', t => {
 
   t.teardown(() => fastify.close())
 
-  fastify.listen(0, (err) => {
+  fastify.listen({ port: 0 }, (err) => {
     t.error(err)
 
     request({

package/docs/Migration-Guide-V4.md

@@ -0,0 +1,12 @@
+# V4 Migration Guide
+
+This guide is intended to help with migration from Fastify v3 to v4.
+
+Before migrating to v4, please ensure that you have fixed all deprecation warningx from v3.
+All v3 deprecations have been removed and they will no longer work after upgrading.
+
+## Breaking Changes
+
+### Deprecation of `app.use()`
+
+Starting this version of Fastify, we have deprecated the use of `app.use()`. We have decided not to support the use of middlewares. Both [`middie`](https://github.com/fastify/middie) and [`fastify-express`](https://github.com/fastify/fastify-express) will still be there and maintained. Use Fastify's [hooks](./Hooks.md) instead.

package/docs/Reference/ContentTypeParser.md

@@ -21,6 +21,9 @@ 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`.
 
+Note that for `GET` and `HEAD` requests the payload is never parsed. For `OPTIONS` and `DELETE` requests the payload is only parsed if 
+the content type is given in the content-type header. If it is not given, the [catch-all](#catch-all) parser is not executed as with `POST`, `PUT` and `PATCH`, but the payload is simply not parsed.
+
 ### Usage
 ```js
 fastify.addContentTypeParser('application/jsoff', function (request, payload, done) {
@@ -90,6 +93,7 @@ if (!fastify.hasContentTypeParser('application/jsoff')){
 }
 ```
 
+=======
 #### removeContentTypeParser
 
 With `removeContentTypeParser` a single or an array of content types can be

package/docs/Reference/Decorators.md

@@ -265,7 +265,7 @@ server.decorateReply('view', function (template, args) {
   // Another rendering engine
 })
 
-server.listen(3000)
+server.listen({ port: 3000 })
 ```
 
 
@@ -291,7 +291,7 @@ server.register(async function (server, opts) {
   })
 }, { prefix: '/bar' })
 
-server.listen(3000)
+server.listen({ port: 3000 })
 ```
 
 ### Getters and Setters