lib: deprecate the default route and improve its documentation

docs/Reference/Server.md

@@ -1011,6 +1011,9 @@ Note that the array contains the `fastify.server.address()` too.
 #### getDefaultRoute
 <a id="getDefaultRoute"></a>
 
+**Notice**: this method is deprecated and should be removed in the next Fastify
+major version.
+
 The `defaultRoute` handler handles requests that do not match any URL specified
 by your Fastify application. This defaults to the 404 handler, but can be
 overridden with [setDefaultRoute](#setdefaultroute). Method to get the
@@ -1023,14 +1026,25 @@ const defaultRoute = fastify.getDefaultRoute()
 #### setDefaultRoute
 <a id="setDefaultRoute"></a>
 
-**Note**: The default 404 handler, or one set using `setNotFoundHandler`, will
-never trigger if the default route is overridden. This sets the handler for the 
+**Notice**: this method is deprecated and should be removed in the next Fastify
+major version. Please, consider to use `setNotFoundHandler` or a wildcard
+matching route.
+
+The default 404 handler, or one set using `setNotFoundHandler`, will
+never trigger if the default route is overridden. This sets the handler for the
 Fastify application, not just the current instance context. Use
 [setNotFoundHandler](#setnotfoundhandler) if you want to customize 404 handling
-instead. Method to set the `defaultRoute` for the server:
+instead.
+
+This method sets the `defaultRoute` for the server. Note that, its purpose is
+to interact with the underlying raw requests. Unlike other Fastify handlers, the
+arguments received are of type [RawRequest](./TypeScript.md#rawrequest) and
+[RawReply](./TypeScript.md#rawreply) respectively.
 
 ```js
 const defaultRoute = function (req, res) {
+  // req = RawRequest
+  // res = RawReply
   res.end('hello world')
 }
 

lib/route.js

@@ -89,9 +89,11 @@ function buildRouting (options) {
     hasRoute,
     prepareRoute,
     getDefaultRoute: function () {
+      warning.emit('FSTDEP014')
       return router.defaultRoute
     },
     setDefaultRoute: function (defaultRoute) {
+      warning.emit('FSTDEP014')
       if (typeof defaultRoute !== 'function') {
         throw new FST_ERR_DEFAULT_ROUTE_INVALID_TYPE()
       }

lib/warnings.js

@@ -25,4 +25,6 @@ warning.create('FastifyDeprecation', 'FSTDEP012', 'Request#context property acce
 
 warning.create('FastifyDeprecation', 'FSTDEP013', 'Direct return of "trailers" function is deprecated. Please use "callback" or "async-await" for return value. The support of direct return will removed in `fastify@5`.')
 
+warning.create('FastifyDeprecation', 'FSTDEP014', 'You are trying to set/access the default route. This property is deprecated. Please, use setNotFoundHandler if you want to custom a 404 handler or the wildcard (*) to match all routes.')
+
 module.exports = warning

test/default-route.test.js

@@ -3,6 +3,51 @@
 const t = require('tap')
 const test = t.test
 const Fastify = require('..')
+const warning = require('../lib/warnings')
+
+// Silence the standard warning logs. We will test the messages explicitly.
+process.removeAllListeners('warning')
+
+test('setDefaultRoute should emit a deprecation warning', t => {
+  t.plan(2)
+
+  const fastify = Fastify()
+  const defaultRoute = (req, res) => {
+    res.end('hello from defaultRoute')
+  }
+
+  process.on('warning', onWarning)
+  function onWarning (warning) {
+    t.equal(warning.name, 'FastifyDeprecation')
+    t.equal(warning.code, 'FSTDEP014')
+  }
+
+  t.teardown(() => {
+    process.removeListener('warning', onWarning)
+    warning.emitted.set('FSTDEP014', false)
+  })
+
+  fastify.setDefaultRoute(defaultRoute)
+})
+
+test('getDefaultRoute should emit a deprecation warning', t => {
+  t.plan(2)
+
+  const fastify = Fastify()
+
+  process.on('warning', onWarning)
+  function onWarning (warning) {
+    t.equal(warning.name, 'FastifyDeprecation')
+    t.equal(warning.code, 'FSTDEP014')
+  }
+
+  t.teardown(() => {
+    process.removeListener('warning', onWarning)
+    warning.emitted.set('FSTDEP014', false)
+  })
+
+  fastify.getDefaultRoute()
+})
 
 test('should fail if defaultRoute is not a function', t => {
   t.plan(1)