fastify 2.7.1 → 2.11.0

package/docs/Routes.md

@@ -1,14 +1,34 @@
 <h1 align="center">Fastify</h1>
 
 ## Routes
-You have two ways to declare a route with Fastify, the shorthand method and the full declaration. Let's start with the second one:
+
+The routes methods will configure the endpoints of your application. 
+You have two ways to declare a route with Fastify, the shorthand method and the full declaration.
+
+- [Full Declaration](#full-declaration)
+- [Route Options](#options)
+- [Shorthand Declaration](#shorthand-declaration)
+- [URL Parameters](#url-building)
+- [Use `async`/`await`](#async-await)
+- [Promise resolution](#promise-resolution)
+- [Route Prefixing](#route-prefixing)
+- Logs
+  - [Custom Log Level](#custom-log-level)
+  - [Custom Log Serializer](#custom-log-serializer)
+- [Route handler configuration](#routes-config)
+- [Route's Versioning](#version)
+
 <a name="full-declaration"></a>
 ### Full declaration
+
 ```js
 fastify.route(options)
 ```
-* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`, `'POST'`, `'PUT'` and `'OPTIONS'`. It could also be an array of methods.
 
+<a name="options"></a>
+### Routes option
+
+* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`, `'POST'`, `'PUT'` and `'OPTIONS'`. It could also be an array of methods.
 * `url`: the path of the url to match this route (alias: `path`).
 * `schema`: an object containing the schemas for the request and response.
 They need to be in
@@ -23,14 +43,18 @@ They need to be in
   * `response`: filter and generate a schema for the response, setting a
     schema allows us to have 10-20% more throughput.
 * `attachValidation`: attach `validationError` to request, if there is a schema validation error, instead of sending the error to the error handler.
-* `onRequest(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) as soon that a request is received, it could also be an array of functions.
-* `preValidation(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called after the shared `preValidation` hooks, useful if you need to perform authentication at route level for example, it could also be an array of functions.
-* `preHandler(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called just before the request handler, it could also be an array of functions.
-* `preSerialization(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called just before the serialization, it could also be an array of functions.
+* `onRequest(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#onrequest) as soon that a request is received, it could also be an array of functions.
+* `preParsing(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#preparsing) called before parsing the request, it could also be an array of functions.
+* `preValidation(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#prevalidation) called after the shared `preValidation` hooks, useful if you need to perform authentication at route level for example, it could also be an array of functions.
+* `preHandler(request, reply, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#prehandler) called just before the request handler, it could also be an array of functions.
+* `preSerialization(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#preserialization) called just before the serialization, it could also be an array of functions.
+* `onSend(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#route-hooks) called right before a response is sent, it could also be an array of functions.
+* `onResponse(request, reply, payload, done)`: a [function](https://github.com/fastify/fastify/blob/master/docs/Hooks.md#onresponse) called when a response has been sent, so you will not be able to send more data to the client. It could also be an array of functions.
 * `handler(request, reply)`: the function that will handle this request.
 * `schemaCompiler(schema)`: the function that build the schema for the validations. See [here](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md#schema-compiler)
 * `bodyLimit`: prevents the default JSON body parser from parsing request bodies larger than this number of bytes. Must be an integer. You may also set this option globally when first creating the Fastify instance with `fastify(options)`. Defaults to `1048576` (1 MiB).
 * `logLevel`: set log level for this route. See below.
+* `logSerializers`: set serializers to log for this route.
 * `config`: object used to store custom configuration.
 * `version`: a [semver](http://semver.org/) compatible string that defined the version of the endpoint. [Example](https://github.com/fastify/fastify/blob/master/docs/Routes.md#version).
 * `prefixTrailingSlash`: string used to determine how to handle passing `/` as a route with a prefix.
@@ -168,7 +192,6 @@ fastify.get('/', options, async function (request, reply) {
   return processed
 })
 ```
-**Warning:** You can't return `undefined`. For more details read [promise-resolution](#promise-resolution).
 
 As you can see we are not calling `reply.send` to send back the data to the user. You just need to return the body and you are done!
 
@@ -180,8 +203,32 @@ fastify.get('/', options, async function (request, reply) {
   reply.send(processed)
 })
 ```
+
+If the route is wrapping a callback-based API that will call
+`reply.send()` outside of the promise chain, it is possible to `await reply`:
+
+```js
+fastify.get('/', options, async function (request, reply) {
+  setImmediate(() => {
+    reply.send({ hello: 'world' })
+  })
+  await reply
+})
+```
+
+Returning reply also works:
+
+```js
+fastify.get('/', options, async function (request, reply) {
+  setImmediate(() => {
+    reply.send({ hello: 'world' })
+  })
+  return reply
+})
+```
+
 **Warning:**
-* If you use `return` and `reply.send` at the same time, the first one that happens takes precedence, the second value will be discarded, a *warn* log will also be emitted because you tried to send a response twice.
+* When using both `return value` and `reply.send(value)` at the same time, the first one that happens takes precedence, the second value will be discarded, and a *warn* log will also be emitted because you tried to send a response twice.
 * You can't return `undefined`. For more details read [promise-resolution](#promise-resolution).
 
 <a name="promise-resolution"></a>
@@ -214,6 +261,7 @@ fastify.register(require('./routes/v2/users'), { prefix: '/v2' })
 
 fastify.listen(3000)
 ```
+
 ```js
 // routes/v1/users.js
 module.exports = function (fastify, opts, done) {
@@ -221,6 +269,7 @@ module.exports = function (fastify, opts, done) {
   done()
 }
 ```
+
 ```js
 // routes/v2/users.js
 module.exports = function (fastify, opts, done) {
@@ -263,6 +312,7 @@ fastify.register(require('./routes/events'), { logLevel: 'debug' })
 
 fastify.listen(3000)
 ```
+
 Or you can directly pass it to a route:
 ```js
 fastify.get('/', { logLevel: 'warn' }, (request, reply) => {
@@ -271,6 +321,64 @@ fastify.get('/', { logLevel: 'warn' }, (request, reply) => {
 ```
 *Remember that the custom log level is applied only to the routes, and not to the global Fastify Logger, accessible with `fastify.log`*
 
+<a name="custom-log-serializer"></a>
+### Custom Log Serializer
+
+In some context, you may need to log a large object but it could be a waste of resources for some routes. In this case, you can define some [`serializer`](https://github.com/pinojs/pino/blob/master/docs/api.md#bindingsserializers-object) and attach them in the right context!
+
+```js
+const fastify = require('fastify')({ logger: true })
+
+fastify.register(require('./routes/user'), { 
+  logSerializers: {
+    user: (value) => `My serializer one - ${value.name}`
+  } 
+})
+fastify.register(require('./routes/events'), {
+  logSerializers: {
+    user: (value) => `My serializer two - ${value.name} ${value.surname}`
+  }
+})
+
+fastify.listen(3000)
+```
+
+You can inherit serializers by context:
+
+```js
+const fastify = Fastify({ 
+  logger: {
+    level: 'info',
+    serializers: {
+      user (req) {
+        return {
+          method: req.method,
+          url: req.url,
+          headers: req.headers,
+          hostname: req.hostname,
+          remoteAddress: req.ip,
+          remotePort: req.connection.remotePort
+        }
+      }
+    }
+  } 
+})
+
+fastify.register(context1, { 
+  logSerializers: {
+    user: value => `My serializer father - ${value}`
+  } 
+})
+
+async function context1 (fastify, opts) {
+  fastify.get('/', (req, reply) => {
+    req.log.info({ user: 'call father serializer', key: 'another key' }) // shows: { user: 'My serializer father - call father  serializer', key: 'another key' }
+    reply.send({})
+  })
+}
+
+fastify.listen(3000)
+```
 
 <a name="routes-config"></a>
 ### Config
@@ -292,10 +400,12 @@ fastify.listen(3000)
 
 <a name="version"></a>
 ### Version
+
 #### Default
 If needed you can provide a version option, which will allow you to declare multiple versions of the same route. The versioning should follow the [semver](http://semver.org/) specification.<br/>
 Fastify will automatically detect the `Accept-Version` header and route the request accordingly (advanced ranges and pre-releases currently are not supported).<br/>
 *Be aware that using this feature will cause a degradation of the overall performances of the router.*
+
 ```js
 fastify.route({
   method: 'GET',
@@ -316,7 +426,9 @@ fastify.inject({
   // { hello: 'world' }
 })
 ```
+
 If you declare multiple versions with the same major or minor, Fastify will always choose the highest compatible with the `Accept-Version` header value.<br/>
 If the request will not have the `Accept-Version` header, a 404 error will be returned.
+
 #### Custom
 It's possible to define a custom versioning logic. This can be done through the [`versioning`](https://github.com/fastify/fastify/blob/master/docs/Server.md#versioning) configuration, when creating a fastify server instance.

package/docs/Server.md

@@ -75,7 +75,7 @@ Defines the maximum payload, in bytes, the server is allowed to accept.
 
 Defines what action the framework must take when parsing a JSON object
 with `__proto__`. This functionality is provided by
-[bourne](https://github.com/hapijs/bourne).
+[secure-json-parse](https://github.com/fastify/secure-json-parse).
 See https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061
 for more details about prototype poisoning attacks.
 
@@ -83,6 +83,19 @@ Possible values are `'error'`, `'remove'` and `'ignore'`.
 
 + Default: `'error'`
 
+<a name="factory-on-constructor-poisoning"></a>
+### `onConstructorPoisoning`
+
+Defines what action the framework must take when parsing a JSON object
+with `constructor`. This functionality is provided by
+[secure-json-parse](https://github.com/fastify/secure-json-parse).
+See https://hueniverse.com/a-tale-of-prototype-poisoning-2610fa170061
+for more details about prototype poisoning attacks.
+
+Possible values are `'error'`, `'remove'` and `'ignore'`.
+
++ Default: `'ignore'`
+
 <a name="factory-logger"></a>
 ### `logger`
 
@@ -104,7 +117,7 @@ are not present on the object, they will be added accordingly:
     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 repsonse
+      are added for `req` (incoming request objects), `res` (outgoing response
       objets), and `err` (standard `Error` objects). When a log method receives
       an object with any of these properties then the respective serializer will
       be used for that property. For example:
@@ -360,6 +373,42 @@ If `false`, the server routes the incoming request as usual.
 
 + Default: `true`
 
+<a name="factory-ajv"></a>
+### `ajv`
+
+Configure the ajv instance used by Fastify without providing a custom one.
+
++ Default:
+
+```js
+{
+  customOptions: {
+    removeAdditional: true,
+    useDefaults: true,
+    coerceTypes: true,
+    allErrors: true,
+    nullable: true
+  },
+  plugins: []
+}
+```
+
+```js
+const fastify = require('fastify')({
+  ajv: {
+    customOptions: {
+      nullable: false // Refer to [ajv options](https://ajv.js.org/#options)
+    },
+    plugins: [
+      require('ajv-merge-patch')
+      [require('ajv-keywords'), 'instanceof'];
+      // Usage: [plugin, pluginOptions] - Plugin with options
+      // Usage: plugin - Plugin without options
+    ]
+  }
+})
+```
+
 ## Instance
 
 ### Server Methods
@@ -547,7 +596,7 @@ A plugin can be a set of routes, a server decorator or whatever, check [here](ht
 
 <a name="use"></a>
 #### use
-Function to add middlewares to Fastify, check [here](https://github.com/fastify/fastify/blob/master/docs/Middlewares.md).
+Function to add middlewares to Fastify, check [here](https://github.com/fastify/fastify/blob/master/docs/Middleware.md).
 
 <a name="addHook"></a>
 #### addHook
@@ -581,6 +630,18 @@ fastify.register(function (instance, opts, done) {
 }, { prefix: '/v1' })
 ```
 
+<a name="pluginName"></a>
+#### pluginName
+Name of the current plugin. There are three ways to define a name (in order).
+
+1. If you use [fastify-plugin](https://github.com/fastify/fastify-plugin) the metadata `name` is used.
+2. If you `module.exports` a plugin the filename is used.
+3. If you use a regular [function declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions#Defining_functions) the function name is used.
+
+*Fallback*: The first two lines of your plugin will represent the plugin name. Newlines are replaced by ` -- `. This will help to indentify the root cause when you deal with many plugins.
+
+Important: If you have to deal with nested plugins the name differs with the usage of the [fastify-plugin](https://github.com/fastify/fastify-plugin) because no new scope is created and therefore we have no place to attach contextual data. In that case the plugin name will represent the boot order of all involved plugins in the format of `plugin-A -> plugin-B`.
+
 <a name="log"></a>
 #### log
 The logger instance, check [here](https://github.com/fastify/fastify/blob/master/docs/Logging.md).
@@ -610,6 +671,11 @@ fastify.setReplySerializer(function (payload, statusCode){
 #### setSchemaCompiler
 Set the schema compiler for all routes [here](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md#schema-compiler).
 
+<a name="set-schema-resolver"></a>
+#### setSchemaResolver
+Set the schema `$ref` resolver for all routes [here](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md#schema-resolver).
+
+
 <a name="schema-compiler"></a>
 #### schemaCompiler
 This property can be used to set the schema compiler, it is a shortcut for the `setSchemaCompiler` method, and get the schema compiler back for all routes.

package/docs/Serverless.md

@@ -6,6 +6,7 @@ Run serverless applications and REST APIs using your existing Fastify applicatio
 
 - [AWS Lambda](#aws-lambda)
 - [Google Cloud Run](#google-cloud-run)
+- [Zeit Now](#zeit-now)
 
 ### Attention Readers:
 > Fastify is not designed to run on serverless environments.
@@ -35,7 +36,7 @@ function init() {
   return app;
 }
 
-if (require.main !== module) {
+if (require.main === module) {
   // called directly i.e. "node app"
   init().listen(3000, (err) => {
     if (err) console.error(err);
@@ -93,9 +94,9 @@ An example deployable with [claudia.js](https://claudiajs.com/tutorials/serverle
 
 ## Google Cloud Run
 
-Unlike AWS Lambda or Google Cloud Functions, Google Cloud Run is a serverless **container** environment. It's primary purpose is to provide an infrastucture-abstracted environment to run arbitrary containers. As a result, Fastify can be deployed to Google Cloud Run with little-to-no code changes from the way you would write your Fastify app normally.
+Unlike AWS Lambda or Google Cloud Functions, Google Cloud Run is a serverless **container** environment. It's primary purpose is to provide an infrastructure-abstracted environment to run arbitrary containers. As a result, Fastify can be deployed to Google Cloud Run with little-to-no code changes from the way you would write your Fastify app normally.
 
-*Follow the steps below to deploy to Google Cloud Run if you are already familiar with gcloud or just follow their [quickstart](https://cloud.google.com/run/docs/quickstarts/build-and-deploy)*
+*Follow the steps below to deploy to Google Cloud Run if you are already familiar with gcloud or just follow their [quickstart](https://cloud.google.com/run/docs/quickstarts/build-and-deploy)*.
 
 ### Adjust Fastfiy server
 
@@ -175,7 +176,7 @@ npm-debug.log
 
 ### Submit build
 
-Next, submit your app to be built into a Docker image by running the following command (replacing `PROJECT-ID` and `APP-NAME` with your GCP project id and an app name:
+Next, submit your app to be built into a Docker image by running the following command (replacing `PROJECT-ID` and `APP-NAME` with your GCP project id and an app name):
 
 ```bash
 gcloud builds submit --tag gcr.io/PROJECT-ID/APP-NAME
@@ -190,3 +191,74 @@ gcloud beta run deploy --image gcr.io/PROJECT-ID/APP-NAME --platform managed
 ```
 
 Your app will be accessible from the URL GCP provides.
+
+## Zeit Now
+
+[now](https://zeit.co/home) 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:
+
+```json
+{
+  "version": 2,
+  "builds": [
+    {
+      "src": "api/serverless.js",
+      "use": "@now/node",
+      "config": {
+        "helpers": false
+      }
+    }
+  ],
+  "routes": [
+    { "src": "/.*", "dest": "/api/serverless.js"}
+  ]
+}
+```
+
+Then, write a `api/serverless.js` like so:
+
+```js
+'use strict'
+
+const build = require('./index')
+
+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'
+
+const fastify = require('fastify')
+
+function build () {
+  const app = fastify({
+    logger: true
+  })
+
+  app.get('/', async (req, res) => {
+    const { name = 'World' } = req.query
+    req.log.info({ name }, 'hello world!')
+    return `Hello ${name}!`
+  })
+
+  return app
+}
+
+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

@@ -7,7 +7,7 @@ Fastify is shipped with a typings file, but you may need to install `@types/node
 ## Types support
 We do care about the TypeScript community, and one of our core team members is currently reworking all types.
 We do our best to have the typings updated with the latest version of the API, but *it can happen* that the typings are not in sync.<br/>
-Luckly this is Open Source and you can contribute to fix them, we will be very happy to accept the fix and release it as soon as possible as a patch release. Checkout the [contributing](#contributing) rules!
+Luckily this is Open Source and you can contribute to fix them, we will be very happy to accept the fix and release it as soon as possible as a patch release. Checkout the [contributing](#contributing) rules!
 
 Plugins may or may not include typings. See [Plugin Types](#plugin-types) for more information.
 
@@ -21,6 +21,7 @@ import { Server, IncomingMessage, ServerResponse } from 'http'
 // Create a http server. We pass the relevant typings for our http version used.
 // By passing types we get correctly typed access to the underlying http objects in routes.
 // If using http2 we'd pass <http2.Http2Server, http2.Http2ServerRequest, http2.Http2ServerResponse>
+// For https pass http2.Http2SecureServer or http.SecureServer instead of Server.
 const server: fastify.FastifyInstance<Server, IncomingMessage, ServerResponse> = fastify({})
 
 const opts: fastify.RouteShorthandOptions = {
@@ -106,7 +107,7 @@ const opts: fastify.RouteShorthandOptions = {
   }
 }
 
-server.get<Query, Params, Body, Headers>('/ping/:bar', opts, (request, reply) => {
+server.get<Query, Params, Headers, Body>('/ping/:bar', opts, (request, reply) => {
   console.log(request.query) // this is of type Query!
   console.log(request.params) // this is of type Params!
   console.log(request.body) // this is of type Body!
@@ -204,7 +205,7 @@ When updating core types you should make a PR to this repository. Ensure you:
 <a id="plugin-types"></a>
 ### Plugin Types
 
-Plugins maintained by and orginized under the fastify organization on GitHub should ship with typings just like fastify itself does.
+Plugins maintained by and organized under the fastify organization on GitHub should ship with typings just like fastify itself does.
 Some plugins already include typings but many do not. We are happy to accept contributions to those plugins without any typings, see [fastify-cors](https://github.com/fastify/fastify-cors) for an example of a plugin that comes with it's own typings.
 
 Typings for third-party-plugins may either be included with the plugin or hosted on DefinitelyTyped. Remember, if you author a plugin to either include typings or publish them on DefinitelyTyped! Information  of how to install typings from DefinitelyTyped can be found [here](https://github.com/DefinitelyTyped/DefinitelyTyped#npm).
@@ -218,26 +219,43 @@ Typings for many plugins that extend the `FastifyRequest`, `FastifyReply` or `Fa
 This code shows the typings for the `fastify-static` plugin.
 
 ```ts
+/// <reference types="node" />
+
 // require fastify typings
-import fastify = require("fastify");
-// require necessary http typings
+import * as fastify from 'fastify';
+
+// require necessary http, http2, https typings
 import { Server, IncomingMessage, ServerResponse } from "http";
+import { Http2SecureServer, Http2Server, Http2ServerRequest, Http2ServerResponse } from "http2";
+import * as https from "https";
+
+type HttpServer = Server | Http2Server | Http2SecureServer | https.Server;
+type HttpRequest = IncomingMessage | Http2ServerRequest;
+type HttpResponse = ServerResponse | Http2ServerResponse;
 
 // extend fastify typings
 declare module "fastify" {
-    interface FastifyReply<HttpResponse> {
-        sendFile(filename: string): FastifyReply<HttpResponse>;
-    }
+  interface FastifyReply<HttpResponse> {
+    sendFile(filename: string): FastifyReply<HttpResponse>;
+  }
 }
 
 // declare plugin type using fastify.Plugin
-declare const fastifyStatic: fastify.Plugin<Server, IncomingMessage, ServerResponse, {
+declare function fastifyStatic(): fastify.Plugin<
+  Server,
+  IncomingMessage,
+  ServerResponse,
+  {
     root: string;
     prefix?: string;
     serve?: boolean;
     decorateReply?: boolean;
     schemaHide?: boolean;
     setHeaders?: (...args: any[]) => void;
+    redirect?: boolean;
+    wildcard?: boolean | string;
+
+    // Passed on to `send`
     acceptRanges?: boolean;
     cacheControl?: boolean;
     dotfiles?: boolean;
@@ -247,7 +265,12 @@ declare const fastifyStatic: fastify.Plugin<Server, IncomingMessage, ServerRespo
     index?: string[];
     lastModified?: boolean;
     maxAge?: string | number;
-}>;
+  }
+>;
+
+declare namespace fastifyStatic {
+  interface FastifyStaticOptions {}
+}
 
 // export plugin type
 export = fastifyStatic;