Fix #273 Enable developers to customize the way to handle unmatched requests

Author: seratch

slack_bolt/app/app.py

@@ -17,7 +17,7 @@
     InstallationStoreAuthorize,
     CallableAuthorize,
 )
-from slack_bolt.error import BoltError
+from slack_bolt.error import BoltError, BoltUnhandledRequestError
 from slack_bolt.lazy_listener.thread_runner import ThreadLazyListenerRunner
 from slack_bolt.listener.builtins import TokenRevocationListeners
 from slack_bolt.listener.custom_listener import CustomListener
@@ -50,6 +50,7 @@
     debug_return_listener_middleware_response,
     info_default_oauth_settings_loaded,
     error_installation_store_required_for_builtin_listeners,
+    warning_unhandled_by_global_middleware,
 )
 from slack_bolt.middleware import (
     Middleware,
@@ -85,6 +86,8 @@ def __init__(
         name: Optional[str] = None,
         # Set True when you run this app on a FaaS platform
         process_before_response: bool = False,
+        # Set True if you want to handle an unhandled request as an exception
+        raise_error_for_unhandled_request: bool = False,
         # Basic Information > Credentials > Signing Secret
         signing_secret: Optional[str] = None,
         # for single-workspace apps
@@ -94,7 +97,7 @@ def __init__(
         # for multi-workspace apps
         authorize: Optional[Callable[..., AuthorizeResult]] = None,
         installation_store: Optional[InstallationStore] = None,
-        # for v1.0.x compatibility
+        # for either only bot scope usage or v1.0.x compatibility
         installation_store_bot_only: Optional[bool] = None,
         # for the OAuth flow
         oauth_settings: Optional[OAuthSettings] = None,
@@ -132,6 +135,9 @@ def message_hello(message, say):
             logger: The custom logger that can be used in this app.
             name: The application name that will be used in logging. If absent, the source file name will be used.
             process_before_response: True if this app runs on Function as a Service. (Default: False)
+            raise_error_for_unhandled_request: True if you want to raise exceptions for unhandled requests
+                and use @app.error listeners instead of
+                the built-in handler, which pints warning logs and returns 404 to Slack (Default: False)
             signing_secret: The Signing Secret value used for verifying requests from Slack.
             token: The bot/user access token required only for single-workspace app.
             token_verification_enabled: Verifies the validity of the given token if True.
@@ -154,6 +160,7 @@ def message_hello(message, say):
             "SLACK_VERIFICATION_TOKEN", None
         )
         self._framework_logger = logger or get_bolt_logger(App)
+        self._raise_error_for_unhandled_request = raise_error_for_unhandled_request
 
         self._token: Optional[str] = token
 
@@ -411,9 +418,26 @@ def middleware_next():
             resp = middleware.process(req=req, resp=resp, next=middleware_next)
             if not middleware_state["next_called"]:
                 if resp is None:
-                    return BoltResponse(
+                    # next() method was not called without providing the response to return to Slack
+                    # This should not be an intentional handling in usual use cases.
+                    resp = BoltResponse(
                         status=404, body={"error": "no next() calls in middleware"}
                     )
+                    if self._raise_error_for_unhandled_request is True:
+                        self._listener_runner.listener_error_handler.handle(
+                            error=BoltUnhandledRequestError(
+                                request=req,
+                                current_response=resp,
+                                last_global_middleware_name=middleware.name,
+                            ),
+                            request=req,
+                            response=resp,
+                        )
+                        return resp
+                    self._framework_logger.warning(
+                        warning_unhandled_by_global_middleware(middleware.name, req)
+                    )
+                    return resp
                 return resp
 
         for listener in self._listeners:
@@ -452,8 +476,27 @@ def middleware_next():
                 if listener_response is not None:
                     return listener_response
 
+        if resp is None:
+            resp = BoltResponse(status=404, body={"error": "unhandled request"})
+        if self._raise_error_for_unhandled_request is True:
+            self._listener_runner.listener_error_handler.handle(
+                error=BoltUnhandledRequestError(
+                    request=req,
+                    current_response=resp,
+                ),
+                request=req,
+                response=resp,
+            )
+            return resp
+        return self._handle_unmatched_requests(req, resp)
+
+    def _handle_unmatched_requests(
+        self, req: BoltRequest, resp: BoltResponse
+    ) -> BoltResponse:
+        # TODO: provide more info like suggestion of listeners
+        # e.g., You can handle this type of message with @app.event("app_mention")
         self._framework_logger.warning(warning_unhandled_request(req))
-        return BoltResponse(status=404, body={"error": "unhandled request"})
+        return resp
 
     # -------------------------
     # middleware
@@ -563,7 +606,7 @@ def step(
     # global error handler
 
     def error(
-        self, func: Callable[..., None]
+        self, func: Callable[..., Optional[BoltResponse]]
     ) -> Optional[Callable[..., Optional[BoltResponse]]]:
         """Updates the global error handler. This method can be used as either a decorator or a method.
 

slack_bolt/app/async_app.py

@@ -33,7 +33,7 @@
     AsyncCallableAuthorize,
     AsyncInstallationStoreAuthorize,
 )
-from slack_bolt.error import BoltError
+from slack_bolt.error import BoltError, BoltUnhandledRequestError
 from slack_bolt.logger.messages import (
     warning_client_prioritized_and_token_skipped,
     warning_token_skipped,
@@ -51,6 +51,7 @@
     debug_return_listener_middleware_response,
     info_default_oauth_settings_loaded,
     error_installation_store_required_for_builtin_listeners,
+    warning_unhandled_by_global_middleware,
 )
 from slack_bolt.lazy_listener.asyncio_runner import AsyncioLazyListenerRunner
 from slack_bolt.listener.async_listener import AsyncListener, AsyncCustomListener
@@ -96,13 +97,16 @@ def __init__(
         name: Optional[str] = None,
         # Set True when you run this app on a FaaS platform
         process_before_response: bool = False,
+        # Set True if you want to handle an unhandled request as an exception
+        raise_error_for_unhandled_request: bool = False,
         # Basic Information > Credentials > Signing Secret
         signing_secret: Optional[str] = None,
         # for single-workspace apps
         token: Optional[str] = None,
         client: Optional[AsyncWebClient] = None,
         # for multi-workspace apps
         installation_store: Optional[AsyncInstallationStore] = None,
+        # for either only bot scope usage or v1.0.x compatibility
         installation_store_bot_only: Optional[bool] = None,
         authorize: Optional[Callable[..., Awaitable[AuthorizeResult]]] = None,
         # for the OAuth flow
@@ -141,6 +145,9 @@ async def message_hello(message, say):  # async function
             logger: The custom logger that can be used in this app.
             name: The application name that will be used in logging. If absent, the source file name will be used.
             process_before_response: True if this app runs on Function as a Service. (Default: False)
+            raise_error_for_unhandled_request: True if you want to raise exceptions for unhandled requests
+                and use @app.error listeners instead of
+                the built-in handler, which pints warning logs and returns 404 to Slack (Default: False)
             signing_secret: The Signing Secret value used for verifying requests from Slack.
             token: The bot/user access token required only for single-workspace app.
             client: The singleton `slack_sdk.web.async_client.AsyncWebClient` instance for this app.
@@ -161,6 +168,7 @@ async def message_hello(message, say):  # async function
             "SLACK_VERIFICATION_TOKEN", None
         )
         self._framework_logger = logger or get_bolt_logger(AsyncApp)
+        self._raise_error_for_unhandled_request = raise_error_for_unhandled_request
 
         self._token: Optional[str] = token
 
@@ -464,9 +472,26 @@ async def async_middleware_next():
             )
             if not middleware_state["next_called"]:
                 if resp is None:
-                    return BoltResponse(
+                    # next() method was not called without providing the response to return to Slack
+                    # This should not be an intentional handling in usual use cases.
+                    resp = BoltResponse(
                         status=404, body={"error": "no next() calls in middleware"}
                     )
+                    if self._raise_error_for_unhandled_request is True:
+                        await self._async_listener_runner.listener_error_handler.handle(
+                            error=BoltUnhandledRequestError(
+                                request=req,
+                                current_response=resp,
+                                last_global_middleware_name=middleware.name,
+                            ),
+                            request=req,
+                            response=resp,
+                        )
+                        return resp
+                    self._framework_logger.warning(
+                        warning_unhandled_by_global_middleware(middleware.name, req)
+                    )
+                    return resp
                 return resp
 
         for listener in self._async_listeners:
@@ -508,8 +533,27 @@ async def async_middleware_next():
                 if listener_response is not None:
                     return listener_response
 
+        if resp is None:
+            resp = BoltResponse(status=404, body={"error": "unhandled request"})
+        if self._raise_error_for_unhandled_request is True:
+            await self._async_listener_runner.listener_error_handler.handle(
+                error=BoltUnhandledRequestError(
+                    request=req,
+                    current_response=resp,
+                ),
+                request=req,
+                response=resp,
+            )
+            return resp
+        return self._handle_unmatched_requests(req, resp)
+
+    def _handle_unmatched_requests(
+        self, req: AsyncBoltRequest, resp: BoltResponse
+    ) -> BoltResponse:
+        # TODO: provide more info like suggestion of listeners
+        # e.g., You can handle this type of message with @app.event("app_mention")
         self._framework_logger.warning(warning_unhandled_request(req))
-        return BoltResponse(status=404, body={"error": "unhandled request"})
+        return resp
 
     # -------------------------
     # middleware
@@ -623,8 +667,8 @@ def step(
     # global error handler
 
     def error(
-        self, func: Callable[..., Awaitable[None]]
-    ) -> Callable[..., Awaitable[None]]:
+        self, func: Callable[..., Awaitable[Optional[BoltResponse]]]
+    ) -> Callable[..., Awaitable[Optional[BoltResponse]]]:
         """Updates the global error handler. This method can be used as either a decorator or a method.
 
             # Use this method as a decorator
@@ -642,6 +686,9 @@ async def custom_error_handler(error, body, logger):
             func: The function that is supposed to be executed
                 when getting an unhandled error in Bolt app.
         """
+        if not inspect.iscoroutinefunction(func):
+            name = get_name_for_callable(func)
+            raise BoltError(error_listener_function_must_be_coro_func(name))
         self._async_listener_runner.listener_error_handler = (
             AsyncCustomListenerErrorHandler(
                 logger=self._framework_logger,

slack_bolt/error/__init__.py

@@ -1,5 +1,25 @@
 """Bolt specific error types."""
+from typing import Optional, Union
 
 
 class BoltError(Exception):
     """General class in a Bolt app"""
+
+
+class BoltUnhandledRequestError(BoltError):
+    request: "BoltRequest"  # type: ignore
+    body: dict
+    current_response: Optional["BoltResponse"]  # type: ignore
+    last_global_middleware_name: Optional[str]
+
+    def __init__(  # type: ignore
+        self,
+        *,
+        request: Union["BoltRequest", "AsyncBoltRequest"],  # type: ignore
+        current_response: Optional["BoltResponse"],  # type: ignore
+        last_global_middleware_name: Optional[str] = None,
+    ):
+        self.request = request
+        self.body = request.body if request is not None else {}
+        self.current_response = current_response
+        self.last_global_middleware_name = last_global_middleware_name

slack_bolt/listener/async_listener_error_handler.py

@@ -33,7 +33,9 @@ async def handle(
 
 
 class AsyncCustomListenerErrorHandler(AsyncListenerErrorHandler):
-    def __init__(self, logger: Logger, func: Callable[..., Awaitable[None]]):
+    def __init__(
+        self, logger: Logger, func: Callable[..., Awaitable[Optional[BoltResponse]]]
+    ):
         self.func = func
         self.logger = logger
         self.arg_names = inspect.getfullargspec(func).args
@@ -55,7 +57,13 @@ async def handle(
             arg_names=self.arg_names,
             logger=self.logger,
         )
-        await self.func(**kwargs)
+        returned_response = await self.func(**kwargs)
+        if returned_response is not None and isinstance(
+            returned_response, BoltResponse
+        ):
+            response.status = returned_response.status
+            response.headers = returned_response.headers
+            response.body = returned_response.body
 
 
 class AsyncDefaultListenerErrorHandler(AsyncListenerErrorHandler):

slack_bolt/listener/listener_error_handler.py

@@ -31,7 +31,7 @@ def handle(
 
 
 class CustomListenerErrorHandler(ListenerErrorHandler):
-    def __init__(self, logger: Logger, func: Callable[..., None]):
+    def __init__(self, logger: Logger, func: Callable[..., Optional[BoltResponse]]):
         self.func = func
         self.logger = logger
         self.arg_names = inspect.getfullargspec(func).args
@@ -53,7 +53,13 @@ def handle(
             arg_names=self.arg_names,
             logger=self.logger,
         )
-        self.func(**kwargs)
+        returned_response = self.func(**kwargs)
+        if returned_response is not None and isinstance(
+            returned_response, BoltResponse
+        ):
+            response.status = returned_response.status
+            response.headers = returned_response.headers
+            response.body = returned_response.body
 
 
 class DefaultListenerErrorHandler(ListenerErrorHandler):

slack_bolt/logger/messages.py

@@ -85,7 +85,18 @@ def warning_installation_store_conflicts() -> str:
     return "As you gave both `installation_store` and `oauth_settings`/`auth_flow`, the top level one is unused."
 
 
-def warning_unhandled_request(req: Union[BoltRequest, "AsyncBoltRequest"]) -> str:  # type: ignore
+def warning_unhandled_by_global_middleware(  # type: ignore
+    name: str, req: Union[BoltRequest, "AsyncBoltRequest"]  # type: ignore
+) -> str:  # type: ignore
+    return (
+        f"A global middleware ({name}) skipped calling `next()` "
+        f"without providing a response for the request ({req.body})"
+    )
+
+
+def warning_unhandled_request(  # type: ignore
+    req: Union[BoltRequest, "AsyncBoltRequest"],  # type: ignore
+) -> str:  # type: ignore
     return f"Unhandled request ({req.body})"