fastify 5.7.4 → 5.8.1

package/docs/Reference/Hooks.md

@@ -34,7 +34,8 @@ are Request/Reply hooks and application hooks:
 - [Using Hooks to Inject Custom Properties](#using-hooks-to-inject-custom-properties)
 - [Diagnostics Channel Hooks](#diagnostics-channel-hooks)
 
-> ℹ️ Note: The `done` callback is not available when using `async`/`await` or
+> ℹ️ Note:
+> The `done` callback is not available when using `async`/`await` or
 > returning a `Promise`. If you do invoke a `done` callback in this situation
 > unexpected behavior may occur, e.g. duplicate invocation of handlers.
 
@@ -68,7 +69,8 @@ fastify.addHook('onRequest', async (request, reply) => {
 })
 ```
 
-> ℹ️ Note: In the [onRequest](#onrequest) hook, `request.body` will always be
+> ℹ️ Note:
+> In the [onRequest](#onrequest) hook, `request.body` will always be
 > `undefined`, because the body parsing happens before the
 > [preValidation](#prevalidation) hook.
 
@@ -98,16 +100,19 @@ fastify.addHook('preParsing', async (request, reply, payload) => {
 })
 ```
 
-> ℹ️ Note: In the [preParsing](#preparsing) hook, `request.body` will always be
+> ℹ️ Note:
+> In the [preParsing](#preparsing) hook, `request.body` will always be
 > `undefined`, because the body parsing happens before the
 > [preValidation](#prevalidation) hook.
 
-> ℹ️ Note: You should also add a `receivedEncodedLength` property to the
+> ℹ️ Note:
+> You should also add a `receivedEncodedLength` property to the
 > returned stream. This property is used to correctly match the request payload
 > with the `Content-Length` header value. Ideally, this property should be updated
 > on each received chunk.
 
-> ℹ️ Note: The size of the returned stream is checked to not exceed the limit
+> ℹ️ Note:
+> The size of the returned stream is checked to not exceed the limit
 > set in [`bodyLimit`](./Server.md#bodylimit) option.
 
 ### preValidation
@@ -166,7 +171,8 @@ fastify.addHook('preSerialization', async (request, reply, payload) => {
 })
 ```
 
-> ℹ️ Note: The hook is NOT called if the payload is a `string`, a `Buffer`, a
+> ℹ️ Note:
+> The hook is NOT called if the payload is a `string`, a `Buffer`, a
 > `stream`, or `null`.
 
 ### onError
@@ -192,7 +198,8 @@ an exception.
 This hook will be executed before
 the [Custom Error Handler set by `setErrorHandler`](./Server.md#seterrorhandler).
 
-> ℹ️ Note: Unlike the other hooks, passing an error to the `done` function is not
+> ℹ️ Note:
+> Unlike the other hooks, passing an error to the `done` function is not
 > supported.
 
 ### onSend
@@ -229,7 +236,8 @@ fastify.addHook('onSend', (request, reply, payload, done) => {
 > to `0`, whereas the `Content-Length` header will not be set if the payload is
 > `null`.
 
-> ℹ️ Note: If you change the payload, you may only change it to a `string`, a
+> ℹ️ Note:
+> If you change the payload, you may only change it to a `string`, a
 > `Buffer`, a `stream`, a `ReadableStream`, a `Response`, or `null`.
 
 
@@ -252,7 +260,8 @@ The `onResponse` hook is executed when a response has been sent, so you will not
 be able to send more data to the client. It can however be useful for sending
 data to external services, for example, to gather statistics.
 
-> ℹ️ Note: Setting `disableRequestLogging` to `true` will disable any error log
+> ℹ️ Note:
+> Setting `disableRequestLogging` to `true` will disable any error log
 > inside the `onResponse` hook. In this case use `try - catch` to log errors.
 
 ### onTimeout
@@ -275,6 +284,12 @@ 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 hung up. Therefore, you will not be able to send data to the client.
 
+> ℹ️ Note:
+> The `onTimeout` hook is triggered by socket-level timeouts set via
+> `connectionTimeout`. For application-level per-route timeouts, see the
+> [`handlerTimeout`](./Server.md#factory-handler-timeout) option which uses
+> `request.signal` for cooperative cancellation.
+
 ### onRequestAbort
 
 ```js
@@ -294,7 +309,8 @@ The `onRequestAbort` hook is executed when a client closes the connection before
 the entire request has been processed. Therefore, you will not be able to send
 data to the client.
 
-> ℹ️ Note: Client abort detection is not completely reliable.
+> ℹ️ Note:
+> Client abort detection is not completely reliable.
 > See: [`Detecting-When-Clients-Abort.md`](../Guides/Detecting-When-Clients-Abort.md)
 
 ### Manage Errors from a hook
@@ -448,16 +464,19 @@ fastify.addHook('onListen', async function () {
 })
 ```
 
-> ℹ️ Note: This hook will not run when the server is started using
-> fastify.inject()` or `fastify.ready()`.
+> ℹ️ Note:
+> This hook will not run when the server is started using
+> `fastify.inject()` or `fastify.ready()`.
 
 ### onClose
 <a id="on-close"></a>
 
-Triggered when `fastify.close()` is invoked to stop the server, after all in-flight
-HTTP requests have been completed.
-It is useful when [plugins](./Plugins.md) need a "shutdown" event, for example,
-to close an open connection to a database.
+Triggered when `fastify.close()` is invoked to stop the server. By the time
+`onClose` hooks execute, the HTTP server has already stopped listening, all
+in-flight HTTP requests have been completed, and connections have been drained.
+This makes `onClose` the safe place for [plugins](./Plugins.md) to release
+resources such as database connection pools, as no new requests will
+arrive.
 
 The hook function takes the Fastify instance as a first argument,
 and a `done` callback for synchronous hook functions.
@@ -475,13 +494,41 @@ fastify.addHook('onClose', async (instance) => {
 })
 ```
 
+#### Execution order
+
+When multiple `onClose` hooks are registered across plugins, child-plugin hooks
+execute before parent-plugin hooks. This means a database plugin's `onClose`
+hook will run before the root-level `onClose` hooks:
+
+```js
+fastify.register(function dbPlugin (instance, opts, done) {
+  instance.addHook('onClose', async (instance) => {
+    // Runs first — close the database pool
+    await instance.db.close()
+  })
+  done()
+})
+
+fastify.addHook('onClose', async (instance) => {
+  // Runs second — after child plugins have cleaned up
+})
+```
+
+See [`close`](./Server.md#close) for the full shutdown lifecycle.
+
 ### preClose
 <a id="pre-close"></a>
 
-Triggered when `fastify.close()` is invoked to stop the server, before all in-flight
-HTTP requests have been completed.
-It is useful when [plugins](./Plugins.md) have set up some state attached
-to the HTTP server that would prevent the server to close.
+Triggered when `fastify.close()` is invoked to stop the server. At this
+point the server is already rejecting new requests with `503` (when
+[`return503OnClosing`](./Server.md#factory-return-503-on-closing) is `true`),
+but the HTTP server has not yet stopped listening and in-flight requests are
+still being processed.
+
+It is useful when [plugins](./Plugins.md) have set up state attached to the HTTP
+server that would prevent the server from closing, such as open WebSocket
+connections or Server-Sent Events streams that must be explicitly terminated for
+`server.close()` to complete.
 _It is unlikely you will need to use this hook_,
 use the [`onClose`](#onclose) for the most common case.
 
@@ -499,6 +546,18 @@ fastify.addHook('preClose', async () => {
 })
 ```
 
+For example, closing WebSocket connections during shutdown:
+
+```js
+fastify.addHook('preClose', async () => {
+  // Close all WebSocket connections so that server.close() can complete.
+  // Without this, open connections would keep the server alive.
+  for (const ws of activeWebSockets) {
+    ws.close(1001, 'Server shutting down')
+  }
+})
+```
+
 ### onRoute
 <a id="on-route"></a>
 
@@ -572,7 +631,8 @@ This hook can be useful if you are developing a plugin that needs to know when a
 plugin context is formed, and you want to operate in that specific context, thus
 this hook is encapsulated.
 
-> ℹ️ Note: This hook will not be called if a plugin is wrapped inside
+> ℹ️ Note:
+> This hook will not be called if a plugin is wrapped inside
 > [`fastify-plugin`](https://github.com/fastify/fastify-plugin).
 ```js
 fastify.decorate('data', [])
@@ -770,7 +830,8 @@ fastify.route({
 })
 ```
 
-> ℹ️ Note: Both options also accept an array of functions.
+> ℹ️ Note:
+> Both options also accept an array of functions.
 
 ## Using Hooks to Inject Custom Properties
 <a id="using-hooks-to-inject-custom-properties"></a>
@@ -857,7 +918,8 @@ channel.subscribe(function ({ fastify }) {
 })
 ```
 
-> ℹ️ Note: The TracingChannel class API is currently experimental and may undergo
+> ℹ️ Note:
+> The TracingChannel class API is currently experimental and may undergo
 > breaking changes even in semver-patch releases of Node.js.
 
 Five other events are published on a per-request basis following the

package/docs/Reference/LTS.md

@@ -38,7 +38,7 @@ A "month" is defined as 30 consecutive days.
 > occasions where we need to release breaking changes as a _minor_ version
 > release. Such changes will _always_ be noted in the [release
 > notes](https://github.com/fastify/fastify/releases).
-> 
+>
 > To avoid automatically receiving breaking security updates it is possible to
 > use the tilde (`~`) range qualifier. For example, to get patches for the 3.15
 > release, and avoid automatically updating to the 3.16 release, specify the
@@ -67,7 +67,7 @@ For more information, see their [Never Ending Support][hd-link] service.
 
 Fastify uses GitHub Actions for CI testing, please refer to [GitHub's
 documentation regarding workflow
-runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
+runners](https://docs.github.com/en/actions/reference/runners/github-hosted-runners#supported-runners-and-hardware-resources)
 for further details on what the latest virtual environment is in relation to the
 YAML workflow labels below:
 

package/docs/Reference/Lifecycle.md

@@ -41,6 +41,11 @@ Incoming Request
                                                                             └─▶ onResponse Hook
 ```
 
+When `handlerTimeout` is configured, a timer starts after routing. If the
+response is not sent within the allowed time, `request.signal` is aborted and
+a 503 error is sent. The timer is cleared when the response finishes or when
+`reply.hijack()` is called. See [`handlerTimeout`](./Server.md#factory-handler-timeout).
+
 Before or during the `User Handler`, `reply.hijack()` can be called to:
 - Prevent Fastify from running subsequent hooks and the user handler
 - Prevent Fastify from sending the response automatically
@@ -81,4 +86,14 @@ submitted, the data flow is as follows:
 - The [reply serializer](./Server.md#setreplyserializer) if set
 - The [serializer compiler](./Server.md#setserializercompiler) if a JSON schema
   is set for the HTTP status code
-- The default `JSON.stringify` function
+- The default `JSON.stringify` function
+
+## Shutdown Lifecycle
+<a id="shutdown-lifecycle"></a>
+
+When [`fastify.close()`](./Server.md#close) is called, the server goes through a
+graceful shutdown sequence involving
+[`preClose`](./Hooks.md#pre-close) hooks, connection draining, and
+[`onClose`](./Hooks.md#on-close) hooks. See the
+[`close`](./Server.md#close) method documentation for the full step-by-step
+lifecycle.

package/docs/Reference/Logging.md

@@ -65,7 +65,7 @@ fastify.log.info('Something important happened!');
 
 #### Passing Logger Options
 To pass options to the logger, provide them to Fastify. See the
-[Pino documentation](https://github.com/pinojs/pino/blob/master/docs/api.md#options)
+[Pino documentation](https://github.com/pinojs/pino/blob/main/docs/api.md#options)
 for available options. To specify a file destination, use:
 
 ```js
@@ -107,7 +107,8 @@ value is used; otherwise, a new incremental ID is generated. See Fastify Factory
 [`requestIdHeader`](./Server.md#factory-request-id-header) and Fastify Factory
 [`genReqId`](./Server.md#genreqid) for customization options.
 
-> ⚠ Warning: enabling `requestIdHeader` allows any callers to set `reqId` to a
+> ⚠ Warning:
+> Enabling `requestIdHeader` allows any callers to set `reqId` to a
 > value of their choosing.
 > No validation is performed on `requestIdHeader`.
 
@@ -161,7 +162,8 @@ const fastify = require('fastify')({
 });
 ```
 
-> ℹ️ Note: In some cases, the [`Reply`](./Reply.md) object passed to the `res`
+> ℹ️ Note:
+> In some cases, the [`Reply`](./Reply.md) object passed to the `res`
 > serializer cannot be fully constructed. When writing a custom `res`
 > serializer, check for the existence of any properties on `reply` aside from
 > `statusCode`, which is always present. For example, verify the existence of
@@ -188,9 +190,10 @@ const fastify = require('fastify')({
 });
 ```
 
-> ℹ️ Note: The body cannot be serialized inside a `req` method because the
-request is serialized when the child logger is created. At that time, the body
-is not yet parsed.
+> ℹ️ Note:
+> The body cannot be serialized inside a `req` method because the
+> request is serialized when the child logger is created. At that time, the body
+> is not yet parsed.
 
 See the following approach to log `req.body`:
 
@@ -203,7 +206,8 @@ app.addHook('preHandler', function (req, reply, done) {
 })
 ```
 
-> ℹ️ Note: Ensure serializers never throw errors, as this can cause the Node
+> ℹ️ Note:
+> Ensure serializers never throw errors, as this can cause the Node
 > process to exit. See the
 > [Pino documentation](https://getpino.io/#/docs/api?id=opt-serializers) for more
 > information.

package/docs/Reference/Middleware.md

@@ -50,7 +50,8 @@ that already has the Fastify [Request](./Request.md#request) and
 To run middleware under certain paths, pass the path as the first parameter to
 `use`.
 
-> ℹ️ Note: This does not support routes with parameters
+> ℹ️ Note:
+> This does not support routes with parameters
 > (e.g. `/user/:id/comments`) and wildcards are not supported in multiple paths.
 
 ```js
@@ -75,4 +76,4 @@ Fastify offers alternatives to commonly used middleware, such as
 [`@fastify/cors`](https://github.com/fastify/fastify-cors) for
 [`cors`](https://github.com/expressjs/cors), and
 [`@fastify/static`](https://github.com/fastify/fastify-static) for
-[`serve-static`](https://github.com/expressjs/serve-static).
+[`serve-static`](https://github.com/expressjs/serve-static).

package/docs/Reference/Reply.md

@@ -152,7 +152,8 @@ fastify.get('/', async function (req, rep) {
 Sets a response header. If the value is omitted or undefined, it is coerced to
 `''`.
 
-> ℹ️ Note: The header's value must be properly encoded using
+> ℹ️ Note:
+> The header's value must be properly encoded using
 > [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
 > or similar modules such as
 > [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid characters
@@ -261,11 +262,13 @@ requires heavy resources to be sent after the `data`, for example,
 `Server-Timing` and `Etag`. It can ensure the client receives the response data
 as soon as possible.
 
-> ℹ️ Note: The header `Transfer-Encoding: chunked` will be added once you use
+> ℹ️ Note:
+> The header `Transfer-Encoding: chunked` will be added once you use
 > the trailer. It is a hard requirement for using trailer in Node.js.
 
-> ℹ️ Note: Any error passed to `done` callback will be ignored. If you interested
-> in the error, you can turn on `debug` level logging.*
+> ℹ️ Note:
+> Any error passed to `done` callback will be ignored. If you are interested
+> in the error, you can turn on `debug` level logging.
 
 ```js
 reply.trailer('server-timing', function() {
@@ -315,7 +318,8 @@ reply.getTrailer('server-timing') // undefined
 Redirects a request to the specified URL, the status code is optional, default
 to `302` (if status code is not already set by calling `code`).
 
-> ℹ️ Note: The input URL must be properly encoded using
+> ℹ️ Note:
+> The input URL must be properly encoded using
 > [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
 > or similar modules such as
 > [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid URLs will
@@ -673,7 +677,8 @@ If you pass a string to `send` without a `Content-Type`, it will be sent as
 string to `send`, it will be serialized with the custom serializer if one is
 set, otherwise, it will be sent unmodified.
 
-> **Note:** Even when the `Content-Type` header is set to `application/json`,
+> ℹ️ Note:
+> Even when the `Content-Type` header is set to `application/json`,
 > strings are sent unmodified by default. To serialize a string as JSON, you
 > must set a custom serializer:
 
@@ -838,7 +843,8 @@ automatically create an error structured as the following:
 You can add custom properties to the Error object, such as `headers`, that will
 be used to enhance the HTTP response.
 
-> ℹ️ Note: If you are passing an error to `send` and the statusCode is less than
+> ℹ️ Note:
+> If you are passing an error to `send` and the statusCode is less than
 > 400, Fastify will automatically set it at 500.
 
 Tip: you can simplify errors by using the
@@ -886,7 +892,8 @@ fastify.get('/', {
 If you want to customize error handling, check out
 [`setErrorHandler`](./Server.md#seterrorhandler) API.
 
-> ℹ️ Note: you are responsible for logging when customizing the error handler.
+> ℹ️ Note:
+> You are responsible for logging when customizing the error handler.
 
 API:
 

package/docs/Reference/Request.md

@@ -25,6 +25,11 @@ Request is a core Fastify object containing the following fields:
   enabled). For HTTP/2 compatibility, it returns `:authority` if no host header
   exists. The host header may return an empty string if `requireHostHeader` is
   `false`, not provided with HTTP/1.0, or removed by schema validation.
+  ⚠ Security: this value comes from client-controlled headers; only trust it
+  when you control proxy behavior and have validated or allow-listed hosts.
+  No additional validation is performed beyond RFC parsing (see
+  [RFC 9110, section 7.2](https://www.rfc-editor.org/rfc/rfc9110#section-7.2) and
+  [RFC 3986, section 3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2)).
 - `hostname` - The hostname derived from the `host` property of the incoming request.
 - `port` - The port from the `host` property, which may refer to the port the
   server is listening on.
@@ -35,12 +40,22 @@ Request is a core Fastify object containing the following fields:
   case of internal re-routing.
 - `is404` - `true` if request is being handled by 404 handler, `false` otherwise.
 - `socket` - The underlying connection of the incoming request.
+- `signal` - An `AbortSignal` that aborts when the handler timeout
+  fires or the client disconnects. Created lazily on first access, so
+  there is zero overhead when not used. When
+  [`handlerTimeout`](./Server.md#factory-handler-timeout) is configured,
+  the signal is pre-created and also aborts on timeout. Pass it to
+  `fetch()`, database queries, or any API accepting a `signal` option
+  for cooperative cancellation. On timeout, `signal.reason` is the
+  `FST_ERR_HANDLER_TIMEOUT` error; on client disconnect it is a generic
+  `AbortError`. Check `signal.reason.code` to distinguish the two cases.
 - `context` - Deprecated, use `request.routeOptions.config` instead. A Fastify
   internal object. Do not use or modify it directly. It is useful to access one
   special key:
   - `context.config` - The route [`config`](./Routes.md#routes-config) object.
 - `routeOptions` - The route [`option`](./Routes.md#routes-options) object.
   - `bodyLimit` - Either server limit or route limit.
+  - `handlerTimeout` - The handler timeout configured for this route.
   - `config` - The [`config`](./Routes.md#routes-config) object for this route.
   - `method` - The HTTP method for the route.
   - `url` - The path of the URL to match this route.
@@ -84,7 +99,8 @@ This operation adds new values to the request headers, accessible via
 For performance reasons, `Symbol('fastify.RequestAcceptVersion')` may be added
 to headers on `not found` routes.
 
-> ℹ️ Note: Schema validation may mutate the `request.headers` and
+> ℹ️ Note:
+> Schema validation may mutate the `request.headers` and
 > `request.raw.headers` objects, causing the headers to become empty.
 
 ```js

package/docs/Reference/Routes.md

@@ -115,6 +115,11 @@ fastify.route(options)
   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).
+* `handlerTimeout`: maximum number of milliseconds for the route's full
+  lifecycle. Overrides the server-level
+  [`handlerTimeout`](./Server.md#factory-handler-timeout). Must be a positive
+  integer. When the timeout fires, `request.signal` is aborted and a 503 error
+  is sent through the error handler (which can be customized per-route).
 * `logLevel`: set log level for this route. See below.
 * `logSerializers`: set serializers to log for this route.
 * `config`: object used to store custom configuration.
@@ -138,7 +143,8 @@ fastify.route(options)
 
 * `reply` is defined in [Reply](./Reply.md).
 
-> ℹ️ Note: The documentation for `onRequest`, `preParsing`, `preValidation`,
+> ℹ️ Note:
+> The documentation for `onRequest`, `preParsing`, `preValidation`,
 > `preHandler`, `preSerialization`, `onSend`, and `onResponse` is detailed in
 > [Hooks](./Hooks.md). To send a response before the request is handled by the
 > `handler`, see [Respond to a request from
@@ -234,7 +240,8 @@ const opts = {
 fastify.get('/', opts)
 ```
 
-> ℹ️ Note: Specifying the handler in both `options` and as the third parameter to
+> ℹ️ Note:
+> Specifying the handler in both `options` and as the third parameter to
 > the shortcut method throws a duplicate `handler` error.
 
 ### Url building
@@ -403,7 +410,8 @@ This approach supports both `callback-style` and `async-await` with minimal
 trade-off. However, it is recommended to use only one style for consistent
 error handling within your application.
 
-> ℹ️ Note: Every async function returns a promise by itself.
+> ℹ️ Note:
+> Every async function returns a promise by itself.
 
 ### Route Prefixing
 <a id="route-prefixing"></a>
@@ -504,7 +512,7 @@ See the `prefixTrailingSlash` route option above to change this behavior.
 
 Different log levels can be set for routes in Fastify by passing the `logLevel`
 option to the plugin or route with the desired
-[value](https://github.com/pinojs/pino/blob/master/docs/api.md#level-string).
+[value](https://github.com/pinojs/pino/blob/main/docs/api.md#level-string).
 
 Be aware that setting `logLevel` at the plugin level also affects
 [`setNotFoundHandler`](./Server.md#setnotfoundhandler) and
@@ -533,7 +541,7 @@ Fastify Logger, accessible with `fastify.log`.*
 <a id="custom-log-serializer"></a>
 
 In some contexts, logging a large object may waste resources. Define custom
-[`serializers`](https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object)
+[`serializers`](https://github.com/pinojs/pino/blob/main/docs/api.md#serializers-object)
 and attach them in the appropriate context.
 
 ```js
@@ -636,7 +644,8 @@ has a version set, and will prefer a versioned route to a non-versioned route
 for the same path. Advanced version ranges and pre-releases currently are not
 supported.
 
-> **Note:** using this feature can degrade the router’s performance.
+> ℹ️ Note:
+> Using this feature can degrade the router's performance.
 
 ```js
 fastify.route({