fastify 5.6.0 → 5.6.2

package/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "workbench.colorCustomizations": {
+    "[GitHub Dark]": {
+      "tab.activeBackground": "#0d0d0d",
+      "tab.activeBorder": "#ffff00"
+    },
+    "activityBar.background": "#FBE7B2",
+    "activityBar.foreground": "#52358C",
+    "activityBar.inactiveForeground": "#616161",
+    "activityBar.activeBorder": "#04184d",
+    "activityBar.activeBackground": "#C3B48B",
+    "activityBar.border": "#C3B48B",
+    "titleBar.activeBackground": "#D2BE88",
+    "titleBar.activeForeground": "#52358C",
+    "titleBar.inactiveBackground": "#bdb59c",
+    "titleBar.inactiveForeground": "#616161",
+    "titleBar.border": "#C3B48B",
+    "statusBar.background": "#E9DBB7",
+    "statusBar.foreground": "#52358C",
+    "statusBar.border": "#C3B48B"
+  }
+}

package/SECURITY.md

@@ -110,6 +110,18 @@ Within HackerOne, this is handled through a "public disclosure request".
 Reference: [HackerOne:
 Disclosure](https://docs.hackerone.com/hackers/disclosure.html)
 
+### Secondary Contact
+
+If you do not receive an acknowledgment of your report within 6 business days,
+or if you cannot find a private security contact for the project, you may
+contact the OpenJS Foundation CNA at `security@lists.openjsf.org` for
+assistance.
+
+The CNA can help ensure your report is properly acknowledged, assist with
+coordinating disclosure timelines, and assign CVEs when necessary. This is a
+support mechanism to ensure security reports are handled appropriately across
+all OpenJS Foundation projects.
+
 ## The Fastify Security team
 
 The core team is responsible for the management of the security program and

package/SPONSORS.md

@@ -17,6 +17,7 @@ _Be the first!_
 - [Val Town, Inc.](https://opencollective.com/valtown)
 - [Handsontable - JavaScript Data Grid](https://handsontable.com/docs/react-data-grid/?utm_source=Fastify_GH&utm_medium=sponsorship&utm_campaign=library_sponsorship_2024)
 - [Lokalise - A Localization and Translation Software Tool](https://lokalise.com/?utm_source=Fastify_GH&utm_medium=sponsorship)
+- [Lambdatest](https://www.lambdatest.com/)
 
 ## Tier 2
 

package/build/build-validation.js

@@ -16,7 +16,7 @@ module.exports.defaultInitOptions = ${JSON.stringify(defaultInitOptions)}
 /* c8 ignore stop */
 `
 
-    const file = path.join(__dirname, '..', 'lib', 'configValidator.js')
+    const file = path.join(__dirname, '..', 'lib', 'config-validator.js')
     fs.writeFileSync(file, moduleCode)
     console.log(`Saved ${file} file successfully`)
   }

package/build/sync-version.js

@@ -9,3 +9,4 @@ const { version } = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'packa
 const fastifyJs = path.join(__dirname, '..', 'fastify.js')
 
 fs.writeFileSync(fastifyJs, fs.readFileSync(fastifyJs).toString('utf8').replace(/const\s*VERSION\s*=.*/, `const VERSION = '${version}'`))
+console.log(`Synchronized fastify.js VERSION to ${version}`)

package/docs/Guides/Ecosystem.md

@@ -119,6 +119,8 @@ section.
   HTTP errors and assertions, but also more request and reply methods.
 - [`@fastify/session`](https://github.com/fastify/session) a session plugin for
   Fastify.
+- [`@fastify/sse`](https://github.com/fastify/sse) Plugin for Server-Sent Events
+  (SSE) support in Fastify.
 - [`@fastify/static`](https://github.com/fastify/fastify-static) Plugin for
   serving static files as fast as possible.
 - [`@fastify/swagger`](https://github.com/fastify/fastify-swagger) Plugin for
@@ -165,6 +167,9 @@ section.
   A simple way to add a crud in your fastify project.
 - [`@applicazza/fastify-nextjs`](https://github.com/applicazza/fastify-nextjs)
   Alternate Fastify and Next.js integration.
+- [`@attaryz/fastify-devtools`](https://github.com/attaryz/fastify-devtools)
+  Development tools plugin for Fastify with live request dashboard, replay
+  capabilities, and metrics tracking.
 - [`@blastorg/fastify-aws-dynamodb-cache`](https://github.com/blastorg/fastify-aws-dynamodb-cache)
   A plugin to help with caching API responses using AWS DynamoDB.
 - [`@clerk/fastify`](https://github.com/clerkinc/javascript/tree/main/packages/fastify)

package/docs/Guides/Fluent-Schema.md

@@ -122,5 +122,5 @@ const schema = { body: bodyJsonSchema }
 fastify.post('/the/url', { schema }, handler)
 ```
 
-NB You can mix up the `$ref-way` and the `replace-way` when using
-`fastify.addSchema`.
+> ℹ️ Note: You can mix up the `$ref-way` and the `replace-way`
+> when using `fastify.addSchema`.

package/docs/Reference/Decorators.md

@@ -366,201 +366,68 @@ Will define the `foo` property on the Fastify instance:
 console.log(fastify.foo) // 'a getter'
 ```
 
-### `getDecorator<T>` API
+#### `getDecorator(name)`
+<a id="get-decorator"></a>
 
-Fastify's `getDecorator<T>` API retrieves an existing decorator from the
-Fastify instance, `Request`, or `Reply`. If the decorator is not defined, an
-`FST_ERR_DEC_UNDECLARED` error is thrown.
+Used to retrieve an existing decorator from the Fastify instance, `Request`, or `Reply`.
+If the decorator is not defined, an `FST_ERR_DEC_UNDECLARED` error is thrown.
 
-#### Use cases
+```js
+// Get a decorator from the Fastify instance
+const utility = fastify.getDecorator('utility')
 
-**Early Plugin Dependency Validation**
+// Get a decorator from the request object
+const user = request.getDecorator('user')
 
-`getDecorator<T>` on Fastify instance verifies that required decorators are
-available at registration time. 
+// Get a decorator from the reply object
+const helper = reply.getDecorator('helper')
+```
 
-For example:
+The `getDecorator` method is useful for dependency validation - it can be used to
+check for required decorators at registration time. If any are missing, it fails
+at boot, ensuring dependencies are available during the request lifecycle.
 
 ```js
 fastify.register(async function (fastify) {
+  // Verify the decorator exists before using it
   const usersRepository = fastify.getDecorator('usersRepository')
 
   fastify.get('/users', async function (request, reply) {
-    // We are sure `usersRepository` exists at runtime
     return usersRepository.findAll()
   })
 })
 ```
 
-**Handling Missing Decorators**
-
-Directly accessing a decorator may lead to unexpected behavior if it is not declared:
-
-```ts
-const user = request.user;
-if (user && user.isAdmin) {
-  // Execute admin tasks.
-}
-```
-
-If `request.user` doesn't exist, then `user` will be set to `undefined`. 
-This makes it unclear whether the user is unauthenticated or the decorator is missing.
-
-Using `getDecorator` enforces runtime safety:
-
-```ts
-// If the decorator is missing, an explicit `FST_ERR_DEC_UNDECLARED` 
-// error is thrown immediately.
-const user = request.getDecorator('user');
-if (user && user.isAdmin) {
-  // Execute admin tasks.
-}
-```
-
-**Alternative to Module Augmentation**
-
-Decorators are typically typed via module augmentation:
-
-```ts
-declare module 'fastify' {
-  interface FastifyInstance {
-    usersRepository: IUsersRepository
-  }
-  interface FastifyRequest {
-    session: ISession
-  }
-  interface FastifyReply {
-    sendSuccess: SendSuccessFn
-  }
-}
-```
-
-This approach modifies the Fastify instance globally, which may lead to
-conflicts and inconsistent behavior in multi-server setups or with plugin
-encapsulation.
-
-Using `getDecorator<T>` allows to limit types scope:
-
-```ts
-serverOne.register(async function (fastify) {
-  const usersRepository = fastify.getDecorator<PostgreUsersRepository>(
-    'usersRepository'
-  )
-
-  fastify.decorateRequest('session', null)
-  fastify.addHook('onRequest', async (req, reply) => {
-    // Yes, the request object has a setDecorator method. 
-    // More information will be provided soon.
-    req.setDecorator('session', { user: 'Jean' })
-  })
-
-  fastify.get('/me', (request, reply) => {
-    const session = request.getDecorator<ISession>('session')
-    reply.send(session)
-  })
-})
-
-serverTwo.register(async function (fastify) {
-  const usersRepository = fastify.getDecorator<SqlLiteUsersRepository>(
-    'usersRepository'
-  )
-
-  fastify.decorateReply('sendSuccess', function (data) {
-    return this.send({ success: true })
-  })
-
-  fastify.get('/success', async (request, reply) => {
-    const sendSuccess = reply.getDecorator<SendSuccessFn>('sendSuccess')
-    await sendSuccess()
-  })
-})
-```
+> ℹ️ Note: For TypeScript users, `getDecorator` supports generic type parameters.
+> See the [TypeScript documentation](/docs/latest/Reference/TypeScript/) for
+> advanced typing examples.
 
-#### Bound functions inference
+#### `setDecorator(name, value)`
+<a id="set-decorator"></a>
 
-To save time, it's common to infer function types instead of 
-writing them manually:
+Used to safely update the value of a `Request` decorator.
+If the decorator does not exist, a `FST_ERR_DEC_UNDECLARED` error is thrown.
 
-```ts
-function sendSuccess (this: FastifyReply) {
-  return this.send({ success: true })
-}
-
-export type SendSuccess = typeof sendSuccess
-```
-
-However, `getDecorator` returns functions with the `this` 
-context already **bound**, meaning the `this` parameter disappears 
-from the function signature.
-
-To correctly type it, you should use `OmitThisParameter` utility:
-
-```ts
-function sendSuccess (this: FastifyReply) {
-  return this.send({ success: true })
-}
-
-type BoundSendSuccess = OmitThisParameter<typeof sendSuccess>
-
-fastify.decorateReply('sendSuccess', sendSuccess)
-fastify.get('/success', async (request, reply) => {
-  const sendSuccess = reply.getDecorator<BoundSendSuccess>('sendSuccess')
-  await sendSuccess()
-})
-```
-
-### `Request.setDecorator<T>` Method
-
-The `setDecorator<T>` method provides a safe and convenient way to 
-update the value of a `Request` decorator.  
-If the decorator does not exist, a `FST_ERR_DEC_UNDECLARED` error 
-is thrown.
-
-#### Use Cases
-
-**Runtime Safety**
-
-A typical way to set a `Request` decorator looks like this:
-
-```ts
-fastify.decorateRequest('user', '')
-fastify.addHook('preHandler', async (req, reply) => {
-  req.user = 'Bob Dylan'
-})
-```
-
-However, there is no guarantee that the decorator actually exists 
-unless you manually check beforehand.  
-Additionally, typos are common, e.g. `account`, `acount`, or `accout`.
-
-By using `setDecorator`, you are always sure that the decorator exists:
+```js
+fastify.decorateRequest('user', null)
 
-```ts
-fastify.decorateRequest('user', '')
 fastify.addHook('preHandler', async (req, reply) => {
-  // Throws FST_ERR_DEC_UNDECLARED if the decorator does not exist
-  req.setDecorator('user-with-typo', 'Bob Dylan')
+  // Safely set the decorator value
+  req.setDecorator('user', 'Bob Dylan')
 })
 ```
 
----
-
-**Type Safety**
+The `setDecorator` method provides runtime safety by ensuring the decorator exists
+before setting its value, preventing errors from typos in decorator names.
 
-If the `FastifyRequest` interface does not declare the decorator, you 
-would typically need to use type assertions:
-
-```ts
+```js
+fastify.decorateRequest('account', null)
 fastify.addHook('preHandler', async (req, reply) => {
-  (req as typeof req & { user: string }).user = 'Bob Dylan'
+  // This will throw FST_ERR_DEC_UNDECLARED due to typo in decorator name
+  req.setDecorator('acount', { id: 123 })
 })
 ```
 
-The `setDecorator<T>` method eliminates the need for explicit type 
-assertions while allowing type safety:
-
-```ts
-fastify.addHook('preHandler', async (req, reply) => {
-  req.setDecorator<string>('user', 'Bob Dylan')
-})
-```
+> ℹ️ Note: For TypeScript users, see the
+> [TypeScript documentation](/docs/latest/Reference/TypeScript/) for advanced
+> typing examples using `setDecorator<T>`.

package/docs/Reference/Encapsulation.md

@@ -27,7 +27,11 @@ registered within its _grandchild context_.
 
 Given that everything in Fastify is a [plugin](./Plugins.md) except for the
 _root context_, every "context" and "plugin" in this example is a plugin
-that can consist of decorators, hooks, plugins, and routes. To put this
+that can consist of decorators, hooks, plugins, and routes. As plugins, they
+must still signal completion either by returning a Promise (e.g., using `async` functions)
+or by calling the `done` function if using the callback style.
+
+To put this
 example into concrete terms, consider a basic scenario of a REST API server
 with three routes: the first route (`/one`) requires authentication, the
 second route (`/two`) does not, and the third route (`/three`) has access to

package/docs/Reference/Plugins.md

@@ -171,18 +171,27 @@ export default plugin
 <a id="create-plugin"></a>
 
 Creating a plugin is easy. Create a function that takes three parameters: the
-`fastify` instance, an `options` object, and the `done` callback.
+`fastify` instance, an `options` object, and the `done` callback. Alternatively,
+use an `async` function and omit the `done` callback.
 
 Example:
 ```js
-module.exports = function (fastify, opts, done) {
+module.exports = function callbackPlugin (fastify, opts, done) {
   fastify.decorate('utility', function () {})
 
   fastify.get('/', handler)
 
   done()
 }
+
+// Or using async
+module.exports = async function asyncPlugin (fastify, opts) {
+  fastify.decorate('utility', function () {})
+
+  fastify.get('/', handler)
+}
 ```
+
 `register` can also be used inside another `register`:
 ```js
 module.exports = function (fastify, opts, done) {

package/docs/Reference/Reply.md

@@ -369,7 +369,7 @@ charset must be set explicitly.
 <a id="getserializationfunction"></a>
 
 By calling this function using a provided `schema` or `httpStatus`,
-and the optional `contentType`, it will return a `serialzation` function
+and the optional `contentType`, it will return a `serialization` function
 that can be used to serialize diverse inputs. It returns `undefined` if no
 serialization function was found using either of the provided inputs.
 
@@ -688,6 +688,9 @@ If you are sending a stream and you have not set a `'Content-Type'` header,
 As noted above, streams are considered to be pre-serialized, so they will be
 sent unmodified without response validation.
 
+See special note about error handling for streams in
+[`setErrorHandler`](./Server.md#seterrorhandler).
+
 ```js
 const fs = require('node:fs')
 

package/docs/Reference/Server.md

@@ -170,6 +170,12 @@ When set to `true`, upon [`close`](#close) the server will iterate the current
 persistent connections and [destroy their
 sockets](https://nodejs.org/dist/latest-v16.x/docs/api/net.html#socketdestroyerror).
 
+When used with HTTP/2 server, it will also close all active HTTP/2 sessions.
+
+> ℹ️ Note:
+> Since Node.js v24 active sessions are closed by default
+
+
 > ⚠ Warning:
 > Connections are not inspected to determine if requests have
 > been completed.
@@ -966,7 +972,7 @@ Fastify uses [find-my-way](https://github.com/delvedor/find-my-way) which suppor
 separating the path and query string with a `;` character (code 59), e.g. `/dev;foo=bar`.
 This decision originated from [delvedor/find-my-way#76]
 (https://github.com/delvedor/find-my-way/issues/76). Thus, this option will support
-backwards compatiblilty for the need to split on `;`. To enable support for splitting
+backwards compatibility for the need to split on `;`. To enable support for splitting
 on `;` set `useSemicolonDelimiter` to `true`.
 
 ```js
@@ -1436,6 +1442,8 @@ fastify.mkcol('/', (req, reply) => {
 })
 ```
 
+> ⚠ Warning:
+> `addHttpMethod` overrides existing methods.
 
 #### addSchema
 <a id="add-schema"></a>
@@ -1687,6 +1695,9 @@ set it to 500 before calling the error handler.
   sent to the client. Use the `onSend` hook instead.
 - 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. 
+  Use custom in-stream data to signal such errors.
 
 ```js
 fastify.setErrorHandler(function (error, request, reply) {
@@ -1716,6 +1727,33 @@ if (statusCode >= 500) {
 > Avoid calling setErrorHandler multiple times in the same scope.
 > See [`allowErrorHandlerOverride`](#allowerrorhandleroverride).
 
+##### Custom error handler for stream replies
+<a id="set-error-handler-stream-replies"></a>
+
+If `Content-Type` differs between the endpoint and error handler, explicitly
+define it in both. For example, if the endpoint returns an `application/text`
+stream and the error handler responds with `application/json`, the error handler
+must explicitly set `Content-Type`. Otherwise, it will fail serialization with
+a `500` status code. Alternatively, always respond with serialized data in the
+error handler by manually calling a serialization method (e.g.,
+`JSON.stringify`).
+
+```js
+fastify.setErrorHandler((err, req, reply) => {
+  reply
+    .code(400)
+    .type('application/json')
+    .send({ error: err.message })
+})
+```
+
+```js
+fastify.setErrorHandler((err, req, reply) => {
+  reply
+    .code(400)
+    .send(JSON.stringify({ error: err.message }))
+})
+```
 
 #### setChildLoggerFactory
 <a id="set-child-logger-factory"></a>

package/docs/Reference/Type-Providers.md

@@ -88,8 +88,8 @@ server.get('/route', {
 ```
 
 See the [TypeBox
-documentation](https://github.com/sinclairzx81/typebox#validation)
-for setting up AJV to work with TypeBox.
+documentation](https://sinclairzx81.github.io/typebox/#/docs/overview/2_setup)
+for setting-up AJV to work with TypeBox.
 
 ### Zod
 

package/docs/Reference/TypeScript.md

@@ -687,6 +687,142 @@ Or even explicit config on tsconfig
 }
 ```
 
+#### `getDecorator<T>`
+
+Fastify's `getDecorator<T>` method retrieves decorators with enhanced type safety.
+
+The `getDecorator<T>` method supports generic type parameters for enhanced type safety:
+
+```typescript
+// Type-safe decorator retrieval
+const usersRepository = fastify.getDecorator<IUsersRepository>('usersRepository')
+const session = request.getDecorator<ISession>('session')
+const sendSuccess = reply.getDecorator<SendSuccessFn>('sendSuccess')
+```
+
+**Alternative to Module Augmentation**
+
+Decorators are typically typed via module augmentation:
+
+```typescript
+declare module 'fastify' {
+  interface FastifyInstance {
+    usersRepository: IUsersRepository
+  }
+  interface FastifyRequest {
+    session: ISession
+  }
+  interface FastifyReply {
+    sendSuccess: SendSuccessFn
+  }
+}
+```
+
+This approach modifies the Fastify instance globally, which may lead to conflicts
+and inconsistent behavior in multi-server setups or with plugin encapsulation.
+
+Using `getDecorator<T>` allows limiting types scope:
+
+```typescript
+serverOne.register(async function (fastify) {
+  const usersRepository = fastify.getDecorator<PostgreUsersRepository>(
+    'usersRepository'
+  )
+
+  fastify.decorateRequest('session', null)
+  fastify.addHook('onRequest', async (req, reply) => {
+    req.setDecorator('session', { user: 'Jean' })
+  })
+
+  fastify.get('/me', (request, reply) => {
+    const session = request.getDecorator<ISession>('session')
+    reply.send(session)
+  })
+})
+
+serverTwo.register(async function (fastify) {
+  const usersRepository = fastify.getDecorator<SqlLiteUsersRepository>(
+    'usersRepository'
+  )
+
+  fastify.decorateReply('sendSuccess', function (data) {
+    return this.send({ success: true })
+  })
+
+  fastify.get('/success', async (request, reply) => {
+    const sendSuccess = reply.getDecorator<SendSuccessFn>('sendSuccess')
+    await sendSuccess()
+  })
+})
+```
+
+**Bound Functions Inference**
+
+To save time, it is common to infer function types instead of writing them manually:
+
+```typescript
+function sendSuccess (this: FastifyReply) {
+  return this.send({ success: true })
+}
+
+export type SendSuccess = typeof sendSuccess
+```
+
+However, `getDecorator` returns functions with the `this` context already **bound**,
+meaning the `this` parameter disappears from the function signature.
+
+To correctly type it, use the `OmitThisParameter` utility:
+
+```typescript
+function sendSuccess (this: FastifyReply) {
+  return this.send({ success: true })
+}
+
+type BoundSendSuccess = OmitThisParameter<typeof sendSuccess>
+
+fastify.decorateReply('sendSuccess', sendSuccess)
+fastify.get('/success', async (request, reply) => {
+  const sendSuccess = reply.getDecorator<BoundSendSuccess>('sendSuccess')
+  await sendSuccess()
+})
+```
+
+#### `setDecorator<T>`
+
+Fastify's `setDecorator<T>` method provides enhanced type safety for updating request
+decorators.
+
+The `setDecorator<T>` method provides enhanced type safety for updating request
+decorators:
+
+```typescript
+fastify.decorateRequest('user', '')
+fastify.addHook('preHandler', async (req, reply) => {
+  // Type-safe decorator setting
+  req.setDecorator<string>('user', 'Bob Dylan')
+})
+```
+
+**Type Safety Benefits**
+
+If the `FastifyRequest` interface does not declare the decorator, type assertions
+are typically needed:
+
+```typescript
+fastify.addHook('preHandler', async (req, reply) => {
+  (req as typeof req & { user: string }).user = 'Bob Dylan'
+})
+```
+
+The `setDecorator<T>` method eliminates the need for explicit type assertions
+while providing type safety:
+
+```typescript
+fastify.addHook('preHandler', async (req, reply) => {
+  req.setDecorator<string>('user', 'Bob Dylan')
+})
+```
+
 ## Code Completion In Vanilla JavaScript
 
 Vanilla JavaScript can use the published types to provide code completion (e.g.

package/eslint.config.js

@@ -4,7 +4,7 @@ const neostandard = require('neostandard')
 module.exports = [
   ...neostandard({
     ignores: [
-      'lib/configValidator.js',
+      'lib/config-validator.js',
       'lib/error-serializer.js',
       'test/same-shape.test.js',
       'test/types/import.js'
@@ -13,7 +13,23 @@ module.exports = [
   }),
   {
     rules: {
-      'comma-dangle': ['error', 'never']
+      'comma-dangle': ['error', 'never'],
+      'max-len': ['error', {
+        code: 120,
+        tabWidth: 2,
+        ignoreUrls: true,
+        ignoreStrings: true,
+        ignoreTemplateLiterals: true,
+        ignoreRegExpLiterals: true,
+        ignoreComments: true,
+        ignoreTrailingComments: true
+      }]
+    }
+  },
+  {
+    files: ['**/*.d.ts'],
+    rules: {
+      'max-len': 'off'
     }
   }
 ]

package/fastify.d.ts

@@ -29,7 +29,7 @@ import { FastifyReply } from './types/reply'
 import { FastifyRequest, RequestGenericInterface } from './types/request'
 import { RouteGenericInterface, RouteHandler, RouteHandlerMethod, RouteOptions, RouteShorthandMethod, RouteShorthandOptions, RouteShorthandOptionsWithHandler } from './types/route'
 import { FastifySchema, FastifySchemaValidationError, FastifySchemaCompiler, FastifySerializerCompiler, SchemaErrorDataVar, SchemaErrorFormatter } from './types/schema'
-import { FastifyServerFactory, FastifyServerFactoryHandler } from './types/serverFactory'
+import { FastifyServerFactory, FastifyServerFactoryHandler } from './types/server-factory'
 import { FastifyTypeProvider, FastifyTypeProviderDefault, SafePromiseLike } from './types/type-provider'
 import { ContextConfigDefault, HTTPMethods, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerBase, RawServerDefault, RequestBodyDefault, RequestHeadersDefault, RequestParamsDefault, RequestQuerystringDefault } from './types/utils'