fastify 5.3.2 → 5.4.0

package/docs/Reference/Server.md

@@ -45,6 +45,7 @@ describes the properties available in that options object.
   - [`clientErrorHandler`](#clienterrorhandler)
   - [`rewriteUrl`](#rewriteurl)
   - [`useSemicolonDelimiter`](#usesemicolondelimiter)
+  - [`allowErrorHandlerOverride`](#allowerrorhandleroverride)
 - [Instance](#instance)
   - [Server Methods](#server-methods)
     - [server](#server)
@@ -193,7 +194,7 @@ to understand the effect of this option. This option only applies when HTTP/1.1
 is in use. Also, when `serverFactory` option is specified, this option is
 ignored.
 
-> 🛈 Note:
+> ℹ️ Note:
 >  At the time of writing, only node >= v16.10.0 supports this option.
 
 ### `requestTimeout`
@@ -211,7 +212,7 @@ It must be set to a non-zero value (e.g. 120 seconds) to protect against potenti
 Denial-of-Service attacks in case the server is deployed without a reverse proxy
 in front.
 
-> 🛈 Note:
+> ℹ️ Note:
 >  At the time of writing, only node >= v14.11.0 supports this option
 
 ### `ignoreTrailingSlash`
@@ -529,7 +530,7 @@ Especially in distributed systems, you may want to override the default ID
 generation behavior as shown below. For generating `UUID`s you may want to check
 out [hyperid](https://github.com/mcollina/hyperid).
 
-> 🛈 Note:
+> ℹ️ Note:
 > `genReqId` will be not called if the header set in
 > <code>[requestIdHeader](#requestidheader)</code> is available (defaults to
 > 'request-id').
@@ -581,7 +582,7 @@ fastify.get('/', (request, reply) => {
 })
 ```
 
-> 🛈 Note:
+> ℹ️ Note:
 > If a request contains multiple `x-forwarded-host` or `x-forwarded-proto`
 > headers, it is only the last one that is used to derive `request.hostname`
 > and `request.protocol`.
@@ -736,7 +737,7 @@ Fastify provides default error handlers for the most common use cases. It is
 possible to override one or more of those handlers with custom code using this
 option.
 
-> 🛈 Note:
+> ℹ️ Note:
 > Only `FST_ERR_BAD_URL` and `FST_ERR_ASYNC_CONSTRAINT` are implemented at present.
 
 ```js
@@ -789,7 +790,7 @@ function defaultClientErrorHandler (err, socket) {
 }
 ```
 
-> 🛈 Note:
+> ℹ️ Note:
 > `clientErrorHandler` operates with raw sockets. The handler is expected to
 > return a properly formed HTTP response that includes a status line, HTTP headers
 > and a message body. Before attempting to write the socket, the handler should
@@ -866,6 +867,29 @@ fastify.get('/dev', async (request, reply) => {
 })
 ```
 
+### `allowErrorHandlerOverride`
+<a id="allow-error-handler-override"></a>
+
+* **Default:** `true`
+
+> ⚠ **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 
+handler is not unintentionally overridden.
+
+#### Example of incorrect usage:
+
+```js
+app.setErrorHandler(function freeSomeResources () {
+  // Never executed, memory leaks
+})
+
+app.setErrorHandler(function anotherErrorHandler () {
+  // Overrides the previous handler
+})
+```
 
 ## Instance
 
@@ -1357,7 +1381,7 @@ Set the schema error formatter for all routes. See
 Set the schema serializer compiler for all routes. See
 [#schema-serializer](./Validation-and-Serialization.md#schema-serializer).
 
-> 🛈 Note:
+> ℹ️ Note:
 > [`setReplySerializer`](#set-reply-serializer) has priority if set!
 
 #### validatorCompiler
@@ -1490,7 +1514,7 @@ lifecycle](./Lifecycle.md#lifecycle). *async-await* is supported as well.
 You can also register [`preValidation`](./Hooks.md#route-hooks) and
 [`preHandler`](./Hooks.md#route-hooks) hooks for the 404 handler.
 
-> 🛈 Note:
+> ℹ️ Note:
 > The `preValidation` hook registered using this method will run for a
 > route that Fastify does not recognize and **not** when a route handler manually
 > calls [`reply.callNotFound`](./Reply.md#call-not-found). In which case, only
@@ -1526,10 +1550,10 @@ plugins are registered. If you would like to augment the behavior of the default
 arguments `fastify.setNotFoundHandler()` within the context of these registered
 plugins.
 
-> 🛈 Note:
+> ℹ️ Note:
 > Some config properties from the request object will be
 > undefined inside the custom not found handler. E.g.:
-> `request.routerPath`, `routerMethod` and `context.config`.
+> `request.routeOptions.url`, `routeOptions.method` and `routeOptions.config`.
 > This method design goal is to allow calling the common not found route.
 > To return a per-route customized 404 response, you can do it in
 > the response itself.
@@ -1574,6 +1598,12 @@ if (statusCode >= 500) {
   log.error(error)
 }
 ```
+
+> ⚠ Warning:
+> Avoid calling setErrorHandler multiple times in the same scope.
+> See [`allowErrorHandlerOverride`](#allowerrorhandleroverride).
+
+
 #### setChildLoggerFactory
 <a id="set-child-logger-factory"></a>
 

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

@@ -432,7 +432,7 @@ 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/eslint.config.js

@@ -1,11 +1,19 @@
 'use strict'
+const neostandard = require('neostandard')
 
-module.exports = require('neostandard')({
-  ignores: [
-    'lib/configValidator.js',
-    'lib/error-serializer.js',
-    'test/same-shape.test.js',
-    'test/types/import.js'
-  ],
-  ts: true
-})
+module.exports = [
+  ...neostandard({
+    ignores: [
+      'lib/configValidator.js',
+      'lib/error-serializer.js',
+      'test/same-shape.test.js',
+      'test/types/import.js'
+    ],
+    ts: true
+  }),
+  {
+    rules: {
+      'comma-dangle': ['error', 'never']
+    }
+  }
+]

package/fastify.d.ts

@@ -157,7 +157,8 @@ declare namespace fastify {
      * listener to error events emitted by client connections
      */
     clientErrorHandler?: (error: ConnectionError, socket: Socket) => void,
-    childLoggerFactory?: FastifyChildLoggerFactory
+    childLoggerFactory?: FastifyChildLoggerFactory,
+    allowErrorHandlerOverride?: boolean
   }
 
   /**

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '5.3.2'
+const VERSION = '5.4.0'
 
 const Avvio = require('avvio')
 const http = require('node:http')
@@ -31,7 +31,8 @@ const {
   kErrorHandler,
   kKeepAliveConnections,
   kChildLoggerFactory,
-  kGenReqId
+  kGenReqId,
+  kErrorHandlerAlreadySet
 } = require('./lib/symbols.js')
 
 const { createServer } = require('./lib/server')
@@ -72,10 +73,12 @@ const {
   FST_ERR_ROUTE_REWRITE_NOT_STR,
   FST_ERR_SCHEMA_ERROR_FORMATTER_NOT_FN,
   FST_ERR_ERROR_HANDLER_NOT_FN,
+  FST_ERR_ERROR_HANDLER_ALREADY_SET,
   FST_ERR_ROUTE_METHOD_INVALID
 } = errorCodes
 
 const { buildErrorHandler } = require('./lib/error-handler.js')
+const { FSTWRN004 } = require('./lib/warnings.js')
 
 const initChannel = diagnostics.channel('fastify.initialization')
 
@@ -149,6 +152,7 @@ function fastify (options) {
   options.disableRequestLogging = disableRequestLogging
   options.ajv = ajvOptions
   options.clientErrorHandler = options.clientErrorHandler || defaultClientErrorHandler
+  options.allowErrorHandlerOverride = options.allowErrorHandlerOverride ?? defaultInitOptions.allowErrorHandlerOverride
 
   const initialConfig = getSecuredInitialConfig(options)
 
@@ -237,6 +241,7 @@ function fastify (options) {
     [kSchemaController]: schemaController,
     [kSchemaErrorFormatter]: null,
     [kErrorHandler]: buildErrorHandler(),
+    [kErrorHandlerAlreadySet]: false,
     [kChildLoggerFactory]: defaultChildLoggerFactory,
     [kReplySerializerDefault]: null,
     [kContentTypeParser]: new ContentTypeParser(
@@ -681,8 +686,12 @@ function fastify (options) {
       this[kHooks].add(name, fn)
     } else {
       this.after((err, done) => {
-        _addHook.call(this, name, fn)
-        done(err)
+        try {
+          _addHook.call(this, name, fn)
+          done(err)
+        } catch (err) {
+          done(err)
+        }
       })
     }
     return this
@@ -854,6 +863,13 @@ function fastify (options) {
       throw new FST_ERR_ERROR_HANDLER_NOT_FN()
     }
 
+    if (!options.allowErrorHandlerOverride && this[kErrorHandlerAlreadySet]) {
+      throw new FST_ERR_ERROR_HANDLER_ALREADY_SET()
+    } else if (this[kErrorHandlerAlreadySet]) {
+      FSTWRN004("To disable this behavior, set 'allowErrorHandlerOverride' to false or ignore this message. For more information, visit: https://fastify.dev/docs/latest/Reference/Server/#allowerrorhandleroverride")
+    }
+
+    this[kErrorHandlerAlreadySet] = true
     this[kErrorHandler] = buildErrorHandler(this[kErrorHandler], func.bind(this))
     return this
   }

package/lib/configValidator.js

@@ -1100,5 +1100,5 @@ return errors === 0;
 }
 
 
-module.exports.defaultInitOptions = {"connectionTimeout":0,"keepAliveTimeout":72000,"maxRequestsPerSocket":0,"requestTimeout":0,"bodyLimit":1048576,"caseSensitive":true,"allowUnsafeRegex":false,"disableRequestLogging":false,"ignoreTrailingSlash":false,"ignoreDuplicateSlashes":false,"maxParamLength":100,"onProtoPoisoning":"error","onConstructorPoisoning":"error","pluginTimeout":10000,"requestIdHeader":false,"requestIdLogLabel":"reqId","http2SessionTimeout":72000,"exposeHeadRoutes":true,"useSemicolonDelimiter":false}
+module.exports.defaultInitOptions = {"connectionTimeout":0,"keepAliveTimeout":72000,"maxRequestsPerSocket":0,"requestTimeout":0,"bodyLimit":1048576,"caseSensitive":true,"allowUnsafeRegex":false,"disableRequestLogging":false,"ignoreTrailingSlash":false,"ignoreDuplicateSlashes":false,"maxParamLength":100,"onProtoPoisoning":"error","onConstructorPoisoning":"error","pluginTimeout":10000,"requestIdHeader":false,"requestIdLogLabel":"reqId","http2SessionTimeout":72000,"exposeHeadRoutes":true,"useSemicolonDelimiter":false,"allowErrorHandlerOverride":true}
 /* c8 ignore stop */

package/lib/decorate.js

@@ -4,7 +4,7 @@ const {
   kReply,
   kRequest,
   kState,
-  kHasBeenDecorated,
+  kHasBeenDecorated
 } = require('./symbols.js')
 
 const {
@@ -13,7 +13,7 @@ const {
   FST_ERR_DEC_AFTER_START,
   FST_ERR_DEC_REFERENCE_TYPE,
   FST_ERR_DEC_DEPENDENCY_INVALID_TYPE,
-  FST_ERR_DEC_UNDECLARED,
+  FST_ERR_DEC_UNDECLARED
 } = require('./errors')
 
 function decorate (instance, name, fn, dependencies) {

package/lib/errors.js

@@ -64,6 +64,12 @@ const codes = {
     500,
     TypeError
   ),
+  FST_ERR_ERROR_HANDLER_ALREADY_SET: createError(
+    'FST_ERR_ERROR_HANDLER_ALREADY_SET',
+    "Error Handler already set in this scope. Set 'allowErrorHandlerOverride: true' to allow overriding.",
+    500,
+    TypeError
+  ),
 
   /**
    * ContentTypeParser
@@ -328,14 +334,6 @@ const codes = {
     'response schemas should be nested under a valid status code, e.g { 2xx: { type: "object" } }'
   ),
 
-  /**
-   * http2
-   */
-  FST_ERR_HTTP2_INVALID_VERSION: createError(
-    'FST_ERR_HTTP2_INVALID_VERSION',
-    'HTTP2 is available only from node >= 8.8.1'
-  ),
-
   /**
    * initialConfig
    */

package/lib/logger-factory.js

@@ -132,5 +132,5 @@ module.exports = {
   defaultChildLoggerFactory,
   createLogger,
   validateLogger,
-  now,
+  now
 }

package/lib/logger-pino.js

@@ -9,7 +9,7 @@
 const pino = require('pino')
 const { serializersSym } = pino.symbols
 const {
-  FST_ERR_LOG_INVALID_DESTINATION,
+  FST_ERR_LOG_INVALID_DESTINATION
 } = require('./errors')
 
 function createPinoLogger (opts) {
@@ -64,5 +64,5 @@ const serializers = {
 
 module.exports = {
   serializers,
-  createPinoLogger,
+  createPinoLogger
 }

package/lib/pluginOverride.js

@@ -12,7 +12,8 @@ const {
   kReply,
   kRequest,
   kFourOhFour,
-  kPluginNameChain
+  kPluginNameChain,
+  kErrorHandlerAlreadySet
 } = require('./symbols.js')
 
 const Reply = require('./reply')
@@ -57,6 +58,7 @@ module.exports = function override (old, fn, opts) {
   // Track the plugin chain since the root instance.
   // When an non-encapsulated plugin is added, the chain will be updated.
   instance[kPluginNameChain] = [fnName]
+  instance[kErrorHandlerAlreadySet] = false
 
   if (instance[kLogSerializers] || opts.logSerializers) {
     instance[kLogSerializers] = Object.assign(Object.create(instance[kLogSerializers]), opts.logSerializers)

package/lib/reply.js

@@ -22,7 +22,7 @@ const {
   kReplyCacheSerializeFns,
   kSchemaController,
   kOptions,
-  kRouteContext,
+  kRouteContext
 } = require('./symbols.js')
 const {
   onSendHookRunner,
@@ -53,7 +53,7 @@ const {
   FST_ERR_BAD_TRAILER_VALUE,
   FST_ERR_MISSING_SERIALIZATION_FN,
   FST_ERR_MISSING_CONTENTTYPE_SERIALIZATION_FN,
-  FST_ERR_DEC_UNDECLARED,
+  FST_ERR_DEC_UNDECLARED
 } = require('./errors')
 const decorators = require('./decorate')
 
@@ -215,12 +215,8 @@ Reply.prototype.send = function (payload) {
 
 Reply.prototype.getHeader = function (key) {
   key = key.toLowerCase()
-  const res = this.raw
-  let value = this[kReplyHeaders][key]
-  if (value === undefined && res.hasHeader(key)) {
-    value = res.getHeader(key)
-  }
-  return value
+  const value = this[kReplyHeaders][key]
+  return value !== undefined ? value : this.raw.getHeader(key)
 }
 
 Reply.prototype.getHeaders = function () {
@@ -315,12 +311,12 @@ Reply.prototype.removeTrailer = function (key) {
 }
 
 Reply.prototype.code = function (code) {
-  const intValue = Number(code)
-  if (isNaN(intValue) || intValue < 100 || intValue > 599) {
+  const statusCode = +code
+  if (!(statusCode >= 100 && statusCode <= 599)) {
     throw new FST_ERR_BAD_STATUS_CODE(code || String(code))
   }
 
-  this.raw.statusCode = intValue
+  this.raw.statusCode = statusCode
   this[kReplyHasStatusCode] = true
   return this
 }
@@ -500,11 +496,11 @@ function preSerializationHook (reply, payload) {
       preSerializationHookEnd
     )
   } else {
-    preSerializationHookEnd(null, reply.request, reply, payload)
+    preSerializationHookEnd(null, undefined, reply, payload)
   }
 }
 
-function preSerializationHookEnd (err, request, reply, payload) {
+function preSerializationHookEnd (err, _request, reply, payload) {
   if (err != null) {
     onErrorHook(reply, err)
     return

package/lib/request.js

@@ -11,7 +11,7 @@ const {
   kOptions,
   kRequestCacheValidateFns,
   kRouteContext,
-  kRequestOriginalUrl,
+  kRequestOriginalUrl
 } = require('./symbols')
 const { FST_ERR_REQ_INVALID_VALIDATION_INVOCATION, FST_ERR_DEC_UNDECLARED } = require('./errors')
 const decorators = require('./decorate')
@@ -188,19 +188,12 @@ Object.defineProperties(Request.prototype, {
         exposeHeadRoute: context.exposeHeadRoute,
         prefixTrailingSlash: context.prefixTrailingSlash,
         handler: context.handler,
+        config: context.config,
+        schema: context.schema,
         version
       }
 
-      Object.defineProperties(options, {
-        config: {
-          get: () => context.config
-        },
-        schema: {
-          get: () => context.schema
-        }
-      })
-
-      return Object.freeze(options)
+      return options
     }
   },
   is404: {

package/lib/server.js

@@ -2,6 +2,7 @@
 
 const http = require('node:http')
 const https = require('node:https')
+const http2 = require('node:http2')
 const dns = require('node:dns')
 const os = require('node:os')
 
@@ -9,7 +10,6 @@ const { kState, kOptions, kServerBindings } = require('./symbols')
 const { FSTWRN003 } = require('./warnings')
 const { onListenHookRunner } = require('./hooks')
 const {
-  FST_ERR_HTTP2_INVALID_VERSION,
   FST_ERR_REOPENED_CLOSE_SERVER,
   FST_ERR_REOPENED_SERVER,
   FST_ERR_LISTEN_OPTIONS_INVALID
@@ -98,7 +98,6 @@ function createServer (options, httpHandler) {
 
     if (cb === undefined) {
       const listening = listenPromise.call(this, server, listenOptions)
-      /* istanbul ignore else */
       return listening.then(address => {
         return new Promise((resolve, reject) => {
           if (host === 'localhost') {
@@ -192,7 +191,6 @@ function multipleBindings (mainServer, httpHandler, serverOpts, listenOptions, o
     // to the secondary servers. It is valid only when the user is
     // listening on localhost
     const originUnref = mainServer.unref
-    /* c8 ignore next 4 */
     mainServer.unref = function () {
       originUnref.call(mainServer)
       mainServer.emit('unref')
@@ -218,7 +216,8 @@ function listenCallback (server, listenOptions) {
 
     if (this[kState].listening && this[kState].closing) {
       return listenOptions.cb(new FST_ERR_REOPENED_CLOSE_SERVER(), null)
-    } else if (this[kState].listening) {
+    }
+    if (this[kState].listening) {
       return listenOptions.cb(new FST_ERR_REOPENED_SERVER(), null)
     }
 
@@ -234,7 +233,8 @@ function listenCallback (server, listenOptions) {
 function listenPromise (server, listenOptions) {
   if (this[kState].listening && this[kState].closing) {
     return Promise.reject(new FST_ERR_REOPENED_CLOSE_SERVER())
-  } else if (this[kState].listening) {
+  }
+  if (this[kState].listening) {
     return Promise.reject(new FST_ERR_REOPENED_SERVER())
   }
 
@@ -272,41 +272,38 @@ function listenPromise (server, listenOptions) {
 }
 
 function getServerInstance (options, httpHandler) {
-  let server = null
-  // node@20 do not accepts options as boolean
-  // we need to provide proper https option
-  const httpsOptions = options.https === true ? {} : options.https
   if (options.serverFactory) {
-    server = options.serverFactory(httpHandler, options)
-  } else if (options.http2) {
-    if (typeof httpsOptions === 'object') {
-      server = http2().createSecureServer(httpsOptions, httpHandler)
-    } else {
-      server = http2().createServer(httpHandler)
-    }
-    server.on('session', sessionTimeout(options.http2SessionTimeout))
-  } else {
-    // this is http1
-    if (httpsOptions) {
-      server = https.createServer(httpsOptions, httpHandler)
-    } else {
-      server = http.createServer(options.http, httpHandler)
-    }
-    server.keepAliveTimeout = options.keepAliveTimeout
-    server.requestTimeout = options.requestTimeout
-    // we treat zero as null
-    // and null is the default setting from nodejs
-    // so we do not pass the option to server
-    if (options.maxRequestsPerSocket > 0) {
-      server.maxRequestsPerSocket = options.maxRequestsPerSocket
-    }
+    // User provided server instance
+    return options.serverFactory(httpHandler, options)
   }
 
-  if (!options.serverFactory) {
+  // We have accepted true as a valid way to init https but node requires an options obj
+  const httpsOptions = options.https === true ? {} : options.https
+
+  if (options.http2) {
+    const server = typeof httpsOptions === 'object' ? http2.createSecureServer(httpsOptions, httpHandler) : http2.createServer(options.http, httpHandler)
+    server.on('session', (session) => session.setTimeout(options.http2SessionTimeout, function closeSession () {
+      this.close()
+    }))
+
     server.setTimeout(options.connectionTimeout)
+
+    return server
   }
+
+  // HTTP1 server instance
+  const server = httpsOptions ? https.createServer(httpsOptions, httpHandler) : http.createServer(options.http, httpHandler)
+  server.keepAliveTimeout = options.keepAliveTimeout
+  server.requestTimeout = options.requestTimeout
+  server.setTimeout(options.connectionTimeout)
+  // We treat zero as null(node default) so we do not pass zero to the server instance
+  if (options.maxRequestsPerSocket > 0) {
+    server.maxRequestsPerSocket = options.maxRequestsPerSocket
+  }
+
   return server
 }
+
 /**
  * Inspects the provided `server.address` object and returns a
  * normalized list of IP address strings. Normalization in this
@@ -355,21 +352,3 @@ function logServerAddress (server, listenTextResolver) {
   }
   return addresses[0]
 }
-
-function http2 () {
-  try {
-    return require('node:http2')
-  } catch (err) {
-    throw new FST_ERR_HTTP2_INVALID_VERSION()
-  }
-}
-
-function sessionTimeout (timeout) {
-  return function (session) {
-    session.setTimeout(timeout, close)
-  }
-}
-
-function close () {
-  this.close()
-}

package/lib/symbols.js

@@ -56,6 +56,7 @@ const keys = {
   // This symbol is only meant to be used for fastify tests and should not be used for any other purpose
   kTestInternals: Symbol('fastify.testInternals'),
   kErrorHandler: Symbol('fastify.errorHandler'),
+  kErrorHandlerAlreadySet: Symbol('fastify.errorHandlerAlreadySet'),
   kChildLoggerFactory: Symbol('fastify.childLoggerFactory'),
   kHasBeenDecorated: Symbol('fastify.hasBeenDecorated'),
   kKeepAliveConnections: Symbol('fastify.keepAliveConnections'),

package/lib/warnings.js

@@ -25,6 +25,13 @@ const FSTWRN003 = createWarning({
   unlimited: true
 })
 
+const FSTWRN004 = createWarning({
+  name: 'FastifyWarning',
+  code: 'FSTWRN004',
+  message: 'It seems that you are overriding an errorHandler in the same scope, which can lead to subtle bugs.',
+  unlimited: true
+})
+
 const FSTSEC001 = createWarning({
   name: 'FastifySecurity',
   code: 'FSTSEC001',
@@ -35,5 +42,6 @@ const FSTSEC001 = createWarning({
 module.exports = {
   FSTWRN001,
   FSTWRN003,
+  FSTWRN004,
   FSTSEC001
 }