docs: asynchronous constraints

docs/Reference/Errors.md

@@ -88,6 +88,11 @@ Some things to consider in your custom error handler:
 
 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.
+
 <a name="FST_ERR_DUPLICATED_ROUTE"></a>
 #### FST_ERR_DUPLICATED_ROUTE
 

docs/Reference/Routes.md

@@ -732,6 +732,56 @@ fastify.route({
 })
 ```
 
+#### Asynchronous Custom Constraints
+
+You can provide your custom constraints and the `constraint` criteria can be fetch
+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 broken or expose sensitive information to hacker.
+> 
+> ```js
+> const fastify = require('fastify')({
+>   frameworkErrors: function(err, res, res) {
+>     if(err instanceof 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

docs/Reference/Server.md

@@ -723,14 +723,15 @@ 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: Only `FST_ERR_BAD_URL` is implemented at the moment.*
-
 ```js
 const fastify = require('fastify')({
   frameworkErrors: function (error, req, res) {
     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)
     }