fastify 3.7.0 → 3.8.0

package/docs/Ecosystem.md

@@ -62,6 +62,8 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-blipp`](https://github.com/PavelPolyakov/fastify-blipp) Prints your routes to the console, so you definitely know which endpoints are available.
 - [`fastify-bookshelf`](https://github.com/butlerx/fastify-bookshelfjs) Fastify plugin to add [bookshelf.js](http://bookshelfjs.org/) orm support.
 - [`fastify-boom`](https://github.com/jeromemacias/fastify-boom) Fastify plugin to add [boom](https://github.com/hapijs/boom) support.
+- [`fastify-casbin`](https://github.com/nearform/fastify-casbin) Casbin support for Fastify.
+- [`fastify-casbin-rest`](https://github.com/nearform/fastify-casbin-rest) Casbin support for Fastify based on a RESTful model.
 - [`fastify-casl`](https://github.com/Inlecom/fastify-casl) Fastify [CASL](https://github.com/stalniy/casl) plugin that supports ACL-like protection of endpoints via either a preSerialization & preHandler hook, sanitizing the inputs and outputs of your application based on user rights.
 - [`fastify-cloudevents`](https://github.com/smartiniOnGitHub/fastify-cloudevents) Fastify plugin to generate and forward Fastify events in the Cloudevents format.
 - [`fastify-cockroachdb`](https://github.com/alex-ppg/fastify-cockroachdb) Fastify plugin to connect to a CockroachDB PostgreSQL instance via the Sequelize ORM.
@@ -82,7 +84,6 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-google-cloud-storage`](https://github.com/carlozamagni/fastify-google-cloud-storage) Fastify plugin that exposes a GCP Cloud Storage client instance.
 - [`fastify-grant`](https://github.com/simov/fastify-grant) Authentication/Authorization plugin for Fastify that supports 200+ OAuth Providers.
 - [`fastify-guard`](https://github.com/hsynlms/fastify-guard) A fastify plugin that protects endpoints by checking authenticated user roles and/or scopes.
-- [`fastify-gql`](https://github.com/mcollina/fastify-gql) A GraphQL server implementation for Fastify with caching and [`graphql-jit`](https://github.com/ruiaraujo/graphql-jit).
 - [`fastify-graceful-shutdown`](https://github.com/hemerajs/fastify-graceful-shutdown) Shutdown Fastify gracefully and asynchronously.
 - [`fastify-healthcheck`](https://github.com/smartiniOnGitHub/fastify-healthcheck) Fastify plugin to serve an health check route and a probe script.
 - [`fastify-hemera`](https://github.com/hemerajs/fastify-hemera) Fastify Hemera plugin, for writing reliable & fault-tolerant microservices with [nats.io](https://nats.io/).
@@ -121,6 +122,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-orientdb`](https://github.com/mahmed8003/fastify-orientdb) Fastify OrientDB connection plugin, with which you can share the OrientDB connection across every part of your server.
 - [`fastify-piscina`](https://github.com/piscinajs/fastify-piscina) A worker thread pool plugin using [Piscina](https://github.com/piscinajs/piscina).
 - [`fastify-peekaboo`](https://github.com/simone-sanfratello/fastify-peekaboo) Fastify plugin for memoize responses by expressive settings.
+- [`fastify-postgraphile`](https://github.com/alemagio/fastify-postgraphile) Plugin to integrate [PostGraphile](https://www.graphile.org/postgraphile/) in a Fastify project.
 - [`fastify-prettier`](https://github.com/hsynlms/fastify-prettier) A fastify plugin that uses [prettier](https://github.com/prettier/prettier) under the hood to beautify outgoing responses and/or other things in the fastify server.
 - [`fastify-qrcode`](https://github.com/chonla/fastify-qrcode) This plugin utilizes [qrcode](https://github.com/soldair/node-qrcode) to generate QR Code.
 - [`fastify-qs`](https://github.com/webdevium/fastify-qs) A plugin for Fastify that adds support for parsing URL query parameters with [qs](https://github.com/ljharb/qs).
@@ -143,6 +145,7 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-sse-v2`](https://github.com/nodefactoryio/fastify-sse-v2) to provide Server-Sent Events using Async Iterators (supports newer versions of Fastify).
 - [`fastify-tls-keygen`](https://gitlab.com/sebdeckers/fastify-tls-keygen) Automatically generate a browser-compatible, trusted, self-signed, localhost-only, TLS certificate.
 - [`fastify-tokenize`](https://github.com/Bowser65/fastify-tokenize) [Tokenize](https://github.com/Bowser65/Tokenize) plugin for Fastify that removes the pain of managing authentication tokens, with built-in integration for `fastify-auth`.
+- [`fastify-totp`](https://github.com/heply/fastify-totp) A plugin to handle TOTP (e.g. for 2FA)
 - [`fastify-twitch-ebs-tools`](https://github.com/lukemnet/fastify-twitch-ebs-tools) Useful functions for Twitch Extension Backend Services (EBS).
 - [`fastify-typeorm-plugin`](https://github.com/inthepocket/fastify-typeorm-plugin) Fastify plugin to work with TypeORM.
 - [`fastify-vhost`](https://github.com/patrickpissurno/fastify-vhost) Proxy subdomain http requests to another server (useful if you want to point multiple subdomains to the same IP address, while running different servers on the same machine).
@@ -153,6 +156,8 @@ Plugins maintained by the fastify team are listed under [Core](#core) while plug
 - [`fastify-webpack-hmr`](https://github.com/lependu/fastify-webpack-hmr) Webpack hot module reloading plugin for Fastify.
 - [`fastify-ws`](https://github.com/gj/fastify-ws) WebSocket integration for Fastify — with support for WebSocket lifecycle hooks instead of a single handler function. Built upon [ws](https://github.com/websockets/ws) and [uws](https://github.com/uNetworking/bindings/tree/master/nodejs).
 - [`fastify-xray`](https://github.com/jeromemacias/fastify-xray) Fastify plugin for AWS XRay recording.
+- [`@gquittet/graceful-server`](https://github.com/gquittet/graceful-server) Tiny (~5k), Fast, KISS and dependency-free Node.JS library to make your Fastify API graceful.
 - [`i18next-http-middleware`](https://github.com/i18next/i18next-http-middleware#fastify-usage) An [i18next](https://www.i18next.com) based i18n (internationalization) middleware to be used with Node.js web frameworks like express or `Fastify` and also for Deno.
 - [`k-fastify-gateway`](https://github.com/jkyberneees/fastify-gateway) API Gateway plugin for `fastify`, a low footprint implementation that uses the `fastify-reply-from` HTTP proxy library.
+- [`mercurius`](https://mercurius.dev/) A fully-featured and performant GraphQL server implementation for Fastify.
 - [`openapi-validator-middleware`](https://github.com/PayU/openapi-validator-middleware#fastify) Swagger and OpenAPI 3.0 spec-based request validation middleware that supports `fastify`.

package/docs/Hooks.md

@@ -50,7 +50,6 @@ Or `async/await`:
 fastify.addHook('onRequest', async (request, reply) => {
   // Some code
   await asyncMethod()
-  return
 })
 ```
 
@@ -97,7 +96,6 @@ Or `async/await`:
 fastify.addHook('preValidation', async (request, reply) => {
   // Some code
   await asyncMethod()
-  return
 })
 ```
 ### preHandler
@@ -112,7 +110,6 @@ Or `async/await`:
 fastify.addHook('preHandler', async (request, reply) => {
   // Some code
   await asyncMethod()
-  return
 })
 ```
 ### preSerialization
@@ -200,7 +197,6 @@ Or `async/await`:
 fastify.addHook('onResponse', async (request, reply) => {
   // Some code
   await asyncMethod()
-  return
 })
 ```
 
@@ -220,7 +216,6 @@ Or `async/await`:
 fastify.addHook('onTimeout', async (request, reply) => {
   // Some code
   await asyncMethod()
-  return
 })
 ```
 `onTimeout` is useful if you need to monitor the request timed out in your service. (if the `connectionTimeout` property is set on the fastify instance). The `onTimeout` hook is executed when a request is timed out and the http socket has been hanged up. Therefore you will not be able to send data to the client.

package/docs/Recommendations.md

@@ -6,6 +6,7 @@ This document contains a set recommendations, or best practices, when using
 Fastify.
 
 * [Use A Reverse Proxy](#reverseproxy)
+* [Kubernetes](#kubernetes)
 
 ## Use A Reverse Proxy
 <a id="reverseproxy"></a>
@@ -161,3 +162,19 @@ backend static-backend
 [scale-horiz]: https://en.wikipedia.org/wiki/Scalability#Horizontal
 [why-use]: https://web.archive.org/web/20190821102906/https://medium.com/intrinsic/why-should-i-use-a-reverse-proxy-if-node-js-is-production-ready-5a079408b2ca
 [haproxy]: https://www.haproxy.org/
+
+## Kubernetes
+<a id="kubernetes"></a>
+
+The `readinessProbe` uses [(by default](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes)) the pod IP as the hostname. Fastify listens on `127.0.0.1` by default. The probe will not be able to reach the application in this case. In order to make it work, the application must listen on `0.0.0.0` or specify a custom hostname in the `readinessProbe.httpGet` spec, as per the following example:
+
+```yaml
+readinessProbe:
+    httpGet:
+        path: /health
+        port: 4000
+    initialDelaySeconds: 30
+    periodSeconds: 30
+    timeoutSeconds: 3
+    successThreshold: 1
+    failureThreshold: 5

package/docs/Reply.md

@@ -11,7 +11,7 @@
   - [.getHeaders()](#getheaders)
   - [.removeHeader(key)](#removeheaderkey)
   - [.hasHeader(key)](#hasheaderkey)
-  - [.redirect(dest)](#redirectdest)
+  - [.redirect([code,] dest)](#redirectcode--dest)
   - [.callNotFound()](#callnotfound)
   - [.getResponseTime()](#getresponsetime)
   - [.type(contentType)](#typecontenttype)
@@ -44,7 +44,7 @@ and properties:
 - `.removeHeader(key)` - Remove the value of a previously set header.
 - `.hasHeader(name)` - Determine if a header has been set.
 - `.type(value)` - Sets the header `Content-Type`.
-- `.redirect([code,] url)` - Redirect to the specified url, the status code is optional (default to `302`).
+- `.redirect([code,] dest)` - Redirect to the specified url, the status code is optional (default to `302`).
 - `.callNotFound()` - Invokes the custom not found handler.
 - `.serialize(payload)` - Serializes the specified payload using the default json serializer or using the custom serializer (if one is set) and returns the serialized payload.
 - `.serializer(function)` - Sets a custom serializer for the payload.

package/docs/Request.md

@@ -13,7 +13,7 @@ Request is a core Fastify object containing the following fields:
 - `log` - the logger instance of the incoming request
 - `ip` - the IP address of the incoming request
 - `ips` - an array of the IP addresses in the `X-Forwarded-For` header of the incoming request (only when the [`trustProxy`](Server.md#factory-trust-proxy) option is enabled)
-- `hostname` - the hostname of the incoming request
+- `hostname` - the hostname of the incoming request (derived from `X-Forwarded-Host` header when the [`trustProxy`](Server.md#factory-trust-proxy) option is enabled)
 - `protocol` - the protocol of the incoming request (`https` or `http`)
 - `method` - the method of the incoming request
 - `url` - the url of the incoming request

package/docs/Routes.md

@@ -302,7 +302,7 @@ See the `prefixTrailingSlash` route option above to change this behaviour.
 <a name="custom-log-level"></a>
 ### Custom Log Level
 It could happen that you need different log levels in your routes, Fastify achieves this in a very straightforward way.<br/>
-You just need to pass the option `logLevel` to the plugin option or the route option with the [value](https://github.com/pinojs/pino/blob/master/docs/API.md#discussion-3) that you need.
+You just need to pass the option `logLevel` to the plugin option or the route option with the [value](https://github.com/pinojs/pino/blob/master/docs/api.md#level-string) that you need.
 
 Be aware that if you set the `logLevel` at plugin level, also the [`setNotFoundHandler`](Server.md#setnotfoundhandler) and [`setErrorHandler`](Server.md#seterrorhandler) will be affected.
 
@@ -431,6 +431,24 @@ fastify.inject({
 })
 ```
 
+> ## ⚠  Security Notice
+> Remember to set a [`Vary`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary) header in your
+> responses with the value you are using for defining the versioning (e.g.: `'Accept-Version'`),
+> to prevent cache poisoning attacks. You can also configure this as part your Proxy/CDN.
+> 
+> ```js
+> const append = require('vary').append
+> fastify.addHook('onSend', async (req, reply) => {
+>   if (req.headers['accept-version']) { // or the custom header you are using
+>     let value = reply.getHeader('Vary') || ''
+>     const header = Array.isArray(value) ? value.join(', ') : String(value)
+>     if ((value = append(header, 'Accept-Version'))) { // or the custom header you are using
+>       reply.header('Vary', value)
+>     }
+>   }
+> })
+> ```
+
 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.
 

package/docs/Server.md

@@ -304,6 +304,8 @@ fastify.get('/', (request, reply) => {
 })
 ```
 
+**Note: if a request contains multiple <code>x-forwarded-host</code> or <code>x-forwarded-proto</code> headers, it is only the last one that is used to derive <code>request.hostname</code> and <code>request.protocol</code>**
+
 <a name="plugin-timeout"></a>
 ### `pluginTimeout`
 

package/docs/Style-Guide.md

@@ -0,0 +1,180 @@
+# 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 don't 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 [CONTRIBUTE.md](/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 NodeJs. It's necessary to keep your readers in mind because they are the one 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. Make references and use words readers can relate with 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/Hooks).
+```
+
+Result:
+>To learn more about hooks, See [Fastify hooks](https://www.fastify.io/docs/latest/Hooks/).
+
+
+
+### Avoid plagiarism
+
+Make sure you avoid copying other people's work. Keep it as original as possible. You can learn from what they've done and also reference where it's 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 also 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.md](/docs/Plugins-Guide.md) page on Github. 
+
+**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 second person "you" as the pronoun
+
+One of the main rules of formal writing such as reference documentation, or API documentation, is to avoid 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.md](/docs/Decorators.md) reference document. 
+
+
+### Avoid using condescending terms
+
+Condescending terms are words that include:
+
+* Just 
+* Easy
+* Simply
+* Basically
+* Obviously
+
+The reader may not find it easy to use the 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 usage present tense because it's easier to read and understand than the past or future tense.
+
+**Example**
+
+ Less like this: There is a need for Nodejs to be installed before you can be able to use Fastify.
+
+ More like this: Install Nodejs to make use of Fastify.
+
+### Grammatical moods 
+
+Grammatical moods is 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, hypothesis 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**: <br>
+>`hook-and-plugins.md`, <br> 
+ `adding-test-plugins.md`, <br>
+ `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 & breif 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 URL's instead of using code strings (``)
+[http://localhost:3000/](http://localhost:3000/)
+
+```
+
+You can include in your documentation as many essential references as possible, but avoid having numerous links when writing for beginners to avoid distractions.