fastify 6.0.0-alpha.4 → 6.0.0-alpha.6

package/docs/Reference/Request.md

@@ -1,92 +1,71 @@
 <h1 align="center">Fastify</h1>
 
 ## Request
+- [Introduction](#introduction)
+- [Request](#request-object)
+  - [Properties](#properties)
+    - [.body](#body)
+    - [.query](#query)
+    - [.params](#params)
+    - [.headers](#headers)
+    - [.id](#id)
+    - [.log](#log)
+    - [.method](#method)
+    - [.url](#url)
+    - [.routeOptions](#routeoptions)
+    - [.server](#server)
+    - [.raw](#raw)
+    - [.ip](#ip)
+    - [.ips](#ips)
+    - [.host](#host)
+    - [.hostname](#hostname)
+    - [.port](#port)
+    - [.protocol](#protocol)
+    - [.originalUrl](#originalurl)
+    - [.mediaType](#mediatype)
+    - [.signal](#signal)
+    - [.socket](#socket)
+    - [.is404](#is404)
+    - [.validationError](#validationerror)
+  - [Methods](#methods)
+    - [.getDecorator(name)](#getdecorator)
+    - [.setDecorator(name, value)](#setdecorator)
+    - [.getValidationFunction(schema | httpPart)](#getvalidationfunction)
+    - [.compileValidationSchema(schema, [httpPart])](#compilevalidationschema)
+    - [.validateInput(data, [schema | httpPart], [httpPart])](#validate)
+
+### Introduction
+<a id="introduction"></a>
+
 The first parameter of the handler function is `Request`.
 
 Request is a core Fastify object containing the following fields:
-- `query` - The parsed querystring, its format is specified by
-  [`querystringParser`](./Server.md#querystringparser).
-- `body` - The request payload, see [Content-Type Parser](./ContentTypeParser.md)
-  for details on what request payloads Fastify natively parses and how to support
-  other content types.
-- `params` - The params matching the URL. Values are percent-decoded
-  (for example `%20` becomes a space, and `%2f` becomes `/`). Decoded
-  values may contain `.`, `..`, `/`, or other characters; treat them as
-  untrusted input. See the security note below and
-  [Routes - Url building](./Routes.md#url-building).
+- `query` - The parsed querystring.
+- `body` - The request payload.
+- `params` - The params matching the URL.
 - [`headers`](#headers) - The headers getter and setter.
 - `raw` - The incoming HTTP request from Node core.
-- `server` - The Fastify server instance, scoped to the current
-  [encapsulation context](./Encapsulation.md).
+- `server` - The Fastify server instance.
 - `id` - The request ID.
 - `log` - The logger instance of the incoming request.
-- `ip` - The IP address of the incoming request. This value is taken from
-  `socket.remoteAddress` (or from `X-Forwarded-For` when
-  [`trustProxy`](./Server.md#factory-trust-proxy) is enabled).
-- `ips` - An array of IP addresses, ordered from closest to furthest, from
-  `X-Forwarded-For` (only when
-  [`trustProxy`](./Server.md#factory-trust-proxy) is enabled).
-- `host` - The host of the incoming request (derived from `X-Forwarded-Host`
-  when [`trustProxy`](./Server.md#factory-trust-proxy) is 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.
+- `ip` - The IP address of the incoming request.
+- `ips` - An array of IP addresses from `X-Forwarded-For`.
+- `host` - The host of the incoming request.
 - `hostname` - The hostname parsed from `request.host`.
-- `port` - The port parsed from `request.host`, which may refer to the port the
-  server is listening on.
-- `protocol` - The protocol of the incoming request (`https` or `http`). This
-  value comes from `socket.encrypted` (or `X-Forwarded-Proto` when
-  [`trustProxy`](./Server.md#factory-trust-proxy) is enabled).
-
-> ⚠️ Security:
-> `request.params`, `request.query`, `request.headers`, and `request.body`
-> are untrusted network input. Route parameter values are percent-decoded
-> before your handler runs, so a segment like `..%2ffile` becomes `../file`
-> in `request.params`. Do not use parameter values as filesystem paths,
-> template names, or redirect targets without validating or containing
-> them. Prefer [`@fastify/static`](https://github.com/fastify/fastify-static)
-> (or `reply.sendFile`) when serving files from a root directory.
->
-> `request.ip`, `request.ips`, `request.host`, `request.hostname`,
-> `request.port`, and `request.protocol` come from request metadata
-> (socket and/or forwarding headers) and should also be treated as
-> untrusted input. Fastify does not perform security validation for
-> business logic. If these values are used in security-sensitive decisions,
-> they must be validated explicitly (for example: trusted proxy
-> configuration, allow-lists, strict parsing, and normalization).
-
+- `port` - The port parsed from `request.host`.
+- `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`, allows access to the original `url` in
-  case of internal re-routing.
-- `mediaType` - The media type extracted from `Content-Type` header. When `Content-Type`
-  header is missing, it will return `undefined`.
+- `originalUrl` - The original URL of the incoming request.
+- `mediaType` - The media type extracted from `Content-Type` header.
 - `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.
+- `signal` - An `AbortSignal` that aborts on handler timeout or client
+  disconnect.
 - `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.
-  - `handler` - The handler for this route.
-  - `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 `/`
-    as a route with a prefix.
+- `validationError` - The validation error, when `attachValidation` is set.
+- `getDecorator(name)` - Returns the value of a request decorator.
+- `setDecorator(name, value)` - Sets the value of a request decorator.
 - [.getValidationFunction(schema | httpPart)](#getvalidationfunction) -
   Returns a validation function for the specified schema or HTTP part, if
   set or cached.
@@ -99,29 +78,6 @@ Request is a core Fastify object containing the following fields:
   `true` if the input is valid, `false` otherwise. If `httpPart` is provided,
   the function uses the validator for that HTTP part. Defaults to `null`.
 
-### Headers
-
-The `request.headers` is a getter that returns an object with the headers of the
-incoming request. Set custom headers as follows:
-
-```js
-request.headers = {
-  'foo': 'bar',
-  'baz': 'qux'
-}
-```
-
-This operation adds new values to the request headers, accessible via
-`request.headers.bar`. Standard request headers remain accessible via
-`request.raw.headers`.
-
-For performance reasons, `Symbol('fastify.RequestAcceptVersion')` may be added
-to headers on `not found` routes.
-
-> ℹ️ Note:
-> Schema validation may mutate the `request.headers` and
-> `request.raw.headers` objects, causing the headers to become empty.
-
 ```js
 fastify.post('/:params', options, function (request, reply) {
   console.log(request.body)
@@ -151,12 +107,260 @@ fastify.post('/:params', options, function (request, reply) {
   request.log.info('some info')
 })
 ```
-### .getValidationFunction(schema | httpPart)
+
+> ⚠️ Security:
+> `request.params`, `request.query`, `request.headers`, and `request.body`
+> are untrusted network input. Route parameter values are percent-decoded
+> before your handler runs, so a segment like `..%2ffile` becomes `../file`
+> in `request.params`. Do not use parameter values as filesystem paths,
+> template names, or redirect targets without validating or containing
+> them. Prefer [`@fastify/static`](https://github.com/fastify/fastify-static)
+> (or `reply.sendFile`) when serving files from a root directory.
+>
+> `request.ip`, `request.ips`, `request.host`, `request.hostname`,
+> `request.port`, and `request.protocol` come from request metadata
+> (socket and/or forwarding headers) and should also be treated as
+> untrusted input. Fastify does not perform security validation for
+> business logic. If these values are used in security-sensitive decisions,
+> they must be validated explicitly (for example: trusted proxy
+> configuration, allow-lists, strict parsing, and normalization).
+
+### Request
+<a id="request-object"></a>
+
+#### Properties
+<a id="properties"></a>
+
+##### .body
+
+The request payload. See [Content-Type Parser](./ContentTypeParser.md) for
+details on what request payloads Fastify natively parses and how to support
+other content types.
+
+##### .query
+
+The parsed querystring. Its format is specified by
+[`querystringParser`](./Server.md#querystringparser).
+
+##### .params
+
+The params matching the URL. Values are percent-decoded (for example `%20`
+becomes a space, and `%2f` becomes `/`). Decoded values may contain `.`, `..`,
+`/`, or other characters; treat them as untrusted input. See the
+[security note](#introduction) and
+[Routes - Url building](./Routes.md#url-building).
+
+##### .headers
+
+The `request.headers` is a getter that returns an object with the headers of the
+incoming request. Set custom headers as follows:
+
+```js
+request.headers = {
+  'foo': 'bar',
+  'baz': 'qux'
+}
+```
+
+This operation adds new values to the request headers, accessible via
+`request.headers.foo`. Standard request headers remain accessible via
+`request.raw.headers`.
+
+For performance reasons, `Symbol('fastify.RequestAcceptVersion')` may be added
+to headers on `not found` routes.
+
+> ℹ️ Note:
+> Schema validation may mutate the `request.headers` and
+> `request.raw.headers` objects, causing the headers to become empty.
+
+> ℹ️ Note:
+> The setter is additive, so it cannot be used to *remove* a header, and a
+> `headers` schema validator's synchronous `{ value }` result is applied through
+> this same setter. `request.headers` is therefore the incoming request's
+> headers (plus any additive values), not a sanitized or authoritative view. If
+> your application needs an allow-listed header subset, build and consume it
+> explicitly from the validated data or from `request.raw.headers`.
+
+##### .id
+
+The request ID. It is generated by [`genReqId`](./Server.md#genreqid), or read
+from the header configured with [`requestIdHeader`](./Server.md#requestidheader)
+when the incoming request includes it.
+
+##### .log
+
+The logger instance of the incoming request. By default, it is a child logger of
+the server logger that adds the request ID (`reqId`) to every log line. See
+[`childLoggerFactory`](./Server.md#childLoggerFactory) to customize it.
+
+##### .method
+
+The method of the incoming request.
+
+##### .url
+
+The URL of the incoming request.
+
+##### .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.
+- `handler` - The handler for this route.
+- `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 `/`
+  as a route with a prefix.
+
+##### .server
+
+The Fastify server instance, scoped to the current
+[encapsulation context](./Encapsulation.md).
+
+##### .raw
+
+The incoming HTTP request from Node core.
+
+##### .ip
+
+The IP address of the incoming request. This value is taken from
+`socket.remoteAddress` (or from `X-Forwarded-For` when
+[`trustProxy`](./Server.md#factory-trust-proxy) is enabled). It is `undefined`
+when the underlying socket is not available.
+
+##### .ips
+
+An array of IP addresses, ordered from closest to furthest, from
+`X-Forwarded-For` (only when [`trustProxy`](./Server.md#factory-trust-proxy) is
+enabled). It is `undefined` when `trustProxy` is not enabled.
+
+##### .host
+
+The host of the incoming request (derived from `X-Forwarded-Host` when
+[`trustProxy`](./Server.md#factory-trust-proxy) is 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.
+
+##### .hostname
+
+The hostname parsed from `request.host`. For IPv6 hosts, the brackets are kept
+(for example, `[::1]`).
+
+##### .port
+
+The port parsed from `request.host`, which may refer to the port the server is
+listening on. It is `null` when the host does not include a port.
+
+##### .protocol
+
+The protocol of the incoming request (`https` or `http`). This value comes from
+`socket.encrypted` (or `X-Forwarded-Proto` when
+[`trustProxy`](./Server.md#factory-trust-proxy) is enabled). It is `undefined`
+when the underlying socket is not available.
+
+##### .originalUrl
+
+Similar to `url`, allows access to the original `url` in case of internal
+re-routing.
+
+##### .mediaType
+
+The media type extracted from `Content-Type` header. When `Content-Type` header
+is missing, it will return `undefined`.
+
+##### .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.
+
+##### .socket
+
+The underlying connection of the incoming request.
+
+##### .is404
+
+`true` if request is being handled by 404 handler, `false` otherwise.
+
+##### .validationError
+
+The validation error of the request. It is set only when the route has the
+[`attachValidation`](./Routes.md#routes-options) option enabled and the
+validation fails; otherwise it is `undefined`. In that case, Fastify calls the
+handler instead of replying with a `400` error. See
+[Validation and Serialization](./Validation-and-Serialization.md#error-handling)
+for the properties of the error object.
+
+```js
+fastify.post('/', { schema, attachValidation: true }, function (request, reply) {
+  if (request.validationError) {
+    // `request.validationError.validationContext` is the failed part,
+    // for example `body`
+    reply.code(422).send(request.validationError)
+    return
+  }
+  reply.send({ hello: 'world' })
+})
+```
+
+#### Methods
+<a id="methods"></a>
+
+##### .getDecorator(name)
+<a id="getdecorator"></a>
+
+Returns the value of a request decorator declared with
+[`decorateRequest`](./Decorators.md#decoraterequestname-value-dependencies).
+If the decorator is a function, it is returned bound to the request. It throws
+an `FST_ERR_DEC_UNDECLARED` error if the decorator has not been declared. See
+[`getDecorator`](./Decorators.md#getdecoratorname) for more details.
+
+```js
+fastify.decorateRequest('user', null)
+
+fastify.get('/', function (request, reply) {
+  const user = request.getDecorator('user')
+  reply.send({ user })
+})
+```
+
+##### .setDecorator(name, value)
+<a id="setdecorator"></a>
+
+Sets the value of a request decorator declared with
+[`decorateRequest`](./Decorators.md#decoraterequestname-value-dependencies).
+It throws an `FST_ERR_DEC_UNDECLARED` error if the decorator has not been
+declared. See [`setDecorator`](./Decorators.md#setdecoratorname-value) for more
+details.
+
+```js
+fastify.decorateRequest('user', null)
+
+fastify.addHook('preHandler', async (request) => {
+  request.setDecorator('user', 'Bob Dylan')
+})
+```
+
+##### .getValidationFunction(schema | httpPart)
 <a id="getvalidationfunction"></a>
 
 By calling this function with a provided `schema` or `httpPart`, it returns a
 `validation` function to validate diverse inputs. It returns `undefined` if no
-serialization function is found using the provided inputs.
+validation function is found using the provided inputs.
 
 This function has an `errors` property. Errors encountered during the last
 validation are assigned to `errors`.
@@ -182,10 +386,10 @@ console.log(validate({ foo: 0.5 })) // false
 console.log(validate.errors) // validation errors
 ```
 
-See [.compileValidationSchema(schema, [httpStatus])](#compileValidationSchema)
+See [.compileValidationSchema(schema, [httpPart])](#compilevalidationschema)
 for more information on compiling validation schemas.
 
-### .compileValidationSchema(schema, [httpPart])
+##### .compileValidationSchema(schema, [httpPart])
 <a id="compilevalidationschema"></a>
 
 This function compiles a validation schema and returns a function to validate data.
@@ -223,8 +427,8 @@ const validate = request
                         type: 'string'
                       }
                     }
-                  }, 200)
-console.log(validate({ hello: 'world' })) // false
+                  }, 'body')
+console.log(validate({ foo: {} })) // false
 console.log(validate.errors) // validation errors
 ```
 
@@ -272,7 +476,7 @@ const newValidate = request.compileValidationSchema(newSchema)
 console.log(newValidate === validate) // false
 ```
 
-### .validateInput(data, [schema | httpPart], [httpPart])
+##### .validateInput(data, [schema | httpPart], [httpPart])
 <a id="validate"></a>
 
 This function validates the input based on the provided schema or HTTP part. If
@@ -310,5 +514,5 @@ request
   .validateInput({ hello: 'world'}, 'query') // false
 ```
 
-See [.compileValidationSchema(schema, [httpStatus])](#compileValidationSchema)
+See [.compileValidationSchema(schema, [httpPart])](#compilevalidationschema)
 for more information on compiling validation schemas.

package/docs/Reference/Routes.md

@@ -32,7 +32,7 @@ fastify.route(options)
 <a id="options"></a>
 
 * `method`: currently it supports `GET`, `HEAD`, `TRACE`, `DELETE`,
-  `OPTIONS`, `PATCH`, `PUT` and `POST`. To accept more methods,
+  `OPTIONS`, `PATCH`, `PUT`, `POST` and `QUERY`. To accept more methods,
   the [`addHttpMethod`](./Server.md#addHttpMethod) must be used.
   It could also be an array of methods.
 * `url`: the path of the URL to match this route (alias: `path`).
@@ -41,7 +41,7 @@ fastify.route(options)
   [here](./Validation-and-Serialization.md) for more info.
 
   * `body`: validates the body of the request if it is a POST, PUT, PATCH,
-    TRACE, SEARCH, PROPFIND, PROPPATCH or LOCK method.
+    TRACE, SEARCH, PROPFIND, PROPPATCH, LOCK or QUERY method.
   * `querystring` or `query`: validates the querystring. This can be a complete
     JSON Schema object, with the property `type` of `object` and `properties`
     object of parameters, or simply the values of what would be contained in the
@@ -198,6 +198,10 @@ The above route declaration is more *Hapi*-like, but if you prefer an
 
 `fastify.patch(path, [options], handler)`
 
+`fastify.query(path, [options], handler)`
+
+> The `QUERY` method (RFC 10008) requires a `Content-Type` header.
+
 Example:
 ```js
 const opts = {

package/docs/Reference/Server.md

@@ -41,6 +41,7 @@ describes the properties available in that options object.
     - [`allowUnsafeRegex`](#allowunsaferegex)
     - [`buildPrettyMeta`](#buildprettymeta)
     - [`caseSensitive`](#casesensitive)
+    - [`compile`](#compile)
     - [`constraints`](#constraints)
     - [`defaultRoute`](#defaultroute)
     - [`ignoreDuplicateSlashes`](#ignoreduplicateslashes)
@@ -213,7 +214,7 @@ ignored.
 
 Defines the maximum number of milliseconds for receiving the entire request from
 the client. See [`server.requestTimeout`
-property](https://nodejs.org/dist/latest/docs/api/http.html#servertimeout)
+property](https://nodejs.org/dist/latest/docs/api/http.html#serverrequesttimeout)
 to understand the effect of this option.
 
 When `serverFactory` option is specified, this option is ignored.
@@ -920,6 +921,36 @@ fastify.get('/user/:username', (request, reply) => {
 })
 ```
 
+### `compile`
+<a id="compile"></a>
+
++ Default: `false`
+
+When `true`, Fastify calls the
+[`compile()`](https://github.com/delvedor/find-my-way#compiler-mode) method of
+`find-my-way` once all the routes are registered, right before the
+[`onReady`](./Hooks.md#onready) hooks run. This applies to both the main
+router and the router used for [not found handlers](#set-not-found-handler).
+Each HTTP method's routing tree is
+turned into generated JavaScript instead of being walked for every request,
+which makes route lookups faster. Matching semantics are the same as with the
+default tree walk.
+
+```js
+const fastify = require('fastify')({
+  routerOptions: {
+    compile: true
+  }
+})
+```
+
+Keep in mind that:
+
++ the compiled matcher works on the raw request URL; URLs containing
+  percent-encoded characters fall back to the decoded path and are not faster;
++ every route generates its own code, so applications with thousands of routes
+  produce a large amount of JavaScript, which needs to warm up per route.
+
 ### `constraints`
 <a id="constraints"></a>
 
@@ -1044,9 +1075,14 @@ multi) routes by using `maxParamLength` option; the default value is 100
 characters. If the maximum length limit is reached, the not found route will
 be invoked.
 
-This can be useful especially if you have a regex-based route, protecting you
-against [ReDoS
-attacks](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS).
+For regex routes, the limit applies to the values captured by the regular
+expression, and it is checked only after the expression has run against the
+whole path segment. `maxParamLength` therefore does not limit the input a route
+regex processes and does not protect against [ReDoS
+attacks](https://community.owasp.org/attacks/Regular_expression_Denial_of_Service_-_ReDoS).
+To guard against ReDoS, keep [`allowUnsafeRegex`](#allow-unsafe-regex)
+disabled so that potentially catastrophic regular expressions are rejected when
+the route is registered.
 
 
 ### `onBadUrl`
@@ -2382,6 +2418,7 @@ The properties that can currently be exposed are:
   - allowUnsafeRegex
   - buildPrettyMeta
   - caseSensitive
+  - compile
   - constraints
   - defaultRoute
   - ignoreDuplicateSlashes

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

@@ -167,6 +167,22 @@ parameters at the top level.
 > ℹ For using the latest Ajv (v8), refer to the
 > [`schemaController`](./Server.md#schema-controller) section.
 
+##### Header name case
+
+Node.js exposes request header names in lowercase. Fastify normalizes header
+names in a `headers` schema to lowercase before compilation, so assertions
+written in the canonical header-name case still match the request, for example
+`required: ['X-Api-Key']`, `dependencies`, and a `propertyNames` deny-list that
+uses `enum` or `const`.
+
+Regular-expression constraints on header names are the exception. A
+`patternProperties` key and a `propertyNames` `pattern` are regular expressions
+matched against the already-lowercased header names, and Fastify cannot safely
+rewrite a regular expression. Author them to match lowercase (for example
+`^x-debug-.*$`, not `^X-Debug-.*$`) or make them case-insensitive. A pattern
+written in canonical case will not match, and the assertion it guards will not
+apply.
+
 Example:
 ```js
 const bodyJsonSchema = {
@@ -639,6 +655,23 @@ an application.
 > failure by rejecting (throwing), and it cannot coerce the request part through
 > a resolved `value`.
 
+##### `headers` and the `{ value }` result
+
+For the `headers` part specifically, the synchronous success `value` is applied
+through the additive [`request.headers`](./Request.md#headers) setter. That
+setter *adds or overrides* headers on top of the raw request headers; it does
+**not** replace them. Raw request headers remain separately available as
+`request.raw.headers`, and any incoming header that is not present in the
+returned `value` is still visible on `request.headers`.
+
+Consequently, a synchronous custom `headers` validator cannot remove a header by
+simply omitting it from `value`. The same applies to the default Ajv validator:
+`request.headers` is the incoming request's headers (plus any additive values)
+and is not a sanitized, authoritative view. If your application needs a
+sanitized or allow-listed header view — for example to drive an authorization
+decision — build and consume that view explicitly from the validated data rather
+than re-reading `request.headers`.
+
 ##### .statusCode property
 
 All validation errors have a `.statusCode` property set to `400`, ensuring the
@@ -766,7 +799,7 @@ For example:
 const schema = {
   response: {
     200: {
-      description: 'Response schema that support different content types'
+      description: 'Response schema that support different content types',
       content: {
         'application/json': {
           schema: {
@@ -818,6 +851,15 @@ const schema = {
 fastify.post('/url', { schema }, handler)
 ```
 
+> When the route declares a per-content-type response schema through `content`,
+> Fastify matches the response `Content-Type` against the declared keys and falls
+> back to `*/*` (if present). If the response `Content-Type` is not declared and
+> there is no `*/*` key, serialization **fails closed**: Fastify throws
+> `FST_ERR_MISSING_CONTENTTYPE_SERIALIZATION_FN` and replies with a `500` error,
+> instead of silently serializing the payload with `JSON.stringify` (which would
+> bypass the response schema). Every `Content-Type` a route may respond with must
+> be declared, or the route must define a `*/*` catch-all.
+
 #### Serializer Compiler
 <a id="schema-serializer"></a>
 
@@ -898,6 +940,11 @@ message has to be rebuilt from the raw validation result:
 - `validationContext` is the part of the request that failed validation
   (`body`, `params`, `querystring` or `headers`).
 - `code` is `FST_ERR_VALIDATION` and `statusCode` is `400`.
+- When the validator reports a list of errors (as Ajv does) and the default
+  [`schemaErrorFormatter`](#schemaerrorformatter) is used, the error is an
+  instance of [`FST_ERR_VALIDATION`](./Errors.md#fst_err_validation) without a
+  [stack trace](./Errors.md#errors-in-input-data). Errors returned by the
+  validator itself, or by a custom formatter, are used as they are.
 
 ```js
 const fastify = Fastify()

package/docs/Reference/Warnings.md

@@ -10,6 +10,7 @@
   - [Fastify Security Codes](#fastify-security-codes)
     - [FSTSEC001](#FSTSEC001)
     - [FSTSEC002](#FSTSEC002)
+    - [FSTSEC003](#FSTSEC003)
   - [Fastify Deprecation Codes](#fastify-deprecation-codes)
 
 ## Warnings
@@ -51,6 +52,7 @@ Disabling warnings is not recommended and may cause unexpected behavior.
 | ---- | ----------- | ------------ | ---------- |
 | <a id="FSTSEC001">FSTSEC001</a> | A `RegExp` Content-Type is used that may be vulnerable to a CORS bypass, because it does not anchor the essence MIME type. | Start the `RegExp` with `^` or include `;?` so the essence MIME type is detected correctly. | [#4450](https://github.com/fastify/fastify/pull/4450) |
 | <a id="FSTSEC002">FSTSEC002</a> | A headers schema references an external `$ref` (a schema registered with `addSchema`) that is not reached by header case normalization. Header names in the referenced schema keep their original case and do not match the lowercased request headers, so case-insensitive assertions such as `required` and `dependencies` may not apply. | Inline the header schema instead of referencing it with an external `$ref`. | - |
+| <a id="FSTSEC003">FSTSEC003</a> | A headers schema uses a `$ref` inside `propertyNames` that is not reached by header case normalization. Header names held in the referenced schema keep their original case and do not match the lowercased request headers, so a case-insensitive deny-list or allow-list on header names may not apply. | Inline the `propertyNames` constraint instead of referencing it with a `$ref`. | - |
 
 ### Fastify Deprecation Codes