fastify 3.11.0 → 3.12.0

package/README.md

@@ -19,7 +19,7 @@
 [![NPM downloads](https://img.shields.io/npm/dm/fastify.svg?style=flat)](https://www.npmjs.com/package/fastify)
 [![Security Responsible
 Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md)
-[![Discord](https://img.shields.io/discord/725613461949906985)](https://discord.gg/D3FZYPy)
+[![Discord](https://img.shields.io/discord/725613461949906985)](https://discord.gg/fastify)
 
 </div>
 
@@ -216,10 +216,12 @@ Team members are listed in alphabetical order.
 ### Fastify Core team
 * [__Tommaso Allevi__](https://github.com/allevo), <https://twitter.com/allevitommaso>, <https://www.npmjs.com/~allevo>
 * [__Ethan Arrowood__](https://github.com/Ethan-Arrowood/), <https://twitter.com/arrowoodtech>, <https://www.npmjs.com/~ethan_arrowood>
+* [__Harry Brundage__](https://github.com/airhorns/), <https://twitter.com/harrybrundage>, <https://www.npmjs.com/~airhorns>
 * [__David Mark Clements__](https://github.com/davidmarkclements), <https://twitter.com/davidmarkclem>, <https://www.npmjs.com/~davidmarkclements>
 * [__Matteo Collina__](https://github.com/mcollina), <https://twitter.com/matteocollina>, <https://www.npmjs.com/~matteo.collina>
 * [__Tomas Della Vedova__](https://github.com/delvedor), <https://twitter.com/delvedor>, <https://www.npmjs.com/~delvedor>
 * [__Dustin Deus__](https://github.com/StarpTech), <https://twitter.com/dustindeus>, <https://www.npmjs.com/~starptech>
+* [__Ayoub El Khattabi__](https://github.com/AyoubElk), <https://twitter.com/ayoubelkh>, <https://www.npmjs.com/~ayoubelk>
 * [__Denis Fäcke__](https://github.com/SerayaEryn), <https://twitter.com/serayaeryn>, <https://www.npmjs.com/~serayaeryn>
 * [__Rafael Gonzaga__](https://github.com/rafaelgss), <https://twitter.com/_rafaelgss>, <https://www.npmjs.com/~rafaelgss>
 * [__Vincent Le Goff__](https://github.com/zekth)
@@ -230,7 +232,9 @@ Team members are listed in alphabetical order.
 
 ### Fastify Plugins team
 * [__Matteo Collina__](https://github.com/mcollina), <https://twitter.com/matteocollina>, <https://www.npmjs.com/~matteo.collina>
+* [__Harry Brundage__](https://github.com/airhorns/), <https://twitter.com/harrybrundage>, <https://www.npmjs.com/~airhorns>
 * [__Tomas Della Vedova__](https://github.com/delvedor), <https://twitter.com/delvedor>, <https://www.npmjs.com/~delvedor>
+* [__Ayoub El Khattabi__](https://github.com/AyoubElk), <https://twitter.com/ayoubelkh>, <https://www.npmjs.com/~ayoubelk>
 * [__Vincent Le Goff__](https://github.com/zekth)
 * [__Salman Mitha__](https://github.com/salmanm), <https://www.npmjs.com/~salmanm>
 * [__Maksim Sinik__](https://github.com/fox1t), <https://twitter.com/maksimsinik>, <https://www.npmjs.com/~fox1t>

package/docs/Ecosystem.md

@@ -44,7 +44,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-schedule`](https://github.com/fastify/fastify-schedule) Plugin for scheduling periodic jobs, based on [toad-scheduler](https://github.com/kibertoad/toad-scheduler).
 - [`fastify-sensible`](https://github.com/fastify/fastify-sensible) Defaults for Fastify that everyone can agree on. It adds some useful decorators such as http errors and assertions, but also more request and reply methods.
 - [`fastify-static`](https://github.com/fastify/fastify-static) Plugin for serving static files as fast as possible.
-- [`fastify-swagger`](https://github.com/fastify/fastify-swagger) Swagger documentation generator for Fastify.
+- [`fastify-swagger`](https://github.com/fastify/fastify-swagger) Plugin for serving Swagger/OpenAPI documentation for Fastify, supporting dynamic generation.
 - [`fastify-websocket`](https://github.com/fastify/fastify-websocket) WebSocket support for Fastify. Built upon [websocket-stream](https://github.com/maxogden/websocket-stream).
 - [`fastify-url-data`](https://github.com/fastify/fastify-url-data) Decorate the `Request` object with a method to access raw URL components.
 - [`point-of-view`](https://github.com/fastify/point-of-view) Templates rendering (_ejs, pug, handlebars, marko_) plugin support for Fastify.
@@ -124,6 +124,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-nodemailer`](https://github.com/lependu/fastify-nodemailer) Plugin to share [nodemailer](https://nodemailer.com) transporter across Fastify.
 - [`fastify-normalize-request-reply`](https://github.com/ericrglass/fastify-normalize-request-reply) Plugin to normalize the request and reply to the Express version 4.x request and response, which allows use of middleware, like swagger-stats, that was originally written for Express.
 - [`fastify-now`](https://github.com/yonathan06/fastify-now) Structure your endpoints in a folder and load them dynamically with fastify
+- [`fastify-nuxtjs`](https://github.com/gomah/fastify-nuxtjs) Vue server side rendering support for Fastify with Nuxt.js Framework.
 - [`fastify-oas`](https://gitlab.com/m03geek/fastify-oas) Generates OpenAPI 3.0+ documentation from routes schemas for Fastify.
 - [`fastify-objectionjs`](https://github.com/jarcodallo/fastify-objectionjs) Plugin for the `fastify` framework that provides integration with objectionjs ORM.
 - [`fastify-objectionjs-classes`](https://github.com/kamikazechaser/fastify-objectionjs-classes) Plugin to cherry pick classes from objectionjs ORM.

package/docs/Encapsulation.md

@@ -52,7 +52,9 @@ fastify.register(async function authenticatedContext (childServer) {
     handler (request, response) {
       response.send({
         answer: request.answer,
+        // request.foo will be undefined as it's only defined in publicContext
         foo: request.foo,
+        // request.bar will be undefined as it's only defined in grandchildContext
         bar: request.bar
       })
     }
@@ -69,6 +71,7 @@ fastify.register(async function publicContext (childServer) {
       response.send({
         answer: request.answer,
         foo: request.foo,
+        // request.bar will be undefined as it's only defined in grandchildContext
         bar: request.bar
       })
     }

package/docs/Hooks.md

@@ -456,7 +456,7 @@ Warn: if you declare the function with an [arrow function](https://developer.moz
 <a name="route-hooks"></a>
 
 ## Route level hooks
-You can declare one or more custom [onRequest](#onrequest), [onResponse](#onresponse), [preParsing](#preparsing), [preValidation](#prevalidation), [preHandler](#prehandler) and [preSerialization](#preserialization) hook(s) that will be **unique** for the route.
+You can declare one or more custom lifecycle hooks ([onRequest](#onrequest), [onResponse](#onresponse), [preParsing](#preparsing), [preValidation](#prevalidation), [preHandler](#prehandler), [preSerialization](#preserialization), [onSend](#onsend), [onTimeout](#ontimeout), and [onError](#onerror)) hook(s) that will be **unique** for the route.
 If you do so, those hooks are always executed as the last hook in their category. <br/>
 This can be useful if you need to implement authentication, where the [preParsing](#preparsing) or [preValidation](#prevalidation) hooks are exactly what you need.
 Multiple route-level hooks can also be specified as an array.
@@ -492,6 +492,21 @@ fastify.addHook('preSerialization', (request, reply, payload, done) => {
   done(null, payload)
 })
 
+fastify.addHook('onSend', (request, reply, payload, done) => {
+  // Your code
+  done(null, payload)
+})
+
+fastify.addHook('onTimeout', (request, reply, done) => {
+  // Your code
+  done()
+})
+
+fastify.addHook('onError', (request, reply, error, done) => {
+  // Your code
+  done()
+})
+
 fastify.route({
   method: 'GET',
   url: '/',
@@ -526,6 +541,18 @@ fastify.route({
     // This hook will always be executed after the shared `preSerialization` hooks
     done(null, payload)
   },
+  onSend: (request, reply, payload, done) => {
+    // This hook will always be executed after the shared `onSend` hooks
+    done(null, payload)
+  },
+  onTimeout: (request, reply, done) => {
+    // This hook will always be executed after the shared `onTimeout` hooks
+    done()
+  },
+  onError: (request, reply, error, done) => {
+    // This hook will always be executed after the shared `onError` hooks
+    done()
+  },
   handler: function (request, reply) {
     reply.send({ hello: 'world' })
   }

package/docs/Reply.md

@@ -224,7 +224,7 @@ app.get('/cookie-2', (req, reply) => {
   reply.raw.end()
 })
 ```
-Another example of the misuse of `Reply.raw` is explained in [Reply.md#getheaders](Reply.md#getheaders).
+Another example of the misuse of `Reply.raw` is explained in [Reply](Reply.md#getheaders).
 
 <a name="sent"></a>
 ### .sent

package/docs/Server.md

@@ -133,8 +133,6 @@ logger will point to this instance.
 + `object`: a standard Pino [options object](https://github.com/pinojs/pino/blob/c77d8ec5ce/docs/API.md#constructor).
 This will be passed directly to the Pino constructor. If the following properties
 are not present on the object, they will be added accordingly:
-    * `genReqId`: a synchronous function that will be used to generate identifiers
-    for incoming requests. The default function generates sequential identifiers.
     * `level`: the minimum logging level. If not set, it will be set to `'info'`.
     * `serializers`: a hash of serialization functions. By default, serializers
       are added for `req` (incoming request objects), `res` (outgoing response
@@ -840,6 +838,47 @@ The input `schema` can access all the shared schemas added with [`.addSchema`](#
 #### schemaErrorFormatter
 This property can be used set a function to format errors that happen while the `validationCompiler` fails to validate the schema. See [#error-handling](Validation-and-Serialization.md#schemaerrorformatter).
 
+<a name="schema-controller"></a>
+#### schemaController
+This property can be used to fully manage where the schemas of your application will be stored.
+It can be useful when your schemas are stored in another data structure that is unknown to Fastify.
+See [issue #2446](https://github.com/fastify/fastify/issues/2446) for an example of what
+this property helps to resolve.
+
+```js
+const fastify = Fastify({
+  schemaController: {
+    /**
+     * This factory is called whenever `fastify.register()` is called.
+     * It may receive as input the schemas of the parent context if some schemas has been added.
+     * @param {object} parentSchemas these schemas will be returned by the `getSchemas()` method function of the returned `bucket`.
+     */
+    bucket: function factory (parentSchemas) {
+      return {
+        addSchema (inputSchema) {
+          // This function must store the schema added by the user.
+          // This function is invoked when `fastify.addSchema()` is called.
+        },
+        getSchema (schema$id) {
+          // This function must return the raw schema requested by the `schema$id`.
+          // This function is invoked when `fastify.getSchema(id)` is called.
+          return aSchema
+        },
+        getSchemas () {
+          // This function must return all the schemas referenced by the routes schemas' $ref
+          // It must return a JSON where the property is the schema `$id` and the value is the raw JSON Schema.
+          const allTheSchemaStored = {
+            'schema$id1': schema1,
+            'schema$id2': schema2
+          }
+          return allTheSchemaStored
+        }
+      }
+    }
+  }
+});
+```
+
 <a name="set-not-found-handler"></a>
 #### setNotFoundHandler
 

package/docs/Serverless.md

@@ -279,69 +279,41 @@ Then it should work fine
 
 [Vercel](https://vercel.com) provides zero configuration deployment for
 Node.js applications. In order to use now, it is as simple as
-configuring your `now.json` file like the following:
+configuring your `vercel.json` file like the following:
 
 ```json
 {
-  "version": 2,
-  "builds": [
-    {
-      "src": "api/serverless.js",
-      "use": "@now/node",
-      "config": {
-        "helpers": false
-      }
-    }
-  ],
-  "routes": [
-    { "src": "/.*", "dest": "/api/serverless.js"}
-  ]
+    "rewrites": [
+        { 
+            "source": "/(.*)", 
+            "destination": "/api/serverless.js" 
+        }
+    ]
 }
 ```
 
 Then, write a `api/serverless.js` like so:
 
 ```js
-'use strict'
+"use strict";
 
-const build = require('./index')
+// Read the .env file.
+import * as dotenv from "dotenv";
+dotenv.config();
 
-const app = build()
-
-module.exports = async function (req, res) {
-  await app.ready()
-  app.server.emit('request', req, res)
-}
-```
-
-And a `api/index.js` file:
-
-```js
-'use strict'
+// Require the framework
+import Fastify from "fastify";
 
-const fastify = require('fastify')
+// Instantiate Fastify with some config
+const app = Fastify({
+  logger: true,
+});
 
-function build () {
-  const app = fastify({
-    logger: true
-  })
+// Register your application as a normal plugin.
+app.register(import("../src/app"));
 
-  app.get('/', async (req, res) => {
-    const { name = 'World' } = req.query
-    req.log.info({ name }, 'hello world!')
-    return `Hello ${name}!`
-  })
-
-  return app
+export default async (req, res) => {
+    await app.ready();
+    app.server.emit('request', req, res);
 }
-
-module.exports = build
-```
-
-Note that you'll need to use Node 10 by setting it in `package.json`:
-
-```js
-  "engines": {
-    "node": "10.x"
-  },
 ```

package/docs/TypeScript.md

@@ -37,7 +37,7 @@ This example will get you up and running with Fastify and TypeScript. It results
   ```
 3. Initialize a TypeScript configuration file:
   ```bash
-  npx typescript --init
+  npx tsc --init
   ```
   or use one of the [recommended ones](https://github.com/tsconfig/bases#node-10-tsconfigjson).
 
@@ -82,7 +82,7 @@ The type system heavily relies on generic properties to provide the most accurat
    }
 
    interface IHeaders {
-     'H-Custom': string;
+     'h-Custom': string;
    }
    ```
 3. Using the two interfaces, define a new API route and pass them as generics. The shorthand route methods (i.e. `.get`) accept a generic object `RequestGenericInterface` containing four named properties: `Body`, `Querystring`, `Params`, and `Headers`. The interfaces will be passed down through the route method into the route method handler `request` instance.
@@ -92,7 +92,7 @@ The type system heavily relies on generic properties to provide the most accurat
      Headers: IHeaders
    }>('/auth', async (request, reply) => {
      const { username, password } = request.query
-     const customerHeader = request.headers['H-Custom']
+     const customerHeader = request.headers['h-Custom']
      // do something with request data
 
      return `logged in!`
@@ -115,7 +115,7 @@ The type system heavily relies on generic properties to provide the most accurat
        done(username !== 'admin' ? new Error('Must be admin') : undefined) // only validate `admin` account
      }
    }, async (request, reply) => {
-     const customerHeader = request.headers['H-Custom']
+     const customerHeader = request.headers['h-Custom']
      // do something with request data
      return `logged in!`
    })
@@ -139,10 +139,10 @@ In the last example we used interfaces to define the types for the request query
      "title": "Headers Schema",
      "type": "object",
      "properties": {
-       "H-Custom": { "type": "string" }
+       "h-Custom": { "type": "string" }
      },
      "additionalProperties": false,
-     "required": ["H-Custom"]
+     "required": ["h-Custom"]
    }
    ```
    ```json
@@ -194,7 +194,7 @@ In the last example we used interfaces to define the types for the request query
        done(username !== 'admin' ? new Error('Must be admin') : undefined)
      }
    }, async (request, reply) => {
-     const customerHeader = request.headers['H-Custom']
+     const customerHeader = request.headers['h-Custom']
      // do something with request data
      return `logged in!`
    })
@@ -211,11 +211,11 @@ In the last example we used interfaces to define the types for the request query
      },
      preHandler: (request, reply) => {
        const { username, password } = request.query
-       const customerHeader = request.headers['H-Custom']
+       const customerHeader = request.headers['h-Custom']
      },
      handler: (request, reply) => {
        const { username, password } = request.query
-       const customerHeader = request.headers['H-Custom']
+       const customerHeader = request.headers['h-Custom']
      }
    })
 
@@ -393,6 +393,23 @@ However, there are a couple of suggestions to help improve this experience:
 - Make sure the `no-unused-vars` rule is enabled in [ESLint](https://eslint.org/docs/rules/no-unused-vars) and any imported plugin are actually being loaded.
 - Use a module such as [depcheck](https://www.npmjs.com/package/depcheck) or [npm-check](https://www.npmjs.com/package/npm-check) to verify plugin dependencies are being used somewhere in your project.
 
+## Code Completion In Vanilla JavaScript
+
+Vanilla JavaScript can use the published types to provide code completion (e.g. [Intellisense](https://code.visualstudio.com/docs/editor/intellisense)) by following the [TypeScript JSDoc Reference](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html).
+
+For example:
+
+```js
+/**
+ * setup some routes
+ * @param {import("fastify").FastifyInstance} fastify 
+ * @param {*} opts 
+ */
+module.exports = async function (fastify, opts) {
+    fastify.get('/look', () => 'at me');
+}
+```
+
 ## API Type System Documentation
 
 This section is a detailed account of all the types available to you in Fastify version 3.x

package/fastify.js

@@ -15,9 +15,7 @@ const {
   kLogLevel,
   kLogSerializers,
   kHooks,
-  kSchemas,
-  kValidatorCompiler,
-  kSerializerCompiler,
+  kSchemaController,
   kReplySerializerDefault,
   kContentTypeParser,
   kReply,
@@ -36,8 +34,8 @@ const Request = require('./lib/request')
 const supportedMethods = ['DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT', 'OPTIONS']
 const decorator = require('./lib/decorate')
 const ContentTypeParser = require('./lib/contentTypeParser')
+const SchemaController = require('./lib/schema-controller')
 const { Hooks, hookRunnerApplication } = require('./lib/hooks')
-const { Schemas } = require('./lib/schemas')
 const { createLogger } = require('./lib/logger')
 const pluginUtils = require('./lib/pluginUtils')
 const reqIdGenFactory = require('./lib/reqIdGenFactory')
@@ -86,6 +84,10 @@ function fastify (options) {
     throw new Error(`querystringParser option should be a function, instead got '${typeof options.querystringParser}'`)
   }
 
+  if (options.schemaController && options.schemaController.bucket && typeof options.schemaController.bucket !== 'function') {
+    throw new Error(`schemaController.bucket option should be a function, instead got '${typeof options.schemaController.bucket}'`)
+  }
+
   validateBodyLimitOption(options.bodyLimit)
 
   const requestIdHeader = options.requestIdHeader || defaultInitOptions.requestIdHeader
@@ -155,7 +157,7 @@ function fastify (options) {
   const { server, listen } = createServer(options, httpHandler)
 
   const setupResponseListeners = Reply.setupResponseListeners
-  const schemas = new Schemas()
+  const schemaController = SchemaController.buildSchemaController(null, options.schemaController)
 
   // Public API
   const fastify = {
@@ -172,11 +174,9 @@ function fastify (options) {
     [kLogLevel]: '',
     [kLogSerializers]: null,
     [kHooks]: new Hooks(),
-    [kSchemas]: schemas,
-    [kValidatorCompiler]: null,
+    [kSchemaController]: schemaController,
     [kSchemaErrorFormatter]: null,
     [kErrorHandler]: defaultErrorHandler,
-    [kSerializerCompiler]: null,
     [kReplySerializerDefault]: null,
     [kContentTypeParser]: new ContentTypeParser(
       bodyLimit,
@@ -230,10 +230,11 @@ function fastify (options) {
     addHook: addHook,
     // schemas
     addSchema: addSchema,
-    getSchema: schemas.getSchema.bind(schemas),
-    getSchemas: schemas.getSchemas.bind(schemas),
+    getSchema: schemaController.getSchema.bind(schemaController),
+    getSchemas: schemaController.getSchemas.bind(schemaController),
     setValidatorCompiler: setValidatorCompiler,
     setSerializerCompiler: setSerializerCompiler,
+    setSchemaController: setSchemaController,
     setReplySerializer: setReplySerializer,
     setSchemaErrorFormatter: setSchemaErrorFormatter,
     // custom parsers
@@ -281,10 +282,10 @@ function fastify (options) {
       get () { return this[kRoutePrefix] }
     },
     validatorCompiler: {
-      get () { return this[kValidatorCompiler] }
+      get () { return this[kSchemaController].getValidatorCompiler() }
     },
     serializerCompiler: {
-      get () { return this[kSerializerCompiler] }
+      get () { return this[kSchemaController].getSerializerCompiler() }
     },
     version: {
       get () {
@@ -495,7 +496,7 @@ function fastify (options) {
   // wrapper that we expose to the user for schemas handling
   function addSchema (schema) {
     throwIfAlreadyStarted('Cannot call "addSchema" when fastify instance is already started!')
-    this[kSchemas].add(schema)
+    this[kSchemaController].add(schema)
     this[kChildren].forEach(child => child.addSchema(schema))
     return this
   }
@@ -562,7 +563,7 @@ function fastify (options) {
 
   function setValidatorCompiler (validatorCompiler) {
     throwIfAlreadyStarted('Cannot call "setValidatorCompiler" when fastify instance is already started!')
-    this[kValidatorCompiler] = validatorCompiler
+    this[kSchemaController].setValidatorCompiler(validatorCompiler)
     return this
   }
 
@@ -575,7 +576,17 @@ function fastify (options) {
 
   function setSerializerCompiler (serializerCompiler) {
     throwIfAlreadyStarted('Cannot call "setSerializerCompiler" when fastify instance is already started!')
-    this[kSerializerCompiler] = serializerCompiler
+    this[kSchemaController].setSerializerCompiler(serializerCompiler)
+    return this
+  }
+
+  function setSchemaController (schemaControllerOpts) {
+    throwIfAlreadyStarted('Cannot call "setSchemaController" when fastify instance is already started!')
+    const old = this[kSchemaController]
+    const schemaController = SchemaController.buildSchemaController(old.parent, Object.assign({}, old.opts, schemaControllerOpts))
+    this[kSchemaController] = schemaController
+    this.getSchema = schemaController.getSchema.bind(schemaController)
+    this.getSchemas = schemaController.getSchemas.bind(schemaController)
     return this
   }