fastify 4.7.0 → 4.8.0

package/docs/Guides/Ecosystem.md

@@ -468,7 +468,7 @@ section.
   Fastify and protobufjs, together at last. Uses protobufjs by default.
 - [`fastify-qrcode`](https://github.com/chonla/fastify-qrcode) This plugin
   utilizes [qrcode](https://github.com/soldair/node-qrcode) to generate QR Code.
-- [`fastify-qs`](https://github.com/webdevium/fastify-qs) A plugin for Fastify
+- [`fastify-qs`](https://github.com/vanodevium/fastify-qs) A plugin for Fastify
   that adds support for parsing URL query parameters with
   [qs](https://github.com/ljharb/qs).
 - [`fastify-racing`](https://github.com/metcoder95/fastify-racing) Fastify's

package/docs/Guides/Testing.md

@@ -243,33 +243,66 @@ after initializing routes and plugins with `fastify.ready()`.
 
 Uses **app.js** from the previous example.
 
-**test-listen.js** (testing with
-[`Request`](https://www.npmjs.com/package/request))
+**test-listen.js** (testing with [`undici`](https://www.npmjs.com/package/undici))
 ```js
 const tap = require('tap')
-const request = require('request')
+const { Client } = require('undici')
 const buildFastify = require('./app')
 
-tap.test('GET `/` route', t => {
-  t.plan(5)
+tap.test('should work with undici', async t => {
+  t.plan(2)
 
   const fastify = buildFastify()
 
-  t.teardown(() => fastify.close())
+  await fastify.listen()
 
-  fastify.listen({ port: 0 }, (err) => {
-    t.error(err)
+   const client = new Client(
+    'http://localhost:' + fastify.server.address().port, {
+      keepAliveTimeout: 10,
+      keepAliveMaxTimeout: 10
+    } 
+  )
 
-    request({
-      method: 'GET',
-      url: 'http://localhost:' + fastify.server.address().port
-    }, (err, response, body) => {
-      t.error(err)
-      t.equal(response.statusCode, 200)
-      t.equal(response.headers['content-type'], 'application/json; charset=utf-8')
-      t.same(JSON.parse(body), { hello: 'world' })
-    })
+  t.teardown(() => {
+    fastify.close()
+    client.close()
   })
+
+  const response = await client.request({ method: 'GET', path: '/' })
+
+  t.equal(await response.body.text(), '{"hello":"world"}')
+  t.equal(response.statusCode, 200)
+})
+```
+
+Alternatively, starting with Node.js 18, 
+[`fetch`](https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch) 
+may be used without requiring any extra dependencies:
+
+**test-listen.js**
+```js
+const tap = require('tap')
+const buildFastify = require('./app')
+
+tap.test('should work with fetch', async t => {
+  t.plan(3)
+
+  const fastify = buildFastify()
+
+  t.teardown(() => fastify.close())
+
+  await fastify.listen()
+  
+  const response = await fetch(
+    'http://localhost:' + fastify.server.address().port
+  )
+
+  t.equal(response.status, 200)
+  t.equal(
+    response.headers.get('content-type'),
+    'application/json; charset=utf-8'
+  )
+  t.has(await response.json(), { hello: 'world' })
 })
 ```
 

package/docs/Reference/Errors.md

@@ -83,15 +83,52 @@ Some things to consider in your custom error handler:
 ### Fastify Error Codes
 <a id="fastify-error-codes"></a>
 
-#### FST_ERR_BAD_URL
-<a id="FST_ERR_BAD_URL"></a>
-
-The router received an invalid url.
-
-<a name="FST_ERR_DUPLICATED_ROUTE"></a>
-#### FST_ERR_DUPLICATED_ROUTE
-
-The HTTP method already has a registered controller for that URL
+You can access `errorCodes` for mapping:
+```js
+// ESM
+import { errorCodes } from 'fastify'
+
+// CommonJs
+const errorCodes = require('fastify').errorCodes
+```
+
+For example:
+```js
+const Fastify = require('./fastify')
+
+// Instantiate the framework
+const fastify = Fastify({
+  logger: true
+})
+
+// Declare a route
+fastify.get('/', function (request, reply) {
+  reply.code('bad status code').send({ hello: 'world' })
+})
+
+fastify.setErrorHandler(function (error, request, reply) {
+  if (error instanceof Fastify.errorCodes.FST_ERR_BAD_STATUS_CODE) {
+    // Log error
+    this.log.error(error)
+    // Send error response
+    reply.status(500).send({ ok: false })
+  }
+})
+
+// Run the server!
+fastify.listen({ port: 3000 }, function (err, address) {
+  if (err) {
+    fastify.log.error(err)
+    process.exit(1)
+  }
+  // Server is now listening on ${address}
+})
+```
+
+#### FST_ERR_NOT_FOUND
+<a id="FST_ERR_NOT_FOUND"></a>
+
+404 Not Found.
 
 <a name="FST_ERR_CTP_ALREADY_PRESENT"></a>
 #### FST_ERR_CTP_ALREADY_PRESENT
@@ -99,130 +136,238 @@ The HTTP method already has a registered controller for that URL
 
 The parser for this content type was already registered.
 
-#### FST_ERR_CTP_BODY_TOO_LARGE
-<a id="FST_ERR_CTP_BODY_TOO_LARGE"></a>
-
-The request body is larger than the provided limit.
+#### FST_ERR_CTP_INVALID_TYPE
+<a id="FST_ERR_CTP_INVALID_TYPE"></a>
 
-This setting can be defined in the Fastify server instance:
-[`bodyLimit`](./Server.md#bodylimit)
+The `Content-Type` should be a string.
 
 #### FST_ERR_CTP_EMPTY_TYPE
 <a id="FST_ERR_CTP_EMPTY_TYPE"></a>
 
 The content type cannot be an empty string.
 
-#### FST_ERR_CTP_INVALID_CONTENT_LENGTH
-<a id="FST_ERR_CTP_INVALID_CONTENT_LENGTH"></a>
-
-Request body size did not match Content-Length.
-
 #### FST_ERR_CTP_INVALID_HANDLER
 <a id="FST_ERR_CTP_INVALID_HANDLER"></a>
 
 An invalid handler was passed for the content type.
 
+#### FST_ERR_CTP_INVALID_PARSE_TYPE
+<a id="FST_ERR_CTP_INVALID_PARSE_TYPE"></a>
+
+The provided parse type is not supported. Accepted values are `string` or
+`buffer`.
+
+#### FST_ERR_CTP_BODY_TOO_LARGE
+<a id="FST_ERR_CTP_BODY_TOO_LARGE"></a>
+
+The request body is larger than the provided limit.
+
+This setting can be defined in the Fastify server instance:
+[`bodyLimit`](./Server.md#bodylimit)
+
 #### FST_ERR_CTP_INVALID_MEDIA_TYPE
 <a id="FST_ERR_CTP_INVALID_MEDIA_TYPE"></a>
 
 The received media type is not supported (i.e. there is no suitable
 `Content-Type` parser for it).
 
-#### FST_ERR_CTP_INVALID_PARSE_TYPE
-<a id="FST_ERR_CTP_INVALID_PARSE_TYPE"></a>
+#### FST_ERR_CTP_INVALID_CONTENT_LENGTH
+<a id="FST_ERR_CTP_INVALID_CONTENT_LENGTH"></a>
 
-The provided parse type is not supported. Accepted values are `string` or
-`buffer`.
+Request body size did not match `Content-Length`.
 
-#### FST_ERR_CTP_INVALID_TYPE
-<a id="FST_ERR_CTP_INVALID_TYPE"></a>
+#### FST_ERR_CTP_EMPTY_JSON_BODY
+<a id="FST_ERR_CTP_EMPTY_JSON_BODY"></a>
 
-The `Content-Type` should be a string.
+Body cannot be empty when content-type is set to `application/json`.
 
 #### FST_ERR_DEC_ALREADY_PRESENT
 <a id="FST_ERR_DEC_ALREADY_PRESENT"></a>
 
 A decorator with the same name is already registered.
 
+#### FST_ERR_DEC_DEPENDENCY_INVALID_TYPE
+<a id="FST_ERR_DEC_DEPENDENCY_INVALID_TYPE"></a>
+
+The dependencies of decorator must be of type `Array`.
+
 #### FST_ERR_DEC_MISSING_DEPENDENCY
 <a id="FST_ERR_DEC_MISSING_DEPENDENCY"></a>
 
 The decorator cannot be registered due to a missing dependency.
 
-#### FST_ERR_HOOK_INVALID_HANDLER
-<a id="FST_ERR_HOOK_INVALID_HANDLER"></a>
+#### FST_ERR_DEC_AFTER_START
+<a id="FST_ERR_DEC_AFTER_START"></a>
 
-The hook callback must be a function.
+The decorator cannot be added after start.
 
 #### FST_ERR_HOOK_INVALID_TYPE
 <a id="FST_ERR_HOOK_INVALID_TYPE"></a>
 
 The hook name must be a string.
 
+#### FST_ERR_HOOK_INVALID_HANDLER
+<a id="FST_ERR_HOOK_INVALID_HANDLER"></a>
+
+The hook callback must be a function.
+
+#### FST_ERR_MISSING_MIDDLEWARE
+<a id="FST_ERR_MISSING_MIDDLEWARE"></a>
+
+You must register a plugin for handling middlewares, 
+visit [`Middleware`](./Middleware.md) for more info.
+
+<a name="FST_ERR_HOOK_TIMEOUT"></a>
+#### FST_ERR_HOOK_TIMEOUT
+
+A callback for a hook timed out
+
 #### FST_ERR_LOG_INVALID_DESTINATION
 <a id="FST_ERR_LOG_INVALID_DESTINATION"></a>
 
 The logger accepts either a `'stream'` or a `'file'` as the destination.
 
-#### FST_ERR_PROMISE_NOT_FULFILLED
-<a id="FST_ERR_PROMISE_NOT_FULFILLED"></a>
+#### FST_ERR_REP_INVALID_PAYLOAD_TYPE
+<a id="FST_ERR_REP_INVALID_PAYLOAD_TYPE"></a>
 
-A promise may not be fulfilled with 'undefined' when statusCode is not 204.
+Reply payload can be either a `string` or a `Buffer`.
 
 #### FST_ERR_REP_ALREADY_SENT
 <a id="FST_ERR_REP_ALREADY_SENT"></a>
 
 A response was already sent.
 
-#### FST_ERR_REP_INVALID_PAYLOAD_TYPE
-<a id="FST_ERR_REP_INVALID_PAYLOAD_TYPE"></a>
+#### FST_ERR_REP_SENT_VALUE
+<a id="FST_ERR_REP_SENT_VALUE"></a>
 
-Reply payload can be either a `string` or a `Buffer`.
+The only possible value for `reply.sent` is `true`.
 
-#### FST_ERR_SCH_ALREADY_PRESENT
-<a id="FST_ERR_SCH_ALREADY_PRESENT"></a>
+#### FST_ERR_SEND_INSIDE_ONERR
+<a id="FST_ERR_SEND_INSIDE_ONERR"></a>
 
-A schema with the same `$id` already exists.
+You cannot use `send` inside the `onError` hook.
+
+#### FST_ERR_SEND_UNDEFINED_ERR
+<a id="FST_ERR_SEND_UNDEFINED_ERR"></a>
+
+Undefined error has occurred.
+
+#### FST_ERR_BAD_STATUS_CODE
+<a id="FST_ERR_BAD_STATUS_CODE"></a>
+
+Called `reply` with an invalid status code.
+
+#### FST_ERR_BAD_TRAILER_NAME
+<a id="FST_ERR_BAD_TRAILER_NAME"></a>
+
+Called `reply.trailer` with an invalid header name.
+
+#### FST_ERR_BAD_TRAILER_VALUE
+<a id="FST_ERR_BAD_TRAILER_VALUE"></a>
+
+Called `reply.trailer` with an invalid type. Expected a function.
+
+#### FST_ERR_MISSING_SERIALIZATION_FN
+<a id="FST_ERR_MISSING_SERIALIZATION_FN"></a>
+
+Missing serialization function.
+
+#### FST_ERR_REQ_INVALID_VALIDATION_INVOCATION
+<a id="FST_ERR_REQ_INVALID_VALIDATION_INVOCATION"></a>
+
+Invalid validation invocation. Missing validation function for 
+HTTP part nor schema provided.
 
 #### FST_ERR_SCH_MISSING_ID
 <a id="FST_ERR_SCH_MISSING_ID"></a>
 
 The schema provided does not have `$id` property.
 
-#### FST_ERR_SCH_SERIALIZATION_BUILD
-<a id="FST_ERR_SCH_SERIALIZATION_BUILD"></a>
+#### FST_ERR_SCH_ALREADY_PRESENT
+<a id="FST_ERR_SCH_ALREADY_PRESENT"></a>
 
-The JSON schema provided for serialization of a route response is not valid.
+A schema with the same `$id` already exists.
+
+#### FST_ERR_SCH_DUPLICATE
+<a id="FST_ERR_SCH_DUPLICATE"></a>
+
+Schema with the same `$id` already present!
 
 #### FST_ERR_SCH_VALIDATION_BUILD
 <a id="FST_ERR_SCH_VALIDATION_BUILD"></a>
 
 The JSON schema provided for validation to a route is not valid.
 
-#### FST_ERR_SEND_INSIDE_ONERR
-<a id="FST_ERR_SEND_INSIDE_ONERR"></a>
+#### FST_ERR_SCH_SERIALIZATION_BUILD
+<a id="FST_ERR_SCH_SERIALIZATION_BUILD"></a>
 
-You cannot use `send` inside the `onError` hook.
+The JSON schema provided for serialization of a route response is not valid.
 
-#### FST_ERR_SEND_UNDEFINED_ERR
-<a id="FST_ERR_SEND_UNDEFINED_ERR"></a>
+#### FST_ERR_HTTP2_INVALID_VERSION
+<a id="FST_ERR_HTTP2_INVALID_VERSION"></a>
 
-Undefined error has occurred.
+HTTP2 is available only from node >= 8.8.1.
 
-<a name="FST_ERR_PLUGIN_NOT_VALID"></a>
-#### FST_ERR_PLUGIN_NOT_VALID
+#### FST_ERR_INIT_OPTS_INVALID
+<a id="FST_ERR_INIT_OPTS_INVALID"></a>
 
-Plugin must be a function or a promise.
+Invalid initialization options.
 
-<a name="FST_ERR_PLUGIN_TIMEOUT"></a>
-#### FST_ERR_PLUGIN_TIMEOUT
+#### FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE
+<a id="FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE"></a>
 
-Plugin did not start in time. Default timeout (in millis): `10000`
+Cannot set forceCloseConnections to `idle` as your HTTP server 
+does not support `closeIdleConnections` method.
 
-<a name="FST_ERR_HOOK_TIMEOUT"></a>
-#### FST_ERR_HOOK_TIMEOUT
+<a name="FST_ERR_DUPLICATED_ROUTE"></a>
+#### FST_ERR_DUPLICATED_ROUTE
 
-A callback for a hook timed out
+The HTTP method already has a registered controller for that URL
+
+#### FST_ERR_BAD_URL
+<a id="FST_ERR_BAD_URL"></a>
+
+The router received an invalid url.
+
+### FST_ERR_ASYNC_CONSTRAINT
+<a id="FST_ERR_ASYNC_CONSTRAINT"></a>
+
+The router received error when using asynchronous constraints.
+
+#### FST_ERR_DEFAULT_ROUTE_INVALID_TYPE
+<a id="FST_ERR_DEFAULT_ROUTE_INVALID_TYPE"></a>
+
+The `defaultRoute` type should be a function.
+
+#### FST_ERR_INVALID_URL
+<a id="FST_ERR_INVALID_URL"></a>
+
+URL must be a string.
+
+#### FST_ERR_REOPENED_CLOSE_SERVER
+<a id="FST_ERR_REOPENED_CLOSE_SERVER"></a>
+
+Fastify has already been closed and cannot be reopened.
+
+#### FST_ERR_REOPENED_SERVER
+<a id="FST_ERR_REOPENED_SERVER"></a>
+
+Fastify is already listening.
+
+#### FST_ERR_PLUGIN_VERSION_MISMATCH
+<a id="FST_ERR_PLUGIN_VERSION_MISMATCH"></a>
+
+Installed Fastify plugin mismatched expected version.
+
+<a name="FST_ERR_PLUGIN_CALLBACK_NOT_FN"></a>
+#### FST_ERR_PLUGIN_CALLBACK_NOT_FN
+
+Callback for a hook is not a function (mapped directly from `avvio`)
+
+<a name="FST_ERR_PLUGIN_NOT_VALID"></a>
+#### FST_ERR_PLUGIN_NOT_VALID
+
+Plugin must be a function or a promise.
 
 <a name="FST_ERR_ROOT_PLG_BOOTED"></a>
 #### FST_ERR_ROOT_PLG_BOOTED
@@ -234,7 +379,7 @@ Root plugin has already booted (mapped directly from `avvio`)
 
 Impossible to load plugin because the parent (mapped directly from `avvio`)
 
-<a name="FST_ERR_PLUGIN_CALLBACK_NOT_FN"></a>
-#### FST_ERR_PLUGIN_CALLBACK_NOT_FN
+<a name="FST_ERR_PLUGIN_TIMEOUT"></a>
+#### FST_ERR_PLUGIN_TIMEOUT
 
-Callback for a hook is not a function (mapped directly from `avvio`)
+Plugin did not start in time. Default timeout (in millis): `10000`

package/docs/Reference/Hooks.md

@@ -449,6 +449,33 @@ fastify.addHook('onRoute', (routeOptions) => {
 })
 ```
 
+If you want to add more routes within an onRoute hook, you have to tag these
+routes properly. If you don't, the hook will run into an infinite loop. The
+recommended approach is shown below.
+
+```js
+const kRouteAlreadyProcessed = Symbol('route-already-processed')
+
+fastify.addHook('onRoute', function (routeOptions) {
+  const { url, method } = routeOptions
+
+  const isAlreadyProcessed = (routeOptions.custom && routeOptions.custom[kRouteAlreadyProcessed]) || false
+
+  if (!isAlreadyProcessed) {
+    this.route({
+      url,
+      method,
+      custom: {
+        [kRouteAlreadyProcessed]: true
+      },
+      handler: () => {}
+    })
+  }
+})
+```
+
+For more details, see this [issue](https://github.com/fastify/fastify/issues/4319).
+
 ### onRegister
 <a id="on-register"></a>
 

package/docs/Reference/Routes.md

@@ -732,6 +732,60 @@ fastify.route({
 })
 ```
 
+#### Asynchronous Custom Constraints
+
+You can provide your custom constraints and the `constraint` criteria can be
+fetched from other source, for example `database`. Usage of asynchronous custom
+constraint should place at the last resort since it impacts the router
+performance.
+
+```js
+function databaseOperation(field, done) {
+  done(null, field)
+}
+
+const secret = {
+  // strategy name for referencing in the route handler `constraints` options
+  name: 'secret',
+  // storage factory for storing routes in the find-my-way route tree
+  storage: function () {
+    let handlers = {}
+    return {
+      get: (type) => { return handlers[type] || null },
+      set: (type, store) => { handlers[type] = store }
+    }
+  },
+  // function to get the value of the constraint from each incoming request
+  deriveConstraint: (req, ctx, done) => {
+    databaseOperation(req.headers['secret'], done)
+  },
+  // optional flag marking if handlers without constraints can match requests that have a value for this constraint
+  mustMatchWhenDerived: true
+}
+```
+
+> ## ⚠  Security Notice
+> When using with asynchronous constraint. It is highly recommend never return error
+> 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) {
+>       res.code(400)
+>       return res.send("Invalid header provided")
+>     } else {
+>       res.send(err)
+>     }
+>   }
+> })
+> ```
+
+
 ### ⚠  HTTP version check
 
 Fastify will check the HTTP version of every request, based on configuration

package/docs/Reference/Server.md

@@ -731,6 +731,9 @@ const fastify = require('fastify')({
     if (error instanceof FST_ERR_BAD_URL) {
       res.code(400)
       return res.send("Provided url is not valid")
+    } else if(error instanceof FST_ERR_ASYNC_CONSTRAINT) {
+      res.code(400)
+      return res.send("Provided header is not valid")
     } else {
       res.send(err)
     }

package/fastify.d.ts

@@ -20,6 +20,7 @@ import { SerializerCompiler } from '@fastify/fast-json-stringify-compiler'
 import { FastifySchema } from './types/schema'
 import { FastifyContextConfig } from './types/context'
 import { FastifyTypeProvider, FastifyTypeProviderDefault } from './types/type-provider'
+import { FastifyErrorCodes } from './types/errors'
 
 /**
  * Fastify factory function for the standard fastify http, https, or http2 server instance.
@@ -61,6 +62,10 @@ declare function fastify<
   TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
 >(opts?: FastifyServerOptions<Server, Logger>): FastifyInstance<Server, Request, Reply, Logger, TypeProvider> & PromiseLike<FastifyInstance<Server, Request, Reply, Logger, TypeProvider>>
 
+declare namespace fastify {
+  export const errorCodes: FastifyErrorCodes;
+}
+
 export default fastify
 
 export type FastifyHttp2SecureOptions<
@@ -206,4 +211,5 @@ export { HTTPMethods, RawServerBase, RawRequestDefaultExpression, RawReplyDefaul
 export * from './types/hooks'
 export { FastifyServerFactory, FastifyServerFactoryHandler } from './types/serverFactory'
 export { FastifyTypeProvider, FastifyTypeProviderDefault } from './types/type-provider'
+export { FastifyErrorCodes } from './types/errors'
 export { fastify }

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '4.7.0'
+const VERSION = '4.8.0'
 
 const Avvio = require('avvio')
 const http = require('http')
@@ -48,14 +48,19 @@ const getSecuredInitialConfig = require('./lib/initialConfigValidation')
 const override = require('./lib/pluginOverride')
 const warning = require('./lib/warnings')
 const noopSet = require('./lib/noop-set')
+const {
+  appendStackTrace,
+  AVVIO_ERRORS_MAP,
+  ...errorCodes
+} = require('./lib/errors')
+
 const { defaultInitOptions } = getSecuredInitialConfig
 
 const {
+  FST_ERR_ASYNC_CONSTRAINT,
   FST_ERR_BAD_URL,
-  FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE,
-  AVVIO_ERRORS_MAP,
-  appendStackTrace
-} = require('./lib/errors')
+  FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE
+} = errorCodes
 
 const { buildErrorHandler } = require('./lib/error-handler.js')
 
@@ -178,7 +183,7 @@ function fastify (options) {
   const fourOhFour = build404(options)
 
   // HTTP server and its handler
-  const httpHandler = wrapRouting(router.routing, options)
+  const httpHandler = wrapRouting(router, options)
 
   // we need to set this before calling createServer
   options.http2SessionTimeout = initialConfig.http2SessionTimeout
@@ -662,6 +667,30 @@ function fastify (options) {
     res.end(body)
   }
 
+  function buildAsyncConstraintCallback (isAsync, req, res) {
+    if (isAsync === false) return undefined
+    return function onAsyncConstraintError (err) {
+      if (err) {
+        if (frameworkErrors) {
+          const id = genReqId(req)
+          const childLogger = logger.child({ reqId: id })
+
+          childLogger.info({ req }, 'incoming request')
+
+          const request = new Request(id, null, req, null, childLogger, onBadUrlContext)
+          const reply = new Reply(res, request, childLogger)
+          return frameworkErrors(new FST_ERR_ASYNC_CONSTRAINT(), request, reply)
+        }
+        const body = '{"error":"Internal Server Error","message":"Unexpected error from async constraint","statusCode":500}'
+        res.writeHead(500, {
+          'Content-Type': 'application/json',
+          'Content-Length': body.length
+        })
+        res.end(body)
+      }
+    }
+  }
+
   function setNotFoundHandler (opts, handler) {
     throwIfAlreadyStarted('Cannot call "setNotFoundHandler" when fastify instance is already started!')
 
@@ -718,8 +747,31 @@ function fastify (options) {
     opts.includeMeta = opts.includeHooks ? opts.includeMeta ? supportedHooks.concat(opts.includeMeta) : supportedHooks : opts.includeMeta
     return router.printRoutes(opts)
   }
+
+  function wrapRouting (router, { rewriteUrl, logger }) {
+    let isAsync
+    return function preRouting (req, res) {
+      // only call isAsyncConstraint once
+      if (isAsync === undefined) isAsync = router.isAsyncConstraint()
+      if (rewriteUrl) {
+        const originalUrl = req.url
+        const url = rewriteUrl(req)
+        if (originalUrl !== url) {
+          logger.debug({ originalUrl, url }, 'rewrite url')
+          if (typeof url === 'string') {
+            req.url = url
+          } else {
+            req.destroy(new Error(`Rewrite url for "${req.url}" needs to be of type "string" but received "${typeof url}"`))
+          }
+        }
+      }
+      router.routing(req, res, buildAsyncConstraintCallback(isAsync, req, res))
+    }
+  }
 }
 
+fastify.errorCodes = errorCodes
+
 function validateSchemaErrorFormatter (schemaErrorFormatter) {
   if (typeof schemaErrorFormatter !== 'function') {
     throw new Error(`schemaErrorFormatter option should be a function, instead got ${typeof schemaErrorFormatter}`)
@@ -728,25 +780,6 @@ function validateSchemaErrorFormatter (schemaErrorFormatter) {
   }
 }
 
-function wrapRouting (httpHandler, { rewriteUrl, logger }) {
-  if (!rewriteUrl) {
-    return httpHandler
-  }
-  return function preRouting (req, res) {
-    const originalUrl = req.url
-    const url = rewriteUrl(req)
-    if (originalUrl !== url) {
-      logger.debug({ originalUrl, url }, 'rewrite url')
-      if (typeof url === 'string') {
-        req.url = url
-      } else {
-        req.destroy(new Error(`Rewrite url for "${req.url}" needs to be of type "string" but received "${typeof url}"`))
-      }
-    }
-    httpHandler(req, res)
-  }
-}
-
 /**
  * These export configurations enable JS and TS developers
  * to consumer fastify in whatever way best suits their needs.

package/lib/errors.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const createError = require('@fastify/error')
+
 const codes = {
   /**
    * Basic
@@ -225,6 +226,11 @@ const codes = {
     "'%s' is not a valid url component",
     400
   ),
+  FST_ERR_ASYNC_CONSTRAINT: createError(
+    'FST_ERR_ASYNC_CONSTRAINT',
+    'Unexpected error from async constraint',
+    500
+  ),
   FST_ERR_DEFAULT_ROUTE_INVALID_TYPE: createError(
     'FST_ERR_DEFAULT_ROUTE_INVALID_TYPE',
     'The defaultRoute type should be a function',
@@ -258,37 +264,42 @@ const codes = {
   ),
 
   /**
-   *  Avvio Errors map
+   *  Avvio Errors
    */
-  AVVIO_ERRORS_MAP: {
-    AVV_ERR_CALLBACK_NOT_FN: createError(
-      'FST_ERR_PLUGIN_CALLBACK_NOT_FN',
-      'fastify-plugin: %s'
-    ),
-    AVV_ERR_PLUGIN_NOT_VALID: createError(
-      'FST_ERR_PLUGIN_NOT_VALID',
-      'fastify-plugin: %s'
-    ),
-    AVV_ERR_ROOT_PLG_BOOTED: createError(
-      'FST_ERR_ROOT_PLG_BOOTED',
-      'fastify-plugin: %s'
-    ),
-    AVV_ERR_PARENT_PLG_LOADED: createError(
-      'FST_ERR_PARENT_PLUGIN_BOOTED',
-      'fastify-plugin: %s'
-    ),
-    AVV_ERR_READY_TIMEOUT: createError(
-      'FST_ERR_PLUGIN_TIMEOUT',
-      'fastify-plugin: %s'
-    )
-  },
+  FST_ERR_PLUGIN_CALLBACK_NOT_FN: createError(
+    'FST_ERR_PLUGIN_CALLBACK_NOT_FN',
+    'fastify-plugin: %s'
+  ),
+  FST_ERR_PLUGIN_NOT_VALID: createError(
+    'FST_ERR_PLUGIN_NOT_VALID',
+    'fastify-plugin: %s'
+  ),
+  FST_ERR_ROOT_PLG_BOOTED: createError(
+    'FST_ERR_ROOT_PLG_BOOTED',
+    'fastify-plugin: %s'
+  ),
+  FST_ERR_PARENT_PLUGIN_BOOTED: createError(
+    'FST_ERR_PARENT_PLUGIN_BOOTED',
+    'fastify-plugin: %s'
+  ),
+  FST_ERR_PLUGIN_TIMEOUT: createError(
+    'FST_ERR_PLUGIN_TIMEOUT',
+    'fastify-plugin: %s'
+  )
+}
 
-  //  Util function
-  appendStackTrace (oldErr, newErr) {
-    newErr.cause = oldErr
+function appendStackTrace (oldErr, newErr) {
+  newErr.cause = oldErr
 
-    return newErr
-  }
+  return newErr
 }
 
 module.exports = codes
+module.exports.appendStackTrace = appendStackTrace
+module.exports.AVVIO_ERRORS_MAP = {
+  AVV_ERR_CALLBACK_NOT_FN: codes.FST_ERR_PLUGIN_CALLBACK_NOT_FN,
+  AVV_ERR_PLUGIN_NOT_VALID: codes.FST_ERR_PLUGIN_NOT_VALID,
+  AVV_ERR_ROOT_PLG_BOOTED: codes.FST_ERR_ROOT_PLG_BOOTED,
+  AVV_ERR_PARENT_PLG_LOADED: codes.FST_ERR_PARENT_PLUGIN_BOOTED,
+  AVV_ERR_READY_TIMEOUT: codes.FST_ERR_PLUGIN_TIMEOUT
+}

package/lib/route.js

@@ -101,7 +101,8 @@ function buildRouting (options) {
     closeRoutes: () => { closing = true },
     printRoutes: router.prettyPrint.bind(router),
     addConstraintStrategy,
-    hasConstraintStrategy
+    hasConstraintStrategy,
+    isAsyncConstraint
   }
 
   function addConstraintStrategy (strategy) {
@@ -113,6 +114,10 @@ function buildRouting (options) {
     return router.hasConstraintStrategy(strategyName)
   }
 
+  function isAsyncConstraint () {
+    return router.constrainer.asyncStrategiesInUse.size > 0
+  }
+
   // Convert shorthand to extended route declaration
   function prepareRoute ({ method, url, options, handler, isFastify }) {
     if (typeof url !== 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Fast and low overhead web framework, for Node.js",
   "main": "fastify.js",
   "type": "commonjs",
@@ -176,7 +176,7 @@
     "@fastify/fast-json-stringify-compiler": "^4.1.0",
     "abstract-logging": "^2.0.1",
     "avvio": "^8.2.0",
-    "find-my-way": "^7.2.0",
+    "find-my-way": "^7.3.0",
     "light-my-request": "^5.6.1",
     "pino": "^8.5.0",
     "process-warning": "^2.0.0",

package/test/constrained-routes.test.js

@@ -660,3 +660,117 @@ test('allows separate constrained and unconstrained HEAD routes', async (t) => {
 
   t.ok(true)
 })
+
+test('allow async constraints', async (t) => {
+  t.plan(5)
+
+  const constraint = {
+    name: 'secret',
+    storage: function () {
+      const secrets = {}
+      return {
+        get: (secret) => { return secrets[secret] || null },
+        set: (secret, store) => { secrets[secret] = store }
+      }
+    },
+    deriveConstraint: (req, ctx, done) => {
+      done(null, req.headers['x-secret'])
+    },
+    validate () { return true }
+  }
+
+  const fastify = Fastify({ constraints: { secret: constraint } })
+
+  fastify.route({
+    method: 'GET',
+    url: '/',
+    constraints: { secret: 'alpha' },
+    handler: (req, reply) => {
+      reply.send({ hello: 'from alpha' })
+    }
+  })
+
+  fastify.route({
+    method: 'GET',
+    url: '/',
+    constraints: { secret: 'beta' },
+    handler: (req, reply) => {
+      reply.send({ hello: 'from beta' })
+    }
+  })
+
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'alpha' } })
+    t.same(JSON.parse(payload), { hello: 'from alpha' })
+    t.equal(statusCode, 200)
+  }
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'beta' } })
+    t.same(JSON.parse(payload), { hello: 'from beta' })
+    t.equal(statusCode, 200)
+  }
+  {
+    const { statusCode } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'gamma' } })
+    t.equal(statusCode, 404)
+  }
+})
+
+test('error in async constraints', async (t) => {
+  t.plan(8)
+
+  const constraint = {
+    name: 'secret',
+    storage: function () {
+      const secrets = {}
+      return {
+        get: (secret) => { return secrets[secret] || null },
+        set: (secret, store) => { secrets[secret] = store }
+      }
+    },
+    deriveConstraint: (req, ctx, done) => {
+      done(Error('kaboom'))
+    },
+    validate () { return true }
+  }
+
+  const fastify = Fastify({ constraints: { secret: constraint } })
+
+  fastify.route({
+    method: 'GET',
+    url: '/',
+    constraints: { secret: 'alpha' },
+    handler: (req, reply) => {
+      reply.send({ hello: 'from alpha' })
+    }
+  })
+
+  fastify.route({
+    method: 'GET',
+    url: '/',
+    constraints: { secret: 'beta' },
+    handler: (req, reply) => {
+      reply.send({ hello: 'from beta' })
+    }
+  })
+
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'alpha' } })
+    t.same(JSON.parse(payload), { error: 'Internal Server Error', message: 'Unexpected error from async constraint', statusCode: 500 })
+    t.equal(statusCode, 500)
+  }
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'beta' } })
+    t.same(JSON.parse(payload), { error: 'Internal Server Error', message: 'Unexpected error from async constraint', statusCode: 500 })
+    t.equal(statusCode, 500)
+  }
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/', headers: { 'X-Secret': 'gamma' } })
+    t.same(JSON.parse(payload), { error: 'Internal Server Error', message: 'Unexpected error from async constraint', statusCode: 500 })
+    t.equal(statusCode, 500)
+  }
+  {
+    const { statusCode, payload } = await fastify.inject({ method: 'GET', path: '/' })
+    t.same(JSON.parse(payload), { error: 'Internal Server Error', message: 'Unexpected error from async constraint', statusCode: 500 })
+    t.equal(statusCode, 500)
+  }
+})

package/test/router-options.test.js

@@ -2,7 +2,10 @@
 
 const test = require('tap').test
 const Fastify = require('../')
-const { FST_ERR_BAD_URL } = require('../lib/errors')
+const {
+  FST_ERR_BAD_URL,
+  FST_ERR_ASYNC_CONSTRAINT
+} = require('../lib/errors')
 
 test('Should honor ignoreTrailingSlash option', async t => {
   t.plan(4)
@@ -137,7 +140,7 @@ test('Should set is404 flag for unmatched paths', t => {
   })
 })
 
-test('Should honor frameworkErrors option', t => {
+test('Should honor frameworkErrors option - FST_ERR_BAD_URL', t => {
   t.plan(3)
   const fastify = Fastify({
     frameworkErrors: function (err, req, res) {
@@ -165,3 +168,54 @@ test('Should honor frameworkErrors option', t => {
     }
   )
 })
+
+test('Should honor frameworkErrors option - FST_ERR_ASYNC_CONSTRAINT', t => {
+  t.plan(3)
+
+  const constraint = {
+    name: 'secret',
+    storage: function () {
+      const secrets = {}
+      return {
+        get: (secret) => { return secrets[secret] || null },
+        set: (secret, store) => { secrets[secret] = store }
+      }
+    },
+    deriveConstraint: (req, ctx, done) => {
+      done(Error('kaboom'))
+    },
+    validate () { return true }
+  }
+
+  const fastify = Fastify({
+    frameworkErrors: function (err, req, res) {
+      if (err instanceof FST_ERR_ASYNC_CONSTRAINT) {
+        t.ok(true)
+      } else {
+        t.fail()
+      }
+      res.send(`${err.message} - ${err.code}`)
+    },
+    constraints: { secret: constraint }
+  })
+
+  fastify.route({
+    method: 'GET',
+    url: '/',
+    constraints: { secret: 'alpha' },
+    handler: (req, reply) => {
+      reply.send({ hello: 'from alpha' })
+    }
+  })
+
+  fastify.inject(
+    {
+      method: 'GET',
+      url: '/'
+    },
+    (err, res) => {
+      t.error(err)
+      t.equal(res.body, 'Unexpected error from async constraint - FST_ERR_ASYNC_CONSTRAINT')
+    }
+  )
+})

package/test/types/fastify.test-d.ts

@@ -9,7 +9,8 @@ import fastify, {
   LightMyRequestCallback,
   InjectOptions, FastifyBaseLogger,
   RouteGenericInterface,
-  ValidationResult
+  ValidationResult,
+  FastifyErrorCodes
 } from '../../fastify'
 import { ErrorObject as AjvErrorObject } from 'ajv'
 import * as http from 'http'
@@ -240,3 +241,6 @@ expectType<unknown>(routeGeneric.Headers)
 expectType<unknown>(routeGeneric.Params)
 expectType<unknown>(routeGeneric.Querystring)
 expectType<unknown>(routeGeneric.Reply)
+
+// ErrorCodes
+expectType<FastifyErrorCodes>(fastify.errorCodes)

package/types/errors.d.ts

@@ -0,0 +1,53 @@
+import { FastifyErrorConstructor } from '@fastify/error'
+
+export type FastifyErrorCodes = Record<
+'FST_ERR_NOT_FOUND' |
+'FST_ERR_CTP_ALREADY_PRESENT' |
+'FST_ERR_CTP_INVALID_TYPE' |
+'FST_ERR_CTP_EMPTY_TYPE' |
+'FST_ERR_CTP_INVALID_HANDLER' |
+'FST_ERR_CTP_INVALID_PARSE_TYPE' |
+'FST_ERR_CTP_BODY_TOO_LARGE' |
+'FST_ERR_CTP_INVALID_MEDIA_TYPE' |
+'FST_ERR_CTP_INVALID_CONTENT_LENGTH' |
+'FST_ERR_CTP_EMPTY_JSON_BODY' |
+'FST_ERR_DEC_ALREADY_PRESENT' |
+'FST_ERR_DEC_DEPENDENCY_INVALID_TYPE' |
+'FST_ERR_DEC_MISSING_DEPENDENCY' |
+'FST_ERR_DEC_AFTER_START' |
+'FST_ERR_HOOK_INVALID_TYPE' |
+'FST_ERR_HOOK_INVALID_HANDLER' |
+'FST_ERR_MISSING_MIDDLEWARE' |
+'FST_ERR_HOOK_TIMEOUT' |
+'FST_ERR_LOG_INVALID_DESTINATION' |
+'FST_ERR_REP_INVALID_PAYLOAD_TYPE' |
+'FST_ERR_REP_ALREADY_SENT' |
+'FST_ERR_REP_SENT_VALUE'|
+'FST_ERR_SEND_INSIDE_ONERR'|
+'FST_ERR_SEND_UNDEFINED_ERR'|
+'FST_ERR_BAD_STATUS_CODE'|
+'FST_ERR_BAD_TRAILER_NAME' |
+'FST_ERR_BAD_TRAILER_VALUE' |
+'FST_ERR_MISSING_SERIALIZATION_FN' |
+'FST_ERR_REQ_INVALID_VALIDATION_INVOCATION' |
+'FST_ERR_SCH_MISSING_ID' |
+'FST_ERR_SCH_ALREADY_PRESENT' |
+'FST_ERR_SCH_DUPLICATE' |
+'FST_ERR_SCH_VALIDATION_BUILD' |
+'FST_ERR_SCH_SERIALIZATION_BUILD' |
+'FST_ERR_HTTP2_INVALID_VERSION' |
+'FST_ERR_INIT_OPTS_INVALID' |
+'FST_ERR_FORCE_CLOSE_CONNECTIONS_IDLE_NOT_AVAILABLE' |
+'FST_ERR_DUPLICATED_ROUTE' |
+'FST_ERR_BAD_URL' |
+'FST_ERR_DEFAULT_ROUTE_INVALID_TYPE' |
+'FST_ERR_INVALID_URL' |
+'FST_ERR_REOPENED_CLOSE_SERVER' |
+'FST_ERR_REOPENED_SERVER' |
+'FST_ERR_PLUGIN_VERSION_MISMATCH' |
+'FST_ERR_PLUGIN_CALLBACK_NOT_FN' |
+'FST_ERR_PLUGIN_NOT_VALID' |
+'FST_ERR_ROOT_PLG_BOOTED' |
+'FST_ERR_PARENT_PLUGIN_BOOTED' |
+'FST_ERR_PLUGIN_TIMEOUT'
+, FastifyErrorConstructor>