fastify 3.24.0 → 3.25.2

package/docs/{Serverless.md → Guides/Serverless.md}

@@ -1,37 +1,43 @@
 <h1 align="center">Serverless</h1>
 
-Run serverless applications and REST APIs using your existing Fastify application.
-By default, Fastify will not work on your serverless platform of choice, you will need
-to make some small changes to fix this. This document contains a small guide for
-the most popular serverless providers and how to use Fastify with them.
+Run serverless applications and REST APIs using your existing Fastify
+application. By default, Fastify will not work on your serverless platform of
+choice, you will need to make some small changes to fix this. This document
+contains a small guide for the most popular serverless providers and how to use
+Fastify with them.
 
 #### Should you use Fastify in a serverless platform?
 
 That is up to you! Keep in mind that functions as a service should always use
-small and focused functions, but you can also run an entire web application with them.
-It is important to remember that the bigger the application the slower the initial boot will be.
-The best way to run Fastify applications in serverless environments
-is to use platforms like Google Cloud Run, AWS Fargate, and Azure Container Instances,
-where the server can handle multiple requests at the same time and make full use of Fastify's features.
-
-One of the best features of using Fastify in serverless applications is the ease of development.
-In your local environment, you will always run the Fastify application directly without the need
-for any additional tools, while the same code will be executed in your serverless platform of
-choice with an additional snippet of code.
+small and focused functions, but you can also run an entire web application with
+them. It is important to remember that the bigger the application the slower the
+initial boot will be. The best way to run Fastify applications in serverless
+environments is to use platforms like Google Cloud Run, AWS Fargate, and Azure
+Container Instances, where the server can handle multiple requests at the same
+time and make full use of Fastify's features.
+
+One of the best features of using Fastify in serverless applications is the ease
+of development. In your local environment, you will always run the Fastify
+application directly without the need for any additional tools, while the same
+code will be executed in your serverless platform of choice with an additional
+snippet of code.
 
 ### Contents
 
 - [AWS Lambda](#aws-lambda)
+- [Google Cloud Functions](#google-cloud-functions)
 - [Google Cloud Run](#google-cloud-run)
 - [Netlify Lambda](#netlify-lambda)
 - [Vercel](#vercel)
 
 ## AWS Lambda
 
-The sample provided allows you to easily build serverless web applications/services
-and RESTful APIs using Fastify on top of AWS Lambda and Amazon API Gateway.
+The sample provided allows you to easily build serverless web
+applications/services and RESTful APIs using Fastify on top of AWS Lambda and
+Amazon API Gateway.
 
-*Note: Using [aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify) is just one possible way.*
+*Note: Using [aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify)
+is just one possible way.*
 
 ### app.js
 
@@ -56,13 +62,14 @@ if (require.main === module) {
 }
 ```
 
-When executed in your lambda function we do not need to listen to a specific port,
-so we just export the wrapper function `init` in this case.
-The [`lambda.js`](https://www.fastify.io/docs/latest/Serverless/#lambda-js) file will use this export.
+When executed in your lambda function we do not need to listen to a specific
+port, so we just export the wrapper function `init` in this case. The
+[`lambda.js`](#lambdajs) file
+will use this export.
 
-When you execute your Fastify application like always,
-i.e. `node app.js` *(the detection for this could be `require.main === module`)*,
-you can normally listen to your port, so you can still run your Fastify function locally.
+When you execute your Fastify application like always, i.e. `node app.js` *(the
+detection for this could be `require.main === module`)*, you can normally listen
+to your port, so you can still run your Fastify function locally.
 
 ### lambda.js
 
@@ -83,32 +90,177 @@ exports.handler = proxy;
 // exports.handler = async (event, context) => proxy(event, context);
 ```
 
-We just require [aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify)
-(make sure you install the dependency `npm i --save aws-lambda-fastify`) and our
-[`app.js`](https://www.fastify.io/docs/latest/Serverless/#app-js) file and call the
-exported `awsLambdaFastify` function with the `app` as the only parameter.
-The resulting `proxy` function has the correct signature to be used as a lambda `handler` function.
-This way all the incoming events (API Gateway requests) are passed to the `proxy` function of [aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify).
+We just require
+[aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify) (make sure
+you install the dependency `npm i --save aws-lambda-fastify`) and our
+[`app.js`](#appjs) file and call
+the exported `awsLambdaFastify` function with the `app` as the only parameter.
+The resulting `proxy` function has the correct signature to be used as a lambda
+`handler` function. This way all the incoming events (API Gateway requests) are
+passed to the `proxy` function of
+[aws-lambda-fastify](https://github.com/fastify/aws-lambda-fastify).
 
 ### Example
 
-An example deployable with [claudia.js](https://claudiajs.com/tutorials/serverless-express.html) can be found [here](https://github.com/claudiajs/example-projects/tree/master/fastify-app-lambda).
+An example deployable with
+[claudia.js](https://claudiajs.com/tutorials/serverless-express.html) can be
+found
+[here](https://github.com/claudiajs/example-projects/tree/master/fastify-app-lambda).
 
 
 ### Considerations
 
-- API Gateway does not support streams yet, so you are not able to handle [streams](https://www.fastify.io/docs/latest/Reply/#streams).
-- API Gateway has a timeout of 29 seconds, so it is important to provide a reply during this time.
+- API Gateway does not support streams yet, so you are not able to handle
+  [streams](../Reference/Reply.md#streams).
+- API Gateway has a timeout of 29 seconds, so it is important to provide a reply
+  during this time.
+
+## Google Cloud Functions
+
+### Creation of Fastify instance
+```js
+const fastify = require("fastify")({
+  logger: true // you can also define the level passing an object configuration to logger: {level: 'debug'}
+});
+```
+
+### Add Custom `contentTypeParser` to Fastify instance
+
+As explained [in issue
+#946](https://github.com/fastify/fastify/issues/946#issuecomment-766319521),
+since the Google Cloud Functions platform parses the body of the request before
+it arrives into Fastify instance, troubling the body request in case of `POST`
+and `PATCH` methods, you need to add a custom [`Content-Type
+Parser`](../Reference/ContentTypeParser.md) to mitigate this behavior.
+
+```js
+fastify.addContentTypeParser('application/json', {}, (req, body, done) => {
+  done(null, body.body);
+});
+```
+
+### Define your endpoint (examples)
+
+A simple `GET` endpoint:
+```js
+fastify.get('/', async (request, reply) => {
+  reply.send({message: 'Hello World!'})
+})
+```
+
+Or a more complete `POST` endpoint with schema validation:
+```js
+fastify.route({
+  method: 'POST',
+  url: '/hello',
+  schema: {
+    body: {
+      type: 'object',
+      properties: {
+        name: { type: 'string'}
+      },
+      required: ['name']
+    },
+    response: {
+      200: {
+        type: 'object',
+        properties: {
+          message: {type: 'string'}
+        }
+      }
+    },
+  },
+  handler: async (request, reply) => {
+    const { name } = request.body;
+    reply.code(200).send({
+      message: `Hello ${name}!`
+    })
+  }
+})
+```
+
+### Implement and export the function
+
+Final step, implement the function to handle the request and pass it to Fastify
+by emitting `request` event to `fastify.server`:
+
+```js
+const fastifyFunction = async (request, reply) => {
+  await fastify.ready();
+  fastify.server.emit('request', request, reply)
+}
+
+export.fastifyFunction = fastifyFunction;
+```
+
+### Local test
+
+Install [Google Functions Framework for
+Node.js](https://github.com/GoogleCloudPlatform/functions-framework-nodejs).
+
+You can install it globally:
+```bash
+npm i -g @google-cloud/functions-framework
+```
+
+Or as a development library:
+```bash
+npm i --save-dev @google-cloud/functions-framework
+```
+
+Than you can run your function locally with Functions Framework:
+```bash
+npx @google-cloud/functions-framework --target=fastifyFunction
+```
+
+Or add this command to your `package.json` scripts:
+```json
+"scripts": {
+...
+"dev": "npx @google-cloud/functions-framework --target=fastifyFunction"
+...
+}
+```
+and run it with `npm run dev`.
+
+
+### Deploy
+```bash
+gcloud functions deploy fastifyFunction \
+--runtime nodejs14 --trigger-http --region $GOOGLE_REGION --allow-unauthenticated
+```
+
+#### Read logs
+```bash
+gcloud functions logs read
+```
+
+#### Example request to `/hello` endpoint
+```bash
+curl -X POST https://$GOOGLE_REGION-$GOOGLE_PROJECT.cloudfunctions.net/me -H "Content-Type: application/json" -d '{ "name": "Fastify" }'
+{"message":"Hello Fastify!"}
+```
+
+### References
+- [Google Cloud Functions - Node.js Quickstart
+  ](https://cloud.google.com/functions/docs/quickstart-nodejs)
 
 ## Google Cloud Run
 
-Unlike AWS Lambda or Google Cloud Functions, Google Cloud Run is a serverless **container** environment. Its 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.
+Unlike AWS Lambda or Google Cloud Functions, Google Cloud Run is a serverless
+**container** environment. Its 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 Fastify server
 
-In order for Fastify to properly listen for requests within the container, be sure to set the correct port and address:
+In order for Fastify to properly listen for requests within the container, be
+sure to set the correct port and address:
 
 ```js
 function build() {
@@ -146,7 +298,9 @@ if (require.main === module) {
 
 ### Add a Dockerfile
 
-You can add any valid `Dockerfile` that packages and runs a Node app. A basic `Dockerfile` can be found in the official [gcloud docs](https://github.com/knative/docs/blob/2d654d1fd6311750cc57187a86253c52f273d924/docs/serving/samples/hello-world/helloworld-nodejs/Dockerfile).
+You can add any valid `Dockerfile` that packages and runs a Node app. A basic
+`Dockerfile` can be found in the official [gcloud
+docs](https://github.com/knative/docs/blob/2d654d1fd6311750cc57187a86253c52f273d924/docs/serving/samples/hello-world/helloworld-nodejs/Dockerfile).
 
 ```Dockerfile
 # Use the official Node.js 10 image.
@@ -173,7 +327,8 @@ CMD [ "npm", "start" ]
 
 ### Add a .dockerignore
 
-To keep build artifacts out of your container (which keeps it small and improves build times) add a `.dockerignore` file like the one below:
+To keep build artifacts out of your container (which keeps it small and improves
+build times) add a `.dockerignore` file like the one below:
 
 ```.dockerignore
 Dockerfile
@@ -184,7 +339,9 @@ 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
@@ -205,7 +362,8 @@ Your app will be accessible from the URL GCP provides.
 
 First, please perform all preparation steps related to **AWS Lambda**.
 
-Create a folder called `functions`,  then create `server.js` (and your endpoint path will be `server.js`) inside the `functions` folder.
+Create a folder called `functions`,  then create `server.js` (and your endpoint
+path will be `server.js`) inside the `functions` folder.
 
 ### functions/server.js
 
@@ -284,9 +442,9 @@ Then it should work fine
 
 ## Vercel
 
-[Vercel](https://vercel.com) provides zero-configuration deployment for
-Node.js applications. In order to use it now, it is as simple as
-configuring your `vercel.json` file like the following:
+[Vercel](https://vercel.com) provides zero-configuration deployment for Node.js
+applications. In order to use it now, it is as simple as configuring your
+`vercel.json` file like the following:
 
 ```json
 {

package/docs/Guides/Style-Guide.md

@@ -0,0 +1,246 @@
+# Fastify Style Guide
+
+## Welcome
+
+Welcome to *Fastify Style Guide*. This guide is here to provide you with a
+conventional writing style for users writing developer documentation on our Open
+Source framework. Each topic is precise and well explained to help you write
+documentation users can easily understand and implement.
+
+## Who is this guide for?
+
+This guide is for anyone who loves to build with Fastify or wants to contribute
+to our documentation. You do not need to be an expert in writing technical
+documentation. This guide is here to help you.
+
+Visit the [contribute](https://www.fastify.io/contribute) page on our website or
+read the
+[CONTRIBUTING.md](https://github.com/fastify/fastify/blob/main/CONTRIBUTING.md)
+file on GitHub to join our Open Source folks.
+
+## Before you write
+
+You need to know the following:
+
+* JavaScript
+* Node.js
+* Git
+* GitHub
+* Markdown
+* HTTP
+* NPM
+
+### Consider your Audience
+
+Before you start writing, think about your audience. In this case, your audience
+should already know HTTP, JavaScript, NPM, and Node.js. It is necessary to keep
+your readers in mind because they are the ones consuming your content. You want
+to give as much useful information as possible. Consider the vital things they
+need to know and how they can understand them. Use words and references that
+readers can relate to easily. Ask for feedback from the community, it can help
+you write better documentation that focuses on the user and what you want to
+achieve.
+
+### Get straight to the point
+
+Give your readers a clear and precise action to take. Start with what is most
+important. This way, you can help them find what they need faster. Mostly,
+readers tend to read the first content on a page, and many will not scroll
+further.
+
+**Example**
+
+Less like this: Colons are very important to register a parametric path. It lets
+the framework know there is a new parameter created. You can place the colon
+before the parameter name so the parametric path can be created.
+
+More Like this: To register a parametric path, put a colon before the parameter
+name. Using a colon lets the framework know it is a parametric path and not a
+static path.
+
+### Avoid adding video or image content
+
+
+Do not add videos or screenshots in the documentation. It is easier to keep
+under version control. Videos and images will eventually end up becoming
+outdated as new updates keep developing. Instead, make a referral link or a
+YouTube video. You can add links by using `[Title](www.websitename.com)` in the
+markdown.
+
+**Example**
+
+```
+To learn more about hooks, see [Fastify hooks](https://www.fastify.io/docs/latest/Reference/Hooks/).
+```
+
+Result:
+>To learn more about hooks, see [Fastify
+>hooks](https://www.fastify.io/docs/latest/Reference/Hooks/).
+
+
+
+### Avoid plagiarism
+
+Make sure you avoid copying other people's work. Keep it as original as
+possible. You can learn from what they have done and reference where it is from
+if you used a particular quote from their work.
+
+
+## Word Choice
+
+There are a few things you need to use and avoid when writing your documentation
+to improve readability for readers and make documentation neat, direct, and
+clean.
+
+
+### When to use the second person "you" as the pronoun
+
+When writing articles or guides, your content should communicate directly to
+readers in the second person ("you") addressed form. It is easier to give them
+direct instruction on what to do on a particular topic. To see an example, visit
+the [Plugins Guide](./Plugins-Guide.md).
+
+**Example**
+
+Less like this: we can use the following plugins.
+
+More like this: You can use the following plugins.
+
+> According to [Wikipedia](#), ***You*** is usually a second person pronoun.
+> Also, used to refer to an indeterminate person, as a more common alternative
+> to a very formal indefinite pronoun.
+
+## When to avoid the second person "you" as the pronoun
+
+One of the main rules of formal writing such as reference documentation, or API
+documentation, is to avoid the second person ("you") or directly addressing the
+reader.
+
+**Example**
+
+Less like this: You can use the following recommendation as an example.
+
+More like this: As an example, the following recommendations should be
+referenced.
+
+To view a live example, refer to the [Decorators](../Reference/Decorators.md)
+reference document.
+
+
+### Avoid using contractions
+
+Contractions are the shortened version of written and spoken forms of a word,
+i.e. using "don't" instead of "do not". Avoid contractions to provide a more
+formal tone.
+
+### Avoid using condescending terms
+
+Condescending terms are words that include:
+
+* Just
+* Easy
+* Simply
+* Basically
+* Obviously
+
+The reader may not find it easy to use Fastify's framework and plugins; avoid
+words that make it sound simple, easy, offensive, or insensitive. Not everyone
+who reads the documentation has the same level of understanding.
+
+
+### Starting with a verb
+
+Mostly start your description with a verb, which makes it simple and precise for
+the reader to follow. Prefer using present tense because it is easier to read
+and understand than the past or future tense.
+
+**Example**
+
+ Less like this: There is a need for Node.js to be installed before you can be
+ able to use Fastify.
+
+ More like this: Install Node.js to make use of Fastify.
+
+### Grammatical moods
+
+Grammatical moods are a great way to express your writing. Avoid sounding too
+bossy while making a direct statement. Know when to switch between indicative,
+imperative, and subjunctive moods.
+
+
+**Indicative** - Use when making a factual statement or question.
+
+Example: Since there is no testing framework available, "Fastify recommends ways
+to write tests".
+
+**Imperative** - Use when giving instructions, actions, commands, or when you
+write your headings.
+
+Example: Install dependencies before starting development.
+
+
+**Subjunctive** -  Use when making suggestions, hypotheses, or non-factual
+statements.
+
+Example: Reading the documentation on our website is recommended to get
+comprehensive knowledge of the framework.
+
+### Use **active** voice instead of **passive**
+
+Using active voice is a more compact and direct way of conveying your
+documentation.
+
+**Example**
+
+
+Passive: The node dependencies and packages are installed by npm.
+
+Active:  npm installs packages and node dependencies.
+
+## Writing Style
+
+### Documentation titles
+
+When creating a new guide, API, or reference in the `/docs/` directory, use
+short titles that best describe the topic of your documentation. Name your files
+in kebab-cases and avoid Raw or camelCase. To learn more about kebab-case you
+can visit this medium article on [Case
+Styles](https://medium.com/better-programming/string-case-styles-camel-pascal-snake-and-kebab-case-981407998841).
+
+**Examples**:
+
+>`hook-and-plugins.md`,
+
+ `adding-test-plugins.md`,
+
+ `removing-requests.md`.
+
+### Hyperlinks
+
+Hyperlinks should have a clear title of what it references. Here is how your
+hyperlink should look:
+
+```MD
+<!-- More like this -->
+
+// Add clear & brief description
+[Fastify Plugins] (https://www.fastify.io/docs/latest/Plugins/)
+
+<!--Less like this -->
+
+// incomplete description
+[Fastify] (https://www.fastify.io/docs/latest/Plugins/)
+
+// Adding title in link brackets
+[](https://www.fastify.io/docs/latest/Plugins/ "fastify plugin")
+
+// Empty title
+[](https://www.fastify.io/docs/latest/Plugins/)
+
+// Adding links localhost URLs instead of using code strings (``)
+[http://localhost:3000/](http://localhost:3000/)
+
+```
+
+Include in your documentation as many essential references as possible, but
+avoid having numerous links when writing for beginners to avoid distractions.

package/docs/{Testing.md → Guides/Testing.md}

@@ -2,9 +2,13 @@
 
 ## Testing
 
-Testing is one of the most important parts of developing an application. Fastify is very flexible when it comes to testing and is compatible with most testing frameworks (such as [Tap](https://www.npmjs.com/package/tap), which is used in the examples below).
+Testing is one of the most important parts of developing an application. Fastify
+is very flexible when it comes to testing and is compatible with most testing
+frameworks (such as [Tap](https://www.npmjs.com/package/tap), which is used in
+the examples below).
 
-Let's `cd` into a fresh directory called 'testing-example' and type `npm init -y` in our terminal.
+Let's `cd` into a fresh directory called 'testing-example' and type `npm init
+-y` in our terminal.
 
 Run `npm install fastify && npm install tap pino-pretty --save-dev`
 
@@ -45,7 +49,7 @@ const server = require('./app')({
 
 server.listen(3000, (err, address) => {
   if (err) {
-    console.log(err)
+    server.log.error(err)
     process.exit(1)
   }
 })
@@ -53,9 +57,11 @@ server.listen(3000, (err, address) => {
 
 ### Benefits of using fastify.inject()
 
-Fastify comes with built-in support for fake HTTP injection thanks to [`light-my-request`](https://github.com/fastify/light-my-request).
+Fastify comes with built-in support for fake HTTP injection thanks to
+[`light-my-request`](https://github.com/fastify/light-my-request).
 
-Before introducing any tests, we will use the `.inject` method to make a fake request to our route:
+Before introducing any tests, we will use the `.inject` method to make a fake
+request to our route:
 
 **app.test.js**:
 
@@ -78,9 +84,12 @@ const test = async () => {
 test()
 ```
 
-First, our code will run inside an asynchronous function, giving us access to async/await.
+First, our code will run inside an asynchronous function, giving us access to
+async/await.
 
-`.inject` ensures all registered plugins have booted up and our application is ready to test. Finally, we pass the request method we want to use and a route. Using await we can store the response without a callback.
+`.inject` ensures all registered plugins have booted up and our application is
+ready to test. Finally, we pass the request method we want to use and a route.
+Using await we can store the response without a callback.
 
 
 
@@ -225,13 +234,15 @@ tap.test('GET `/` route', t => {
 ```
 
 ### Testing with a running server
-Fastify can also be tested after starting the server with `fastify.listen()` or after initializing routes and plugins with `fastify.ready()`.
+Fastify can also be tested after starting the server with `fastify.listen()` or
+after initializing routes and plugins with `fastify.ready()`.
 
 #### Example:
 
 Uses **app.js** from the previous example.
 
-**test-listen.js** (testing with [`Request`](https://www.npmjs.com/package/request))
+**test-listen.js** (testing with
+[`Request`](https://www.npmjs.com/package/request))
 ```js
 const tap = require('tap')
 const request = require('request')
@@ -260,7 +271,8 @@ tap.test('GET `/` route', t => {
 })
 ```
 
-**test-ready.js** (testing with [`SuperTest`](https://www.npmjs.com/package/supertest))
+**test-ready.js** (testing with
+[`SuperTest`](https://www.npmjs.com/package/supertest))
 ```js
 const tap = require('tap')
 const supertest = require('supertest')
@@ -293,6 +305,8 @@ test('should ...', {only: true}, t => ...)
 - `-O` specifies to run tests with the `only` option enabled
 - `-T` specifies not to timeout (while you're debugging)
 - `--node-arg=--inspect-brk` will launch the node debugger
-3. In VS Code, create and launch a `Node.js: Attach` debug configuration. No modification should be necessary.
+3. In VS Code, create and launch a `Node.js: Attach` debug configuration. No
+   modification should be necessary.
 
-Now you should be able to step through your test file (and the rest of `Fastify`) in your code editor.
+Now you should be able to step through your test file (and the rest of
+`Fastify`) in your code editor.