feat(middlewares): remove kwargs from middleware signature for cleane…

…r DX and relabler get_response to next_middleware for consistency

aws_lambda_powertools/event_handler/api_gateway.py

@@ -245,7 +245,7 @@ def __init__(
         self.method = method.upper()
         self.rule = rule
         self.func = func
-        self._call_stack = func
+        self._middleware_stack = func
         self.cors = cors
         self.compress = compress
         self.cache_control = cache_control
@@ -300,8 +300,11 @@ def __call__(
             print("\n".join(getattr(item, "__name__", "Unknown") for item in all_middlewares))
             print("=================")
 
-        # Call the Middleware Wrapped _call_stack function handler with the app and route arguments
-        return self._call_stack(app, **route_arguments)
+        # Add Route Arguments to app context
+        app.append_context(_route_args=route_arguments)
+
+        # Call the Middleware Wrapped _call_stack function handler with the app
+        return self._middleware_stack(app)
 
     def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None:
         """
@@ -327,12 +330,10 @@ def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None:
         # this must be the last middleware in the stack (tech debt for backward
         # compatability purposes)
         #
-        # This adapter will call the registered API using **kwargs only and not the middleware
-        # param list of get_response(app: ApiGatewayResolver, **kwargs)
-        # to ensure the call signature of existing defined routes of Users do not
-        # need to change (avoid breaking changes)
+        # This adapter will call the registered API passing only the expected route arguments extracted from the path
+        # and not the middleware.
         # This adapter will adapt the response type of the route handler (Union[Dict, Tuple, Response])
-        # and normalise into a Resposne object so middleware will always have a constant signature
+        # and normalise into a Response object so middleware will always have a constant signature
         all_middlewares.append(_registered_api_adapter)
 
         # Wrap the original route handler function in the middleware handlers
@@ -341,7 +342,7 @@ def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None:
         #
         # Start with the route function and wrap from last to the first Middleware handler.
         for handler in reversed(all_middlewares):
-            self._call_stack = MiddlewareFrame(current_middleware=handler, next_middleware=self._call_stack)
+            self._middleware_stack = MiddlewareFrame(current_middleware=handler, next_middleware=self._middleware_stack)
 
         self._middleware_stack_built = True
 
@@ -718,16 +719,14 @@ def __str__(self) -> str:
         middleware_name = self.__name__
         return f"[{middleware_name}] next call chain is {middleware_name} -> {self._next_middleware_name}"
 
-    def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]:
+    def __call__(self, app: BaseRouter) -> Union[Dict, Tuple, Response]:
         """
         Call the middleware Frame to process the request.
 
         Parameters
         ----------
         app: BaseRouter
             The router instance
-        **kwargs
-            Any additional arguments to pass to the middleware Frame
 
         Returns
         -------
@@ -742,17 +741,17 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]:
         logger.debug("MiddlewareFrame: %s", self)
         app._push_processed_stack_frame(str(self))
 
-        return self.current_middleware(app, self.next_middleware, **kwargs)
+        return self.current_middleware(app, self.next_middleware)
 
 
 def _registered_api_adapter(
     app: "ApiGatewayResolver",
-    get_response: Callable[..., Any],
-    **kwargs,
+    next_middleware: Callable[..., Any],
 ) -> Union[Dict, Tuple, Response]:
     """
-    Calls the registered API using ONLY the **kwargs provided to ensure the last call
-    in the chain will match the API route function signature.
+    Calls the registered API using the "_route_args" from the Resolver context to ensure the last call
+    in the chain will match the API route function signature and ensure that Powertools passes the API
+    route handler the expected arguments.
 
     **IMPORTANT: This internal middleware ensures the actual API route is called with the correct call signature
     and it MUST be the final frame in the middleware stack.  This can only be removed when the API Route
@@ -762,20 +761,19 @@ def _registered_api_adapter(
     ----------
     app: ApiGatewayResolver
         The API Gateway resolver
-    get_response: Callable[..., Any]
+    next_middleware: Callable[..., Any]
         The function to handle the API
-    **kwargs:
-        The arguments to pass to the API
 
     Returns
     -------
     Response
         The API Response Object
 
     """
-    logger.debug(f"Calling API Route Handler: {kwargs}")
+    route_args: Dict = app.context.get("_route_args", {})
+    logger.debug(f"Calling API Route Handler: {route_args}")
 
-    return app._to_response(get_response(**kwargs))
+    return app.to_response(next_middleware(**route_args))
 
 
 class ApiGatewayResolver(BaseRouter):
@@ -1088,7 +1086,7 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response
             self._reset_processed_stack()
 
             return ResponseBuilder(
-                self._to_response(
+                self.to_response(
                     route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments),
                 ),
                 route,
@@ -1159,7 +1157,7 @@ def _call_exception_handler(self, exp: Exception, route: Route) -> Optional[Resp
 
         return None
 
-    def _to_response(self, result: Union[Dict, Tuple, Response]) -> Response:
+    def to_response(self, result: Union[Dict, Tuple, Response]) -> Response:
         """Convert the route's result to a Response
 
          3 main result types are supported:
@@ -1330,6 +1328,6 @@ def __init__(
 
 
 class NextMiddlewareCallback(Protocol):
-    def __call__(self, app: ApiGatewayResolver, **kwds: Any) -> Response:
-        """Protocol for callback regardless of get_response(app, **kwargs), next(app, **kwargs)"""
+    def __call__(self, app: ApiGatewayResolver) -> Response:
+        """Protocol for callback regardless of next_middleware(app), next(app)"""
         ...

aws_lambda_powertools/event_handler/middlewares/base.py

@@ -11,7 +11,7 @@ class BaseMiddlewareHandler(ABC):
 
     This is the middleware handler function where middleware logic is implemented.
     Here you have the option to execute code before and after the next handler in the
-    middleware chain is called.  The next middleware handler is represented by `get_response`.
+    middleware chain is called.  The next middleware handler is represented by `next_middleware`.
 
 
     ```python
@@ -20,15 +20,15 @@ class BaseMiddlewareHandler(ABC):
     # or optionally raise an exception to short-circuit the middleware execution chain
 
     # Get the response from the NEXT middleware handler (optionally injecting custom
-    # arguments into the get_response call)
-    result: Response = get_response(app, my_custom_arg="handled", **kwargs)
+    # arguments into the next_middleware call)
+    result: Response = next_middleware(app, my_custom_arg="handled")
 
     # Place code here for actions AFTER the next middleware handler is called
 
     return result
     ```
 
-    To implement ERROR style middleware wrap the call to `get_response` in a `try..except`
+    To implement ERROR style middleware wrap the call to `next_middleware` in a `try..except`
     block - you can also catch specific types of errors this way so your middleware only handles
     specific types of exceptions.
 
@@ -37,7 +37,7 @@ class BaseMiddlewareHandler(ABC):
     ```python
 
     try:
-        result: Response = get_response(app, my_custom_arg="handled", **kwargs)
+        result: Response = next_middleware(app, my_custom_arg="handled")
     except MyCustomValidationException as e:
         # Make sure we send back a 400 response for any Custom Validation Exceptions.
         result.status_code = 400
@@ -48,7 +48,7 @@ class BaseMiddlewareHandler(ABC):
     ```
 
     To short-circuit the middleware execution chain you can either raise an exception to cause
-    the function call stack to unwind naturally OR you can simple not call the `get_response`
+    the function call stack to unwind naturally OR you can simple not call the `next_middleware`
     handler to get the response from the next middleware handler in the chain.
 
     for example:
@@ -63,12 +63,12 @@ class BaseMiddlewareHandler(ABC):
 
 
     # Call the next middleware in the chain (needed for when condition above is valid)
-    return get_response(app, **kwargs)
+    return next_middleware(app)
 
     """
 
     @abstractmethod
-    def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response:
+    def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback) -> Response:
         """
         The Middleware Handler
 
@@ -78,8 +78,6 @@ def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback,
             The ApiGatewayResolver object
         get_response: NextMiddlewareCallback
             The next middleware handler in the chain
-        kwargs: Any
-            Any additional arguments to pass to the next middleware handler
 
         Returns
         -------
@@ -93,22 +91,20 @@ def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback,
     def __name__(self) -> str:  # noqa A003
         return str(self.__class__.__name__)
 
-    def __call__(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response:
+    def __call__(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response:
         """
         The Middleware handler function.
 
         Parameters
         ----------
         app: ApiGatewayResolver
             The ApiGatewayResolver object
-        get_response: Callable[...,Any]
+        next_middleware: NextMiddlewareCallback
             The next middleware handler in the chain
-        kwargs:
-            Any additional arguments to pass to the next middleware handler
 
         Returns
         -------
         Response
             The response from the next middleware handler in the chain
         """
-        return self.handler(app, get_response, **kwargs)
+        return self.handler(app, next_middleware)

aws_lambda_powertools/event_handler/middlewares/schema_validation.py

@@ -43,7 +43,7 @@ def bad_config(self, error: InvalidSchemaFormatError) -> Response:
         logger.debug(f"Invalid Schema Format: {error}")
         raise InternalServerError("Internal Server Error")
 
-    def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response:
+    def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response:
         """
         Validate using Powertools validate() utility.
 
@@ -53,8 +53,7 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k
         Return the next middleware response if validation passes.
 
         :param app: The ApiGatewayResolver instance
-        :param get_response: The original response
-        :param kwargs: Additional arguments
+        :param next_middleware: The original response
         :return: The original response or HTTP 400 Response or HTTP 500 Response.
 
         """
@@ -66,7 +65,7 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k
             return self.bad_config(error)
 
         # return next middleware response if validation passes.
-        result: Response = get_response(app, **kwargs)
+        result: Response = next_middleware(app)
 
         if self.outbound_formats is not None:
             try:

examples/event_handler_rest/src/custom_middlewares.py

@@ -6,19 +6,19 @@
 logger = Logger()
 
 
-def validate_correlation_id(app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **context_args) -> Response:
+def validate_correlation_id(app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response:
     # If missing mandatory header raise an error
     if not app.current_event.headers.get("x-correlation-id", None):
         raise BadRequestError("No [x-correlation-id] header provided.  All requests must include this header.")
 
     # Get the response from the next middleware and return it
-    return get_response(app, **context_args)
+    return next_middleware(app)
 
 
-def sanitise_exceptions(app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **context_args) -> Response:
+def sanitise_exceptions(app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response:
     try:
         # Get the Result from the next middleware
-        result = get_response(app, **context_args)
+        result = next_middleware(app)
     except Exception as err:
         logger.exception(err)
         # Raise a clean error for ALL unexpected exceptions (ServiceError based Exceptions are okay)

examples/event_handler_rest/src/middleware_getting_started.py

@@ -8,7 +8,7 @@
 logger = Logger()
 
 
-def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response:
+def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response:
     request_id = app.current_event.request_context.request_id  # (1)!
 
     # Use API Gateway REST API request ID if caller didn't include a correlation ID
@@ -19,7 +19,7 @@ def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlew
     logger.set_correlation_id(request_id)
 
     # Get response from next middleware OR /todos route
-    result = get_response(app, **kwargs)  # (3)!
+    result = next_middleware(app)  # (3)!
 
     # Include Correlation ID in the response back to caller
     result.headers["x-correlation-id"] = correlation_id  # (4)!

examples/event_handler_rest/src/middleware_global_middlewares_module.py

@@ -5,16 +5,16 @@
 logger = Logger()
 
 
-def log_request_response(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response:
+def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback, **kwargs) -> Response:
     logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event)
 
-    result = get_response(app, **kwargs)
+    result = next_middleware(app)
     logger.info("Response received", response=result.__dict__)
 
     return result
 
 
-def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response:
+def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback, **kwargs) -> Response:
     request_id = app.current_event.request_context.request_id
 
     # Use API Gateway REST API request ID if caller didn't include a correlation ID
@@ -25,17 +25,17 @@ def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlew
     logger.set_correlation_id(request_id)
 
     # Get response from next middleware OR /todos route
-    result = get_response(app, **kwargs)
+    result = next_middleware(app)
 
     # Include Correlation ID in the response back to caller
     result.headers["x-correlation-id"] = correlation_id
     return result
 
 
-def enforce_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response:
+def enforce_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response:
     # If missing mandatory header raise an error
     if not app.current_event.get_header_value("x-correlation-id", case_sensitive=False):
         return Response(status_code=400, body="Correlation ID header is now mandatory.")  # (1)!
 
     # Get the response from the next middleware and return it
-    return get_response(app, **kwargs)
+    return next_middleware(app)

tests/functional/event_handler/test_api_gateway.py

@@ -909,7 +909,8 @@ def test_debug_print_event(capsys):
     # THEN print the event
     out, err = capsys.readouterr()
     assert "\n" in out
-    assert json.loads(out) == event
+    output: str = out.split("\n")[0]
+    assert json.loads(output) == event
 
 
 def test_similar_dynamic_routes():