fastify 5.7.4 → 5.8.1

package/docs/Reference/Server.md

@@ -224,6 +224,71 @@ in front.
 > ℹ️ Note:
 >  At the time of writing, only node >= v14.11.0 supports this option
 
+### `handlerTimeout`
+<a id="factory-handler-timeout"></a>
+
++ Default: `0` (no timeout)
+
+Defines the maximum number of milliseconds allowed for processing a request
+through the entire route lifecycle (from routing through onRequest, parsing,
+validation, handler execution, and serialization). If the response is not sent
+within this time, a `503 Service Unavailable` error is returned and
+`request.signal` is aborted.
+
+Unlike `connectionTimeout` and `requestTimeout` (which operate at the socket
+level), `handlerTimeout` is an application-level timeout that works correctly
+with HTTP keep-alive connections. It can be overridden per-route via
+[route options](./Routes.md#routes-options). When set at both levels, the
+route-level value takes precedence. Routes without an explicit `handlerTimeout`
+inherit the server default. Once a server-level timeout is set, individual
+routes cannot opt out of it — they can only override it with a different
+positive integer.
+
+The timeout is **cooperative**: when it fires, Fastify sends the 503 error
+response, but the handler's async work continues to run. Use
+[`request.signal`](./Request.md) to detect cancellation and stop ongoing work
+(database queries, HTTP requests, etc.). APIs that accept a `signal` option
+(`fetch()`, database drivers, `stream.pipeline()`) will cancel automatically.
+
+The timeout error (`FST_ERR_HANDLER_TIMEOUT`) is sent through the route's
+[error handler](./Routes.md#routes-options), which can be customized per-route
+to change the status code or response body.
+
+When `reply.hijack()` is called, the timeout timer is cleared — the handler
+takes full responsibility for the response lifecycle.
+
+> ℹ️ Note:
+> `handlerTimeout` does not apply to 404 handlers or custom not-found handlers
+> set via `setNotFoundHandler()`, as they bypass the route handler lifecycle.
+
+```js
+const fastify = require('fastify')({
+  handlerTimeout: 10000 // 10s default for all routes
+})
+
+// Override per-route
+fastify.get('/slow-report', { handlerTimeout: 120000 }, async (request) => {
+  // Use request.signal for cooperative cancellation
+  const data = await db.query(longQuery, { signal: request.signal })
+  return data
+})
+
+// Customize the timeout response
+fastify.get('/custom-timeout', {
+  handlerTimeout: 5000,
+  errorHandler: (error, request, reply) => {
+    if (error.code === 'FST_ERR_HANDLER_TIMEOUT') {
+      reply.code(504).send({ error: 'Gateway Timeout' })
+    } else {
+      reply.send(error)
+    }
+  }
+}, async (request) => {
+  const result = await externalService.call({ signal: request.signal })
+  return result
+})
+```
+
 ### `bodyLimit`
 <a id="factory-body-limit"></a>
 
@@ -427,7 +492,8 @@ const fastify = require('fastify')({
 })
 ```
 
-> ⚠ Warning: enabling this allows any callers to set `reqId` to a
+> ⚠ Warning:
+> Enabling this allows any callers to set `reqId` to a
 > value of their choosing.
 > No validation is performed on `requestIdHeader`.
 
@@ -521,8 +587,8 @@ controls [avvio](https://www.npmjs.com/package/avvio) 's `timeout` parameter.
 ### `querystringParser`
 <a id="factory-querystring-parser"></a>
 
-The default query string parser that Fastify uses is a more performant fork 
-of Node.js's core `querystring` module called 
+The default query string parser that Fastify uses is a more performant fork
+of Node.js's core `querystring` module called
 [`fast-querystring`](https://github.com/anonrig/fast-querystring).
 
 You can use this option to use a custom parser, such as
@@ -566,8 +632,14 @@ define it before the `GET` route.
 
 + Default: `true`
 
-Returns 503 after calling `close` server method. If `false`, the server routes
-the incoming request as usual.
+When `true`, any request arriving after [`close`](#close) has been called will
+receive a `503 Service Unavailable` response with `Connection: close` header
+(HTTP/1.1). This lets load balancers detect that the server is shutting down and
+stop routing traffic to it.
+
+When `false`, requests arriving during the closing phase are routed and
+processed normally. They will still receive a `Connection: close` header so that
+clients do not attempt to reuse the connection.
 
 ### `ajv`
 <a id="factory-ajv"></a>
@@ -745,7 +817,7 @@ function rewriteUrl (req) {
 <a id="routeroptions"></a>
 
 Fastify uses [`find-my-way`](https://github.com/delvedor/find-my-way) for its
-HTTP router. The `routerOptions` parameter allows passing 
+HTTP router. The `routerOptions` parameter allows passing
 [`find-my-way` options](https://github.com/delvedor/find-my-way?tab=readme-ov-file#findmywayoptions)
 to customize the HTTP router within Fastify.
 
@@ -769,8 +841,8 @@ fastify.get('/user/:id(^([0-9]+){4}$)', (request, reply) => {
 <a id="build-pretty-meta"></a>
 
 Fastify uses [find-my-way](https://github.com/delvedor/find-my-way) which
-supports, `buildPrettyMeta` where you can assign a `buildPrettyMeta` 
-function to sanitize a route's store object to use with the `prettyPrint` 
+supports, `buildPrettyMeta` where you can assign a `buildPrettyMeta`
+function to sanitize a route's store object to use with the `prettyPrint`
 functions. This function should accept a single object and return an object.
 
 ```js
@@ -865,7 +937,7 @@ const fastify = require('fastify')({
 })
 ```
 
-> **Note**
+> ℹ️ Note:
 > The `req` and `res` objects passed to `defaultRoute` are the raw Node.js
 > `IncomingMessage` and `ServerResponse` instances. They do **not** expose the
 > Fastify-specific methods available on `FastifyRequest`/`FastifyReply` (for
@@ -1029,11 +1101,12 @@ fastify.get('/dev', async (request, reply) => {
 
 * **Default:** `true`
 
-> ⚠ **Warning:** This option will be set to `false` by default 
+> ⚠ Warning:
+> This option will be set to `false` by default
 > in the next major release.
 
-When set to `false`, it prevents `setErrorHandler` from being called 
-multiple times within the same scope, ensuring that the previous error 
+When set to `false`, it prevents `setErrorHandler` from being called
+multiple times within the same scope, ensuring that the previous error
 handler is not unintentionally overridden.
 
 #### Example of incorrect usage:
@@ -1331,6 +1404,53 @@ fastify.close().then(() => {
 })
 ```
 
+##### Shutdown lifecycle
+
+When `fastify.close()` is called, the following steps happen in order:
+
+1. The server is flagged as **closing**. New incoming requests receive a
+   `Connection: close` header (HTTP/1.1) and are handled according to
+   [`return503OnClosing`](#factory-return-503-on-closing).
+2. [`preClose`](./Hooks.md#pre-close) hooks execute. The server is still
+   processing in-flight requests at this point.
+3. **Connection draining** based on the
+   [`forceCloseConnections`](#forcecloseconnections) option:
+   - `"idle"` — idle keep-alive connections are closed; in-flight requests
+     continue.
+   - `true` — all persistent connections are destroyed immediately.
+   - `false` — no forced closure; idle connections remain open until they time
+     out naturally (see [`keepAliveTimeout`](#keepalivetimeout)).
+4. The HTTP server **stops accepting** new TCP connections
+   (`server.close()`). Node.js waits for all in-flight requests to complete
+   before invoking the callback.
+5. [`onClose`](./Hooks.md#on-close) hooks execute. All in-flight requests have
+   completed and the server is no longer listening.
+6. The `close` callback (or the returned Promise) resolves.
+
+```
+fastify.close() called
+  │
+  ├─▶ closing = true (new requests receive 503)
+  │
+  ├─▶ preClose hooks
+  │     (in-flight requests still active)
+  │
+  ├─▶ Connection draining (forceCloseConnections)
+  │
+  ├─▶ server.close()
+  │     (waits for in-flight requests to complete)
+  │
+  ├─▶ onClose hooks
+  │     (server stopped, all requests done)
+  │
+  └─▶ close callback / Promise resolves
+```
+
+> ℹ️ Note:
+> Upgraded connections (such as WebSocket) are not tracked by the HTTP
+> server and will prevent `server.close()` from completing. Close them
+> explicitly in a [`preClose`](./Hooks.md#pre-close) hook.
+
 #### decorate*
 <a id="decorate"></a>
 
@@ -1391,7 +1511,7 @@ different ways to define a name (in order).
    Example: `pluginFn[Symbol.for('fastify.display-name')] = "Custom Name"`
 3. If you `module.exports` a plugin the filename is used.
 4. If you use a regular [function
-   declaration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions#Defining_functions)
+   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.
@@ -1731,7 +1851,7 @@ set it to 500 before calling the error handler.
 - not found (404) errors. Use [`setNotFoundHandler`](#set-not-found-handler)
   instead.
 - Stream errors thrown during piping into the response socket, as
-  headers/response were already sent to the client. 
+  headers/response were already sent to the client.
   Use custom in-stream data to signal such errors.
 
 ```js
@@ -2173,6 +2293,7 @@ initial options passed down by the user to the Fastify instance.
 The properties that can currently be exposed are:
 - connectionTimeout
 - keepAliveTimeout
+- handlerTimeout
 - bodyLimit
 - caseSensitive
 - http2

package/docs/Reference/Type-Providers.md

@@ -63,13 +63,13 @@ server.get('/route', {
 The following sets up a TypeBox Type Provider:
 
 ```bash
-$ npm i @fastify/type-provider-typebox
+$ npm i typebox @fastify/type-provider-typebox
 ```
 
 ```typescript
 import fastify from 'fastify'
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
-import { Type } from '@sinclair/typebox'
+import { Type } from 'typebox'
 
 const server = fastify().withTypeProvider<TypeBoxTypeProvider>()
 
@@ -109,7 +109,7 @@ Example:
 import Fastify from 'fastify'
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
 import { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
-import { Type } from '@sinclair/typebox'
+import { Type } from 'typebox'
 
 const fastify = Fastify()
 
@@ -159,7 +159,7 @@ with several scopes, as shown below:
 ```ts
 import Fastify from 'fastify'
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
-import { Type } from '@sinclair/typebox'
+import { Type } from 'typebox'
 
 const server = Fastify().withTypeProvider<TypeBoxTypeProvider>()
 
@@ -221,7 +221,7 @@ server.listen({ port: 3000 })
 
 ```ts
 // routes.ts
-import { Type } from '@sinclair/typebox'
+import { Type } from 'typebox'
 import {
   FastifyInstance,
   FastifyBaseLogger,

package/docs/Reference/TypeScript.md

@@ -58,8 +58,9 @@ in a blank http Fastify server.
   or use one of the [recommended
   ones](https://github.com/tsconfig/bases#node-14-tsconfigjson).
 
-*Note: Set `target` property in `tsconfig.json` to `es2017` or greater to avoid
-[FastifyDeprecation](https://github.com/fastify/fastify/issues/3284) warning.*
+> ℹ️ Note:
+> Set `target` property in `tsconfig.json` to `es2017` or greater to avoid
+> [FastifyDeprecation](https://github.com/fastify/fastify/issues/3284) warning.
 
 4. Create an `index.ts` file - this will contain the server code
 5. Add the following code block to your file:
@@ -216,7 +217,7 @@ providers.
 
 #### TypeBox
 
-A useful library for building types and a schema at once is [TypeBox](https://www.npmjs.com/package/@sinclair/typebox).
+A useful library for building types and a schema at once is [TypeBox](https://www.npmjs.com/package/typebox).
 With TypeBox you define your schema within your code and use them directly as
 types or schemas as you need them.
 
@@ -226,14 +227,14 @@ can do it as follows:
 1. Install `typebox` in your project.
 
     ```bash
-    npm i @sinclair/typebox
+    npm i typebox
     ```
 
 2. Define the schema you need with `Type` and create the respective type  with
    `Static`.
 
     ```typescript
-    import { Static, Type } from '@sinclair/typebox'
+    import { Static, Type } from 'typebox'
 
     export const User = Type.Object({
       name: Type.String(),
@@ -1621,8 +1622,9 @@ previous hook was `preValidation`, the next hook will be `preSerialization`.
 `preSerialization` is the fifth hook to be executed in the request lifecycle.
 The previous hook was `preHandler`, the next hook will be `onSend`.
 
-Note: the hook is NOT called if the payload is a string, a Buffer, a stream or
-null.
+> ℹ️ Note:
+> The hook is NOT called if the payload is a string, a Buffer,
+> a stream, or null.
 
 ##### fastify.onSendHookHandler< OnSendPayload, [RawServer][RawServerGeneric], [RawRequest][RawRequestGeneric], [RawReply][RawReplyGeneric], [RequestGeneric][FastifyRequestGenericInterface], [ContextConfig][ContextConfigGeneric]>(request: [FastifyRequest][FastifyRequest], reply: [FastifyReply][FastifyReply], payload: OnSendPayload, done: (err: [FastifyError][FastifyError] | null, res?: unknown) => void): Promise\<unknown\> | void
 
@@ -1632,8 +1634,9 @@ You can change the payload with the `onSend` hook. It is the sixth hook to be
 executed in the request lifecycle. The previous hook was `preSerialization`, the
 next hook will be `onResponse`.
 
-Note: If you change the payload, you may only change it to a string, a Buffer, a
-stream, or null.
+> ℹ️ Note:
+>  If you change the payload, you may only change it to a string,
+> a Buffer, a stream, or null.
 
 ##### fastify.onResponseHookHandler< [RawServer][RawServerGeneric], [RawRequest][RawRequestGeneric], [RawReply][RawReplyGeneric], [RequestGeneric][FastifyRequestGenericInterface], [ContextConfig][ContextConfigGeneric]>(request: [FastifyRequest][FastifyRequest], reply: [FastifyReply][FastifyReply], done: (err?: [FastifyError][FastifyError]) => void): Promise\<unknown\> | void
 
@@ -1679,7 +1682,8 @@ created. The hook will be executed before the registered code.
 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.
 
-Note: This hook will not be called if a plugin is wrapped inside fastify-plugin.
+> ℹ️ Note:
+> This hook will not be called if a plugin is wrapped inside fastify-plugin.
 
 ##### fastify.onCloseHookHandler< [RawServer][RawServerGeneric], [RawRequest][RawRequestGeneric], [RawReply][RawReplyGeneric], [Logger][LoggerGeneric]>(instance: [FastifyInstance][FastifyInstance], done: (err?: [FastifyError][FastifyError]) => void): Promise\<unknown\> | void
 

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

@@ -329,6 +329,31 @@ server.setValidatorCompiler(req => {
 })
 ```
 
+When type coercion is enabled, using `anyOf` with nullable primitive types
+can produce unexpected results. For example, a value of `0` or `false` may be
+coerced to `null` because Ajv evaluates `anyOf` schemas in order and applies
+type coercion during matching. This means the `{ "type": "null" }` branch can
+match before the intended type:
+
+```json
+{
+  "anyOf": [
+    { "type": "null" },
+    { "type": "number" }
+  ]
+}
+```
+
+To avoid this, use the `nullable` keyword instead of `anyOf` for primitive
+types:
+
+```json
+{
+  "type": "number",
+  "nullable": true
+}
+```
+
 For more information, see [Ajv Coercion](https://ajv.js.org/coercion.html).
 
 #### Ajv Plugins
@@ -439,7 +464,9 @@ fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
   return ajv.compile(schema)
 })
 ```
-> ℹ️ Note: When using a custom validator instance, add schemas to the validator
+
+> ℹ️ Note:
+> When using a custom validator instance, add schemas to the validator
 > instead of Fastify. Fastify's `addSchema` method will not recognize the custom
 > validator.
 

package/fastify.d.ts

@@ -119,6 +119,7 @@ declare namespace fastify {
     requestTimeout?: number,
     pluginTimeout?: number,
     bodyLimit?: number,
+    handlerTimeout?: number,
     maxParamLength?: number,
     disableRequestLogging?: boolean | ((req: FastifyRequest) => boolean),
     exposeHeadRoutes?: boolean,

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '5.7.4'
+const VERSION = '5.8.1'
 
 const Avvio = require('avvio')
 const http = require('node:http')
@@ -32,7 +32,8 @@ const {
   kKeepAliveConnections,
   kChildLoggerFactory,
   kGenReqId,
-  kErrorHandlerAlreadySet
+  kErrorHandlerAlreadySet,
+  kHandlerTimeout
 } = require('./lib/symbols.js')
 
 const { createServer } = require('./lib/server')
@@ -147,6 +148,7 @@ function fastify (serverOptions) {
     [kChildren]: [],
     [kServerBindings]: [],
     [kBodyLimit]: options.bodyLimit,
+    [kHandlerTimeout]: options.handlerTimeout,
     [kRoutePrefix]: '',
     [kLogLevel]: '',
     [kLogSerializers]: null,