fastify 4.12.0 → 4.13.0

package/docs/Guides/Detecting-When-Clients-Abort.md

@@ -0,0 +1,170 @@
+<h1 align="center">Fastify</h1>
+
+# Detecting When Clients Abort
+
+## Introduction
+
+Fastify provides request events to trigger at certain points in a request's 
+lifecycle. However, there isn't a built-in mechanism to 
+detect unintentional client disconnection scenarios such as when the client's 
+internet connection is interrupted. This guide covers methods to detect if
+and when a client intentionally aborts a request.
+
+Keep in mind, Fastify's `clientErrorHandler` is not designed to detect when a 
+client aborts a request. This works in the same way as the standard Node HTTP 
+module, which triggers the `clientError` event when there is a bad request or 
+exceedingly large header data. When a client aborts a request, there is no 
+error on the socket and the `clientErrorHandler` will not be triggered.
+
+## Solution
+
+### Overview
+
+The proposed solution is a possible way of detecting when a client 
+intentionally aborts a request, such as when a browser is closed or the HTTP 
+request is aborted from your client application. If there is an error in your 
+application code that results in the server crashing, you may require 
+additional logic to avoid a false abort detection.
+
+The goal here is to detect when a client intentionally aborts a connection 
+so your application logic can proceed accordingly. This can be useful for 
+logging purposes or halting business logic.
+
+### Hands-on
+
+Say we have the following base server set up:
+
+```js
+import Fastify from 'fastify';
+
+const sleep = async (time) => {
+  return await new Promise(resolve => setTimeout(resolve, time || 1000));
+}
+
+const app = Fastify({
+  logger: {
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        translateTime: 'HH:MM:ss Z',
+        ignore: 'pid,hostname',
+      },
+    },
+  },
+})
+
+app.addHook('onRequest', async (request, reply) => {
+  request.raw.on('close', () => {
+    if (request.raw.aborted) {
+      app.log.info('request closed')
+    }
+  })
+})
+
+app.get('/', async (request, reply) => {
+  await sleep(3000)
+  reply.code(200).send({ ok: true })
+})
+
+const start = async () => {
+  try {
+    await app.listen({ port: 3000 })
+  } catch (err) {
+    app.log.error(err)
+    process.exit(1)
+  }
+}
+
+start()
+```
+
+Our code is setting up a Fastify server which includes the following 
+functionality:
+
+- Accepting requests at http://localhost:3000, with a 3 second delayed response 
+of `{ ok: true }`.
+- An onRequest hook that triggers when every request is received.
+- Logic that triggers in the hook when the request is closed.
+- Logging that occurs when the closed request property `aborted` is true.
+
+In the request close event, you should examine the diff between a successful 
+request and one aborted by the client to determine the best property for your 
+use case. You can find details about request properties in the 
+[NodeJS documentation](https://nodejs.org/api/http.html).
+
+You can also perform this logic outside of a hook, directly in a specific route.
+
+```js
+app.get('/', async (request, reply) => {
+  request.raw.on('close', () => {
+    if (request.raw.aborted) {
+      app.log.info('request closed')
+    }
+  })
+  await sleep(3000)
+  reply.code(200).send({ ok: true })
+})
+```
+
+At any point in your business logic, you can check if the request has been 
+aborted and perform alternative actions.
+
+```js
+app.get('/', async (request, reply) => {
+  await sleep(3000)
+  if (request.raw.aborted) {
+    // do something here
+  }
+  await sleep(3000)
+  reply.code(200).send({ ok: true })
+})
+```
+
+A benefit to adding this in your application code is that you can log Fastify 
+details such as the reqId, which may be unavailable in lower-level code that 
+only has access to the raw request information.
+
+### Testing
+
+To test this functionality you can use an app like Postman and cancel your 
+request within 3 seconds. Alternatively, you can use Node to send an HTTP 
+request with logic to abort the request before 3 seconds. Example:
+
+```js
+const controller = new AbortController();
+const signal = controller.signal;
+
+(async () => {
+   try {
+      const response = await fetch('http://localhost:3000', { signal });
+      const body = await response.text();
+      console.log(body);
+   } catch (error) {
+      console.error(error);
+   }
+})();
+
+setTimeout(() => {
+   controller.abort()
+}, 1000);
+```
+
+With either approach, you should see the Fastify log appear at the moment the 
+request is aborted.
+
+## Conclusion
+
+Specifics of the implementation will vary from one problem to another, but the
+main goal of this guide was to show a very specific use case of an issue that
+could be solved within Fastify's ecosystem.
+
+You can listen to the request close event and determine if the request was 
+aborted or if it was successfully delivered. You can implement this solution 
+in an onRequest hook or directly in an individual route.
+
+This approach will not trigger in the event of internet disruption, and such 
+detection would require additional business logic. If you have flawed backend 
+application logic that results in a server crash, then you could trigger a 
+false detection. The `clientErrorHandler`, either by default or with custom 
+logic, is not intended to handle this scenario and will not trigger when the 
+client aborts a request.

package/docs/Guides/Ecosystem.md

@@ -140,6 +140,8 @@ section.
 
 - [`@applicazza/fastify-nextjs`](https://github.com/applicazza/fastify-nextjs)
   Alternate Fastify and Next.js integration.
+- [`@clerk/fastify`](https://github.com/clerkinc/javascript/tree/main/packages/fastify)
+  Add authentication and user management to your Fastify application with Clerk.
 - [`@coobaha/typed-fastify`](https://github.com/Coobaha/typed-fastify) Strongly
   typed routes with a runtime validation using JSON schema generated from types.
 - [`@dnlup/fastify-doc`](https://github.com/dnlup/fastify-doc) A plugin for
@@ -201,6 +203,8 @@ section.
   using Fastify without the need of consuming a port on Electron apps.
 - [`fast-water`](https://github.com/tswayne/fast-water) A Fastify plugin for
   waterline. Decorates Fastify with waterline models.
+- [`fastify-204`](https://github.com/Shiva127/fastify-204) Fastify plugin that
+  return 204 status on empty response.
 - [`fastify-405`](https://github.com/Eomm/fastify-405) Fastify plugin that adds
   405 HTTP status to your routes
 - [`fastify-allow`](https://github.com/mattbishop/fastify-allow) Fastify plugin
@@ -266,6 +270,10 @@ section.
 - [`fastify-cloudevents`](https://github.com/smartiniOnGitHub/fastify-cloudevents)
   Fastify plugin to generate and forward Fastify events in the Cloudevents
   format.
+- [`fastify-cloudinary`](https://github.com/Vanilla-IceCream/fastify-cloudinary)
+  The Cloudinary Fastify SDK allows you to quickly and easily integrate your
+  application with Cloudinary. Effortlessly optimize and transform your cloud's
+  assets.
 - [`fastify-cockroachdb`](https://github.com/alex-ppg/fastify-cockroachdb)
   Fastify plugin to connect to a CockroachDB PostgreSQL instance via the
   Sequelize ORM.
@@ -280,6 +288,9 @@ section.
   functions.
 - [`fastify-decorators`](https://github.com/L2jLiga/fastify-decorators) Fastify
   plugin that provides the set of TypeScript decorators.
+- [`fastify-delay-request`](https://github.com/climba03003/fastify-delay-request)
+  Fastify plugin that allows requests to be delayed whilst a task the response is
+  dependent on is run, such as a resource intensive process.
 - [`fastify-disablecache`](https://github.com/Fdawgs/fastify-disablecache)
   Fastify plugin to disable client-side caching, inspired by
   [nocache](https://github.com/helmetjs/nocache).
@@ -369,6 +380,8 @@ section.
 - [`fastify-ip`](https://github.com/metcoder95/fastify-ip) A plugin
   for Fastify that allows you to infer a request ID by a
   given set of custom Request headers.
+- [`fastify-json-to-xml`](https://github.com/Fdawgs/fastify-json-to-xml) Fastify
+  plugin to serialize JSON responses into XML.
 - [`fastify-jwt-authz`](https://github.com/Ethan-Arrowood/fastify-jwt-authz) JWT
   user scope verifier.
 - [`fastify-jwt-webapp`](https://github.com/charlesread/fastify-jwt-webapp) JWT
@@ -387,7 +400,7 @@ section.
   Fastify plugin to parse request language.
 - [`fastify-lcache`](https://github.com/denbon05/fastify-lcache)
   Lightweight cache plugin
-- [`fastify-list-routes`](https://github.com/chuongtrh/fastify-list-routes) 
+- [`fastify-list-routes`](https://github.com/chuongtrh/fastify-list-routes)
   A simple plugin for Fastify list all available routes.
 - [`fastify-loader`](https://github.com/TheNoim/fastify-loader) Load routes from
   a directory and inject the Fastify instance in each file.
@@ -537,9 +550,11 @@ section.
 - [`fastify-server-session`](https://github.com/jsumners/fastify-server-session)
   A session plugin with support for arbitrary backing caches via
   `fastify-caching`.
+- [`fastify-shared-schema`](https://github.com/Adibla/fastify-shared-schema) Plugin
+  for sharing schemas between different routes.
 - [`fastify-slonik`](https://github.com/Unbuttun/fastify-slonik) Fastify Slonik
   plugin, with this you can use slonik in every part of your server.
-- [`fastify-slow-down`](https://github.com/nearform/fastify-slow-down) A plugin 
+- [`fastify-slow-down`](https://github.com/nearform/fastify-slow-down) A plugin
   to delay the response from the server.
 - [`fastify-socket.io`](https://github.com/alemagio/fastify-socket.io) a
   Socket.io plugin for Fastify.
@@ -590,6 +605,8 @@ section.
   should use.
 - [`fastify-wamp-router`](https://github.com/lependu/fastify-wamp-router) Web
   Application Messaging Protocol router for Fastify.
+- [`fastify-web-response`](https://github.com/erfanium/fastify-web-response)
+  Enables returning web streams objects `Response` and `ReadableStream` in routes.
 - [`fastify-webpack-hmr`](https://github.com/lependu/fastify-webpack-hmr)
   Webpack hot module reloading plugin for Fastify.
 - [`fastify-webpack-hot`](https://github.com/gajus/fastify-webpack-hot) Webpack
@@ -626,7 +643,6 @@ section.
   and lightweight Sequelize plugin for Fastify.
 - [`typeorm-fastify-plugin`](https://github.com/jclemens24/fastify-typeorm) A simple
   and updated Typeorm plugin for use with Fastify.
-
 #### [Community Tools](#community-tools)
 - [`@fastify-userland/workflows`](https://github.com/fastify-userland/workflows)
   Reusable workflows for use in the Fastify plugin

package/docs/Guides/Index.md

@@ -15,6 +15,8 @@ This table of contents is in alphabetical order.
   met in your application. This guide focuses on solving the problem using
   [`Hooks`](../Reference/Hooks.md), [`Decorators`](../Reference/Decorators.md),
   and [`Plugins`](../Reference/Plugins.md).
++ [Detecting When Clients Abort](./Detecting-When-Clients-Abort.md): A 
+  practical guide on detecting if and when a client aborts a request.
 + [Ecosystem](./Ecosystem.md): Lists all core plugins and many known community
   plugins.
 + [Fluent Schema](./Fluent-Schema.md): Shows how writing JSON Schema can be

package/docs/Guides/Migration-Guide-V4.md

@@ -121,7 +121,7 @@ As a result, if you specify an `onRoute` hook in a plugin you should now either:
 
   Into this:
   ```js
-  await fastify.register((instance, opts) => {
+  await fastify.register((instance, opts, done) => {
     instance.addHook('onRoute', (routeOptions) => {
       const { path, method } = routeOptions;
       console.log({ path, method });

package/docs/Reference/Errors.md

@@ -133,7 +133,43 @@ fastify.listen({ port: 3000 }, function (err, address) {
 
 404 Not Found.
 
+#### FST_ERR_OPTIONS_NOT_OBJ
+<a id="FST_ERR_OPTIONS_NOT_OBJ"></a>
+
+Fastify options must be an object.
+
+#### FST_ERR_QSP_NOT_FN
+<a id="FST_ERR_QSP_NOT_FN"></a>
+
+QueryStringParser option should be a function.
+
+#### FST_ERR_SCHEMA_CONTROLLER_BUCKET_OPT_NOT_FN
+<a id="FST_ERR_SCHEMA_CONTROLLER_BUCKET_OPT_NOT_FN"></a>
+
+SchemaController.bucket option should be a function.
+
+#### FST_ERR_SCHEMA_ERROR_FORMATTER_NOT_FN
+<a id="FST_ERR_SCHEMA_ERROR_FORMATTER_NOT_FN"></a>
+
+SchemaErrorFormatter option should be a non async function.
+
+#### FST_ERR_AJV_CUSTOM_OPTIONS_OPT_NOT_OBJ
+<a id="FST_ERR_AJV_CUSTOM_OPTIONS_OPT_NOT_OBJ"></a>
+
+ajv.customOptions option should be an object.
+
+#### FST_ERR_AJV_CUSTOM_OPTIONS_OPT_NOT_ARR
+<a id="FST_ERR_AJV_CUSTOM_OPTIONS_OPT_NOT_ARR"></a>
+
+ajv.plugins option should be an array.
+
+#### FST_ERR_VERSION_CONSTRAINT_NOT_STR
+<a id="FST_ERR_VERSION_CONSTRAINT_NOT_STR"></a>
+
+Version constraint should be a string.
+
 <a name="FST_ERR_CTP_ALREADY_PRESENT"></a>
+
 #### FST_ERR_CTP_ALREADY_PRESENT
 <a id="FST_ERR_CTP_ALREADY_PRESENT"></a>
 
@@ -184,6 +220,16 @@ Request body size did not match `Content-Length`.
 
 Body cannot be empty when content-type is set to `application/json`.
 
+#### FST_ERR_CTP_INSTANCE_ALREADY_STARTED
+<a id="FST_ERR_CTP_INSTANCE_ALREADY_STARTED"></a>
+
+Fastify is already started.
+
+#### FST_ERR_INSTANCE_ALREADY_LISTENING
+<a id="FST_ERR_INSTANCE_ALREADY_LISTENING"></a>
+
+Fastify instance is already listening.
+
 #### FST_ERR_DEC_ALREADY_PRESENT
 <a id="FST_ERR_DEC_ALREADY_PRESENT"></a>
 
@@ -214,10 +260,15 @@ The hook name must be a string.
 
 The hook callback must be a function.
 
+#### FST_ERR_HOOK_NOT_SUPPORTED
+<a id="FST_ERR_HOOK_NOT_SUPPORTED"></a>
+
+The hook is not supported.
+
 #### FST_ERR_MISSING_MIDDLEWARE
 <a id="FST_ERR_MISSING_MIDDLEWARE"></a>
 
-You must register a plugin for handling middlewares, 
+You must register a plugin for handling middlewares,
 visit [`Middleware`](./Middleware.md) for more info.
 
 <a name="FST_ERR_HOOK_TIMEOUT"></a>
@@ -278,7 +329,7 @@ Missing serialization function.
 #### FST_ERR_REQ_INVALID_VALIDATION_INVOCATION
 <a id="FST_ERR_REQ_INVALID_VALIDATION_INVOCATION"></a>
 
-Invalid validation invocation. Missing validation function for 
+Invalid validation invocation. Missing validation function for
 HTTP part nor schema provided.
 
 #### FST_ERR_SCH_MISSING_ID
@@ -306,6 +357,11 @@ The JSON schema provided for validation to a route is not valid.
 
 The JSON schema provided for serialization of a route response is not valid.
 
+#### FST_ERR_SCH_RESPONSE_SCHEMA_NOT_NESTED_2XX
+<a id="FST_ERR_SCH_RESPONSE_SCHEMA_NOT_NESTED_2XX"></a>
+
+Response schemas should be nested under a valid status code (2XX).
+
 #### FST_ERR_HTTP2_INVALID_VERSION
 <a id="FST_ERR_HTTP2_INVALID_VERSION"></a>
 
@@ -319,7 +375,7 @@ Invalid initialization options.
 #### FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE
 <a id="FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE"></a>
 
-Cannot set forceCloseConnections to `idle` as your HTTP server 
+Cannot set forceCloseConnections to `idle` as your HTTP server
 does not support `closeIdleConnections` method.
 
 <a name="FST_ERR_DUPLICATED_ROUTE"></a>
@@ -347,6 +403,46 @@ The `defaultRoute` type should be a function.
 
 URL must be a string.
 
+#### FST_ERR_ROUTE_OPTIONS_NOT_OBJ
+<a id="FST_ERR_ROUTE_OPTIONS_NOT_OBJ"></a>
+
+Options for the route must be an object.
+
+#### FST_ERR_ROUTE_DUPLICATED_HANDLER
+<a id="FST_ERR_ROUTE_DUPLICATED_HANDLER"></a>
+
+Duplicate handler for the route is not allowed.
+
+#### FST_ERR_ROUTE_HANDLER_NOT_FN
+<a id="FST_ERR_ROUTE_HANDLER_NOT_FN"></a>
+
+Handler for the route must be a function.
+
+#### FST_ERR_ROUTE_MISSING_HANDLER
+<a id="FST_ERR_ROUTE_MISSING_HANDLER"></a>
+
+Missing handler function for the route.
+
+#### FST_ERR_ROUTE_METHOD_NOT_SUPPORTED
+<a id="FST_ERR_ROUTE_METHOD_NOT_SUPPORTED"></a>
+
+Method is not supported for the route.
+
+#### FST_ERR_ROUTE_BODY_VALIDATION_SCHEMA_NOT_SUPPORTED
+<a id="FST_ERR_ROUTE_BODY_VALIDATION_SCHEMA_NOT_SUPPORTED"></a>
+
+Body validation schema route is not supported.
+
+#### FST_ERR_ROUTE_BODY_LIMIT_OPTION_NOT_INT
+<a id="FST_ERR_ROUTE_BODY_LIMIT_OPTION_NOT_INT"></a>
+
+BodyLimit option must be an integer.
+
+#### FST_ERR_ROUTE_REWRITE_NOT_STR
+<a id="FST_ERR_ROUTE_REWRITE_NOT_STR"></a>
+
+Rewrite url needs to be of type "string".
+
 #### FST_ERR_REOPENED_CLOSE_SERVER
 <a id="FST_ERR_REOPENED_CLOSE_SERVER"></a>
 
@@ -363,26 +459,37 @@ Fastify is already listening.
 Installed Fastify plugin mismatched expected version.
 
 <a name="FST_ERR_PLUGIN_CALLBACK_NOT_FN"></a>
+
 #### FST_ERR_PLUGIN_CALLBACK_NOT_FN
 
 Callback for a hook is not a function (mapped directly from `avvio`)
 
 <a name="FST_ERR_PLUGIN_NOT_VALID"></a>
+
 #### FST_ERR_PLUGIN_NOT_VALID
 
 Plugin must be a function or a promise.
 
 <a name="FST_ERR_ROOT_PLG_BOOTED"></a>
+
 #### FST_ERR_ROOT_PLG_BOOTED
 
 Root plugin has already booted (mapped directly from `avvio`)
 
 <a name="FST_ERR_PARENT_PLUGIN_BOOTED"></a>
+
 #### FST_ERR_PARENT_PLUGIN_BOOTED
 
 Impossible to load plugin because the parent (mapped directly from `avvio`)
 
 <a name="FST_ERR_PLUGIN_TIMEOUT"></a>
+
 #### FST_ERR_PLUGIN_TIMEOUT
 
 Plugin did not start in time. Default timeout (in millis): `10000`
+
+<a name="FST_ERR_PLUGIN_NOT_PRESENT_IN_INSTANCE"></a>
+
+#### FST_ERR_PLUGIN_NOT_PRESENT_IN_INSTANCE
+
+The decorator is not present in the instance.

package/docs/Reference/Server.md

@@ -9,6 +9,7 @@ options object which is used to customize the resulting instance. This document
 describes the properties available in that options object.
 
 - [Factory](#factory)
+  - [`http`](#http)
   - [`http2`](#http2)
   - [`https`](#https)
   - [`connectionTimeout`](#connectiontimeout)
@@ -91,6 +92,18 @@ describes the properties available in that options object.
     - [errorHandler](#errorhandler)
     - [initialConfig](#initialconfig)
 
+### `http`
+<a id="factory-http"></a>
+
+An object used to configure the server's listening socket. The options
+are the same as the Node.js core [`createServer`
+method](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_http_createserver_options_requestlistener).
+
+This option is ignored if options [`http2`](#factory-http2) or
+[`https`](#factory-https) are set.
+
++ Default: `null`
+
 ### `http2`
 <a id="factory-http2"></a>
 
@@ -494,7 +507,7 @@ request-id](./Logging.md#logging-request-id) section.
 Setting `requestIdHeader` to `false` will always use [genReqId](#genreqid)
 
 + Default: `'request-id'`
-  
+
 ```js
 const fastify = require('fastify')({
   requestIdHeader: 'x-custom-id', // -> use 'X-Custom-Id' header if available
@@ -1440,9 +1453,9 @@ plugins are registered. If you would like to augment the behavior of the default
 arguments `fastify.setNotFoundHandler()` within the context of these registered
 plugins.
 
-> Note: Some config properties from the request object will be 
+> Note: Some config properties from the request object will be
 > undefined inside the custom not found handler. E.g:
-> `request.routerPath`, `routerMethod` and `context.config`. 
+> `request.routerPath`, `routerMethod` and `context.config`.
 > This method design goal is to allow calling the common not found route.
 > To return a per-route customized 404 response, you can do it in
 > the response itself.

package/docs/Reference/Validation-and-Serialization.md

@@ -394,9 +394,11 @@ configuration](https://github.com/fastify/ajv-compiler#ajv-configuration) is:
 
 ```js
 {
-  coerceTypes: true, // change data type of data to match type keyword
+  coerceTypes: 'array', // change data type of data to match type keyword
   useDefaults: true, // replace missing properties and items with the values from corresponding default keyword
   removeAdditional: true, // remove additional properties
+  uriResolver: require('fast-uri'),
+  addUsedSchema: false,
   // Explicitly set allErrors to `false`.
   // When set to `true`, a DoS attack is possible.
   allErrors: false

package/fastify.d.ts

@@ -61,6 +61,13 @@ declare namespace fastify {
     https: https.ServerOptions | null
   }
 
+  export type FastifyHttpOptions<
+    Server extends http.Server,
+    Logger extends FastifyBaseLogger = FastifyBaseLogger
+  > = FastifyServerOptions<Server, Logger> & {
+    http?: http.ServerOptions | null
+  }
+
   type FindMyWayVersion<RawServer extends RawServerBase> = RawServer extends http.Server ? HTTPVersion.V1 : HTTPVersion.V2
 
   export interface ConnectionError extends Error {
@@ -224,7 +231,7 @@ declare function fastify<
   Reply extends RawReplyDefaultExpression<Server> = RawReplyDefaultExpression<Server>,
   Logger extends FastifyBaseLogger = FastifyBaseLogger,
   TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
->(opts?: fastify.FastifyServerOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
+>(opts?: fastify.FastifyHttpOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
 
 // CJS export
 // const fastify = require('fastify')