feat(routing): override default responders via on_request()

Add an option to CompiledRouterOptions that allows for overriding the default responders by implementing on_request() in the resource class

Closes falconry#2071

Author: gespyrop

docs/_newsfragments/2071.newandimproved.rst

@@ -0,0 +1,6 @@
+Added the :attr:`~.CompiledRouterOptions.allow_on_request` router option that
+allows for providing a default responder by defining `on_request()` on the 
+resource. This option is disabled by default. If enabled, `on_request()` is
+set as the responder for every unimplemented method except for `on_options()`. 
+If the option is disabled or `on_request()` is not provided in the resource,
+the default responder for "405 Method Not Allowed" is used.

falcon/routing/compiled.py

@@ -209,7 +209,14 @@ class can use suffixed responders to distinguish requests
 
         method_map = self.map_http_methods(resource, **kwargs)
 
-        set_default_responders(method_map, asgi=asgi)
+        default_responder = None
+
+        if self._options.allow_on_request:
+            default_responder = getattr(resource, 'on_request', None)
+
+        set_default_responders(
+            method_map, asgi=asgi, default_responder=default_responder
+        )
 
         if asgi:
             self._require_coroutine_responders(method_map)
@@ -941,15 +948,35 @@ class CompiledRouterOptions:
     (See also: :ref:`Field Converters <routing_field_converters>`)
     """
 
-    __slots__ = ('converters',)
+    allow_on_request: bool
+    """Allows for providing a default responder by defining `on_request()` on
+    the resource.
 
-    def __init__(self) -> None:
+    This feature is disabled by default and can be enabled by::
+
+        app.router_options.allow_on_request = True
+
+    Note:
+        This option does not override `on_options()`.
+
+    Note:
+        In order for this option to take effect, it must be enabled before
+        calling :meth:`add_route()`.
+
+    .. versionadded:: 4.1
+    """
+
+    __slots__ = ('converters', 'allow_on_request')
+
+    def __init__(self, allow_on_request: bool = False) -> None:
         object.__setattr__(
             self,
             'converters',
             ConverterDict((name, converter) for name, converter in converters.BUILTIN),
         )
 
+        self.allow_on_request = allow_on_request
+
     def __setattr__(self, name: str, value: Any) -> None:
         if name == 'converters':
             raise AttributeError('Cannot set "converters", please update it in place.')

falcon/routing/util.py

@@ -16,13 +16,15 @@
 
 from __future__ import annotations
 
-from typing import Optional, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING, Union
 
 from falcon import constants
 from falcon import responders
 
 if TYPE_CHECKING:
+    from falcon._typing import AsgiResponderCallable
     from falcon._typing import MethodDict
+    from falcon._typing import ResponderCallable
 
 
 class SuffixedMethodNotFoundError(Exception):
@@ -78,14 +80,21 @@ def map_http_methods(resource: object, suffix: Optional[str] = None) -> MethodDi
     return method_map
 
 
-def set_default_responders(method_map: MethodDict, asgi: bool = False) -> None:
+def set_default_responders(
+    method_map: MethodDict,
+    asgi: bool = False,
+    default_responder: Optional[Union[ResponderCallable, AsgiResponderCallable]] = None,
+) -> None:
     """Map HTTP methods not explicitly defined on a resource to default responders.
 
     Args:
         method_map: A dict with HTTP methods mapped to responders explicitly
             defined in a resource.
         asgi (bool): ``True`` if using an ASGI app, ``False`` otherwise
             (default ``False``).
+        default_responder: An optional default responder for unimplmented
+            resource methods. If not provided a responder for
+            "405 Method Not Allowed" is used.
     """
 
     # Attach a resource for unsupported HTTP methods
@@ -99,8 +108,11 @@ def set_default_responders(method_map: MethodDict, asgi: bool = False) -> None:
         method_map['OPTIONS'] = opt_responder  # type: ignore[assignment]
         allowed_methods.append('OPTIONS')
 
-    na_responder = responders.create_method_not_allowed(allowed_methods, asgi=asgi)
+    if not default_responder:
+        default_responder = responders.create_method_not_allowed(
+            allowed_methods, asgi=asgi
+        )
 
     for method in constants.COMBINED_METHODS:
         if method not in method_map:
-            method_map[method] = na_responder  # type: ignore[assignment]
+            method_map[method] = default_responder  # type: ignore[assignment]

tests/test_default_router.py

@@ -103,6 +103,14 @@ def on_get(self, req, resp):
         resp.text = self.resource_id
 
 
+class ResourceWithDefaultResponder:
+    def on_get(self, req, resp):
+        pass
+
+    def on_request(self, req, resp):
+        pass
+
+
 class SpamConverter:
     def __init__(self, times, eggs=False):
         self._times = times
@@ -695,6 +703,30 @@ def test_options_converters_invalid_name_on_update(router):
         )
 
 
+def test_options_allow_on_request_disabled():
+    router = DefaultRouter()
+    router.add_route('/default', ResourceWithDefaultResponder())
+
+    resource, method_map, __, __ = router.find('/default')
+
+    for method, responder in method_map.items():
+        assert responder != resource.on_request
+
+
+def test_options_allow_on_request_enabled():
+    router = DefaultRouter()
+    router.options.allow_on_request = True
+    router.add_route('/default', ResourceWithDefaultResponder())
+
+    resource, method_map, __, __ = router.find('/default')
+
+    for method, responder in method_map.items():
+        if method not in ('GET', 'OPTIONS'):
+            assert responder == resource.on_request
+        else:
+            assert responder != resource.on_request
+
+
 @pytest.fixture
 def param_router():
     r = DefaultRouter()