fastify 5.1.0 → 5.2.0

package/docs/Reference/Errors.md

@@ -178,13 +178,13 @@ When utilizing Fastify's custom error handling through [`setErrorHandler`](./Ser
 you should be aware of how errors are propagated between custom and default
 error handlers.
 
-If a plugin's error handler re-throws an error, and the error is not an 
+If a plugin's error handler re-throws an error, and the error is not an
 instance of [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
 (as seen in the `/bad` route in the following example), it will not propagate
 to the parent context error handler. Instead, it will be caught by the default
 error handler.
 
-To ensure consistent error handling, it is recommended to throw instances of 
+To ensure consistent error handling, it is recommended to throw instances of
 `Error`. For instance, in the following example, replacing `throw 'foo'` with
 `throw new Error('foo')` in the `/bad` route ensures that errors propagate through
 the custom error handling chain as intended. This practice helps avoid potential

package/docs/Reference/Hooks.md

@@ -107,7 +107,7 @@ 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.
 
-**Notice:** The size of the returned stream is checked to not exceed the limit 
+**Notice:** The size of the returned stream is checked to not exceed the limit
 set in [`bodyLimit`](./Server.md#bodylimit) option.
 
 ### preValidation
@@ -256,8 +256,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 
-inside the `onResponse` hook. In this case use `try - catch` to log errors. 
+**Note:** setting `disableRequestLogging` to `true` will disable any error log
+inside the `onResponse` hook. In this case use `try - catch` to log errors.
 
 ### onTimeout
 
@@ -428,8 +428,8 @@ fastify.addHook('onReady', async function () {
 
 ### onListen
 
-Triggered when the server starts listening for requests. The hooks run one 
-after another. If a hook function causes an error, it is logged and 
+Triggered when the server starts listening for requests. The hooks run one
+after another. If a hook function causes an error, it is logged and
 ignored, allowing the queue of hooks to continue. Hook functions accept one
 argument: a callback, `done`, to be invoked after the hook function is
 complete. Hook functions are invoked with `this` bound to the associated
@@ -451,7 +451,7 @@ fastify.addHook('onListen', async function () {
 })
 ```
 
-> **Note**  
+> **Note**
 > This hook will not run when the server is started using `fastify.inject()` or `fastify.ready()`
 
 ### onClose
@@ -462,7 +462,7 @@ 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.
 
-The hook function takes the Fastify instance as a first argument, 
+The hook function takes the Fastify instance as a first argument,
 and a `done` callback for synchronous hook functions.
 ```js
 // callback style

package/docs/Reference/LTS.md

@@ -48,6 +48,12 @@ A "month" is defined as 30 consecutive days.
 > dependency as `"fastify": "~3.15.x"`. This will leave your application
 > vulnerable, so please use with caution.
 
+### Security Support Beyond LTS
+
+Fastify's partner, HeroDevs, provides commercial security support through the
+OpenJS Ecosystem Sustainability Program for versions of Fastify that are EOL.
+For more information, see their [Never Ending Support][hd-link] service.
+
 ### Schedule
 
 `<a id="lts-schedule"></a>`
@@ -81,3 +87,5 @@ Using [yarn](https://yarnpkg.com/) might require passing the `--ignore-engines`
 flag.
 
 [semver]: https://semver.org/
+
+[hd-link]: https://www.herodevs.com/support/fastify-nes?utm_source=fastify&utm_medium=link&utm_campaign=eol_support_fastify

package/docs/Reference/Logging.md

@@ -204,15 +204,16 @@ on serializers for more information.
 *Any logger other than Pino will ignore this option.*
 
 You can also supply your own logger instance. Instead of passing configuration
-options, pass the instance. The logger you supply must conform to the Pino
-interface; that is, it must have the following methods: `info`, `error`,
-`debug`, `fatal`, `warn`, `trace`, `silent`, `child` and a string property `level`.
+options, pass the instance as `loggerInstance`. The logger you supply must
+conform to the Pino interface; that is, it must have the following methods:
+`info`, `error`, `debug`, `fatal`, `warn`, `trace`, `silent`, `child` and a
+string property `level`.
 
 Example:
 
 ```js
 const log = require('pino')({ level: 'info' })
-const fastify = require('fastify')({ logger: log })
+const fastify = require('fastify')({ loggerInstance: log })
 
 log.info('does not have request information')
 

package/docs/Reference/Reply.md

@@ -11,9 +11,9 @@
   - [.headers(object)](#headersobject)
   - [.getHeader(key)](#getheaderkey)
   - [.getHeaders()](#getheaders)
-    - [set-cookie](#set-cookie)
   - [.removeHeader(key)](#removeheaderkey)
   - [.hasHeader(key)](#hasheaderkey)
+  - [.writeEarlyHints(hints, callback)](#writeearlyhintshints-callback)
   - [.trailer(key, function)](#trailerkey-function)
   - [.hasTrailer(key)](#hastrailerkey)
   - [.removeTrailer(key)](#removetrailerkey)
@@ -32,8 +32,9 @@
     - [Strings](#strings)
     - [Streams](#streams)
     - [Buffers](#buffers)
-    - [ReadableStream](#send-readablestream)
-    - [Response](#send-response)
+    - [TypedArrays](#typedarrays)
+    - [ReadableStream](#readablestream)
+    - [Response](#response)
     - [Errors](#errors)
     - [Type of the final payload](#type-of-the-final-payload)
     - [Async-Await and Promises](#async-await-and-promises)
@@ -71,14 +72,14 @@ since the request was received by Fastify.
   serialized payload.
 - `.getSerializationFunction(schema | httpStatus, [contentType])` - Returns the serialization
   function for the specified schema or http status, if any of either are set.
-- `.compileSerializationSchema(schema, [httpStatus], [contentType])` - Compiles 
-  the specified schema and returns a serialization function using the default 
-  (or customized) `SerializerCompiler`. The optional `httpStatus` is forwarded 
+- `.compileSerializationSchema(schema, [httpStatus], [contentType])` - Compiles
+  the specified schema and returns a serialization function using the default
+  (or customized) `SerializerCompiler`. The optional `httpStatus` is forwarded
   to the `SerializerCompiler` if provided, default to `undefined`.
-- `.serializeInput(data, schema, [,httpStatus], [contentType])` - Serializes 
+- `.serializeInput(data, schema, [,httpStatus], [contentType])` - Serializes
   the specified data using the specified schema and returns the serialized payload.
-  If the optional `httpStatus`, and `contentType` are provided, the function 
-  will use the serializer function given for that specific content type and 
+  If the optional `httpStatus`, and `contentType` are provided, the function
+  will use the serializer function given for that specific content type and
   HTTP Status Code. Default to `undefined`.
 - `.serializer(function)` - Sets a custom serializer for the payload.
 - `.send(payload)` - Sends the payload to the user, could be a plain text, a
@@ -87,7 +88,7 @@ since the request was received by Fastify.
   already been called.
 - `.hijack()` - interrupt the normal request lifecycle.
 - `.raw` - The
-  [`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
+  [`http.ServerResponse`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_class_http_serverresponse)
   from Node core.
 - `.log` - The logger instance of the incoming request.
 - `.request` - The incoming request.
@@ -157,7 +158,7 @@ Sets a response header. If the value is omitted or undefined, it is coerced to
 > will result in a 500 `TypeError` response.
 
 For more information, see
-[`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_response_setheader_name_value).
+[`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_response_setheader_name_value).
 
 - ### set-cookie
   <a id="set-cookie"></a>
@@ -243,7 +244,7 @@ The hints parameter is an object containing the early hint key-value pairs.
 Example:
 
 ```js
-reply.writeEarlyHints({ 
+reply.writeEarlyHints({
   Link: '</styles.css>; rel=preload; as=style'
 });
 ```
@@ -366,8 +367,8 @@ If the `Content-Type` has a JSON subtype, and the charset parameter is not set,
 ### .getSerializationFunction(schema | httpStatus, [contentType])
 <a id="getserializationfunction"></a>
 
-By calling this function using a provided `schema` or `httpStatus`, 
-and the optional `contentType`, it will return a `serialzation` function 
+By calling this function using a provided `schema` or `httpStatus`,
+and the optional `contentType`, it will return a `serialzation` function
 that can be used to serialize diverse inputs. It returns `undefined` if no
 serialization function was found using either of the provided inputs.
 
@@ -377,12 +378,12 @@ the serialization functions compiled by using `compileSerializationSchema`.
 ```js
 const serialize = reply
                   .getSerializationFunction({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   })
 serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
@@ -411,8 +412,8 @@ The function returned (a.k.a. _serialization function_) returned is compiled
 by using the provided `SerializerCompiler`. Also this is cached by using
 a `WeakMap` for reducing compilation calls.
 
-The optional parameters `httpStatus` and `contentType`, if provided, 
-are forwarded directly to the `SerializerCompiler`, so it can be used 
+The optional parameters `httpStatus` and `contentType`, if provided,
+are forwarded directly to the `SerializerCompiler`, so it can be used
 to compile the serialization function if a custom `SerializerCompiler` is used.
 
 This heavily depends of the `schema#responses` attached to the route, or
@@ -421,12 +422,12 @@ the serialization functions compiled by using `compileSerializationSchema`.
 ```js
 const serialize = reply
                   .compileSerializationSchema({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   })
 serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
@@ -434,12 +435,12 @@ serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
 const serialize = reply
                   .compileSerializationSchema({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   }, 200)
 serialize({ foo: 'bar' }) // '{"foo":"bar"}'
 
@@ -485,7 +486,7 @@ const schema1 = {
 ```
 
 *Not*
-```js 
+```js
 const serialize = reply.compileSerializationSchema(schema1)
 
 // Later on...
@@ -519,25 +520,25 @@ function will be compiled, forwarding the `httpStatus` and `contentType` if prov
 
 ```js
 reply
-  .serializeInput({ foo: 'bar'}, {  
-    type: 'object', 
-    properties: { 
-      foo: { 
-        type: 'string' 
-      } 
-    } 
+  .serializeInput({ foo: 'bar'}, {
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
   }) // '{"foo":"bar"}'
 
 // or
 
 reply
   .serializeInput({ foo: 'bar'}, {
-    type: 'object', 
-    properties: { 
-      foo: { 
-        type: 'string' 
-      } 
-    } 
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
   }, 200) // '{"foo":"bar"}'
 
 // or
@@ -586,7 +587,7 @@ values.
 <a id="raw"></a>
 
 This is the
-[`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
+[`http.ServerResponse`](https://nodejs.org/dist/latest-v20.x/docs/api/http.html#http_class_http_serverresponse)
 from Node core. Whilst you are using the Fastify `Reply` object, the use of
 `Reply.raw` functions is at your own risk as you are skipping all the Fastify
 logic of handling the HTTP response. e.g.:
@@ -712,7 +713,7 @@ fastify.get('/streams', async function (request, reply) {
 If you are sending a buffer and you have not set a `'Content-Type'` header,
 *send* will set it to `'application/octet-stream'`.
 
-As noted above, Buffers are considered to be pre-serialized, so they will be 
+As noted above, Buffers are considered to be pre-serialized, so they will be
 sent unmodified without response validation.
 
 ```js
@@ -743,7 +744,7 @@ fastify.get('/streams', async function (request, reply) {
 `send` manages TypedArray like a Buffer, and sets the `'Content-Type'`
 header to `'application/octet-stream'` if not already set.
 
-As noted above, TypedArray/Buffers are considered to be pre-serialized, so they 
+As noted above, TypedArray/Buffers are considered to be pre-serialized, so they
 will be sent unmodified without response validation.
 
 ```js
@@ -759,7 +760,7 @@ fastify.get('/streams', function (request, reply) {
 <a id="send-readablestream"></a>
 
 `ReadableStream` will be treated as a node stream mentioned above,
-the content is considered to be pre-serialized, so they will be 
+the content is considered to be pre-serialized, so they will be
 sent unmodified without response validation.
 
 ```js
@@ -778,7 +779,7 @@ fastify.get('/streams', function (request, reply) {
 
 `Response` allows to manage the reply payload, status code and
 headers in one place. The payload provided inside `Response` is
-considered to be pre-serialized, so they will be sent unmodified 
+considered to be pre-serialized, so they will be sent unmodified
 without response validation.
 
 Please be aware when using `Response`, the status code and headers

package/docs/Reference/Request.md

@@ -23,20 +23,23 @@ Request is a core Fastify object containing the following fields:
 - `host` - the host of the incoming request (derived from `X-Forwarded-Host`
   header when the [`trustProxy`](./Server.md#factory-trust-proxy) option is
   enabled). For HTTP/2 compatibility it returns `:authority` if no host header
-  exists. When you use `requireHostHeader = false` in the server options, it
-  will fallback as empty when the host header is missing.
-- `hostname` - the host of the incoming request without the port
-- `port` - the port that the server is listening on
+  exists. The host header may return empty string when using
+  `requireHostHeader = false`, not suppied when connected with `HTTP/1.0` or
+  using schema validation that remove the extra headers.
+- `hostname` - the host of the `host` property, it may refers the incoming
+  request hostname
+- `port` - the port of the `host` property, it may refers the port thats
+  the server is listening on
 - `protocol` - the protocol of the incoming request (`https` or `http`)
 - `method` - the method of the incoming request
 - `url` - the URL of the incoming request
-- `originalUrl` - similar to `url`, this allows you to access the 
-  original `url` in case of internal re-routing 
+- `originalUrl` - similar to `url`, this allows you to access the
+  original `url` in case of internal re-routing
 - `is404` - true if request is being handled by 404 handler, false if it is not
 - `socket` - the underlying connection of the incoming request
 - `context` - Deprecated, use `request.routeOptions.config` instead.
 A Fastify internal object. You should not use
-it directly or modify it. It is useful to access one special key:	
+it directly or modify it. 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
@@ -44,15 +47,15 @@ it directly or modify it. It is useful to access one special key:
   - `method` - the http method for the route
   - `url` - the path of the URL to match this route
   - `handler` - the handler for this route
-  - `attachValidation` - attach `validationError` to request 
+  - `attachValidation` - attach `validationError` to request
     (if there is a schema defined)
   - `logLevel` - log level defined for this route
   - `schema` - the JSON schemas definition for this route
   - `version` -  a semver compatible string that defines the version of the endpoint
   - `exposeHeadRoute` - creates a sibling HEAD route for any GET routes
-  - `prefixTrailingSlash` - string used to determine how to handle passing / 
+  - `prefixTrailingSlash` - string used to determine how to handle passing /
     as a route with a prefix.
-- [.getValidationFunction(schema | httpPart)](#getvalidationfunction) - 
+- [.getValidationFunction(schema | httpPart)](#getvalidationfunction) -
   Returns a validation function for the specified schema or http part,
   if any of either are set or cached.
 - [.compileValidationSchema(schema, [httpPart])](#compilevalidationschema) -
@@ -85,6 +88,9 @@ request's headers with the `request.raw.headers` property.
 > Note: For performance reason on `not found` route, you may see that we will
 add an extra property `Symbol('fastify.RequestAcceptVersion')` on the headers.
 
+> Note: When using schema, it may mutate the `request.headers` and
+`request.raw.headers` object. So, you may found the headers becomes empty.
+
 ```js
 fastify.post('/:params', options, function (request, reply) {
   console.log(request.body)
@@ -117,7 +123,7 @@ fastify.post('/:params', options, function (request, reply) {
 ### .getValidationFunction(schema | httpPart)
 <a id="getvalidationfunction"></a>
 
-By calling this function using a provided `schema` or `httpPart`, 
+By calling this function using a provided `schema` or `httpPart`,
 it will return a `validation` function that can be used to
 validate diverse inputs. It returns `undefined` if no
 serialization function was found using either of the provided inputs.
@@ -128,12 +134,12 @@ are assigned to errors
 ```js
 const validate = request
                   .getValidationFunction({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   })
 console.log(validate({ foo: 'bar' })) // true
 console.log(validate.errors) // null
@@ -168,12 +174,12 @@ are assigned to errors
 ```js
 const validate = request
                   .compileValidationSchema({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   })
 console.log(validate({ foo: 'bar' })) // true
 console.log(validate.errors) // null
@@ -182,12 +188,12 @@ console.log(validate.errors) // null
 
 const validate = request
                   .compileValidationSchema({
-                    type: 'object', 
-                    properties: { 
-                      foo: { 
-                        type: 'string' 
-                      } 
-                    } 
+                    type: 'object',
+                    properties: {
+                      foo: {
+                        type: 'string'
+                      }
+                    }
                   }, 200)
 console.log(validate({ hello: 'world' })) // false
 console.log(validate.errors) // validation errors
@@ -217,7 +223,7 @@ const schema1 = {
 ```
 
 *Not*
-```js 
+```js
 const validate = request.compileValidationSchema(schema1)
 
 // Later on...
@@ -252,25 +258,25 @@ function will be compiled, forwarding the `httpPart` if provided.
 
 ```js
 request
-  .validateInput({ foo: 'bar'}, {  
-    type: 'object', 
-    properties: { 
-      foo: { 
-        type: 'string' 
-      } 
-    } 
+  .validateInput({ foo: 'bar'}, {
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
   }) // true
 
 // or
 
 request
   .validateInput({ foo: 'bar'}, {
-    type: 'object', 
-    properties: { 
-      foo: { 
-        type: 'string' 
-      } 
-    } 
+    type: 'object',
+    properties: {
+      foo: {
+        type: 'string'
+      }
+    }
   }, 'body') // true
 
 // or

package/docs/Reference/Routes.md

@@ -93,16 +93,16 @@ fastify.route(options)
 * `childLoggerFactory(logger, binding, opts, rawReq)`: a custom factory function
   that will be called to produce a child logger instance for every request.
   See [`childLoggerFactory`](./Server.md#childloggerfactory) for more info.
-  Overrides the default logger factory, and anything set by 
+  Overrides the default logger factory, and anything set by
   [`setChildLoggerFactory`](./Server.md#setchildloggerfactory), for requests to
-  the route. To access the default factory, you can access 
+  the route. To access the default factory, you can access
   `instance.childLoggerFactory`. Note that this will point to Fastify's default
   `childLoggerFactory` only if a plugin hasn't overridden it already.
 * `validatorCompiler({ schema, method, url, httpPart })`: function that builds
   schemas for request validations. See the [Validation and
   Serialization](./Validation-and-Serialization.md#schema-validator)
   documentation.
-* `serializerCompiler({ { schema, method, url, httpStatus, contentType } })`: 
+* `serializerCompiler({ { schema, method, url, httpStatus, contentType } })`:
   function that builds schemas for response serialization. See the [Validation and
   Serialization](./Validation-and-Serialization.md#schema-serializer)
   documentation.
@@ -121,8 +121,8 @@ fastify.route(options)
 * `version`: a [semver](https://semver.org/) compatible string that defined the
   version of the endpoint. [Example](#version-constraints).
 * `constraints`: defines route restrictions based on request properties or
-  values, enabling customized matching using 
-  [find-my-way](https://github.com/delvedor/find-my-way) constraints. Includes 
+  values, enabling customized matching using
+  [find-my-way](https://github.com/delvedor/find-my-way) constraints. Includes
   built-in `version` and `host` constraints, with support for custom constraint
   strategies.
 * `prefixTrailingSlash`: string used to determine how to handle passing `/` as a
@@ -796,10 +796,10 @@ const secret = {
 > inside the callback. If the error is not preventable, it is recommended to provide
 > a custom `frameworkErrors` handler to deal with it. Otherwise, you route selection
 > may break or expose sensitive information to attackers.
-> 
+>
 > ```js
 > const Fastify = require('fastify')
-> 
+>
 > const fastify = Fastify({
 >   frameworkErrors: function (err, res, res) {
 >     if (err instanceof Fastify.errorCodes.FST_ERR_ASYNC_CONSTRAINT) {